From 0bfa087b038af612bb9cff108aa2bd5de533495d Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 11 May 2007 23:07:02 +0000 Subject: [PATCH] Add section numbers to references to other pages --- man2/_exit.2 | 13 ++++++----- man2/alarm.2 | 6 ++--- man2/alloc_hugepages.2 | 2 +- man2/bdflush.2 | 3 ++- man2/clone.2 | 8 +++---- man2/dup.2 | 4 ++-- man2/epoll_wait.2 | 6 ++--- man2/execve.2 | 3 ++- man2/fcntl.2 | 30 ++++++++++++------------ man2/fdatasync.2 | 8 +++---- man2/flock.2 | 2 +- man2/futimesat.2 | 4 ++-- man2/getcontext.2 | 22 +++++++++--------- man2/getpagesize.2 | 2 +- man2/getrlimit.2 | 24 ++++++++++---------- man2/intro.2 | 2 +- man2/ioperm.2 | 8 +++---- man2/iopl.2 | 6 ++--- man2/kill.2 | 4 ++-- man2/killpg.2 | 5 ++-- man2/link.2 | 2 +- man2/madvise.2 | 6 ++--- man2/mbind.2 | 6 ++--- man2/mmap.2 | 6 ++--- man2/mount.2 | 2 +- man2/mremap.2 | 4 ++-- man2/msgctl.2 | 12 +++++----- man2/msgop.2 | 4 ++-- man2/open.2 | 12 +++++----- man2/openat.2 | 4 ++-- man2/poll.2 | 8 +++---- man2/posix_fadvise.2 | 2 +- man2/prctl.2 | 2 +- man2/ptrace.2 | 26 ++++++++++----------- man2/readv.2 | 4 ++-- man2/remap_file_pages.2 | 6 ++--- man2/sched_setscheduler.2 | 16 ++++++------- man2/select_tut.2 | 48 ++++++++++++++++++++------------------- man2/semctl.2 | 12 +++++----- man2/semget.2 | 2 +- man2/send.2 | 4 ++-- man2/sendfile.2 | 4 ++-- man2/setfsgid.2 | 2 +- man2/setfsuid.2 | 2 +- man2/setpgid.2 | 2 +- man2/setsid.2 | 4 ++-- man2/setuid.2 | 2 +- man2/shmctl.2 | 6 ++--- man2/shmget.2 | 12 +++++----- man2/shmop.2 | 16 ++++++------- man2/sigaction.2 | 10 ++++---- man2/sigaltstack.2 | 7 +++--- man2/sigsuspend.2 | 6 ++--- man2/sigwaitinfo.2 | 2 +- man2/splice.2 | 4 ++-- man2/statfs.2 | 4 ++-- man2/statvfs.2 | 4 ++-- man2/symlink.2 | 2 +- man2/times.2 | 2 +- man2/tkill.2 | 2 +- man2/uname.2 | 2 +- man2/vfork.2 | 34 +++++++++++++-------------- man2/vmsplice.2 | 4 ++-- man2/wait.2 | 6 ++--- man2/write.2 | 2 +- 65 files changed, 248 insertions(+), 243 deletions(-) diff --git a/man2/_exit.2 b/man2/_exit.2 index 3aa6e23d8..a47f04b1f 100644 --- a/man2/_exit.2 +++ b/man2/_exit.2 @@ -53,7 +53,7 @@ The value .I status is returned to the parent process as the process's exit status, and can be collected using one of the -.BR wait () +.BR wait (2) family of calls. .LP The function @@ -72,11 +72,11 @@ exit status, zombie processes, signals sent, etc., see .LP The function .BR _exit () -is like \fBexit\fP(), but does not call any +is like \fBexit\fP(3), but does not call any functions registered with -.BR atexit () +.BR atexit (3) or -.BR on_exit (). +.BR on_exit (3). Whether it flushes standard I/O buffers and removes temporary files created with .BR tmpfile (3) @@ -86,8 +86,9 @@ On the other hand, does close open file descriptors, and this may cause an unknown delay, waiting for pending output to finish. If the delay is undesired, -it may be useful to call functions like \fItcflush\fP() before -calling \fB_exit\fP(). +it may be useful to call functions like +.BR tcflush (3) +before calling \fB_exit\fP(). Whether any pending I/O is cancelled, and which pending I/O may be cancelled upon \fB_exit\fP(), is implementation-dependent. .SH "SEE ALSO" diff --git a/man2/alarm.2 b/man2/alarm.2 index 2fd310434..5683ba892 100644 --- a/man2/alarm.2 +++ b/man2/alarm.2 @@ -61,17 +61,17 @@ scheduled alarm. .SH NOTES .BR alarm () and -.BR setitimer () +.BR setitimer (2) share the same timer; calls to one will interfere with use of the other. .PP -.BR sleep () +.BR sleep (3) may be implemented using .BR SIGALRM ; mixing calls to .BR alarm () and -.BR sleep () +.BR sleep (3) is a bad idea. Scheduling delays can, as ever, cause the execution of the process to diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2 index c57dcc74c..5b1713cdd 100644 --- a/man2/alloc_hugepages.2 +++ b/man2/alloc_hugepages.2 @@ -131,7 +131,7 @@ The system calls are gone. Now the hugetlbfs filesystem can be used instead. Memory backed by huge pages (if the CPU supports them) is obtained by using -.BR mmap () +.BR mmap (2) to map files in this virtual filesystem. .LP The maximal number of huge pages can be specified using the diff --git a/man2/bdflush.2 b/man2/bdflush.2 index e4bde50ef..be35b5bfb 100644 --- a/man2/bdflush.2 +++ b/man2/bdflush.2 @@ -103,7 +103,8 @@ Caller does not have the .B CAP_SYS_ADMIN capability. .SH "CONFORMING TO" -\fBbdflush\fP() is Linux specific and should not be used in programs +.BR bdflush () +is Linux specific and should not be used in programs intended to be portable. .SH "SEE ALSO" .BR fsync (2), diff --git a/man2/clone.2 b/man2/clone.2 index ae8892b63..86e1609fc 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -568,8 +568,8 @@ was specified, and which points to the location (in child memory) where the child thread ID will be written in case CLONE_CHILD_SETTID was specified. .SH "RETURN VALUE" -.\" gettid() returns current->pid; -.\" getpid() returns current->tgid; +.\" gettid(2) returns current->pid; +.\" getpid(2) returns current->tgid; On success, the thread ID of the child process is returned in the caller's thread of execution. On failure, a \-1 will be returned @@ -689,10 +689,10 @@ intended to be portable. .SH BUGS Versions of the GNU C library that include the NPTL threading library contain a wrapper function for -.BR getpid () +.BR getpid (2) that performs caching of PIDs. In programs linked against such libraries, calls to -.BR getpid () +.BR getpid (2) may return the same value, even when the threads were not created using .B CLONE_THREAD (and thus are not in the same thread group). diff --git a/man2/dup.2 b/man2/dup.2 index d81147ce5..8838d70fb 100644 --- a/man2/dup.2 +++ b/man2/dup.2 @@ -88,7 +88,7 @@ is out of the allowed range for file descriptors. (Linux only) This may be returned by .BR dup2 () during a race condition with -.BR open () +.BR open (2) and .BR dup (). .TP @@ -118,7 +118,7 @@ like If .I newfd was open, any errors that would have been reported at -.BR close () +.BR close (2) time, are lost. A careful programmer will not use .BR dup2 () diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2 index de766af73..4ad9326c2 100644 --- a/man2/epoll_wait.2 +++ b/man2/epoll_wait.2 @@ -97,11 +97,11 @@ The relationship between and .BR epoll_pwait () is analogous to the relationship between -.BR select () +.BR select (2) and -.BR pselect (): +.BR pselect (2): like -.BR pselect (), +.BR pselect (2), .BR epoll_pwait () allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. diff --git a/man2/execve.2 b/man2/execve.2 index 0cd30e963..0ae55a1b7 100644 --- a/man2/execve.2 +++ b/man2/execve.2 @@ -372,7 +372,8 @@ but is otherwise compatible. .\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, .\" EISDIR or ELIBBAD error conditions. .SH NOTES -Set-user-ID and set-group-ID processes can not be \fBptrace\fP()d. +Set-user-ID and set-group-ID processes can not be +.BR ptrace (2)d. Linux ignores the set-user-ID and set-group-ID bits on scripts. diff --git a/man2/fcntl.2 b/man2/fcntl.2 index 502e8a39f..3b3321f32 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -116,9 +116,9 @@ and possibly modified by .BR fcntl (2). Duplicated file descriptors (made with -.BR dup (), +.BR dup (2), .BR fcntl (F_DUPFD), -.BR fork (), +.BR fork (2), etc.) refer to the same open file description, and thus share the same file status flags. .sp @@ -391,7 +391,7 @@ Most commonly, the calling process specifies itself as the owner (that is, .I arg is specified as -.BR getpid ()). +.BR getpid (2)). .\" From glibc.info: If you set the @@ -456,18 +456,18 @@ it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass .B F_SETOWN the result of -.BR gettid () +.BR gettid (2) instead of -.BR getpid () +.BR getpid (2) to get sensible results when .B F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use -.BR gettid () +.BR gettid (2) or -.BR getpid () +.BR getpid (2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: @@ -625,9 +625,9 @@ read, a write, or no lease on the file. is omitted.) .PP When a process (the "lease breaker") performs an -.BR open () +.BR open (2) or -.BR truncate () +.BR truncate (2) that conflicts with a lease established via .BR F_SETLEASE , the system call is blocked by the kernel and @@ -663,22 +663,22 @@ and assuming the lease breaker has not unblocked its system call, the kernel permits the lease breaker's system call to proceed. If the lease breaker's blocked -.BR open () +.BR open (2) or -.BR truncate () +.BR truncate (2) is interrupted by a signal handler, then the system call fails with the error .BR EINTR , but the other steps still occur as described above. If the lease breaker is killed by a signal while blocked in -.BR open () +.BR open (2) or -.BR truncate (), +.BR truncate (2), then the other steps still occur as described above. If the lease breaker specifies the .B O_NONBLOCK flag when calling -.BR open (), +.BR open (2), then the call immediately fails with the error .BR EWOULDBLOCK , but the other steps still occur as described above. @@ -866,7 +866,7 @@ Attempted to clear the flag on a file that has the append-only attribute set. .SH NOTES The errors returned by -.BR dup2 () +.BR dup2 (2) are different from those returned by .BR F_DUPFD . diff --git a/man2/fdatasync.2 b/man2/fdatasync.2 index 49cd2315c..34fbbdbd2 100644 --- a/man2/fdatasync.2 +++ b/man2/fdatasync.2 @@ -40,16 +40,16 @@ fdatasync \- synchronize a file's in-core data with that on disk flushes all data buffers of a file to disk (before the system call returns). It resembles -.BR fsync () +.BR fsync (2) but is not required to update the metadata such as access time. Applications that access databases or log files often write a tiny data fragment (e.g., one line in a log file) and then call -.BR fsync () +.BR fsync (2) immediately in order to ensure that the written data is physically stored on the harddisk. Unfortunately, -.BR fsync () +.BR fsync (2) will always initiate two write operations: one for the newly written data and another one in order to update the modification time stored in the inode. @@ -78,7 +78,7 @@ is bound to a special file which does not support synchronization. Currently (Linux 2.2) .BR fdatasync () is equivalent to -.BR fsync (). +.BR fsync (2). .SH AVAILABILITY On POSIX systems on which .BR fdatasync () diff --git a/man2/flock.2 b/man2/flock.2 index f131a129a..c4f549972 100644 --- a/man2/flock.2 +++ b/man2/flock.2 @@ -178,7 +178,7 @@ locks have different semantics with respect to forked processes and On systems that implement .BR flock () using -.BR fcntl (), +.BR fcntl (2), the semantics of .BR flock () will be different from those described in this manual page. diff --git a/man2/futimesat.2 b/man2/futimesat.2 index 6b66bd56f..78fa84172 100644 --- a/man2/futimesat.2 +++ b/man2/futimesat.2 @@ -25,7 +25,7 @@ .\" .TH FUTIMESAT 2 2006-05-05 "Linux 2.6.16" "Linux Programmer's Manual" .SH NAME -futimes \- change timestamps of a file relative to a \ +futimesat \- change timestamps of a file relative to a \ directory file descriptor .SH SYNOPSIS .nf @@ -101,7 +101,7 @@ A similar system call exists on Solaris. If .I pathname is NULL, then the glibc -.BR futimes () +.BR futimesat () wrapper function updates the times for the file referred to by .IR dirfd . .\" The Solaris futimesat() also has this strangeness. diff --git a/man2/getcontext.2 b/man2/getcontext.2 index 3630365d8..d02d4b6c6 100644 --- a/man2/getcontext.2 +++ b/man2/getcontext.2 @@ -34,8 +34,8 @@ In a System V-like environment, one has the two types \fImcontext_t\fP and \fIucontext_t\fP defined in .I and the four functions -\fBgetcontext\fP(), \fBsetcontext\fP(), \fBmakecontext\fP() -and \fBswapcontext\fP() +\fBgetcontext\fP(), \fBsetcontext\fP(), \fBmakecontext\fP(3) +and \fBswapcontext\fP(3) that allow user-level context switching between multiple threads of control within a process. .LP @@ -59,7 +59,7 @@ with \fIsigset_t\fP and \fIstack_t\fP defined in .IR . 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()), \fIuc_sigmask\fP is the +was created using \fBmakecontext\fP(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 @@ -75,18 +75,18 @@ The function \fBsetcontext\fP() 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(), or passed as third argument to a signal +or \fBmakecontext\fP(3), or passed as third argument to a signal handler. .LP If the context was obtained by a call of \fBgetcontext\fP(), program execution continues as if this call just returned. .LP -If the context was obtained by a call of \fBmakecontext\fP(), +If the context was obtained by a call of \fBmakecontext\fP(3), program execution continues by a call to the function \fIfunc\fP -specified as the second argument of that call to \fBmakecontext\fP(). +specified as the second argument of that call to \fBmakecontext\fP(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(). +first argument of that call to \fBmakecontext\fP(3). When this member is NULL, the thread exits. .LP If the context was obtained by a call to a signal handler, @@ -104,10 +104,10 @@ appropriately. None defined. .SH NOTES The earliest incarnation of this mechanism was the -\fIsetjmp\fP()/\fIlongjmp\fP() mechanism. +\fIsetjmp\fP(3)/\fIlongjmp\fP(3) mechanism. Since that does not define the handling of the signal context, the next stage was the -\fIsigsetjmp\fP()/\fIsiglongjmp\fP() pair. +\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() @@ -117,9 +117,9 @@ variable won't do since registers are restored. .LP When a signal occurs, the current user context is saved and a new context is created by the kernel for the signal handler. -Do not leave the handler using \fIlongjmp\fP(): it is undefined +Do not leave the handler using \fIlongjmp\fP(3): it is undefined what would happen with contexts. -Use \fIsiglongjmp\fP() or +Use \fIsiglongjmp\fP(3) or \fIsetcontext\fP() instead. .SH "CONFORMING TO" SUSv2, POSIX.1-2001. diff --git a/man2/getpagesize.2 b/man2/getpagesize.2 index ef9c37046..23215a1ba 100644 --- a/man2/getpagesize.2 +++ b/man2/getpagesize.2 @@ -36,7 +36,7 @@ used where it says in the description of that files are mapped in page-sized units. The size of the kind of pages that -.BR mmap () +.BR mmap (2) uses, is found using .RS diff --git a/man2/getrlimit.2 b/man2/getrlimit.2 index a2ac61218..55cb03cda 100644 --- a/man2/getrlimit.2 +++ b/man2/getrlimit.2 @@ -163,9 +163,9 @@ perform an orderly termination upon first receipt of The maximum size of the process's data segment (initialized data, uninitialized data, and heap). This limit affects calls to -.BR brk () +.BR brk (2) and -.BR sbrk (), +.BR sbrk (2), which fail with the error .B ENOMEM upon encountering the soft limit of this resource. @@ -177,17 +177,17 @@ Attempts to extend a file beyond this limit result in delivery of a signal. By default, this signal terminates a process, but a process can catch this signal instead, in which case the relevant system call (e.g., -.BR write () -.BR truncate ()) +.BR write (2) +.BR truncate (2)) fails with the error .BR EFBIG . .TP .BR RLIMIT_LOCKS " (Early Linux 2.4 only)" .\" to be precise: Linux 2.4.0-test9; no longer in 2.4.25 / 2.5.65 A limit on the combined number of -.BR flock () +.BR flock (2) locks and -.BR fcntl () +.BR fcntl (2) leases that this process may establish. .TP .B RLIMIT_MEMLOCK @@ -246,7 +246,7 @@ where is the .I mq_attr structure specified as the fourth argument to -.BR mq_open (). +.BR mq_open (3). The first addend in the formula, which includes .I "sizeof(struct msg_msg *)" @@ -269,9 +269,9 @@ For example, RLIM_INFINITY typically is the same as \-1.) Specifies a value one greater than the maximum file descriptor number that can be opened by this process. Attempts -.RB ( open (), -.BR pipe (), -.BR dup (), +.RB ( open (2), +.BR pipe (2), +.BR dup (2), etc.) to exceed this limit yield the error .BR EMFILE . @@ -280,7 +280,7 @@ to exceed this limit yield the error The maximum number of processes (or, more precisely on Linux, threads) that can be created for the real user ID of the calling process. Upon encountering this limit, -.BR fork () +.BR fork (2) fails with the error .BR EAGAIN . .TP @@ -289,7 +289,7 @@ Specifies the limit (in pages) of the process's resident set (the number of virtual pages resident in RAM). This limit only has effect in Linux 2.4.x, x < 30, and there only affects calls to -.BR madvise () +.BR madvise (2) specifying .BR MADV_WILLNEED . .\" As at kernel 2.6.12, this limit still does nothing in 2.6 though diff --git a/man2/intro.2 b/man2/intro.2 index 01b32232d..9c26cff45 100644 --- a/man2/intro.2 +++ b/man2/intro.2 @@ -144,7 +144,7 @@ For the error codes, see .BR errno (3). .sp Some system calls, such as -.BR mmap (), +.BR mmap (2), require more than five arguments. These are handled by pushing the arguments on the stack and passing a pointer to the block of arguments. diff --git a/man2/ioperm.2 b/man2/ioperm.2 index 90d77cbdd..3d368491a 100644 --- a/man2/ioperm.2 +++ b/man2/ioperm.2 @@ -52,12 +52,12 @@ If \fBturn_on\fP is non-zero, the calling process must be privileged Only the first 0x3ff I/O ports can be specified in this manner. For more ports, the -.BR iopl () -function must be used. +.BR iopl (2) +system call must be used. Permissions are not inherited on -.BR fork (), +.BR fork (2), but on -.BR exec () +.BR execve (2) they are. This is useful for giving port access permissions to non-privileged tasks. diff --git a/man2/iopl.2 b/man2/iopl.2 index 6789dc89d..68d2bb39f 100644 --- a/man2/iopl.2 +++ b/man2/iopl.2 @@ -45,7 +45,7 @@ changes the I/O privilege level of the current process, as specified in This call is necessary to allow 8514-compatible X servers to run under Linux. Since these X servers require access to all 65536 I/O ports, the -.BR ioperm () +.BR ioperm (2) call is not sufficient. In addition to granting unrestricted I/O port access, running at a higher @@ -53,9 +53,9 @@ I/O privilege level also allows the process to disable interrupts. This will probably crash the system, and is not recommended. Permissions are inherited by -.BR fork () +.BR fork (2) and -.BR exec (). +.BR execve (2). The I/O privilege level for a normal process is 0. diff --git a/man2/kill.2 b/man2/kill.2 index bff782109..20b1b8c3b 100644 --- a/man2/kill.2 +++ b/man2/kill.2 @@ -99,7 +99,7 @@ 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()ed for. +has not yet been \fBwait\fP(2)ed for. .SH NOTES The only signals that can be sent process ID 1, the .I init @@ -118,7 +118,7 @@ Linux allows a process to signal itself, but on Linux the call POSIX.1-2001 requires that if a process sends a signal to itself, and the sending thread does not have the signal blocked, and no other thread -has it unblocked or is waiting for it in \fIsigwait\fP(), at least one +has it unblocked or is waiting for it in \fIsigwait\fP(3), at least one unblocked signal must be delivered to the sending thread before the \fIkill\fP(). .SH BUGS diff --git a/man2/killpg.2 b/man2/killpg.2 index c2e7e7d25..d424fe7fb 100644 --- a/man2/killpg.2 +++ b/man2/killpg.2 @@ -96,9 +96,8 @@ have a process group. .SH NOTES There are various differences between the permission checking in BSD-type systems and System V-type systems. -See the POSIX rationale -for -.BR kill (). +See the POSIX rationale for +.BR kill (2). A difference not mentioned by POSIX concerns the return value EPERM: BSD documents that no signal is sent and EPERM returned when the permission check failed for at least one target process, diff --git a/man2/link.2 b/man2/link.2 index cf89917f2..4e780c8f0 100644 --- a/man2/link.2 +++ b/man2/link.2 @@ -130,7 +130,7 @@ Hard links, as created by .BR link (), cannot span filesystems. Use -.BR symlink () +.BR symlink (2) if this is required. POSIX.1-2001 says that diff --git a/man2/madvise.2 b/man2/madvise.2 index 73fd48fcc..9f4e4b8e9 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -80,7 +80,7 @@ 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()) or zero-fill-on-demand pages for mappings +(see \fBmmap\fP(2)) or zero-fill-on-demand pages for mappings without an underlying file. .TP .BR MADV_REMOVE " (Since Linux 2.6.16)" @@ -190,11 +190,11 @@ function first appeared in 4.4BSD. .SH "CONFORMING TO" POSIX.1b. POSIX.1-2001 describes -.BR posix_madvise () +.BR posix_madvise (3) with constants POSIX_MADV_NORMAL, etc., with a behaviour close to that described here. There is a similar -.BR posix_fadvise () +.BR posix_fadvise (3) for file access. .BR MADV_REMOVE , diff --git a/man2/mbind.2 b/man2/mbind.2 index b58f22d41..d5801f484 100644 --- a/man2/mbind.2 +++ b/man2/mbind.2 @@ -206,7 +206,7 @@ and .BR set_mempolicy (2). To select "allocation on the node of the CPU that triggered the allocation" (like -.BR set_mempolicy () +.BR set_mempolicy (2) .BR MPOL_DEFAULT ) when calling .BR mbind (), @@ -219,9 +219,9 @@ with an empty .SH "VERSIONS AND LIBRARY SUPPORT" The .BR mbind (), -.BR get_mempolicy (), +.BR get_mempolicy (2), and -.BR set_mempolicy () +.BR set_mempolicy (2) system calls were added to the Linux kernel with version 2.6.7. They are only available on kernels compiled with .BR CONFIG_NUMA . diff --git a/man2/mmap.2 b/man2/mmap.2 index c1f4642ef..4f10e1251 100644 --- a/man2/mmap.2 +++ b/man2/mmap.2 @@ -216,7 +216,7 @@ should extend downwards in memory. .TP .BR MAP_LOCKED " (since Linux 2.5.37)" Lock the pages of the mapped region into memory in the manner of -.BR mlock () . +.BR mlock (2) . This flag is ignored in older kernels. .\" If set, the mapped pages will not be swapped out. .TP @@ -306,7 +306,7 @@ and .B MAP_SHARED will be updated after a write to the mapped region, and before a subsequent -.BR msync () +.BR msync (2) with the .B MS_SYNC or @@ -432,7 +432,7 @@ case where another process has truncated the file). .SH AVAILABILITY On POSIX systems on which .BR mmap (), -.BR msync () +.BR msync (2) and .BR munmap () are available, diff --git a/man2/mount.2 b/man2/mount.2 index 14385cb58..de0aaac2e 100644 --- a/man2/mount.2 +++ b/man2/mount.2 @@ -37,7 +37,7 @@ .\" .TH MOUNT 2 2004-05-18 "Linux 2.6.12" "Linux Programmer's Manual" .SH NAME -mount, umount \- mount and unmount filesystems +mount, umount, umount2 \- mount and unmount filesystems .SH SYNOPSIS .nf .B "#include " diff --git a/man2/mremap.2 b/man2/mremap.2 index 47a5ddb34..6b53f5341 100644 --- a/man2/mremap.2 +++ b/man2/mremap.2 @@ -67,7 +67,7 @@ segments will also cause a segmentation violation. \fBmremap\fR() uses the Linux page table scheme. \fBmremap\fR() changes the mapping between virtual addresses and memory pages. -This can be used to implement a very efficient \fBrealloc\fR(). +This can be used to implement a very efficient \fBrealloc\fR(3). The \fIflags\fR bit-mask argument may be 0, or include the following flag: .TP @@ -110,7 +110,7 @@ If the memory segment specified by and .I old_size is locked (using -.BR mlock () +.BR mlock (2) 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. diff --git a/man2/msgctl.2 b/man2/msgctl.2 index 675ed744c..757d9a4e0 100644 --- a/man2/msgctl.2 +++ b/man2/msgctl.2 @@ -63,8 +63,8 @@ data structure is defined in as follows: struct msqid_ds { struct ipc_perm msg_perm; /* Ownership and permissions */ - time_t msg_stime; /* Time of last msgsnd() */ - time_t msg_rtime; /* Time of last msgrcv() */ + time_t msg_stime; /* Time of last msgsnd(2) */ + time_t msg_rtime; /* Time of last msgrcv(2) */ time_t msg_ctime; /* Time of last change */ unsigned long __msg_cbytes; /* Current number of bytes in queue (non-standard) */ @@ -72,8 +72,8 @@ struct msqid_ds { in queue */ msglen_t msg_qbytes; /* Maximum number of bytes allowed in queue */ - pid_t msg_lspid; /* PID of last msgsnd() */ - pid_t msg_lrpid; /* PID of last msgrcv() */ + pid_t msg_lspid; /* PID of last msgsnd(2) */ + pid_t msg_lrpid; /* PID of last msgrcv(2) */ }; .in -4n .fi @@ -87,7 +87,7 @@ structure is defined in as follows .nf .in +4n struct ipc_perm { - key_t key; /* Key supplied to msgget() */ + key_t key; /* Key supplied to msgget(2) */ uid_t \fBuid\fP; /* Effective UID of owner */ gid_t \fBgid\fP; /* Effective GID of owner */ uid_t cuid; /* Effective UID of creator */ @@ -171,7 +171,7 @@ struct msginfo { written in a single message */ int msgmnb; /* Max. # of bytes that can be written to queue; used to initialize msg_qbytes - during queue creation (msgget()) */ + during queue creation (msgget(2)) */ int msgmni; /* Max. # of message queues */ int msgssz; /* Message segment size; unused */ int msgtql; /* Max. # of messages on all queues diff --git a/man2/msgop.2 b/man2/msgop.2 index fa444f1c8..099c9c8d6 100644 --- a/man2/msgop.2 +++ b/man2/msgop.2 @@ -36,7 +36,7 @@ .\" .TH MSGOP 2 2006-02-02 "Linux 2.6.15" "Linux Programmer's Manual" .SH NAME -msgop \- message operations +msgop, msgrcv, msgsnd \- message operations .SH SYNOPSIS .nf .B #include @@ -407,7 +407,7 @@ Default maximum size in bytes of a message queue: 16384 bytes The superuser can increase the size of a message queue beyond .B MSGMNB by a -.BR msgctl () +.BR msgctl (2) system call. .PP The implementation has no intrinsic limits for the system wide maximum diff --git a/man2/open.2 b/man2/open.2 index 8649009ba..7ac28d93d 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -77,7 +77,7 @@ creates a new an entry in the system-wide table of open files. This entry records the file offset and the file status flags (modifiable via the -.BR fcntl () +.BR fcntl (2) .B F_SETFL operation). A file descriptor is a reference to one of these entries; @@ -118,10 +118,10 @@ The full list of file creation flags and file status flags is as follows: .B O_APPEND The file is opened in append mode. Before each -.BR write (), +.BR write (2), the file offset is positioned at the end of the file, as if with -.BR lseek (). +.BR lseek (2). .B O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. @@ -203,7 +203,7 @@ 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() returns 0, the lock is +If \fBlink\fP(2) returns 0, the lock is successful. Otherwise, use .BR stat (2) @@ -273,7 +273,7 @@ in conjunction with mandatory file locks and with file leases, see .B O_SYNC The file is opened for synchronous I/O. Any -.BR write ()s +.BR write (2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware. .IR "But see RESTRICTIONS below" . @@ -286,7 +286,7 @@ flag is ignored. Otherwise the effect of O_TRUNC is unspecified. .PP Some of these optional flags can be altered using -.BR fcntl () +.BR fcntl (2) after the file has been opened. The argument diff --git a/man2/openat.2 b/man2/openat.2 index b11c3d54a..49911bee0 100644 --- a/man2/openat.2 +++ b/man2/openat.2 @@ -106,9 +106,9 @@ occur when using to open files in directories other than the current working directory. These race conditions result from the fact that some component of the directory prefix given to -.BR open () +.BR open (2) could be changed in parallel with the call to -.BR open (). +.BR open (2). Such races can be avoided by opening a file descriptor for the target directory, and then specifying that file descriptor as the diff --git a/man2/poll.2 b/man2/poll.2 index 6348422b5..766d28508 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -176,11 +176,11 @@ The relationship between and .BR ppoll () is analogous to the relationship between -.BR select () +.BR select (2) and -.BR pselect (): +.BR pselect (2): like -.BR pselect (), +.BR pselect (2), .BR ppoll () allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. @@ -294,7 +294,7 @@ system call was introduced in Linux 2.1.23. The .BR poll () library call was introduced in libc 5.4.28 -(and provides emulation using select() if your kernel does not +(and provides emulation using select(2) if your kernel does not have a .BR poll () system call). diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 index cd9a00823..446441820 100644 --- a/man2/posix_fadvise.2 +++ b/man2/posix_fadvise.2 @@ -113,7 +113,7 @@ 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() or \fBfdatasync\fP() first. +call \fBfsync\fP(2) or \fBfdatasync\fP(2) first. .SH "CONFORMING TO" POSIX.1-2001. Note that the type of the diff --git a/man2/prctl.2 b/man2/prctl.2 index a64fa7d70..767bfe8dc 100644 --- a/man2/prctl.2 +++ b/man2/prctl.2 @@ -57,7 +57,7 @@ in the range 1..maxsig, or 0 to clear). This is the signal that the calling process will get when its parent dies. This value is cleared upon a -.BR fork (). +.BR fork (2). .TP .B PR_GET_PDEATHSIG (Since Linux 2.3.15) diff --git a/man2/ptrace.2 b/man2/ptrace.2 index 8afe00f15..8db4f6b62 100644 --- a/man2/ptrace.2 +++ b/man2/ptrace.2 @@ -88,9 +88,9 @@ Indicates that this process is to be traced by its parent. Any signal (except SIGKILL) delivered to this process will cause it to stop and its parent to be notified via -.BR wait (). +.BR wait (2). Also, all subsequent calls to -.BR exec () +.BR execve (2) by this process will cause a SIGTRAP to be sent to it, giving the parent a chance to gain control before the new program begins execution. @@ -197,7 +197,7 @@ between normal traps and those caused by a syscall. .TP PTRACE_O_TRACEFORK (since Linux 2.5.46) Stop the child at the next -.BR fork () +.BR fork (2) call with SIGTRAP | PTRACE_EVENT_FORK << 8 and automatically start tracing the newly forked process, which will start with a SIGSTOP. @@ -205,36 +205,36 @@ The PID for the new process can be retrieved with PTRACE_GETEVENTMSG. .TP PTRACE_O_TRACEVFORK (since Linux 2.5.46) Stop the child at the next -.BR vfork () +.BR vfork (2) call with SIGTRAP | PTRACE_EVENT_VFORK << 8 and automatically start tracing the newly vforked process, which will start with a SIGSTOP. The PID for the new process can be retrieved with PTRACE_GETEVENTMSG. .TP PTRACE_O_TRACECLONE (since Linux 2.5.46) Stop the child at the next -.BR clone () +.BR clone (2) call with SIGTRAP | PTRACE_EVENT_CLONE << 8 and automatically start tracing the newly cloned process, which will start with a SIGSTOP. The PID for the new process can be retrieved with PTRACE_GETEVENTMSG. This option may not catch -.BR clone () +.BR clone (2) calls in all cases. If the child calls -.BR clone () +.BR clone (2) with the CLONE_VFORK flag, PTRACE_EVENT_VFORK will be delivered instead if PTRACE_O_TRACEVFORK is set; otherwise if the child calls -.BR clone () +.BR clone (2) with the exit signal set to SIGCHLD, PTRACE_EVENT_FORK will be delivered if PTRACE_O_TRACEFORK is set. .TP PTRACE_O_TRACEEXEC (since Linux 2.5.46) Stop the child at the next -.BR exec () +.BR execve (2) call with SIGTRAP | PTRACE_EVENT_EXEC << 8. .TP PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60) Stop the child at the completion of the next -.BR vfork () +.BR vfork (2) call with SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8. .TP PTRACE_O_TRACEEXIT (since Linux 2.5.60) @@ -310,7 +310,7 @@ output as the child's parent), but a by the child will still return the PID of the original parent. The child is sent a SIGSTOP, but will not necessarily have stopped by the completion of this call; use -.BR wait () +.BR wait (2) to wait for the child to stop. (\fIaddr\fP and \fIdata\fP are ignored.) .TP @@ -347,7 +347,7 @@ Tracing causes a few subtle differences in the semantics of traced processes. For example, if a process is attached to with PTRACE_ATTACH, its original parent can no longer receive notification via -.BR wait () +.BR wait (2) when it stops, and there is no way for the new parent to effectively simulate this notification. .LP @@ -357,7 +357,7 @@ This means the parent cannot do .BR ptrace (PTRACE_CONT) with a signal or .BR ptrace (PTRACE_KILL). -.BR kill () +.BR kill (2) with a SIGKILL signal can be used instead to kill the child process after receiving one of these messages. .LP diff --git a/man2/readv.2 b/man2/readv.2 index a5eac63e2..0bd058e4a 100644 --- a/man2/readv.2 +++ b/man2/readv.2 @@ -178,7 +178,7 @@ the wrapper function allocates a temporary buffer large enough for all of the items specified by .IR iov , passes that buffer in a call to -.BR read (), +.BR read (2), copies data from the buffer to the locations specified by the .I iov_base fields of the elements of @@ -187,7 +187,7 @@ and then frees the buffer. The wrapper function for .BR writev () performs the analogous task using a temporary buffer and a call to -.BR write (). +.BR write (2). .SH BUGS It is not advisable to mix calls to functions like .BR readv () diff --git a/man2/remap_file_pages.2 b/man2/remap_file_pages.2 index e05e8aba9..0f5be6452 100644 --- a/man2/remap_file_pages.2 +++ b/man2/remap_file_pages.2 @@ -48,7 +48,7 @@ To create a non-linear mapping we perform the following steps: .TP \fB1.\fP Use -.BR mmap () +.BR mmap (2) to create a mapping (which is initially linear). This mapping must be created with the .B MAP_SHARED @@ -81,7 +81,7 @@ Thus, .I start must be an address that falls within a region previously mapped by a call to -.BR mmap (). +.BR mmap (2). Second, .I start specifies the address at which the file pages @@ -112,7 +112,7 @@ argument must be specified as 0. The .I flags argument has the same meaning as for -.BR mmap (), +.BR mmap (2), but all flags other than .B MAP_NONBLOCK are ignored. diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2 index 228854d01..dc62559dc 100644 --- a/man2/sched_setscheduler.2 +++ b/man2/sched_setscheduler.2 @@ -110,8 +110,8 @@ 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() and -\fBsched_get_priority_max\fP() can be used to find out the valid +The system calls \fBsched_get_priority_min\fP(2) and +\fBsched_get_priority_max\fP(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 +137,7 @@ 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() will put the +\fBsched_setscheduler\fP() or \fBsched_setparam\fP(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 +146,14 @@ 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() will be +A process calling \fBsched_yield\fP(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(). +preempted by a higher priority process, or it calls \fBsched_yield\fP(2). .SS SCHED_RR: Round Robin scheduling \fISCHED_RR\fP is a simple enhancement of \fISCHED_FIFO\fP. Everything @@ -265,15 +265,15 @@ interrupt handler. .\" .BR request_irq (9). .SS Miscellaneous Child processes inherit the scheduling algorithm and parameters across a -.BR fork (). +.BR fork (2). The scheduling algorithm and parameters are preserved across .BR execve (2). Memory locking is usually needed for real-time processes to avoid paging delays, this can be done with -.BR mlock () +.BR mlock (2) or -.BR mlockall (). +.BR mlockall (2). As a non-blocking end-less loop in a process scheduled under \fISCHED_FIFO\fP or \fISCHED_RR\fP will block all processes with lower diff --git a/man2/select_tut.2 b/man2/select_tut.2 index 1506e3f08..96b544ae6 100644 --- a/man2/select_tut.2 +++ b/man2/select_tut.2 @@ -86,8 +86,9 @@ 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 \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 a newly declared set. Thereafter, the individual file descriptors that you are interested in can be added one by one with \fBFD_SET\fP(). @@ -95,7 +96,8 @@ you are interested in can be added one by one with \fBFD_SET\fP(). 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 -it is not. \fBFD_CLR\fP() removes a file descriptor from the set. +it is not. +\fBFD_CLR\fP() removes a file descriptor from the set. .SH ARGUMENTS .TP \fIreadfds\fP @@ -103,16 +105,16 @@ 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 cleared of all file descriptors except for those file descriptors that -are immediately available for reading with a \fBrecv\fP() (for sockets) or -\fBread\fP() (for pipes, files, and sockets) call. +are immediately available for reading with a \fBrecv\fP(2) (for sockets) or +\fBread\fP(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 cleared of all file descriptors except for those file descriptors that -are immediately available for writing with a \fBsend\fP() (for sockets) or -\fBwrite\fP() (for pipes, files, and sockets) call. +are immediately available for writing with a \fBsend\fP(2) (for sockets) or +\fBwrite\fP(2) (for pipes, files, and sockets) call. .TP \fIexceptfds\fP This set is watched for exceptions or errors on any of the file @@ -129,8 +131,8 @@ After \fBselect\fP() 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()), and -writing OOB data (done with \fBsend\fP()) can be done at any time and will +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 not block. Hence there is no need for a fourth set to check if a socket is available for writing OOB data. @@ -209,7 +211,7 @@ mask out signals that are not to be received except within the 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(). +would block \fBSIGCHLD\fP using \fBsigprocmask\fP(2). Our \fBpselect\fP() call would enable \fBSIGCHLD\fP by using the virgin signal mask. Our @@ -258,7 +260,7 @@ 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() and \fBwrite\fP() calls, you would +merely create a sequence of \fBread\fP(2) and \fBwrite\fP(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. @@ -543,12 +545,12 @@ 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() +You might think it more efficient to use a \fBfork\fP(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() call. +\fBioctl\fP(2) call. This also has its problems because you end up having to have inefficient timeouts. @@ -595,8 +597,8 @@ should be checked to see if they are ready. .\" available for reading \fImust\fP be read, etc. .TP \fB5.\fP -The functions \fBread\fP(), \fBrecv\fP(), \fBwrite\fP(), and -\fBsend\fP() do \fInot\fP necessarily read/write the full amount of data +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 that you have requested. If they do read/write the full amount, its because you have a low traffic load and a fast stream. @@ -614,8 +616,8 @@ The buffers in the example above are 1024 bytes although they could easily be made larger. .TP \fB7.\fP -The functions \fBread\fP(), \fBrecv\fP(), \fBwrite\fP(), and -\fBsend\fP() as well as the \fBselect\fP() call can return \-1 with +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 .I errno set to \fBEINTR\fP, or with @@ -631,12 +633,12 @@ Nonetheless you should still cope with these errors for completeness. .TP \fB8.\fP -Never call \fBread\fP(), \fBrecv\fP(), \fBwrite\fP(), or \fBsend\fP() +Never call \fBread\fP(2), \fBrecv\fP(2), \fBwrite\fP(2), or \fBsend\fP(2) with a buffer length of zero. .TP \fB9.\fP -If the functions \fBread\fP(), -\fBrecv\fP(), \fBwrite\fP(), and \fBsend\fP() fail +If the functions \fBread\fP(2), +\fBrecv\fP(2), \fBwrite\fP(2), and \fBsend\fP(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 @@ -648,8 +650,8 @@ to prevent it being included in a set. .TP \fB10.\fP The timeout value must be initialized with each new call to \fBselect\fP(), -since some operating systems modify the structure. \fBpselect\fP() -however does not modify its timeout structure. +since some operating systems modify the structure. +\fBpselect\fP() however does not modify its timeout structure. .TP \fB11.\fP I have heard that the Windows socket layer does not cope with OOB data @@ -660,7 +662,7 @@ 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() function, you can call +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 follows: .PP diff --git a/man2/semctl.2 b/man2/semctl.2 index dab331939..a709b748a 100644 --- a/man2/semctl.2 +++ b/man2/semctl.2 @@ -100,7 +100,7 @@ structure is defined in as follows .nf .in +4n struct ipc_perm { - key_t key; /* Key supplied to semget() */ + key_t key; /* Key supplied to semget(2) */ uid_t \fBuid\fP; /* Effective UID of owner */ gid_t \fBgid\fP; /* Effective GID of owner */ uid_t cuid; /* Effective UID of creator */ @@ -153,7 +153,7 @@ is ignored. .B IPC_RMID Immediately remove the semaphore set, awakening all processes blocked in -.BR semop () +.BR semop (2) calls on the set (with an error return and .I errno set to @@ -186,7 +186,7 @@ struct seminfo { int semmnu; /* System-wide max. # of undo structures; unused */ int semmsl; /* Max. # of semaphores in a set */ - int semopm; /* Max. # of operations for semop() */ + int semopm; /* Max. # of operations for semop(2) */ int semume; /* Max. # of undo entries per process; unused */ int semusz; /* size of struct sem_undo */ @@ -266,7 +266,7 @@ for the .IR semnum \-th semaphore of the set (i.e. the PID of the process that executed the last -.BR semop () +.BR semop (2) call for the .IR semnum \-th semaphore of the set). @@ -308,7 +308,7 @@ Undo entries (see .BR semop (2)) are cleared for altered semaphores in all processes. If the changes to semaphore values would permit blocked -.BR semop () +.BR semop (2) calls in other processes to proceed, then those processes are woken up. The argument .I semnum @@ -330,7 +330,7 @@ member of the structure associated with the set. Undo entries are cleared for altered semaphores in all processes. If the changes to semaphore values would permit blocked -.BR semop () +.BR semop (2) calls in other processes to proceed, then those processes are woken up. The calling process must have alter permission on the semaphore set. .SH "RETURN VALUE" diff --git a/man2/semget.2 b/man2/semget.2 index 7d54fa059..ae9a3cba1 100644 --- a/man2/semget.2 +++ b/man2/semget.2 @@ -269,7 +269,7 @@ operation on the semaphore set. initialise the set, checking for a non-zero .I sem_otime in the associated data structure retrieved by a -.BR semctl () +.BR semctl (2) .B IPC_STAT operation can be used to avoid races.) .SH "CONFORMING TO" diff --git a/man2/send.2 b/man2/send.2 index ab743078c..bb949b820 100644 --- a/man2/send.2 +++ b/man2/send.2 @@ -69,7 +69,7 @@ state (so that the intended recipient is known). The only difference between .BR send () and -.BR write () +.BR write (2) is the presence of .IR flags . With zero @@ -77,7 +77,7 @@ With zero parameter, .BR send () is equivalent to -.BR write (). +.BR write (2). Also, .RI send( s , buf , len , flags ) is equivalent to diff --git a/man2/sendfile.2 b/man2/sendfile.2 index ad70a1f2d..dba7e0383 100644 --- a/man2/sendfile.2 +++ b/man2/sendfile.2 @@ -83,7 +83,7 @@ is the number of bytes to copy between the file descriptors. Presently (Linux 2.6.9): .IR in_fd , must correspond to a file which supports -.BR mmap ()-like +.BR mmap (2)-like operations (i.e., it cannot be a socket); and @@ -134,7 +134,7 @@ Bad address. .TP .B EINVAL Descriptor is not valid or locked, or an -.BR mmap ()-like +.BR mmap (2)-like operation is not available for .IR in_fd . .TP diff --git a/man2/setfsgid.2 b/man2/setfsgid.2 index ef381d45a..0908df893 100644 --- a/man2/setfsgid.2 +++ b/man2/setfsgid.2 @@ -48,7 +48,7 @@ effective group ID is changed, will also be changed to the new value of the effective group ID. Explicit calls to -.BR setfsuid () +.BR setfsuid (2) and .BR setfsgid () are usually only used by programs such as the Linux NFS server that diff --git a/man2/setfsuid.2 b/man2/setfsuid.2 index c0f671ac6..e2bf45405 100644 --- a/man2/setfsuid.2 +++ b/man2/setfsuid.2 @@ -50,7 +50,7 @@ will also be changed to the new value of the effective user ID. Explicit calls to .BR setfsuid () and -.BR setfsgid () +.BR setfsgid (2) are usually only used by programs such as the Linux NFS server that need to change what user and group ID is used for file access without a corresponding change in the real and effective user and group IDs. diff --git a/man2/setpgid.2 b/man2/setpgid.2 index 771291785..21d54972c 100644 --- a/man2/setpgid.2 +++ b/man2/setpgid.2 @@ -141,7 +141,7 @@ 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() +already performed an \fBexecve\fP(2) (\fBsetpgid\fP(), \fBsetpgrp\fP()). .TP .B EINVAL diff --git a/man2/setsid.2 b/man2/setsid.2 index d0f4ea3d6..75cd1a2b1 100644 --- a/man2/setsid.2 +++ b/man2/setsid.2 @@ -70,9 +70,9 @@ to its PID. In order to be sure that .BR setsid () will succeed, -.BR fork () +.BR fork (2) and -.BR exit (), +.BR _exit (2), and have the child do .BR setsid (). .SH "CONFORMING TO" diff --git a/man2/setuid.2 b/man2/setuid.2 index 80cbc3e66..56ed6f331 100644 --- a/man2/setuid.2 +++ b/man2/setuid.2 @@ -62,7 +62,7 @@ privileges, assume the identity of a non-root user, and then regain root privileges afterwards cannot use .BR setuid (). You can accomplish this with the (non-POSIX, BSD) call -.BR seteuid (). +.BR seteuid (2). .SH "RETURN VALUE" On success, zero is returned. On error, \-1 is returned, and diff --git a/man2/shmctl.2 b/man2/shmctl.2 index 923110b7b..1a49e218e 100644 --- a/man2/shmctl.2 +++ b/man2/shmctl.2 @@ -71,7 +71,7 @@ struct shmid_ds { time_t shm_dtime; /* Last detach time */ time_t shm_ctime; /* Last change time */ pid_t shm_cpid; /* PID of creator */ - pid_t shm_lpid; /* PID of last shmat()/shmdt() */ + pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */ shmatt_t shm_nattch; /* No. of current attaches */ ... }; @@ -87,7 +87,7 @@ structure is defined in as follows .in +4n .nf struct ipc_perm { - key_t key; /* Key supplied to shmget() */ + key_t key; /* Key supplied to shmget(2) */ uid_t \fBuid\fP; /* Effective UID of owner */ gid_t \fBgid\fP; /* Effective GID of owner */ uid_t cuid; /* Effective UID of creator */ @@ -367,7 +367,7 @@ In the future these may modified or moved to a /proc file system interface. Linux permits a process to attach -.RB ( shmat ()) +.RB ( shmat (2)) a shared memory segment that has already been marked for deletion using .IR shmctl(IPC_RMID) . diff --git a/man2/shmget.2 b/man2/shmget.2 index 3e772fd2e..aeb75f8f7 100644 --- a/man2/shmget.2 +++ b/man2/shmget.2 @@ -174,19 +174,19 @@ If the shared memory segment already exists, the permissions are verified, and a check is made to see if it is marked for destruction. .SH "SYSTEM CALLS" .TP -.BR fork () +.BR fork (2) After a -.BR fork () +.BR fork (2) the child inherits the attached shared memory segments. .TP -.BR exec () +.BR execve (2) After an -.BR exec () +.BR execve (2) all attached shared memory segments are detached (not destroyed). .TP -.BR exit () +.BR _exit (2) Upon -.BR exit () +.BR _exit (2) all attached shared memory segments are detached (not destroyed). .SH "RETURN VALUE" A valid segment identifier, diff --git a/man2/shmop.2 b/man2/shmop.2 index 88094794e..d47198925 100644 --- a/man2/shmop.2 +++ b/man2/shmop.2 @@ -36,7 +36,7 @@ .\" .TH SHMOP 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual" .SH NAME -shmop \- shared memory operations +shmop, shmat, shmdt \- shared memory operations .SH SYNOPSIS .nf .B @@ -158,19 +158,19 @@ If it becomes 0 and the segment is marked for deletion, the segment is deleted. .SH "SYSTEM CALLS" .TP 11 -.BR fork () +.BR fork (2) After a -.BR fork () +.BR fork (2) the child inherits the attached shared memory segments. .TP -.BR exec () +.BR execve (2) After an -.BR exec () +.BR execve (2) all attached shared memory segments are detached from the process. .TP -.BR exit () +.BR _exit (2) Upon -.BR exit () +.BR _exit (2) all attached shared memory segments are detached from the process. .SH "RETURN VALUE" On success @@ -206,7 +206,7 @@ value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not specified) or invalid .I shmaddr value, or failing attach at -.BR brk (), +.BR brk (2), .\" FIXME What does "failing attach at brk" mean? (Is this phrase .\" just junk?) or diff --git a/man2/sigaction.2 b/man2/sigaction.2 index ba640ddbd..f2166b1eb 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -272,14 +272,14 @@ c s l l. \fIsi_code\fR Value:Signal origin -SI_USER:kill(), sigsend(), or raise() +SI_USER:kill(2), sigsend(2), or raise(3) SI_KERNEL:The kernel -SI_QUEUE:sigqueue() +SI_QUEUE:sigqueue(2) SI_TIMER:POSIX timer expired SI_MESGQ:POSIX message queue state changed (since Linux 2.6.6) SI_ASYNCIO:AIO completed SI_SIGIO:queued SIGIO -SI_TKILL:tkill() or tgkill() (since Linux 2.4.19) +SI_TKILL:tkill(2) or tgkill(2) (since Linux 2.4.19) .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented .\" It appears to have been an idea that was tried during 2.5.6 .\" through to 2.5.24 and then was backed out. @@ -392,9 +392,9 @@ ignores a or .BR SIGSEGV signal that was not generated by -.BR kill () +.BR kill (2) or -.BR raise (). +.BR raise (3). Integer division by zero has undefined result. On some architectures it will generate a .B SIGFPE diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 index 8f7cf2223..f93c81556 100644 --- a/man2/sigaltstack.2 +++ b/man2/sigaltstack.2 @@ -47,7 +47,7 @@ Use \fBsigaltstack\fP() to inform the system of the existence and location of the alternate signal stack. .TP 3. -When establishing a signal handler using \fBsigaction\fP(), +When establishing a signal handler using \fBsigaction\fP(2), inform the system that the signal handler should be executed on the alternate signal stack by specifying the \fBSA_ONSTACK\fP flag. @@ -160,7 +160,8 @@ In these circumstances the only way to catch this signal is on an alternate signal stack. .P On most hardware architectures supported by Linux, stacks grow -downwards. \fBsigaltstack\fP() automatically takes account +downwards. +\fBsigaltstack\fP() automatically takes account of the direction of stack growth. .P Functions called from a signal handler executing on an alternate @@ -172,7 +173,7 @@ 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() removes any existing alternate +A successful call to \fBexecve\fP(2) removes any existing alternate signal stack. .P \fBsigaltstack\fP() supersedes the older \fBsigstack\fP() call. diff --git a/man2/sigsuspend.2 b/man2/sigsuspend.2 index ae1422ffe..0c84361eb 100644 --- a/man2/sigsuspend.2 +++ b/man2/sigsuspend.2 @@ -69,16 +69,16 @@ The call was interrupted by a signal. Normally, .BR sigsuspend () is used in conjunction with -.BR sigprocmask () +.BR sigprocmask (2) in order to prevent delivery of a signal during the execution of a critical code section. The caller first blocks the signals with -.BR sigprocmask (). +.BR sigprocmask (2). When the critical code has completed, the caller then waits for the signals by calling .BR sigsuspend () with the signal mask that was returned by -.BR sigprocmask () +.BR sigprocmask (2) (in the .IR oldset argument). diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2 index bc2b6aed7..ceeb8dcd6 100644 --- a/man2/sigwaitinfo.2 +++ b/man2/sigwaitinfo.2 @@ -114,7 +114,7 @@ was invalid. In normal usage, the calling program blocks the signals in .I set via a prior call to -.BR sigprocmask () +.BR sigprocmask (2) (so that the default disposition for these signals does not occur if they are delivered between successive calls to .BR sigwaitinfo () diff --git a/man2/splice.2 b/man2/splice.2 index defc55016..3ec60bac8 100644 --- a/man2/splice.2 +++ b/man2/splice.2 @@ -171,10 +171,10 @@ In overview, these system calls perform the following tasks: moves data from the buffer to an arbitrary file descriptor, or vice versa, or from one buffer to another. .TP -.BR tee () +.BR tee (2) "copies" the data from one buffer to another. .TP -.BR vmsplice () +.BR vmsplice (2) "copies" data from user space into the buffer. .PP Though we talk of copying, actual copies are generally avoided. diff --git a/man2/statfs.2 b/man2/statfs.2 index ab1374e3a..e96979184 100644 --- a/man2/statfs.2 +++ b/man2/statfs.2 @@ -200,9 +200,9 @@ LSB has deprecated the library calls and .BR fstatfs () and tells us to use -.BR statvfs () +.BR statvfs (2) and -.BR fstatvfs () +.BR fstatvfs (2) instead. .SS The f_fsid field Solaris, Irix and POSIX have a system call diff --git a/man2/statvfs.2 b/man2/statvfs.2 index 4631025f4..e2b4850f8 100644 --- a/man2/statvfs.2 +++ b/man2/statvfs.2 @@ -154,9 +154,9 @@ Some values were too large to be represented in the returned struct. POSIX.1-2001 .SH NOTES The Linux kernel has system calls -.BR statfs () +.BR statfs (2) and -.BR fstatfs () +.BR fstatfs (2) to support this library call. The current glibc implementations of diff --git a/man2/symlink.2 b/man2/symlink.2 index e5488d6f1..4a6934934 100644 --- a/man2/symlink.2 +++ b/man2/symlink.2 @@ -136,7 +136,7 @@ is done. Deleting the name referred to by a symlink will actually delete the file (unless it also has other hard links). If this behaviour is not desired, use -.BR link (). +.BR link (2). .SH "CONFORMING TO" SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional error codes EDQUOT and ENOSYS. diff --git a/man2/times.2 b/man2/times.2 index f17a70f95..7278c5c5f 100644 --- a/man2/times.2 +++ b/man2/times.2 @@ -132,7 +132,7 @@ and .I tms_cutime fields, although POSIX.1-2001 says that this should only happen if the calling process -.BR wait ()s +.BR wait (2)s on its children. This non-conformance is rectified in Linux 2.6.9 and later. .\" See the description of times() in XSH, which says: diff --git a/man2/tkill.2 b/man2/tkill.2 index 43e927f22..cb966ac30 100644 --- a/man2/tkill.2 +++ b/man2/tkill.2 @@ -50,7 +50,7 @@ The \fBtkill\fP() system call is analogous to 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(). +they cannot be individually signalled with \fBkill\fP(2). With \fBtkill\fP(), however, one can address each process by its unique TID. .PP diff --git a/man2/uname.2 b/man2/uname.2 index 4e66b7b1e..091a22722 100644 --- a/man2/uname.2 +++ b/man2/uname.2 @@ -115,7 +115,7 @@ used length 9, the second one used 65, the third one also uses 65 but adds the \fIdomainname\fP field. .LP Part of the utsname information is also accessible via -.BR sysctl () +.BR sysctl (2) and via .IR /proc/sys/kernel/ { ostype , .IR hostname , diff --git a/man2/vfork.2 b/man2/vfork.2 index 0ae5e628d..f49ac8905 100644 --- a/man2/vfork.2 +++ b/man2/vfork.2 @@ -37,7 +37,7 @@ vfork \- create a child process and block parent The .BR vfork () function has the same effect as -.BR fork (), +.BR fork (2), except that the behaviour is undefined if the process created by .BR vfork () either modifies any data other than a variable of type @@ -47,7 +47,7 @@ used to store the return value from or returns from the function in which .BR vfork () was called, or calls any other function before successfully calling -.BR _exit () +.BR _exit (2) or one of the .BR exec () family of functions. @@ -66,35 +66,35 @@ It is used to create new processes without copying the page tables of the parent process. It may be useful in performance sensitive applications where a child will be created which then immediately issues an -.BR execve () . +.BR execve (2) . .PP .BR vfork () differs from -.BR fork () +.BR fork (2) in that the parent is suspended until the child makes a call to .BR execve (2) or .BR _exit (2). The child shares all memory with its parent, including the stack, until -.BR execve () +.BR execve (2) is issued by the child. The child must not return from the current function or call -.BR exit (), +.BR exit (3), but may call -.BR _exit (). +.BR _exit (2). .PP Signal handlers are inherited, but not shared. Signals to the parent arrive after the child releases the parent's memory. .SH "HISTORIC DESCRIPTION" Under Linux, -.BR fork () +.BR fork (2) is implemented using copy-on-write pages, so the only penalty incurred by -.BR fork () +.BR fork (2) is the time and memory required to duplicate the parent's page tables, and to create a unique task structure for the child. However, in the bad old days a -.BR fork () +.BR fork (2) would require making a complete copy of the caller's data space, often needlessly, since usually immediately afterwards an .BR exec () @@ -104,7 +104,7 @@ Thus, for greater efficiency, BSD introduced the system call, that did not fully copy the address space of the parent process, but borrowed the parent's memory and thread of control until a call to -.BR execve () +.BR execve (2) or an exit occurred. The parent process was suspended while the child was using its resources. @@ -121,7 +121,7 @@ are implemented. Users should not depend on the memory sharing semantics of .BR vfork () as it will, in that case, be made synonymous to -.BR fork ().\c +.BR fork (2).\c " Details of the signal handling are obscure and differ between systems. @@ -146,11 +146,11 @@ system call appeared in 3.0BSD. .\" In the release notes for 4.2BSD Sam Leffler wrote: `vfork: Is still .\" present, but definitely on its way out'. In 4.4BSD it was made synonymous to -.BR fork () +.BR fork (2) but NetBSD introduced it again, cf. http://www.netbsd.org/Documentation/kernel/vfork.html . In Linux, it has been equivalent to -.BR fork () +.BR fork (2) until 2.2.0-pre6 or so. Since 2.2.0-pre9 (on i386, somewhat later on other architectures) it is an independent system call. @@ -162,13 +162,13 @@ Support was added in glibc 2.0.112. The requirements put on .BR vfork () by the standards are weaker than those put on -.BR fork (), +.BR fork (2), so an implementation where the two are synonymous is compliant. In particular, the programmer cannot rely on the parent remaining blocked until a call of -.BR execve () +.BR execve (2) or -.BR _exit () +.BR _exit (2) and cannot rely on any specific behaviour w.r.t. shared memory. .\" In AIXv3.1 vfork is equivalent to fork. .SH "LINUX NOTES" diff --git a/man2/vmsplice.2 b/man2/vmsplice.2 index 662730876..e91a05cd1 100644 --- a/man2/vmsplice.2 +++ b/man2/vmsplice.2 @@ -100,11 +100,11 @@ The application may not modify this memory ever, .\" FIXME Explain the following line in a little more detail: or page cache and on-disk data may differ. Gifting pages to the kernel means that a subsequent -.BR splice () +.BR splice (2) .B SPLICE_F_MOVE can successfully move the pages; if this flag is not specified, then a subsequent -.BR splice () +.BR splice (2) .B SPLICE_F_MOVE must copy the pages. Data must also be properly page aligned, both in memory and length. diff --git a/man2/wait.2 b/man2/wait.2 index 5c9b41500..612e8fde5 100644 --- a/man2/wait.2 +++ b/man2/wait.2 @@ -48,7 +48,7 @@ .\" .TH WAIT 2 2004-11-11 "Linux" "Linux Programmer's Manual" .SH NAME -wait, waitpid \- wait for process to change state +wait, waitpid, waitid \- wait for process to change state .SH SYNOPSIS .B #include .br @@ -186,9 +186,9 @@ returns the exit status of the child. This consists of the least significant 8 bits of the .I status argument that the child specified in a call to -.BR exit () +.BR exit (3) or -.BR _exit () +.BR _exit (2) or as the argument for a return statement in main(). This macro should only be employed if .B WIFEXITED diff --git a/man2/write.2 b/man2/write.2 index bf430072d..ea2c2f8dd 100644 --- a/man2/write.2 +++ b/man2/write.2 @@ -45,7 +45,7 @@ bytes to the file referenced by the file descriptor .I fd from the buffer starting at .IR buf . -POSIX requires that a \fBread\fP() which can be proved to occur after a +POSIX requires that a \fBread\fP(2) which can be proved to occur after a \fBwrite\fP() has returned returns the new data. Note that not all file systems are POSIX conforming.