From 682edefb1bfc4e86ac804cff0e15c5d880fda907 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 22 Jun 2007 17:16:20 +0000 Subject: [PATCH] ffix --- man1/time.1 | 25 ++++++++++++---- man2/__clone.2 | 11 +++++-- man2/accept.2 | 3 +- man2/acct.2 | 2 +- man2/alloc_hugepages.2 | 15 +++++++--- man2/capget.2 | 8 ++++-- man2/chmod.2 | 28 +++++++++--------- man2/chown.2 | 15 +++++++--- man2/clone.2 | 11 +++++-- man2/epoll_ctl.2 | 10 +++++-- man2/execve.2 | 3 +- man2/fcntl.2 | 5 ++-- man2/futex.2 | 65 ++++++++++++++++++++++++++++++------------ man2/getgroups.2 | 4 ++- man2/gethostname.2 | 7 +++-- man2/getitimer.2 | 3 +- man2/getpagesize.2 | 5 +++- man2/getpriority.2 | 4 ++- man2/getresuid.2 | 4 ++- man2/getrlimit.2 | 8 ++++-- man2/getsid.2 | 10 +++++-- man2/gettid.2 | 4 ++- man2/getxattr.2 | 9 ++++-- man2/ioctl.2 | 4 ++- man2/ioprio_set.2 | 6 ++-- man2/killpg.2 | 12 +++++--- man2/listxattr.2 | 6 ++-- man2/lookup_dcookie.2 | 4 ++- man2/lseek.2 | 5 +++- man2/madvise.2 | 15 +++++++--- man2/mkdir.2 | 5 ++-- man2/mknod.2 | 7 +++-- man2/mmap.2 | 4 ++- man2/mount.2 | 16 ++++++++--- man2/mremap.2 | 7 +++-- man2/msgctl.2 | 8 ++++-- man2/msgget.2 | 8 ++++-- man2/msync.2 | 17 +++++++---- man2/nice.2 | 4 ++- man2/open.2 | 27 +++++++++++++----- man2/pciconfig_read.2 | 12 ++++++-- man2/poll.2 | 4 ++- man2/posix_fadvise.2 | 7 +++-- man2/read.2 | 12 ++++++-- man2/reboot.2 | 30 +++++++++++++------ man2/removexattr.2 | 6 ++-- man2/rename.2 | 8 ++++-- man2/select.2 | 8 ++++-- man2/semctl.2 | 8 ++++-- man2/semget.2 | 4 ++- 50 files changed, 368 insertions(+), 145 deletions(-) diff --git a/man1/time.1 b/man1/time.1 index 7186d9f68..0b7fe9bef 100644 --- a/man1/time.1 +++ b/man1/time.1 @@ -61,8 +61,16 @@ Otherwise it is 127 if could not be found, 126 if it could be found but could not be invoked, and some other non-zero value (1-125) if something else went wrong. .SH ENVIRONMENT -The variables LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_NUMERIC, -NLSPATH and PATH are used. +The variables +.BR LANG , +.BR LC_ALL , +.BR LC_CTYPE , +.BR LC_MESSAGES , +.BR LC_NUMERIC , +.BR NLSPATH, +and +.B PATH +are used. The last one to search for .IR command . The remaining ones for the text and formatting of the output. @@ -73,7 +81,9 @@ Disregarding the name of the utility, GNU makes it output lots of useful information, not only about time used, but also on other resources like memory, I/O and IPC calls (where available). The output is formatted using a format string that can be specified -using the \-f option or the TIME environment variable. +using the \-f option or the +.BR TIME +environment variable. .LP The default format string is .br @@ -230,8 +240,13 @@ provided by 4.2 or 4.3BSD. GNU time version 1.7 is not yet localized. Thus, it does not implement the POSIX requirements. .LP -The environment variable TIME was badly chosen. -It is not unusual for systems like autoconf or make +The environment variable +.BR TIME +was badly chosen. +It is not unusual for systems like +.BR autoconf (1) +or +.BR make (1) to use environment variables with the name of a utility to override the utility to be used. Uses like MORE or TIME for options to programs diff --git a/man2/__clone.2 b/man2/__clone.2 index bc6c49f38..954c87edf 100644 --- a/man2/__clone.2 +++ b/man2/__clone.2 @@ -504,7 +504,9 @@ parameter is the new TLS (Thread Local Storage) descriptor. Store child thread ID at location .I parent_tidptr in parent and child memory. -(In Linux 2.5.32-2.5.48 there was a flag CLONE_SETTID that did this.) +(In Linux 2.5.32-2.5.48 there was a flag +.BR CLONE_SETTID +that did this.) .TP .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" Store child thread ID at location @@ -553,11 +555,14 @@ Since Linux 2.5.49 the system call has five parameters. The two new parameters are .I parent_tidptr which points to the location (in parent and child memory) where -the child thread ID will be written in case CLONE_PARENT_SETTID +the child thread ID will be written in case +.B CLONE_PARENT_SETTID was specified, and .I child_tidptr which points to the location (in child memory) where the child thread ID -will be written in case CLONE_CHILD_SETTID was specified. +will be written in case +.B CLONE_CHILD_SETTID +was specified. .SH "RETURN VALUE" .\" gettid(2) returns current->pid; .\" getpid(2) returns current->tgid; diff --git a/man2/accept.2 b/man2/accept.2 index b25b86b8b..73806681b 100644 --- a/man2/accept.2 +++ b/man2/accept.2 @@ -98,7 +98,8 @@ blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, .BR accept () -fails with the error EAGAIN. +fails with the error +.BR EAGAIN . .PP In order to be notified of incoming connections on a socket, you can use .BR select (2) diff --git a/man2/acct.2 b/man2/acct.2 index 1586a7245..6d7bd143f 100644 --- a/man2/acct.2 +++ b/man2/acct.2 @@ -96,7 +96,7 @@ Out of memory. BSD process accounting has not been enabled when the operating system kernel was compiled. The kernel configuration parameter controlling this feature is -CONFIG_BSD_PROCESS_ACCT. +.BR CONFIG_BSD_PROCESS_ACCT . .TP .B ENOTDIR A component used as a directory in diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2 index 7e6f6f6bf..b945a58cd 100644 --- a/man2/alloc_hugepages.2 +++ b/man2/alloc_hugepages.2 @@ -41,7 +41,8 @@ The system calls and .BR free_hugepages () were introduced in Linux 2.5.36 and removed again in 2.5.54. -They existed only on i386 and ia64 (when built with CONFIG_HUGETLB_PAGE). +They existed only on i386 and ia64 (when built with +.BR CONFIG_HUGETLB_PAGE ). In Linux 2.4.20 the syscall numbers exist, but the calls fail with the error .BR ENOSYS . @@ -86,7 +87,10 @@ It must be a multiple of the huge page size. The .I prot parameter specifies the memory protection of the segment. -It is one of PROT_READ, PROT_WRITE, PROT_EXEC. +It is one of +.BR PROT_READ , +.BR PROT_WRITE , +.BR PROT_EXEC . .LP The .I flag @@ -95,9 +99,12 @@ parameter is ignored, unless is positive. In that case, if .I flag -is IPC_CREAT, then a new huge page segment is created when none +is +.BR IPC_CREAT , +then a new huge page segment is created when none with the given key existed. -If this flag is not set, then ENOENT +If this flag is not set, then +.BR ENOENT is returned when no segment with the given key exists. .IR .SH "RETURN VALUE" diff --git a/man2/capget.2 b/man2/capget.2 index e501e480b..13aa63bc6 100644 --- a/man2/capget.2 +++ b/man2/capget.2 @@ -67,11 +67,15 @@ typedef struct __user_cap_data_struct { .fi .in -4n .sp -The calls will return EINVAL, and set the +The calls will return +.BR EINVAL , +and set the .I version field of .I hdr -to _LINUX_CAPABILITY_VERSION when another version was specified. +to +.B _LINUX_CAPABILITY_VERSION +when another version was specified. The calls operate on the capabilities of the thread specified by the .I pid diff --git a/man2/chmod.2 b/man2/chmod.2 index fe7c2c407..e42a77754 100644 --- a/man2/chmod.2 +++ b/man2/chmod.2 @@ -51,40 +51,40 @@ Modes are specified by the following: .RS .TP 1.0i -S_ISUID +.B S_ISUID 04000 set user ID on execution .TP -S_ISGID +.B S_ISGID 02000 set group ID on execution .TP -S_ISVTX +.B S_ISVTX 01000 sticky bit .TP -S_IRUSR +.B S_IRUSR 00400 read by owner .TP -S_IWUSR +.B S_IWUSR 00200 write by owner .TP -S_IXUSR +.B S_IXUSR 00100 execute/search by owner .TP -S_IRGRP +.B S_IRGRP 00040 read by group .TP -S_IWGRP +.B S_IWGRP 00020 write by group .TP -S_IXGRP +.B S_IXGRP 00010 execute/search by group .TP -S_IROTH +.B S_IROTH 00004 read by others .TP -S_IWOTH +.B S_IWOTH 00002 write by others .TP -S_IXOTH +.B S_IXOTH 00001 execute/search by others .RE .PP @@ -97,7 +97,9 @@ If the calling process is not privileged (Linux: does not have the .B CAP_FSETID capability), and the group of the file does not match the effective group ID of the process or one of its -supplementary group IDs, the S_ISGID bit will be turned off, +supplementary group IDs, the +.B S_ISGID +bit will be turned off, but this will not cause an error to be returned. As a security measure, depending on the file system, diff --git a/man2/chown.2 b/man2/chown.2 index 6c6667a1e..fbee99cdf 100644 --- a/man2/chown.2 +++ b/man2/chown.2 @@ -64,7 +64,11 @@ or is specified as \-1, then that ID is not changed. When the owner or group of an executable file are changed by a non-superuser, -the S_ISUID and S_ISGID mode bits are cleared. +the +.B S_ISUID +and +.B S_ISGID +mode bits are cleared. POSIX does not specify whether this also should happen when root does the .BR chown (); @@ -72,9 +76,12 @@ the Linux behavior depends on the kernel version. .\" In Linux 2.0 kernels, superuser was like everyone else .\" In 2.2, up to 2.2.12, these bits were not cleared for superuser. .\" Since 2.2.13, superuser is once more like everyone else. -In case of a non-group-executable file (with clear S_IXGRP bit) -the S_ISGID bit indicates mandatory locking, and is not cleared -by a +In case of a non-group-executable file (with clear +.B S_IXGRP +bit) +the +.B S_ISGID +bit indicates mandatory locking, and is not cleared by a .BR chown (). .SH "RETURN VALUE" On success, zero is returned. diff --git a/man2/clone.2 b/man2/clone.2 index bc6c49f38..c33a46fab 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -504,7 +504,9 @@ parameter is the new TLS (Thread Local Storage) descriptor. Store child thread ID at location .I parent_tidptr in parent and child memory. -(In Linux 2.5.32-2.5.48 there was a flag CLONE_SETTID that did this.) +(In Linux 2.5.32-2.5.48 there was a flag +.B CLONE_SETTID +that did this.) .TP .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" Store child thread ID at location @@ -553,11 +555,14 @@ Since Linux 2.5.49 the system call has five parameters. The two new parameters are .I parent_tidptr which points to the location (in parent and child memory) where -the child thread ID will be written in case CLONE_PARENT_SETTID +the child thread ID will be written in case +.B CLONE_PARENT_SETTID was specified, and .I child_tidptr which points to the location (in child memory) where the child thread ID -will be written in case CLONE_CHILD_SETTID was specified. +will be written in case +.B CLONE_CHILD_SETTID +was specified. .SH "RETURN VALUE" .\" gettid(2) returns current->pid; .\" getpid(2) returns current->tgid; diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2 index fe4fa5486..d974553d0 100644 --- a/man2/epoll_ctl.2 +++ b/man2/epoll_ctl.2 @@ -177,7 +177,9 @@ is not a valid file descriptor. .TP .B EEXIST .I op -was EPOLL_CTL_ADD, and the supplied file descriptor +was +.BR EPOLL_CTL_ADD , +and the supplied file descriptor .IR fd is already in .IR epfd . @@ -197,7 +199,11 @@ is not supported by this interface. .TP .B ENOENT .I op -was EPOLL_CTL_MOD or EPOLL_CTL_DEL, and +was +.BR EPOLL_CTL_MOD +or +.BR EPOLL_CTL_DEL , +and .IR fd is not in .IR epfd . diff --git a/man2/execve.2 b/man2/execve.2 index e127df771..88bdaf6f8 100644 --- a/man2/execve.2 +++ b/man2/execve.2 @@ -390,7 +390,8 @@ The result of mounting a filesystem varies across Linux kernel versions: some will refuse execution of set-user-ID and set-group-ID executables when this would -give the user powers she did not have already (and return EPERM), +give the user powers she did not have already (and return +.BR EPERM ), some will just ignore the set-user-ID and set-group-ID bits and .BR exec () successfully. diff --git a/man2/fcntl.2 b/man2/fcntl.2 index d8ad9b4ce..83510d9dd 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -760,8 +760,9 @@ DN_ATTRIB The attributes of a file were changed (chown, chmod, utime[s]) .TE .sp -(In order to obtain these definitions, the _GNU_SOURCE feature test macro -must be defined.) +(In order to obtain these definitions, the +.B _GNU_SOURCE +feature test macro must be defined.) .sp Directory notifications are normally "one-shot", and the application must re-register to receive further notifications. diff --git a/man2/futex.2 b/man2/futex.2 index f26beabd3..d50e6815e 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -73,7 +73,9 @@ This operation atomically verifies that the futex address .I uaddr still contains the value .IR val , -and sleeps awaiting FUTEX_WAKE on this futex address. +and sleeps awaiting +.B FUTEX_WAKE +on this futex address. If the .I timeout argument is non-NULL, its contents describe the maximum @@ -88,11 +90,14 @@ For .BR futex (7), this call is executed if decrementing the count gave a negative value (indicating contention), and will sleep until another process releases -the futex and executes the FUTEX_WAKE operation. +the futex and executes the +.B FUTEX_WAKE +operation. .TP .B FUTEX_WAKE This operation wakes at most \fIval\fR -processes waiting on this futex address (ie. inside FUTEX_WAIT). +processes waiting on this futex address (ie. inside +.BR FUTEX_WAIT ). The arguments .IR timeout , .I uaddr2 @@ -110,8 +115,9 @@ to 1 (indicating that it is available). To support asynchronous wakeups, this operation associates a file descriptor with a futex. .\" , suitable for .BR poll (2). -If another process executes a FUTEX_WAKE, the process will receive the signal -number that was passed in +If another process executes a +.BR FUTEX_WAKE , +the process will receive the signal number that was passed in .IR val . The calling process must close the returned file descriptor after use. The arguments @@ -122,16 +128,21 @@ and are ignored. To prevent race conditions, the caller should test if the futex has -been upped after FUTEX_FD returns. +been upped after +.B FUTEX_FD +returns. .\" FIXME . Check that this flag does eventually get removed. -Because it is inherently racy, FUTEX_FD is scheduled for removal +Because it is inherently racy, +.B FUTEX_FD +is scheduled for removal in June 2007; any applications that use it should be fixed now. .TP .BR FUTEX_REQUEUE " (since Linux 2.5.70)" This operation was introduced in order to avoid a "thundering herd" effect -when FUTEX_WAKE is used and all processes woken up need to acquire another -futex. +when +.B FUTEX_WAKE +is used and all processes woken up need to acquire another futex. This call wakes up .I val processes, and requeues all other waiters on the futex at address @@ -143,14 +154,20 @@ and are ignored. .TP .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" -There was a race in the intended use of FUTEX_REQUEUE, so -FUTEX_CMP_REQUEUE was introduced. -This is similar to FUTEX_REQUEUE, +There was a race in the intended use of +.BR FUTEX_REQUEUE , +so +.B FUTEX_CMP_REQUEUE +was introduced. +This is similar to +.BR FUTEX_REQUEUE , but first checks whether the location .I uaddr still contains the value .IR val3 . -If not, an error EAGAIN is returned. +If not, an error +.B EAGAIN +is returned. The argument .I timeout is ignored. @@ -160,13 +177,20 @@ Depending on which operation was executed, the returned value can have differing meanings. .TP .B FUTEX_WAIT -Returns 0 if the process was woken by a FUTEX_WAKE call. +Returns 0 if the process was woken by a +.B FUTEX_WAKE +call. In case of timeout, -ETIMEDOUT is returned. +.B ETIMEDOUT +is returned. If the futex was not equal to the expected value, -the operation fails with the error EWOULDBLOCK. +the operation fails with the error +.BR EWOULDBLOCK . Signals (or other spurious wakeups) -cause FUTEX_WAIT to return EINTR. +cause +.B FUTEX_WAIT +to return +.BR EINTR . .TP .B FUTEX_WAKE Returns the number of processes woken up. @@ -185,9 +209,12 @@ Returns the number of processes woken up. No read access to futex memory. .TP .B EAGAIN -FUTEX_CMP_REQUEUE found an unexpected futex value. +.B FUTEX_CMP_REQUEUE +found an unexpected futex value. (This probably indicates a race; -use the safe FUTEX_WAKE now.) +use the safe +.B FUTEX_WAKE +now.) .TP .B EFAULT Error in getting diff --git a/man2/getgroups.2 b/man2/getgroups.2 index c4df7b0a1..6860b3600 100644 --- a/man2/getgroups.2 +++ b/man2/getgroups.2 @@ -106,7 +106,9 @@ Since .BR setgroups () requires privilege, it is not covered by POSIX.1-2001. .SH NOTES -A process can have up to at least NGROUPS_MAX supplementary group IDs +A process can have up to at least +.B NGROUPS_MAX +supplementary group IDs in addition to the effective group ID. The set of supplementary group IDs is inherited from the parent process and may be changed using diff --git a/man2/gethostname.2 b/man2/gethostname.2 index e6b7c7ee5..0a981182f 100644 --- a/man2/gethostname.2 +++ b/man2/gethostname.2 @@ -71,7 +71,8 @@ or, for on Linux/i386, .I len is smaller than the actual size. -(In this last case glibc 2.1 uses ENAMETOOLONG.) +(In this last case glibc 2.1 uses +.BR ENAMETOOLONG .) .TP .B EPERM For @@ -88,7 +89,9 @@ but not .SH NOTES SUSv2 guarantees that `Host names are limited to 255 bytes'. POSIX.1-2001 guarantees that `Host names (not including -the terminating null byte) are limited to HOST_NAME_MAX bytes'. +the terminating null byte) are limited to +.BR HOST_NAME_MAX +bytes'. .SS Glibc Notes The GNU C library implements .BR gethostname () diff --git a/man2/getitimer.2 b/man2/getitimer.2 index 34692a6f8..5a2d822a5 100644 --- a/man2/getitimer.2 +++ b/man2/getitimer.2 @@ -151,7 +151,8 @@ The second signal in such an event will be lost. On Linux, timer values are represented in jiffies. If a request is made set a timer with a value whose jiffies -representation exceeds MAX_SEC_IN_JIFFIES +representation exceeds +.B MAX_SEC_IN_JIFFIES (defined in .IR include/linux/jiffies.h ), then the timer is silently truncated to this ceiling value. diff --git a/man2/getpagesize.2 b/man2/getpagesize.2 index 2309ec94f..1874b461a 100644 --- a/man2/getpagesize.2 +++ b/man2/getpagesize.2 @@ -46,7 +46,10 @@ long sz = sysconf(_SC_PAGESIZE); .fi .RE -(most systems allow the synonym _SC_PAGE_SIZE for _SC_PAGESIZE), +(most systems allow the synonym +.BR _SC_PAGE_SIZE +for +.BR _SC_PAGESIZE ), or .RS diff --git a/man2/getpriority.2 b/man2/getpriority.2 index 05313e610..797e22716 100644 --- a/man2/getpriority.2 +++ b/man2/getpriority.2 @@ -162,7 +162,9 @@ inherits its parent's nice value. The nice value is preserved across .BR execve (2). -The details on the condition for EPERM depend on the system. +The details on the condition for +.BR EPERM +depend on the system. The above description is what POSIX.1-2001 says, and seems to be followed on all System V-like systems. Linux kernels before 2.6.12 required the real or diff --git a/man2/getresuid.2 b/man2/getresuid.2 index 4922929e5..7e98c8bf3 100644 --- a/man2/getresuid.2 +++ b/man2/getresuid.2 @@ -56,7 +56,9 @@ These calls are non-standard; they also appear on HP-UX and some of the BSDs. The prototype is given by glibc since version 2.3.2 -provided _GNU_SOURCE is defined. +provided +.B _GNU_SOURCE +is defined. .SH "SEE ALSO" .BR getuid (2), .BR setresuid (2), diff --git a/man2/getrlimit.2 b/man2/getrlimit.2 index 1ccae182a..2358b80b9 100644 --- a/man2/getrlimit.2 +++ b/man2/getrlimit.2 @@ -263,7 +263,9 @@ The actual ceiling for the nice value is calculated as .IR "20\ \-\ rlim_cur" . (This strangeness occurs because negative numbers cannot be specified as resource limit values, since they typically have special meanings. -For example, RLIM_INFINITY typically is the same as \-1.) +For example, +.B RLIM_INFINITY +typically is the same as \-1.) .TP .B RLIMIT_NOFILE Specifies a value one greater than the maximum file descriptor number @@ -358,7 +360,9 @@ capability is required to do this. Or, the process tried to use .BR setrlimit () to increase -the soft or hard RLIMIT_NOFILE limit above the current kernel +the soft or hard +.B RLIMIT_NOFILE +limit above the current kernel maximum (NR_OPEN). .SH CONFORMING TO SVr4, 4.3BSD, POSIX.1-2001. diff --git a/man2/getsid.2 b/man2/getsid.2 index f5c6b31ba..515ddfb89 100644 --- a/man2/getsid.2 +++ b/man2/getsid.2 @@ -57,13 +57,17 @@ was found. .SH "CONFORMING TO" SVr4, POSIX.1-2001. .SH NOTES -Linux does not return EPERM. +Linux does not return +.BR EPERM . .LP Linux has this system call since Linux 1.3.44. There is libc support since libc 5.2.19. .LP -To get the prototype under glibc, define both _XOPEN_SOURCE and -_XOPEN_SOURCE_EXTENDED, or use "#define _XOPEN_SOURCE \fIn\fP" +To get the prototype under glibc, define both +.BR _XOPEN_SOURCE +and +.BR _XOPEN_SOURCE_EXTENDED , +or use "#define _XOPEN_SOURCE \fIn\fP" for some integer \fIn\fP larger than or equal to 500. .SH "SEE ALSO" .BR getpgid (2), diff --git a/man2/gettid.2 b/man2/gettid.2 index 6c64c3b89..802c4614a 100644 --- a/man2/gettid.2 +++ b/man2/gettid.2 @@ -37,7 +37,9 @@ This is equal to the process ID (as returned by .BR getpid (2)), unless the process is part of a thread group (created by specifying -the CLONE_THREAD flag to the +the +.B CLONE_THREAD +flag to the .BR clone (2) system call). All processes in the same thread group diff --git a/man2/getxattr.2 b/man2/getxattr.2 index 9c9556050..868f321f6 100644 --- a/man2/getxattr.2 +++ b/man2/getxattr.2 @@ -109,7 +109,8 @@ is set appropriately. If the named attribute does not exist, or the process has no access to this attribute, .I errno -is set to ENOATTR. +is set to +.BR ENOATTR . .PP If the .I size @@ -117,11 +118,13 @@ of the .I value buffer is too small to hold the result, .I errno -is set to ERANGE. +is set to +.BR ERANGE . .PP If extended attributes are not supported by the filesystem, or are disabled, .I errno -is set to ENOTSUP. +is set to +.BR ENOTSUP . .PP The errors documented for the .BR stat (2) diff --git a/man2/ioctl.2 b/man2/ioctl.2 index ffd289d56..55ca07b6f 100644 --- a/man2/ioctl.2 +++ b/man2/ioctl.2 @@ -132,7 +132,9 @@ In order to use this call, one needs an open file descriptor. Often the .BR open (2) call has unwanted side effects, that can be avoided under Linux -by giving it the O_NONBLOCK flag. +by giving it the +.BR O_NONBLOCK +flag. .SH "SEE ALSO" .BR execve (2), .BR fcntl (2), diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2 index 4b0346ff7..35046569f 100644 --- a/man2/ioprio_set.2 +++ b/man2/ioprio_set.2 @@ -129,8 +129,10 @@ component. See the NOTES section for more information on scheduling classes and priorities. -I/O priorities are supported for reads and for synchronous (O_DIRECT, -O_SYNC) writes. +I/O priorities are supported for reads and for synchronous +.RB ( O_DIRECT , +.BR O_SYNC ) +writes. I/O priorities are not supported for asynchronous writes because they are issued outside the context of the program dirtying the memory, and thus program-specific priorities do not apply. diff --git a/man2/killpg.2 b/man2/killpg.2 index e2a0fbb28..89a806249 100644 --- a/man2/killpg.2 +++ b/man2/killpg.2 @@ -105,10 +105,14 @@ in BSD-type systems and System V-type systems. See the POSIX rationale for .BR kill (). 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, -while POSIX documents EPERM only when the permission check failed -for all target processes. +value +.BR EPERM : +BSD documents that no signal is sent and +.BR EPERM +returned when the permission check failed for at least one target process, +while POSIX documents +.B EPERM +only when the permission check failed for all target processes. .SH "SEE ALSO" .BR getpgrp (2), .BR kill (2), diff --git a/man2/listxattr.2 b/man2/listxattr.2 index 28b9b35f3..3ec873c6b 100644 --- a/man2/listxattr.2 +++ b/man2/listxattr.2 @@ -130,11 +130,13 @@ of the .I list buffer is too small to hold the result, .I errno -is set to ERANGE. +is set to +.BR ERANGE . .PP If extended attributes are not supported by the filesystem, or are disabled, .I errno -is set to ENOTSUP. +is set to +.BR ENOTSUP . .PP The errors documented for the .BR stat (2) diff --git a/man2/lookup_dcookie.2 b/man2/lookup_dcookie.2 index ff88a87ff..7a1291f6d 100644 --- a/man2/lookup_dcookie.2 +++ b/man2/lookup_dcookie.2 @@ -74,7 +74,9 @@ required to look up cookie values. The buffer was not large enough to hold the path of the directory entry. .SH VERSIONS Available since Linux 2.5.43. -The ENAMETOOLONG error return was added in 2.5.70. +The +.BR ENAMETOOLONG +error return was added in 2.5.70. .SH "CONFORMING TO" .BR lookup_dcookie () is Linux specific. diff --git a/man2/lseek.2 b/man2/lseek.2 index f2beef0d2..4a6b6d0b1 100644 --- a/man2/lseek.2 +++ b/man2/lseek.2 @@ -99,7 +99,10 @@ is not an open file descriptor. .TP .B EINVAL .I whence -is not one of SEEK_SET, SEEK_CUR, SEEK_END; +is not one of +.BR SEEK_SET , +.BR SEEK_CUR , +.BR SEEK_END ; or the resulting file offset would be negative, or beyond the end of a seekable device. .\" Some systems may allow negative offsets for character devices diff --git a/man2/madvise.2 b/man2/madvise.2 index b5505a435..612e82b58 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -154,14 +154,19 @@ is negative, is not page-aligned, .I advice is not a valid value, or the application is attempting -to release locked or shared pages (with MADV_DONTNEED). +to release locked or shared pages (with +.BR MADV_DONTNEED ). .TP .B EIO -(for MADV_WILLNEED) Paging in this area would exceed the process's +(for +.BR MADV_WILLNEED ) +Paging in this area would exceed the process's maximum resident set size. .TP .B ENOMEM -(for MADV_WILLNEED) Not enough memory: paging in failed. +(for +.BR MADV_WILLNEED ) +Not enough memory: paging in failed. .TP .B ENOMEM Addresses in the specified range are not currently @@ -170,7 +175,9 @@ mapped, or are outside the address space of the process. POSIX.1b. POSIX.1-2001 describes .BR posix_madvise (3) -with constants POSIX_MADV_NORMAL, etc., +with constants +.BR POSIX_MADV_NORMAL , +etc., with a behavior close to that described here. There is a similar .BR posix_fadvise (3) diff --git a/man2/mkdir.2 b/man2/mkdir.2 index 6bdb9df2d..8e1d16633 100644 --- a/man2/mkdir.2 +++ b/man2/mkdir.2 @@ -107,8 +107,9 @@ refers to a file on a read-only filesystem. SVr4, BSD, POSIX.1-2001. .\" SVr4 documents additional EIO, EMULTIHOP .SH NOTES -Under Linux apart from the permission bits, only the S_ISVTX mode bit -is honored. +Under Linux apart from the permission bits, only the +.B S_ISVTX +mode bit is honored. That is, under Linux the created directory actually gets mode .RI ( mode " & ~" umask " & 01777)." See also diff --git a/man2/mknod.2 b/man2/mknod.2 index 39596d361..93bd823c8 100644 --- a/man2/mknod.2 +++ b/man2/mknod.2 @@ -56,7 +56,8 @@ or to specify a normal file (which will be created empty), character special file, block special file, FIFO (named pipe), or Unix domain socket, respectively. -(Zero file type is equivalent to type S_IFREG.) +(Zero file type is equivalent to type +.BR S_IFREG .) If the file type is .BR S_IFCHR " or " S_IFBLK @@ -67,7 +68,9 @@ special file; otherwise it is ignored. If .I pathname -already exists, or is a symbolic link, this call fails with an EEXIST error. +already exists, or is a symbolic link, this call fails with an +.B EEXIST +error. The newly created node will be owned by the effective user ID of the process. diff --git a/man2/mmap.2 b/man2/mmap.2 index 34a252509..0fb871cfa 100644 --- a/man2/mmap.2 +++ b/man2/mmap.2 @@ -347,7 +347,9 @@ was requested and .B PROT_WRITE is set, but .I fd -is not open in read/write (O_RDWR) mode. +is not open in read/write +.RB ( O_RDWR ) +mode. Or .B PROT_WRITE is set, but the file is append-only. diff --git a/man2/mount.2 b/man2/mount.2 index c9d0e1f58..149be13b5 100644 --- a/man2/mount.2 +++ b/man2/mount.2 @@ -357,7 +357,8 @@ is a descendant of Table of dummy devices is full. .TP .B ENAMETOOLONG -A pathname was longer than MAXPATHLEN. +A pathname was longer than +.BR MAXPATHLEN . .TP .B ENODEV .I filesystemtype @@ -391,7 +392,8 @@ programs intended to be portable. .SS Linux Notes The original .BR umount () -function was called as \fIumount(device)\fP and would return ENOTBLK +function was called as \fIumount(device)\fP and would return +.B ENOTBLK when called with something other than a block device. In Linux 0.98p4 a call \fIumount(dir)\fP was added, in order to support anonymous devices. @@ -399,8 +401,14 @@ In Linux 2.3.99-pre7 the call \fIumount(device)\fP was removed, leaving only \fIumount(dir)\fP (since now devices can be mounted in more than one place, so specifying the device does not suffice). .LP -The original MS_SYNC flag was renamed MS_SYNCHRONOUS in 1.1.69 -when a different MS_SYNC was added to \fI\fP. +The original +.BR MS_SYNC +flag was renamed +.BR MS_SYNCHRONOUS +in 1.1.69 +when a different +.BR MS_SYNC +was added to \fI\fP. .LP Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID program on a filesystem mounted with diff --git a/man2/mremap.2 b/man2/mremap.2 index c06884997..4ac26ce09 100644 --- a/man2/mremap.2 +++ b/man2/mremap.2 @@ -131,13 +131,16 @@ On error, the value .B EAGAIN The caller tried to expand a memory segment that is locked, but this was not possible without exceeding the -RLIMIT_MEMLOCK resource limit. +.B RLIMIT_MEMLOCK +resource limit. .TP .B EFAULT "Segmentation fault." Some address in the range \fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid virtual memory address for this process. -You can also get EFAULT even if there exist mappings that cover the +You can also get +.B EFAULT +even if there exist mappings that cover the whole address space requested, but those mappings are of different types. .TP .B EINVAL diff --git a/man2/msgctl.2 b/man2/msgctl.2 index d04aaf54a..90e412d98 100644 --- a/man2/msgctl.2 +++ b/man2/msgctl.2 @@ -158,7 +158,9 @@ This structure is of type (thus, a cast is required), defined in .I -if the _GNU_SOURCE feature test macro is defined: +if the +.BR _GNU_SOURCE +feature test macro is defined: .nf .in +2n @@ -324,7 +326,9 @@ Various fields in the \fIstruct msqid_ds\fP were shorts under Linux 2.2 and have become longs under Linux 2.4. To take advantage of this, a recompilation under glibc-2.1.91 or later should suffice. -(The kernel distinguishes old and new calls by an IPC_64 flag in +(The kernel distinguishes old and new calls by an +.BR IPC_64 +flag in .IR cmd .) .SH "SEE ALSO" .BR msgget (2), diff --git a/man2/msgget.2 b/man2/msgget.2 index 24de33176..9ebe55431 100644 --- a/man2/msgget.2 +++ b/man2/msgget.2 @@ -205,11 +205,15 @@ dependent (on Linux, this limit can be read and modified via .IR /proc/sys/kernel/msgmni ). .SS "Linux Notes" -Until version 2.3.20 Linux would return EIDRM for a +Until version 2.3.20 Linux would return +.BR EIDRM +for a .BR msgget () on a message queue scheduled for deletion. .SH BUGS -The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW +The name choice +.BR IPC_PRIVATE +was perhaps unfortunate, IPC_NEW would more clearly show its function. .SH "SEE ALSO" .BR msgctl (2), diff --git a/man2/msync.2 b/man2/msync.2 index f93fb1d68..f82337db7 100644 --- a/man2/msync.2 +++ b/man2/msync.2 @@ -80,10 +80,14 @@ and a memory lock exists for the specified address range. .BR EINVAL .I start is not a multiple of PAGESIZE; or any bit other than -MS_ASYNC | MS_INVALIDATE | MS_SYNC is set in +.BR MS_ASYNC " | " MS_INVALIDATE " | " MS_SYNC +is set in .IR flags ; or both -MS_SYNC and MS_ASYNC are set in +.B MS_SYNC +and +.B MS_ASYNC +are set in .IR flags . .TP .B ENOMEM @@ -91,9 +95,12 @@ The indicated memory (or part of it) was not mapped. .SH "CONFORMING TO" POSIX.1-2001. -This call was introduced in Linux 1.3.21, and then used EFAULT instead of -ENOMEM. -In Linux 2.4.19 this was changed to the POSIX value ENOMEM. +This call was introduced in Linux 1.3.21, and then used +.B EFAULT +instead of +.BR ENOMEM . +In Linux 2.4.19 this was changed to the POSIX value +.BR ENOMEM . .SH AVAILABILITY On POSIX systems on which .BR msync () diff --git a/man2/nice.2 b/man2/nice.2 index b6248ee73..41b6736c8 100644 --- a/man2/nice.2 +++ b/man2/nice.2 @@ -68,7 +68,9 @@ resource limit in SVr4, 4.3BSD, POSIX.1-2001. However, the Linux and (g)libc (earlier than glibc 2.2.4) return value is nonstandard, see below. -SVr4 documents an additional EINVAL error code. +SVr4 documents an additional +.BR EINVAL +error code. .SH NOTES SUSv2 and POSIX.1-2001 specify that .BR nice () diff --git a/man2/open.2 b/man2/open.2 index c94363643..8f0e1aab8 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -287,10 +287,17 @@ the data has been physically written to the underlying hardware. .TP .B O_TRUNC If the file already exists and is a regular file and the open mode allows -writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0. -If the file is a FIFO or terminal device file, the O_TRUNC +writing (i.e., is +.B O_RDWR +or +.BR O_WRONLY ) +it will be truncated to length 0. +If the file is a FIFO or terminal device file, the +.B O_TRUNC flag is ignored. -Otherwise the effect of O_TRUNC is unspecified. +Otherwise the effect of +.B O_TRUNC +is unspecified. .PP Some of these optional flags can be altered using .BR fcntl (2) @@ -394,7 +401,9 @@ points outside your accessible address space. .TP .B EFBIG .I pathname -refers to a regular file, too large to be opened; see O_LARGEFILE above. +refers to a regular file, too large to be opened; see +.B O_LARGEFILE +above. (POSIX.1-2001 specifies the error .B EOVERFLOW for this case.) @@ -432,10 +441,13 @@ The system limit on the total number of open files has been reached. .B ENODEV .I pathname refers to a device special file and no corresponding device exists. -(This is a Linux kernel bug; in this situation ENXIO must be returned.) +(This is a Linux kernel bug; in this situation +.B ENXIO +must be returned.) .TP .B ENOENT -O_CREAT is not set and the named file does not exist. +.B O_CREAT +is not set and the named file does not exist. Or, a directory component in .I pathname does not exist or is a dangling symbolic link. @@ -457,7 +469,8 @@ is not, in fact, a directory, or \fBO_DIRECTORY\fR was specified and was not a directory. .TP .B ENXIO -O_NONBLOCK | O_WRONLY is set, the named file is a FIFO and +.BR O_NONBLOCK " | " O_WRONLY +is set, the named file is a FIFO and no process has the file open for reading. Or, the file is a device special file and no corresponding device exists. .TP diff --git a/man2/pciconfig_read.2 b/man2/pciconfig_read.2 index 310a108cc..f1358cc9b 100644 --- a/man2/pciconfig_read.2 +++ b/man2/pciconfig_read.2 @@ -71,8 +71,12 @@ regions in physical memory according to the value. Values for .I which -are: IOBASE_BRIDGE_NUMBER, IOBASE_MEMORY, -IOBASE_IO, IOBASE_ISA_IO, IOBASE_ISA_MEM. +are: +.BR IOBASE_BRIDGE_NUMBER , +.BR IOBASE_MEMORY , +.BR IOBASE_IO , +.BR IOBASE_ISA_IO , +.BR IOBASE_ISA_MEM . .SH ERRORS .TP .B EINVAL @@ -91,7 +95,9 @@ For For the other calls, could not find a slot. .TP .B ENOSYS -The system has not implemented these calls (CONFIG_PCI not defined). +The system has not implemented these calls +.RB ( CONFIG_PCI +not defined). .TP .B EOPNOTSUPP This return value is only valid for diff --git a/man2/poll.2 b/man2/poll.2 index e41a837c2..6f5a81b15 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -259,7 +259,9 @@ A signal occurred before any requested event. .B EINVAL The .I nfds -value exceeds the RLIMIT_NOFILE value. +value exceeds the +.B RLIMIT_NOFILE +value. .TP .B ENOMEM There was no space to allocate file descriptor tables. diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 index e65ff773d..24ddfda46 100644 --- a/man2/posix_fadvise.2 +++ b/man2/posix_fadvise.2 @@ -81,8 +81,11 @@ The \fIfd\fP argument was not a valid file descriptor. An invalid value was specified for \fIadvice\fP. .TP .B ESPIPE -The specified file descriptor refers to a pipe or FIFO. (Linux actually -returns EINVAL in this case.) +The specified file descriptor refers to a pipe or FIFO. +(Linux actually +returns +.B EINVAL +in this case.) .SH VERSIONS .BR posix_fadvise () appeared in kernel 2.5.60. diff --git a/man2/read.2 b/man2/read.2 index dae813d4e..8a8947664 100644 --- a/man2/read.2 +++ b/man2/read.2 @@ -57,7 +57,9 @@ is zero, returns zero and has no other results. If .I count -is greater than SSIZE_MAX, the result is unspecified. +is greater than +.BR SSIZE_MAX , +the result is unspecified. .SH "RETURN VALUE" On success, the number of bytes read is returned (zero indicates end of file), and the file position is advanced by this number. @@ -123,7 +125,9 @@ POSIX allows a that is interrupted after reading some data to return \-1 (with .I errno -set to EINTR) or to return the number of bytes already read. +set to +.BR EINTR ) +or to return the number of bytes already read. .SH "CONFORMING TO" SVr4, 4.3BSD, POSIX.1-2001. .SH NOTES @@ -143,7 +147,9 @@ Many filesystems and disks were considered to be fast enough that the implementation of .B O_NONBLOCK was deemed unnecessary. -So, O_NONBLOCK may not be available on files +So, +.B O_NONBLOCK +may not be available on files and/or disks. .SH "SEE ALSO" .BR close (2), diff --git a/man2/reboot.2 b/man2/reboot.2 index b98acb207..2ac466b6f 100644 --- a/man2/reboot.2 +++ b/man2/reboot.2 @@ -53,14 +53,26 @@ call reboots the system, or enables/disables the reboot keystroke it can be changed using .BR loadkeys (1)). .PP -This system call will fail (with EINVAL) unless +This system call will fail (with +.BR EINVAL ) +unless .I magic -equals LINUX_REBOOT_MAGIC1 (that is, 0xfee1dead) and +equals +.BR LINUX_REBOOT_MAGIC1 +(that is, 0xfee1dead) and .I magic2 -equals LINUX_REBOOT_MAGIC2 (that is, 672274793). -However, since 2.1.17 also LINUX_REBOOT_MAGIC2A (that is, 85072278) -and since 2.1.97 also LINUX_REBOOT_MAGIC2B (that is, 369367448) -and since 2.5.71 also LINUX_REBOOT_MAGIC2C (that is, 537993216) +equals +.BR LINUX_REBOOT_MAGIC2 +(that is, 672274793). +However, since 2.1.17 also +.BR LINUX_REBOOT_MAGIC2A +(that is, 85072278) +and since 2.1.97 also +.BR LINUX_REBOOT_MAGIC2B +(that is, 369367448) +and since 2.5.71 also +.BR LINUX_REBOOT_MAGIC2C +(that is, 537993216) are permitted as value for .IR magic2 . (The hexadecimal values of these constants are meaningful.) @@ -106,7 +118,8 @@ data will be lost. (RB_ENABLE_CAD, 0x89abcdef). CAD is enabled. This means that the CAD keystroke will immediately cause -the action associated with LINUX_REBOOT_CMD_RESTART. +the action associated with +.BR LINUX_REBOOT_CMD_RESTART . .TP .B LINUX_REBOOT_CMD_CAD_OFF (RB_DISABLE_CAD, 0). @@ -132,7 +145,8 @@ is set appropriately. .SH ERRORS .TP .B EFAULT -Problem with getting userspace data under LINUX_REBOOT_CMD_RESTART2. +Problem with getting userspace data under +.BR LINUX_REBOOT_CMD_RESTART2 . .TP .B EINVAL Bad magic numbers or \fIflag\fP. diff --git a/man2/removexattr.2 b/man2/removexattr.2 index 4e010926a..15e5b6d98 100644 --- a/man2/removexattr.2 +++ b/man2/removexattr.2 @@ -85,11 +85,13 @@ is set appropriately. .PP If the named attribute does not exist, .I errno -is set to ENOATTR. +is set to +.BR ENOATTR . .PP If extended attributes are not supported by the filesystem, or are disabled, .I errno -is set to ENOTSUP. +is set to +.BR ENOTSUP . .PP The errors documented for the .BR stat (2) diff --git a/man2/rename.2 b/man2/rename.2 index 1813bbb6a..4aefe0e03 100644 --- a/man2/rename.2 +++ b/man2/rename.2 @@ -122,9 +122,13 @@ current working directory, or as root directory, or because it was open for reading) or is in use by the system (for example as mount point), while the system considers this an error. -(Note that there is no requirement to return EBUSY in such +(Note that there is no requirement to return +.BR EBUSY +in such cases \(em there is nothing wrong with doing the rename anyway \(em -but it is allowed to return EBUSY if the system cannot otherwise +but it is allowed to return +.B EBUSY +if the system cannot otherwise handle such situations.) .TP .B EFAULT diff --git a/man2/select.2 b/man2/select.2 index 2cccb6934..882a4990d 100644 --- a/man2/select.2 +++ b/man2/select.2 @@ -339,7 +339,9 @@ or .BR FD_SET () with a value of .I fd -that is negative or is equal to or larger than FD_SETSIZE will result +that is negative or is equal to or larger than +.B FD_SETSIZE +will result in undefined behavior. Moreover, POSIX requires .I fd @@ -444,7 +446,9 @@ There may be other circumstances in which a file descriptor is spuriously reported as ready. .\" Stevens discusses a case where accept can block after select .\" returns successfully because of an intervening RST from the client. -Thus it may be safer to use O_NONBLOCK on sockets that should not block. +Thus it may be safer to use +.B O_NONBLOCK +on sockets that should not block. .\" Maybe the kernel should have returned EIO in such a situation? On Linux, diff --git a/man2/semctl.2 b/man2/semctl.2 index 1bf636e13..da48e93f9 100644 --- a/man2/semctl.2 +++ b/man2/semctl.2 @@ -173,7 +173,9 @@ This structure is of type .IR seminfo , defined in .I -if the _GNU_SOURCE feature test macro is defined: +if the +.BR _GNU_SOURCE +feature test macro is defined: .nf .in +2n @@ -474,7 +476,9 @@ Various fields in a \fIstruct semid_ds\fP were shorts under Linux 2.2 and have become longs under Linux 2.4. To take advantage of this, a recompilation under glibc-2.1.91 or later should suffice. -(The kernel distinguishes old and new calls by an IPC_64 flag in +(The kernel distinguishes old and new calls by an +.BR IPC_64 +flag in .IR cmd .) .PP In some earlier versions of glibc, the diff --git a/man2/semget.2 b/man2/semget.2 index 749df9c4d..e6ecc3988 100644 --- a/man2/semget.2 +++ b/man2/semget.2 @@ -255,7 +255,9 @@ Values greater than .B SEMMSL * SEMMNI makes it irrelevant. .SH BUGS -The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW +The name choice +.B IPC_PRIVATE +was perhaps unfortunate, IPC_NEW would more clearly show its function. .LP The semaphores in a set are not initialized by