Output is unchanged, except for one font change for a punctuation mark (futex.2). Signed-off-by: Bjarni Ingi Gislason <bjarniig@xxxxxxxxx> --- man2/fallocate.2 | 52 ++++++------- man2/fanotify_mark.2 | 6 +- man2/fcntl.2 | 126 +++++++++++++++--------------- man2/fork.2 | 6 +- man2/futex.2 | 180 +++++++++++++++++++++---------------------- 5 files changed, 185 insertions(+), 185 deletions(-) diff --git a/man2/fallocate.2 b/man2/fallocate.2 index 7e9577ec8..b1107d5cc 100644 --- a/man2/fallocate.2 +++ b/man2/fallocate.2 @@ -56,7 +56,7 @@ is greater than the file size. Any subregion within the range specified by .I offset and -.IR len +.I len that did not contain data before the call will be initialized to zero. This default behavior closely resembles the behavior of the .BR posix_fallocate (3) @@ -64,9 +64,9 @@ library function, and is intended as a method of optimally implementing that function. .PP After a successful call, subsequent writes into the range specified by -.IR offset +.I offset and -.IR len +.I len are guaranteed not to fail because of lack of disk space. .PP If the @@ -95,7 +95,7 @@ Because allocation is done in block size chunks, may allocate a larger range of disk space than was specified. .SS Deallocating file space Specifying the -.BR FALLOC_FL_PUNCH_HOLE +.B FALLOC_FL_PUNCH_HOLE flag (available since Linux 2.6.38) in .I mode deallocates space (i.e., creates a hole) @@ -110,9 +110,9 @@ After a successful call, subsequent reads from this range will return zeros. .PP The -.BR FALLOC_FL_PUNCH_HOLE +.B FALLOC_FL_PUNCH_HOLE flag must be ORed with -.BR FALLOC_FL_KEEP_SIZE +.B FALLOC_FL_KEEP_SIZE in .IR mode ; in other words, even when punching off the end of the file, the file size @@ -137,7 +137,7 @@ Btrfs (since Linux 3.7) .SS Collapsing file space .\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841 Specifying the -.BR FALLOC_FL_COLLAPSE_RANGE +.B FALLOC_FL_COLLAPSE_RANGE flag (available since Linux 3.15) in .I mode removes a byte range from a file, without leaving a hole. @@ -166,7 +166,7 @@ which varies according to the filesystem type and configuration. If a filesystem has such a requirement, .BR fallocate () fails with the error -.BR EINVAL +.B EINVAL if this requirement is violated. .PP If the region specified by @@ -179,7 +179,7 @@ instead, use to truncate a file. .PP No other flags may be specified in -.IR mode +.I mode in conjunction with .BR FALLOC_FL_COLLAPSE_RANGE . .PP @@ -192,7 +192,7 @@ and XFS. .\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d .SS Zeroing file space Specifying the -.BR FALLOC_FL_ZERO_RANGE +.B FALLOC_FL_ZERO_RANGE flag (available since Linux 3.15) .\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642 in @@ -243,7 +243,7 @@ Btrfs (since Linux 4.16) .\" commit f27451f229966874a8793995b8e6b74326d125df .SS Increasing file space Specifying the -.BR FALLOC_FL_INSERT_RANGE +.B FALLOC_FL_INSERT_RANGE flag (available since Linux 4.1) .\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d @@ -266,12 +266,12 @@ Inserting a hole inside a file increases the file size by bytes. .PP This mode has the same limitations as -.BR FALLOC_FL_COLLAPSE_RANGE +.B FALLOC_FL_COLLAPSE_RANGE regarding the granularity of the operation. If the granularity requirements are not met, .BR fallocate () fails with the error -.BR EINVAL. +.B EINVAL. If the .I offset is equal to or greater than the end of file, an error is returned. @@ -280,7 +280,7 @@ For such operations (i.e., inserting a hole at the end of file), should be used. .PP No other flags may be specified in -.IR mode +.I mode in conjunction with .BR FALLOC_FL_INSERT_RANGE . .PP @@ -335,7 +335,7 @@ was less than or equal to 0. .B EINVAL .I mode is -.BR FALLOC_FL_COLLAPSE_RANGE +.B FALLOC_FL_COLLAPSE_RANGE and the range specified by .I offset plus @@ -345,7 +345,7 @@ reaches or passes the end of the file. .B EINVAL .I mode is -.BR FALLOC_FL_INSERT_RANGE +.B FALLOC_FL_INSERT_RANGE and the range specified by .I offset reaches or passes the end of the file. @@ -353,7 +353,7 @@ reaches or passes the end of the file. .B EINVAL .I mode is -.BR FALLOC_FL_COLLAPSE_RANGE +.B FALLOC_FL_COLLAPSE_RANGE or .BR FALLOC_FL_INSERT_RANGE , but either @@ -370,16 +370,16 @@ or .B FALLOC_FL_INSERT_RANGE and also other flags; no other flags are permitted with -.BR FALLOC_FL_COLLAPSE_RANGE +.B FALLOC_FL_COLLAPSE_RANGE or .BR FALLOC_FL_INSERT_RANGE . .TP .B EINVAL .I mode is -.BR FALLOC_FL_COLLAPSE_RANGE +.B FALLOC_FL_COLLAPSE_RANGE or -.BR FALLOC_FL_ZERO_RANGE +.B FALLOC_FL_ZERO_RANGE or .BR FALLOC_FL_INSERT_RANGE , but the file referred to by @@ -430,11 +430,11 @@ is marked immutable (see .B EPERM .I mode specifies -.BR FALLOC_FL_PUNCH_HOLE +.B FALLOC_FL_PUNCH_HOLE or -.BR FALLOC_FL_COLLAPSE_RANGE +.B FALLOC_FL_COLLAPSE_RANGE or -.BR FALLOC_FL_INSERT_RANGE +.B FALLOC_FL_INSERT_RANGE and the file referred to by .I fd @@ -453,18 +453,18 @@ refers to a pipe or FIFO. .B ETXTBSY .I mode specifies -.BR FALLOC_FL_COLLAPSE_RANGE +.B FALLOC_FL_COLLAPSE_RANGE or .BR FALLOC_FL_INSERT_RANGE , but the file referred to by -.IR fd +.I fd is currently being executed. .SH VERSIONS .BR fallocate () is available on Linux since kernel 2.6.23. Support is provided by glibc since version 2.10. The -.BR FALLOC_FL_* +.B FALLOC_FL_* flags are defined in glibc headers only since version 2.18. .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964 .SH CONFORMING TO diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 index a9a482fe7..f4b9d5fcd 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -255,7 +255,7 @@ An invalid file descriptor was passed in .TP .B EINVAL An invalid value was passed in -.IR flags +.I flags or .IR mask , or @@ -272,9 +272,9 @@ or .TP .B ENOENT The filesystem object indicated by -.IR dirfd +.I dirfd and -.IR pathname +.I pathname does not exist. This error also occurs when trying to remove a mark from an object which is not marked. diff --git a/man2/fcntl.2 b/man2/fcntl.2 index 03533d65b..3d02b94fe 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -102,7 +102,7 @@ The preferred method of checking whether the host kernel supports a particular operation is to invoke .BR fcntl () with the desired -.IR cmd +.I cmd value and then test whether the call failed with .BR EINVAL , indicating that the kernel does not recognize this value. @@ -110,7 +110,7 @@ indicating that the kernel does not recognize this value. .TP .BR F_DUPFD " (\fIint\fP)" Duplicate the file descriptor -.IR fd +.I fd using the lowest-numbered available file descriptor greater than or equal to .IR arg . This is different from @@ -177,7 +177,7 @@ plus is vulnerable to a race condition that may unintentionally leak the file descriptor to the program executed in the child process. See the discussion of the -.BR O_CLOEXEC +.B O_CLOEXEC flag in .BR open (2) for details and a remedy to the problem. @@ -226,9 +226,9 @@ and .B O_NONBLOCK flags. It is not possible to change the -.BR O_DSYNC +.B O_DSYNC and -.BR O_SYNC +.B O_SYNC flags; see BUGS, below. .SS Advisory record locking Linux implements traditional ("process-associated") UNIX record locks, @@ -239,7 +239,7 @@ see the discussion of open file description locks below. .BR F_SETLK , .BR F_SETLKW , and -.BR F_GETLK +.B F_GETLK are used to acquire, release, and test for the existence of record locks (also known as byte-range, file-segment, or file-region locks). The third argument, @@ -543,7 +543,7 @@ As with traditional advisory locks, the third argument to .BR fcntl (), .IR lock , is a pointer to an -.IR flock +.I flock structure. By contrast with traditional record locks, the .I l_pid @@ -701,7 +701,7 @@ asynchronous notification of lost locks. .BR F_SETOWN , .BR F_GETOWN_EX , .BR F_SETOWN_EX , -.BR F_GETSIG +.B F_GETSIG and .B F_SETSIG are used to manage I/O availability signals: @@ -765,7 +765,7 @@ If this permission check fails, then the signal is silently discarded. .IR Note : The -.BR F_SETOWN +.B F_SETOWN operation records the caller's credentials at the time of the .BR fcntl () call, @@ -842,7 +842,7 @@ depending on the value given to The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use -.BR F_SETOWN_EX +.B F_SETOWN_EX to target .B SIGIO and @@ -852,7 +852,7 @@ signals at a particular thread. .BR F_GETOWN_EX " (\fIstruct f_owner_ex *\fP) (since Linux 2.6.32)" Return the current file descriptor owner settings as defined by a previous -.BR F_SETOWN_EX +.B F_SETOWN_EX operation. The information is returned in the structure pointed to by .IR arg , @@ -890,7 +890,7 @@ to a specific thread, process, or process group. The caller specifies the target of signals via .IR arg , which is a pointer to a -.IR f_owner_ex +.I f_owner_ex structure. The .I type @@ -899,7 +899,7 @@ field has one of the following values, which define how is interpreted: .RS .TP -.BR F_OWNER_TID +.B F_OWNER_TID Send the signal to the thread whose thread ID (the value returned by a call to .BR clone (2) @@ -908,12 +908,12 @@ or is specified in .IR pid . .TP -.BR F_OWNER_PID +.B F_OWNER_PID Send the signal to the process whose ID is specified in .IR pid . .TP -.BR F_OWNER_PGRP +.B F_OWNER_PGRP Send the signal to the process group whose ID is specified in .IR pid . @@ -991,7 +991,7 @@ set etc.) to determine which file descriptors are available for I/O. Note that the file descriptor provided in .I si_fd is the one that was specified during the -.BR F_SETSIG +.B F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated @@ -1031,17 +1031,17 @@ or most of the time. .PP The use of -.BR O_ASYNC +.B O_ASYNC is specific to BSD and Linux. The only use of -.BR F_GETOWN +.B F_GETOWN and .B F_SETOWN specified in POSIX.1 is in conjunction with the use of the .B SIGURG signal on sockets. (POSIX does not specify the -.BR SIGIO +.B SIGIO signal.) .BR F_GETOWN_EX , .BR F_SETOWN_EX , @@ -1350,13 +1350,13 @@ to be at least bytes. An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in -.IR /proc/sys/fs/pipe-max-size +.I /proc/sys/fs/pipe-max-size (see .BR proc (5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in -.IR /proc/sys/fs/pipe-max-size +.I /proc/sys/fs/pipe-max-size yield the error .BR EPERM ; a privileged process @@ -1422,7 +1422,7 @@ to the set of seals of the inode referred to by the file descriptor Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes -.BR F_SEAL_SEAL +.B F_SEAL_SEAL (see below), then this call will be rejected with .BR EPERM . Adding a seal that is already set is a no-op, in case @@ -1444,7 +1444,7 @@ is set to .PP The following seals are available: .TP -.BR F_SEAL_SEAL +.B F_SEAL_SEAL If this seal is set, any further call to .BR fcntl () with @@ -1456,7 +1456,7 @@ If the initial set of seals of a file includes .BR F_SEAL_SEAL , then this effectively causes the set of seals to be constant and locked. .TP -.BR F_SEAL_SHRINK +.B F_SEAL_SHRINK If this seal is set, the file in question cannot be reduced in size. This affects .BR open (2) @@ -1471,7 +1471,7 @@ Those calls fail with if you try to shrink the file in question. Increasing the file size is still possible. .TP -.BR F_SEAL_GROW +.B F_SEAL_GROW If this seal is set, the size of the file in question cannot be increased. This affects .BR write (2) @@ -1485,7 +1485,7 @@ These calls fail with if you use them to increase the file size. If you keep the size or shrink it, those calls still work as expected. .TP -.BR F_SEAL_WRITE +.B F_SEAL_WRITE If this seal is set, you cannot modify the contents of the file. Note that shrinking or growing the size of the file is still possible and allowed. @@ -1576,30 +1576,30 @@ then it shall use the value assigned to the inode, if any. The following read/write hints are valid since Linux 4.13: .TP -.BR RWH_WRITE_LIFE_NOT_SET +.B RWH_WRITE_LIFE_NOT_SET No specific hint has been set. This is the default value. .TP -.BR RWH_WRITE_LIFE_NONE +.B RWH_WRITE_LIFE_NONE No specific write lifetime is associated with this file or inode. .TP -.BR RWH_WRITE_LIFE_SHORT +.B RWH_WRITE_LIFE_SHORT Data written to this inode or via this open file description is expected to have a short lifetime. .TP -.BR RWH_WRITE_LIFE_MEDIUM +.B RWH_WRITE_LIFE_MEDIUM Data written to this inode or via this open file description is expected to have a lifetime longer than data written with .BR RWH_WRITE_LIFE_SHORT . .TP -.BR RWH_WRITE_LIFE_LONG +.B RWH_WRITE_LIFE_LONG Data written to this inode or via this open file description is expected to have a lifetime longer than data written with .BR RWH_WRITE_LIFE_MEDIUM . .TP -.BR RWH_WRITE_LIFE_EXTREME +.B RWH_WRITE_LIFE_EXTREME Data written to this inode or via this open file description is expected to have a lifetime longer than data written with @@ -1634,7 +1634,7 @@ behavior. .BR F_GETPIPE_SZ ", " F_SETPIPE_SZ The pipe capacity. .TP -.BR F_GET_SEALS +.B F_GET_SEALS A bit mask identifying the seals that have been set for the inode referred to by .IR fd . @@ -1667,10 +1667,10 @@ or and the file descriptor open mode doesn't match with the type of lock requested. .TP -.BR EBUSY +.B EBUSY .I cmd is -.BR F_SETPIPE_SZ +.B F_SETPIPE_SZ and the new pipe capacity specified in .I arg is smaller than the amount of buffer space currently @@ -1680,7 +1680,7 @@ used to store data in the pipe. .I cmd is .BR F_ADD_SEALS , -.IR arg +.I arg includes .BR F_SEAL_WRITE , and there exists a writable, shared mapping on the file referred to by @@ -1698,9 +1698,9 @@ is outside your accessible address space. .B EINTR .I cmd is -.BR F_SETLKW +.B F_SETLKW or -.BR F_OFD_SETLKW +.B F_OFD_SETLKW and the operation was interrupted by a signal; see .BR signal (7). .TP @@ -1725,17 +1725,17 @@ is not recognized by this kernel. .B EINVAL .I cmd is -.BR F_ADD_SEALS +.B F_ADD_SEALS and .I arg includes an unrecognized sealing bit. .TP -.BR EINVAL +.B EINVAL .I cmd is -.BR F_ADD_SEALS +.B F_ADD_SEALS or -.BR F_GET_SEALS +.B F_GET_SEALS and the filesystem containing the inode referred to by .I fd does not support sealing. @@ -1743,19 +1743,19 @@ does not support sealing. .B EINVAL .I cmd is -.BR F_DUPFD +.B F_DUPFD and .I arg is negative or is greater than the maximum allowable value (see the discussion of -.BR RLIMIT_NOFILE +.B RLIMIT_NOFILE in .BR getrlimit (2)). .TP .B EINVAL .I cmd is -.BR F_SETSIG +.B F_SETSIG and .I arg is not an allowable signal number. @@ -1774,7 +1774,7 @@ was not specified as zero. .B EMFILE .I cmd is -.BR F_DUPFD +.B F_DUPFD and the per-process limit on the number of open file descriptors has been reached. .TP @@ -1787,13 +1787,13 @@ protocol failed (e.g., locking over NFS). was specified in .IR cmd , but -.IR fd +.I fd does not refer to a directory. .TP -.BR EPERM +.B EPERM .I cmd is -.BR F_SETPIPE_SZ +.B F_SETPIPE_SZ and the soft or hard user pipe limit has been reached; see .BR pipe (7). .TP @@ -1822,19 +1822,19 @@ Only the operations .BR F_GETLK , .BR F_SETLK , and -.BR F_SETLKW +.B F_SETLKW are specified in POSIX.1-2001. .PP -.BR F_GETOWN +.B F_GETOWN and .B F_SETOWN are specified in POSIX.1-2001. (To get their definitions, define either .\" .BR _BSD_SOURCE , .\" or -.BR _XOPEN_SOURCE +.B _XOPEN_SOURCE with the value 500 or greater, or -.BR _POSIX_C_SOURCE +.B _POSIX_C_SOURCE with the value 200809L or greater.) .PP .B F_DUPFD_CLOEXEC @@ -1865,15 +1865,15 @@ macro to obtain these definitions.) .BR F_OFD_SETLK , .BR F_OFD_SETLKW , and -.BR F_OFD_GETLK +.B F_OFD_GETLK are Linux-specific (and one must define -.BR _GNU_SOURCE +.B _GNU_SOURCE to obtain their definitions), but work is being done to have them included in the next version of POSIX.1. .PP -.BR F_ADD_SEALS +.B F_ADD_SEALS and -.BR F_GET_SEALS +.B F_GET_SEALS are Linux-specific. .\" FIXME . Once glibc adds support, add a note about FTM requirements .SH NOTES @@ -1988,11 +1988,11 @@ this parameter defaults to 0 (disabled). .SH BUGS .SS F_SETFL It is not possible to use -.BR F_SETFL +.B F_SETFL to change the state of the -.BR O_DSYNC +.B O_DSYNC and -.BR O_SYNC +.B O_SYNC flags. .\" FIXME . According to POSIX.1-2001, O_SYNC should also be modifiable .\" via fcntl(2), but currently Linux does not permit this @@ -2012,7 +2012,7 @@ will be \-1, and .I errno will contain the (positive) process group ID. The Linux-specific -.BR F_GETOWN_EX +.B F_GETOWN_EX operation avoids this problem. .\" mtk, Dec 04: some limited testing on alpha and ia64 seems to .\" indicate that ANY negative PGID value will cause F_GETOWN @@ -2044,7 +2044,7 @@ and signals will be sent to the owner. .\" .SS Deadlock detection The deadlock-detection algorithm employed by the kernel when dealing with -.BR F_SETLKW +.B F_SETLKW requests can yield both false negatives (failures to detect deadlocks, leaving a set of deadlocked processes blocked indefinitely) @@ -2098,7 +2098,7 @@ It is therefore inadvisable to rely on mandatory locking. and .I dnotify.txt in the Linux kernel source directory -.IR Documentation/filesystems/ +.I Documentation/filesystems/ (on older kernels, these files are directly under the .I Documentation/ directory, and diff --git a/man2/fork.2 b/man2/fork.2 index 235a88e50..ab9cbf367 100644 --- a/man2/fork.2 +++ b/man2/fork.2 @@ -132,7 +132,7 @@ when its parent terminates. The default timer slack value is set to the parent's current timer slack value. See the description of -.BR PR_SET_TIMERSLACK +.B PR_SET_TIMERSLACK in .BR prctl (2). .IP * @@ -227,7 +227,7 @@ There are a number of limits that may trigger this error: .RS .IP * 3 the -.BR RLIMIT_NPROC +.B RLIMIT_NPROC soft resource limit (set via .BR setrlimit (2)), which limits the number of processes and threads for a real user ID, @@ -251,7 +251,7 @@ imposed by the cgroup "process number" (PIDs) controller was reached. .TP .B EAGAIN The caller is operating under the -.BR SCHED_DEADLINE +.B SCHED_DEADLINE scheduling policy and does not have the reset-on-fork flag set. See .BR sched (7). diff --git a/man2/futex.2 b/man2/futex.2 index adb8dab89..bc8cacb4d 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -154,7 +154,7 @@ integers that must be aligned on a four-byte boundary. The operation to perform on the futex is specified in the .I futex_op argument; -.IR val +.I val is a value whose meaning and purpose depends on .IR futex_op . .PP @@ -169,7 +169,7 @@ Where one of these arguments is not required, it is ignored. For several blocking operations, the .I timeout argument is a pointer to a -.IR timespec +.I timespec structure that specifies a timeout for the operation. However, notwithstanding the prototype shown above, for some operations, the least significant four bytes of this argument are instead @@ -177,7 +177,7 @@ used as an integer whose meaning is determined by the operation. For these operations, the kernel casts the .I timeout value first to -.IR "unsigned long", +.IR "unsigned long" , then to .IR uint32_t , and in the remainder of this page, this argument is referred to as @@ -185,7 +185,7 @@ and in the remainder of this page, this argument is referred to as when interpreted in this fashion. .PP Where it is required, the -.IR uaddr2 +.I uaddr2 argument is a pointer to a second futex word that is employed by the operation. .PP @@ -218,14 +218,14 @@ This allows the kernel to make some additional performance optimizations. .\" taking reference counts on file backing store, and so on. .IP As a convenience, -.IR <linux/futex.h> +.I <linux/futex.h> defines a set of constants with the suffix -.BR _PRIVATE +.B _PRIVATE that are equivalents of all of the operations listed below, .\" except the obsolete FUTEX_FD, for which the "private" flag was .\" meaningless but with the -.BR FUTEX_PRIVATE_FLAG +.B FUTEX_PRIVATE_FLAG ORed into the constant value. Thus, there are .BR FUTEX_WAIT_PRIVATE , @@ -240,19 +240,19 @@ This option bit can be employed only with the and (since Linux 4.5) .\" commit 337f13046ff03717a9e99675284a817527440a49 -.BR FUTEX_WAIT +.B FUTEX_WAIT operations. .IP If this option is set, the kernel measures the .I timeout against the -.BR CLOCK_REALTIME +.B CLOCK_REALTIME clock. .IP If this option is not set, the kernel measures the .I timeout against the -.BR CLOCK_MONOTONIC +.B CLOCK_MONOTONIC clock. .PP The operation specified in @@ -293,9 +293,9 @@ wake-ups. If another thread changed the value of the futex word after the calling thread decided to block based on the prior value, and if the other thread executed a -.BR FUTEX_WAKE +.B FUTEX_WAKE operation (or similar wake-up) after the value change and before this -.BR FUTEX_WAIT +.B FUTEX_WAIT operation, then the calling thread will observe the value change and will not start to sleep. .IP @@ -306,11 +306,11 @@ timeout for the wait. (This interval will be rounded up to the system clock granularity, and is guaranteed not to expire early.) The timeout is by default measured according to the -.BR CLOCK_MONOTONIC +.B CLOCK_MONOTONIC clock, but, since Linux 4.5, the -.BR CLOCK_REALTIME +.B CLOCK_REALTIME clock can be selected by specifying -.BR FUTEX_CLOCK_REALTIME +.B FUTEX_CLOCK_REALTIME in .IR futex_op . If @@ -320,19 +320,19 @@ is NULL, the call blocks indefinitely. .IR Note : for .BR FUTEX_WAIT , -.IR timeout +.I timeout is interpreted as a -.IR relative +.I relative value. This differs from other futex operations, where .I timeout is interpreted as an absolute value. To obtain the equivalent of -.BR FUTEX_WAIT +.B FUTEX_WAIT with an absolute timeout, employ -.BR FUTEX_WAIT_BITSET +.B FUTEX_WAIT_BITSET with -.IR val3 +.I val3 specified as .BR FUTEX_BITSET_MATCH_ANY . .IP @@ -367,7 +367,7 @@ on the futex word at the address Most commonly, .I val is specified as either 1 (wake up a single waiter) or -.BR INT_MAX +.B INT_MAX (wake up all waiters). No guarantee is provided about which waiters are awoken (e.g., a waiter with a higher scheduling priority is not guaranteed @@ -401,7 +401,7 @@ the futex at .IR uaddr . The caller must close the returned file descriptor after use. When another process or thread performs a -.BR FUTEX_WAKE +.B FUTEX_WAKE on the futex word, the file descriptor indicates as being readable with .BR select (2), .BR poll (2), @@ -433,7 +433,7 @@ from Linux 2.6.26 onward. .TP .BR FUTEX_REQUEUE " (since Linux 2.6.0)" This operation performs the same task as -.BR FUTEX_CMP_REQUEUE +.B FUTEX_CMP_REQUEUE (see below), except that no check is made using the value in .IR val3 . (The argument @@ -487,9 +487,9 @@ Typical values to specify for .I val are 0 or 1. (Specifying -.BR INT_MAX +.B INT_MAX is not useful, because it would make the -.BR FUTEX_CMP_REQUEUE +.B FUTEX_CMP_REQUEUE operation equivalent to .BR FUTEX_WAKE .) The limit value specified via @@ -497,7 +497,7 @@ The limit value specified via is typically either 1 or .BR INT_MAX . (Specifying the argument as 0 is not useful, because it would make the -.BR FUTEX_CMP_REQUEUE +.B FUTEX_CMP_REQUEUE operation equivalent to .BR FUTEX_WAIT .) .IP @@ -519,9 +519,9 @@ conditions, which allows race conditions to be avoided in certain use cases. .\" Subject: Re: Add futex wrapper to glibc? .IP Both -.BR FUTEX_REQUEUE +.B FUTEX_REQUEUE and -.BR FUTEX_CMP_REQUEUE +.B FUTEX_CMP_REQUEUE can be used to avoid "thundering herd" wake-ups that could occur when using .B FUTEX_WAKE in cases where all of the waiters that are woken need to acquire @@ -570,12 +570,12 @@ The most notable example is the implementation of which requires operations on two futexes, the one used to implement the mutex and the one used in the implementation of the wait queue associated with the condition variable. -.BR FUTEX_WAKE_OP +.B FUTEX_WAKE_OP allows such cases to be implemented without leading to high rates of contention and context switching. .IP The -.BR FUTEX_WAKE_OP +.B FUTEX_WAKE_OP operation is equivalent to executing the following code atomically and totally ordered with respect to other futex operations on any of the two supplied futex words: @@ -591,12 +591,12 @@ if (oldval \fIcmp\fP \fIcmparg\fP) .in .IP In other words, -.BR FUTEX_WAKE_OP +.B FUTEX_WAKE_OP does the following: .RS .IP * 3 saves the original value of the futex word at -.IR uaddr2 +.I uaddr2 and performs an operation to modify the value of the futex at .IR uaddr2 ; this is an atomic read-modify-write memory access (i.e., using atomic @@ -671,7 +671,7 @@ FUTEX_OP_XOR 4 /* uaddr2 ^= oparg; */ In addition, bit-wise ORing the following value into .I op causes -.IR "(1\ <<\ oparg)" +.I "(1\ <<\ oparg)" to be used as the operand: .IP .in +4n @@ -696,9 +696,9 @@ FUTEX_OP_CMP_GE 5 /* if (oldval >= cmparg) wake */ .in .IP The return value of -.BR FUTEX_WAKE_OP +.B FUTEX_WAKE_OP is the sum of the number of waiters woken on the futex -.IR uaddr +.I uaddr plus the number of waiters woken on the futex .IR uaddr2 . .\" @@ -708,14 +708,14 @@ plus the number of waiters woken on the futex .BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)" .\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d This operation is like -.BR FUTEX_WAIT +.B FUTEX_WAIT except that .I val3 is used to provide a 32-bit bit mask to the kernel. This bit mask, in which at least one bit must be set, is stored in the kernel-internal state of the waiter. See the description of -.BR FUTEX_WAKE_BITSET +.B FUTEX_WAKE_BITSET for further details. .IP If @@ -737,7 +737,7 @@ argument is ignored. .BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)" .\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d This operation is the same as -.BR FUTEX_WAKE +.B FUTEX_WAKE except that the .I val3 argument is used to provide a 32-bit bit mask to the kernel. @@ -753,9 +753,9 @@ All of the waiters for which the result of the AND is nonzero are woken up; the remaining waiters are left sleeping. .IP The effect of -.BR FUTEX_WAIT_BITSET +.B FUTEX_WAIT_BITSET and -.BR FUTEX_WAKE_BITSET +.B FUTEX_WAKE_BITSET is to allow selective wake-ups among multiple waiters that are blocked on the same futex. However, note that, depending on the use case, @@ -784,26 +784,26 @@ The constant which corresponds to all 32 bits set in the bit mask, can be used as the .I val3 argument for -.BR FUTEX_WAIT_BITSET +.B FUTEX_WAIT_BITSET and .BR FUTEX_WAKE_BITSET . Other than differences in the handling of the .I timeout argument, the -.BR FUTEX_WAIT +.B FUTEX_WAIT operation is equivalent to -.BR FUTEX_WAIT_BITSET +.B FUTEX_WAIT_BITSET with -.IR val3 +.I val3 specified as .BR FUTEX_BITSET_MATCH_ANY ; that is, allow a wake-up by any waker. The -.BR FUTEX_WAKE +.B FUTEX_WAKE operation is equivalent to -.BR FUTEX_WAKE_BITSET +.B FUTEX_WAKE_BITSET with -.IR val3 +.I val3 specified as .BR FUTEX_BITSET_MATCH_ANY ; that is, wake up any waiter(s). @@ -884,7 +884,7 @@ bit shall be set in the futex word's value; in other words, this value is: FUTEX_WAITERS | TID .IP (Note that is invalid for a PI futex word to have no owner and -.BR FUTEX_WAITERS +.B FUTEX_WAITERS set.) .PP With this policy in place, @@ -964,7 +964,7 @@ and are subject to some additional requirements: and .B FUTEX_TRYLOCK_PI pair with -.BR FUTEX_UNLOCK_PI. +.BR FUTEX_UNLOCK_PI . .B FUTEX_UNLOCK_PI must be called only on a futex owned by the calling thread, as defined by the value policy, otherwise the error @@ -1059,16 +1059,16 @@ the enqueueing of the waiter is in descending priority order. .BR SCHED_DEADLINE , .BR SCHED_FIFO , and -.BR SCHED_RR +.B SCHED_RR scheduling policies in .BR sched (7).) The owner inherits either the waiter's CPU bandwidth (if the waiter is scheduled under the -.BR SCHED_DEADLINE +.B SCHED_DEADLINE policy) or the waiter's priority (if the waiter is scheduled under the -.BR SCHED_RR +.B SCHED_RR or -.BR SCHED_FIFO +.B SCHED_FIFO policy). .\" August 2015: .\" mtk: If the realm is restricted purely to SCHED_OTHER (SCHED_NORMAL) @@ -1087,7 +1087,7 @@ If .I timeout is not NULL, the structure it points to specifies an absolute timeout, measured against the -.BR CLOCK_REALTIME +.B CLOCK_REALTIME clock. .\" 2016-07-07 response from Thomas Gleixner on LKML: .\" From: Thomas Gleixner <tglx@xxxxxxxxxxxxx> @@ -1113,7 +1113,7 @@ The .IR uaddr2 , .IR val , and -.IR val3 +.I val3 arguments are ignored. .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -1155,7 +1155,7 @@ The .IR val , .IR timeout , and -.IR val3 +.I val3 arguments are ignored. .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -1178,7 +1178,7 @@ The .IR val , .IR timeout , and -.IR val3 +.I val3 arguments are ignored. .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -1239,7 +1239,7 @@ arguments serve the same purposes as for Wait on a non-PI futex at .I uaddr and potentially be requeued (via a -.BR FUTEX_CMP_REQUEUE_PI +.B FUTEX_CMP_REQUEUE_PI operation in another task) onto a PI futex at .IR uaddr2 . The wait operation on @@ -1250,12 +1250,12 @@ is the same as for The waiter can be removed from the wait on .I uaddr without requeueing on -.IR uaddr2 +.I uaddr2 via a -.BR FUTEX_WAKE +.B FUTEX_WAKE operation in another task. In this case, the -.BR FUTEX_WAIT_REQUEUE_PI +.B FUTEX_WAIT_REQUEUE_PI operation fails with the error .BR EAGAIN . .IP @@ -1272,18 +1272,18 @@ The argument is ignored. .IP The -.BR FUTEX_WAIT_REQUEUE_PI +.B FUTEX_WAIT_REQUEUE_PI and -.BR FUTEX_CMP_REQUEUE_PI +.B FUTEX_CMP_REQUEUE_PI were added to support a fairly specific use case: support for priority-inheritance-aware POSIX threads condition variables. The idea is that these operations should always be paired, in order to ensure that user space and the kernel remain in sync. Thus, in the -.BR FUTEX_WAIT_REQUEUE_PI +.B FUTEX_WAIT_REQUEUE_PI operation, the user-space application pre-specifies the target of the requeue that takes place in the -.BR FUTEX_CMP_REQUEUE_PI +.B FUTEX_CMP_REQUEUE_PI operation. .\" .\" Darren Hart notes that a patch to allow glibc to fully support @@ -1431,7 +1431,7 @@ The value pointed to by is not equal to the expected value .IR val3 . .TP -.BR EAGAIN +.B EAGAIN .RB ( FUTEX_LOCK_PI , .BR FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) @@ -1444,7 +1444,7 @@ is about to exit, but has not yet handled the internal state cleanup. Try again. .TP -.BR EDEADLK +.B EDEADLK .RB ( FUTEX_LOCK_PI , .BR FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) @@ -1452,7 +1452,7 @@ The futex word at .I uaddr is already locked by the caller. .TP -.BR EDEADLK +.B EDEADLK .\" FIXME . I see that kernel/locking/rtmutex.c uses EDEADLK in some .\" places, and EDEADLOCK in others. On almost all architectures .\" these constants are synonymous. Is there a reason that both @@ -1485,18 +1485,18 @@ a spurious wakeup; since Linux 2.6.22, this no longer happens. .TP .B EINVAL The operation in -.IR futex_op +.I futex_op is one of those that employs a timeout, but the supplied .I timeout argument was invalid .RI ( tv_sec was less than zero, or -.IR tv_nsec +.I tv_nsec was not less than 1,000,000,000). .TP .B EINVAL The operation specified in -.IR futex_op +.I futex_op employs one or both of the pointers .I uaddr and @@ -1508,17 +1508,17 @@ the address is not four-byte-aligned. .RB ( FUTEX_WAIT_BITSET , .BR FUTEX_WAKE_BITSET ) The bit mask supplied in -.IR val3 +.I val3 is zero. .TP .B EINVAL .RB ( FUTEX_CMP_REQUEUE_PI ) .I uaddr equals -.IR uaddr2 +.I uaddr2 (i.e., an attempt was made to requeue to the same futex). .TP -.BR EINVAL +.B EINVAL .RB ( FUTEX_FD ) The signal number supplied in .I val @@ -1533,7 +1533,7 @@ is invalid. The kernel detected an inconsistency between the user-space state at .I uaddr and the kernel state\(emthat is, it detected a waiter which waits in -.BR FUTEX_LOCK_PI +.B FUTEX_LOCK_PI on .IR uaddr . .TP @@ -1548,7 +1548,7 @@ This indicates either state corruption or that the kernel found a waiter on .I uaddr which is waiting via -.BR FUTEX_WAIT +.B FUTEX_WAIT or .BR FUTEX_WAIT_BITSET . .TP @@ -1561,9 +1561,9 @@ and the kernel state; .\" The kernel sees: I have non PI state for a futex you tried to .\" tell me was PI that is, the kernel detected a waiter which waits via -.BR FUTEX_WAIT +.B FUTEX_WAIT or -.BR FUTEX_WAIT_BITSET +.B FUTEX_WAIT_BITSET on .IR uaddr2 . .TP @@ -1573,9 +1573,9 @@ The kernel detected an inconsistency between the user-space state at .I uaddr and the kernel state; that is, the kernel detected a waiter which waits via -.BR FUTEX_WAIT +.B FUTEX_WAIT or -.BR FUTEX_WAIT_BITESET +.B FUTEX_WAIT_BITESET on .IR uaddr . .TP @@ -1587,7 +1587,7 @@ and the kernel state; that is, the kernel detected a waiter which waits on .I uaddr via -.BR FUTEX_LOCK_PI +.B FUTEX_LOCK_PI (instead of .BR FUTEX_WAIT_REQUEUE_PI ). .TP @@ -1614,7 +1614,7 @@ Invalid argument. .RB ( FUTEX_FD ) The system-wide limit on the total number of open files has been reached. .TP -.BR ENOMEM +.B ENOMEM .RB ( FUTEX_LOCK_PI , .BR FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) @@ -1626,7 +1626,7 @@ Invalid operation specified in .TP .B ENOSYS The -.BR FUTEX_CLOCK_REALTIME +.B FUTEX_CLOCK_REALTIME option was specified in .IR futex_op , but the accompanying operation was neither @@ -1635,7 +1635,7 @@ but the accompanying operation was neither nor .BR FUTEX_WAIT_REQUEUE_PI . .TP -.BR ENOSYS +.B ENOSYS .RB ( FUTEX_LOCK_PI , .BR FUTEX_TRYLOCK_PI , .BR FUTEX_UNLOCK_PI , @@ -1645,7 +1645,7 @@ A run-time check determined that the operation is not available. The PI-futex operations are not implemented on all architectures and are not supported on some CPU variants. .TP -.BR EPERM +.B EPERM .RB ( FUTEX_LOCK_PI , .BR FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) @@ -1657,11 +1657,11 @@ the futex at .IR uaddr2 ). (This may be caused by a state corruption in user space.) .TP -.BR EPERM +.B EPERM .RB ( FUTEX_UNLOCK_PI ) The caller does not own the lock represented by the futex word. .TP -.BR ESRCH +.B ESRCH .RB ( FUTEX_LOCK_PI , .BR FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) @@ -1669,7 +1669,7 @@ The thread ID in the futex word at .I uaddr does not exist. .TP -.BR ESRCH +.B ESRCH .RB ( FUTEX_CMP_REQUEUE_PI ) The thread ID in the futex word at .I uaddr2 @@ -1677,7 +1677,7 @@ does not exist. .TP .B ETIMEDOUT The operation in -.IR futex_op +.I futex_op employed the timeout specified in .IR timeout , and the timeout expired before the operation completed. @@ -1717,7 +1717,7 @@ process and a child process use a pair of futexes located inside a shared anonymous mapping to synchronize access to a shared resource: the terminal. The two processes each write -.IR nloops +.I nloops (a command-line argument that defaults to 5 if omitted) messages to the terminal and employ a synchronization protocol that ensures that they alternate in writing messages. -- 2.19.2 -- Bjarni I. Gislason
