diff options
| author | Alejandro Colomar <alx@kernel.org> | 2022-10-26 01:01:32 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2022-10-29 23:51:29 +0200 |
| commit | 22356d97e388c79993c94d43109087d3c8740187 (patch) | |
| tree | 3746eae8880200683dc61f1c44d55e3d62649dfd | |
| parent | 4279e42dd98a11b31fa4e1fcebbb00b7a677bb70 (diff) | |
| download | man-pages-22356d97e388c79993c94d43109087d3c8740187.tar.gz | |
Many pages: Use a consistent style for lists
There are different kinds of lists:
Tagged paragraphs
These are fixed in a separate commit (the previous one).
They are used for a list of tags and their descriptions.
An example is this commit message itself.
Ordered lists
Elements are preceeded by a number in parentheses.
These represent a set of steps that have an order.
When there are substeps, they will be numbered like (4.2).
Positional lists
Elements are preceeded by a number in square brackets
(index). These represent fields in a set. The index will
start at:
0 fields of a C data structure, to be consistent
with arrays.
1 fields of a file, to be consistent with tools like
cut(1).
Alternatives list
Elements are preceeded by a letter in parentheses.
These represent a set of (normally) exclusive
alternatives.
Bullet lists
Elements are preceeded by bullet symbols. Anything that
doesn't fit elsewhere usually is covered by this type of
list.
Notes
Not really a list, but the syntax is identical to
"positional lists".
There should always be 2 spaces between the list symbol and the
elements. This doesn't apply to "tagged paragraphs", which use
the default indentation rules.
Reported-by: Mike Frysinger <vapier@gentoo.org>
Cc: <groff@gnu.org>
Acked-by: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
169 files changed, 1408 insertions, 1408 deletions
diff --git a/man1/iconv.1 b/man1/iconv.1 index 4fd06a1adb..5140e15e1a 100644 --- a/man1/iconv.1 +++ b/man1/iconv.1 @@ -110,7 +110,7 @@ program must first allocate a conversion descriptor using The operation of the latter function is influenced by the setting of the .B GCONV_PATH environment variable: -.IP * 3 +.IP \(bu 3 If .B GCONV_PATH is not set, @@ -121,7 +121,7 @@ and then, based on the configuration, loads the gconv modules needed to perform the conversion. If the system gconv module configuration cache file is not available then the system gconv module configuration file is used. -.IP * +.IP \(bu If .B GCONV_PATH is defined (as a colon-separated list of pathnames), diff --git a/man1/locale.1 b/man1/locale.1 index 0b5e765c79..da240d1167 100644 --- a/man1/locale.1 +++ b/man1/locale.1 @@ -62,9 +62,9 @@ or locale categories (for example, or .BR LC_TIME ). For each argument, the following is displayed: -.IP * 3 +.IP \(bu 3 For a locale keyword, the value of that keyword to be displayed. -.IP * +.IP \(bu For a locale category, the values of all keywords in that category are displayed. .PP diff --git a/man1/localedef.1 b/man1/localedef.1 index 1f6f8efcce..9c393cd669 100644 --- a/man1/localedef.1 +++ b/man1/localedef.1 @@ -57,7 +57,7 @@ etc.), and places the output in The .I outputpath argument is interpreted as follows: -.IP * 3 +.IP \(bu 3 If .I outputpath contains a slash character ('/'), it is interpreted as the name of the @@ -66,7 +66,7 @@ In this case, there is a separate output file for each locale category .RI ( LC_TIME , .IR LC_NUMERIC , and so on). -.IP * +.IP \(bu If the .B \-\-no\-archive option is used, @@ -74,7 +74,7 @@ option is used, is the name of a subdirectory in .I /usr/lib/locale where per-category compiled files are placed. -.IP * +.IP \(bu Otherwise, .I outputpath is the name of a locale and the compiled locale data is added to the diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 index 0c3ec71cdf..eb09cc21d8 100644 --- a/man2/adjtimex.2 +++ b/man2/adjtimex.2 @@ -367,22 +367,22 @@ is a more portable interface for performing the same task as .BR adjtimex (). Other than the following points, it is identical to .BR adjtimex (): -.IP * 3 +.IP \(bu 3 The constants used in .I modes are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus, .BR MOD_OFFSET , .BR MOD_FREQUENCY , and so on), other than the exceptions noted in the following points. -.IP * +.IP \(bu .B MOD_CLKA is the synonym for .BR ADJ_OFFSET_SINGLESHOT . -.IP * +.IP \(bu .B MOD_CLKB is the synonym for .BR ADJ_TICK . -.IP * +.IP \(bu The is no synonym for .BR ADJ_OFFSET_SS_READ , which is not described in the KAPI. @@ -419,25 +419,25 @@ flags. The system clock is not synchronized to a reliable server. This value is returned when any of the following holds true: .RS -.IP * 3 +.IP \(bu 3 Either .B STA_UNSYNC or .B STA_CLOCKERR is set. -.IP * +.IP \(bu .B STA_PPSSIGNAL is clear and either .B STA_PPSFREQ or .B STA_PPSTIME is set. -.IP * +.IP \(bu .B STA_PPSTIME and .B STA_PPSJITTER are both set. -.IP * +.IP \(bu .B STA_PPSFREQ is set and either .B STA_PPSWANDER diff --git a/man2/bpf.2 b/man2/bpf.2 index d23e8333fa..7f56bbcd92 100644 --- a/man2/bpf.2 +++ b/man2/bpf.2 @@ -211,13 +211,13 @@ They allow sharing of data between eBPF kernel programs, and also between kernel and user-space applications. .PP Each map type has the following attributes: -.IP * 3 +.IP \(bu 3 type -.IP * +.IP \(bu maximum number of elements -.IP * +.IP \(bu key size in bytes -.IP * +.IP \(bu value size in bytes .PP The following wrapper functions demonstrate how various @@ -578,20 +578,20 @@ The following map types are supported: .\" commit 0f8e4bd8a1fc8c4185f1630061d0a1f2d197a475 Hash-table maps have the following characteristics: .RS -.IP * 3 +.IP \(bu 3 Maps are created and destroyed by user-space programs. Both user-space and eBPF programs can perform lookup, update, and delete operations. -.IP * +.IP \(bu The kernel takes care of allocating and freeing key/value pairs. -.IP * +.IP \(bu The .BR map_update_elem () helper will fail to insert new element when the .I max_entries limit is reached. (This ensures that eBPF programs cannot exhaust memory.) -.IP * +.IP \(bu .BR map_update_elem () replaces existing elements atomically. .RE @@ -603,7 +603,7 @@ optimized for speed of lookup. .\" commit 28fbcfa08d8ed7c5a50d41a0433aad222835e8e3 Array maps have the following characteristics: .RS -.IP * 3 +.IP \(bu 3 Optimized for fastest possible lookup. In the future the verifier/JIT compiler may recognize lookup() operations that employ a constant key @@ -616,16 +616,16 @@ In other words, .BR array_map_lookup_elem () may be 'inlined' by the verifier/JIT compiler while preserving concurrent access to this map from user space. -.IP * +.IP \(bu All array elements pre-allocated and zero initialized at init time -.IP * +.IP \(bu The key is an array index, and must be exactly four bytes. -.IP * +.IP \(bu .BR map_delete_elem () fails with the error .BR EINVAL , since elements cannot be deleted. -.IP * +.IP \(bu .BR map_update_elem () replaces elements in a .B nonatomic @@ -644,13 +644,13 @@ This is quite often useful for aggregation and accounting of events. .IP Among the uses for array maps are the following: .RS -.IP * 3 +.IP \(bu 3 As "global" eBPF variables: an array of 1 element whose key is (index) 0 and where the value is a collection of 'global' variables which eBPF programs can use to keep state between events. -.IP * +.IP \(bu Aggregation of tracing events into a fixed set of buckets. -.IP * +.IP \(bu Accounting of networking events, for example, number of packets and packet sizes. .RE @@ -775,23 +775,23 @@ For further details of eBPF program types, see below. The remaining fields of .I bpf_attr are set as follows: -.IP * 3 +.IP \(bu 3 .I insns is an array of .I "struct bpf_insn" instructions. -.IP * +.IP \(bu .I insn_cnt is the number of instructions in the program referred to by .IR insns . -.IP * +.IP \(bu .I license is a license string, which must be GPL compatible to call helper functions marked .IR gpl_only . (The licensing rules are the same as for kernel modules, so that also dual licenses, such as "Dual BSD/GPL", may be used.) -.IP * +.IP \(bu .I log_buf is a pointer to a caller-allocated buffer in which the in-kernel verifier can store the verification log. @@ -799,7 +799,7 @@ This log is a multi-line string that can be checked by the program author in order to understand how the verifier came to the conclusion that the eBPF program is unsafe. The format of the output can change at any time as the verifier evolves. -.IP * +.IP \(bu .I log_size size of the buffer pointed to by .IR log_buf . @@ -808,7 +808,7 @@ verifier messages, \-1 is returned and .I errno is set to .BR ENOSPC . -.IP * +.IP \(bu .I log_level verbosity level of the verifier. A value of zero means that the verifier will not provide a log; @@ -1075,16 +1075,16 @@ However they may not store kernel pointers within the maps and are presently limited to the following helper functions: .\" [Linux 5.6] mtk: The list of available functions is, I think, governed .\" by the check in net/core/filter.c::bpf_base_func_proto(). -.IP * 3 +.IP \(bu 3 get_random .PD 0 -.IP * +.IP \(bu get_smp_processor_id -.IP * +.IP \(bu tail_call -.IP * +.IP \(bu ktime_get_ns -.PD 1 +.PD .PP Unprivileged access may be blocked by writing the value 1 to the file .IR /proc/sys/kernel/unprivileged_bpf_disabled . @@ -1151,37 +1151,37 @@ The JIT compiler for eBPF is currently .\" and by checking the documentation for bpf_jit_enable in .\" Documentation/sysctl/net.txt available for the following architectures: -.IP * 3 +.IP \(bu 3 x86-64 (since Linux 3.18; cBPF since Linux 3.0); .\" commit 0a14842f5a3c0e88a1e59fac5c3025db39721f74 .PD 0 -.IP * +.IP \(bu ARM32 (since Linux 3.18; cBPF since Linux 3.4); .\" commit ddecdfcea0ae891f782ae853771c867ab51024c2 -.IP * +.IP \(bu SPARC 32 (since Linux 3.18; cBPF since Linux 3.5); .\" commit 2809a2087cc44b55e4377d7b9be3f7f5d2569091 -.IP * +.IP \(bu ARM-64 (since Linux 3.18); .\" commit e54bcde3d69d40023ae77727213d14f920eb264a -.IP * +.IP \(bu s390 (since Linux 4.1; cBPF since Linux 3.7); .\" commit c10302efe569bfd646b4c22df29577a4595b4580 -.IP * +.IP \(bu PowerPC 64 (since Linux 4.8; cBPF since Linux 3.1); .\" commit 0ca87f05ba8bdc6791c14878464efc901ad71e99 .\" commit 156d0e290e969caba25f1851c52417c14d141b24 -.IP * +.IP \(bu SPARC 64 (since Linux 4.12); .\" commit 7a12b5031c6b947cc13918237ae652b536243b76 -.IP * +.IP \(bu x86-32 (since Linux 4.18); .\" commit 03f5781be2c7b7e728d724ac70ba10799cc710d7 -.IP * +.IP \(bu MIPS 64 (since Linux 4.18; cBPF since Linux 3.16); .\" commit c6610de353da5ca6eee5b8960e838a87a90ead0c .\" commit f381bf6d82f032b7410185b35d000ea370ac706b -.IP * +.IP \(bu riscv (since Linux 5.1). .\" commit 2353ecc6f91fd15b893fa01bf85a1c7a823ee4f2 .PD diff --git a/man2/capget.2 b/man2/capget.2 index c2fcd3f1e4..a9eda28175 100644 --- a/man2/capget.2 +++ b/man2/capget.2 @@ -214,9 +214,9 @@ permitted set. .B EPERM An attempt was made to add a capability to the inheritable set, and either: .RS -.IP * 3 +.IP \(bu 3 that capability was not in the caller's bounding set; or -.IP * +.IP \(bu the capability was not in the caller's permitted set and the caller lacked the .B CAP_SETPCAP diff --git a/man2/chmod.2 b/man2/chmod.2 index f7d36b5868..f09ba4752d 100644 --- a/man2/chmod.2 +++ b/man2/chmod.2 @@ -67,12 +67,12 @@ system calls change a file's mode bits. (The file mode consists of the file permission bits plus the set-user-ID, set-group-ID, and sticky bits.) These system calls differ only in how the file is specified: -.IP * 2 +.IP \(bu 3 .BR chmod () changes the mode of the file specified whose pathname is given in .IR pathname , which is dereferenced if it is a symbolic link. -.IP * +.IP \(bu .BR fchmod () changes the mode of the file referred to by the open file descriptor .IR fd . diff --git a/man2/chown.2 b/man2/chown.2 index 52364f14e5..75229639f8 100644 --- a/man2/chown.2 +++ b/man2/chown.2 @@ -65,16 +65,16 @@ The and .BR lchown () system calls differ only in how the file is specified: -.IP * 2 +.IP \(bu 3 .BR chown () changes the ownership of the file specified by .IR pathname , which is dereferenced if it is a symbolic link. -.IP * +.IP \(bu .BR fchown () changes the ownership of the file referred to by the open file descriptor .IR fd . -.IP * +.IP \(bu .BR lchown () is like .BR chown (), @@ -321,18 +321,18 @@ and .BR "\-o\ sysvgroups" ) .BR mount (8) options, then the rules are as follows: -.IP * 2 +.IP \(bu 3 If the filesystem is mounted with .BR "\-o\ grpid" , then the group of a new file is made the same as that of the parent directory. -.IP * +.IP \(bu If the filesystem is mounted with .B \-o\ nogrpid and the set-group-ID bit is disabled on the parent directory, then the group of a new file is made the same as the process's filesystem GID. -.IP * +.IP \(bu If the filesystem is mounted with .B \-o\ nogrpid and the set-group-ID bit is enabled on the parent directory, diff --git a/man2/clone.2 b/man2/clone.2 index f6f0892606..7198334c73 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -95,14 +95,14 @@ and below. .PP This page describes the following interfaces: -.IP * 3 +.IP \(bu 3 The glibc .BR clone () wrapper function and the underlying system call on which it is based. The main text describes the wrapper function; the differences for the raw system call are described toward the end of this page. -.IP * +.IP \(bu The newer .BR clone3 () system call. @@ -571,7 +571,7 @@ Among the possible use cases for .B CLONE_INTO_CGROUP are the following: .RS -.IP * 3 +.IP \(bu 3 Spawning a process into a cgroup different from the parent's cgroup makes it possible for a service manager to directly spawn new services into dedicated cgroups. @@ -582,7 +582,7 @@ moved into the target cgroup. Furthermore, spawning the child process directly into a target cgroup is significantly cheaper than moving the child process into the target cgroup after it has been created. -.IP * +.IP \(bu The .B CLONE_INTO_CGROUP flag also allows the creation of @@ -590,7 +590,7 @@ frozen child processes by spawning them into a frozen cgroup. (See .BR cgroups (7) for a description of the freezer controller.) -.IP * +.IP \(bu For threaded applications (or even thread implementations which make use of cgroups to limit individual threads), it is possible to establish a fixed cgroup layout before spawning each thread @@ -872,12 +872,12 @@ The close-on-exec flag is set on this new file descriptor. PID file descriptors can be used for the purposes described in .BR pidfd_open (2). .RS -.IP * 3 +.IP \(bu 3 When using .BR clone3 (), the PID file descriptor is placed at the location pointed to by .IR cl_args.pidfd . -.IP * +.IP \(bu When using .BR clone (), the PID file descriptor is placed at the location pointed to by @@ -1808,7 +1808,7 @@ be used for the child's stack using rather than .BR malloc (3) for the following reasons: -.IP * 3 +.IP \(bu 3 .BR mmap (2) allocates a block of memory that starts on a page boundary and is a multiple of the page size. @@ -1816,7 +1816,7 @@ This is useful if we want to establish a guard page (a page with protection .BR PROT_NONE ) at the end of the stack using .BR mprotect (2). -.IP * +.IP \(bu We can specify the .B MAP_STACK flag to request a mapping that is suitable for a stack. diff --git a/man2/close.2 b/man2/close.2 index 48e0d58de2..9efa4c48a1 100644 --- a/man2/close.2 +++ b/man2/close.2 @@ -117,14 +117,14 @@ that may cause unintended side effects. .PP Furthermore, consider the following scenario where two threads are performing operations on the same file descriptor: -.IP 1. 3 +.IP (1) 5 One thread is blocked in an I/O system call on the file descriptor. For example, it is trying to .BR write (2) to a pipe that is already full, or trying to .BR read (2) from a stream socket which currently has no available data. -.IP 2. +.IP (2) Another thread closes the file descriptor. .PP The behavior in this situation varies across systems. diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2 index 692ce7f6c1..a51960eca3 100644 --- a/man2/copy_file_range.2 +++ b/man2/copy_file_range.2 @@ -35,14 +35,14 @@ The following semantics apply for .IR off_in , and similar statements apply to .IR off_out : -.IP * 3 +.IP \(bu 3 If .I off_in is NULL, then bytes are read from .I fd_in starting from the file offset, and the file offset is adjusted by the number of bytes copied. -.IP * +.IP \(bu If .I off_in is not NULL, then diff --git a/man2/delete_module.2 b/man2/delete_module.2 index 310c018e1b..80b21ebb51 100644 --- a/man2/delete_module.2 +++ b/man2/delete_module.2 @@ -38,15 +38,15 @@ as described below. This system call requires privilege. .PP Module removal is attempted according to the following rules: -.IP 1. 4 +.IP (1) 5 If there are other loaded modules that depend on (i.e., refer to symbols defined in) this module, then the call fails. -.IP 2. +.IP (2) Otherwise, if the reference count for the module (i.e., the number of processes currently using the module) is zero, then the module is immediately unloaded. -.IP 3. +.IP (3) If a module has a nonzero reference count, then the behavior depends on the bits set in .IR flags . @@ -61,7 +61,7 @@ flag may additionally be specified. The various combinations for .I flags have the following effect: -.RS 4 +.RS .TP .B flags == O_NONBLOCK The call returns immediately, with an error. @@ -77,14 +77,14 @@ does not specify .BR O_NONBLOCK , the following steps occur: .RS -.IP * 3 +.IP \(bu 3 The module is marked so that no new references are permitted. -.IP * +.IP \(bu If the module's reference count is nonzero, the caller is placed in an uninterruptible sleep state .RB ( TASK_UNINTERRUPTIBLE ) until the reference count is zero, at which point the call unblocks. -.IP * +.IP \(bu The module is unloaded in the usual way. .RE .RE diff --git a/man2/dup.2 b/man2/dup.2 index c2fa4cc248..3ac1aeffb9 100644 --- a/man2/dup.2 +++ b/man2/dup.2 @@ -99,13 +99,13 @@ by a signal handler that allocates a file descriptor, or because a parallel thread allocates a file descriptor. .PP Note the following points: -.IP * 3 +.IP \(bu 3 If .I oldfd is not a valid file descriptor, then the call fails, and .I newfd is not closed. -.IP * +.IP \(bu If .I oldfd is a valid file descriptor, and @@ -122,7 +122,7 @@ does nothing, and returns is the same as .BR dup2 (), except that: -.IP * 3 +.IP \(bu 3 The caller can force the close-on-exec flag to be set for the new file descriptor by specifying .B O_CLOEXEC @@ -131,7 +131,7 @@ in See the description of the same flag in .BR open (2) for reasons why this may be useful. -.IP * +.IP \(bu .\" Ulrich Drepper, LKML, 2008-10-09: .\" We deliberately decided on this change. Otherwise, what is the .\" result of dup3(fd, fd, O_CLOEXEC)? diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2 index dfcb985ec6..130b3c1719 100644 --- a/man2/epoll_wait.2 +++ b/man2/epoll_wait.2 @@ -58,7 +58,7 @@ clock. A call to .BR epoll_wait () will block until either: -.IP \(bu 2 +.IP \(bu 3 a file descriptor delivers an event; .IP \(bu the call is interrupted by a signal handler; or diff --git a/man2/eventfd.2 b/man2/eventfd.2 index afb9ac8273..74736934c4 100644 --- a/man2/eventfd.2 +++ b/man2/eventfd.2 @@ -91,21 +91,21 @@ and whether the .B EFD_SEMAPHORE flag was specified when creating the eventfd file descriptor: .RS -.IP * 3 +.IP \(bu 3 If .B EFD_SEMAPHORE was not specified and the eventfd counter has a nonzero value, then a .BR read (2) returns 8 bytes containing that value, and the counter's value is reset to zero. -.IP * +.IP \(bu If .B EFD_SEMAPHORE was specified and the eventfd counter has a nonzero value, then a .BR read (2) returns 8 bytes containing the value 1, and the counter's value is decremented by 1. -.IP * +.IP \(bu If the eventfd counter is zero at the time of the call to .BR read (2), then the call either blocks until the counter becomes nonzero @@ -150,7 +150,7 @@ and .BR select (2), as follows: .RS -.IP * 3 +.IP \(bu 3 The file descriptor is readable (the .BR select (2) @@ -160,7 +160,7 @@ argument; the .B POLLIN flag) if the counter has a value greater than 0. -.IP * +.IP \(bu The file descriptor is writable (the .BR select (2) @@ -170,7 +170,7 @@ argument; the .B POLLOUT flag) if it is possible to write a value of at least "1" without blocking. -.IP * +.IP \(bu If an overflow of the counter value was detected, then .BR select (2) diff --git a/man2/execve.2 b/man2/execve.2 index e0752613c8..54c2d00409 100644 --- a/man2/execve.2 +++ b/man2/execve.2 @@ -110,12 +110,12 @@ The aforementioned transformations of the effective IDs are .I not performed (i.e., the set-user-ID and set-group-ID bits are ignored) if any of the following is true: -.IP * 3 +.IP \(bu 3 the .I no_new_privs attribute is set for the calling thread (see .BR prctl (2)); -.IP * +.IP \(bu the underlying filesystem is mounted .I nosuid (the @@ -123,7 +123,7 @@ the underlying filesystem is mounted flag for .BR mount (2)); or -.IP * +.IP \(bu the calling process is being ptraced. .PP The capabilities of the program file (see @@ -159,43 +159,43 @@ for binaries linked with glibc (see All process attributes are preserved during an .BR execve (), except the following: -.IP * 3 +.IP \(bu 3 The dispositions of any signals that are being caught are reset to the default .RB ( signal (7)). -.IP * +.IP \(bu Any alternate signal stack is not preserved .RB ( sigaltstack (2)). -.IP * +.IP \(bu Memory mappings are not preserved .RB ( mmap (2)). -.IP * +.IP \(bu Attached System\ V shared memory segments are detached .RB ( shmat (2)). -.IP * +.IP \(bu POSIX shared memory regions are unmapped .RB ( shm_open (3)). -.IP * +.IP \(bu Open POSIX message queue descriptors are closed .RB ( mq_overview (7)). -.IP * +.IP \(bu Any open POSIX named semaphores are closed .RB ( sem_overview (7)). -.IP * +.IP \(bu POSIX timers are not preserved .RB ( timer_create (2)). -.IP * +.IP \(bu Any open directory streams are closed .RB ( opendir (3)). -.IP * +.IP \(bu Memory locks are not preserved .RB ( mlock (2), .BR mlockall (2)). -.IP * +.IP \(bu Exit handlers are not preserved .RB ( atexit (3), .BR on_exit (3)). -.IP * +.IP \(bu The floating-point environment is reset to the default (see .BR fenv (3)). .PP @@ -204,7 +204,7 @@ in POSIX.1. The following Linux-specific process attributes are also not preserved during an .BR execve (): -.IP * 3 +.IP \(bu 3 The process's "dumpable" attribute is set to the value 1, unless a set-user-ID program, a set-group-ID program, or a program with capabilities is being executed, @@ -221,52 +221,52 @@ directory to change to .IR root:root , as described in .BR proc (5). -.IP * +.IP \(bu The .BR prctl (2) .B PR_SET_KEEPCAPS flag is cleared. -.IP * +.IP \(bu (Since Linux 2.4.36 / 2.6.23) If a set-user-ID or set-group-ID program is being executed, then the parent death signal set by .BR prctl (2) .B PR_SET_PDEATHSIG flag is cleared. -.IP * +.IP \(bu The process name, as set by .BR prctl (2) .B PR_SET_NAME (and displayed by .IR "ps\ \-o comm" ), is reset to the name of the new executable file. -.IP * +.IP \(bu The .B SECBIT_KEEP_CAPS .I securebits flag is cleared. See .BR capabilities (7). -.IP * +.IP \(bu The termination signal is reset to .B SIGCHLD (see .BR clone (2)). -.IP * +.IP \(bu The file descriptor table is unshared, undoing the effect of the .B CLONE_FILES flag of .BR clone (2). .PP Note the following further points: -.IP * 3 +.IP \(bu 3 All threads other than the calling thread are destroyed during an .BR execve (). Mutexes, condition variables, and other pthreads objects are not preserved. -.IP * +.IP \(bu The equivalent of \fIsetlocale(LC_ALL, "C")\fP is executed at program start-up. -.IP * +.IP \(bu POSIX.1 specifies that the dispositions of any signals that are ignored or set to the default are left unchanged. POSIX.1 specifies one exception: if @@ -274,16 +274,16 @@ POSIX.1 specifies one exception: if is being ignored, then an implementation may leave the disposition unchanged or reset it to the default; Linux does the former. -.IP * +.IP \(bu Any outstanding asynchronous I/O operations are canceled .RB ( aio_read (3), .BR aio_write (3)). -.IP * +.IP \(bu For the handling of capabilities during .BR execve (), see .BR capabilities (7). -.IP * +.IP \(bu By default, file descriptors remain open across an .BR execve (). File descriptors that are marked close-on-exec are closed; diff --git a/man2/fallocate.2 b/man2/fallocate.2 index fbede0ea22..2940b2f2b0 100644 --- a/man2/fallocate.2 +++ b/man2/fallocate.2 @@ -125,18 +125,18 @@ Not all filesystems support .BR FALLOC_FL_PUNCH_HOLE ; if a filesystem doesn't support the operation, an error is returned. The operation is supported on at least the following filesystems: -.IP * 3 +.IP \(bu 3 XFS (since Linux 2.6.38) -.IP * +.IP \(bu ext4 (since Linux 3.0) .\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622 -.IP * +.IP \(bu Btrfs (since Linux 3.7) -.IP * +.IP \(bu .BR tmpfs (5) (since Linux 3.5) .\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe -.IP * +.IP \(bu .BR gfs2 (5) (since Linux 4.16) .\" commit 4e56a6411fbce6f859566e17298114c2434391a4 @@ -235,16 +235,16 @@ Not all filesystems support .BR FALLOC_FL_ZERO_RANGE ; if a filesystem doesn't support the operation, an error is returned. The operation is supported on at least the following filesystems: -.IP * 3 +.IP \(bu 3 XFS (since Linux 3.15) .\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa -.IP * +.IP \(bu ext4, for extent-based files (since Linux 3.15) .\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0 -.IP * +.IP \(bu SMB3 (since Linux 3.17) .\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556 -.IP * +.IP \(bu Btrfs (since Linux 4.16) .\" commit f27451f229966874a8793995b8e6b74326d125df .SS Increasing file space diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 index 32a8f4a9e5..d43cc897bd 100644 --- a/man2/fanotify_init.2 +++ b/man2/fanotify_init.2 @@ -484,24 +484,24 @@ The limitations imposed on an event listener created by a user without the .B CAP_SYS_ADMIN capability are as follows: .RS -.IP * 3 +.IP \(bu 3 The user cannot request for an unlimited event queue by using .BR FAN_UNLIMITED_QUEUE . -.IP * 3 +.IP \(bu The user cannot request for an unlimited number of marks by using .BR FAN_UNLIMITED_MARKS . -.IP * 3 +.IP \(bu The user cannot request to use either notification classes .B FAN_CLASS_CONTENT or .BR FAN_CLASS_PRE_CONTENT . This means that user cannot request permission events. -.IP * 3 +.IP \(bu The user is required to create a group that identifies filesystem objects by file handles, for example, by providing the .B FAN_REPORT_FID flag. -.IP * 3 +.IP \(bu The user is limited to only mark inodes. The ability to mark a mount or filesystem via .BR fanotify_mark () @@ -510,7 +510,7 @@ through the use of or .B FAN_MARK_FILESYSTEM is not permitted. -.IP * 3 +.IP \(bu The event object in the event queue is limited in terms of the information that is made available to the unprivileged user. A user will also not receive the pid that generated the event, unless the @@ -520,7 +520,7 @@ listening process itself generated the event. This system call is Linux-specific. .SH BUGS The following bug was present in Linux kernels before version 3.18: -.IP * 3 +.IP \(bu 3 .\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 The .B O_CLOEXEC @@ -528,7 +528,7 @@ is ignored when passed in .IR event_f_flags . .PP The following bug was present in Linux kernels before version 3.14: -.IP * 3 +.IP \(bu 3 .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580 The .I event_f_flags diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 index 0afc8c2921..6cd3ae2ae0 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -501,13 +501,13 @@ The filesystem object to be marked is determined by the file descriptor .I dirfd and the pathname specified in .IR pathname : -.IP * 3 +.IP \(bu 3 If .I pathname is NULL, .I dirfd defines the filesystem object to be marked. -.IP * +.IP \(bu If .I pathname is NULL, and @@ -515,13 +515,13 @@ is NULL, and takes the special value .BR AT_FDCWD , the current working directory is to be marked. -.IP * +.IP \(bu If .I pathname is absolute, it defines the filesystem object to be marked, and .I dirfd is ignored. -.IP * +.IP \(bu If .I pathname is relative, and @@ -532,7 +532,7 @@ then the filesystem object to be marked is determined by interpreting .I pathname relative the directory referred to by .IR dirfd . -.IP * +.IP \(bu If .I pathname is relative, and @@ -815,7 +815,7 @@ events for both the ELF binary and interpreter, respectively: .in .SH BUGS The following bugs were present in Linux kernels before version 3.16: -.IP * 3 +.IP \(bu 3 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563 If .I flags @@ -825,13 +825,13 @@ contains and .I pathname must specify a valid filesystem object, even though this object is not used. -.IP * +.IP \(bu .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b .BR readdir (2) does not generate a .B FAN_ACCESS event. -.IP * +.IP \(bu .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406 If .BR fanotify_mark () diff --git a/man2/fcntl.2 b/man2/fcntl.2 index 7da1d51bc5..665dffc01e 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -440,7 +440,7 @@ instead. The record locks described above are associated with the process (unlike the open file description locks described below). This has some unfortunate consequences: -.IP * 3 +.IP \(bu 3 If a process closes .I any file descriptor referring to a file, @@ -456,7 +456,7 @@ or .I /etc/mtab when for some reason a library function decides to open, read, and close the same file. -.IP * +.IP \(bu The threads in a process share locks. In other words, a multithreaded program can't use record locking to ensure diff --git a/man2/fork.2 b/man2/fork.2 index a93fc416cd..eb72696e54 100644 --- a/man2/fork.2 +++ b/man2/fork.2 @@ -50,30 +50,30 @@ performed by one of the processes do not affect the other. .PP The child process is an exact duplicate of the parent process except for the following points: -.IP * 3 +.IP \(bu 3 The child has its own unique process ID, and this PID does not match the ID of any existing process group .RB ( setpgid (2)) or session. -.IP * +.IP \(bu The child's parent process ID is the same as the parent's process ID. -.IP * +.IP \(bu The child does not inherit its parent's memory locks .RB ( mlock (2), .BR mlockall (2)). -.IP * +.IP \(bu Process resource utilizations .RB ( getrusage (2)) and CPU time counters .RB ( times (2)) are reset to zero in the child. -.IP * +.IP \(bu The child's set of pending signals is initially empty .RB ( sigpending (2)). -.IP * +.IP \(bu The child does not inherit semaphore adjustments from its parent .RB ( semop (2)). -.IP * +.IP \(bu The child does not inherit process-associated record locks from its parent .RB ( fcntl (2)). (On the other hand, it does inherit @@ -81,12 +81,12 @@ The child does not inherit process-associated record locks from its parent open file description locks and .BR flock (2) locks from its parent.) -.IP * +.IP \(bu The child does not inherit timers from its parent .RB ( setitimer (2), .BR alarm (2), .BR timer_create (2)). -.IP * +.IP \(bu The child does not inherit outstanding asynchronous I/O operations from its parent .RB ( aio_read (3), @@ -98,33 +98,33 @@ The process attributes in the preceding list are all specified in POSIX.1. The parent and child also differ with respect to the following Linux-specific process attributes: -.IP * 3 +.IP \(bu 3 The child does not inherit directory change notifications (dnotify) from its parent (see the description of .B F_NOTIFY in .BR fcntl (2)). -.IP * +.IP \(bu The .BR prctl (2) .B PR_SET_PDEATHSIG setting is reset so that the child does not receive a signal when its parent terminates. -.IP * +.IP \(bu The default timer slack value is set to the parent's current timer slack value. See the description of .B PR_SET_TIMERSLACK in .BR prctl (2). -.IP * +.IP \(bu Memory mappings that have been marked with the .BR madvise (2) .B MADV_DONTFORK flag are not inherited across a .BR fork (). -.IP * +.IP \(bu Memory in address ranges that have been marked with the .BR madvise (2) .B MADV_WIPEONFORK @@ -133,12 +133,12 @@ flag is zeroed in the child after a (The .B MADV_WIPEONFORK setting remains in place for those address ranges in the child.) -.IP * +.IP \(bu The termination signal of the child is always .B SIGCHLD (see .BR clone (2)). -.IP * +.IP \(bu The port access permission bits set by .BR ioperm (2) are not inherited by the child; @@ -146,7 +146,7 @@ the child must turn on any bits that it requires using .BR ioperm (2). .PP Note the following further points: -.IP * 3 +.IP \(bu 3 The child process is created with a single thread\(emthe one that called .BR fork (). @@ -155,7 +155,7 @@ including the states of mutexes, condition variables, and other pthreads objects; the use of .BR pthread_atfork (3) may be helpful for dealing with problems that this can cause. -.IP * +.IP \(bu After a .BR fork () in a multithreaded program, @@ -163,7 +163,7 @@ the child can safely call only async-signal-safe functions (see .BR signal\-safety (7)) until such time as it calls .BR execve (2). -.IP * +.IP \(bu The child inherits copies of the parent's set of open file descriptors. Each file descriptor in the child refers to the same open file description (see @@ -177,7 +177,7 @@ and .B F_SETSIG in .BR fcntl (2)). -.IP * +.IP \(bu The child inherits copies of the parent's set of open message queue descriptors (see .BR mq_overview (7)). @@ -186,7 +186,7 @@ open message queue description as the corresponding file descriptor in the parent. This means that the two file descriptors share the same flags .RI ( mq_flags ). -.IP * +.IP \(bu The child inherits copies of the parent's set of open directory streams (see .BR opendir (3)). POSIX.1 says that the corresponding directory streams @@ -208,25 +208,25 @@ is set to indicate the error. A system-imposed limit on the number of threads was encountered. There are a number of limits that may trigger this error: .RS -.IP * 3 +.IP \(bu 3 the .B RLIMIT_NPROC soft resource limit (set via .BR setrlimit (2)), which limits the number of processes and threads for a real user ID, was reached; -.IP * +.IP \(bu the kernel's system-wide limit on the number of processes and threads, .IR /proc/sys/kernel/threads\-max , was reached (see .BR proc (5)); -.IP * +.IP \(bu the maximum number of PIDs, .IR /proc/sys/kernel/pid_max , was reached (see .BR proc (5)); or -.IP * +.IP \(bu the PID limit .RI ( pids.max ) imposed by the cgroup "process number" (PIDs) controller was reached. diff --git a/man2/futex.2 b/man2/futex.2 index 4b6a9ae830..c9df0fb806 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -604,20 +604,20 @@ In other words, .B FUTEX_WAKE_OP does the following: .RS -.IP * 3 +.IP \(bu 3 saves the original value of the futex word at .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 machine instructions of the respective architecture) -.IP * +.IP \(bu wakes up a maximum of .I val waiters on the futex for the futex word at .IR uaddr ; and -.IP * +.IP \(bu dependent on the results of a test of the original value of the futex word at .IR uaddr2 , @@ -876,15 +876,15 @@ for the implementation of very specific IPC mechanisms.) The PI-futex operations described below differ from the other futex operations in that they impose policy on the use of the value of the futex word: -.IP * 3 +.IP \(bu 3 If the lock is not acquired, the futex word's value shall be 0. -.IP * +.IP \(bu If the lock is acquired, the futex word's value shall be the thread ID (TID; see .BR gettid (2)) of the owning thread. -.IP * +.IP \(bu If the lock is owned and there are threads contending for the lock, then the .B FUTEX_WAITERS @@ -974,7 +974,7 @@ PI futexes are operated on by specifying one of the values listed below in .IR futex_op . Note that the PI futex operations must be used as paired operations and are subject to some additional requirements: -.IP * 3 +.IP \(bu 3 .BR FUTEX_LOCK_PI , .BR FUTEX_LOCK_PI2 , and @@ -986,7 +986,7 @@ must be called only on a futex owned by the calling thread, as defined by the value policy, otherwise the error .B EPERM results. -.IP * +.IP \(bu .B FUTEX_WAIT_REQUEUE_PI pairs with .BR FUTEX_CMP_REQUEUE_PI . @@ -1056,15 +1056,15 @@ user space atomically by setting the futex value to 0. .\" After that, the kernel: .RS -.IP 1. 3 +.IP (1) 5 Tries to find the thread which is associated with the owner TID. -.IP 2. +.IP (2) Creates or reuses kernel state on behalf of the owner. (If this is the first waiter, there is no kernel state for this futex, so kernel state is created by locking the RT-mutex and the futex owner is made the owner of the RT-mutex. If there are existing waiters, then the existing state is reused.) -.IP 3. +.IP (3) Attaches the waiter to the futex (i.e., the waiter is enqueued on the RT-mutex waiter list). .RE @@ -1945,15 +1945,15 @@ main(int argc, char *argv[]) .BR sched (7) .PP The following kernel source files: -.IP * 2 +.IP \(bu 3 .I Documentation/pi\-futex.txt -.IP * +.IP \(bu .I Documentation/futex\-requeue\-pi.txt -.IP * +.IP \(bu .I Documentation/locking/rt\-mutex.txt -.IP * +.IP \(bu .I Documentation/locking/rt\-mutex\-design.txt -.IP * +.IP \(bu .I Documentation/robust\-futex\-ABI.txt .PP Franke, H., Russell, R., and Kirwood, M., 2002. diff --git a/man2/getrandom.2 b/man2/getrandom.2 index a6bedb1bfd..83ca574625 100644 --- a/man2/getrandom.2 +++ b/man2/getrandom.2 @@ -184,7 +184,7 @@ that was opened by a library. .\" .SS Maximum number of bytes returned As of Linux 3.19 the following limits apply: -.IP * 3 +.IP \(bu 3 When reading from the .I urandom source, a maximum of 33554431 bytes is returned by a single call to @@ -192,7 +192,7 @@ source, a maximum of 33554431 bytes is returned by a single call to on systems where .I int has a size of 32 bits. -.IP * +.IP \(bu When reading from the .I random source, a maximum of 512 bytes is returned. @@ -283,7 +283,7 @@ but the careful programmer will check for this anyway! .SH BUGS As of Linux 3.19, the following bug exists: .\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16 -.IP * 3 +.IP \(bu 3 Depending on CPU load, .BR getrandom () does not react to interrupts before reading all bytes requested. diff --git a/man2/intro.2 b/man2/intro.2 index 9184991503..da5ad34c67 100644 --- a/man2/intro.2 +++ b/man2/intro.2 @@ -21,13 +21,13 @@ Thus, making a system call looks the same as invoking a normal library function. .PP In many cases, the C library wrapper function does nothing more than: -.IP * 3 +.IP \(bu 3 copying arguments and the unique system call number to the registers where the kernel expects them; -.IP * +.IP \(bu trapping to kernel mode, at which point the kernel does the real work of the system call; -.IP * +.IP \(bu setting .I errno if the system call returns an error number when the kernel returns the diff --git a/man2/kexec_load.2 b/man2/kexec_load.2 index 87e9c7a609..d8e0020fd1 100644 --- a/man2/kexec_load.2 +++ b/man2/kexec_load.2 @@ -128,7 +128,7 @@ If these checks pass, the kernel copies the segment data to kernel memory. Each segment specified in .I segments is copied as follows: -.IP * 3 +.IP \(bu 3 .I buf and .I bufsz @@ -139,14 +139,14 @@ The value in may not exceed the value in the .I memsz field. -.IP * +.IP \(bu .I mem and .I memsz specify a physical address range that is the target of the copy. The values specified in both fields must be multiples of the system page size. -.IP * +.IP \(bu .I bufsz bytes are copied from the source buffer to the target kernel buffer. If diff --git a/man2/keyctl.2 b/man2/keyctl.2 index 901e1aac4b..0aad89a626 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -173,7 +173,7 @@ Otherwise, is treated as the description (name) of a keyring, and the behavior is as follows: .RS -.IP * 3 +.IP \(bu 3 If a keyring with a matching description exists, the process will attempt to subscribe to that keyring as its session keyring if possible; @@ -182,7 +182,7 @@ In order to subscribe to the keyring, the caller must have .I search permission on the keyring. -.IP * +.IP \(bu If a keyring with a matching description does not exist, then a new keyring with the specified description is created, and the process is subscribed to that keyring as its session keyring. @@ -2028,20 +2028,20 @@ Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf .PP The last few lines of the above output show that the example program was able to fetch: -.IP * 3 +.IP \(bu 3 the description of the key to be instantiated, which included the name of the key .RI ( mykey ); -.IP * +.IP \(bu the payload of the authorization key, which consisted of the data .RI ( somepayloaddata ) passed to .BR request_key (2); -.IP * +.IP \(bu the destination keyring that was specified in the call to .BR request_key (2); and -.IP * +.IP \(bu the description of the authorization key, where we can see that the name of the authorization key matches the ID of the key that is to be instantiated diff --git a/man2/listen.2 b/man2/listen.2 index 7b71dfea49..fb9908f039 100644 --- a/man2/listen.2 +++ b/man2/listen.2 @@ -96,20 +96,20 @@ first appeared in 4.2BSD). .SH NOTES To accept connections, the following steps are performed: .RS 4 -.IP 1. 4 +.IP (1) 5 A socket is created with .BR socket (2). -.IP 2. +.IP (2) The socket is bound to a local address using .BR bind (2), so that other sockets may be .BR connect (2)ed to it. -.IP 3. +.IP (3) A willingness to accept incoming connections and a queue limit for incoming connections are specified with .BR listen (). -.IP 4. +.IP (4) Connections are accepted with .BR accept (2). .RE diff --git a/man2/lseek.2 b/man2/lseek.2 index 718d82421c..f329f14484 100644 --- a/man2/lseek.2 +++ b/man2/lseek.2 @@ -137,26 +137,26 @@ The and .B SEEK_DATA operations are supported for the following filesystems: -.IP * 3 +.IP \(bu 3 Btrfs (since Linux 3.1) -.IP * 3 +.IP \(bu OCFS (since Linux 3.2) .\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1 -.IP * +.IP \(bu XFS (since Linux 3.5) -.IP * +.IP \(bu ext4 (since Linux 3.8) -.IP * +.IP \(bu .BR tmpfs (5) (since Linux 3.8) -.IP * +.IP \(bu NFS (since Linux 3.18) .\" commit 1c6dcbe5ceff81c2cf8d929646af675cd59fe7c0 .\" commit 24bab491220faa446d945624086d838af41d616c -.IP * +.IP \(bu FUSE (since Linux 4.5) .\" commit 0b5da8db145bfd44266ac964a2636a0cf8d7c286 -.IP * +.IP \(bu GFS2 (since Linux 4.15) .\" commit 3a27411cb4bc3ce31db228e3569ad01b462a4310 .SH RETURN VALUE diff --git a/man2/memfd_create.2 b/man2/memfd_create.2 index ea9206499f..af3d833bd3 100644 --- a/man2/memfd_create.2 +++ b/man2/memfd_create.2 @@ -259,20 +259,20 @@ by allowing a process to operate secure in the knowledge that its peer can't modify the shared memory in an undesired fashion. .PP An example of the usage of the sealing mechanism is as follows: -.IP 1. 3 +.IP (1) 5 The first process creates a .BR tmpfs (5) file using .BR memfd_create (). The call yields a file descriptor used in subsequent steps. -.IP 2. +.IP (2) The first process sizes the file created in the previous step using .BR ftruncate (2), maps it using .BR mmap (2), and populates the shared memory with the desired data. -.IP 3. +.IP (3) The first process uses the .BR fcntl (2) .B F_ADD_SEALS @@ -291,13 +291,13 @@ which will prevent future writes via and .BR write (2) from succeeding while keeping existing shared writable mappings). -.IP 4. +.IP (4) A second process obtains a file descriptor for the .BR tmpfs (5) file and maps it. Among the possible ways in which this could happen are the following: .RS -.IP * 3 +.IP \(bu 3 The process that called .BR memfd_create () could transfer the resulting file descriptor to the second process @@ -307,7 +307,7 @@ and .BR cmsg (3)). The second process then maps the file using .BR mmap (2). -.IP * +.IP \(bu The second process is created via .BR fork (2) and thus automatically inherits the file descriptor and mapping. @@ -315,7 +315,7 @@ and thus automatically inherits the file descriptor and mapping. there is a natural trust relationship between the two processes, since they are running under the same user ID. Therefore, file sealing would not normally be necessary.) -.IP * +.IP \(bu The second process opens the file .IR /proc/<pid>/fd/<fd> , where @@ -330,7 +330,7 @@ in that process. The second process then maps the file using .BR mmap (2). .RE -.IP 5. +.IP (5) The second process uses the .BR fcntl (2) .B F_GET_SEALS diff --git a/man2/mount.2 b/man2/mount.2 index 60622dfe85..28a9a1ebb6 100644 --- a/man2/mount.2 +++ b/man2/mount.2 @@ -73,17 +73,17 @@ The choice of which operation to perform is determined by testing the bits set in .IR mountflags , with the tests being conducted in the order listed here: -.IP * 3 +.IP \(bu 3 Remount an existing mount: .I mountflags includes .BR MS_REMOUNT . -.IP * +.IP \(bu Create a bind mount: .I mountflags includes .BR MS_BIND . -.IP * +.IP \(bu Change the propagation type of an existing mount: .I mountflags includes one of @@ -92,12 +92,12 @@ includes one of .BR MS_SLAVE , or .BR MS_UNBINDABLE . -.IP * +.IP \(bu Move an existing mount to a new location: .I mountflags includes .BR MS_MOVE . -.IP * +.IP \(bu Create a new mount: .I mountflags includes none of the above flags. @@ -134,17 +134,17 @@ Reduce on-disk updates of inode timestamps (atime, mtime, ctime) by maintaining these changes only in memory. The on-disk timestamps are updated only when: .RS -.IP (a) 4 +.IP \(bu 3 the inode needs to be updated for some change unrelated to file timestamps; -.IP (b) +.IP \(bu the application employs .BR fsync (2), .BR syncfs (2), or .BR sync (2); -.IP (c) +.IP \(bu an undeleted inode is evicted from memory; or -.IP (d) +.IP \(bu more than 24 hours have passed since the inode was written to disk. .RE .IP @@ -292,16 +292,16 @@ meaning that all mounts of the same filesystem share those flags. (Previously, all of the flags were per-superblock.) .PP The per-mount-point flags are as follows: -.IP * 3 +.IP \(bu 3 Since Linux 2.4: .BR MS_NODEV ", " MS_NOEXEC ", and " MS_NOSUID flags are settable on a per-mount-point basis. -.IP * +.IP \(bu Additionally, since Linux 2.6.16: .B MS_NOATIME and .BR MS_NODIRATIME . -.IP * +.IP \(bu Additionally, since Linux 2.6.20: .BR MS_RELATIME . .PP diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2 index 4acbbc171b..696071947e 100644 --- a/man2/mount_setattr.2 +++ b/man2/mount_setattr.2 @@ -641,8 +641,8 @@ capability in the user namespace the filesystem was mounted in. The underlying filesystem must support ID-mapped mounts. Currently, the following filesystems support ID-mapped mounts: .\" fs_flags = FS_ALLOW_IDMAP in kernel sources -.PP -.RS 3 +.IP +.RS .PD 0 .IP \(bu 3 .BR xfs (5) diff --git a/man2/move_pages.2 b/man2/move_pages.2 index 9aeb46558e..437e468b77 100644 --- a/man2/move_pages.2 +++ b/man2/move_pages.2 @@ -53,13 +53,13 @@ is 0, then moves pages of the calling process. .PP To move pages in another process requires the following privileges: -.IP * 3 +.IP \(bu 3 In kernels up to and including Linux 4.12: the caller must be privileged .RB ( CAP_SYS_NICE ) or the real or effective user ID of the calling process must match the real or saved-set user ID of the target process. -.IP * +.IP \(bu The older rules allowed the caller to discover various virtual address choices made by the kernel that could lead to the defeat of address-space-layout randomization diff --git a/man2/mremap.2 b/man2/mremap.2 index e642f61715..5ff3d0e366 100644 --- a/man2/mremap.2 +++ b/man2/mremap.2 @@ -170,10 +170,10 @@ whole address space requested, but those mappings are of different types. An invalid argument was given. Possible causes are: .RS -.IP * 3 +.IP \(bu 3 \fIold_address\fP was not page aligned; -.IP * +.IP \(bu a value other than .B MREMAP_MAYMOVE or @@ -182,15 +182,15 @@ or .B MREMAP_DONTUNMAP was specified in .IR flags ; -.IP * +.IP \(bu .I new_size was zero; -.IP * +.IP \(bu .I new_size or .I new_address was invalid; -.IP * +.IP \(bu the new address range specified by .I new_address and @@ -199,29 +199,29 @@ overlapped the old address range specified by .I old_address and .IR old_size ; -.IP * +.IP \(bu .B MREMAP_FIXED or .B MREMAP_DONTUNMAP was specified without also specifying .BR MREMAP_MAYMOVE ; -.IP * +.IP \(bu .B MREMAP_DONTUNMAP was specified, but one or more pages in the range specified by .I old_address and .I old_size were not private anonymous; -.IP * +.IP \(bu .B MREMAP_DONTUNMAP was specified and .I old_size was not equal to .IR new_size ; -.IP * +.IP \(bu \fIold_size\fP was zero and \fIold_address\fP does not refer to a shareable mapping (but see BUGS); -.IP * +.IP \(bu \fIold_size\fP was zero and the .B MREMAP_MAYMOVE flag was not specified. @@ -231,12 +231,12 @@ flag was not specified. Not enough memory was available to complete the operation. Possible causes are: .RS -.IP * 3 +.IP \(bu 3 The memory area cannot be expanded at the current virtual address, and the .B MREMAP_MAYMOVE flag is not set in \fIflags\fP. Or, there is not enough (virtual) memory available. -.IP * +.IP \(bu .B MREMAP_DONTUNMAP was used causing a new mapping to be created that would exceed the (virtual) memory available. @@ -292,7 +292,7 @@ argument. Possible applications for .B MREMAP_DONTUNMAP include: -.IP * 3 +.IP \(bu 3 Non-cooperative .BR userfaultfd (2): an application can yank out a virtual address range using @@ -301,7 +301,7 @@ and then employ a .BR userfaultfd (2) handler to handle the page faults that subsequently occur as other threads in the process touch pages in the yanked range. -.IP * +.IP \(bu Garbage collection: .B MREMAP_DONTUNMAP can be used in conjunction with diff --git a/man2/msgget.2 b/man2/msgget.2 index 2b735f9386..76aeb5134b 100644 --- a/man2/msgget.2 +++ b/man2/msgget.2 @@ -90,7 +90,7 @@ then its associated data structure (see .BR msgctl (2)) is initialized as follows: -.IP \(bu 2 +.IP \(bu 3 .I msg_perm.cuid and .I msg_perm.uid diff --git a/man2/msgop.2 b/man2/msgop.2 index a46f79cee6..37deacd8a5 100644 --- a/man2/msgop.2 +++ b/man2/msgop.2 @@ -95,7 +95,7 @@ bytes, but this limit can be modified using .BR msgctl (2). A message queue is considered to be full if either of the following conditions is true: -.IP \(bu 2 +.IP \(bu 3 Adding a new message to the queue would cause the total number of bytes in the queue to exceed the queue's maximum size (the .I msg_qbytes @@ -124,7 +124,7 @@ then the call instead fails with the error A blocked .BR msgsnd () call may also fail if: -.IP \(bu 2 +.IP \(bu 3 the queue is removed, in which case the system call fails with .I errno @@ -146,7 +146,7 @@ flag when establishing a signal handler.) .PP Upon successful completion the message queue data structure is updated as follows: -.IP \(bu 2 +.IP \(bu 3 .I msg_lspid is set to the process ID of the calling process. .IP \(bu @@ -198,7 +198,7 @@ is specified in the .I msgtyp argument specifies the type of message requested, as follows: -.IP \(bu 2 +.IP \(bu 3 If .I msgtyp is 0, @@ -285,7 +285,7 @@ If no message of the requested type is available and isn't specified in .IR msgflg , the calling process is blocked until one of the following conditions occurs: -.IP \(bu 2 +.IP \(bu 3 A message of the desired type is placed in the queue. .IP \(bu The message queue is removed from the system. diff --git a/man2/open.2 b/man2/open.2 index 6f08a305eb..3c7ce161fe 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -502,11 +502,11 @@ when the file is .IP This flag can be employed only if one of the following conditions is true: .RS -.IP * 3 +.IP \(bu 3 The effective UID of the process .\" Strictly speaking: the filesystem UID matches the owner UID of the file. -.IP * +.IP \(bu The calling process has the .B CAP_FOWNER capability in its user namespace and @@ -617,40 +617,40 @@ The following operations .I can be performed on the resulting file descriptor: .RS -.IP * 3 +.IP \(bu 3 .BR close (2). -.IP * +.IP \(bu .BR fchdir (2), if the file descriptor refers to a directory (since Linux 3.5). .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24 -.IP * +.IP \(bu .BR fstat (2) (since Linux 3.6). -.IP * +.IP \(bu .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2 .BR fstatfs (2) (since Linux 3.12). .\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf -.IP * +.IP \(bu Duplicating the file descriptor .RB ( dup (2), .BR fcntl (2) .BR F_DUPFD , etc.). -.IP * +.IP \(bu Getting and setting file descriptor flags .RB ( fcntl (2) .B F_GETFD and .BR F_SETFD ). -.IP * +.IP \(bu Retrieving open file status flags using the .BR fcntl (2) .B F_GETFL operation: the returned flags will include the bit .BR O_PATH . -.IP * +.IP \(bu Passing the file descriptor as the .I dirfd argument of @@ -663,7 +663,7 @@ with (or via procfs using .BR AT_SYMLINK_FOLLOW ) even if the file is not a directory. -.IP * +.IP \(bu Passing the file descriptor to another process via a UNIX domain socket (see .B SCM_RIGHTS @@ -843,7 +843,7 @@ There are two main use cases for .\" Inspired by http://lwn.net/Articles/559147/ .BR O_TMPFILE : .RS -.IP * 3 +.IP \(bu 3 Improved .BR tmpfile (3) functionality: race-free creation of temporary files that @@ -851,7 +851,7 @@ functionality: race-free creation of temporary files that (2) can never be reached via any pathname; (3) are not subject to symlink attacks; and (4) do not require the caller to devise unique names. -.IP * +.IP \(bu Creating a file that is initially invisible, which is then populated with data and adjusted to have appropriate filesystem attributes .RB ( fchown (2), @@ -914,13 +914,13 @@ The argument is used in conjunction with the .I pathname argument as follows: -.IP * 3 +.IP \(bu 3 If the pathname given in .I pathname is absolute, then .I dirfd is ignored. -.IP * +.IP \(bu If the pathname given in .I pathname is relative and @@ -932,7 +932,7 @@ then is interpreted relative to the current working directory of the calling process (like .BR open ()). -.IP * +.IP \(bu If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -1678,10 +1678,10 @@ and The use of the .I dirfd file descriptor also has other benefits: -.IP * 3 +.IP \(bu 3 the file descriptor is a stable reference to the directory, even if the directory is renamed; and -.IP * +.IP \(bu the open file descriptor prevents the underlying filesystem from being dismounted, just as when a process has a current working directory on a filesystem. diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2 index 2d8ac019b5..545063a1fd 100644 --- a/man2/open_by_handle_at.2 +++ b/man2/open_by_handle_at.2 @@ -126,7 +126,7 @@ and .I dirfd arguments identify the file for which a handle is to be obtained. There are four distinct cases: -.IP * 3 +.IP \(bu 3 If .I pathname is a nonempty string containing an absolute pathname, @@ -134,7 +134,7 @@ then a handle is returned for the file referred to by that pathname. In this case, .I dirfd is ignored. -.IP * +.IP \(bu If .I pathname is a nonempty string containing a relative pathname and @@ -145,7 +145,7 @@ then .I pathname is interpreted relative to the current working directory of the caller, and a handle is returned for the file to which it refers. -.IP * +.IP \(bu If .I pathname is a nonempty string containing a relative pathname and @@ -158,7 +158,7 @@ and a handle is returned for the file to which it refers. (See .BR openat (2) for an explanation of why "directory file descriptors" are useful.) -.IP * +.IP \(bu If .I pathname is an empty string and diff --git a/man2/openat2.2 b/man2/openat2.2 index 3dd3d3f1e0..810dd9674e 100644 --- a/man2/openat2.2 +++ b/man2/openat2.2 @@ -251,7 +251,7 @@ for more details.) Unknowingly opening magic links can be risky for some applications. Examples of such risks include the following: .RS -.IP \(bu 2 +.IP \(bu 3 If the process opening a pathname is a controlling process that currently has no controlling terminal (see .BR credentials (7)), @@ -503,7 +503,7 @@ be the size of the structure as specified by the user-space application, and .I ksize be the size of the structure which the kernel supports, then there are three cases to consider: -.IP \(bu 2 +.IP \(bu 3 If .I ksize equals diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index d915678934..45759a1478 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -1488,7 +1488,7 @@ data, the error results. .PP Here is the layout of the data returned by a read: -.IP * 2 +.IP \(bu 3 If .B PERF_FORMAT_GROUP was specified to allow reading all events in a group at once: @@ -1506,7 +1506,7 @@ struct read_format { }; .EE .in -.IP * +.IP \(bu If .B PERF_FORMAT_GROUP was diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2 index 06cedbdeeb..34f77a21d4 100644 --- a/man2/pidfd_getfd.2 +++ b/man2/pidfd_getfd.2 @@ -121,7 +121,7 @@ is similar to the use of messages described in .BR unix (7), but differs in the following respects: -.IP \(bu 2 +.IP \(bu 3 In order to pass a file descriptor using an .B SCM_RIGHTS message, diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2 index e04c102330..4c9fdb1d63 100644 --- a/man2/pidfd_open.2 +++ b/man2/pidfd_open.2 @@ -107,7 +107,7 @@ call, its PID will not have been recycled and the returned file descriptor will refer to the resulting zombie process. Note, however, that this is guaranteed only if the following conditions hold true: -.IP \(bu 2 +.IP \(bu 3 the disposition of .B SIGCHLD has not been explicitly set to @@ -146,7 +146,7 @@ A PID file descriptor returned by with the .B CLONE_PID flag) can be used for the following purposes: -.IP \(bu 2 +.IP \(bu 3 The .BR pidfd_send_signal (2) system call can be used to send a signal to the process referred to by diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2 index 037c706a99..5d2f66d908 100644 --- a/man2/pidfd_send_signal.2 +++ b/man2/pidfd_send_signal.2 @@ -53,20 +53,20 @@ implicitly supplied when a signal is sent using .BR kill (2): .PP .PD 0 -.IP * 3 +.IP \(bu 3 .I si_signo is set to the signal number; -.IP * +.IP \(bu .I si_errno is set to 0; -.IP * +.IP \(bu .I si_code is set to .BR SI_USER ; -.IP * +.IP \(bu .I si_pid is set to the caller's PID; and -.IP * +.IP \(bu .I si_uid is set to the caller's real user ID. .PD @@ -132,15 +132,15 @@ The argument is a PID file descriptor, a file descriptor that refers to process. Such a file descriptor can be obtained in any of the following ways: -.IP * 3 +.IP \(bu 3 by opening a .IR /proc/ pid directory; -.IP * +.IP \(bu using .BR pidfd_open (2); or -.IP * +.IP \(bu via the PID file descriptor that is returned by a call to .BR clone (2) or diff --git a/man2/pipe.2 b/man2/pipe.2 index 4e316252c7..961768656d 100644 --- a/man2/pipe.2 +++ b/man2/pipe.2 @@ -85,7 +85,7 @@ to the pipe is dealt with as a separate packet, and from the pipe will read one packet at a time. Note the following points: .RS -.IP * 3 +.IP \(bu 3 Writes of greater than .B PIPE_BUF bytes (see @@ -95,7 +95,7 @@ The constant .B PIPE_BUF is defined in .IR <limits.h> . -.IP * +.IP \(bu If a .BR read (2) specifies a buffer size that is smaller than the next packet, @@ -105,7 +105,7 @@ Specifying a buffer size of .B PIPE_BUF will be sufficient to read the largest possible packets (see the previous point). -.IP * +.IP \(bu Zero-length packets are not supported. (A .BR read (2) diff --git a/man2/pivot_root.2 b/man2/pivot_root.2 index 0e52b86eb5..8d39d40221 100644 --- a/man2/pivot_root.2 +++ b/man2/pivot_root.2 @@ -47,29 +47,29 @@ and thus it should be followed by a \fBchdir("/")\fP call. .PP The following restrictions apply: -.IP \- 3 +.IP \(bu 3 .I new_root and .I put_old must be directories. -.IP \- +.IP \(bu .I new_root and .I put_old must not be on the same mount as the current root. -.IP \- +.IP \(bu \fIput_old\fP must be at or underneath \fInew_root\fP; that is, adding some nonnegative number of "\fI/..\fP" suffixes to the pathname pointed to by .I put_old must yield the same directory as \fInew_root\fP. -.IP \- +.IP \(bu .I new_root must be a path to a mount point, but can't be .IR """/""" . A path that is not already a mount point can be converted into one by bind mounting the path onto itself. -.IP \- +.IP \(bu The propagation type of the parent mount of .I new_root and the parent mount of the current root directory must not be @@ -81,7 +81,7 @@ is an existing mount point, its propagation type must not be These restrictions ensure that .BR pivot_root () never propagates any changes to another mount namespace. -.IP \- +.IP \(bu The current root directory must be a mount point. .SH RETURN VALUE On success, zero is returned. diff --git a/man2/poll.2 b/man2/poll.2 index 0c37743e84..850228171c 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -115,7 +115,7 @@ argument specifies the number of milliseconds that .BR poll () should block waiting for a file descriptor to become ready. The call will block until either: -.IP \(bu 2 +.IP \(bu 3 a file descriptor becomes ready; .IP \(bu the call is interrupted by a signal handler; or @@ -149,7 +149,7 @@ There is data to read. There is some exceptional condition on the file descriptor. Possibilities include: .RS -.IP \(bu 2 +.IP \(bu 3 There is out-of-band data on a TCP socket (see .BR tcp (7)). .IP \(bu @@ -460,7 +460,7 @@ The program loops, repeatedly using to monitor the file descriptors, printing the number of ready file descriptors on return. For each ready file descriptor, the program: -.IP \(bu 2 +.IP \(bu 3 displays the returned .I revents field in a human-readable form; @@ -516,7 +516,7 @@ All file descriptors closed; bye In the above output, we see that .BR poll () returned three times: -.IP \(bu 2 +.IP \(bu 3 On the first return, the bits returned in the .I revents field were diff --git a/man2/prctl.2 b/man2/prctl.2 index c7fb4e449c..ef9e0dcf02 100644 --- a/man2/prctl.2 +++ b/man2/prctl.2 @@ -258,17 +258,17 @@ However, it is reset to the current value contained in the file in the following circumstances: .\" See kernel/cred.c::commit_creds() (Linux 3.18 sources) .RS -.IP * 3 +.IP \(bu 3 The process's effective user or group ID is changed. -.IP * +.IP \(bu The process's filesystem user or group ID is changed (see .BR credentials (7)). -.IP * +.IP \(bu The process executes .RB ( execve (2)) a set-user-ID or set-group-ID program, resulting in a change of either the effective user ID or the effective group ID. -.IP * +.IP \(bu The process executes .RB ( execve (2)) a program that has file capabilities (see @@ -1561,23 +1561,23 @@ structure (see .BR sigaction (2)) associated with the signal: .RS -.IP * 3 +.IP \(bu 3 .I si_signo will contain .BR SIGSYS . -.IP * +.IP \(bu .I si_call_addr will show the address of the system call instruction. -.IP * +.IP \(bu .I si_syscall and .I si_arch will indicate which system call was attempted. -.IP * +.IP \(bu .I si_code will contain .BR SYS_USER_DISPATCH . -.IP * +.IP \(bu .I si_errno will be set to 0. .RE @@ -1672,7 +1672,7 @@ Irrespective of which mode is set, addresses passed to certain interfaces must always be untagged: .RS -.IP \(bu 2 +.IP \(bu 3 .BR brk (2), .BR mmap (2), .BR shmat (2), @@ -2142,17 +2142,17 @@ is .BR PR_SET_MM , and one of the following is true .RS -.IP * 3 +.IP \(bu 3 .I arg4 or .I arg5 is nonzero; -.IP * +.IP \(bu .I arg3 is greater than .B TASK_SIZE (the limit on the size of the user address space for this architecture); -.IP * +.IP \(bu .I arg2 is .BR PR_SET_MM_START_CODE , @@ -2162,7 +2162,7 @@ is or .BR PR_SET_MM_START_STACK , and the permissions of the corresponding memory area are not as required; -.IP * +.IP \(bu .I arg2 is .B PR_SET_MM_START_BRK @@ -2328,18 +2328,18 @@ is .B PR_SET_SYSCALL_USER_DISPATCH and one of the following is true: .RS -.IP * 3 +.IP \(bu 3 .I arg2 is .B PR_SYS_DISPATCH_OFF and the remaining arguments are not 0; -.IP * 3 +.IP \(bu .I arg2 is .B PR_SYS_DISPATCH_ON and the memory range specified is outside the address space of the process. -.IP * 3 +.IP \(bu .I arg2 is invalid. .RE diff --git a/man2/ptrace.2 b/man2/ptrace.2 index 7e3f320f7a..ab1714ba81 100644 --- a/man2/ptrace.2 +++ b/man2/ptrace.2 @@ -2189,7 +2189,7 @@ at completion of the call, it appears as though the occurred in the thread group leader, regardless of which thread did the .BR execve (2).) This resetting of the thread ID looks very confusing to tracers: -.IP * 3 +.IP \(bu 3 All other threads stop in .B PTRACE_EVENT_EXIT stop, if the @@ -2199,7 +2199,7 @@ Then all other threads except the thread group leader report death as if they exited via .BR _exit (2) with exit code 0. -.IP * +.IP \(bu The execing tracee changes its thread ID while it is in the .BR execve (2). (Remember, under ptrace, the "pid" returned from @@ -2207,13 +2207,13 @@ The execing tracee changes its thread ID while it is in the or fed into ptrace calls, is the tracee's thread ID.) That is, the tracee's thread ID is reset to be the same as its process ID, which is the same as the thread group leader's thread ID. -.IP * +.IP \(bu Then a .B PTRACE_EVENT_EXEC stop happens, if the .B PTRACE_O_TRACEEXEC option was turned on. -.IP * +.IP \(bu If the thread group leader has reported its .B PTRACE_EVENT_EXIT stop by this time, @@ -2353,7 +2353,7 @@ Many of these bugs have been fixed, but as of Linux 2.6.38 several still exist; see BUGS below. .PP As of Linux 2.6.38, the following is believed to work correctly: -.IP * 3 +.IP \(bu 3 exit/death by signal is reported first to the tracer, then, when the tracer consumes the .BR waitpid (2) @@ -2600,10 +2600,10 @@ on the target process. files, the "calling process" is the one opening the file, and the process with the corresponding PID is the "target process".) The algorithm is as follows: -.IP 1. 3 +.IP (1) 5 If the calling thread and the target thread are in the same thread group, access is always allowed. -.IP 2. +.IP (2) If the access mode specifies .BR PTRACE_MODE_FSCREDS , then, for the check in the next step, @@ -2620,12 +2620,12 @@ so use the caller's real UID and GID for the checks in the next step. For historical reasons, the .B PTRACE_MODE_REALCREDS check uses the real IDs instead.) -.IP 3. +.IP (3) Deny access if .I neither of the following is true: .RS -.IP \(bu 2 +.IP \(bu 3 The real, effective, and saved-set user IDs of the target match the caller's user ID, .I and @@ -2636,7 +2636,7 @@ The caller has the .B CAP_SYS_PTRACE capability in the user namespace of the target. .RE -.IP 4. +.IP (4) Deny access if the target process "dumpable" attribute has a value other than 1 .RB ( SUID_DUMP_USER ; see the discussion of @@ -2646,7 +2646,7 @@ in and the caller does not have the .B CAP_SYS_PTRACE capability in the user namespace of the target process. -.IP 5. +.IP (5) The kernel LSM .IR security_ptrace_access_check () interface is invoked to see if ptrace access is permitted. @@ -2655,7 +2655,7 @@ The implementation of this interface in the commoncap LSM performs the following steps: .\" (in cap_ptrace_access_check()): .RS -.IP a) 3 +.IP (5.1) 7 If the access mode includes .BR PTRACE_MODE_FSCREDS , then use the caller's @@ -2667,12 +2667,12 @@ otherwise (the access mode specifies so) use the caller's .I permitted capability set. -.IP b) +.IP (5.2) Deny access if .I neither of the following is true: .RS -.IP \(bu 2 +.IP \(bu 3 The caller and the target process are in the same user namespace, and the caller's capabilities are a superset of the target process's .I permitted @@ -2688,7 +2688,7 @@ Note that the commoncap LSM does not distinguish between and .BR PTRACE_MODE_ATTACH . .RE -.IP 6. +.IP (6) If access has not been denied by any of the preceding steps, then access is allowed. .\" @@ -2715,14 +2715,14 @@ to gain additional credentials that may exist in memory and thus expand the scope of the attack. .PP More precisely, the Yama LSM limits two types of operations: -.IP * 3 +.IP \(bu 3 Any operation that performs a ptrace access mode .B PTRACE_MODE_ATTACH check\(emfor example, .BR ptrace () .BR PTRACE_ATTACH . (See the "Ptrace access mode checking" discussion above.) -.IP * +.IP \(bu .BR ptrace () .BR PTRACE_TRACEME . .PP diff --git a/man2/rename.2 b/man2/rename.2 index 5053649510..a27c9fdc3f 100644 --- a/man2/rename.2 +++ b/man2/rename.2 @@ -187,19 +187,19 @@ can't be employed together with requires support from the underlying filesystem. Support for various filesystems was added as follows: .RS -.IP * 3 +.IP \(bu 3 ext4 (Linux 3.15); .\" ext4: commit 0a7c3937a1f23f8cb5fc77ae01661e9968a51d0c -.IP * +.IP \(bu btrfs, tmpfs, and cifs (Linux 3.17); -.IP * +.IP \(bu xfs (Linux 4.0); .\" btrfs: commit 80ace85c915d0f41016f82917218997b72431258 .\" tmpfs: commit 3b69ff51d087d265aa4af3a532fc4f20bf33e718 .\" cifs: commit 7c33d5972ce382bcc506d16235f1e9b7d22cbef8 .\" .\" gfs2 in 4.2? -.IP * +.IP \(bu Support for many other filesystems was added in Linux 4.9, including ext2, minix, reiserfs, jfs, vfat, and bpf. .\" Also affs, bfs, exofs, hfs, hfsplus, jffs2, logfs, msdos, diff --git a/man2/request_key.2 b/man2/request_key.2 index dec25f0890..3002f508b0 100644 --- a/man2/request_key.2 +++ b/man2/request_key.2 @@ -205,33 +205,33 @@ program to instantiate a key with the given and .IR description . In this case, the following steps are performed: -.IP a) 4 +.IP (1) 5 The kernel creates an uninstantiated key, U, with the requested .I type and .IR description . -.IP b) +.IP (2) The kernel creates an authorization key, V, .\" struct request_key_auth, defined in security/keys/internal.h that refers to the key U and records the facts that the caller of .BR request_key () is: .RS -.IP (1) 4 +.IP (2.1) 7 the context in which the key U should be instantiated and secured, and -.IP (2) +.IP (2.2) the context from which associated key requests may be satisfied. .RE .IP The authorization key is constructed as follows: .RS -.IP * 3 +.IP \(bu 3 The key type is .IR """.request_key_auth""" . -.IP * +.IP \(bu The key's UID and GID are the same as the corresponding filesystem IDs of the requesting process. -.IP * +.IP \(bu The key grants .IR view , .IR read , @@ -240,18 +240,18 @@ and permissions to the key possessor as well as .I view permission for the key user. -.IP * +.IP \(bu The description (name) of the key is the hexadecimal string representing the ID of the key that is to be instantiated in the requesting program. -.IP * +.IP \(bu The payload of the key is taken from the data specified in .IR callout_info . -.IP * +.IP \(bu Internally, the kernel also records the PID of the process that called .BR request_key (). .RE -.IP c) +.IP (3) The kernel creates a process that executes a user-space service such as .BR request\-key (8) with a new session keyring that contains a link to the authorization key, V. @@ -261,7 +261,7 @@ with a new session keyring that contains a link to the authorization key, V. .IP This program is supplied with the following command-line arguments: .RS -.IP [0] 4 +.IP [0] 5 The string .IR """/sbin/request\-key""" . .IP [1] @@ -295,17 +295,17 @@ each of the command-line arguments that is a key ID is encoded in (unlike the key IDs shown in .IR /proc/keys , which are shown as hexadecimal values). -.IP d) +.IP (4) The program spawned in the previous step: .RS -.IP * 3 +.IP \(bu 3 Assumes the authority to instantiate the key U using the .BR keyctl (2) .B KEYCTL_ASSUME_AUTHORITY operation (typically via the .BR keyctl_assume_authority (3) function). -.IP * +.IP \(bu Obtains the callout data from the payload of the authorization key V (using the .BR keyctl (2) @@ -314,7 +314,7 @@ operation (or, more commonly, the .BR keyctl_read (3) function) with a key ID value of .BR KEY_SPEC_REQKEY_AUTH_KEY ). -.IP * +.IP \(bu Instantiates the key (or execs another program that performs that task), specifying the payload and destination keyring. diff --git a/man2/rt_sigqueueinfo.2 b/man2/rt_sigqueueinfo.2 index 293eb827dc..b7884e21a8 100644 --- a/man2/rt_sigqueueinfo.2 +++ b/man2/rt_sigqueueinfo.2 @@ -72,7 +72,7 @@ codes in the Linux kernel source file If the signal is being sent to any process other than the caller itself, the following restrictions apply: .RS -.IP * 3 +.IP \(bu 3 The code can't be a value greater than or equal to zero. In particular, it can't be .BR SI_USER , @@ -81,7 +81,7 @@ which is used by the kernel to indicate a signal sent by and nor can it be .BR SI_KERNEL , which is used to indicate a signal generated by the kernel. -.IP * +.IP \(bu The code can't (since Linux 2.6.39) be .BR SI_TKILL , which is used by the kernel to indicate a signal sent using diff --git a/man2/seccomp.2 b/man2/seccomp.2 index 05ae604545..aa69b5c0b3 100644 --- a/man2/seccomp.2 +++ b/man2/seccomp.2 @@ -565,23 +565,23 @@ structure (see .BR sigaction (2)) associated with signal: .RS -.IP * 3 +.IP \(bu 3 .I si_signo will contain .BR SIGSYS . -.IP * +.IP \(bu .I si_call_addr will show the address of the system call instruction. -.IP * +.IP \(bu .I si_syscall and .I si_arch will indicate which system call was attempted. -.IP * +.IP \(bu .I si_code will contain .BR SYS_SECCOMP . -.IP * +.IP \(bu .I si_errno will contain the .B SECCOMP_RET_DATA @@ -742,11 +742,11 @@ file, and whether kernel auditing is enabled .IR audit=1 ). .\" or auditing could be enabled via the netlink API (AUDIT_SET) The rules are as follows: -.IP * 3 +.IP \(bu 3 If the action is .BR SECCOMP_RET_ALLOW , the action is not logged. -.IP * +.IP \(bu Otherwise, if the action is either .B SECCOMP_RET_KILL_PROCESS or @@ -754,18 +754,18 @@ or and that action appears in the .I actions_logged file, the action is logged. -.IP * +.IP \(bu Otherwise, if the filter has requested logging (the .B SECCOMP_FILTER_FLAG_LOG flag) and the action appears in the .I actions_logged file, the action is logged. -.IP * +.IP \(bu Otherwise, if kernel auditing is enabled and the process is being audited .RB ( autrace (8)), the action is logged. -.IP * +.IP \(bu Otherwise, the action is not logged. .SH RETURN VALUE On success, @@ -900,22 +900,22 @@ Architecture support for seccomp BPF filtering .\" Check by grepping for HAVE_ARCH_SECCOMP_FILTER in Kconfig files in .\" kernel source. Last checked in Linux 4.16-rc source. is available on the following architectures: -.IP * 3 +.IP \(bu 3 x86-64, i386, x32 (since Linux 3.5) .PD 0 -.IP * +.IP \(bu ARM (since Linux 3.8) -.IP * +.IP \(bu s390 (since Linux 3.8) -.IP * +.IP \(bu MIPS (since Linux 3.16) -.IP * +.IP \(bu ARM-64 (since Linux 3.19) -.IP * +.IP \(bu PowerPC (since Linux 4.3) -.IP * +.IP \(bu Tile (since Linux 4.3) -.IP * +.IP \(bu PA-RISC (since Linux 4.6) .\" User mode Linux since Linux 4.6 .PD @@ -923,7 +923,7 @@ PA-RISC (since Linux 4.6) .SS Caveats There are various subtleties to consider when applying seccomp filters to a program, including the following: -.IP * 3 +.IP \(bu 3 Some traditional system calls have user-space implementations in the .BR vdso (7) on many architectures. @@ -938,7 +938,7 @@ seccomp filtering for these system calls will have no effect. .BR vdso (7) implementations may fall back to invoking the true system call, in which case seccomp filters would see the system call.) -.IP * +.IP \(bu Seccomp filtering is based on system call numbers. However, applications typically do not directly invoke system calls, but instead call wrapper functions in the C library which @@ -987,7 +987,7 @@ filters if the bugs occur in rarely used application code paths. .\" .SS Seccomp-specific BPF details Note the following BPF details specific to seccomp filters: -.IP * 3 +.IP \(bu 3 The .B BPF_H and @@ -995,13 +995,13 @@ and size modifiers are not supported: all operations must load and store (4-byte) words .RB ( BPF_W ). -.IP * +.IP \(bu To access the contents of the .I seccomp_data buffer, use the .B BPF_ABS addressing mode modifier. -.IP * +.IP \(bu The .B BPF_LEN addressing mode modifier yields an immediate mode operand @@ -1014,11 +1014,11 @@ The first three arguments are a system call number, a numeric architecture identifier, and an error number. The program uses these values to construct a BPF filter that is used at run time to perform the following checks: -.IP [1] 4 +.IP \(bu 3 If the program is not running on the specified architecture, the BPF filter causes system calls to fail with the error .BR ENOSYS . -.IP [2] +.IP \(bu If the program attempts to execute the system call with the specified number, the BPF filter causes the system call to fail, with .I errno diff --git a/man2/seccomp_unotify.2 b/man2/seccomp_unotify.2 index 3f4dba23dc..80db1b154e 100644 --- a/man2/seccomp_unotify.2 +++ b/man2/seccomp_unotify.2 @@ -73,11 +73,11 @@ is running on a virtual machine inside the kernel.) An overview of the steps performed by the target and the supervisor is as follows: .\"------------------------------------- -.IP 1. 3 +.IP (1) 5 The target establishes a seccomp filter in the usual manner, but with two differences: .RS -.IP \(bu 2 +.IP \(bu 3 The .BR seccomp (2) .I flags @@ -107,7 +107,7 @@ In cases where it is appropriate, the seccomp filter returns the action value This return value will trigger a notification event. .RE .\"------------------------------------- -.IP 2. +.IP (2) In order that the supervisor can obtain notifications using the listening file descriptor, (a duplicate of) that file descriptor must be passed from @@ -130,7 +130,7 @@ Another way to do this is through the use of .\" I'm not sure whether that'd look better or worse in the .\" end though, so maybe just ignore this comment. .\"------------------------------------- -.IP 3. +.IP (3) The supervisor will receive notification events on the listening file descriptor. These events are returned as structures of type @@ -152,7 +152,7 @@ bytes for the response (a structure) that it will provide to the kernel (and thus the target). .\"------------------------------------- -.IP 4. +.IP (4) The target then performs its workload, which includes system calls that will be controlled by the seccomp filter. Whenever one of these system calls causes the filter to return the @@ -164,7 +164,7 @@ instead, execution of the target is temporarily blocked inside the kernel (in a sleep state that is interruptible by signals) and a notification event is generated on the listening file descriptor. .\"------------------------------------- -.IP 5. +.IP (5) The supervisor can now repeatedly monitor the listening file descriptor for .BR SECCOMP_RET_USER_NOTIF -triggered @@ -196,7 +196,7 @@ or .\" behavior of SECCOMP_IOCTL_NOTIF_RECV. . .\"------------------------------------- -.IP 6. +.IP (6) The .I seccomp_notif structure returned by the @@ -235,7 +235,7 @@ In addition, the supervisor can access other system information that is visible in user space but which is not accessible from a seccomp filter. .\"------------------------------------- -.IP 7. +.IP (7) Having obtained information as per the previous step, the supervisor may then choose to perform an action in response to the target's system call @@ -250,7 +250,7 @@ in the container's mount namespace. However, the supervisor may be a more privileged process that does have sufficient capabilities to perform the mount operation. .\"------------------------------------- -.IP 8. +.IP (8) The supervisor then sends a response to the notification. The information in this response is used by the kernel to construct a return value for the target's system call and provide @@ -279,7 +279,7 @@ structure returned by the operation; the cookie allows the kernel to associate the response with the target. .\"------------------------------------- -.IP 9. +.IP (9) Once the notification has been sent, the system call in the target thread unblocks, returning the information that was provided by the supervisor @@ -336,7 +336,7 @@ This is a cookie for the notification. Each such cookie is guaranteed to be unique for the corresponding seccomp filter. .RS -.IP \(bu 2 +.IP \(bu 3 The cookie can be used with the .B SECCOMP_IOCTL_NOTIF_ID_VALID .BR ioctl (2) @@ -438,19 +438,19 @@ returned by the .B SECCOMP_IOCTL_NOTIF_RECV operation terminates, and that process ID is reused by another process. An example of this kind of race is the following -.IP 1. 3 +.IP (1) 5 A notification is generated on the listening file descriptor. The returned .I seccomp_notif contains the TID of the target thread (in the .I pid field of the structure). -.IP 2. +.IP (2) The target terminates. -.IP 3. +.IP (3) Another thread or process is created on the system that by chance reuses the TID that was freed when the target terminated. -.IP 4. +.IP (4) The supervisor .BR open (2)s the @@ -539,7 +539,7 @@ Tell the kernel to execute the target's system call. .RE .PP Two kinds of response are possible: -.IP \(bu 2 +.IP \(bu 3 A response to the kernel telling it to execute the target's system call. In this case, the @@ -906,7 +906,7 @@ flag can be monitored using and .BR select (2). These interfaces indicate that the file descriptor is ready as follows: -.IP \(bu 2 +.IP \(bu 3 When a notification is pending, these interfaces indicate that the file descriptor is readable. Following such an indication, a subsequent @@ -999,35 +999,35 @@ Consider the following scenario, where the supervisor tries to read the pathname argument of a target's blocked .BR mount (2) system call: -.IP \(bu 2 +.IP (1) 5 From one of its functions .RI ( func() ), the target calls .BR mount (2), which triggers a user-space notification and causes the target to block. -.IP \(bu +.IP (2) The supervisor receives the notification, opens .IR /proc/ tid /mem , and (successfully) performs the .B SECCOMP_IOCTL_NOTIF_ID_VALID check. -.IP \(bu +.IP (3) The target receives a signal, which causes the .BR mount (2) to abort. -.IP \(bu +.IP (4) The signal handler executes in the target, and returns. -.IP \(bu +.IP (5) Upon return from the handler, the execution of .I func() resumes, and it returns (and perhaps other functions are called, overwriting the memory that had been used for the stack frame of .IR func() ). -.IP \(bu +.IP (6) Using the address provided in the notification information, the supervisor reads from the target's memory location that used to contain the pathname. -.IP \(bu +.IP (7) The supervisor now calls .BR mount (2) with some arbitrary bytes obtained in the previous step. @@ -1102,19 +1102,19 @@ that it acquired on behalf of the target. .\" .SS Interaction with SA_RESTART signal handlers Consider the following scenario: -.IP \(bu 2 +.IP (1) 5 The target process has used .BR sigaction (2) to install a signal handler with the .B SA_RESTART flag. -.IP \(bu +.IP (2) The target has made a system call that triggered a seccomp user-space notification and the target is currently blocked until the supervisor sends a notification response. -.IP \(bu +.IP (3) A signal is delivered to the target and the signal handler is executed. -.IP \(bu +.IP (4) When (if) the supervisor attempts to send a notification response, the .B SECCOMP_IOCTL_NOTIF_SEND .BR ioctl (2)) @@ -1205,7 +1205,7 @@ the supervisor examines the memory of the target process (using to discover the pathname argument that was supplied to the .BR mkdir (2) call, and performs one of the following actions: -.IP \(bu 2 +.IP \(bu 3 If the pathname begins with the prefix "/tmp/", then the supervisor attempts to create the specified directory, and then spoofs a return for the target process based on the return diff --git a/man2/select.2 b/man2/select.2 index 6bea71057a..e0f1580bd9 100644 --- a/man2/select.2 +++ b/man2/select.2 @@ -203,7 +203,7 @@ structure (shown below) that specifies the interval that should block waiting for a file descriptor to become ready. The call will block until either: .RS -.IP \(bu 2 +.IP \(bu 3 a file descriptor becomes ready; .IP \(bu the call is interrupted by a signal handler; or @@ -241,7 +241,7 @@ The operation of and .BR pselect () is identical, other than these three differences: -.IP \(bu 2 +.IP \(bu 3 .BR select () uses a timeout that is a .I struct timeval diff --git a/man2/semget.2 b/man2/semget.2 index 561e1c1feb..ea6ae6d7e1 100644 --- a/man2/semget.2 +++ b/man2/semget.2 @@ -95,7 +95,7 @@ initializes the set's associated data structure, (see .BR semctl (2)), as follows: -.IP \(bu 2 +.IP \(bu 3 .I sem_perm.cuid and .I sem_perm.uid diff --git a/man2/semop.2 b/man2/semop.2 index 7d984aa1ad..986a32741a 100644 --- a/man2/semop.2 +++ b/man2/semop.2 @@ -142,7 +142,7 @@ Otherwise, (the count of threads waiting until this semaphore's value becomes zero) is incremented by one and the thread sleeps until one of the following occurs: -.IP \(bu 2 +.IP \(bu 3 .I semval becomes 0, at which time the value of .I semzcnt @@ -207,7 +207,7 @@ Otherwise, (the counter of threads waiting for this semaphore's value to increase) is incremented by one and the thread sleeps until one of the following occurs: -.IP \(bu 2 +.IP \(bu 3 .I semval becomes greater than or equal to the absolute value of .IR sem_op : diff --git a/man2/setns.2 b/man2/setns.2 index 9245b9a968..d23e2a9228 100644 --- a/man2/setns.2 +++ b/man2/setns.2 @@ -23,7 +23,7 @@ system call allows the calling thread to move into different namespaces. The .I fd argument is one of the following: -.IP \(bu 2 +.IP \(bu 3 a file descriptor referring to one of the magic links in a .IR /proc/ pid /ns/ directory (or a bind mount to such a link); diff --git a/man2/shmget.2 b/man2/shmget.2 index e6e4eccac3..73334e9745 100644 --- a/man2/shmget.2 +++ b/man2/shmget.2 @@ -161,7 +161,7 @@ its associated data structure, (see .BR shmctl (2)), is initialized as follows: -.IP \(bu 2 +.IP \(bu 3 .I shm_perm.cuid and .I shm_perm.uid diff --git a/man2/shmop.2 b/man2/shmop.2 index c4156d03cf..e5a0ae8142 100644 --- a/man2/shmop.2 +++ b/man2/shmop.2 @@ -39,7 +39,7 @@ to the address space of the calling process. The attaching address is specified by .I shmaddr with one of the following criteria: -.IP \(bu 2 +.IP \(bu 3 If .I shmaddr is NULL, @@ -107,7 +107,7 @@ call updates the members of the structure (see .BR shmctl (2)) associated with the shared memory segment as follows: -.IP \(bu 2 +.IP \(bu 3 .I shm_atime is set to the current time. .IP \(bu @@ -134,7 +134,7 @@ On a successful call, the system updates the members of the .I shmid_ds structure associated with the shared memory segment as follows: -.IP \(bu 2 +.IP \(bu 3 .I shm_dtime is set to the current time. .IP \(bu diff --git a/man2/sigaction.2 b/man2/sigaction.2 index 64d03bc181..fcade7dbd2 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -113,13 +113,13 @@ Some further details of the purpose of this field can be found in specifies the action to be associated with .I signum and can be one of the following: -.IP * 2 +.IP \(bu 3 .B SIG_DFL for the default action. -.IP * +.IP \(bu .B SIG_IGN to ignore this signal. -.IP * +.IP \(bu A pointer to a signal handling function. This function receives the signal number as its only argument. .PP @@ -386,7 +386,7 @@ are defined for all signals. is generally unused on Linux.) The rest of the struct may be a union, so that one should read only the fields that are meaningful for the given signal: -.IP * 2 +.IP \(bu 3 Signals sent with .BR kill (2) and @@ -401,7 +401,7 @@ with the values specified by the sender of the signal; see .BR sigqueue (3) for more details. -.IP * +.IP \(bu Signals sent by POSIX.1b timers (since Linux 2.6) fill in .I si_overrun and @@ -417,7 +417,7 @@ field is the timer overrun count; this is the same information as is obtained by a call to .BR timer_getoverrun (2). These fields are nonstandard Linux extensions. -.IP * +.IP \(bu Signals sent for message queue notification (see the description of .B SIGEV_SIGNAL in @@ -432,7 +432,7 @@ supplied to with the process ID of the message sender; and .IR si_uid , with the real user ID of the message sender. -.IP * +.IP \(bu .B SIGCHLD fills in .IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime , @@ -479,7 +479,7 @@ of the (configurable) system jiffy (see .\" But note that these fields still don't return the times of .\" waited-for children (as is done by getrusage() and times() .\" and wait4()). Solaris 8 does include child times. -.IP * +.IP \(bu .BR SIGILL , .BR SIGFPE , .BR SIGSEGV , @@ -543,7 +543,7 @@ suberror of .B SIGSEGV populates .IR si_pkey . -.IP * +.IP \(bu .BR SIGIO / SIGPOLL (the two names are synonyms on Linux) fills in @@ -563,7 +563,7 @@ for further details, see the description of .B F_SETSIG in .BR fcntl (2). -.IP * +.IP \(bu .BR SIGSYS , generated (since Linux 3.5) .\" commit a0727e8ce513fe6890416da960181ceb10fbfae6 @@ -612,15 +612,15 @@ the definitions of most of these symbols are obtained from by defining feature test macros (before including .I any header file) as follows: -.IP * 3 +.IP \(bu 3 .B _XOPEN_SOURCE with the value 500 or greater; -.IP * +.IP \(bu .B _XOPEN_SOURCE and .BR _XOPEN_SOURCE_EXTENDED ; or -.IP * +.IP \(bu .B _POSIX_C_SOURCE with the value 200809L or greater. .PP diff --git a/man2/signal.2 b/man2/signal.2 index 3c8aa2075b..eb59a0cfcd 100644 --- a/man2/signal.2 +++ b/man2/signal.2 @@ -219,11 +219,11 @@ sa.sa_flags = SA_RESTART; .in .PP The situation on Linux is as follows: -.IP * 2 +.IP \(bu 3 The kernel's .BR signal () system call provides System\ V semantics. -.IP * +.IP \(bu By default, in glibc 2 and later, the .BR signal () wrapper function does not invoke the kernel system call. diff --git a/man2/splice.2 b/man2/splice.2 index b52e581f93..0dbdb88a6c 100644 --- a/man2/splice.2 +++ b/man2/splice.2 @@ -35,13 +35,13 @@ The following semantics apply for .I fd_in and .IR off_in : -.IP * 3 +.IP \(bu 3 If .I fd_in refers to a pipe, then .I off_in must be NULL. -.IP * +.IP \(bu If .I fd_in does not refer to a pipe and @@ -50,7 +50,7 @@ is NULL, then bytes are read from .I fd_in starting from the file offset, and the file offset is adjusted appropriately. -.IP * +.IP \(bu If .I fd_in does not refer to a pipe and diff --git a/man2/syscall.2 b/man2/syscall.2 index b7b8405da4..95b2e7dbd9 100644 --- a/man2/syscall.2 +++ b/man2/syscall.2 @@ -196,7 +196,7 @@ xtensa syscall a2 a2 - - .TE .PP Notes: -.IP [1] 4 +.IP \(bu 3 On a few architectures, a register is used as a boolean (0 indicating no error, and \-1 indicating an error) to signal that the @@ -212,20 +212,20 @@ On powerpc64, the summary overflow bit in field 0 of the condition register .RI ( cr0 ) is used. -.IP [2] +.IP \(bu .I NR is the system call number. -.IP [3] +.IP \(bu For s390 and s390x, .I NR (the system call number) may be passed directly with .I "svc\ NR" if it is less than 256. -.IP [4] +.IP \(bu On SuperH additional trap numbers are supported for historic reasons, but .BR trapa #31 is the recommended "unified" ABI. -.IP [5] +.IP \(bu The x32 ABI shares syscall table with x86-64 ABI, but there are some nuances: .RS @@ -265,7 +265,7 @@ but passes an 8-byte .I pos argument in a single register and not two, as is done in every other ABI. .RE -.IP [6] +.IP \(bu Some architectures (namely, Alpha, IA-64, MIPS, SuperH, sparc/32, and sparc/64) use an additional register ("Retval2" in the above table) @@ -322,7 +322,7 @@ xtensa a6 a3 a4 a5 a8 a9 - .TE .PP Notes: -.IP [1] 4 +.IP \(bu 3 The mips/o32 system call convention passes arguments 5 through 8 on the user stack. .if t \{\ diff --git a/man2/syscalls.2 b/man2/syscalls.2 index 274d600cb0..8f6825f495 100644 --- a/man2/syscalls.2 +++ b/man2/syscalls.2 @@ -68,16 +68,16 @@ column indicates the kernel version for those system calls that were new in Linux 2.2, or have appeared since that kernel version. Note the following points: -.IP * 3 +.IP \(bu 3 Where no kernel version is indicated, the system call appeared in kernel 1.0 or earlier. -.IP * +.IP \(bu Where a system call is marked "1.2" this means the system call probably appeared in a 1.1.x kernel version, and first appeared in a stable kernel with 1.2. (Development of the 1.2 kernel was initiated from a branch of kernel 1.0.6 via the 1.1.x unstable kernel series.) -.IP * +.IP \(bu Where a system call is marked "2.0" this means the system call probably appeared in a 1.3.x kernel version, and first appeared in a stable kernel with 2.0. @@ -93,25 +93,25 @@ via the 1.3.x unstable kernel series.) .\" timestamps of some files in 1.3.0 seem to be older .\" than those in 1.2.10. All of this suggests .\" that there might not have been a clean branch point. -.IP * +.IP \(bu Where a system call is marked "2.2" this means the system call probably appeared in a 2.1.x kernel version, and first appeared in a stable kernel with 2.2.0. (Development of the 2.2 kernel was initiated from a branch of kernel 2.0.21 via the 2.1.x unstable kernel series.) -.IP * +.IP \(bu Where a system call is marked "2.4" this means the system call probably appeared in a 2.3.x kernel version, and first appeared in a stable kernel with 2.4.0. (Development of the 2.4 kernel was initiated from a branch of kernel 2.2.8 via the 2.3.x unstable kernel series.) -.IP * +.IP \(bu Where a system call is marked "2.6" this means the system call probably appeared in a 2.5.x kernel version, and first appeared in a stable kernel with 2.6.0. (Development of kernel 2.6 was initiated from a branch of kernel 2.4.15 via the 2.5.x unstable kernel series.) -.IP * +.IP \(bu Starting with kernel 2.6.0, the development model changed, and new system calls may appear in each 2.6.x release. In this case, the exact version number where the system call appeared @@ -120,7 +120,7 @@ This convention continues with the 3.x kernel series, which followed on from kernel 2.6.39; and the 4.x kernel series, which followed on from kernel 3.19; and the 5.x kernel series, which followed on from kernel 4.20. -.IP * +.IP \(bu In some cases, a system call was added to a stable kernel series after it branched from the previous stable kernel series, and then backported into the earlier stable kernel series. @@ -897,9 +897,9 @@ since been removed from the kernel: AVR32 (port removed in Linux 4.12) .RS .PD 0 -.IP * 2 +.IP \(bu 3 .BR pread (2) -.IP * +.IP \(bu .BR pwrite (2) .PD .RE @@ -907,22 +907,22 @@ AVR32 (port removed in Linux 4.12) Blackfin (port removed in Linux 4.17) .RS .PD 0 -.IP * 2 +.IP \(bu 3 .BR bfin_spinlock (2) (added in Linux 2.6.22) -.IP * +.IP \(bu .BR dma_memcpy (2) (added in Linux 2.6.22) -.IP * +.IP \(bu .BR pread (2) (added in Linux 2.6.22) -.IP * +.IP \(bu .BR pwrite (2) (added in Linux 2.6.22) -.IP * +.IP \(bu .BR sram_alloc (2) (added in Linux 2.6.22) -.IP * +.IP \(bu .BR sram_free (2) (added in Linux 2.6.22) .PD @@ -931,16 +931,16 @@ Blackfin (port removed in Linux 4.17) Metag (port removed in Linux 4.17) .RS .PD 0 -.IP * 2 +.IP \(bu 3 .BR metag_get_tls (2) (add in Linux 3.9) -.IP * +.IP \(bu .BR metag_set_fpu_flags (2) (add in Linux 3.9) -.IP * +.IP \(bu .BR metag_set_tls (2) (add in Linux 3.9) -.IP * +.IP \(bu .BR metag_setglobalbit (2) (add in Linux 3.9) .PD @@ -949,7 +949,7 @@ Metag (port removed in Linux 4.17) Tile (port removed in Linux 4.17) .RS .PD 0 -.IP * 2 +.IP \(bu 3 .BR cmpxchg_badaddr (2) (added in Linux 2.6.36) .PD @@ -987,7 +987,7 @@ system call is invoked, and that ABI compatibility is preserved for old binaries.) Examples of systems calls that exist in multiple versions are the following: -.IP * 3 +.IP \(bu 3 By now there are three different versions of .BR stat (2): .IR sys_stat () @@ -1008,7 +1008,7 @@ A similar story applies for .BR lstat (2) and .BR fstat (2). -.IP * +.IP \(bu Similarly, the defines .IR __NR_oldolduname , .IR __NR_olduname , @@ -1019,14 +1019,14 @@ refer to the routines .IR sys_uname (), and .IR sys_newuname (). -.IP * +.IP \(bu In Linux 2.0, a new version of .BR vm86 (2) appeared, with the old and the new kernel routines being named .IR sys_vm86old () and .IR sys_vm86 (). -.IP * +.IP \(bu In Linux 2.4, a new version of .BR getrlimit (2) appeared, with the old and the new kernel routines being named @@ -1037,7 +1037,7 @@ and .IR sys_getrlimit () (slot .IR __NR_ugetrlimit ). -.IP * +.IP \(bu Linux 2.4 increased the size of user and group IDs from 16 to 32 bits. .\" 64-bit off_t changes: ftruncate64, *stat64, .\" fcntl64 (because of the flock structure), getdents64, *statfs64 @@ -1049,7 +1049,7 @@ To support this change, a range of system calls were added .BR setresuid32 (2)), superseding earlier calls of the same name without the "32" suffix. -.IP * +.IP \(bu Linux 2.4 added support for applications on 32-bit architectures to access large files (i.e., files for which the sizes and file offsets can't be represented in 32 bits.) @@ -1072,7 +1072,7 @@ On newer platforms that only have 64-bit file access and 32-bit UIDs/GIDs the UID/GID and file access system calls. On platforms (typically, 32-bit platforms) where the *64 and *32 calls exist, the other versions are obsolete. -.IP * +.IP \(bu The .I rt_sig* calls were added in kernel 2.2 to support the addition @@ -1080,7 +1080,7 @@ of real-time signals (see .BR signal (7)). These system calls supersede the older system calls of the same name without the "rt_" prefix. -.IP * +.IP \(bu The .BR select (2) and diff --git a/man2/timer_create.2 b/man2/timer_create.2 index 59481c0168..57f42019ee 100644 --- a/man2/timer_create.2 +++ b/man2/timer_create.2 @@ -281,7 +281,7 @@ option. Part of the implementation of the POSIX timers API is provided by glibc. .\" See nptl/sysdeps/unix/sysv/linux/timer_create.c In particular: -.IP * 3 +.IP \(bu 3 Much of the functionality for .B SIGEV_THREAD is implemented within glibc, rather than the kernel. @@ -295,14 +295,14 @@ value of .B SIGEV_THREAD_ID along with a real-time signal that is reserved by the implementation (see .BR nptl (7)). -.IP * +.IP \(bu The implementation of the default case where .I evp is NULL is handled inside glibc, which invokes the underlying system call with a suitably populated .I sigevent structure. -.IP * +.IP \(bu The timer IDs presented at user level are maintained by glibc, which maps these IDs to the timer IDs employed by the kernel. .\" See the glibc source file kernel-posix-timers.h for the structure diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2 index c89065f5b0..078a2d4b9b 100644 --- a/man2/timerfd_create.2 +++ b/man2/timerfd_create.2 @@ -480,7 +480,7 @@ or .B CLOCK_REALTIME_ALARM timer that was created with .BR timerfd_create (): -.IP (a) 4 +.IP (1) 5 The timer has been started .RB ( timerfd_settime ()) with the @@ -488,13 +488,13 @@ with the and .B TFD_TIMER_CANCEL_ON_SET flags; -.IP (b) +.IP (2) A discontinuous change (e.g., .BR settimeofday (2)) is subsequently made to the .B CLOCK_REALTIME clock; and -.IP (c) +.IP (3) the caller once more calls .BR timerfd_settime () to rearm the timer (without first doing a @@ -502,7 +502,7 @@ to rearm the timer (without first doing a on the file descriptor). .PP In this case the following occurs: -.IP \(bu 2 +.IP \(bu 3 The .BR timerfd_settime () returns \-1 with diff --git a/man2/utimensat.2 b/man2/utimensat.2 index 42efbd7b44..e37fb1f7b1 100644 --- a/man2/utimensat.2 +++ b/man2/utimensat.2 @@ -112,15 +112,15 @@ is NULL, or both fields specify .BR UTIME_NOW ), either: -.IP 1. 3 +.IP \(bu 3 the caller must have write access to the file; .\" 2.6.22 was broken here -- for futimens() the check is .\" based on whether or not the file descriptor is writable, .\" not on whether the caller's effective UID has write .\" permission for the file referred to by the descriptor. -.IP 2. +.IP \(bu the caller's effective user ID must match the owner of the file; or -.IP 3. +.IP \(bu the caller must have appropriate privileges. .PP To make any change other than setting both timestamps to the @@ -339,13 +339,13 @@ field is .BR UTIME_OMIT ) and either: .RS -.IP * 3 +.IP \(bu 3 the caller's effective user ID does not match the owner of file, and the caller is not privileged (Linux: does not have the .B CAP_FOWNER capability); or, -.IP * +.IP \(bu .\" Linux 2.6.22 was broken here: .\" it was not consistent with the old utimes() implementation, .\" since the case when both tv_nsec fields are UTIME_NOW, was not @@ -462,7 +462,7 @@ and on kernels before 2.6.26. These bugs are either nonconformances with the POSIX.1 draft specification or inconsistencies with historical Linux behavior. -.IP * 3 +.IP \(bu 3 POSIX.1 specifies that if one of the .I tv_nsec fields has the value @@ -477,7 +477,7 @@ Instead, the value of the field is required to be 0 (or the error .B EINVAL results). -.IP * +.IP \(bu Various bugs mean that for the purposes of permission checking, the case where both .I tv_nsec @@ -579,7 +579,7 @@ value is returned in case of an error. .\" .BR UTIME_NOW . .\" Instead, the call fails with the error .\" .BR EPERM . -.IP * +.IP \(bu POSIX.1 says that a process that has \fIwrite access to the file\fP can make a call with .I times diff --git a/man2/vfork.2 b/man2/vfork.2 index 4f98ce2f22..a4d88cda92 100644 --- a/man2/vfork.2 +++ b/man2/vfork.2 @@ -167,11 +167,11 @@ and .BR vfork (), there are various reasons why Linux and other systems have retained .BR vfork (): -.IP * 3 +.IP \(bu 3 Some performance-critical applications require the small performance advantage conferred by .BR vfork (). -.IP * +.IP \(bu .BR vfork () can be implemented on systems that lack a memory-management unit (MMU), but .BR fork (2) @@ -188,7 +188,7 @@ is designed to be implementable on systems that lack an MMU.) .\" http://developers.sun.com/solaris/articles/subprocess/subprocess.html .\" http://mailman.uclinux.org/pipermail/uclinux-dev/2009-April/000684.html .\" -.IP * +.IP \(bu On systems where memory is constrained, .BR vfork () avoids the need to temporarily commit memory (see the description of diff --git a/man3/__setfpucw.3 b/man3/__setfpucw.3 index d7975a2672..8f7e9f489e 100644 --- a/man3/__setfpucw.3 +++ b/man3/__setfpucw.3 @@ -57,11 +57,11 @@ can be used. Set FPU control word on the i386 architecture to .RS .PD 0 -.IP - 2 +.IP \(bu 3 extended precision -.IP - +.IP \(bu rounding to nearest -.IP - +.IP \(bu exceptions on overflow, zero divide and NaN .PD .RE diff --git a/man3/aio_suspend.3 b/man3/aio_suspend.3 index fe9b161e29..102fb52f03 100644 --- a/man3/aio_suspend.3 +++ b/man3/aio_suspend.3 @@ -21,13 +21,13 @@ Real-time library The .BR aio_suspend () function suspends the calling thread until one of the following occurs: -.IP * 3 +.IP \(bu 3 One or more of the asynchronous I/O requests in the list .I aiocb_list has completed. -.IP * +.IP \(bu A signal is delivered. -.IP * +.IP \(bu .I timeout is not NULL and the specified time interval has passed. (For details of the diff --git a/man3/backtrace.3 b/man3/backtrace.3 index 97d8964baa..552eaa173f 100644 --- a/man3/backtrace.3 +++ b/man3/backtrace.3 @@ -159,17 +159,17 @@ These functions are GNU extensions. These functions make some assumptions about how a function's return address is stored on the stack. Note the following: -.IP * 3 +.IP \(bu 3 Omission of the frame pointers (as implied by any of .BR gcc (1)'s nonzero optimization levels) may cause these assumptions to be violated. -.IP * +.IP \(bu Inlined functions do not have stack frames. -.IP * +.IP \(bu Tail-call optimization causes one stack frame to replace another. -.IP * +.IP \(bu .BR backtrace () and .BR backtrace_symbols_fd () diff --git a/man3/bzero.3 b/man3/bzero.3 index 2045162cc2..cd57670077 100644 --- a/man3/bzero.3 +++ b/man3/bzero.3 @@ -101,7 +101,7 @@ are never optimized away by the compiler. The .BR explicit_bzero () function does not solve all problems associated with erasing sensitive data: -.IP 1. 3 +.IP \(bu 3 The .BR explicit_bzero () function does @@ -114,7 +114,7 @@ a register and in "scratch" stack areas. The .BR explicit_bzero () function is not aware of these copies, and can't erase them. -.IP 2. +.IP \(bu In some circumstances, .BR explicit_bzero () can diff --git a/man3/dlinfo.3 b/man3/dlinfo.3 index 03103d965d..bcf74bc5e9 100644 --- a/man3/dlinfo.3 +++ b/man3/dlinfo.3 @@ -102,7 +102,7 @@ The request described below allows applications to size the buffer suitably. The caller must perform the following steps: .RS -.IP 1. 3 +.IP (1) 5 Use a .B RTLD_DI_SERINFOSIZE request to populate a @@ -112,12 +112,12 @@ structure with the size of the structure needed for the subsequent .B RTLD_DI_SERINFO request. -.IP 2. +.IP (2) Allocate a .I Dl_serinfo buffer of the correct size .RI ( dls_size ). -.IP 3. +.IP (3) Use a further .B RTLD_DI_SERINFOSIZE request to populate the @@ -125,7 +125,7 @@ request to populate the and .I dls_cnt fields of the buffer allocated in the previous step. -.IP 4. +.IP (4) Use a .B RTLD_DI_SERINFO to obtain the library search paths. diff --git a/man3/dlopen.3 b/man3/dlopen.3 index aca98f4896..3391471b22 100644 --- a/man3/dlopen.3 +++ b/man3/dlopen.3 @@ -67,32 +67,32 @@ Otherwise, the dynamic linker searches for the object as follows (see .BR ld.so (8) for further details): -.IP o 4 +.IP \(bu 3 (ELF only) If the calling object (i.e., the shared library or executable from which .BR dlopen () is called) contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag, then the directories listed in the DT_RPATH tag are searched. -.IP o +.IP \(bu If, at the time that the program was started, the environment variable .B LD_LIBRARY_PATH was defined to contain a colon-separated list of directories, then these are searched. (As a security measure, this variable is ignored for set-user-ID and set-group-ID programs.) -.IP o +.IP \(bu (ELF only) If the calling object contains a DT_RUNPATH tag, then the directories listed in that tag are searched. -.IP o +.IP \(bu The cache file .I /etc/ld.so.cache (maintained by .BR ldconfig (8)) is checked to see whether it contains an entry for .IR filename . -.IP o +.IP \(bu The directories .I /lib and diff --git a/man3/duplocale.3 b/man3/duplocale.3 index 93bbec210e..51d1544eeb 100644 --- a/man3/duplocale.3 +++ b/man3/duplocale.3 @@ -62,11 +62,11 @@ function first appeared in version 2.3 of the GNU C library. POSIX.1-2008. .SH NOTES Duplicating a locale can serve the following purposes: -.IP * 3 +.IP \(bu 3 To create a copy of a locale object in which one of more categories are to be modified (using .BR newlocale (3)). -.IP * +.IP \(bu To obtain a handle for the current locale which can used in other functions that employ a locale handle, such as .BR toupper_l (3). diff --git a/man3/fopencookie.3 b/man3/fopencookie.3 index 6bcb10db52..1696bc3527 100644 --- a/man3/fopencookie.3 +++ b/man3/fopencookie.3 @@ -31,10 +31,10 @@ which provides a stream interface to data that is stored in a buffer in memory. .PP In order to create a custom stream the programmer must: -.IP * 3 +.IP \(bu 3 Implement four "hook" functions that are used internally by the standard I/O library when performing I/O on the stream. -.IP * +.IP \(bu Define a "cookie" data type, a structure that provides bookkeeping information (e.g., where to store data) used by the aforementioned hook functions. @@ -45,7 +45,7 @@ when passed to .BR fopencookie ()), but automatically supplies the cookie as the first argument when calling the hook functions. -.IP * +.IP \(bu Call .BR fopencookie () to open a new stream and associate the cookie and hook functions diff --git a/man3/fpathconf.3 b/man3/fpathconf.3 index 130bddc9e9..a09a94f0ad 100644 --- a/man3/fpathconf.3 +++ b/man3/fpathconf.3 @@ -156,7 +156,7 @@ or must refer to a terminal. .SH RETURN VALUE The return value of these functions is one of the following: -.IP * 3 +.IP \(bu 3 On error, \-1 is returned and .I errno is set to indicate the error @@ -165,7 +165,7 @@ is set to indicate the error indicating that .I name is invalid). -.IP * +.IP \(bu If .I name corresponds to a maximum or minimum limit, and that limit is indeterminate, @@ -177,13 +177,13 @@ is not changed. to zero before the call, and then check whether .I errno is nonzero when \-1 is returned.) -.IP * +.IP \(bu If .I name corresponds to an option, a positive value is returned if the option is supported, and \-1 is returned if the option is not supported. -.IP * +.IP \(bu Otherwise, the current value of the option or limit is returned. This value will not be more restrictive than diff --git a/man3/ftw.3 b/man3/ftw.3 index a02f621b7d..4ac422b949 100644 --- a/man3/ftw.3 +++ b/man3/ftw.3 @@ -306,7 +306,7 @@ is never called for a directory that would be a descendant of itself. is an older function that offers a subset of the functionality of .BR nftw (). The notable differences are as follows: -.IP * 3 +.IP \(bu 3 .BR ftw () has no .I flags @@ -316,11 +316,11 @@ It behaves the same as when is called with .I flags specified as zero. -.IP * +.IP \(bu The callback function, .IR fn (), is not supplied with a fourth argument. -.IP * +.IP \(bu The range of values that is passed via the .I typeflag argument supplied to diff --git a/man3/getaddrinfo.3 b/man3/getaddrinfo.3 index d33a40fd0f..8ab6a56a7f 100644 --- a/man3/getaddrinfo.3 +++ b/man3/getaddrinfo.3 @@ -329,7 +329,7 @@ official name of the host. The remaining fields of each returned .I addrinfo structure are initialized as follows: -.IP * 2 +.IP \(bu 3 The .IR ai_family , .IR ai_socktype , @@ -352,7 +352,7 @@ or and .I ai_protocol returns the protocol for the socket. -.IP * +.IP \(bu A pointer to the socket address is placed in the .I ai_addr field, and the length of the socket address, in bytes, diff --git a/man3/getaddrinfo_a.3 b/man3/getaddrinfo_a.3 index 8d4be103c5..4d6e311318 100644 --- a/man3/getaddrinfo_a.3 +++ b/man3/getaddrinfo_a.3 @@ -168,13 +168,13 @@ The argument specifies the size of the array .IR list . The call blocks until one of the following occurs: -.IP * 3 +.IP \(bu 3 One or more of the operations in .I list completes. -.IP * +.IP \(bu The call is interrupted by a signal that is caught. -.IP * +.IP \(bu The time interval specified in .I timeout elapses. diff --git a/man3/getenv.3 b/man3/getenv.3 index 8aa76c0d6f..f96b34b33a 100644 --- a/man3/getenv.3 +++ b/man3/getenv.3 @@ -50,14 +50,14 @@ function is just like except that it returns NULL in cases where "secure execution" is required. Secure execution is required if one of the following conditions was true when the program run by the calling process was loaded: -.IP * 3 +.IP \(bu 3 the process's effective user ID did not match its real user ID or the process's effective group ID did not match its real group ID (typically this is the result of executing a set-user-ID or set-group-ID program); -.IP * +.IP \(bu the effective capability bit was set on the executable file; or -.IP * +.IP \(bu the process has a nonempty permitted capability set. .PP Secure execution may also be required if triggered diff --git a/man3/getopt.3 b/man3/getopt.3 index 9f25478999..5b9dcc5daf 100644 --- a/man3/getopt.3 +++ b/man3/getopt.3 @@ -174,14 +174,14 @@ can detect two kinds of errors: and (2) a missing option argument (i.e., an option at the end of the command line without an expected argument). Such errors are handled and reported as follows: -.IP * 3 +.IP \(bu 3 By default, .BR getopt () prints an error message on standard error, places the erroneous option character in .IR optopt , and returns \(aq?\(aq as the function result. -.IP * +.IP \(bu If the caller has set the global variable .I opterr to zero, then @@ -192,7 +192,7 @@ the function return value is \(aq?\(aq. (By default, .I opterr has a nonzero value.) -.IP * +.IP \(bu If the first character (following any optional \(aq+\(aq or \(aq\-\(aq described above) of \fIoptstring\fP diff --git a/man3/iconv.3 b/man3/iconv.3 index d6099cf3c0..2bb37cde2e 100644 --- a/man3/iconv.3 +++ b/man3/iconv.3 @@ -71,21 +71,21 @@ function can also convert a sequence of input bytes to an update to the conversion state without producing any output bytes; such input is called a \fIshift sequence\fP. The conversion can stop for four reasons: -.IP 1. 3 +.IP \(bu 3 An invalid multibyte sequence is encountered in the input. In this case, it sets \fIerrno\fP to \fBEILSEQ\fP and returns .IR (size_t)\ \-1 . \fI*inbuf\fP is left pointing to the beginning of the invalid multibyte sequence. -.IP 2. +.IP \(bu The input byte sequence has been entirely converted, that is, \fI*inbytesleft\fP has gone down to 0. In this case, .BR iconv () returns the number of nonreversible conversions performed during this call. -.IP 3. +.IP \(bu An incomplete multibyte sequence is encountered in the input, and the input byte sequence terminates after it. In this case, it sets \fIerrno\fP to @@ -93,7 +93,7 @@ In this case, it sets \fIerrno\fP to .IR (size_t)\ \-1 . \fI*inbuf\fP is left pointing to the beginning of the incomplete multibyte sequence. -.IP 4. +.IP \(bu The output buffer has no more room for the next converted character. In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns .IR (size_t)\ \-1 . diff --git a/man3/ilogb.3 b/man3/ilogb.3 index 99779a9cb8..acdcb4034a 100644 --- a/man3/ilogb.3 +++ b/man3/ilogb.3 @@ -132,13 +132,13 @@ C99, POSIX.1-2001, POSIX.1-2008. .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6794 Before version 2.16, the following bugs existed in the glibc implementation of these functions: -.IP * 3 +.IP \(bu 3 The domain error case where .I x is 0 or a NaN did not cause .I errno to be set or (on some architectures) raise a floating-point exception. -.IP * 3 +.IP \(bu The domain error case where .I x is an infinity did not cause diff --git a/man3/inet_net_pton.3 b/man3/inet_net_pton.3 index 24b57975e9..9c8abd7383 100644 --- a/man3/inet_net_pton.3 +++ b/man3/inet_net_pton.3 @@ -181,34 +181,34 @@ an explicit size value, then that size becomes the return value of Otherwise, the return value, .IR bits , is inferred as follows: -.IP * 3 +.IP \(bu 3 If the most significant byte of the network number is greater than or equal to 240, then .I bits is 32. -.IP * 3 +.IP \(bu Otherwise, if the most significant byte of the network number is greater than or equal to 224, then .I bits is 4. -.IP * 3 +.IP \(bu Otherwise, if the most significant byte of the network number is greater than or equal to 192, then .I bits is 24. -.IP * 3 +.IP \(bu Otherwise, if the most significant byte of the network number is greater than or equal to 128, then .I bits is 16. -.IP * +.IP \(bu Otherwise, .I bits is 8. diff --git a/man3/inet_pton.3 b/man3/inet_pton.3 index 0320d8191d..5560c84ce1 100644 --- a/man3/inet_pton.3 +++ b/man3/inet_pton.3 @@ -63,14 +63,14 @@ which must be (16) bytes (128 bits) long. The allowed formats for IPv6 addresses follow these rules: .RS -.IP 1. 3 +.IP \(bu 3 The preferred format is .IR x:x:x:x:x:x:x:x . This form consists of eight hexadecimal numbers, each of which expresses a 16-bit value (i.e., each .I x can be up to 4 hex digits). -.IP 2. +.IP \(bu A series of contiguous zero values in the preferred format can be abbreviated to .IR :: . @@ -83,7 +83,7 @@ can be abbreviated as .IR ::1 . The wildcard address, consisting of all zeros, can be written as .IR :: . -.IP 3. +.IP \(bu An alternate format is useful for expressing IPv4-mapped IPv6 addresses. This form is written as .IR x:x:x:x:x:x:d.d.d.d , diff --git a/man3/mallopt.3 b/man3/mallopt.3 index 37a719de92..e058b0dec4 100644 --- a/man3/mallopt.3 +++ b/man3/mallopt.3 @@ -285,13 +285,13 @@ to modify the program break. (The measurement unit for this parameter is bytes.) This parameter has an effect in the following circumstances: .RS -.IP * 3 +.IP \(bu 3 When the program break is increased, then .B M_TOP_PAD bytes are added to the .BR sbrk (2) request. -.IP * +.IP \(bu When the heap is trimmed as a consequence of calling .BR free (3) (see the discussion of diff --git a/man3/mbsnrtowcs.3 b/man3/mbsnrtowcs.3 index 1bd08438c7..caf129258a 100644 --- a/man3/mbsnrtowcs.3 +++ b/man3/mbsnrtowcs.3 @@ -78,7 +78,7 @@ by one and by the number of bytes consumed. The conversion can stop for three reasons: -.IP 1. 3 +.IP \(bu 3 An invalid multibyte sequence has been encountered. In this case, .I *src @@ -89,7 +89,7 @@ and .I errno is set to .BR EILSEQ . -.IP 2. +.IP \(bu The .I nms limit forces a stop, @@ -105,7 +105,7 @@ next multibyte sequence to be converted, and the number of wide characters written to .I dest is returned. -.IP 3. +.IP \(bu The multibyte string has been completely converted, including the terminating null wide character (\(aq\e0\(aq) (which has the side effect of bringing back diff --git a/man3/mbsrtowcs.3 b/man3/mbsrtowcs.3 index ef61409d1a..e0e9b75d3c 100644 --- a/man3/mbsrtowcs.3 +++ b/man3/mbsrtowcs.3 @@ -50,7 +50,7 @@ by one and .I *src by the number of bytes consumed. The conversion can stop for three reasons: -.IP 1. 3 +.IP \(bu 3 An invalid multibyte sequence has been encountered. In this case, .I *src @@ -61,7 +61,7 @@ and .I errno is set to .BR EILSEQ . -.IP 2. +.IP \(bu .I len non-L\(aq\e0\(aq wide characters have been stored at .IR dest . @@ -72,7 +72,7 @@ multibyte sequence to be converted, and the number of wide characters written to .I dest is returned. -.IP 3. +.IP \(bu The multibyte string has been completely converted, including the terminating null wide character (\(aq\e0\(aq), which has the side effect of bringing back diff --git a/man3/mbstowcs.3 b/man3/mbstowcs.3 index 29ced70a54..a8f57a0457 100644 --- a/man3/mbstowcs.3 +++ b/man3/mbstowcs.3 @@ -41,12 +41,12 @@ The sequence of characters in the string .I src shall begin in the initial shift state. The conversion can stop for three reasons: -.IP 1. 3 +.IP \(bu 3 An invalid multibyte sequence has been encountered. In this case, .I (size_t)\ \-1 is returned. -.IP 2. +.IP \(bu .I n non-L\(aq\e0\(aq wide characters have been stored at .IR dest . @@ -54,7 +54,7 @@ In this case, the number of wide characters written to .I dest is returned, but the shift state at this point is lost. -.IP 3. +.IP \(bu The multibyte string has been completely converted, including the terminating null character (\(aq\e0\(aq). In this case, the number of wide characters written to diff --git a/man3/newlocale.3 b/man3/newlocale.3 index 489c6aab1a..cc4dd7d9c0 100644 --- a/man3/newlocale.3 +++ b/man3/newlocale.3 @@ -38,13 +38,13 @@ returning a reference to the new or modified object as the function result. Whether the call creates a new object or modifies an existing object is determined by the value of .IR base : -.IP * 3 +.IP \(bu 3 If .I base is .IR "(locale_t)\ 0" , a new object is created. -.IP * +.IP \(bu If .I base refers to valid existing locale object @@ -211,7 +211,7 @@ Having created and initialized the locale object, the program then applies it using .BR uselocale (3), and then tests the effect of the locale changes by: -.IP 1. 3 +.IP (1) 5 Displaying a floating-point number with a fractional part. This output will be affected by the .B LC_NUMERIC @@ -219,7 +219,7 @@ setting. In many European-language locales, the fractional part of the number is separated from the integer part using a comma, rather than a period. -.IP 2. +.IP (2) Displaying the date. The format and language of the output will be affected by the .B LC_TIME diff --git a/man3/posix_fallocate.3 b/man3/posix_fallocate.3 index 200a354759..74fe758b24 100644 --- a/man3/posix_fallocate.3 +++ b/man3/posix_fallocate.3 @@ -146,16 +146,16 @@ system call, which is MT-safe. If the underlying filesystem does not support .BR fallocate (2), then the operation is emulated with the following caveats: -.IP * 2 +.IP \(bu 3 The emulation is inefficient. -.IP * +.IP \(bu There is a race condition where concurrent writes from another thread or process could be overwritten with null bytes. -.IP * +.IP \(bu There is a race condition where concurrent file size increases by another thread or process could result in a file whose size is smaller than expected. -.IP * +.IP \(bu If .I fd has been opened with the diff --git a/man3/posix_spawn.3 b/man3/posix_spawn.3 index 2bcf58272c..0a20edbc2a 100644 --- a/man3/posix_spawn.3 +++ b/man3/posix_spawn.3 @@ -168,7 +168,7 @@ Before glibc 2.24, the child process is created using instead of .BR fork (2) when either of the following is true: -.IP * 3 +.IP \(bu 3 the .I spawn-flags element of the attributes object pointed to by @@ -176,7 +176,7 @@ element of the attributes object pointed to by contains the GNU-specific flag .BR POSIX_SPAWN_USEVFORK ; or -.IP * +.IP \(bu .I file_actions is NULL and the .I spawn-flags @@ -214,20 +214,20 @@ These operations are controlled by the attributes object pointed to by and the file actions object pointed to by .IR file_actions . In the child, processing is done in the following sequence: -.IP 1. 3 +.IP (1) 5 Process attribute actions: signal mask, signal default handlers, scheduling algorithm and parameters, process group, and effective user and group IDs are changed as specified by the attributes object pointed to by .IR attrp . -.IP 2. +.IP (2) File actions, as specified in the .I file_actions argument, are performed in the order that they were specified using calls to the .BR posix_spawn_file_actions_add* () functions. -.IP 3. +.IP (3) File descriptors with the .B FD_CLOEXEC flag set are closed. @@ -306,7 +306,7 @@ of the object pointed to by Set the scheduling policy algorithm and parameters of the child, as follows: .RS -.IP * 3 +.IP \(bu 3 The scheduling policy is set to the value specified in the .I spawn-schedpolicy attribute @@ -315,7 +315,7 @@ attribute .\" .BR posix_spawnattr_setpolicy (3)) of the object pointed to by .IR attrp . -.IP * +.IP \(bu The scheduling parameters are set to the value specified in the .I spawn-schedparam attribute diff --git a/man3/psignal.3 b/man3/psignal.3 index e4e0d9c0ff..47a4e72ea5 100644 --- a/man3/psignal.3 +++ b/man3/psignal.3 @@ -102,11 +102,11 @@ POSIX.1-2008, 4.3BSD. In glibc versions up to 2.12, .BR psiginfo () had the following bugs: -.IP * 3 +.IP \(bu 3 In some circumstances, a trailing newline is not printed. .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12107 .\" Reportedly now fixed; check glibc 2.13 -.IP * +.IP \(bu Additional details are not displayed for real-time signals. .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12108 .\" Reportedly now fixed; check glibc 2.13 diff --git a/man3/pthread_atfork.3 b/man3/pthread_atfork.3 index 590e3355ea..0109a7ff34 100644 --- a/man3/pthread_atfork.3 +++ b/man3/pthread_atfork.3 @@ -25,17 +25,17 @@ The handlers are executed in the context of the thread that calls .BR fork (2). .PP Three kinds of handler can be registered: -.IP * 3 +.IP \(bu 3 .I prepare specifies a handler that is executed in the parent process before .BR fork (2) processing starts. -.IP * +.IP \(bu .I parent specifies a handler that is executed in the parent process after .BR fork (2) processing completes. -.IP * +.IP \(bu .I child specifies a handler that is executed in the child process after .BR fork (2) diff --git a/man3/pthread_attr_setsigmask_np.3 b/man3/pthread_attr_setsigmask_np.3 index 7c1c58bdac..a2c7595cd5 100644 --- a/man3/pthread_attr_setsigmask_np.3 +++ b/man3/pthread_attr_setsigmask_np.3 @@ -107,7 +107,7 @@ that can be used to manipulate and inspect signal sets, see In the absence of .BR pthread_attr_setsigmask_np () it is possible to create a thread with a desired signal mask as follows: -.IP \(bu 2 +.IP \(bu 3 The creating thread uses .BR pthread_sigmask (3) to save its current signal mask and set its mask to block all signals. diff --git a/man3/pthread_cancel.3 b/man3/pthread_cancel.3 index be55339404..00b5c679d5 100644 --- a/man3/pthread_cancel.3 +++ b/man3/pthread_cancel.3 @@ -59,17 +59,17 @@ A list of functions that are or may be cancelation points is provided in When a cancelation requested is acted on, the following steps occur for .I thread (in this order): -.IP 1. 3 +.IP (1) 5 Cancellation clean-up handlers are popped (in the reverse of the order in which they were pushed) and called. (See .BR pthread_cleanup_push (3).) -.IP 2. +.IP (2) Thread-specific data destructors are called, in an unspecified order. (See .BR pthread_key_create (3).) -.IP 3. +.IP (3) The thread is terminated. (See .BR pthread_exit (3).) diff --git a/man3/pthread_cleanup_push.3 b/man3/pthread_cleanup_push.3 index c6e27f0cf2..273e9fa46e 100644 --- a/man3/pthread_cleanup_push.3 +++ b/man3/pthread_cleanup_push.3 @@ -46,11 +46,11 @@ is nonzero. .PP A cancelation clean-up handler is popped from the stack and executed in the following circumstances: -.IP 1. 3 +.IP \(bu 3 When a thread is canceled, all of the stacked clean-up handlers are popped and executed in the reverse of the order in which they were pushed onto the stack. -.IP 2. +.IP \(bu When a thread terminates by calling .BR pthread_exit (3), all clean-up handlers are executed as described in the preceding point. @@ -60,7 +60,7 @@ called if the thread terminates by performing a .I return from the thread start function.) -.IP 3. +.IP \(bu When a thread calls .BR pthread_cleanup_pop () with a nonzero diff --git a/man3/pthread_create.3 b/man3/pthread_create.3 index 9cbae0ff6e..3b27a8db4c 100644 --- a/man3/pthread_create.3 +++ b/man3/pthread_create.3 @@ -29,13 +29,13 @@ is passed as the sole argument of .IR start_routine (). .PP The new thread terminates in one of the following ways: -.IP * 2 +.IP \(bu 3 It calls .BR pthread_exit (3), specifying an exit status value that is available to another thread in the same process that calls .BR pthread_join (3). -.IP * +.IP \(bu It returns from .IR start_routine (). This is equivalent to calling @@ -43,10 +43,10 @@ This is equivalent to calling with the value supplied in the .I return statement. -.IP * +.IP \(bu It is canceled (see .BR pthread_cancel (3)). -.IP * +.IP \(bu Any of the threads in the process calls .BR exit (3), or the main thread performs a return from diff --git a/man3/pthread_getattr_default_np.3 b/man3/pthread_getattr_default_np.3 index 3a936b5443..47d16b6b15 100644 --- a/man3/pthread_getattr_default_np.3 +++ b/man3/pthread_getattr_default_np.3 @@ -28,13 +28,13 @@ The default attributes are set using the attributes supplied in .IR *attr , a previously initialized thread attributes object. Note the following details about the supplied attributes object: -.IP * 3 +.IP \(bu 3 The attribute settings in the object must be valid. -.IP * +.IP \(bu The .I stack address attribute must not be set in the object. -.IP * +.IP \(bu Setting the .I stack size attribute to zero means leave the default stack size unchanged. diff --git a/man3/pthread_getattr_np.3 b/man3/pthread_getattr_np.3 index 29a8278f2c..32c9db6edb 100644 --- a/man3/pthread_getattr_np.3 +++ b/man3/pthread_getattr_np.3 @@ -30,13 +30,13 @@ the corresponding attribute values passed in the object that was used to create the thread using .BR pthread_create (3). In particular, the following attributes may differ: -.IP * 2 +.IP \(bu 3 the detach state, since a joinable thread may have detached itself after creation; -.IP * +.IP \(bu the stack size, which the implementation may align to a suitable boundary. -.IP * +.IP \(bu and the guard size, which the implementation may round upward to a multiple of the page size, or ignore (i.e., treat as 0), diff --git a/man3/readdir_r.3 b/man3/readdir_r.3 index 7ce6aadf11..b32ab4c5ee 100644 --- a/man3/readdir_r.3 +++ b/man3/readdir_r.3 @@ -59,14 +59,14 @@ instead of Furthermore, since version 2.24, glibc deprecates .BR readdir_r (). The reasons are as follows: -.IP * 3 +.IP \(bu 3 On systems where .B NAME_MAX is undefined, calling .BR readdir_r () may be unsafe because the interface does not allow the caller to specify the length of the buffer used for the returned directory entry. -.IP * +.IP \(bu On some systems, .BR readdir_r () can't read directory entries with very long names. @@ -80,7 +80,7 @@ On some other systems, may return a success status, but the returned .I d_name field may not be null terminated or may be truncated. -.IP * +.IP \(bu In the current POSIX.1 specification (POSIX.1-2008), .BR readdir (3) is not required to be thread-safe. @@ -97,7 +97,7 @@ using with external synchronization is still preferable to the use of .BR readdir_r (), for the reasons given in the points above. -.IP * +.IP \(bu It is expected that a future version of POSIX.1 .\" FIXME . .\" http://www.austingroupbugs.net/view.php?id=696 diff --git a/man3/scanf.3 b/man3/scanf.3 index 38ed9b9773..979d76cb5f 100644 --- a/man3/scanf.3 +++ b/man3/scanf.3 @@ -687,12 +687,12 @@ As well as being standardized by POSIX, the modifier has the following further advantages over the use of .BR a : -.IP * 2 +.IP \(bu 3 It may also be applied to .B %c conversion specifiers (e.g., .BR %3mc ). -.IP * +.IP \(bu It avoids ambiguity with respect to the .B %a floating-point conversion specifier (and is unaffected by diff --git a/man3/setjmp.3 b/man3/setjmp.3 index 269794fe01..c2df55cca0 100644 --- a/man3/setjmp.3 +++ b/man3/setjmp.3 @@ -301,12 +301,12 @@ that occur upon a return from the initial call to the behavior is undefined if the program subsequently makes a call to a non-async-signal-safe function. The only way of avoiding undefined behavior is to ensure one of the following: -.IP * 3 +.IP \(bu 3 After long jumping from the signal handler, the program does not call any non-async-signal-safe functions and does not return from the initial call to .IR main (). -.IP * +.IP \(bu Any signal whose handler performs a long jump must be blocked during .I every call to a non-async-signal-safe function and diff --git a/man3/setlocale.3 b/man3/setlocale.3 index 032d45fdbd..e5f840c5eb 100644 --- a/man3/setlocale.3 +++ b/man3/setlocale.3 @@ -152,7 +152,7 @@ setlocale(LC_ALL, ""); .in .PP after program initialization, and then: -.IP \(bu 2 +.IP \(bu 3 using the values returned from a .BR localeconv (3) call for locale-dependent information; diff --git a/man3/sigpause.3 b/man3/sigpause.3 index c4d3b689c2..5acfe85361 100644 --- a/man3/sigpause.3 +++ b/man3/sigpause.3 @@ -101,11 +101,11 @@ or is defined. Otherwise, the System V version is used, and feature test macros must be defined as follows to obtain the declaration: -.IP * 3 +.IP \(bu 3 Since glibc 2.26: _XOPEN_SOURCE >= 500 .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) -.IP * +.IP \(bu Glibc 2.25 and earlier: _XOPEN_SOURCE .PP Since glibc 2.19, only the System V version is exposed by diff --git a/man3/sigwait.3 b/man3/sigwait.3 index 4ebf048d55..bf724add54 100644 --- a/man3/sigwait.3 +++ b/man3/sigwait.3 @@ -45,12 +45,12 @@ The operation of is the same as .BR sigwaitinfo (2), except that: -.IP * 2 +.IP \(bu 3 .BR sigwait () returns only the signal number, rather than a .I siginfo_t structure describing the signal. -.IP * +.IP \(bu The return values of the two functions are different. .SH RETURN VALUE On success, diff --git a/man3/strcat.3 b/man3/strcat.3 index 058b121197..44e0ac3a80 100644 --- a/man3/strcat.3 +++ b/man3/strcat.3 @@ -46,13 +46,13 @@ is not large enough, program behavior is unpredictable; The .BR strncat () function is similar, except that -.IP * 3 +.IP \(bu 3 it will use at most .I n bytes from .IR src ; and -.IP * +.IP \(bu .I src does not need to be null-terminated if it contains .I n diff --git a/man3/strcmp.3 b/man3/strcmp.3 index fc1b79ce68..4ab4803acf 100644 --- a/man3/strcmp.3 +++ b/man3/strcmp.3 @@ -36,7 +36,7 @@ The comparison is done using unsigned characters. .PP .BR strcmp () returns an integer indicating the result of the comparison, as follows: -.IP \(bu 2 +.IP \(bu 3 0, if the .I s1 and diff --git a/man3/strsep.3 b/man3/strsep.3 index 17b02d3380..da2dc5827f 100644 --- a/man3/strsep.3 +++ b/man3/strsep.3 @@ -95,11 +95,11 @@ conforms to C89/C99 and hence is more portable. .SH BUGS Be cautious when using this function. If you do use it, note that: -.IP * 2 +.IP \(bu 3 This function modifies its first argument. -.IP * +.IP \(bu This function cannot be used on constant strings. -.IP * +.IP \(bu The identity of the delimiting character is lost. .SH EXAMPLES The program below is a port of the one found in diff --git a/man3/strtok.3 b/man3/strtok.3 index b193d940b6..08a66c4454 100644 --- a/man3/strtok.3 +++ b/man3/strtok.3 @@ -188,13 +188,13 @@ that is being used to parse .SH BUGS Be cautious when using these functions. If you do use them, note that: -.IP * 2 +.IP \(bu 3 These functions modify their first argument. -.IP * +.IP \(bu These functions cannot be used on constant strings. -.IP * +.IP \(bu The identity of the delimiting byte is lost. -.IP * +.IP \(bu The .BR strtok () function uses a static buffer while parsing, so it's not thread safe. diff --git a/man3/sysconf.3 b/man3/sysconf.3 index a6df6ebfab..afe1b48b28 100644 --- a/man3/sysconf.3 +++ b/man3/sysconf.3 @@ -310,7 +310,7 @@ See also The return value of .BR sysconf () is one of the following: -.IP * 3 +.IP \(bu 3 On error, \-1 is returned and .I errno is set to indicate the error @@ -319,7 +319,7 @@ is set to indicate the error indicating that .I name is invalid). -.IP * +.IP \(bu If .I name corresponds to a maximum or minimum limit, and that limit is indeterminate, @@ -331,13 +331,13 @@ is not changed. to zero before the call, and then check whether .I errno is nonzero when \-1 is returned.) -.IP * +.IP \(bu If .I name corresponds to an option, a positive value is returned if the option is supported, and \-1 is returned if the option is not supported. -.IP * +.IP \(bu Otherwise, the current value of the option or limit is returned. This value will not be more restrictive than diff --git a/man3/system.3 b/man3/system.3 index 5f9fb55843..ca8de84ae7 100644 --- a/man3/system.3 +++ b/man3/system.3 @@ -61,23 +61,23 @@ returns a status indicating whether a shell is available on the system. The return value of .BR system () is one of the following: -.IP * 3 +.IP \(bu 3 If .I command is NULL, then a nonzero value if a shell is available, or 0 if no shell is available. -.IP * +.IP \(bu If a child process could not be created, or its status could not be retrieved, the return value is \-1 and .I errno is set to indicate the error. -.IP * +.IP \(bu If a shell could not be executed in the child process, then the return value is as though the child shell terminated by calling .BR _exit (2) with the status 127. -.IP * +.IP \(bu If all system calls succeed, then the return value is the termination status of the child shell used to execute diff --git a/man3/termios.3 b/man3/termios.3 index 16a620b0b3..2b9e8c41da 100644 --- a/man3/termios.3 +++ b/man3/termios.3 @@ -701,14 +701,14 @@ By default, is set. .PP In canonical mode: -.IP * 2 +.IP \(bu 3 Input is made available line by line. An input line is available when one of the line delimiters is typed (NL, EOL, EOL2; or EOF at the start of line). Except in the case of EOF, the line delimiter is included in the buffer returned by .BR read (2). -.IP * 2 +.IP \(bu Line editing is enabled (ERASE, KILL; and if the .B IEXTEN @@ -721,7 +721,7 @@ requested fewer bytes than are available in the current line of input, then only as many bytes as requested are read, and the remaining characters will be available for a future .BR read (2). -.IP * 2 +.IP \(bu The maximum line length is 4096 chars (including the terminating newline character); lines longer than 4096 chars are truncated. @@ -785,11 +785,11 @@ the timer is restarted after each further byte is received. .BR read (2) returns when any of the following conditions is met: .RS -.IP * 3 +.IP \(bu 3 MIN bytes have been received. -.IP * +.IP \(bu The interbyte timer expires. -.IP * +.IP \(bu The number of bytes requested by .BR read (2) has been received. diff --git a/man3/wcsnrtombs.3 b/man3/wcsnrtombs.3 index 91f5b0565e..12e2a9337c 100644 --- a/man3/wcsnrtombs.3 +++ b/man3/wcsnrtombs.3 @@ -77,7 +77,7 @@ number of bytes written and .I *src by one. The conversion can stop for three reasons: -.IP 1. 3 +.IP \(bu 3 A wide character has been encountered that can not be represented as a multibyte sequence (according to the current locale). In this case, @@ -89,7 +89,7 @@ and .I errno is set to .BR EILSEQ . -.IP 2. +.IP \(bu .I nwc wide characters have been converted without encountering a null wide character (L\(aq\e0\(aq), @@ -101,7 +101,7 @@ to the next wide character to be converted, and the number of bytes written to .I dest is returned. -.IP 3. +.IP \(bu The wide-character string has been completely converted, including the terminating null wide character (which has the side effect of bringing back .I *ps diff --git a/man3/wcsrtombs.3 b/man3/wcsrtombs.3 index 9c4ab02b95..76b269c060 100644 --- a/man3/wcsrtombs.3 +++ b/man3/wcsrtombs.3 @@ -50,7 +50,7 @@ number of bytes written and .I *src by one. The conversion can stop for three reasons: -.IP 1. 3 +.IP \(bu 3 A wide character has been encountered that can not be represented as a multibyte sequence (according to the current locale). In this case, @@ -62,7 +62,7 @@ and .I errno is set to .BR EILSEQ . -.IP 2. +.IP \(bu The length limit forces a stop. In this case, .I *src @@ -71,7 +71,7 @@ to the next wide character to be converted, and the number of bytes written to .I dest is returned. -.IP 3. +.IP \(bu The wide-character string has been completely converted, including the terminating null wide character (L\(aq\e0\(aq), which has the side effect of bringing back diff --git a/man3/wcstombs.3 b/man3/wcstombs.3 index ccb336b356..ef33936c8d 100644 --- a/man3/wcstombs.3 +++ b/man3/wcstombs.3 @@ -39,18 +39,18 @@ The sequence of characters placed in .I dest begins in the initial shift state. The conversion can stop for three reasons: -.IP 1. 3 +.IP \(bu 3 A wide character has been encountered that can not be represented as a multibyte sequence (according to the current locale). In this case, .I (size_t)\ \-1 is returned. -.IP 2. +.IP \(bu The length limit forces a stop. In this case, the number of bytes written to .I dest is returned, but the shift state at this point is lost. -.IP 3. +.IP \(bu The wide-character string has been completely converted, including the terminating null wide character (L\(aq\e0\(aq). In this case, the conversion ends in the initial shift state. diff --git a/man4/cciss.4 b/man4/cciss.4 index 406c329726..44ddc1c900 100644 --- a/man4/cciss.4 +++ b/man4/cciss.4 @@ -285,10 +285,10 @@ echo "rescan" > /proc/scsi/cciss0/1 .PP This causes the driver to: .RS -.IP 1. 3 +.IP (1) 5 query the adapter about changes to the physical SCSI buses and/or fiber channel arbitrated loop, and -.IP 2. +.IP (2) make note of any new or removed sequential access devices or medium changers. .RE @@ -331,13 +331,13 @@ The .B cciss driver participates in this protocol to some extent. The normal protocol is a four-step process: -.IP * 3 +.IP (1) 5 First, the device is told to abort the command. -.IP * +.IP (2) If that doesn't work, the device is reset. -.IP * +.IP (3) If that doesn't work, the SCSI bus is reset. -.IP * +.IP (4) If that doesn't work, the host bus adapter is reset. .PP The diff --git a/man4/fuse.4 b/man4/fuse.4 index 3eea967e01..2b5385cf5e 100644 --- a/man4/fuse.4 +++ b/man4/fuse.4 @@ -471,11 +471,11 @@ operations on the provided filesystem's files and directories to fail with .BR EIO . Among the possible incorrect uses are: .RS -.IP * 3 +.IP \(bu 3 changing .I mode & S_IFMT for an inode that has previously been reported to the kernel; or -.IP * +.IP \(bu giving replies to the kernel that are shorter than what the kernel expected. .RE .TP diff --git a/man4/initrd.4 b/man4/initrd.4 index 4d85929d4e..b5132404d9 100644 --- a/man4/initrd.4 +++ b/man4/initrd.4 @@ -74,11 +74,11 @@ different device. When booting up with .BR initrd , the system boots as follows: -.IP 1. 3 +.IP (1) 5 The boot loader loads the kernel program and .IR /dev/initrd 's contents into memory. -.IP 2. +.IP (2) On kernel startup, the kernel uncompresses and copies the contents of the device .I /dev/initrd @@ -86,16 +86,16 @@ onto device .I /dev/ram0 and then frees the memory used by .IR /dev/initrd . -.IP 3. +.IP (3) The kernel then read-write mounts the device .I /dev/ram0 as the initial root filesystem. -.IP 4. +.IP (4) If the indicated normal root filesystem is also the initial root filesystem (e.g., .IR /dev/ram0 ) then the kernel skips to the last step for the usual boot sequence. -.IP 5. +.IP (5) If the executable file .I /linuxrc is present in the initial root filesystem, @@ -107,7 +107,7 @@ must have executable permission. The file .I /linuxrc can be any valid executable, including a shell script.) -.IP 6. +.IP (6) If .I /linuxrc is not executed or when @@ -119,7 +119,7 @@ exits with any filesystems mounted on the initial root filesystem, then the behavior of the kernel is .BR UNSPECIFIED . See the NOTES section for the current kernel behavior.) -.IP 7. +.IP (7) If the normal root filesystem has a directory .IR /initrd , the device @@ -150,7 +150,7 @@ when exits, the behavior of the kernel is .BR UNSPECIFIED . See the NOTES section for the current kernel behavior.) -.IP 8. +.IP (8) The usual boot sequence (e.g., invocation of .IR /sbin/init ) is performed on the normal root filesystem. @@ -312,7 +312,7 @@ The main motivation for implementing was to allow for modular kernel configuration at system installation. .PP A possible system installation scenario is as follows: -.IP 1. 3 +.IP (1) 5 The loader program boots from floppy or other media with a minimal kernel (e.g., support for .IR /dev/ram , @@ -320,7 +320,7 @@ The loader program boots from floppy or other media with a minimal kernel and the ext2 filesystem) and loads .I /dev/initrd with a gzipped version of the initial filesystem. -.IP 2. +.IP (2) The executable .I /linuxrc determines what is needed to (1) mount the normal root filesystem @@ -328,17 +328,17 @@ determines what is needed to (1) mount the normal root filesystem distribution media (e.g., CD-ROM, network, tape, ...). This can be done by asking the user, by auto-probing, or by using a hybrid approach. -.IP 3. +.IP (3) The executable .I /linuxrc loads the necessary modules from the initial root filesystem. -.IP 4. +.IP (4) The executable .I /linuxrc creates and populates the root filesystem. (At this stage the normal root filesystem does not have to be a completed system yet.) -.IP 5. +.IP (5) The executable .I /linuxrc sets @@ -347,12 +347,12 @@ unmounts .IR /proc , the normal root filesystem and any other filesystems it has mounted, and then terminates. -.IP 6. +.IP (6) The kernel then mounts the normal root filesystem. -.IP 7. +.IP (7) Now that the filesystem is accessible and intact, the boot loader can be installed. -.IP 8. +.IP (8) The boot loader is configured to load into .I /dev/initrd a filesystem with the set of modules that was used to bring up the system. @@ -361,7 +361,7 @@ a filesystem with the set of modules that was used to bring up the system. can be modified, then unmounted, and finally, the image is written from .I /dev/ram0 to a file.) -.IP 9. +.IP (9) The system is now bootable and additional installation tasks can be performed. .PP @@ -419,7 +419,7 @@ from the CD-ROM. .\" .\" .SH NOTES -.IP 1. 3 +.IP \(bu 3 With the current kernel, any filesystems that remain mounted when .I /dev/ram0 is moved from @@ -430,7 +430,7 @@ continue to be accessible. However, the .I /proc/mounts entries are not updated. -.IP 2. +.IP \(bu With the current kernel, if directory .I /initrd does not exist, then @@ -447,7 +447,7 @@ is fully unmounted, then .I /dev/ram0 will remain in memory. -.IP 3. +.IP \(bu Users of .I /dev/initrd should not depend on the behavior given in the above notes. diff --git a/man4/lirc.4 b/man4/lirc.4 index 57ad344235..d89994cd6d 100644 --- a/man4/lirc.4 +++ b/man4/lirc.4 @@ -259,10 +259,10 @@ is 0) timeout packages in .BR LIRC_MODE_MODE2 . The behavior of this operation has varied across kernel versions: .RS -.IP * 3 +.IP \(bu 3 Since Linux 5.17: timeout packages are always enabled and this ioctl is a no-op. -.IP * +.IP \(bu Since Linux 4.16: timeout packages are enabled by default. Each time the @@ -271,7 +271,7 @@ device is opened, the .B LIRC_SET_REC_TIMEOUT operation can be used to disable (and, if desired, to later re-enable) the timeout on the file descriptor. -.IP * +.IP \(bu In Linux 4.15 and earlier: timeout packages are disabled by default, and enabling them (via .BR LIRC_SET_REC_TIMEOUT ) diff --git a/man4/loop.4 b/man4/loop.4 index bcbf88b318..671648c9bb 100644 --- a/man4/loop.4 +++ b/man4/loop.4 @@ -199,16 +199,16 @@ can do, .B LOOP_CONFIGURE can also be used to do the following: .RS -.IP * 2 +.IP \(bu 3 set the correct block size immediately by setting .IR loop_config.block_size ; -.IP * +.IP \(bu explicitly request direct I/O mode by setting .B LO_FLAGS_DIRECT_IO in .IR loop_config.info.lo_flags ; and -.IP * +.IP \(bu explicitly request read-only mode by setting .B LO_FLAGS_READ_ONLY in diff --git a/man4/rtc.4 b/man4/rtc.4 index 5859eba743..e72c3e7b1e 100644 --- a/man4/rtc.4 +++ b/man4/rtc.4 @@ -66,12 +66,12 @@ requests listed below. .PP Besides tracking the date and time, many RTCs can also generate interrupts -.IP * 3 +.IP \(bu 3 on every clock update (i.e., once per second); -.IP * +.IP \(bu at periodic intervals with a frequency that can be set to any power-of-2 multiple in the range 2 Hz to 8192 Hz; -.IP * +.IP \(bu on reaching a previously specified alarm time. .PP Each of those interrupt sources can be enabled or disabled separately. @@ -31,11 +31,11 @@ where is the number of the physical drive in order of detection, and .I partition_number is as follows: -.IP +3 +.IP \(bu 3 partition 0 is the whole drive -.IP +.IP \(bu partitions 1\(en4 are the DOS "primary" partitions -.IP +.IP \(bu partitions 5\(en8 are the DOS "extended" (or "logical") partitions .PP For example, @@ -886,7 +886,7 @@ the nonrewind SCSI tape devices .\" Several other .\" people have also contributed to the driver. .SH NOTES -.IP 1. 4 +.IP \(bu 3 When exchanging data between systems, both systems have to agree on the physical tape block size. The parameters of a drive after startup @@ -906,26 +906,26 @@ exchanging data with a foreign system. The drawback of this is that a fairly large tape block size has to be used to get acceptable data transfer rates on the SCSI bus. -.IP 2. +.IP \(bu Many programs (e.g., .BR tar (1)) allow the user to specify the blocking factor on the command line. Note that this determines the physical block size on tape only in variable-block mode. -.IP 3. +.IP \(bu In order to use SCSI tape drives, the basic SCSI driver, a SCSI-adapter driver and the SCSI tape driver must be either configured into the kernel or loaded as modules. If the SCSI-tape driver is not present, the drive is recognized but the tape support described in this page is not available. -.IP 4. +.IP \(bu The driver writes error messages to the console/log. The SENSE codes written into some messages are automatically translated to text if verbose SCSI messages are enabled in kernel configuration. -.IP 5. +.IP \(bu The driver's internal buffering allows good throughput in fixed-block mode also with small .BR read (2) diff --git a/man5/core.5 b/man5/core.5 index 73f608abda..2f07107f56 100644 --- a/man5/core.5 +++ b/man5/core.5 @@ -26,7 +26,7 @@ for details. .PP There are various circumstances in which a core dump file is not produced: -.IP * 3 +.IP \(bu 3 The process does not have permission to write the core file. (By default, the core file is called .I core @@ -43,18 +43,18 @@ or if a file with the same name exists and is not writable or is not a regular file (e.g., it is a directory or a symbolic link). -.IP * +.IP \(bu A (writable, regular) file with the same name as would be used for the core dump already exists, but there is more than one hard link to that file. -.IP * +.IP \(bu The filesystem where the core dump file would be created is full; or has run out of inodes; or is mounted read-only; or the user has reached their quota for the filesystem. -.IP * +.IP \(bu The directory in which the core dump file is to be created does not exist. -.IP * +.IP \(bu The .B RLIMIT_CORE (core file size) or @@ -67,14 +67,14 @@ command .RI ( limit in .BR csh (1)). -.IP * +.IP \(bu The binary being executed by the process does not have read permission enabled. (This is a security measure to ensure that an executable whose contents are not readable does not produce a\(empossibly readable\(emcore dump containing an image of the executable.) -.IP * +.IP \(bu The process is executing a set-user-ID (set-group-ID) program that is owned by a user (group) other than the real user (group) ID of the process, @@ -89,7 +89,7 @@ operation, and the description of the .\" and PR_SET_DUMPABLE to this page? file in .BR proc (5).) -.IP * +.IP \(bu .I /proc/sys/kernel/core_pattern is empty and .I /proc/sys/kernel/core_uses_pid @@ -106,7 +106,7 @@ and such files are hidden unless one uses the .BR ls (1) .I \-a option. -.IP * +.IP \(bu (Since Linux 3.7) .\" commit 046d662f481830e652ac34cd112249adde16452a The kernel was configured without the @@ -284,33 +284,33 @@ the executable name. Instead of being written to a file, the core dump is given as standard input to the program. Note the following points: -.IP * 3 +.IP \(bu 3 The program must be specified using an absolute pathname (or a pathname relative to the root directory, \fI/\fP), and must immediately follow the '|' character. -.IP * +.IP \(bu The command-line arguments can include any of the % specifiers listed above. For example, to pass the PID of the process that is being dumped, specify .I %p in an argument. -.IP * +.IP \(bu The process created to run the program runs as user and group .IR root . -.IP * +.IP \(bu Running as .I root does not confer any exceptional security bypasses. Namely, LSMs (e.g., SELinux) are still active and may prevent the handler from accessing details about the crashed process via .IR /proc/ pid. -.IP * +.IP \(bu The program pathname is interpreted with respect to the initial mount namespace as it is always executed there. It is not affected by the settings (e.g., root directory, mount namespace, current working directory) of the crashing process. -.IP * +.IP \(bu The process runs in the initial namespaces (PID, mount, user, and so on) and not in the namespaces of the crashing process. @@ -319,7 +319,7 @@ One can utilize specifiers such as to find the right .IR /proc/ pid directory and probe/enter the crashing process's namespaces if needed. -.IP * +.IP \(bu The process starts with its current working directory as the root directory. If desired, it is possible change to the working directory of @@ -327,11 +327,11 @@ the dumping process by employing the value provided by the .I %P specifier to change to the location of the dumping process via .IR /proc/ pid /cwd . -.IP * +.IP \(bu Command-line arguments can be supplied to the program (since Linux 2.6.24), delimited by white space (up to a total line length of 128 bytes). -.IP * +.IP \(bu The .B RLIMIT_CORE limit is not enforced for core dumps that are piped to a program diff --git a/man5/elf.5 b/man5/elf.5 index bd4192ccee..3deb194c25 100644 --- a/man5/elf.5 +++ b/man5/elf.5 @@ -2079,15 +2079,15 @@ The desc field will be 4 words: .IP .PD 0 .RS -.IP \(bu 2 -word 0: OS descriptor +.IP [0] 5 +OS descriptor (\fBELF_NOTE_OS_LINUX\fR, \fBELF_NOTE_OS_GNU\fR, and so on)` -.IP \(bu -word 1: major version of the ABI -.IP \(bu -word 2: minor version of the ABI -.IP \(bu -word 3: subminor version of the ABI +.IP [1] +major version of the ABI +.IP [2] +minor version of the ABI +.IP [3] +subminor version of the ABI .RE .PD .TP @@ -2097,10 +2097,10 @@ The desc field begins with two words: .IP .PD 0 .RS -.IP \(bu 2 -word 0: number of entries -.IP \(bu -word 1: bit mask of enabled entries +.IP [0] 5 +number of entries +.IP [1] +bit mask of enabled entries .RE .PD .IP diff --git a/man5/locale.5 b/man5/locale.5 index 14d0319764..9ba120e450 100644 --- a/man5/locale.5 +++ b/man5/locale.5 @@ -58,32 +58,32 @@ provided locale definition file should be used as a reference to follow common glibc conventions. .SS Locale category sections The following category sections are defined by POSIX: -.IP * 3 +.IP \(bu 3 .B LC_CTYPE -.IP * +.IP \(bu .B LC_COLLATE -.IP * +.IP \(bu .B LC_MESSAGES -.IP * +.IP \(bu .B LC_MONETARY -.IP * +.IP \(bu .B LC_NUMERIC -.IP * +.IP \(bu .B LC_TIME .PP In addition, since version 2.2, the GNU C library supports the following nonstandard categories: -.IP * 3 +.IP \(bu 3 .B LC_ADDRESS -.IP * +.IP \(bu .B LC_IDENTIFICATION -.IP * +.IP \(bu .B LC_MEASUREMENT -.IP * +.IP \(bu .B LC_NAME -.IP * +.IP \(bu .B LC_PAPER -.IP * +.IP \(bu .B LC_TELEPHONE .PP See @@ -600,11 +600,11 @@ In addition, for each of the categories defined by the document, there should be a line starting with the keyword .IR category , followed by: -.IP * 3 +.IP (1) 5 a string that identifies this locale category definition, -.IP * +.IP (2) a semicolon, and -.IP * +.IP (3) one of the .B LC_* identifiers. @@ -1262,7 +1262,7 @@ and states at https://sourceware.org/glibc/wiki/Locales the following: -.IP * 3 +.IP \(bu 3 The value of the second .I week list item specifies the base of the @@ -1270,14 +1270,14 @@ list item specifies the base of the and .I day lists. -.IP * +.IP \(bu .I first_weekday specifies the offset of the first day-of-week in the .I abday and .I day lists. -.IP * +.IP \(bu For compatibility reasons, all glibc locales should set the value of the second .I week diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5 index bc2b2d7c9e..10208f8e3b 100644 --- a/man5/nscd.conf.5 +++ b/man5/nscd.conf.5 @@ -299,7 +299,7 @@ the value of the attribute. .PP Please consider the following advice carefully: -.IP \(bu +.IP \(bu 3 If your application will make a second request for the same name, after more than 1 TTL but before .B reload\-count diff --git a/man5/nsswitch.conf.5 b/man5/nsswitch.conf.5 index 12d71c8bed..098585cf10 100644 --- a/man5/nsswitch.conf.5 +++ b/man5/nsswitch.conf.5 @@ -122,11 +122,11 @@ services: nis [NOTFOUND=return] files .PP The first column is the database name. The remaining columns specify: -.IP * 3 +.IP \(bu 3 One or more service specifications, for example, "files", "db", or "nis". The order of the services on the line determines the order in which those services will be queried, in turn, until a result is found. -.IP * +.IP \(bu Optional actions to perform if a particular result is obtained from the preceding service, for example, "[NOTFOUND=return]". .PP diff --git a/man5/proc.5 b/man5/proc.5 index b7d48f840d..1217cea897 100644 --- a/man5/proc.5 +++ b/man5/proc.5 @@ -244,12 +244,12 @@ things work as expected for the container "root" user. .IP The process's "dumpable" attribute may change for the following reasons: .RS -.IP * 3 +.IP \(bu 3 The attribute was explicitly set via the .BR prctl (2) .B PR_SET_DUMPABLE operation. -.IP * +.IP \(bu The attribute was reset to the value in the file .I /proc/sys/fs/suid_dumpable (described below), for the reasons described in @@ -1638,7 +1638,7 @@ with increases (+) or decreases (\-) for factors including: .\" See mm/oom_kill.c::oom_badness() after 2.6.36 .\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 .RS -.IP * 2 +.IP \(bu 3 whether the process is privileged (\-). .\" More precisely, if it has CAP_SYS_ADMIN or (pre 2.6.36) CAP_SYS_RESOURCE .RE @@ -1646,16 +1646,16 @@ whether the process is privileged (\-). Before kernel 2.6.36 the following factors were also used in the calculation of oom_score: .RS -.IP * 2 +.IP \(bu 3 whether the process creates a lot of children using .BR fork (2) (+); -.IP * +.IP \(bu whether the process has been running a long time, or has used a lot of CPU time (\-); -.IP * +.IP \(bu whether the process has a low nice value (i.e., > 0) (+); and -.IP * +.IP \(bu whether the process is making direct hardware access (\-). .\" More precisely, if it has CAP_SYS_RAWIO .RE @@ -3444,9 +3444,9 @@ An example of the content shown in this file is the following: .IP The fields shown in each line are as follows: .RS -.IP (1) 4 +.IP [1] 5 The ordinal position of the lock in the list. -.IP (2) +.IP [2] The lock type. Values that may appear here include: .RS @@ -3463,7 +3463,7 @@ This is an open file description (OFD) lock created using This is a POSIX byte-range lock created using .BR fcntl (2). .RE -.IP (3) +.IP [3] Among the strings that can appear here are the following: .RS .TP @@ -3473,7 +3473,7 @@ This is an advisory lock. .B MANDATORY This is a mandatory lock. .RE -.IP (4) +.IP [4] The type of lock. Values that can appear here are: .RS @@ -3484,7 +3484,7 @@ This is a POSIX or OFD read lock, or a BSD shared lock. .B WRITE This is a POSIX or OFD write lock, or a BSD exclusive lock. .RE -.IP (5) +.IP [5] The PID of the process that owns the lock. .IP Because OFD locks are not owned by a single process @@ -3495,14 +3495,14 @@ the value \-1 is displayed in this field for OFD locks. .\" commit 9d5b86ac13c573795525ecac6ed2db39ab23e2a8 a bug meant that the PID of the process that initially acquired the lock was displayed instead of the value \-1.) -.IP (6) +.IP [6] Three colon-separated subfields that identify the major and minor device ID of the device containing the filesystem where the locked file resides, followed by the inode number of the locked file. -.IP (7) +.IP [7] The byte offset of the first byte of the lock. For BSD locks, this value is always 0. -.IP (8) +.IP [8] The byte offset of the last byte of the lock. .B EOF in this field means that the lock extends to the end of the file. @@ -4301,16 +4301,16 @@ pseudo-file. This value is not reliable, for the following reasons: .\" See kernel commit 9c240d757658a3ae9968dd309e674c61f07c7f48 .RS -.IP 1. 3 +.IP \(bu 3 The CPU will not wait for I/O to complete; iowait is the time that a task is waiting for I/O to complete. When a CPU goes into idle state for outstanding task I/O, another task will be scheduled on this CPU. -.IP 2. +.IP \(bu On a multi-core CPU, the task waiting for I/O to complete is not running on any CPU, so the iowait of each CPU is difficult to calculate. -.IP 3. +.IP \(bu The value in this field may .I decrease in certain conditions. @@ -4469,19 +4469,19 @@ The file contains six numbers, .I want_pages (pages requested by system) and two dummy values. .RS -.IP * 2 +.IP \(bu 3 .I nr_dentry is the number of allocated dentries (dcache entries). This field is unused in Linux 2.2. -.IP * +.IP \(bu .I nr_unused is the number of unused dentries. -.IP * +.IP \(bu .I age_limit .\" looks like this is unused in kernels 2.2 to 2.6 is the age in seconds after which dcache entries can be reclaimed when memory is short. -.IP * +.IP \(bu .I want_pages .\" looks like this is unused in kernels 2.2 to 2.6 is nonzero when the kernel has called shrink_dcache_pages() and the @@ -4710,18 +4710,18 @@ When the value in this file is 1, a hard link can be created to a target file only if one of the following conditions is true: .RS -.IP * 3 +.IP \(bu 3 The calling process has the .B CAP_FOWNER capability in its user namespace and the file UID has a mapping in the namespace. -.IP * +.IP \(bu The filesystem UID of the process creating the link matches the owner (UID) of the target file (as described in .BR credentials (7), a process's filesystem UID is normally the same as its effective UID). -.IP * +.IP \(bu All of the following conditions are true: .RS 4 .IP \(bu 3 @@ -4786,15 +4786,15 @@ no restrictions are placed on following symbolic links When the value in this file is 1, symbolic links are followed only in the following circumstances: .RS -.IP * 3 +.IP \(bu 3 the filesystem UID of the process following the link matches the owner (UID) of the symbolic link (as described in .BR credentials (7), a process's filesystem UID is normally the same as its effective UID); -.IP * +.IP \(bu the link is not in a sticky world-writable directory; or -.IP * +.IP \(bu the symbolic link and its parent directory have the same owner (UID) .RE .IP @@ -5874,19 +5874,19 @@ CommitLimit = (total_RAM \- total_huge_TLB) * .in .IP where: -.RS 12 -.IP * 3 +.RS +.IP \(bu 3 .I total_RAM is the total amount of RAM on the system; -.IP * +.IP \(bu .I total_huge_TLB is the amount of memory set aside for huge pages; -.IP * +.IP \(bu .I overcommit_ratio is the value in .IR /proc/sys/vm/overcommit_ratio ; and -.IP * +.IP \(bu .I total_swap is the amount of swap space. .RE @@ -6127,18 +6127,17 @@ Collection: active .IP The output columns are: .RS -.IP * 3 +.IP [1] 5 a count of the number of events, optionally (since Linux 2.6.23) followed by the letter \(aqD\(aq .\" commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers if this is a deferrable timer; -.IP * +.IP [2] the PID of the process that initialized the timer; -.IP * +.IP [3] the name of the process that initialized the timer; -.IP * +.IP [4] the function where the timer was initialized; and -.IP * (in parentheses) the callback function that is associated with the timer. .RE diff --git a/man5/slabinfo.5 b/man5/slabinfo.5 index 1a7a3b51a4..e8cfac73aa 100644 --- a/man5/slabinfo.5 +++ b/man5/slabinfo.5 @@ -39,11 +39,11 @@ The next line lists the names of the columns in the remaining lines. Each of the remaining lines displays information about a specified cache. Following the cache name, the output shown in each line shows three components for each cache: -.IP * 3 +.IP \(bu 3 statistics -.IP * +.IP \(bu tunables -.IP * +.IP \(bu slabdata .PP The statistics are as follows: diff --git a/man5/tmpfs.5 b/man5/tmpfs.5 index 45ba9bd59a..f914a19120 100644 --- a/man5/tmpfs.5 +++ b/man5/tmpfs.5 @@ -27,13 +27,13 @@ $ sudo mount \-t tmpfs \-o size=10M tmpfs /mnt/mytmpfs A .B tmpfs filesystem has the following properties: -.IP * 3 +.IP \(bu 3 The filesystem can employ swap space when physical memory pressure demands it. -.IP * +.IP \(bu The filesystem consumes only as much physical memory and swap space as is required to store the current contents of the filesystem. -.IP * +.IP \(bu During a remount operation .RI ( "mount\ \-o\ remount" ), the filesystem size can be changed diff --git a/man7/boot.7 b/man7/boot.7 index 9b4e0171a9..b9a25cb539 100644 --- a/man7/boot.7 +++ b/man7/boot.7 @@ -17,15 +17,15 @@ boot \- System bootup process based on UNIX System V Release 4 The \fBbootup process\fR (or "\fBboot sequence\fR") varies in details among systems, but can be roughly divided into phases controlled by the following components: -.IP 1. 4 +.IP (1) 5 hardware -.IP 2. 4 +.IP (2) operating system (OS) loader -.IP 3. 4 +.IP (3) kernel -.IP 4. 4 +.IP (4) root user-space process (\fIinit\fR and \fIinittab\fR) -.IP 5. 4 +.IP (5) boot scripts .PP Each of these is described below in more detail. diff --git a/man7/capabilities.7 b/man7/capabilities.7 index 921ff5ebe4..d85c62f463 100644 --- a/man7/capabilities.7 +++ b/man7/capabilities.7 @@ -85,12 +85,12 @@ capability. .\" commit 124ea650d3072b005457faed69909221c2905a1f .PD 0 .RS -.IP * 2 +.IP \(bu 3 Update .I /proc/sys/kernel/ns_last_pid (see .BR pid_namespaces (7)); -.IP * +.IP \(bu employ the .I set_tid feature of @@ -98,7 +98,7 @@ feature of .\" FIXME There is also some use case relating to .\" prctl_set_mm_exe_file(); in the 5.9 sources, see .\" prctl_set_mm_map(). -.IP * +.IP \(bu read the contents of the symbolic links in .IR /proc/ pid /map_files for other processes. @@ -121,13 +121,13 @@ Bypass file read, write, and execute permission checks. .B CAP_DAC_READ_SEARCH .PD 0 .RS -.IP * 2 +.IP \(bu 3 Bypass file read permission checks and directory read and execute permission checks; -.IP * +.IP \(bu invoke .BR open_by_handle_at (2); -.IP * +.IP \(bu use the .BR linkat (2) .B AT_EMPTY_PATH @@ -138,7 +138,7 @@ flag to create a link to a file referred to by a file descriptor. .B CAP_FOWNER .PD 0 .RS -.IP * 2 +.IP \(bu 3 Bypass permission checks on operations that normally require the filesystem UID of the process to match the UID of the file (e.g., @@ -148,19 +148,19 @@ excluding those operations covered by .B CAP_DAC_OVERRIDE and .BR CAP_DAC_READ_SEARCH ; -.IP * +.IP \(bu set inode flags (see .BR ioctl_iflags (2)) on arbitrary files; -.IP * +.IP \(bu set Access Control Lists (ACLs) on arbitrary files; -.IP * +.IP \(bu ignore directory sticky bit on file deletion; -.IP * +.IP \(bu modify .I user extended attributes on sticky directory owned by any user; -.IP * +.IP \(bu specify .B O_NOATIME for arbitrary files in @@ -173,10 +173,10 @@ and .B CAP_FSETID .PD 0 .RS -.IP * 2 +.IP \(bu 3 Don't clear set-user-ID and set-group-ID mode bits when a file is modified; -.IP * +.IP \(bu set the set-group-ID bit for a file whose GID does not match the filesystem or any of the supplementary GIDs of the calling process. .RE @@ -187,13 +187,13 @@ the filesystem or any of the supplementary GIDs of the calling process. .\" in other places; they probably should be replaced with something else. .PD 0 .RS -.IP * 2 +.IP \(bu 3 Lock memory .RB ( mlock (2), .BR mlockall (2), .BR mmap (2), .BR shmctl (2)); -.IP * +.IP \(bu Allocate memory using huge pages .RB ( memfd_create (2), .BR mmap (2), @@ -245,23 +245,23 @@ Create special files using Perform various network-related operations: .PD 0 .RS -.IP * 2 +.IP \(bu 3 interface configuration; -.IP * +.IP \(bu administration of IP firewall, masquerading, and accounting; -.IP * +.IP \(bu modify routing tables; -.IP * +.IP \(bu bind to any address for transparent proxying; -.IP * +.IP \(bu set type-of-service (TOS); -.IP * +.IP \(bu clear driver statistics; -.IP * +.IP \(bu set promiscuous mode; -.IP * +.IP \(bu enabling multicasting; -.IP * +.IP \(bu use .BR setsockopt (2) to set the following socket options: @@ -287,9 +287,9 @@ Bind a socket to Internet domain privileged ports .B CAP_NET_RAW .PD 0 .RS -.IP * 2 +.IP \(bu 3 Use RAW and PACKET sockets; -.IP * +.IP \(bu bind to any address for transparent proxying. .RE .PD @@ -298,11 +298,11 @@ bind to any address for transparent proxying. .BR CAP_PERFMON " (since Linux 5.8)" Employ various performance-monitoring mechanisms, including: .RS -.IP * 2 +.IP \(bu 3 .PD 0 call .BR perf_event_open (2); -.IP * +.IP \(bu employ various BPF operations that have performance implications. .RE .PD @@ -317,11 +317,11 @@ See also the kernel source file .B CAP_SETGID .RS .PD 0 -.IP * 2 +.IP \(bu 3 Make arbitrary manipulations of process GIDs and supplementary GID list; -.IP * +.IP \(bu forge GID when passing socket credentials via UNIX domain sockets; -.IP * +.IP \(bu write a group ID mapping in a user namespace (see .BR user_namespaces (7)). .PD @@ -360,15 +360,15 @@ has entirely different semantics for such kernels.) .B CAP_SETUID .RS .PD 0 -.IP * 2 +.IP \(bu 3 Make arbitrary manipulations of process UIDs .RB ( setuid (2), .BR setreuid (2), .BR setresuid (2), .BR setfsuid (2)); -.IP * +.IP \(bu forge UID when passing socket credentials via UNIX domain sockets; -.IP * +.IP \(bu write a user ID mapping in a user namespace (see .BR user_namespaces (7)). .PD @@ -383,7 +383,7 @@ below. .IP .PD 0 .RS -.IP * 2 +.IP \(bu 3 Perform a range of system administration operations including: .BR quotactl (2), .BR mount (2), @@ -394,53 +394,53 @@ Perform a range of system administration operations including: .BR sethostname (2), and .BR setdomainname (2); -.IP * +.IP \(bu perform privileged .BR syslog (2) operations (since Linux 2.6.37, .B CAP_SYSLOG should be used to permit such operations); -.IP * +.IP \(bu perform .B VM86_REQUEST_IRQ .BR vm86 (2) command; -.IP * +.IP \(bu access the same checkpoint/restore functionality that is governed by .B CAP_CHECKPOINT_RESTORE (but the latter, weaker capability is preferred for accessing that functionality). -.IP * +.IP \(bu perform the same BPF operations as are governed by .B CAP_BPF (but the latter, weaker capability is preferred for accessing that functionality). -.IP * +.IP \(bu employ the same performance monitoring mechanisms as are governed by .B CAP_PERFMON (but the latter, weaker capability is preferred for accessing that functionality). -.IP * +.IP \(bu perform .B IPC_SET and .B IPC_RMID operations on arbitrary System V IPC objects; -.IP * +.IP \(bu override .B RLIMIT_NPROC resource limit; -.IP * +.IP \(bu perform operations on .I trusted and .I security extended attributes (see .BR xattr (7)); -.IP * +.IP \(bu use .BR lookup_dcookie (2); -.IP * +.IP \(bu use .BR ioprio_set (2) to assign @@ -448,9 +448,9 @@ to assign and (before Linux 2.6.25) .B IOPRIO_CLASS_IDLE I/O scheduling classes; -.IP * +.IP \(bu forge PID when passing socket credentials via UNIX domain sockets; -.IP * +.IP \(bu exceed .IR /proc/sys/fs/file\-max , the system-wide limit on the number of open files, @@ -459,7 +459,7 @@ in system calls that open files (e.g., .BR execve (2), .BR open (2), .BR pipe (2)); -.IP * +.IP \(bu employ .B CLONE_* flags that create new namespaces with @@ -468,11 +468,11 @@ and .BR unshare (2) (but, since Linux 3.8, creating user namespaces does not require any capability); -.IP * +.IP \(bu access privileged .I perf event information; -.IP * +.IP \(bu call .BR setns (2) (requires @@ -480,73 +480,73 @@ call in the .I target namespace); -.IP * +.IP \(bu call .BR fanotify_init (2); -.IP * +.IP \(bu perform privileged .B KEYCTL_CHOWN and .B KEYCTL_SETPERM .BR keyctl (2) operations; -.IP * +.IP \(bu perform .BR madvise (2) .B MADV_HWPOISON operation; -.IP * +.IP \(bu employ the .B TIOCSTI .BR ioctl (2) to insert characters into the input queue of a terminal other than the caller's controlling terminal; -.IP * +.IP \(bu employ the obsolete .BR nfsservctl (2) system call; -.IP * +.IP \(bu employ the obsolete .BR bdflush (2) system call; -.IP * +.IP \(bu perform various privileged block-device .BR ioctl (2) operations; -.IP * +.IP \(bu perform various privileged filesystem .BR ioctl (2) operations; -.IP * +.IP \(bu perform privileged .BR ioctl (2) operations on the .I /dev/random device (see .BR random (4)); -.IP * +.IP \(bu install a .BR seccomp (2) filter without first having to set the .I no_new_privs thread attribute; -.IP * +.IP \(bu modify allow/deny rules for device control groups; -.IP * +.IP \(bu employ the .BR ptrace (2) .B PTRACE_SECCOMP_GET_FILTER operation to dump tracee's seccomp filters; -.IP * +.IP \(bu employ the .BR ptrace (2) .B PTRACE_SETOPTIONS operation to suspend the tracee's seccomp protections (i.e., the .B PTRACE_O_SUSPEND_SECCOMP flag); -.IP * +.IP \(bu perform administrative operations on many device drivers; -.IP * +.IP \(bu modify autogroup nice values by writing to .IR /proc/ pid /autogroup (see @@ -563,10 +563,10 @@ and .B CAP_SYS_CHROOT .RS .PD 0 -.IP * 2 +.IP \(bu 3 Use .BR chroot (2); -.IP * +.IP \(bu change mount namespaces using .BR setns (2). .PD @@ -575,13 +575,13 @@ change mount namespaces using .B CAP_SYS_MODULE .RS .PD 0 -.IP * 2 +.IP \(bu 3 Load and unload kernel modules (see .BR init_module (2) and .BR delete_module (2)); -.IP * +.IP \(bu in kernels before 2.6.25: drop capabilities from the system-wide capability bounding set. .PD @@ -590,24 +590,24 @@ drop capabilities from the system-wide capability bounding set. .B CAP_SYS_NICE .PD 0 .RS -.IP * 2 +.IP \(bu 3 Lower the process nice value .RB ( nice (2), .BR setpriority (2)) and change the nice value for arbitrary processes; -.IP * +.IP \(bu set real-time scheduling policies for calling process, and set scheduling policies and priorities for arbitrary processes .RB ( sched_setscheduler (2), .BR sched_setparam (2), .BR sched_setattr (2)); -.IP * +.IP \(bu set CPU affinity for arbitrary processes .RB ( sched_setaffinity (2)); -.IP * +.IP \(bu set I/O scheduling class and priority for arbitrary processes .RB ( ioprio_set (2)); -.IP * +.IP \(bu apply .BR migrate_pages (2) to arbitrary processes and allow processes @@ -618,11 +618,11 @@ to be migrated to arbitrary nodes; .\" capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE); .\" .\" Document this. -.IP * +.IP \(bu apply .BR move_pages (2) to arbitrary processes; -.IP * +.IP \(bu use the .B MPOL_MF_MOVE_ALL flag with @@ -639,19 +639,19 @@ Use .B CAP_SYS_PTRACE .PD 0 .RS -.IP * 2 +.IP \(bu 3 Trace arbitrary processes using .BR ptrace (2); -.IP * +.IP \(bu apply .BR get_robust_list (2) to arbitrary processes; -.IP * +.IP \(bu transfer data to or from the memory of arbitrary processes using .BR process_vm_readv (2) and .BR process_vm_writev (2); -.IP * +.IP \(bu inspect processes using .BR kcmp (2). .RE @@ -660,45 +660,45 @@ inspect processes using .B CAP_SYS_RAWIO .PD 0 .RS -.IP * 2 +.IP \(bu 3 Perform I/O port operations .RB ( iopl (2) and .BR ioperm (2)); -.IP * +.IP \(bu access .IR /proc/kcore ; -.IP * +.IP \(bu employ the .B FIBMAP .BR ioctl (2) operation; -.IP * +.IP \(bu open devices for accessing x86 model-specific registers (MSRs, see .BR msr (4)); -.IP * +.IP \(bu update .IR /proc/sys/vm/mmap_min_addr ; -.IP * +.IP \(bu create memory mappings at addresses below the value specified by .IR /proc/sys/vm/mmap_min_addr ; -.IP * +.IP \(bu map files in .IR /proc/bus/pci ; -.IP * +.IP \(bu open .I /dev/mem and .IR /dev/kmem ; -.IP * +.IP \(bu perform various SCSI device commands; -.IP * +.IP \(bu perform certain operations on .BR hpsa (4) and .BR cciss (4) devices; -.IP * +.IP \(bu perform a range of device-specific operations on other devices. .RE .PD @@ -706,28 +706,28 @@ perform a range of device-specific operations on other devices. .B CAP_SYS_RESOURCE .PD 0 .RS -.IP * 2 +.IP \(bu 3 Use reserved space on ext2 filesystems; -.IP * +.IP \(bu make .BR ioctl (2) calls controlling ext3 journaling; -.IP * +.IP \(bu override disk quota limits; -.IP * +.IP \(bu increase resource limits (see .BR setrlimit (2)); -.IP * +.IP \(bu override .B RLIMIT_NPROC resource limit; -.IP * +.IP \(bu override maximum number of consoles on console allocation; -.IP * +.IP \(bu override maximum number of keymaps; -.IP * +.IP \(bu allow more than 64hz interrupts from the real-time clock; -.IP * +.IP \(bu raise .I msg_qbytes limit for a System V message queue above the limit in @@ -736,26 +736,26 @@ limit for a System V message queue above the limit in .BR msgop (2) and .BR msgctl (2)); -.IP * +.IP \(bu allow the .B RLIMIT_NOFILE resource limit on the number of "in-flight" file descriptors to be bypassed when passing file descriptors to another process via a UNIX domain socket (see .BR unix (7)); -.IP * +.IP \(bu override the .I /proc/sys/fs/pipe\-size\-max limit when setting the capacity of a pipe using the .B F_SETPIPE_SZ .BR fcntl (2) command; -.IP * +.IP \(bu use .B F_SETPIPE_SZ to increase the capacity of a pipe above the limit specified by .IR /proc/sys/fs/pipe\-max\-size ; -.IP * +.IP \(bu override .IR /proc/sys/fs/mqueue/queues_max , .IR /proc/sys/fs/mqueue/msg_max , @@ -763,12 +763,12 @@ and .I /proc/sys/fs/mqueue/msgsize_max limits when creating POSIX message queues (see .BR mq_overview (7)); -.IP * +.IP \(bu employ the .BR prctl (2) .B PR_SET_MM operation; -.IP * +.IP \(bu set .IR /proc/ pid /oom_score_adj to a value lower than the value last set by a process with @@ -793,14 +793,14 @@ operations on virtual terminals. .BR CAP_SYSLOG " (since Linux 2.6.37)" .RS .PD 0 -.IP * 2 +.IP \(bu 3 Perform privileged .BR syslog (2) operations. See .BR syslog (2) for information on which operations require privilege. -.IP * +.IP \(bu View kernel addresses exposed via .I /proc and other interfaces when @@ -822,14 +822,14 @@ timers). .\" .SS Past and current implementation A full implementation of capabilities requires that: -.IP 1. 3 +.IP \(bu 3 For all privileged operations, the kernel must check whether the thread has the required capability in its effective set. -.IP 2. +.IP \(bu The kernel must provide system calls allowing a thread's capability sets to be changed and retrieved. -.IP 3. +.IP \(bu The filesystem must support attaching capabilities to an executable file, so that a process gains those capabilities when the file is executed. .PP @@ -839,12 +839,12 @@ since kernel 2.6.24, all three requirements are met. .SS Notes to kernel developers When adding a new kernel feature that should be governed by a capability, consider the following points. -.IP * 3 +.IP \(bu 3 The goal of capabilities is divide the power of superuser into pieces, such that if a program that has one or more capabilities is compromised, its power to do damage to the system would be less than the same program running with root privilege. -.IP * +.IP \(bu You have the choice of either creating a new capability for your new feature, or associating the feature with one of the existing capabilities. In order to keep the set of capabilities to a manageable size, @@ -852,7 +852,7 @@ the latter option is preferable, unless there are compelling reasons to take the former option. (There is also a technical limit: the size of capability sets is currently limited to 64 bits.) -.IP * +.IP \(bu To determine which existing capability might best be associated with your new feature, review the list of capabilities above in order to find a "silo" into which your new feature best fits. @@ -860,7 +860,7 @@ One approach to take is to determine if there are other features requiring capabilities that will always be used along with the new feature. If the new feature is useless without these other features, you should use the same capability as the other features. -.IP * +.IP \(bu .I Don't choose .B CAP_SYS_ADMIN @@ -878,7 +878,7 @@ The only new features that should be associated with are ones that .I closely match existing uses in that silo. -.IP * +.IP \(bu If you have determined that it really is necessary to create a new capability for your feature, don't make or name it as a "single-use" capability. @@ -1102,11 +1102,11 @@ extended attribute is automatically created as (or converted to) a version 3 .RB ( VFS_CAP_REVISION_3 ) attribute if both of the following are true: -.IP (1) 4 +.IP \(bu 3 The thread writing the attribute resides in a noninitial user namespace. (More precisely: the thread resides in a user namespace other than the one from which the underlying filesystem was mounted.) -.IP (2) +.IP \(bu The thread has the .B CAP_SETFCAP capability over the file inode, @@ -1209,13 +1209,13 @@ denotes a file capability set .PP Note the following details relating to the above capability transformation rules: -.IP * 3 +.IP \(bu 3 The ambient capability set is present only since Linux 4.3. When determining the transformation of the ambient set during .BR execve (2), a privileged file is one that has capabilities or has the set-user-ID or set-group-ID bit set. -.IP * +.IP \(bu Prior to Linux 2.6.25, the bounding set was a system-wide attribute shared by all threads. That system-wide value was employed to calculate the new permitted set during @@ -1294,7 +1294,7 @@ were triggered by the set-user-ID mode bit of the binary\(eme.g., switching the effective user ID to 0 (root) because a set-user-ID-root program was executed\(emthe kernel calculates the file capability sets as follows: -.IP 1. 3 +.IP (1) 5 If the real or effective user ID of the process is 0 (root), then the file inheritable and permitted sets are ignored; instead they are notionally considered to be all ones @@ -1302,7 +1302,7 @@ instead they are notionally considered to be all ones (There is one exception to this behavior, described in .I Set-user-ID-root programs that have file capabilities below.) -.IP 2. +.IP (2) If the effective user ID of the process is 0 (root) or the file effective bit is in fact enabled, then the file effective bit is notionally defined to be one (enabled). @@ -1370,7 +1370,7 @@ The capability bounding set is a security mechanism that can be used to limit the capabilities that can be gained during an .BR execve (2). The bounding set is used in the following ways: -.IP * 2 +.IP \(bu 3 During an .BR execve (2), the capability bounding set is ANDed with the file permitted @@ -1378,7 +1378,7 @@ capability set, and the result of this operation is assigned to the thread's permitted capability set. The capability bounding set thus places a limit on the permitted capabilities that may be granted by an executable file. -.IP * +.IP \(bu (Since Linux 2.6.25) The capability bounding set acts as a limiting superset for the capabilities that a thread can add to its inheritable set using @@ -1491,19 +1491,19 @@ and filesystem user IDs (using .BR setuid (2), .BR setresuid (2), or similar): -.IP 1. 3 +.IP \(bu 3 If one or more of the real, effective, or saved set user IDs was previously 0, and as a result of the UID changes all of these IDs have a nonzero value, then all capabilities are cleared from the permitted, effective, and ambient capability sets. -.IP 2. +.IP \(bu If the effective user ID is changed from 0 to nonzero, then all capabilities are cleared from the effective set. -.IP 3. +.IP \(bu If the effective user ID is changed from nonzero to 0, then the permitted set is copied to the effective set. -.IP 4. +.IP \(bu If the filesystem user ID is changed from 0 to nonzero (see .BR setfsuid (2)), then the following capabilities are cleared from the effective set: @@ -1544,21 +1544,21 @@ both provided in the package, is preferred for this purpose. The following rules govern changes to the thread capability sets: -.IP 1. 3 +.IP \(bu 3 If the caller does not have the .B CAP_SETPCAP capability, the new inheritable set must be a subset of the combination of the existing inheritable and permitted sets. -.IP 2. +.IP \(bu (Since Linux 2.6.25) The new inheritable set must be a subset of the combination of the existing inheritable set and the capability bounding set. -.IP 3. +.IP \(bu The new permitted set must be a subset of the existing permitted set (i.e., it is not possible to acquire permitted capabilities that the thread does not currently have). -.IP 4. +.IP \(bu The new effective set must be a subset of the new permitted set. .SS The securebits flags: establishing a capabilities-only environment .\" For some background: @@ -1824,14 +1824,14 @@ However, this is only theoretically possible, since no thread ever has .B CAP_SETPCAP in either of these cases: -.IP * 2 +.IP \(bu 3 In the pre-2.6.25 implementation the system-wide capability bounding set, .IR /proc/sys/kernel/cap\-bound , always masks out the .B CAP_SETPCAP capability, and this can not be changed without modifying the kernel source and rebuilding the kernel. -.IP * +.IP \(bu If file capabilities are disabled (i.e., the kernel .B CONFIG_SECURITY_FILE_CAPABILITIES option is disabled), then diff --git a/man7/cgroup_namespaces.7 b/man7/cgroup_namespaces.7 index 134c2e6e0a..96960f53b8 100644 --- a/man7/cgroup_namespaces.7 +++ b/man7/cgroup_namespaces.7 @@ -168,13 +168,13 @@ Use of cgroup namespaces requires a kernel that is configured with the option. .PP The virtualization provided by cgroup namespaces serves a number of purposes: -.IP * 2 +.IP \(bu 3 It prevents information leaks whereby cgroup directory paths outside of a container would otherwise be visible to processes in the container. Such leakages could, for example, reveal information about the container framework to containerized applications. -.IP * +.IP \(bu It eases tasks such as container migration. The virtualization provided by cgroup namespaces allows containers to be isolated from knowledge of @@ -184,13 +184,13 @@ Without such isolation, the full cgroup pathnames (displayed in would need to be replicated on the target system when migrating a container; those pathnames would also need to be unique, so that they don't conflict with other pathnames on the target system. -.IP * +.IP \(bu It allows better confinement of containerized processes, because it is possible to mount the container's cgroup filesystems such that the container processes can't gain access to ancestor cgroup directories. Consider, for example, the following scenario: -.RS 4 -.IP \(bu 2 +.RS +.IP \(bu 3 We have a cgroup directory, .IR /cg/1 , that is owned by user ID 9000. diff --git a/man7/cgroups.7 b/man7/cgroups.7 index 6f6ac289c5..26a82f80f3 100644 --- a/man7/cgroups.7 +++ b/man7/cgroups.7 @@ -559,20 +559,20 @@ under both the v1 and the v2 hierarchies. .PP The new behaviors in cgroups v2 are summarized here, and in some cases elaborated in the following subsections. -.IP 1. 3 +.IP \(bu 3 Cgroups v2 provides a unified hierarchy against which all controllers are mounted. -.IP 2. +.IP \(bu "Internal" processes are not permitted. With the exception of the root cgroup, processes may reside only in leaf nodes (cgroups that do not themselves contain child cgroups). The details are somewhat more subtle than this, and are described below. -.IP 3. +.IP \(bu Active cgroups must be specified via the files .I cgroup.controllers and .IR cgroup.subtree_control . -.IP 4. +.IP \(bu The .I tasks file has been removed. @@ -581,7 +581,7 @@ In addition, the file that is employed by the .I cpuset controller has been removed. -.IP 5. +.IP \(bu An improved mechanism for notification of empty cgroups is provided by the .I cgroup.events file. @@ -920,14 +920,14 @@ The cgroups v2 release-notification mechanism offers the following advantages over the cgroups v1 .I release_agent mechanism: -.IP * 3 +.IP \(bu 3 It allows for cheaper notification, since a single process can monitor multiple .I cgroup.events files (using the techniques described earlier). By contrast, the cgroups v1 mechanism requires the expense of creating a process for each notification. -.IP * +.IP \(bu Notification for different cgroup subhierarchies can be delegated to different processes. By contrast, the cgroups v1 mechanism allows only one release agent @@ -1114,7 +1114,7 @@ The effect of this mount option is to cause cgroup namespaces to automatically become delegation boundaries. More specifically, the following restrictions apply for processes inside the cgroup namespace: -.IP * 3 +.IP \(bu 3 Writes to controller interface files in the root directory of the namespace will fail with the error .BR EPERM . @@ -1124,7 +1124,7 @@ files in the root directory of the cgroup namespace such as and .IR cgroup.subtree_control , and can create subhierarchy underneath the root directory. -.IP * +.IP \(bu Attempts to migrate processes across the namespace boundary are denied (with the error .BR ENOENT ). @@ -1151,7 +1151,7 @@ Even if a cgroup namespace was employed, because both hierarchies are owned by the unprivileged user .IR cecilia , the following illegitimate actions could be performed: -.IP * 3 +.IP \(bu 3 A process in the inferior hierarchy could change the resource controller settings in the root directory of that hierarchy. (These resource controller settings are intended to allow control to @@ -1159,7 +1159,7 @@ be exercised from the .I parent cgroup; a process inside the child cgroup should not be allowed to modify them.) -.IP * +.IP \(bu A process inside the inferior hierarchy could move processes into and out of the inferior hierarchy if the cgroups in the superior hierarchy were somehow visible. @@ -1208,11 +1208,11 @@ A nonprivileged process (i.e., the delegatee) can write the PID of a "target" process into a .I cgroup.procs file only if all of the following are true: -.IP * 3 +.IP \(bu 3 The writer has write permission on the .I cgroup.procs file in the destination cgroup. -.IP * +.IP \(bu The writer has write permission on the .I cgroup.procs file in the nearest common ancestor of the source and destination cgroups. @@ -1222,12 +1222,12 @@ This requirement is not enforced for cgroups v1 hierarchies, with the consequence that containment in v1 is less strict than in v2. (For example, in cgroups v1 the user that owns two distinct delegated subhierarchies can move a process between the hierarchies.) -.IP * +.IP \(bu If the cgroup v2 filesystem was mounted with the .I nsdelegate option, the writer must be able to see the source and destination cgroups from its cgroup namespace. -.IP * +.IP \(bu In cgroups v1: the effective UID of the writer (i.e., the delegatee) matches the real user ID or the saved set-user-ID of the target process. @@ -1248,10 +1248,10 @@ instead, the delegater must place the first process .SH CGROUPS VERSION 2 THREAD MODE Among the restrictions imposed by cgroups v2 that were not present in cgroups v1 are the following: -.IP * 3 +.IP \(bu 3 .IR "No thread-granularity control" : all of the threads of a process must be in the same cgroup. -.IP * +.IP \(bu .IR "No internal processes" : a cgroup can't both have member processes and exercise controllers on child cgroups. @@ -1278,17 +1278,17 @@ To accommodate such use cases, Linux 4.14 added for cgroups v2. .PP Thread mode allows the following: -.IP * 3 +.IP \(bu 3 The creation of .I threaded subtrees in which the threads of a process may be spread across cgroups inside the tree. (A threaded subtree may contain multiple multithreaded processes.) -.IP * +.IP \(bu The concept of .IR "threaded controllers" , which can distribute resources across the cgroups in a threaded subtree. -.IP * +.IP \(bu A relaxation of the "no internal processes rule", so that, within a threaded subtree, a cgroup can both contain member threads and @@ -1343,7 +1343,7 @@ possible future extensions to the thread mode model .SS Threaded versus domain controllers With the addition of threads mode, cgroups v2 now distinguishes two types of resource controllers: -.IP * 3 +.IP \(bu 3 .I Threaded .\" In the kernel source, look for ".threaded[ \t]*= true" in .\" initializations of struct cgroup_subsys @@ -1356,7 +1356,7 @@ As at Linux 4.19, the following controllers are threaded: .IR perf_event , and .IR pids . -.IP * +.IP \(bu .I Domain controllers: these controllers support only process granularity for resource control. @@ -1367,7 +1367,7 @@ Domain controllers can't be enabled inside a threaded subtree. .SS Creating a threaded subtree There are two pathways that lead to the creation of a threaded subtree. The first pathway proceeds as follows: -.IP 1. 3 +.IP (1) 5 We write the string .I """threaded""" to the @@ -1378,19 +1378,19 @@ that currently has the type .IR domain . This has the following effects: .RS -.IP * 3 +.IP \(bu 3 The type of the cgroup .I y/z becomes .IR threaded . -.IP * +.IP \(bu The type of the parent cgroup, .IR y , becomes .IR "domain threaded" . The parent cgroup is the root of a threaded subtree (also known as the "threaded root"). -.IP * +.IP \(bu All other cgroups under .I y that were not already of type @@ -1404,7 +1404,7 @@ Any subsequently created cgroups under will also have the type .IR "domain invalid" . .RE -.IP 2. +.IP (2) We write the string .I """threaded""" to each of the @@ -1423,23 +1423,23 @@ to each of these cgroups is somewhat cumbersome, but allows for possible future extensions to the thread-mode model. .PP The second way of creating a threaded subtree is as follows: -.IP 1. 3 +.IP (1) 5 In an existing cgroup, .IR z , that currently has the type .IR domain , -we (1) enable one or more threaded controllers and -(2) make a process a member of +we (1.1) enable one or more threaded controllers and +(1.2) make a process a member of .IR z . (These two steps can be done in either order.) This has the following consequences: .RS -.IP * 3 +.IP \(bu 3 The type of .I z becomes .IR "domain threaded" . -.IP * +.IP \(bu All of the descendant cgroups of .I x that were not already of type @@ -1447,7 +1447,7 @@ that were not already of type are converted to type .IR "domain invalid" . .RE -.IP 2. +.IP (2) As before, we make the threaded subtree usable by writing the string .I """threaded""" to each of the @@ -1498,17 +1498,17 @@ As with writing to some containment rules apply when writing to the .I cgroup.threads file: -.IP * 3 +.IP \(bu 3 The writer must have write permission on the cgroup.threads file in the destination cgroup. -.IP * +.IP \(bu The writer must have write permission on the .I cgroup.procs file in the common ancestor of the source and destination cgroups. (In some cases, the common ancestor may be the source or destination cgroup itself.) -.IP * +.IP \(bu The source and destination cgroups must be in the same threaded subtree. (Outside a threaded subtree, an attempt to move a thread by writing its thread ID to the @@ -1551,7 +1551,7 @@ and exercise controllers on child cgroups. A number of rules apply when writing to the .I cgroup.type file: -.IP * 3 +.IP \(bu 3 Only the string .I """threaded""" may be written. @@ -1559,7 +1559,7 @@ In other words, the only explicit transition that is possible is to convert a .I domain cgroup to type .IR threaded . -.IP * +.IP \(bu The effect of writing .I """threaded""" depends on the current value in @@ -1582,7 +1582,7 @@ state; .IR threaded : no effect (a "no-op"). .RE -.IP * +.IP \(bu We can't write to a .I cgroup.type file if the parent's type is @@ -1594,13 +1594,13 @@ state in a top-down manner. There are also some constraints that must be satisfied in order to create a threaded subtree rooted at the cgroup .IR x : -.IP * 3 +.IP \(bu 3 There can be no member processes in the descendant cgroups of .IR x . (The cgroup .I x can itself have member processes.) -.IP * +.IP \(bu No domain controllers may be enabled in .IR x 's .I cgroup.subtree_control @@ -1618,11 +1618,11 @@ According to the pathways described above, the type of a cgroup can change to .I domain threaded in either of the following cases: -.IP * 3 +.IP \(bu 3 The string .I """threaded""" is written to a child cgroup. -.IP * +.IP \(bu A threaded controller is enabled inside the cgroup and a process is made a member of the cgroup. .PP @@ -1647,14 +1647,14 @@ cgroup .I x reverts to the type .IR domain : -.IP * 3 +.IP \(bu 3 All .I domain invalid descendants of .I x that are not in lower-level threaded subtrees revert to the type .IR domain . -.IP * +.IP \(bu The root cgroups in any lower-level threaded subtrees revert to the type .IR "domain threaded" . .\" @@ -1670,10 +1670,10 @@ If the string is written to the .I cgroup.type file of one of the children of the root cgroup, then -.IP * 3 +.IP \(bu 3 The type of that cgroup becomes .IR threaded . -.IP * +.IP \(bu The type of any descendants of that cgroup that are not part of lower-level threaded subtrees changes to .IR "domain invalid" . @@ -1772,24 +1772,24 @@ pids 2 1 1 .IP The fields in this file are, from left to right: .RS -.IP 1. 3 +.IP [1] 5 The name of the controller. -.IP 2. +.IP [2] The unique ID of the cgroup hierarchy on which this controller is mounted. If multiple cgroups v1 controllers are bound to the same hierarchy, then each will show the same hierarchy ID in this field. The value in this field will be 0 if: -.RS 5 -.IP a) 3 +.RS +.IP \(bu 3 the controller is not mounted on a cgroups v1 hierarchy; -.IP b) +.IP \(bu the controller is bound to the cgroups v2 single unified hierarchy; or -.IP c) +.IP \(bu the controller is disabled (see below). .RE -.IP 3. +.IP [3] The number of control groups in this hierarchy using this controller. -.IP 4. +.IP [4] This field contains the value 1 if this controller is enabled, or 0 if it has been disabled (via the .I cgroup_disable @@ -1821,18 +1821,18 @@ For example: .IP The colon-separated fields are, from left to right: .RS -.IP 1. 3 +.IP [1] 5 For cgroups version 1 hierarchies, this field contains a unique hierarchy ID number that can be matched to a hierarchy ID in .IR /proc/cgroups . For the cgroups version 2 hierarchy, this field contains the value 0. -.IP 2. +.IP [2] For cgroups version 1 hierarchies, this field contains a comma-separated list of the controllers bound to the hierarchy. For the cgroups version 2 hierarchy, this field is empty. -.IP 3. +.IP [3] This field contains the pathname of the control group in the hierarchy to which the process belongs. This pathname is relative to the mount point of the hierarchy. diff --git a/man7/cpuset.7 b/man7/cpuset.7 index 01abdc05d3..aae3ac04c8 100644 --- a/man7/cpuset.7 +++ b/man7/cpuset.7 @@ -519,17 +519,17 @@ always return zero, as represented by the ASCII string "0\en". See the \fBWARNINGS\fR section, below. .PP A per-cpuset, running average is employed for the following reasons: -.IP * 3 +.IP \(bu 3 Because this meter is per-cpuset rather than per-process or per virtual memory region, the system load imposed by a batch scheduler monitoring this metric is sharply reduced on large systems, because a scan of the tasklist can be avoided on each set of queries. -.IP * +.IP \(bu Because this meter is a running average rather than an accumulating counter, a batch scheduler can detect memory pressure with a single read, instead of having to read and accumulate results for a period of time. -.IP * +.IP \(bu Because this meter is per-cpuset rather than per-process, the batch scheduler can obtain the key information\(emmemory pressure in a cpuset\(emwith a single read, rather than having to @@ -629,11 +629,11 @@ Cpuset-specified memory spreading behaves similarly to what is known .PP Cpuset-specified memory spreading can provide substantial performance improvements for jobs that: -.IP a) 3 +.IP \(bu 3 need to place thread-local data on memory nodes close to the CPUs which are running the threads that most frequently access that data; but also -.IP b) +.IP \(bu need to access large filesystem data sets that must to be spread across the several nodes in the job's cpuset in order to fit. .PP @@ -705,11 +705,11 @@ marked isolated using the kernel boot time "isolcpus=" argument. .PP This default load balancing across all CPUs is not well suited to the following two situations: -.IP * 3 +.IP \(bu 3 On large systems, load balancing across many CPUs is expensive. If the system is managed using cpusets to place independent jobs on separate sets of CPUs, full load balancing is unnecessary. -.IP * +.IP \(bu Systems supporting real-time on some CPUs need to minimize system overhead on those CPUs, including avoiding process load balancing if that is not needed. @@ -911,22 +911,22 @@ Examples of the \fBList Format\fR: .\" ================== RULES ================== .SH RULES The following rules apply to each cpuset: -.IP * 3 +.IP \(bu 3 Its CPUs and memory nodes must be a (possibly equal) subset of its parent's. -.IP * +.IP \(bu It can be marked .I cpu_exclusive only if its parent is. -.IP * +.IP \(bu It can be marked .I mem_exclusive only if its parent is. -.IP * +.IP \(bu If it is .IR cpu_exclusive , its CPUs may not overlap any sibling. -.IP * +.IP \(bu If it is .IR mem_exclusive , its memory nodes may not overlap any sibling. @@ -1357,16 +1357,16 @@ To create a new cpuset and attach the current command shell to it, the steps are: .PP .PD 0 -.IP 1) 4 +.IP (1) 5 mkdir /dev/cpuset (if not already done) -.IP 2) +.IP (2) mount \-t cpuset none /dev/cpuset (if not already done) -.IP 3) +.IP (3) Create the new cpuset using .BR mkdir (1). -.IP 4) +.IP (4) Assign CPUs and memory nodes to the new cpuset. -.IP 5) +.IP (5) Attach the shell to the new cpuset. .PD .PP @@ -1397,24 +1397,24 @@ the memory pages currently allocated to that job, perform the following steps. .PP .PD 0 -.IP 1) 4 +.IP (1) 5 Let's say we want to move the job in cpuset .I alpha (CPUs 4\(en7 and memory nodes 2\(en3) to a new cpuset .I beta (CPUs 16\(en19 and memory nodes 8\(en9). -.IP 2) +.IP (2) First create the new cpuset .IR beta . -.IP 3) +.IP (3) Then allow CPUs 16\(en19 and memory nodes 8\(en9 in .IR beta . -.IP 4) +.IP (4) Then enable .I memory_migration in .IR beta . -.IP 5) +.IP (5) Then move each process from .I alpha to diff --git a/man7/credentials.7 b/man7/credentials.7 index 01a5319740..60f4aeba40 100644 --- a/man7/credentials.7 +++ b/man7/credentials.7 @@ -154,13 +154,13 @@ and .IR <sys/types.h> ). .PP On Linux, each process has the following user and group identifiers: -.IP * 3 +.IP \(bu 3 Real user ID and real group ID. These IDs determine who owns the process. A process can obtain its real user (group) ID using .BR getuid (2) .RB ( getgid (2)). -.IP * +.IP \(bu Effective user ID and effective group ID. These IDs are used by the kernel to determine the permissions that the process will have when accessing shared resources such @@ -172,7 +172,7 @@ for this task. A process can obtain its effective user (group) ID using .BR geteuid (2) .RB ( getegid (2)). -.IP * +.IP \(bu Saved set-user-ID and saved set-group-ID. These IDs are used in set-user-ID and set-group-ID programs to save a copy of the corresponding effective IDs that were set when @@ -194,7 +194,7 @@ or A process can obtain its saved set-user-ID (set-group-ID) using .BR getresuid (2) .RB ( getresgid (2)). -.IP * +.IP \(bu Filesystem user ID and filesystem group ID (Linux-specific). These IDs, in conjunction with the supplementary group IDs described below, are used to determine permissions for accessing files; see @@ -211,7 +211,7 @@ by calling .BR setfsuid (2) and .BR setfsgid (2). -.IP * +.IP \(bu Supplementary group IDs. This is a set of additional group IDs that are used for permission checks when accessing files and other shared resources. @@ -241,10 +241,10 @@ the effective and saved set IDs may be changed, as described in .PP Aside from the purposes noted above, a process's user IDs are also employed in a number of other contexts: -.IP * 3 +.IP \(bu 3 when determining the permissions for sending signals (see .BR kill (2)); -.IP * +.IP \(bu when determining the permissions for setting process-scheduling parameters (nice value, real time scheduling policy and priority, CPU affinity, I/O priority) using @@ -255,10 +255,10 @@ scheduling policy and priority, CPU affinity, I/O priority) using .BR sched_setattr (2), and .BR ioprio_set (2); -.IP * +.IP \(bu when checking resource limits (see .BR getrlimit (2)); -.IP * +.IP \(bu when checking the limit on the number of inotify instances that the process may create (see .BR inotify (7)). diff --git a/man7/environ.7 b/man7/environ.7 index e62164df19..99b49351d2 100644 --- a/man7/environ.7 +++ b/man7/environ.7 @@ -198,7 +198,7 @@ command shall be valid. Note that the behavior of many programs and library routines is influenced by the presence or value of certain environment variables. Examples include the following: -.IP * 3 +.IP \(bu 3 The variables .BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH , .BR LC_ALL ", " LC_MESSAGES , @@ -207,37 +207,37 @@ and so on influence locale handling; see .BR gettext (3), and .BR locale (7). -.IP * +.IP \(bu .B TMPDIR influences the path prefix of names created by .BR tempnam (3) and other routines, and the temporary directory used by .BR sort (1) and other programs. -.IP * +.IP \(bu .BR LD_LIBRARY_PATH ", " LD_PRELOAD , and other .B LD_* variables influence the behavior of the dynamic loader/linker. See also .BR ld.so (8). -.IP * +.IP \(bu .B POSIXLY_CORRECT makes certain programs and library routines follow the prescriptions of POSIX. -.IP * +.IP \(bu The behavior of .BR malloc (3) is influenced by .B MALLOC_* variables. -.IP * +.IP \(bu The variable .B HOSTALIASES gives the name of a file containing aliases to be used with .BR gethostbyname (3). -.IP * +.IP \(bu .BR TZ " and " TZDIR give timezone information used by .BR tzset (3) @@ -248,14 +248,14 @@ and through that by functions like .BR strftime (3). See also .BR tzselect (8). -.IP * +.IP \(bu .B TERMCAP gives information on how to address a given terminal (or gives the name of a file containing such information). -.IP * +.IP \(bu .BR COLUMNS " and " LINES tell applications about the window size, possibly overriding the actual size. -.IP * +.IP \(bu .BR PRINTER " or " LPDEST may specify the desired printer to use. See diff --git a/man7/epoll.7 b/man7/epoll.7 index 29ae4c307c..146cc815af 100644 --- a/man7/epoll.7 +++ b/man7/epoll.7 @@ -29,7 +29,7 @@ API is the .IR instance , an in-kernel data structure which, from a user-space perspective, can be considered as a container for two lists: -.IP \(bu 2 +.IP \(bu 3 The .I interest list (sometimes also called the @@ -50,7 +50,7 @@ The following system calls are provided to create and manage an .B epoll instance: -.IP \(bu 2 +.IP \(bu 3 .BR epoll_create (2) creates a new .B epoll @@ -83,24 +83,24 @@ The difference between the two mechanisms can be described as follows. Suppose that this scenario happens: -.IP 1. 3 +.IP (1) 5 The file descriptor that represents the read side of a pipe .RI ( rfd ) is registered on the .B epoll instance. -.IP 2. +.IP (2) A pipe writer writes 2\ kB of data on the write side of the pipe. -.IP 3. +.IP (3) A call to .BR epoll_wait (2) is done that will return .I rfd as a ready file descriptor. -.IP 4. +.IP (4) The pipe reader reads 1\ kB of data from .IR rfd . -.IP 5. +.IP (5) A call to .BR epoll_wait (2) is done. @@ -149,9 +149,9 @@ The suggested way to use as an edge-triggered .RB ( EPOLLET ) interface is as follows: -.IP a) 3 +.IP (1) 5 with nonblocking file descriptors; and -.IP b) +.IP (2) by waiting for an event only after .BR read (2) or @@ -355,7 +355,7 @@ calling with .BR EPOLL_CTL_MOD . .SS Questions and answers -.IP 0. 4 +.IP \(bu 3 What is the key used to distinguish the file descriptors registered in an interest list? .IP @@ -363,7 +363,7 @@ The key is the combination of the file descriptor number and the open file description (also known as an "open file handle", the kernel's internal representation of an open file). -.IP 1. +.IP \(bu What happens if you register the same file descriptor on an .B epoll instance twice? @@ -397,7 +397,7 @@ This can be a useful technique for filtering events, if the duplicate file descriptors are registered with different .I events masks. -.IP 2. +.IP \(bu Can two .B epoll instances wait for the same file descriptor? @@ -407,7 +407,7 @@ file descriptors? .IP Yes, and events would be reported to both. However, careful programming may be needed to do this correctly. -.IP 3. +.IP \(bu Is the .B epoll file descriptor itself poll/epoll/selectable? @@ -417,7 +417,7 @@ If an .B epoll file descriptor has events waiting, then it will indicate as being readable. -.IP 4. +.IP \(bu What happens if one attempts to put an .B epoll file descriptor into its own file descriptor set? @@ -431,14 +431,14 @@ However, you can add an file descriptor inside another .B epoll file descriptor set. -.IP 5. +.IP \(bu Can I send an .B epoll file descriptor over a UNIX domain socket to another process? .IP Yes, but it does not make sense to do this, since the receiving process would not have copies of the file descriptors in the interest list. -.IP 6. +.IP \(bu Will closing a file descriptor cause it to be removed from all .B epoll interest lists? @@ -477,13 +477,13 @@ behind the scenes by library functions that used .BR dup (2) or .BR fork (2)). -.IP 7. +.IP \(bu If more than one event occurs between .BR epoll_wait (2) calls, are they combined or reported separately? .IP They will be combined. -.IP 8. +.IP \(bu Does an operation on a file descriptor affect the already collected but not yet reported events? .IP @@ -491,7 +491,7 @@ You can do two operations on an existing file descriptor. Remove would be meaningless for this case. Modify will reread available I/O. -.IP 9. +.IP \(bu Do I need to continuously read/write a file descriptor until .B EAGAIN @@ -530,15 +530,15 @@ The same is true when writing using (Avoid this latter technique if you cannot guarantee that the monitored file descriptor always refers to a stream-oriented file.) .SS Possible pitfalls and ways to avoid them -.TP -.B o Starvation (edge-triggered) -.PP +.IP \(bu 3 +.B Starvation (edge-triggered) +.IP If there is a large amount of I/O space, it is possible that by trying to drain it the other files will not get processed causing starvation. (This problem is not specific to .BR epoll .) -.PP +.IP The solution is to maintain a ready list and mark the file descriptor as ready in its associated data structure, thereby allowing the application to @@ -546,9 +546,9 @@ remember which files need to be processed but still round robin amongst all the ready files. This also supports ignoring subsequent events you receive for file descriptors that are already ready. -.TP -.B o If using an event cache... -.PP +.IP \(bu +.B If using an event cache... +.IP If you use an event cache or store all the file descriptors returned from .BR epoll_wait (2), then make sure to provide a way to mark @@ -562,7 +562,7 @@ If you remove the structure and the file descriptor for event #13, then your event cache might still say there are events waiting for that file descriptor causing confusion. -.PP +.IP One solution for this is to call, during the processing of event 47, .BR epoll_ctl ( EPOLL_CTL_DEL ) to delete file descriptor 13 and diff --git a/man7/fanotify.7 b/man7/fanotify.7 index fd477802ce..6531f2eaed 100644 --- a/man7/fanotify.7 +++ b/man7/fanotify.7 @@ -968,7 +968,7 @@ events. .PP As of Linux 3.17, the following bugs exist: -.IP * 3 +.IP \(bu 3 On Linux, a filesystem object may be accessible through multiple paths, for example, a part of a filesystem may be remounted using the .I \-\-bind @@ -977,7 +977,7 @@ option of A listener that marked a mount will be notified only of events that were triggered for a filesystem object using the same mount. Any other event will pass unnoticed. -.IP * +.IP \(bu .\" FIXME . A patch was proposed. When an event is generated, no check is made to see whether the user ID of the @@ -986,7 +986,7 @@ before passing a file descriptor for that file. This poses a security risk, when the .B CAP_SYS_ADMIN capability is set for programs executed by unprivileged users. -.IP * +.IP \(bu If a call to .BR read (2) processes multiple events from the fanotify queue and an error occurs, diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7 index 2a0d8be2a8..6a5f1de62e 100644 --- a/man7/feature_test_macros.7 +++ b/man7/feature_test_macros.7 @@ -129,7 +129,7 @@ in glibc 2.\fIx\fP, > 0. .PP First, though, a summary of a few details for the impatient: -.IP * 3 +.IP \(bu 3 The macros that you most likely need to use in modern source code are .B _POSIX_C_SOURCE (for definitions from various versions of POSIX.1), @@ -139,13 +139,13 @@ The macros that you most likely need to use in modern source code are (for GNU and/or Linux specific stuff), and .B _DEFAULT_SOURCE (to get definitions that would normally be provided by default). -.IP * +.IP \(bu Certain macros are defined with default values. Thus, although one or more macros may be indicated as being required in the SYNOPSIS of a man page, it may not be necessary to define them explicitly. Full details of the defaults are given later in this man page. -.IP * +.IP \(bu Defining .B _XOPEN_SOURCE with a value of 600 or greater produces the same effects as defining @@ -167,7 +167,7 @@ it is implicit that the following has the same effect: _XOPEN_SOURCE >= 600 .EE .in -.IP * +.IP \(bu Defining .B _XOPEN_SOURCE with a value of 700 or greater produces the same effects as defining @@ -712,10 +712,10 @@ and either is not defined or .B _XOPEN_SOURCE is defined with a value of 500 or more, then -.IP * 3 +.IP \(bu 3 .B _POSIX_SOURCE is defined with the value 1; and -.IP * +.IP \(bu .B _POSIX_C_SOURCE is defined with one of the following values: .RS 3 diff --git a/man7/inotify.7 b/man7/inotify.7 index 2bb576e258..dba592c25d 100644 --- a/man7/inotify.7 +++ b/man7/inotify.7 @@ -16,7 +16,7 @@ When a directory is monitored, inotify will return events for the directory itself, and for files inside the directory. .PP The following system calls are used with this API: -.IP * 3 +.IP \(bu 3 .BR inotify_init (2) creates an inotify instance and returns a file descriptor referring to the inotify instance. @@ -27,7 +27,7 @@ is like but has a .I flags argument that provides access to some extra functionality. -.IP * +.IP \(bu .BR inotify_add_watch (2) manipulates the "watch list" associated with an inotify instance. Each item ("watch") in the watch list specifies the pathname of @@ -40,16 +40,16 @@ Each watch has a unique "watch descriptor", an integer returned by .BR inotify_add_watch (2) when the watch is created. -.IP * +.IP \(bu When events occur for monitored files and directories, those events are made available to the application as structured data that can be read from the inotify file descriptor using .BR read (2) (see below). -.IP * +.IP \(bu .BR inotify_rm_watch (2) removes an item from an inotify watch list. -.IP * +.IP \(bu When all file descriptors referring to an inotify instance have been closed (using .BR close (2)), @@ -259,10 +259,10 @@ an event can be generated for activity on any link to the file (in the same or a different directory). .PP When monitoring a directory: -.IP * 3 +.IP \(bu 3 the events marked above with an asterisk (*) can occur both for the directory itself and for objects inside the directory; and -.IP * +.IP \(bu the events marked with a plus sign (+) occur only for objects inside the directory (not for the directory itself). .PP @@ -89,7 +89,7 @@ is the IP protocol in the IP header to be received or sent. Valid values for .I protocol include: -.IP \(bu 2 +.IP \(bu 3 0 and .B IPPROTO_TCP for @@ -1147,16 +1147,16 @@ is, the range used for .IR "ephemeral ports" . An ephemeral port is allocated to a socket in the following circumstances: .RS -.IP * 3 +.IP \(bu 3 the port number in a socket address is specified as 0 when calling .BR bind (2); -.IP * +.IP \(bu .BR listen (2) is called on a stream socket that was not previously bound; -.IP * +.IP \(bu .BR connect (2) was called on a socket that was not previously bound; -.IP * +.IP \(bu .BR sendto (2) is called on a datagram socket that was not previously bound. .RE diff --git a/man7/ipc_namespaces.7 b/man7/ipc_namespaces.7 index 754e3c88a0..a284d09c8a 100644 --- a/man7/ipc_namespaces.7 +++ b/man7/ipc_namespaces.7 @@ -28,10 +28,10 @@ but are not visible to processes in other IPC namespaces. The following .I /proc interfaces are distinct in each IPC namespace: -.IP * 3 +.IP \(bu 3 The POSIX message queue interfaces in .IR /proc/sys/fs/mqueue . -.IP * +.IP \(bu The System V IPC interfaces in .IR /proc/sys/kernel , namely: @@ -44,7 +44,7 @@ namely: .IR shmmni , and .IR shm_rmid_forced . -.IP * +.IP \(bu The System V IPC interfaces in .IR /proc/sysvipc . .PP diff --git a/man7/kernel_lockdown.7 b/man7/kernel_lockdown.7 index a6528f245b..883f962555 100644 --- a/man7/kernel_lockdown.7 +++ b/man7/kernel_lockdown.7 @@ -50,7 +50,7 @@ kprobes .PP and the ability to directly configure and control devices, so as to prevent the use of a device to access or modify a kernel image: -.IP \(bu 2 +.IP \(bu 3 The use of module parameters that directly specify hardware parameters to drivers through the kernel command line or when loading a module. .IP \(bu @@ -75,7 +75,7 @@ The specification of the ACPI RDSP address. The use of ACPI custom methods. .PP Certain facilities are restricted: -.IP \(bu 2 +.IP \(bu 3 Only validly signed modules may be loaded (waived if the module file being loaded is vouched for by IMA appraisal). .IP \(bu diff --git a/man7/keyrings.7 b/man7/keyrings.7 index 56c9fbe2bc..f6f9594ba2 100644 --- a/man7/keyrings.7 +++ b/man7/keyrings.7 @@ -314,7 +314,7 @@ has been defined for this keyring. The concept of possession is important to understanding the keyrings security model. Whether a thread possesses a key is determined by the following rules: -.IP (1) 4 +.IP (1) 5 Any key or keyring that does not grant .I search permission to the caller is ignored in all the following rules. @@ -353,13 +353,13 @@ thus making the user keyring and anything it contains possessed by default. .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SS Access rights Each key has the following security-related attributes: -.IP * 3 +.IP \(bu 3 The owning user ID -.IP * +.IP \(bu The ID of a group that is permitted to access the key -.IP * +.IP \(bu A security label -.IP * +.IP \(bu A permissions mask .PP The permissions mask contains four sets of rights. @@ -449,7 +449,7 @@ access for user-space applications to find a key. for use by internal components that make use of keys.) .PP The search algorithm works as follows: -.IP (1) 4 +.IP (1) 5 The process keyrings are searched in the following order: the thread .BR thread\-keyring (7) if it exists, the diff --git a/man7/locale.7 b/man7/locale.7 index 80492c2815..696124187e 100644 --- a/man7/locale.7 +++ b/man7/locale.7 @@ -219,16 +219,16 @@ If the second argument to is an empty string, .IR \(dq\(dq , for the default locale, it is determined using the following steps: -.IP 1. 3 +.IP (1) 5 If there is a non-null environment variable .BR LC_ALL , the value of .B LC_ALL is used. -.IP 2. +.IP (2) If an environment variable with the same name as one of the categories above exists and is non-null, its value is used for that category. -.IP 3. +.IP (3) If there is a non-null environment variable .BR LANG , the value of diff --git a/man7/man-pages.7 b/man7/man-pages.7 index 52446b7693..cda5b4d0f8 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -482,17 +482,17 @@ be separated by blank lines. However, blank lines (achieved using .IR .PP ) may be added in the following cases: -.IP * 3 +.IP \(bu 3 to separate long lists of function prototypes into related groups (see for example .BR list (3)); -.IP * +.IP \(bu in other cases that may improve readability. .PP In the SYNOPSIS, a long function prototype may need to be continued over to the next line. The continuation line is indented according to the following rules: -.IP 1. 3 +.IP (1) 5 If there is a single such prototype that needs to be continued, then align the continuation line so that when the page is rendered on a fixed-width font device (e.g., on an xterm) the @@ -503,14 +503,14 @@ adjusted if necessary to prevent a very long continuation line or a further continuation line where the function prototype is very long.) As an example: -.PP -.RS +.IP +.in +4n .nf .BI "int tcsetattr(int " fd ", int " optional_actions , .BI " const struct termios *" termios_p ); .fi -.RE -.IP 2. 3 +.in +.IP (2) But, where multiple functions in the SYNOPSIS require continuation lines, and the function names have different lengths, then align all continuation lines to start in the @@ -542,19 +542,19 @@ This wording is consistent with the wording used in both POSIX.1 and FreeBSD. .SS ATTRIBUTES .\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf Note the following: -.IP * 3 +.IP \(bu 3 Wrap the table in this section in a .IR ".ad\ l" / .ad pair to disable text filling and a .IR .nh / .hy pair to disable hyphenation. -.IP * +.IP \(bu Ensure that the table occupies the full page width through the use of an .I lbx description for one of the columns (usually the first column, though in some cases the last column if it contains a lot of text). -.IP * +.IP \(bu Make free use of .IR T{ / T} macro pairs to allow table cells to be broken over multiple lines @@ -712,11 +712,11 @@ please write all new pages and patches according to these conventions. .PP Aside from the well-known spelling differences, there are a few other subtleties to watch for: -.IP * 3 +.IP \(bu 3 American English tends to use the forms "backward", "upward", "toward", and so on rather than the British forms "backwards", "upwards", "towards", and so on. -.IP * +.IP \(bu Opinions are divided on "acknowledgement" vs "acknowledgment". The latter is predominant, but not universal usage in American English. POSIX and the BSD license use the former spelling. @@ -1017,11 +1017,11 @@ This guideline applies also to code examples. .PP The use of real minus signs serves the following purposes: .\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/ -.IP * 3 +.IP \(bu 3 To provide better renderings on various targets other than ASCII terminals, notably in PDF and on Unicode/UTF\-8-capable terminals. -.IP * +.IP \(bu To generate glyphs that when copied from rendered pages will produce real minus signs when pasted into a terminal. .PP @@ -1053,22 +1053,22 @@ to get a nicely rendered tilde when rendering to PDF. Manual pages may include example programs demonstrating how to use a system call or library function. However, note the following: -.IP * 3 +.IP \(bu 3 Example programs should be written in C. -.IP * +.IP \(bu An example program is necessary and useful only if it demonstrates something beyond what can easily be provided in a textual description of the interface. An example program that does nothing other than call an interface usually serves little purpose. -.IP * +.IP \(bu Example programs should ideally be short (e.g., a good example can often be provided in less than 100 lines of code), though in some cases longer programs may be necessary to properly illustrate the use of an API. -.IP * +.IP \(bu Expressive code is appreciated. -.IP * +.IP \(bu Comments should included where helpful. Complete sentences in free-standing comments should be terminated by a period. @@ -1076,18 +1076,18 @@ Periods should generally be omitted in "tag" comments (i.e., comments that are placed on the same line of code); such comments are in any case typically brief phrases rather than complete sentences. -.IP * +.IP \(bu Example programs should do error checking after system calls and library function calls. -.IP * +.IP \(bu Example programs should be complete, and compile without warnings when compiled with \fIcc\ \-Wall\fP. -.IP * +.IP \(bu Where possible and appropriate, example programs should allow experimentation, by varying their behavior based on inputs (ideally from command-line arguments, or alternatively, via input read by the program). -.IP * +.IP \(bu Example programs should be laid out according to Kernighan and Ritchie style, with 4-space indents. (Avoid the use of TAB characters in source code!) @@ -1099,7 +1099,7 @@ something close to the preferred style: indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c .EE .in -.IP * +.IP \(bu For consistency, all example programs should terminate using either of: .IP .in +4n @@ -1118,7 +1118,7 @@ exit(1); return n; .EE .in -.IP * +.IP \(bu If there is extensive explanatory text before the program source code, mark off the source code with a subsection heading @@ -1135,11 +1135,11 @@ Always do this if the explanatory text includes a shell session log. .PP If you include a shell session log demonstrating the use of a program or other system feature: -.IP * 3 +.IP \(bu 3 Place the session log above the source code listing. -.IP * +.IP \(bu Indent the session log by four spaces. -.IP * +.IP \(bu Boldface the user input text, to distinguish it from output produced by the system. .PP diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7 index a1e0c0d36b..5530ce704f 100644 --- a/man7/mount_namespaces.7 +++ b/man7/mount_namespaces.7 @@ -37,12 +37,12 @@ with the flag. When a new mount namespace is created, its mount list is initialized as follows: -.IP * 3 +.IP \(bu 3 If the namespace is created using .BR clone (2), the mount list of the child's namespace is a copy of the mount list in the parent process's mount namespace. -.IP * +.IP \(bu If the namespace is created using .BR unshare (2), the mount list of the new namespace is a copy of @@ -144,9 +144,9 @@ of the mount. Members are added to a .I peer group when a mount is marked as shared and either: -.IP * 3 +.IP (a) 5 the mount is replicated during the creation of a new mount namespace; or -.IP * +.IP (b) a new bind mount is created from the mount. .PP In both of these cases, the new mount joins the peer group diff --git a/man7/mq_overview.7 b/man7/mq_overview.7 index dcab4ced87..10ae3ae5a7 100644 --- a/man7/mq_overview.7 +++ b/man7/mq_overview.7 @@ -168,13 +168,13 @@ The definition of .B HARD_MSGMAX has changed across kernel versions: .RS -.IP * 3 +.IP \(bu 3 Up to Linux 2.6.32: .I 131072\~/\~sizeof(void\~*) -.IP * +.IP \(bu Linux 2.6.33 to 3.4: .I (32768\~*\~sizeof(void\~*) / 4) -.IP * +.IP \(bu Since Linux 3.5: .\" commit 5b5c4d1a1440e94994c73dddbad7be0676cd8b9a 65,536 @@ -222,12 +222,12 @@ The upper limit for .I msgsize_max has varied across kernel versions: .RS -.IP * 3 +.IP \(bu 3 Before Linux 2.6.28, the upper limit is .BR INT_MAX . -.IP * +.IP \(bu From Linux 2.6.28 to 3.4, the limit is 1,048,576. -.IP * +.IP \(bu Since Linux 3.5, the limit is 16,777,216 .RB ( HARD_MSGSIZEMAX ). .RE diff --git a/man7/namespaces.7 b/man7/namespaces.7 index dcae034c4d..b7d3142556 100644 --- a/man7/namespaces.7 +++ b/man7/namespaces.7 @@ -310,48 +310,48 @@ The value in this file defines a per-user limit on the number of uts namespaces that may be created in the user namespace. .PP Note the following details about these files: -.IP * 3 +.IP \(bu 3 The values in these files are modifiable by privileged processes. -.IP * +.IP \(bu The values exposed by these files are the limits for the user namespace in which the opening process resides. -.IP * +.IP \(bu The limits are per-user. Each user in the same user namespace can create namespaces up to the defined limit. -.IP * +.IP \(bu The limits apply to all users, including UID 0. -.IP * +.IP \(bu These limits apply in addition to any other per-namespace limits (such as those for PID and user namespaces) that may be enforced. -.IP * +.IP \(bu Upon encountering these limits, .BR clone (2) and .BR unshare (2) fail with the error .BR ENOSPC . -.IP * +.IP \(bu For the initial user namespace, the default value in each of these files is half the limit on the number of threads that may be created .RI ( /proc/sys/kernel/threads\-max ). In all descendant user namespaces, the default value in each file is .BR MAXINT . -.IP * +.IP \(bu When a namespace is created, the object is also accounted against ancestor namespaces. More precisely: .RS -.IP + 3 +.IP \(bu 3 Each user namespace has a creator UID. -.IP + +.IP \(bu When a namespace is created, it is accounted against the creator UIDs in each of the ancestor user namespaces, and the kernel ensures that the corresponding namespace limit for the creator UID in the ancestor namespace is not exceeded. -.IP + +.IP \(bu The aforementioned point ensures that creating a new user namespace cannot be used as a means to escape the limits in force in the current user namespace. @@ -364,32 +364,32 @@ the namespace terminates or leaves the namespace. However, there are a number of other factors that may pin a namespace into existence even though it has no member processes. These factors include the following: -.IP * 3 +.IP \(bu 3 An open file descriptor or a bind mount exists for the corresponding .IR /proc/ pid /ns/* file. -.IP * +.IP \(bu The namespace is hierarchical (i.e., a PID or user namespace), and has a child namespace. -.IP * +.IP \(bu It is a user namespace that owns one or more nonuser namespaces. -.IP * +.IP \(bu It is a PID namespace, and there is a process that refers to the namespace via a .IR /proc/ pid /ns/pid_for_children symbolic link. -.IP * +.IP \(bu It is a time namespace, and there is a process that refers to the namespace via a .IR /proc/ pid /ns/time_for_children symbolic link. -.IP * +.IP \(bu It is an IPC namespace, and a corresponding mount of an .I mqueue filesystem (see .BR mq_overview (7)) refers to this namespace. -.IP * +.IP \(bu It is a PID namespace, and a corresponding mount of a .BR proc (5) filesystem refers to this namespace. diff --git a/man7/nptl.7 b/man7/nptl.7 index f7cabc4ef8..5a17e05414 100644 --- a/man7/nptl.7 +++ b/man7/nptl.7 @@ -26,10 +26,10 @@ which might interfere with the operation of the NPTL implementation, various glibc library functions and system call wrapper functions attempt to hide these signals from applications, as follows: -.IP * 3 +.IP \(bu 3 .B SIGRTMIN is defined with the value 34 (rather than 32). -.IP * +.IP \(bu The .BR sigwaitinfo (2), .BR sigtimedwait (2), @@ -37,13 +37,13 @@ and .BR sigwait (3) interfaces silently ignore requests to wait for these two signals if they are specified in the signal set argument of these calls. -.IP * +.IP \(bu The .BR sigprocmask (2) and .BR pthread_sigmask (3) interfaces silently ignore attempts to block these two signals. -.IP * +.IP \(bu The .BR sigaction (2), .BR pthread_kill (3), @@ -52,7 +52,7 @@ and interfaces fail with the error .B EINVAL (indicating an invalid signal number) if these signals are specified. -.IP * +.IP \(bu .BR sigfillset (3) does not include these two signals when it creates a full signal set. .\" diff --git a/man7/packet.7 b/man7/packet.7 index 6a32d1b5c4..c3650cfec3 100644 --- a/man7/packet.7 +++ b/man7/packet.7 @@ -297,7 +297,7 @@ The group is deleted when the last socket is closed. Fanout supports multiple algorithms to spread traffic between sockets, as follows: .RS -.IP * 3 +.IP \(bu 3 The default mode, .BR PACKET_FANOUT_HASH , sends packets from the same flow to the same socket to maintain @@ -305,21 +305,21 @@ per-flow ordering. For each packet, it chooses a socket by taking the packet flow hash modulo the number of sockets in the group, where a flow hash is a hash over network-layer address and optional transport-layer port fields. -.IP * +.IP \(bu The load-balance mode .B PACKET_FANOUT_LB implements a round-robin algorithm. -.IP * +.IP \(bu .B PACKET_FANOUT_CPU selects the socket based on the CPU that the packet arrived on. -.IP * +.IP \(bu .B PACKET_FANOUT_ROLLOVER processes all data on a single socket, moving to the next when one becomes backlogged. -.IP * +.IP \(bu .B PACKET_FANOUT_RND selects the socket using a pseudo-random number generator. -.IP * +.IP \(bu .B PACKET_FANOUT_QM .\" commit 2d36097d26b5991d71a2cf4a20c1a158f0f1bfcd (available since Linux 3.14) diff --git a/man7/pipe.7 b/man7/pipe.7 index 0194bff8a2..40d08d8091 100644 --- a/man7/pipe.7 +++ b/man7/pipe.7 @@ -334,7 +334,7 @@ operation to change a pipe's capacity: .\" These bugs where remedied by a series of patches, in particular, .\" commit b0b91d18e2e97b741b294af9333824ecc3fadfd8 and .\" commit a005ca0e6813e1d796a7422a7e31d8b8d6555df1 -.IP (1) 5 +.IP (a) 5 When increasing the pipe capacity, the checks against the soft and hard limits were made against existing consumption, and excluded the memory required for the increased pipe capacity. @@ -344,7 +344,7 @@ memory used by the user for pipes (possibly far) over a limit. .IP Starting with Linux 4.9, the limit checking includes the memory required for the new pipe capacity. -.IP (2) +.IP (b) The limit checks were performed even when the new pipe capacity was less than the existing pipe capacity. This could lead to problems if a user set a large pipe capacity, @@ -354,22 +354,23 @@ no longer decrease the pipe capacity. Starting with Linux 4.9, checks against the limits are performed only when increasing a pipe's capacity; an unprivileged user can always decrease a pipe's capacity. -.IP (3) +.IP (c) The accounting and checking against the limits were done as follows: +.IP .RS .PD 0 -.IP (a) 4 +.IP (1) 5 Test whether the user has exceeded the limit. -.IP (b) +.IP (2) Make the new pipe buffer allocation. -.IP (c) +.IP (3) Account new allocation against the limits. .PD .RE .IP This was racey. -Multiple processes could pass point (a) simultaneously, -and then allocate pipe buffers that were accounted for only in step (c), +Multiple processes could pass point (1) simultaneously, +and then allocate pipe buffers that were accounted for only in step (3), with the result that the user's pipe buffer allocation could be pushed over the limit. .IP @@ -377,7 +378,7 @@ Starting with Linux 4.9, the accounting step is performed before doing the allocation, and the operation fails if the limit would be exceeded. .PP -Before Linux 4.9, bugs similar to points (1) and (3) could also occur +Before Linux 4.9, bugs similar to points (a) and (c) could also occur when the kernel allocated memory for a new pipe buffer; that is, when calling .BR pipe (2) diff --git a/man7/pthreads.7 b/man7/pthreads.7 index d2c010b0e9..606085d8eb 100644 --- a/man7/pthreads.7 +++ b/man7/pthreads.7 @@ -15,44 +15,44 @@ but each thread has its own stack (automatic variables). .PP POSIX.1 also requires that threads share a range of other attributes (i.e., these attributes are process-wide rather than per-thread): -.IP \- 3 +.IP \(bu 3 process ID -.IP \- 3 +.IP \(bu parent process ID -.IP \- 3 +.IP \(bu process group ID and session ID -.IP \- 3 +.IP \(bu controlling terminal -.IP \- 3 +.IP \(bu user and group IDs -.IP \- 3 +.IP \(bu open file descriptors -.IP \- 3 +.IP \(bu record locks (see .BR fcntl (2)) -.IP \- 3 +.IP \(bu signal dispositions -.IP \- 3 +.IP \(bu file mode creation mask .RB ( umask (2)) -.IP \- 3 +.IP \(bu current directory .RB ( chdir (2)) and root directory .RB ( chroot (2)) -.IP \- 3 +.IP \(bu interval timers .RB ( setitimer (2)) and POSIX timers .RB ( timer_create (2)) -.IP \- 3 +.IP \(bu nice value .RB ( setpriority (2)) -.IP \- 3 +.IP \(bu resource limits .RB ( setrlimit (2)) -.IP \- 3 +.IP \(bu measurements of the consumption of CPU time .RB ( times (2)) and resources @@ -60,29 +60,29 @@ and resources .PP As well as the stack, POSIX.1 specifies that various other attributes are distinct for each thread, including: -.IP \- 3 +.IP \(bu 3 thread ID (the .I pthread_t data type) -.IP \- 3 +.IP \(bu signal mask .RB ( pthread_sigmask (3)) -.IP \- 3 +.IP \(bu the .I errno variable -.IP \- 3 +.IP \(bu alternate signal stack .RB ( sigaltstack (2)) -.IP \- 3 +.IP \(bu real-time scheduling policy and priority .RB ( sched (7)) .PP The following Linux-specific features are also per-thread: -.IP \- 3 +.IP \(bu 3 capabilities (see .BR capabilities (7)) -.IP \- 3 +.IP \(bu CPU affinity .RB ( sched_setaffinity (2)) .SS Pthreads function return values @@ -681,14 +681,14 @@ thread joining, and so on) are implemented using the Linux system call. .SS LinuxThreads The notable features of this implementation are the following: -.IP \- 3 +.IP \(bu 3 In addition to the main (initial) thread, and the threads that the program creates using .BR pthread_create (3), the implementation creates a "manager" thread. This thread handles thread creation and termination. (Problems can result if this thread is inadvertently killed.) -.IP \- 3 +.IP \(bu Signals are used internally by the implementation. On Linux 2.2 and later, the first three real-time signals are used (see also @@ -700,7 +700,7 @@ and are used. Applications must avoid the use of whichever set of signals is employed by the implementation. -.IP \- 3 +.IP \(bu Threads do not share process IDs. (In effect, LinuxThreads threads are implemented as processes which share more information than usual, but which do not share a common process ID.) @@ -710,11 +710,11 @@ are visible as separate processes using .PP The LinuxThreads implementation deviates from the POSIX.1 specification in a number of ways, including the following: -.IP \- 3 +.IP \(bu 3 Calls to .BR getpid (2) return a different value in each thread. -.IP \- 3 +.IP \(bu Calls to .BR getppid (2) in threads other than the main thread return the process ID of the @@ -723,7 +723,7 @@ manager thread; instead in these threads should return the same value as .BR getppid (2) in the main thread. -.IP \- 3 +.IP \(bu When one thread creates a new child process using .BR fork (2), any thread should be able to @@ -733,39 +733,39 @@ However, the implementation allows only the thread that created the child to .BR wait (2) on it. -.IP \- 3 +.IP \(bu When a thread calls .BR execve (2), all other threads are terminated (as required by POSIX.1). However, the resulting process has the same PID as the thread that called .BR execve (2): it should have the same PID as the main thread. -.IP \- 3 +.IP \(bu Threads do not share user and group IDs. This can cause complications with set-user-ID programs and can cause failures in Pthreads functions if an application changes its credentials using .BR seteuid (2) or similar. -.IP \- 3 +.IP \(bu Threads do not share a common session ID and process group ID. -.IP \- 3 +.IP \(bu Threads do not share record locks created using .BR fcntl (2). -.IP \- 3 +.IP \(bu The information returned by .BR times (2) and .BR getrusage (2) is per-thread rather than process-wide. -.IP \- 3 +.IP \(bu Threads do not share semaphore undo values (see .BR semop (2)). -.IP \- 3 +.IP \(bu Threads do not share interval timers. -.IP \- 3 +.IP \(bu Threads do not share a common nice value. -.IP \- 3 +.IP \(bu POSIX.1 distinguishes the notions of signals that are directed to the process as a whole and signals that are directed to individual threads. @@ -775,7 +775,7 @@ for example) should be handled by a single, arbitrarily selected thread within the process. LinuxThreads does not support the notion of process-directed signals: signals may be sent only to specific threads. -.IP \- 3 +.IP \(bu Threads have distinct alternate signal stack settings. However, a new thread's alternate signal stack settings are copied from the thread that created it, so that @@ -797,7 +797,7 @@ See for further details. .PP NPTL still has at least one nonconformance with POSIX.1: -.IP \- 3 +.IP \(bu 3 Threads do not share a common nice value. .\" FIXME . bug report filed for NPTL nice nonconformance .\" http://bugzilla.kernel.org/show_bug.cgi?id=6258 @@ -806,26 +806,26 @@ Threads do not share a common nice value. .\" Monitor this to see if it makes it into mainline. .PP Some NPTL nonconformances occur only with older kernels: -.IP \- 3 +.IP \(bu 3 The information returned by .BR times (2) and .BR getrusage (2) is per-thread rather than process-wide (fixed in kernel 2.6.9). -.IP \- 3 +.IP \(bu Threads do not share resource limits (fixed in kernel 2.6.10). -.IP \- 3 +.IP \(bu Threads do not share interval timers (fixed in kernel 2.6.12). -.IP \- 3 +.IP \(bu Only the main thread is permitted to start a new session using .BR setsid (2) (fixed in kernel 2.6.16). -.IP \- 3 +.IP \(bu Only the main thread is permitted to make the process into a process group leader using .BR setpgid (2) (fixed in kernel 2.6.16). -.IP \- 3 +.IP \(bu Threads have distinct alternate signal stack settings. However, a new thread's alternate signal stack settings are copied from the thread that created it, so that @@ -833,7 +833,7 @@ the threads initially share an alternate signal stack (fixed in kernel 2.6.16). .PP Note the following further points about the NPTL implementation: -.IP \- 3 +.IP \(bu 3 If the stack size soft resource limit (see the description of .B RLIMIT_STACK in diff --git a/man7/queue.7 b/man7/queue.7 index 78fb4d33ee..919262b52a 100644 --- a/man7/queue.7 +++ b/man7/queue.7 @@ -30,13 +30,13 @@ CIRCLEQ doubly linked circular queues .PP All structures support the following functionality: -.IP * 3 +.IP \(bu 3 Insertion of a new entry at the head of the list. -.IP * +.IP \(bu Insertion of a new entry after any element in the list. -.IP * +.IP \(bu O(1) removal of an entry from the head of the list. -.IP * +.IP \(bu Forward traversal through the list. .\".IP * .\" Swapping the contents of two lists. @@ -51,21 +51,21 @@ Singly linked lists are ideal for applications with large datasets and few or no removals, or for implementing a LIFO queue. Singly linked lists add the following functionality: -.IP * 3 +.IP \(bu 3 O(n) removal of any entry in the list. .SS Singly linked tail queues (STAILQ) Singly linked tail queues add the following functionality: -.IP * 3 +.IP \(bu 3 Entries can be added at the end of a list. -.IP * +.IP \(bu O(n) removal of any entry in the list. -.IP * +.IP \(bu They may be concatenated. .PP However: -.IP * 3 +.IP \(bu 3 All list insertions must specify the head of the list. -.IP * +.IP \(bu Each head entry requires two pointers rather than one. .PP Singly linked tail queues are ideal for applications with @@ -74,45 +74,45 @@ or for implementing a FIFO queue. .SS Doubly linked data structures All doubly linked types of data structures (lists and tail queues) additionally allow: -.IP * 3 +.IP \(bu 3 Insertion of a new entry before any element in the list. -.IP * +.IP \(bu O(1) removal of any entry in the list. .PP However: -.IP * 3 +.IP \(bu 3 Each element requires two pointers rather than one. .SS Doubly linked lists (LIST) Linked lists are the simplest of the doubly linked data structures. They add the following functionality over the above: -.IP * 3 +.IP \(bu 3 They may be traversed backwards. .PP However: -.IP * 3 +.IP \(bu 3 To traverse backwards, an entry to begin the traversal and the list in which it is contained must be specified. .SS Doubly linked tail queues (TAILQ) Tail queues add the following functionality: -.IP * 3 +.IP \(bu 3 Entries can be added at the end of a list. -.IP * +.IP \(bu They may be traversed backwards, from tail to head. -.IP * +.IP \(bu They may be concatenated. .PP However: -.IP * 3 +.IP \(bu 3 All list insertions and removals must specify the head of the list. -.IP * +.IP \(bu Each head entry requires two pointers rather than one. .SS Doubly linked circular queues (CIRCLEQ) Circular queues add the following functionality over the above: -.IP * 3 +.IP \(bu 3 The first and last entries are connected. .PP However: -.IP * 3 +.IP \(bu 3 The termination condition for traversal is more complex. .SH STANDARDS Not in POSIX.1, POSIX.1-2001, or POSIX.1-2008. diff --git a/man7/random.7 b/man7/random.7 index 9a7e49ee7c..666e133323 100644 --- a/man7/random.7 +++ b/man7/random.7 @@ -18,7 +18,7 @@ a cryptographically secure pseudorandom number generator (CSPRNG). It is designed for security, rather than speed. .PP The following interfaces provide access to output from the kernel CSPRNG: -.IP * 3 +.IP \(bu 3 The .I /dev/urandom and @@ -27,7 +27,7 @@ devices, both described in .BR random (4). These devices have been present on Linux since early times, and are also available on many other systems. -.IP * +.IP \(bu The Linux-specific .BR getrandom (2) system call, available since Linux 3.17. diff --git a/man7/rtld-audit.7 b/man7/rtld-audit.7 index 92ca2f1765..42c1795ea0 100644 --- a/man7/rtld-audit.7 +++ b/man7/rtld-audit.7 @@ -464,11 +464,11 @@ in the chapter .SH NOTES Note the following differences from the Solaris dynamic linker auditing API: -.IP * 3 +.IP \(bu 3 The Solaris .BR la_objfilter () interface is not supported by the GNU implementation. -.IP * +.IP \(bu The Solaris .BR la_symbind32 () and @@ -476,7 +476,7 @@ and functions do not provide a .I symname argument. -.IP * +.IP \(bu The Solaris .BR la_pltexit () function does not provide diff --git a/man7/sched.7 b/man7/sched.7 index 5baf6fad43..8432552157 100644 --- a/man7/sched.7 +++ b/man7/sched.7 @@ -137,15 +137,15 @@ it will always immediately preempt any currently running algorithm without time slicing. For threads scheduled under the \fBSCHED_FIFO\fP policy, the following rules apply: -.IP 1) 3 +.IP \(bu 3 A running \fBSCHED_FIFO\fP thread that has been preempted by another thread of higher priority will stay at the head of the list for its priority and will resume execution as soon as all threads of higher priority are blocked again. -.IP 2) +.IP \(bu When a blocked \fBSCHED_FIFO\fP thread becomes runnable, it will be inserted at the end of the list for its priority. -.IP 3) +.IP \(bu If a call to .BR sched_setscheduler (2), .BR sched_setparam (2), @@ -160,15 +160,15 @@ thread identified by the effect on the thread's position in the list depends on the direction of the change to threads priority: .RS -.IP \(bu 3 +.IP (a) 5 If the thread's priority is raised, it is placed at the end of the list for its new priority. As a consequence, it may preempt a currently running thread with the same priority. -.IP \(bu +.IP (b) If the thread's priority is unchanged, its position in the run list is unchanged. -.IP \(bu +.IP (c) If the thread's priority is lowered, it is placed at the front of the list for its new priority. .RE @@ -180,7 +180,7 @@ should result in the thread being placed at the end of the list for its priority. .\" In 2.2.x and 2.4.x, the thread is placed at the front of the queue .\" In 2.0.x, the Right Thing happened: the thread went to the back -- MTK -.IP 4) +.IP \(bu A thread calling .BR sched_yield (2) will be put at the end of the list. @@ -492,7 +492,7 @@ When this flag is set, children created by .BR fork (2) do not inherit privileged scheduling policies. The reset-on-fork flag can be set by either: -.IP * 3 +.IP \(bu 3 ORing the .B SCHED_RESET_ON_FORK flag into the @@ -501,7 +501,7 @@ argument when calling .BR sched_setscheduler (2) (since Linux 2.6.32); or -.IP * +.IP \(bu specifying the .B SCHED_FLAG_RESET_ON_FORK flag in @@ -524,7 +524,7 @@ by creating multiple child processes. .PP More precisely, if the reset-on-fork flag is set, the following rules apply for subsequently created children: -.IP * 3 +.IP \(bu 3 If the calling thread has a scheduling policy of .B SCHED_FIFO or @@ -532,7 +532,7 @@ or the policy is reset to .B SCHED_OTHER in child processes. -.IP * +.IP \(bu If the calling process has a negative nice value, the nice value is reset to zero in child processes. .PP @@ -571,7 +571,7 @@ and .B SCHED_FIFO policies. The rules for changing scheduling policy and priority are as follows: -.IP * 3 +.IP \(bu 3 If an unprivileged thread has a nonzero .B RLIMIT_RTPRIO soft limit, then it can change its scheduling policy and priority, @@ -579,17 +579,17 @@ subject to the restriction that the priority cannot be set to a value higher than the maximum of its current priority and its .B RLIMIT_RTPRIO soft limit. -.IP * +.IP \(bu If the .B RLIMIT_RTPRIO soft limit is 0, then the only permitted changes are to lower the priority, or to switch to a non-real-time policy. -.IP * +.IP \(bu Subject to the same rules, another unprivileged thread can also make these changes, as long as the effective user ID of the thread making the change matches the real or effective user ID of the target thread. -.IP * +.IP \(bu Special rules apply for the .B SCHED_IDLE policy. @@ -832,11 +832,11 @@ Task groups have a hierarchical relationship, rooted under the initial task group on the system, known as the "root task group". Task groups are formed in the following circumstances: -.IP * 3 +.IP \(bu 3 All of the threads in a CPU cgroup form a task group. The parent of this task group is the task group of the corresponding parent cgroup. -.IP * +.IP \(bu If autogrouping is enabled, then all of the threads that are (implicitly) placed in an autogroup (i.e., the same session, as created by @@ -844,14 +844,14 @@ then all of the threads that are (implicitly) placed in an autogroup form a task group. Each new autogroup is thus a separate task group. The root task group is the parent of all such autogroups. -.IP * +.IP \(bu If autogrouping is enabled, then the root task group consists of all processes in the root CPU cgroup that were not otherwise implicitly placed into a new autogroup. -.IP * +.IP \(bu If autogrouping is disabled, then the root task group consists of all processes in the root CPU cgroup. -.IP * +.IP \(bu If group scheduling was disabled (i.e., the kernel was configured without .BR CONFIG_FAIR_GROUP_SCHED ), then all of the processes on the system are notionally placed diff --git a/man7/signal-safety.7 b/man7/signal-safety.7 index 91e3d5132c..b6a563b919 100644 --- a/man7/signal-safety.7 +++ b/man7/signal-safety.7 @@ -39,13 +39,13 @@ then the second call to will operate on inconsistent data, with unpredictable results. .PP To avoid problems with unsafe functions, there are two possible choices: -.IP 1. 3 +.IP (a) 5 Ensure that -(a) the signal handler calls only async-signal-safe functions, +(1) the signal handler calls only async-signal-safe functions, and -(b) the signal handler itself is reentrant +(2) the signal handler itself is reentrant with respect to global variables in the main program. -.IP 2. +.IP (b) Block signal delivery in the main program when calling functions that are unsafe or operating on global data that is also accessed by the signal handler. @@ -273,14 +273,14 @@ T} .TE .PP Notes: -.IP * 3 +.IP \(bu 3 POSIX.1-2001 and POSIX.1-2001 TC2 required the functions .BR fpathconf (3), .BR pathconf (3), and .BR sysconf (3) to be async-signal-safe, but this requirement was removed in POSIX.1-2008. -.IP * +.IP \(bu If a signal handler interrupts the execution of an unsafe function, and the handler terminates via a call to .BR longjmp (3) @@ -288,7 +288,7 @@ or .BR siglongjmp (3) and the program subsequently calls an unsafe function, then the behavior of the program is undefined. -.IP * +.IP \(bu POSIX.1-2001 TC1 clarified that if an application calls .BR fork (2) @@ -301,7 +301,7 @@ is likely to remove .BR fork (2) from the list of async-signal-safe functions. .\" -.IP * 3 +.IP \(bu Asynchronous signal handlers that call functions which are cancelation points and nest over regions of deferred cancelation may trigger cancelation whose behavior is as if asynchronous cancelation had @@ -317,7 +317,7 @@ on entry and restores its value before returning. .SS Deviations in the GNU C library The following known deviations from the standard occur in the GNU C library: -.IP * 3 +.IP \(bu 3 Before glibc 2.24, .BR execl (3) and @@ -327,7 +327,7 @@ employed internally and were consequently not async-signal-safe. .\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534 This was fixed in glibc 2.24. -.IP * +.IP \(bu .\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172 The glibc implementation of .BR aio_suspend (3) diff --git a/man7/signal.7 b/man7/signal.7 index 98e6e35208..0d5f219275 100644 --- a/man7/signal.7 +++ b/man7/signal.7 @@ -135,7 +135,7 @@ to block execution until the signal is delivered, at which point the kernel returns information about the signal to the caller. There are two general ways to do this: -.IP * 2 +.IP \(bu 3 .BR sigwaitinfo (2), .BR sigtimedwait (2), and @@ -143,7 +143,7 @@ and suspend execution until one of the signals in a specified set is delivered. Each of these calls returns information about the delivered signal. -.IP * +.IP \(bu .BR signalfd (2) returns a file descriptor that can be used to read information about signals that are delivered to the caller. @@ -244,13 +244,13 @@ Whenever there is a transition from kernel-mode to user-mode execution the kernel checks whether there is a pending unblocked signal for which the process has established a signal handler. If there is such a pending signal, the following steps occur: -.IP 1. 3 +.IP (1) 5 The kernel performs the necessary preparatory steps for execution of the signal handler: .RS -.IP a) 3 +.IP (1.1) 7 The signal is removed from the set of pending signals. -.IP b) +.IP (1.2) If the signal handler was installed by a call to .BR sigaction (2) that specified the @@ -258,21 +258,21 @@ that specified the flag and the thread has defined an alternate signal stack (using .BR sigaltstack (2)), then that stack is installed. -.IP c) +.IP (1.3) Various pieces of signal-related context are saved into a special frame that is created on the stack. The saved information includes: .RS -.IP + 2 +.IP \(bu 3 the program counter register (i.e., the address of the next instruction in the main program that should be executed when the signal handler returns); -.IP + +.IP \(bu architecture-specific register state required for resuming the interrupted program; -.IP + +.IP \(bu the thread's current signal mask; -.IP + +.IP \(bu the thread's alternate signal stack settings. .RE .IP @@ -282,7 +282,7 @@ the thread's alternate signal stack settings. flag, then the above information is accessible via the .I ucontext_t object that is pointed to by the third argument of the signal handler.) -.IP d) +.IP (1.4) Any signals specified in .I act\->sa_mask when registering the handler with @@ -294,19 +294,19 @@ added to the signal mask, unless was specified when registering the handler. These signals are thus blocked while the handler executes. .RE -.IP 2. +.IP (2) The kernel constructs a frame for the signal handler on the stack. The kernel sets the program counter for the thread to point to the first instruction of the signal handler function, and configures the return address for that function to point to a piece of user-space code known as the signal trampoline (described in .BR sigreturn (2)). -.IP 3. +.IP (3) The kernel passes control back to user-space, where execution commences at the start of the signal handler function. -.IP 4. +.IP (4) When the signal handler returns, control passes to the signal trampoline code. -.IP 5. +.IP (5) The signal trampoline calls .BR sigreturn (2), a system call that uses the information in the stack frame created in step 1 @@ -511,7 +511,7 @@ SIGUNUSED 31 \- \- 31 .TE .PP Note the following: -.IP * 3 +.IP \(bu 3 Where defined, .B SIGUNUSED is synonymous with @@ -519,7 +519,7 @@ is synonymous with Since glibc 2.26, .B SIGUNUSED is no longer defined on any architecture. -.IP * +.IP \(bu Signal 29 is .BR SIGINFO / SIGPWR (synonyms for the same value) on Alpha but @@ -568,11 +568,11 @@ The default action for an unhandled real-time signal is to terminate the receiving process. .PP Real-time signals are distinguished by the following: -.IP 1. 4 +.IP \(bu 3 Multiple instances of real-time signals can be queued. By contrast, if multiple instances of a standard signal are delivered while that signal is currently blocked, then only one instance is queued. -.IP 2. 4 +.IP \(bu If the signal is sent using .BR sigqueue (3), an accompanying value (either an integer or a pointer) can be sent @@ -592,7 +592,7 @@ and .I si_uid fields of this structure can be used to obtain the PID and real user ID of the process sending the signal. -.IP 3. 4 +.IP \(bu Real-time signals are delivered in a guaranteed order. Multiple real-time signals of the same type are delivered in the order they were sent. @@ -652,9 +652,9 @@ Linux 2.0 and earlier Linux 2.2 and later .SS Interruption of system calls and library functions by signal handlers If a signal handler is invoked while a system call or library function call is blocked, then either: -.IP * 2 +.IP \(bu 3 the call is automatically restarted after the signal handler returns; or -.IP * +.IP \(bu the call fails with the error .BR EINTR . .PP @@ -674,7 +674,7 @@ flag was used; otherwise the call fails with the error .BR EINTR : .\" The following system calls use ERESTARTSYS, .\" so that they are restartable -.IP * 2 +.IP \(bu 3 .BR read (2), .BR readv (2), .BR write (2), @@ -690,18 +690,18 @@ then the call will return a success status (normally, the number of bytes transferred). Note that a (local) disk is not a slow device according to this definition; I/O operations on disk devices are not interrupted by signals. -.IP * +.IP \(bu .BR open (2), if it can block (e.g., when opening a FIFO; see .BR fifo (7)). -.IP * +.IP \(bu .BR wait (2), .BR wait3 (2), .BR wait4 (2), .BR waitid (2), and .BR waitpid (2). -.IP * +.IP \(bu Socket interfaces: .\" If a timeout (setsockopt()) is in effect on the socket, then these .\" system calls switch to using EINTR. Consequently, they and are not @@ -719,7 +719,7 @@ and .BR sendmsg (2), .\" FIXME What about sendmmsg()? unless a timeout has been set on the socket (see below). -.IP * +.IP \(bu File locking interfaces: .BR flock (2) and @@ -729,30 +729,30 @@ and .B F_OFD_SETLKW operations of .BR fcntl (2) -.IP * +.IP \(bu POSIX message queue interfaces: .BR mq_receive (3), .BR mq_timedreceive (3), .BR mq_send (3), and .BR mq_timedsend (3). -.IP * +.IP \(bu .BR futex (2) .B FUTEX_WAIT (since Linux 2.6.22; .\" commit 72c1bbf308c75a136803d2d76d0e18258be14c7a beforehand, always failed with .BR EINTR ). -.IP * +.IP \(bu .BR getrandom (2). -.IP * +.IP \(bu .BR pthread_mutex_lock (3), .BR pthread_cond_wait (3), and related APIs. -.IP * +.IP \(bu .BR futex (2) .BR FUTEX_WAIT_BITSET . -.IP * +.IP \(bu POSIX semaphore interfaces: .BR sem_wait (3) and @@ -761,7 +761,7 @@ and .\" as a consequence of the 2.6.22 changes in the futex() implementation beforehand, always failed with .BR EINTR ). -.IP * +.IP \(bu .BR read (2) from an .BR inotify (7) @@ -780,7 +780,7 @@ they always fail with the error when interrupted by a signal handler: .\" These are the system calls that give EINTR or ERESTARTNOHAND .\" on interruption by a signal handler. -.IP * 2 +.IP \(bu 3 "Input" socket interfaces, when a timeout .RB ( SO_RCVTIMEO ) has been set on the socket using @@ -794,7 +794,7 @@ has been set on the socket using argument), and .BR recvmsg (2). -.IP * +.IP \(bu "Output" socket interfaces, when a timeout .RB ( SO_RCVTIMEO ) has been set on the socket using @@ -805,14 +805,14 @@ has been set on the socket using and .BR sendmsg (2). .\" FIXME What about sendmmsg()? -.IP * +.IP \(bu Interfaces used to wait for signals: .BR pause (2), .BR sigsuspend (2), .BR sigtimedwait (2), and .BR sigwaitinfo (2). -.IP * +.IP \(bu File descriptor multiplexing interfaces: .BR epoll_wait (2), .BR epoll_pwait (2), @@ -821,7 +821,7 @@ File descriptor multiplexing interfaces: .BR select (2), and .BR pselect (2). -.IP * +.IP \(bu System V IPC interfaces: .\" On some other systems, SA_RESTART does restart these system calls .BR msgrcv (2), @@ -829,13 +829,13 @@ System V IPC interfaces: .BR semop (2), and .BR semtimedop (2). -.IP * +.IP \(bu Sleep interfaces: .BR clock_nanosleep (2), .BR nanosleep (2), and .BR usleep (3). -.IP * +.IP \(bu .BR io_getevents (2). .PP The @@ -862,7 +862,7 @@ This behavior is not sanctioned by POSIX.1, and doesn't occur on other systems. .PP The Linux interfaces that display this behavior are: -.IP * 2 +.IP \(bu 3 "Input" socket interfaces, when a timeout .RB ( SO_RCVTIMEO ) has been set on the socket using @@ -876,7 +876,7 @@ has been set on the socket using argument), and .BR recvmsg (2). -.IP * +.IP \(bu "Output" socket interfaces, when a timeout .RB ( SO_RCVTIMEO ) has been set on the socket using @@ -890,33 +890,33 @@ and if a send timeout .RB ( SO_SNDTIMEO ) has been set. -.IP * 2 +.IP \(bu .BR epoll_wait (2), .BR epoll_pwait (2). -.IP * +.IP \(bu .BR semop (2), .BR semtimedop (2). -.IP * +.IP \(bu .BR sigtimedwait (2), .BR sigwaitinfo (2). -.IP * +.IP \(bu Linux 3.7 and earlier: .BR read (2) from an .BR inotify (7) file descriptor .\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06 -.IP * +.IP \(bu Linux 2.6.21 and earlier: .BR futex (2) .BR FUTEX_WAIT , .BR sem_timedwait (3), .BR sem_wait (3). -.IP * +.IP \(bu Linux 2.6.8 and earlier: .BR msgrcv (2), .BR msgsnd (2). -.IP * +.IP \(bu Linux 2.4 and earlier: .BR nanosleep (2). .SH STANDARDS diff --git a/man7/symlink.7 b/man7/symlink.7 index f8147a6ede..01eb17cfbd 100644 --- a/man7/symlink.7 +++ b/man7/symlink.7 @@ -168,12 +168,12 @@ exceeded.) .PP There are three separate areas that need to be discussed. They are as follows: -.IP 1. 3 +.IP \(bu 3 Symbolic links used as filename arguments for system calls. -.IP 2. +.IP \(bu Symbolic links specified as command-line arguments to utilities that are not traversing a file tree. -.IP 3. +.IP \(bu Symbolic links encountered by utilities that are traversing a file tree (either specified on the command line or encountered as part of the file hierarchy walk). @@ -198,7 +198,7 @@ system calls. .PP The treatment of symbolic links within a pathname passed to a system call is as follows: -.IP 1. 3 +.IP (1) 5 Within the dirname component of a pathname, symbolic links are always followed in nearly every system call. (This is also true for commands.) @@ -206,7 +206,7 @@ The one exception is .BR openat2 (2), which provides flags that can be used to explicitly prevent following of symbolic links in the dirname component. -.IP 2. +.IP (2) Except as noted below, all system calls follow symbolic links in the basename component of a pathname. @@ -315,7 +315,7 @@ would change the ownership of itself. .PP There are some exceptions to this rule: -.IP * 2 +.IP \(bu 3 The .BR mv (1) and @@ -325,7 +325,7 @@ but respectively attempt to rename and delete them. (Note, if the symbolic link references a file via a relative path, moving it to another directory may very well cause it to stop working, since the path may no longer be correct.) -.IP * +.IP \(bu The .BR ls (1) command is also an exception to this rule. @@ -355,7 +355,7 @@ and .I \-L options affect its behavior even though it is not doing a walk of a file tree.) -.IP * +.IP \(bu The .BR file (1) command is also an exception to this rule. @@ -415,7 +415,7 @@ walk (where symbolic links that refer to directories are followed). .PP Certain conventions are (should be) followed as consistently as possible by commands that perform file tree walks: -.IP * 2 +.IP \(bu 3 A command can be made to follow any symbolic links named on the command line, regardless of the type of file they reference, by specifying the @@ -444,7 +444,7 @@ flag causes symbolic links specified on the command line to be dereferenced for the purposes of both the action to be performed and the tree walk, and it is as if the user had specified the name of the file to which the symbolic link pointed. -.IP * +.IP \(bu A command can be made to follow any symbolic links named on the command line, as well as any symbolic links encountered during the traversal, @@ -473,7 +473,7 @@ In addition, if any symbolic links are encountered in any file tree that .B chown traverses, they will be treated in the same fashion as .IR slink . -.IP * +.IP \(bu A command can be made to provide the default behavior by specifying the .I \-P @@ -504,7 +504,7 @@ The and .BR rm (1) commands have exceptions to these rules: -.IP * 2 +.IP \(bu 3 The .BR rm (1) command operates on the symbolic link, and not the file it references, @@ -517,7 +517,7 @@ command does not support the or .I \-P options. -.IP * +.IP \(bu To maintain compatibility with historic systems, the .BR ls (1) diff --git a/man7/time_namespaces.7 b/man7/time_namespaces.7 index 7271b17af0..a3032aac38 100644 --- a/man7/time_namespaces.7 +++ b/man7/time_namespaces.7 @@ -8,7 +8,7 @@ time_namespaces \- overview of Linux time namespaces .SH DESCRIPTION Time namespaces virtualize the values of two system clocks: -.IP \(bu 2 +.IP \(bu 3 .B CLOCK_MONOTONIC (and likewise .B CLOCK_MONOTONIC_COARSE @@ -147,7 +147,7 @@ An value is out of range. In particular; .RS -.IP \(bu 2 +.IP \(bu 3 .I offset-secs can't be set to a value which would make the current time on the corresponding clock inside the namespace a negative value; and diff --git a/man7/unicode.7 b/man7/unicode.7 index 86be576fb7..825b470427 100644 --- a/man7/unicode.7 +++ b/man7/unicode.7 @@ -195,7 +195,7 @@ Two other planes are reserved for private usage, plane 15 and plane 16 (Supplementary Private Use Area-B, range 0x100000 to 0x10fffd). .SS Literature -.IP * 3 +.IP \(bu 3 Information technology \(em Universal Multiple-Octet Coded Character Set (UCS) \(em Part 1: Architecture and Basic Multilingual Plane. International Standard ISO/IEC 10646-1, International Organization @@ -205,11 +205,11 @@ This is the official specification of UCS. Available from .UR http://www.iso.ch/ .UE . -.IP * +.IP \(bu The Unicode Standard, Version 3.0. The Unicode Consortium, Addison-Wesley, Reading, MA, 2000, ISBN 0-201-61633-5. -.IP * +.IP \(bu S.\& Harbison, G.\& Steele. C: A Reference Manual. Fourth edition, Prentice Hall, Englewood Cliffs, 1995, ISBN 0-13-326224-3. .IP @@ -219,19 +219,19 @@ edition covers the 1994 Amendment 1 to the ISO C90 standard, which adds a large number of new C library functions for handling wide and multibyte character encodings, but it does not yet cover ISO C99, which improved wide and multibyte character support even further. -.IP * +.IP \(bu Unicode Technical Reports. .RS .UR http://www.unicode.org\:/reports/ .UE .RE -.IP * +.IP \(bu Markus Kuhn: UTF-8 and Unicode FAQ for UNIX/Linux. .RS .UR http://www.cl.cam.ac.uk\:/\(timgk25\:/unicode.html .UE .RE -.IP * +.IP \(bu Bruno Haible: Unicode HOWTO. .RS .UR http://www.tldp.org\:/HOWTO\:/Unicode\-HOWTO.html diff --git a/man7/unix.7 b/man7/unix.7 index 113fef9493..f11a70ebc2 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -166,15 +166,15 @@ bytes of .SS Pathname sockets When binding a socket to a pathname, a few rules should be observed for maximum portability and ease of coding: -.IP * 3 +.IP \(bu 3 The pathname in .I sun_path should be null-terminated. -.IP * +.IP \(bu The length of the pathname, including the terminating null byte, should not exceed the size of .IR sun_path . -.IP * +.IP \(bu The .I addrlen argument that describes the enclosing @@ -598,13 +598,13 @@ For example, suppose that the sender transmits as follows: .PP .RS .PD 0 -.IP 1. 3 +.IP (1) 5 .BR sendmsg (2) of four bytes, with no ancillary data. -.IP 2. +.IP (2) .BR sendmsg (2) of one byte, with ancillary data. -.IP 3. +.IP (3) .BR sendmsg (2) of four bytes, with no ancillary data. .PD diff --git a/man7/uri.7 b/man7/uri.7 index dd9be43cd6..22d4227a73 100644 --- a/man7/uri.7 +++ b/man7/uri.7 @@ -522,11 +522,11 @@ For URIs which must handle characters outside the US ASCII character set, the HTML 4.01 specification (section B.2) and IETF RFC\~3986 (last paragraph of section 2.5) recommend the following approach: -.IP 1. 4 +.IP (1) 5 translate the character sequences into UTF-8 (IETF RFC\~3629)\(emsee .BR utf\-8 (7)\(emand then -.IP 2. +.IP (2) use the URI escaping mechanism, that is, use the %HH encoding for unsafe octets. .SS Writing a URI diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7 index d5dba8fca3..02d3ee01cd 100644 --- a/man7/user_namespaces.7 +++ b/man7/user_namespaces.7 @@ -157,7 +157,7 @@ its original user namespace. .PP The rules for determining whether or not a process has a capability in a particular user namespace are as follows: -.IP 1. 3 +.IP \(bu 3 A process has a capability inside a user namespace if it is a member of that namespace and it has the capability in its effective capability set. @@ -173,11 +173,11 @@ or .BR setns (2), as already described. .\" In the 3.8 sources, see security/commoncap.c::cap_capable(): -.IP 2. +.IP \(bu If a process has a capability in a user namespace, then it has that capability in all child (and further removed descendant) namespaces as well. -.IP 3. +.IP \(bu .\" * The owner of the user namespace in the parent of the .\" * user namespace has all caps. When a user namespace is created, the kernel records the effective @@ -234,29 +234,29 @@ and mount the following types of filesystems: .PP .RS 4 .PD 0 -.IP * 2 +.IP \(bu 3 .I /proc (since Linux 3.8) -.IP * +.IP \(bu .I /sys (since Linux 3.8) -.IP * +.IP \(bu .I devpts (since Linux 3.9) -.IP * +.IP \(bu .BR tmpfs (5) (since Linux 3.9) -.IP * +.IP \(bu .I ramfs (since Linux 3.9) -.IP * +.IP \(bu .I mqueue (since Linux 3.9) -.IP * +.IP \(bu .I bpf .\" commit b2197755b2633e164a439682fb05a9b5ea48f706 (since Linux 4.4) -.IP * +.IP \(bu .I overlayfs .\" commit 92dbc9dedccb9759c7f9f2f0ae6242396376988f .\" commit 4cb2c00c43b3fe88b32f29df4f76da1b92c33224 @@ -397,7 +397,7 @@ The first two numbers specify the starting user ID in each of the two user namespaces. The third number specifies the length of the mapped range. In detail, the fields are interpreted as follows: -.IP (1) 4 +.IP (1) 5 The start of the range of user IDs in the user namespace of the process .IR pid . @@ -410,12 +410,12 @@ and the process .I pid are in the same user namespace, as follows: .RS -.IP a) 3 +.IP (a) 5 If the two processes are in different user namespaces: field two is the start of a range of user IDs in the user namespace of the process that opened .IR uid_map . -.IP b) +.IP (b) If the two processes are in the same user namespace: field two is the start of the range of user IDs in the parent user namespace of the process @@ -499,12 +499,12 @@ The lines written to .I uid_map .RI ( gid_map ) must conform to the following validity rules: -.IP * 3 +.IP \(bu 3 The three fields must be valid numbers, and the last field must be greater than 0. -.IP * +.IP \(bu Lines are terminated by newline characters. -.IP * +.IP \(bu There is a limit on the number of lines in the file. In Linux 4.14 and earlier, this limit was (arbitrarily) .\" 5*12-byte records could fit in a 64B cache line @@ -519,7 +519,7 @@ and the write must be performed at the start of the file (i.e., and .BR pwrite (2) can't be used to write to nonzero offsets in the file). -.IP * +.IP \(bu The range of user IDs (group IDs) specified in each line cannot overlap with the ranges in any other lines. @@ -532,7 +532,7 @@ which prevented some otherwise valid maps from being created. Linux 3.9 and later .\" commit 0bd14b4fd72afd5df41e9fd59f356740f22fceba fix this limitation, allowing any valid set of nonoverlapping maps. -.IP * +.IP \(bu At least one line must be written to the file. .PP Writes that violate the above rules fail with the error @@ -542,32 +542,32 @@ In order for a process to write to the .IR /proc/ pid /uid_map .RI ( /proc/ pid /gid_map ) file, all of the following permission requirements must be met: -.IP 1. 3 +.IP \(bu 3 The writing process must have the .B CAP_SETUID .RB ( CAP_SETGID ) capability in the user namespace of the process .IR pid . -.IP 2. +.IP \(bu The writing process must either be in the user namespace of the process .I pid or be in the parent user namespace of the process .IR pid . -.IP 3. +.IP \(bu The mapped user IDs (group IDs) must in turn have a mapping in the parent user namespace. -.IP 4. +.IP \(bu If updating .IR /proc/ pid /uid_map to create a mapping that maps UID 0 in the parent namespace, then one of the following must be true: .RS -.IP * 3 +.IP (a) 5 if writing process is in the parent user namespace, then it must have the .B CAP_SETFCAP capability in that user namespace; or -.IP * +.IP (b) if the writing process is in the child user namespace, then the process that created the user namespace must have had the .B CAP_SETFCAP @@ -587,21 +587,21 @@ which is needed to create a binary with namespaced file capabilities could nevertheless create such a binary, by the following steps: .RS -.IP * 3 +.IP (1) 5 Create a new user namespace with the identity mapping (i.e., UID 0 in the new user namespace maps to UID 0 in the parent namespace), so that UID 0 in both namespaces is equivalent to the same root user ID. -.IP * +.IP (2) Since the child process has the .B CAP_SETFCAP capability, it could create a binary with namespaced file capabilities that would then be effective in the parent user namespace (because the root user IDs are the same in the two namespaces). .RE -.IP 5. +.IP \(bu One of the following two cases applies: .RS -.IP * 3 +.IP (a) 5 .I Either the writing process has the .B CAP_SETUID @@ -610,16 +610,16 @@ capability in the .I parent user namespace. .RS -.IP + 3 +.IP \(bu 3 No further restrictions apply: the process can make mappings to arbitrary user IDs (group IDs) in the parent user namespace. .RE -.IP * 3 +.IP (b) .I Or otherwise all of the following restrictions apply: .RS -.IP + 3 +.IP \(bu 3 The data written to .I uid_map .RI ( gid_map ) @@ -627,10 +627,10 @@ must consist of a single line that maps the writing process's effective user ID (group ID) in the parent user namespace to a user ID (group ID) in the user namespace. -.IP + +.IP \(bu The writing process must have the same effective user ID as the process that created the user namespace. -.IP + +.IP \(bu In the case of .IR gid_map , use of the @@ -675,12 +675,12 @@ to fail with the error The permission rules for writing to the .IR /proc/ pid /projid_map file are as follows: -.IP 1. 3 +.IP \(bu 3 The writing process must either be in the user namespace of the process .I pid or be in the parent user namespace of the process .IR pid . -.IP 2. +.IP \(bu The mapped project IDs must in turn have a mapping in the parent user namespace. .PP @@ -965,9 +965,9 @@ Within a user namespace, these capabilities allow a process to bypass the rules if the process has the relevant capability over the file, meaning that: -.IP * 3 +.IP \(bu 3 the process has the relevant effective capability in its user namespace; and -.IP * +.IP \(bu the file's user ID and group ID both have valid mappings in the user namespace. .PP diff --git a/man8/ld.so.8 b/man8/ld.so.8 index bcdb2f0abf..5f790323dc 100644 --- a/man8/ld.so.8 +++ b/man8/ld.so.8 @@ -57,17 +57,17 @@ and the shared object is loaded using that pathname. .PP If a shared object dependency does not contain a slash, then it is searched for in the following order: -.IP o 3 +.IP (1) 5 Using the directories specified in the DT_RPATH dynamic section attribute of the binary if present and DT_RUNPATH attribute does not exist. Use of DT_RPATH is deprecated. -.IP o +.IP (2) Using the environment variable .BR LD_LIBRARY_PATH , unless the executable is being run in secure-execution mode (see below), in which case this variable is ignored. -.IP o +.IP (3) Using the directories specified in the DT_RUNPATH dynamic section attribute of the binary if present. @@ -77,7 +77,7 @@ and do not apply to those objects' children, which must themselves have their own DT_RUNPATH entries. This is unlike DT_RPATH, which is applied to searches for all children in the dependency tree. -.IP o +.IP (4) From the cache file .IR /etc/ld.so.cache , which contains a compiled list of candidate shared objects previously found @@ -87,7 +87,7 @@ If, however, the binary was linked with the linker option, shared objects in the default paths are skipped. Shared objects installed in hardware capability directories (see below) are preferred to other shared objects. -.IP o +.IP (5) In the default path .IR /lib , and then @@ -102,13 +102,13 @@ linker option, this step is skipped. .\" .SS Dynamic string tokens In several places, the dynamic linker expands dynamic string tokens: -.IP o 3 +.IP \(bu 3 In the environment variables .BR LD_LIBRARY_PATH , .BR LD_PRELOAD , and .BR LD_AUDIT , -.IP o 3 +.IP \(bu inside the values of the dynamic section tags .BR DT_NEEDED , .BR DT_RPATH , @@ -117,7 +117,7 @@ inside the values of the dynamic section tags and .B DT_DEPAUDIT of ELF binaries, -.IP o 3 +.IP \(bu in the arguments to the .B ld.so command line options @@ -126,7 +126,7 @@ command line options and .B \-\-preload (see below), and -.IP o 3 +.IP \(bu in the filename arguments to the .BR dlopen (3) and @@ -296,15 +296,15 @@ entry in the auxiliary vector (see .BR getauxval (3)) has a nonzero value. This entry may have a nonzero value for various reasons, including: -.IP * 3 +.IP \(bu 3 The process's real and effective user IDs differ, or the real and effective group IDs differ. This typically occurs as a result of executing a set-user-ID or set-group-ID program. -.IP * +.IP \(bu A process with a non-root user ID executed a binary that conferred capabilities to the process. -.IP * +.IP \(bu A nonzero value may have been set by a Linux Security Module. .\" .SS Environment variables @@ -438,7 +438,7 @@ as described above in There are various methods of specifying libraries to be preloaded, and these are handled in the following order: .RS -.IP (1) 4 +.IP (1) 5 The .B LD_PRELOAD environment variable. |