diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-05-12 09:06:04 +0000 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-05-12 09:06:04 +0000 |
| commit | 60a90ecdae7bf6d1a91dc5d1d7177e400b114e47 (patch) | |
| tree | 9f7c19a897084607a9688be5414d0d4cd6391b54 /man2 | |
| parent | d92a60f2575c95cd532b822e4fb983c3a9e35641 (diff) | |
| download | man-pages-60a90ecdae7bf6d1a91dc5d1d7177e400b114e47.tar.gz | |
Convert function formatting of the form "\fBname\fP()" to ".BR name ()".
Diffstat (limited to 'man2')
43 files changed, 586 insertions, 230 deletions
diff --git a/man2/_exit.2 b/man2/_exit.2 index a47f04b1f6..65e395c5fa 100644 --- a/man2/_exit.2 +++ b/man2/_exit.2 @@ -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), diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 index c3cf28036b..d2e9c2c1c1 100644 --- a/man2/adjtimex.2 +++ b/man2/adjtimex.2 @@ -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) diff --git a/man2/chown.2 b/man2/chown.2 index 122c20b49d..a444d559aa 100644 --- a/man2/chown.2 +++ b/man2/chown.2 @@ -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 diff --git a/man2/dup.2 b/man2/dup.2 index 8838d70fb5..2104f30099 100644 --- a/man2/dup.2 +++ b/man2/dup.2 @@ -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)) diff --git a/man2/execve.2 b/man2/execve.2 index 0ae55a1b79..9a66efae8e 100644 --- a/man2/execve.2 +++ b/man2/execve.2 @@ -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 diff --git a/man2/getcontext.2 b/man2/getcontext.2 index d02d4b6c65..5c7ac70faf 100644 --- a/man2/getcontext.2 +++ b/man2/getcontext.2 @@ -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 diff --git a/man2/getrlimit.2 b/man2/getrlimit.2 index 55cb03cda5..3d1ed4e5f2 100644 --- a/man2/getrlimit.2 +++ b/man2/getrlimit.2 @@ -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 diff --git a/man2/gettid.2 b/man2/gettid.2 index 6bd37cc1d9..b89965406e 100644 --- a/man2/gettid.2 +++ b/man2/gettid.2 @@ -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), diff --git a/man2/getuid.2 b/man2/getuid.2 index e061a165c1..d735998cda 100644 --- a/man2/getuid.2 +++ b/man2/getuid.2 @@ -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) diff --git a/man2/io_cancel.2 b/man2/io_cancel.2 index fc999a52a8..7742b3b4a8 100644 --- a/man2/io_cancel.2 +++ b/man2/io_cancel.2 @@ -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 diff --git a/man2/io_destroy.2 b/man2/io_destroy.2 index fdc1429a8f..856f55fc45 100644 --- a/man2/io_destroy.2 +++ b/man2/io_destroy.2 @@ -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 diff --git a/man2/io_getevents.2 b/man2/io_getevents.2 index 8836c48ed6..b92d8e789c 100644 --- a/man2/io_getevents.2 +++ b/man2/io_getevents.2 @@ -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 diff --git a/man2/io_setup.2 b/man2/io_setup.2 index 4c128183d4..645a7ac105 100644 --- a/man2/io_setup.2 +++ b/man2/io_setup.2 @@ -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. diff --git a/man2/io_submit.2 b/man2/io_submit.2 index 6e251ba79e..ea6e582309 100644 --- a/man2/io_submit.2 +++ b/man2/io_submit.2 @@ -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. diff --git a/man2/ioperm.2 b/man2/ioperm.2 index 3d368491ab..0b02b64574 100644 --- a/man2/ioperm.2 +++ b/man2/ioperm.2 @@ -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 diff --git a/man2/iopl.2 b/man2/iopl.2 index 68d2bb39f6..586b64d9a3 100644 --- a/man2/iopl.2 +++ b/man2/iopl.2 @@ -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 diff --git a/man2/ipc.2 b/man2/ipc.2 index 0c1f12f332..238d6c33c2 100644 --- a/man2/ipc.2 +++ b/man2/ipc.2 @@ -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), diff --git a/man2/kill.2 b/man2/kill.2 index 20b1b8c3b5..545cc85c16 100644 --- a/man2/kill.2 +++ b/man2/kill.2 @@ -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 diff --git a/man2/lseek.2 b/man2/lseek.2 index a360f69cc0..1180fe0139 100644 --- a/man2/lseek.2 +++ b/man2/lseek.2 @@ -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.) diff --git a/man2/madvise.2 b/man2/madvise.2 index 9f4e4b8e95..3157443d83 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -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)" diff --git a/man2/mprotect.2 b/man2/mprotect.2 index dbf4c6d134..8f0202e395 100644 --- a/man2/mprotect.2 +++ b/man2/mprotect.2 @@ -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" diff --git a/man2/mremap.2 b/man2/mremap.2 index 6b53f5341a..2778ad271a 100644 --- a/man2/mremap.2 +++ b/man2/mremap.2 @@ -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. diff --git a/man2/open.2 b/man2/open.2 index 7ac28d93da..99d6f689cf 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -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. diff --git a/man2/outb.2 b/man2/outb.2 index a95d0efce3..55d95bb602 100644 --- a/man2/outb.2 +++ b/man2/outb.2 @@ -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 diff --git a/man2/pivot_root.2 b/man2/pivot_root.2 index 5a1be7e692..8f5c07606d 100644 --- a/man2/pivot_root.2 +++ b/man2/pivot_root.2 @@ -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), diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 index 4464418207..bd0edad221 100644 --- a/man2/posix_fadvise.2 +++ b/man2/posix_fadvise.2 @@ -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 diff --git a/man2/pread.2 b/man2/pread.2 index 716e0b56f3..06a95b1d0a 100644 --- a/man2/pread.2 +++ b/man2/pread.2 @@ -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 diff --git a/man2/read.2 b/man2/read.2 index f049099d03..f77113dcb4 100644 --- a/man2/read.2 +++ b/man2/read.2 @@ -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. diff --git a/man2/sched_get_priority_max.2 b/man2/sched_get_priority_max.2 index ed73019f8c..822af108e7 100644 --- a/man2/sched_get_priority_max.2 +++ b/man2/sched_get_priority_max.2 @@ -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. diff --git a/man2/sched_rr_get_interval.2 b/man2/sched_rr_get_interval.2 index e6421ff8a7..429a91202b 100644 --- a/man2/sched_rr_get_interval.2 +++ b/man2/sched_rr_get_interval.2 @@ -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" diff --git a/man2/sched_setparam.2 b/man2/sched_setparam.2 index 3308028f01..45383983f1 100644 --- a/man2/sched_setparam.2 +++ b/man2/sched_setparam.2 @@ -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 diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2 index dc62559dcc..317544ca0c 100644 --- a/man2/sched_setscheduler.2 +++ b/man2/sched_setscheduler.2 @@ -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 diff --git a/man2/select_tut.2 b/man2/select_tut.2 index 96b544ae63..fc1911b343 100644 --- a/man2/select_tut.2 +++ b/man2/select_tut.2 @@ -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) diff --git a/man2/setpgid.2 b/man2/setpgid.2 index 21d54972c9..b7dfb2101b 100644 --- a/man2/setpgid.2 +++ b/man2/setpgid.2 @@ -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 diff --git a/man2/setsid.2 b/man2/setsid.2 index 75cd1a2b11..05437659fb 100644 --- a/man2/setsid.2 +++ b/man2/setsid.2 @@ -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 diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 index f93c815560..4f727b6ae6 100644 --- a/man2/sigaltstack.2 +++ b/man2/sigaltstack.2 @@ -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 diff --git a/man2/stime.2 b/man2/stime.2 index bc7ae5b54c..3004ddf353 100644 --- a/man2/stime.2 +++ b/man2/stime.2 @@ -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 diff --git a/man2/sync.2 b/man2/sync.2 index 3b34a821de..fc0fffeafa 100644 --- a/man2/sync.2 +++ b/man2/sync.2 @@ -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 diff --git a/man2/syslog.2 b/man2/syslog.2 index f637ee9d7c..452de0d053 100644 --- a/man2/syslog.2 +++ b/man2/syslog.2 @@ -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 diff --git a/man2/time.2 b/man2/time.2 index 0d70329277..b6c405bd59 100644 --- a/man2/time.2 +++ b/man2/time.2 @@ -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 diff --git a/man2/tkill.2 b/man2/tkill.2 index cb966ac30d..780bf82cdf 100644 --- a/man2/tkill.2 +++ b/man2/tkill.2 @@ -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) diff --git a/man2/uselib.2 b/man2/uselib.2 index 763a50f457..db44f080e0 100644 --- a/man2/uselib.2 +++ b/man2/uselib.2 @@ -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 diff --git a/man2/write.2 b/man2/write.2 index ea2c2f8ddd..53b688e0d0 100644 --- a/man2/write.2 +++ b/man2/write.2 @@ -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" |