LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

Convert function formatting of the form "\fBname\fP()" to ".BR name ()".

This commit is contained in:
Michael Kerrisk 2007-05-12 09:06:04 +00:00
parent d92a60f257
commit 60a90ecdae
273 changed files with 3530 additions and 1230 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
man2/_exit.2
View File

@ -64,7 +64,9 @@ is equivalent to
These functions do not return.
.SH "CONFORMING TO"
SVr4, POSIX.1-2001, 4.3BSD.
The function \fB_Exit\fP() was introduced by C99.
The function
.BR _Exit ()
was introduced by C99.
.SH NOTES
For a discussion on the effects of an exit, the transmission of
exit status, zombie processes, signals sent, etc., see
@ -72,7 +74,9 @@ exit status, zombie processes, signals sent, etc., see
.LP
The function
.BR _exit ()
is like \fBexit\fP(3), but does not call any
is like
.BR exit (3),
but does not call any
functions registered with
.BR atexit (3)
or
@ -88,9 +92,12 @@ waiting for pending output to finish.
If the delay is undesired,
it may be useful to call functions like
.BR tcflush (3)
before calling \fB_exit\fP().
before calling
.BR _exit ().
Whether any pending I/O is cancelled, and which pending I/O may be
cancelled upon \fB_exit\fP(), is implementation-dependent.
cancelled upon
.BR _exit (),
is implementation-dependent.
.SH "SEE ALSO"
.BR execve (2),
.BR exit_group (2),

3
man2/adjtimex.2
View File

@ -138,7 +138,8 @@ Under Linux the
.B CAP_SYS_TIME
capability is required.
.SH "CONFORMING TO"
\fBadjtimex\fP() is Linux specific and should not be used in programs
.BR adjtimex ()
is Linux specific and should not be used in programs
intended to be portable.
See
.BR adjtime (3)

7
man2/chown.2
View File

@ -171,10 +171,13 @@ used by the superuser (that is, ordinary users cannot give away files).
.\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
.\" error conditions.
.SH RESTRICTIONS
The \fBchown\fP() semantics are deliberately violated on NFS file systems
The
.BR chown ()
semantics are deliberately violated on NFS file systems
which have UID mapping enabled.
Additionally, the semantics of all system
calls which access the file contents are violated, because \fBchown\fP()
calls which access the file contents are violated, because
.BR chown ()
may cause immediate access revocation on already open files.
Client side
caching may lead to a delay between the time where ownership have

5
man2/dup.2
View File

@ -46,7 +46,10 @@ and
create a copy of the file descriptor
.IR oldfd .
After a successful return from \fBdup\fR() or \fBdup2\fR(),
After a successful return from
.BR dup ()
or
.BR dup2 (),
the old and new file descriptors may be used interchangeably.
They refer to the same open file description (see
.BR open (2))

16
man2/execve.2
View File

@ -42,7 +42,8 @@ execve \- execute program
.br
.BI " char *const " envp []);
.SH DESCRIPTION
\fBexecve\fP() executes the program pointed to by \fIfilename\fP.
.BR execve ()
executes the program pointed to by \fIfilename\fP.
\fIfilename\fP must be either a binary executable, or a script
starting with a line of the form:
@ -67,12 +68,14 @@ int main(int argc, char *argv[], char *envp[])\fR.
.fi
.in
\fBexecve\fP() does not return on success, and the text, data, bss, and
.BR execve ()
does not return on success, and the text, data, bss, and
stack of the calling process are overwritten by that of the program
loaded.
If the current program is being ptraced, a \fBSIGTRAP\fP is sent to it
after a successful \fBexecve\fP().
after a successful
.BR execve ().
If the set-user-ID bit is set on the program file pointed to by
\fIfilename\fP,
@ -271,7 +274,9 @@ For portable use,
should either be absent, or be specified as a single word (i.e., it
should not contain white space); see NOTES below.
.SH "RETURN VALUE"
On success, \fBexecve\fP() does not return, on error \-1 is returned, and
On success,
.BR execve ()
does not return, on error \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
@ -429,7 +434,8 @@ on most other Unix systems doing this will result in an error.
.\" Some Linux versions have failed to check permissions on ELF
.\" interpreters. This is a security hole, because it allows users to
.\" open any file, such as a rewinding tape device, for reading. Some
.\" Linux versions have also had other security holes in \fBexecve\fP(),
.\" Linux versions have also had other security holes in
.BR execve (),
.\" that could be exploited for denial of service by a suitably crafted
.\" ELF binary. There are no known problems with 2.0.34 or 2.2.15.
.SH HISTORICAL

50
man2/getcontext.2
View File

@ -34,8 +34,11 @@ In a System V-like environment, one has the two types
\fImcontext_t\fP and \fIucontext_t\fP defined in
.I <ucontext.h>
and the four functions
\fBgetcontext\fP(), \fBsetcontext\fP(), \fBmakecontext\fP(3)
and \fBswapcontext\fP(3)
.BR getcontext (),
.BR setcontext (),
.BR makecontext (3)
and
.BR swapcontext (3)
that allow user-level context switching between multiple
threads of control within a process.
.LP
@ -59,7 +62,9 @@ with \fIsigset_t\fP and \fIstack_t\fP defined in
.IR <signal.h> .
Here \fIuc_link\fP points to the context that will be resumed
when the current context terminates (in case the current context
was created using \fBmakecontext\fP(3)), \fIuc_sigmask\fP is the
was created using
.BR makecontext (3)),
\fIuc_sigmask\fP is the
set of signals blocked in this context (see
.BR sigprocmask (2)),
\fIuc_stack\fP is the stack used by this context (see
@ -68,25 +73,36 @@ and \fIuc_mcontext\fP is the
machine-specific representation of the saved context,
that includes the calling thread's machine registers.
.LP
The function \fBgetcontext\fP() initializes the structure
The function
.BR getcontext ()
initializes the structure
pointed at by \fIucp\fP to the currently active context.
.LP
The function \fBsetcontext\fP() restores the user context
The function
.BR setcontext ()
restores the user context
pointed at by \fIucp\fP.
A successful call does not return.
The context should have been obtained by a call of \fBgetcontext\fP(),
or \fBmakecontext\fP(3), or passed as third argument to a signal
The context should have been obtained by a call of
.BR getcontext (),
or
.BR makecontext (3),
or passed as third argument to a signal
handler.
.LP
If the context was obtained by a call of \fBgetcontext\fP(),
If the context was obtained by a call of
.BR getcontext (),
program execution continues as if this call just returned.
.LP
If the context was obtained by a call of \fBmakecontext\fP(3),
If the context was obtained by a call of
.BR makecontext (3),
program execution continues by a call to the function \fIfunc\fP
specified as the second argument of that call to \fBmakecontext\fP(3).
specified as the second argument of that call to
.BR makecontext (3).
When the function \fIfunc\fP returns, we continue with the
\fIuc_link\fP member of the structure \fIucp\fP specified as the
first argument of that call to \fBmakecontext\fP(3).
first argument of that call to
.BR makecontext (3).
When this member is NULL, the thread exits.
.LP
If the context was obtained by a call to a signal handler,
@ -96,7 +112,10 @@ by the signal".
However, this sentence was removed in SUSv2,
and the present verdict is "the result is unspecified".
.SH "RETURN VALUE"
When successful, \fBgetcontext\fP() returns 0 and \fBsetcontext\fP()
When successful,
.BR getcontext ()
returns 0 and
.BR setcontext ()
does not return.
On error, both return \-1 and set \fIerrno\fP
appropriately.
@ -110,8 +129,11 @@ the handling of the signal context, the next stage was the
\fIsigsetjmp\fP(3)/\fIsiglongjmp\fP(3) pair.
The present mechanism gives much more control.
On the other hand,
there is no easy way to detect whether a return from \fBgetcontext\fP()
is from the first call, or via a \fBsetcontext\fP() call.
there is no easy way to detect whether a return from
.BR getcontext ()
is from the first call, or via a
.BR setcontext ()
call.
The user has to invent her own bookkeeping device, and a register
variable won't do since registers are restored.
.LP

8
man2/getrlimit.2
View File

@ -349,11 +349,15 @@ was greater than
.IR rlim->rlim_max .
.TP
.B EPERM
An unprivileged process tried to use \fBsetrlimit\fP() to
An unprivileged process tried to use
.BR setrlimit ()
to
increase a soft or hard limit above the current hard limit; the
.B CAP_SYS_RESOURCE
capability is required to do this.
Or, the process tried to use \fBsetrlimit\fP() to increase
Or, the process tried to use
.BR setrlimit ()
to increase
the soft or hard RLIMIT_NOFILE limit above the current kernel
maximum (NR_OPEN).
.SH BUGS

6
man2/gettid.2
View File

@ -38,7 +38,8 @@ gettid \- get thread identification
.fi
.B pid_t gettid(void);
.SH DESCRIPTION
\fBgettid\fP() returns the thread ID of the current process.
.BR gettid ()
returns the thread ID of the current process.
This is equal
to the process ID (as returned by
.BR getpid (2)),
@ -53,7 +54,8 @@ On success, returns the thread ID of the current process.
.SH ERRORS
This call is always successful.
.SH "CONFORMING TO"
\fBgettid\fP() is Linux specific and should not be used in programs that
.BR gettid ()
is Linux specific and should not be used in programs that
are intended to be portable.
.SH "SEE ALSO"
.BR clone (2),

9
man2/getuid.2
View File

@ -45,8 +45,13 @@ These functions are always successful.
.SH "CONFORMING TO"
POSIX.1-2001, 4.3BSD.
.SH HISTORY
In Unix V6 the \fBgetuid\fP() call returned (euid << 8) + uid.
Unix V7 introduced separate calls \fBgetuid\fP() and \fBgeteuid\fP().
In Unix V6 the
.BR getuid ()
call returned (euid << 8) + uid.
Unix V7 introduced separate calls
.BR getuid ()
and
.BR geteuid ().
.SH "SEE ALSO"
.BR setreuid (2),
.BR setuid (2)

18
man2/io_cancel.2
View File

@ -39,7 +39,8 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
.fi
.SH "DESCRIPTION"
.PP
\fBio_cancel\fR() attempts to cancel an asynchronous I/O operation
.BR io_cancel ()
attempts to cancel an asynchronous I/O operation
previously submitted with the \fBio_submit\fR system call.
\fIctx_id\fR is the AIO context ID of the operation to be cancelled.
If the AIO context is found, the event will be cancelled and then copied
@ -47,7 +48,8 @@ into the memory pointed to by \fIresult\fR without being placed
into the completion queue.
.SH "RETURN VALUE"
.PP
\fBio_cancel\fR() returns 0 on success;
.BR io_cancel ()
returns 0 on success;
on failure, it returns one of the errors listed under ERRORS.
.SH "ERRORS"
.TP
@ -61,18 +63,22 @@ One of the data structures points to invalid data.
The \fIiocb\fR specified was not cancelled.
.TP
.B ENOSYS
\fBio_cancel\fR() is not implemented on this architecture.
.BR io_cancel ()
is not implemented on this architecture.
.SH "VERSIONS"
.PP
The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
.SH "CONFORMING TO"
.PP
\fBio_cancel\fR() is Linux specific and should not be used
.BR io_cancel ()
is Linux specific and should not be used
in programs that are intended to be portable.
.SH "SEE ALSO"
.PP
\fBio_setup\fR(2), \fBio_destroy\fR(2), \fBio_getevents\fR(2),
\fBio_submit\fR(2).
.BR io_setup (2),
.BR io_destroy (2),
.BR io_getevents (2),
.BR io_submit (2).
.\" .SH "NOTES"
.\"
.\" .PP

21
man2/io_destroy.2
View File

@ -37,13 +37,16 @@ io_destroy \- destroy an asynchronous I/O context
.fi
.SH "DESCRIPTION"
.PP
\fBio_destroy\fR() removes the asynchronous I/O context from the list of
.BR io_destroy ()
removes the asynchronous I/O context from the list of
I/O contexts and then destroys it.
\fBio_destroy\fR() can also cancel any outstanding asynchronous I/O
.BR io_destroy ()
can also cancel any outstanding asynchronous I/O
actions on \fIctx\fR and block on completion.
.SH "RETURN VALUE"
.PP
\fBio_destroy\fR() returns 0 on success;
.BR io_destroy ()
returns 0 on success;
on failure, it returns one of the errors listed under ERRORS.
.SH "ERRORS"
.SH "ERRORS"
@ -55,18 +58,22 @@ The AIO context specified by \fIctx\fR is invalid.
The context pointed to is invalid.
.TP
.B ENOSYS
\fBio_destroy\fR() is not implemented on this architecture.
.BR io_destroy ()
is not implemented on this architecture.
.SH "CONFORMING TO"
.PP
\fBio_destroy\fR() is Linux specific and should not be used in programs
.BR io_destroy ()
is Linux specific and should not be used in programs
that are intended to be portable.
.SH "VERSIONS"
.PP
The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
.SH "SEE ALSO"
.PP
\fBio_setup\fR(2), \fBio_submit\fR(2), \fBio_getevents\fR(2),
\fBio_cancel\fR(2).
.BR io_setup (2),
.BR io_submit (2),
.BR io_getevents (2),
.BR io_cancel (2).
.\" .SH "NOTES"
.\"
.\" .PP

19
man2/io_getevents.2
View File

@ -40,7 +40,8 @@ io_getevents \- read asynchronous I/O events from the completion queue
.fi
.SH "DESCRIPTION"
.PP
\fBio_getevents\fR() attempts to read at least \fImin_nr\fR events and
.BR io_getevents ()
attempts to read at least \fImin_nr\fR events and
up to \fInr\fR events from the completion queue of the AIO context
specified by \fIctx_id\fR.
\fItimeout\fR specifies the amount of time to wait for events,
@ -51,7 +52,8 @@ and the operation blocks.
.SH "RETURN VALUE"
.PP
On success,
\fBio_getevents\fR() returns the number of events read: 0 if no events are
.BR io_getevents ()
returns the number of events read: 0 if no events are
available or < \fImin_nr\fR if the \fItimeout\fR has elapsed;
on failure, it returns one of the errors listed under ERRORS.
.SH "ERRORS"
@ -64,18 +66,23 @@ out of range.
Either \fIevents\fR or \fItimeout\fR is an invalid pointer.
.TP
.B ENOSYS
\fBio_getevents\fR() is not implemented on this architecture.
.BR io_getevents ()
is not implemented on this architecture.
.SH "CONFORMING TO"
.PP
\fBio_getevents\fR() is Linux specific and should not be used in
.BR io_getevents ()
is Linux specific and should not be used in
programs that are intended to be portable.
.SH "VERSIONS"
.PP
The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
.SH "SEE ALSO"
.PP
\fBio_setup\fR(2), \fBio_submit\fR(2), \fBio_getevents\fR(2),
\fBio_cancel\fR(2), \fBio_destroy\fR(2).
.BR io_setup (2),
.BR io_submit (2),
.BR io_getevents (2),
.BR io_cancel (2),
.BR io_destroy (2).
.\" .SH "NOTES"
.\"
.\" .PP

18
man2/io_setup.2
View File

@ -37,7 +37,8 @@ io_setup \- create an asynchronous I/O context
.fi
.SH "DESCRIPTION"
.PP
\fBio_setup\fR() creates an asynchronous I/O context capable of receiving
.BR io_setup ()
creates an asynchronous I/O context capable of receiving
at least \fInr_events\fR.
\fIctxp\fR must not point to an AIO context that already exists, and must
be initialized to 0 prior to the call.
@ -45,7 +46,8 @@ On successful creation of the AIO context, \fI*ctxp\fR is filled in
with the resulting handle.
.SH "RETURN VALUE"
.PP
\fBio_setup\fR() returns 0 on success;
.BR io_setup ()
returns 0 on success;
on failure, it returns one of the errors listed under ERRORS.
.SH "ERRORS"
.TP
@ -63,18 +65,22 @@ Insufficient kernel resources are available.
The specified \fInr_events\fR exceeds the user's limit of available events.
.TP
.B ENOSYS
\fBio_setup\fR() is not implemented on this architecture.
.BR io_setup ()
is not implemented on this architecture.
.SH "CONFORMING TO"
.PP
\fBio_setup\fR() is Linux specific and should not be used in programs
.BR io_setup ()
is Linux specific and should not be used in programs
that are intended to be portable.
.SH "VERSIONS"
.PP
The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
.SH "SEE ALSO"
.PP
\fBio_destroy\fR(2), \fBio_getevents\fR(2), \fBio_submit\fR(2),
\fBio_cancel\fR(2).
.BR io_destroy (2),
.BR io_getevents (2),
.BR io_submit (2),
.BR io_cancel (2).
.\" .SH "NOTES"
.\" .PP
.\" The asynchronous I/O system calls were written by Benjamin LaHaise.

18
man2/io_submit.2
View File

@ -37,14 +37,16 @@ io_submit \- submit asynchronous I/O blocks for processing
.fi
.SH "DESCRIPTION"
.PP
\fBio_submit\fR() queues \fInr\fR I/O request blocks for processing in
.BR io_submit ()
queues \fInr\fR I/O request blocks for processing in
the AIO context \fIctx_id\fR. \fIiocbpp\fR should be an array of
\fInr\fR AIO request blocks,
which will be submitted to context \fIctx_id\fR.
.SH "RETURN VALUE"
.PP
On success,
\fBio_submit\fR() returns the number of \fIiocb\fRs submitted (which may be
.BR io_submit ()
returns the number of \fIiocb\fRs submitted (which may be
0 if \fInr\fR is zero);
on failure, it returns one of the errors listed under ERRORS.
.SH "ERRORS"
@ -65,18 +67,22 @@ The file descriptor specified in the first \fIiocb\fR is invalid.
Insufficient resources are available to queue any \fIiocb\fRs.
.TP
.B ENOSYS
\fBio_submit\fR() is not implemented on this architecture.
.BR io_submit ()
is not implemented on this architecture.
.SH "CONFORMING TO"
.PP
\fBio_submit\fR() is Linux specific and should not be used in
.BR io_submit ()
is Linux specific and should not be used in
programs that are intended to be portable.
.SH "VERSIONS"
.PP
The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
.SH "SEE ALSO"
.PP
\fBio_setup\fR(2), \fBio_destroy\fR(2), \fBio_getevents\fR(2),
\fBio_cancel\fR(2).
.BR io_setup (2),
.BR io_destroy (2),
.BR io_getevents (2),
.BR io_cancel (2).
.\" .SH "NOTES"
.\" .PP
.\" The asynchronous I/O system calls were written by Benjamin LaHaise.

6
man2/ioperm.2
View File

@ -44,7 +44,8 @@ ioperm \- set port input/output permissions
.sp
.BI "int ioperm(unsigned long " from ", unsigned long " num ", int " turn_on );
.SH DESCRIPTION
\fBioperm\fP() sets the port access permission bits for the process for
.BR ioperm ()
sets the port access permission bits for the process for
\fInum\fP bytes starting from port address \fBfrom\fP to the value
\fBturn_on\fP.
If \fBturn_on\fP is non-zero, the calling process must be privileged
@ -87,7 +88,8 @@ Out of memory.
.B EPERM
The calling process has insufficient privilege.
.SH "CONFORMING TO"
\fBioperm\fP() is Linux specific and should not be used in programs
.BR ioperm ()
is Linux specific and should not be used in programs
intended to be portable.
.SH NOTES
Libc5 treats it as a system call and has a prototype in

3
man2/iopl.2
View File

@ -83,7 +83,8 @@ the
.B CAP_SYS_RAWIO
capability is required.
.SH "CONFORMING TO"
\fBiopl\fP() is Linux specific and should not be used in processes
.BR iopl ()
is Linux specific and should not be used in processes
intended to be portable.
.SH NOTES
Libc5 treats it as a system call and has a prototype in

3
man2/ipc.2
View File

@ -44,7 +44,8 @@ User programs should call the appropriate functions by their usual names.
Only standard library implementors and kernel hackers need to know about
.BR ipc ().
.SH "CONFORMING TO"
\fBipc\fP() is Linux specific, and should not be used in programs
.BR ipc ()
is Linux specific, and should not be used in programs
intended to be portable.
.SH "SEE ALSO"
.BR msgctl (2),

4
man2/kill.2
View File

@ -99,7 +99,9 @@ to any of the target processes.
The pid or process group does not exist.
Note that an existing process might be a zombie,
a process which already committed termination, but
has not yet been \fBwait\fP(2)ed for.
has not yet been
.BR wait (2)ed
for.
.SH NOTES
The only signals that can be sent process ID 1, the
.I init

4
man2/lseek.2
View File

@ -120,7 +120,9 @@ Some devices are incapable of seeking and POSIX does not specify which
devices must support
.BR lseek ().
Linux specific restrictions: using \fBlseek\fP() on a tty device returns
Linux specific restrictions: using
.BR lseek ()
on a tty device returns
\fBESPIPE\fP.
.\" Other systems return the number of written characters,
.\" using SEEK_SET to set the counter. (Of written characters.)

4
man2/madvise.2
View File

@ -80,7 +80,9 @@ Do not expect access in the near future.
so the kernel can free resources associated with it.)
Subsequent accesses of pages in this range will succeed, but will result
either in re-loading of the memory contents from the underlying mapped file
(see \fBmmap\fP(2)) or zero-fill-on-demand pages for mappings
(see
.BR mmap (2))
or zero-fill-on-demand pages for mappings
without an underlying file.
.TP
.BR MADV_REMOVE " (Since Linux 2.6.16)"

3
man2/mprotect.2
View File

@ -64,7 +64,8 @@ The memory can contain executing code.
.PP
The new protection replaces any existing protection.
For example, if the
memory had previously been marked \fBPROT_READ\fR, and \fBmprotect\fR()
memory had previously been marked \fBPROT_READ\fR, and
.BR mprotect ()
is then called with \fIprot\fR \fBPROT_WRITE\fR, it will no longer
be readable.
.SH "RETURN VALUE"

16
man2/mremap.2
View File

@ -41,7 +41,8 @@ mremap \- re-map a virtual memory address
.BI " size_t " new_size ", int " flags );
.fi
.SH DESCRIPTION
\fBmremap\fR() expands (or shrinks) an existing memory mapping, potentially
.BR mremap ()
expands (or shrinks) an existing memory mapping, potentially
moving it at the same time (controlled by the \fIflags\fR argument and
the available virtual address space).
@ -64,10 +65,13 @@ writing to a read-only segment).
Accessing virtual memory outside of the
segments will also cause a segmentation violation.
\fBmremap\fR() uses the Linux page table scheme.
\fBmremap\fR() changes the
.BR mremap ()
uses the Linux page table scheme.
.BR mremap ()
changes the
mapping between virtual addresses and memory pages.
This can be used to implement a very efficient \fBrealloc\fR(3).
This can be used to implement a very efficient
.BR realloc (3).
The \fIflags\fR bit-mask argument may be 0, or include the following flag:
.TP
@ -115,7 +119,9 @@ or similar), then this lock is maintained when the segment is
resized and/or relocated.
As a consequence, the amount of memory locked by the process may change.
.SH "RETURN VALUE"
On success \fBmremap\fR() returns a pointer to the new virtual memory area.
On success
.BR mremap ()
returns a pointer to the new virtual memory area.
On error, the value
.B MAP_FAILED
(that is, (void *) \-1) is returned, and \fIerrno\fR is set appropriately.

20
man2/open.2
View File

@ -183,7 +183,9 @@ If \fIpathname\fR is not a directory, cause the open to fail.
.\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
.\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
This flag is Linux-specific, and was added in kernel version 2.1.126, to
avoid denial-of-service problems if \fBopendir\fR(3) is called on a
avoid denial-of-service problems if
.BR opendir (3)
is called on a
FIFO or tape device, but should not be used outside of the
implementation of \fBopendir\fR.
.TP
@ -203,7 +205,9 @@ atomic file locking using a lockfile is to create a unique file on
the same file system (e.g., incorporating hostname and pid), use
.BR link (2)
to make a link to the lockfile.
If \fBlink\fP(2) returns 0, the lock is
If
.BR link (2)
returns 0, the lock is
successful.
Otherwise, use
.BR stat (2)
@ -373,10 +377,16 @@ cannot create them; use
.BR mknod (2)
instead.
.LP
On NFS file systems with UID mapping enabled, \fBopen\fP() may
return a file descriptor but e.g. \fBread\fP(2) requests are denied
On NFS file systems with UID mapping enabled,
.BR open ()
may
return a file descriptor but e.g.
.BR read (2)
requests are denied
with \fBEACCES\fP.
This is because the client performs \fBopen\fP() by checking the
This is because the client performs
.BR open ()
by checking the
permissions, but UID mapping is performed by the server upon
read and write requests.

3
man2/outb.2
View File

@ -56,7 +56,8 @@ I/O ports in question.
Failure to do this will cause the application
to receive a segmentation fault.
.SH "CONFORMING TO"
\fBoutb\fP() and friends are hardware specific.
.BR outb ()
and friends are hardware specific.
The
.I value
argument is passed first and the

61
man2/pivot_root.2
View File

@ -17,7 +17,8 @@ pivot_root \- change the root file system
.sp
.BI "int pivot_root(const char *" new_root ", const char *" put_old );
.SH DESCRIPTION
\fBpivot_root\fP() moves the root file system of the current process to the
.BR pivot_root ()
moves the root file system of the current process to the
directory \fIput_old\fP and makes \fInew_root\fP the new root file system
of the current process.
.\"
@ -25,24 +26,32 @@ of the current process.
.\" .B CAP_SYS_ADMIN
.\" capability is required.
The typical use of \fBpivot_root\fP() is during system startup, when the
The typical use of
.BR pivot_root ()
is during system startup, when the
system mounts a temporary root file system (e.g. an \fBinitrd\fP), then
mounts the real root file system, and eventually turns the latter into
the current root of all relevant processes or threads.
\fBpivot_root\fP() may or may not change the current root and the current
.BR pivot_root ()
may or may not change the current root and the current
working directory (cwd) of any processes or threads which use the old
root directory.
The caller of \fBpivot_root\fP()
The caller of
.BR pivot_root ()
must ensure that processes with root or cwd at the old root operate
correctly in either case.
An easy way to ensure this is to change their
root and cwd to \fInew_root\fP before invoking \fBpivot_root\fP().
root and cwd to \fInew_root\fP before invoking
.BR pivot_root ().
The paragraph above is intentionally vague because the implementation
of \fBpivot_root\fP() may change in the future.
of
.BR pivot_root ()
may change in the future.
At the time of writing,
\fBpivot_root\fP() changes root and cwd of each process or
.BR pivot_root ()
changes root and cwd of each process or
thread to \fInew_root\fP if they point to the old root directory.
This
is necessary in order to prevent kernel threads from keeping the old
@ -51,12 +60,15 @@ the file system in any way.
In the future, there may be a mechanism for
kernel threads to explicitly relinquish any access to the file system,
such that this fairly intrusive mechanism can be removed from
\fBpivot_root\fP().
.BR pivot_root ().
Note that this also applies to the current process: \fBpivot_root\fP() may
Note that this also applies to the current process:
.BR pivot_root ()
may
or may not affect its cwd.
It is therefore recommended to call
\fBchdir("/")\fP immediately after \fBpivot_root\fP().
\fBchdir("/")\fP immediately after
.BR pivot_root ().
The following restrictions apply to \fInew_root\fP and \fIput_old\fP:
.IP \- 3
@ -71,10 +83,15 @@ the same directory as \fInew_root\fP.
.IP \- 3
No other file system may be mounted on \fIput_old\fP.
.PP
See also \fBpivot_root(8)\fP for additional usage examples.
See also
.BR pivot_root (8)
for additional usage examples.
If the current root is not a mount point (e.g. after \fBchroot(2)\fP or
\fBpivot_root\fP(), see also below), not the old root directory, but the
If the current root is not a mount point (e.g. after
.BR chroot (2)
or
.BR pivot_root (),
see also below), not the old root directory, but the
mount point of that file system is mounted on \fIput_old\fP.
.SH NOTES
\fInew_root\fP does not have to be a mount point.
@ -86,8 +103,9 @@ On success, zero is returned.
On error, \-1 is returned, and
\fIerrno\fP is set appropriately.
.SH ERRORS
\fBpivot_root\fP() may return (in \fIerrno\fP) any of the errors returned by
\fBstat(2)\fP.
.BR pivot_root ()
may return (in \fIerrno\fP) any of the errors returned by
.BR stat (2).
Additionally, it may return:
.TP
.B EBUSY
@ -105,15 +123,20 @@ The current process does not have the
.B CAP_SYS_ADMIN
capability.
.SH BUGS
\fBpivot_root\fP() should not have to change root and cwd of all other
.BR pivot_root ()
should not have to change root and cwd of all other
processes in the system.
Some of the more obscure uses of \fBpivot_root\fP() may quickly lead to
Some of the more obscure uses of
.BR pivot_root ()
may quickly lead to
insanity.
.SH "CONFORMING TO"
\fBpivot_root\fP() is Linux specific and hence is not portable.
.BR pivot_root ()
is Linux specific and hence is not portable.
.SH HISTORY
\fBpivot_root\fP() was introduced in Linux 2.3.41.
.BR pivot_root ()
was introduced in Linux 2.3.41.
.SH "SEE ALSO"
.BR chdir (2),
.BR chroot (2),

10
man2/posix_fadvise.2
View File

@ -34,7 +34,9 @@ posix_fadvise \- predeclare an access pattern for file data
.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len ", int " advice ");"
.fi
.SH DESCRIPTION
Programs can use \fBposix_fadvise\fP() to announce an intention to access
Programs can use
.BR posix_fadvise ()
to announce an intention to access
file data in a specific pattern in the future, thus allowing the kernel
to perform appropriate optimisations.
@ -113,7 +115,11 @@ discarded instead.
Pages that have not yet been written out will be unaffected, so if the
application wishes to guarantee that pages will be released, it should
call \fBfsync\fP(2) or \fBfdatasync\fP(2) first.
call
.BR fsync (2)
or
.BR fdatasync (2)
first.
.SH "CONFORMING TO"
POSIX.1-2001.
Note that the type of the

20
man2/pread.2
View File

@ -60,7 +60,9 @@ The file referenced by
must be capable of seeking.
.SH "RETURN VALUE"
On success, the number of bytes read or written is returned (zero
indicates that nothing was written, in the case of \fBpwrite\fR(), or
indicates that nothing was written, in the case of
.BR pwrite (),
or
end of file, in the case of \fBpread\fR), or \-1 on error, in which
case
.I errno
@ -69,15 +71,25 @@ is set to indicate the error.
.BR pread ()
can fail and set
.I errno
to any error specified for \fBread\fR(2) or \fBlseek\fR(2).
to any error specified for
.BR read (2)
or
.BR lseek (2).
.BR pwrite ()
can fail and set
.I errno
to any error specified for \fBwrite\fR(2) or \fBlseek\fR(2).
to any error specified for
.BR write (2)
or
.BR lseek (2).
.SH "CONFORMING TO"
POSIX.1-2001.
.SH HISTORY
The \fBpread\fR() and \fBpwrite\fR() system calls were added to Linux in
The
.BR pread ()
and
.BR pwrite ()
system calls were added to Linux in
version 2.1.60; the entries in the i386 system call table were added
in 2.1.69.
The libc support (including emulation on older kernels

7
man2/read.2
View File

@ -52,7 +52,9 @@ into the buffer starting at
.PP
If
.I count
is zero, \fBread\fP() returns zero and has no other results.
is zero,
.BR read ()
returns zero and has no other results.
If
.I count
is greater than SSIZE_MAX, the result is unspecified.
@ -63,7 +65,8 @@ It is not an error if this number is smaller than the number of bytes
requested; this may happen for example because fewer bytes are actually
available right now (maybe because we were close to end-of-file, or
because we are reading from a pipe, or from a terminal), or because
\fBread\fP() was interrupted by a signal.
.BR read ()
was interrupted by a signal.
On error, \-1 is returned, and
.I errno
is set appropriately.

11
man2/sched_get_priority_max.2
View File

@ -57,8 +57,11 @@ Further details about these policies can be found in
Processes with numerically higher priority values are scheduled before
processes with numerically lower priority values.
Thus, the value
returned by \fBsched_get_priority_max\fR() will be greater than the
value returned by \fBsched_get_priority_min\fR().
returned by
.BR sched_get_priority_max ()
will be greater than the
value returned by
.BR sched_get_priority_min ().
Linux allows the static priority value range 1 to 99 for
\fISCHED_FIFO\fR and \fISCHED_RR\fR and the priority 0 for
@ -69,7 +72,9 @@ are not alterable.
The range of scheduling priorities may vary on other POSIX systems,
thus it is a good idea for portable applications to use a virtual
priority range and map it to the interval given by
\fBsched_get_priority_max\fR() and \fBsched_get_priority_min\fR().
.BR sched_get_priority_max ()
and
.BR sched_get_priority_min ().
POSIX.1-2001 requires a spread of at least 32 between the maximum and the
minimum values for \fISCHED_FIFO\fR and \fISCHED_RR\fR.

4
man2/sched_rr_get_interval.2
View File

@ -99,7 +99,9 @@ The default quantum is 0.1 seconds;
the degree to which changing the nice value affects the
quantum has varied somewhat across kernel versions.
.\" .SH BUGS
.\" As of Linux 1.3.81 \fBsched_rr_get_interval\fR() returns with error
.\" As of Linux 1.3.81
.BR sched_rr_get_interval ()
returns with error
.\" ENOSYS, because SCHED_RR has not yet been fully implemented and tested
.\" properly.
.SH "SEE ALSO"

6
man2/sched_setparam.2
View File

@ -69,8 +69,10 @@ of the current process are retrieved.
checks the validity of \fIparam\fR for the scheduling policy of the
process.
The parameter \fIparam->sched_priority\fR must lie within the
range given by \fBsched_get_priority_min\fR(2) and
\fBsched_get_priority_max\fR(2).
range given by
.BR sched_get_priority_min (2)
and
.BR sched_get_priority_max (2).
For a discussion of the privileges and resource limits related to
scheduling priority and policy, see

28
man2/sched_setscheduler.2
View File

@ -110,8 +110,11 @@ Processes scheduled with \fISCHED_OTHER\fP or \fISCHED_BATCH\fP
must be assigned the static priority 0.
Processes scheduled under \fISCHED_FIFO\fP or
\fISCHED_RR\fP can have a static priority in the range 1 to 99.
The system calls \fBsched_get_priority_min\fP(2) and
\fBsched_get_priority_max\fP(2) can be used to find out the valid
The system calls
.BR sched_get_priority_min (2)
and
.BR sched_get_priority_max (2)
can be used to find out the valid
priority range for a scheduling policy in a portable way on all
POSIX.1-2001 conforming systems.
@ -137,7 +140,10 @@ blocked again.
When a \fISCHED_FIFO\fP process becomes runnable, it
will be inserted at the end of the list for its priority.
A call to
\fBsched_setscheduler\fP() or \fBsched_setparam\fP(2) will put the
.BR sched_setscheduler ()
or
.BR sched_setparam (2)
will put the
\fISCHED_FIFO\fP (or \fISCHED_RR\fP) process identified by
\fIpid\fP at the start of the list if it was runnable.
As a consequence, it may preempt the currently running process if
@ -146,14 +152,17 @@ it has the same priority.
of the list.)
.\" In 2.2.x and 2.4.x, the process is placed at the front of the queue
.\" In 2.0.x, the Right Thing happened: the process went to the back -- MTK
A process calling \fBsched_yield\fP(2) will be
A process calling
.BR sched_yield (2)
will be
put at the end of the list.
No other events will move a process
scheduled under the \fISCHED_FIFO\fP policy in the wait list of
runnable processes with equal static priority.
A \fISCHED_FIFO\fP
process runs until either it is blocked by an I/O request, it is
preempted by a higher priority process, or it calls \fBsched_yield\fP(2).
preempted by a higher priority process, or it calls
.BR sched_yield (2).
.SS SCHED_RR: Round Robin scheduling
\fISCHED_RR\fP is a simple enhancement of \fISCHED_FIFO\fP.
Everything
@ -168,7 +177,8 @@ been preempted by a higher priority process and subsequently resumes
execution as a running process will complete the unexpired portion of
its round robin time quantum.
The length of the time quantum can be
retrieved using \fBsched_rr_get_interval\fP(2).
retrieved using
.BR sched_rr_get_interval (2).
.\" On Linux 2.4, the length of the RR interval is influenced
.\" by the process nice value -- MTK
.\"
@ -181,7 +191,11 @@ The process to run is chosen from the static
priority 0 list based on a dynamic priority that is determined only
inside this list.
The dynamic priority is based on the nice level (set
by \fBnice\fP(2) or \fBsetpriority\fP(2)) and increased for
by
.BR nice (2)
or
.BR setpriority (2))
and increased for
each time quantum the process is ready to run, but denied to run by
the scheduler.
This ensures fair progress among all \fISCHED_OTHER\fP

266
man2/select_tut.2
View File

@ -64,7 +64,10 @@ synchronous I/O multiplexing
.fi
.SH DESCRIPTION
\fBselect\fP() (or \fBpselect\fP()) is the pivot function of
.BR select ()
(or
.BR pselect ())
is the pivot function of
most C programs that
handle more than one simultaneous file descriptor (or socket handle)
in an efficient
@ -72,7 +75,8 @@ manner.
Its principal arguments are three arrays of file descriptors:
\fIreadfds\fP, \fIwritefds\fP, and \fIexceptfds\fP.
The way that
\fBselect\fP() is usually used is to block while waiting for a "change of
.BR select ()
is usually used is to block while waiting for a "change of
status" on one or more of the file descriptors.
A "change of status" is
when more characters become available from the file descriptor, \fIor\fP
@ -81,40 +85,65 @@ more to be written to the file descriptor, \fIor\fP when a file
descriptor goes into error (in the case of a socket or pipe this is
when the other end of the connection is closed).
In summary, \fBselect\fP() just watches multiple file descriptors,
In summary,
.BR select ()
just watches multiple file descriptors,
and is the standard Unix call to do so.
The arrays of file descriptors are called \fIfile descriptor sets\fP.
Each set is declared as type \fBfd_set\fP, and its contents can be
altered with the macros \fBFD_CLR\fP(), \fBFD_ISSET\fP(),
\fBFD_SET\fP(), and \fBFD_ZERO\fP().
\fBFD_ZERO\fP() is usually the first function to be used on
altered with the macros
.BR FD_CLR (),
.BR FD_ISSET (),
.BR FD_SET (),
and
.BR FD_ZERO ().
.BR FD_ZERO ()
is usually the first function to be used on
a newly declared set.
Thereafter, the individual file descriptors that
you are interested in can be added one by one with \fBFD_SET\fP().
\fBselect\fP() modifies the contents of the sets according to the rules
described below; after calling \fBselect\fP() you can test if your file
descriptor is still present in the set with the \fBFD_ISSET\fP() macro.
\fBFD_ISSET\fP() returns non-zero if the descriptor is present and zero if
you are interested in can be added one by one with
.BR FD_SET ().
.BR select ()
modifies the contents of the sets according to the rules
described below; after calling
.BR select ()
you can test if your file
descriptor is still present in the set with the
.BR FD_ISSET ()
macro.
.BR FD_ISSET ()
returns non-zero if the descriptor is present and zero if
it is not.
\fBFD_CLR\fP() removes a file descriptor from the set.
.BR FD_CLR ()
removes a file descriptor from the set.
.SH ARGUMENTS
.TP
\fIreadfds\fP
This set is watched to see if data is available for reading from any of
its file descriptors.
After \fBselect\fP() has returned, \fIreadfds\fP will be
After
.BR select ()
has returned, \fIreadfds\fP will be
cleared of all file descriptors except for those file descriptors that
are immediately available for reading with a \fBrecv\fP(2) (for sockets) or
\fBread\fP(2) (for pipes, files, and sockets) call.
are immediately available for reading with a
.BR recv (2)
(for sockets) or
.BR read (2)
(for pipes, files, and sockets) call.
.TP
\fIwritefds\fP
This set is watched to see if there is space to write data to any of
its file descriptors.
After \fBselect\fP() has returned, \fIwritefds\fP will be
After
.BR select ()
has returned, \fIwritefds\fP will be
cleared of all file descriptors except for those file descriptors that
are immediately available for writing with a \fBsend\fP(2) (for sockets) or
\fBwrite\fP(2) (for pipes, files, and sockets) call.
are immediately available for writing with a
.BR send (2)
(for sockets) or
.BR write (2)
(for pipes, files, and sockets) call.
.TP
\fIexceptfds\fP
This set is watched for exceptions or errors on any of the file
@ -125,14 +154,23 @@ How you use
OOB data
is data sent on a socket using the \fBMSG_OOB\fP flag, and hence
\fIexceptfds\fP only really applies to sockets.
See \fBrecv\fP(2) and
\fBsend\fP(2) about this.
After \fBselect\fP() has returned,
See
.BR recv (2)
and
.BR send (2)
about this.
After
.BR select ()
has returned,
\fIexceptfds\fP will be cleared of all file descriptors except for those
descriptors that are available for reading OOB data.
You can only ever
read one byte of OOB data though (which is done with \fBrecv\fP(2)), and
writing OOB data (done with \fBsend\fP(2)) can be done at any time and will
read one byte of OOB data though (which is done with
.BR recv (2)),
and
writing OOB data (done with
.BR send (2))
can be done at any time and will
not block.
Hence there is no need for a fourth set to check if a socket
is available for writing OOB data.
@ -143,15 +181,21 @@ any of the sets.
In other words, while you are busy adding file descriptors
to your sets, you must calculate the maximum integer value of all of
them, then increment this value by one, and then pass this as \fInfds\fP to
\fBselect\fP().
.BR select ().
.TP
\fIutimeout\fP
.RS
This is the longest time \fBselect\fP() must wait before returning, even
This is the longest time
.BR select ()
must wait before returning, even
if nothing interesting happened.
If this value is passed as NULL,
then \fBselect\fP() blocks indefinitely waiting for an event.
\fIutimeout\fP can be set to zero seconds, which causes \fBselect\fP() to
then
.BR select ()
blocks indefinitely waiting for an event.
\fIutimeout\fP can be set to zero seconds, which causes
.BR select ()
to
return immediately.
The structure \fBstruct timeval\fP is defined as,
.PP
@ -178,41 +222,60 @@ struct timespec {
.TP
\fIsigmask\fP
This argument holds a set of signals to allow while performing a
\fBpselect\fP() call (see \fBsigaddset\fP(3) and \fBsigprocmask\fP(2)).
.BR pselect ()
call (see
.BR sigaddset (3)
and
.BR sigprocmask (2)).
It can be passed
as NULL, in which case it does not modify the set of allowed signals on
entry and exit to the function.
It will then behave just like \fBselect\fP().
It will then behave just like
.BR select ().
.SH COMBINING SIGNAL AND DATA EVENTS
\fBpselect\fP() must be used if you are waiting for a signal as well as
.BR pselect ()
must be used if you are waiting for a signal as well as
data from a file descriptor.
Programs that receive signals as events
normally use the signal handler only to raise a global flag.
The global
flag will indicate that the event must be processed in the main loop of
the program.
A signal will cause the \fBselect\fP() (or \fBpselect\fP())
A signal will cause the
.BR select ()
(or
.BR pselect ())
call to return with \fIerrno\fP set to \fBEINTR\fP.
This behavior is
essential so that signals can be processed in the main loop of the
program, otherwise \fBselect\fP() would block indefinitely.
program, otherwise
.BR select ()
would block indefinitely.
Now, somewhere
in the main loop will be a conditional to check the global flag.
So we
must ask: what if a signal arrives after the conditional, but before the
\fBselect\fP() call?
The answer is that \fBselect\fP() would block
.BR select ()
call?
The answer is that
.BR select ()
would block
indefinitely, even though an event is actually pending.
This race
condition is solved by the \fBpselect\fP() call.
condition is solved by the
.BR pselect ()
call.
This call can be used to
mask out signals that are not to be received except within the
\fBpselect\fP() call.
.BR pselect ()
call.
For instance, let us say that the event in question
was the exit of a child process.
Before the start of the main loop, we
would block \fBSIGCHLD\fP using \fBsigprocmask\fP(2).
Our \fBpselect\fP()
would block \fBSIGCHLD\fP using
.BR sigprocmask (2).
Our
.BR pselect ()
call would enable \fBSIGCHLD\fP by using the virgin signal mask.
Our
program would look like:
@ -249,9 +312,13 @@ main(int argc, char **argv)
}
.fi
.SH PRACTICAL
So what is the point of \fBselect\fP()? Can't I just read and write to my
So what is the point of
.BR select ()?
Can't I just read and write to my
descriptors whenever I want?
The point of \fBselect\fP() is that it watches
The point of
.BR select ()
is that it watches
multiple descriptors at the same time and properly puts the process to
sleep if there is no activity.
It does this while enabling you to handle
@ -260,10 +327,16 @@ Unix programmers often find
themselves in a position where they have to handle I/O from more than one
file descriptor where the data flow may be intermittent.
If you were to
merely create a sequence of \fBread\fP(2) and \fBwrite\fP(2) calls, you would
merely create a sequence of
.BR read (2)
and
.BR write (2)
calls, you would
find that one of your calls may block waiting for data from/to a file
descriptor, while another file descriptor is unused though available
for data. \fBselect\fP() efficiently copes with this situation.
for data.
.BR select ()
efficiently copes with this situation.
A simple example of the use of
.BR select ()
@ -272,7 +345,7 @@ can be found in the
manual page.
.SH PORT FORWARDING EXAMPLE
Here is an example that better demonstrates the true utility of
\fBselect\fP().
.BR select ().
The listing below is a TCP forwarding program that forwards
from one TCP port to another.
.PP
@ -545,12 +618,14 @@ including OOB signal data transmitted by \fBtelnet\fP servers.
It
handles the tricky problem of having data flow in both directions
simultaneously.
You might think it more efficient to use a \fBfork\fP(2)
You might think it more efficient to use a
.BR fork (2)
call and devote a thread to each stream.
This becomes more tricky than
you might suspect.
Another idea is to set non-blocking I/O using an
\fBioctl\fP(2) call.
.BR ioctl (2)
call.
This also has its problems because you end up having
to have inefficient timeouts.
@ -560,19 +635,26 @@ of buffers \(em one for each connection.
At the moment, new
connections cause the current connection to be dropped.
.SH SELECT LAW
Many people who try to use \fBselect\fP() come across behavior that is
Many people who try to use
.BR select ()
come across behavior that is
difficult to understand and produces non-portable or borderline
results.
For instance, the above program is carefully written not to
block at any point, even though it does not set its file descriptors to
non-blocking mode at all (see \fBioctl\fP(2)).
non-blocking mode at all (see
.BR ioctl (2)).
It is easy to introduce
subtle errors that will remove the advantage of using \fBselect\fP(),
subtle errors that will remove the advantage of using
.BR select (),
hence I will present a list of essentials to watch for when using the
\fBselect\fP() call.
.BR select ()
call.
.TP
\fB1.\fP
You should always try to use \fBselect\fP() without a timeout.
You should always try to use
.BR select ()
without a timeout.
Your program
should have nothing to do if there is no data available.
Code that
@ -584,12 +666,16 @@ explained above.
.TP
\fB3.\fP
No file descriptor must be added to any set if you do not intend
to check its result after the \fBselect\fP() call, and respond
to check its result after the
.BR select ()
call, and respond
appropriately.
See next rule.
.TP
\fB4.\fP
After \fBselect\fP() returns, all file descriptors in all sets
After
.BR select ()
returns, all file descriptors in all sets
should be checked to see if they are ready.
.\" mtk, May 2006: the following isn't really true.
.\" Any file descriptor that is available
@ -597,8 +683,13 @@ should be checked to see if they are ready.
.\" available for reading \fImust\fP be read, etc.
.TP
\fB5.\fP
The functions \fBread\fP(2), \fBrecv\fP(2), \fBwrite\fP(2), and
\fBsend\fP(2) do \fInot\fP necessarily read/write the full amount of data
The functions
.BR read (2),
.BR recv (2),
.BR write (2),
and
.BR send (2)
do \fInot\fP necessarily read/write the full amount of data
that you have requested.
If they do read/write the full amount, its
because you have a low traffic load and a fast stream.
@ -616,8 +707,15 @@ The buffers in the example above are 1024 bytes although they could
easily be made larger.
.TP
\fB7.\fP
The functions \fBread\fP(2), \fBrecv\fP(2), \fBwrite\fP(2), and
\fBsend\fP(2) as well as the \fBselect\fP() call can return \-1 with
The functions
.BR read (2),
.BR recv (2),
.BR write (2),
and
.BR send (2)
as well as the
.BR select ()
call can return \-1 with
.I errno
set to \fBEINTR\fP,
or with
@ -633,12 +731,22 @@ Nonetheless
you should still cope with these errors for completeness.
.TP
\fB8.\fP
Never call \fBread\fP(2), \fBrecv\fP(2), \fBwrite\fP(2), or \fBsend\fP(2)
Never call
.BR read (2),
.BR recv (2),
.BR write (2),
or
.BR send (2)
with a buffer length of zero.
.TP
\fB9.\fP
If the functions \fBread\fP(2),
\fBrecv\fP(2), \fBwrite\fP(2), and \fBsend\fP(2) fail
If the functions
.BR read (2),
.BR recv (2),
.BR write (2),
and
.BR send (2)
fail
with errors other than those listed in \fB7.\fP,
or one of the input functions returns 0, indicating end of file,
then you should \fInot\fP pass that descriptor to
@ -649,21 +757,28 @@ I close the descriptor immediately, and then set it to \-1
to prevent it being included in a set.
.TP
\fB10.\fP
The timeout value must be initialized with each new call to \fBselect\fP(),
The timeout value must be initialized with each new call to
.BR select (),
since some operating systems modify the structure.
\fBpselect\fP() however does not modify its timeout structure.
.BR pselect ()
however does not modify its timeout structure.
.TP
\fB11.\fP
I have heard that the Windows socket layer does not cope with OOB data
properly.
It also does not cope with \fBselect\fP() calls when no file
It also does not cope with
.BR select ()
calls when no file
descriptors are set at all.
Having no file descriptors set is a useful
way to sleep the process with sub-second precision by using the timeout.
(See further on.)
.SH USLEEP EMULATION
On systems that do not have a \fBusleep\fP(3) function, you can call
\fBselect\fP() with a finite timeout and no file descriptors as
On systems that do not have a
.BR usleep (3)
function, you can call
.BR select ()
with a finite timeout and no file descriptors as
follows:
.PP
.nf
@ -675,10 +790,14 @@ follows:
.PP
This is only guaranteed to work on Unix systems, however.
.SH RETURN VALUE
On success, \fBselect\fP() returns the total number of file descriptors
On success,
.BR select ()
returns the total number of file descriptors
still present in the file descriptor sets.
If \fBselect\fP() timed out, then
If
.BR select ()
timed out, then
the return value will be zero.
The file descriptors set should be all
empty (but may not be on some systems).
@ -687,25 +806,30 @@ A return value of \-1 indicates an error, with \fIerrno\fP being
set appropriately.
In the case of an error, the returned sets and
the timeout struct contents are undefined and should not be used.
\fBpselect\fP() however never modifies \fIntimeout\fP.
.BR pselect ()
however never modifies \fIntimeout\fP.
.SH NOTES
Generally speaking, all operating systems that support sockets, also
support \fBselect\fP().
support
.BR select ().
Many types of programs become
extremely complicated without the use of
.BR select ().
\fBselect\fP() can be used to solve
.BR select ()
can be used to solve
many problems in a portable and efficient way that naive programmers try
to solve in a more complicated manner using
threads, forking, IPCs, signals, memory sharing, and so on.
.PP
The
.BR poll (2)
system call has the same functionality as \fBselect\fP(),
system call has the same functionality as
.BR select (),
and is somewhat more efficient when monitoring sparse
file descriptor sets.
It is nowadays widely available,
but historically was less portable than \fBselect\fP().
but historically was less portable than
.BR select ().
.PP
The Linux-specific
.BR epoll (7)

16
man2/setpgid.2
View File

@ -67,7 +67,9 @@ If
is zero, the process ID of the process specified by
.I pid
is used.
If \fBsetpgid\fP() is used to move a process from one process
If
.BR setpgid ()
is used to move a process from one process
group to another (as is done by some shells when creating pipelines),
both process groups must be part of the same session.
In this case,
@ -141,13 +143,16 @@ always returns the current process group.
.B EACCES
An attempt was made to change the process group ID
of one of the children of the calling process and the child had
already performed an \fBexecve\fP(2)
(\fBsetpgid\fP(), \fBsetpgrp\fP()).
already performed an
.BR execve (2)
.RB ( setpgid (),
.BR setpgrp ()).
.TP
.B EINVAL
.I pgid
is less than 0
(\fBsetpgid\fP(), \fBsetpgrp\fP()).
.RB ( setpgid (),
.BR setpgrp ()).
.TP
.B EPERM
An attempt was made to move a process into a process group in a
@ -155,7 +160,8 @@ different session, or to change the process
group ID of one of the children of the calling process and the
child was in a different session, or to change the process group ID of
a session leader
(\fBsetpgid\fP(), \fBsetpgrp\fP()).
.RB ( setpgid (),
.BR setpgrp ()).
.TP
.B ESRCH
For

3
man2/setsid.2
View File

@ -36,7 +36,8 @@ setsid \- creates a session and sets the process group ID
.br
.ad b
.SH DESCRIPTION
\fBsetsid\fP() creates a new session if the calling process is not a
.BR setsid ()
creates a new session if the calling process is not a
process group leader.
The calling process is the leader of the new
session, the process group leader of the new process group, and has no

37
man2/sigaltstack.2
View File

@ -27,7 +27,8 @@ sigaltstack \- set and/or get signal stack context
.sp
.BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss );
.SH DESCRIPTION
\fBsigaltstack\fP() allows a process to define a new alternate
.BR sigaltstack ()
allows a process to define a new alternate
signal stack and/or retrieve the state of an existing
alternate signal stack.
An alternate signal stack is used during the
@ -43,11 +44,14 @@ Allocate an area of memory to be used for the alternate
signal stack.
.TP
2.
Use \fBsigaltstack\fP() to inform the system of the existence and
Use
.BR sigaltstack ()
to inform the system of the existence and
location of the alternate signal stack.
.TP
3.
When establishing a signal handler using \fBsigaction\fP(2),
When establishing a signal handler using
.BR sigaction (2),
inform the system that the signal handler should be executed
on the alternate signal stack by
specifying the \fBSA_ONSTACK\fP flag.
@ -90,7 +94,8 @@ in \fIss\fP are ignored.
If \fIoss\fP is not NULL, then it is used to return information about
the alternate signal stack which was in effect prior to the
call to \fBsigaltstack\fP().
call to
.BR sigaltstack ().
The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
address and size of that stack.
The \fIoss.ss_flags\fP may return either of the following values:
@ -104,7 +109,8 @@ currently executing on it.)
.B SS_DISABLE
The alternate signal stack is currently disabled.
.SH "RETURN VALUE"
\fBsigaltstack\fP() returns 0 on success, or \-1 on failure with
.BR sigaltstack ()
returns 0 on success, or \-1 on failure with
\fIerrno\fP set to indicate the error.
.SH ERRORS
.TP
@ -133,7 +139,8 @@ normal process stack is exhausted: in this case, a signal handler for
cannot be invoked on the process stack; if we wish to handle it,
we must use an alternate signal stack.
The following code segment demonstrates the use of \fBsigaltstack\fP():
The following code segment demonstrates the use of
.BR sigaltstack ():
.RS
.nf
@ -161,7 +168,8 @@ on an alternate signal stack.
.P
On most hardware architectures supported by Linux, stacks grow
downwards.
\fBsigaltstack\fP() automatically takes account
.BR sigaltstack ()
automatically takes account
of the direction of stack growth.
.P
Functions called from a signal handler executing on an alternate
@ -173,12 +181,19 @@ automatically extend the alternate signal stack.
Exceeding the allocated size of the alternate signal stack will
lead to unpredictable results.
.P
A successful call to \fBexecve\fP(2) removes any existing alternate
A successful call to
.BR execve (2)
removes any existing alternate
signal stack.
.P
\fBsigaltstack\fP() supersedes the older \fBsigstack\fP() call.
For backwards compatibility, glibc also provides \fBsigstack\fP().
All new applications should be written using \fBsigaltstack\fP().
.BR sigaltstack ()
supersedes the older
.BR sigstack ()
call.
For backwards compatibility, glibc also provides
.BR sigstack ().
All new applications should be written using
.BR sigaltstack ().
.SH HISTORY
4.2BSD had a \fIsigstack\fP() system call.
It used a slightly

6
man2/stime.2
View File

@ -37,10 +37,12 @@ stime \- set time
.sp
.BI "int stime(time_t *" t );
.SH DESCRIPTION
\fBstime\fP() sets the system's idea of the time and date.
.BR stime ()
sets the system's idea of the time and date.
Time, pointed
to by \fIt\fP, is measured in seconds from 00:00:00 GMT January 1, 1970.
\fBstime\fP() may only be executed by the superuser.
.BR stime ()
may only be executed by the superuser.
.SH "RETURN VALUE"
On success, zero is returned.
On error, \-1 is returned, and

3
man2/sync.2
View File

@ -47,7 +47,8 @@ This function is always successful.
SVr4, 4.3BSD, POSIX.1-2001.
.SH BUGS
According to the standard specification (e.g., POSIX.1-2001),
\fBsync\fP() schedules the writes, but may return before the actual
.BR sync ()
schedules the writes, but may return before the actual
writing is done.
However, since version 1.3.20 Linux does actually wait.
(This still does not guarantee data integrity: modern disks have

4
man2/syslog.2
View File

@ -161,7 +161,9 @@ as follows:
.SH "RETURN VALUE"
In case of error, \-1 is returned, and \fIerrno\fP is set.
Otherwise,
for \fItype\fP equal to 2, 3 or 4, \fBsyslog\fP() returns the number
for \fItype\fP equal to 2, 3 or 4,
.BR syslog ()
returns the number
of bytes read, and otherwise 0.
.SH ERRORS
.TP

3
man2/time.2
View File

@ -34,7 +34,8 @@ time \- get time in seconds
.sp
.BI "time_t time(time_t *" t );
.SH DESCRIPTION
\fBtime\fP() returns the time since the Epoch
.BR time ()
returns the time since the Epoch
(00:00:00 UTC, January 1, 1970), measured in seconds.
If

35
man2/tkill.2
View File

@ -45,20 +45,32 @@ tkill, tgkill \- send a signal to a single process
.B int tgkill(int tgid, int tid, int sig);
.fi
.SH DESCRIPTION
The \fBtkill\fP() system call is analogous to
The
.BR tkill ()
system call is analogous to
.BR kill (2),
except when the specified process is part of a thread group
(created by specifying the CLONE_THREAD flag in the call to clone).
Since all the processes in a thread group have the same PID,
they cannot be individually signalled with \fBkill\fP(2).
With \fBtkill\fP(), however, one can address each process
they cannot be individually signalled with
.BR kill (2).
With
.BR tkill (),
however, one can address each process
by its unique TID.
.PP
The \fBtgkill\fP() call improves on \fBtkill\fP() by allowing the caller to
The
.BR tgkill ()
call improves on
.BR tkill ()
by allowing the caller to
specify the thread group ID of the thread to be signalled, protecting
against TID reuse.
If the tgid is specified as \-1, \fBtgkill\fP() degenerates
into \fBtkill\fP().
If the tgid is specified as \-1,
.BR tgkill ()
degenerates
into
.BR tkill ().
.PP
These are the raw system call interfaces, meant for internal
thread library use.
@ -79,11 +91,16 @@ For the required permissions, see
.B ESRCH
No process with the specified thread ID (and thread group ID) exists.
.SH "CONFORMING TO"
\fBtkill\fP() and \fBtgkill\fP() are Linux specific and should not be used
.BR tkill ()
and
.BR tgkill ()
are Linux specific and should not be used
in programs that are intended to be portable.
.SH VERSIONS
\fBtkill\fP() is supported since Linux 2.4.19 / 2.5.4.
\fBtgkill\fP() was added in Linux 2.5.75.
.BR tkill ()
is supported since Linux 2.4.19 / 2.5.4.
.BR tgkill ()
was added in Linux 2.5.75.
.SH "SEE ALSO"
.BR gettid (2),
.BR kill (2)

10
man2/uselib.2
View File

@ -36,7 +36,9 @@ uselib \- load shared library
.sp
.BI "int uselib(const char *" library );
.SH DESCRIPTION
The system call \fBuselib\fP() serves to load
The system call
.BR uselib ()
serves to load
a shared library to be used by the calling process.
It is given a pathname.
The address where to load is found
@ -72,10 +74,12 @@ The file specified by
is not an executable of known type,
e.g., does not have the correct magic numbers.
.SH "CONFORMING TO"
\fBuselib\fP() is Linux specific, and should not be used in programs
.BR uselib ()
is Linux specific, and should not be used in programs
intended to be portable.
.SH NOTES
\fBuselib\fP() was used by early libc startup code to load
.BR uselib ()
was used by early libc startup code to load
the shared libraries with names found in an array of names
in the binary.
.LP

7
man2/write.2
View File

@ -45,8 +45,11 @@ bytes to the file referenced by the file descriptor
.I fd
from the buffer starting at
.IR buf .
POSIX requires that a \fBread\fP(2) which can be proved to occur after a
\fBwrite\fP() has returned returns the new data.
POSIX requires that a
.BR read (2)
which can be proved to occur after a
.BR write ()
has returned returns the new data.
Note that not all file
systems are POSIX conforming.
.SH "RETURN VALUE"

15
man3/abort.3
View File

@ -37,15 +37,22 @@ abort \- cause abnormal program termination
.B void abort(void);
.fi
.SH DESCRIPTION
The \fBabort\fP() function causes abnormal program termination unless
The
.BR abort ()
function causes abnormal program termination unless
the signal SIGABRT is caught and the signal handler does not return.
If the \fBabort\fP() function causes program termination, all open
If the
.BR abort ()
function causes program termination, all open
streams are closed and flushed.
.PP
If the SIGABRT signal is blocked or ignored, the \fBabort\fP()
If the SIGABRT signal is blocked or ignored, the
.BR abort ()
function will still override it.
.SH "RETURN VALUE"
The \fBabort\fP() function never returns.
The
.BR abort ()
function never returns.
.SH "CONFORMING TO"
SVr4, POSIX.1-2001, 4.3BSD, C89, C99
.SH "SEE ALSO"

49
man3/abs.3
View File

@ -47,9 +47,15 @@ abs, labs, llabs, imaxabs \- compute the absolute value of an integer
.BI "intmax_t imaxabs(intmax_t " j );
.fi
.SH DESCRIPTION
The \fBabs\fP() function computes the absolute value of the integer
The
.BR abs ()
function computes the absolute value of the integer
argument \fIj\fP.
The \fBlabs\fP(), \fBllabs\fP() and \fBimaxabs\fP()
The
.BR labs (),
.BR llabs ()
and
.BR imaxabs ()
functions compute the absolute value of the argument \fIj\fP of the
appropriate integer type for the function.
.SH "RETURN VALUE"
@ -57,25 +63,48 @@ Returns the absolute value of the integer argument, of the appropriate
integer type for the function.
.SH "CONFORMING TO"
SVr4, POSIX.1-2001, 4.3BSD, C99.
.\" POSIX.1 (1996 edition) only requires the \fBabs\fP() function.
.\" POSIX.1 (1996 edition) only requires the
.BR abs ()
function.
C89 only
includes the \fBabs\fP() and \fBlabs\fP() functions; the functions
\fBllabs\fP() and \fBimaxabs\fP() were added in C99.
includes the
.BR abs ()
and
.BR labs ()
functions; the functions
.BR llabs ()
and
.BR imaxabs ()
were added in C99.
.SH NOTES
Trying to take the absolute value of the most negative integer
is not defined.
.PP
The \fBllabs\fP() function is included in glibc since version 2.0, but
The
.BR llabs ()
function is included in glibc since version 2.0, but
is not in libc5 or libc4.
The \fBimaxabs\fP() function is included in
The
.BR imaxabs ()
function is included in
glibc since version 2.1.1.
.PP
For \fBllabs\fP() to be declared, it may be necessary to define
For
.BR llabs ()
to be declared, it may be necessary to define
\fB_ISOC99_SOURCE\fP or \fB_ISOC9X_SOURCE\fP (depending on the
version of glibc) before including any standard headers.
.PP
GCC handles \fBabs\fP() and \fBlabs\fP() as builtin functions.
GCC 3.0 also handles \fBllabs\fP() and \fBimaxabs\fP() as builtins.
GCC handles
.BR abs ()
and
.BR labs ()
as builtin functions.
GCC 3.0 also handles
.BR llabs ()
and
.BR imaxabs ()
as builtins.
.SH "SEE ALSO"
.BR cabs (3),
.BR ceil (3),

12
man3/acos.3
View File

@ -42,12 +42,18 @@ acos, acosf, acosl \- arc cosine function
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBacos\fP() function calculates the arc cosine of \fIx\fP; that is
The
.BR acos ()
function calculates the arc cosine of \fIx\fP; that is
the value whose cosine is \fIx\fP.
If \fIx\fP falls outside the range
\-1 to 1, \fBacos\fP() fails and \fIerrno\fP is set.
\-1 to 1,
.BR acos ()
fails and \fIerrno\fP is set.
.SH "RETURN VALUE"
The \fBacos\fP() function returns the arc cosine in radians and the
The
.BR acos ()
function returns the arc cosine in radians and the
value is mathematically defined to be between 0 and PI (inclusive).
.SH ERRORS
.TP

8
man3/acosh.3
View File

@ -44,9 +44,13 @@ acosh, acoshf, acoshl \- inverse hyperbolic cosine function
.fi
Link with \-lm.
.SH DESCRIPTION
The \fBacosh\fP() function calculates the inverse hyperbolic cosine of
The
.BR acosh ()
function calculates the inverse hyperbolic cosine of
\fIx\fP; that is the value whose hyperbolic cosine is \fIx\fP.
If \fIx\fP is less than 1.0, \fBacosh\fP() returns
If \fIx\fP is less than 1.0,
.BR acosh ()
returns
not-a-number (NaN) and \fIerrno\fP is set.
.SH ERRORS
.TP

12
man3/asin.3
View File

@ -44,12 +44,18 @@ asin, asinf, asinl \- arc sine function
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBasin\fP() function calculates the arc sine of \fIx\fP; that is
The
.BR asin ()
function calculates the arc sine of \fIx\fP; that is
the value whose sine is \fIx\fP.
If \fIx\fP falls outside the range
\-1 to 1, \fBasin\fP() fails and \fIerrno\fP is set.
\-1 to 1,
.BR asin ()
fails and \fIerrno\fP is set.
.SH "RETURN VALUE"
The \fBasin\fP() function returns the arc sine in radians and the
The
.BR asin ()
function returns the arc sine in radians and the
value is mathematically defined to be between \-PI/2 and PI/2
(inclusive).
.SH ERRORS

4
man3/asinh.3
View File

@ -44,7 +44,9 @@ asinh, asinhf, asinhl \- inverse hyperbolic sine function
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBasinh\fP() function calculates the inverse hyperbolic sine of
The
.BR asinh ()
function calculates the inverse hyperbolic sine of
\fIx\fP; that is the value whose hyperbolic sine is \fIx\fP.
.SH "CONFORMING TO"
SVr4, POSIX.1-2001, 4.3BSD, C89.

8
man3/atan.3
View File

@ -44,10 +44,14 @@ atan, atanf, atanl \- arc tangent function
.fi
Link with \-lm.
.SH DESCRIPTION
The \fBatan\fP() function calculates the arc tangent of \fIx\fP; that is
The
.BR atan ()
function calculates the arc tangent of \fIx\fP; that is
the value whose tangent is \fIx\fP.
.SH "RETURN VALUE"
The \fBatan\fP() function returns the arc tangent in radians and the
The
.BR atan ()
function returns the arc tangent in radians and the
value is mathematically defined to be between \-PI/2 and PI/2
(inclusive).
.SH "CONFORMING TO"

8
man3/atan2.3
View File

@ -44,13 +44,17 @@ atan2, atan2f, atan2l \- arc tangent function of two variables
.fi
Link with \-lm.
.SH DESCRIPTION
The \fBatan2\fP() function calculates the arc tangent of the two
The
.BR atan2 ()
function calculates the arc tangent of the two
variables \fIx\fP and \fIy\fP.
It is similar to calculating the
arc tangent of \fIy\fP / \fIx\fP, except that the signs of both
arguments are used to determine the quadrant of the result.
.SH "RETURN VALUE"
The \fBatan2\fP() function returns the result in radians, which
The
.BR atan2 ()
function returns the result in radians, which
is between \-PI and PI (inclusive).
.SH "CONFORMING TO"
SVr4, POSIX.1-2001, 4.3BSD, C89.

8
man3/atanh.3
View File

@ -44,9 +44,13 @@ atanh, atanhf, atanhl \- inverse hyperbolic tangent function
.fi
Link with \-lm.
.SH DESCRIPTION
The \fBatanh\fP() function calculates the inverse hyperbolic tangent of
The
.BR atanh ()
function calculates the inverse hyperbolic tangent of
\fIx\fP; that is the value whose hyperbolic tangent is \fIx\fP.
If the absolute value of \fIx\fP is greater than 1.0, \fBatanh\fP() returns
If the absolute value of \fIx\fP is greater than 1.0,
.BR atanh ()
returns
not-a-number (NaN) and \fIerrno\fP is set.
.SH ERRORS
.TP

18
man3/atexit.3
View File

@ -38,7 +38,9 @@ atexit \- register a function to be called at normal process termination
.BI "int atexit(void (*" function )(void));
.fi
.SH DESCRIPTION
The \fBatexit\fP() function registers the given \fIfunction\fP to be
The
.BR atexit ()
function registers the given \fIfunction\fP to be
called at normal process termination, either via
.BR exit (3)
or via return from the program's \fImain\fP().
@ -58,7 +60,9 @@ Upon a successful call to one of the
functions,
all registrations are removed.
.SH "RETURN VALUE"
The \fBatexit\fP() function returns the value 0 if successful; otherwise
The
.BR atexit ()
function returns the value 0 if successful; otherwise
it returns a non-zero value.
.SH EXAMPLE
.nf
@ -90,11 +94,17 @@ main(void)
}
.fi
.SH NOTES
Since glibc 2.2.3, \fBatexit\fP() (and \fBon_exit\fP(3))
Since glibc 2.2.3,
.BR atexit ()
(and
.BR on_exit (3))
can be used to within a shared library to establish functions
that are called when the shared library is unloaded.
.PP
Functions registered using \fBatexit\fP() (and \fBon_exit\fP(3))
Functions registered using
.BR atexit ()
(and
.BR on_exit (3))
are not called if a process terminates abnormally because
of the delivery of a signal.
.SH "CONFORMING TO"

8
man3/atof.3
View File

@ -36,7 +36,9 @@ atof \- convert a string to a double
.BI "double atof(const char *" nptr );
.fi
.SH DESCRIPTION
The \fBatof\fP() function converts the initial portion of the string
The
.BR atof ()
function converts the initial portion of the string
pointed to by \fInptr\fP to double.
The behaviour is the same as
.sp
@ -44,7 +46,9 @@ The behaviour is the same as
.B strtod(nptr, (char **) NULL);
.RE
.sp
except that \fBatof\fP() does not detect errors.
except that
.BR atof ()
does not detect errors.
.SH "RETURN VALUE"
The converted value.
.SH "CONFORMING TO"

35
man3/atoi.3
View File

@ -44,7 +44,9 @@ atoi, atol, atoll, atoq \- convert a string to an integer
.BI "long long atoq(const char *" nptr );
.fi
.SH DESCRIPTION
The \fBatoi\fP() function converts the initial portion of the string
The
.BR atoi ()
function converts the initial portion of the string
pointed to by \fInptr\fP to
.IR int .
The behaviour is the same as
@ -53,25 +55,42 @@ The behaviour is the same as
.B strtol(nptr, (char **) NULL, 10);
.RE
.sp
except that \fBatoi\fP() does not detect errors.
except that
.BR atoi ()
does not detect errors.
.PP
The \fBatol\fP() and \fBatoll\fP() functions behave the same as
\fBatoi\fR(), except that they convert the initial portion of the
The
.BR atol ()
and
.BR atoll ()
functions behave the same as
.BR atoi (),
except that they convert the initial portion of the
string to their return type of \fIlong\fP or \fIlong long\fP.
\fBatoq\fP() is an obsolete name for \fBatoll\fP().
.BR atoq ()
is an obsolete name for
.BR atoll ().
.SH "RETURN VALUE"
The converted value.
.SH "CONFORMING TO"
SVr4, POSIX.1-2001, 4.3BSD, C99.
C89 and
POSIX.1-1996 include the functions \fBatoi\fP() and \fBatol\fP() only.
POSIX.1-1996 include the functions
.BR atoi ()
and
.BR atol ()
only.
.BR atoq (3)
is a GNU extension.
.SH NOTES
The non-standard \fBatoq\fP() function is not present in libc 4.6.27
The non-standard
.BR atoq ()
function is not present in libc 4.6.27
or glibc 2, but is present in libc5 and libc 4.7 (though only as an
inline function in \fB<stdlib.h>\fP until libc 5.4.44).
The \fBatoll\fP() function is present in glibc 2 since version 2.0.2, but
The
.BR atoll ()
function is present in glibc 2 since version 2.0.2, but
not in libc4 or libc5.
.SH "SEE ALSO"
.BR atof (3),

8
man3/bsearch.3
View File

@ -39,7 +39,9 @@ bsearch \- binary search of a sorted array
.RE
.fi
.SH DESCRIPTION
The \fBbsearch\fP() function searches an array of \fInmemb\fP objects,
The
.BR bsearch ()
function searches an array of \fInmemb\fP objects,
the initial member of which is pointed to by \fIbase\fP, for a member
that matches the object pointed to by \fIkey\fP.
The size of each member
@ -54,7 +56,9 @@ less than, equal to, or greater than zero if the \fIkey\fP object is found,
respectively, to be less than, to match, or be greater than the array
member.
.SH "RETURN VALUE"
The \fBbsearch\fP() function returns a pointer to a matching member of the
The
.BR bsearch ()
function returns a pointer to a matching member of the
array, or NULL if no match is found.
If there are multiple elements that
match the key, the element returned is unspecified.

20
man3/btowc.3
View File

@ -21,14 +21,20 @@ btowc \- convert single byte to wide character
.BI "wint_t btowc(int " c );
.fi
.SH DESCRIPTION
The \fBbtowc\fP() function converts \fIc\fP,
The
.BR btowc ()
function converts \fIc\fP,
interpreted as a multibyte sequence
of length 1, starting in the initial shift state, to a wide character and
returns it.
If \fIc\fP is EOF or not a valid multibyte sequence of length 1,
the \fBbtowc\fP() function returns WEOF.
the
.BR btowc ()
function returns WEOF.
.SH "RETURN VALUE"
The \fBbtowc\fP() function returns the wide character
The
.BR btowc ()
function returns the wide character
converted from the single byte \fIc\fP.
If \fIc\fP is EOF or not a valid multibyte sequence of length 1,
it returns WEOF.
@ -37,11 +43,15 @@ C99, POSIX.1-2001.
.SH "SEE ALSO"
.BR mbtowc (3)
.SH NOTES
The behaviour of \fBbtowc\fP() depends on the LC_CTYPE category of the
The behaviour of
.BR btowc ()
depends on the LC_CTYPE category of the
current locale.
.PP
This function should never be used.
It does not work for encodings which have
state, and unnecessarily treats single bytes differently from multibyte
sequences.
Use the function \fBmbtowc\fP() instead.
Use the function
.BR mbtowc ()
instead.

16
man3/byteorder.3
View File

@ -44,16 +44,24 @@ byte order
.BI "uint16_t ntohs(uint16_t " netshort );
.fi
.SH DESCRIPTION
The \fBhtonl\fP() function converts the unsigned integer \fIhostlong\fP
The
.BR htonl ()
function converts the unsigned integer \fIhostlong\fP
from host byte order to network byte order.
.PP
The \fBhtons\fP() function converts the unsigned short integer \fIhostshort\fP
The
.BR htons ()
function converts the unsigned short integer \fIhostshort\fP
from host byte order to network byte order.
.PP
The \fBntohl\fP() function converts the unsigned integer \fInetlong\fP
The
.BR ntohl ()
function converts the unsigned integer \fInetlong\fP
from network byte order to host byte order.
.PP
The \fBntohs\fP() function converts the unsigned short integer \fInetshort\fP
The
.BR ntohs ()
function converts the unsigned short integer \fInetshort\fP
from network byte order to host byte order.
.PP
On the i80x86 the host byte order is Least Significant Byte first,

4
man3/cbrt.3
View File

@ -41,7 +41,9 @@ cbrt, cbrtf, cbrtl \- cube root function
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBcbrt\fP() function returns the (real) cube root of \fIx\fP.
The
.BR cbrt ()
function returns the (real) cube root of \fIx\fP.
This function cannot fail; every representable real value has a
representable real cube root.
.SH "CONFORMING TO"

15
man3/clearenv.3
View File

@ -31,12 +31,16 @@ clearenv \- clear the environment
.BI "int clearenv(void);"
.fi
.SH DESCRIPTION
The \fBclearenv\fP() function clears the environment of all name-value
The
.BR clearenv ()
function clears the environment of all name-value
pairs and sets the value of the external variable
.I environ
to NULL.
.SH "RETURN VALUE"
The \fBclearenv\fP() function returns zero on success, and a non-zero
The
.BR clearenv ()
function returns zero on success, and a non-zero
value on failure.
.\" Most versions of Unix return -1 on error, or do not even have errors.
.\" Glibc info and the Watcom C library document "a non-zero value".
@ -46,11 +50,14 @@ In glibc since glibc 2.0.
.SH "CONFORMING TO"
Various Unix variants (DG/UX, HP-UX, QNX, ...).
POSIX.9 (bindings for FORTRAN77).
POSIX.1-1996 did not accept \fBclearenv\fP() and \fIputenv\fP(3),
POSIX.1-1996 did not accept
.BR clearenv ()
and \fIputenv\fP(3),
but changed its mind and scheduled these functions for some
later issue of this standard (cf. B.4.6.1).
However, POSIX.1-2001
only adds \fIputenv\fP(3), and rejected \fBclearenv\fP().
only adds \fIputenv\fP(3), and rejected
.BR clearenv ().
.SH NOTES
Used in security-conscious applications.
If it is unavailable

8
man3/closedir.3
View File

@ -38,12 +38,16 @@ closedir \- close a directory
.BI "int closedir(DIR *" dir );
.fi
.SH DESCRIPTION
The \fBclosedir\fP() function closes the directory stream associated with
The
.BR closedir ()
function closes the directory stream associated with
\fIdir\fP.
The directory stream descriptor \fIdir\fP is not available
after this call.
.SH "RETURN VALUE"
The \fBclosedir\fP() function returns 0 on success.
The
.BR closedir ()
function returns 0 on success.
On error, \-1 is returned, and
.I errno
is set appropriately.

8
man3/copysign.3
View File

@ -42,12 +42,16 @@ copysign, copysignf, copysignl \- copy sign of a number
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBcopysign\fP() functions return a value whose absolute value matches
The
.BR copysign ()
functions return a value whose absolute value matches
that of \fIx\fP, but whose sign matches that of \fIy\fP.
If \fIx\fP is a NaN, then a NaN with the sign of \fIy\fP is returned.
.SH NOTES
On architectures where the floating-point formats are not IEEE 754 compliant,
the \fBcopysign\fP() functions may treat a negative zero as positive.
the
.BR copysign ()
functions may treat a negative zero as positive.
.SH "CONFORMING TO"
C99, 4.3BSD.
This function is defined in IEC 559 (and the appendix with

8
man3/cos.3
View File

@ -43,10 +43,14 @@ cos, cosf, cosl \- cosine function
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBcos\fP() function returns the cosine of \fIx\fP, where \fIx\fP is
The
.BR cos ()
function returns the cosine of \fIx\fP, where \fIx\fP is
given in radians.
.SH "RETURN VALUE"
The \fBcos\fP() function returns a value between \-1 and 1.
The
.BR cos ()
function returns a value between \-1 and 1.
.SH "CONFORMING TO"
SVr4, 4.3BSD, C99.
The

4
man3/cosh.3
View File

@ -45,7 +45,9 @@ cosh, coshf, coshl \- hyperbolic cosine function
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBcosh\fP() function returns the hyperbolic cosine of \fIx\fP, which
The
.BR cosh ()
function returns the hyperbolic cosine of \fIx\fP, which
is defined mathematically as (exp(x) + exp(\-x)) / 2.
.SH "CONFORMING TO"
SVr4, POSIX, 4.3BSD, C99.

59
man3/ctime.3
View File

@ -57,13 +57,22 @@ localtime_r \- transform date and time to broken-down time or ASCII
.BI "time_t mktime(struct tm *" tm );
.fi
.SH DESCRIPTION
The \fBctime\fP(), \fBgmtime\fP() and \fBlocaltime\fP() functions all take
The
.BR ctime (),
.BR gmtime ()
and
.BR localtime ()
functions all take
an argument of data type \fItime_t\fP which represents calendar time.
When interpreted as an absolute time value, it represents the number of
seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal
Time (UTC).
.PP
The \fBasctime\fP() and \fBmktime\fP() functions both take an argument
The
.BR asctime ()
and
.BR mktime ()
functions both take an argument
representing broken-down time which is a representation
separated into year, month, day, etc.
.PP
@ -141,21 +150,29 @@ functions.
The function also sets the external variable \fItzname\fP (see
.BR tzset (3))
with information about the current time zone.
The re-entrant version \fBctime_r\fP() does the same, but stores the
The re-entrant version
.BR ctime_r ()
does the same, but stores the
string in a user-supplied buffer of length at least 26.
It need not
set \fItzname\fP.
.PP
The \fBgmtime\fP() function converts the calendar time \fItimep\fP to
The
.BR gmtime ()
function converts the calendar time \fItimep\fP to
broken-down time representation, expressed in Coordinated Universal Time
(UTC).
It may return NULL when the year does not fit into an integer.
The return value points to a statically allocated struct which might be
overwritten by subsequent calls to any of the date and time functions.
The \fBgmtime_r\fP() function does the same, but stores the data in a
The
.BR gmtime_r ()
function does the same, but stores the data in a
user-supplied struct.
.PP
The \fBlocaltime\fP() function converts the calendar time \fItimep\fP to
The
.BR localtime ()
function converts the calendar time \fItimep\fP to
broken-time representation, expressed relative to the user's specified
time zone.
The function acts as if it called
@ -167,18 +184,27 @@ seconds, and \fIdaylight\fP to a non-zero value if daylight savings
time rules apply during some part of the year.
The return value points to a statically allocated struct which might be
overwritten by subsequent calls to any of the date and time functions.
The \fBlocaltime_r\fP() function does the same, but stores the data in a
The
.BR localtime_r ()
function does the same, but stores the data in a
user-supplied struct.
It need not set \fItzname\fP.
.PP
The \fBasctime\fP() function converts the broken-down time value
\fItm\fP into a string with the same format as \fBctime\fP().
The
.BR asctime ()
function converts the broken-down time value
\fItm\fP into a string with the same format as
.BR ctime ().
The return value points to a statically allocated string which might be
overwritten by subsequent calls to any of the date and time functions.
The \fBasctime_r\fP() function does the same, but stores the string in
The
.BR asctime_r ()
function does the same, but stores the string in
a user-supplied buffer of length at least 26.
.PP
The \fBmktime\fP() function converts a broken-down time structure, expressed
The
.BR mktime ()
function converts a broken-down time structure, expressed
as local time, to calendar time representation.
The function ignores
the specified contents of the structure members \fItm_wday\fP and \fItm_yday\fP
@ -186,15 +212,20 @@ and recomputes them from the other information in the broken-down time
structure.
If structure members are outside their legal interval, they will be
normalized (so that, e.g., 40 October is changed into 9 November).
Calling \fBmktime\fP() also sets the external variable \fItzname\fP with
Calling
.BR mktime ()
also sets the external variable \fItzname\fP with
information about the current time zone.
If the specified broken-down
time cannot be represented as calendar time (seconds since the epoch),
\fBmktime\fP() returns a value of (time_t)(\-1) and does not alter the
.BR mktime ()
returns a value of (time_t)(\-1) and does not alter the
\fItm_wday\fP and \fItm_yday\fP members of the broken-down time structure.
.SH "RETURN VALUE"
Each of these functions returns the value described, or NULL
(\-1 in case of \fBmktime\fP()) in case an error was detected.
(\-1 in case of
.BR mktime ())
in case an error was detected.
.SH NOTES
The four functions
.BR asctime (),

4
man3/difftime.3
View File

@ -35,7 +35,9 @@ difftime \- calculate time difference
.BI "double difftime(time_t " time1 ", time_t " time0 );
.fi
.SH DESCRIPTION
The \fBdifftime\fP() function returns the number of seconds elapsed
The
.BR difftime ()
function returns the number of seconds elapsed
between time \fItime1\fP and time \fItime0\fP, represented as a double.
The two times are specified in calendar time, which represents the time
elapsed since the Epoch

11
man3/div.3
View File

@ -48,7 +48,9 @@ an integer division
.BI "imaxdiv_t imaxdiv(intmax_t " numerator ", intmax_t " denominator );
.fi
.SH DESCRIPTION
The \fBdiv\fP() function computes the value
The
.BR div ()
function computes the value
\fInumerator\fP/\fIdenominator\fP and
returns the quotient and remainder in a structure
named \fIdiv_t\fP that contains
@ -56,7 +58,12 @@ two integer members (in unspecified order) named \fIquot\fP and \fIrem\fP.
The quotient is rounded towards zero.
The result satisfies \fIquot\fP*\fIdenominator\fP+\fIrem\fP = \fInumerator\fP.
.LP
The \fBldiv\fP() and \fBlldiv\fP() and \fBimaxdiv\fP() functions do the same,
The
.BR ldiv () and
.BR lldiv ()
and
.BR imaxdiv ()
functions do the same,
dividing numbers of the indicated type and
returning the result in a structure
of the indicated name, in all cases with fields \fIquot\fP and \fIrem\fP

89
man3/drand48.3
View File

@ -55,21 +55,45 @@ lcong48 \- generate uniformly distributed pseudo-random numbers
These functions generate pseudo-random numbers using the linear congruential
algorithm and 48-bit integer arithmetic.
.PP
The \fBdrand48\fP() and \fBerand48\fP() functions return non-negative
The
.BR drand48 ()
and
.BR erand48 ()
functions return non-negative
double-precision floating-point values uniformly distributed between
[0.0, 1.0).
.PP
The \fBlrand48\fP() and \fBnrand48\fP() functions return non-negative
The
.BR lrand48 ()
and
.BR nrand48 ()
functions return non-negative
long integers uniformly distributed between 0 and 2^31.
.PP
The \fBmrand48\fP() and \fBjrand48\fP() functions return signed long
The
.BR mrand48 ()
and
.BR jrand48 ()
functions return signed long
integers uniformly distributed between \-2^31 and 2^31.
.PP
The \fBsrand48\fP(), \fBseed48\fP() and \fBlcong48\fP() functions are
The
.BR srand48 (),
.BR seed48 ()
and
.BR lcong48 ()
functions are
initialization functions, one of which should be called before using
\fBdrand48\fP(), \fBlrand48\fP() or \fBmrand48\fP().
.BR drand48 (),
.BR lrand48 ()
or
.BR mrand48 ().
The functions
\fBerand48\fP(), \fBnrand48\fP() and \fBjrand48\fP() do not require
.BR erand48 (),
.BR nrand48 ()
and
.BR jrand48 ()
do not require
an initialization function to be called first.
.PP
All the functions work by generating a sequence of 48-bit integers,
@ -82,7 +106,9 @@ All the functions work by generating a sequence of 48-bit integers,
.fi
.sp
The parameter \fIm\fP = 2^48, hence 48-bit integer arithmetic is performed.
Unless \fBlcong48\fP() is called, \fIa\fP and \fIc\fP are given by:
Unless
.BR lcong48 ()
is called, \fIa\fP and \fIc\fP are given by:
.sp
.nf
.RS
@ -91,42 +117,69 @@ Unless \fBlcong48\fP() is called, \fIa\fP and \fIc\fP are given by:
.RE
.fi
.sp
The value returned by any of the functions \fBdrand48\fP(), \fBerand48\fP(),
\fBlrand48\fP(), \fBnrand48\fP(), \fBmrand48\fP() or \fBjrand48\fP() is
The value returned by any of the functions
.BR drand48 (),
.BR erand48 (),
.BR lrand48 (),
.BR nrand48 (),
.BR mrand48 ()
or
.BR jrand48 ()
is
computed by first generating the next 48-bit \fIXi\fP in the sequence.
Then the appropriate number of bits, according to the type of data item to
be returned, is copied from the high-order bits of \fIXi\fP and transformed
into the returned value.
.PP
The functions \fBdrand48\fP(), \fBlrand48\fP() and \fBmrand48\fP() store
The functions
.BR drand48 (),
.BR lrand48 ()
and
.BR mrand48 ()
store
the last 48-bit \fIXi\fP generated in an internal buffer.
The functions
\fBerand48\fP(), \fBnrand48\fP() and \fBjrand48\fP() require the calling
.BR erand48 (),
.BR nrand48 ()
and
.BR jrand48 ()
require the calling
program to provide storage for the successive \fIXi\fP values in the array
argument \fIxsubi\fP.
The functions are initialized by placing the initial
value of \fIXi\fP into the array before calling the function for the first
time.
.PP
The initializer function \fBsrand48\fP() sets the high order 32-bits of
The initializer function
.BR srand48 ()
sets the high order 32-bits of
\fIXi\fP to the argument \fIseedval\fP.
The low order 16-bits are set
to the arbitrary value 0x330E.
.PP
The initializer function \fBseed48\fP() sets the value of \fIXi\fP to
The initializer function
.BR seed48 ()
sets the value of \fIXi\fP to
the 48-bit value specified in the array argument \fIseed16v\fP.
The
previous value of \fIXi\fP is copied into an internal buffer and a
pointer to this buffer is returned by \fBseed48\fP().
pointer to this buffer is returned by
.BR seed48 ().
.PP
The initialization function \fBlcong48\fP() allows the user to specify
The initialization function
.BR lcong48 ()
allows the user to specify
initial values for \fIXi\fP, \fIa\fP and \fIc\fP.
Array argument
elements \fIparam[0-2]\fP specify \fIXi\fP, \fIparam[3-5]\fP specify
\fIa\fP, and \fIparam[6]\fP specifies \fIc\fP.
After \fBlcong48\fP()
has been called, a subsequent call to either \fBsrand48\fP() or
\fBseed48\fP() will restore the standard values of \fIa\fP and \fIc\fP.
After
.BR lcong48 ()
has been called, a subsequent call to either
.BR srand48 ()
or
.BR seed48 ()
will restore the standard values of \fIa\fP and \fIc\fP.
.SH "CONFORMING TO"
SVr4, POSIX.1-2001.
.SH NOTES

22
man3/ecvt.3
View File

@ -39,7 +39,9 @@ ecvt, fcvt \- convert a floating-point number to a string
.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt ,
.BI "int *" sign );
.SH DESCRIPTION
The \fBecvt\fP() function converts \fInumber\fP to a null-terminated
The
.BR ecvt ()
function converts \fInumber\fP to a null-terminated
string of \fIndigits\fP digits (where \fIndigits\fP is reduced to an
system-specific limit determined by the precision of a double),
and returns a pointer to the string.
@ -59,13 +61,23 @@ If
.I number
is zero, it is unspecified whether *\fIdecpt\fP is 0 or 1.
.PP
The \fBfcvt\fP() function is identical to \fBecvt\fP(), except that
The
.BR fcvt ()
function is identical to
.BR ecvt (),
except that
\fIndigits\fP specifies the number of digits after the decimal point.
.SH "RETURN VALUE"
Both the \fBecvt\fP() and \fBfcvt\fP() functions return a pointer to a
Both the
.BR ecvt ()
and
.BR fcvt ()
functions return a pointer to a
static string containing the ASCII representation of \fInumber\fP.
The static string is overwritten by each call to \fBecvt\fP() or
\fBfcvt\fP().
The static string is overwritten by each call to
.BR ecvt ()
or
.BR fcvt ().
.SH NOTES
These functions are obsolete.
Instead,

8
man3/erf.3
View File

@ -51,12 +51,16 @@ complementary error function
.fi
Link with \-lm.
.SH DESCRIPTION
The \fBerf\fP() function returns the error function of \fIx\fP; defined
The
.BR erf ()
function returns the error function of \fIx\fP; defined
as
.TP
erf(x) = 2/sqrt(pi)* integral from 0 to x of exp(\-t*t) dt
.PP
The \fBerfc\fP() function returns the complementary error function of
The
.BR erfc ()
function returns the complementary error function of
\fIx\fP, that is 1.0 \- erf(x).
.SH "CONFORMING TO"
SVr4, 4.3BSD, C99.

18
man3/error.3
View File

@ -45,7 +45,8 @@ error_print_progname \- glibc error reporting functions
\fBextern void (* \fIerror_print_progname\fB) (void);
.fi
.SH DESCRIPTION
\fBerror\fP() is a general error reporting function.
.BR error ()
is a general error reporting function.
It flushes
.IR stdout ,
and then outputs to
@ -79,7 +80,10 @@ calls
.BR exit (3)
to terminate the program using the given value as the exit status.
The \fBerror_at_line\fP() function is exactly the same as \fBerror\fP(),
The
.BR error_at_line ()
function is exactly the same as
.BR error (),
except for the addition of the arguments
.I filename
and
@ -91,19 +95,23 @@ except that after the program name are written: a colon, the value of
a colon, and the value of
.IR linenum .
The preprocessor values \fB__LINE__\fP and
\fB__FILE__\fP may be useful when calling \fBerror_at_line\fP(),
\fB__FILE__\fP may be useful when calling
.BR error_at_line (),
but other values can also be used.
For example, these arguments could refer to a location in an input file.
If the global variable \fIerror_one_per_line\fP is set non-zero,
a sequence of
\fBerror_at_line\fP() calls with the
.BR error_at_line ()
calls with the
same value of \fIfilename\fP and \fIlinenum\fP will result in only
one message (the first) being output.
The global variable \fIerror_message_count\fP counts the number of
messages that have been output by
\fBerror\fP() and \fBerror_at_line\fP().
.BR error ()
and
.BR error_at_line ().
If the global variable \fIerror_print_progname\fP
is assigned the address of a function

34
man3/ether_aton.3
View File

@ -55,29 +55,40 @@ ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines
.BI " struct ether_addr *" addr );
.fi
.SH DESCRIPTION
\fBether_aton\fP() converts the 48-bit Ethernet host address \fIasc\fP
.BR ether_aton ()
converts the 48-bit Ethernet host address \fIasc\fP
from the standard hex-digits-and-colons notation into binary data in
network byte order and returns a pointer to it in a statically
allocated buffer, which subsequent calls will
overwrite. \fBether_aton\fP() returns NULL if the address is invalid.
overwrite.
.BR ether_aton ()
returns NULL if the address is invalid.
.PP
The \fBether_ntoa\fP() function converts the Ethernet host address
The
.BR ether_ntoa ()
function converts the Ethernet host address
\fIaddr\fP given in network byte order to a string in standard
hex-digits-and-colons notation, omitting leading zeroes.
The string is returned in a statically allocated buffer,
which subsequent calls will overwrite.
.PP
The \fBether_ntohost\fP() function maps an Ethernet address to the
The
.BR ether_ntohost ()
function maps an Ethernet address to the
corresponding hostname in
.I /etc/ethers
and returns non-zero if it cannot be found.
.PP
The \fBether_hostton\fP() function maps a hostname to the
The
.BR ether_hostton ()
function maps a hostname to the
corresponding Ethernet address in
.I /etc/ethers
and returns non-zero if it cannot be found.
.PP
The \fBether_line\fP() function parses a line in
The
.BR ether_line ()
function parses a line in
.I /etc/ethers
format (ethernet address followed by whitespace followed by
hostname; '#' introduces a comment) and returns an address
@ -87,8 +98,15 @@ The buffer pointed to by
must be sufficiently long, e.g., have the same length as
.IR line .
.PP
The functions \fBether_ntoa_r\fP() and \fBether_aton_r\fP() are re-entrant
threadsafe versions of \fBether_ntoa\fP() and \fBether_aton\fP()
The functions
.BR ether_ntoa_r ()
and
.BR ether_aton_r ()
are re-entrant
threadsafe versions of
.BR ether_ntoa ()
and
.BR ether_aton ()
respectively, and do not use static buffers.
.PP
The structure \fIether_addr\fP is defined in \fInet/ethernet.h\fP as:

39
man3/exit.3
View File

@ -30,36 +30,55 @@ exit \- cause normal process termination
.BI "void exit(int " status );
.fi
.SH DESCRIPTION
The \fBexit\fP() function causes normal process termination and the
The
.BR exit ()
function causes normal process termination and the
value of \fIstatus & 0377\fP is returned to the parent
(see
.BR wait (2)).
.LP
All functions registered with
\fBatexit\fP(3) and \fBon_exit\fP(3)
.BR atexit (3)
and
.BR on_exit (3)
are called, in the reverse order of their registration.
(It is possible for one of these functions to use
\fBatexit\fP(3) or \fBon_exit\fP(3) to register an additional
.BR atexit (3)
or
.BR on_exit (3)
to register an additional
function to be executed during exit processing;
the new registration is added to the front of the list of functions
that remain to be called.)
.LP
All open streams are flushed and closed.
Files created by \fBtmpfile\fP(3) are removed.
Files created by
.BR tmpfile (3)
are removed.
.LP
The C standard specifies two constants,
\fIEXIT_SUCCESS\fP and \fIEXIT_FAILURE\fP,
that may be passed to \fBexit\fP() to indicate successful or unsuccessful
that may be passed to
.BR exit ()
to indicate successful or unsuccessful
termination, respectively.
.SH "RETURN VALUE"
The \fBexit\fP() function does not return.
The
.BR exit ()
function does not return.
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001, C89, C99.
.SH NOTES
.LP
It is undefined what happens if one of the
functions registered using \fBatexit\fP(3) and \fBon_exit\fP(3)
calls either \fBexit\fP() or \fBlongjmp\fP(3).
functions registered using
.BR atexit (3)
and
.BR on_exit (3)
calls either
.BR exit ()
or
.BR longjmp (3).
.LP
The use of EXIT_SUCCESS and EXIT_FAILURE is slightly more portable
(to non-Unix environments) than that of 0 and some non-zero value
@ -69,7 +88,9 @@ In particular, VMS uses a different convention.
BSD has attempted to standardize exit codes; see the file
.IR <sysexits.h> .
.LP
After \fBexit\fP(), the exit status must be transmitted to the
After
.BR exit (),
the exit status must be transmitted to the
parent process.
There are three cases.
If the parent has set

4
man3/exp.3
View File

@ -45,7 +45,9 @@ exp, expf, expl \- base-e exponential function
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBexp\fP() function returns the value of e (the base of natural
The
.BR exp ()
function returns the value of e (the base of natural
logarithms) raised to the power of \fIx\fP.
.SH "CONFORMING TO"
SVr4, 4.3BSD, C89, C99, POSIX.1-2001.

4
man3/exp10.3
View File

@ -46,7 +46,9 @@ exp10, exp10f, exp10l \- base-10 exponential function
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBexp10\fP() function returns the value of 10
The
.BR exp10 ()
function returns the value of 10
raised to the power of \fIx\fP.
.SH "CONFORMING TO"
The function is a GNU extension.

4
man3/exp2.3
View File

@ -45,7 +45,9 @@ exp2, exp2f, exp2l \- base-2 exponential function
.sp
Compile with \-std=c99; link with \-lm.
.SH DESCRIPTION
The \fBexp2\fP() function returns the value of 2
The
.BR exp2 ()
function returns the value of 2
raised to the power of \fIx\fP.
.SH "CONFORMING TO"
SVr4, POSIX.1-2001, 4.3BSD, C89.

4
man3/fabs.3
View File

@ -43,7 +43,9 @@ fabs, fabsf, fabsl \- absolute value of floating-point number
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBfabs\fP() functions return the absolute value of the floating-point
The
.BR fabs ()
functions return the absolute value of the floating-point
number \fIx\fP.
.SH ERRORS
No errors can occur.

10
man3/ffs.3
View File

@ -46,12 +46,18 @@ ffs \- find first bit set in a word
.BI "int ffsll(long long int " i );
.fi
.SH DESCRIPTION
The \fBffs\fP() function returns the position of the first
The
.BR ffs ()
function returns the position of the first
(least significant) bit set in the word \fIi\fP.
The least significant bit is position 1 and the
most significant position e.g. 32 or 64.
.BR
The functions \fBffsll\fP() and \fBffsl\fP() do the same but take
The functions
.BR ffsll ()
and
.BR ffsl ()
do the same but take
arguments of possibly different size.
.SH "RETURN VALUE"
These functions return the position of the first bit set,

8
man3/fgetgrent.3
View File

@ -37,7 +37,9 @@ fgetgrent \- get group file entry
.BI "struct group *fgetgrent(FILE *" stream );
.fi
.SH DESCRIPTION
The \fBfgetgrent\fP() function returns a pointer to a structure containing
The
.BR fgetgrent ()
function returns a pointer to a structure containing
the group information from the file \fIstream\fP.
The first time it is called
it returns the first entry; thereafter, it returns successive entries.
@ -58,7 +60,9 @@ struct group {
.fi
.RE
.SH "RETURN VALUE"
The \fBfgetgrent\fP() function returns the group information structure,
The
.BR fgetgrent ()
function returns the group information structure,
or NULL if there are no more entries or an error occurs.
.SH ERRORS
.TP

8
man3/fgetpwent.3
View File

@ -40,7 +40,9 @@ fgetpwent \- get password file entry
.BI "struct passwd *fgetpwent(FILE *" stream );
.fi
.SH DESCRIPTION
The \fBfgetpwent\fP() function returns a pointer to a structure containing
The
.BR fgetpwent ()
function returns a pointer to a structure containing
the broken out fields of a line in the file \fIstream\fP.
The first time it is called it returns the first entry;
thereafter, it returns successive entries.
@ -63,7 +65,9 @@ struct passwd {
.fi
.in -0.5i
.SH "RETURN VALUE"
The \fBfgetpwent\fP() function returns the passwd structure, or NULL if
The
.BR fgetpwent ()
function returns the passwd structure, or NULL if
there are no more entries or an error occurs.
.SH ERRORS
.TP

24
man3/fgetwc.3
View File

@ -26,15 +26,22 @@ fgetwc, getwc \- read a wide character from a FILE stream
.BI "wint_t getwc(FILE *" stream );
.fi
.SH DESCRIPTION
The \fBfgetwc\fP() function is the wide-character equivalent
of the \fBfgetc\fP() function.
The
.BR fgetwc ()
function is the wide-character equivalent
of the
.BR fgetc ()
function.
It reads a wide character from \fIstream\fP and returns it.
If the end of stream is reached, or if \fIferror(stream)\fP becomes true,
it returns WEOF.
If a wide-character conversion error occurs, it sets
\fIerrno\fP to \fBEILSEQ\fP and returns WEOF.
.PP
The \fBgetwc\fP() function or macro functions identically to \fBfgetwc\fP().
The
.BR getwc ()
function or macro functions identically to
.BR fgetwc ().
It may be implemented as a macro, and may evaluate its argument
more than once.
There is no reason ever to use it.
@ -42,7 +49,9 @@ There is no reason ever to use it.
For non-locking counterparts, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
The \fBfgetwc\fP() function returns the next wide-character
The
.BR fgetwc ()
function returns the next wide-character
from the stream, or WEOF.
.SH ERRORS
Apart from the usual ones, there is
@ -53,13 +62,16 @@ form a valid character.
.SH "CONFORMING TO"
C99, POSIX.1-2001.
.SH NOTES
The behaviour of \fBfgetwc\fP() depends on the LC_CTYPE category of the
The behaviour of
.BR fgetwc ()
depends on the LC_CTYPE category of the
current locale.
.PP
In the absence of additional information passed to the
.BR fopen (3)
call, it is
reasonable to expect that \fBfgetwc\fP()
reasonable to expect that
.BR fgetwc ()
will actually read a multibyte sequence
from the stream and then convert it to a wide character.
.SH "SEE ALSO"

19
man3/fgetws.3
View File

@ -22,8 +22,12 @@ fgetws \- read a wide-character string from a FILE stream
.BI "wchar_t *fgetws(wchar_t *" ws ", int " n ", FILE *" stream );
.fi
.SH DESCRIPTION
The \fBfgetws\fP() function is the wide-character equivalent
of the \fBfgets\fP() function.
The
.BR fgetws ()
function is the wide-character equivalent
of the
.BR fgets ()
function.
It reads a string of at most \fIn-1\fP wide characters into the
wide-character array pointed to by \fIws\fP, and adds a terminating L'\\0'
character.
@ -37,19 +41,24 @@ characters at \fIws\fP.
For a non-locking counterpart, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
The \fBfgetws\fP() function, if successful, returns \fIws\fP.
The
.BR fgetws ()
function, if successful, returns \fIws\fP.
If end of stream
was already reached or if an error occurred, it returns NULL.
.SH "CONFORMING TO"
C99, POSIX.1-2001.
.SH NOTES
The behaviour of \fBfgetws\fP() depends on the LC_CTYPE category of the
The behaviour of
.BR fgetws ()
depends on the LC_CTYPE category of the
current locale.
.PP
In the absence of additional information passed to the
.BR fopen (3)
call, it is
reasonable to expect that \fBfgetws\fP()
reasonable to expect that
.BR fgetws ()
will actually read a multibyte string
from the stream and then convert it to a wide-character string.
.PP

19
man3/flockfile.3
View File

@ -66,20 +66,29 @@ the non-locking versions of the stdio functions: with
\fIgetc_unlocked\fP(3) and \fIputc_unlocked\fP(3) instead of
\fIgetc\fP(3) and \fIputc\fP(3).
.LP
The \fBflockfile\fP() function waits for *\fIfilehandle\fP to be
The
.BR flockfile ()
function waits for *\fIfilehandle\fP to be
no longer locked by a different thread, then makes the
current thread owner of *\fIfilehandle\fP, and increments
the lockcount.
.LP
The \fBfunlockfile\fP() function decrements the lock count.
The
.BR funlockfile ()
function decrements the lock count.
.LP
The \fBftrylockfile\fP() function is a non-blocking version
of \fBflockfile\fP().
The
.BR ftrylockfile ()
function is a non-blocking version
of
.BR flockfile ().
It does nothing in case some other thread
owns *\fIfilehandle\fP, and it obtains ownership and increments
the lockcount otherwise.
.SH "RETURN VALUE"
The \fBftrylockfile\fP() function returns zero for success
The
.BR ftrylockfile ()
function returns zero for success
(the lock was obtained), and non-zero for failure.
.SH ERRORS
None.

8
man3/fmod.3
View File

@ -44,12 +44,16 @@ fmod, fmodf, fmodl \- floating-point remainder function
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBfmod\fP() function computes the remainder of dividing \fIx\fP by
The
.BR fmod ()
function computes the remainder of dividing \fIx\fP by
\fIy\fP.
The return value is \fIx\fP \- \fIn\fP * \fIy\fP, where \fIn\fP
is the quotient of \fIx\fP / \fIy\fP, rounded towards zero to an integer.
.SH "RETURN VALUE"
The \fBfmod\fP() function returns the remainder, unless \fIy\fP is zero,
The
.BR fmod ()
function returns the remainder, unless \fIy\fP is zero,
when the function fails and \fIerrno\fP is set.
.SH ERRORS
.TP

25
man3/fputwc.3
View File

@ -24,8 +24,12 @@ fputwc \- write a wide character to a FILE stream
.BI "wint_t putwc(wchar_t " wc ", FILE *" stream );
.fi
.SH DESCRIPTION
The \fBfputwc\fP() function is the wide-character
equivalent of the \fBfputc\fP() function.
The
.BR fputwc ()
function is the wide-character
equivalent of the
.BR fputc ()
function.
It writes the wide character \fIwc\fP to \fIstream\fP.
If
\fIferror(stream)\fP becomes true, it returns WEOF.
@ -33,7 +37,10 @@ If a wide-character conversion error occurs,
it sets \fIerrno\fP to \fBEILSEQ\fP and returns WEOF.
Otherwise it returns \fIwc\fP.
.PP
The \fBputwc\fP() function or macro functions identically to \fBfputwc\fP().
The
.BR putwc ()
function or macro functions identically to
.BR fputwc ().
It may be implemented as a macro, and may evaluate its argument
more than once.
There is no reason ever to use it.
@ -41,7 +48,9 @@ There is no reason ever to use it.
For non-locking counterparts, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
The \fBfputwc\fP() function returns \fIwc\fP if no error occurred,
The
.BR fputwc ()
function returns \fIwc\fP if no error occurred,
or WEOF to indicate an error.
.SH ERRORS
Apart from the usual ones, there is
@ -51,13 +60,17 @@ Conversion of \fIwc\fP to the stream's encoding fails.
.SH "CONFORMING TO"
C99, POSIX.1-2001.
.SH NOTES
The behaviour of \fBfputwc\fP() depends on the LC_CTYPE category of the
The behaviour of
.BR fputwc ()
depends on the LC_CTYPE category of the
current locale.
.PP
In the absence of additional information passed to the
.BR fopen (3)
call, it is
reasonable to expect that \fBfputwc\fP() will actually write the multibyte
reasonable to expect that
.BR fputwc ()
will actually write the multibyte
sequence corresponding to the wide character \fIwc\fP.
.SH "SEE ALSO"
.BR fgetwc (3),

20
man3/fputws.3
View File

@ -21,27 +21,37 @@ fputws \- write a wide-character string to a FILE stream
.BI "int fputws(const wchar_t *" ws ", FILE *" stream );
.fi
.SH DESCRIPTION
The \fBfputws\fP() function is the wide-character equivalent of
the \fBfputs\fP(3) function.
The
.BR fputws ()
function is the wide-character equivalent of
the
.BR fputs (3)
function.
It writes the wide-character string starting at \fIws\fP, up to but
not including the terminating L'\\0' character, to \fIstream\fP.
.PP
For a non-locking counterpart, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
The \fBfputws\fP() function returns a
The
.BR fputws ()
function returns a
non-negative integer if the operation was
successful, or \-1 to indicate an error.
.SH "CONFORMING TO"
C99, POSIX.1-2001.
.SH NOTES
The behaviour of \fBfputws\fP() depends on the LC_CTYPE category of the
The behaviour of
.BR fputws ()
depends on the LC_CTYPE category of the
current locale.
.PP
In the absence of additional information passed to the
.BR fopen (3)
call, it is
reasonable to expect that \fBfputws\fP() will actually write the multibyte
reasonable to expect that
.BR fputws ()
will actually write the multibyte
string corresponding to the wide-character string \fIws\fP.
.SH "SEE ALSO"
.BR fputwc (3),

8
man3/frexp.3
View File

@ -45,10 +45,14 @@ and integral components
.sp
Link with \-lm.
.SH DESCRIPTION
The \fBfrexp\fP() function is used to split the number \fIx\fP into a
The
.BR frexp ()
function is used to split the number \fIx\fP into a
normalized fraction and an exponent which is stored in \fIexp\fP.
.SH "RETURN VALUE"
The \fBfrexp\fP() function returns the normalized fraction.
The
.BR frexp ()
function returns the normalized fraction.
If the argument \fIx\fP is not zero,
the normalized fraction is \fIx\fP times a power of two,
and its absolute value is always in the range 1/2 (inclusive) to

18
man3/fseeko.3
View File

@ -33,11 +33,21 @@ fseeko, ftello \- seek to or report file position
.BI
.fi
.SH DESCRIPTION
The \fBfseeko\fP() and \fBftello\fP() functions are identical to
\fBfseek\fP(3) and \fBftell\fP(3) (see
The
.BR fseeko ()
and
.BR ftello ()
functions are identical to
.BR fseek (3)
and
.BR ftell (3)
(see
.BR fseek (3)),
respectively, except that the \fIoffset\fP argument of \fBfseeko\fP()
and the return value of \fBftello\fP() is of type \fIoff_t\fP
respectively, except that the \fIoffset\fP argument of
.BR fseeko ()
and the return value of
.BR ftello ()
is of type \fIoff_t\fP
instead of \fIlong\fP.
.LP
On many architectures both \fIoff_t\fP and \fIlong\fP are 32-bit types,

56
man3/ftw.3
View File

@ -52,7 +52,8 @@ ftw, nftw \- file tree walk
.BI " int " nopenfd ", int " flags );
.fi
.SH DESCRIPTION
\fBftw\fP() walks through the directory tree that is
.BR ftw ()
walks through the directory tree that is
located under the directory \fIdirpath\fP,
and calls \fIfn\fP() once for each entry in the tree.
By default, directories are handled before the files and
@ -60,10 +61,15 @@ subdirectories they contain (pre-order traversal).
To avoid using up all of the calling process's file descriptors,
\fInopenfd\fP specifies the maximum number of directories that
\fBftw\fP() will hold open simultaneously.
.BR ftw ()
will hold open simultaneously.
When
the search depth exceeds this, \fBftw\fP() will become slower because
directories have to be closed and reopened. \fBftw\fP() uses at most
the search depth exceeds this,
.BR ftw ()
will become slower because
directories have to be closed and reopened.
.BR ftw ()
uses at most
one file descriptor for each level in the directory tree.
For each entry found in the tree,
@ -116,21 +122,30 @@ is passed in
.IR typeflag .
.PP
To stop the tree walk, \fIfn\fP() returns a non-zero value; this
value will become the return value of \fBftw\fP().
value will become the return value of
.BR ftw ().
As long as \fIfn\fP() returns 0,
\fBftw\fP() will continue either until it has traversed the entire tree,
.BR ftw ()
will continue either until it has traversed the entire tree,
in which case it will return zero,
or until it encounters an error (such as a
.BR malloc (3)
failure), in which case it will return \-1.
.PP
Because \fBftw\fP() uses dynamic data structures, the only safe way to
Because
.BR ftw ()
uses dynamic data structures, the only safe way to
exit out of a tree walk is to return a non-zero value from \fIfn\fP().
To allow a signal to terminate the walk without causing a memory leak,
have the handler set a global flag that is checked by \fIfn\fP().
\fIDon't\fP use \fBlongjmp\fP(3) unless the program is going to terminate.
\fIDon't\fP use
.BR longjmp (3)
unless the program is going to terminate.
.SS nftw()
The function \fBnftw\fP() is the same as \fBftw\fP(),
The function
.BR nftw ()
is the same as
.BR ftw (),
except that it has one additional argument, \fIflags\fP,
and calls \fIfn\fP() with one more argument, \fIftwbuf\fP.
@ -148,7 +163,9 @@ should return one of the following values:
.RS
.TP
.B FTW_CONTINUE
Instructs \fBnftw\fP() to continue normally.
Instructs
.BR nftw ()
to continue normally.
.TP
.B FTW_SKIP_SIBLINGS
If \fIfn\fP() returns this value, then
@ -167,7 +184,9 @@ arguments to \fIfn\fP().
continues processing with the next sibling of the directory.
.TP
.B FTW_STOP
Causes \fBnftw\fP() to return immediately with the return value
Causes
.BR nftw ()
to return immediately with the return value
\fBFTW_STOP\fP.
.PP
Other return values could be associated with new actions in the future;
@ -264,12 +283,18 @@ These functions return 0 on success, and \-1 if an error occurs.
If \fIfn\fP() returns non-zero,
then the tree walk is terminated and the value returned by \fIfn\fP()
is returned as the result of \fBftw\fP() or \fBnftw\fP().
is returned as the result of
.BR ftw ()
or
.BR nftw ().
If \fBnftw\fP() is called with the \fBFTW_ACTIONRETVAL\fP flag,
If
.BR nftw ()
is called with the \fBFTW_ACTIONRETVAL\fP flag,
then the only non-zero value that should be used by \fIfn\fP()
to terminate the tree walk is \fBFTW_STOP\fP,
and that value is returned as the result of \fBnftw\fP().
and that value is returned as the result of
.BR nftw ().
.SH NOTES
The function
.BR nftw ()
@ -305,7 +330,8 @@ if no argument is supplied.
It displays various information about each file.
The second-command line argument can be used to specify characters that
control the value assigned to the \fIflags\fP
argument when calling \fBnftw\fP().
argument when calling
.BR nftw ().
.nf
#define _XOPEN_SOURCE 500

19
man3/fwide.3
View File

@ -21,7 +21,9 @@ fwide \- set and determine the orientation of a FILE stream
.BI "int fwide(FILE *" stream ", int " mode );
.fi
.SH DESCRIPTION
When \fImode\fP is zero, the \fBfwide\fP() function determines the current
When \fImode\fP is zero, the
.BR fwide ()
function determines the current
orientation of \fIstream\fP.
It returns a value > 0 if \fIstream\fP is
wide-character oriented, i.e. if wide-character I/O is permitted but char
@ -37,13 +39,17 @@ operation).
Once a stream has an orientation, it cannot be changed and persists until
the stream is closed.
.PP
When \fImode\fP is non-zero, the \fBfwide\fP() function first attempts to set
When \fImode\fP is non-zero, the
.BR fwide ()
function first attempts to set
\fIstream\fP's orientation (to wide-character oriented if \fImode\fP > 0, or
to byte oriented if \fImode\fP < 0).
It then returns a value denoting the
current orientation, as above.
.SH "RETURN VALUE"
The \fBfwide\fP() function returns the stream's orientation, after possibly
The
.BR fwide ()
function returns the stream's orientation, after possibly
changing it.
A return value > 0 means wide-character oriented.
A return value
@ -56,7 +62,10 @@ C99, POSIX.1-2001.
.BR fwprintf (3)
.SH NOTES
Wide-character output to a byte oriented stream can be performed through the
\fBfprintf\fP(3) function with the %lc and %ls directives.
.BR fprintf (3)
function with the %lc and %ls directives.
.PP
Char oriented output to a wide-character oriented stream can be performed
through the \fBfwprintf\fP(3) function with the %c and %s directives.
through the
.BR fwprintf (3)
function with the %c and %s directives.

8
man3/gcvt.3
View File

@ -35,7 +35,9 @@ gcvt \- convert a floating-point number to a string
.BI "char *gcvt(double " number ", size_t " ndigit ", char *" buf );
.fi
.SH DESCRIPTION
The \fBgcvt\fP() function converts \fInumber\fP to a minimal length NULL
The
.BR gcvt ()
function converts \fInumber\fP to a minimal length NULL
terminated ASCII string and stores the result in \fIbuf\fP.
It produces \fIndigit\fP significant digits in either
.BR printf (3)
@ -46,7 +48,9 @@ Instead,
.BR sprintf (3)
is recommended.
.SH "RETURN VALUE"
The \fBgcvt\fP() function returns the address of the string pointed to
The
.BR gcvt ()
function returns the address of the string pointed to
by \fIbuf\fP.
.SH "CONFORMING TO"
marked as LEGACY in POSIX.1-2001.

3
man3/getdate.3
View File

@ -163,7 +163,8 @@ conversion specification.
File containing format patterns.
.TP
.BR TZ ", " LC_TIME
Variables used by \fBstrptime\fP(3).
Variables used by
.BR strptime (3).
.SH "CONFORMING TO"
POSIX.1-2001
.SH "SEE ALSO"

8
man3/getenv.3
View File

@ -37,11 +37,15 @@ getenv \- get an environment variable
.BI "char *getenv(const char *" name );
.fi
.SH DESCRIPTION
The \fBgetenv\fP() function searches the environment list for a string
The
.BR getenv ()
function searches the environment list for a string
that matches the string pointed to by \fIname\fP.
The strings are of the form \fIname = value\fP.
.SH "RETURN VALUE"
The \fBgetenv\fP() function returns a pointer to the value in the
The
.BR getenv ()
function returns a pointer to the value in the
environment, or NULL if there is no match.
.SH "CONFORMING TO"
SVr4, POSIX.1-2001, 4.3BSD, C89, C99.

15
man3/getgrent.3
View File

@ -40,7 +40,8 @@ getgrent, setgrent, endgrent \- get group file entry
.B void endgrent(void);
.fi
.SH DESCRIPTION
The \fBgetgrent\fP()
The
.BR getgrent ()
function returns a pointer to a structure containing
the broken-out fields of a record in the group database
(e.g., the local group file
@ -49,10 +50,14 @@ NIS, and LDAP).
The first time it is called
it returns the first entry; thereafter, it returns successive entries.
.PP
The \fBsetgrent\fP() function rewinds to the beginning
The
.BR setgrent ()
function rewinds to the beginning
of the group database, to allow repeated scans.
.PP
The \fBendgrent\fP() function is used to close the group database
The
.BR endgrent ()
function is used to close the group database
after all processing has been performed.
.PP
The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows:
@ -68,7 +73,9 @@ struct group {
.fi
.RE
.SH "RETURN VALUE"
The \fBgetgrent\fP() function returns a pointer to a
The
.BR getgrent ()
function returns a pointer to a
.I group
structure,
or NULL if there are no more entries or an error occurs.

12
man3/getgrnam.3
View File

@ -105,7 +105,11 @@ can be found using
.BR sysconf (3)
with the _SC_GETGR_R_SIZE_MAX parameter.
.SH "RETURN VALUE"
The \fBgetgrnam\fP() and \fBgetgrgid\fP() functions return a pointer to a
The
.BR getgrnam ()
and
.BR getgrgid ()
functions return a pointer to a
.I group
structure, or NULL if the matching entry
is not found or an error occurs.
@ -123,7 +127,11 @@ by subsequent calls to
or
.BR getgrnam ().
.LP
The \fBgetgrnam_r\fP() and \fBgetgrgid_r\fP() functions return
The
.BR getgrnam_r ()
and
.BR getgrgid_r ()
functions return
zero on success.
In case of error, an error number is returned.
.SH ERRORS

27
man3/gethostbyname.3
View File

@ -117,7 +117,9 @@ for the file format).
The current domain and its parents are searched unless \fIname\fP
ends in a dot.
.PP
The \fBgethostbyaddr\fP() function returns a structure of type \fIhostent\fP
The
.BR gethostbyaddr ()
function returns a structure of type \fIhostent\fP
for the given host address \fIaddr\fP of length \fIlen\fP and address type
\fItype\fP.
Valid address types are
@ -128,22 +130,33 @@ The host address argument is a pointer to a struct of a type depending
on the address type, for example a \fBstruct in_addr *\fP (probably
obtained via a call to \fIinet_addr\fP()) for address type AF_INET.
.PP
The \fBsethostent\fP() function specifies, if \fIstayopen\fP is true (1),
The
.BR sethostent ()
function specifies, if \fIstayopen\fP is true (1),
that a connected TCP socket should be used for the name server queries and
that the connection should remain open during successive queries.
Otherwise, name server queries will use UDP datagrams.
.PP
The \fBendhostent\fP() function ends the use of a TCP connection for name
The
.BR endhostent ()
function ends the use of a TCP connection for name
server queries.
.PP
The (obsolete) \fBherror\fP() function prints the error message associated
The (obsolete)
.BR herror ()
function prints the error message associated
with the current value of \fIh_errno\fP on stderr.
.PP
The (obsolete) \fBhstrerror\fP() function takes an error number
The (obsolete)
.BR hstrerror ()
function takes an error number
(typically \fIh_errno\fP) and returns the corresponding message string.
.PP
The domain name queries carried out by \fBgethostbyname\fP() and
\fBgethostbyaddr\fP() use a combination of any or all of the name server
The domain name queries carried out by
.BR gethostbyname ()
and
.BR gethostbyaddr ()
use a combination of any or all of the name server
.BR named (8),
a broken out line from \fI/etc/hosts\fP, and the Network
Information Service (NIS or YP), depending upon the contents of the

43
man3/getlogin.3
View File

@ -39,19 +39,23 @@ getlogin, getlogin_r, cuserid \- get user name
.sp
.BI "char *cuserid(char *" string );
.SH DESCRIPTION
\fBgetlogin\fP() returns a pointer to a string containing the name of
.BR getlogin ()
returns a pointer to a string containing the name of
the user logged in on the controlling terminal of the process, or a
null pointer if this information cannot be determined.
The string is
statically allocated and might be overwritten on subsequent calls to
this function or to \fBcuserid\fP().
this function or to
.BR cuserid ().
.PP
\fBgetlogin_r\fP() returns this same user name in the array
.BR getlogin_r ()
returns this same user name in the array
.I buf
of size
.IR bufsize .
.PP
\fBcuserid\fP() returns a pointer to a string containing a user name
.BR cuserid ()
returns a pointer to a string containing a user name
associated with the effective user ID of the process.
If \fIstring\fP
is not a null pointer, it should be an array that can hold at least
@ -59,25 +63,30 @@ is not a null pointer, it should be an array that can hold at least
Otherwise, a pointer to a string in a static area is returned.
This
string is statically allocated and might be overwritten on subsequent
calls to this function or to \fBgetlogin\fP().
calls to this function or to
.BR getlogin ().
.PP
The macro \fBL_cuserid\fP is an integer constant that indicates how
long an array you might need to store a user name. \fBL_cuserid\fP is
declared in \fBstdio.h\fP.
.PP
These functions let your program identify positively the user who is
running (\fBcuserid\fP()) or the user who logged in this session
(\fBgetlogin\fP()). (These can differ when set-user-ID programs are
involved.)
running
.RB ( cuserid ())
or the user who logged in this session
.RB ( getlogin ()).
(These can differ when set-user-ID programs are involved.)
.PP
For most purposes, it is more useful to use the environment variable
\fBLOGNAME\fP to find out who the user is.
This is more flexible
precisely because the user can set \fBLOGNAME\fP arbitrarily.
.SH "RETURN VALUE"
\fBgetlogin\fP() returns a pointer to the user name when successful,
.BR getlogin ()
returns a pointer to the user name when successful,
and NULL on failure.
\fBgetlogin_r\fP() returns 0 when successful, and non-zero on failure.
.BR getlogin_r ()
returns 0 when successful, and non-zero on failure.
.SH ERRORS
POSIX specifies
.TP
@ -116,14 +125,22 @@ and
.BR getlogin_r ()
specified in POSIX.1-2001.
System V has a \fBcuserid\fP() function which uses the real
System V has a
.BR cuserid ()
function which uses the real
user ID rather than the effective user ID.
The \fBcuserid\fP() function
The
.BR cuserid ()
function
was included in the 1988 version of POSIX,
but removed from the 1990 version.
It was present in SUSv2, but removed in POSIX.1-2001.
.LP
OpenBSD has \fBgetlogin\fP() and \fBsetlogin\fP(), and a username
OpenBSD has
.BR getlogin ()
and
.BR setlogin (),
and a username
associated with a session, even if it has no controlling tty.
.SH BUGS
Unfortunately, it is often rather easy to fool

64
man3/getmntent.3
View File

@ -58,33 +58,47 @@ These routines are used to access the file system description file
\fI/etc/fstab\fP and the mounted file system description file
\fI/etc/mtab\fP.
.PP
The \fBsetmntent\fP() function opens the file system description file
The
.BR setmntent ()
function opens the file system description file
\fIfp\fP and returns a file pointer which can be used by
\fBgetmntent\fP().
.BR getmntent ().
The argument \fItype\fP is the type of access
required and can take the same values as the \fImode\fP argument of
.BR fopen (3).
.PP
The \fBgetmntent\fP() function reads the next line from the file system
The
.BR getmntent ()
function reads the next line from the file system
description file \fIfp\fP and returns a pointer to a structure
containing the broken out fields from a line in the file.
The pointer
points to a static area of memory which is overwritten by subsequent
calls to \fBgetmntent\fP().
calls to
.BR getmntent ().
.PP
The \fBaddmntent\fP() function adds the mntent structure \fImnt\fP to
The
.BR addmntent ()
function adds the mntent structure \fImnt\fP to
the end of the open file \fIfp\fP.
.PP
The \fBendmntent\fP() function closes the file system description file
The
.BR endmntent ()
function closes the file system description file
\fIfp\fP.
.PP
The \fBhasmntopt\fP() function scans the \fImnt_opts\fP field (see below)
The
.BR hasmntopt ()
function scans the \fImnt_opts\fP field (see below)
of the mntent structure \fImnt\fP for a substring that matches \fIopt\fP.
See \fI<mntent.h>\fP and
.BR mount (8)
for valid mount options.
.PP
The reentrant \fBgetmntent_r\fP() function is similar to \fBgetmntent\fP(),
The reentrant
.BR getmntent_r ()
function is similar to
.BR getmntent (),
but stores the struct mount in the provided
.RI * mntbuf
and stores the strings pointed to by the entries in that struct
@ -112,17 +126,31 @@ Since fields in the mtab and fstab files are separated by whitespace,
octal escapes are used to represent the four characters space (\e040),
tab (\e011), newline (\e012) and backslash (\e134) in those files
when they occur in one of the four strings in a mntent structure.
The routines \fBaddmntent\fP() and \fBgetmntent\fP() will convert
The routines
.BR addmntent ()
and
.BR getmntent ()
will convert
from string representation to escaped representation and back.
.SH "RETURN VALUE"
The \fBgetmntent\fP() and \fBgetmntent_r\fP() functions return
The
.BR getmntent ()
and
.BR getmntent_r ()
functions return
a pointer to the mntent structure or NULL on failure.
.PP
The \fBaddmntent\fP() function returns 0 on success and 1 on failure.
The
.BR addmntent ()
function returns 0 on success and 1 on failure.
.PP
The \fBendmntent\fP() function always returns 1.
The
.BR endmntent ()
function always returns 1.
.PP
The \fBhasmntopt\fP() function returns the address of the substring if
The
.BR hasmntopt ()
function returns the address of the substring if
a match is found and NULL otherwise.
.SH FILES
.nf
@ -141,13 +169,17 @@ LSB deprecates the functions
and
.BR setmntent ().
.SH NOTES
System V also has a \fBgetmntent\fP() function but the calling sequence
System V also has a
.BR getmntent ()
function but the calling sequence
differs, and the returned structure is different.
Under System V
.I /etc/mnttab
is used.
4.4BSD and Digital Unix have a routine \fBgetmntinfo\fP(),
a wrapper around the system call \fBgetfsstat\fP().
4.4BSD and Digital Unix have a routine
.BR getmntinfo (),
a wrapper around the system call
.BR getfsstat ().
.SH "SEE ALSO"
.BR fopen (3),
.BR fstab (5),

32
man3/getnetent.3
View File

@ -44,27 +44,39 @@ get network entry
.B void endnetent(void);
.fi
.SH DESCRIPTION
The \fBgetnetent\fP() function reads the next line from the file
The
.BR getnetent ()
function reads the next line from the file
\fI/etc/networks\fP and returns a structure \fInetent\fP containing
the broken out fields from the line.
The \fI/etc/networks\fP file
is opened if necessary.
.PP
The \fBgetnetbyname\fP() function returns a \fInetent\fP structure
The
.BR getnetbyname ()
function returns a \fInetent\fP structure
for the line from \fI/etc/networks\fP that matches the network
\fIname\fP.
.PP
The \fBgetnetbyaddr\fP() function returns a \fInetent\fP structure
The
.BR getnetbyaddr ()
function returns a \fInetent\fP structure
for the line that matches the network number \fInet\fP of type
\fItype\fP.
.PP
The \fBsetnetent\fP() function opens and rewinds the
The
.BR setnetent ()
function opens and rewinds the
\fI/etc/networks\fP file.
If \fIstayopen\fP is true (1), then the
file will not be closed between calls to \fBgetnetbyname\fP() and
\fBgetnetbyaddr\fP().
file will not be closed between calls to
.BR getnetbyname ()
and
.BR getnetbyaddr ().
.PP
The \fBendnetent\fP() function closes \fI/etc/networks\fP.
The
.BR endnetent ()
function closes \fI/etc/networks\fP.
.PP
The \fInetent\fP structure is defined in \fI<netdb.h>\fP as follows:
.sp
@ -93,7 +105,11 @@ The type of the network number; always AF_INET.
.I n_net
The network number in host byte order.
.SH "RETURN VALUE"
The \fBgetnetent\fP(), \fBgetnetbyname\fP() and \fBgetnetbyaddr\fP()
The
.BR getnetent (),
.BR getnetbyname ()
and
.BR getnetbyaddr ()
functions return the \fInetent\fP structure, or a NULL pointer if an
error occurs or the end of the file is reached.
.SH FILES

61
man3/getopt.3
View File

@ -77,17 +77,24 @@ An element of \fIargv\fP that starts with '\-'
is an option element.
The characters of this element
(aside from the initial '\-') are option characters.
If \fBgetopt\fP()
If
.BR getopt ()
is called repeatedly, it returns successively each of the option characters
from each of the option elements.
.PP
If \fBgetopt\fP() finds another option character, it returns that
If
.BR getopt ()
finds another option character, it returns that
character, updating the external variable \fIoptind\fP and a static
variable \fInextchar\fP so that the next call to \fBgetopt\fP() can
variable \fInextchar\fP so that the next call to
.BR getopt ()
can
resume the scan with the following option character or
\fIargv\fP-element.
.PP
If there are no more option characters, \fBgetopt\fP() returns \-1.
If there are no more option characters,
.BR getopt ()
returns \-1.
Then \fIoptind\fP is the index in \fIargv\fP of the first
\fIargv\fP-element that is not an option.
.PP
@ -95,7 +102,8 @@ Then \fIoptind\fP is the index in \fIargv\fP of the first
is a string containing the legitimate option characters.
If such a
character is followed by a colon, the option requires an argument, so
\fBgetopt\fP() places a pointer to the following text in the same
.BR getopt ()
places a pointer to the following text in the same
\fIargv\fP-element, or the text of the following \fIargv\fP-element, in
.IR optarg .
Two colons mean an option takes
@ -117,7 +125,9 @@ option is reserved by POSIX.2 for implementation extensions.)
This behaviour is a GNU extension, not available with libraries before
GNU libc 2.
.PP
By default, \fBgetopt\fP() permutes the contents of \fIargv\fP as it
By default,
.BR getopt ()
permutes the contents of \fIargv\fP as it
scans, so that eventually all the non-options are at the end.
Two other modes are also implemented.
If the first character of
@ -132,25 +142,32 @@ and that care about the ordering of the two.)
The special argument "\-\-" forces an end of option-scanning regardless
of the scanning mode.
.PP
If \fBgetopt\fP() does not recognize an option character, it prints an
If
.BR getopt ()
does not recognize an option character, it prints an
error message to stderr, stores the character in \fIoptopt\fP, and
returns '?'.
The calling program may prevent the error message by
setting \fIopterr\fP to 0.
.PP
If \fBgetopt\fP() finds an option character in \fIargv\fP that was not
If
.BR getopt ()
finds an option character in \fIargv\fP that was not
included in \fIoptstring\fP, or if it detects a missing option argument,
it returns '?' and sets the external variable \fIoptopt\fP to the
actual option character.
If the first character
(following any optional '+' or '\-' described above)
of \fIoptstring\fP
is a colon (':'), then \fBgetopt\fP() returns ':' instead of '?' to
is a colon (':'), then
.BR getopt ()
returns ':' instead of '?' to
indicate a missing option argument.
If an error was detected, and
the first character of \fIoptstring\fP is not a colon, and
the external variable \fIopterr\fP is non-zero (which is the default),
\fBgetopt\fP() prints an error message.
.BR getopt ()
prints an error message.
.PP
The
.BR getopt_long ()
@ -201,10 +218,14 @@ is:
.I flag
specifies how results are returned for a long option.
If \fIflag\fP
is NULL, then \fBgetopt_long\fP() returns \fIval\fP. (For
is NULL, then
.BR getopt_long ()
returns \fIval\fP. (For
example, the calling program may set \fIval\fP to the equivalent short
option character.)
Otherwise, \fBgetopt_long\fP() returns 0, and
Otherwise,
.BR getopt_long ()
returns 0, and
\fIflag\fP points to a variable which is set to \fIval\fP if the
option is found, but left unchanged if the option is not found.
.TP
@ -218,7 +239,10 @@ If \fIlongindex\fP is not NULL, it
points to a variable which is set to the index of the long option relative to
.IR longopts .
.PP
\fBgetopt_long_only\fP() is like \fBgetopt_long\fP(), but '\-' as well
.BR getopt_long_only ()
is like
.BR getopt_long (),
but '\-' as well
as '\-\-' can indicate a long option.
If an option that starts with '\-'
(not '\-\-') doesn't match a long option, but does match a short option,
@ -242,11 +266,16 @@ then the return value depends on the first character in
.IR optstring :
if it is ':', then ':' is returned; otherwise '?' is returned.
.PP
\fBgetopt_long\fP() and \fBgetopt_long_only\fP() also return the option
.BR getopt_long ()
and
.BR getopt_long_only ()
also return the option
character when a short option is recognized.
For a long option, they
return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise.
Error and \-1 returns are the same as for \fBgetopt\fP(), plus '?' for an
Error and \-1 returns are the same as for
.BR getopt (),
plus '?' for an
ambiguous match or an extraneous parameter.
.SH "ENVIRONMENT VARIABLES"
.TP
@ -411,7 +440,7 @@ implementation (and probably all other implementations) implements the
correct behaviour rather than that specified.
.SH "CONFORMING TO"
.TP
\fBgetopt\fP():
.BR getopt ():
POSIX.2 and POSIX.1-2001,
provided the environment variable POSIXLY_CORRECT is set.
Otherwise, the elements of \fIargv\fP aren't really const, because we

Some files were not shown because too many files have changed in this diff Show More