diff options
273 files changed, 3530 insertions, 1230 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" diff --git a/man3/abort.3 b/man3/abort.3 index 5af3b5e2bd..8f14c110f1 100644 --- a/man3/abort.3 +++ b/man3/abort.3 @@ -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" diff --git a/man3/abs.3 b/man3/abs.3 index 94d1e82645..f20411d008 100644 --- a/man3/abs.3 +++ b/man3/abs.3 @@ -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), diff --git a/man3/acos.3 b/man3/acos.3 index d44e0f36a2..1b4004a361 100644 --- a/man3/acos.3 +++ b/man3/acos.3 @@ -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 diff --git a/man3/acosh.3 b/man3/acosh.3 index 8785aa32e8..d467c87ac5 100644 --- a/man3/acosh.3 +++ b/man3/acosh.3 @@ -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 diff --git a/man3/asin.3 b/man3/asin.3 index 0fe40c54a6..e3a0d39ae1 100644 --- a/man3/asin.3 +++ b/man3/asin.3 @@ -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 diff --git a/man3/asinh.3 b/man3/asinh.3 index 4079ec945e..a8f7d2643a 100644 --- a/man3/asinh.3 +++ b/man3/asinh.3 @@ -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. diff --git a/man3/atan.3 b/man3/atan.3 index 9771e0387a..0e09781e86 100644 --- a/man3/atan.3 +++ b/man3/atan.3 @@ -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" diff --git a/man3/atan2.3 b/man3/atan2.3 index f52ab3a47b..78516b8516 100644 --- a/man3/atan2.3 +++ b/man3/atan2.3 @@ -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. diff --git a/man3/atanh.3 b/man3/atanh.3 index a75a3e5df5..50cd590e4a 100644 --- a/man3/atanh.3 +++ b/man3/atanh.3 @@ -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 diff --git a/man3/atexit.3 b/man3/atexit.3 index 79f7e9dfa8..7e269553dc 100644 --- a/man3/atexit.3 +++ b/man3/atexit.3 @@ -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" diff --git a/man3/atof.3 b/man3/atof.3 index a8641109ea..910b379058 100644 --- a/man3/atof.3 +++ b/man3/atof.3 @@ -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" diff --git a/man3/atoi.3 b/man3/atoi.3 index eadaac17fa..674c018459 100644 --- a/man3/atoi.3 +++ b/man3/atoi.3 @@ -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), diff --git a/man3/bsearch.3 b/man3/bsearch.3 index 4714da6ba7..1243e2a67a 100644 --- a/man3/bsearch.3 +++ b/man3/bsearch.3 @@ -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. diff --git a/man3/btowc.3 b/man3/btowc.3 index c25caa89be..9d3043f38f 100644 --- a/man3/btowc.3 +++ b/man3/btowc.3 @@ -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. diff --git a/man3/byteorder.3 b/man3/byteorder.3 index b25fa61bb6..6be15e2ab6 100644 --- a/man3/byteorder.3 +++ b/man3/byteorder.3 @@ -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, diff --git a/man3/cbrt.3 b/man3/cbrt.3 index 6e628bc25d..7dae300bdd 100644 --- a/man3/cbrt.3 +++ b/man3/cbrt.3 @@ -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" diff --git a/man3/clearenv.3 b/man3/clearenv.3 index c554c516ce..82194a58ff 100644 --- a/man3/clearenv.3 +++ b/man3/clearenv.3 @@ -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 diff --git a/man3/closedir.3 b/man3/closedir.3 index b773c8a353..a7c03b37d8 100644 --- a/man3/closedir.3 +++ b/man3/closedir.3 @@ -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. diff --git a/man3/copysign.3 b/man3/copysign.3 index 5b8931b333..48adc7430b 100644 --- a/man3/copysign.3 +++ b/man3/copysign.3 @@ -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 diff --git a/man3/cos.3 b/man3/cos.3 index 224f852a99..a5e5a6fd04 100644 --- a/man3/cos.3 +++ b/man3/cos.3 @@ -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 diff --git a/man3/cosh.3 b/man3/cosh.3 index 942d42fc89..57a8cf7450 100644 --- a/man3/cosh.3 +++ b/man3/cosh.3 @@ -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. diff --git a/man3/ctime.3 b/man3/ctime.3 index 9bf5cea5e9..635166d00d 100644 --- a/man3/ctime.3 +++ b/man3/ctime.3 @@ -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 (), diff --git a/man3/difftime.3 b/man3/difftime.3 index 6005d0a36a..cd3837b7a8 100644 --- a/man3/difftime.3 +++ b/man3/difftime.3 @@ -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 diff --git a/man3/div.3 b/man3/div.3 index 499d481077..cdd878d2b6 100644 --- a/man3/div.3 +++ b/man3/div.3 @@ -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 diff --git a/man3/drand48.3 b/man3/drand48.3 index 47e7e7e6cc..758c084d7e 100644 --- a/man3/drand48.3 +++ b/man3/drand48.3 @@ -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 diff --git a/man3/ecvt.3 b/man3/ecvt.3 index 1eafca785b..f5555a3c9d 100644 --- a/man3/ecvt.3 +++ b/man3/ecvt.3 @@ -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, diff --git a/man3/erf.3 b/man3/erf.3 index 1aeb83030e..9778a47057 100644 --- a/man3/erf.3 +++ b/man3/erf.3 @@ -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. diff --git a/man3/error.3 b/man3/error.3 index 7de381527e..bb2bfceef1 100644 --- a/man3/error.3 +++ b/man3/error.3 @@ -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 diff --git a/man3/ether_aton.3 b/man3/ether_aton.3 index a6d01ab9e2..3587110b47 100644 --- a/man3/ether_aton.3 +++ b/man3/ether_aton.3 @@ -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: diff --git a/man3/exit.3 b/man3/exit.3 index 4dca002d3d..44bba81a69 100644 --- a/man3/exit.3 +++ b/man3/exit.3 @@ -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 diff --git a/man3/exp.3 b/man3/exp.3 index ead2d8e3b1..f00d026300 100644 --- a/man3/exp.3 +++ b/man3/exp.3 @@ -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. diff --git a/man3/exp10.3 b/man3/exp10.3 index 1caa89197e..1305cbf264 100644 --- a/man3/exp10.3 +++ b/man3/exp10.3 @@ -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. diff --git a/man3/exp2.3 b/man3/exp2.3 index d2031320a3..63961701f6 100644 --- a/man3/exp2.3 +++ b/man3/exp2.3 @@ -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. diff --git a/man3/fabs.3 b/man3/fabs.3 index 87f3e169ff..c2ae6f30f8 100644 --- a/man3/fabs.3 +++ b/man3/fabs.3 @@ -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. diff --git a/man3/ffs.3 b/man3/ffs.3 index 2c2d7d99de..c1581ecb75 100644 --- a/man3/ffs.3 +++ b/man3/ffs.3 @@ -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, diff --git a/man3/fgetgrent.3 b/man3/fgetgrent.3 index 16f8ff9614..9b913013e7 100644 --- a/man3/fgetgrent.3 +++ b/man3/fgetgrent.3 @@ -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 diff --git a/man3/fgetpwent.3 b/man3/fgetpwent.3 index 7bb85878be..182b66f73f 100644 --- a/man3/fgetpwent.3 +++ b/man3/fgetpwent.3 @@ -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 diff --git a/man3/fgetwc.3 b/man3/fgetwc.3 index 948c967c7e..5f7c66598f 100644 --- a/man3/fgetwc.3 +++ b/man3/fgetwc.3 @@ -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" diff --git a/man3/fgetws.3 b/man3/fgetws.3 index 2027e283d2..3d98b397d8 100644 --- a/man3/fgetws.3 +++ b/man3/fgetws.3 @@ -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 diff --git a/man3/flockfile.3 b/man3/flockfile.3 index 5cc2ffb6b8..461595c10f 100644 --- a/man3/flockfile.3 +++ b/man3/flockfile.3 @@ -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. diff --git a/man3/fmod.3 b/man3/fmod.3 index 84d1e57537..ca43e460b6 100644 --- a/man3/fmod.3 +++ b/man3/fmod.3 @@ -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 diff --git a/man3/fputwc.3 b/man3/fputwc.3 index 219883cbe0..e6d2da4558 100644 --- a/man3/fputwc.3 +++ b/man3/fputwc.3 @@ -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), diff --git a/man3/fputws.3 b/man3/fputws.3 index 91782619c0..6a7a60ca49 100644 --- a/man3/fputws.3 +++ b/man3/fputws.3 @@ -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), diff --git a/man3/frexp.3 b/man3/frexp.3 index 3034047942..7b655ab9bf 100644 --- a/man3/frexp.3 +++ b/man3/frexp.3 @@ -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 diff --git a/man3/fseeko.3 b/man3/fseeko.3 index fa1f0423e6..1ee12b0d29 100644 --- a/man3/fseeko.3 +++ b/man3/fseeko.3 @@ -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, diff --git a/man3/ftw.3 b/man3/ftw.3 index 54c72b17df..be6a22a617 100644 --- a/man3/ftw.3 +++ b/man3/ftw.3 @@ -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 diff --git a/man3/fwide.3 b/man3/fwide.3 index 7f0c695a31..82d2efad22 100644 --- a/man3/fwide.3 +++ b/man3/fwide.3 @@ -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. diff --git a/man3/gcvt.3 b/man3/gcvt.3 index 4a167ec49e..dfe31c8e8f 100644 --- a/man3/gcvt.3 +++ b/man3/gcvt.3 @@ -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. diff --git a/man3/getdate.3 b/man3/getdate.3 index 68cbd6a429..b113ff3efb 100644 --- a/man3/getdate.3 +++ b/man3/getdate.3 @@ -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" diff --git a/man3/getenv.3 b/man3/getenv.3 index a43a03a03f..48f7eba41e 100644 --- a/man3/getenv.3 +++ b/man3/getenv.3 @@ -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. diff --git a/man3/getgrent.3 b/man3/getgrent.3 index c9b586df89..6c95b651be 100644 --- a/man3/getgrent.3 +++ b/man3/getgrent.3 @@ -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. diff --git a/man3/getgrnam.3 b/man3/getgrnam.3 index e0e8faa393..6958dcd851 100644 --- a/man3/getgrnam.3 +++ b/man3/getgrnam.3 @@ -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 diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3 index 2b3d4926e2..48ebbbe5e2 100644 --- a/man3/gethostbyname.3 +++ b/man3/gethostbyname.3 @@ -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 diff --git a/man3/getlogin.3 b/man3/getlogin.3 index 1c152cc111..47b433f97a 100644 --- a/man3/getlogin.3 +++ b/man3/getlogin.3 @@ -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 diff --git a/man3/getmntent.3 b/man3/getmntent.3 index 1ad69f9af1..8ca5f0d764 100644 --- a/man3/getmntent.3 +++ b/man3/getmntent.3 @@ -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), diff --git a/man3/getnetent.3 b/man3/getnetent.3 index c028240e25..be2dd21252 100644 --- a/man3/getnetent.3 +++ b/man3/getnetent.3 @@ -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 diff --git a/man3/getopt.3 b/man3/getopt.3 index b7b51b776f..93f6ef1e3b 100644 --- a/man3/getopt.3 +++ b/man3/getopt.3 @@ -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 diff --git a/man3/getprotoent.3 b/man3/getprotoent.3 index 5a67f23eee..ae4e6949cd 100644 --- a/man3/getprotoent.3 +++ b/man3/getprotoent.3 @@ -44,25 +44,37 @@ endprotoent \- get protocol entry .B void endprotoent(void); .fi .SH DESCRIPTION -The \fBgetprotoent\fP() function reads the next line from the file +The +.BR getprotoent () +function reads the next line from the file \fI/etc/protocols\fP and returns a structure \fIprotoent\fP containing the broken out fields from the line. The \fI/etc/protocols\fP file is opened if necessary. .PP -The \fBgetprotobyname\fP() function returns a \fIprotoent\fP +The +.BR getprotobyname () +function returns a \fIprotoent\fP structure for the line from \fI/etc/protocols\fP that matches the protocol name \fIname\fP. .PP -The \fBgetprotobynumber\fP() function returns a \fIprotoent\fP +The +.BR getprotobynumber () +function returns a \fIprotoent\fP structure for the line that matches the protocol number \fInumber\fP. .PP -The \fBsetprotoent\fP() function opens and rewinds the +The +.BR setprotoent () +function opens and rewinds the \fI/etc/protocols\fP file. If \fIstayopen\fP is true (1), then -the file will not be closed between calls to \fBgetprotobyname\fP() -or \fBgetprotobynumber\fP(). +the file will not be closed between calls to +.BR getprotobyname () +or +.BR getprotobynumber (). .PP -The \fBendprotoent\fP() function closes \fI/etc/protocols\fP. +The +.BR endprotoent () +function closes \fI/etc/protocols\fP. .PP The \fIprotoent\fP structure is defined in \fI<netdb.h>\fP as follows: .sp @@ -87,7 +99,11 @@ A zero terminated list of alternative names for the protocol. .I p_proto The protocol number. .SH "RETURN VALUE" -The \fBgetprotoent\fP(), \fBgetprotobyname\fP() and \fBgetprotobynumber\fP() +The +.BR getprotoent (), +.BR getprotobyname () +and +.BR getprotobynumber () functions return the \fIprotoent\fP structure, or a NULL pointer if an error occurs or the end of the file is reached. .SH FILES diff --git a/man3/getpw.3 b/man3/getpw.3 index 5424d30f22..bcd7d978c2 100644 --- a/man3/getpw.3 +++ b/man3/getpw.3 @@ -38,7 +38,9 @@ getpw \- Re-construct password line entry .BI "int getpw(uid_t " uid ", char *" buf ); .fi .SH DESCRIPTION -The \fBgetpw\fP() function re-constructs the password line entry for +The +.BR getpw () +function re-constructs the password line entry for the given user ID \fIuid\fP in the buffer \fIbuf\fP. The returned buffer contains a line of format .sp @@ -62,7 +64,9 @@ struct passwd { .fi .RE .SH "RETURN VALUE" -The \fBgetpw\fP() function returns 0 on success, or \-1 if an error +The +.BR getpw () +function returns 0 on success, or \-1 if an error occurs. .SH ERRORS .TP diff --git a/man3/getpwent.3 b/man3/getpwent.3 index fe851e4657..ebb63cbc6e 100644 --- a/man3/getpwent.3 +++ b/man3/getpwent.3 @@ -43,7 +43,9 @@ getpwent, setpwent, endpwent \- get password file entry .B void endpwent(void); .fi .SH DESCRIPTION -The \fBgetpwent\fP() function returns a pointer to a structure containing +The +.BR getpwent () +function returns a pointer to a structure containing the broken-out fields of a record from the password database (e.g., the local password file .IR /etc/passwd , @@ -52,10 +54,14 @@ The first time it is called it returns the first entry; thereafter, it returns successive entries. .PP -The \fBsetpwent\fP() function rewinds to the beginning +The +.BR setpwent () +function rewinds to the beginning of the password database. .PP -The \fBendpwent\fP() function is used to close the password database +The +.BR endpwent () +function is used to close the password database after all processing has been performed. .PP The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: @@ -74,7 +80,9 @@ struct passwd { .fi .RE .SH "RETURN VALUE" -The \fBgetpwent\fP() function returns a pointer to a +The +.BR getpwent () +function returns a pointer to a .I passwd structure, or NULL if there are no more entries or an error occurs. diff --git a/man3/getpwnam.3 b/man3/getpwnam.3 index bed5bae4d7..e83f0e01d1 100644 --- a/man3/getpwnam.3 +++ b/man3/getpwnam.3 @@ -108,7 +108,11 @@ can be found using .BR sysconf (3) with the _SC_GETPW_R_SIZE_MAX parameter. .SH "RETURN VALUE" -The \fBgetpwnam\fP() and \fBgetpwuid\fP() functions return a pointer to a +The +.BR getpwnam () +and +.BR getpwuid () +functions return a pointer to a .I passwd structure, or NULL if the matching entry is not found or an error occurs. @@ -126,7 +130,11 @@ by subsequent calls to or .BR getpwuid (). .LP -The \fBgetpwnam_r\fP() and \fBgetpwuid_r\fP() functions return +The +.BR getpwnam_r () +and +.BR getpwuid_r () +functions return zero on success. In case of error, an error number is returned. .SH ERRORS diff --git a/man3/getservent.3 b/man3/getservent.3 index 9a74d367c1..83349deccf 100644 --- a/man3/getservent.3 +++ b/man3/getservent.3 @@ -48,29 +48,41 @@ get service entry .B void endservent(void); .fi .SH DESCRIPTION -The \fBgetservent\fP() function reads the next line from the file +The +.BR getservent () +function reads the next line from the file \fI/etc/services\fP and returns a structure \fIservent\fP containing the broken out fields from the line. The \fI/etc/services\fP file is opened if necessary. .PP -The \fBgetservbyname\fP() function returns a \fIservent\fP structure +The +.BR getservbyname () +function returns a \fIservent\fP structure for the line from \fI/etc/services\fP that matches the service \fIname\fP using protocol \fIproto\fP. If \fIproto\fP is NULL, any protocol will be matched. .PP -The \fBgetservbyport\fP() function returns a \fIservent\fP structure +The +.BR getservbyport () +function returns a \fIservent\fP structure for the line that matches the port \fIport\fP given in network byte order using protocol \fIproto\fP. If \fIproto\fP is NULL, any protocol will be matched. .PP -The \fBsetservent\fP() function opens and rewinds the +The +.BR setservent () +function opens and rewinds the \fI/etc/services\fP file. If \fIstayopen\fP is true (1), then the -file will not be closed between calls to \fBgetservbyname\fP() and -\fBgetservbyport\fP(). +file will not be closed between calls to +.BR getservbyname () +and +.BR getservbyport (). .PP -The \fBendservent\fP() function closes \fI/etc/services\fP. +The +.BR endservent () +function closes \fI/etc/services\fP. .PP The \fIservent\fP structure is defined in \fI<netdb.h>\fP as follows: .sp @@ -99,7 +111,11 @@ The port number for the service given in network byte order. .I s_proto The name of the protocol to use with this service. .SH "RETURN VALUE" -The \fBgetservent\fP(), \fBgetservbyname\fP() and \fBgetservbyport\fP() +The +.BR getservent (), +.BR getservbyname () +and +.BR getservbyport () functions return the \fIservent\fP structure, or a NULL pointer if an error occurs or the end of the file is reached. .SH FILES diff --git a/man3/getusershell.3 b/man3/getusershell.3 index f58076cdb0..d4572d2914 100644 --- a/man3/getusershell.3 +++ b/man3/getusershell.3 @@ -39,19 +39,29 @@ getusershell, setusershell, endusershell \- get legal user shells .B void endusershell(void); .fi .SH DESCRIPTION -The \fBgetusershell\fP() function returns the next line from the file +The +.BR getusershell () +function returns the next line from the file \fI/etc/shells\fP, opening the file if necessary. The line should contain the pathname of a valid user shell. If \fI/etc/shells\fP does not exist or -is unreadable, \fBgetusershell\fP() behaves as if \fI/bin/sh\fP and +is unreadable, +.BR getusershell () +behaves as if \fI/bin/sh\fP and \fI/bin/csh\fP were listed in the file. .PP -The \fBsetusershell\fP() function rewinds \fI/etc/shells\fP. +The +.BR setusershell () +function rewinds \fI/etc/shells\fP. .PP -The \fBendusershell\fP() function closes \fI/etc/shells\fP. +The +.BR endusershell () +function closes \fI/etc/shells\fP. .SH "RETURN VALUE" -The \fBgetusershell\fP() function returns a NULL pointer on end-of-file. +The +.BR getusershell () +function returns a NULL pointer on end-of-file. .SH FILES .nf /etc/shells diff --git a/man3/getutent.3 b/man3/getutent.3 index 9848338e47..260406d89c 100644 --- a/man3/getutent.3 +++ b/man3/getutent.3 @@ -46,47 +46,67 @@ getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- access .sp .BI "void utmpname(const char *" file ); .SH DESCRIPTION -\fButmpname\fP() sets the name of the utmp-format file for the other utmp +.BR utmpname () +sets the name of the utmp-format file for the other utmp functions to access. -If \fButmpname\fP() is not used to set the filename +If +.BR utmpname () +is not used to set the filename before the other functions are used, they assume \fB_PATH_UTMP\fP, as defined in \fI<paths.h>\fP. .PP -\fBsetutent\fP() rewinds the file pointer to the beginning of the utmp file. +.BR setutent () +rewinds the file pointer to the beginning of the utmp file. It is generally a Good Idea to call it before any of the other functions. .PP -\fBendutent\fP() closes the utmp file. +.BR endutent () +closes the utmp file. It should be called when the user code is done accessing the file with the other functions. .PP -\fBgetutent\fP() reads a line from the current file position in the utmp +.BR getutent () +reads a line from the current file position in the utmp file. It returns a pointer to a structure containing the fields of the line. .PP -\fBgetutid\fP() searches forward from the current file position in the utmp +.BR getutid () +searches forward from the current file position in the utmp file based upon \fIut\fP. If \fIut\fP->ut_type is one of \fBRUN_LVL\fP, -\fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP, \fBgetutid\fP() will +\fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP, +.BR getutid () +will find the first entry whose \fIut_type\fP field matches \fIut\fP->ut_type. If \fIut\fP->ut_type is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, -\fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP, \fBgetutid\fP() will find the +\fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP, +.BR getutid () +will find the first entry whose ut_id field matches \fIut\fP->ut_id. .PP -\fBgetutline\fP() searches forward from the current file position in the +.BR getutline () +searches forward from the current file position in the utmp file. It scans entries whose ut_type is \fBUSER_PROCESS\fP or \fBLOGIN_PROCESS\fP and returns the first one whose ut_line field matches \fIut\fP->ut_line. .PP -\fBpututline\fP() writes the utmp structure \fIut\fP into the utmp file. -It uses \fBgetutid\fP() to search for the proper place in the file to insert +.BR pututline () +writes the utmp structure \fIut\fP into the utmp file. +It uses +.BR getutid () +to search for the proper place in the file to insert the new entry. If it cannot find an appropriate slot for \fIut\fP, -\fBpututline\fP() will append the new entry to the end of the file. +.BR pututline () +will append the new entry to the end of the file. .SH "RETURN VALUE" -\fBgetutent\fP(), \fBgetutid\fP(), \fBgetutline\fP() and \fBpututline\fP() +.BR getutent (), +.BR getutid (), +.BR getutline () +and +.BR pututline () return a pointer to a \fBstruct utmp\fP on success, and NULL on failure. This \fBstruct utmp\fP is allocated in static storage, and may be overwritten by subsequent calls. diff --git a/man3/getw.3 b/man3/getw.3 index edbd4cbe9b..6bacf43c28 100644 --- a/man3/getw.3 +++ b/man3/getw.3 @@ -31,20 +31,30 @@ getw, putw \- input and output of words (ints) .br .BI "int putw(int " w ", FILE *" stream ); .SH DESCRIPTION -\fBgetw\fP() reads a word (that is, an \fIint\fP) from \fIstream\fP. +.BR getw () +reads a word (that is, an \fIint\fP) from \fIstream\fP. It's provided for compatibility with SVr4. -We recommend you use \fBfread\fP(3) instead. +We recommend you use +.BR fread (3) +instead. .P -\fBputw\fP() writes the word \fIw\fP (that is, +.BR putw () +writes the word \fIw\fP (that is, an \fIint\fP) to \fIstream\fP. It is provided for compatibility with SVr4, but we recommend you use -\fBfwrite\fP(3) instead. +.BR fwrite (3) +instead. .SH "RETURN VALUE" -Normally, \fBgetw\fP() returns the word read, and \fBputw\fP() returns 0. +Normally, +.BR getw () +returns the word read, and +.BR putw () +returns 0. On error, they return \fBEOF\fP. .SH BUGS The value returned on error is also a legitimate data value. -\fBferror\fP(3) can be used to distinguish between the two cases. +.BR ferror (3) +can be used to distinguish between the two cases. .SH "CONFORMING TO" SVr4 .SH "SEE ALSO" diff --git a/man3/getwchar.3 b/man3/getwchar.3 index 06d348b387..b4394887e0 100644 --- a/man3/getwchar.3 +++ b/man3/getwchar.3 @@ -22,8 +22,11 @@ getwchar \- read a wide character from standard input .BI "wint_t getwchar(void);" .fi .SH DESCRIPTION -The \fBgetwchar\fP() function is the wide-character equivalent of the -\fBgetchar\fP(3) function. +The +.BR getwchar () +function is the wide-character equivalent of the +.BR getchar (3) +function. It reads a wide character from \fBstdin\fP and returns it. If the end of stream is reached, or if \fIferror(stdin)\fP becomes @@ -34,15 +37,21 @@ If a wide-character conversion error occurs, it sets For a non-locking counterpart, see .BR unlocked_stdio (3). .SH "RETURN VALUE" -The \fBgetwchar\fP() function returns the next wide-character from +The +.BR getwchar () +function returns the next wide-character from standard input, or WEOF. .SH "CONFORMING TO" C99 .SH NOTES -The behaviour of \fBgetwchar\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR getwchar () +depends on the LC_CTYPE category of the current locale. .PP -It is reasonable to expect that \fBgetwchar\fP() will actually +It is reasonable to expect that +.BR getwchar () +will actually read a multibyte sequence from standard input and then convert it to a wide character. .SH "SEE ALSO" diff --git a/man3/hsearch.3 b/man3/hsearch.3 index 98d866b52f..00089d8779 100644 --- a/man3/hsearch.3 +++ b/man3/hsearch.3 @@ -60,13 +60,18 @@ and allow the user to create a hash table (only one at a time) which associates a key with any data. .PP -First the table must be created with the function \fBhcreate\fP(). +First the table must be created with the function +.BR hcreate (). The argument \fInel\fP is an estimate of the maximum number of entries in the table. -The function \fBhcreate\fP() may adjust this value upward to improve the +The function +.BR hcreate () +may adjust this value upward to improve the performance of the resulting hash table. .PP -The corresponding function \fBhdestroy\fP() frees the memory occupied by +The corresponding function +.BR hdestroy () +frees the memory occupied by the hash table so that a new table can be constructed. .PP The argument \fIitem\fP is of type \fBENTRY\fP, which is a typedef defined in @@ -84,11 +89,15 @@ typedef struct entry { The field \fIkey\fP points to the null-terminated string which is the search key. The field \fIdata\fP points to the data associated with that key. -The function \fBhsearch\fP() searches the hash table for an +The function +.BR hsearch () +searches the hash table for an item with the same key as \fIitem\fP (where "the same" is determined using .BR strcmp (3)), and if successful returns a pointer to it. -The argument \fIaction\fP determines what \fBhsearch\fP() does +The argument \fIaction\fP determines what +.BR hsearch () +does after an unsuccessful search. A value of \fBENTER\fP instructs it to insert a copy of \fIitem\fP, while a value of \fBFIND\fP means to return @@ -104,14 +113,19 @@ The struct it points to must be zeroed before the first call to .BR hcreate_r (). .SH "RETURN VALUE" -\fBhcreate\fP() and \fBhcreate_r\fP() return 0 when allocation of the memory +.BR hcreate () +and +.BR hcreate_r () +return 0 when allocation of the memory for the hash table fails, non-zero otherwise. .LP -\fBhsearch\fP() returns NULL if \fIaction\fP is \fBENTER\fP and +.BR hsearch () +returns NULL if \fIaction\fP is \fBENTER\fP and the hash table is full, or \fIaction\fP is \fBFIND\fP and \fIitem\fP cannot be found in the hash table. .LP -\fBhsearch_r\fP() returns 0 if \fIaction\fP is \fBENTER\fP and +.BR hsearch_r () +returns 0 if \fIaction\fP is \fBENTER\fP and the hash table is full, and non-zero otherwise. .SH ERRORS POSIX documents diff --git a/man3/iconv.3 b/man3/iconv.3 index 23fe54215a..ba2527e3cc 100644 --- a/man3/iconv.3 +++ b/man3/iconv.3 @@ -26,15 +26,20 @@ iconv \- perform character set conversion .fi .SH DESCRIPTION The argument \fIcd\fP must be a conversion descriptor created using the -function \fBiconv_open\fP(). +function +.BR iconv_open (). .PP The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL. -In this case, the \fBiconv\fP() function converts the multibyte sequence +In this case, the +.BR iconv () +function converts the multibyte sequence starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP. At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read. At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. .PP -The \fBiconv\fP() function converts one multibyte character at a time, and for +The +.BR iconv () +function converts one multibyte character at a time, and for each character conversion it increments \fI*inbuf\fP and decrements \fI*inbytesleft\fP by the number of converted input bytes, it increments \fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted @@ -48,7 +53,9 @@ is left pointing to the beginning of the invalid multibyte sequence. .PP 2. The input byte sequence has been entirely converted, i.e. \fI*inbytesleft\fP has gone down to 0. -In this case \fBiconv\fP() returns the number of +In this case +.BR iconv () +returns the number of non-reversible conversions performed during this call. .PP 3. An incomplete multibyte sequence is encountered in the input, and the @@ -63,7 +70,8 @@ In this case it sets \fIerrno\fP to \fBE2BIG\fP and returns (size_t)(\-1). A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but \fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. In this case, the -\fBiconv\fP() function attempts to set \fIcd\fP's conversion state to the +.BR iconv () +function attempts to set \fIcd\fP's conversion state to the initial state and store a corresponding shift sequence at \fI*outbuf\fP. At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. If the output buffer has no more room for this reset sequence, it sets @@ -74,10 +82,13 @@ written. .PP A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and \fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. -In this case, the \fBiconv\fP() +In this case, the +.BR iconv () function sets \fIcd\fP's conversion state to the initial state. .SH "RETURN VALUE" -The \fBiconv\fP() function returns the number of characters converted in a +The +.BR iconv () +function returns the number of characters converted in a non-reversible way during this call; reversible conversions are not counted. In case of error, it sets \fIerrno\fP and returns (size_t)(\-1). .SH ERRORS diff --git a/man3/iconv_close.3 b/man3/iconv_close.3 index 6745b25ef9..4f6694e480 100644 --- a/man3/iconv_close.3 +++ b/man3/iconv_close.3 @@ -19,10 +19,15 @@ iconv_close \- deallocate descriptor for character set conversion .BI "int iconv_close(iconv_t " cd ); .fi .SH DESCRIPTION -The \fBiconv_close\fP() function deallocates a conversion descriptor \fIcd\fP -previously allocated using \fBiconv_open\fP(). +The +.BR iconv_close () +function deallocates a conversion descriptor \fIcd\fP +previously allocated using +.BR iconv_open (). .SH "RETURN VALUE" -When successful, the \fBiconv_close\fP() function returns 0. +When successful, the +.BR iconv_close () +function returns 0. In case of error, it sets .I errno and returns \-1. diff --git a/man3/iconv_open.3 b/man3/iconv_open.3 index e98811d68b..99c45d4a3b 100644 --- a/man3/iconv_open.3 +++ b/man3/iconv_open.3 @@ -23,7 +23,9 @@ iconv_open \- allocate descriptor for character set conversion .BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode ); .fi .SH DESCRIPTION -The \fBiconv_open\fP() function allocates a conversion descriptor suitable +The +.BR iconv_open () +function allocates a conversion descriptor suitable for converting byte sequences from character encoding \fIfromcode\fP to character encoding \fItocode\fP. .PP @@ -46,21 +48,28 @@ similarly looking characters. When the string "//IGNORE" is appended to \fItocode\fP, characters that cannot be represented in the target character set will be silently discarded. .PP -The resulting conversion descriptor can be used with \fBiconv\fP() +The resulting conversion descriptor can be used with +.BR iconv () any number of times. -It remains valid until deallocated using \fBiconv_close\fP(). +It remains valid until deallocated using +.BR iconv_close (). .PP A conversion descriptor contains a conversion state. After creation using -\fBiconv_open\fP(), the state is in the initial state. -Using \fBiconv\fP() +.BR iconv_open (), +the state is in the initial state. +Using +.BR iconv () modifies the descriptor's conversion state. (This implies that a conversion descriptor can not be used in multiple threads simultaneously.) -To bring the state back to the initial state, use \fBiconv\fP() +To bring the state back to the initial state, use +.BR iconv () with NULL as \fIinbuf\fP argument. .SH "RETURN VALUE" -The \fBiconv_open\fP() function returns a freshly allocated conversion +The +.BR iconv_open () +function returns a freshly allocated conversion descriptor. In case of error, it sets \fIerrno\fP and returns (iconv_t)(\-1). .SH ERRORS diff --git a/man3/index.3 b/man3/index.3 index aaa9a31922..9a3e16c982 100644 --- a/man3/index.3 +++ b/man3/index.3 @@ -38,16 +38,24 @@ index, rindex \- locate character in string .BI "char *rindex(const char *" s ", int " c ); .fi .SH DESCRIPTION -The \fBindex\fP() function returns a pointer to the first occurrence +The +.BR index () +function returns a pointer to the first occurrence of the character \fIc\fP in the string \fIs\fP. .PP -The \fBrindex\fP() function returns a pointer to the last occurrence +The +.BR rindex () +function returns a pointer to the last occurrence of the character \fIc\fP in the string \fIs\fP. .PP The terminating NULL character is considered to be a part of the strings. .SH "RETURN VALUE" -The \fBindex\fP() and \fBrindex\fP() functions return a pointer to +The +.BR index () +and +.BR rindex () +functions return a pointer to the matched character or NULL if the character is not found. .SH "CONFORMING TO" 4.3BSD; marked as LEGACY in POSIX.1-2001. diff --git a/man3/inet.3 b/man3/inet.3 index 06a42c48d8..5d40062577 100644 --- a/man3/inet.3 +++ b/man3/inet.3 @@ -57,48 +57,71 @@ inet_netof \- Internet address manipulation routines .BI "in_addr_t inet_netof(struct in_addr " in ); .fi .SH DESCRIPTION -\fBinet_aton\fP() converts the Internet host address \fIcp\fP from the +.BR inet_aton () +converts the Internet host address \fIcp\fP from the standard numbers-and-dots notation into binary data and stores it in -the structure that \fIinp\fP points to. \fBinet_aton\fP() returns +the structure that \fIinp\fP points to. +.BR inet_aton () +returns non-zero if the address is valid, zero if not. .PP -The \fBinet_addr\fP() function converts the Internet host address +The +.BR inet_addr () +function converts the Internet host address \fIcp\fP from numbers-and-dots notation into binary data in network byte order. If the input is invalid, INADDR_NONE (usually \-1) is returned. -This is an \fIobsolete\fP interface to \fBinet_aton\fP(), described +This is an \fIobsolete\fP interface to +.BR inet_aton (), +described immediately above; it is obsolete because \-1 is a valid address -(255.255.255.255), and \fBinet_aton\fP() provides a cleaner way +(255.255.255.255), and +.BR inet_aton () +provides a cleaner way to indicate error return. .PP -The \fBinet_network\fP() function extracts +The +.BR inet_network () +function extracts a number in host byte order suitable for use as an Internet address from \fIcp\fP, which is a string in numbers-and-dots notation. If the input is invalid, \-1 is returned. .PP -The \fBinet_ntoa\fP() function converts the Internet host address +The +.BR inet_ntoa () +function converts the Internet host address \fIin\fP given in network byte order to a string in standard numbers-and-dots notation. The string is returned in a statically allocated buffer, which subsequent calls will overwrite. .PP -The \fBinet_makeaddr\fP() function makes an Internet host address +The +.BR inet_makeaddr () +function makes an Internet host address in network byte order by combining the network number \fInet\fP with the local address \fIhost\fP in network \fInet\fP, both in local host byte order. .PP -The \fBinet_lnaof\fP() function returns the local host address part +The +.BR inet_lnaof () +function returns the local host address part of the Internet address \fIin\fP. The local host address is returned in local host byte order. .PP -The \fBinet_netof\fP() function returns the network number part of +The +.BR inet_netof () +function returns the network number part of the Internet Address \fIin\fP. The network number is returned in local host byte order. .PP -The structure \fIin_addr\fP as used in \fBinet_ntoa\fP(), -\fBinet_makeaddr\fP(), \fBinet_lnoaf\fP() and \fBinet_netof\fP() +The structure \fIin_addr\fP as used in +.BR inet_ntoa (), +.BR inet_makeaddr (), +.BR inet_lnoaf () +and +.BR inet_netof () is defined in \fInetinet/in.h\fP as: .sp .RS diff --git a/man3/infnan.3 b/man3/infnan.3 index 41bb8961cd..fbf2a76e0c 100644 --- a/man3/infnan.3 +++ b/man3/infnan.3 @@ -40,7 +40,9 @@ infnan \- deal with infinite or not-a-number (NaN) result .sp Link with \-lm. .SH DESCRIPTION -The \fBinfnan\fP() function returns a suitable value for infinity and +The +.BR infnan () +function returns a suitable value for infinity and "not-a-number" (NaN) results. The value of \fIerror\fP can be ERANGE to represent infinity or anything else to represent NaN. \fIerrno\fP diff --git a/man3/initgroups.3 b/man3/initgroups.3 index c71a9bcaef..a70bbb5253 100644 --- a/man3/initgroups.3 +++ b/man3/initgroups.3 @@ -38,7 +38,9 @@ initgroups \- initialize the supplementary group access list .BI "int initgroups(const char *" user ", gid_t " group ); .fi .SH DESCRIPTION -The \fBinitgroups\fP() function initializes the group access list by +The +.BR initgroups () +function initializes the group access list by reading the group database \fI/etc/group\fP and using all groups of which \fIuser\fP is a member. The additional group \fIgroup\fP is @@ -48,7 +50,9 @@ The .I user argument must be non-NULL. .SH "RETURN VALUE" -The \fBinitgroups\fP() function returns 0 on success. +The +.BR initgroups () +function returns 0 on success. On error, \-1 is returned, and .I errno is set appropriately. diff --git a/man3/insque.3 b/man3/insque.3 index 9091b68666..bebfebfa99 100644 --- a/man3/insque.3 +++ b/man3/insque.3 @@ -38,17 +38,22 @@ insque, remque \- insert/remove an item from a queue .BI "void insque(void *" elem ", void *" prev ); .BI "void remque(void *" elem ); .SH DESCRIPTION -\fBinsque\fP() and \fBremque\fP() are functions for manipulating +.BR insque () +and +.BR remque () +are functions for manipulating doubly-linked lists. Each element in the list is a structure of which the first two structure elements are a forward and a backward pointer. -\fBinsque\fP() inserts the element pointed to by \fIelem\fP +.BR insque () +inserts the element pointed to by \fIelem\fP immediately after the element pointed to by \fIprev\fP, which must not be NULL. -\fBremque\fP() removes the element pointed to by \fIelem\fP from the +.BR remque () +removes the element pointed to by \fIelem\fP from the doubly-linked list. .SH "CONFORMING TO" POSIX.1-2001 diff --git a/man3/isalpha.3 b/man3/isalpha.3 index 3358829276..ed0b45d453 100644 --- a/man3/isalpha.3 +++ b/man3/isalpha.3 @@ -142,11 +142,15 @@ falls into the tested class, and a zero value if not. .SH "CONFORMING TO" C99, 4.3BSD. -C89 specifies all of these functions except \fBisascii\fP() and -\fBisblank\fP(). -\fBisascii\fP() is a BSD extension +C89 specifies all of these functions except +.BR isascii () +and +.BR isblank (). +.BR isascii () +is a BSD extension and is also an SVr4 extension. -\fBisblank\fP() conforms to POSIX.1-2001 and C99 7.4.1.3. +.BR isblank () +conforms to POSIX.1-2001 and C99 7.4.1.3. .SH NOTE The details of what characters belong into which class depend on the current locale. diff --git a/man3/iswalnum.3 b/man3/iswalnum.3 index 4f05c6ac8c..2ba4946b00 100644 --- a/man3/iswalnum.3 +++ b/man3/iswalnum.3 @@ -21,8 +21,11 @@ iswalnum \- test for alphanumeric wide character .BI "int iswalnum(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswalnum\fP() function is the wide-character equivalent of the -\fBisalnum\fP() function. +The +.BR iswalnum () +function is the wide-character equivalent of the +.BR isalnum () +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "alnum". .PP @@ -48,7 +51,9 @@ As such, it also contains the wide-character class The wide-character class "alnum" always contains at least the letters 'A' to 'Z', 'a' to 'z' and the digits '0' to '9'. .SH "RETURN VALUE" -The \fBiswalnum\fP() function returns non-zero +The +.BR iswalnum () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "alnum". Otherwise it returns zero. @@ -58,5 +63,7 @@ C99. .BR isalnum (3), .BR iswctype (3) .SH NOTES -The behaviour of \fBiswalnum\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswalnum () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/iswalpha.3 b/man3/iswalpha.3 index 947c918588..4e1f2d99ee 100644 --- a/man3/iswalpha.3 +++ b/man3/iswalpha.3 @@ -21,8 +21,11 @@ iswalpha \- test for alphabetic wide character .BI "int iswalpha(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswalpha\fP() function is the wide-character equivalent of the -\fBisalpha\fP(3) function. +The +.BR iswalpha () +function is the wide-character equivalent of the +.BR isalpha (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "alpha". .PP @@ -52,7 +55,9 @@ and "lower". The wide-character class "alpha" always contains at least the letters 'A' to 'Z' and 'a' to 'z'. .SH "RETURN VALUE" -The \fBiswalpha\fP() function returns non-zero +The +.BR iswalpha () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "alpha". Otherwise it returns zero. @@ -62,5 +67,7 @@ C99. .BR isalpha (3), .BR iswctype (3) .SH NOTES -The behaviour of \fBiswalpha\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswalpha () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/iswblank.3 b/man3/iswblank.3 index f189bd6439..bd71a152f2 100644 --- a/man3/iswblank.3 +++ b/man3/iswblank.3 @@ -21,8 +21,11 @@ iswblank \- test for whitespace wide character .BI "int iswblank(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswblank\fP() function is the wide-character equivalent of the -\fBisblank\fP(3) function. +The +.BR iswblank () +function is the wide-character equivalent of the +.BR isblank (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "blank". .PP @@ -39,7 +42,9 @@ The wide-character class "blank" always contains at least the space character and the control character '\\t'. .SH "RETURN VALUE" -The \fBiswblank\fP() function returns non-zero +The +.BR iswblank () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "blank". Otherwise it returns zero. @@ -49,5 +54,7 @@ POSIX.1-2001. .BR isblank (3), .BR iswctype (3) .SH NOTES -The behaviour of \fBiswblank\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswblank () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/iswcntrl.3 b/man3/iswcntrl.3 index ee340a083e..e9ee07b6da 100644 --- a/man3/iswcntrl.3 +++ b/man3/iswcntrl.3 @@ -21,8 +21,11 @@ iswcntrl \- test for control wide character .BI "int iswcntrl(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswcntrl\fP() function is the wide-character equivalent of the -\fBiscntrl\fP(3) function. +The +.BR iswcntrl () +function is the wide-character equivalent of the +.BR iscntrl (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "cntrl". .PP @@ -34,7 +37,9 @@ For an unsigned char \fIc\fP, \fIiscntrl(c)\fP implies \fIiswcntrl(btowc(c))\fP, but not vice versa. .SH "RETURN VALUE" -The \fBiswcntrl\fP() function returns non-zero if \fIwc\fP is a +The +.BR iswcntrl () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "cntrl". Otherwise it returns zero. .SH "CONFORMING TO" @@ -43,5 +48,7 @@ C99. .BR iscntrl (3), .BR iswctype (3) .SH NOTES -The behaviour of \fBiswcntrl\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswcntrl () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/iswctype.3 b/man3/iswctype.3 index e41340e75f..8509c0dc30 100644 --- a/man3/iswctype.3 +++ b/man3/iswctype.3 @@ -23,7 +23,9 @@ iswctype \- wide-character classification .SH DESCRIPTION If \fIwc\fP is a wide character having the character property designated by \fIdesc\fP (or in other words: belongs to the character class designated by -\fIdesc\fP), the \fBiswctype\fP() function returns non-zero. +\fIdesc\fP), the +.BR iswctype () +function returns non-zero. Otherwise it returns zero. If \fIwc\fP is WEOF, zero is returned. @@ -32,7 +34,9 @@ If \fIwc\fP is WEOF, zero is returned. returned by the \fBwctype\fP function. .SH "RETURN VALUE" -The \fBiswctype\fP() function returns non-zero if +The +.BR iswctype () +function returns non-zero if the \fIwc\fP has the designated property. Otherwise it returns 0. @@ -53,5 +57,7 @@ C99. .BR iswxdigit (3), .BR wctype (3) .SH NOTES -The behaviour of \fBiswctype\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswctype () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/iswdigit.3 b/man3/iswdigit.3 index 65a48dd4a4..12f71dfd1b 100644 --- a/man3/iswdigit.3 +++ b/man3/iswdigit.3 @@ -21,8 +21,11 @@ iswdigit \- test for decimal digit wide character .BI "int iswdigit(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswdigit\fP() function is the wide-character equivalent of the -\fBisdigit\fP(3) function. +The +.BR iswdigit () +function is the wide-character equivalent of the +.BR isdigit (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "digit". .PP @@ -51,7 +54,9 @@ disjoint from the wide-character class The wide-character class "digit" always contains exactly the digits '0' to '9'. .SH "RETURN VALUE" -The \fBiswdigit\fP() function returns non-zero +The +.BR iswdigit () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "digit". Otherwise it returns zero. @@ -61,5 +66,7 @@ C99. .BR isdigit (3), .BR iswctype (3) .SH NOTES -The behaviour of \fBiswdigit\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswdigit () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/iswgraph.3 b/man3/iswgraph.3 index 6045edbf37..3731942326 100644 --- a/man3/iswgraph.3 +++ b/man3/iswgraph.3 @@ -21,8 +21,11 @@ iswgraph \- test for graphic wide character .BI "int iswgraph(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswgraph\fP() function is the wide-character equivalent of the -\fBisgraph\fP(3) function. +The +.BR iswgraph () +function is the wide-character equivalent of the +.BR isgraph (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "graph". .PP @@ -44,7 +47,9 @@ wide-character class "print" except the space character. It therefore contains the wide-character classes "alnum" and "punct". .SH "RETURN VALUE" -The \fBiswgraph\fP() function returns non-zero +The +.BR iswgraph () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "graph". Otherwise it returns zero. @@ -54,5 +59,7 @@ C99. .BR isgraph (3), .BR iswctype (3) .SH NOTES -The behaviour of \fBiswgraph\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswgraph () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/iswlower.3 b/man3/iswlower.3 index f7f9f03b01..12bde7921f 100644 --- a/man3/iswlower.3 +++ b/man3/iswlower.3 @@ -21,8 +21,11 @@ iswlower \- test for lowercase wide character .BI "int iswlower(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswlower\fP() function is the wide-character equivalent of the -\fBislower\fP(3) function. +The +.BR iswlower () +function is the wide-character equivalent of the +.BR islower (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "lower". .PP @@ -56,7 +59,9 @@ The wide-character class "lower" always contains at least the letters 'a' to 'z'. .SH "RETURN VALUE" -The \fBiswlower\fP() function returns non-zero +The +.BR iswlower () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "lower". Otherwise it returns zero. @@ -67,7 +72,9 @@ C99. .BR iswctype (3), .BR towlower (3) .SH NOTES -The behaviour of \fBiswlower\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswlower () +depends on the LC_CTYPE category of the current locale. .PP This function is not very appropriate for dealing with Unicode characters, diff --git a/man3/iswprint.3 b/man3/iswprint.3 index 7b082ac8be..3433f35daa 100644 --- a/man3/iswprint.3 +++ b/man3/iswprint.3 @@ -21,8 +21,11 @@ iswprint \- test for printing wide character .BI "int iswprint(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswprint\fP() function is the wide-character equivalent of the -\fBisprint\fP(3) function. +The +.BR iswprint () +function is the wide-character equivalent of the +.BR isprint (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "print". .PP @@ -31,7 +34,9 @@ The wide-character class "print" is disjoint from the wide-character class .PP The wide-character class "print" contains the wide-character class "graph". .SH "RETURN VALUE" -The \fBiswprint\fP() function returns non-zero if \fIwc\fP is a +The +.BR iswprint () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "print". Otherwise it returns zero. .SH "CONFORMING TO" @@ -40,5 +45,7 @@ C99. .BR isprint (3), .BR iswctype (3) .SH NOTES -The behaviour of \fBiswprint\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswprint () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/iswpunct.3 b/man3/iswpunct.3 index 0d4f85a6ac..f988106039 100644 --- a/man3/iswpunct.3 +++ b/man3/iswpunct.3 @@ -21,8 +21,11 @@ iswpunct \- test for punctuation or symbolic wide character .BI "int iswpunct(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswpunct\fP() function is the wide-character equivalent of the -\fBispunct\fP(3) function. +The +.BR iswpunct () +function is the wide-character equivalent of the +.BR ispunct (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "punct". .PP @@ -42,7 +45,9 @@ the wide-character class "punct" is disjoint from the wide-character class "space" and its subclass "blank". .SH "RETURN VALUE" -The \fBiswpunct\fP() function returns non-zero +The +.BR iswpunct () +function returns non-zero if \fIwc\fP is a wide-character belonging to the wide-character class "punct". Otherwise it returns zero. @@ -52,7 +57,9 @@ C99. .BR ispunct (3), .BR iswctype (3) .SH NOTES -The behaviour of \fBiswpunct\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswpunct () +depends on the LC_CTYPE category of the current locale. .PP This function's name is a misnomer when dealing with Unicode characters, diff --git a/man3/iswspace.3 b/man3/iswspace.3 index adac1eb562..2247a1e972 100644 --- a/man3/iswspace.3 +++ b/man3/iswspace.3 @@ -21,8 +21,11 @@ iswspace \- test for whitespace wide character .BI "int iswspace(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswspace\fP() function is the wide-character equivalent of the -\fBisspace\fP(3) function. +The +.BR iswspace () +function is the wide-character equivalent of the +.BR isspace (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "space". .PP @@ -38,7 +41,9 @@ The wide-character class "space" contains the wide-character class "blank". The wide-character class "space" always contains at least the space character and the control characters '\\f', '\\n', '\\r', '\\t', '\\v'. .SH "RETURN VALUE" -The \fBiswspace\fP() function returns non-zero if \fIwc\fP is a wide character +The +.BR iswspace () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "space". Otherwise it returns zero. .SH "CONFORMING TO" @@ -47,5 +52,7 @@ C99. .BR isspace (3), .BR iswctype (3) .SH NOTES -The behaviour of \fBiswspace\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswspace () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/iswupper.3 b/man3/iswupper.3 index aaf6f0e150..2d4b6981b7 100644 --- a/man3/iswupper.3 +++ b/man3/iswupper.3 @@ -21,8 +21,11 @@ iswupper \- test for uppercase wide character .BI "int iswupper(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswupper\fP() function is the wide-character equivalent of the -\fBisupper\fP(3) function. +The +.BR iswupper () +function is the wide-character equivalent of the +.BR isupper (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "upper". .PP @@ -49,7 +52,9 @@ which are equal to \fItowupper(wc)\fP and different from \fItowlower(wc)\fP. The wide-character class "upper" always contains at least the letters 'A' to 'Z'. .SH "RETURN VALUE" -The \fBiswupper\fP() function returns non-zero if \fIwc\fP is a wide character +The +.BR iswupper () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "upper". Otherwise it returns zero. .SH "CONFORMING TO" @@ -59,7 +64,9 @@ C99. .BR iswctype (3), .BR towupper (3) .SH NOTES -The behaviour of \fBiswupper\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswupper () +depends on the LC_CTYPE category of the current locale. .PP This function is not very appropriate for dealing with Unicode characters, diff --git a/man3/iswxdigit.3 b/man3/iswxdigit.3 index 3d29c6cb1d..7930d932ff 100644 --- a/man3/iswxdigit.3 +++ b/man3/iswxdigit.3 @@ -21,8 +21,11 @@ iswxdigit \- test for hexadecimal digit wide character .BI "int iswxdigit(wint_t " wc ); .fi .SH DESCRIPTION -The \fBiswxdigit\fP() function is the wide-character equivalent of the -\fBisxdigit\fP(3) function. +The +.BR iswxdigit () +function is the wide-character equivalent of the +.BR isxdigit (3) +function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "xdigit". .PP @@ -43,7 +46,9 @@ Being a subclass of the wide-character class "alnum", the wide-character class The wide-character class "xdigit" always contains at least the letters 'A' to 'F', 'a' to 'f' and the digits '0' to '9'. .SH "RETURN VALUE" -The \fBiswxdigit\fP() function returns non-zero if \fIwc\fP is a wide character +The +.BR iswxdigit () +function returns non-zero if \fIwc\fP is a wide character belonging to the wide-character class "xdigit". Otherwise it returns zero. .SH "CONFORMING TO" @@ -52,5 +57,7 @@ C99. .BR iswctype (3), .BR isxdigit (3) .SH NOTES -The behaviour of \fBiswxdigit\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR iswxdigit () +depends on the LC_CTYPE category of the current locale. @@ -76,22 +76,43 @@ y0, y0f, y0l, y1, y1f, y1l, yn, ynf, ynl \- Bessel functions .sp Link with \-lm. .SH DESCRIPTION -The \fBj0\fP() and \fBj1\fP() functions return Bessel functions of \fIx\fP +The +.BR j0 () +and +.BR j1 () +functions return Bessel functions of \fIx\fP of the first kind of orders 0 and 1, respectively. -The \fBjn\fP() function +The +.BR jn () +function returns the Bessel function of \fIx\fP of the first kind of order \fIn\fP. .PP -The \fBy0\fP() and \fBy1\fP() functions return Bessel functions of \fIx\fP +The +.BR y0 () +and +.BR y1 () +functions return Bessel functions of \fIx\fP of the second kind of orders 0 and 1, respectively. -The \fByn\fP() function +The +.BR yn () +function returns the Bessel function of \fIx\fP of the second kind of order \fIn\fP. .PP -For the functions \fBy0\fP(), \fBy1\fP() and \fByn\fP(), the value of \fIx\fP +For the functions +.BR y0 (), +.BR y1 () +and +.BR yn (), +the value of \fIx\fP must be positive. For negative values of \fIx\fP, these functions return \-HUGE_VAL. .PP -The \fBj0f\fP() etc. and \fBj0l\fP() etc. functions are versions that take +The +.BR j0f () +etc. and +.BR j0l () +etc. functions are versions that take and return .I float and @@ -103,7 +124,11 @@ The functions returning conform to SVr4, 4.3BSD, POSIX.1-2001. .SH BUGS -There are errors of up to 2e\-16 in the values returned by \fBj0\fP(), -\fBj1\fP() and \fBjn\fP() for values of \fIx\fP between \-8 and 8. +There are errors of up to 2e\-16 in the values returned by +.BR j0 (), +.BR j1 () +and +.BR jn () +for values of \fIx\fP between \-8 and 8. .SH "SEE ALSO" .BR feature_test_macros (7) diff --git a/man3/lgamma.3 b/man3/lgamma.3 index 1692b748f5..224476286b 100644 --- a/man3/lgamma.3 +++ b/man3/lgamma.3 @@ -27,7 +27,9 @@ Compile with \-std=c99; link with \-lm. For the definition of the Gamma function, see .BR tgamma (3). .PP -The \fBlgamma\fP() function returns the natural logarithm of +The +.BR lgamma () +function returns the natural logarithm of the absolute value of the Gamma function. The sign of the Gamma function is returned in the external integer \fIsigngam\fP declared in @@ -37,13 +39,21 @@ when it is negative. .PP Since using a constant location .I signgam -is not thread-safe, the functions \fBlgamma_r\fP() etc. have +is not thread-safe, the functions +.BR lgamma_r () +etc. have been introduced; they return this sign via the parameter .IR signp . .PP -For non-positive integer values of \fIx\fP, \fBlgamma\fP() returns HUGE_VAL, +For non-positive integer values of \fIx\fP, +.BR lgamma () +returns HUGE_VAL, sets \fIerrno\fP to ERANGE and raises the zero divide exception. -(Similarly, \fBlgammaf\fP() returns HUGE_VALF and \fBlgammal\fP() returns +(Similarly, +.BR lgammaf () +returns HUGE_VALF and +.BR lgammal () +returns HUGE_VALL.) .SH ERRORS In order to check for errors, set diff --git a/man3/log.3 b/man3/log.3 index 74c90893b9..6a24b6e03e 100644 --- a/man3/log.3 +++ b/man3/log.3 @@ -45,9 +45,13 @@ log, logf, logl \- natural logarithmic function .sp Link with \-lm. .SH DESCRIPTION -The \fBlog\fP() function returns the natural logarithm of \fIx\fP. +The +.BR log () +function returns the natural logarithm of \fIx\fP. .SH ERRORS -The \fBlog\fP() function can return the following errors: +The +.BR log () +function can return the following errors: .TP .B EDOM The argument \fIx\fP is negative. diff --git a/man3/log10.3 b/man3/log10.3 index a277c0dec2..827cad36e4 100644 --- a/man3/log10.3 +++ b/man3/log10.3 @@ -45,9 +45,13 @@ log10, log10f, log10l \- base-10 logarithmic function .sp Link with \-lm. .SH DESCRIPTION -The \fBlog10\fP() function returns the base 10 logarithm of \fIx\fP. +The +.BR log10 () +function returns the base 10 logarithm of \fIx\fP. .SH ERRORS -The \fBlog10\fP() function can return the following errors: +The +.BR log10 () +function can return the following errors: .TP .B EDOM The argument \fIx\fP is negative. diff --git a/man3/log2.3 b/man3/log2.3 index 8c0ea01256..db8e2fb2c7 100644 --- a/man3/log2.3 +++ b/man3/log2.3 @@ -45,9 +45,13 @@ log2, log2f, log2l \- base-2 logarithmic function .sp Compile with \-std=c99; link with \-lm. .SH DESCRIPTION -The \fBlog2\fP() function returns the base 2 logarithm of \fIx\fP. +The +.BR log2 () +function returns the base 2 logarithm of \fIx\fP. .SH ERRORS -The \fBlog2\fP() function can return the following error: +The +.BR log2 () +function can return the following error: .TP .B EDOM The argument \fIx\fP is negative. diff --git a/man3/longjmp.3 b/man3/longjmp.3 index c93368baac..3efb8a5cdb 100644 --- a/man3/longjmp.3 +++ b/man3/longjmp.3 @@ -36,35 +36,59 @@ longjmp, siglongjmp \- non-local jump to a saved stack context .fi .ad b .SH DESCRIPTION -\fBlongjmp\fP() and \fBsetjmp\fP(3) are useful for dealing with errors +.BR longjmp () +and +.BR setjmp (3) +are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. -\fBlongjmp\fP() restores the environment saved by the last call of -\fBsetjmp\fP(3) with the corresponding \fIenv\fP argument. +.BR longjmp () +restores the environment saved by the last call of +.BR setjmp (3) +with the corresponding \fIenv\fP argument. After -\fBlongjmp\fP() is completed, program execution continues as if the -corresponding call of \fBsetjmp\fP(3) had just returned the value +.BR longjmp () +is completed, program execution continues as if the +corresponding call of +.BR setjmp (3) +had just returned the value \fIval\fP. -\fBlongjmp\fP() cannot cause 0 to be returned. -If \fBlongjmp\fP() +.BR longjmp () +cannot cause 0 to be returned. +If +.BR longjmp () is invoked with a second argument of 0, 1 will be returned instead. .P -\fBsiglongjmp\fP() is similar to \fBlongjmp\fP() except for the type of +.BR siglongjmp () +is similar to +.BR longjmp () +except for the type of its \fIenv\fP argument. -If the \fBsigsetjmp\fP(3) call that set this -\fIenv\fP used a non-zero \fIsavesigs\fP flag, \fBsiglongjmp\fP() also +If the +.BR sigsetjmp (3) +call that set this +\fIenv\fP used a non-zero \fIsavesigs\fP flag, +.BR siglongjmp () +also restores the set of blocked signals. .SH "RETURN VALUE" These functions never return. .SH "CONFORMING TO" -C89, C99, and POSIX.1-2001 specify \fBlongjmp\fP(). -POSIX.1-2001 specifies \fBsiglongjmp\fP(). +C89, C99, and POSIX.1-2001 specify +.BR longjmp (). +POSIX.1-2001 specifies +.BR siglongjmp (). .SH NOTES -POSIX does not specify whether \fBlongjmp\fP() will restore the signal +POSIX does not specify whether +.BR longjmp () +will restore the signal context. If you want to save and restore signal masks, use -\fBsiglongjmp\fP(). +.BR siglongjmp (). .P -\fBlongjmp\fP() and \fBsiglongjmp\fP() make programs hard to +.BR longjmp () +and +.BR siglongjmp () +make programs hard to understand and maintain. If possible an alternative should be used. .SH "SEE ALSO" diff --git a/man3/lsearch.3 b/man3/lsearch.3 index f4fe16cec3..bf3f0659da 100644 --- a/man3/lsearch.3 +++ b/man3/lsearch.3 @@ -40,7 +40,10 @@ lfind, lsearch \- linear search of an array .RE .fi .SH DESCRIPTION -\fBlfind\fP() and \fBlsearch\fP() perform a linear search for +.BR lfind () +and +.BR lsearch () +perform a linear search for \fIkey\fP in the array \fIbase\fP which has *\fInmemb\fP elements of \fIsize\fP bytes each. The comparison function referenced by @@ -49,14 +52,19 @@ The comparison function referenced by returns zero if the \fIkey\fP object matches the array member, and non-zero otherwise. .PP -If \fBlsearch\fP() does not find a matching element, then the \fIkey\fP +If +.BR lsearch () +does not find a matching element, then the \fIkey\fP object is inserted at the end of the table, and *\fInmemb\fP is incremented. In particular, one should know that a matching element exists, or that more room is available. .SH "RETURN VALUE" -\fBlfind\fP() returns a pointer to a matching member of the array, or -NULL if no match is found. \fBlsearch\fP() returns a pointer to +.BR lfind () +returns a pointer to a matching member of the array, or +NULL if no match is found. +.BR lsearch () +returns a pointer to a matching member of the array, or to the newly added member if no match is found. .SH "CONFORMING TO" diff --git a/man3/makecontext.3 b/man3/makecontext.3 index 2c9e578ab2..25ccfcc2b7 100644 --- a/man3/makecontext.3 +++ b/man3/makecontext.3 @@ -34,22 +34,34 @@ makecontext, swapcontext \- manipulate user context In a System V-like environment, one has the type \fIucontext_t\fP defined in .I <ucontext.h> and the four functions -\fBgetcontext\fP(3), \fBsetcontext\fP(3), \fBmakecontext\fP() -and \fBswapcontext\fP() that allow user-level context switching +.BR getcontext (3), +.BR setcontext (3), +.BR makecontext () +and +.BR swapcontext () +that allow user-level context switching between multiple threads of control within a process. .LP For the type and the first two functions, see .BR getcontext (2). .LP -The \fBmakecontext\fP() function modifies the context pointed to -by \fIucp\fP (which was obtained from a call to \fBgetcontext\fP(3)). -Before invoking \fBmakecontext\fP(), the caller must allocate a new stack +The +.BR makecontext () +function modifies the context pointed to +by \fIucp\fP (which was obtained from a call to +.BR getcontext (3)). +Before invoking +.BR makecontext (), +the caller must allocate a new stack for this context and assign its address to \fIucp->uc_stack\fP, and define a successor context and assign its address to \fIucp->uc_link\fP. -When this context is later activated (using \fBsetcontext\fP(3) or -\fBswapcontext\fP()) the function \fIfunc\fP is called, +When this context is later activated (using +.BR setcontext (3) +or +.BR swapcontext ()) +the function \fIfunc\fP is called, and passed the series of integer .RI ( int ) arguments that follow @@ -59,15 +71,22 @@ the caller must specify the number of these arguments in When this function returns, the successor context is activated. If the successor context pointer is NULL, the thread exits. .LP -The \fBswapcontext\fP() function saves the current context in +The +.BR swapcontext () +function saves the current context in the structure pointed to by \fIoucp\fP, and then activates the context pointed to by \fIucp\fP. .SH "RETURN VALUE" -When successful, \fBswapcontext\fP() +When successful, +.BR swapcontext () does not return. (But we may return later, in case \fIoucp\fP is -activated, in which case it looks like \fBswapcontext\fP() returns 0.) -On error, \fBswapcontext\fP() returns \-1 and +activated, in which case it looks like +.BR swapcontext () +returns 0.) +On error, +.BR swapcontext () +returns \-1 and sets \fIerrno\fP appropriately. .SH ERRORS .TP diff --git a/man3/mblen.3 b/man3/mblen.3 index 5f592f1278..1c8e1e5027 100644 --- a/man3/mblen.3 +++ b/man3/mblen.3 @@ -21,7 +21,9 @@ mblen \- determine number of bytes in next multibyte character .BI "int mblen(const char *" s ", size_t " n ); .fi .SH DESCRIPTION -If \fIs\fP is not a NULL pointer, the \fBmblen\fP() function inspects at most +If \fIs\fP is not a NULL pointer, the +.BR mblen () +function inspects at most \fIn\fP bytes of the multibyte string starting at \fIs\fP and extracts the next complete multibyte character. It uses a static anonymous shift state only @@ -31,23 +33,30 @@ character, it returns the number of bytes that were consumed from \fIs\fP. If the multibyte character is the null wide character, it returns 0. .PP If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte -character, \fBmblen\fP() returns \-1. +character, +.BR mblen () +returns \-1. This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift sequences. .PP If the multibyte string starting at \fIs\fP contains an invalid multibyte -sequence before the next complete character, \fBmblen\fP() +sequence before the next complete character, +.BR mblen () also returns \-1. .PP -If \fIs\fP is a NULL pointer, the \fBmblen\fP() function +If \fIs\fP is a NULL pointer, the +.BR mblen () +function .\" The Dinkumware doc and the Single Unix specification say this, but .\" glibc doesn't implement this. resets the shift state, only known to this function, to the initial state, and returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "RETURN VALUE" -The \fBmblen\fP() function returns the number of +The +.BR mblen () +function returns the number of bytes parsed from the multibyte sequence starting at \fIs\fP, if a non-null wide character was recognized. It returns 0, if a null wide character was recognized. @@ -59,8 +68,12 @@ C99 .SH "SEE ALSO" .BR mbrlen (3) .SH NOTES -The behaviour of \fBmblen\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR mblen () +depends on the LC_CTYPE category of the current locale. .PP -The function \fBmbrlen\fP(3) provides a better interface to the same +The function +.BR mbrlen (3) +provides a better interface to the same functionality. diff --git a/man3/mbrlen.3 b/man3/mbrlen.3 index 4bc21b8fd0..64c55a3446 100644 --- a/man3/mbrlen.3 +++ b/man3/mbrlen.3 @@ -21,7 +21,9 @@ mbrlen \- determine number of bytes in next multibyte character .BI "size_t mbrlen(const char *" s ", size_t " n ", mbstate_t *" ps ); .fi .SH DESCRIPTION -The \fBmbrlen\fP() function inspects at most \fIn\fP bytes of the multibyte +The +.BR mbrlen () +function inspects at most \fIn\fP bytes of the multibyte string starting at \fIs\fP and extracts the next complete multibyte character. It updates the shift state \fI*ps\fP. If the multibyte character is not the @@ -31,13 +33,17 @@ If the multibyte character is the null wide character, it resets the shift state \fI*ps\fP to the initial state and returns 0. .PP If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte -character, \fBmbrlen\fP() returns \fI(size_t)(\-2)\fP. +character, +.BR mbrlen () +returns \fI(size_t)(\-2)\fP. This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift sequences. .PP If the multibyte string starting at \fIs\fP contains an invalid multibyte -sequence before the next complete character, \fBmbrlen\fP() returns +sequence before the next complete character, +.BR mbrlen () +returns \fI(size_t)(\-1)\fP and sets \fIerrno\fP to \fBEILSEQ\fP. In this case, the effects on \fI*ps\fP are undefined. @@ -45,7 +51,9 @@ the effects on \fI*ps\fP are undefined. If \fIps\fP is a NULL pointer, a static anonymous state only known to the mbrlen function is used instead. .SH "RETURN VALUE" -The \fBmbrlen\fP() function returns the number of bytes +The +.BR mbrlen () +function returns the number of bytes parsed from the multibyte sequence starting at \fIs\fP, if a non-null wide character was recognized. It returns 0, if a null wide character was recognized. @@ -59,5 +67,7 @@ C99 .SH "SEE ALSO" .BR mbrtowc (3) .SH NOTES -The behaviour of \fBmbrlen\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR mbrlen () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/mbrtowc.3 b/man3/mbrtowc.3 index fdbed133a9..1c1f1895e5 100644 --- a/man3/mbrtowc.3 +++ b/man3/mbrtowc.3 @@ -24,7 +24,9 @@ mbrtowc \- convert a multibyte sequence to a wide character .SH DESCRIPTION The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is not NULL. -In this case, the \fBmbrtowc\fP() function inspects at most \fIn\fP +In this case, the +.BR mbrtowc () +function inspects at most \fIn\fP bytes of the multibyte string starting at \fIs\fP, extracts the next complete multibyte character, converts it to a wide character and stores it at \fI*pwc\fP. @@ -36,30 +38,40 @@ If the converted wide character is L'\\0', it resets the shift state \fI*ps\fP to the initial state and returns 0. .PP If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte -character, \fBmbrtowc\fP() returns \fI(size_t)(\-2)\fP. +character, +.BR mbrtowc () +returns \fI(size_t)(\-2)\fP. This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift sequences. .PP If the multibyte string starting at \fIs\fP contains an invalid multibyte -sequence before the next complete character, \fBmbrtowc\fP() returns +sequence before the next complete character, +.BR mbrtowc () +returns \fI(size_t)(\-1)\fP and sets \fIerrno\fP to \fBEILSEQ\fP. In this case, the effects on \fI*ps\fP are undefined. .PP A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. In this -case the \fBmbrtowc\fP() function behaves as above, excepts that it does not +case the +.BR mbrtowc () +function behaves as above, excepts that it does not store the converted wide character in memory. .PP A third case is when \fIs\fP is NULL. In this case, \fIpwc\fP and \fIn\fP are ignored. If the conversion state represented by \fI*ps\fP denotes an -incomplete multibyte character conversion, the \fBmbrtowc\fP() function +incomplete multibyte character conversion, the +.BR mbrtowc () +function returns \fI(size_t)(\-1)\fP, sets \fIerrno\fP to \fBEILSEQ\fP, and leaves \fI*ps\fP in an undefined state. -Otherwise, the \fBmbrtowc\fP() function +Otherwise, the +.BR mbrtowc () +function puts \fI*ps\fP in the initial state and returns 0. .PP In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous @@ -72,7 +84,9 @@ by zeroing it, for example using memset(&a, 0, sizeof(a)); .RE .SH "RETURN VALUE" -The \fBmbrtowc\fP() function returns the number of bytes parsed from the +The +.BR mbrtowc () +function returns the number of bytes parsed from the multibyte sequence starting at \fIs\fP, if a non-L'\\0' wide character was recognized. It returns 0, if a L'\\0' wide character was recognized. @@ -86,5 +100,7 @@ C99 .SH "SEE ALSO" .BR mbsrtowcs (3) .SH NOTES -The behaviour of \fBmbrtowc\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR mbrtowc () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/mbsinit.3 b/man3/mbsinit.3 index 6576eb0e01..c4d9ca0875 100644 --- a/man3/mbsinit.3 +++ b/man3/mbsinit.3 @@ -31,15 +31,20 @@ state is needed for the sake of encodings such as ISO-2022 and UTF-7. .PP The initial state is the state at the beginning of conversion of a string. There are two kinds of state: The one used by multibyte to wide character -conversion functions, such as \fBmbsrtowcs\fP(3), and the one used by wide -character to multibyte conversion functions, such as \fBwcsrtombs\fP(3), +conversion functions, such as +.BR mbsrtowcs (3), +and the one used by wide +character to multibyte conversion functions, such as +.BR wcsrtombs (3), but they both fit in a \fBmbstate_t\fP, and they both have the same representation for an initial state. .PP For 8-bit encodings, all states are equivalent to the initial state. For multibyte encodings like UTF-8, EUC-*, BIG5 or SJIS, the wide character to multibyte conversion functions never produce non-initial states, but the -multibyte to wide-character conversion functions like \fBmbrtowc\fP(3) do +multibyte to wide-character conversion functions like +.BR mbrtowc (3) +do produce non-initial states when interrupted in the middle of a character. .PP One possible way to create an mbstate_t in initial @@ -53,10 +58,13 @@ On Linux, the following works as well, but might generate compiler warnings: mbstate_t state = { 0 }; .fi .PP -The function \fBmbsinit\fP() tests whether \fI*ps\fP corresponds to an +The function +.BR mbsinit () +tests whether \fI*ps\fP corresponds to an initial state. .SH "RETURN VALUE" -\fBmbsinit\fP() returns non-zero if \fI*ps\fP is an initial state, or if +.BR mbsinit () +returns non-zero if \fI*ps\fP is an initial state, or if \fIps\fP is a null pointer. Otherwise it returns 0. .SH "CONFORMING TO" @@ -65,5 +73,7 @@ C99 .BR mbsrtowcs (3), .BR wcsrtombs (3) .SH NOTES -The behaviour of \fBmbsinit\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR mbsinit () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/mbsnrtowcs.3 b/man3/mbsnrtowcs.3 index 528c385136..f416fd55f9 100644 --- a/man3/mbsnrtowcs.3 +++ b/man3/mbsnrtowcs.3 @@ -21,11 +21,17 @@ mbsnrtowcs \- convert a multibyte string to a wide-character string .BI " size_t " nms ", size_t " len ", mbstate_t *" ps ); .fi .SH DESCRIPTION -The \fBmbsnrtowcs\fP() function is like the \fBmbsrtowcs\fP() function, except that +The +.BR mbsnrtowcs () +function is like the +.BR mbsrtowcs () +function, except that the number of bytes to be converted, starting at \fI*src\fP, is limited to \fInms\fP. .PP -If \fIdest\fP is not a NULL pointer, the \fBmbsnrtowcs\fP() function converts at +If \fIdest\fP is not a NULL pointer, the +.BR mbsnrtowcs () +function converts at most \fInms\fP bytes from the multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP. At most \fIlen\fP wide characters are written to \fIdest\fP. @@ -67,7 +73,9 @@ state only known to the mbsnrtowcs function is used instead. The programmer must ensure that there is room for at least \fIlen\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -The \fBmbsnrtowcs\fP() function returns the number of wide characters +The +.BR mbsnrtowcs () +function returns the number of wide characters that make up the converted part of the wide-character string, not including the terminating null wide character. If an invalid multibyte sequence was @@ -78,7 +86,9 @@ This function is a GNU extension. .BR iconv (3), .BR mbsrtowcs (3) .SH NOTES -The behaviour of \fBmbsnrtowcs\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR mbsnrtowcs () +depends on the LC_CTYPE category of the current locale. .PP Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/mbsrtowcs.3 b/man3/mbsrtowcs.3 index 1a92f9d8a3..cff0066c9e 100644 --- a/man3/mbsrtowcs.3 +++ b/man3/mbsrtowcs.3 @@ -22,7 +22,9 @@ mbsrtowcs \- convert a multibyte string to a wide-character string .BI " size_t " len ", mbstate_t *" ps ); .fi .SH DESCRIPTION -If \fIdest\fP is not a NULL pointer, the \fBmbsrtowcs\fP() function converts the +If \fIdest\fP is not a NULL pointer, the +.BR mbsrtowcs () +function converts the multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP. At most \fIlen\fP wide characters are written to \fIdest\fP. The shift state @@ -60,7 +62,9 @@ state only known to the mbsrtowcs function is used instead. The programmer must ensure that there is room for at least \fIlen\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -The \fBmbsrtowcs\fP() function returns the number of wide characters that make +The +.BR mbsrtowcs () +function returns the number of wide characters that make up the converted part of the wide-character string, not including the terminating null wide character. If an invalid multibyte sequence was @@ -72,7 +76,9 @@ C99 .BR mbsnrtowcs (3), .BR mbstowcs (3) .SH NOTES -The behaviour of \fBmbsrtowcs\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR mbsrtowcs () +depends on the LC_CTYPE category of the current locale. .PP Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/mbstowcs.3 b/man3/mbstowcs.3 index 5e996fe6d9..2a8569c551 100644 --- a/man3/mbstowcs.3 +++ b/man3/mbstowcs.3 @@ -22,7 +22,9 @@ mbstowcs \- convert a multibyte string to a wide-character string .fi .SH DESCRIPTION If \fIdest\fP is not a NULL pointer, -the \fBmbstowcs\fP() function converts the +the +.BR mbstowcs () +function converts the multibyte string \fIsrc\fP to a wide-character string starting at \fIdest\fP. At most \fIn\fP wide characters are written to \fIdest\fP. The conversion starts @@ -53,7 +55,9 @@ and that no length limit exists. In order to avoid the case 2 above, the programmer should make sure \fIn\fP is greater or equal to \fImbstowcs(NULL,src,0)+1\fP. .SH "RETURN VALUE" -The \fBmbstowcs\fP() function returns the number of wide characters that make +The +.BR mbstowcs () +function returns the number of wide characters that make up the converted part of the wide-character string, not including the terminating null wide character. If an invalid multibyte sequence was @@ -63,8 +67,12 @@ C99 .SH "SEE ALSO" .BR mbsrtowcs (3) .SH NOTES -The behaviour of \fBmbstowcs\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR mbstowcs () +depends on the LC_CTYPE category of the current locale. .PP -The function \fBmbsrtowcs\fP(3) provides a better interface to the same +The function +.BR mbsrtowcs (3) +provides a better interface to the same functionality. diff --git a/man3/mbtowc.3 b/man3/mbtowc.3 index 837edab2c3..1fd59bd579 100644 --- a/man3/mbtowc.3 +++ b/man3/mbtowc.3 @@ -23,7 +23,9 @@ mbtowc \- convert a multibyte sequence to a wide character .SH DESCRIPTION The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is not NULL. -In this case, the \fBmbtowc\fP() function inspects at most \fIn\fP +In this case, the +.BR mbtowc () +function inspects at most \fIn\fP bytes of the multibyte string starting at \fIs\fP, extracts the next complete multibyte character, converts it to a wide character and stores it at @@ -34,20 +36,25 @@ If \fIs\fP does not point to a '\\0' byte, it returns the number of bytes that were consumed from \fIs\fP, otherwise it returns 0. .PP If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte -character, or if they contain an invalid multibyte sequence, \fBmbtowc\fP() +character, or if they contain an invalid multibyte sequence, +.BR mbtowc () returns \-1. This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift sequences. .PP A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. In this -case the \fBmbtowc\fP() function behaves as above, excepts that it does not +case the +.BR mbtowc () +function behaves as above, excepts that it does not store the converted wide character in memory. .PP A third case is when \fIs\fP is NULL. In this case, \fIpwc\fP and \fIn\fP are ignored. -The \fBmbtowc\fP() function +The +.BR mbtowc () +function .\" The Dinkumware doc and the Single Unix specification say this, but .\" glibc doesn't implement this. resets the shift state, only known to this function, @@ -55,11 +62,15 @@ to the initial state, and returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "RETURN VALUE" -If \fIs\fP is not NULL, the \fBmbtowc\fP() function returns the number of +If \fIs\fP is not NULL, the +.BR mbtowc () +function returns the number of consumed bytes starting at \fIs\fP, or 0 if \fIs\fP points to a null byte, or \-1 upon failure. .PP -If \fIs\fP is NULL, the \fBmbtowc\fP() function +If \fIs\fP is NULL, the +.BR mbtowc () +function returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "CONFORMING TO" @@ -69,9 +80,13 @@ C99 .BR mbrtowc (3), .BR mbstowcs (3) .SH NOTES -The behaviour of \fBmbtowc\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR mbtowc () +depends on the LC_CTYPE category of the current locale. .PP This function is not multi-thread safe. -The function \fBmbrtowc\fP(3) provides +The function +.BR mbrtowc (3) +provides a better interface to the same functionality. diff --git a/man3/memccpy.3 b/man3/memccpy.3 index ac9fb49086..22ce158321 100644 --- a/man3/memccpy.3 +++ b/man3/memccpy.3 @@ -35,11 +35,15 @@ memccpy \- copy memory area .BI "void *memccpy(void *" dest ", const void *" src ", int " c ", size_t " n ); .fi .SH DESCRIPTION -The \fBmemccpy\fP() function copies no more than \fIn\fP bytes from +The +.BR memccpy () +function copies no more than \fIn\fP bytes from memory area \fIsrc\fP to memory area \fIdest\fP, stopping when the character \fIc\fP is found. .SH "RETURN VALUE" -The \fBmemccpy\fP() function returns a pointer to the next character +The +.BR memccpy () +function returns a pointer to the next character in \fIdest\fP after \fIc\fP, or NULL if \fIc\fP was not found in the first \fIn\fP characters of \fIsrc\fP. .SH "CONFORMING TO" diff --git a/man3/memchr.3 b/man3/memchr.3 index 604fd8ced2..b0dd9b51b2 100644 --- a/man3/memchr.3 +++ b/man3/memchr.3 @@ -51,7 +51,11 @@ function, except that it searches backwards from the end of the \fIn\fP bytes pointed to by \fIs\fP instead of forwards from the front. .SH "RETURN VALUE" -The \fBmemchr\fP() and \fBmemrchr\fP() functions return a pointer +The +.BR memchr () +and +.BR memrchr () +functions return a pointer to the matching byte or NULL if the character does not occur in the given memory area. .SH "CONFORMING TO" diff --git a/man3/memcmp.3 b/man3/memcmp.3 index 866e6de630..6d9975baea 100644 --- a/man3/memcmp.3 +++ b/man3/memcmp.3 @@ -35,13 +35,17 @@ memcmp \- compare memory areas .BI "int memcmp(const void *" s1 ", const void *" s2 ", size_t " n ); .fi .SH DESCRIPTION -The \fBmemcmp\fP() function compares the first \fIn\fP bytes of the +The +.BR memcmp () +function compares the first \fIn\fP bytes of the memory areas \fIs1\fP and \fIs2\fP. It returns an integer less than, equal to, or greater than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP. .SH "RETURN VALUE" -The \fBmemcmp\fP() function returns an integer less than, equal to, or +The +.BR memcmp () +function returns an integer less than, equal to, or greater than zero if the first \fIn\fP bytes of \fIs1\fP is found, respectively, to be less than, to match, or be greater than the first \fIn\fP bytes of \fIs2\fP. diff --git a/man3/memcpy.3 b/man3/memcpy.3 index 0b64de37a5..0c3baf1f29 100644 --- a/man3/memcpy.3 +++ b/man3/memcpy.3 @@ -35,12 +35,18 @@ memcpy \- copy memory area .BI "void *memcpy(void *" dest ", const void *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBmemcpy\fP() function copies \fIn\fP bytes from memory area +The +.BR memcpy () +function copies \fIn\fP bytes from memory area \fIsrc\fP to memory area \fIdest\fP. The memory areas should not overlap. -Use \fBmemmove\fP(3) if the memory areas do overlap. +Use +.BR memmove (3) +if the memory areas do overlap. .SH "RETURN VALUE" -The \fBmemcpy\fP() function returns a pointer to \fIdest\fP. +The +.BR memcpy () +function returns a pointer to \fIdest\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99, POSIX.1-2001. .SH "SEE ALSO" diff --git a/man3/memfrob.3 b/man3/memfrob.3 index ee3e9658d5..ce0fcd6ce0 100644 --- a/man3/memfrob.3 +++ b/man3/memfrob.3 @@ -35,19 +35,27 @@ memfrob \- frobnicate (encrypt) a memory area .BI "void *memfrob(void *" s ", size_t " n ); .fi .SH DESCRIPTION -The \fBmemfrob\fP() function encrypts the first \fIn\fP bytes of the +The +.BR memfrob () +function encrypts the first \fIn\fP bytes of the memory area \fIs\fP by exclusive-ORing each character with the number 42. -The effect can be reversed by using \fBmemfrob\fP() on the +The effect can be reversed by using +.BR memfrob () +on the encrypted memory area. .PP Note that this function is not a proper encryption routine as the XOR constant is fixed, and is only suitable for hiding strings. .SH "RETURN VALUE" -The \fBmemfrob\fP() function returns a pointer to the encrypted memory +The +.BR memfrob () +function returns a pointer to the encrypted memory area. .SH "CONFORMING TO" -The \fBmemfrob\fP() function is unique to the +The +.BR memfrob () +function is unique to the GNU C Library. .SH "SEE ALSO" .BR strfry (3) diff --git a/man3/memmem.3 b/man3/memmem.3 index 6376083b3d..cd742d29a3 100644 --- a/man3/memmem.3 +++ b/man3/memmem.3 @@ -40,11 +40,15 @@ memmem \- locate a substring .in .fi .SH DESCRIPTION -The \fBmemmem\fP() function finds the start of the first occurrence +The +.BR memmem () +function finds the start of the first occurrence of the substring \fIneedle\fP of length \fIneedlelen\fP in the memory area \fIhaystack\fP of length \fIhaystacklen\fP. .SH "RETURN VALUE" -The \fBmemmem\fP() function returns a pointer to the beginning of the +The +.BR memmem () +function returns a pointer to the beginning of the substring, or NULL if the substring is not found. .SH "CONFORMING TO" This function is a GNU extension. diff --git a/man3/memmove.3 b/man3/memmove.3 index ca2c25b29b..6bb8b2290d 100644 --- a/man3/memmove.3 +++ b/man3/memmove.3 @@ -35,11 +35,15 @@ memmove \- copy memory area .BI "void *memmove(void *" dest ", const void *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBmemmove\fP() function copies \fIn\fP bytes from memory area +The +.BR memmove () +function copies \fIn\fP bytes from memory area \fIsrc\fP to memory area \fIdest\fP. The memory areas may overlap. .SH "RETURN VALUE" -The \fBmemmove\fP() function returns a pointer to \fIdest\fP. +The +.BR memmove () +function returns a pointer to \fIdest\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99, POSIX.1-2001. .SH "SEE ALSO" diff --git a/man3/memset.3 b/man3/memset.3 index a6f64b449d..377b349495 100644 --- a/man3/memset.3 +++ b/man3/memset.3 @@ -35,10 +35,14 @@ memset \- fill memory with a constant byte .BI "void *memset(void *" s ", int " c ", size_t " n ); .fi .SH DESCRIPTION -The \fBmemset\fP() function fills the first \fIn\fP bytes of the +The +.BR memset () +function fills the first \fIn\fP bytes of the memory area pointed to by \fIs\fP with the constant byte \fIc\fP. .SH "RETURN VALUE" -The \fBmemset\fP() function returns a pointer to the memory area +The +.BR memset () +function returns a pointer to the memory area \fIs\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99, POSIX.1-2001. diff --git a/man3/mkdtemp.3 b/man3/mkdtemp.3 index ff677f7f91..3c8642b71b 100644 --- a/man3/mkdtemp.3 +++ b/man3/mkdtemp.3 @@ -31,7 +31,9 @@ mkdtemp \- create a unique temporary directory .BI "char *mkdtemp(char *" template ); .fi .SH DESCRIPTION -The \fBmkdtemp\fP() function generates a uniquely-named temporary +The +.BR mkdtemp () +function generates a uniquely-named temporary directory from \fItemplate\fP. The last six characters of \fItemplate\fP must be XXXXXX and these are replaced with a string that makes the @@ -42,7 +44,9 @@ Since it will be modified, .I template must not be a string constant, but should be declared as a character array. .SH "RETURN VALUE" -The \fBmkdtemp\fP() function returns a pointer to the modified template +The +.BR mkdtemp () +function returns a pointer to the modified template string on success, and NULL on failure, in which case .IR errno is set appropriately. @@ -52,7 +56,9 @@ is set appropriately. The last six characters of \fItemplate\fP were not XXXXXX. Now \fItemplate\fP is unchanged. .PP -Also see \fBmkdir(2)\fP for other possible values for \fIerrno\fP. +Also see +.BR mkdir (2) +for other possible values for \fIerrno\fP. .SH "CONFORMING TO" This function is present on the BSDs. .\" As at 2006, this function is being considered for a revision of POSIX.1 diff --git a/man3/mkfifo.3 b/man3/mkfifo.3 index a9ea26033a..031dea4ccd 100644 --- a/man3/mkfifo.3 +++ b/man3/mkfifo.3 @@ -35,7 +35,8 @@ mkfifo \- make a FIFO special file (a named pipe) .BI "int mkfifo(const char *" pathname ", mode_t " mode ); .fi .SH DESCRIPTION -\fBmkfifo\fP() makes a FIFO special file with name \fIpathname\fP. +.BR mkfifo () +makes a FIFO special file with name \fIpathname\fP. \fImode\fP specifies the FIFO's permissions. It is modified by the process's \fBumask\fP in the usual way: the permissions of the created @@ -45,7 +46,8 @@ A FIFO special file is similar to a pipe, except that it is created in a different way. Instead of being an anonymous communications channel, a FIFO special file is entered into the file system by -calling \fBmkfifo\fP(). +calling +.BR mkfifo (). .PP Once you have created a FIFO special file in this way, any process can open it for reading or writing, in the same way as an ordinary file. diff --git a/man3/mkstemp.3 b/man3/mkstemp.3 index 862a412fab..43d0d7c8b9 100644 --- a/man3/mkstemp.3 +++ b/man3/mkstemp.3 @@ -38,7 +38,9 @@ mkstemp \- create a unique temporary file .BI "int mkstemp(char *" template ); .fi .SH DESCRIPTION -The \fBmkstemp\fP() function generates a unique temporary filename +The +.BR mkstemp () +function generates a unique temporary filename from \fItemplate\fP. The last six characters of \fItemplate\fP must be XXXXXX and these are replaced with a string that makes the @@ -55,7 +57,9 @@ flag, guaranteeing that when .BR mkstemp () returns successfully we are the only user. .SH "RETURN VALUE" -On success, the \fBmkstemp\fP() function returns the file descriptor +On success, the +.BR mkstemp () +function returns the file descriptor of the temporary file. On error, \-1 is returned, and .I errno diff --git a/man3/mktemp.3 b/man3/mktemp.3 index d93a447531..8f3f0df6e7 100644 --- a/man3/mktemp.3 +++ b/man3/mktemp.3 @@ -39,7 +39,9 @@ mktemp \- make a unique temporary filename .BI "char *mktemp(char *" template ); .fi .SH DESCRIPTION -The \fBmktemp\fP() function generates a unique temporary filename +The +.BR mktemp () +function generates a unique temporary filename from \fItemplate\fP. The last six characters of \fItemplate\fP must be XXXXXX and these are replaced with a string that makes the @@ -48,7 +50,9 @@ Since it will be modified, .I template must not be a string constant, but should be declared as a character array. .SH "RETURN VALUE" -The \fBmktemp\fP() function returns NULL on error (\fItemplate\fP did not +The +.BR mktemp () +function returns NULL on error (\fItemplate\fP did not end in XXXXXX) and \fItemplate\fP otherwise. If the call was successful, the last six bytes of \fItemplate\fP will have been modified in such a way that the resulting name is unique @@ -68,13 +72,16 @@ for libc4, libc5, glibc1; glibc2 follows the Single Unix Specification and has the prototype in .IR <stdlib.h> . .SH BUGS -Never use \fBmktemp\fP(). +Never use +.BR mktemp (). Some implementations follow 4.3BSD and replace XXXXXX by the current process ID and a single letter, so that at most 26 different names can be returned. Since on the one hand the names are easy to guess, and on the other hand there is a race between testing whether the name exists and -opening the file, every use of \fBmktemp\fP() is a security risk. +opening the file, every use of +.BR mktemp () +is a security risk. The race is avoided by .BR mkstemp (3). .SH "SEE ALSO" diff --git a/man3/modf.3 b/man3/modf.3 index 2a16c5a985..4c75b80618 100644 --- a/man3/modf.3 +++ b/man3/modf.3 @@ -45,11 +45,15 @@ floating-point number .sp Link with \-lm. .SH DESCRIPTION -The \fBmodf\fP() function breaks the argument \fIx\fP into an integral +The +.BR modf () +function breaks the argument \fIx\fP into an integral part and a fractional part, each of which has the same sign as \fIx\fP. The integral part is stored in \fIiptr\fP. .SH "RETURN VALUE" -The \fBmodf\fP() function returns the fractional part of \fIx\fP. +The +.BR modf () +function returns the fractional part of \fIx\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. The diff --git a/man3/nl_langinfo.3 b/man3/nl_langinfo.3 index d6e19bc5ad..fb88e1f73f 100644 --- a/man3/nl_langinfo.3 +++ b/man3/nl_langinfo.3 @@ -21,7 +21,9 @@ nl_langinfo \- query language and locale information .BI "char *nl_langinfo(nl_item " item ); .fi .SH DESCRIPTION -The \fBnl_langinfo\fP() function provides access to locale information +The +.BR nl_langinfo () +function provides access to locale information in a more flexible way than .BR localeconv (3) does. @@ -96,13 +98,17 @@ For a more detailed list, consult .IR "The GNU C Library Reference Manual" . .SH "RETURN VALUE" If no locale has been selected for the appropriate category, -\fBnl_langinfo\fP() returns a pointer to the corresponding string in the +.BR nl_langinfo () +returns a pointer to the corresponding string in the "C" locale. .PP If \fIitem\fP is not valid, a pointer to an empty string is returned. .PP This pointer may point to static data that may be overwritten on the -next call to \fBnl_langinfo\fP() or \fBsetlocale\fP(). +next call to +.BR nl_langinfo () +or +.BR setlocale (). .SH "CONFORMING TO" SUSv2, POSIX.1-2001. .SH "SEE ALSO" diff --git a/man3/offsetof.3 b/man3/offsetof.3 index b282410457..75ba7551fb 100644 --- a/man3/offsetof.3 +++ b/man3/offsetof.3 @@ -31,7 +31,9 @@ offsetof \- offset of a structure member \fBsize_t offsetof(\fItype\fP, \fPmember\fP); .SH DESCRIPTION -The macro \fBoffsetof\fP() returns the offset of the field +The macro +.BR offsetof () +returns the offset of the field \fImember\fP from the start of the structure \fItype\fP. This macro is useful because the sizes of the fields that compose @@ -45,10 +47,12 @@ A compiler error will result if \fImember\fP is not aligned to a byte boundary (i.e., it is a bit field). .SH "RETURN VALUE" -\fBoffsetof\fP() returns the offset of the given element within the +.BR offsetof () +returns the offset of the given element within the given type, in units of bytes. .SH EXAMPLE -On a Linux/x86 system, when compiled using the default \fBgcc\fP(1) +On a Linux/x86 system, when compiled using the default +.BR gcc (1) options, the program below produces the following output: .fi diff --git a/man3/on_exit.3 b/man3/on_exit.3 index a3e1a14e26..988765430d 100644 --- a/man3/on_exit.3 +++ b/man3/on_exit.3 @@ -36,15 +36,20 @@ on_exit \- register a function to be called at normal process termination .BI "int on_exit(void (*" function ")(int , void *), void *" arg ); .fi .SH DESCRIPTION -The \fBon_exit\fP() function registers the given \fIfunction\fP to be +The +.BR on_exit () +function registers the given \fIfunction\fP to be called at normal process termination, whether via .BR exit (3) or via return from the program's \fImain\fP(). The \fIfunction\fP is passed the argument to .BR exit (3) -and the \fIarg\fP argument from \fBon_exit\fP(). +and the \fIarg\fP argument from +.BR on_exit (). .SH "RETURN VALUE" -The \fBon_exit\fP() function returns the value 0 if successful; otherwise +The +.BR on_exit () +function returns the value 0 if successful; otherwise it returns a non-zero value. .SH "CONFORMING TO" This function comes from SunOS 4, but is also present in diff --git a/man3/opendir.3 b/man3/opendir.3 index 4c7edb9020..8739862b84 100644 --- a/man3/opendir.3 +++ b/man3/opendir.3 @@ -38,11 +38,15 @@ opendir \- open a directory .BI "DIR *opendir(const char *" name ); .fi .SH DESCRIPTION -The \fBopendir\fP() function opens a directory stream corresponding to the +The +.BR opendir () +function opens a directory stream corresponding to the directory \fIname\fP, and returns a pointer to the directory stream. The stream is positioned at the first entry in the directory. .SH "RETURN VALUE" -The \fBopendir\fP() function returns a pointer to the directory stream. +The +.BR opendir () +function returns a pointer to the directory stream. On error, NULL is returned, and .I errno is set appropriately. diff --git a/man3/pow.3 b/man3/pow.3 index 4f7cb1919d..eed74bc87b 100644 --- a/man3/pow.3 +++ b/man3/pow.3 @@ -44,10 +44,14 @@ pow, powf, powl \- power functions .sp Link with \-lm. .SH DESCRIPTION -The \fBpow\fP() function returns the value of \fIx\fP raised to the +The +.BR pow () +function returns the value of \fIx\fP raised to the power of \fIy\fP. .SH ERRORS -The \fBpow\fP() function can return the following error: +The +.BR pow () +function can return the following error: .TP .B EDOM The argument \fIx\fP is negative and \fIy\fP is not an integral value. diff --git a/man3/pow10.3 b/man3/pow10.3 index 49ae63e575..4e48864a81 100644 --- a/man3/pow10.3 +++ b/man3/pow10.3 @@ -37,7 +37,9 @@ pow10, pow10f, pow10l \- base-10 power functions .sp Link with \-lm. .SH DESCRIPTION -The \fBpow10\fP() function returns the value of 10 raised to the +The +.BR pow10 () +function returns the value of 10 raised to the power \fIx\fP. .SH "CONFORMING TO" This is a GNU extension. diff --git a/man3/psignal.3 b/man3/psignal.3 index 982ae0b68e..de8eb85ca2 100644 --- a/man3/psignal.3 +++ b/man3/psignal.3 @@ -37,7 +37,9 @@ psignal \- print signal message .BI "extern const char *const " sys_siglist []; .fi .SH DESCRIPTION -The \fBpsignal\fP() function displays a message on \fIstderr\fP +The +.BR psignal () +function displays a message on \fIstderr\fP consisting of the string \fIs\fP, a colon, a space, and a string describing the signal number \fIsig\fP. If \fIsig\fP is invalid, @@ -46,7 +48,9 @@ the message displayed will indicate an unknown signal. The array \fIsys_siglist\fP holds the signal description strings indexed by signal number. .SH "RETURN VALUE" -The \fBpsignal\fP() function returns no value. +The +.BR psignal () +function returns no value. .SH "CONFORMING TO" 4.3BSD .SH "SEE ALSO" diff --git a/man3/putenv.3 b/man3/putenv.3 index 22ae42490a..f643e36523 100644 --- a/man3/putenv.3 +++ b/man3/putenv.3 @@ -42,7 +42,9 @@ putenv \- change or add an environment variable .\" Not: const char * .fi .SH DESCRIPTION -The \fBputenv\fP() function adds or changes the value of environment +The +.BR putenv () +function adds or changes the value of environment variables. The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP. If \fIname\fP does not already exist in the environment, then @@ -53,31 +55,42 @@ then the value of \fIname\fP in the environment is changed to The string pointed to by \fIstring\fP becomes part of the environment, so altering the string changes the environment. .SH "RETURN VALUE" -The \fBputenv\fP() function returns zero on success, +The +.BR putenv () +function returns zero on success, or non-zero if an error occurs. .SH ERRORS .TP .B ENOMEM Insufficient space to allocate new environment. .SH NOTES -The \fBputenv\fP() function is not required to be reentrant, and the +The +.BR putenv () +function is not required to be reentrant, and the one in libc4, libc5 and glibc2.0 is not, but the glibc2.1 version is. .LP Description for libc4, libc5, glibc: If the argument \fIstring\fP is of the form \fIname\fP, and does not contain an `=' character, then the variable \fIname\fP is removed from the environment. -If \fBputenv\fP() has to allocate a new array \fIenviron\fP, -and the previous array was also allocated by \fBputenv\fP(), +If +.BR putenv () +has to allocate a new array \fIenviron\fP, +and the previous array was also allocated by +.BR putenv (), then it will be freed. In no case will the old storage associated to the environment variable itself be freed. .LP The libc4 and libc5 and glibc 2.1.2 versions conform to SUSv2: -the pointer \fIstring\fP given to \fBputenv\fP() is used. +the pointer \fIstring\fP given to +.BR putenv () +is used. In particular, this string becomes part of the environment; changing it later will change the environment. -(Thus, it is an error is to call \fBputenv\fP() with an automatic variable +(Thus, it is an error is to call +.BR putenv () +with an automatic variable as the argument, then return from the calling function while \fIstring\fP is still part of the environment.) However, glibc 2.0-2.1.1 differs: a copy of the string is used. diff --git a/man3/putpwent.3 b/man3/putpwent.3 index e05e7833b2..7e1239ab54 100644 --- a/man3/putpwent.3 +++ b/man3/putpwent.3 @@ -37,7 +37,9 @@ putpwent \- write a password file entry .BI "int putpwent(const struct passwd *" p ", FILE *" stream ); .fi .SH DESCRIPTION -The \fBputpwent\fP() function writes a password entry from the +The +.BR putpwent () +function writes a password entry from the structure \fIp\fP in the file associated with \fIstream\fP. .PP The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: @@ -57,7 +59,9 @@ struct passwd { .fi .in -0.5i .SH "RETURN VALUE" -The \fBputpwent\fP() function returns 0 on success, or \-1 if an error +The +.BR putpwent () +function returns 0 on success, or \-1 if an error occurs. .SH ERRORS .TP diff --git a/man3/putwchar.3 b/man3/putwchar.3 index e849a55667..f2afa1ed06 100644 --- a/man3/putwchar.3 +++ b/man3/putwchar.3 @@ -22,8 +22,11 @@ putwchar \- write a wide character to standard output .BI "wint_t putwchar(wchar_t " wc ); .fi .SH DESCRIPTION -The \fBputwchar\fP() function is the wide-character equivalent of the -\fBputchar\fP(3) function. +The +.BR putwchar () +function is the wide-character equivalent of the +.BR putchar (3) +function. It writes the wide character \fIwc\fP to \fBstdout\fP. If \fIferror(stdout)\fP becomes true, it returns WEOF. If a wide character @@ -33,15 +36,21 @@ Otherwise it returns \fIwc\fP. For a non-locking counterpart, see .BR unlocked_stdio (3). .SH "RETURN VALUE" -The \fBputwchar\fP() function returns \fIwc\fP if no error occurred, +The +.BR putwchar () +function returns \fIwc\fP if no error occurred, or WEOF to indicate an error. .SH "CONFORMING TO" C99. .SH NOTES -The behaviour of \fBputwchar\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR putwchar () +depends on the LC_CTYPE category of the current locale. .PP -It is reasonable to expect that \fBputwchar\fP() will actually write +It is reasonable to expect that +.BR putwchar () +will actually write the multibyte sequence corresponding to the wide character \fIwc\fP. .SH "SEE ALSO" .BR fputwc (3), diff --git a/man3/qsort.3 b/man3/qsort.3 index 2a05e19daf..87539018ba 100644 --- a/man3/qsort.3 +++ b/man3/qsort.3 @@ -42,7 +42,9 @@ qsort \- sorts an array .in .fi .SH DESCRIPTION -The \fBqsort\fP() function sorts an array with \fInmemb\fP elements of +The +.BR qsort () +function sorts an array with \fInmemb\fP elements of size \fIsize\fP. The \fIbase\fP argument points to the start of the array. @@ -57,7 +59,9 @@ less than, equal to, or greater than the second. If two members compare as equal, their order in the sorted array is undefined. .SH "RETURN VALUE" -The \fBqsort\fP() function returns no value. +The +.BR qsort () +function returns no value. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99. .SH NOTE diff --git a/man3/rand.3 b/man3/rand.3 index 933eba7be3..ef27552fbd 100644 --- a/man3/rand.3 +++ b/man3/rand.3 @@ -49,15 +49,24 @@ rand, rand_r, srand \- pseudo-random number generator .BI "void srand(unsigned int " seed ); .fi .SH DESCRIPTION -The \fBrand\fP() function returns a pseudo-random integer between 0 +The +.BR rand () +function returns a pseudo-random integer between 0 and \fBRAND_MAX\fR. .PP -The \fBsrand\fP() function sets its argument as the seed for a new -sequence of pseudo-random integers to be returned by \fBrand\fP(). -These sequences are repeatable by calling \fBsrand\fP() with the same +The +.BR srand () +function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by +.BR rand (). +These sequences are repeatable by calling +.BR srand () +with the same seed value. .PP -If no seed value is provided, the \fBrand\fP() function is automatically +If no seed value is provided, the +.BR rand () +function is automatically seeded with a value of 1. .PP The function @@ -78,9 +87,15 @@ Try .BR drand48_r (3) instead. .SH "RETURN VALUE" -The \fBrand\fP() and \fBrand_r\fP() functions return a value +The +.BR rand () +and +.BR rand_r () +functions return a value between 0 and RAND_MAX. -The \fBsrand\fP() function returns no value. +The +.BR srand () +function returns no value. .SH EXAMPLE POSIX.1-2001 gives the following example of an implementation of .BR rand () @@ -102,8 +117,16 @@ possibly useful when one needs the same sequence on two different machines. } .fi .SH NOTES -The versions of \fBrand\fP() and \fBsrand\fP() in the Linux C Library use -the same random number generator as \fBrandom\fP() and \fBsrandom\fP(), so +The versions of +.BR rand () +and +.BR srand () +in the Linux C Library use +the same random number generator as +.BR random () +and +.BR srandom (), +so the lower-order bits should be as random as the higher-order bits. However, on older .BR rand () diff --git a/man3/random.3 b/man3/random.3 index f2ab23087e..5c2f4981ec 100644 --- a/man3/random.3 +++ b/man3/random.3 @@ -44,46 +44,76 @@ random, srandom, initstate, setstate \- random number generator .BI "char *setstate(char *" state ); .fi .SH DESCRIPTION -The \fBrandom\fP() function uses a non-linear additive feedback random +The +.BR random () +function uses a non-linear additive feedback random number generator employing a default table of size 31 long integers to return successive pseudo-random numbers in the range from 0 to \fBRAND_MAX\fR. The period of this random number generator is very large, approximately 16*((2**31)\-1). .PP -The \fBsrandom\fP() function sets its argument as the seed for a new -sequence of pseudo-random integers to be returned by \fBrandom\fP(). -These sequences are repeatable by calling \fBsrandom\fP() with the same +The +.BR srandom () +function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by +.BR random (). +These sequences are repeatable by calling +.BR srandom () +with the same seed value. -If no seed value is provided, the \fBrandom\fP() function +If no seed value is provided, the +.BR random () +function is automatically seeded with a value of 1. .PP -The \fBinitstate\fP() function allows a state array \fIstate\fP to -be initialized for use by \fBrandom\fP(). +The +.BR initstate () +function allows a state array \fIstate\fP to +be initialized for use by +.BR random (). The size of the state array -\fIn\fP is used by \fBinitstate\fP() to decide how sophisticated a +\fIn\fP is used by +.BR initstate () +to decide how sophisticated a random number generator it should use \(em the larger the state array, the better the random numbers will be. \fIseed\fP is the seed for the initialization, which specifies a starting point for the random number sequence, and provides for restarting at the same point. .PP -The \fBsetstate\fP() function changes the state array used by the -\fBrandom\fP() function. +The +.BR setstate () +function changes the state array used by the +.BR random () +function. The state array \fIstate\fP is used for -random number generation until the next call to \fBinitstate\fP() -or \fBsetstate\fP(). \fIstate\fP must first have been initialized -using \fBinitstate\fP() or be the result of a previous call of -\fBsetstate\fP(). +random number generation until the next call to +.BR initstate () +or +.BR setstate (). +\fIstate\fP must first have been initialized +using +.BR initstate () +or be the result of a previous call of +.BR setstate (). .SH "RETURN VALUE" -The \fBrandom\fP() function returns a value between 0 and RAND_MAX. -The \fBsrandom\fP() function returns no value. -The \fBinitstate\fP() -and \fBsetstate\fP() functions return a pointer to the previous state +The +.BR random () +function returns a value between 0 and RAND_MAX. +The +.BR srandom () +function returns no value. +The +.BR initstate () +and +.BR setstate () +functions return a pointer to the previous state array, or NULL on error. .SH ERRORS .TP .B EINVAL -A state array of less than 8 bytes was specified to \fBinitstate\fP(). +A state array of less than 8 bytes was specified to +.BR initstate (). .SH NOTES Current "optimal" values for the size of the state array \fIn\fP are 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to diff --git a/man3/readdir.3 b/man3/readdir.3 index 5e52f1d9ae..6003c70ba9 100644 --- a/man3/readdir.3 +++ b/man3/readdir.3 @@ -40,7 +40,9 @@ readdir \- read a directory .BI "struct dirent *readdir(DIR *" dir ); .fi .SH DESCRIPTION -The \fBreaddir\fP() function returns a pointer to a \fIdirent\fP structure +The +.BR readdir () +function returns a pointer to a \fIdirent\fP structure representing the next directory entry in the directory stream pointed to by \fIdir\fP. It returns NULL on reaching the end-of-file or if @@ -74,10 +76,16 @@ POSIX.1-2001 also documents the field as an XSI extension. .IR "Use of other fields will harm the portability of your programs" . .PP -The data returned by \fBreaddir\fP() may be overwritten by subsequent -calls to \fBreaddir\fP() for the same directory stream. +The data returned by +.BR readdir () +may be overwritten by subsequent +calls to +.BR readdir () +for the same directory stream. .SH "RETURN VALUE" -The \fBreaddir\fP() function returns a pointer to a +The +.BR readdir () +function returns a pointer to a .I dirent structure, or NULL if an error occurs or end-of-file is reached. diff --git a/man3/resolver.3 b/man3/resolver.3 index 01306e6b43..57ac009cd3 100644 --- a/man3/resolver.3 +++ b/man3/resolver.3 @@ -85,44 +85,65 @@ Link with \-lresolv. These functions make queries to and interpret the responses from Internet domain name servers. .PP -The \fBres_init\fP() function reads the configuration files (see +The +.BR res_init () +function reads the configuration files (see resolv.conf(5)) to get the default domain name, search order and name server address(es). If no server is given, the local host is tried. If no domain is given, that associated with the local host is used. It can be overridden with the environment variable LOCALDOMAIN. -\fBres_init\fP() is normally executed by the first call to one of the +.BR res_init () +is normally executed by the first call to one of the other functions. .PP -The \fBres_query\fP() function queries the name server for the +The +.BR res_query () +function queries the name server for the fully-qualified domain name \fIname\fP of specified \fItype\fP and \fIclass\fP. The reply is left in the buffer \fIanswer\fP of length \fIanslen\fP supplied by the caller. .PP -The \fBres_search\fP() function makes a query and waits for the response -like \fBres_query\fP(), but in addition implements the default and search +The +.BR res_search () +function makes a query and waits for the response +like +.BR res_query (), +but in addition implements the default and search rules controlled by RES_DEFNAMES and RES_DNSRCH (see description of \fI_res\fP options below). .PP -The \fBres_querydomain\fP() function makes a query using \fBres_query\fP() +The +.BR res_querydomain () +function makes a query using +.BR res_query () on the concatenation of \fIname\fP and \fIdomain\fP. .PP -The following functions are lower-level routines used by \fBres_query\fP(). +The following functions are lower-level routines used by +.BR res_query (). .PP -The \fBres_mkquery\fP() function constructs a query message in \fIbuf\fP +The +.BR res_mkquery () +function constructs a query message in \fIbuf\fP of length \fIbuflen\fP for the domain name \fIdname\fP. The query type \fIop\fP is usually QUERY, but can be any of the types defined in \fI<arpa/nameser.h>\fP. \fInewrr\fP is currently unused. .PP -The \fBres_send\fP() function sends a pre-formatted query given in +The +.BR res_send () +function sends a pre-formatted query given in \fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP which is of length \fIanslen\fP. -It will call \fBres_init\fP(), if it +It will call +.BR res_init (), +if it has not already been called. .PP -The \fBdn_comp\fP() function compresses the domain name \fIexp_dn\fP +The +.BR dn_comp () +function compresses the domain name \fIexp_dn\fP and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP. The compression uses an array of pointers \fIdnptrs\fP to previously compressed names in the current message. @@ -149,13 +170,17 @@ This field can contain the bitwise ``or'' of the following options: .TP .B RES_INIT -True if \fBres_init\fP() has been called. +True if +.BR res_init () +has been called. .TP .B RES_DEBUG Print debugging messages. .TP .B RES_AAONLY -Accept authoritative answers only. \fBres_send\fP() continues until +Accept authoritative answers only. +.BR res_send () +continues until it fins an authoritative answer or returns an error. [Not currently implemented]. .TP @@ -173,11 +198,14 @@ implemented]. .B RES_RECURSE Set the recursion desired bit in queries. Recursion is carried out -by the domain name server, not by \fBres_send\fP(). +by the domain name server, not by +.BR res_send (). [Enabled by default]. .TP .B RES_DEFNAMES -If set, \fBres_search\fP() will append the default domain name to +If set, +.BR res_search () +will append the default domain name to single component names, ie. those that do not contain a dot. [Enabled by default]. .TP @@ -185,20 +213,34 @@ single component names, ie. those that do not contain a dot. Used with RES_USEVC to keep the TCP connection open between queries. .TP .B RES_DNSRCH -If set, \fBres_search\fP() will search for host names in the current +If set, +.BR res_search () +will search for host names in the current domain and in parent domains. This option is used by .BR gethostbyname (3). [Enabled by default]. .SH "RETURN VALUE" -The \fBres_init\fP() function returns 0 on success, or \-1 if an error +The +.BR res_init () +function returns 0 on success, or \-1 if an error occurs. .PP -The \fBres_query\fP(), \fBres_search\fP(), \fBres_querydomain\fP(), -\fBres_mkquery\fP() and \fBres_send\fP() functions return the length +The +.BR res_query (), +.BR res_search (), +.BR res_querydomain (), +.BR res_mkquery () +and +.BR res_send () +functions return the length of the response, or \-1 if an error occurs. .PP -The \fBdn_comp\fP() and \fBdn_expand\fP() functions return the length +The +.BR dn_comp () +and +.BR dn_expand () +functions return the length of the compressed name, or \-1 if an error occurs. .SH FILES .nf diff --git a/man3/rewinddir.3 b/man3/rewinddir.3 index ea2a02c83e..ed61092631 100644 --- a/man3/rewinddir.3 +++ b/man3/rewinddir.3 @@ -38,10 +38,14 @@ rewinddir \- reset directory stream .BI "void rewinddir(DIR *" dir ); .fi .SH DESCRIPTION -The \fBrewinddir\fP() function resets the position of the directory +The +.BR rewinddir () +function resets the position of the directory stream \fIdir\fP to the beginning of the directory. .SH "RETURN VALUE" -The \fBrewinddir\fP() function returns no value. +The +.BR rewinddir () +function returns no value. .SH "CONFORMING TO" SVr4, 4.3BSD, POSIX.1-2001. .SH "SEE ALSO" diff --git a/man3/rpmatch.3 b/man3/rpmatch.3 index 6592e04343..dd18ca8be8 100644 --- a/man3/rpmatch.3 +++ b/man3/rpmatch.3 @@ -35,16 +35,21 @@ rpmatch \- determine if the answer to a question is affirmative or negative \fBint rpmatch(const char *\fIresponse\fB); .fi .SH DESCRIPTION -\fBrpmatch\fP() handles a user response to yes or no questions, with +.BR rpmatch () +handles a user response to yes or no questions, with support for internationalization. \fIresponse\fP should be a null-terminated string containing a -user-supplied response, perhaps obtained with \fBfgets\fP(3) or -\fBgetline\fP(3). +user-supplied response, perhaps obtained with +.BR fgets (3) +or +.BR getline (3). The user's language preference is taken into account per the environment variables \fBLANG\fP, \fBLC_MESSAGES\fP, and \fBLC_ALL\fP, -if the program has called \fBsetlocale\fP(3) to effect their changes. +if the program has called +.BR setlocale (3) +to effect their changes. Regardless of the locale, responses matching \fB^[Yy]\fP are always accepted as affirmative, and those matching \fB^[Nn]\fP are always @@ -52,7 +57,8 @@ accepted as negative. .SH "RETURN VALUE" After examining .IR response , -\fBrpmatch\fP() returns 0 for a recognized negative response ("no"), 1 +.BR rpmatch () +returns 0 for a recognized negative response ("no"), 1 for a recognized positive response ("yes"), and \-1 when the value of \fIresponse\fP is unrecognized. .SH ERRORS @@ -60,23 +66,31 @@ A return value of \-1 may indicate either an invalid input, or some other error. It is incorrect to only test if the return value is nonzero. -\fBrpmatch\fP() can fail for any of the reasons that -\fBregcomp\fP(3) or \fBregexec\fP(3) can fail; the cause of the error +.BR rpmatch () +can fail for any of the reasons that +.BR regcomp (3) +or +.BR regexec (3) +can fail; the cause of the error is not available from \fIerrno\fP or anywhere else, but indicates a failure of the regex engine (but this case is indistinguishable from that of an unrecognized value of \fIresponse\fP). .SH "CONFORMING TO" -\fBrpmatch\fP() is not required by any standard, but +.BR rpmatch () +is not required by any standard, but is available on a few other systems. .\" It is available on at least AIX 5.1 and FreeBSD 6.0. .SH BUGS -The \fBrpmatch\fP() implementation looks at only the first character +The +.BR rpmatch () +implementation looks at only the first character of \fIresponse\fP. As a consequence, "nyes" returns 0, and "ynever; not in a million years" returns 1. It would be preferable to accept input strings much more strictly, for example (using the extended regular -expression notation described in \fBregex\fP(7)): +expression notation described in +.BR regex (7)): \fB^([yY]|yes|YES)$\fP and \fB^([nN]|no|NO)$\fP. .SH EXAMPLE The following program displays the results when diff --git a/man3/scandir.3 b/man3/scandir.3 index 0c1b56b839..9a350adf82 100644 --- a/man3/scandir.3 +++ b/man3/scandir.3 @@ -49,13 +49,19 @@ scandir, alphasort, versionsort \- scan a directory for matching entries .BI "int versionsort(const void *" a ", const void *" b ); .fi .SH DESCRIPTION -The \fBscandir\fP() function scans the directory \fIdir\fP, calling +The +.BR scandir () +function scans the directory \fIdir\fP, calling \fIfilter\fP() on each directory entry. Entries for which \fIfilter\fP() returns non-zero are stored in strings allocated via -\fBmalloc\fP(3), sorted using \fBqsort\fP(3) with the comparison +.BR malloc (3), +sorted using +.BR qsort (3) +with the comparison function \fIcompar\fP(), and collected in array \fInamelist\fP -which is allocated via \fBmalloc\fP(3). +which is allocated via +.BR malloc (3). If \fIfilter\fP is NULL, all entries are selected. .LP The @@ -70,7 +76,9 @@ the latter using .BR strverscmp (3) on the strings \fI(*a)\->d_name\fP and \fI(*b)\->d_name\fP. .SH "RETURN VALUE" -The \fBscandir\fP() function returns the number of directory entries +The +.BR scandir () +function returns the number of directory entries selected or \-1 if an error occurs. .PP The diff --git a/man3/seekdir.3 b/man3/seekdir.3 index 0f53fc39cc..c0cef79c27 100644 --- a/man3/seekdir.3 +++ b/man3/seekdir.3 @@ -36,11 +36,19 @@ stream. .BI "void seekdir(DIR *" dir ", off_t " offset ); .fi .SH DESCRIPTION -The \fBseekdir\fP() function sets the location in the directory stream -from which the next \fBreaddir\fP(2) call will start. -\fBseekdir\fP() should be used with an offset returned by \fBtelldir\fP(3). +The +.BR seekdir () +function sets the location in the directory stream +from which the next +.BR readdir (2) +call will start. +.BR seekdir () +should be used with an offset returned by +.BR telldir (3). .SH "RETURN VALUE" -The \fBseekdir\fP() function returns no value. +The +.BR seekdir () +function returns no value. .SH "CONFORMING TO" 4.3BSD, POSIX.1-2001. .SH "SEE ALSO" diff --git a/man3/setenv.3 b/man3/setenv.3 index 46cac244e7..9596a9dab0 100644 --- a/man3/setenv.3 +++ b/man3/setenv.3 @@ -43,7 +43,9 @@ setenv \- change or add an environment variable .BI "int unsetenv(const char *" name ); .fi .SH DESCRIPTION -The \fBsetenv\fP() function adds the variable \fIname\fP to the +The +.BR setenv () +function adds the variable \fIname\fP to the environment with the value \fIvalue\fP, if \fIname\fP does not already exist. If \fIname\fP does exist in the environment, then @@ -51,12 +53,18 @@ its value is changed to \fIvalue\fP if \fIoverwrite\fP is non-zero; if \fIoverwrite\fP is zero, then the value of \fIname\fP is not changed. .PP -The \fBunsetenv\fP() function deletes the variable \fIname\fP from +The +.BR unsetenv () +function deletes the variable \fIname\fP from the environment. .SH "RETURN VALUE" -The \fBsetenv\fP() function returns zero on success, or \-1 if there +The +.BR setenv () +function returns zero on success, or \-1 if there was insufficient space in the environment. -The \fBunsetenv\fP() function returns zero on success, +The +.BR unsetenv () +function returns zero on success, or \-1 on error, with .I errno set to indicate the cause of the error. @@ -68,7 +76,9 @@ contained an '=' character. .SH "CONFORMING TO" 4.3BSD, POSIX.1-2001. .SH "NOTES" -Prior to glibc 2.2.2, \fBunsetenv\fP() was prototyped +Prior to glibc 2.2.2, +.BR unsetenv () +was prototyped as returning \fIvoid\fP; more recent glibc versions follow the POSIX.1-2001-compliant prototype shown in the SYNOPSIS. .SH BUGS diff --git a/man3/setjmp.3 b/man3/setjmp.3 index 3be52b49a2..21d3f2d495 100644 --- a/man3/setjmp.3 +++ b/man3/setjmp.3 @@ -36,32 +36,56 @@ setjmp, sigsetjmp \- save stack context for non-local goto .fi .ad b .SH DESCRIPTION -\fBsetjmp\fP() and \fBlongjmp\fP(3) are useful for dealing with errors +.BR setjmp () +and +.BR longjmp (3) +are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. -\fBsetjmp\fP() saves the stack context/environment in \fIenv\fP for -later use by \fBlongjmp\fP(3). +.BR setjmp () +saves the stack context/environment in \fIenv\fP for +later use by +.BR longjmp (3). The stack context will be invalidated -if the function which called \fBsetjmp\fP() returns. +if the function which called +.BR setjmp () +returns. .P -\fBsigsetjmp\fP() is similar to \fBsetjmp\fP(). +.BR sigsetjmp () +is similar to +.BR setjmp (). If \fIsavesigs\fP is non-zero, the set of blocked signals is saved in \fIenv\fP and will be restored -if a \fBsiglongjmp\fP(3) is later performed with this \fIenv\fP. +if a +.BR siglongjmp (3) +is later performed with this \fIenv\fP. .SH "RETURN VALUE" -\fBsetjmp\fP() and \fBsigsetjmp\fP() return 0 if returning directly, and -non-zero when returning from \fBlongjmp\fP(3) using the saved context. +.BR setjmp () +and +.BR sigsetjmp () +return 0 if returning directly, and +non-zero when returning from +.BR longjmp (3) +using the saved context. .SH "CONFORMING TO" -C89, C99, and POSIX.1-2001 specify \fBsetjmp\fP(). -POSIX.1-2001 specifies \fBsigsetjmp\fP(). +C89, C99, and POSIX.1-2001 specify +.BR setjmp (). +POSIX.1-2001 specifies +.BR sigsetjmp (). .SH NOTES -POSIX does not specify whether \fBsetjmp\fP() will save the +POSIX does not specify whether +.BR setjmp () +will save the signal context. (In System V it will not. In 4.3BSD it will, and there is a function \fB_setjmp\fP that will not.) -If you want to save signal masks, use \fBsigsetjmp\fP(). +If you want to save signal masks, use +.BR sigsetjmp (). .P -\fBsetjmp\fP() and \fBsigsetjmp\fP() make programs hard to understand +.BR setjmp () +and +.BR sigsetjmp () +make programs hard to understand and maintain. If possible an alternative should be used. .SH "SEE ALSO" diff --git a/man3/siginterrupt.3 b/man3/siginterrupt.3 index 322704b469..a62d9ee99b 100644 --- a/man3/siginterrupt.3 +++ b/man3/siginterrupt.3 @@ -36,14 +36,17 @@ siginterrupt \- allow signals to interrupt system calls .BI "int siginterrupt(int " sig ", int " flag ); .fi .SH DESCRIPTION -The \fBsiginterrupt\fP() function changes the restart behaviour when +The +.BR siginterrupt () +function changes the restart behaviour when a system call is interrupted by the signal \fIsig\fP. If the \fIflag\fP argument is false (0), then system calls will be restarted if interrupted by the specified signal \fIsig\fP. This is the default behaviour in Linux. However, when a new signal handler is specified with the -\fBsignal\fP(2) function, the system call is interrupted by default. +.BR signal (2) +function, the system call is interrupted by default. .PP If the \fIflags\fP argument is true (1) and no data has been transferred, then a system call interrupted by the signal \fIsig\fP will return \-1 @@ -53,7 +56,9 @@ If the \fIflags\fP argument is true (1) and data transfer has started, then the system call will be interrupted and will return the actual amount of data transferred. .SH "RETURN VALUE" -The \fBsiginterrupt\fP() function returns 0 on success, or \-1 if the +The +.BR siginterrupt () +function returns 0 on success, or \-1 if the signal number \fIsig\fP is invalid. .SH ERRORS .TP diff --git a/man3/sin.3 b/man3/sin.3 index 919c121457..84ed8b483e 100644 --- a/man3/sin.3 +++ b/man3/sin.3 @@ -43,10 +43,14 @@ sin, sinf, sinl \- sine function .sp Link with \-lm. .SH DESCRIPTION -The \fBsin\fP() function returns the sine of \fIx\fP, where \fIx\fP is +The +.BR sin () +function returns the sine of \fIx\fP, where \fIx\fP is given in radians. .SH "RETURN VALUE" -The \fBsin\fP() function returns a value between \-1 and 1. +The +.BR sin () +function returns a value between \-1 and 1. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. The diff --git a/man3/sinh.3 b/man3/sinh.3 index 39e67d0013..9cd607aa1a 100644 --- a/man3/sinh.3 +++ b/man3/sinh.3 @@ -45,7 +45,9 @@ sinh, sinhf, sinhl \- hyperbolic sine function .sp Link with \-lm. .SH DESCRIPTION -The \fBsinh\fP() function returns the hyperbolic sine of \fIx\fP, which +The +.BR sinh () +function returns the hyperbolic sine of \fIx\fP, which is defined mathematically as (exp(x) \- exp(\-x)) / 2. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. diff --git a/man3/sqrt.3 b/man3/sqrt.3 index d0128c496f..964ac7c457 100644 --- a/man3/sqrt.3 +++ b/man3/sqrt.3 @@ -43,7 +43,9 @@ sqrt, sqrtf, sqrtl \- square root function .sp Link with \-lm. .SH DESCRIPTION -The \fBsqrt\fP() function returns the non-negative square root of \fIx\fP. +The +.BR sqrt () +function returns the non-negative square root of \fIx\fP. It fails and sets \fIerrno\fP to EDOM, if \fIx\fP is negative. .SH ERRORS .TP diff --git a/man3/stpcpy.3 b/man3/stpcpy.3 index 51cfedbf43..472d3b4faf 100644 --- a/man3/stpcpy.3 +++ b/man3/stpcpy.3 @@ -34,17 +34,22 @@ stpcpy \- copy a string returning a pointer to its end .BI "char *stpcpy(char *" dest ", const char *" src ); .fi .SH DESCRIPTION -The \fBstpcpy\fP() function copies the string pointed to by \fIsrc\fP +The +.BR stpcpy () +function copies the string pointed to by \fIsrc\fP (including the terminating `\\0' character) to the array pointed to by \fIdest\fP. The strings may not overlap, and the destination string \fIdest\fP must be large enough to receive the copy. .SH "RETURN VALUE" -\fBstpcpy\fP() returns a pointer to the \fBend\fP of the string +.BR stpcpy () +returns a pointer to the \fBend\fP of the string \fIdest\fP (that is, the address of the terminating null byte) rather than the beginning. .SH EXAMPLE -For example, this program uses \fBstpcpy\fP() to concatenate \fBfoo\fP and +For example, this program uses +.BR stpcpy () +to concatenate \fBfoo\fP and \fBbar\fP to produce \fBfoobar\fP, which it then prints. .nf diff --git a/man3/stpncpy.3 b/man3/stpncpy.3 index 47cb76490b..1ebe669a97 100644 --- a/man3/stpncpy.3 +++ b/man3/stpncpy.3 @@ -21,7 +21,9 @@ stpncpy \- copy a fixed-size string, returning a pointer to its end .BI "char *stpncpy(char *" dest ", const char *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBstpncpy\fP() function copies at most \fIn\fP characters from the string +The +.BR stpncpy () +function copies at most \fIn\fP characters from the string pointed to by \fIsrc\fP, including the terminating '\\0' character, to the array pointed to by \fIdest\fP. Exactly \fIn\fP characters are written at @@ -37,7 +39,8 @@ The strings may not overlap. The programmer must ensure that there is room for at least \fIn\fP characters at \fIdest\fP. .SH "RETURN VALUE" -\fBstpncpy\fP() returns a pointer to the terminating null +.BR stpncpy () +returns a pointer to the terminating null in \fIdest\fP, or, if \fIdest\fP is not null-terminated, \fIdest + n\fP. .SH "CONFORMING TO" diff --git a/man3/strcasecmp.3 b/man3/strcasecmp.3 index 5e7327398c..5acb947318 100644 --- a/man3/strcasecmp.3 +++ b/man3/strcasecmp.3 @@ -37,16 +37,24 @@ strcasecmp, strncasecmp \- compare two strings ignoring case .BI "int strncasecmp(const char *" s1 ", const char *" s2 ", size_t " n ); .fi .SH DESCRIPTION -The \fBstrcasecmp\fP() function compares the two strings \fIs1\fP and +The +.BR strcasecmp () +function compares the two strings \fIs1\fP and \fIs2\fP, ignoring the case of the characters. It returns an integer less than, equal to, or greater than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP. .PP -The \fBstrncasecmp\fP() function is similar, except it only compares +The +.BR strncasecmp () +function is similar, except it only compares the first \fIn\fP characters of \fIs1\fP. .SH "RETURN VALUE" -The \fBstrcasecmp\fP() and \fBstrncasecmp\fP() functions return +The +.BR strcasecmp () +and +.BR strncasecmp () +functions return an integer less than, equal to, or greater than zero if \fIs1\fP (or the first \fIn\fP bytes thereof) is found, respectively, to be less than, to match, or be greater than \fIs2\fP. diff --git a/man3/strcat.3 b/man3/strcat.3 index 01b3a4b3a0..f0791e1319 100644 --- a/man3/strcat.3 +++ b/man3/strcat.3 @@ -37,18 +37,26 @@ strcat, strncat \- concatenate two strings .BI "char *strncat(char *" dest ", const char *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBstrcat\fP() function appends the \fIsrc\fP string to the +The +.BR strcat () +function appends the \fIsrc\fP string to the \fIdest\fP string overwriting the `\\0' character at the end of \fIdest\fP, and then adds a terminating `\\0' character. The strings may not overlap, and the \fIdest\fP string must have enough space for the result. .PP -The \fBstrncat\fP() function is similar, except that it will use +The +.BR strncat () +function is similar, except that it will use at most \fIn\fP characters from \fIsrc\fP. Since the result is always terminated with `\\0', at most \fIn\fP+1 characters are written. .SH "RETURN VALUE" -The \fBstrcat\fP() and \fBstrncat\fP() functions return a pointer +The +.BR strcat () +and +.BR strncat () +functions return a pointer to the resulting string \fIdest\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99. diff --git a/man3/strchr.3 b/man3/strchr.3 index 6b9e7be5ea..45d84bfa2f 100644 --- a/man3/strchr.3 +++ b/man3/strchr.3 @@ -45,13 +45,20 @@ strchr, strrchr, strchrnul \- locate character in string .BI "char *strchrnul(const char *" s ", int " c ); .fi .SH DESCRIPTION -The \fBstrchr\fP() function returns a pointer to the first occurrence +The +.BR strchr () +function returns a pointer to the first occurrence of the character \fIc\fP in the string \fIs\fP. .PP -The \fBstrrchr\fP() function returns a pointer to the last occurrence +The +.BR strrchr () +function returns a pointer to the last occurrence of the character \fIc\fP in the string \fIs\fP. .PP -The \fBstrchrnul\fP() function is like \fBstrchr\fP() +The +.BR strchrnul () +function is like +.BR strchr () except that if \fIc\fP is not found in \fIs\fP, then it returns a pointer to the null byte at the end of \fIs\fP, rather than NULL. @@ -59,17 +66,27 @@ at the end of \fIs\fP, rather than NULL. Here "character" means "byte"; these functions do not work with wide or multi-byte characters. .SH "RETURN VALUE" -The \fBstrchr\fP() and \fBstrrchr\fP() functions return a pointer to +The +.BR strchr () +and +.BR strrchr () +functions return a pointer to the matched character or NULL if the character is not found. -The \fBstrchrnul\fP() function returns a pointer to +The +.BR strchrnul () +function returns a pointer to the matched character, or a pointer to the null byte at the end of \fIs\fP (i.e., \fIs+strlen(s)\fP) if the character is not found. .SH "CONFORMING TO" -\fBstrchr\fP() and \fBstrrchr\fP() are in SVr4, 4.3BSD, C89, C99. -\fBstrchrnul\fP() is a GNU extension. +.BR strchr () +and +.BR strrchr () +are in SVr4, 4.3BSD, C89, C99. +.BR strchrnul () +is a GNU extension. .SH "SEE ALSO" .BR index (3), .BR memchr (3), diff --git a/man3/strcmp.3 b/man3/strcmp.3 index 6ddabb4593..0304a855b4 100644 --- a/man3/strcmp.3 +++ b/man3/strcmp.3 @@ -39,16 +39,24 @@ strcmp, strncmp \- compare two strings .BI "int strncmp(const char *" s1 ", const char *" s2 ", size_t " n ); .fi .SH DESCRIPTION -The \fBstrcmp\fP() function compares the two strings \fIs1\fP and +The +.BR strcmp () +function compares the two strings \fIs1\fP and \fIs2\fP. It returns an integer less than, equal to, or greater than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP. .PP -The \fBstrncmp\fP() function is similar, except it only compares +The +.BR strncmp () +function is similar, except it only compares the first (at most) \fIn\fP characters of \fIs1\fP and \fIs2\fP. .SH "RETURN VALUE" -The \fBstrcmp\fP() and \fBstrncmp\fP() functions return an integer +The +.BR strcmp () +and +.BR strncmp () +functions return an integer less than, equal to, or greater than zero if \fIs1\fP (or the first \fIn\fP bytes thereof) is found, respectively, to be less than, to match, or be greater than \fIs2\fP. diff --git a/man3/strcoll.3 b/man3/strcoll.3 index 47d5ad38b5..5d609609e4 100644 --- a/man3/strcoll.3 +++ b/man3/strcoll.3 @@ -35,24 +35,31 @@ strcoll \- compare two strings using the current locale .BI "int strcoll(const char *" s1 ", const char *" s2 ); .fi .SH DESCRIPTION -The \fBstrcoll\fP() function compares the two strings \fIs1\fP and +The +.BR strcoll () +function compares the two strings \fIs1\fP and \fIs2\fP. It returns an integer less than, equal to, or greater than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP. The comparison is based on strings interpreted as appropriate for the program's current locale -for category \fILC_COLLATE\fP. (See \fBsetlocale\fP(3)). +for category \fILC_COLLATE\fP. (See +.BR setlocale (3)). .SH "RETURN VALUE" -The \fBstrcoll\fP() function returns an integer less than, equal to, +The +.BR strcoll () +function returns an integer less than, equal to, or greater than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP, when both are interpreted as appropriate for the current locale. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99. .SH NOTES -In the \fI"POSIX"\fP or \fI"C"\fP locales \fBstrcoll\fP() is equivalent to -\fBstrcmp\fP(3). +In the \fI"POSIX"\fP or \fI"C"\fP locales +.BR strcoll () +is equivalent to +.BR strcmp (3). .SH "SEE ALSO" .BR bcmp (3), .BR memcmp (3), diff --git a/man3/strcpy.3 b/man3/strcpy.3 index 6429afafe4..ad494e7114 100644 --- a/man3/strcpy.3 +++ b/man3/strcpy.3 @@ -40,13 +40,17 @@ strcpy, strncpy \- copy a string .BI "char *strncpy(char *" dest ", const char *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBstrcpy\fP() function copies the string pointed to by \fIsrc\fP +The +.BR strcpy () +function copies the string pointed to by \fIsrc\fP (including the terminating `\\0' character) to the array pointed to by \fIdest\fP. The strings may not overlap, and the destination string \fIdest\fP must be large enough to receive the copy. .PP -The \fBstrncpy\fP() function is similar, except that not more than +The +.BR strncpy () +function is similar, except that not more than \fIn\fP bytes of \fIsrc\fP are copied. Thus, if there is no null byte among the first \fIn\fP bytes of \fIsrc\fP, the result will not be @@ -60,10 +64,16 @@ the remainder of .I dest will be padded with null bytes. .SH "RETURN VALUE" -The \fBstrcpy\fP() and \fBstrncpy\fP() functions return a pointer to +The +.BR strcpy () +and +.BR strncpy () +functions return a pointer to the destination string \fIdest\fP. .SH BUGS -If the destination string of a \fBstrcpy\fP() is not large enough +If the destination string of a +.BR strcpy () +is not large enough (that is, if the programmer was stupid/lazy, and failed to check the size before copying) then anything might happen. Overflowing fixed length strings is a favourite cracker technique. diff --git a/man3/strdup.3 b/man3/strdup.3 index e232cd51d0..2ee0d8f36d 100644 --- a/man3/strdup.3 +++ b/man3/strdup.3 @@ -46,22 +46,36 @@ strdup, strndup, strdupa, strndupa \- duplicate a string .BI "char *strndupa(const char *" s ", size_t " n ); .fi .SH DESCRIPTION -The \fBstrdup\fP() function returns a pointer to a new string which +The +.BR strdup () +function returns a pointer to a new string which is a duplicate of the string \fIs\fP. Memory for the new string is -obtained with \fBmalloc\fP(3), and can be freed with \fBfree\fP(3). +obtained with +.BR malloc (3), +and can be freed with +.BR free (3). -The \fBstrndup\fP() function is similar, but only copies at most +The +.BR strndup () +function is similar, but only copies at most \fIn\fP characters. If \fIs\fP is longer than \fIn\fP, only \fIn\fP characters are copied, and a terminating null byte ('\\0') is added. -\fBstrdupa\fP() and \fBstrndupa\fP() are similar, but use \fBalloca(3)\fP +.BR strdupa () +and +.BR strndupa () +are similar, but use +.BR alloca (3) to allocate the buffer. They are only available when using the GNU -GCC suite, and suffer from the same limitations described in \fBalloca(3)\fP. +GCC suite, and suffer from the same limitations described in +.BR alloca (3). .SH "RETURN VALUE" -The \fBstrdup\fP() function returns a pointer to the duplicated +The +.BR strdup () +function returns a pointer to the duplicated string, or NULL if insufficient memory was available. .SH ERRORS .TP @@ -71,7 +85,11 @@ Insufficient memory available to allocate duplicate string. .\" 4.3BSD-Reno, not (first) 4.3BSD. .BR strdup () conforms to SVr4, 4.3BSD, POSIX.1-2001. -\fBstrndup\fP(), \fBstrdupa\fP(), and \fBstrndupa\fP() are GNU extensions. +.BR strndup (), +.BR strdupa (), +and +.BR strndupa () +are GNU extensions. .SH "SEE ALSO" .BR alloca (3), .BR calloc (3), diff --git a/man3/strerror.3 b/man3/strerror.3 index 5d9098e335..f21300e2e6 100644 --- a/man3/strerror.3 +++ b/man3/strerror.3 @@ -53,14 +53,23 @@ strerror, strerror_r \- return string describing error number /* XSI-compliant strerror_r() */ .fi .SH DESCRIPTION -The \fBstrerror\fP() function returns a string describing the error +The +.BR strerror () +function returns a string describing the error code passed in the argument \fIerrnum\fP, possibly using the LC_MESSAGES part of the current locale to select the appropriate language. This string must not be modified by the application, but may be -modified by a subsequent call to \fBperror\fP(3) or \fBstrerror\fP(). +modified by a subsequent call to +.BR perror (3) +or +.BR strerror (). No library function will modify this string. -The \fBstrerror_r\fP() function is similar to \fBstrerror\fP(), but is +The +.BR strerror_r () +function is similar to +.BR strerror (), +but is thread safe. This function is available in two versions: an XSI-compliant version specified in POSIX.1-2001, @@ -94,11 +103,17 @@ bytes are stored (the string may be truncated if .I buflen is too small) and the string always includes a terminating null byte. .SH "RETURN VALUE" -The \fBstrerror\fP() and \fBstrerror_r\fP() functions return +The +.BR strerror () +and +.BR strerror_r () +functions return the appropriate error description string, or an "Unknown error nnn" message if the error number is unknown. -The XSI-compliant \fBstrerror_r\fP() function returns 0 on success; +The XSI-compliant +.BR strerror_r () +function returns 0 on success; on error, \-1 is returned and .I errno is set to indicate the error. @@ -112,8 +127,10 @@ is not a valid error number. .B ERANGE Insufficient storage was supplied to contain the error description string. .SH "CONFORMING TO" -\fBstrerror\fP() is specified by POSIX.1-2001, C89, C99. -\fBstrerror_r\fP() is specified by POSIX.1-2001. +.BR strerror () +is specified by POSIX.1-2001, C89, C99. +.BR strerror_r () +is specified by POSIX.1-2001. The GNU-specific .BR strerror_r () diff --git a/man3/strfmon.3 b/man3/strfmon.3 index f35c3feefb..9071cdf81e 100644 --- a/man3/strfmon.3 +++ b/man3/strfmon.3 @@ -29,7 +29,9 @@ strfmon \- convert monetary value to a string .BI "ssize_t strfmon(char *" s ", size_t " max ", const char *" format , .B "...);" .SH DESCRIPTION -The \fBstrfmon\fP() function formats the specified amounts +The +.BR strfmon () +function formats the specified amounts according to the format specification \fIformat\fP and places the result in the character array \fIs\fP of size \fImax\fP. .PP @@ -108,7 +110,9 @@ international currency format. One argument of type double is converted using the locale's national currency format. .SH "RETURN VALUE" -The \fBstrfmon\fP() function returns the number of characters placed +The +.BR strfmon () +function returns the number of characters placed in the array \fIs\fP, not including the terminating null byte, provided the string, including the terminating null byte, fits. Otherwise, it sets diff --git a/man3/strfry.3 b/man3/strfry.3 index 6ceb7a04a9..2e642f97b8 100644 --- a/man3/strfry.3 +++ b/man3/strfry.3 @@ -37,14 +37,22 @@ strfry \- randomize a string .BI "char *strfry(char *" string ); .fi .SH DESCRIPTION -The \fBstrfry\fP() function randomizes the contents of \fIstring\fP by -using \fBrand\fP(3) to randomly swap characters in the string. +The +.BR strfry () +function randomizes the contents of \fIstring\fP by +using +.BR rand (3) +to randomly swap characters in the string. The result is an anagram of \fIstring\fP. .SH "RETURN VALUE" -The \fBstrfry\fP() functions returns a pointer to the randomized +The +.BR strfry () +functions returns a pointer to the randomized string. .SH "CONFORMING TO" -The \fBstrfry\fP() function is unique to the +The +.BR strfry () +function is unique to the GNU C Library. .SH "SEE ALSO" .BR memfrob (3), diff --git a/man3/strftime.3 b/man3/strftime.3 index 66825796ee..30bb02eb3b 100644 --- a/man3/strftime.3 +++ b/man3/strftime.3 @@ -43,7 +43,9 @@ strftime \- format date and time .BI " const struct tm *" tm ); .fi .SH DESCRIPTION -The \fBstrftime\fP() function formats the broken-down time \fItm\fP +The +.BR strftime () +function formats the broken-down time \fItm\fP according to the format specification \fIformat\fP and places the result in the character array \fIs\fP of size \fImax\fP. .PP @@ -239,7 +241,9 @@ The broken-down time structure \fItm\fP is defined in \fI<time.h>\fP. See also .BR ctime (3). .SH "RETURN VALUE" -The \fBstrftime\fP() function returns the number of characters placed +The +.BR strftime () +function returns the number of characters placed in the array \fIs\fP, not including the terminating null byte, provided the string, including the terminating null byte, fits. Otherwise, it returns 0, and the contents of the array is undefined. diff --git a/man3/strlen.3 b/man3/strlen.3 index 606b7e9e56..dcd9e03364 100644 --- a/man3/strlen.3 +++ b/man3/strlen.3 @@ -35,10 +35,14 @@ strlen \- calculate the length of a string .BI "size_t strlen(const char *" s ); .fi .SH DESCRIPTION -The \fBstrlen\fP() function calculates the length of the string +The +.BR strlen () +function calculates the length of the string \fIs\fP, not including the terminating `\\0' character. .SH "RETURN VALUE" -The \fBstrlen\fP() function returns the number of characters in \fIs\fP. +The +.BR strlen () +function returns the number of characters in \fIs\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99. .SH "SEE ALSO" diff --git a/man3/strnlen.3 b/man3/strnlen.3 index 28d458d706..30ab8f9049 100644 --- a/man3/strnlen.3 +++ b/man3/strnlen.3 @@ -20,13 +20,19 @@ strnlen \- determine the length of a fixed-size string .BI "size_t strnlen(const char *" s ", size_t " maxlen ); .fi .SH DESCRIPTION -The \fBstrnlen\fP() function returns the number of characters in the string +The +.BR strnlen () +function returns the number of characters in the string pointed to by \fIs\fP, not including the terminating '\\0' character, but at most \fImaxlen\fP. -In doing this, \fBstrnlen\fP() looks only at the first +In doing this, +.BR strnlen () +looks only at the first \fImaxlen\fP characters at \fIs\fP and never beyond \fIs+maxlen\fP. .SH "RETURN VALUE" -The \fBstrnlen\fP() function returns \fIstrlen(s)\fP, if that is less than +The +.BR strnlen () +function returns \fIstrlen(s)\fP, if that is less than \fImaxlen\fP, or \fImaxlen\fP if there is no '\\0' character among the first \fImaxlen\fP characters pointed to by \fIs\fP. .SH "CONFORMING TO" diff --git a/man3/strpbrk.3 b/man3/strpbrk.3 index 6152c5f7fc..2e161fe7a2 100644 --- a/man3/strpbrk.3 +++ b/man3/strpbrk.3 @@ -35,10 +35,14 @@ strpbrk \- search a string for any of a set of characters .BI "char *strpbrk(const char *" s ", const char *" accept ); .fi .SH DESCRIPTION -The \fBstrpbrk\fP() function locates the first occurrence in the +The +.BR strpbrk () +function locates the first occurrence in the string \fIs\fP of any of the characters in the string \fIaccept\fP. .SH "RETURN VALUE" -The \fBstrpbrk\fP() function returns a pointer to the character in +The +.BR strpbrk () +function returns a pointer to the character in \fIs\fP that matches one of the characters in \fIaccept\fP, or NULL if no such character is found. .SH "CONFORMING TO" diff --git a/man3/strptime.3 b/man3/strptime.3 index 149f9ac8ba..a4e4ec389e 100644 --- a/man3/strptime.3 +++ b/man3/strptime.3 @@ -66,7 +66,9 @@ whitespace characters in the input string. There should be white\%space or other alphanumeric characters between any two field descriptors. .PP -The \fBstrptime\fP() function processes the input string from left +The +.BR strptime () +function processes the input string from left to right. Each of the three possible input elements (whitespace, literal, or format) are handled one after the other. @@ -264,14 +266,18 @@ value points right after the last consumed input character. In case the whole input string is consumed the return value points to the null byte at the end of the string. -If \fBstrptime\fP() fails to match all +If +.BR strptime () +fails to match all of the format string and therefore an error occurred the function returns NULL. .SH "CONFORMING TO" SUSv2, POSIX.1-2001. .SH EXAMPLE -The following example demonstrates the use of \fBstrptime\fP() -and \fBstrftime\fP(3). +The following example demonstrates the use of +.BR strptime () +and +.BR strftime (3). .sp .nf #include <stdio.h> diff --git a/man3/strsep.3 b/man3/strsep.3 index 624eca6c7e..0ffae734ad 100644 --- a/man3/strsep.3 +++ b/man3/strsep.3 @@ -38,7 +38,9 @@ strsep \- extract token from string .BI "char *strsep(char **" stringp ", const char *" delim ); .fi .SH DESCRIPTION -If *\fIstringp\fP is NULL, the \fBstrsep\fP() function returns NULL +If *\fIstringp\fP is NULL, the +.BR strsep () +function returns NULL and does nothing else. Otherwise, this function finds the first token in the string *\fIstringp\fP, where tokens @@ -49,14 +51,22 @@ and *\fIstringp\fP is updated to point past the token. In case no delimiter was found, the token is taken to be the entire string *\fIstringp\fP, and *\fIstringp\fP is made NULL. .SH "RETURN VALUE" -The \fBstrsep\fP() function returns a pointer to the token, +The +.BR strsep () +function returns a pointer to the token, that is, it returns the original value of *\fIstringp\fP. .SH NOTES -The \fBstrsep\fP() function was introduced as a replacement for -\fBstrtok\fP(3), since the latter cannot handle empty fields. -However, \fBstrtok\fP(3) conforms to C89/C99 and hence is more portable. +The +.BR strsep () +function was introduced as a replacement for +.BR strtok (3), +since the latter cannot handle empty fields. +However, +.BR strtok (3) +conforms to C89/C99 and hence is more portable. .SH BUGS -This function suffers from the same problems as \fBstrtok\fP(3). +This function suffers from the same problems as +.BR strtok (3). In particular, it modifies the original string. Avoid it. .SH "CONFORMING TO" diff --git a/man3/strsignal.3 b/man3/strsignal.3 index 529b0a3a3a..40184c3326 100644 --- a/man3/strsignal.3 +++ b/man3/strsignal.3 @@ -39,17 +39,24 @@ strsignal \- return string describing signal .BI "extern const char * const " sys_siglist []; .fi .SH DESCRIPTION -The \fBstrsignal\fP() function returns a string describing the signal +The +.BR strsignal () +function returns a string describing the signal number passed in the argument \fIsig\fP. The string can only be used -until the next call to \fBstrsignal\fP(). +until the next call to +.BR strsignal (). .PP The array \fIsys_siglist\fP holds the signal description strings indexed by signal number. -The \fBstrsignal\fP() function should be +The +.BR strsignal () +function should be used if possible instead of this array. .SH "RETURN VALUE" -The \fBstrsignal\fP() function returns the appropriate description +The +.BR strsignal () +function returns the appropriate description string, or an unknown signal message if the signal number is invalid. On some systems (but not on Linux), a NULL pointer may be returned instead for an invalid signal number. diff --git a/man3/strspn.3 b/man3/strspn.3 index 33430caec1..10cfa8801c 100644 --- a/man3/strspn.3 +++ b/man3/strspn.3 @@ -37,19 +37,27 @@ strspn, strcspn \- search a string for a set of characters .BI "size_t strcspn(const char *" s ", const char *" reject ); .fi .SH DESCRIPTION -The \fBstrspn\fP() function calculates the length of the initial +The +.BR strspn () +function calculates the length of the initial segment of \fIs\fP which consists entirely of characters in \fIaccept\fP. .PP -The \fBstrcspn\fP() function calculates the length of the initial +The +.BR strcspn () +function calculates the length of the initial segment of \fIs\fP which consists entirely of characters not in \fIreject\fP. .SH "RETURN VALUE" -The \fBstrspn\fP() function returns the number of characters in +The +.BR strspn () +function returns the number of characters in the initial segment of \fIs\fP which consist only of characters from \fIaccept\fP. .PP -The \fBstrcspn\fP() function returns the number of characters in +The +.BR strcspn () +function returns the number of characters in the initial segment of \fIs\fP which are not in the string \fIreject\fP. .SH "CONFORMING TO" diff --git a/man3/strstr.3 b/man3/strstr.3 index 87255199b1..061d46a482 100644 --- a/man3/strstr.3 +++ b/man3/strstr.3 @@ -44,23 +44,33 @@ strstr \- locate a substring .BI "char *strcasestr(const char *" haystack ", const char *" needle ); .fi .SH DESCRIPTION -The \fBstrstr\fP() function finds the first occurrence of the substring +The +.BR strstr () +function finds the first occurrence of the substring \fIneedle\fP in the string \fIhaystack\fP. The terminating \`\\0' characters are not compared. -The \fBstrcasestr\fP() function is like \fBstrstr\fP(), +The +.BR strcasestr () +function is like +.BR strstr (), but ignores the case of both arguments. .SH "RETURN VALUE" These functions return a pointer to the beginning of the substring, or NULL if the substring is not found. .SH BUGS Early versions of Linux libc (like 4.5.26) would not allow -an empty \fIneedle\fP argument for \fBstrstr\fP(). +an empty \fIneedle\fP argument for +.BR strstr (). Later versions (like 4.6.27) work correctly, and return \fIhaystack\fP when \fIneedle\fP is empty. .SH "CONFORMING TO" -The \fBstrstr\fP() function conforms to C89 and C99. -The \fBstrcasestr\fP() function is a non-standard extension. +The +.BR strstr () +function conforms to C89 and C99. +The +.BR strcasestr () +function is a non-standard extension. .SH "SEE ALSO" .BR index (3), .BR memchr (3), diff --git a/man3/strtod.3 b/man3/strtod.3 index 238196838e..e10bc9121d 100644 --- a/man3/strtod.3 +++ b/man3/strtod.3 @@ -71,7 +71,8 @@ and representation, respectively. The expected form of the (initial portion of the) string is -optional leading white space as recognized by \fBisspace\fP(3), +optional leading white space as recognized by +.BR isspace (3), an optional plus (``+'') or minus sign (``\-'') and then either (i) a decimal number, or (ii) a hexadecimal number, or (iii) an infinity, or (iv) a NAN (not-a-number). diff --git a/man3/strtok.3 b/man3/strtok.3 index 371e3d384d..1ba125d68a 100644 --- a/man3/strtok.3 +++ b/man3/strtok.3 @@ -37,8 +37,12 @@ strtok, strtok_r \- extract tokens from strings .BI "char *strtok_r(char *" str ", const char *" delim ", char **" saveptr ); .fi .SH DESCRIPTION -The \fBstrtok\fP() function parses a string into a sequence of tokens. -On the first call to \fBstrtok\fP() the string to be parsed should be +The +.BR strtok () +function parses a string into a sequence of tokens. +On the first call to +.BR strtok () +the string to be parsed should be specified in \fIstr\fP. In each subsequent call that should parse the same string, \fIstr\fP should be NULL. @@ -48,15 +52,20 @@ delimit the tokens in the parsed string. The caller may specify different strings in \fIdelim\fP in successive calls that parse the same string. -Each call to \fBstrtok\fP() returns a pointer to a +Each call to +.BR strtok () +returns a pointer to a null-terminated string containing the next token. This string does not include the delimiting character. -If no more tokens are found, \fBstrtok\fP() returns NULL. +If no more tokens are found, +.BR strtok () +returns NULL. A sequence of two or more contiguous delimiter characters in the parsed string is considered to be a single delimiter. Delimiter characters at the start or end of the string are ignored. -Put another way: the tokens returned by \fBstrtok\fP() +Put another way: the tokens returned by +.BR strtok () are always non-empty strings. The @@ -159,7 +168,11 @@ Use if this matters to you. .RE .SH "RETURN VALUE" -The \fBstrtok\fP() and \fBstrtok_r\fP() functions return a pointer to +The +.BR strtok () +and +.BR strtok_r () +functions return a pointer to the next token, or NULL if there are no more tokens. .SH "CONFORMING TO" .TP diff --git a/man3/strtol.3 b/man3/strtol.3 index 9945675f55..961efb07cf 100644 --- a/man3/strtol.3 +++ b/man3/strtol.3 @@ -40,7 +40,9 @@ strtol, strtoll, strtoq \- convert a string to a long integer .BI "strtoll(const char *" nptr ", char **" endptr ", int " base ); .fi .SH DESCRIPTION -The \fBstrtol\fP() function converts the initial part of the string +The +.BR strtol () +function converts the initial part of the string in \fInptr\fP to a long integer value according to the given \fIbase\fP, which must be between 2 and 36 inclusive, or be the special value 0. .PP @@ -62,10 +64,14 @@ valid digit in the given base. either upper or lower case represents 10, `B' represents 11, and so forth, with `Z' representing 35.) .PP -If \fIendptr\fP is not NULL, \fBstrtol\fP() stores the address of the +If \fIendptr\fP is not NULL, +.BR strtol () +stores the address of the first invalid character in \fI*endptr\fP. If there were no digits at -all, \fBstrtol\fP() stores the original value of \fInptr\fP in +all, +.BR strtol () +stores the original value of \fInptr\fP in \fI*endptr\fP (and returns 0). In particular, if \fI*nptr\fP is not `\\0' but \fI**endptr\fP is `\\0' on return, the entire string is valid. @@ -76,11 +82,15 @@ function works just like the .BR strtol () function but returns a long long integer value. .SH "RETURN VALUE" -The \fBstrtol\fP() function returns the result of the conversion, +The +.BR strtol () +function returns the result of the conversion, unless the value would underflow or overflow. If an underflow occurs, -\fBstrtol\fP() returns LONG_MIN. -If an overflow occurs, \fBstrtol\fP() +.BR strtol () +returns LONG_MIN. +If an overflow occurs, +.BR strtol () returns LONG_MAX. In both cases, \fIerrno\fP is set to ERANGE. Precisely the same holds for diff --git a/man3/strtoul.3 b/man3/strtoul.3 index 85b8bf8752..dc3627e522 100644 --- a/man3/strtoul.3 +++ b/man3/strtoul.3 @@ -42,7 +42,9 @@ strtoul, strtoull, strtouq \- convert a string to an unsigned long integer .BI "strtoull(const char *" nptr ", char **" endptr ", int " base ); .fi .SH DESCRIPTION -The \fBstrtoul\fP() function converts the initial part of the string +The +.BR strtoul () +function converts the initial part of the string in \fInptr\fP to an unsigned long integer value according to the given \fIbase\fP, which must be between 2 and 36 inclusive, or be the special value 0. @@ -64,10 +66,14 @@ valid digit in the given base. either upper or lower case represents 10, `B' represents 11, and so forth, with `Z' representing 35.) .PP -If \fIendptr\fP is not NULL, \fBstrtoul\fP() stores the address of the +If \fIendptr\fP is not NULL, +.BR strtoul () +stores the address of the first invalid character in \fI*endptr\fP. If there were no digits at -all, \fBstrtoul\fP() stores the original value of \fInptr\fP in +all, +.BR strtoul () +stores the original value of \fInptr\fP in \fI*endptr\fP (and returns 0). In particular, if \fI*nptr\fP is not `\\0' but \fI**endptr\fP is `\\0' on return, the entire string is valid. @@ -78,11 +84,15 @@ function works just like the .BR strtoul () function but returns an unsigned long long integer value. .SH "RETURN VALUE" -The \fBstrtoul\fP() function returns either the result of the conversion +The +.BR strtoul () +function returns either the result of the conversion or, if there was a leading minus sign, the negation of the result of the conversion represented as an unsigned value, unless the original (non-negated) value would overflow; in -the latter case, \fBstrtoul\fP() returns ULONG_MAX and sets the global +the latter case, +.BR strtoul () +returns ULONG_MAX and sets the global variable \fIerrno\fP to ERANGE. Precisely the same holds for .BR strtoull () diff --git a/man3/strverscmp.3 b/man3/strverscmp.3 index 033bd3c5a0..50d83808e8 100644 --- a/man3/strverscmp.3 +++ b/man3/strverscmp.3 @@ -75,7 +75,9 @@ come before digit strings with fewer leading zeroes). Thus, the ordering is .IR 000 ", " 00 ", " 01 ", " 010 ", " 09 ", " 0 ", " 1 ", " 9 ", " 10 . .SH "RETURN VALUE" -The \fBstrverscmp\fP() function returns an integer +The +.BR strverscmp () +function returns an integer less than, equal to, or greater than zero if \fIs1\fP is found, respectively, to be earlier than, equal to, or later than \fIs2\fP. diff --git a/man3/strxfrm.3 b/man3/strxfrm.3 index 8fb1487e50..059f13f1cb 100644 --- a/man3/strxfrm.3 +++ b/man3/strxfrm.3 @@ -35,16 +35,26 @@ strxfrm \- string transformation .BI "size_t strxfrm(char *" dest ", const char *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBstrxfrm\fP() function transforms the \fIsrc\fP string into a -form such that the result of \fBstrcmp\fP(3) on two strings that have -been transformed with \fBstrxfrm\fP() is the same as the result of -\fBstrcoll\fP(3) on the two strings before their transformation. +The +.BR strxfrm () +function transforms the \fIsrc\fP string into a +form such that the result of +.BR strcmp (3) +on two strings that have +been transformed with +.BR strxfrm () +is the same as the result of +.BR strcoll (3) +on the two strings before their transformation. The first \fIn\fP characters of the transformed string are placed in \fIdest\fP. The transformation is based on the program's current -locale for category \fILC_COLLATE\fP. (See \fBsetlocale\fP(3)). +locale for category \fILC_COLLATE\fP. (See +.BR setlocale (3)). .SH "RETURN VALUE" -The \fBstrxfrm\fP() function returns the number of bytes required to +The +.BR strxfrm () +function returns the number of bytes required to store the transformed string in \fIdest\fP excluding the terminating `\\0' character. If the value returned is \fIn\fP or more, the @@ -52,8 +62,11 @@ contents of \fIdest\fP are indeterminate. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99 .SH NOTES -In the \fI"POSIX"\fP or \fI"C"\fP locales \fBstrxfrm\fP() is equivalent to -copying the string with \fBstrncpy\fP(3). +In the \fI"POSIX"\fP or \fI"C"\fP locales +.BR strxfrm () +is equivalent to +copying the string with +.BR strncpy (3). .SH "SEE ALSO" .BR bcmp (3), .BR memcmp (3), diff --git a/man3/swab.3 b/man3/swab.3 index 3258ee5593..8bb004af3a 100644 --- a/man3/swab.3 +++ b/man3/swab.3 @@ -37,7 +37,9 @@ swab \- swap adjacent bytes .BI "void swab(const void *" from ", void *" to ", ssize_t " n ); .fi .SH DESCRIPTION -The \fBswab\fP() function copies \fIn\fP bytes from the array pointed +The +.BR swab () +function copies \fIn\fP bytes from the array pointed to by \fIfrom\fP to the array pointed to by \fIto\fP, exchanging adjacent even and odd bytes. This function is used to exchange data @@ -48,7 +50,9 @@ When \fIn\fP is positive and odd, it handles \fIn\fP\-1 bytes as above, and does something unspecified with the last byte. (In other words, \fIn\fP should be even.) .SH "RETURN VALUE" -The \fBswab\fP() function returns no value. +The +.BR swab () +function returns no value. .SH "CONFORMING TO" SVr4, 4.3BSD, POSIX.1-2001 .SH "SEE ALSO" diff --git a/man3/tan.3 b/man3/tan.3 index 590f52e3db..8a1e5c17ff 100644 --- a/man3/tan.3 +++ b/man3/tan.3 @@ -44,7 +44,9 @@ tan, tanf, tanl \- tangent function .sp Link with \-lm. .SH DESCRIPTION -The \fBtan\fP() function returns the tangent of \fIx\fP, where \fIx\fP is +The +.BR tan () +function returns the tangent of \fIx\fP, where \fIx\fP is given in radians. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. diff --git a/man3/tanh.3 b/man3/tanh.3 index ff23e1a90e..ef336274f1 100644 --- a/man3/tanh.3 +++ b/man3/tanh.3 @@ -44,7 +44,9 @@ tanh, tanhf, tanhl \- hyperbolic tangent function .sp Link with \-lm. .SH DESCRIPTION -The \fBtanh\fP() function returns the hyperbolic tangent of \fIx\fP, which +The +.BR tanh () +function returns the hyperbolic tangent of \fIx\fP, which is defined mathematically as sinh(x) / cosh(x). .SH "CONFORMING TO" SVr4, 4.3BSD, C89. diff --git a/man3/telldir.3 b/man3/telldir.3 index c12747cff9..9ccb5a9144 100644 --- a/man3/telldir.3 +++ b/man3/telldir.3 @@ -35,10 +35,14 @@ telldir \- return current location in directory stream .BI "off_t telldir(DIR *" dir ); .fi .SH DESCRIPTION -The \fBtelldir\fP() function returns the current location associated with +The +.BR telldir () +function returns the current location associated with the directory stream \fIdir\fP. .SH "RETURN VALUE" -On success, the \fBtelldir\fP() function returns the current location +On success, the +.BR telldir () +function returns the current location in the directory stream. On error, \-1 is returned, and .I errno diff --git a/man3/termios.3 b/man3/termios.3 index 5cdf543efe..c291694f7d 100644 --- a/man3/termios.3 +++ b/man3/termios.3 @@ -613,7 +613,8 @@ Because the timer is only started after the initial byte becomes available, at least one byte will be read. .SS "Raw mode" .LP -\fBcfmakeraw\fP() sets the terminal to something like the +.BR cfmakeraw () +sets the terminal to something like the "raw" mode of the old Version 7 terminal driver: input is available character by character, echoing is disabled, and all special processing of @@ -640,7 +641,8 @@ If \fIduration\fP is not zero, it sends zero-valued bits for some implementation-defined length of time. .LP If the terminal is not using asynchronous serial data transmission, -\fBtcsendbreak\fP() returns without taking any action. +.BR tcsendbreak () +returns without taking any action. .LP .BR tcdrain () waits until all output written to the object referred to by @@ -683,11 +685,13 @@ output is suspended. The baud rate functions are provided for getting and setting the values of the input and output baud rates in the \fItermios\fP structure. The new values do not take effect -until \fBtcsetattr\fP() is successfully called. +until +.BR tcsetattr () +is successfully called. Setting the speed to \fBB0\fP instructs the modem to "hang up". The actual bit rate corresponding to \fBB38400\fP may be altered with -\fBsetserial\fP(8). +.BR setserial (8). .LP The input and output baud rates are stored in the \fItermios\fP structure. @@ -780,7 +784,9 @@ where after the fourteen values B0, ..., B9600 one finds the two constants EXTA, EXTB ("External A" and "External B"). Many systems extend the list with much higher baud rates. .LP -The effect of a non-zero \fIduration\fP with \fBtcsendbreak\fP() varies. +The effect of a non-zero \fIduration\fP with +.BR tcsendbreak () +varies. SunOS specifies a break of .IB duration * N seconds, where \fIN\fP is at least 0.25, and not more than 0.5. diff --git a/man3/tmpfile.3 b/man3/tmpfile.3 index ec2ebf5a94..ac7d7c5749 100644 --- a/man3/tmpfile.3 +++ b/man3/tmpfile.3 @@ -36,12 +36,16 @@ tmpfile \- create a temporary file .B FILE *tmpfile(void); .fi .SH DESCRIPTION -The \fBtmpfile\fP() function opens a unique temporary file +The +.BR tmpfile () +function opens a unique temporary file in binary read/write (w+b) mode. The file will be automatically deleted when it is closed or the program terminates. .SH "RETURN VALUE" -The \fBtmpfile\fP() function returns a stream descriptor, or NULL if +The +.BR tmpfile () +function returns a stream descriptor, or NULL if a unique filename cannot be generated or the unique file cannot be opened. In the latter case, \fIerrno\fP is set to indicate the error. diff --git a/man3/toascii.3 b/man3/toascii.3 index 9e447dde98..cf6f6cc7fd 100644 --- a/man3/toascii.3 +++ b/man3/toascii.3 @@ -34,7 +34,8 @@ toascii \- convert character to ASCII .BI "int toascii(int " "c" ); .fi .SH DESCRIPTION -\fBtoascii\fP() converts \fIc\fP to a 7-bit \fIunsigned char\fP value +.BR toascii () +converts \fIc\fP to a 7-bit \fIunsigned char\fP value that fits into the ASCII character set, by clearing the high-order bits. .SH "RETURN VALUE" diff --git a/man3/towctrans.3 b/man3/towctrans.3 index ee874f11a7..c5793a0d23 100644 --- a/man3/towctrans.3 +++ b/man3/towctrans.3 @@ -21,14 +21,20 @@ towctrans \- wide-character transliteration .BI "wint_t towctrans(wint_t " wc ", wctrans_t " desc ); .fi .SH DESCRIPTION -If \fIwc\fP is a wide character, the \fBtowctrans\fP() function +If \fIwc\fP is a wide character, the +.BR towctrans () +function translates it according to the transliteration descriptor \fIdesc\fP. If \fIwc\fP is WEOF, WEOF is returned. .PP \fIdesc\fP must be a transliteration descriptor returned by -the \fBwctrans\fP(3) function. +the +.BR wctrans (3) +function. .SH "RETURN VALUE" -The \fBtowctrans\fP() function returns the translated wide character, +The +.BR towctrans () +function returns the translated wide character, or WEOF if \fIwc\fP is WEOF. .SH "CONFORMING TO" C99. @@ -37,5 +43,7 @@ C99. .BR towupper (3), .BR wctrans (3) .SH NOTES -The behaviour of \fBtowctrans\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR towctrans () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/towlower.3 b/man3/towlower.3 index 5af8e592fd..1a8d23096d 100644 --- a/man3/towlower.3 +++ b/man3/towlower.3 @@ -21,14 +21,19 @@ towlower \- convert a wide character to lowercase .BI "wint_t towlower(wint_t " wc ); .fi .SH DESCRIPTION -The \fBtowlower\fP() function is the wide-character equivalent of the -\fBtolower\fP(3) function. +The +.BR towlower () +function is the wide-character equivalent of the +.BR tolower (3) +function. If \fIwc\fP is a wide character, it is converted to lowercase. Characters which do not have case are returned unchanged. If \fIwc\fP is WEOF, WEOF is returned. .SH "RETURN VALUE" -The \fBtowlower\fP() function returns the lowercase equivalent of \fIwc\fP, +The +.BR towlower () +function returns the lowercase equivalent of \fIwc\fP, or WEOF if \fIwc\fP is WEOF. .SH "CONFORMING TO" C99. @@ -37,7 +42,9 @@ C99. .BR towctrans (3), .BR towupper (3) .SH NOTES -The behaviour of \fBtowlower\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR towlower () +depends on the LC_CTYPE category of the current locale. .PP This function is not very appropriate for dealing with Unicode characters, diff --git a/man3/towupper.3 b/man3/towupper.3 index 2f571cf693..52fbb54d09 100644 --- a/man3/towupper.3 +++ b/man3/towupper.3 @@ -21,14 +21,19 @@ towupper \- convert a wide character to uppercase .BI "wint_t towupper(wint_t " wc ); .fi .SH DESCRIPTION -The \fBtowupper\fP() function is the wide-character equivalent of the -\fBtoupper\fP(3) function. +The +.BR towupper () +function is the wide-character equivalent of the +.BR toupper (3) +function. If \fIwc\fP is a wide character, it is converted to uppercase. Characters which do not have case are returned unchanged. If \fIwc\fP is WEOF, WEOF is returned. .SH "RETURN VALUE" -The \fBtowupper\fP() function returns the uppercase equivalent of \fIwc\fP, +The +.BR towupper () +function returns the uppercase equivalent of \fIwc\fP, or WEOF if \fIwc\fP is WEOF. .SH "CONFORMING TO" C99. @@ -37,7 +42,9 @@ C99. .BR towctrans (3), .BR towlower (3) .SH NOTES -The behaviour of \fBtowupper\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR towupper () +depends on the LC_CTYPE category of the current locale. .PP This function is not very appropriate for dealing with Unicode characters, diff --git a/man3/tsearch.3 b/man3/tsearch.3 index ba95558150..9adc8e5f57 100644 --- a/man3/tsearch.3 +++ b/man3/tsearch.3 @@ -49,7 +49,12 @@ tsearch, tfind, tdelete, twalk, tdestroy \- manage a binary tree .RE .fi .SH DESCRIPTION -\fBtsearch\fP(), \fBtfind\fP(), \fBtwalk\fP(), and \fBtdelete\fP() manage a +.BR tsearch (), +.BR tfind (), +.BR twalk (), +and +.BR tdelete () +manage a binary tree. They are generalized from Knuth (6.2.2) Algorithm T. The first field in each node of the tree is a pointer to the @@ -61,26 +66,40 @@ It should return an integer which is negative, zero, or positive, depending on whether the first item is less than, equal to, or greater than the second. .PP -\fBtsearch\fP() searches the tree for an item. +.BR tsearch () +searches the tree for an item. \fIkey\fP points to the item to be searched for. \fIrootp\fP points to a variable which points to the root of the tree. If the tree is empty, then the variable that \fIrootp\fP points to should be set to NULL. -If the item is found in the tree, then \fBtsearch\fP() returns a pointer +If the item is found in the tree, then +.BR tsearch () +returns a pointer to it. -If it is not found, then \fBtsearch\fP() adds it, and returns a +If it is not found, then +.BR tsearch () +adds it, and returns a pointer to the newly added item. .PP -\fBtfind\fP() is like \fBtsearch\fP(), except that if the item is not -found, then \fBtfind\fP() returns NULL. +.BR tfind () +is like +.BR tsearch (), +except that if the item is not +found, then +.BR tfind () +returns NULL. .PP -\fBtdelete\fP() deletes an item from the tree. -Its arguments are the same as for \fBtsearch\fP(). +.BR tdelete () +deletes an item from the tree. +Its arguments are the same as for +.BR tsearch (). .PP -\fBtwalk\fP() performs depth-first, left-to-right traversal of a binary +.BR twalk () +performs depth-first, left-to-right traversal of a binary tree. \fIroot\fP points to the starting node for the traversal. If that node is not the root, then only part of the tree will be visited. -\fBtwalk\fP() calls the user function \fIaction\fP each time a node is +.BR twalk () +calls the user function \fIaction\fP each time a node is visited (that is, three times for an internal node, and once for a leaf). \fIaction\fP, in turn, takes three arguments. The first is a pointer to the node being visited. @@ -100,39 +119,55 @@ and after visiting the children. Thus, the choice of name \fBpost\%order\fP is rather confusing.) .PP -\fBtdestroy\fP() removes the whole tree pointed to by \fIroot\fP, -freeing all resources allocated by the \fBtsearch\fP() function. +.BR tdestroy () +removes the whole tree pointed to by \fIroot\fP, +freeing all resources allocated by the +.BR tsearch () +function. For the data in each tree node the function \fIfree_node\fP is called. The pointer to the data is passed as the argument to the function. If no such work is necessary \fIfree_node\fP must point to a function doing nothing. .SH "RETURN VALUE" -\fBtsearch\fP() returns a pointer to a matching item in the tree, or to +.BR tsearch () +returns a pointer to a matching item in the tree, or to the newly added item, or NULL if there was insufficient memory -to add the item. \fBtfind\fP() returns a pointer to the item, or +to add the item. +.BR tfind () +returns a pointer to the item, or NULL if no match is found. If there are multiple elements that match the key, the element returned is unspecified. .PP -\fBtdelete\fP() returns a pointer to the parent of the item deleted, or +.BR tdelete () +returns a pointer to the parent of the item deleted, or NULL if the item was not found. .PP -\fBtsearch\fP(), \fBtfind\fP(), and \fBtdelete\fP() also +.BR tsearch (), +.BR tfind (), +and +.BR tdelete () +also return NULL if \fIrootp\fP was NULL on entry. .SH WARNINGS -\fBtwalk\fP() takes a pointer to the root, while the other functions +.BR twalk () +takes a pointer to the root, while the other functions take a pointer to a variable which points to the root. .PP -\fBtwalk\fP() uses \fBpostorder\fP to mean "after the left subtree, but +.BR twalk () +uses \fBpostorder\fP to mean "after the left subtree, but before the right subtree". Some authorities would call this "inorder", and reserve "postorder" to mean "after both subtrees". .PP -\fBtdelete\fP() frees the memory required for the node in the tree. +.BR tdelete () +frees the memory required for the node in the tree. The user is responsible for freeing the memory for the corresponding data. .PP -The example program depends on the fact that \fBtwalk\fP() makes no +The example program depends on the fact that +.BR twalk () +makes no further reference to a node after calling the user function with argument "endorder" or "leaf". This works with the GNU library diff --git a/man3/tzset.3 b/man3/tzset.3 index 4edfd86474..3747fb4561 100644 --- a/man3/tzset.3 +++ b/man3/tzset.3 @@ -42,7 +42,9 @@ tzset, tzname, timezone, daylight \- initialize time conversion information .BI "extern int " daylight ; .fi .SH DESCRIPTION -The \fBtzset\fP() function initializes the \fItzname\fP variable from the +The +.BR tzset () +function initializes the \fItzname\fP variable from the TZ environment variable. This function is automatically called by the other time conversion functions that depend on the time zone. diff --git a/man3/ualarm.3 b/man3/ualarm.3 index fee46e82e6..f77f1987b0 100644 --- a/man3/ualarm.3 +++ b/man3/ualarm.3 @@ -31,7 +31,9 @@ ualarm \- schedule signal after given number of microseconds .BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval ); .fi .SH DESCRIPTION -The \fBualarm\fP() function causes the signal SIGALRM to be sent +The +.BR ualarm () +function causes the signal SIGALRM to be sent to the invoking process after (not less than) .I usecs microseconds. diff --git a/man3/ungetwc.3 b/man3/ungetwc.3 index 9f92612dbe..fc2a39f54b 100644 --- a/man3/ungetwc.3 +++ b/man3/ungetwc.3 @@ -21,7 +21,10 @@ ungetwc \- push back a wide character onto a FILE stream .BI "wint_t ungetwc(wint_t " wc ", FILE *" stream ); .fi .SH DESCRIPTION -The \fBungetwc\fP() function is the wide-character equivalent of the \fBungetc\fP() +The +.BR ungetwc () +function is the wide-character equivalent of the +.BR ungetc () function. It pushes back a wide character onto \fIstream\fP and returns it. .PP @@ -43,12 +46,16 @@ If the implementation supports multiple push-back operations in a row, the pushed-back wide characters will be read in reverse order; however, only one level of push-back is guaranteed. .SH "RETURN VALUE" -The \fBungetwc\fP() function returns \fIwc\fP when successful, or WEOF upon +The +.BR ungetwc () +function returns \fIwc\fP when successful, or WEOF upon failure. .SH "CONFORMING TO" C99. .SH "SEE ALSO" .BR fgetwc (3) .SH NOTES -The behaviour of \fBungetwc\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR ungetwc () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/updwtmp.3 b/man3/updwtmp.3 index f25c664891..9ab4f9f213 100644 --- a/man3/updwtmp.3 +++ b/man3/updwtmp.3 @@ -31,14 +31,18 @@ updwtmp, logwtmp \- append an entry to the wtmp file .BI "void logwtmp(const char *" line ", const char *" name ", const char *" host ); .fi .SH DESCRIPTION -\fBupdwtmp\fR() appends the utmp structure +.BR updwtmp () +appends the utmp structure .I ut to the wtmp file. .PP -\fBlogwtmp\fR() constructs a utmp structure using +.BR logwtmp () +constructs a utmp structure using .IR line ", " name ", " host , current time and current process ID. -Then it calls \fBupdwtmp\fR() to append the structure to the utmp file. +Then it calls +.BR updwtmp () +to append the structure to the utmp file. .SH AVAILABILITY Both functions are available under glibc2, but not under libc5. However, diff --git a/man3/usleep.3 b/man3/usleep.3 index 402f88c46b..85a2b1a87c 100644 --- a/man3/usleep.3 +++ b/man3/usleep.3 @@ -40,7 +40,9 @@ usleep \- suspend execution for microsecond intervals .BI "int usleep(useconds_t " usec ); .fi .SH DESCRIPTION -The \fBusleep\fP() function suspends execution of the calling process for +The +.BR usleep () +function suspends execution of the calling process for (at least) \fIusec\fP microseconds. The sleep may be lengthened slightly by any system activity or by the time spent processing the call or by the diff --git a/man3/wcpcpy.3 b/man3/wcpcpy.3 index 0fadb77a19..017ca509cc 100644 --- a/man3/wcpcpy.3 +++ b/man3/wcpcpy.3 @@ -22,7 +22,10 @@ wcpcpy \- copy a wide-character string, returning a pointer to its end .BI "wchar_t *wcpcpy(wchar_t *" dest ", const wchar_t *" src ); .fi .SH DESCRIPTION -The \fBwcpcpy\fP() function is the wide-character equivalent of the \fBstpcpy\fP() +The +.BR wcpcpy () +function is the wide-character equivalent of the +.BR stpcpy () function. It copies the wide-character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, to the array pointed to by @@ -33,7 +36,8 @@ The strings may not overlap. The programmer must ensure that there is room for at least \fIwcslen(src)+1\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -\fBwcpcpy\fP() returns a pointer to the end of the wide-character string +.BR wcpcpy () +returns a pointer to the end of the wide-character string \fIdest\fP, that is, a pointer to the terminating L'\\0' character. .SH "CONFORMING TO" This function is a GNU extension. diff --git a/man3/wcpncpy.3 b/man3/wcpncpy.3 index dd933dd9f8..839b43d295 100644 --- a/man3/wcpncpy.3 +++ b/man3/wcpncpy.3 @@ -23,8 +23,12 @@ returning a pointer to its end .BI "wchar_t *wcpncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcpncpy\fP() function is the wide-character equivalent -of the \fBstpncpy\fP(3) function. +The +.BR wcpncpy () +function is the wide-character equivalent +of the +.BR stpncpy (3) +function. It copies at most \fIn\fP wide characters from the wide-character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, to the array pointed to by \fIdest\fP. @@ -42,7 +46,8 @@ The strings may not overlap. The programmer must ensure that there is room for at least \fIn\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -\fBwcpncpy\fP() returns a pointer to the last wide character written, i.e. +.BR wcpncpy () +returns a pointer to the last wide character written, i.e. \fIdest + n \- 1\fP. .SH "CONFORMING TO" This function is a GNU extension. diff --git a/man3/wcrtomb.3 b/man3/wcrtomb.3 index 8567374f7f..7c9a3025f1 100644 --- a/man3/wcrtomb.3 +++ b/man3/wcrtomb.3 @@ -24,7 +24,9 @@ wcrtomb \- convert a wide character to a multibyte sequence The main case for this function is when \fIs\fP is not NULL and \fIwc\fP is not L'\\0'. -In this case, the \fBwcrtomb\fP() function +In this case, the +.BR wcrtomb () +function converts the wide character \fIwc\fP to its multibyte representation and stores it at the beginning of the character @@ -36,7 +38,9 @@ written at \fIs\fP. .PP A different case is when \fIs\fP is not NULL but \fIwc\fP is L'\\0'. In this -case the \fBwcrtomb\fP() function stores at +case the +.BR wcrtomb () +function stores at the character array pointed to by \fIs\fP the shift sequence needed to bring \fI*ps\fP back to the initial state, @@ -52,9 +56,13 @@ and the function effectively returns wcrtomb(buf,L'\\0',\fIps\fP) where buf is an internal anonymous buffer. .PP In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous -state only known to the \fBwcrtomb\fP() function is used instead. +state only known to the +.BR wcrtomb () +function is used instead. .SH "RETURN VALUE" -The \fBwcrtomb\fP() function returns the number of +The +.BR wcrtomb () +function returns the number of bytes that have been or would have been written to the byte array at \fIs\fP. If \fIwc\fP can not be @@ -65,7 +73,9 @@ C99. .SH "SEE ALSO" .BR wcsrtombs (3) .SH NOTES -The behaviour of \fBwcrtomb\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wcrtomb () +depends on the LC_CTYPE category of the current locale. .PP Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/wcscasecmp.3 b/man3/wcscasecmp.3 index ec32073f9f..550fcf0e8a 100644 --- a/man3/wcscasecmp.3 +++ b/man3/wcscasecmp.3 @@ -20,13 +20,20 @@ wcscasecmp \- compare two wide-character strings, ignoring case .BI "int wcscasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ); .fi .SH DESCRIPTION -The \fBwcscasecmp\fP() function is the wide-character equivalent of the -\fBstrcasecmp\fP(3) function. +The +.BR wcscasecmp () +function is the wide-character equivalent of the +.BR strcasecmp (3) +function. It compares the wide-character string pointed to by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, ignoring -case differences (\fBtowupper\fP(3), \fBtowlower\fP(3)). +case differences +.RB ( towupper (3), +.BR towlower (3)). .SH "RETURN VALUE" -The \fBwcscasecmp\fP() function returns zero if the wide-character strings at +The +.BR wcscasecmp () +function returns zero if the wide-character strings at \fIs1\fP and \fIs2\fP are equal except for case distinctions. It returns a positive integer if \fIs1\fP is greater than \fIs2\fP, ignoring case. @@ -39,5 +46,7 @@ This function is a GNU extension. .BR strcasecmp (3), .BR wcscmp (3) .SH NOTES -The behaviour of \fBwcscasecmp\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wcscasecmp () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/wcscat.3 b/man3/wcscat.3 index 00ec6c3a90..f6447a255f 100644 --- a/man3/wcscat.3 +++ b/man3/wcscat.3 @@ -21,8 +21,12 @@ wcscat \- concatenate two wide-character strings .BI "wchar_t *wcscat(wchar_t *" dest ", const wchar_t *" src ); .fi .SH DESCRIPTION -The \fBwcscat\fP() function is the wide-character equivalent -of the \fBstrcat\fP(3) function. +The +.BR wcscat () +function is the wide-character equivalent +of the +.BR strcat (3) +function. It copies the wide-character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, to the end of the wide-character string pointed to by \fIdest\fP. @@ -32,7 +36,8 @@ The strings may not overlap. The programmer must ensure that there is room for at least \fIwcslen(dest)+wcslen(src)+1\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -\fBwcscat\fP() returns \fIdest\fP. +.BR wcscat () +returns \fIdest\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wcschr.3 b/man3/wcschr.3 index bd30f0ed68..5da6c4c03d 100644 --- a/man3/wcschr.3 +++ b/man3/wcschr.3 @@ -21,12 +21,18 @@ wcschr \- search a wide character in a wide-character string .BI "wchar_t *wcschr(const wchar_t *" wcs ", wchar_t " wc ); .fi .SH DESCRIPTION -The \fBwcschr\fP() function is the wide-character equivalent -of the \fBstrchr\fP(3) function. +The +.BR wcschr () +function is the wide-character equivalent +of the +.BR strchr (3) +function. It searches the first occurrence of \fIwc\fP in the wide-character string pointed to by \fIwcs\fP. .SH "RETURN VALUE" -The \fBwcschr\fP() function returns a pointer to the first occurrence of +The +.BR wcschr () +function returns a pointer to the first occurrence of \fIwc\fP in the wide-character string pointed to by \fIwcs\fP, or NULL if \fIwc\fP does not occur in the string. .SH "CONFORMING TO" diff --git a/man3/wcscmp.3 b/man3/wcscmp.3 index cbecb3593e..336eedf545 100644 --- a/man3/wcscmp.3 +++ b/man3/wcscmp.3 @@ -21,12 +21,18 @@ wcscmp \- compare two wide-character strings .BI "int wcscmp(const wchar_t *" s1 ", const wchar_t *" s2 ); .fi .SH DESCRIPTION -The \fBwcscmp\fP() function is the wide-character equivalent -of the \fBstrcmp\fP(3) function. +The +.BR wcscmp () +function is the wide-character equivalent +of the +.BR strcmp (3) +function. It compares the wide-character string pointed to by \fIs1\fP and the wide-character string pointed to by \fIs2\fP. .SH "RETURN VALUE" -The \fBwcscmp\fP() function returns zero if the wide-character strings at +The +.BR wcscmp () +function returns zero if the wide-character strings at \fIs1\fP and \fIs2\fP are equal. It returns an integer greater than zero if at the first differing position \fIi\fP, the corresponding wide-character diff --git a/man3/wcscpy.3 b/man3/wcscpy.3 index 69e7d61699..db5427acf9 100644 --- a/man3/wcscpy.3 +++ b/man3/wcscpy.3 @@ -21,8 +21,12 @@ wcscpy \- copy a wide-character string .BI "wchar_t *wcscpy(wchar_t *" dest ", const wchar_t *" src ); .fi .SH DESCRIPTION -The \fBwcscpy\fP() function is the wide-character equivalent -of the \fBstrcpy\fP(3) function. +The +.BR wcscpy () +function is the wide-character equivalent +of the +.BR strcpy (3) +function. It copies the wide-character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, to the array pointed to by \fIdest\fP. @@ -33,7 +37,8 @@ The programmer must ensure that there is room for at least \fIwcslen(src)+1\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -\fBwcscpy\fP() returns \fIdest\fP. +.BR wcscpy () +returns \fIdest\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wcscspn.3 b/man3/wcscspn.3 index dd444ef1a1..c6c84a21cc 100644 --- a/man3/wcscspn.3 +++ b/man3/wcscspn.3 @@ -21,8 +21,12 @@ wcscspn \- search a wide-character string for any of a set of wide characters .BI "size_t wcscspn(const wchar_t *" wcs ", const wchar_t *" reject ); .fi .SH DESCRIPTION -The \fBwcscspn\fP() function is the wide-character equivalent -of the \fBstrcspn\fP(3) function. +The +.BR wcscspn () +function is the wide-character equivalent +of the +.BR strcspn (3) +function. It determines the length of the longest initial segment of \fIwcs\fP which consists entirely of wide-characters not listed in \fIreject\fP. In @@ -30,7 +34,9 @@ other words, it searches for the first occurrence in the wide-character string \fIwcs\fP of any of the characters in the wide-character string \fIreject\fP. .SH "RETURN VALUE" -The \fBwcscspn\fP() function returns the number of +The +.BR wcscspn () +function returns the number of wide characters in the longest initial segment of \fIwcs\fP which consists entirely of wide-characters not listed in \fIreject\fP. diff --git a/man3/wcsdup.3 b/man3/wcsdup.3 index 7f2049918a..370a3b9614 100644 --- a/man3/wcsdup.3 +++ b/man3/wcsdup.3 @@ -22,16 +22,25 @@ wcsdup \- duplicate a wide-character string .BI "wchar_t *wcsdup(const wchar_t *" s ); .fi .SH DESCRIPTION -The \fBwcsdup\fP() function is the wide-character equivalent -of the \fBstrdup\fP(3) function. +The +.BR wcsdup () +function is the wide-character equivalent +of the +.BR strdup (3) +function. It allocates and returns a new wide-character string whose initial contents is a duplicate of the wide-character string pointed to by \fIs\fP. .PP Memory for the new wide-character string is -obtained with \fBmalloc\fP(3), and -can be freed with \fBfree\fP(3). +obtained with +.BR malloc (3), +and +can be freed with +.BR free (3). .SH "RETURN VALUE" -The \fBwcsdup\fP() function returns a pointer +The +.BR wcsdup () +function returns a pointer to the new wide-character string, or NULL if sufficient memory was not available. .SH ERRORS diff --git a/man3/wcslen.3 b/man3/wcslen.3 index 5f5efd4cc8..9fc34b5c41 100644 --- a/man3/wcslen.3 +++ b/man3/wcslen.3 @@ -21,12 +21,18 @@ wcslen \- determine the length of a wide-character string .BI "size_t wcslen(const wchar_t *" s ); .fi .SH DESCRIPTION -The \fBwcslen\fP() function is the wide-character equivalent -of the \fBstrlen\fP(3) function. +The +.BR wcslen () +function is the wide-character equivalent +of the +.BR strlen (3) +function. It determines the length of the wide-character string pointed to by \fIs\fP, not including the terminating L'\\0' character. .SH "RETURN VALUE" -The \fBwcslen\fP() function returns the +The +.BR wcslen () +function returns the number of wide characters in \fIs\fP. .SH "CONFORMING TO" C99. diff --git a/man3/wcsncasecmp.3 b/man3/wcsncasecmp.3 index 4a4ad60884..061bf37fcd 100644 --- a/man3/wcsncasecmp.3 +++ b/man3/wcsncasecmp.3 @@ -20,15 +20,21 @@ wcsncasecmp \- compare two fixed-size wide-character strings, ignoring case .BI "int wcsncasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcsncasecmp\fP() function is the wide-character equivalent of the -\fBstrncasecmp\fP(3) function. +The +.BR wcsncasecmp () +function is the wide-character equivalent of the +.BR strncasecmp (3) +function. It compares the wide-character string pointed to by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, but at most \fIn\fP wide characters from each string, ignoring case differences -(\fBtowupper\fP(3), \fBtowlower\fP(3)). +.RB ( towupper (3), +.BR towlower (3)). .SH "RETURN VALUE" -The \fBwcsncasecmp\fP() function returns zero +The +.BR wcsncasecmp () +function returns zero if the wide-character strings at \fIs1\fP and \fIs2\fP, truncated to at most length \fIn\fP, are equal except @@ -43,5 +49,7 @@ This function is a GNU extension. .BR strncasecmp (3), .BR wcsncmp (3) .SH NOTES -The behaviour of \fBwcsncasecmp\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wcsncasecmp () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/wcsncat.3 b/man3/wcsncat.3 index 962c6035d2..82cae00ac7 100644 --- a/man3/wcsncat.3 +++ b/man3/wcsncat.3 @@ -21,8 +21,11 @@ wcsncat \- concatenate two wide-character strings .BI "wchar_t *wcsncat(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcsncat\fP() function is the wide-character equivalent of the -\fBstrncat\fP(3) function. +The +.BR wcsncat () +function is the wide-character equivalent of the +.BR strncat (3) +function. It copies at most \fIn\fP wide characters from the wide-character string pointed to by \fIsrc\fP to the end of the wide-character string pointed to by \fIdest\fP, and adds a terminating L'\\0' character. @@ -32,7 +35,8 @@ The strings may not overlap. The programmer must ensure that there is room for at least \fIwcslen(dest)+n+1\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -\fBwcsncat\fP() returns \fIdest\fP. +.BR wcsncat () +returns \fIdest\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wcsncmp.3 b/man3/wcsncmp.3 index 35adf2121f..02414d8325 100644 --- a/man3/wcsncmp.3 +++ b/man3/wcsncmp.3 @@ -21,15 +21,20 @@ wcsncmp \- compare two fixed-size wide-character strings .BI "int wcsncmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcsncmp\fP() function is the wide-character equivalent of the -\fBstrncmp\fP(3) function. +The +.BR wcsncmp () +function is the wide-character equivalent of the +.BR strncmp (3) +function. It compares the wide-character string pointed to by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, but at most \fIn\fP wide characters from each string. In each string, the comparison extends only up to the first occurrence of a L'\\0' character, if any. .SH "RETURN VALUE" -The \fBwcsncmp\fP() function returns zero if the wide-character strings at +The +.BR wcsncmp () +function returns zero if the wide-character strings at \fIs1\fP and \fIs2\fP, truncated to at most length \fIn\fP, are equal. It returns an integer greater than zero if at the first differing position \fIi\fP (\fIi\fP < \fIn\fP), diff --git a/man3/wcsncpy.3 b/man3/wcsncpy.3 index 9ca023d86d..fb746726cb 100644 --- a/man3/wcsncpy.3 +++ b/man3/wcsncpy.3 @@ -21,8 +21,11 @@ wcsncpy \- copy a fixed-size string of wide characters .BI "wchar_t *wcsncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcsncpy\fP() function is the wide-character equivalent of the -\fBstrncpy\fP(3) function. +The +.BR wcsncpy () +function is the wide-character equivalent of the +.BR strncpy (3) +function. It copies at most \fIn\fP wide characters from the wide-character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, to the array pointed to by \fIdest\fP. @@ -41,7 +44,8 @@ The strings may not overlap. The programmer must ensure that there is room for at least \fIn\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -\fBwcsncpy\fP() returns \fIdest\fP. +.BR wcsncpy () +returns \fIdest\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wcsnlen.3 b/man3/wcsnlen.3 index 18a964c12c..d1793b6ab7 100644 --- a/man3/wcsnlen.3 +++ b/man3/wcsnlen.3 @@ -20,15 +20,23 @@ wcsnlen \- determine the length of a fixed-size wide-character string .BI "size_t wcsnlen(const wchar_t *" s ", size_t " maxlen ); .fi .SH DESCRIPTION -The \fBwcsnlen\fP() function is the wide-character equivalent -of the \fBstrnlen\fP(3) function. +The +.BR wcsnlen () +function is the wide-character equivalent +of the +.BR strnlen (3) +function. It returns the number of wide-characters in the string pointed to by \fIs\fP, not including the terminating L'\\0' character, but at most \fImaxlen\fP. -In doing this, \fBwcsnlen\fP() looks only at the first \fImaxlen\fP +In doing this, +.BR wcsnlen () +looks only at the first \fImaxlen\fP wide-characters at \fIs\fP and never beyond \fIs+maxlen\fP. .SH "RETURN VALUE" -The \fBwcsnlen\fP() function returns \fIwcslen(s)\fP, if that is less than +The +.BR wcsnlen () +function returns \fIwcslen(s)\fP, if that is less than \fImaxlen\fP, or \fImaxlen\fP if there is no L'\\0' character among the first \fImaxlen\fP wide characters pointed to by \fIs\fP. .SH "CONFORMING TO" diff --git a/man3/wcsnrtombs.3 b/man3/wcsnrtombs.3 index 0de0ff1523..2cb5814c0c 100644 --- a/man3/wcsnrtombs.3 +++ b/man3/wcsnrtombs.3 @@ -21,12 +21,18 @@ wcsnrtombs \- convert a wide-character string to a multibyte string .BI " size_t " len ", mbstate_t *" ps ); .fi .SH DESCRIPTION -The \fBwcsnrtombs\fP() function is like the \fBwcsrtombs\fP() function, +The +.BR wcsnrtombs () +function is like the +.BR wcsrtombs () +function, except that the number of wide characters to be converted, starting at \fI*src\fP, is limited to \fInwc\fP. .PP If \fIdest\fP is not a NULL pointer, -the \fBwcsnrtombs\fP() function converts +the +.BR wcsnrtombs () +function converts at most \fInwc\fP wide characters from the wide-character string \fI*src\fP to a multibyte string starting at \fIdest\fP. @@ -73,7 +79,9 @@ state only known to the wcsnrtombs function is used instead. The programmer must ensure that there is room for at least \fIlen\fP bytes at \fIdest\fP. .SH "RETURN VALUE" -The \fBwcsnrtombs\fP() function returns +The +.BR wcsnrtombs () +function returns the number of bytes that make up the converted part of multibyte sequence, not including the terminating null byte. @@ -86,7 +94,9 @@ This function is a GNU extension. .BR iconv (3), .BR wcsrtombs (3) .SH NOTES -The behaviour of \fBwcsnrtombs\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wcsnrtombs () +depends on the LC_CTYPE category of the current locale. .PP Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/wcspbrk.3 b/man3/wcspbrk.3 index 44e249c037..3069b43494 100644 --- a/man3/wcspbrk.3 +++ b/man3/wcspbrk.3 @@ -21,14 +21,20 @@ wcspbrk \- search a wide-character string for any of a set of wide characters .BI "wchar_t *wcspbrk(const wchar_t *" wcs ", const wchar_t *" accept ); .fi .SH DESCRIPTION -The \fBwcspbrk\fP() function is the wide-character equivalent -of the \fBstrpbrk\fP(3) function. +The +.BR wcspbrk () +function is the wide-character equivalent +of the +.BR strpbrk (3) +function. It searches for the first occurrence in the wide-character string pointed to by \fIwcs\fP of any of the characters in the wide-character string pointed to by \fIaccept\fP. .SH "RETURN VALUE" -The \fBwcspbrk\fP() function returns a pointer to the first occurrence in +The +.BR wcspbrk () +function returns a pointer to the first occurrence in \fIwcs\fP of any of the characters listed in \fIaccept\fP. If \fIwcs\fP contains none of these characters, NULL is returned. diff --git a/man3/wcsrchr.3 b/man3/wcsrchr.3 index 0ef3480b27..e7bfb7d055 100644 --- a/man3/wcsrchr.3 +++ b/man3/wcsrchr.3 @@ -21,12 +21,18 @@ wcsrchr \- search a wide character in a wide-character string .BI "wchar_t *wcsrchr(const wchar_t *" wcs ", wchar_t " wc ); .fi .SH DESCRIPTION -The \fBwcsrchr\fP() function is the wide-character equivalent -of the \fBstrrchr\fP(3) function. +The +.BR wcsrchr () +function is the wide-character equivalent +of the +.BR strrchr (3) +function. It searches the last occurrence of \fIwc\fP in the wide-character string pointed to by \fIwcs\fP. .SH "RETURN VALUE" -The \fBwcsrchr\fP() function returns a pointer to the last occurrence of +The +.BR wcsrchr () +function returns a pointer to the last occurrence of \fIwc\fP in the wide-character string pointed to by \fIwcs\fP, or NULL if \fIwc\fP does not occur in the string. .SH "CONFORMING TO" diff --git a/man3/wcsrtombs.3 b/man3/wcsrtombs.3 index a66e20d6b8..808656c0cf 100644 --- a/man3/wcsrtombs.3 +++ b/man3/wcsrtombs.3 @@ -23,7 +23,9 @@ wcsrtombs \- convert a wide-character string to a multibyte string .fi .SH DESCRIPTION If \fIdest\fP is not a NULL pointer, -the \fBwcsrtombs\fP() function converts +the +.BR wcsrtombs () +function converts the wide-character string \fI*src\fP to a multibyte string starting at \fIdest\fP. At most \fIlen\fP bytes are written to \fIdest\fP. @@ -70,7 +72,9 @@ state only known to the wcsrtombs function is used instead. The programmer must ensure that there is room for at least \fIlen\fP bytes at \fIdest\fP. .SH "RETURN VALUE" -The \fBwcsrtombs\fP() function returns +The +.BR wcsrtombs () +function returns the number of bytes that make up the converted part of multibyte sequence, not including the terminating null byte. @@ -86,7 +90,9 @@ C99. .BR wcsnrtombs (3), .BR wcstombs (3) .SH NOTES -The behaviour of \fBwcsrtombs\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wcsrtombs () +depends on the LC_CTYPE category of the current locale. .PP Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/wcsspn.3 b/man3/wcsspn.3 index 8f6106915a..435f0b7b94 100644 --- a/man3/wcsspn.3 +++ b/man3/wcsspn.3 @@ -22,8 +22,11 @@ any of a set of wide characters .BI "wcsspn(const wchar_t *" wcs ", const wchar_t *" accept ); .fi .SH DESCRIPTION -The \fBwcsspn\fP() function is the wide-character equivalent of the -\fBstrspn\fP(3) function. +The +.BR wcsspn () +function is the wide-character equivalent of the +.BR strspn (3) +function. It determines the length of the longest initial segment of \fIwcs\fP which consists entirely of wide-characters listed in \fIaccept\fP. In other @@ -31,7 +34,9 @@ words, it searches for the first occurrence in the wide-character string \fIwcs\fP of a wide-character not contained in the wide-character string \fIaccept\fP. .SH "RETURN VALUE" -The \fBwcsspn\fP() function returns the number of +The +.BR wcsspn () +function returns the number of wide characters in the longest initial segment of \fIwcs\fP which consists entirely of wide-characters listed in \fIaccept\fP. diff --git a/man3/wcsstr.3 b/man3/wcsstr.3 index dbac85a4a3..281586096e 100644 --- a/man3/wcsstr.3 +++ b/man3/wcsstr.3 @@ -21,13 +21,18 @@ wcsstr \- locate a substring in a wide-character string .BI "wchar_t *wcsstr(const wchar_t *" haystack ", const wchar_t *" needle ); .fi .SH DESCRIPTION -The \fBwcsstr\fP() function is the wide-character equivalent of the -\fBstrstr\fP(3) function. +The +.BR wcsstr () +function is the wide-character equivalent of the +.BR strstr (3) +function. It searches for the first occurrence of the wide-character string \fIneedle\fP (without its terminating L'\\0' character) as a substring in the wide-character string \fIhaystack\fP. .SH "RETURN VALUE" -The \fBwcsstr\fP() function returns a pointer to the first occurrence of +The +.BR wcsstr () +function returns a pointer to the first occurrence of \fIneedle\fP in \fIhaystack\fP. It returns NULL if \fIneedle\fP does not occur as a substring in \fIhaystack\fP. diff --git a/man3/wcstok.3 b/man3/wcstok.3 index 9b3690a539..23a8d1b7bf 100644 --- a/man3/wcstok.3 +++ b/man3/wcstok.3 @@ -21,8 +21,11 @@ wcstok \- split wide-character string into tokens .BI "wchar_t *wcstok(wchar_t *" wcs ", const wchar_t *" delim ", wchar_t **" ptr ); .fi .SH DESCRIPTION -The \fBwcstok\fP() function is the wide-character equivalent of the -\fBstrtok\fP(3) function, +The +.BR wcstok () +function is the wide-character equivalent of the +.BR strtok (3) +function, with an added argument to make it multithread-safe. It can be used to split a wide-character string \fIwcs\fP into tokens, where a token is @@ -33,16 +36,24 @@ or at \fI*ptr\fP, if \fIwcs\fP is NULL. First, any delimiter wide-characters are skipped, i.e. the pointer is advanced beyond any wide-characters which occur in \fIdelim\fP. If the end of the wide-character string is now -reached, \fBwcstok\fP() returns NULL, to indicate that no tokens +reached, +.BR wcstok () +returns NULL, to indicate that no tokens were found, and stores an appropriate value in \fI*ptr\fP, -so that subsequent calls to \fBwcstok\fP() will continue to return NULL. -Otherwise, the \fBwcstok\fP() function recognizes the beginning of a token +so that subsequent calls to +.BR wcstok () +will continue to return NULL. +Otherwise, the +.BR wcstok () +function recognizes the beginning of a token and returns a pointer to it, but before doing that, it zero-terminates the token by replacing the next wide-character which occurs in \fIdelim\fP with a L'\\0' character, and it updates \fI*ptr\fP so that subsequent calls will continue searching after the end of recognized token. .SH "RETURN VALUE" -The \fBwcstok\fP() function returns a pointer to the next token, +The +.BR wcstok () +function returns a pointer to the next token, or NULL if no further token was found. .SH NOTES The original \fIwcs\fP wide-character string is destructively modified during diff --git a/man3/wcstombs.3 b/man3/wcstombs.3 index 2e2e286a3d..c4ab6d215b 100644 --- a/man3/wcstombs.3 +++ b/man3/wcstombs.3 @@ -21,7 +21,9 @@ wcstombs \- convert a wide-character string to a multibyte string .BI "size_t wcstombs(char *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -If \fIdest\fP is not a NULL pointer, the \fBwcstombs\fP() function converts +If \fIdest\fP is not a NULL pointer, the +.BR wcstombs () +function converts the wide-character string \fIsrc\fP to a multibyte string starting at \fIdest\fP. At most \fIn\fP bytes are written to \fIdest\fP. @@ -54,7 +56,9 @@ and that no length limit exists. In order to avoid the case 2 above, the programmer should make sure \fIn\fP is greater or equal to \fIwcstombs(NULL,src,0)+1\fP. .SH "RETURN VALUE" -The \fBwcstombs\fP() function returns the number of bytes that make up the +The +.BR wcstombs () +function returns the number of bytes that make up the converted part of multibyte sequence, not including the terminating null byte. If a wide character was encountered which could not be converted, (size_t)(\-1) is returned. @@ -63,8 +67,12 @@ C99. .SH "SEE ALSO" .BR wcsrtombs (3) .SH NOTES -The behaviour of \fBwcstombs\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wcstombs () +depends on the LC_CTYPE category of the current locale. .PP -The function \fBwcsrtombs\fP(3) provides a thread safe interface to +The function +.BR wcsrtombs (3) +provides a thread safe interface to the same functionality. diff --git a/man3/wcswidth.3 b/man3/wcswidth.3 index 3ce8579043..3b341db629 100644 --- a/man3/wcswidth.3 +++ b/man3/wcswidth.3 @@ -20,14 +20,18 @@ wcswidth \- determine columns needed for a fixed-size wide-character string .BI "int wcswidth(const wchar_t *" s ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcswidth\fP() function returns the +The +.BR wcswidth () +function returns the number of columns needed to represent the wide-character string pointed to by \fIs\fP, but at most \fIn\fP wide characters. If a non-printable wide character occurs among these characters, \-1 is returned. .SH "RETURN VALUE" -The \fBwcswidth\fP() function +The +.BR wcswidth () +function returns the number of column positions for the wide-character string \fIs\fP, truncated to at most length \fIn\fP. .SH "CONFORMING TO" @@ -36,5 +40,7 @@ POSIX.1-2001. .BR iswprint (3), .BR wcwidth (3) .SH NOTES -The behaviour of \fBwcswidth\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wcswidth () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/wctob.3 b/man3/wctob.3 index 267638e6a2..63f623a6aa 100644 --- a/man3/wctob.3 +++ b/man3/wctob.3 @@ -21,7 +21,9 @@ wctob \- try to represent a wide character as a single byte .BI "int wctob(wint_t " c ); .fi .SH DESCRIPTION -The \fBwctob\fP() function tests whether +The +.BR wctob () +function tests whether the multi-byte representation of the wide character \fIc\fP, starting in the initial state, consists of a single byte. @@ -33,18 +35,23 @@ programs. Internationalized programs must never distinguish single-byte and multi-byte characters. .SH "RETURN VALUE" -The \fBwctob\fP() function returns the single-byte representation of \fIc\fP, +The +.BR wctob () +function returns the single-byte representation of \fIc\fP, if it exists, of EOF otherwise. .SH "CONFORMING TO" C99. .SH "SEE ALSO" .BR wctomb (3) .SH NOTES -The behaviour of \fBwctob\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wctob () +depends on the LC_CTYPE category of the current locale. .PP This function should never be used. Internationalized programs must never distinguish single-byte and multi-byte characters. Use the function -\fBwctomb\fP(3) instead. +.BR wctomb (3) +instead. diff --git a/man3/wctomb.3 b/man3/wctomb.3 index 0d81366c22..3c90708d4a 100644 --- a/man3/wctomb.3 +++ b/man3/wctomb.3 @@ -22,7 +22,9 @@ wctomb \- convert a wide character to a multibyte sequence .fi .SH DESCRIPTION If \fIs\fP is not NULL, -the \fBwctomb\fP() function converts the wide character +the +.BR wctomb () +function converts the wide character \fIwc\fP to its multibyte representation and stores it at the beginning of the character array pointed to by \fIs\fP. It updates the shift state, which @@ -36,7 +38,9 @@ The programmer must ensure that there is room for at least \fBMB_CUR_MAX\fP bytes at \fIs\fP. .PP -If \fIs\fP is NULL, the \fBwctomb\fP() function +If \fIs\fP is NULL, the +.BR wctomb () +function .\" The Dinkumware doc and the Single Unix specification say this, but .\" glibc doesn't implement this. resets the shift state, only known to this function, @@ -44,14 +48,18 @@ to the initial state, and returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "RETURN VALUE" -If \fIs\fP is not NULL, the \fBwctomb\fP() function +If \fIs\fP is not NULL, the +.BR wctomb () +function returns the number of bytes that have been written to the byte array at \fIs\fP. If \fIwc\fP can not be represented as a multibyte sequence (according to the current locale), \-1 is returned. .PP -If \fIs\fP is NULL, the \fBwctomb\fP() function returns non-zero if the +If \fIs\fP is NULL, the +.BR wctomb () +function returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "CONFORMING TO" C99. @@ -60,9 +68,13 @@ C99. .BR wcrtomb (3), .BR wcstombs (3) .SH NOTES -The behaviour of \fBwctomb\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wctomb () +depends on the LC_CTYPE category of the current locale. .PP This function is not multi-thread safe. -The function \fBwcrtomb\fP(3) provides +The function +.BR wcrtomb (3) +provides a better interface to the same functionality. diff --git a/man3/wctrans.3 b/man3/wctrans.3 index 99b022b0ae..c5cff01d0d 100644 --- a/man3/wctrans.3 +++ b/man3/wctrans.3 @@ -27,10 +27,14 @@ another wide character. Its nature is implementation dependent, but the special value \fI(wctrans_t)\ 0\fP denotes an invalid mapping. Nonzero \fBwctrans_t\fP -values can be passed to the \fBtowctrans\fP() function to actually perform +values can be passed to the +.BR towctrans () +function to actually perform the wide-character mapping. .PP -The \fBwctrans\fP() function returns a mapping, given by its name. +The +.BR wctrans () +function returns a mapping, given by its name. The set of valid names depends on the LC_CTYPE category of the current locale, but the following names are valid in all locales. @@ -39,7 +43,9 @@ following names are valid in all locales. "toupper" \- realizes the \fBtoupper\fP(3) mapping .fi .SH "RETURN VALUE" -The \fBwctrans\fP() function returns a mapping descriptor if the \fIname\fP +The +.BR wctrans () +function returns a mapping descriptor if the \fIname\fP is valid. Otherwise it returns \fI(wctrans_t)0\fP. .SH "CONFORMING TO" @@ -47,5 +53,7 @@ C99. .SH "SEE ALSO" .BR towctrans (3) .SH NOTES -The behaviour of \fBwctrans\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wctrans () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/wctype.3 b/man3/wctype.3 index c8c50486dc..0b57b6219b 100644 --- a/man3/wctype.3 +++ b/man3/wctype.3 @@ -27,11 +27,15 @@ In other words, it represents a class of wide characters. This type's nature is implementation dependent, but the special value \fI(wctype_t)0\fP denotes an invalid property. Nonzero \fBwctype_t\fP values -can be passed to the \fBiswctype\fP(3) function +can be passed to the +.BR iswctype (3) +function to actually test whether a given wide character has the property. .PP -The \fBwctype\fP() function returns a property, given by its name. +The +.BR wctype () +function returns a property, given by its name. The set of valid names depends on the LC_CTYPE category of the current locale, but the following names are valid in all locales. @@ -50,7 +54,9 @@ following names are valid in all locales. "xdigit" \- realizes the \fBisxdigit\fP(3) classification function .fi .SH "RETURN VALUE" -The \fBwctype\fP() function returns a property descriptor +The +.BR wctype () +function returns a property descriptor if the \fIname\fP is valid. Otherwise it returns \fI(wctype_t)0\fP. .SH "CONFORMING TO" @@ -58,5 +64,7 @@ C99. .SH "SEE ALSO" .BR iswctype (3) .SH NOTES -The behaviour of \fBwctype\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wctype () +depends on the LC_CTYPE category of the current locale. diff --git a/man3/wcwidth.3 b/man3/wcwidth.3 index 08ebbca830..7437647154 100644 --- a/man3/wcwidth.3 +++ b/man3/wcwidth.3 @@ -21,13 +21,17 @@ wcwidth \- determine columns needed for a wide character .BI "int wcwidth(wchar_t " c ); .fi .SH DESCRIPTION -The \fBwcwidth\fP() function returns the number of columns +The +.BR wcwidth () +function returns the number of columns needed to represent the wide character \fIc\fP. If \fIc\fP is a printable wide character, the value is at least 0. If \fIc\fP is L'\\0', the value is 0. Otherwise \-1 is returned. .SH "RETURN VALUE" -The \fBwcwidth\fP() function returns the number of +The +.BR wcwidth () +function returns the number of column positions for \fIc\fP. .SH "CONFORMING TO" POSIX.1-2001. @@ -38,7 +42,9 @@ Note that glibc before 2.2.5 used the prototype .BI "int wcwidth(wint_t " c ); .fi .SH NOTES -The behaviour of \fBwcwidth\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR wcwidth () +depends on the LC_CTYPE category of the current locale. .SH "SEE ALSO" .BR iswprint (3), diff --git a/man3/wmemchr.3 b/man3/wmemchr.3 index 03ce6a93a9..505be09422 100644 --- a/man3/wmemchr.3 +++ b/man3/wmemchr.3 @@ -21,12 +21,17 @@ wmemchr \- search a wide character in a wide-character array .BI "wchar_t *wmemchr(const wchar_t *" s ", wchar_t " c ", size_t " n ); .fi .SH DESCRIPTION -The \fBwmemchr\fP() function is the wide-character equivalent of the -\fBmemchr\fP(3) function. +The +.BR wmemchr () +function is the wide-character equivalent of the +.BR memchr (3) +function. It searches the \fIn\fP wide characters starting at \fIs\fP for the first occurrence of the wide character \fIc\fP. .SH "RETURN VALUE" -The \fBwmemchr\fP() function returns a pointer to the first occurrence of \fIc\fP +The +.BR wmemchr () +function returns a pointer to the first occurrence of \fIc\fP among the \fIn\fP wide characters starting at \fIs\fP, or NULL if \fIc\fP does not occur among these. .SH "CONFORMING TO" diff --git a/man3/wmemcmp.3 b/man3/wmemcmp.3 index 3f8ecad961..36802fb6ac 100644 --- a/man3/wmemcmp.3 +++ b/man3/wmemcmp.3 @@ -20,12 +20,17 @@ wmemcmp \- compare two arrays of wide-characters .BI "int wmemcmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); .fi .SH DESCRIPTION -The \fBwmemcmp\fP() function is the wide-character equivalent of the -\fBmemcmp\fP(3) function. +The +.BR wmemcmp () +function is the wide-character equivalent of the +.BR memcmp (3) +function. It compares the \fIn\fP wide-characters starting at \fIs1\fP and the \fIn\fP wide-characters starting at \fIs2\fP. .SH "RETURN VALUE" -The \fBwmemcmp\fP() function returns +The +.BR wmemcmp () +function returns zero if the wide-character arrays of size \fIn\fP at \fIs1\fP and \fIs2\fP are equal. It returns an integer greater than diff --git a/man3/wmemcpy.3 b/man3/wmemcpy.3 index 35f690b862..ec0358b105 100644 --- a/man3/wmemcpy.3 +++ b/man3/wmemcpy.3 @@ -21,18 +21,24 @@ wmemcpy \- copy an array of wide-characters .BI "wchar_t *wmemcpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBwmemcpy\fP() function is the wide-character equivalent of the -\fBmemcpy\fP(3) function. +The +.BR wmemcpy () +function is the wide-character equivalent of the +.BR memcpy (3) +function. It copies \fIn\fP wide characters from the array starting at \fIsrc\fP to the array starting at \fIdest\fP. .PP -The arrays may not overlap; use \fBwmemmove\fP(3) to copy between overlapping +The arrays may not overlap; use +.BR wmemmove (3) +to copy between overlapping arrays. .PP The programmer must ensure that there is room for at least \fIn\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -\fBwmemcpy\fP() returns \fIdest\fP. +.BR wmemcpy () +returns \fIdest\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wmemmove.3 b/man3/wmemmove.3 index 4e75a9b359..42ad51faa6 100644 --- a/man3/wmemmove.3 +++ b/man3/wmemmove.3 @@ -21,8 +21,11 @@ wmemmove \- copy an array of wide-characters .BI "wchar_t *wmemmove(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBwmemmove\fP() function is the wide-character equivalent of the -\fBmemmove\fP(3) function. +The +.BR wmemmove () +function is the wide-character equivalent of the +.BR memmove (3) +function. It copies \fIn\fP wide characters from the array starting at \fIsrc\fP to the array starting at \fIdest\fP. The arrays may @@ -31,7 +34,8 @@ overlap. The programmer must ensure that there is room for at least \fIn\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" -\fBwmemmove\fP() returns \fIdest\fP. +.BR wmemmove () +returns \fIdest\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wmemset.3 b/man3/wmemset.3 index 382c3295bb..e18fc681f5 100644 --- a/man3/wmemset.3 +++ b/man3/wmemset.3 @@ -21,12 +21,16 @@ wmemset \- fill an array of wide-characters with a constant wide character .BI "wchar_t *wmemset(wchar_t *" wcs ", wchar_t " wc ", size_t " n ); .fi .SH DESCRIPTION -The \fBwmemset\fP() function is the wide-character equivalent of the -\fBmemset\fP(3) function. +The +.BR wmemset () +function is the wide-character equivalent of the +.BR memset (3) +function. It fills the array of \fIn\fP wide-characters starting at \fIwcs\fP with \fIn\fP copies of the wide character \fIwc\fP. .SH "RETURN VALUE" -\fBwmemset\fP() returns \fIwcs\fP. +.BR wmemset () +returns \fIwcs\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wprintf.3 b/man3/wprintf.3 index 7ee99dbe93..abe4aaa360 100644 --- a/man3/wprintf.3 +++ b/man3/wprintf.3 @@ -33,23 +33,40 @@ wide-character output conversion .BI " const wchar_t *" format ", va_list " args ); .fi .SH DESCRIPTION -The \fBwprintf\fP() family of functions is +The +.BR wprintf () +family of functions is the wide-character equivalent of the -\fBprintf\fP(3) family of functions. +.BR printf (3) +family of functions. It performs formatted output of wide characters. .PP -The \fBwprintf\fP() and \fBvwprintf\fP() functions +The +.BR wprintf () +and +.BR vwprintf () +functions perform wide-character output to \fBstdout\fP. \fBstdout\fP must not be byte oriented; see function -\fBfwide\fP(3) for more information. +.BR fwide (3) +for more information. .PP -The \fBfwprintf\fP() and \fBvfwprintf\fP() functions +The +.BR fwprintf () +and +.BR vfwprintf () +functions perform wide-character output to \fIstream\fP. \fIstream\fP must not be byte oriented; see function -\fBfwide\fP(3) for more information. +.BR fwide (3) +for more information. .PP -The \fBswprintf\fP() and \fBvswprintf\fP() functions +The +.BR swprintf () +and +.BR vswprintf () +functions perform wide-character output to an array of wide characters. The programmer must ensure that there is @@ -57,8 +74,13 @@ room for at least \fImaxlen\fP wide characters at \fIwcs\fP. .PP These functions are like -the \fBprintf\fP(3), \fBvprintf\fP(3), \fBfprintf\fP(3), -\fBvfprintf\fP(3), \fBsprintf\fP(3), \fBvsprintf\fP(3) +the +.BR printf (3), +.BR vprintf (3), +.BR fprintf (3), +.BR vfprintf (3), +.BR sprintf (3), +.BR vsprintf (3) functions except for the following differences: .TP @@ -69,9 +91,17 @@ The \fIformat\fP string is a wide-character string. The output consists of wide characters, not bytes. .TP .B \(bu -\fBswprintf\fP() and \fBvswprintf\fP() take a \fImaxlen\fP argument, -\fBsprintf\fP(3) and \fBvsprintf\fP(3) do not. -(\fBsnprintf\fP(3) and \fBvsnprintf\fP(3) +.BR swprintf () +and +.BR vswprintf () +take a \fImaxlen\fP argument, +.BR sprintf (3) +and +.BR vsprintf (3) +do not. +.RB ( snprintf (3) +and +.BR vsnprintf (3) take a \fImaxlen\fP argument, but these functions do not return \-1 upon buffer overflow on Linux.) .PP @@ -132,8 +162,10 @@ to the number of wide characters in the array. .SH "RETURN VALUE" The functions return the number of wide characters written, excluding the terminating null wide character in -case of the functions \fBswprintf\fP() and -\fBvswprintf\fP(). +case of the functions +.BR swprintf () +and +.BR vswprintf (). They return \-1 when an error occurs. .SH "CONFORMING TO" C99. @@ -145,7 +177,9 @@ C99. .BR snprintf (3), .BR wscanf (3) .SH NOTES -The behaviour of \fBwprintf\fP() et al. depends +The behaviour of +.BR wprintf () +et al. depends on the LC_CTYPE category of the current locale. .PP diff --git a/man4/console_codes.4 b/man4/console_codes.4 index e688957512..76f9b52957 100644 --- a/man4/console_codes.4 +++ b/man4/console_codes.4 @@ -142,7 +142,8 @@ ESC ( B \0\0\0Select default (ISO 8859-1 mapping) ESC ( 0 \0\0\0Select VT100 graphics mapping ESC ( U \0\0\0Select null mapping \- straight to character ROM ESC ( K \0\0\0Select user mapping \- the map that is loaded by - \0\0\0the utility \fBmapscrn\fP(8). + \0\0\0the utility +.BR mapscrn (8). ESC ) Start sequence defining G1 (followed by one of B, 0, U, K, as above). ESC > DECPNM Set numeric keypad mode @@ -398,7 +399,9 @@ the device or type of the mouse, these reports are returned in the console input stream only when the virtual terminal driver receives a mouse update ioctl. These ioctls must be generated by a mouse-aware -user-mode application such as the \fBgpm(8)\fR daemon. +user-mode application such as the +.BR gpm (8) +daemon. .PP The mouse tracking escape sequences generated by \fIxterm\fP encode numeric parameters in a single character as diff --git a/man4/console_ioctl.4 b/man4/console_ioctl.4 index 33cf4dd133..11e644d209 100644 --- a/man4/console_ioctl.4 +++ b/man4/console_ioctl.4 @@ -29,7 +29,9 @@ .SH NAME console ioctl \- ioctl's for console terminal and virtual consoles .SH DESCRIPTION -The following Linux-specific \fBioctl\fP(2) requests are supported. +The following Linux-specific +.BR ioctl (2) +requests are supported. Each requires a third argument, assumed here to be \fIargp\fP. .IP \fBKDGETLED\fP Get state of LEDs. \fIargp\fP points to a long int. diff --git a/man4/rtc.4 b/man4/rtc.4 index e0e17b7312..a1d627cf6a 100644 --- a/man4/rtc.4 +++ b/man4/rtc.4 @@ -166,7 +166,9 @@ Read and set the alarm time, for RTCs that support alarms. The alarm interrupt must be separately enabled or disabled using the .BR RTC_AIE_ON ", " RTC_AIE_OFF requests. -The third \fBioctl\fP(2) argument is a pointer to an +The third +.BR ioctl (2) +argument is a pointer to an .I rtc_time structure. Only the @@ -182,7 +184,9 @@ for RTCs that support periodic interrupts. The periodic interrupt must be separately enabled or disabled using the .BR RTC_PIE_ON ", " RTC_PIE_OFF requests. -The third \fBioctl\fP(2) argument is a +The third +.BR ioctl (2) +argument is a .I "unsigned long\ *" or a .IR "unsigned long" , @@ -198,17 +202,23 @@ capability) can set frequencies above the value specified in .TP .BR RTC_AIE_ON ", " RTC_AIE_OFF Enable or disable the alarm interrupt, for RTCs that support alarms. -The third \fBioctl\fP(2) argument is ignored. +The third +.BR ioctl (2) +argument is ignored. .TP .BR RTC_UIE_ON ", " RTC_UIE_OFF Enable or disable the interrupt on every clock update, for RTCs that support this once-per-second interrupt. -The third \fBioctl\fP(2) argument is ignored. +The third +.BR ioctl (2) +argument is ignored. .TP .BR RTC_PIE_ON ", " RTC_PIE_OFF Enable or disable the periodic interrupt, for RTCs that support these periodic interrupts. -The third \fBioctl\fP(2) argument is ignored. +The third +.BR ioctl (2) +argument is ignored. Only a privileged process (i.e., one having the .B CAP_SYS_RESOURCE capability) can enable the periodic interrupt if the frequency is @@ -227,7 +237,9 @@ an RTC register for the year. With some RTCs, these operations can be used to read or to set the RTC's Epoch, respectively. -The third \fBioctl\fP(2) argument is a +The third +.BR ioctl (2) +argument is a .I "unsigned long\ *" or a .IR "unsigned long" , diff --git a/man4/tty.4 b/man4/tty.4 index d9fdece164..a5ddcc52b5 100644 --- a/man4/tty.4 +++ b/man4/tty.4 @@ -31,8 +31,12 @@ The file \fI/dev/tty\fP is a character file with major number 5 and minor number 0, usually of mode 0666 and owner.group root.tty. It is a synonym for the controlling terminal of a process, if any. .LP -In addition to the \fBioctl\fP(2) requests supported by the device that -\fBtty\fP refers to, the \fBioctl\fP(2) request \fBTIOCNOTTY\fP is supported. +In addition to the +.BR ioctl (2) +requests supported by the device that +\fBtty\fP refers to, the +.BR ioctl (2) +request \fBTIOCNOTTY\fP is supported. .SS TIOCNOTTY Detach the current process from its controlling terminal. .sp @@ -40,7 +44,9 @@ If the process is the session leader, then SIGHUP and SIGCONT signals are sent to the foreground process group and all processes in the current session lose their controlling tty. .sp -This \fBioctl\fP(2) call only works on file descriptors connected +This +.BR ioctl (2) +call only works on file descriptors connected to \fI/dev/tty\fP. It is used by daemon processes when they are invoked by a user at a terminal. diff --git a/man4/vcs.4 b/man4/vcs.4 index 46d0cdd097..a084701a51 100644 --- a/man4/vcs.4 +++ b/man4/vcs.4 @@ -41,7 +41,9 @@ dimensions and cursor position: \fIlines\fP, \fIcolumns\fP, \fIx\fP, \fIy\fP. .PP These replace the screendump .IR ioctl s -of \fBconsole\fP(4), so the system +of +.BR console (4), +so the system administrator can control access using file system permissions. .PP The devices for the first eight virtual consoles may be created by: diff --git a/man5/resolv.conf.5 b/man5/resolv.conf.5 index 3eb6431ae4..b1acb7f5fb 100644 --- a/man5/resolv.conf.5 +++ b/man5/resolv.conf.5 @@ -129,7 +129,9 @@ sets RES_DEBUG in .TP .BI ndots: n sets a threshold for the number of dots which -must appear in a name given to \fBres_query\fP() (see +must appear in a name given to +.BR res_query () +(see .BR resolver (3)) before an \fIinitial absolute query\fP will be made. The default for diff --git a/man7/environ.7 b/man7/environ.7 index cfd822fdce..f8cc7f870b 100644 --- a/man7/environ.7 +++ b/man7/environ.7 @@ -78,11 +78,15 @@ by \fBLC_ALL\fP or more specific environment variables like .BR locale (5). .TP .B PATH -The sequence of directory prefixes that \fBsh\fP(1) and many other +The sequence of directory prefixes that +.BR sh (1) +and many other programs apply in searching for a file known by an incomplete pathname. The prefixes are separated by `\fB:\fP'. (Similarly one has \fBCDPATH\fP used by some shells to find the target -of a change directory command, \fBMANPATH\fP used by \fBman\fP(1) to +of a change directory command, \fBMANPATH\fP used by +.BR man (1) +to find manual pages, etc.) .TP .B PWD @@ -133,7 +137,8 @@ etc. influence locale handling, cf. .B TMPDIR influences the path prefix of names created by \fBtmpnam(3)\fP and other routines, the temporary directory used by -\fBsort\fP(1) and other programs, etc. +.BR sort (1) +and other programs, etc. .LP .BR LD_LIBRARY_PATH ", " LD_PRELOAD and other LD_* variables influence @@ -143,12 +148,15 @@ the behaviour of the dynamic loader/linker. makes certain programs and library routines follow the prescriptions of POSIX. .LP -The behaviour of \fBmalloc\fP(3) is influenced by MALLOC_* variables. +The behaviour of +.BR malloc (3) +is influenced by MALLOC_* variables. .LP The variable .B HOSTALIASES gives the name of a file containing aliases -to be used with \fBgethostbyname\fP(3). +to be used with +.BR gethostbyname (3). .LP .BR TZ " and " TZDIR give time zone information used by diff --git a/man7/futex.7 b/man7/futex.7 index a958b25013..55371e934f 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -49,7 +49,8 @@ in which case the application is commonly called multithreaded. .PP Any futex operation starts in userspace, but it may necessary to communicate with the kernel using the -\fBfutex\fR(2) system call. +.BR futex (2) +system call. .PP To 'up' a futex, execute the proper assembler instructions that will cause the host CPU to atomically increment the integer. @@ -76,7 +77,9 @@ system call can optionally be passed a timeout specifying how long the kernel should wait for the futex to be upped. In this case, semantics are more complex and the programmer is referred -to \fBfutex\fR(2) for +to +.BR futex (2) +for more details. The same holds for asynchronous futex waiting. .SH "NOTES" @@ -87,7 +90,8 @@ Implementors are expected to be assembly literate and to have read the sources of the futex userspace library referenced below. .PP -This man page illustrates the most common use of the \fBfutex\fR(2) +This man page illustrates the most common use of the +.BR futex (2) primitives: it is by no means the only one. .SH "AUTHORS" .PP @@ -103,7 +107,7 @@ but with different semantics from those described above. Current semantics are available from Linux 2.5.40 onwards. .SH "SEE ALSO" .PP -\fBfutex\fR(2), +.BR futex (2), `Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' (proceedings of the Ottawa Linux Symposium 2002), futex example library, futex-*.tar.bz2 |