diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:41:07 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:41:07 +0000 |
commit | 3af6d22bb3850ab2bac67287e3a3d3b0e32868e5 (patch) | |
tree | 3ee7a3ec64525911fa865bb984c86d997d855527 /man7 | |
parent | Adding debian version 6.05.01-1. (diff) | |
download | manpages-3af6d22bb3850ab2bac67287e3a3d3b0e32868e5.tar.xz manpages-3af6d22bb3850ab2bac67287e3a3d3b0e32868e5.zip |
Merging upstream version 6.7.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man7')
122 files changed, 3135 insertions, 3691 deletions
diff --git a/man7/address_families.7 b/man7/address_families.7 index 4a75b72..14464be 100644 --- a/man7/address_families.7 +++ b/man7/address_families.7 @@ -3,14 +3,14 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH address_families 7 2023-01-22 "Linux man-pages 6.05.01" +.TH address_families 7 2024-01-28 "Linux man-pages 6.7" .SH NAME address_families \- socket address families (domains) .SH SYNOPSIS .nf .BR "#include <sys/types.h>" " /* See NOTES */" .B #include <sys/socket.h> -.PP +.P .BI "int socket(int " domain ", int " type ", int " protocol ); .fi .SH DESCRIPTION @@ -24,7 +24,9 @@ These families are defined in .IR <sys/socket.h> . The formats currently understood by the Linux kernel include: .TP -.BR AF_UNIX ", " AF_LOCAL +.B AF_UNIX +.TQ +.B AF_LOCAL Local communication. For further information, see .BR unix (7). @@ -77,7 +79,7 @@ For further information, see the .UE . .TP .B AF_X25 -ITU-T X.25 / ISO-8208 protocol. +ITU-T X.25 / ISO/IEC\~8208 protocol. For further information, see .BR x25 (7). .TP @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH AIO 7 2023-05-03 "Linux man-pages 6.05.01" +.TH AIO 7 2023-10-31 "Linux man-pages 6.7" .SH NAME aio \- POSIX asynchronous I/O overview .SH DESCRIPTION @@ -13,7 +13,7 @@ The application can elect to be notified of completion of the I/O operation in a variety of ways: by delivery of a signal, by instantiation of a thread, or no notification at all. -.PP +.P The POSIX AIO interface consists of the following functions: .TP .BR aio_read (3) @@ -49,14 +49,14 @@ file descriptor. .TP .BR lio_listio (3) Enqueue multiple I/O requests using a single function call. -.PP +.P The .I aiocb ("asynchronous I/O control block") structure defines parameters that control an I/O operation. An argument of this type is employed with all of the functions listed above. This structure has the following form: -.PP +.P .in +4n .EX #include <aiocb.h> @@ -81,7 +81,7 @@ struct aiocb { enum { LIO_READ, LIO_WRITE, LIO_NOP }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I aio_fildes @@ -117,13 +117,13 @@ are and .BR SIGEV_THREAD . See -.BR sigevent (7) +.BR sigevent (3type) for further details. .TP .I aio_lio_opcode The type of operation to be performed; used only for .BR lio_listio (3). -.PP +.P In addition to the standard functions listed above, the GNU C library provides the following extension to the POSIX AIO API: .TP @@ -151,11 +151,11 @@ The control block buffer and the buffer pointed to by .I aio_buf must not be changed while the I/O operation is in progress. These buffers must remain valid until the I/O operation completes. -.PP +.P Simultaneous asynchronous read or write operations using the same .I aiocb structure yield undefined results. -.PP +.P The current Linux POSIX AIO implementation is provided in user space by glibc. This has a number of limitations, most notably that maintaining multiple threads to perform I/O operations is expensive and scales poorly. @@ -186,18 +186,18 @@ of a signal. After all I/O requests have completed, the program retrieves their status using .BR aio_return (3). -.PP +.P The .B SIGQUIT signal (generated by typing control-\e) causes the program to request cancelation of each of the outstanding requests using .BR aio_cancel (3). -.PP +.P Here is an example of what we might see when running this program. In this example, the program queues two requests to standard input, and these are satisfied by two lines of input containing "abc" and "x". -.PP +.P .in +4n .EX $ \fB./a.out /dev/stdin /dev/stdin\fP @@ -438,7 +438,7 @@ main(int argc, char *argv[]) .BR aio_return (3), .BR aio_write (3), .BR lio_listio (3) -.PP +.P "Asynchronous I/O Support in Linux 2.5", Bhattacharya, Pratt, Pulavarty, and Morgan, Proceedings of the Linux Symposium, 2003, diff --git a/man7/armscii-8.7 b/man7/armscii-8.7 index 2ef36ab..633c8d6 100644 --- a/man7/armscii-8.7 +++ b/man7/armscii-8.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ARMSCII-8 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ARMSCII-8 7 2022-12-15 "Linux man-pages 6.7" .SH NAME armscii-8 \- Armenian character set encoded in octal, decimal, and hexadecimal @@ -6,7 +6,7 @@ .\" Modified June 1999 Andi Kleen .\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $ .\" -.TH arp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH arp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME arp \- Linux ARP kernel module. .SH DESCRIPTION @@ -17,7 +17,7 @@ and IPv4 protocol addresses on directly connected networks. The user normally doesn't interact directly with this module except to configure it; instead it provides a service for other protocols in the kernel. -.PP +.P A user process can receive ARP packets by using .BR packet (7) sockets. @@ -30,7 +30,7 @@ The ARP table can also be controlled via on any .B AF_INET socket. -.PP +.P The ARP module maintains a cache of mappings between hardware addresses and protocol addresses. The cache has a limited size so old and less @@ -42,7 +42,7 @@ be directly manipulated by the use of ioctls and its behavior can be tuned by the .I /proc interfaces described below. -.PP +.P When there is no positive feedback for an existing mapping after some time (see the .I /proc @@ -65,7 +65,7 @@ If that fails too, it will broadcast a new ARP request to the network. Requests are sent only when there is data queued for sending. -.PP +.P Linux will automatically add a nonpermanent proxy arp entry when it receives a request for an address it forwards to and proxy arp is enabled on the receiving interface. @@ -77,7 +77,7 @@ sockets. They take a pointer to a .I struct arpreq as their argument. -.PP +.P .in +4n .EX struct arpreq { @@ -89,14 +89,14 @@ struct arpreq { }; .EE .in -.PP +.P .BR SIOCSARP ", " SIOCDARP " and " SIOCGARP respectively set, delete, and get an ARP mapping. Setting and deleting ARP maps are privileged operations and may be performed only by a process with the .B CAP_NET_ADMIN capability or an effective UID of 0. -.PP +.P .I arp_pa must be an .B AF_INET @@ -121,7 +121,7 @@ ATF_NETMASK:Use a netmask ATF_DONTPUB:Don't answer .TE .RE -.PP +.P If the .B ATF_NETMASK flag is set, then @@ -272,13 +272,13 @@ changed in Linux 2.0 to include the .I arp_dev member and the ioctl numbers changed at the same time. Support for the old ioctls was dropped in Linux 2.2. -.PP +.P Support for proxy arp entries for networks (netmask not equal 0xffffffff) was dropped in Linux 2.2. It is replaced by automatic proxy arp setup by the kernel for all reachable hosts on other interfaces (when forwarding and proxy arp is enabled for the interface). -.PP +.P The .I neigh/* interfaces did not exist before Linux 2.2. @@ -286,20 +286,20 @@ interfaces did not exist before Linux 2.2. Some timer settings are specified in jiffies, which is architecture- and kernel version-dependent; see .BR time (7). -.PP +.P There is no way to signal positive feedback from user space. This means connection-oriented protocols implemented in user space will generate excessive ARP traffic, because ndisc will regularly reprobe the MAC address. The same problem applies for some kernel protocols (e.g., NFS over UDP). -.PP +.P This man page mashes together functionality that is IPv4-specific with functionality that is shared between IPv4 and IPv6. .SH SEE ALSO .BR capabilities (7), .BR ip (7), .BR arpd (8) -.PP +.P RFC\ 826 for a description of ARP. RFC\ 2461 for a description of IPv6 neighbor discovery and the base algorithms used. diff --git a/man7/ascii.7 b/man7/ascii.7 index 13f5578..19193e1 100644 --- a/man7/ascii.7 +++ b/man7/ascii.7 @@ -13,20 +13,20 @@ .\" Modified 1999-08-08 by Michael Haardt (michael@moria.de) .\" Modified 2004-04-01 by aeb .\" -.TH ascii 7 2023-05-02 "Linux man-pages 6.05.01" +.TH ascii 7 2024-01-28 "Linux man-pages 6.7" .SH NAME ascii \- ASCII character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION ASCII is the American Standard Code for Information Interchange. It is a 7-bit code. -Many 8-bit codes (e.g., ISO 8859-1) contain ASCII as their lower half. -The international counterpart of ASCII is known as ISO 646-IRV. -.PP +Many 8-bit codes (e.g., ISO/IEC\~8859-1) contain ASCII as their lower half. +The international counterpart of ASCII is known as ISO/IEC\~646-IRV. +.P The following table contains the 128 ASCII characters. -.PP +.P C program \f(CW\[aq]\eX\[aq]\fP escapes are noted. -.PP +.P .EX .TS l l l l | l l l l. @@ -100,7 +100,7 @@ _ .EE .SS Tables For convenience, below are more compact tables in hex and decimal. -.PP +.P .EX 2 3 4 5 6 7 30 40 50 60 70 80 90 100 110 120 ------------- --------------------------------- @@ -124,17 +124,17 @@ F: / ? O _ o DEL .SH NOTES .SS History /etc/ascii (VII) appears in the UNIX Programmer's Manual. -.PP +.P On older terminals, the underscore code is displayed as a left arrow, called backarrow, the caret is displayed as an up-arrow and the vertical bar has a hole in the middle. -.PP +.P Uppercase and lowercase characters differ by just one bit and the ASCII character 2 differs from the double quote by just one bit, too. That made it much easier to encode characters mechanically or with a non-microcontroller-based electronic keyboard and that pairing was found on old teletypes. -.PP +.P The ASCII standard was published by the United States of America Standards Institute (USASI) in 1968. .\" diff --git a/man7/attributes.7 b/man7/attributes.7 index b32fe54..838f039 100644 --- a/man7/attributes.7 +++ b/man7/attributes.7 @@ -2,7 +2,7 @@ .\" Written by Alexandre Oliva <aoliva@redhat.com> .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH attributes 7 2023-03-18 "Linux man-pages 6.05.01" +.TH attributes 7 2023-11-01 "Linux man-pages 6.7" .SH NAME attributes \- POSIX safety concepts .SH DESCRIPTION @@ -13,7 +13,7 @@ the text of this man page is based on the material taken from the "POSIX Safety Concepts" section of the GNU C Library manual. Further details on the topics described here can be found in that manual. -.PP +.P Various function manual pages include a section ATTRIBUTES that describes the safety of calling the function in various contexts. This section annotates functions with the following safety markings: @@ -145,7 +145,7 @@ functions are not safe to call in a multithreaded programs. .\" keyword from safety notes. .\" As long as the keyword remains, however, .\" they are not to be regarded as a promise of future behavior. -.PP +.P Other keywords that appear in safety notes are defined in subsequent sections. .\" .\" @@ -470,7 +470,7 @@ in others, they are not even exposed to users. .\" In some cases, such as .\" .BR tmpname (3), .\" the variant is chosen not by calling an alternate entry point, -.\" but by passing a non-NULL pointer to the buffer in which the +.\" but by passing a non-null pointer to the buffer in which the .\" returned values are to be stored. .\" These variants are generally preferable in multi-threaded programs, .\" although some of them are not MT-Safe because of other internal buffers, diff --git a/man7/boot.7 b/man7/boot.7 index f69e8c1..3aa0341 100644 --- a/man7/boot.7 +++ b/man7/boot.7 @@ -10,7 +10,7 @@ .\" .\" Modified 2004-11-03 patch from Martin Schulze <joey@infodrom.org> .\" -.TH boot 7 2023-07-08 "Linux man-pages 6.05.01" +.TH boot 7 2023-10-31 "Linux man-pages 6.7" .SH NAME boot \- System bootup process based on UNIX System V Release 4 .SH DESCRIPTION @@ -27,14 +27,14 @@ kernel root user-space process (\fIinit\fR and \fIinittab\fR) .IP (5) boot scripts -.PP +.P Each of these is described below in more detail. .SS Hardware After power-on or hard reset, control is given to a program stored in read-only memory (normally PROM); for historical reasons involving the personal computer, this program is often called "the \fBBIOS\fR". -.PP +.P This program normally performs a basic self-test of the machine and accesses nonvolatile memory to read further parameters. @@ -43,7 +43,7 @@ battery-backed CMOS memory, so most people refer to it as "the \fBCMOS\fR"; outside of the PC world, it is usually called "the \fBNVRAM\fR" (nonvolatile RAM). -.PP +.P The parameters stored in the NVRAM vary among systems, but as a minimum, they should specify which device can supply an OS loader, or at least which @@ -64,11 +64,11 @@ interactive use, in order to enable specification of an alternative kernel (maybe a backup in case the one last compiled isn't functioning) and to pass optional parameters to the kernel. -.PP +.P In a traditional PC, the OS loader is located in the initial 512-byte block of the boot device; this block is known as "the \fBMBR\fR" (Master Boot Record). -.PP +.P In most systems, the OS loader is very limited due to various constraints. Even on non-PC systems, @@ -76,12 +76,12 @@ there are some limitations on the size and complexity of this loader, but the size limitation of the PC MBR (512 bytes, including the partition table) makes it almost impossible to squeeze much functionality into it. -.PP +.P Therefore, most systems split the role of loading the OS between a primary OS loader and a secondary OS loader; this secondary OS loader may be located within a larger portion of persistent storage, such as a disk partition. -.PP +.P In Linux, the OS loader is often .BR grub (8) (an alternative is @@ -95,13 +95,13 @@ The kernel starts the virtual memory swapper (it is a kernel process, called "kswapd" in a modern Linux kernel), and mounts some filesystem at the root path, .IR / . -.PP +.P Some of the parameters that may be passed to the kernel relate to these activities (for example, the default root filesystem can be overridden); for further information on Linux kernel parameters, read .BR bootparam (7). -.PP +.P Only then does the kernel create the initial userland process, which is given the number 1 as its .B PID @@ -120,7 +120,7 @@ fundamentally different approach known as .BR systemd (1), for which the bootup process is detailed in its associated .BR bootup (7). -.PP +.P When .I /sbin/init starts, it reads @@ -137,12 +137,12 @@ is single-user mode, and run level .B 2 entails running most network services). -.PP +.P The administrator may change the current run level via .BR init (1), and query the current run level via .BR runlevel (8). -.PP +.P However, since it is not convenient to manage individual services by editing this file, .I /etc/inittab @@ -154,7 +154,7 @@ Note: The following description applies to an OS based on UNIX System V Release 4. However, a number of widely used systems (Slackware Linux, FreeBSD, OpenBSD) have a somewhat different scheme for boot scripts. -.PP +.P For each managed service (mail, nfs server, cron, etc.), there is a single startup script located in a specific directory .RI ( /etc/init.d @@ -174,7 +174,7 @@ of the form \fI/etc/rc[0\-6S].d\fR. In each of these directories, there are links (usually symbolic) to the scripts in the \fI/etc/init.d\fR directory. -.PP +.P A primary script (usually \fI/etc/rc\fR) is called from .BR inittab (5); this primary script calls each service's script via a link in the @@ -183,7 +183,7 @@ Each link whose name begins with \[aq]S\[aq] is called with the argument "start" (thereby starting the service). Each link whose name begins with \[aq]K\[aq] is called with the argument "stop" (thereby stopping the service). -.PP +.P To define the starting or stopping order within the same run level, the name of a link contains an \fBorder-number\fR. Also, for clarity, the name of a link usually @@ -195,7 +195,7 @@ service on run level 2. This happens after \fI/etc/rc2.d/S12syslog\fR is run but before \fI/etc/rc2.d/S90xfs\fR is run. -.PP +.P To manage these links is to manage the boot order and run levels; under many systems, there are tools to help with this task (e.g., @@ -209,7 +209,7 @@ inputs without editing an entire boot script, some separate configuration file is used, and is located in a specific directory where an associated boot script may find it (\fI/etc/sysconfig\fR on older Red Hat systems). -.PP +.P In older UNIX systems, such a file contained the actual command line options for a daemon, but in modern Linux systems (and also in HP-UX), it just contains shell variables. diff --git a/man7/bootparam.7 b/man7/bootparam.7 index 5514aca..f9d3c10 100644 --- a/man7/bootparam.7 +++ b/man7/bootparam.7 @@ -6,7 +6,7 @@ .\" (dated v1.0.1, 15/08/95). .\" Major update, aeb, 970114. .\" -.TH bootparam 7 2023-02-05 "Linux man-pages 6.05.01" +.TH bootparam 7 2023-10-31 "Linux man-pages 6.7" .SH NAME bootparam \- introduction to boot time parameters of the Linux kernel .SH DESCRIPTION @@ -16,7 +16,7 @@ In general, this is used to supply the kernel with information about hardware parameters that the kernel would not be able to determine on its own, or to avoid/override the values that the kernel would otherwise detect. -.PP +.P When the kernel is booted directly by the BIOS, you have no opportunity to specify any parameters. So, in order to take advantage of this possibility you have to @@ -25,13 +25,13 @@ use a boot loader that is able to pass parameters, such as GRUB. The kernel command line is parsed into a list of strings (boot arguments) separated by spaces. Most of the boot arguments have the form: -.PP +.P .in +4n .EX name[=value_1][,value_2]...[,value_10] .EE .in -.PP +.P where 'name' is a unique keyword that is used to identify what part of the kernel the associated values (if any) are to be given to. Note the limit of 10 is real, as the present code handles only 10 comma @@ -39,14 +39,14 @@ separated parameters per keyword. (However, you can reuse the same keyword with up to an additional 10 parameters in unusually complicated situations, assuming the setup function supports it.) -.PP +.P Most of the sorting is coded in the kernel source file .IR init/main.c . First, the kernel checks to see if the argument is any of the special arguments 'root=', \&'nfsroot=', 'nfsaddrs=', 'ro', 'rw', 'debug', or 'init'. The meaning of these special arguments is described below. -.PP +.P Then it walks a list of setup functions to see if the specified argument string (such as 'foo') has been associated with a setup function ('foo_setup()') for a particular @@ -57,13 +57,13 @@ if 'foo' was registered. If it was, then it would call the setup function associated with 'foo' (foo_setup()) and hand it the arguments 3, 4, 5, and 6 as given on the kernel command line. -.PP +.P Anything of the form 'foo=bar' that is not accepted as a setup function as described above is then interpreted as an environment variable to be set. A (useless?) example would be to use 'TERM=vt100' as a boot argument. -.PP +.P Any remaining arguments that were not picked up by the kernel and were not interpreted as environment variables are then passed onto PID 1, which is usually the @@ -376,12 +376,12 @@ the last process that used it has closed .IR /dev/initrd .) .SS Boot arguments for SCSI devices General notation for this section: -.PP +.P .I iobase -- the first I/O port that the SCSI host occupies. These are specified in hexadecimal notation, and usually lie in the range from 0x200 to 0x3ff. -.PP +.P .I irq -- the hardware interrupt that the card is configured to use. Valid values will be dependent on the card in question, but will @@ -389,7 +389,7 @@ usually be 5, 7, 9, 10, 11, 12, and 15. The other values are usually used for common peripherals like IDE hard disks, floppies, serial ports, and so on. -.PP +.P .I scsi\-id -- the ID that the host adapter uses to identify itself on the SCSI bus. @@ -397,7 +397,7 @@ Only some host adapters allow you to change this value, as most have it permanently specified internally. The usual default value is 7, but the Seagate and Future Domain TMC-950 boards use 6. -.PP +.P .I parity -- whether the SCSI host adapter expects the attached devices to supply a parity value with all information exchanges. @@ -553,33 +553,33 @@ geometry parameters of the second disk. Different drivers make use of different parameters, but they all at least share having an IRQ, an I/O port base value, and a name. In its most generic form, it looks something like this: -.PP +.P .in +4n .EX ether=irq,iobase[,param_1[,...param_8]],name .EE .in -.PP +.P The first nonnumeric argument is taken as the name. The param_n values (if applicable) usually have different meanings for each different card/driver. Typical param_n values are used to specify things like shared memory address, interface selection, DMA channel and the like. -.PP +.P The most common use of this parameter is to force probing for a second ethercard, as the default is to probe only for one. This can be accomplished with a simple: -.PP +.P .in +4n .EX ether=0,0,eth1 .EE .in -.PP +.P Note that the values of zero for the IRQ and I/O base in the above example tell the driver(s) to autoprobe. -.PP +.P The Ethernet-HowTo has extensive documentation on using multiple cards and on the card/driver-specific implementation of the param_n values where used. @@ -604,25 +604,25 @@ It is described in the Linux kernel source file in older kernel versions). It accepts a boot argument of the form: -.PP +.P .in +4n .EX sound=device1[,device2[,device3...[,device10]]] .EE .in -.PP +.P where each deviceN value is of the following format 0xTaaaId and the bytes are used as follows: -.PP +.P T \- device type: 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16, 7=SB16-MPU401 -.PP +.P aaa \- I/O address in hex. -.PP +.P I \- interrupt line in hex (i.e., 10=a, 11=b, ...) -.PP +.P d \- DMA channel. -.PP +.P As you can see, it gets pretty messy, and you are better off to compile in your own personal values as recommended. Using a boot argument of @@ -659,6 +659,6 @@ lp=0. .SH SEE ALSO .BR klogd (8), .BR mount (8) -.PP +.P For up-to-date information, see the kernel source file .IR Documentation/admin\-guide/kernel\-parameters.txt . diff --git a/man7/bpf-helpers.7 b/man7/bpf-helpers.7 index 26ddf83..b4236f1 100644 --- a/man7/bpf-helpers.7 +++ b/man7/bpf-helpers.7 @@ -27,18 +27,18 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BPF-HELPERS" 7 "2023-04-11" "Linux v6.2" +.TH "BPF-HELPERS" 7 "2023-11-10" "Linux v6.8" .SH NAME BPF-HELPERS \- list of eBPF helper functions .\" Copyright (C) All BPF authors and contributors from 2014 to present. . .\" See git log include/uapi/linux/bpf.h in kernel tree for details. . -.\" +.\" . -.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" SPDX-License-Identifier: Linux-man-pages-copyleft . -.\" +.\" . .\" Please do not edit this file. It was generated from the documentation . @@ -156,27 +156,25 @@ Current \fIktime\fP\&. .B Description This helper is a \(dqprintk()\-like\(dq facility for debugging. It prints a message defined by format \fIfmt\fP (of size \fIfmt_size\fP) -to file \fI/sys/kernel/debug/tracing/trace\fP from DebugFS, if +to file \fI/sys/kernel/tracing/trace\fP from TraceFS, if available. It can take up to three additional \fBu64\fP arguments (as an eBPF helpers, the total number of arguments is limited to five). .sp Each time the helper is called, it appends a line to the trace. -Lines are discarded while \fI/sys/kernel/debug/tracing/trace\fP is -open, use \fI/sys/kernel/debug/tracing/trace_pipe\fP to avoid this. +Lines are discarded while \fI/sys/kernel/tracing/trace\fP is +open, use \fI/sys/kernel/tracing/trace_pipe\fP to avoid this. The format of the trace is customizable, and the exact output one will get depends on the options set in -\fI/sys/kernel/debug/tracing/trace_options\fP (see also the +\fI/sys/kernel/tracing/trace_options\fP (see also the \fIREADME\fP file under the same directory). However, it usually defaults to something like: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C -telnet\-470 [001] .N.. 419421.045894: 0x00000001: <fmt> -.ft P -.fi +.EX +telnet\-470 [001] .N.. 419421.045894: 0x00000001: <formatted msg> +.EE .UNINDENT .UNINDENT .sp @@ -204,7 +202,8 @@ are set. \fB0x00000001\fP is a fake value used by BPF for the instruction pointer register. .IP \(bu 2 -\fB<fmt>\fP is the message formatted with \fIfmt\fP\&. +\fB<formatted msg>\fP is the message formatted with +\fIfmt\fP\&. .UNINDENT .UNINDENT .UNINDENT @@ -404,7 +403,9 @@ performed again, if the helper is used in combination with direct packet access. .TP .B Return -0 on success, or a negative error in case of failure. +0 on success, or a negative error in case of failure. Positive +error indicates a potential drop or congestion in the target +device. The particular positive error codes are not defined. .UNINDENT .TP .B \fBu64 bpf_get_current_pid_tgid(void)\fP @@ -541,8 +542,7 @@ remote ends with IPv4 address other than 10.0.0.1: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX int ret; struct bpf_tunnel_key key = {}; @@ -554,8 +554,7 @@ if (key.remote_ipv4 != 0x0a000001) return TC_ACT_SHOT; // drop packet return TC_ACT_OK; // accept packet -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -600,20 +599,22 @@ sequence number should be added to tunnel header before sending the packet. This flag was added for GRE encapsulation, but might be used with other protocols as well in the future. +.TP +.B \fBBPF_F_NO_TUNNEL_KEY\fP +Add a flag to tunnel metadata indicating that no tunnel +key should be set in the resulting tunnel header. .UNINDENT .sp Here is a typical usage on the transmit path: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX struct bpf_tunnel_key key; populate key ... bpf_skb_set_tunnel_key(skb, &key, sizeof(key), 0); bpf_clone_redirect(skb, vxlan_dev_ifindex, 0); -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -827,11 +828,9 @@ user stacks (such as stacks for Java programs). To do so, use: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # sysctl kernel.perf_event_max_stack=<new value> -.ft P -.fi +.EE .UNINDENT .UNINDENT .TP @@ -1334,8 +1333,8 @@ The option value of length \fIoptlen\fP is pointed by \fIoptval\fP\&. .IP \(bu 2 \fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. .IP \(bu 2 -\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP -and \fBBPF_CGROUP_INET6_CONNECT\fP\&. +\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP, +\fBBPF_CGROUP_INET6_CONNECT\fP and \fBBPF_CGROUP_UNIX_CONNECT\fP\&. .UNINDENT .sp This helper actually implements a subset of \fBsetsockopt()\fP\&. @@ -1417,6 +1416,11 @@ type; \fIlen\fP is the length of the inner MAC header. \fBBPF_F_ADJ_ROOM_ENCAP_L2_ETH\fP: Use with BPF_F_ADJ_ROOM_ENCAP_L2 flag to further specify the L2 type as Ethernet. +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_DECAP_L3_IPV4\fP, +\fBBPF_F_ADJ_ROOM_DECAP_L3_IPV6\fP: +Indicate the new IP header version after decapsulating the outer +IP header. Used when the inner and outer IP versions are different. .UNINDENT .sp A call to this helper is susceptible to change the underlying @@ -1572,11 +1576,9 @@ as follows. .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX normalized_counter = counter * t_enabled / t_running -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -1596,7 +1598,7 @@ value and do the calculation inside the eBPF program. .INDENT 7.0 .TP .B Description -For en eBPF program attached to a perf event, retrieve the +For an eBPF program attached to a perf event, retrieve the value of the event counter associated to \fIctx\fP and store it in the structure pointed by \fIbuf\fP and of size \fIbuf_size\fP\&. Enabled and running times are also stored in the structure (see @@ -1623,8 +1625,8 @@ The retrieved value is stored in the structure pointed by .IP \(bu 2 \fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. .IP \(bu 2 -\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP -and \fBBPF_CGROUP_INET6_CONNECT\fP\&. +\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP, +\fBBPF_CGROUP_INET6_CONNECT\fP and \fBBPF_CGROUP_UNIX_CONNECT\fP\&. .UNINDENT .sp This helper actually implements a subset of \fBgetsockopt()\fP\&. @@ -1945,11 +1947,9 @@ user stacks (such as stacks for Java programs). To do so, use: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # sysctl kernel.perf_event_max_stack=<new value> -.ft P -.fi +.EE .UNINDENT .UNINDENT .TP @@ -2010,9 +2010,26 @@ following values: Do a direct table lookup vs full lookup using FIB rules. .TP +.B \fBBPF_FIB_LOOKUP_TBID\fP +Used with BPF_FIB_LOOKUP_DIRECT. +Use the routing table ID present in \fIparams\fP\->tbid +for the fib lookup. +.TP .B \fBBPF_FIB_LOOKUP_OUTPUT\fP Perform lookup from an egress perspective (default is ingress). +.TP +.B \fBBPF_FIB_LOOKUP_SKIP_NEIGH\fP +Skip the neighbour table lookup. \fIparams\fP\->dmac +and \fIparams\fP\->smac will not be set as output. A common +use case is to call \fBbpf_redirect_neigh\fP() after +doing \fBbpf_fib_lookup\fP(). +.TP +.B \fBBPF_FIB_LOOKUP_SRC\fP +Derive and set source IP addr in \fIparams\fP\->ipv{4,6}_src +for the nexthop. If the src addr cannot be derived, +\fBBPF_FIB_LKUP_RET_NO_SRC_ADDR\fP is returned. In this +case, \fIparams\fP\->dmac and \fIparams\fP\->smac are not set either. .UNINDENT .sp \fIctx\fP is either \fBstruct xdp_md\fP for XDP programs or @@ -3029,24 +3046,20 @@ get its length at runtime. See the following snippet: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX SEC(\(dqkprobe/sys_open\(dq) void bpf_sys_open(struct pt_regs *ctx) { char buf[PATHLEN]; // PATHLEN is defined to 256 - int res; - - res = bpf_probe_read_user_str(buf, sizeof(buf), - ctx\->di); + int res = bpf_probe_read_user_str(buf, sizeof(buf), + ctx\->di); // Consume buf, for example push it to // userspace via bpf_perf_event_output(); we // can use res (the string length) as event // size, after checking its boundaries. } -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -3253,9 +3266,6 @@ The \fIflags\fP argument must be zero. .sp \fB\-EOPNOTSUPP\fP if the operation is not supported, for example a call from outside of TC ingress. -.sp -\fB\-ESOCKTNOSUPPORT\fP if the socket type is not supported -(reuseport). .UNINDENT .TP .B \fBlong bpf_sk_assign(struct bpf_sk_lookup *\fP\fIctx\fP\fB, struct bpf_sock *\fP\fIsk\fP\fB, u64\fP \fIflags\fP\fB)\fP @@ -3605,6 +3615,8 @@ Dynamically cast a \fIsk\fP pointer to a \fIudp6_sock\fP pointer. .TP .B Description Return a user or a kernel stack in bpf program provided buffer. +Note: the user stack will only be populated if the \fItask\fP is +the current task; all other tasks will return \-EOPNOTSUPP. To achieve this, the helper needs \fItask\fP, which is a valid pointer to \fBstruct task_struct\fP\&. To store the stacktrace, the bpf program provides \fIbuf\fP with a nonnegative \fIsize\fP\&. @@ -3617,6 +3629,7 @@ the following flags: .TP .B \fBBPF_F_USER_STACK\fP Collect a user space stack instead of a kernel stack. +The \fItask\fP must be the current task. .TP .B \fBBPF_F_USER_BUILD_ID\fP Collect buildid+offset instead of ips for user stack, @@ -3632,11 +3645,9 @@ user stacks (such as stacks for Java programs). To do so, use: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # sysctl kernel.perf_event_max_stack=<new value> -.ft P -.fi +.EE .UNINDENT .UNINDENT .TP @@ -4334,6 +4345,17 @@ The map can contain timers that invoke callback_fn\-s from different programs. The same callback_fn can serve different timers from different maps if key/value layout matches across maps. Every bpf_timer_set_callback() can have different callback_fn. +.sp +\fIflags\fP can be one of: +.INDENT 7.0 +.TP +.B \fBBPF_F_TIMER_ABS\fP +Start the timer in absolute expire value instead of the +default relative one. +.TP +.B \fBBPF_F_TIMER_CPU_PIN\fP +Timer will be pinned to the CPU of the caller. +.UNINDENT .TP .B Return 0 on success. @@ -4360,10 +4382,14 @@ own timer which would have led to a deadlock otherwise. .TP .B Description Get address of the traced function (for tracing and kprobe programs). +.sp +When called for kprobe program attached as uprobe it returns +probe address for both entry and return uprobe. .TP .B Return -Address of the traced function. +Address of the traced function for kprobe. 0 for kprobes placed within the function (not at the entry). +Address of the probe for uprobe and return uprobe. .UNINDENT .TP .B \fBu64 bpf_get_attach_cookie(void *\fP\fIctx\fP\fB)\fP @@ -4817,12 +4843,28 @@ of \fIsrc\fP\(aqs data, \-EINVAL if \fIsrc\fP is an invalid dynptr or if .B Description Write \fIlen\fP bytes from \fIsrc\fP into \fIdst\fP, starting from \fIoffset\fP into \fIdst\fP\&. -\fIflags\fP is currently unused. +.sp +\fIflags\fP must be 0 except for skb\-type dynptrs. +.INDENT 7.0 +.TP +.B For skb\-type dynptrs: +.INDENT 7.0 +.IP \(bu 2 +All data slices of the dynptr are automatically +invalidated after \fBbpf_dynptr_write\fP(). This is +because writing may pull the skb and change the +underlying packet buffer. +.IP \(bu 2 +For \fIflags\fP, please see the flags accepted by +\fBbpf_skb_store_bytes\fP(). +.UNINDENT +.UNINDENT .TP .B Return 0 on success, \-E2BIG if \fIoffset\fP + \fIlen\fP exceeds the length of \fIdst\fP\(aqs data, \-EINVAL if \fIdst\fP is an invalid dynptr or if \fIdst\fP -is a read\-only dynptr or if \fIflags\fP is not 0. +is a read\-only dynptr or if \fIflags\fP is not correct. For skb\-type dynptrs, +other errors correspond to errors returned by \fBbpf_skb_store_bytes\fP(). .UNINDENT .TP .B \fBvoid *bpf_dynptr_data(const struct bpf_dynptr *\fP\fIptr\fP\fB, u32\fP \fIoffset\fP\fB, u32\fP \fIlen\fP\fB)\fP @@ -4833,6 +4875,9 @@ Get a pointer to the underlying dynptr data. .sp \fIlen\fP must be a statically known value. The returned data slice is invalidated whenever the dynptr is invalidated. +.sp +skb and xdp type dynptrs may not use bpf_dynptr_data. They should +instead use bpf_dynptr_slice and bpf_dynptr_slice_rdwr. .TP .B Return Pointer to the underlying dynptr data, NULL if the dynptr is @@ -5049,7 +5094,7 @@ eBPF programs can have an associated license, passed along with the bytecode instructions to the kernel when the programs are loaded. The format for that string is identical to the one in use for kernel modules (Dual licenses, such as \(dqDual BSD/GPL\(dq, may be used). Some helper functions are only accessible to -programs that are compatible with the GNU Privacy License (GPL). +programs that are compatible with the GNU General Public License (GNU GPL). .sp In order to use such helpers, the eBPF program must be loaded with the correct license string passed (via \fBattr\fP) to the \fBbpf\fP() system call, and this @@ -5058,11 +5103,9 @@ similar to the following: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX char ____license[] __attribute__((section(\(dqlicense\(dq), used)) = \(dqGPL\(dq; -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH IMPLEMENTATION diff --git a/man7/capabilities.7 b/man7/capabilities.7 index c8766d2..ad087f9 100644 --- a/man7/capabilities.7 +++ b/man7/capabilities.7 @@ -25,7 +25,7 @@ .\" other capabilities where the permitted or inheritable bit is set. .\" 2011-09-07, mtk/Serge hallyn: Add CAP_SYSLOG .\" -.TH Capabilities 7 2023-05-03 "Linux man-pages 6.05.01" +.TH Capabilities 7 2024-02-25 "Linux man-pages 6.7" .SH NAME capabilities \- overview of Linux capabilities .SH DESCRIPTION @@ -40,7 +40,7 @@ Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (usually: effective UID, effective GID, and supplementary group list). -.PP +.P Starting with Linux 2.2, Linux divides the privileges traditionally associated with superuser into distinct units, known as .IR capabilities , @@ -832,7 +832,7 @@ be changed and retrieved. .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 +.P Before Linux 2.6.24, only the first two of these requirements are met; since Linux 2.6.24, all three requirements are met. .\" @@ -961,7 +961,7 @@ capabilities to increase during an .BR execve (2), this does not trigger the secure-execution mode described in .BR ld.so (8). -.PP +.P A child created via .BR fork (2) inherits copies of its parent's capability sets. @@ -970,13 +970,13 @@ For details on how affects capabilities, see .I Transformation of capabilities during execve() below. -.PP +.P Using .BR capset (2), a thread may manipulate its own capability sets; see .I Programmatically adjusting capability sets below. -.PP +.P Since Linux 3.2, the file .I /proc/sys/kernel/cap_last_cap .\" commit 73efc0394e148d0e15583e13712637831f926720 @@ -1002,7 +1002,7 @@ The file capability sets, in conjunction with the capability sets of the thread, determine the capabilities of a thread after an .BR execve (2). -.PP +.P The three file capability sets are: .TP .IR Permitted " (formerly known as " forced ): @@ -1084,7 +1084,7 @@ with version 2 capabilities; that is, on a modern Linux system, there may be some files with version 2 capabilities while others have version 3 capabilities. -.PP +.P Before Linux 4.14, the only kind of file capability extended attribute that could be attached to a file was a @@ -1095,7 +1095,7 @@ the version of the .I security.capability extended attribute that is attached to a file depends on the circumstances in which the attribute was created. -.PP +.P Starting with Linux 4.14, a .I security.capability extended attribute is automatically created as (or converted to) @@ -1115,13 +1115,13 @@ meaning that (a) the thread has the capability in its own user namespace; and (b) the UID and GID of the file inode have mappings in the writer's user namespace. -.PP +.P When a .B VFS_CAP_REVISION_3 .I security.capability extended attribute is created, the root user ID of the creating thread's user namespace is saved in the extended attribute. -.PP +.P By contrast, creating or modifying a .I security.capability extended attribute from a privileged @@ -1132,7 +1132,7 @@ namespace where the underlying filesystem was mounted automatically results in the creation of a version 2 .RB ( VFS_CAP_REVISION_2 ) attribute. -.PP +.P Note that the creation of a version 3 .I security.capability extended attribute is automatic. @@ -1161,7 +1161,7 @@ and in order for those tools to be used to create and retrieve version 3 .I security.capability attributes. -.PP +.P Note that a file can have either a version 2 or a version 3 .I security.capability extended attribute associated with it, but not both: @@ -1176,7 +1176,7 @@ During an .BR execve (2), the kernel calculates the new capabilities of the process using the following algorithm: -.PP +.P .in +4n .EX P'(ambient) = (file is privileged) ? 0 : P(ambient) @@ -1191,7 +1191,7 @@ P'(inheritable) = P(inheritable) [i.e., unchanged] P'(bounding) = P(bounding) [i.e., unchanged] .EE .in -.PP +.P where: .RS 4 .TP @@ -1206,7 +1206,7 @@ denotes the value of a thread capability set after the F() denotes a file capability set .RE -.PP +.P Note the following details relating to the above capability transformation rules: .IP \[bu] 3 @@ -1222,7 +1222,7 @@ That system-wide value was employed to calculate the new permitted set during .BR execve (2) in the same manner as shown above for .IR P(bounding) . -.PP +.P .IR Note : during the capability transitions described above, file capabilities may be ignored (treated as empty) for the same reasons @@ -1231,7 +1231,7 @@ that the set-user-ID and set-group-ID bits are ignored; see File capabilities are similarly ignored if the kernel was booted with the .I no_file_caps option. -.PP +.P .IR Note : according to the rules above, if a process with nonzero user IDs performs an @@ -1259,7 +1259,7 @@ so that the file permitted capabilities are automatically enabled in the process effective set when executing the file. The kernel recognizes a file which has the effective capability bit set as capability-dumb for the purpose of the check described here. -.PP +.P When executing a capability-dumb binary, the kernel checks if the process obtained all permitted capabilities that were specified in the file permitted set, @@ -1288,7 +1288,7 @@ In order to mirror traditional UNIX semantics, the kernel performs special treatment of file capabilities when a process with UID 0 (root) executes a program and when a set-user-ID-root program is executed. -.PP +.P After having performed any changes to the process effective ID that were triggered by the set-user-ID mode bit of the binary\[em]e.g., switching the effective user ID to 0 (root) because @@ -1306,12 +1306,12 @@ below.) 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). -.PP +.P These notional values for the file's capability sets are then used as described above to calculate the transformation of the process's capabilities during .BR execve (2). -.PP +.P Thus, when a process with nonzero UIDs .BR execve (2)s a set-user-ID-root program that does not have capabilities attached, @@ -1319,7 +1319,7 @@ or when a process whose real and effective UIDs are zero .BR execve (2)s a program, the calculation of the process's new permitted capabilities simplifies to: -.PP +.P .in +4n .EX P'(permitted) = P(inheritable) | P(bounding) @@ -1327,14 +1327,14 @@ P'(permitted) = P(inheritable) | P(bounding) P'(effective) = P'(permitted) .EE .in -.PP +.P Consequently, the process gains all capabilities in its permitted and effective capability sets, except those masked out by the capability bounding set. (In the calculation of P'(permitted), the P'(ambient) term can be simplified away because it is by definition a proper subset of P(inheritable).) -.PP +.P The special treatments of user ID 0 (root) described in this subsection can be disabled using the securebits mechanism described below. .\" @@ -1358,7 +1358,7 @@ the process gains just the capabilities granted by the program (i.e., not all capabilities, as would occur when executing a set-user-ID-root program that does not have any associated file capabilities). -.PP +.P Note that one can assign empty capability sets to a program file, and thus it is possible to create a set-user-ID-root program that changes the effective and saved set-user-ID of the process @@ -1390,29 +1390,29 @@ and thereby cannot have this capability preserved in its permitted set when it .BR execve (2)s a file that has the capability in its inheritable set. -.PP +.P Note that the bounding set masks the file permitted capabilities, but not the inheritable capabilities. If a thread maintains a capability in its inheritable set that is not in its bounding set, then it can still gain that capability in its permitted set by executing a file that has the capability in its inheritable set. -.PP +.P Depending on the kernel version, the capability bounding set is either a system-wide attribute, or a per-process attribute. -.PP +.P .B "Capability bounding set from Linux 2.6.25 onward" -.PP +.P From Linux 2.6.25, the .I "capability bounding set" is a per-thread attribute. (The system-wide capability bounding set described below no longer exists.) -.PP +.P The bounding set is inherited at .BR fork (2) from the thread's parent, and is preserved across an .BR execve (2). -.PP +.P A thread may remove capabilities from its capability bounding set using the .BR prctl (2) .B PR_CAPBSET_DROP @@ -1425,7 +1425,7 @@ A thread can determine if a capability is in its bounding set using the .BR prctl (2) .B PR_CAPBSET_READ operation. -.PP +.P Removing capabilities from the bounding set is supported only if file capabilities are compiled into the kernel. Before Linux 2.6.33, @@ -1445,14 +1445,14 @@ begins with a full bounding set minus .BR CAP_SETPCAP , because this capability has a different meaning when there are no file capabilities. -.PP +.P Removing a capability from the bounding set does not remove it from the thread's inheritable set. However it does prevent the capability from being added back into the thread's inheritable set in the future. -.PP +.P .B "Capability bounding set prior to Linux 2.6.25" -.PP +.P Before Linux 2.6.25, the capability bounding set is a system-wide attribute that affects all threads on the system. The bounding set is accessible via the file @@ -1460,14 +1460,14 @@ The bounding set is accessible via the file (Confusingly, this bit mask parameter is expressed as a signed decimal number in .IR /proc/sys/kernel/cap\-bound .) -.PP +.P Only the .B init process may set capabilities in the capability bounding set; other than that, the superuser (more precisely: a process with the .B CAP_SYS_MODULE capability) may only clear capabilities from this set. -.PP +.P On a standard system the capability bounding set always masks out the .B CAP_SETPCAP capability. @@ -1476,7 +1476,7 @@ To remove this restriction (dangerous!), modify the definition of in .I include/linux/capability.h and rebuild the kernel. -.PP +.P The system-wide capability bounding set feature was added to Linux 2.2.11. .\" @@ -1521,7 +1521,7 @@ and If the filesystem UID is changed from nonzero to 0, then any of these capabilities that are enabled in the permitted set are enabled in the effective set. -.PP +.P If a thread that has a 0 value for one or more of its user IDs wants to prevent its permitted capability set being cleared when it resets all of its user IDs to nonzero values, it can do so using the @@ -1625,7 +1625,7 @@ Setting this flag disallows raising ambient capabilities via the .BR prctl (2) .B PR_CAP_AMBIENT_RAISE operation. -.PP +.P Each of the above "base" flags has a companion "locked" flag. Setting any of the "locked" flags is irreversible, and has the effect of preventing further changes to the @@ -1636,7 +1636,7 @@ The locked flags are: .BR SECBIT_NOROOT_LOCKED , and .BR SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED . -.PP +.P The .I securebits flags can be modified and retrieved using the @@ -1653,7 +1653,7 @@ Note that the constants are available only after including the .I <linux/securebits.h> header file. -.PP +.P The .I securebits flags are inherited by child processes. @@ -1662,12 +1662,12 @@ During an all of the flags are preserved, except .B SECBIT_KEEP_CAPS which is always cleared. -.PP +.P An application can use the following call to lock itself, and all of its descendants, into an environment where the only way of gaining capabilities is by executing a program with associated file capabilities: -.PP +.P .in +4n .EX prctl(PR_SET_SECUREBITS, @@ -1683,13 +1683,13 @@ prctl(PR_SET_SECUREBITS, .in .\" .\" -.SS Per-user-namespace """set-user-ID-root""" programs +.SS Per-user-namespace \[dq]set-user-ID-root\[dq] programs A set-user-ID program whose UID matches the UID that created a user namespace will confer capabilities in the process's permitted and effective sets when executed by any process inside that namespace or any descendant user namespace. -.PP +.P The rules about the transformation of the process's capabilities during the .BR execve (2) are exactly as described in @@ -1710,7 +1710,7 @@ it gains the associated capabilities (within its user namespace) as per the rules described in .I Transformation of capabilities during execve() above. -.PP +.P Because version 2 file capabilities confer capabilities to the executing process regardless of which user namespace it resides in, only privileged processes are permitted to associate capabilities with a file. @@ -1723,7 +1723,7 @@ For example, in user-namespaced containers, it can be desirable to be able to create a binary that confers capabilities only to processes executed inside that container, but not to processes that are executed outside the container. -.PP +.P Linux 4.14 added so-called namespaced file capabilities to support such use cases. Namespaced file capabilities are recorded as version 3 (i.e., @@ -1739,7 +1739,7 @@ When a version 3 extended attribute is created, the kernel records not just the capability masks in the extended attribute, but also the namespace root user ID. -.PP +.P As with a binary that has .B VFS_CAP_REVISION_2 file capabilities, a binary with @@ -1770,13 +1770,13 @@ you may find the .I \-u <username> option useful. Something like: -.PP +.P .in +4n .EX $ \fBsudo strace \-o trace.log \-u ceci ./myprivprog\fP .EE .in -.PP +.P From Linux 2.5.27 to Linux 2.6.26, .\" commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 removed .\" CONFIG_SECURITY_CAPABILITIES @@ -1784,7 +1784,7 @@ capabilities were an optional kernel component, and could be enabled/disabled via the .B CONFIG_SECURITY_CAPABILITIES kernel configuration option. -.PP +.P The .IR /proc/ pid /task/TID/status file can be used to view the capability sets of a thread. @@ -1798,7 +1798,7 @@ Since Linux 3.8, all nonexistent capabilities (above .BR CAP_LAST_CAP ) are shown as disabled (0). -.PP +.P The .I libcap package provides a suite of routines for setting and @@ -1816,7 +1816,7 @@ It can be found at .br .UR https://git.kernel.org\:/pub\:/scm\:/libs\:/libcap\:/libcap.git\:/refs/ .UE . -.PP +.P Before Linux 2.6.24, and from Linux 2.6.24 to Linux 2.6.32 if file capabilities are not enabled, a thread with the .B CAP_SETPCAP @@ -1867,6 +1867,6 @@ created on the system. .BR netcap (8), \" from libcap-ng .BR pscap (8), \" from libcap-ng .BR setcap (8) -.PP +.P .I include/linux/capability.h in the Linux kernel source tree diff --git a/man7/cgroup_namespaces.7 b/man7/cgroup_namespaces.7 index c1162fe..f5c73ab 100644 --- a/man7/cgroup_namespaces.7 +++ b/man7/cgroup_namespaces.7 @@ -3,20 +3,20 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH cgroup_namespaces 7 2023-03-30 "Linux man-pages 6.05.01" +.TH cgroup_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME cgroup_namespaces \- overview of Linux cgroup namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P Cgroup namespaces virtualize the view of a process's cgroups (see .BR cgroups (7)) as seen via .IR /proc/ pid /cgroup and .IR /proc/ pid /mountinfo . -.PP +.P Each cgroup namespace has its own set of cgroup root directories. These root directories are the base points for the relative locations displayed in the corresponding records in the @@ -33,7 +33,7 @@ cgroups directories become the cgroup root directories of the new namespace. (This applies both for the cgroups version 1 hierarchies and the cgroups version 2 unified hierarchy.) -.PP +.P When reading the cgroup memberships of a "target" process from .IR /proc/ pid /cgroup , the pathname shown in the third field of each record will be @@ -44,16 +44,16 @@ the root directory of the reading process's cgroup namespace, then the pathname will show .I ../ entries for each ancestor level in the cgroup hierarchy. -.PP +.P The following shell session demonstrates the effect of creating a new cgroup namespace. -.PP +.P First, (as superuser) in a shell in the initial cgroup namespace, we create a child cgroup in the .I freezer hierarchy, and place a process in that cgroup that we will use as part of the demonstration below: -.PP +.P .in +4n .EX # \fBmkdir \-p /sys/fs/cgroup/freezer/sub2\fP @@ -62,11 +62,11 @@ use as part of the demonstration below: # \fBecho 20124 > /sys/fs/cgroup/freezer/sub2/cgroup.procs\fP .EE .in -.PP +.P We then create another child cgroup in the .I freezer hierarchy and put the shell into that cgroup: -.PP +.P .in +4n .EX # \fBmkdir \-p /sys/fs/cgroup/freezer/sub\fP @@ -77,17 +77,17 @@ hierarchy and put the shell into that cgroup: 7:freezer:/sub .EE .in -.PP +.P Next, we use .BR unshare (1) to create a process running a new shell in new cgroup and mount namespaces: -.PP +.P .in +4n .EX # \fBPS1="sh2# " unshare \-Cm bash\fP .EE .in -.PP +.P From the new shell started by .BR unshare (1), we then inspect the @@ -97,7 +97,7 @@ a process that is in the initial cgroup namespace .RI ( init , with PID 1), and the process in the sibling cgroup .RI ( sub2 ): -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/cgroup | grep freezer\fP @@ -108,7 +108,7 @@ sh2# \fBcat /proc/20124/cgroup | grep freezer\fP 7:freezer:/../sub2 .EE .in -.PP +.P From the output of the first command, we see that the freezer cgroup membership of the new shell (which is in the same cgroup as the initial shell) @@ -122,18 +122,18 @@ and the root directory of the freezer cgroup hierarchy in the new cgroup namespace is also .IR /sub . Thus, the new shell's cgroup membership is displayed as \[aq]/\[aq].) -.PP +.P However, when we look in .I /proc/self/mountinfo we see the following anomaly: -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/mountinfo | grep freezer\fP 155 145 0:32 /.. /sys/fs/cgroup/freezer ... .EE .in -.PP +.P The fourth field of this line .RI ( /.. ) should show the @@ -148,7 +148,7 @@ filesystem corresponding to the initial cgroup namespace To fix this problem, we must remount the freezer cgroup filesystem from the new shell (i.e., perform the mount from a process that is in the new cgroup namespace), after which we see the expected results: -.PP +.P .in +4n .EX sh2# \fBmount \-\-make\-rslave /\fP # Don\[aq]t propagate mount events @@ -166,7 +166,7 @@ Linux. Use of cgroup namespaces requires a kernel that is configured with the .B CONFIG_CGROUPS option. -.PP +.P The virtualization provided by cgroup namespaces serves a number of purposes: .IP \[bu] 3 It prevents information leaks whereby cgroup directory paths outside of diff --git a/man7/cgroups.7 b/man7/cgroups.7 index c070ca7..e2c3ec2 100644 --- a/man7/cgroups.7 +++ b/man7/cgroups.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH cgroups 7 2023-04-03 "Linux man-pages 6.05.01" +.TH cgroups 7 2024-03-05 "Linux man-pages 6.7" .SH NAME cgroups \- Linux control groups .SH DESCRIPTION @@ -22,7 +22,7 @@ A .I cgroup is a collection of processes that are bound to a set of limits or parameters defined via the cgroup filesystem. -.PP +.P A .I subsystem is a kernel component that modifies the behavior of @@ -34,7 +34,7 @@ and freezing and resuming execution of the processes in a cgroup. Subsystems are sometimes also known as .I resource controllers (or simply, controllers). -.PP +.P The cgroups for a controller are arranged in a .IR hierarchy . This hierarchy is defined by creating, removing, and @@ -60,7 +60,7 @@ source file (or .I Documentation/cgroup\-v2.txt in Linux 4.17 and earlier). -.PP +.P Because of the problems with the initial cgroups implementation (cgroups version 1), starting in Linux 3.10, work began on a new, @@ -74,7 +74,7 @@ The file .IR cgroup.sane_behavior , present in cgroups v1, is a relic of this mount option. The file always reports "0" and is only retained for backward compatibility. -.PP +.P Although cgroups v2 is intended as a replacement for cgroups v1, the older system continues to exist (and for compatibility reasons is unlikely to be removed). @@ -96,7 +96,7 @@ processes on the system. It is also possible to comount multiple (or even all) cgroups v1 controllers against the same cgroup filesystem, meaning that the comounted controllers manage the same hierarchical organization of processes. -.PP +.P For each mounted hierarchy, the directory tree mirrors the control group hierarchy. Each control group is represented by a directory, with each of its child @@ -123,7 +123,7 @@ In this view, a process can consist of multiple tasks and called such in the remainder of this man page). In cgroups v1, it is possible to independently manipulate the cgroup memberships of the threads in a process. -.PP +.P The cgroups v1 ability to split threads across different cgroups caused problems in some cases. For example, it made no sense for the @@ -142,7 +142,7 @@ The use of cgroups requires a kernel built with the option. In addition, each of the v1 controllers has an associated configuration option that must be set in order to employ that controller. -.PP +.P In order to use a v1 controller, it must be mounted against a cgroup filesystem. The usual place for such mounts is under a @@ -152,26 +152,26 @@ filesystem mounted at Thus, one might mount the .I cpu controller as follows: -.PP +.P .in +4n .EX mount \-t cgroup \-o cpu none /sys/fs/cgroup/cpu .EE .in -.PP +.P It is possible to comount multiple controllers against the same hierarchy. For example, here the .I cpu and .I cpuacct controllers are comounted against a single hierarchy: -.PP +.P .in +4n .EX mount \-t cgroup \-o cpu,cpuacct none /sys/fs/cgroup/cpu,cpuacct .EE .in -.PP +.P Comounting controllers has the effect that a process is in the same cgroup for all of the comounted controllers. Separately mounting controllers allows a process to @@ -180,19 +180,19 @@ be in cgroup for one controller while being in .I /foo2/foo3 for another. -.PP +.P It is possible to comount all v1 controllers against the same hierarchy: -.PP +.P .in +4n .EX mount \-t cgroup \-o all cgroup /sys/fs/cgroup .EE .in -.PP +.P (One can achieve the same result by omitting .IR "\-o all" , since it is the default if no controllers are explicitly specified.) -.PP +.P It is not possible to mount the same controller against multiple cgroup hierarchies. For example, it is not possible to mount both the @@ -206,7 +206,7 @@ It is possible to create multiple mount with exactly the same set of comounted controllers. However, in this case all that results is multiple mount points providing a view of the same hierarchy. -.PP +.P Note that on many systems, the v1 controllers are automatically mounted under .IR /sys/fs/cgroup ; in particular, @@ -217,13 +217,13 @@ automatically creates such mounts. A mounted cgroup filesystem can be unmounted using the .BR umount (8) command, as in the following example: -.PP +.P .in +4n .EX umount /sys/fs/cgroup/pids .EE .in -.PP +.P .IR "But note well" : a cgroup filesystem is unmounted only if it is not busy, that is, it has no child cgroups. @@ -409,41 +409,41 @@ in Linux 5.2 and earlier). A cgroup filesystem initially contains a single root cgroup, '/', which all processes belong to. A new cgroup is created by creating a directory in the cgroup filesystem: -.PP +.P .in +4n .EX mkdir /sys/fs/cgroup/cpu/cg1 .EE .in -.PP +.P This creates a new empty cgroup. -.PP +.P A process may be moved to this cgroup by writing its PID into the cgroup's .I cgroup.procs file: -.PP +.P .in +4n .EX echo $$ > /sys/fs/cgroup/cpu/cg1/cgroup.procs .EE .in -.PP +.P Only one PID at a time should be written to this file. -.PP +.P Writing the value 0 to a .I cgroup.procs file causes the writing process to be moved to the corresponding cgroup. -.PP +.P When writing a PID into the .IR cgroup.procs , all threads in the process are moved into the new cgroup at once. -.PP +.P Within a hierarchy, a process can be a member of exactly one cgroup. Writing a process's PID to a .I cgroup.procs file automatically removes it from the cgroup of which it was previously a member. -.PP +.P The .I cgroup.procs file can be read to obtain a list of the processes that are @@ -451,7 +451,7 @@ members of a cgroup. The returned list of PIDs is not guaranteed to be in order. Nor is it guaranteed to be free of duplicates. (For example, a PID may be recycled while reading from the list.) -.PP +.P In cgroups v1, an individual thread can be moved to another cgroup by writing its thread ID (i.e., the kernel thread ID returned by @@ -477,7 +477,7 @@ Two files can be used to determine whether the kernel provides notifications when a cgroup becomes empty. A cgroup is considered to be empty when it contains no child cgroups and no member processes. -.PP +.P A special file in the root directory of each cgroup hierarchy, .IR release_agent , can be used to register the pathname of a program that may be invoked when @@ -490,22 +490,22 @@ The .I release_agent program might remove the cgroup directory, or perhaps repopulate it with a process. -.PP +.P The default value of the .I release_agent file is empty, meaning that no release agent is invoked. -.PP +.P The content of the .I release_agent file can also be specified via a mount option when the cgroup filesystem is mounted: -.PP +.P .in +4n .EX mount \-o release_agent=pathname ... .EE .in -.PP +.P Whether or not the .I release_agent program is invoked when a particular cgroup becomes empty is determined @@ -526,13 +526,13 @@ in the parent cgroup. .SS Cgroup v1 named hierarchies In cgroups v1, it is possible to mount a cgroup hierarchy that has no attached controllers: -.PP +.P .in +4n .EX mount \-t cgroup \-o none,name=somename none /some/mount/point .EE .in -.PP +.P Multiple instances of such hierarchies can be mounted; each hierarchy must have a unique name. The only purpose of such hierarchies is to track processes. @@ -542,7 +542,7 @@ An example of this is the cgroup hierarchy that is used by .BR systemd (1) to track services and user sessions. -.PP +.P Since Linux 5.0, the .I cgroup_no_v1 kernel boot option (described below) can be used to disable cgroup v1 @@ -556,7 +556,7 @@ While (different) controllers may be simultaneously mounted under the v1 and v2 hierarchies, it is not possible to mount the same controller simultaneously under both the v1 and the v2 hierarchies. -.PP +.P The new behaviors in cgroups v2 are summarized here, and in some cases elaborated in the following subsections. .IP \[bu] 3 @@ -585,7 +585,7 @@ controller has been removed. An improved mechanism for notification of empty cgroups is provided by the .I cgroup.events file. -.PP +.P For more changes, see the .I Documentation/admin\-guide/cgroup\-v2.rst file in the kernel source @@ -593,7 +593,7 @@ file in the kernel source .I Documentation/cgroup\-v2.txt in Linux 4.17 and earlier). . -.PP +.P Some of the new behaviors listed above saw subsequent modification with the addition in Linux 4.14 of "thread mode" (described below). .\" @@ -609,13 +609,13 @@ all available controllers are mounted against a single hierarchy. The available controllers are automatically mounted, meaning that it is not necessary (or possible) to specify the controllers when mounting the cgroup v2 filesystem using a command such as the following: -.PP +.P .in +4n .EX mount \-t cgroup2 none /mnt/cgroup2 .EE .in -.PP +.P A cgroup v2 controller is available only if it is not currently in use via a mount against a cgroup v1 hierarchy. Or, to put things another way, it is not possible to employ @@ -638,7 +638,7 @@ to disable all v1 controllers. (This situation is correctly handled by .BR systemd (1), which falls back to operating without the specified controllers.) -.PP +.P Note that on many modern systems, .BR systemd (1) automatically mounts the @@ -726,7 +726,7 @@ controller. This is the same as the version 1 .I rdma controller. -.PP +.P There is no direct equivalent of the .I net_cls and @@ -736,7 +736,7 @@ Instead, support has been added to .BR iptables (8) to allow eBPF filters that hook on cgroup v2 pathnames to make decisions about network traffic on a per-cgroup basis. -.PP +.P The v2 .I devices controller provides no interface files; @@ -782,14 +782,14 @@ leads to an error when writing to the .I cgroup.subtree_control file. -.PP +.P Because the list of controllers in .I cgroup.subtree_control is a subset of those .IR cgroup.controllers , a controller that has been disabled in one cgroup in the hierarchy can never be re-enabled in the subtree below that cgroup. -.PP +.P A cgroup's .I cgroup.subtree_control file determines the set of controllers that are exercised in the @@ -805,14 +805,14 @@ then the corresponding controller-interface files (e.g., are automatically created in the children of that cgroup and can be used to exert resource control in the child cgroups. .\" -.SS Cgroups v2 """no internal processes""" rule +.SS Cgroups v2 \[dq]no internal processes\[dq] rule Cgroups v2 enforces a so-called "no internal processes" rule. Roughly speaking, this rule means that, with the exception of the root cgroup, processes may reside only in leaf nodes (cgroups that do not themselves contain child cgroups). This avoids the need to decide how to partition resources between processes which are members of cgroup A and processes in child cgroups of A. -.PP +.P For instance, if cgroup .I /cg1/cg2 exists, then a process may reside in @@ -836,7 +836,7 @@ the relationship between processes in and .IR /cg1 's other children. -.PP +.P The "no internal processes" rule is in fact more subtle than stated above. More precisely, the rule is that a (nonroot) cgroup can't both (1) have member processes, and @@ -849,7 +849,7 @@ possible for a cgroup to have both member processes and child cgroups, but before controllers can be enabled for that cgroup, the member processes must be moved out of the cgroup (e.g., perhaps into the child cgroups). -.PP +.P With the Linux 4.14 addition of "thread mode" (described below), the "no internal processes" rule has been relaxed in some cases. .\" @@ -859,7 +859,7 @@ Each nonroot cgroup in the v2 hierarchy contains a read-only file, whose contents are key-value pairs (delimited by newline characters, with the key and value separated by spaces) providing state information about the cgroup: -.PP +.P .in +4n .EX $ \fBcat mygrp/cgroup.events\fP @@ -867,7 +867,7 @@ populated 1 frozen 0 .EE .in -.PP +.P The following keys may appear in this file: .TP .I populated @@ -879,7 +879,7 @@ or otherwise 0. .\" commit 76f969e8948d82e78e1bc4beb6b9465908e7487 The value of this key is 1 if this cgroup is currently frozen, or 0 if it is not. -.PP +.P The .I cgroup.events file can be monitored, in order to receive notification when the value of @@ -915,7 +915,7 @@ meaning that the cgroup (and its descendants) contain no (nonzombie) member processes, or 1, meaning that the cgroup (or one of its descendants) contains member processes. -.PP +.P The cgroups v2 release-notification mechanism offers the following advantages over the cgroups v1 .I release_agent @@ -974,10 +974,10 @@ fails with the error .BR EAGAIN ). .IP Writing the string -.I """max""" +.I \[dq]max\[dq] to this file means that no limit is imposed. The default value in this file is -.I """max""" . +.IR \[dq]max\[dq] . .TP .IR cgroup.max.descendants " (since Linux 4.14)" .\" commit 1a926e0bbab83bae8207d05a533173425e0496d1 @@ -989,10 +989,10 @@ fails with the error .BR EAGAIN ). .IP Writing the string -.I """max""" +.I \[dq]max\[dq] to this file means that no limit is imposed. The default value in this file is -.IR """max""" . +.IR \[dq]max\[dq] . .\" .SH CGROUPS DELEGATION: DELEGATING A HIERARCHY TO A LESS PRIVILEGED USER In the context of cgroups, @@ -1004,7 +1004,7 @@ in the cgroup hierarchy but with less strict containment rules than v2 Cgroups v2 supports delegation with containment by explicit design. The focus of the discussion in this section is on delegation in cgroups v2, with some differences for cgroups v1 noted along the way. -.PP +.P Some terminology is required in order to describe delegation. A .I delegater @@ -1015,7 +1015,7 @@ is a nonprivileged user who will be granted the permissions needed to manage some subhierarchy under that parent cgroup, known as the .IR "delegated subtree" . -.PP +.P To perform delegation, the delegater makes certain directories and files writable by the delegatee, typically by changing the ownership of the objects to be the user ID @@ -1056,7 +1056,7 @@ file.) In cgroups v1, the corresponding file that should instead be delegated is the .I tasks file. -.PP +.P The delegater should .I not change the ownership of any of the controller interfaces files (e.g., @@ -1068,11 +1068,11 @@ Those files are used from the next level above the delegated subtree in order to distribute resources into the subtree, and the delegatee should not have permission to change the resources that are distributed into the delegated subtree. -.PP +.P See also the discussion of the .I /sys/kernel/cgroup/delegate file in NOTES for information about further delegatable files in cgroups v2. -.PP +.P After the aforementioned steps have been performed, the delegatee can create child cgroups within the delegated subtree (the cgroup subdirectories and the files they contain @@ -1095,7 +1095,7 @@ For example, if the cgroup v2 filesystem has already been mounted, we can remount it with the .I nsdelegate option as follows: -.PP +.P .in +4n .EX mount \-t cgroup2 \-o remount,nsdelegate \e @@ -1109,7 +1109,7 @@ mount \-t cgroup2 \-o remount,nsdelegate \e .\" .\" The effect of the latter option is to prevent systemd from employing .\" its "hybrid" cgroup mode, where it tries to make use of cgroups v2. -.PP +.P The effect of this mount option is to cause cgroup namespaces to automatically become delegation boundaries. More specifically, @@ -1133,7 +1133,7 @@ Processes inside the cgroup namespace can still move processes between cgroups .I within the subhierarchy under the namespace root. -.PP +.P The ability to define cgroup namespaces as delegation boundaries makes cgroup namespaces more useful. To understand why, suppose that we already have one cgroup hierarchy @@ -1163,17 +1163,17 @@ a process inside the child cgroup should not be allowed to modify them.) 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. -.PP +.P Employing the .I nsdelegate mount option prevents both of these possibilities. -.PP +.P The .I nsdelegate mount option only has an effect when performed in the initial mount namespace; in other mount namespaces, the option is silently ignored. -.PP +.P .IR Note : On some systems, .BR systemd (1) @@ -1182,13 +1182,13 @@ In order to experiment with the .I nsdelegate operation, it may be useful to boot the kernel with the following command-line options: -.PP +.P .in +4n .EX cgroup_no_v1=all systemd.legacy_systemd_cgroup_controller .EE .in -.PP +.P These options cause the kernel to boot with the cgroups v1 controllers disabled (meaning that the controllers are available in the v2 hierarchy), and tells @@ -1237,7 +1237,7 @@ this requirement also applied in cgroups v2 (This was a historical requirement inherited from cgroups v1 that was later deemed unnecessary, since the other rules suffice for containment in cgroups v2.) -.PP +.P .IR Note : one consequence of these delegation containment rules is that the unprivileged delegatee can't place the first process into @@ -1255,7 +1255,7 @@ all of the threads of a process must be in the same cgroup. .IR "No internal processes" : a cgroup can't both have member processes and exercise controllers on child cgroups. -.PP +.P Both of these restrictions were added because the lack of these restrictions had caused problems in cgroups v1. @@ -1267,7 +1267,7 @@ controller: since threads share an address space, it made no sense to split threads across different .I memory cgroups.) -.PP +.P Notwithstanding the initial design decision in cgroups v2, there were use cases for certain controllers, notably the .I cpu @@ -1276,7 +1276,7 @@ for which thread-level granularity of control was meaningful and useful. To accommodate such use cases, Linux 4.14 added .I "thread mode" for cgroups v2. -.PP +.P Thread mode allows the following: .IP \[bu] 3 The creation of @@ -1293,7 +1293,7 @@ A relaxation of the "no internal processes rule", so that, within a threaded subtree, a cgroup can both contain member threads and exercise resource control over child cgroups. -.PP +.P With the addition of thread mode, each nonroot cgroup now contains a new file, .IR cgroup.type , @@ -1327,7 +1327,7 @@ The only thing that can be done with this cgroup (other than deleting it) is to convert it to a .I threaded cgroup by writing the string -.I """threaded""" +.I \[dq]threaded\[dq] to the .I cgroup.type file. @@ -1369,7 +1369,7 @@ There are two pathways that lead to the creation of a threaded subtree. The first pathway proceeds as follows: .IP (1) 5 We write the string -.I """threaded""" +.I \[dq]threaded\[dq] to the .I cgroup.type file of a cgroup @@ -1406,7 +1406,7 @@ will also have the type .RE .IP (2) We write the string -.I """threaded""" +.I \[dq]threaded\[dq] to each of the .I domain invalid cgroups under @@ -1418,10 +1418,10 @@ now have the type .I threaded and the threaded subtree is now fully usable. The requirement to write -.I """threaded""" +.I \[dq]threaded\[dq] to each of these cgroups is somewhat cumbersome, but allows for possible future extensions to the thread-mode model. -.PP +.P The second way of creating a threaded subtree is as follows: .IP (1) 5 In an existing cgroup, @@ -1441,7 +1441,7 @@ becomes .IR "domain threaded" . .IP \[bu] All of the descendant cgroups of -.I x +.I z that were not already of type .I threaded are converted to type @@ -1449,14 +1449,14 @@ are converted to type .RE .IP (2) As before, we make the threaded subtree usable by writing the string -.I """threaded""" +.I \[dq]threaded\[dq] to each of the .I domain invalid cgroups under -.IR y , +.IR z , in order to convert them to the type .IR threaded . -.PP +.P One of the consequences of the above pathways to creating a threaded subtree is that the threaded root cgroup can be a parent only to .I threaded @@ -1478,7 +1478,7 @@ in each subgroup whose type has been changed to .IR threaded ; upon doing so, the corresponding controller interface files appear in the children of that cgroup. -.PP +.P A process can be moved into a threaded subtree by writing its PID to the .I cgroup.procs file in one of the cgroups inside the tree. @@ -1492,7 +1492,7 @@ to the .I cgroup.threads files in different cgroups inside the subtree. The threads of a process must all reside in the same threaded subtree. -.PP +.P As with writing to .IR cgroup.procs , some containment rules apply when writing to the @@ -1517,7 +1517,7 @@ file in a different .I domain cgroup fails with the error .BR EOPNOTSUPP .) -.PP +.P The .I cgroup.threads file is present in each cgroup (including @@ -1526,7 +1526,7 @@ cgroups) and can be read in order to discover the set of threads that is present in the cgroup. The set of thread IDs obtained when reading this file is not guaranteed to be ordered or free of duplicates. -.PP +.P The .I cgroup.procs file in the threaded root shows the PIDs of all processes @@ -1534,7 +1534,7 @@ that are members of the threaded subtree. The .I cgroup.procs files in the other cgroups in the subtree are not readable. -.PP +.P Domain controllers can't be enabled in a threaded subtree; no controller-interface files appear inside the cgroups underneath the threaded root. @@ -1542,7 +1542,7 @@ From the point of view of a domain controller, threaded subtrees are invisible: a multithreaded process inside a threaded subtree appears to a domain controller as a process that resides in the threaded root cgroup. -.PP +.P Within a threaded subtree, the "no internal processes" rule does not apply: a cgroup can both contain member processes (or thread) and exercise controllers on child cgroups. @@ -1553,7 +1553,7 @@ A number of rules apply when writing to the file: .IP \[bu] 3 Only the string -.I """threaded""" +.I \[dq]threaded\[dq] may be written. In other words, the only explicit transition that is possible is to convert a .I domain @@ -1561,7 +1561,7 @@ cgroup to type .IR threaded . .IP \[bu] The effect of writing -.I """threaded""" +.I \[dq]threaded\[dq] depends on the current value in .IR cgroup.type , as follows: @@ -1590,7 +1590,7 @@ file if the parent's type is In other words, the cgroups of a threaded subtree must be converted to the .I threaded state in a top-down manner. -.PP +.P There are also some constraints that must be satisfied in order to create a threaded subtree rooted at the cgroup .IR x : @@ -1605,27 +1605,27 @@ No domain controllers may be enabled in .IR x 's .I cgroup.subtree_control file. -.PP +.P If any of the above constraints is violated, then an attempt to write -.I """threaded""" +.I \[dq]threaded\[dq] to a .I cgroup.type file fails with the error .BR ENOTSUP . .\" -.SS The """domain threaded""" cgroup type +.SS The \[dq]domain threaded\[dq] cgroup type According to the pathways described above, the type of a cgroup can change to .I domain threaded in either of the following cases: .IP \[bu] 3 The string -.I """threaded""" +.I \[dq]threaded\[dq] is written to a child cgroup. .IP \[bu] A threaded controller is enabled inside the cgroup and a process is made a member of the cgroup. -.PP +.P A .I domain threaded cgroup, @@ -1640,7 +1640,7 @@ are removed and either .I x no longer has threaded controllers enabled or no longer has member processes. -.PP +.P When a .I domain threaded cgroup @@ -1666,7 +1666,7 @@ and .I threaded cgroups. If the string -.I """threaded""" +.I \[dq]threaded\[dq] is written to the .I cgroup.type file of one of the children of the root cgroup, then @@ -1677,20 +1677,20 @@ The type of that cgroup becomes The type of any descendants of that cgroup that are not part of lower-level threaded subtrees changes to .IR "domain invalid" . -.PP +.P Note that in this case, there is no cgroup whose type becomes .IR "domain threaded" . (Notionally, the root cgroup can be considered as the threaded root for the cgroup whose type was changed to .IR threaded .) -.PP +.P The aim of this exceptional treatment for the root cgroup is to allow a threaded cgroup that employs the .I cpu controller to be placed as high as possible in the hierarchy, so as to minimize the (small) cost of traversing the cgroup hierarchy. .\" -.SS The cgroups v2 """cpu""" controller and realtime threads +.SS The cgroups v2 \[dq]cpu\[dq] controller and realtime threads As at Linux 4.19, the cgroups v2 .I cpu controller does not support control of realtime threads @@ -1708,12 +1708,12 @@ if all realtime threads are in the root cgroup. (If there are realtime threads in nonroot cgroups, then a .BR write (2) of the string -.I """+cpu""" +.I \[dq]+cpu\[dq] to the .I cgroup.subtree_control file fails with the error .BR EINVAL .) -.PP +.P On some systems, .BR systemd (1) places certain realtime threads in nonroot cgroups in the v2 hierarchy. @@ -1737,7 +1737,7 @@ A child process created via inherits its parent's cgroup memberships. A process's cgroup memberships are preserved across .BR execve (2). -.PP +.P The .BR clone3 (2) .B CLONE_INTO_CGROUP @@ -1909,6 +1909,6 @@ mount option. .BR namespaces (7), .BR sched (7), .BR user_namespaces (7) -.PP +.P The kernel source file .IR Documentation/admin\-guide/cgroup\-v2.rst . diff --git a/man7/charsets.7 b/man7/charsets.7 index 0692d8d..eb9f8f8 100644 --- a/man7/charsets.7 +++ b/man7/charsets.7 @@ -8,7 +8,7 @@ .\" .\" Changes also by David Starner <dstarner98@aasaa.ofe.org>. .\" -.TH charsets 7 2023-03-12 "Linux man-pages 6.05.01" +.TH charsets 7 2024-01-28 "Linux man-pages 6.7" .SH NAME charsets \- character set standards and internationalization .SH DESCRIPTION @@ -16,10 +16,10 @@ This manual page gives an overview on different character set standards and how they were used on Linux before Unicode became ubiquitous. Some of this information is still helpful for people working with legacy systems and documents. -.PP +.P Standards discussed include such as -ASCII, GB 2312, ISO 8859, JIS, KOI8-R, KS, and Unicode. -.PP +ASCII, GB 2312, ISO/IEC\~8859, JIS, KOI8-R, KS, and Unicode. +.P The primary emphasis is on character sets that were actually used by locale character sets, not the myriad others that could be found in data from other systems. @@ -27,9 +27,9 @@ from other systems. ASCII (American Standard Code For Information Interchange) is the original 7-bit character set, originally designed for American English. Also known as US-ASCII. -It is currently described by the ISO 646:1991 IRV +It is currently described by the ISO/IEC\~646:1991 IRV (International Reference Version) standard. -.PP +.P Various ASCII variants replacing the dollar sign with other currency symbols and replacing punctuation with non-English alphabetic characters to cover German, French, Spanish, and others in 7 bits @@ -37,30 +37,30 @@ emerged. All are deprecated; glibc does not support locales whose character sets are not true supersets of ASCII. -.PP +.P As Unicode, when using UTF-8, is ASCII-compatible, plain ASCII text still renders properly on modern UTF-8 using systems. -.SS ISO 8859 -ISO 8859 is a series of 15 8-bit character sets, all of which have ASCII +.SS ISO/IEC\~8859 +ISO/IEC\~8859 is a series of 15 8-bit character sets, all of which have ASCII in their low (7-bit) half, invisible control characters in positions 128 to 159, and 96 fixed-width graphics in positions 160\[en]255. -.PP -Of these, the most important is ISO 8859-1 +.P +Of these, the most important is ISO/IEC\~8859-1 ("Latin Alphabet No. 1" / Latin-1). It was widely adopted and supported by different systems, and is gradually being replaced with Unicode. -The ISO 8859-1 characters are also the first 256 characters of Unicode. -.PP -Console support for the other 8859 character sets is available under +The ISO/IEC\~8859-1 characters are also the first 256 characters of Unicode. +.P +Console support for the other ISO/IEC\~8859 character sets is available under Linux through user-mode utilities (such as .BR setfont (8)) that modify keyboard bindings and the EGA graphics table and employ the "user mapping" font table in the console driver. -.PP +.P Here are brief descriptions of each character set: .TP -8859-1 (Latin-1) +ISO/IEC\~8859-1 (Latin-1) Latin-1 covers many European languages such as Albanian, Basque, Danish, English, Faroese, Galician, Icelandic, Irish, Italian, Norwegian, Portuguese, Spanish, and Swedish. @@ -70,81 +70,81 @@ French œ, and „German“ quotation marks was considered tolerable. .TP -8859-2 (Latin-2) +ISO/IEC\~8859-2 (Latin-2) Latin-2 supports many Latin-written Central and East European languages such as Bosnian, Croatian, Czech, German, Hungarian, Polish, Slovak, and Slovene. Replacing Romanian ș/ț with ş/ţ was considered tolerable. .TP -8859-3 (Latin-3) +ISO/IEC\~8859-3 (Latin-3) Latin-3 was designed to cover of Esperanto, Maltese, and Turkish, but -8859-9 later superseded it for Turkish. +ISO/IEC\~8859-9 later superseded it for Turkish. .TP -8859-4 (Latin-4) +ISO/IEC\~8859-4 (Latin-4) Latin-4 introduced letters for North European languages such as -Estonian, Latvian, and Lithuanian, but was superseded by 8859-10 and -8859-13. +Estonian, Latvian, and Lithuanian, but was superseded by ISO/IEC\~8859-10 and +ISO/IEC\~8859-13. .TP -8859-5 +ISO/IEC\~8859-5 Cyrillic letters supporting Bulgarian, Byelorussian, Macedonian, Russian, Serbian, and (almost completely) Ukrainian. It was never widely used, see the discussion of KOI8-R/KOI8-U below. .TP -8859-6 +ISO/IEC\~8859-6 Was created for Arabic. -The 8859-6 glyph table is a fixed font of separate +The ISO/IEC\~8859-6 glyph table is a fixed font of separate letter forms, but a proper display engine should combine these using the proper initial, medial, and final forms. .TP -8859-7 +ISO/IEC\~8859-7 Was created for Modern Greek in 1987, updated in 2003. .TP -8859-8 +ISO/IEC\~8859-8 Supports Modern Hebrew without niqud (punctuation signs). Niqud and full-fledged Biblical Hebrew were outside the scope of this character set. .TP -8859-9 (Latin-5) +ISO/IEC\~8859-9 (Latin-5) This is a variant of Latin-1 that replaces Icelandic letters with Turkish ones. .TP -8859-10 (Latin-6) +ISO/IEC\~8859-10 (Latin-6) Latin-6 added the Inuit (Greenlandic) and Sami (Lappish) letters that were missing in Latin-4 to cover the entire Nordic area. .TP -8859-11 +ISO/IEC\~8859-11 Supports the Thai alphabet and is nearly identical to the TIS-620 standard. .TP -8859-12 +ISO/IEC\~8859-12 This character set does not exist. .TP -8859-13 (Latin-7) +ISO/IEC\~8859-13 (Latin-7) Supports the Baltic Rim languages; in particular, it includes Latvian characters not found in Latin-4. .TP -8859-14 (Latin-8) +ISO/IEC\~8859-14 (Latin-8) This is the Celtic character set, covering Old Irish, Manx, Gaelic, Welsh, Cornish, and Breton. .TP -8859-15 (Latin-9) +ISO/IEC\~8859-15 (Latin-9) Latin-9 is similar to the widely used Latin-1 but replaces some less common symbols with the Euro sign and French and Finnish letters that were missing in Latin-1. .TP -8859-16 (Latin-10) +ISO/IEC\~8859-16 (Latin-10) This character set covers many Southeast European languages, and most importantly supports Romanian more completely than Latin-2. .SS KOI8-R / KOI8-U KOI8-R is a non-ISO character set popular in Russia before Unicode. The lower half is ASCII; the upper is a Cyrillic character set somewhat better designed than -ISO 8859-5. +ISO/IEC\~8859-5. KOI8-U, based on KOI8-R, has better support for Ukrainian. -Neither of these sets are ISO-2022 compatible, -unlike the ISO 8859 series. -.PP +Neither of these sets are ISO/IEC\~2022 compatible, +unlike the ISO/IEC\~8859 series. +.P Console support for KOI8-R is available under Linux through user-mode utilities that modify keyboard bindings and the EGA graphics table, and employ the "user mapping" font table in the console driver. @@ -165,7 +165,7 @@ It is a superset of ASCII. Non-ASCII characters are expressed in two bytes. Bytes 0xa1\[en]0xfe are used as leading bytes for two-byte characters. Big5 and its extension were widely used in Taiwan and Hong Kong. -It is not ISO 2022 compliant. +It is not ISO/IEC\~2022 compliant. .\" Thanks to Tomohiro KUBOTA for the following sections about .\" national standards. .SS JIS X 0208 @@ -179,7 +179,7 @@ This means that JIS X 0208 itself is not used for expressing text data. JIS X 0208 is used as a component to construct encodings such as EUC-JP, Shift_JIS, -and ISO-2022-JP. +and ISO/IEC\~2022-JP. EUC-JP is the most important encoding for Linux and includes ASCII and JIS X 0208. In EUC-JP, JIS X 0208 @@ -190,19 +190,19 @@ KS X 1001 is a Korean national standard character set. Just as JIS X 0208, characters are mapped into a 94x94 two-byte matrix. KS X 1001 is used like JIS X 0208, as a component -to construct encodings such as EUC-KR, Johab, and ISO-2022-KR. +to construct encodings such as EUC-KR, Johab, and ISO/IEC\~2022-KR. EUC-KR is the most important encoding for Linux and includes ASCII and KS X 1001. KS C 5601 is an older name for KS X 1001. -.SS ISO 2022 and ISO 4873 -The ISO 2022 and 4873 standards describe a font-control model +.SS ISO/IEC\~2022 and ISO/IEC\~4873 +The ISO/IEC\~2022 and ISO/IEC\~4873 standards describe a font-control model based on VT100 practice. This model is (partially) supported by the Linux kernel and by .BR xterm (1). -Several ISO 2022-based character encodings have been defined, +Several ISO/IEC\~2022-based character encodings have been defined, especially for Japanese. -.PP +.P There are 4 graphic character sets, called G0, G1, G2, and G3, and one of them is the current character set for codes with high bit zero (initially G0), and one of them is the current @@ -212,7 +212,7 @@ essentially a 7-bit character set. It uses codes either 040\[en]0177 (041\[en]0176) or 0240\[en]0377 (0241\[en]0376). G0 always has size 94 and uses codes 041\[en]0176. -.PP +.P Switching between character sets is done using the shift functions \fB\[ha]N\fP (SO or LS1), \fB\[ha]O\fP (SI or LS0), ESC n (LS2), ESC o (LS3), ESC N (SS2), ESC O (SS3), ESC \[ti] (LS1R), ESC } (LS2R), ESC | (LS3R). @@ -223,32 +223,32 @@ for codes with high bit one. The function SS\fIn\fP makes character set G\fIn\fP (\fIn\fP=2 or 3) the current one for the next character only (regardless of the value of its high order bit). -.PP +.P A 94-character set is designated as G\fIn\fP character set by an escape sequence ESC ( xx (for G0), ESC ) xx (for G1), ESC * xx (for G2), ESC + xx (for G3), where xx is a symbol -or a pair of symbols found in the ISO 2375 International +or a pair of symbols found in the ISO/IEC\~2375 International Register of Coded Character Sets. -For example, ESC ( @ selects the ISO 646 character set as G0, +For example, ESC ( @ selects the ISO/IEC\~646 character set as G0, ESC ( A selects the UK standard character set (with pound instead of number sign), ESC ( B selects ASCII (with dollar instead of currency sign), ESC ( M selects a character set for African languages, ESC ( ! A selects the Cuban character set, and so on. -.PP +.P A 96-character set is designated as G\fIn\fP character set by an escape sequence ESC \- xx (for G1), ESC . xx (for G2) or ESC / xx (for G3). For example, ESC \- G selects the Hebrew alphabet as G1. -.PP +.P A multibyte character set is designated as G\fIn\fP character set by an escape sequence ESC $ xx or ESC $ ( xx (for G0), ESC $ ) xx (for G1), ESC $ * xx (for G2), ESC $ + xx (for G3). For example, ESC $ ( C selects the Korean character set for G0. The Japanese character set selected by ESC $ B has a more recent version selected by ESC & @ ESC $ B. -.PP -ISO 4873 stipulates a narrower use of character sets, where G0 +.P +ISO/IEC\~4873 stipulates a narrower use of character sets, where G0 is fixed (always ASCII), so that G1, G2, and G3 can be invoked only for codes with the high order bit set. In particular, \fB\[ha]N\fP and \fB\[ha]O\fP are not used anymore, ESC ( xx @@ -257,7 +257,7 @@ are equivalent to ESC \- xx, ESC . xx, ESC / xx, respectively. .SS TIS-620 TIS-620 is a Thai national standard character set and a superset of ASCII. -In the same fashion as the ISO 8859 series, Thai characters are mapped into +In the same fashion as the ISO/IEC\~8859 series, Thai characters are mapped into 0xa1\[en]0xfe. .SS Unicode Unicode (ISO/IEC 10646) is a standard which aims to unambiguously represent @@ -267,14 +267,14 @@ Since most computers don't include 20.1-bit integers, Unicode is usually encoded as 32-bit integers internally and either a series of 16-bit integers (UTF-16) (needing two 16-bit integers only when encoding certain rare characters) or a series of 8-bit bytes (UTF-8). -.PP +.P Linux represents Unicode using the 8-bit Unicode Transformation Format (UTF-8). UTF-8 is a variable length encoding of Unicode. It uses 1 byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes for 21 bits, 5 bytes for 26 bits, 6 bytes for 31 bits. -.PP +.P Let 0,1,x stand for a zero, one, or arbitrary bit. A byte 0xxxxxxx stands for the Unicode 00000000 0xxxxxxx which codes the same symbol @@ -282,7 +282,7 @@ as the ASCII 0xxxxxxx. Thus, ASCII goes unchanged into UTF-8, and people using only ASCII do not notice any change: not in code, and not in file size. -.PP +.P A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy is assembled into 00000xxx xxyyyyyy. A byte 1110xxxx is the start @@ -290,8 +290,8 @@ of a 3-byte code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled into xxxxyyyy yyzzzzzz. (When UTF-8 is used to code the 31-bit ISO/IEC 10646 then this progression continues up to 6-byte codes.) -.PP -For most texts in ISO 8859 character sets, this means that the +.P +For most texts in ISO/IEC\~8859 character sets, this means that the characters outside of ASCII are now coded with two bytes. This tends to expand ordinary text files by only one or two percent. @@ -301,10 +301,10 @@ those languages is mostly outside of ASCII. For Japanese users this means that the 16-bit codes now in common use will take three bytes. While there are algorithmic conversions from some character sets -(especially ISO 8859-1) to Unicode, general conversion requires +(especially ISO/IEC\~8859-1) to Unicode, general conversion requires carrying around conversion tables, which can be quite large for 16-bit codes. -.PP +.P Note that UTF-8 is self-synchronizing: 10xxxxxx is a tail, any other byte is the head of a code. @@ -313,12 +313,12 @@ is as themselves. In particular, there are no embedded NULs (\[aq]\e0\[aq]) or \[aq]/\[aq]s that form part of some larger code. -.PP +.P Since ASCII, and, in particular, NUL and \[aq]/\[aq], are unchanged, the kernel does not notice that UTF-8 is being used. It does not care at all what the bytes it is handling stand for. -.PP +.P Rendering of Unicode data streams is typically handled through "subfont" tables which map a subset of Unicode to glyphs. Internally diff --git a/man7/complex.7 b/man7/complex.7 index 3685a8d..a61551e 100644 --- a/man7/complex.7 +++ b/man7/complex.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH complex 7 2023-07-18 "Linux man-pages 6.05.01" +.TH complex 7 2023-10-31 "Linux man-pages 6.7" .SH NAME complex \- basics of complex mathematics .SH LIBRARY @@ -15,7 +15,7 @@ Math library .SH DESCRIPTION Complex numbers are numbers of the form z = a+b*i, where a and b are real numbers and i = sqrt(\-1), so that i*i = \-1. -.PP +.P There are other ways to represent that number. The pair (a,b) of real numbers may be viewed as a point in the plane, given by X- and @@ -25,7 +25,7 @@ the pair of real numbers (r,phi), where r is the distance to the origin O, and phi the angle between the X-axis and the line Oz. Now z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)). -.PP +.P The basic operations are defined on z = a+b*i and w = c+d*i as: .TP .B addition: z+w = (a+c) + (b+d)*i @@ -33,13 +33,13 @@ The basic operations are defined on z = a+b*i and w = c+d*i as: .B multiplication: z*w = (a*c \- b*d) + (a*d + b*c)*i .TP .B division: z/w = ((a*c + b*d)/(c*c + d*d)) + ((b*c \- a*d)/(c*c + d*d))*i -.PP +.P Nearly all math function have a complex counterpart but there are some complex-only functions. .SH EXAMPLES Your C-compiler can work with complex numbers if it supports the C99 standard. The imaginary unit is represented by I. -.PP +.P .EX /* check that exp(i * pi) == \-1 */ #include <math.h> /* for atan */ diff --git a/man7/cp1251.7 b/man7/cp1251.7 index 6dd88c2..6668ad7 100644 --- a/man7/cp1251.7 +++ b/man7/cp1251.7 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH cp1251 7 2022-12-15 "Linux man-pages 6.05.01" +.TH cp1251 7 2024-01-28 "Linux man-pages 6.7" .SH NAME cp1251 \- CP\ 1251 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The Windows Code Pages include several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). +character set (also known as ISO/IEC\~646-IRV). CP\ 1251 encodes the characters used in Cyrillic scripts. .SS CP\ 1251 characters diff --git a/man7/cp1252.7 b/man7/cp1252.7 index 2522b1d..6630434 100644 --- a/man7/cp1252.7 +++ b/man7/cp1252.7 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH cp1252 7 2022-12-15 "Linux man-pages 6.05.01" +.TH cp1252 7 2024-01-28 "Linux man-pages 6.7" .SH NAME cp1252 \- CP\ 1252 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The Windows Code Pages include several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). +character set (also known as ISO/IEC\~646-IRV). CP\ 1252 encodes the characters used in many West European languages. .SS CP\ 1252 characters diff --git a/man7/cpuset.7 b/man7/cpuset.7 index 800e4da..2db2bfc 100644 --- a/man7/cpuset.7 +++ b/man7/cpuset.7 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-only .\" -.TH cpuset 7 2023-07-18 "Linux man-pages 6.05.01" +.TH cpuset 7 2023-10-31 "Linux man-pages 6.7" .SH NAME cpuset \- confine processes to processor and memory node subsets .SH DESCRIPTION @@ -14,7 +14,7 @@ which is used to control the processor placement and memory placement of processes. It is commonly mounted at .IR /dev/cpuset . -.PP +.P On systems with kernels compiled with built in support for cpusets, all processes are attached to a cpuset, and cpusets are always present. If a system supports cpusets, then it will have the entry @@ -31,9 +31,9 @@ By default, if the cpuset configuration on a system is not modified or if the cpuset filesystem is not even mounted, then the cpuset mechanism, though present, has no effect on the system's behavior. -.PP +.P A cpuset defines a list of CPUs and memory nodes. -.PP +.P The CPUs of a system include all the logical processing units on which a process can execute, including, if present, multiple processor cores within a package and Hyper-Threads @@ -42,7 +42,7 @@ Memory nodes include all distinct banks of main memory; small and SMP systems typically have just one memory node that contains all the system's main memory, while NUMA (non-uniform memory access) systems have multiple memory nodes. -.PP +.P Cpusets are represented as directories in a hierarchical pseudo-filesystem, where the top directory in the hierarchy .RI ( /dev/cpuset ) @@ -52,7 +52,7 @@ another parent cpuset contains a subset of that parent's CPUs and memory nodes. The directories and files representing cpusets have normal filesystem permissions. -.PP +.P Every process in the system belongs to exactly one cpuset. A process is confined to run only on the CPUs in the cpuset it belongs to, and to allocate memory only @@ -63,7 +63,7 @@ the child process is placed in the same cpuset as its parent. With sufficient privilege, a process may be moved from one cpuset to another and the allowed CPUs and memory nodes of an existing cpuset may be changed. -.PP +.P When the system begins booting, a single cpuset is defined that includes all CPUs and memory nodes on the system, and all processes are in that cpuset. @@ -71,7 +71,7 @@ During the boot process, or later during normal system operation, other cpusets may be created, as subdirectories of this top cpuset, under the control of the system administrator, and processes may be placed in these other cpusets. -.PP +.P Cpusets are integrated with the .BR sched_setaffinity (2) scheduling affinity mechanism and the @@ -93,7 +93,7 @@ other calls returning an error, if for example, such a call ends up requesting an empty set of CPUs or memory nodes, after that request is restricted to the invoking process's cpuset. -.PP +.P Typically, a cpuset is used to manage the CPU and memory-node confinement for a set of cooperating processes such as a batch scheduler job, and these @@ -104,7 +104,7 @@ Each directory below .I /dev/cpuset represents a cpuset and contains a fixed set of pseudo-files describing the state of that cpuset. -.PP +.P New cpusets are created using the .BR mkdir (2) system call or the @@ -114,13 +114,13 @@ The properties of a cpuset, such as its flags, allowed CPUs and memory nodes, and attached processes, are queried and modified by reading or writing to the appropriate file in that cpuset's directory, as listed below. -.PP +.P The pseudo-files in each cpuset directory are automatically created when the cpuset is created, as a result of the .BR mkdir (2) invocation. It is not possible to directly add or remove these pseudo-files. -.PP +.P A cpuset directory that contains no child cpuset directories, and has no attached processes, can be removed using .BR rmdir (2) @@ -128,7 +128,7 @@ or .BR rmdir (1). It is not necessary, or possible, to remove the pseudo-files inside the directory before removing it. -.PP +.P The pseudo-files in each cpuset directory are small text files that may be read and written using traditional shell utilities such as @@ -142,7 +142,7 @@ such as .BR write (2), and .BR close (2). -.PP +.P The pseudo-files in a cpuset directory represent internal kernel state and do not have any persistent image on disk. Each of these per-cpuset files is listed and described below. @@ -338,7 +338,7 @@ the wider the range of CPUs over which immediate load balancing is attempted. See \fBScheduler Relax Domain Level\fR, below, for further details. .\" ================== proc cpuset ================== -.PP +.P In addition to the above pseudo-files in each directory below .IR /dev/cpuset , each process has a pseudo-file, @@ -346,7 +346,7 @@ each process has a pseudo-file, that displays the path of the process's cpuset directory relative to the root of the cpuset filesystem. .\" ================== proc status ================== -.PP +.P Also the .IR /proc/ pid /status file for each process has four added lines, @@ -357,7 +357,7 @@ displaying the process's (on which memory nodes it may obtain memory), in the two formats \fBMask Format\fR and \fBList Format\fR (see below) as shown in the following example: -.PP +.P .in +4n .EX Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff @@ -366,7 +366,7 @@ Mems_allowed: ffffffff,ffffffff Mems_allowed_list: 0\-63 .EE .in -.PP +.P The "allowed" fields were added in Linux 2.6.24; the "allowed_list" fields were added in Linux 2.6.26. .\" ================== EXTENDED CAPABILITIES ================== @@ -385,7 +385,7 @@ or .IR mem_exclusive , no other cpuset, other than a direct ancestor or descendant, may share any of the same CPUs or memory nodes. -.PP +.P A cpuset that is .I mem_exclusive restricts kernel allocations for @@ -426,7 +426,7 @@ and other data commonly shared by the kernel across multiple users. All cpusets, whether .I hardwall or not, restrict allocations of memory for user space. -.PP +.P This enables configuring a system so that several independent jobs can share common kernel data, such as filesystem pages, while isolating each job's user allocation in its own cpuset. @@ -437,7 +437,7 @@ all the jobs, and construct child cpusets for each individual job which are not .I hardwall cpusets. -.PP +.P Only a small amount of kernel memory, such as requests from interrupt handlers, is allowed to be taken outside even a .I hardwall @@ -455,7 +455,7 @@ the kernel will run the command supplying the pathname (relative to the mount point of the cpuset filesystem) of the abandoned cpuset. This enables automatic removal of abandoned cpusets. -.PP +.P The default value of .I notify_on_release in the root cpuset at system boot is disabled (0). @@ -463,7 +463,7 @@ The default value of other cpusets at creation is the current value of their parent's .I notify_on_release setting. -.PP +.P The command .I /sbin/cpuset_release_agent is invoked, with the name @@ -471,18 +471,18 @@ is invoked, with the name relative path) of the to-be-released cpuset in .IR argv[1] . -.PP +.P The usual contents of the command .I /sbin/cpuset_release_agent is simply the shell script: -.PP +.P .in +4n .EX #!/bin/sh rmdir /dev/cpuset/$1 .EE .in -.PP +.P As with other flag values below, this flag can be changed by writing an ASCII number 0 or 1 (with optional trailing newline) @@ -494,30 +494,30 @@ The of a cpuset provides a simple per-cpuset running average of the rate that the processes in a cpuset are attempting to free up in-use memory on the nodes of the cpuset to satisfy additional memory requests. -.PP +.P This enables batch managers that are monitoring jobs running in dedicated cpusets to efficiently detect what level of memory pressure that job is causing. -.PP +.P This is useful both on tightly managed systems running a wide mix of submitted jobs, which may choose to terminate or reprioritize jobs that are trying to use more memory than allowed on the nodes assigned them, and with tightly coupled, long-running, massively parallel scientific computing jobs that will dramatically fail to meet required performance goals if they start to use more memory than allowed to them. -.PP +.P This mechanism provides a very economical way for the batch manager to monitor a cpuset for signs of memory pressure. It's up to the batch manager or other user code to decide what action to take if it detects signs of memory pressure. -.PP +.P Unless memory pressure calculation is enabled by setting the pseudo-file .IR /dev/cpuset/cpuset.memory_pressure_enabled , it is not computed for any cpuset, and reads from any .I memory_pressure always return zero, as represented by the ASCII string "0\en". See the \fBWARNINGS\fR section, below. -.PP +.P A per-cpuset, running average is employed for the following reasons: .IP \[bu] 3 Because this meter is per-cpuset rather than per-process or per virtual @@ -535,7 +535,7 @@ the batch scheduler can obtain the key information\[em]memory pressure in a cpuset\[em]with a single read, rather than having to query and accumulate results over all the (dynamically changing) set of processes in the cpuset. -.PP +.P The .I memory_pressure of a cpuset is calculated using a per-cpuset simple digital filter @@ -543,7 +543,7 @@ that is kept within the kernel. For each cpuset, this filter tracks the recent rate at which processes attached to that cpuset enter the kernel direct reclaim code. -.PP +.P The kernel direct reclaim code is entered whenever a process has to satisfy a memory page request by first finding some other page to repurpose, due to lack of any readily available already free pages. @@ -552,7 +552,7 @@ to disk. Unmodified filesystem buffer pages are repurposed by simply dropping them, though if that page is needed again, it will have to be reread from disk. -.PP +.P The .I cpuset.memory_pressure file provides an integer number representing the recent (half-life of @@ -568,14 +568,14 @@ They are called .I cpuset.memory_spread_page and .IR cpuset.memory_spread_slab . -.PP +.P If the per-cpuset Boolean flag file .I cpuset.memory_spread_page is set, then the kernel will spread the filesystem buffers (page cache) evenly over all the nodes that the faulting process is allowed to use, instead of preferring to put those pages on the node where the process is running. -.PP +.P If the per-cpuset Boolean flag file .I cpuset.memory_spread_slab is set, @@ -583,12 +583,12 @@ then the kernel will spread some filesystem-related slab caches, such as those for inodes and directory entries, evenly over all the nodes that the faulting process is allowed to use, instead of preferring to put those pages on the node where the process is running. -.PP +.P The setting of these flags does not affect the data segment (see .BR brk (2)) or stack segment pages of a process. -.PP +.P By default, both kinds of memory spreading are off and the kernel prefers to allocate memory pages on the node local to where the requesting process is running. @@ -596,10 +596,10 @@ If that node is not allowed by the process's NUMA memory policy or cpuset configuration or if there are insufficient free memory pages on that node, then the kernel looks for the nearest node that is allowed and has sufficient free memory. -.PP +.P When new cpusets are created, they inherit the memory spread settings of their parent. -.PP +.P Setting memory spreading causes allocations for the affected page or slab caches to ignore the process's NUMA memory policy and be spread instead. @@ -614,7 +614,7 @@ no cpuset-specified memory spreading is in effect, even if it is. If cpuset memory spreading is subsequently turned off, the NUMA memory policy most recently specified by these calls is automatically reapplied. -.PP +.P Both .I cpuset.memory_spread_page and @@ -623,10 +623,10 @@ are Boolean flag files. By default, they contain "0", meaning that the feature is off for that cpuset. If a "1" is written to that file, that turns the named feature on. -.PP +.P Cpuset-specified memory spreading behaves similarly to what is known (in other contexts) as round-robin or interleave memory placement. -.PP +.P Cpuset-specified memory spreading can provide substantial performance improvements for jobs that: .IP \[bu] 3 @@ -636,7 +636,7 @@ frequently access that data; but also .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 +.P Without this policy, the memory allocation across the nodes in the job's cpuset can become very uneven, @@ -652,19 +652,19 @@ was allocated, so long as it remains allocated, even if the cpuset's memory-placement policy .I mems subsequently changes. -.PP +.P When memory migration is enabled in a cpuset, if the .I mems setting of the cpuset is changed, then any memory page in use by any process in the cpuset that is on a memory node that is no longer allowed will be migrated to a memory node that is allowed. -.PP +.P Furthermore, if a process is moved into a cpuset with .I memory_migrate enabled, any memory pages it uses that were on memory nodes allowed in its previous cpuset, but which are not allowed in its new cpuset, will be migrated to a memory node allowed in the new cpuset. -.PP +.P The relative placement of a migrated page within the cpuset is preserved during these migration operations if possible. For example, @@ -679,7 +679,7 @@ the kernel will look for processes on other more overloaded CPUs and move those processes to the underutilized CPU, within the constraints of such placement mechanisms as cpusets and .BR sched_setaffinity (2). -.PP +.P The algorithmic cost of load balancing and its impact on key shared kernel data structures such as the process list increases more than linearly with the number of CPUs being balanced. @@ -692,17 +692,17 @@ and the cost of load balancing depends on implementation details of the kernel process scheduler, which is subject to change over time, as improved kernel scheduler algorithms are implemented.) -.PP +.P The per-cpuset flag .I sched_load_balance provides a mechanism to suppress this automatic scheduler load balancing in cases where it is not needed and suppressing it would have worthwhile performance benefits. -.PP +.P By default, load balancing is done across all CPUs, except those marked isolated using the kernel boot time "isolcpus=" argument. (See \fBScheduler Relax Domain Level\fR, below, to change this default.) -.PP +.P This default load balancing across all CPUs is not well suited to the following two situations: .IP \[bu] 3 @@ -713,7 +713,7 @@ on separate sets of CPUs, full load balancing is unnecessary. 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. -.PP +.P When the per-cpuset flag .I sched_load_balance is enabled (the default setting), @@ -723,7 +723,7 @@ ensuring that load balancing can move a process (not otherwise pinned, as by .BR sched_setaffinity (2)) from any CPU in that cpuset to any other. -.PP +.P When the per-cpuset flag .I sched_load_balance is disabled, then the @@ -732,7 +732,7 @@ scheduler will avoid load balancing across the CPUs in that cpuset, has .I sched_load_balance enabled. -.PP +.P So, for example, if the top cpuset has the flag .I sched_load_balance enabled, then the scheduler will load balance across all @@ -740,12 +740,12 @@ CPUs, and the setting of the .I sched_load_balance flag in other cpusets has no effect, as we're already fully load balancing. -.PP +.P Therefore in the above two situations, the flag .I sched_load_balance should be disabled in the top cpuset, and only some of the smaller, child cpusets would have this flag enabled. -.PP +.P When doing this, you don't usually want to leave any unpinned processes in the top cpuset that might use nontrivial amounts of CPU, as such processes may be artificially constrained to some subset of CPUs, depending on @@ -753,7 +753,7 @@ the particulars of this flag setting in descendant cpusets. Even if such a process could use spare CPU cycles in some other CPUs, the kernel scheduler might not consider the possibility of load balancing that process to the underused CPU. -.PP +.P Of course, processes pinned to a particular CPU can be left in a cpuset that disables .I sched_load_balance @@ -780,7 +780,7 @@ In any case, of course, tasks will be scheduled to run only on CPUs allowed by their cpuset, as modified by .BR sched_setaffinity (2) system calls. -.PP +.P On small systems, such as those with just a few CPUs, immediate load balancing is useful to improve system interactivity and to minimize wasteful idle CPU cycles. @@ -788,7 +788,7 @@ But on large systems, attempting immediate load balancing across a large number of CPUs can be more costly than it is worth, depending on the particular performance characteristics of the job mix and the hardware. -.PP +.P The exact meaning of the small integer values of .I sched_relax_domain_level will depend on internal @@ -796,12 +796,12 @@ implementation details of the kernel scheduler code and on the non-uniform architecture of the hardware. Both of these will evolve over time and vary by system architecture and kernel version. -.PP +.P As of this writing, when this capability was introduced in Linux 2.6.26, on certain popular architectures, the positive values of .I sched_relax_domain_level have the following meanings. -.PP +.P .PD 0 .TP .B 1 @@ -823,7 +823,7 @@ Perform immediate load balancing across over several Perform immediate load balancing across over all CPUs in system [On NUMA systems]. .PD -.PP +.P The .I sched_relax_domain_level value of zero (0) always means @@ -831,7 +831,7 @@ don't perform immediate load balancing, hence that load balancing is done only periodically, not immediately when a CPU becomes available or another task becomes runnable. -.PP +.P The .I sched_relax_domain_level value of minus one (\-1) @@ -839,7 +839,7 @@ always means use the system default value. The system default value can vary by architecture and kernel version. This system default value can be changed by kernel boot-time "relax_domain_level=" argument. -.PP +.P In the case of multiple overlapping cpusets which have conflicting .I sched_relax_domain_level values, then the highest such value @@ -860,7 +860,7 @@ The \fBMask Format\fR is used to represent CPU and memory-node bit masks in the .IR /proc/ pid /status file. -.PP +.P This format displays each 32-bit word in hexadecimal (using ASCII characters "0" - "9" and "a" - "f"); words are filled with leading zeros, if required. @@ -868,12 +868,12 @@ For masks longer than one word, a comma separator is used between words. Words are displayed in big-endian order, which has the most significant bit first. The hex digits within a word are also in big-endian order. -.PP +.P The number of 32-bit words displayed is the minimum number needed to display all bits of the bit mask, based on the size of the bit mask. -.PP +.P Examples of the \fBMask Format\fR: -.PP +.P .in +4n .EX 00000001 # just bit 0 set @@ -883,15 +883,15 @@ Examples of the \fBMask Format\fR: 00000000,000e3862 # 1,5,6,11\-13,17\-19 set .EE .in -.PP +.P A mask with bits 0, 1, 2, 4, 8, 16, 32, and 64 set displays as: -.PP +.P .in +4n .EX 00000001,00000001,00010117 .EE .in -.PP +.P The first "1" is for bit 64, the second for bit 32, the third for bit 16, the fourth for bit 8, the fifth for bit 4, and the "7" is for bits 2, 1, and 0. @@ -903,9 +903,9 @@ and .I mems is a comma-separated list of CPU or memory-node numbers and ranges of numbers, in ASCII decimal. -.PP +.P Examples of the \fBList Format\fR: -.PP +.P .in +4n .EX 0\-4,9 # bits 0, 1, 2, 3, 4, and 9 set @@ -940,7 +940,7 @@ The permissions of a cpuset are determined by the permissions of the directories and pseudo-files in the cpuset filesystem, normally mounted at .IR /dev/cpuset . -.PP +.P For instance, a process can put itself in some other cpuset (than its current one) if it can write the .I tasks @@ -949,14 +949,14 @@ This requires execute permission on the encompassing directories and write permission on the .I tasks file. -.PP +.P An additional constraint is applied to requests to place some other process in a cpuset. One process may not attach another to a cpuset unless it would have permission to send that process a signal (see .BR kill (2)). -.PP +.P A process may create a child cpuset if it can access and write the parent cpuset directory. It can modify the CPUs or memory nodes @@ -967,7 +967,7 @@ corresponding or .I mems file. -.PP +.P There is one minor difference between the manner in which these permissions are evaluated and the manner in which normal filesystem operation permissions are evaluated. @@ -988,7 +988,7 @@ to its cpuset directory beneath which is a bit unusual) or if some user code converts the relative cpuset path to a full filesystem path. -.PP +.P In theory, this means that user code should specify cpusets using absolute pathnames, which requires knowing the mount point of the cpuset filesystem (usually, but not necessarily, @@ -1024,13 +1024,13 @@ command in some shells does not display an error message if the system call fails. .\" Gack! csh(1)'s echo does this For example, if the command: -.PP +.P .in +4n .EX echo 19 > cpuset.mems .EE .in -.PP +.P failed because memory node 19 was not allowed (perhaps the current system does not have a memory node 19), then the .B echo @@ -1041,7 +1041,7 @@ external command to change cpuset file settings, as this command will display .BR write (2) errors, as in the example: -.PP +.P .in +4n .EX /bin/echo 19 > cpuset.mems @@ -1053,7 +1053,7 @@ errors, as in the example: .SS Memory placement Not all allocations of system memory are constrained by cpusets, for the following reasons. -.PP +.P If hot-plug functionality is used to remove all the CPUs that are currently assigned to a cpuset, then the kernel will automatically update the @@ -1068,7 +1068,7 @@ rather than starving a process that has had all its allowed CPUs or memory nodes taken offline. User code should reconfigure cpusets to refer only to online CPUs and memory nodes when using hot-plug to add or remove such resources. -.PP +.P A few kernel-critical, internal memory-allocation requests, marked GFP_ATOMIC, must be satisfied immediately. The kernel may drop some @@ -1076,7 +1076,7 @@ request or malfunction if one of these allocations fail. If such a request cannot be satisfied within the current process's cpuset, then we relax the cpuset, and look for memory anywhere we can find it. It's better to violate the cpuset than stress the kernel. -.PP +.P Allocations of memory requested by kernel drivers while processing an interrupt lack any relevant process context, and are not confined by cpusets. @@ -1092,7 +1092,7 @@ a different directory is not permitted. The Linux kernel implementation of cpusets sets .I errno to specify the reason for a failed system call affecting cpusets. -.PP +.P The possible .I errno settings and their meaning when set on @@ -1359,7 +1359,7 @@ options using shell commands. .SS Creating and attaching to a cpuset. To create a new cpuset and attach the current command shell to it, the steps are: -.PP +.P .PD 0 .IP (1) 5 mkdir /dev/cpuset (if not already done) @@ -1373,11 +1373,11 @@ Assign CPUs and memory nodes to the new cpuset. .IP (5) Attach the shell to the new cpuset. .PD -.PP +.P For example, the following sequence of commands will set up a cpuset named "Charlie", containing just CPUs 2 and 3, and memory node 1, and then attach the current shell to that cpuset. -.PP +.P .in +4n .EX .RB "$" " mkdir /dev/cpuset" @@ -1399,7 +1399,7 @@ To migrate a job (the set of processes attached to a cpuset) to different CPUs and memory nodes in the system, including moving the memory pages currently allocated to that job, perform the following steps. -.PP +.P .PD 0 .IP (1) 5 Let's say we want to move the job in cpuset @@ -1424,9 +1424,9 @@ Then move each process from to .IR beta . .PD -.PP +.P The following sequence of commands accomplishes this. -.PP +.P .in +4n .EX .RB "$" " cd /dev/cpuset" @@ -1438,22 +1438,22 @@ The following sequence of commands accomplishes this. .RB "$" " while read i; do /bin/echo $i; done < ../alpha/tasks > tasks" .EE .in -.PP +.P The above should move any processes in .I alpha to .IR beta , and any memory held by these processes on memory nodes 2\[en]3 to memory nodes 8\[en]9, respectively. -.PP +.P Notice that the last step of the above sequence did not do: -.PP +.P .in +4n .EX .RB "$" " cp ../alpha/tasks tasks" .EE .in -.PP +.P The .I while loop, rather than the seemingly easier use of the @@ -1462,7 +1462,7 @@ command, was necessary because only one process PID at a time may be written to the .I tasks file. -.PP +.P The same effect (writing one PID at a time) as the .I while loop can be accomplished more efficiently, in fewer keystrokes and in @@ -1470,7 +1470,7 @@ syntax that works on any shell, but alas more obscurely, by using the .B \-u (unbuffered) option of .BR sed (1): -.PP +.P .in +4n .EX .RB "$" " sed \-un p < ../alpha/tasks > tasks" @@ -1493,7 +1493,7 @@ syntax that works on any shell, but alas more obscurely, by using the .BR sched (7), .BR migratepages (8), .BR numactl (8) -.PP +.P .I Documentation/admin\-guide/cgroup\-v1/cpusets.rst in the Linux kernel source tree .\" commit 45ce80fb6b6f9594d1396d44dd7e7c02d596fef8 diff --git a/man7/credentials.7 b/man7/credentials.7 index 653e7a3..ddade68 100644 --- a/man7/credentials.7 +++ b/man7/credentials.7 @@ -4,7 +4,7 @@ .\" .\" 2007-06-13 Creation .\" -.TH credentials 7 2023-03-30 "Linux man-pages 6.05.01" +.TH credentials 7 2023-11-19 "Linux man-pages 6.7" .SH NAME credentials \- process identifiers .SH DESCRIPTION @@ -18,7 +18,7 @@ A PID is represented using the type .I pid_t (defined in .IR <sys/types.h> ). -.PP +.P PIDs are used in a range of system calls to identify the process affected by the call, for example: .BR kill (2), @@ -39,7 +39,7 @@ and .BR waitpid (2). .\" .BR waitid (2), .\" .BR wait4 (2), -.PP +.P A process's PID is preserved across an .BR execve (2). .SS Parent process ID (PPID) @@ -50,7 +50,7 @@ A process can obtain its PPID using .BR getppid (2). A PPID is represented using the type .IR pid_t . -.PP +.P A process's PPID is preserved across an .BR execve (2). .SS Process group ID and session ID @@ -61,13 +61,13 @@ A process can obtain its session ID using .BR getsid (2), and its process group ID using .BR getpgrp (2). -.PP +.P A child created by .BR fork (2) inherits its parent's session ID and process group ID. A process's session ID and process group ID are preserved across an .BR execve (2). -.PP +.P Sessions and process groups are abstractions devised to support shell job control. A process group (sometimes called a "job") is a collection of @@ -80,7 +80,7 @@ A process's group membership can be set using .BR setpgid (2). The process whose process ID is the same as its process group ID is the \fIprocess group leader\fP for that group. -.PP +.P A session is a collection of processes that share the same session ID. All of the members of a process group also have the same session ID (i.e., all of the members of a process group always belong to the @@ -92,7 +92,7 @@ which creates a new session whose session ID is the same as the PID of the process that called .BR setsid (2). The creator of the session is called the \fIsession leader\fP. -.PP +.P All of the processes in a session share a .IR "controlling terminal" . The controlling terminal is established when the session leader @@ -101,7 +101,7 @@ first opens a terminal (unless the flag is specified when calling .BR open (2)). A terminal may be the controlling terminal of at most one session. -.PP +.P At most one of the jobs in a session may be the .IR "foreground job" ; other jobs in the session are @@ -123,7 +123,7 @@ When terminal keys that generate a signal (such as the .I interrupt key, normally control-C) are pressed, the signal is sent to the processes in the foreground job. -.PP +.P Various system calls and library functions may operate on all members of a process group, including @@ -152,7 +152,7 @@ and .I gid_t (defined in .IR <sys/types.h> ). -.PP +.P On Linux, each process has the following user and group identifiers: .IP \[bu] 3 Real user ID and real group ID. @@ -228,7 +228,7 @@ of which a process may be a member. .\" As at 2.6.22-rc2, this file is still read-only. A process can obtain its set of supplementary group IDs using .BR getgroups (2). -.PP +.P A child process created by .BR fork (2) inherits copies of its parent's user and groups IDs. @@ -238,7 +238,7 @@ a process's real user and group ID and supplementary group IDs are preserved; the effective and saved set IDs may be changed, as described in .BR execve (2). -.PP +.P Aside from the purposes noted above, a process's user IDs are also employed in a number of other contexts: .IP \[bu] 3 @@ -267,33 +267,38 @@ that the process may create (see Subject to rules described in the relevant manual pages, a process can use the following APIs to modify its user and group IDs: .TP -.BR setuid "(2) (" setgid (2)) +.BR setuid (2)\~(\c +.BR setgid (2)) Modify the process's real (and possibly effective and saved-set) user (group) IDs. .TP -.BR seteuid "(2) (" setegid (2)) +.BR seteuid (2)\~(\c +.BR setegid (2)) Modify the process's effective user (group) ID. .TP -.BR setfsuid "(2) (" setfsgid (2)) +.BR setfsuid (2)\~(\c +.BR setfsgid (2)) Modify the process's filesystem user (group) ID. .TP -.BR setreuid "(2) (" setregid (2)) +.BR setreuid (2)\~(\c +.BR setregid (2)) Modify the process's real and effective (and possibly saved-set) user (group) IDs. .TP -.BR setresuid "(2) (" setresgid (2)) +.BR setresuid (2)\~(\c +.BR setresgid (2)) Modify the process's real, effective, and saved-set user (group) IDs. .TP .BR setgroups (2) Modify the process's supplementary group list. -.PP +.P Any changes to a process's effective user (group) ID are automatically carried over to the process's filesystem user (group) ID. Changes to a process's effective user or group ID can also affect the process "dumpable" attribute, as described in .BR prctl (2). -.PP +.P Changes to process user and group IDs can affect the capabilities of the process, as described in .BR capabilities (7). @@ -302,7 +307,7 @@ Process IDs, parent process IDs, process group IDs, and session IDs are specified in POSIX.1. The real, effective, and saved set user and groups IDs, and the supplementary group IDs, are specified in POSIX.1. -.PP +.P The filesystem user and group IDs are a Linux extension. .SH NOTES Various fields in the @@ -311,7 +316,7 @@ file show the process credentials described above. See .BR proc (5) for further information. -.PP +.P The POSIX threads specification requires that credentials are shared by all of the threads in a process. However, at the kernel level, Linux maintains separate user and group @@ -4,14 +4,14 @@ .\" .\" $Id: ddp.7,v 1.3 1999/05/13 11:33:22 freitag Exp $ .\" -.TH ddp 7 2023-05-26 "Linux man-pages 6.05.01" +.TH ddp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME ddp \- Linux AppleTalk protocol implementation .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <netatalk/at.h> -.PP +.P .IB ddp_socket " = socket(AF_APPLETALK, SOCK_DGRAM, 0);" .IB raw_socket " = socket(AF_APPLETALK, SOCK_RAW, " protocol ");" .fi @@ -26,12 +26,12 @@ protocol libraries. This page documents the interface for those who wish or need to use the DDP layer directly. -.PP +.P The communication between AppleTalk and the user program works using a BSD-compatible socket interface. For more information on sockets, see .BR socket (7). -.PP +.P An AppleTalk socket is created by calling the .BR socket (2) function with a @@ -52,7 +52,7 @@ For .B SOCK_RAW you must specify .BR ATPROTO_DDP . -.PP +.P Raw sockets may be opened only by a process with effective user ID 0 or when the process has the .B CAP_NET_RAW @@ -60,7 +60,7 @@ capability. .SS Address format An AppleTalk socket address is defined as a combination of a network number, a node number, and a port number. -.PP +.P .in +4n .EX struct at_addr { @@ -75,7 +75,7 @@ struct sockaddr_atalk { }; .EE .in -.PP +.P .I sat_family is always set to .BR AF_APPLETALK . @@ -133,7 +133,7 @@ dead. .TP .I aarp\-tick\-time The timer rate (in seconds) for the timer driving AARP. -.PP +.P The default values match the specification and should never need to be changed. .SS Ioctls @@ -228,14 +228,14 @@ on BSD-derived systems. Many BSD systems fail to check .B SO_BROADCAST when sending broadcast frames; this can lead to compatibility problems. -.PP +.P The raw socket mode is unique to Linux and exists to support the alternative CAP package and AppleTalk monitoring tools more easily. .SH BUGS There are too many inconsistent error values. -.PP +.P The ioctls used to configure routing tables, devices, AARP tables, and other devices are not yet described. .SH SEE ALSO diff --git a/man7/environ.7 b/man7/environ.7 index 345b350..cb7a839 100644 --- a/man7/environ.7 +++ b/man7/environ.7 @@ -12,7 +12,7 @@ .\" Modified Wed Jan 24 06:37:24 2001 by Eric S. Raymond (esr@thyrsus.com) .\" Modified Thu Dec 13 23:53:27 2001 by Martin Schulze <joey@infodrom.org> .\" -.TH environ 7 2023-02-05 "Linux man-pages 6.05.01" +.TH environ 7 2023-10-31 "Linux man-pages 6.7" .SH NAME environ \- user environment .SH SYNOPSIS @@ -32,7 +32,7 @@ When a child process is created via it inherits a .I copy of its parent's environment. -.PP +.P By convention, the strings in .I environ have the form "\fIname\fP\fB=\fP\fIvalue\fP". @@ -41,7 +41,7 @@ the character "\fB=\fP". The value can be anything that can be represented as a string. The name and the value may not contain an embedded null byte (\[aq]\e0\[aq]), since this is assumed to terminate the string. -.PP +.P Environment variables may be placed in the shell's environment by the .I export command in @@ -50,7 +50,7 @@ or by the .I setenv command if you use .BR csh (1). -.PP +.P The initial environment of the shell is populated in various ways, such as definitions from .I /etc/environment @@ -63,21 +63,21 @@ In addition, various shell initialization scripts, such as the system-wide script and per-user initializations script may include commands that add variables to the shell's environment; see the manual page of your preferred shell for details. -.PP +.P Bourne-style shells support the syntax -.PP +.P .in +4n .EX NAME=value command .EE .in -.PP +.P to create an environment variable definition only in the scope of the process that executes .IR command . Multiple variable definitions, separated by white space, may precede .IR command . -.PP +.P Arguments may also be placed in the environment at the point of an .BR exec (3). @@ -87,7 +87,7 @@ A C program can manipulate its environment using the functions .BR setenv (3), and .BR unsetenv (3). -.PP +.P What follows is a list of environment variables typically seen on a system. This list is incomplete and includes only common variables seen @@ -194,7 +194,7 @@ command shall be valid. .\" .B BROWSER .\" The user's preferred utility to browse URLs. Sequence of colon-separated .\" browser commands. See http://www.catb.org/\[ti]esr/BROWSER/ . -.PP +.P 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: @@ -272,14 +272,14 @@ if the .B _GNU_SOURCE feature test macro is defined (see .BR feature_test_macros (7)). -.PP +.P The .BR prctl (2) .B PR_SET_MM_ENV_START and .B PR_SET_MM_ENV_END operations can be used to control the location of the process's environment. -.PP +.P The .BR HOME , .BR LOGNAME , @@ -305,7 +305,7 @@ Clearly there is a security risk here. Many a system command has been tricked into mischief by a user who specified unusual values for .BR IFS " or " LD_LIBRARY_PATH . -.PP +.P There is also the risk of name space pollution. Programs like .I make diff --git a/man7/epoll.7 b/man7/epoll.7 index 02a53e9..a93bc0b 100644 --- a/man7/epoll.7 +++ b/man7/epoll.7 @@ -4,7 +4,7 @@ .\" .\" Davide Libenzi <davidel@xmailserver.org> .\" -.TH epoll 7 2023-05-03 "Linux man-pages 6.05.01" +.TH epoll 7 2023-10-31 "Linux man-pages 6.7" .SH NAME epoll \- I/O event notification facility .SH SYNOPSIS @@ -21,7 +21,7 @@ The .B epoll API can be used either as an edge-triggered or a level-triggered interface and scales well to large numbers of watched file descriptors. -.PP +.P The central concept of the .B epoll API is the @@ -45,7 +45,7 @@ The ready list is a subset of the file descriptors in the interest list. The ready list is dynamically populated by the kernel as a result of I/O activity on those file descriptors. -.PP +.P The following system calls are provided to create and manage an .B epoll @@ -104,7 +104,7 @@ The pipe reader reads 1\ kB of data from A call to .BR epoll_wait (2) is done. -.PP +.P If the .I rfd file descriptor has been added to the @@ -139,7 +139,7 @@ does not consume the whole buffer data, the call to done in step .B 5 might block indefinitely. -.PP +.P An application that employs the .B EPOLLET flag should use nonblocking file descriptors to avoid having a blocking @@ -158,7 +158,7 @@ or .BR write (2) return .BR EAGAIN . -.PP +.P By contrast, when used as a level-triggered interface (the default, when .B EPOLLET @@ -168,7 +168,7 @@ is simply a faster .BR poll (2), and can be used wherever the latter is used since it shares the same semantics. -.PP +.P Since even with edge-triggered .BR epoll , multiple events can be generated upon receipt of multiple chunks of data, @@ -185,7 +185,7 @@ it is the caller's responsibility to rearm the file descriptor using .BR epoll_ctl (2) with .BR EPOLL_CTL_MOD . -.PP +.P If multiple threads (or processes, if child processes have inherited the .B epoll @@ -214,7 +214,7 @@ it is necessary to use the .BR epoll_ctl (2) .B EPOLLWAKEUP flag. -.PP +.P When the .B EPOLLWAKEUP flag is set in the @@ -284,7 +284,7 @@ it will continue to or .BR write (2) from where it stopped before. -.PP +.P .in +4n .EX #define MAX_EVENTS 10 @@ -337,7 +337,7 @@ for (;;) { } .EE .in -.PP +.P When used as an edge-triggered interface, for performance reasons, it is possible to add the file descriptor inside the .B epoll @@ -595,7 +595,7 @@ directory. See .BR proc (5) for further details. -.PP +.P The .BR kcmp (2) .B KCMP_EPOLL_TFD diff --git a/man7/fanotify.7 b/man7/fanotify.7 index eea8835..b0b5121 100644 --- a/man7/fanotify.7 +++ b/man7/fanotify.7 @@ -2,7 +2,7 @@ .\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com> .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH fanotify 7 2023-05-03 "Linux man-pages 6.05.01" +.TH fanotify 7 2023-10-31 "Linux man-pages 6.7" .SH NAME fanotify \- monitoring filesystem events .SH DESCRIPTION @@ -15,14 +15,14 @@ The support for those events was added in Linux 5.1. (See .BR inotify (7) for details of an API that did notify those events pre Linux 5.1.) -.PP +.P Additional capabilities compared to the .BR inotify (7) API include the ability to monitor all of the objects in a mounted filesystem, the ability to make access permission decisions, and the possibility to read or modify files before access by other applications. -.PP +.P The following system calls are used with this API: .BR fanotify_init (2), .BR fanotify_mark (2), @@ -35,11 +35,11 @@ The .BR fanotify_init (2) system call creates and initializes an fanotify notification group and returns a file descriptor referring to it. -.PP +.P An fanotify notification group is a kernel-internal object that holds a list of files, directories, filesystems, and mounts for which events shall be created. -.PP +.P For each entry in an fanotify notification group, two bit masks exist: the .I mark mask and the @@ -50,13 +50,13 @@ The ignore mask defines activities for which no event shall be generated. Having these two types of masks permits a filesystem, mount, or directory to be marked for receiving events, while at the same time ignoring events for specific objects under a mount or directory. -.PP +.P The .BR fanotify_mark (2) system call adds a file, directory, filesystem, or mount to a notification group and specifies which events shall be reported (or ignored), or removes or modifies such an entry. -.PP +.P A possible usage of the ignore mask is for a file cache. Events of interest for a file cache are modification of a file and closing of the same. @@ -69,7 +69,7 @@ is closed. Hence, the modify event can be added to the ignore mask. Upon receiving the close event, the modify event can be removed from the ignore mask and the file cache entry can be updated. -.PP +.P The entries in the fanotify notification groups refer to files and directories via their inode number and to mounts via their mount ID. If files or directories are renamed or moved within the same mount, @@ -85,7 +85,7 @@ or similar) from the fanotify file descriptor returned by .BR fanotify_init (2). -.PP +.P Two types of events are generated: .I notification events and @@ -98,7 +98,7 @@ Permission events are requests to the receiving application to decide whether permission for a file access shall be granted. For these events, the recipient must write a response which decides whether access is granted or not. -.PP +.P An event is removed from the event queue of the fanotify group when it has been read. Permission events that have been read are kept in an internal list of the @@ -117,11 +117,11 @@ is not specified in the call to until either a file event occurs or the call is interrupted by a signal (see .BR signal (7)). -.PP +.P After a successful .BR read (2), the read buffer contains one or more of the following structures: -.PP +.P .in +4n .EX struct fanotify_event_metadata { @@ -135,7 +135,7 @@ struct fanotify_event_metadata { }; .EE .in -.PP +.P Information records are supplemental pieces of information that may be provided alongside the generic @@ -193,7 +193,7 @@ It is imperative for event listeners to inspect the field of this structure in order to determine the type of information record that had been received for a given event. -.PP +.P In cases where an fanotify group identifies filesystem objects by file handles, event listeners should also expect to @@ -201,24 +201,24 @@ receive one or more of the below information record objects alongside the generic .I fanotify_event_metadata structure within the read buffer: -.PP +.P .in +4n .EX struct fanotify_event_info_fid { struct fanotify_event_info_header hdr; __kernel_fsid_t fsid; - unsigned char file_handle[0]; + unsigned char handle[]; }; .EE .in -.PP +.P In cases where an fanotify group is initialized with .BR FAN_REPORT_PIDFD , event listeners should expect to receive the below information record object alongside the generic .I fanotify_event_metadata structure within the read buffer: -.PP +.P .in +4n .EX struct fanotify_event_info_pidfd { @@ -227,7 +227,7 @@ struct fanotify_event_info_pidfd { }; .EE .in -.PP +.P In case of a .B FAN_FS_ERROR event, @@ -236,7 +236,7 @@ is returned alongside the generic .I fanotify_event_metadata structure within the read buffer. This structure is defined as follows: -.PP +.P .in +4n .EX struct fanotify_event_info_error { @@ -246,7 +246,7 @@ struct fanotify_event_info_error { }; .EE .in -.PP +.P All information records contain a nested structure of type .IR fanotify_event_info_header . This structure holds meta-information about the information record @@ -254,7 +254,7 @@ that may have been returned alongside the generic .I fanotify_event_metadata structure. This structure is defined as follows: -.PP +.P .in +4n .EX struct fanotify_event_info_header { @@ -264,17 +264,17 @@ struct fanotify_event_info_header { }; .EE .in -.PP +.P For performance reasons, it is recommended to use a large buffer size (for example, 4096 bytes), so that multiple events can be retrieved by a single .BR read (2). -.PP +.P The return value of .BR read (2) is the number of bytes placed in the buffer, or \-1 in case of an error (but see BUGS). -.PP +.P The fields of the .I fanotify_event_metadata structure are as follows: @@ -343,13 +343,13 @@ was set in .BR fanotify_init (2), this is the TID of the thread that caused the event. Otherwise, this the PID of the process that caused the event. -.PP +.P A program listening to fanotify events can compare this PID to the PID returned by .BR getpid (2), to determine whether the event is caused by the listener itself, or is due to a file access by another process. -.PP +.P The bit mask in .I mask indicates which events have occurred for a single filesystem object. @@ -359,7 +359,7 @@ In particular, consecutive events for the same filesystem object and originating from the same process may be merged into a single event, with the exception that two permission events are never merged into one queue entry. -.PP +.P The bits that may appear in .I mask are as follows: @@ -446,7 +446,7 @@ open the filesystem object for execution shall be granted. See NOTES in .BR fanotify_mark (2) for additional details. -.PP +.P To check for any close event, the following bit mask may be used: .TP .B FAN_CLOSE @@ -458,7 +458,7 @@ This is a synonym for: FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE .EE .in -.PP +.P To check for any move event, the following bit mask may be used: .TP .B FAN_MOVE @@ -470,7 +470,7 @@ This is a synonym for: FAN_MOVED_FROM | FAN_MOVED_TO .EE .in -.PP +.P The following bits may appear in .I mask only in conjunction with other event type bits: @@ -487,7 +487,7 @@ The .B FAN_ONDIR flag is reported in an event mask only if the fanotify group identifies filesystem objects by file handles. -.PP +.P Information records that are supplied alongside the generic .I fanotify_event_metadata structure will always contain a nested structure of type @@ -528,7 +528,7 @@ is not expected to be larger than .RI ( event_len \- .IR metadata_len ). -.PP +.P The fields of the .I fanotify_event_info_fid structure are as follows: @@ -576,8 +576,9 @@ and contains the same value as when calling .BR statfs (2). .TP -.I file_handle -This is a variable length structure of type struct file_handle. +.I handle +This field contains a variable-length structure of type +.IR "struct file_handle" . It is an opaque handle that corresponds to a specified object on a filesystem as returned by .BR name_to_handle_at (2). @@ -601,14 +602,14 @@ if the value of field is .BR FAN_EVENT_INFO_TYPE_FID , the -.I file_handle +.I handle identifies the object correlated to the event. If the value of .I info_type field is .BR FAN_EVENT_INFO_TYPE_DFID , the -.I file_handle +.I handle identifies the directory object correlated to the event or the parent directory of a non-directory object correlated to the event. If the value of @@ -616,13 +617,13 @@ If the value of field is .BR FAN_EVENT_INFO_TYPE_DFID_NAME , the -.I file_handle +.I handle identifies the same directory object that would be reported with .B FAN_EVENT_INFO_TYPE_DFID and the file handle is followed by a null terminated string that identifies the name of a directory entry in that directory, or '.' to identify the directory object itself. -.PP +.P The fields of the .I fanotify_event_info_pidfd structure are as follows: @@ -667,7 +668,7 @@ Once the event listener has dealt with an event and the pidfd is no longer required, the pidfd should be closed via .BR close (2). -.PP +.P The fields of the .I fanotify_event_info_error structure are as follows: @@ -686,7 +687,7 @@ Identifies the type of error that occurred. .I error_count This is a counter of the number of errors suppressed since the last error was read. -.PP +.P The following macros are provided to iterate over a buffer containing fanotify event metadata returned by a .BR read (2) @@ -719,7 +720,7 @@ has been skipped over (i.e., it subtracts .I meta\->event_len from .IR len ). -.PP +.P In addition, there is: .TP .B FAN_EVENT_METADATA_LEN @@ -739,7 +740,7 @@ For permission events, the application must .BR write (2) a structure of the following form to the fanotify file descriptor: -.PP +.P .in +4n .EX struct fanotify_response { @@ -748,7 +749,7 @@ struct fanotify_response { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I fd @@ -762,7 +763,7 @@ Its value must be either to allow the file operation or .B FAN_DENY to deny the file operation. -.PP +.P If access is denied, the requesting application call will receive an .B EPERM error. @@ -786,19 +787,19 @@ field of the existing .B FAN_FS_ERROR event record, but details about the errors are lost. -.PP +.P Errors reported by .B FAN_FS_ERROR are generic .I errno values, but not all kinds of error types are reported by all filesystems. -.PP +.P Errors not directly related to a file (i.e. super block corruption) are reported with an invalid -.IR file_handle . +.IR handle . For these errors, the -.I file_handle +.I handle will have the field .I handle_type set to @@ -823,7 +824,7 @@ of process See .BR proc (5) for details. -.PP +.P Since Linux 5.13, .\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b the following interfaces can be used to control the amount of @@ -889,7 +890,7 @@ was specified in the argument when calling .BR fanotify_init (2) and an event occurred for a monitored file that is currently being executed. -.PP +.P In addition to the usual errors for .BR write (2), the following errors can occur when writing to the fanotify file descriptor: @@ -924,19 +925,19 @@ Fanotify reports only events that a user-space program triggers through the filesystem API. As a result, it does not catch remote events that occur on network filesystems. -.PP +.P The fanotify API does not report file accesses and modifications that may occur because of .BR mmap (2), .BR msync (2), and .BR munmap (2). -.PP +.P Events for directories are created only if the directory itself is opened, read, and closed. Adding, removing, or changing children of a marked directory does not create events for the monitored directory itself. -.PP +.P Fanotify monitoring of directories is not recursive: to monitor subdirectories under a directory, additional marks must be created. @@ -951,7 +952,7 @@ Monitoring mounts offers the capability to monitor a whole directory tree in a race-free manner. Monitoring filesystems offers the capability to monitor changes made from any mount of a filesystem instance in a race-free manner. -.PP +.P The event queue can overflow. In this case, events are lost. .SH BUGS @@ -965,7 +966,7 @@ calls to generate .B FAN_MODIFY events. -.PP +.P As of Linux 3.17, the following bugs exist: .IP \[bu] 3 @@ -1010,7 +1011,7 @@ and When a permission event occurs, a .B FAN_ALLOW response is given. -.PP +.P The following shell session shows an example of running this program. This session involved editing the file @@ -1022,7 +1023,7 @@ After the file was closed, a .B FAN_CLOSE_WRITE event occurred. Execution of the program ends when the user presses the ENTER key. -.PP +.P .in +4n .EX # \fB./fanotify_example /home\fP @@ -1240,10 +1241,10 @@ The event mask indicates which type of filesystem object\[em]either a file or a directory\[em]was created. Once all events have been read from the buffer and processed accordingly, the program simply terminates. -.PP +.P The following shell sessions show two different invocations of this program, with different actions performed on a watched object. -.PP +.P The first session shows a mark being placed on .IR /home/user . This is followed by the creation of a regular file, @@ -1254,7 +1255,7 @@ event being generated and reported against the file's parent watched directory object and with the created file name. Program execution ends once all events captured within the buffer have been processed. -.PP +.P .in +4n .EX # \fB./fanotify_fid /home/user\fP @@ -1267,7 +1268,7 @@ All events processed successfully. Program exiting. $ \fBtouch /home/user/testfile.txt\fP # In another terminal .EE .in -.PP +.P The second session shows a mark being placed on .IR /home/user . This is followed by the creation of a directory, @@ -1277,7 +1278,7 @@ This specific action results in a event being generated and is reported with the .B FAN_ONDIR flag set and with the created directory name. -.PP +.P .in +4n .EX # \fB./fanotify_fid /home/user\fP diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7 index 4e264d8..ee414dd 100644 --- a/man7/feature_test_macros.7 +++ b/man7/feature_test_macros.7 @@ -2,13 +2,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH feature_test_macros 7 2023-07-15 "Linux man-pages 6.05.01" +.TH feature_test_macros 7 2023-10-31 "Linux man-pages 6.7" .SH NAME feature_test_macros \- feature test macros .SH DESCRIPTION Feature test macros allow the programmer to control the definitions that are exposed by system header files when a program is compiled. -.PP +.P .B NOTE: In order to be effective, a feature test macro .IR "must be defined before including any header files" . @@ -25,7 +25,7 @@ macro may have no effect because the header itself includes .I <xyz.h> (POSIX explicitly allows this): -.PP +.P .in +4n .EX #include <abc.h> @@ -33,12 +33,12 @@ itself includes #include <xyz.h> .EE .in -.PP +.P Some feature test macros are useful for creating portable applications, by preventing nonstandard definitions from being exposed. Other macros can be used to expose nonstandard definitions that are not exposed by default. -.PP +.P The precise effects of each of the feature test macros described below can be ascertained by inspecting the .I <features.h> @@ -56,23 +56,23 @@ the manual page SYNOPSIS typically includes a note of the following form (this example from the .BR acct (2) manual page): -.PP +.P .RS .B #include <unistd.h> -.PP +.P .BI "int acct(const char *" filename ); -.PP +.P .RS -4 .EX Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .EE .RE -.PP +.P .BR acct (): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) .RE -.PP +.P The .B || means that in order to obtain the declaration of @@ -82,44 +82,44 @@ from .I either of the following macro definitions must be made before including any header files: -.PP +.P .in +4n .EX #define _BSD_SOURCE #define _XOPEN_SOURCE /* or any value < 500 */ .EE .in -.PP +.P Alternatively, equivalent definitions can be included in the compilation command: -.PP +.P .in +4n .EX cc \-D_BSD_SOURCE cc \-D_XOPEN_SOURCE # Or any value < 500 .EE .in -.PP +.P Note that, as described below, .BR "some feature test macros are defined by default" , so that it may not always be necessary to explicitly specify the feature test macro(s) shown in the SYNOPSIS. -.PP +.P In a few cases, manual pages use a shorthand for expressing the feature test macro requirements (this example from .BR readahead (2)): -.PP +.P .RS +4 .EX .B #define _GNU_SOURCE .B #define _FILE_OFFSET_BITS 64 .B #include <fcntl.h> -.PP +.P .BI "ssize_t readahead(int " fd ", off_t *" offset ", size_t " count ); .EE .RE -.PP +.P This format is employed when the feature test macros ensure that the proper function declarations are visible, and the macros are not defined by default. @@ -128,7 +128,7 @@ The paragraphs below explain how feature test macros are handled in glibc 2.\fIx\fP, .I x > 0. -.PP +.P First, though, a summary of a few details for the impatient: .IP \[bu] 3 The macros that you most likely need to use in modern source code are @@ -193,7 +193,7 @@ _XOPEN_SOURCE >= 700 .\" The details in glibc 2.0 are simpler, but combining a .\" a description of them with the details in later glibc versions .\" would make for a complicated description. -.PP +.P glibc understands the following feature test macros: .TP .B __STRICT_ANSI__ @@ -683,7 +683,7 @@ and (200112L before glibc 2.10; 199506L before glibc 2.4; 199309L before glibc 2.1). -.PP +.P If any of .BR __STRICT_ANSI__ , .BR _ISOC99_SOURCE , @@ -705,7 +705,7 @@ is explicitly defined, then and .B _DEFAULT_SOURCE are not defined by default. -.PP +.P If .B _POSIX_SOURCE and @@ -722,7 +722,7 @@ is defined with the value 1; and .IP \[bu] .B _POSIX_C_SOURCE is defined with one of the following values: -.RS 3 +.RS .IP \[bu] 3 2, if @@ -760,7 +760,7 @@ depends on the glibc version: 200112L, since glibc 2.4 to glibc 2.9; and 200809L, since glibc 2.10. .RE -.PP +.P Multiple macros can be defined; the results are additive. .SH STANDARDS POSIX.1 specifies @@ -768,11 +768,11 @@ POSIX.1 specifies .BR _POSIX_SOURCE , and .BR _XOPEN_SOURCE . -.PP +.P .B _FILE_OFFSET_BITS is not specified by any standard, but is employed on some other implementations. -.PP +.P .BR _BSD_SOURCE , .BR _SVID_SOURCE , .BR _DEFAULT_SOURCE , @@ -793,7 +793,7 @@ Other systems have an analogous file, but typically with a different name. This header file is automatically included by other header files as required: it is not necessary to explicitly include it in order to employ feature test macros. -.PP +.P According to which of the above feature test macros are defined, .I <features.h> internally defines various other macros that are checked by @@ -811,7 +811,7 @@ feature test macros are set depending on the glibc version and what feature test macros are explicitly set. The following shell session, on a system with glibc 2.10, shows some examples of what we would see: -.PP +.P .in +4n .EX $ \fBcc ftm.c\fP @@ -929,9 +929,9 @@ main(int argc, char *argv[]) .BR libc (7), .BR standards (7), .BR system_data_types (7) -.PP +.P The section "Feature Test Macros" under .IR "info libc" . .\" But beware: the info libc document is out of date (Jul 07, mtk) -.PP +.P .I /usr/include/features.h diff --git a/man7/fifo.7 b/man7/fifo.7 index f27dcc7..6241a43 100644 --- a/man7/fifo.7 +++ b/man7/fifo.7 @@ -4,7 +4,7 @@ .\" .\" 990620 - page created - aeb@cwi.nl .\" -.TH fifo 7 2023-07-15 "Linux man-pages 6.05.01" +.TH fifo 7 2023-10-31 "Linux man-pages 6.7" .SH NAME fifo \- first-in first-out special file, named pipe .SH DESCRIPTION @@ -19,14 +19,14 @@ Thus, the FIFO special file has no contents on the filesystem; the filesystem entry merely serves as a reference point so that processes can access the pipe using a name in the filesystem. -.PP +.P The kernel maintains exactly one pipe object for each FIFO special file that is opened by at least one process. The FIFO must be opened on both ends (reading and writing) before data can be passed. Normally, opening the FIFO blocks until the other end is opened also. -.PP +.P A process can open a FIFO in nonblocking mode. In this case, opening for read-only succeeds even if no one has @@ -35,7 +35,7 @@ fails with .B ENXIO (no such device or address) unless the other end has already been opened. -.PP +.P Under Linux, opening a FIFO for read and write will succeed both in blocking and nonblocking mode. POSIX leaves this @@ -48,12 +48,12 @@ with itself should be very careful to avoid deadlocks. .SH NOTES For details of the semantics of I/O on FIFOs, see .BR pipe (7). -.PP +.P When a process tries to write to a FIFO that is not opened for read on the other side, the process is sent a .B SIGPIPE signal. -.PP +.P FIFO special files can be created by .BR mkfifo (3), and are indicated by diff --git a/man7/futex.7 b/man7/futex.7 index 233933b..52af91f 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: MIT .\" -.TH futex 7 2022-10-30 "Linux man-pages 6.05.01" +.TH futex 7 2023-10-31 "Linux man-pages 6.7" .SH NAME futex \- fast user-space locking .SH SYNOPSIS @@ -20,24 +20,24 @@ locking and semaphores. Futexes are very basic and lend themselves well for building higher-level locking abstractions such as mutexes, condition variables, read-write locks, barriers, and semaphores. -.PP +.P Most programmers will in fact not be using futexes directly but will instead rely on system libraries built on them, such as the Native POSIX Thread Library (NPTL) (see .BR pthreads (7)). -.PP +.P A futex is identified by a piece of memory which can be shared between processes or threads. In these different processes, the futex need not have identical addresses. In its bare form, a futex has semaphore semantics; it is a counter that can be incremented and decremented atomically; processes can wait for the value to become positive. -.PP +.P Futex operation occurs entirely in user space for the noncontended case. The kernel is involved only to arbitrate the contended case. As any sane design will strive for noncontention, futexes are also optimized for this situation. -.PP +.P In its bare form, a futex is an aligned integer which is touched only by atomic assembler instructions. This integer is four bytes long on all platforms. @@ -50,13 +50,13 @@ Any futex operation starts in user space, but it may be necessary to communicate with the kernel using the .BR futex (2) system call. -.PP +.P To "up" a futex, execute the proper assembler instructions that will cause the host CPU to atomically increment the integer. Afterward, check if it has in fact changed from 0 to 1, in which case there were no waiters and the operation is done. This is the noncontended case which is fast and should be common. -.PP +.P In the contended case, the atomic increment changed the counter from \-1 (or some other negative number). If this is detected, there are waiters. @@ -64,7 +64,7 @@ User space should now set the counter to 1 and instruct the kernel to wake up any waiters using the .B FUTEX_WAKE operation. -.PP +.P Waiting on a futex, to "down" it, is the reverse operation. Atomically decrement the counter and check if it changed to 0, in which case the operation is done and the futex was uncontended. @@ -73,7 +73,7 @@ and request that the kernel wait for another process to up the futex. This is done using the .B FUTEX_WAIT operation. -.PP +.P The .BR futex (2) system call can optionally be passed a timeout specifying how long @@ -95,12 +95,12 @@ abstraction for end users. Implementors are expected to be assembly literate and to have read the sources of the futex user-space library referenced below. -.PP +.P This man page illustrates the most common use of the .BR futex (2) primitives; it is by no means the only one. .\" .SH AUTHORS -.\" .PP +.\" .P .\" Futexes were designed and worked on by Hubertus Franke .\" (IBM Thomas J. Watson Research Center), .\" Matthew Kirkwood, Ingo Molnar (Red Hat) and @@ -113,7 +113,7 @@ primitives; it is by no means the only one. .BR set_robust_list (2), .BR set_tid_address (2), .BR pthreads (7) -.PP +.P .I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux (proceedings of the Ottawa Linux Symposium 2002), futex example library, futex-*.tar.bz2 diff --git a/man7/glob.7 b/man7/glob.7 index 466701c..0130c80 100644 --- a/man7/glob.7 +++ b/man7/glob.7 @@ -4,7 +4,7 @@ .\" .\" 2003-08-24 fix for / by John Kristoff + joey .\" -.TH glob 7 2023-03-08 "Linux man-pages 6.05.01" +.TH glob 7 2023-10-31 "Linux man-pages 6.7" .SH NAME glob \- globbing pathnames .SH DESCRIPTION @@ -12,11 +12,11 @@ Long ago, in UNIX\ V6, there was a program .I /etc/glob that would expand wildcard patterns. Soon afterward this became a shell built-in. -.PP +.P These days there is also a library routine .BR glob (3) that will perform this function for a user program. -.PP +.P The rules are as follows (POSIX.2, 3.13). .SS Wildcard matching A string is a wildcard pattern if it contains one of the @@ -25,14 +25,14 @@ Globbing is the operation that expands a wildcard pattern into the list of pathnames matching the pattern. Matching is defined by: -.PP +.P A \[aq]?\[aq] (not between brackets) matches any single character. -.PP +.P A \[aq]*\[aq] (not between brackets) matches any string, including the empty string. -.PP +.P .B "Character classes" -.PP +.P An expression "\fI[...]\fP" where the first character after the leading \[aq][\[aq] is not an \[aq]!\[aq] matches a single character, namely any of the characters enclosed by the brackets. @@ -41,9 +41,9 @@ therefore \[aq]]\[aq] can be allowed between the brackets, provided that it is the first character. (Thus, "\fI[][!]\fP" matches the three characters \[aq][\[aq], \[aq]]\[aq], and \[aq]!\[aq].) -.PP +.P .B Ranges -.PP +.P There is one special convention: two characters separated by \[aq]\-\[aq] denote a range. (Thus, @@ -55,15 +55,15 @@ by making it the first or last character between the brackets. and "\fI[\-\-0]\fP" matches the three characters \[aq]\-\[aq], \[aq].\[aq], and \[aq]0\[aq], since \[aq]/\[aq] cannot be matched.) -.PP +.P .B Complementation -.PP +.P An expression "\fI[!...]\fP" matches a single character, namely any character that is not matched by the expression obtained by removing the first \[aq]!\[aq] from it. (Thus, "\fI[!]a\-]\fP" matches any single character except \[aq]]\[aq], \[aq]a\[aq], and \[aq]\-\[aq].) -.PP +.P One can remove the special meaning of \[aq]?\[aq], \[aq]*\[aq], and \[aq][\[aq] by preceding them by a backslash, or, @@ -79,7 +79,7 @@ A \[aq]/\[aq] in a pathname cannot be matched by a \[aq]?\[aq] or \[aq]*\[aq] wildcard, or by a range like "\fI[.\-0]\fP". A range containing an explicit \[aq]/\[aq] character is syntactically incorrect. (POSIX requires that syntactically incorrect patterns are left unchanged.) -.PP +.P If a filename starts with a \[aq].\[aq], this character must be matched explicitly. (Thus, \fIrm\ *\fP will not remove .profile, and \fItar\ c\ *\fP will not @@ -90,11 +90,11 @@ into the list of matching pathnames" was the original UNIX definition. It allowed one to have patterns that expand into an empty list, as in -.PP +.P .nf xv \-wait 0 *.gif *.jpg .fi -.PP +.P where perhaps no *.gif files are present (and this is not an error). However, POSIX requires that a wildcard pattern is left @@ -103,31 +103,31 @@ matching pathnames is empty. With .I bash one can force the classical behavior using this command: -.PP +.P .in +4n .EX shopt \-s nullglob .EE .in .\" In Bash v1, by setting allow_null_glob_expansion=true -.PP +.P (Similar problems occur elsewhere. For example, where old scripts have -.PP +.P .in +4n .EX rm \`find . \-name "*\[ti]"\` .EE .in -.PP +.P new scripts require -.PP +.P .in +4n .EX rm \-f nosuchfile \`find . \-name "*\[ti]"\` .EE .in -.PP +.P to avoid error messages from .I rm called with an empty argument list.) @@ -139,7 +139,7 @@ First of all, they match filenames, rather than text, and secondly, the conventions are not the same: for example, in a regular expression \[aq]*\[aq] means zero or more copies of the preceding thing. -.PP +.P Now that regular expressions have bracket expressions where the negation is indicated by a \[aq]\[ha]\[aq], POSIX has declared the effect of a wildcard pattern "\fI[\[ha]...]\fP" to be undefined. @@ -161,21 +161,21 @@ expression: namely (i) the negation, (ii) explicit single characters, and (iii) ranges. POSIX specifies ranges in an internationally more useful way and adds three more types: -.PP +.P (iii) Ranges X\-Y comprise all characters that fall between X and Y (inclusive) in the current collating sequence as defined by the .B LC_COLLATE category in the current locale. -.PP +.P (iv) Named character classes, like -.PP +.P .nf [:alnum:] [:alpha:] [:blank:] [:cntrl:] [:digit:] [:graph:] [:lower:] [:print:] [:punct:] [:space:] [:upper:] [:xdigit:] .fi -.PP +.P so that one can say "\fI[[:lower:]]\fP" instead of "\fI[a\-z]\fP", and have things work in Denmark, too, where there are three letters past \[aq]z\[aq] in the alphabet. @@ -183,13 +183,13 @@ These character classes are defined by the .B LC_CTYPE category in the current locale. -.PP +.P (v) Collating symbols, like "\fI[.ch.]\fP" or "\fI[.a-acute.]\fP", where the string between "\fI[.\fP" and "\fI.]\fP" is a collating element defined for the current locale. Note that this may be a multicharacter element. -.PP +.P (vi) Equivalence class expressions, like "\fI[=a=]\fP", where the string between "\fI[=\fP" and "\fI=]\fP" is any collating element from its equivalence class, as defined for the diff --git a/man7/hier.7 b/man7/hier.7 index 314d28a..497e0f5 100644 --- a/man7/hier.7 +++ b/man7/hier.7 @@ -8,7 +8,7 @@ .\" Modified Mon Feb 6 16:41:00 1999 by Nicolás Lichtmaier <nick@debian.org> .\" Modified Tue Feb 8 16:46:45 2000 by Chris Pepper <pepper@tgg.com> .\" Modified Fri Sep 7 20:32:45 2001 by Tammy Fox <tfox@redhat.com> -.TH hier 7 2023-04-18 "Linux man-pages 6.05.01" +.TH hier 7 2023-10-31 "Linux man-pages 6.7" .SH NAME hier \- description of the filesystem hierarchy .SH DESCRIPTION @@ -650,5 +650,5 @@ different distributions and systems may be configured differently. .BR proc (5), .BR file\-hierarchy (7), .BR mount (8) -.PP +.P The Filesystem Hierarchy Standard diff --git a/man7/hostname.7 b/man7/hostname.7 index 60940ba..58d00d1 100644 --- a/man7/hostname.7 +++ b/man7/hostname.7 @@ -8,14 +8,14 @@ .\" .\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and modified for Linux. .\" -.TH hostname 7 2022-10-30 "Linux man-pages 6.05.01" +.TH hostname 7 2023-11-11 "Linux man-pages 6.7" .SH NAME hostname \- hostname resolution description .SH DESCRIPTION Hostnames are domains, where a domain is a hierarchical, dot-separated list of subdomains; for example, the machine "monet", in the "example" subdomain of the "com" domain would be represented as "monet.example.com". -.PP +.P Each element of the hostname must be from 1 to 63 characters long and the entire hostname, including the dots, can be at most 253 characters long. Valid characters for hostnames are @@ -30,24 +30,24 @@ to .IR 9 , and the hyphen (\-). A hostname may not start with a hyphen. -.PP +.P Hostnames are often used with network client and server programs, which must generally translate the name to an address for use. (This task is generally performed by either .BR getaddrinfo (3) or the obsolete .BR gethostbyname (3).) -.PP +.P Hostnames are resolved by the NSS framework in glibc according to the .B hosts configuration in -.BR nsswitch.conf . +.BR nsswitch.conf (5). The DNS-based name resolver (in the .B dns NSS service module) resolves them in the following fashion. -.PP +.P If the name consists of a single component, that is, contains no dot, and if the environment variable .B HOSTALIASES @@ -60,11 +60,11 @@ to be substituted for that alias. If a case-insensitive match is found between the hostname to be resolved and the first field of a line in the file, the substituted name is looked up with no further processing. -.PP +.P If the input name ends with a trailing dot, the trailing dot is removed, and the remaining name is looked up with no further processing. -.PP +.P If the input name does not end with a trailing dot, it is looked up by searching through a list of domains until a match is found. The default search list includes first the local domain, @@ -84,11 +84,11 @@ by a system-wide configuration file (see .BR resolver (5), .BR mailaddr (7), .BR named (8) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc1123.txt IETF RFC\ 1123 .UE -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc1178.txt IETF RFC\ 1178 .UE diff --git a/man7/icmp.7 b/man7/icmp.7 index cd54614..3969fe2 100644 --- a/man7/icmp.7 +++ b/man7/icmp.7 @@ -5,7 +5,7 @@ .\" .\" $Id: icmp.7,v 1.6 2000/08/14 08:03:45 ak Exp $ .\" -.TH icmp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH icmp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME icmp \- Linux IPv4 ICMP kernel module. .SH DESCRIPTION @@ -16,7 +16,7 @@ The user doesn't interact directly with this module; instead it communicates with the other protocols in the kernel and these pass the ICMP errors to the application layers. The kernel ICMP module also answers ICMP requests. -.PP +.P A user protocol may receive ICMP packets for all local sockets by opening a raw socket with the protocol .BR IPPROTO_ICMP . @@ -28,7 +28,7 @@ The types of ICMP packets passed to the socket can be filtered using the socket option. ICMP packets are always processed by the kernel too, even when passed to a user socket. -.PP +.P Linux limits the rate of ICMP error packets to each destination. .B ICMP_REDIRECT and @@ -143,7 +143,7 @@ H Address Mask Request I Address Mask Reply .TE .RE -.PP +.P The bits marked with an asterisk are rate limited by default (see the default mask above). .TP @@ -163,7 +163,7 @@ means no group is allowed to create ICMP Echo sockets. Support for the .B ICMP_ADDRESS request was removed in Linux 2.2. -.PP +.P Support for .B ICMP_SOURCE_QUENCH was removed in Linux 2.2. @@ -173,18 +173,18 @@ As many other implementations don't support raw sockets, this feature should not be relied on in portable programs. .\" not really true ATM -.\" .PP +.\" .P .\" Linux ICMP should be compliant to RFC 1122. -.PP +.P .B ICMP_REDIRECT packets are not sent when Linux is not acting as a router. They are also accepted only from the old gateway defined in the routing table and the redirect routes are expired after some time. -.PP +.P The 64-bit timestamp returned by .B ICMP_TIMESTAMP is in milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P Linux ICMP internally uses a raw socket to send ICMPs. This raw socket may appear in .BR netstat (8) @@ -192,5 +192,5 @@ output with a zero inode. .SH SEE ALSO .BR ip (7), .BR rdisc (8) -.PP +.P RFC\ 792 for a description of the ICMP protocol. diff --git a/man7/inode.7 b/man7/inode.7 index 3cbdeee..7054fe8 100644 --- a/man7/inode.7 +++ b/man7/inode.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH inode 7 2023-07-30 "Linux man-pages 6.05.01" +.TH inode 7 2023-10-31 "Linux man-pages 6.7" .SH NAME inode \- file inode information .SH DESCRIPTION @@ -17,7 +17,7 @@ structure, or which returns a .I statx structure. -.PP +.P The following is a list of the information typically found in, or associated with, the file inode, with the names of the corresponding structure fields returned by @@ -56,7 +56,6 @@ Additional links to an existing file are created using .BR link (2). .TP User ID -.I st_uid \fIstat.st_uid\fP; \fIstatx.stx_uid\fP .IP This field records the user ID of the owner of the file. @@ -99,7 +98,7 @@ This field gives the "preferred" blocksize for efficient filesystem I/O. an inefficient read-modify-rewrite.) .TP Number of blocks allocated to the file -\fIstat.st_blocks\fP; \fIstatx.stx_size\fP +\fIstat.st_blocks\fP; \fIstatx.stx_blocks\fP .IP This field indicates the number of blocks allocated to the file, 512-byte units, @@ -185,12 +184,12 @@ Last status change timestamp (ctime) This is the file's last status change timestamp. It is changed by writing or by setting inode information (i.e., owner, group, link count, mode, etc.). -.PP +.P The timestamp fields report time measured with a zero point at the .IR Epoch , 1970-01-01 00:00:00 +0000, UTC (see .BR time (7)). -.PP +.P Nanosecond timestamps are supported on XFS, JFS, Btrfs, and ext4 (since Linux 2.6.23). .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80 @@ -221,7 +220,7 @@ field (for the .I statx.stx_mode field) contains the file type and mode. -.PP +.P POSIX refers to the .I stat.st_mode bits corresponding to the mask @@ -232,7 +231,7 @@ the 12 bits corresponding to the mask 07777 as the .I file mode bits and the least significant 9 bits (0777) as the .IR "file permission bits" . -.PP +.P The following mask values are defined for the file type: .in +4n .TS @@ -248,9 +247,9 @@ S_IFCHR 0020000 character device S_IFIFO 0010000 FIFO .TE .in -.PP +.P Thus, to test for a regular file (for example), one could write: -.PP +.P .in +4n .EX stat(pathname, &sb); @@ -259,7 +258,7 @@ if ((sb.st_mode & S_IFMT) == S_IFREG) { } .EE .in -.PP +.P Because tests of the above form are common, additional macros are defined by POSIX to allow the test of the file type in .I st_mode @@ -287,9 +286,9 @@ symbolic link? (Not in POSIX.1-1996.) .BR S_ISSOCK (m) socket? (Not in POSIX.1-1996.) .RE -.PP +.P The preceding code snippet could thus be rewritten as: -.PP +.P .in +4n .EX stat(pathname, &sb); @@ -298,7 +297,7 @@ if (S_ISREG(sb.st_mode)) { } .EE .in -.PP +.P The definitions of most of the above file type test macros are provided if any of the following feature test macros is defined: .B _BSD_SOURCE @@ -315,7 +314,7 @@ and are provided if .B _XOPEN_SOURCE is defined. -.PP +.P The definition of .B S_IFSOCK can also be exposed either by defining @@ -324,7 +323,7 @@ with a value of 500 or greater or (since glibc 2.24) by defining both .B _XOPEN_SOURCE and .BR _XOPEN_SOURCE_EXTENDED . -.PP +.P The definition of .BR S_ISSOCK () is exposed if any of the following feature test macros is defined: @@ -339,7 +338,7 @@ with a value of 200112L or greater, or (since glibc 2.24) by defining both .B _XOPEN_SOURCE and .BR _XOPEN_SOURCE_EXTENDED . -.PP +.P The following mask values are defined for the file mode component of the .I st_mode @@ -397,7 +396,7 @@ others have execute permission T} .TE .in -.PP +.P The set-group-ID bit .RB ( S_ISGID ) has several special uses. @@ -414,7 +413,7 @@ For a file that does not have the group execution bit .RB ( S_IXGRP ) set, the set-group-ID bit indicates mandatory file/record locking. -.PP +.P The sticky bit .RB ( S_ISVTX ) on a directory means that a file @@ -425,7 +424,7 @@ process. POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P POSIX.1-1990 did not describe the .BR S_IFMT , .BR S_IFSOCK , @@ -441,7 +440,7 @@ constants, but instead specified the use of the macros .BR S_ISDIR () and so on. -.PP +.P The .BR S_ISLNK () and @@ -449,7 +448,7 @@ and macros were not in POSIX.1-1996; the former is from SVID 4, the latter from SUSv2. -.PP +.P UNIX\ V7 (and later systems) had .BR S_IREAD , .BR S_IWRITE , diff --git a/man7/inotify.7 b/man7/inotify.7 index 73a6ab0..51faaaa 100644 --- a/man7/inotify.7 +++ b/man7/inotify.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH inotify 7 2023-07-08 "Linux man-pages 6.05.01" +.TH inotify 7 2023-10-31 "Linux man-pages 6.7" .SH NAME inotify \- monitoring filesystem events .SH DESCRIPTION @@ -14,7 +14,7 @@ Inotify can be used to monitor individual files, or to monitor directories. When a directory is monitored, inotify will return events for the directory itself, and for files inside the directory. -.PP +.P The following system calls are used with this API: .IP \[bu] 3 .BR inotify_init (2) @@ -56,7 +56,7 @@ instance have been closed (using the underlying object and its resources are freed for reuse by the kernel; all associated watches are automatically freed. -.PP +.P With careful programming, an application can use inotify to efficiently monitor and cache the state of a set of filesystem objects. @@ -78,11 +78,11 @@ in which case the call fails with the error .BR EINTR ; see .BR signal (7)). -.PP +.P Each successful .BR read (2) returns a buffer containing one or more of the following structures: -.PP +.P .in +4n .EX struct inotify_event { @@ -99,15 +99,15 @@ struct inotify_event { }; .EE .in -.PP +.P .I wd identifies the watch for which this event occurs. It is one of the watch descriptors returned by a previous call to .BR inotify_add_watch (2). -.PP +.P .I mask contains bits that describe the event that occurred (see below). -.PP +.P .I cookie is a unique integer that connects related events. Currently, this is used only for rename events, and @@ -119,7 +119,7 @@ events to be connected by the application. For all other event types, .I cookie is set to 0. -.PP +.P The .I name field is present only when an event is returned @@ -128,7 +128,7 @@ it identifies the filename within the watched directory. This filename is null-terminated, and may include further null bytes (\[aq]\e0\[aq]) to align subsequent reads to a suitable address boundary. -.PP +.P The .I len field counts all of the bytes in @@ -138,7 +138,7 @@ the length of each .I inotify_event structure is thus .IR "sizeof(struct inotify_event)+len" . -.PP +.P The behavior when the buffer given to .BR read (2) is too small to return information about the next event depends @@ -149,13 +149,13 @@ returns 0; since Linux 2.6.21, fails with the error .BR EINVAL . Specifying a buffer of size -.PP +.P .in +4n .EX sizeof(struct inotify_event) + NAME_MAX + 1 .EE .in -.PP +.P will be sufficient to read at least one event. .SS inotify events The @@ -252,12 +252,12 @@ when a file is renamed. .BR IN_OPEN " (*)" File or directory was opened. .RE -.PP +.P Inotify monitoring is inode-based: when monitoring a file (but not when monitoring the directory containing a file), an event can be generated for activity on any link to the file (in the same or a different directory). -.PP +.P When monitoring a directory: .IP \[bu] 3 the events marked above with an asterisk (*) can occur both @@ -265,19 +265,19 @@ for the directory itself and for objects inside the directory; and .IP \[bu] the events marked with a plus sign (+) occur only for objects inside the directory (not for the directory itself). -.PP +.P .IR Note : when monitoring a directory, events are not generated for the files inside the directory when the events are performed via a pathname (i.e., a link) that lies outside the monitored directory. -.PP +.P When events are generated for objects inside a watched directory, the .I name field in the returned .I inotify_event structure identifies the name of the file within the directory. -.PP +.P The .B IN_ALL_EVENTS macro is defined as a bit mask of all of the above events. @@ -285,7 +285,7 @@ This macro can be used as the .I mask argument when calling .BR inotify_add_watch (2). -.PP +.P Two additional convenience macros are defined: .RS 4 .TP @@ -297,7 +297,7 @@ Equates to Equates to .BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" . .RE -.PP +.P The following further bits can be specified in .I mask when calling @@ -372,7 +372,7 @@ and multiple calls to .BR inotify_add_watch (2) without this flag may clobber existing watch masks. .RE -.PP +.P The following bits may be set in the .I mask field returned by @@ -449,7 +449,7 @@ events for both and .IR dir/myfile . .RE -.PP +.P Suppose an application is watching the directories .I dir1 and @@ -490,7 +490,7 @@ events will have the same .I cookie value. .RE -.PP +.P Suppose that .I dir1/xx and @@ -529,7 +529,7 @@ and an event for .IR dir1 . .RE -.PP +.P Suppose an application is watching the directory .I dir and (the empty) directory @@ -592,7 +592,7 @@ Inotify file descriptors can be monitored using and .BR epoll (7). When an event is available, the file descriptor indicates as readable. -.PP +.P Since Linux 2.6.25, signal-driven I/O notification is available for inotify file descriptors; see the discussion of @@ -621,7 +621,7 @@ and .B POLLIN is set in .IR si_band . -.PP +.P If successive output inotify events produced on the inotify file descriptor are identical (same .IR wd , @@ -634,13 +634,13 @@ older event has not yet been read (but see BUGS). This reduces the amount of kernel memory required for the event queue, but also means that an application can't use inotify to reliably count file events. -.PP +.P The events returned by reading from an inotify file descriptor form an ordered queue. Thus, for example, it is guaranteed that when renaming from one directory to another, events will be produced in the correct order on the inotify file descriptor. -.PP +.P The set of watch descriptors that is being monitored via an inotify file descriptor can be viewed via the entry for the inotify file descriptor in the process's @@ -661,7 +661,7 @@ In particular, there is no easy way for a process that is monitoring events via inotify to distinguish events that it triggers itself from those that are triggered by other processes. -.PP +.P Inotify reports only events that a user-space program triggers through the filesystem API. As a result, it does not catch remote events that occur @@ -674,28 +674,28 @@ Furthermore, various pseudo-filesystems such as and .I /dev/pts are not monitorable with inotify. -.PP +.P The inotify API does not report file accesses and modifications that may occur because of .BR mmap (2), .BR msync (2), and .BR munmap (2). -.PP +.P The inotify API identifies affected files by filename. However, by the time an application processes an inotify event, the filename may already have been deleted or renamed. -.PP +.P The inotify API identifies events via watch descriptors. It is the application's responsibility to cache a mapping (if one is needed) between watch descriptors and pathnames. Be aware that directory renamings may affect multiple cached pathnames. -.PP +.P Inotify monitoring of directories is not recursive: to monitor subdirectories under a directory, additional watches must be created. This can take a significant amount time for large directory trees. -.PP +.P If monitoring an entire directory subtree, and a new subdirectory is created in that tree or an existing directory is renamed into that tree, @@ -704,7 +704,7 @@ new files (and subdirectories) may already exist inside the subdirectory. Therefore, you may want to scan the contents of the subdirectory immediately after adding the watch (and, if desired, recursively add watches for any subdirectories that it contains). -.PP +.P Note that the event queue can overflow. In this case, events are lost. Robust applications should handle the possibility of @@ -716,7 +716,7 @@ approach is to close the inotify file descriptor, empty the cache, create a new inotify file descriptor, and then re-create watches and cache entries for the objects to be monitored.) -.PP +.P If a filesystem is mounted on top of a monitored directory, no event is generated, and no events are generated for objects immediately under the new mount point. @@ -733,7 +733,7 @@ event pair that is generated by .BR rename (2) can be matched up via their shared cookie value. However, the task of matching has some challenges. -.PP +.P These two events are usually consecutive in the event stream available when reading from the inotify file descriptor. However, this is not guaranteed. @@ -750,7 +750,7 @@ inserted into the queue: there may be a brief interval where the has appeared, but the .B IN_MOVED_TO has not. -.PP +.P Matching up the .B IN_MOVED_FROM and @@ -775,7 +775,7 @@ then those watch descriptors will be inconsistent with the watch descriptors in any pending events. (Re-creating the inotify file descriptor and rebuilding the cache may be useful to deal with this scenario.) -.PP +.P Applications should also allow for the possibility that the .B IN_MOVED_FROM event was the last event that could fit in the buffer @@ -803,7 +803,7 @@ calls to generate .B IN_MODIFY events. -.PP +.P .\" FIXME . kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321 .\" implies that unmount events were buggy since Linux 2.6.11 to Linux 2.6.36 .\" @@ -811,7 +811,7 @@ Before Linux 2.6.16, the .B IN_ONESHOT .I mask flag does not work. -.PP +.P As originally designed and implemented, the .B IN_ONESHOT flag did not cause an @@ -821,7 +821,7 @@ However, as an unintended effect of other changes, since Linux 2.6.36, an .B IN_IGNORED event is generated in this case. -.PP +.P Before Linux 2.6.25, .\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2 the kernel code that was intended to coalesce successive identical events @@ -830,7 +830,7 @@ if the older had not yet been read) instead checked if the most recent event could be coalesced with the .I oldest unread event. -.PP +.P When a watch descriptor is removed by calling .BR inotify_rm_watch (2) (or because a watch file is deleted or the filesystem @@ -868,7 +868,7 @@ and waits for events of type .BR IN_CLOSE_NOWRITE , and .BR IN_CLOSE_WRITE . -.PP +.P The following output was recorded while editing the file .I /home/user/temp/foo and listing directory @@ -1095,6 +1095,6 @@ main(int argc, char* argv[]) .BR read (2), .BR stat (2), .BR fanotify (7) -.PP +.P .I Documentation/filesystems/inotify.txt in the Linux kernel source tree diff --git a/man7/intro.7 b/man7/intro.7 index e12ff9d..98c8ed9 100644 --- a/man7/intro.7 +++ b/man7/intro.7 @@ -6,7 +6,7 @@ .\" .\" Modified by Thomas Koenig (ig25@rz.uni-karlsruhe.de) 24 Apr 1993 .\" Modified Sat Jul 24 17:28:08 1993 by Rik Faith (faith@cs.unc.edu) -.TH intro 7 2022-10-30 "Linux man-pages 6.05.01" +.TH intro 7 2022-10-30 "Linux man-pages 6.7" .SH NAME intro \- introduction to overview and miscellany section .SH DESCRIPTION @@ -35,7 +35,7 @@ .\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71 .\" Author: Erich E. Hoover <ehoover@mines.edu> .\" -.TH ip 7 2023-07-15 "Linux man-pages 6.05.01" +.TH ip 7 2024-03-17 "Linux man-pages 6.7" .SH NAME ip \- Linux IPv4 protocol implementation .SH SYNOPSIS @@ -45,7 +45,7 @@ ip \- Linux IPv4 protocol implementation .\" .B #include <linux/errqueue.h> -- never include <linux/foo.h> .B #include <netinet/in.h> .B #include <netinet/ip.h> \fR/* superset of previous */ -.PP +.P .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" .IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");" @@ -56,20 +56,20 @@ described in RFC\ 791 and RFC\ 1122. .B ip contains a level 2 multicasting implementation conforming to RFC\ 1112. It also contains an IP router including a packet filter. -.PP +.P The programming interface is BSD-sockets compatible. For more information on sockets, see .BR socket (7). -.PP +.P An IP socket is created using .BR socket (2): -.PP +.P .in +4n .EX socket(AF_INET, socket_type, protocol); .EE .in -.PP +.P Valid socket types include .B SOCK_STREAM to open a stream socket, @@ -79,7 +79,7 @@ to open a datagram socket, and to open a .BR raw (7) socket to access the IP protocol directly. -.PP +.P .I protocol is the IP protocol in the IP header to be received or sent. Valid values for @@ -107,12 +107,12 @@ stream sockets; and for .BR udplite (7) datagram sockets. -.PP +.P For .B SOCK_RAW you may specify a valid IANA IP protocol defined in RFC\ 1700 assigned numbers. -.PP +.P When a process wants to receive new incoming packets or connections, it should bind a socket to a local interface address using .BR bind (2). @@ -134,7 +134,7 @@ is called on an unbound socket, the socket is automatically bound to a random free port or to a usable shared port with the local address set to .BR INADDR_ANY . -.PP +.P A TCP local socket address that has been bound is unavailable for some time after closing, unless the .B SO_REUSEADDR @@ -151,7 +151,7 @@ and On raw sockets .I sin_port is set to the IP protocol. -.PP +.P .in +4n .EX struct sockaddr_in { @@ -166,7 +166,7 @@ struct in_addr { }; .EE .in -.PP +.P .I sin_family is always set to .BR AF_INET . @@ -190,7 +190,7 @@ port, they are implemented only by higher protocols like .BR tcp (7) and .BR udp (7). -.PP +.P .I sin_addr is the IP host address. The @@ -212,7 +212,7 @@ or set using the .BR inet_makeaddr (3) library functions or directly with the name resolver (see .BR gethostbyname (3)). -.PP +.P IPv4 addresses are divided into unicast, broadcast, and multicast addresses. Unicast addresses specify a single interface of a host, @@ -224,7 +224,7 @@ socket flag is set. In the current implementation, connection-oriented sockets are allowed to use only unicast addresses. .\" Leave a loophole for XTP @) -.PP +.P Note that the address and the port are always stored in network byte order. In particular, this means that you need to call @@ -275,7 +275,7 @@ Since Linux 5.14, .\" commit 58fee5fc83658aaacf60246aeab738946a9ba516 it is treated as an ordinary unicast address and can be assigned to an interface. -.PP +.P Internet standards have traditionally also reserved various addresses for particular uses, though Linux no longer treats some of these specially. @@ -314,7 +314,7 @@ The socket option level for IP is .BR IPPROTO_IP . .\" or SOL_IP on Linux A boolean integer flag is zero when it is false, otherwise true. -.PP +.P When an invalid socket option is specified, .BR getsockopt (2) and @@ -607,7 +607,7 @@ IP_PMTUDISC_DONT:Never do Path MTU Discovery. IP_PMTUDISC_DO:Always do Path MTU Discovery. IP_PMTUDISC_PROBE:Set DF but ignore Path MTU. .TE -.sp 1 +.IP When PMTU discovery is enabled, the kernel automatically keeps track of the path MTU per destination host. When it is connected to a specific peer with @@ -828,6 +828,10 @@ is not zero, the primary local address of the interface specified by the index overwrites .I ipi_spec_dst for the routing table lookup. +.IP +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_RECVERR " (since Linux 2.2)" .\" Precisely: since Linux 2.1.15 @@ -989,6 +993,9 @@ in which the kernel returns the original destination address of the datagram being received. The ancillary message contains a .IR "struct sockaddr_in" . +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_RECVTOS " (since Linux 2.2)" .\" Precisely: since Linux 2.1.68 @@ -998,6 +1005,9 @@ ancillary message is passed with incoming packets. It contains a byte which specifies the Type of Service/Precedence field of the packet header. Expects a boolean integer flag. +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_RECVTTL " (since Linux 2.2)" .\" Precisely: since Linux 2.1.68 @@ -1015,6 +1025,9 @@ Identical to .BR IP_RECVOPTS , but returns raw unprocessed options with timestamp and route record options not filled in for this hop. +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_ROUTER_ALERT " (since Linux 2.2)" .\" Precisely: since Linux 2.1.68 @@ -1287,7 +1300,9 @@ Time in seconds to keep an IPv6 fragment in memory. Regeneration interval (in seconds) of the hash secret (or lifetime for the hash secret) for IPv6 fragments. .TP -.IR ipfrag_high_thresh " (integer), " ipfrag_low_thresh " (integer)" +.IR ipfrag_high_thresh " (integer)" +.TQ +.IR ipfrag_low_thresh " (integer)" If the amount of queued IP fragments reaches .IR ipfrag_high_thresh , the queue is pruned down to @@ -1305,7 +1320,7 @@ All ioctls described in .BR socket (7) apply to .BR ip . -.PP +.P Ioctls to configure generic device parameters are described in .BR netdevice (7). .\" FIXME Add a discussion of multicasting @@ -1365,7 +1380,9 @@ was called on an already connected socket. .B EMSGSIZE Datagram is bigger than an MTU on the path and it cannot be fragmented. .TP -.BR ENOBUFS ", " ENOMEM +.B ENOBUFS +.TQ +.B ENOMEM Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory, but this is not 100% consistent. @@ -1393,7 +1410,7 @@ The connection was unexpectedly closed or shut down by the other end. .TP .B ESOCKTNOSUPPORT The socket is not configured or an unknown socket type was requested. -.PP +.P Other errors may be generated by the overlaying protocols; see .BR tcp (7), .BR raw (7), @@ -1415,7 +1432,7 @@ and are Linux-specific. .\" IP_XFRM_POLICY is Linux-specific .\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs -.PP +.P Be very careful with the .B SO_BROADCAST option \- it is not privileged in Linux. @@ -1428,7 +1445,7 @@ See RFC 6762 for an example of a protocol (mDNS) using the more modern multicast approach to communicating with an open-ended group of hosts on the local network. -.PP +.P Some other BSD sockets implementations provide .B IP_RCVDSTADDR and @@ -1438,7 +1455,7 @@ received datagrams. Linux has the more general .B IP_PKTINFO for the same task. -.PP +.P Some BSD sockets implementations also provide an .B IP_RECVTTL option, but an ancillary message with type @@ -1447,13 +1464,13 @@ is passed with the incoming packet. This is different from the .B IP_TTL option used in Linux. -.PP +.P Using the .B SOL_IP socket options level isn't portable; BSD-based stacks use the .B IPPROTO_IP level. -.PP +.P .B INADDR_ANY (0.0.0.0) and .B INADDR_BROADCAST @@ -1476,7 +1493,7 @@ address structure for generic link layer information instead of the old .BR sockaddr_pkt . .SH BUGS There are too many inconsistent error values. -.PP +.P The error used to diagnose exhaustion of the ephemeral port range differs across the various system calls .RB ( connect (2), @@ -1484,14 +1501,14 @@ across the various system calls .BR listen (2), .BR sendto (2)) that can assign ephemeral ports. -.PP +.P The ioctls to configure IP-specific interface options and ARP tables are not described. -.\" .PP +.\" .P .\" Some versions of glibc forget to declare .\" .IR in_pktinfo . .\" Workaround currently is to copy it into your program from this man page. -.PP +.P Receiving the original destination address with .B MSG_ERRQUEUE in @@ -1515,10 +1532,10 @@ does not work in some Linux 2.2 kernels. .BR tcp (7), .BR udp (7), .BR ip (8) -.PP +.P The kernel source file .IR Documentation/networking/ip\-sysctl.txt . -.PP +.P RFC\ 791 for the original IP specification. RFC\ 1122 for the IPv4 host requirements. RFC\ 1812 for the IPv4 router requirements. diff --git a/man7/ipc_namespaces.7 b/man7/ipc_namespaces.7 index 0b13f07..fe17ae1 100644 --- a/man7/ipc_namespaces.7 +++ b/man7/ipc_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ipc_namespaces 7 2023-02-05 "Linux man-pages 6.05.01" +.TH ipc_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME ipc_namespaces \- overview of Linux IPC namespaces .SH DESCRIPTION @@ -18,13 +18,13 @@ POSIX message queues (see The common characteristic of these IPC mechanisms is that IPC objects are identified by mechanisms other than filesystem pathnames. -.PP +.P Each IPC namespace has its own set of System V IPC identifiers and its own POSIX message queue filesystem. Objects created in an IPC namespace are visible to all other processes that are members of that namespace, but are not visible to processes in other IPC namespaces. -.PP +.P The following .I /proc interfaces are distinct in each IPC namespace: @@ -47,11 +47,11 @@ and .IP \[bu] The System V IPC interfaces in .IR /proc/sysvipc . -.PP +.P When an IPC namespace is destroyed (i.e., when the last process that is a member of the namespace terminates), all IPC objects in the namespace are automatically destroyed. -.PP +.P Use of IPC namespaces requires a kernel that is configured with the .B CONFIG_IPC_NS option. diff --git a/man7/ipv6.7 b/man7/ipv6.7 index e6f9d54..18acdc9 100644 --- a/man7/ipv6.7 +++ b/man7/ipv6.7 @@ -78,14 +78,14 @@ .\" commit c4062dfc425e94290ac427a98d6b4721dd2bc91f .\" Author: Erich E. Hoover <ehoover@mines.edu> .\" -.TH ipv6 7 2023-07-30 "Linux man-pages 6.05.01" +.TH ipv6 7 2023-10-31 "Linux man-pages 6.7" .SH NAME ipv6 \- Linux IPv6 protocol implementation .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <netinet/in.h> -.PP +.P .IB tcp6_socket " = socket(AF_INET6, SOCK_STREAM, 0);" .IB raw6_socket " = socket(AF_INET6, SOCK_RAW, " protocol ");" .IB udp6_socket " = socket(AF_INET6, SOCK_DGRAM, " protocol ");" @@ -97,12 +97,12 @@ implemented by the Linux kernel and glibc 2.1. The interface is based on the BSD sockets interface; see .BR socket (7). -.PP +.P The IPv6 API aims to be mostly compatible with the IPv4 API (see .BR ip (7)). Only differences are described in this man page. -.PP +.P To bind an .B AF_INET6 socket to any process, the local address should be copied from the @@ -114,21 +114,21 @@ In static initializations, .B IN6ADDR_ANY_INIT may also be used, which expands to a constant expression. Both of them are in network byte order. -.PP +.P The IPv6 loopback address (::1) is available in the global .I in6addr_loopback variable. For initializations, .B IN6ADDR_LOOPBACK_INIT should be used. -.PP +.P IPv4 connections can be handled with the v6 API by using the v4-mapped-on-v6 address type; thus a program needs to support only this API type to support both protocols. This is handled transparently by the address handling functions in the C library. -.PP +.P IPv4 and IPv6 share the local port space. When you get an IPv4 connection or packet to an IPv6 socket, @@ -149,7 +149,7 @@ struct in6_addr { }; .EE .in -.PP +.P .I sin6_family is always set to .BR AF_INET6 ; @@ -169,19 +169,19 @@ Linux supports it only for link-local addresses, in that case .I sin6_scope_id contains the interface index (see .BR netdevice (7)) -.PP +.P IPv6 supports several address types: unicast to address a single host, multicast to address a group of hosts, anycast to address the nearest member of a group of hosts (not implemented in Linux), IPv4-on-IPv6 to address an IPv4 host, and other reserved address types. -.PP +.P The address notation for IPv6 is a group of 8 4-digit hexadecimal numbers, separated with a \[aq]:\[aq]. \&"::" stands for a string of 0 bits. Special addresses are ::1 for loopback and ::FFFF:<IPv4 address> for IPv4-mapped-on-IPv6. -.PP +.P The port space of IPv6 is shared with IPv4. .SS Socket options IPv6 supports some protocol-specific socket options that can be set with @@ -368,7 +368,7 @@ or into other structures may not be. This is not a problem for 32-bit hosts like i386. -.PP +.P The .I sin6_flowinfo field is new in Linux 2.4. @@ -386,7 +386,7 @@ Programs that assume that all address types can be stored safely in a need to be changed to use .I struct sockaddr_storage for that instead. -.PP +.P .BR SOL_IP , .BR SOL_IPV6 , .BR SOL_ICMPV6 , @@ -401,16 +401,16 @@ The IPv6 extended API as in RFC\ 2292 is currently only partly implemented; although the 2.2 kernel has near complete support for receiving options, the macros for generating IPv6 options are missing in glibc 2.1. -.PP +.P IPSec support for EH and AH headers is missing. -.PP +.P Flow label management is not complete and not documented here. -.PP +.P This man page is not complete. .SH SEE ALSO .BR cmsg (3), .BR ip (7) -.PP +.P RFC\ 2553: IPv6 BASIC API; Linux tries to be compliant to this. RFC\ 2460: IPv6 specification. diff --git a/man7/iso_8859-1.7 b/man7/iso_8859-1.7 index 7534a85..18e1bdc 100644 --- a/man7/iso_8859-1.7 +++ b/man7/iso_8859-1.7 @@ -5,37 +5,37 @@ .\" .\" Slightly rearranged, aeb, 950713 .\" Updated, dpo, 990531 -.TH ISO_8859-1 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-1 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-1 \- ISO 8859-1 character set encoded in octal, decimal, +iso_8859-1 \- ISO/IEC\~8859-1 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-1 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-1 encodes the characters used in many West European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-1 characters -The following table displays the characters in ISO 8859-1 that +.SS ISO/IEC\~8859-1 characters +The following table displays the characters in ISO/IEC\~8859-1 that are printable and unlisted in the .BR ascii (7) manual page. @@ -141,7 +141,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-1 is also known as Latin-1. +ISO/IEC\~8859-1 is also known as Latin-1. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-10.7 b/man7/iso_8859-10.7 index d43a00a..79ee5f3 100644 --- a/man7/iso_8859-10.7 +++ b/man7/iso_8859-10.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-10 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-10 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-10 \- ISO 8859-10 character set encoded in octal, decimal, +iso_8859-10 \- ISO/IEC\~8859-10 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-10 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-10 encodes the characters used in Nordic languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-10 characters -The following table displays the characters in ISO 8859-10 that +.SS ISO/IEC\~8859-10 characters +The following table displays the characters in ISO/IEC\~8859-10 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ĸ LATIN SMALL LETTER KRA .TE .SH NOTES -ISO 8859-10 is also known as Latin-6. +ISO/IEC\~8859-10 is also known as Latin-6. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-11.7 b/man7/iso_8859-11.7 index e488606..f7dc9b4 100644 --- a/man7/iso_8859-11.7 +++ b/man7/iso_8859-11.7 @@ -5,37 +5,37 @@ .\" .\"Thanomsub Noppaburana <donga.nb@gmail.com> made valuable suggestions. .\" -.TH ISO_8859-11 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-11 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-11 \- ISO 8859-11 character set encoded in octal, decimal, +iso_8859-11 \- ISO/IEC\~8859-11 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-11 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-11 encodes the characters used in the Thai language. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-11 characters -The following table displays the characters in ISO 8859-11 that +.SS ISO/IEC\~8859-11 characters +The following table displays the characters in ISO/IEC\~8859-11 that are printable and unlisted in the .BR ascii (7) manual page. @@ -133,9 +133,9 @@ _ 373 251 FB ๛ THAI CHARACTER KHOMUT .TE .SH NOTES -ISO 8859-11 is the same as TIS (Thai Industrial Standard) 620-2253, +ISO/IEC\~8859-11 is the same as TIS (Thai Industrial Standard) 620-2253, commonly known as TIS-620, except for the character in position A0: -ISO 8859-11 defines this as NO-BREAK SPACE, +ISO/IEC\~8859-11 defines this as NO-BREAK SPACE, while TIS-620 leaves it undefined. .SH SEE ALSO .BR ascii (7), diff --git a/man7/iso_8859-13.7 b/man7/iso_8859-13.7 index 1158347..62561bf 100644 --- a/man7/iso_8859-13.7 +++ b/man7/iso_8859-13.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-13 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-13 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-13 \- ISO 8859-13 character set encoded in octal, decimal, +iso_8859-13 \- ISO/IEC\~8859-13 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-13 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-13 encodes the characters used in Baltic Rim languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-13 characters -The following table displays the characters in ISO 8859-13 that +.SS ISO/IEC\~8859-13 characters +The following table displays the characters in ISO/IEC\~8859-13 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ’ RIGHT SINGLE QUOTATION MARK .TE .SH NOTES -ISO 8859-13 is also known as Latin-7. +ISO/IEC\~8859-13 is also known as Latin-7. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-14.7 b/man7/iso_8859-14.7 index eedac82..6c1f6ee 100644 --- a/man7/iso_8859-14.7 +++ b/man7/iso_8859-14.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-14 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-14 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-14 \- ISO 8859-14 character set encoded in octal, decimal, +iso_8859-14 \- ISO/IEC\~8859-14 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-14 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-14 encodes the characters used in Celtic languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-14 characters -The following table displays the characters in ISO 8859-14 that +.SS ISO/IEC\~8859-14 characters +The following table displays the characters in ISO/IEC\~8859-14 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-14 is also known as Latin-8. +ISO/IEC\~8859-14 is also known as Latin-8. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-15.7 b/man7/iso_8859-15.7 index 908bb9b..fb6d681 100644 --- a/man7/iso_8859-15.7 +++ b/man7/iso_8859-15.7 @@ -4,37 +4,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-15 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-15 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-15 \- ISO 8859-15 character set encoded in octal, decimal, +iso_8859-15 \- ISO/IEC\~8859-15 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-15 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-15 encodes the characters used in many West European languages and adds the Euro sign. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-15 characters -The following table displays the characters in ISO 8859-15 that +.SS ISO/IEC\~8859-15 characters +The following table displays the characters in ISO/IEC\~8859-15 that are printable and unlisted in the .BR ascii (7) manual page. @@ -140,7 +140,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-15 is also known as Latin-9 (or sometimes as Latin-0). +ISO/IEC\~8859-15 is also known as Latin-9 (or sometimes as Latin-0). .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-16.7 b/man7/iso_8859-16.7 index 697a3f9..9e3fdd3 100644 --- a/man7/iso_8859-16.7 +++ b/man7/iso_8859-16.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-16 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-16 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-16 \- ISO 8859-16 character set encoded in octal, decimal, +iso_8859-16 \- ISO/IEC\~8859-16 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-16 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-16 encodes the Latin characters used in Southeast European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-16 characters -The following table displays the characters in ISO 8859-16 that +.SS ISO/IEC\~8859-16 characters +The following table displays the characters in ISO/IEC\~8859-16 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-16 is also known as Latin-10. +ISO/IEC\~8859-16 is also known as Latin-10. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-2.7 b/man7/iso_8859-2.7 index 403e85e..225fbaa 100644 --- a/man7/iso_8859-2.7 +++ b/man7/iso_8859-2.7 @@ -6,37 +6,37 @@ .\" .\" Slightly rearranged, aeb, 950713 .\" Updated, dpo, 990531 -.TH ISO_8859-2 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-2 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-2 \- ISO 8859-2 character set encoded in octal, decimal, +iso_8859-2 \- ISO/IEC\~8859-2 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-2 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-2 encodes the Latin characters used in many Central and East European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-2 characters -The following table displays the characters in ISO 8859-2 that +.SS ISO/IEC\~8859-2 characters +The following table displays the characters in ISO/IEC\~8859-2 that are printable and unlisted in the .BR ascii (7) manual page. @@ -142,7 +142,7 @@ _ 377 255 FF ˙ DOT ABOVE .TE .SH NOTES -ISO 8859-2 is also known as Latin-2. +ISO/IEC\~8859-2 is also known as Latin-2. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-3.7 b/man7/iso_8859-3.7 index 8eb9a24..29c9e59 100644 --- a/man7/iso_8859-3.7 +++ b/man7/iso_8859-3.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-3 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-3 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-3 \- ISO 8859-3 character set encoded in octal, decimal, +iso_8859-3 \- ISO/IEC\~8859-3 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-3 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-3 encodes the characters used in certain Southeast European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-3 characters -The following table displays the characters in ISO 8859-3 that +.SS ISO/IEC\~8859-3 characters +The following table displays the characters in ISO/IEC\~8859-3 that are printable and unlisted in the .BR ascii (7) manual page. @@ -132,7 +132,7 @@ _ 377 255 FF ˙ DOT ABOVE .TE .SH NOTES -ISO 8859-3 is also known as Latin-3. +ISO/IEC\~8859-3 is also known as Latin-3. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-4.7 b/man7/iso_8859-4.7 index b209bf1..d772f62 100644 --- a/man7/iso_8859-4.7 +++ b/man7/iso_8859-4.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-4 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-4 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-4 \- ISO 8859-4 character set encoded in octal, decimal, +iso_8859-4 \- ISO/IEC\~8859-4 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-4 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-4 encodes the characters used in Scandinavian and Baltic languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-4 characters -The following table displays the characters in ISO 8859-4 that +.SS ISO/IEC\~8859-4 characters +The following table displays the characters in ISO/IEC\~8859-4 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ˙ DOT ABOVE .TE .SH NOTES -ISO 8859-4 is also known as Latin-4. +ISO/IEC\~8859-4 is also known as Latin-4. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-5.7 b/man7/iso_8859-5.7 index 1fbb266..6100a1d 100644 --- a/man7/iso_8859-5.7 +++ b/man7/iso_8859-5.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-5 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-5 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-5 \- ISO 8859-5 character set encoded in octal, decimal, +iso_8859-5 \- ISO/IEC\~8859-5 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-5 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-5 encodes the Cyrillic characters used in many East European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-5 characters -The following table displays the characters in ISO 8859-5 that +.SS ISO/IEC\~8859-5 characters +The following table displays the characters in ISO/IEC\~8859-5 that are printable and unlisted in the .BR ascii (7) manual page. diff --git a/man7/iso_8859-6.7 b/man7/iso_8859-6.7 index b73e846..f1b4b5c 100644 --- a/man7/iso_8859-6.7 +++ b/man7/iso_8859-6.7 @@ -3,37 +3,39 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-6 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-6 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-6 \- ISO 8859-6 character set encoded in octal, decimal, +iso_8859-6 +\- +ISO/IEC\~8859-6 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-6 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-6 encodes the characters used in the Arabic language. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-6 characters -The following table displays the characters in ISO 8859-6 that +.SS ISO/IEC\~8859-6 characters +The following table displays the characters in ISO/IEC\~8859-6 that are printable and unlisted in the .BR ascii (7) manual page. @@ -94,7 +96,7 @@ _ 362 242 F2 ْ ARABIC SUKUN .TE .SH NOTES -ISO 8859-6 lacks the glyphs required for many related languages, +ISO/IEC\~8859-6 lacks the glyphs required for many related languages, such as Urdu and Persian (Farsi). .SH SEE ALSO .BR ascii (7), diff --git a/man7/iso_8859-7.7 b/man7/iso_8859-7.7 index a66a28e..242359c 100644 --- a/man7/iso_8859-7.7 +++ b/man7/iso_8859-7.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-7 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-7 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-7 \- ISO 8859-7 character set encoded in octal, decimal, +iso_8859-7 \- ISO/IEC\~8859-7 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-7 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-7 encodes the characters used in modern monotonic Greek. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-7 characters -The following table displays the characters in ISO 8859-7 that +.SS ISO/IEC\~8859-7 characters +The following table displays the characters in ISO/IEC\~8859-7 that are printable and unlisted in the .BR ascii (7) manual page. @@ -143,7 +143,7 @@ T} 376 254 FE ώ GREEK SMALL LETTER OMEGA WITH TONOS .TE .SH NOTES -ISO 8859-7 was formerly known as ELOT-928 or ECMA-118:1986. +ISO/IEC\~8859-7 was formerly known as ELOT-928 or ECMA-118:1986. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-8.7 b/man7/iso_8859-8.7 index d854116..9fcc066 100644 --- a/man7/iso_8859-8.7 +++ b/man7/iso_8859-8.7 @@ -5,37 +5,37 @@ .\" .\" Eli Zaretskii <eliz@gnu.org> made valuable suggestions .\" -.TH ISO_8859-8 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-8 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-8 \- ISO 8859-8 character set encoded in octal, decimal, +iso_8859-8 \- ISO/IEC\~8859-8 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-8 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-8 encodes the characters used in Modern Hebrew. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-8 characters -The following table displays the characters in ISO 8859-8 that +.SS ISO/IEC\~8859-8 characters +The following table displays the characters in ISO/IEC\~8859-8 that are printable and unlisted in the .BR ascii (7) manual page. @@ -105,8 +105,8 @@ _ 376 254 FE RIGHT-TO-LEFT MARK .TE .SH NOTES -ISO 8859-8 was also known as ISO-IR-138. -ISO 8859-8 includes neither short vowels nor diacritical marks, +ISO/IEC\~8859-8 was also known as ISO-IR-138. +ISO/IEC\~8859-8 includes neither short vowels nor diacritical marks, and Yiddish is not provided for. .SH SEE ALSO .BR ascii (7), diff --git a/man7/iso_8859-9.7 b/man7/iso_8859-9.7 index 6386144..4e630d7 100644 --- a/man7/iso_8859-9.7 +++ b/man7/iso_8859-9.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-9 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-9 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-9 \- ISO 8859-9 character set encoded in octal, decimal, +iso_8859-9 \- ISO/IEC\~8859-9 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-9 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-9 encodes the characters used in Turkish. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-9 characters -The following table displays the characters in ISO 8859-9 that +.SS ISO/IEC\~8859-9 characters +The following table displays the characters in ISO/IEC\~8859-9 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-9 is also known as Latin-5. +ISO/IEC\~8859-9 is also known as Latin-5. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/kernel_lockdown.7 b/man7/kernel_lockdown.7 index aac19aa..cb8aa7c 100644 --- a/man7/kernel_lockdown.7 +++ b/man7/kernel_lockdown.7 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH kernel_lockdown 7 2023-02-05 "Linux man-pages 6.05.01" +.TH kernel_lockdown 7 2023-10-31 "Linux man-pages 6.7" .SH NAME kernel_lockdown \- kernel image access prevention feature .SH DESCRIPTION @@ -13,18 +13,18 @@ access to a running kernel image, attempting to protect against unauthorized modification of the kernel image and to prevent access to security and cryptographic data located in kernel memory, whilst still permitting driver modules to be loaded. -.PP +.P If a prohibited or restricted feature is accessed or used, the kernel will emit a message that looks like: -.PP +.P .in +4n .EX Lockdown: X: Y is restricted, see man kernel_lockdown.7 .EE .in -.PP +.P where X indicates the process name and Y indicates what is restricted. -.PP +.P On an EFI-enabled x86 or arm64 machine, lockdown will be automatically enabled if the system boots in EFI Secure Boot mode. .\" @@ -33,7 +33,7 @@ When lockdown is in effect, a number of features are disabled or have their use restricted. This includes special device files and kernel services that allow direct access of the kernel image: -.PP +.P .RS /dev/mem .br @@ -47,7 +47,7 @@ BPF .br kprobes .RE -.PP +.P 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] 3 @@ -73,7 +73,7 @@ The use of ACPI error injection. The specification of the ACPI RDSP address. .IP \[bu] The use of ACPI custom methods. -.PP +.P Certain facilities are restricted: .IP \[bu] 3 Only validly signed modules may be loaded (waived if the module file being diff --git a/man7/keyrings.7 b/man7/keyrings.7 index 1ebd25f..879d1aa 100644 --- a/man7/keyrings.7 +++ b/man7/keyrings.7 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH keyrings 7 2023-02-05 "Linux man-pages 6.05.01" +.TH keyrings 7 2024-02-25 "Linux man-pages 6.7" .SH NAME keyrings \- in-kernel key management and retention facility .SH DESCRIPTION @@ -12,14 +12,14 @@ The Linux key-management facility is primarily a way for various kernel components to retain or cache security data, authentication keys, encryption keys, and other data in the kernel. -.PP +.P System call interfaces are provided so that user-space programs can manage those objects and also use the facility for their own purposes; see .BR add_key (2), .BR request_key (2), and .BR keyctl (2). -.PP +.P A library and some user-space utilities are provided to allow access to the facility. See @@ -98,7 +98,7 @@ the key is scheduled for garbage collection. .SS Key types The kernel provides several basic types of key: .TP -.I """keyring""" +.I \[dq]keyring\[dq] .\" Note that keyrings use different fields in struct key in order to store .\" their data - index_key instead of type/description and name_link/keys .\" instead of payload. @@ -111,7 +111,7 @@ being garbage collected because nothing refers to them. Keyrings with descriptions (names) that begin with a period (\[aq].\[aq]) are reserved to the implementation. .TP -.I """user""" +.I \[dq]user\[dq] This is a general-purpose key type. The key is kept entirely within kernel memory. The payload may be read and updated by user-space applications. @@ -123,12 +123,12 @@ The description may be any valid string, though it is preferred that it start with a colon-delimited prefix representing the service to which the key is of interest (for instance -.IR """afs:mykey""" ). +.IR \[dq]afs:mykey\[dq] ). .TP -.IR """logon""" " (since Linux 3.3)" +.IR \[dq]logon\[dq] " (since Linux 3.3)" .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b This key type is essentially the same as -.IR """user""" , +.IR \[dq]user\[dq] , but it does not provide reading (i.e., the .BR keyctl (2) .B KEYCTL_READ @@ -138,19 +138,19 @@ This is suitable for storing username-password pairs that should not be readable from user space. .IP The description of a -.I """logon""" +.I \[dq]logon\[dq] key .I must start with a non-empty colon-delimited prefix whose purpose is to identify the service to which the key belongs. (Note that this differs from keys of the -.I """user""" +.I \[dq]user\[dq] type, where the inclusion of a prefix is recommended but is not enforced.) .TP -.IR """big_key""" " (since Linux 3.13)" +.IR \[dq]big_key\[dq] " (since Linux 3.13)" .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 This key type is similar to the -.I """user""" +.I \[dq]user\[dq] key type, but it may hold a payload of up to 1\ MiB in size. This key type is useful for purposes such as holding Kerberos ticket caches. .IP @@ -165,11 +165,11 @@ Since Linux 4.8, .\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef the payload data is encrypted when stored in tmpfs, thereby preventing it from being written unencrypted into swap space. -.PP +.P There are more specialized key types available also, but they aren't discussed here because they aren't intended for normal user-space use. -.PP +.P Key type names that begin with a period (\[aq].\[aq]) are reserved to the implementation. .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -179,7 +179,7 @@ links to other keys (which may include other keyrings). Keys may be linked to by multiple keyrings. Keyrings may be considered as analogous to UNIX directories where each directory contains a set of hard links to files. -.PP +.P Various operations (system calls) may be applied only to keyrings: .TP Adding @@ -204,7 +204,7 @@ A keyring may be considered the root of a tree or subtree in which keyrings form the branches and non-keyrings the leaves. This tree may be searched for a key matching a particular type and description. -.PP +.P See .BR keyctl_clear (3), .BR keyctl_link (3), @@ -217,13 +217,13 @@ for more information. To prevent a key from being garbage collected, it must be anchored to keep its reference count elevated when it is not in active use by the kernel. -.PP +.P Keyrings are used to anchor other keys: each link is a reference on a key. Note that keyrings themselves are just keys and are also subject to the same anchoring requirement to prevent them being garbage collected. -.PP +.P The kernel makes available a number of anchor keyrings. Note that some of these keyrings will be created only when first accessed. .TP @@ -302,7 +302,7 @@ encryption keys for module signature verification. .IP These special keyrings are usually closed to direct alteration by user space. -.PP +.P An originally planned "group keyring", for storing keys associated with each GID known to the kernel, is not so far implemented, is unlikely to be implemented. @@ -335,16 +335,16 @@ If a process is upcalled from the kernel to instantiate a key (see .BR request_key (2)), then it also possesses the requester's keyrings as in rule (1) as if it were the requester. -.PP +.P Note that possession is not a fundamental property of a key, but must rather be calculated each time the key is needed. -.PP +.P Possession is designed to allow set-user-ID programs run from, say a user's shell to access the user's keys. Granting permissions to the key possessor while denying them to the key owner and group allows the prevention of access to keys on the basis of UID and GID matches. -.PP +.P When it creates the session keyring, .BR pam_keyinit (8) adds a link to the @@ -361,7 +361,7 @@ The ID of a group that is permitted to access the key A security label .IP \[bu] A permissions mask -.PP +.P The permissions mask contains four sets of rights. The first three sets are mutually exclusive. One and only one will be in force for a particular access check. @@ -379,17 +379,17 @@ filesystem GID or one of the caller's supplementary group IDs. .I other The set specifies the rights granted if neither the key's user ID nor group ID matched. -.PP +.P The fourth set of rights is: .TP .I possessor The set specifies the rights granted if a key is determined to be possessed by the caller. -.PP +.P The complete set of rights for a key is the union of whichever of the first three sets is applicable plus the fourth set if the key is possessed. -.PP +.P The set of rights that may be granted in each of the four masks is as follows: .TP @@ -421,14 +421,14 @@ doesn't require this permission. .I setattr The ownership details and security label of the key may be changed, the key's expiration time may be set, and the key may be revoked. -.PP +.P In addition to access rights, any active Linux Security Module (LSM) may prevent access to a key if its policy so dictates. A key may be given a security label or other attribute by the LSM; this label is retrievable via .BR keyctl_get_security (3). -.PP +.P See .BR keyctl_chown (3), .BR keyctl_describe (3), @@ -447,7 +447,7 @@ system call is the primary point of access for user-space applications to find a key. (Internally, the kernel has something similar available for use by internal components that make use of keys.) -.PP +.P The search algorithm works as follows: .IP (1) 5 The process keyrings are searched in the following order: the @@ -480,10 +480,10 @@ If no valid matching key is found, then the first noted error state is returned; otherwise, an .B ENOKEY error is returned. -.PP +.P It is also possible to search a specific keyring, in which case only steps (3) to (6) apply. -.PP +.P See .BR request_key (2) and @@ -498,18 +498,18 @@ will, if given a argument, create a new key and then upcall to user space to instantiate the key. This allows keys to be created on an as-needed basis. -.PP +.P Typically, this will involve the kernel creating a new process that executes the .BR request\-key (8) program, which will then execute the appropriate handler based on its configuration. -.PP +.P The handler is passed a special authorization key that allows it and only it to instantiate the new key. This is also used to permit searches performed by the handler program to also search the requester's keyrings. -.PP +.P See .BR request_key (2), .BR keyctl_assume_authority (3), @@ -685,16 +685,16 @@ field provides some further information about the key. The information that appears here depends on the key type, as follows: .RS .TP -.IR """user""" " and " """logon""" +.IR \[dq]user\[dq] " and " \[dq]logon\[dq] The size in bytes of the key payload (expressed in decimal). .TP -.I """keyring""" +.I \[dq]keyring\[dq] The number of keys linked to the keyring, or the string .I empty if there are no keys linked to the keyring. .TP -.I """big_key""" +.I \[dq]big_key\[dq] The payload size in bytes, followed either by the string .IR [file] , if the key payload exceeds the threshold that means that the @@ -707,7 +707,7 @@ indicating that the key is small enough to reside in kernel memory. .RE .IP For the -.I """.request_key_auth""" +.I \[dq].request_key_auth\[dq] key type (authorization key; see .BR request_key (2)), @@ -796,7 +796,7 @@ or the operation.) .IP The default value in this file is 259200 (i.e., 3 days). -.PP +.P The following files (which are writable by privileged processes) are used to enforce quotas on the number of keys and number of bytes of data that can be stored in key payloads: @@ -833,14 +833,14 @@ may own. .IP .\"738c5d190f6540539a04baf36ce21d46b5da04bd The default value in this file is 1,000,000 (200 before Linux 3.17). -.PP +.P With respect to keyrings, note that each link in a keyring consumes 4 bytes of the keyring payload. .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SS Users The Linux key-management facility has a number of users and usages, but is not limited to those that already exist. -.PP +.P In-kernel users of this facility include: .TP Network filesystems - DNS @@ -863,7 +863,7 @@ The CIFS filesystem uses keys to store passwords for accessing remote shares. Module verification The kernel build process can be made to cryptographically sign modules. That signature is then checked when a module is loaded. -.PP +.P User-space users of this facility include: .TP Kerberos key storage @@ -892,7 +892,7 @@ scripts can use them. .BR user\-session\-keyring (7), .BR pam_keyinit (8), .BR request\-key (8) -.PP +.P The kernel source files .I Documentation/crypto/asymmetric\-keys.txt and under diff --git a/man7/koi8-r.7 b/man7/koi8-r.7 index 65fc642..5239cb5 100644 --- a/man7/koi8-r.7 +++ b/man7/koi8-r.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH KOI8-R 7 2022-12-15 "Linux man-pages 6.05.01" +.TH KOI8-R 7 2022-12-15 "Linux man-pages 6.7" .SH NAME koi8-r \- Russian character set encoded in octal, decimal, and hexadecimal diff --git a/man7/koi8-u.7 b/man7/koi8-u.7 index c515c2a..00dec19 100644 --- a/man7/koi8-u.7 +++ b/man7/koi8-u.7 @@ -5,7 +5,7 @@ .\" .\" 2009-01-15, mtk, Some edits .\" -.TH KOI8-U 7 2022-12-15 "Linux man-pages 6.05.01" +.TH KOI8-U 7 2022-12-15 "Linux man-pages 6.7" .SH NAME koi8-u \- Ukrainian character set encoded in octal, decimal, and hexadecimal diff --git a/man7/landlock.7 b/man7/landlock.7 index 96f8217..3df7d7b 100644 --- a/man7/landlock.7 +++ b/man7/landlock.7 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH Landlock 7 2023-05-03 "Linux man-pages 6.05.01" +.TH Landlock 7 2023-10-31 "Linux man-pages 6.7" .SH NAME Landlock \- unprivileged access-control .SH DESCRIPTION @@ -18,7 +18,7 @@ the existing system-wide access-controls. This kind of sandbox is expected to help mitigate the security impact of bugs, and unexpected or malicious behaviors in applications. -.PP +.P A Landlock security policy is a set of access rights (e.g., open a file in read-only, make a directory, etc.) tied to a file hierarchy. @@ -33,7 +33,7 @@ adds a new rule to a ruleset; .IP \[bu] .BR landlock_restrict_self (2) enforces a ruleset on the calling thread. -.PP +.P To be able to use these system calls, the running kernel must support Landlock and it must be enabled at boot time. @@ -57,7 +57,7 @@ See and .BR landlock_create_ruleset (2) for more context. -.PP +.P A file can only receive these access rights: .TP .B LANDLOCK_ACCESS_FS_EXECUTE @@ -98,14 +98,14 @@ using and .BR LANDLOCK_ACCESS_FS_WRITE_FILE . This access right is available since the third version of the Landlock ABI. -.PP +.P A directory can receive access rights related to files or directories. The following access right is applied to the directory itself, and the directories beneath it: .TP .B LANDLOCK_ACCESS_FS_READ_DIR Open a directory or list its content. -.PP +.P However, the following access rights only apply to the content of a directory, not the directory itself: @@ -194,7 +194,7 @@ Indeed, this complementary policy is composed with the potentially other rulesets already restricting this thread. A sandboxed thread can then safely add more constraints to itself with a new enforced ruleset. -.PP +.P One policy layer grants access to a file path if at least one of its rules encountered on the path grants the access. A sandboxed thread can only access a file path @@ -208,7 +208,7 @@ which means that these access rights can be propagated with bind mounts (cf. .BR mount_namespaces (7)) but not with OverlayFS. -.PP +.P A bind mount mirrors a source file hierarchy to a destination. The destination hierarchy is then composed of the exact same files, on which Landlock rules can be tied, @@ -217,7 +217,7 @@ These rules restrict access when they are encountered on a path, which means that they can restrict access to multiple file hierarchies at the same time, whether these hierarchies are the result of bind mounts or not. -.PP +.P An OverlayFS mount point consists of upper and lower layers. These layers are combined in a merge directory, result of the mount point. This merge hierarchy may include files from the upper and lower layers, @@ -244,7 +244,7 @@ For instance, one process's thread may apply Landlock rules to itself, but they will not be automatically applied to other sibling threads (unlike POSIX thread credential changes, cf. .BR nptl (7)). -.PP +.P When a thread sandboxes itself, we have the guarantee that the related security policy will stay enforced on all this thread's descendants. @@ -271,14 +271,14 @@ and both change the contents of a file and sometimes overlap in non-intuitive ways. It is recommended to always specify both of these together. -.PP +.P A particularly surprising example is .BR creat (2). The name suggests that this system call requires the rights to create and write files. However, it also requires the truncate right if an existing file under the same name is already present. -.PP +.P It should also be noted that truncating files does not require the .B LANDLOCK_ACCESS_FS_WRITE_FILE right. @@ -288,7 +288,7 @@ system call, this can also be done through .BR open (2) with the flags .IR "O_RDONLY\ |\ O_TRUNC" . -.PP +.P When opening a file, the availability of the .B LANDLOCK_ACCESS_FS_TRUNCATE right is associated with the newly created file descriptor @@ -302,7 +302,7 @@ but not during the subsequent and .BR write (2) calls. -.PP +.P As a consequence, it is possible to have multiple open file descriptors for the same file, where one grants the right to truncate the file and the other does not. @@ -311,7 +311,7 @@ keeping their Landlock properties, even when these processes do not have an enforced Landlock ruleset. .SH VERSIONS Landlock was introduced in Linux 5.13. -.PP +.P To determine which Landlock features are available, users should query the Landlock ABI version: .TS @@ -338,20 +338,19 @@ _ _ _ _ _ _ 3 6.2 LANDLOCK_ACCESS_FS_TRUNCATE .TE -.sp 1 -.PP +.P Users should use the Landlock ABI version rather than the kernel version to determine which features are available. The mainline kernel versions listed here are only included for orientation. Kernels from other sources may contain backported features, and their version numbers may not match. -.PP +.P To query the running kernel's Landlock ABI version, programs may pass the .B LANDLOCK_CREATE_RULESET_VERSION flag to .BR landlock_create_ruleset (2). -.PP +.P When building fallback mechanisms for compatibility with older kernels, users are advised to consider the special semantics of the .B LANDLOCK_ACCESS_FS_REFER @@ -394,7 +393,7 @@ accessible through these system call families: Future Landlock evolutions will enable to restrict them. .SH EXAMPLES We first need to create the ruleset that will contain our rules. -.PP +.P For this example, the ruleset will contain rules that only allow read actions, but write actions will be denied. @@ -402,7 +401,7 @@ The ruleset then needs to handle both of these kinds of actions. See the .B DESCRIPTION section for the description of filesystem actions. -.PP +.P .in +4n .EX struct landlock_ruleset_attr attr = {0}; @@ -426,11 +425,11 @@ attr.handled_access_fs = LANDLOCK_ACCESS_FS_TRUNCATE; .EE .in -.PP +.P To be compatible with older Linux versions, we detect the available Landlock ABI version, and only use the available subset of access rights: -.PP +.P .in +4n .EX /* @@ -459,11 +458,11 @@ abi = MIN(abi, 3); attr.handled_access_fs &= landlock_fs_access_rights[abi \- 1]; .EE .in -.PP +.P The available access rights for each ABI version are listed in the .B VERSIONS section. -.PP +.P If our program needed to create hard links or rename files between different directories .RB ( LANDLOCK_ACCESS_FS_REFER ), @@ -474,13 +473,13 @@ Therefore, if the program needed to do file reparenting, and if only Landlock ABI version 1 was available, we could not restrict the process. -.PP +.P Now that the ruleset attributes are determined, we create the Landlock ruleset and acquire a file descriptor as a handle to it, using .BR landlock_create_ruleset (2): -.PP +.P .in +4n .EX ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); @@ -490,13 +489,13 @@ if (ruleset_fd == \-1) { } .EE .in -.PP +.P We can now add a new rule to the ruleset through the ruleset's file descriptor. The requested access rights must be a subset of the access rights which were specified in .I attr.handled_access_fs at ruleset creation time. -.PP +.P In this example, the rule will only allow reading the file hierarchy .IR /usr . Without another rule, write actions would then be denied by the ruleset. @@ -507,7 +506,7 @@ to the ruleset, we open it with the flag and fill the .I struct landlock_path_beneath_attr with this file descriptor. -.PP +.P .in +4n .EX struct landlock_path_beneath_attr path_beneath = {0}; @@ -534,14 +533,14 @@ if (err) { } .EE .in -.PP +.P We now have a ruleset with one rule allowing read access to .I /usr while denying all other handled accesses for the filesystem. The next step is to restrict the current thread from gaining more privileges (e.g., thanks to a set-user-ID binary). -.PP +.P .in +4n .EX if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { @@ -551,9 +550,9 @@ if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { } .EE .in -.PP +.P The current thread is now ready to sandbox itself with the ruleset. -.PP +.P .in +4n .EX if (landlock_restrict_self(ruleset_fd, 0)) { @@ -564,7 +563,7 @@ if (landlock_restrict_self(ruleset_fd, 0)) { close(ruleset_fd); .EE .in -.PP +.P If the .BR landlock_restrict_self (2) system call succeeds, the current thread is now restricted and @@ -573,7 +572,7 @@ Once a thread is landlocked, there is no way to remove its security policy; only adding more restrictions is allowed. These threads are now in a new Landlock domain, merge of their parent one (if any) with the new ruleset. -.PP +.P Full working code can be found in .UR https://git.kernel.org/\:pub/\:scm/\:linux/\:kernel/\:git/\:stable/\:linux.git/\:tree/\:samples/\:landlock/\:sandboxer.c .UE @@ -581,6 +580,6 @@ Full working code can be found in .BR landlock_create_ruleset (2), .BR landlock_add_rule (2), .BR landlock_restrict_self (2) -.PP +.P .UR https://landlock.io/ .UE diff --git a/man7/libc.7 b/man7/libc.7 index 7a62251..5e906d1 100644 --- a/man7/libc.7 +++ b/man7/libc.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH libc 7 2023-02-05 "Linux man-pages 6.05.01" +.TH libc 7 2023-10-31 "Linux man-pages 6.7" .SH NAME libc \- overview of standard C libraries on Linux .SH DESCRIPTION @@ -36,7 +36,7 @@ Release 1.0 of glibc was made in September 1992. (There were earlier 0.x releases.) The next major release of glibc was 2.0, at the beginning of 1997. -.PP +.P The pathname .I /lib/libc.so.6 (or something similar) @@ -61,7 +61,7 @@ this version used the shared library soname .IR libc.so.5 . For a while, Linux libc was the standard C library in many Linux distributions. -.PP +.P However, notwithstanding the original motivations of the Linux libc effort, by the time glibc 2.0 was released @@ -72,7 +72,7 @@ soon switched back to glibc. To avoid any confusion with Linux libc versions, glibc 2.0 and later used the shared library soname .IR libc.so.6 . -.PP +.P Since the switch from Linux libc to glibc 2.0 occurred long ago, .I man-pages no longer takes care to document Linux libc details. diff --git a/man7/locale.7 b/man7/locale.7 index 49aa367..862a1d5 100644 --- a/man7/locale.7 +++ b/man7/locale.7 @@ -8,7 +8,7 @@ .\" <jochen.hein@delphi.central.de> .\" Modified Thu Apr 25 00:43:19 2002 by Bruno Haible <bruno@clisp.org> .\" -.TH locale 7 2023-05-03 "Linux man-pages 6.05.01" +.TH locale 7 2024-02-25 "Linux man-pages 6.7" .SH NAME locale \- description of multilanguage support .SH SYNOPSIS @@ -22,18 +22,18 @@ such as language for messages, different character sets, lexicographic conventions, and so on. A program needs to be able to determine its locale and act accordingly to be portable to different cultures. -.PP +.P The header .I <locale.h> declares data types, functions, and macros which are useful in this task. -.PP +.P The functions it declares are .BR setlocale (3) to set the current locale, and .BR localeconv (3) to get information about number formatting. -.PP +.P There are different categories for locale information a program might need; they are declared as macros. Using them as the first argument @@ -131,7 +131,7 @@ functions also obey the environment variable .B LANGUAGE (containing a colon-separated list of locales) if the category is set to a valid locale other than -.BR """C""" . +.BR \[dq]C\[dq] . This category also affects the behavior of .BR catopen (3). .TP @@ -213,7 +213,7 @@ and .TP .B LC_ALL All of the above. -.PP +.P If the second argument to .BR setlocale (3) is an empty string, @@ -234,13 +234,13 @@ If there is a non-null environment variable the value of .B LANG is used. -.PP +.P Values about local numeric formatting is made available in a .I struct lconv returned by the .BR localeconv (3) function, which has the following declaration: -.PP +.P .in +4n .EX struct lconv { @@ -299,7 +299,7 @@ based on implementations that first appeared in glibc 2.3. These extensions are designed to address the problem that the traditional locale APIs do not mix well with multithreaded applications and with applications that must deal with multiple locales. -.PP +.P The extensions take the form of new functions for creating and manipulating locale objects .RB ( newlocale (3), diff --git a/man7/mailaddr.7 b/man7/mailaddr.7 index 8218daa..f2da7da 100644 --- a/man7/mailaddr.7 +++ b/man7/mailaddr.7 @@ -24,7 +24,7 @@ .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" %%%LICENSE_END .\" -.TH mailaddr 7 2023-02-05 "Linux man-pages 6.05.01" +.TH mailaddr 7 2023-10-31 "Linux man-pages 6.7" .UC 5 .SH NAME mailaddr \- mail addressing description @@ -33,16 +33,16 @@ mailaddr \- mail addressing description This manual page gives a brief introduction to SMTP mail addresses, as used on the Internet. These addresses are in the general format -.PP +.P .in +4n .EX user@domain .EE .in -.PP +.P where a domain is a hierarchical dot-separated list of subdomains. These examples are valid forms of the same address: -.PP +.P .in +4n .EX john.doe@monet.example.com @@ -50,11 +50,11 @@ John Doe <john.doe@monet.example.com> john.doe@monet.example.com (John Doe) .EE .in -.PP +.P The domain part ("monet.example.com") is a mail-accepting domain. It can be a host and in the past it usually was, but it doesn't have to be. The domain part is not case sensitive. -.PP +.P The local part ("john.doe") is often a username, but its meaning is defined by the local software. Sometimes it is case sensitive, @@ -62,7 +62,7 @@ although that is unusual. If you see a local-part that looks like garbage, it is usually because of a gateway between an internal e-mail system and the net, here are some examples: -.PP +.P .in +4n .EX "surname/admd=telemail/c=us/o=hp/prmd=hp"@some.where @@ -71,17 +71,17 @@ machine!machine!name@some.where I2461572@some.where .EE .in -.PP +.P (These are, respectively, an X.400 gateway, a gateway to an arbitrary internal mail system that lacks proper internet support, an UUCP gateway, and the last one is just boring username policy.) -.PP +.P The real-name part ("John Doe") can either be placed before <>, or in () at the end. (Strictly speaking the two aren't the same, but the difference is beyond the scope of this page.) The name may have to be quoted using "", for example, if it contains ".": -.PP +.P .in +4n .EX "John Q. Doe" <john.doe@monet.example.com> @@ -99,17 +99,17 @@ In the past, sometimes one had to route a message through several hosts to get it to its final destination. Addresses which show these relays are termed "route-addrs". These use the syntax: -.PP +.P .in +4n .EX <@hosta,@hostb:user@hostc> .EE .in -.PP +.P This specifies that the message should be sent to hosta, from there to hostb, and finally to hostc. Many hosts disregard route-addrs and send directly to hostc. -.PP +.P Route-addrs are very unusual now. They occur sometimes in old mail archives. It is generally possible to ignore all but the "user@hostc" @@ -128,7 +128,7 @@ The "postmaster" address is not case sensitive. .BR aliases (5), .BR forward (5), .BR sendmail (8) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc5322.txt IETF RFC\ 5322 .UE diff --git a/man7/man-pages.7 b/man7/man-pages.7 index 6d8b0ea..c7eeb0a 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -8,7 +8,7 @@ .\" 2007-05-30 created by mtk, using text from old man.7 plus .\" rewrites and additional text. .\" -.TH man-pages 7 2023-03-30 "Linux man-pages 6.05.01" +.TH man-pages 7 2023-10-31 "Linux man-pages 6.7" .SH NAME man-pages \- conventions for writing Linux man pages .SH SYNOPSIS @@ -86,12 +86,12 @@ submitted inline. The first command in a man page should be a .B TH command: -.PP +.P .RS .B \&.TH .I "title section date source manual-section" .RE -.PP +.P The arguments of the command are as follows: .TP .I title @@ -126,7 +126,7 @@ Most manual pages should include at least the sections. Arrange a new manual page so that sections are placed in the order shown in the list. -.PP +.P .RS .TS l l. @@ -163,7 +163,7 @@ COPYRIGHT [Not used in man-pages] \fBSEE ALSO\fP .TE .RE -.PP +.P .IR "Where a traditional heading would apply" ", " "please use it" ; this kind of consistency can make the information easier to understand. If you must, you can create your own @@ -172,7 +172,7 @@ be especially useful for pages in Sections 4 and 5). However, before doing this, consider whether you could use the traditional headings, with some subsections (\fI.SS\fP) within those sections. -.PP +.P The following list elaborates on the contents of each of the above sections. .TP @@ -386,7 +386,7 @@ The .BR syscalls (2) manual page also provides information about kernel versions in which various system calls first appeared. -.PP +.P Old versions of standards should be mentioned here, rather than in STANDARDS, for example, @@ -479,13 +479,13 @@ project. Wrap the function prototype(s) in a .IR .nf / .fi pair to prevent filling. -.PP +.P In general, where more than one function prototype is shown in the SYNOPSIS, the prototypes should .I not be separated by blank lines. However, blank lines (achieved using -.IR .PP ) +.IR .P ) may be added in the following cases: .IP \[bu] 3 to separate long lists of function prototypes into related groups @@ -493,7 +493,7 @@ to separate long lists of function prototypes into related groups .BR list (3)); .IP \[bu] in other cases that may improve readability. -.PP +.P 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: @@ -565,7 +565,7 @@ Make free use of macro pairs to allow table cells to be broken over multiple lines (also bearing in mind that pages may sometimes be rendered to a width of less than 80 columns). -.PP +.P For examples of all of the above, see the source code of various pages. .SH STYLE GUIDE The following subsections describe the preferred style for the @@ -584,7 +584,7 @@ pronoun is acceptable. For manual pages that describe a command (typically in Sections 1 and 8), the arguments are always specified using italics, .IR "even in the SYNOPSIS section" . -.PP +.P The name of the command, and its options, should always be formatted in bold. .\" @@ -593,11 +593,11 @@ For manual pages that describe functions (typically in Sections 2 and 3), the arguments are always specified using italics, .IR "even in the SYNOPSIS section" , where the rest of the function is specified in bold: -.PP +.P .BI " int myfunction(int " argc ", char **" argv ); -.PP +.P Variable names should, like argument names, be specified in italics. -.PP +.P Any reference to the subject of the current manual page should be written with the name in bold followed by a pair of parentheses in Roman (normal) font. @@ -606,11 +606,11 @@ For example, in the man page, references to the subject of the page would be written as: .BR fcntl (). The preferred way to write this in the source file is: -.PP +.P .EX .BR fcntl () .EE -.PP +.P (Using this format, rather than the use of "\efB...\efP()" makes it easier to write tools that parse man page source files.) .\" @@ -676,7 +676,7 @@ usually covered by this type of list. Numbered notes Not really a list, but the syntax is identical to "positional lists". -.PP +.P There should always be exactly 2 spaces between the list symbol and the elements. This doesn't apply to "tagged paragraphs", @@ -684,14 +684,14 @@ which use the default indentation rules. .\" .SS Formatting conventions (general) Paragraphs should be separated by suitable markers (usually either -.I .PP +.I .P or .IR .IP ). Do .I not separate paragraphs using blank lines, as this results in poor rendering in some output formats (such as PostScript and PDF). -.PP +.P Filenames (whether pathnames, or references to header files) are always in italics (e.g., .IR <stdio.h> ), @@ -701,26 +701,26 @@ When referring to a standard header file include, specify the header file surrounded by angle brackets, in the usual C way (e.g., .IR <stdio.h> ). -.PP +.P Special macros, which are usually in uppercase, are in bold (e.g., .BR MAXINT ). Exception: don't boldface NULL. -.PP +.P When enumerating a list of error codes, the codes are in bold (this list usually uses the .B \&.TP macro). -.PP +.P Complete commands should, if long, be written as an indented line on their own, with a blank line before and after the command, for example -.PP +.P .in +4n .EX man 7 man\-pages .EE .in -.PP +.P If the command is short, then it can be included inline in the text, in italic format, for example, .IR "man 7 man-pages" . @@ -728,23 +728,23 @@ In this case, it may be worth using nonbreaking spaces (\e[ti]) at suitable places in the command. Command options should be written in italics (e.g., .IR \-l ). -.PP +.P Expressions, if not written on a separate indented line, should be specified in italics. Again, the use of nonbreaking spaces may be appropriate if the expression is inlined with normal text. -.PP +.P When showing example shell sessions, user input should be formatted in bold, for example -.PP +.P .in +4n .EX $ \fBdate\fP Thu Jul 7 13:01:27 CEST 2016 .EE .in -.PP +.P Any reference to another man page should be written with the name in bold, .I always @@ -753,15 +753,15 @@ formatted in Roman (normal) font, without any separating spaces (e.g., .BR intro (2)). The preferred way to write this in the source file is: -.PP +.P .EX .BR intro (2) .EE -.PP +.P (Including the section number in cross references lets tools like .BR man2html (1) create properly hyperlinked pages.) -.PP +.P Control characters should be written in bold face, with no quotes; for example, .BR \[ha]X . @@ -771,7 +771,7 @@ Starting with release 2.59, follows American spelling conventions (previously, there was a random mix of British and American spellings); please write all new pages and patches according to these conventions. -.PP +.P Aside from the well-known spelling differences, there are a few other subtleties to watch for: .IP \[bu] 3 @@ -797,7 +797,7 @@ capitalize the first word in the heading, but otherwise use lowercase, except where English usage (e.g., proper nouns) or programming language requirements (e.g., identifier names) dictate otherwise. For example: -.PP +.P .in +4n .EX \&.SS Unicode under Linux @@ -815,14 +815,14 @@ format them using the and .I .EE macros, and surround them with suitable paragraph markers (either -.I .PP +.I .P or .IR .IP ). For example: -.PP +.P .in +4n .EX -\&.PP +\&.P \&.in +4n \&.EX int @@ -832,7 +832,7 @@ main(int argc, char *argv[]) } \&.EE \&.in -\&.PP +\&.P .EE .in .SS Preferred terms @@ -897,7 +897,7 @@ Except if referring to result of "uname\ \-m" or similar T} zeros zeroes .TE -.PP +.P See also the discussion .I Hyphenation of attributive compounds below. @@ -958,10 +958,10 @@ is the .IR "null byte" , a byte with the value 0, represented in C via the character constant .IR \[aq]\e0\[aq] . -.PP +.P The preferred term for the pointer is "null pointer" or simply "NULL"; avoid writing "NULL pointer". -.PP +.P The preferred term for the byte is "null byte". Avoid writing "NUL", since it is too easily confused with "NULL". Avoid also the terms "zero byte" and "null character". @@ -977,7 +977,7 @@ macro pair .BR groff_man (7)). This produces proper hyperlinks that can be used in a web browser, when rendering a page with, say: -.PP +.P .in +4n .EX BROWSER=firefox man -H pagename @@ -988,11 +988,11 @@ In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", "cf.", and "a.k.a." should be avoided, in favor of suitable full wordings ("for example", "that is", "and so on", "compare to", "also known as"). -.PP +.P The only place where such abbreviations may be acceptable is in .I short parenthetical asides (e.g., like this one). -.PP +.P Always include periods in such abbreviations, as shown here. In addition, "e.g." and "i.e." should always be followed by a comma. .SS Em-dashes @@ -1046,7 +1046,7 @@ subcomponent subdirectory subsystem .TE -.PP +.P Hyphens should be retained when the prefixes are used in nonstandard English words, with trademarks, proper nouns, acronyms, or compound terms. Some examples: @@ -1058,7 +1058,7 @@ non-English non-NULL non-real-time .TE -.PP +.P Finally, note that "re-create" and "recreate" are two different verbs, and the former is probably what you want. .\" @@ -1069,15 +1069,15 @@ for man page cross references such as or when writing options that have a leading dash, such as in .IR "ls\ \-l"), use the following form in the man page source: -.PP +.P .in +4n .EX \e\- .EE .in -.PP +.P This guideline applies also to code examples. -.PP +.P The use of real minus signs serves the following purposes: .\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/ .IP \[bu] 3 @@ -1087,26 +1087,26 @@ notably in PDF and on Unicode/UTF\-8-capable terminals. .IP \[bu] To generate glyphs that when copied from rendered pages will produce real minus signs when pasted into a terminal. -.PP +.P To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, use "\e[aq]" ("apostrophe quote"); for example -.PP +.P .in +4n .EX \e[aq]C\e[aq] .EE .in -.PP +.P where .I C is the quoted character. This guideline applies also to character constants used in code examples. -.PP +.P Where a proper caret (\[ha]) that renders well in both a terminal and PDF is required, use "\\[ha]". This is especially necessary in code samples, to get a nicely rendered caret when rendering to PDF. -.PP +.P Using a naked "\[ti]" character results in a poor rendering in PDF. Instead use "\\[ti]". This is especially necessary in code samples, @@ -1195,7 +1195,7 @@ as in: .in .IP Always do this if the explanatory text includes a shell session log. -.PP +.P If you include a shell session log demonstrating the use of a program or other system feature: .IP \[bu] 3 @@ -1205,7 +1205,7 @@ Indent the session log by four spaces. .IP \[bu] Boldface the user input text, to distinguish it from output produced by the system. -.PP +.P For some examples of what example programs should look like, see .BR wait (2) and @@ -1,507 +1 @@ -.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler -.\" (faith@cs.unc.edu and dwheeler@ida.org) -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu) -.\" Modified Sat Jun 8 00:39:52 1996 by aeb -.\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org) -.\" Modified Thu Jul 15 12:43:28 1999 by aeb -.\" Modified Sun Jan 6 18:26:25 2002 by Martin Schulze <joey@infodrom.org> -.\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@debian.org> -.\" 2007-05-30, mtk: various rewrites and moved much text to new man-pages.7. -.\" -.TH man 7 2023-07-29 "Linux man-pages 6.05.01" -.SH NAME -man \- macros to format man pages -.SH SYNOPSIS -.B groff \-Tascii \-man -.I file -\&... -.br -.B groff \-Tps \-man -.I file -\&... -.PP -.B man -.RI [ section ] -.I title -.SH DESCRIPTION -This manual page explains the -.B "groff an.tmac" -macro package (often called the -.B man -macro package). -This macro package should be used by developers when -writing or porting man pages for Linux. -It is fairly compatible with other -versions of this macro package, so porting man pages should not be a major -problem (exceptions include the NET-2 BSD release, which uses a totally -different macro package called mdoc; see -.BR mdoc (7)). -.PP -Note that NET-2 BSD mdoc man pages can be used with -.B groff -simply by specifying the -.B \-mdoc -option instead of the -.B \-man -option. -Using the -.B \-mandoc -option is, however, recommended, since this will automatically detect which -macro package is in use. -.PP -For conventions that should be employed when writing man pages -for the Linux \fIman-pages\fP package, see -.BR man\-pages (7). -.SS Title line -The first command in a man page (after comment lines, -that is, lines that start with \fB.\e"\fP) should be -.PP -.RS -.B .TH -.I "title section date source manual" -.RE -.PP -For details of the arguments that should be supplied to the -.B TH -command, see -.BR man\-pages (7). -.PP -Note that BSD mdoc-formatted pages begin with the -.B Dd -command, not the -.B TH -command. -.SS Sections -Sections are started with -.B .SH -followed by the heading name. -.\" The following doesn't seem to be required (see Debian bug 411303), -.\" If the name contains spaces and appears -.\" on the same line as -.\" .BR .SH , -.\" then place the heading in double quotes. -.PP -The only mandatory heading is NAME, which should be the first section and -be followed on the next line by a one-line description of the program: -.PP -.RS -\&.SH NAME -.br -item \e- description -.RE -.PP -It is extremely important that this format is followed, and that there is a -backslash before the single dash which follows the item name. -This syntax is used by the -.BR mandb (8) -program to create a database of short descriptions for the -.BR whatis (1) -and -.BR apropos (1) -commands. -(See -.BR lexgrog (1) -for further details on the syntax of the NAME section.) -.PP -For a list of other sections that might appear in a manual page, see -.BR man\-pages (7). -.SS Fonts -The commands to select the type face are: -.TP 4 -.B .B -Bold -.TP -.B .BI -Bold alternating with italics -(especially useful for function specifications) -.TP -.B .BR -Bold alternating with Roman -(especially useful for referring to other -manual pages) -.TP -.B .I -Italics -.TP -.B .IB -Italics alternating with bold -.TP -.B .IR -Italics alternating with Roman -.TP -.B .RB -Roman alternating with bold -.TP -.B .RI -Roman alternating with italics -.TP -.B .SB -Small alternating with bold -.TP -.B .SM -Small (useful for acronyms) -.PP -Traditionally, each command can have up to six arguments, but the GNU -implementation removes this limitation (you might still want to limit -yourself to 6 arguments for portability's sake). -Arguments are delimited by spaces. -Double quotes can be used to specify an argument which contains spaces. -For the macros that produce alternating type faces, -the arguments will be printed next to each other without -intervening spaces, so that the -.B .BR -command can be used to specify a word in bold followed by a mark of -punctuation in Roman. -If no arguments are given, the command is applied to the following line -of text. -.SS Other macros and strings -Below are other relevant macros and predefined strings. -Unless noted otherwise, all macros -cause a break (end the current line of text). -Many of these macros set or use the "prevailing indent". -The "prevailing indent" value is set by any macro with the parameter -.I i -below; -macros may omit -.I i -in which case the current prevailing indent will be used. -As a result, successive indented paragraphs can use the same indent without -respecifying the indent value. -A normal (nonindented) paragraph resets the prevailing indent value -to its default value (0.5 inches). -By default, a given indent is measured in ens; -try to use ens or ems as units for -indents, since these will automatically adjust to font size changes. -The other key macro definitions are: -.SS Normal paragraphs -.TP 9m -.B .LP -Same as -.B .PP -(begin a new paragraph). -.TP -.B .P -Same as -.B .PP -(begin a new paragraph). -.TP -.B .PP -Begin a new paragraph and reset prevailing indent. -.SS Relative margin indent -.TP 9m -.BI .RS " i" -Start relative margin indent: moves the left margin -.I i -to the right (if -.I i -is omitted, the prevailing indent value is used). -A new prevailing indent is set to 0.5 inches. -As a result, all following paragraph(s) will be -indented until the corresponding -.BR .RE . -.TP -.B .RE -End relative margin indent and -restores the previous value of the prevailing indent. -.SS Indented paragraph macros -.TP 9m -.BI .HP " i" -Begin paragraph with a hanging indent -(the first line of the paragraph is at the left margin of -normal paragraphs, and the rest of the paragraph's lines are indented). -.TP -.BI .IP " x i" -Indented paragraph with optional hanging tag. -If the tag -.I x -is omitted, the entire following paragraph is indented by -.IR i . -If the tag -.I x -is provided, it is hung at the left margin -before the following indented paragraph -(this is just like -.B .TP -except the tag is included with the command instead of being on the -following line). -If the tag is too long, the text after the tag will be moved down to the -next line (text will not be lost or garbled). -For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash) -as the tag, and for numbered lists, use the number or letter followed by -a period as the tag; -this simplifies translation to other formats. -.TP -.BI .TP " i" -Begin paragraph with hanging tag. -The tag is given on the next line, but -its results are like those of the -.B .IP -command. -.SS Hypertext link macros -.TP -.BI .UR " url" -Insert a hypertext link to the URI (URL) -.IR url , -with all text up to the following -.B .UE -macro as the link text. -.TP -.BR .UE \~\c -.RI [ trailer ] -Terminate the link text of the preceding -.B .UR -macro, with the optional -.I trailer -(if present, usually a closing parenthesis and/or end-of-sentence -punctuation) immediately following. -For non-HTML output devices (e.g., -.BR "man \-Tutf8" ), -the link text is followed by the URL in angle brackets; if there is no -link text, the URL is printed as its own link text, surrounded by angle -brackets. -(Angle brackets may not be available on all output devices.) -For the HTML output device, the link text is hyperlinked to the URL; if -there is no link text, the URL is printed as its own link text. -.PP -These macros have been supported since GNU Troff 1.20 (2009-01-05) and -Heirloom Doctools Troff since 160217 (2016-02-17). -.SS Miscellaneous macros -.TP 9m -.B .DT -Reset tabs to default tab values (every 0.5 inches); -does not cause a break. -.TP -.BI .PD " d" -Set inter-paragraph vertical distance to d -(if omitted, d=0.4v); -does not cause a break. -.TP -.BI .SS " t" -Subheading -.I t -(like -.BR .SH , -but used for a subsection inside a section). -.SS Predefined strings -The -.B man -package has the following predefined strings: -.TP -\e*R -Registration Symbol: \*R -.TP -\e*S -Change to default font size -.TP -\e*(Tm -Trademark Symbol: \*(Tm -.TP -\e*(lq -Left angled double quote: \*(lq -.TP -\e*(rq -Right angled double quote: \*(rq -.SS Safe subset -Although technically -.B man -is a troff macro package, in reality a large number of other tools -process man page files that don't implement all of troff's abilities. -Thus, it's best to avoid some of troff's more exotic abilities -where possible to permit these other tools to work correctly. -Avoid using the various troff preprocessors -(if you must, go ahead and use -.BR tbl (1), -but try to use the -.B IP -and -.B TP -commands instead for two-column tables). -Avoid using computations; most other tools can't process them. -Use simple commands that are easy to translate to other formats. -The following troff macros are believed to be safe (though in many cases -they will be ignored by translators): -.BR \e" , -.BR . , -.BR ad , -.BR bp , -.BR br , -.BR ce , -.BR de , -.BR ds , -.BR el , -.BR ie , -.BR if , -.BR fi , -.BR ft , -.BR hy , -.BR ig , -.BR in , -.BR na , -.BR ne , -.BR nf , -.BR nh , -.BR ps , -.BR so , -.BR sp , -.BR ti , -.BR tr . -.PP -You may also use many troff escape sequences (those sequences beginning -with \e). -When you need to include the backslash character as normal text, -use \ee. -Other sequences you may use, where x or xx are any characters and N -is any digit, include: -.BR \e\[aq] , -.BR \e\[ga] , -.BR \e- , -.BR \e. , -.BR \e" , -.BR \e% , -.BR \e*x , -.BR \e*(xx , -.BR \e(xx , -.BR \e$N , -.BR \enx , -.BR \en(xx , -.BR \efx , -and -.BR \ef(xx . -Avoid using the escape sequences for drawing graphics. -.PP -Do not use the optional parameter for -.B bp -(break page). -Use only positive values for -.B sp -(vertical space). -Don't define a macro -.RB ( de ) -with the same name as a macro in this or the -mdoc macro package with a different meaning; it's likely that -such redefinitions will be ignored. -Every positive indent -.RB ( in ) -should be paired with a matching negative indent -(although you should be using the -.B RS -and -.B RE -macros instead). -The condition test -.RB ( if,ie ) -should only have \[aq]t\[aq] or \[aq]n\[aq] as the condition. -Only translations -.RB ( tr ) -that can be ignored should be used. -Font changes -.RB ( ft -and the \fB\ef\fP escape sequence) -should only have the values 1, 2, 3, 4, R, I, B, P, or CW -(the ft command may also have no parameters). -.PP -If you use capabilities beyond these, check the -results carefully on several tools. -Once you've confirmed that the additional capability is safe, -let the maintainer of this -document know about the safe command or sequence -that should be added to this list. -.SH FILES -.IR /usr/share/groff/ [*/] tmac/an.tmac -.br -.I /usr/man/whatis -.SH NOTES -By all means include full URLs (or URIs) in the text itself; -some tools such as -.BR man2html (1) -can automatically turn them into hypertext links. -You can also use the -.B UR -and -.B UE -macros to identify links to related information. -If you include URLs, use the full URL -(e.g., -.UR http://www.kernel.org -.UE ) -to ensure that tools can automatically find the URLs. -.PP -Tools processing these files should open the file and examine the first -nonwhitespace character. -A period (.) or single quote (\[aq]) at the beginning -of a line indicates a troff-based file (such as man or mdoc). -A left angle bracket (<) indicates an SGML/XML-based -file (such as HTML or Docbook). -Anything else suggests simple ASCII -text (e.g., a "catman" result). -.PP -Many man pages begin with \fB\[aq]\e"\fP followed by a -space and a list of characters, -indicating how the page is to be preprocessed. -For portability's sake to non-troff translators we recommend -that you avoid using anything other than -.BR tbl (1), -and Linux can detect that automatically. -However, you might want to include this information so your man page -can be handled by other (less capable) systems. -Here are the definitions of the preprocessors invoked by these characters: -.TP 3 -.B e -eqn(1) -.TP -.B g -grap(1) -.TP -.B p -pic(1) -.TP -.B r -refer(1) -.TP -.B t -tbl(1) -.TP -.B v -vgrind(1) -.SH BUGS -Most of the macros describe formatting (e.g., font type and spacing) instead -of marking semantic content (e.g., this text is a reference to another page), -compared to formats like mdoc and DocBook (even HTML has more semantic -markings). -This situation makes it harder to vary the -.B man -format for different media, -to make the formatting consistent for a given media, and to automatically -insert cross-references. -By sticking to the safe subset described above, it should be easier to -automate transitioning to a different reference page format in the future. -.PP -The Sun macro -.B TX -is not implemented. -.\" .SH AUTHORS -.\" .IP \[em] 3m -.\" James Clark (jjc@jclark.com) wrote the implementation of the macro package. -.\" .IP \[em] -.\" Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of -.\" this manual page. -.\" .IP \[em] -.\" Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO -.\" (which influenced this manual page). -.\" .IP \[em] -.\" David A. Wheeler (dwheeler@ida.org) heavily modified this -.\" manual page, such as adding detailed information on sections and macros. -.SH SEE ALSO -.BR apropos (1), -.BR groff (1), -.BR lexgrog (1), -.BR man (1), -.BR man2html (1), -.BR whatis (1), -.BR groff_man (7), -.BR groff_www (7), -.BR man\-pages (7), -.BR mdoc (7) +.so man7/groff_man.7 diff --git a/man7/math_error.7 b/man7/math_error.7 index d3b3c1a..6fdff9a 100644 --- a/man7/math_error.7 +++ b/man7/math_error.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH math_error 7 2023-05-03 "Linux man-pages 6.05.01" +.TH math_error 7 2023-10-31 "Linux man-pages 6.7" .SH NAME math_error \- detecting errors from mathematical functions .SH SYNOPSIS @@ -30,33 +30,33 @@ and as outlined below) described in .BR fenv (3). -.PP +.P A portable program that needs to check for an error from a mathematical function should set .I errno to zero, and make the following call -.PP +.P .in +4n .EX feclearexcept(FE_ALL_EXCEPT); .EE .in -.PP +.P before calling a mathematical function. -.PP +.P Upon return from the mathematical function, if .I errno is nonzero, or the following call (see .BR fenv (3)) returns nonzero -.PP +.P .in +4n .EX fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW); .EE .in -.PP +.P .\" enum .\" { .\" FE_INVALID = 0x01, @@ -67,7 +67,7 @@ fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | .\" FE_INEXACT = 0x20 .\" }; then an error occurred in the mathematical function. -.PP +.P The error conditions that can occur for mathematical functions are described below. .SS Domain error @@ -117,7 +117,7 @@ occurs when the magnitude of the function result means that it cannot be represented in the result type of the function. The return value of the function depends on whether the range error was an overflow or an underflow. -.PP +.P A floating result .I overflows if the result is finite, @@ -139,7 +139,7 @@ is set to and an "overflow" .RB ( FE_OVERFLOW ) floating-point exception is raised. -.PP +.P A floating result .I underflows if the result is too small to be represented in the result type. @@ -154,7 +154,7 @@ may be set to and an "underflow" .RB ( FE_UNDERFLOW ) floating-point exception may be raised. -.PP +.P Some functions deliver a range error if the supplied argument value, or the correct function result, would be .IR subnormal . @@ -186,7 +186,7 @@ A few functions set but don't raise an exception. A very few functions do neither. See the individual manual pages for details. -.PP +.P To avoid the complexities of using .I errno and @@ -199,7 +199,7 @@ For example, the following code ensures that .BR log (3)'s argument is not a NaN and is not zero (a pole error) or less than zero (a domain error): -.PP +.P .in +4n .EX double x, r; @@ -211,13 +211,13 @@ if (isnan(x) || islessequal(x, 0)) { r = log(x); .EE .in -.PP +.P The discussion on this page does not apply to the complex mathematical functions (i.e., those declared by .IR <complex.h> ), which in general are not required to return errors by C99 and POSIX.1. -.PP +.P The .BR gcc (1) .I "\-fno\-math\-errno" @@ -242,5 +242,5 @@ An error can still be tested for using .BR isgreater (3), .BR matherr (3), .BR nan (3) -.PP +.P .I "info libc" diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7 index 0ce2fee..475b44d 100644 --- a/man7/mount_namespaces.7 +++ b/man7/mount_namespaces.7 @@ -4,18 +4,18 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH mount_namespaces 7 2023-05-03 "Linux man-pages 6.05.01" +.TH mount_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME mount_namespaces \- overview of Linux mount namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P Mount namespaces provide isolation of the list of mounts seen by the processes in each namespace instance. Thus, the processes in each of the mount namespace instances will see distinct single-directory hierarchies. -.PP +.P The views provided by the .IR /proc/ pid /mounts , .IR /proc/ pid /mountinfo , @@ -28,7 +28,7 @@ correspond to the mount namespace in which the process with the PID resides. (All of the processes that reside in the same mount namespace will see the same view in these files.) -.PP +.P A new mount namespace is created using either .BR clone (2) or @@ -48,7 +48,7 @@ If the namespace is created using .BR unshare (2), the mount list of the new namespace is a copy of the mount list in the caller's previous mount namespace. -.PP +.P Subsequent modifications to the mount list .RB ( mount (2) and @@ -75,7 +75,7 @@ between namespaces (or, more precisely, between the mounts that are members of a .I peer group that are propagating events to one another). -.PP +.P Each mount is marked (via .BR mount (2)) as having one of the following @@ -148,16 +148,16 @@ flags) is performed on a directory subtree, any bind mounts within the subtree are automatically pruned (i.e., not replicated) when replicating that subtree to produce the target subtree. -.PP +.P For a discussion of the propagation type assigned to a new mount, see NOTES. -.PP +.P The propagation type is a per-mount-point setting; some mounts may be marked as shared (with each shared mount being a member of a distinct peer group), while others are private (or slaved or unbindable). -.PP +.P Note that a mount's propagation type determines whether .BR mount (2) and @@ -171,7 +171,7 @@ What happens if the mount itself is unmounted is determined by the propagation type that is in effect for the .I parent of the mount. -.PP +.P Members are added to a .I peer group when a mount is marked as shared and either: @@ -179,21 +179,21 @@ when a mount is marked as shared and either: the mount is replicated during the creation of a new mount namespace; or .IP (b) a new bind mount is created from the mount. -.PP +.P In both of these cases, the new mount joins the peer group of which the existing mount is a member. -.PP +.P A new peer group is also created when a child mount is created under an existing mount that is marked as shared. In this case, the new child mount is also marked as shared and the resulting peer group consists of all the mounts that are replicated under the peers of parent mounts. -.PP +.P A mount ceases to be a member of a peer group when either the mount is explicitly unmounted, or when the mount is implicitly unmounted because a mount namespace is removed (because it has no more member processes). -.PP +.P The propagation type of the mounts in a mount namespace can be discovered via the "optional fields" exposed in .IR /proc/ pid /mountinfo . @@ -239,14 +239,14 @@ For further details, see below. .TP .I unbindable This is an unbindable mount. -.PP +.P If none of the above tags is present, then this is a private mount. .SS MS_SHARED and MS_PRIVATE example Suppose that on a terminal in the initial mount namespace, we mark one mount as shared and another as private, and then view the mounts in .IR /proc/self/mountinfo : -.PP +.P .in +4n .EX sh1# \fBmount \-\-make\-shared /mntS\fP @@ -256,7 +256,7 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 83 61 8:15 / /mntP rw,relatime .EE .in -.PP +.P From the .I /proc/self/mountinfo output, we see that @@ -273,18 +273,18 @@ and is the root directory, .IR / , which is mounted as private: -.PP +.P .in +4n .EX sh1# \fBcat /proc/self/mountinfo | awk \[aq]$1 == 61\[aq] | sed \[aq]s/ \- .*//\[aq]\fP 61 0 8:2 / / rw,relatime .EE .in -.PP +.P On a second terminal, we create a new mount namespace where we run a second shell and inspect the mounts: -.PP +.P .in +4n .EX $ \fBPS1=\[aq]sh2# \[aq] sudo unshare \-m \-\-propagation unchanged sh\fP @@ -293,7 +293,7 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 225 145 8:15 / /mntP rw,relatime .EE .in -.PP +.P The new mount namespace received a copy of the initial mount namespace's mounts. These new mounts maintain the same propagation types, @@ -305,13 +305,13 @@ option prevents from marking all mounts as private when creating a new mount namespace, .\" Since util-linux 2.27 which it does by default.) -.PP +.P In the second terminal, we then create submounts under each of .I /mntS and .I /mntP and inspect the set-up: -.PP +.P .in +4n .EX sh2# \fBmkdir /mntS/a\fP @@ -325,13 +325,13 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 230 225 8:23 / /mntP/b rw,relatime .EE .in -.PP +.P From the above, it can be seen that .I /mntS/a was created as shared (inheriting this setting from its parent mount) and .I /mntP/b was created as a private mount. -.PP +.P Returning to the first terminal and inspecting the set-up, we see that the new mount created under the shared mount .I /mntS @@ -339,7 +339,7 @@ propagated to its peer mount (in the initial mount namespace), but the new mount created under the private mount .I /mntP did not propagate: -.PP +.P .in +4n .EX sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -365,10 +365,10 @@ and .BR umount (2) events under the slave mount from having side effects in other namespaces. -.PP +.P We can demonstrate the effect of slaving by first marking two mounts as shared in the initial mount namespace: -.PP +.P .in +4n .EX sh1# \fBmount \-\-make\-shared /mntX\fP @@ -378,10 +378,10 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 133 83 8:22 / /mntY rw,relatime shared:2 .EE .in -.PP +.P On a second terminal, we create a new mount namespace and inspect the mounts: -.PP +.P .in +4n .EX sh2# \fBunshare \-m \-\-propagation unchanged sh\fP @@ -390,9 +390,9 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 169 167 8:22 / /mntY rw,relatime shared:2 .EE .in -.PP +.P In the new mount namespace, we then mark one of the mounts as a slave: -.PP +.P .in +4n .EX sh2# \fBmount \-\-make\-slave /mntY\fP @@ -401,17 +401,17 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 169 167 8:22 / /mntY rw,relatime master:2 .EE .in -.PP +.P From the above output, we see that .I /mntY is now a slave mount that is receiving propagation events from the shared peer group with the ID 2. -.PP +.P Continuing in the new namespace, we create submounts under each of .I /mntX and .IR /mntY : -.PP +.P .in +4n .EX sh2# \fBmkdir /mntX/a\fP @@ -420,7 +420,7 @@ sh2# \fBmkdir /mntY/b\fP sh2# \fBmount /dev/sda5 /mntY/b\fP .EE .in -.PP +.P When we inspect the state of the mounts in the new mount namespace, we see that .I /mntX/a @@ -428,7 +428,7 @@ was created as a new shared mount (inheriting the "shared" setting from its parent mount) and .I /mntY/b was created as a private mount: -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -438,7 +438,7 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 175 169 8:5 / /mntY/b rw,relatime .EE .in -.PP +.P Returning to the first terminal (in the initial mount namespace), we see that the mount .I /mntX/a @@ -447,7 +447,7 @@ propagated to the peer (the shared but the mount .I /mntY/b was not propagated: -.PP +.P .in +4n .EX sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -456,11 +456,11 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 174 132 8:3 / /mntX/a rw,relatime shared:3 .EE .in -.PP +.P Now we create a new mount under .I /mntY in the first shell: -.PP +.P .in +4n .EX sh1# \fBmkdir /mntY/c\fP @@ -472,12 +472,12 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 178 133 8:1 / /mntY/c rw,relatime shared:4 .EE .in -.PP +.P When we examine the mounts in the second mount namespace, we see that in this case the new mount has been propagated to the slave mount, and that the new mount is itself a slave mount (to peer group 4): -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -494,9 +494,9 @@ One of the primary purposes of unbindable mounts is to avoid the "mount explosion" problem when repeatedly performing bind mounts of a higher-level subtree at a lower-level mount. The problem is illustrated by the following shell session. -.PP +.P Suppose we have a system with the following mounts: -.PP +.P .in +4n .EX # \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP @@ -505,11 +505,11 @@ Suppose we have a system with the following mounts: /dev/sdb7 on /mntY .EE .in -.PP +.P Suppose furthermore that we wish to recursively bind mount the root directory under several users' home directories. We do this for the first user, and inspect the mounts: -.PP +.P .in +4n .EX # \fBmount \-\-rbind / /home/cecilia/\fP @@ -522,10 +522,10 @@ We do this for the first user, and inspect the mounts: /dev/sdb7 on /home/cecilia/mntY .EE .in -.PP +.P When we repeat this operation for the second user, we start to see the explosion problem: -.PP +.P .in +4n .EX # \fBmount \-\-rbind / /home/henry\fP @@ -544,7 +544,7 @@ we start to see the explosion problem: /dev/sdb7 on /home/henry/home/cecilia/mntY .EE .in -.PP +.P Under .IR /home/henry , we have not only recursively added the @@ -556,7 +556,7 @@ mounts, but also the recursive mounts of those directories under that were created in the previous step. Upon repeating the step for a third user, it becomes obvious that the explosion is exponential in nature: -.PP +.P .in +4n .EX # \fBmount \-\-rbind / /home/otto\fP @@ -587,21 +587,21 @@ it becomes obvious that the explosion is exponential in nature: /dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY .EE .in -.PP +.P The mount explosion problem in the above scenario can be avoided by making each of the new mounts unbindable. The effect of doing this is that recursive mounts of the root directory will not replicate the unbindable mounts. We make such a mount for the first user: -.PP +.P .in +4n .EX # \fBmount \-\-rbind \-\-make\-unbindable / /home/cecilia\fP .EE .in -.PP +.P Before going further, we show that unbindable mounts are indeed unbindable: -.PP +.P .in +4n .EX # \fBmkdir /mntZ\fP @@ -613,21 +613,21 @@ mount: wrong fs type, bad option, bad superblock on /home/cecilia, dmesg | tail or so. .EE .in -.PP +.P Now we create unbindable recursive bind mounts for the other two users: -.PP +.P .in +4n .EX # \fBmount \-\-rbind \-\-make\-unbindable / /home/henry\fP # \fBmount \-\-rbind \-\-make\-unbindable / /home/otto\fP .EE .in -.PP +.P Upon examining the list of mounts, we see there has been no explosion of mounts, because the unbindable mounts were not replicated under each user's directory: -.PP +.P .in +4n .EX # \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP @@ -666,9 +666,9 @@ slave+shared slave+shared slave priv unbind private shared priv [2] priv unbind unbindable shared unbind [2] priv unbind .TE -.sp 1 +.P Note the following details to the table: -.IP [1] 4 +.IP [1] 5 If a shared mount is the only mount in its peer group, making it a slave automatically makes it private. .IP [2] @@ -676,13 +676,13 @@ Slaving a nonshared mount has no effect on the mount. .\" .SS Bind (MS_BIND) semantics Suppose that the following command is performed: -.PP +.P .in +4n .EX mount \-\-bind A/a B/b .EE .in -.PP +.P Here, .I A is the source mount, @@ -702,7 +702,7 @@ depends on the propagation types of the mounts and .IR B , and is summarized in the following table. -.PP +.P .TS lb2 lb1 lb2 lb2 lb2 lb0 lb2 lb1 lb2 lb2 lb2 lb0 @@ -713,24 +713,24 @@ _ dest(B) shared shared shared slave+shared invalid nonshared shared private slave invalid .TE -.sp 1 +.P Note that a recursive bind of a subtree follows the same semantics as for a bind operation on each mount in the subtree. (Unbindable mounts are automatically pruned at the target mount point.) -.PP +.P For further details, see .I Documentation/filesystems/sharedsubtree.rst in the kernel source tree. .\" .SS Move (MS_MOVE) semantics Suppose that the following command is performed: -.PP +.P .in +4n .EX mount \-\-move A B/b .EE .in -.PP +.P Here, .I A is the source mount, @@ -746,7 +746,7 @@ depends on the propagation types of the mounts and .IR B , and is summarized in the following table. -.PP +.P .TS lb2 lb1 lb2 lb2 lb2 lb0 lb2 lb1 lb2 lb2 lb2 lb0 @@ -757,22 +757,22 @@ _ dest(B) shared shared shared slave+shared invalid nonshared shared private slave unbindable .TE -.sp 1 +.P Note: moving a mount that resides under a shared mount is invalid. -.PP +.P For further details, see .I Documentation/filesystems/sharedsubtree.rst in the kernel source tree. .\" .SS Mount semantics Suppose that we use the following command to create a mount: -.PP +.P .in +4n .EX mount device B/b .EE .in -.PP +.P Here, .I B is the destination mount, and @@ -787,13 +787,13 @@ is considered always to be private. .\" .SS Unmount semantics Suppose that we use the following command to tear down a mount: -.PP +.P .in +4n .EX umount A .EE .in -.PP +.P Here, .I A is a mount on @@ -822,7 +822,7 @@ record in cases where a process can't see a slave's immediate master the filesystem root directory) and so cannot determine the chain of propagation between the mounts it can see. -.PP +.P In the following example, we first create a two-link master-slave chain between the mounts .IR /mnt , @@ -837,7 +837,7 @@ mount point unreachable from the root directory, creating a situation where the master of .I /mnt/tmp/etc is not reachable from the (new) root directory of the process. -.PP +.P First, we bind mount the root directory onto .I /mnt and then bind mount @@ -850,7 +850,7 @@ the .BR proc (5) filesystem remains visible at the correct location in the chroot-ed environment. -.PP +.P .in +4n .EX # \fBmkdir \-p /mnt/proc\fP @@ -858,11 +858,11 @@ in the chroot-ed environment. # \fBmount \-\-bind /proc /mnt/proc\fP .EE .in -.PP +.P Next, we ensure that the .I /mnt mount is a shared mount in a new peer group (with no peers): -.PP +.P .in +4n .EX # \fBmount \-\-make\-private /mnt\fP # Isolate from any previous peer group @@ -872,12 +872,12 @@ mount is a shared mount in a new peer group (with no peers): 248 239 0:4 / /mnt/proc ... shared:5 .EE .in -.PP +.P Next, we bind mount .I /mnt/etc onto .IR /tmp/etc : -.PP +.P .in +4n .EX # \fBmkdir \-p /tmp/etc\fP @@ -888,7 +888,7 @@ onto 267 40 8:2 /etc /tmp/etc ... shared:102 .EE .in -.PP +.P Initially, these two mounts are in the same peer group, but we then make the .I /tmp/etc @@ -898,7 +898,7 @@ and then make .I /tmp/etc shared as well, so that it can propagate events to the next slave in the chain: -.PP +.P .in +4n .EX # \fBmount \-\-make\-slave /tmp/etc\fP @@ -909,7 +909,7 @@ so that it can propagate events to the next slave in the chain: 267 40 8:2 /etc /tmp/etc ... shared:105 master:102 .EE .in -.PP +.P Then we bind mount .I /tmp/etc onto @@ -919,7 +919,7 @@ but we then make .I /mnt/tmp/etc a slave of .IR /tmp/etc : -.PP +.P .in +4n .EX # \fBmkdir \-p /mnt/tmp/etc\fP @@ -932,30 +932,30 @@ a slave of 273 239 8:2 /etc /mnt/tmp/etc ... master:105 .EE .in -.PP +.P From the above, we see that .I /mnt is the master of the slave .IR /tmp/etc , which in turn is the master of the slave .IR /mnt/tmp/etc . -.PP +.P We then .BR chroot (1) to the .I /mnt directory, which renders the mount with ID 267 unreachable from the (new) root directory: -.PP +.P .in +4n .EX # \fBchroot /mnt\fP .EE .in -.PP +.P When we examine the state of the mounts inside the chroot-ed environment, we see the following: -.PP +.P .in +4n .EX # \fBcat /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP @@ -964,7 +964,7 @@ we see the following: 273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102 .EE .in -.PP +.P Above, we see that the mount with ID 273 is a slave whose master is the peer group 105. The mount point for that master is unreachable, and so a @@ -992,7 +992,7 @@ then the propagation type of the new mount is also .BR MS_SHARED . Otherwise, the propagation type of the new mount is .BR MS_PRIVATE . -.PP +.P Notwithstanding the fact that the default propagation type for new mount is in many cases .BR MS_PRIVATE , @@ -1005,7 +1005,7 @@ automatically remounts all mounts as on system startup. Thus, on most modern systems, the default propagation type is in practice .BR MS_SHARED . -.PP +.P Since, when one uses .BR unshare (1) to create a mount namespace, @@ -1020,18 +1020,18 @@ by making all mounts private in the new namespace. That is, .BR unshare (1) performs the equivalent of the following in the new mount namespace: -.PP +.P .in +4n .EX mount \-\-make\-rprivate / .EE .in -.PP +.P To prevent this, one can use the .I \-\-propagation\~unchanged option to .BR unshare (1). -.PP +.P An application that creates a new mount namespace directly using .BR clone (2) or @@ -1045,13 +1045,13 @@ mounts in the new namespace to either or .BR MS_PRIVATE , using a call such as the following: -.PP +.P .in +4n .EX mount(NULL, "/", MS_SLAVE | MS_REC, NULL); .EE .in -.PP +.P For a discussion of propagation types when moving mounts .RB ( MS_MOVE ) and creating bind mounts @@ -1063,7 +1063,7 @@ see .\" .SS Restrictions on mount namespaces Note the following points with respect to mount namespaces: -.IP [1] 4 +.IP [1] 5 Each mount namespace has an owner user namespace. As explained above, when a new mount namespace is created, its mount list is initialized as a copy of the mount list @@ -1366,6 +1366,6 @@ See .BR pam_namespace (8), .BR pivot_root (8), .BR umount (8) -.PP +.P .I Documentation/filesystems/sharedsubtree.rst in the kernel source tree. diff --git a/man7/mq_overview.7 b/man7/mq_overview.7 index b022ea0..223f238 100644 --- a/man7/mq_overview.7 +++ b/man7/mq_overview.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_overview 7 2023-02-05 "Linux man-pages 6.05.01" +.TH mq_overview 7 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_overview \- overview of POSIX message queues .SH DESCRIPTION @@ -14,7 +14,7 @@ This API is distinct from that provided by System V message queues .BR msgsnd (2), .BR msgrcv (2), etc.), but provides similar functionality. -.PP +.P Message queues are created and opened using .BR mq_open (3); this function returns a @@ -29,7 +29,7 @@ that is, a null-terminated string of up to followed by one or more characters, none of which are slashes. Two processes can operate on the same queue by passing the same name to .BR mq_open (3). -.PP +.P Messages are transferred to and from a queue using .BR mq_send (3) and @@ -45,7 +45,7 @@ and A process can request asynchronous notification of the arrival of a message on a previously empty queue using .BR mq_notify (3). -.PP +.P A message queue descriptor is a reference to an .I "open message queue description" (see @@ -58,7 +58,7 @@ as the corresponding message queue descriptors in the parent. Corresponding message queue descriptors in the two processes share the flags .RI ( mq_flags ) that are associated with the open message queue description. -.PP +.P Each message has an associated .IR priority , and messages are always delivered to the receiving process @@ -71,7 +71,7 @@ On Linux, returns 32768, but POSIX.1 requires only that an implementation support at least priorities in the range 0 to 31; some implementations provide only this range. -.PP +.P The remainder of this section describes some specific details of the Linux implementation of POSIX message queues. .SS Library interfaces and system calls @@ -265,33 +265,33 @@ On Linux, message queues are created in a virtual filesystem. but the details are likely to differ.) This filesystem can be mounted (by the superuser) using the following commands: -.PP +.P .in +4n .EX .RB "#" " mkdir /dev/mqueue" .RB "#" " mount \-t mqueue none /dev/mqueue" .EE .in -.PP +.P The sticky bit is automatically enabled on the mount directory. -.PP +.P After the filesystem has been mounted, the message queues on the system can be viewed and manipulated using the commands usually used for files (e.g., .BR ls (1) and .BR rm (1)). -.PP +.P The contents of each file in the directory consist of a single line containing information about the queue: -.PP +.P .in +4n .EX .RB "$" " cat /dev/mqueue/mymq" QSIZE:129 NOTIFY:2 SIGNO:0 NOTIFY_PID:8260 .EE .in -.PP +.P These fields are as follows: .TP .B QSIZE @@ -325,7 +325,7 @@ This means that a message queue descriptor can be monitored using or .BR epoll (7). This is not portable. -.PP +.P The close-on-exec flag (see .BR open (2)) is automatically set on the file descriptor returned by @@ -344,7 +344,7 @@ POSIX message queues provide a better designed interface than System V message queues; on the other hand POSIX message queues are less widely available (especially on older systems) than System V message queues. -.PP +.P Linux does not currently (Linux 2.6.26) support the use of access control lists (ACLs) for POSIX message queues. .SH BUGS @@ -356,7 +356,7 @@ limit could be raised, and the ceiling was enforced even for privileged processes. This ceiling value was removed in Linux 3.14, and patches to stable Linux 3.5.x to Linux 3.13.x also removed the ceiling. -.PP +.P As originally implemented (and documented), the QSIZE field displayed the total number of (user-supplied) bytes in all messages in the message queue. diff --git a/man7/namespaces.7 b/man7/namespaces.7 index 6ff11af..5fdca2e 100644 --- a/man7/namespaces.7 +++ b/man7/namespaces.7 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH namespaces 7 2023-07-20 "Linux man-pages 6.05.01" +.TH namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME namespaces \- overview of Linux namespaces .SH DESCRIPTION @@ -15,7 +15,7 @@ have their own isolated instance of the global resource. Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. One use of namespaces is to implement containers. -.PP +.P This page provides pointers to information on the various namespace types, describes the associated .I /proc @@ -108,7 +108,7 @@ Various operations can be used to discover information about namespaces. These operations are described in .BR ioctl_ns (2). -.PP +.P Creation of new namespaces using .BR clone (2) and @@ -131,7 +131,7 @@ Each process has a subdirectory containing one entry for each namespace that supports being manipulated by .BR setns (2): -.PP +.P .in +4n .EX $ \fBls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]\fP @@ -148,7 +148,7 @@ lrwxrwxrwx. user \-> user:[4026531837] lrwxrwxrwx. uts \-> uts:[4026531838] .EE .in -.PP +.P Bind mounting (see .BR mount (2)) one of the files in this directory @@ -156,7 +156,7 @@ to somewhere else in the filesystem keeps the corresponding namespace of the process specified by .I pid alive even if all processes currently in the namespace terminate. -.PP +.P Opening one of the files in this directory (or a file that is bind mounted to one of these files) returns a file handle for @@ -167,7 +167,7 @@ the namespace will remain alive, even if all processes in the namespace terminate. The file descriptor can be passed to .BR setns (2). -.PP +.P In Linux 3.7 and earlier, these files were visible as hard links. Since Linux 3.8, .\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5 @@ -188,14 +188,14 @@ fields returned by .BR stat (2). The content of this symbolic link is a string containing the namespace type and inode number as in the following example: -.PP +.P .in +4n .EX $ \fBreadlink /proc/$$/ns/uts\fP uts:[4026531838] .EE .in -.PP +.P The symbolic links in this subdirectory are as follows: .TP .IR /proc/ pid /ns/cgroup " (since Linux 4.6)" @@ -256,7 +256,7 @@ This file is a handle for the user namespace of the process. .TP .IR /proc/ pid /ns/uts " (since Linux 3.0)" This file is a handle for the UTS namespace of the process. -.PP +.P Permission to dereference or read .RB ( readlink (2)) these symbolic links is governed by a ptrace access mode @@ -305,7 +305,7 @@ user namespaces that may be created in the user namespace. .I max_uts_namespaces 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 +.P Note the following details about these files: .IP \[bu] 3 The values in these files are modifiable by privileged processes. diff --git a/man7/netdevice.7 b/man7/netdevice.7 index a0f0049..9f9f002 100644 --- a/man7/netdevice.7 +++ b/man7/netdevice.7 @@ -10,7 +10,7 @@ .\" Modified, 2011-11-02, <bidulock@openss7.org>, added many basic .\" but missing ioctls, such as SIOCGIFADDR. .\" -.TH netdevice 7 2023-07-15 "Linux man-pages 6.05.01" +.TH netdevice 7 2023-10-31 "Linux man-pages 6.7" .SH NAME netdevice \- low-level access to Linux network devices .SH SYNOPSIS @@ -21,14 +21,14 @@ netdevice \- low-level access to Linux network devices .SH DESCRIPTION This man page describes the sockets interface which is used to configure network devices. -.PP +.P Linux supports some standard ioctls to configure network devices. They can be used on any socket's file descriptor regardless of the family or type. Most of them pass an .I ifreq structure: -.PP +.P .in +4n .EX struct ifreq { @@ -51,13 +51,13 @@ struct ifreq { }; .EE .in -.PP +.P .B AF_INET6 is an exception. It passes an .I in6_ifreq structure: -.PP +.P .in +4n .EX struct in6_ifreq { @@ -67,7 +67,7 @@ struct in6_ifreq { }; .EE .in -.PP +.P Normally, the user specifies which device to affect by setting .I ifr_name to the name of the interface or @@ -96,7 +96,9 @@ This is the only ioctl which returns its result in Retrieve the interface index of the interface into .IR ifr_ifindex . .TP -.BR SIOCGIFFLAGS ", " SIOCSIFFLAGS +.B SIOCGIFFLAGS +.TQ +.B SIOCSIFFLAGS Get or set the active flag word of the device. .I ifr_flags contains a bit mask of the following values: @@ -132,11 +134,13 @@ IFF_DORMANT:Driver signals dormant (since Linux 2.6.17) IFF_ECHO:Echo sent packets (since Linux 2.6.25) .TE .ad -.PP +.P Setting the active flag word is a privileged operation, but any process may read it. .TP -.BR SIOCGIFPFLAGS ", " SIOCSIFPFLAGS +.B SIOCGIFPFLAGS +.TQ +.B SIOCSIFPFLAGS Get or set extended (private) flags for the device. .I ifr_flags contains a bit mask of the following values: @@ -154,10 +158,14 @@ IFF_BONDING:Interface is a bonding master or slave. IFF_SLAVE_NEEDARP:Interface needs ARPs for validation. IFF_ISATAP:Interface is RFC4214 ISATAP interface. .TE -.PP +.P Setting the extended (private) interface flags is a privileged operation. .TP -.BR SIOCGIFADDR ", " SIOCSIFADDR ", " SIOCDIFADDR +.B SIOCGIFADDR +.TQ +.B SIOCSIFADDR +.TQ +.B SIOCDIFADDR Get, set, or delete the address of the device using .IR ifr_addr , or @@ -185,7 +193,9 @@ A address can be deleted by setting it to zero via .BR SIOCSIFADDR . .TP -.BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR +.B SIOCGIFDSTADDR +.TQ +.B SIOCSIFDSTADDR Get or set the destination address of a point-to-point device using .IR ifr_dstaddr . For compatibility, only @@ -193,7 +203,9 @@ For compatibility, only addresses are accepted or returned. Setting the destination address is a privileged operation. .TP -.BR SIOCGIFBRDADDR ", " SIOCSIFBRDADDR +.B SIOCGIFBRDADDR +.TQ +.B SIOCSIFBRDADDR Get or set the broadcast address for a device using .IR ifr_brdaddr . For compatibility, only @@ -201,7 +213,9 @@ For compatibility, only addresses are accepted or returned. Setting the broadcast address is a privileged operation. .TP -.BR SIOCGIFNETMASK ", " SIOCSIFNETMASK +.B SIOCGIFNETMASK +.TQ +.B SIOCSIFNETMASK Get or set the network mask for a device using .IR ifr_netmask . For compatibility, only @@ -209,7 +223,9 @@ For compatibility, only addresses are accepted or returned. Setting the network mask is a privileged operation. .TP -.BR SIOCGIFMETRIC ", " SIOCSIFMETRIC +.B SIOCGIFMETRIC +.TQ +.B SIOCSIFMETRIC Get or set the metric of the device using .IR ifr_metric . This is currently not implemented; it sets @@ -218,14 +234,18 @@ to 0 if you attempt to read it and returns .B EOPNOTSUPP if you attempt to set it. .TP -.BR SIOCGIFMTU ", " SIOCSIFMTU +.B SIOCGIFMTU +.TQ +.B SIOCSIFMTU Get or set the MTU (Maximum Transfer Unit) of a device using .IR ifr_mtu . Setting the MTU is a privileged operation. Setting the MTU to too small values may cause kernel crashes. .TP -.BR SIOCGIFHWADDR ", " SIOCSIFHWADDR +.B SIOCGIFHWADDR +.TQ +.B SIOCSIFHWADDR Get or set the hardware address of a device using .IR ifr_hwaddr . The hardware address is specified in a struct @@ -241,7 +261,9 @@ Set the hardware broadcast address of a device from .IR ifr_hwaddr . This is a privileged operation. .TP -.BR SIOCGIFMAP ", " SIOCSIFMAP +.B SIOCGIFMAP +.TQ +.B SIOCSIFMAP Get or set the interface's hardware parameters using .IR ifr_map . Setting the parameters is a privileged operation. @@ -262,7 +284,9 @@ struct ifmap { The interpretation of the ifmap structure depends on the device driver and the architecture. .TP -.BR SIOCADDMULTI ", " SIOCDELMULTI +.B SIOCADDMULTI +.TQ +.B SIOCDELMULTI Add an address to or delete an address from the device's link layer multicast filters using .IR ifr_hwaddr . @@ -271,7 +295,9 @@ See also .BR packet (7) for an alternative. .TP -.BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN +.B SIOCGIFTXQLEN +.TQ +.B SIOCSIFTXQLEN Get or set the transmit queue length of a device using .IR ifr_qlen . Setting the transmit queue length is a privileged operation. @@ -357,19 +383,21 @@ will be returned. .\" Slaving isn't supported in Linux 2.2 .\" . .\" .TP -.\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE +.\" .B SIOCGIFSLAVE +.\" .TQ +.\" .B SIOCSIFSLAVE .\" Get or set the slave device using .\" .IR ifr_slave . .\" Setting the slave device is a privileged operation. -.\" .PP +.\" .P .\" FIXME . add amateur radio stuff. -.PP +.P Most protocols support their own ioctls to configure protocol-specific interface options. See the protocol man pages for a description. For configuring IP addresses, see .BR ip (7). -.PP +.P In addition, some devices support private ioctls. These are not described here. .SH NOTES @@ -379,12 +407,12 @@ and the other ioctls that accept or return only socket addresses are IP-specific and perhaps should rather be documented in .BR ip (7). -.PP +.P The names of interfaces with no addresses or that don't have the .B IFF_RUNNING flag set can be found via .IR /proc/net/dev . -.PP +.P .B AF_INET6 IPv6 addresses can be read from .I /proc/net/if_inet6 @@ -406,7 +434,7 @@ glibc 2.1 is missing the macro in .IR <net/if.h> . Add the following to your program as a workaround: -.PP +.P .in +4n .EX #ifndef ifr_newname diff --git a/man7/netlink.7 b/man7/netlink.7 index 4d6cdbc..e0e14f4 100644 --- a/man7/netlink.7 +++ b/man7/netlink.7 @@ -6,7 +6,7 @@ .\" Based on the original comments from Alexey Kuznetsov .\" Modified 2005-12-27 by Hasso Tepper <hasso@estpak.ee> .\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $ -.TH netlink 7 2023-07-30 "Linux man-pages 6.05.01" +.TH netlink 7 2023-10-31 "Linux man-pages 6.7" .SH NAME netlink \- communication between kernel and user space (AF_NETLINK) .SH SYNOPSIS @@ -14,7 +14,7 @@ netlink \- communication between kernel and user space (AF_NETLINK) .B #include <asm/types.h> .B #include <sys/socket.h> .B #include <linux/netlink.h> -.PP +.P .BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ The internal kernel interface is not documented in this manual page. There is also an obsolete netlink interface via netlink character devices; this interface is not documented here and is provided only for backward compatibility. -.PP +.P Netlink is a datagram-oriented service. Both .B SOCK_RAW @@ -36,7 +36,7 @@ are valid values for .IR socket_type . However, the netlink protocol does not distinguish between datagram and raw sockets. -.PP +.P .I netlink_family selects the kernel module or netlink group to communicate with. The currently assigned netlink families are: @@ -144,7 +144,7 @@ Generic netlink family for simplified netlink usage. Netlink interface to request information about ciphers registered with the kernel crypto API as well as allow configuration of the kernel crypto API. -.PP +.P Netlink messages consist of a byte stream with one or multiple .I nlmsghdr headers and associated payload. @@ -154,7 +154,7 @@ macros. See .BR netlink (3) for further information. -.PP +.P In multipart messages (multiple .I nlmsghdr headers with associated payload in one byte stream) the first and all @@ -162,11 +162,11 @@ following headers have the .B NLM_F_MULTI flag set, except for the last header which has the type .BR NLMSG_DONE . -.PP +.P After each .I nlmsghdr the payload follows. -.PP +.P .in +4n .EX struct nlmsghdr { @@ -178,7 +178,7 @@ struct nlmsghdr { }; .EE .in -.PP +.P .I nlmsg_type can be one of the standard message types: .B NLMSG_NOOP @@ -192,7 +192,7 @@ message terminates a multipart message. Error messages get the original request appended, unless the user requests to cap the error message, and get extra error data if requested. -.PP +.P .in +4n .EX struct nlmsgerr { @@ -212,7 +212,7 @@ struct nlmsgerr { }; .EE .in -.PP +.P A netlink family usually specifies more message types, see the appropriate manual pages for that, for example, .BR rtnetlink (7) @@ -261,7 +261,7 @@ Convenience macro; equivalent to T} .TE .\" FIXME NLM_F_ATOMIC is not used anymore? -.PP +.P Note that .B NLM_F_ATOMIC requires the @@ -286,7 +286,7 @@ NLM_F_APPEND:T{ Add to the end of the object list. T} .TE -.PP +.P .I nlmsg_seq and .I nlmsg_pid @@ -300,14 +300,14 @@ socket. See the .B ADDRESS FORMATS section for further information. -.PP +.P Both .I nlmsg_seq and .I nlmsg_pid .\" FIXME Explain more about nlmsg_seq and nlmsg_pid. are opaque to netlink core. -.PP +.P Netlink is not a reliable protocol. It tries its best to deliver a message to its destination(s), but may drop messages when an out-of-memory condition or @@ -325,7 +325,7 @@ The kernel tries to send an .B NLMSG_ERROR message for every failed packet. A user process should follow this convention too. -.PP +.P However, reliable transmissions from kernel to user are impossible in any case. The kernel can't send a netlink message if the socket buffer is full: @@ -346,7 +346,7 @@ can be either unicast (only sent to one peer) or sent to netlink multicast groups .RI ( nl_groups not equal 0). -.PP +.P .in +4n .EX struct sockaddr_nl { @@ -357,7 +357,7 @@ struct sockaddr_nl { }; .EE .in -.PP +.P .I nl_pid is the unicast address of netlink socket. It's always 0 if the destination is in the kernel. @@ -386,7 +386,7 @@ The kernel assigns the process ID to the first netlink socket the process opens and assigns a unique .I nl_pid to every netlink socket that the process subsequently creates. -.PP +.P .I nl_groups is a bit mask with every bit representing a netlink group number. Each netlink family has a set of 32 multicast groups. @@ -443,7 +443,9 @@ Enable control messages for received packets to get the extended destination group number. .TP -.BR NETLINK_ADD_MEMBERSHIP ,\ NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)" +.B NETLINK_ADD_MEMBERSHIP +.TQ +.BR NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)" .\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99 .\" Author: Patrick McHardy <kaber@trash.net> Join/leave a group specified by @@ -502,7 +504,7 @@ The netlink message header is still included, so the user can guess from the sequence number which message triggered the acknowledgement. .SH VERSIONS The socket interface to netlink first appeared Linux 2.2. -.PP +.P Linux 2.0 supported a more primitive device-based netlink interface (which is still available as a compatibility option). This obsolete interface is not described here. @@ -522,7 +524,7 @@ netlink socket which will listen to the (network interface create/delete/up/down events) and .B RTMGRP_IPV4_IFADDR (IPv4 addresses add/delete events) multicast groups. -.PP +.P .in +4n .EX struct sockaddr_nl sa; @@ -535,12 +537,12 @@ fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE); bind(fd, (struct sockaddr *) &sa, sizeof(sa)); .EE .in -.PP +.P The next example demonstrates how to send a netlink message to the kernel (pid 0). Note that the application must take care of message sequence numbers in order to reliably track acknowledgements. -.PP +.P .in +4n .EX struct nlmsghdr *nh; /* The nlmsghdr with payload to send */ @@ -559,9 +561,9 @@ nh\->nlmsg_flags |= NLM_F_ACK; sendmsg(fd, &msg, 0); .EE .in -.PP +.P And the last example is about reading netlink message. -.PP +.P .in +4n .EX int len; @@ -597,13 +599,13 @@ for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len); .BR capabilities (7), .BR rtnetlink (7), .BR sock_diag (7) -.PP +.P .UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2* information about libnetlink .UE -.PP +.P .UR http://www.infradead.org\:/\[ti]tgr\:/libnl/ information about libnl .UE -.PP +.P RFC 3549 "Linux Netlink as an IP Services Protocol" diff --git a/man7/network_namespaces.7 b/man7/network_namespaces.7 index a9e6306..06d323f 100644 --- a/man7/network_namespaces.7 +++ b/man7/network_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH network_namespaces 7 2023-03-12 "Linux man-pages 6.05.01" +.TH network_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME network_namespaces \- overview of Linux network namespaces .SH DESCRIPTION @@ -21,7 +21,7 @@ port numbers (sockets), and so on. In addition, network namespaces isolate the UNIX domain abstract socket namespace (see .BR unix (7)). -.PP +.P A physical network device can live in exactly one network namespace. When a network namespace is freed @@ -29,7 +29,7 @@ When a network namespace is freed its physical network devices are moved back to the initial network namespace (not to the namespace of the parent of the process). -.PP +.P A virtual network .RB ( veth (4)) device pair provides a pipe-like abstraction @@ -39,7 +39,7 @@ in another namespace. When a namespace is freed, the .BR veth (4) devices that it contains are destroyed. -.PP +.P Use of network namespaces requires a kernel that is configured with the .B CONFIG_NET_NS option. diff --git a/man7/nptl.7 b/man7/nptl.7 index a00c845..421ad5f 100644 --- a/man7/nptl.7 +++ b/man7/nptl.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH nptl 7 2023-02-05 "Linux man-pages 6.05.01" +.TH nptl 7 2023-10-31 "Linux man-pages 6.7" .SH NAME nptl \- Native POSIX Threads Library .SH DESCRIPTION @@ -20,7 +20,7 @@ One of these signals is used to support thread cancelation and POSIX timers the other is used as part of a mechanism that ensures all threads in a process always have the same UIDs and GIDs, as required by POSIX. These signals cannot be used in applications. -.PP +.P To prevent accidental use of these signals in applications, which might interfere with the operation of the NPTL implementation, various glibc library functions and system call wrapper functions @@ -66,7 +66,7 @@ the NPTL implementation wraps all of the system calls that change process credentials with functions that, in addition to invoking the underlying system call, arrange for all other threads in the process to also change their credentials. -.PP +.P The implementation of each of these system calls involves the use of a real-time signal that is sent (using .BR tgkill (2)) @@ -76,7 +76,7 @@ saves the new credential(s) and records the system call being employed in a global buffer. A signal handler in the receiving thread(s) fetches this information and then uses the same system call to change its credentials. -.PP +.P Wrapper functions employing this technique are provided for .BR setgid (2), .BR setuid (2), diff --git a/man7/numa.7 b/man7/numa.7 index 9ac5097..0365469 100644 --- a/man7/numa.7 +++ b/man7/numa.7 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH numa 7 2023-04-03 "Linux man-pages 6.05.01" +.TH numa 7 2023-10-31 "Linux man-pages 6.7" .SH NAME numa \- overview of Non-Uniform Memory Architecture .SH DESCRIPTION @@ -35,11 +35,11 @@ see "Library Support" below. .\" See also Changelog-2.6.14 This file displays information about a process's NUMA memory policy and allocation. -.PP +.P Each line contains information about a memory range used by the process, displaying\[em]among other information\[em]the effective memory policy for that memory range and on which nodes the pages have been allocated. -.PP +.P .I numa_maps is a read-only file. When @@ -47,14 +47,14 @@ When is read, the kernel will scan the virtual address space of the process and report how memory is used. One line is displayed for each unique memory range of the process. -.PP +.P The first field of each line shows the starting address of the memory range. This field allows a correlation with the contents of the .IR /proc/ pid /maps file, which contains the end address of the range and other information, such as the access permissions and sharing. -.PP +.P The second field shows the memory policy currently in effect for the memory range. Note that the effective policy is not necessarily the policy @@ -62,7 +62,7 @@ installed by the process for that memory range. Specifically, if the process installed a "default" policy for that range, the effective policy for that range will be the process policy, which may or may not be "default". -.PP +.P The rest of the line contains information about the pages allocated in the memory range, as follows: .TP @@ -143,7 +143,7 @@ and the required header are available in the .I numactl package. -.PP +.P However, applications should not use these system calls directly. Instead, the higher level interface provided by the .BR numa (3) diff --git a/man7/operator.7 b/man7/operator.7 index ec4652f..047041e 100644 --- a/man7/operator.7 +++ b/man7/operator.7 @@ -14,12 +14,12 @@ .\" .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" -.TH operator 7 2023-02-05 "Linux man-pages 6.05.01" +.TH operator 7 2023-10-31 "Linux man-pages 6.7" .SH NAME operator \- C operator precedence and order of evaluation .SH DESCRIPTION This manual page lists C operators and their precedence in evaluation. -.PP +.P .TS lb lb lb l l l. @@ -41,11 +41,11 @@ Operator Associativity Notes = *= /= %= += \-= <<= >>= &= \[ha]= |= right to left , left to right .TE -.PP +.P The following notes provide further information to the above table: -.PP +.P .PD 0 -.IP [1] 4 +.IP [1] 5 The ++ and \-\- operators at this precedence level are the postfix flavors of the operators. .IP [2] diff --git a/man7/packet.7 b/man7/packet.7 index b2a264c..5d9d0cf 100644 --- a/man7/packet.7 +++ b/man7/packet.7 @@ -4,7 +4,7 @@ .\" .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ .\" -.TH packet 7 2023-07-15 "Linux man-pages 6.05.01" +.TH packet 7 2023-10-31 "Linux man-pages 6.7" .SH NAME packet \- packet interface on device level .SH SYNOPSIS @@ -12,7 +12,7 @@ packet \- packet interface on device level .B #include <sys/socket.h> .B #include <linux/if_packet.h> .B #include <net/ethernet.h> /* the L2 protocols */ -.PP +.P .BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol ); .fi .SH DESCRIPTION @@ -20,7 +20,7 @@ Packet sockets are used to receive or send raw packets at the device driver (OSI Layer 2) level. They allow the user to implement protocol modules in user space on top of the physical layer. -.PP +.P The .I socket_type is either @@ -50,11 +50,11 @@ no packets are received. can optionally be called with a nonzero .I sll_protocol to start receiving packets for the protocols specified. -.PP +.P In order to create a packet socket, a process must have the .B CAP_NET_RAW capability in the user namespace that governs its network namespace. -.PP +.P .B SOCK_RAW packets are passed to and from the device driver without any changes in the packet data. @@ -72,7 +72,7 @@ Some device drivers always add other headers. is similar to but not compatible with the obsolete .B AF_INET/SOCK_PACKET of Linux 2.0. -.PP +.P .B SOCK_DGRAM operates on a slightly higher level. The physical header is removed before the packet is passed to the user. @@ -82,7 +82,7 @@ packet socket get a suitable physical-layer header based on the information in the .I sockaddr_ll destination address before they are queued. -.PP +.P By default, all packets of the specified protocol type are passed to a packet socket. To get packets only from a specific interface use @@ -97,11 +97,11 @@ Fields used for binding are .IR sll_protocol , and .IR sll_ifindex . -.PP +.P The .BR connect (2) operation is not supported on packet sockets. -.PP +.P When the .B MSG_TRUNC flag is passed to @@ -115,7 +115,7 @@ even when it is longer than the buffer. The .I sockaddr_ll structure is a device-independent physical-layer address. -.PP +.P .in +4n .EX struct sockaddr_ll { @@ -129,7 +129,7 @@ struct sockaddr_ll { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I sll_protocol @@ -171,7 +171,7 @@ These types make sense only for receiving. .I sll_halen contain the physical-layer (e.g., IEEE 802.3) address and its length. The exact interpretation depends on the device. -.PP +.P When you send packets, it is enough to specify .IR sll_family , .IR sll_addr , @@ -502,7 +502,7 @@ Argument is a .I struct timeval variable. .\" FIXME Document SIOCGSTAMPNS -.PP +.P In addition, all standard ioctls defined in .BR netdevice (7) and @@ -546,7 +546,7 @@ Interface address contained an invalid interface index. .TP .B EPERM User has insufficient privileges to carry out this operation. -.PP +.P In addition, other errors may be generated by the low-level driver. .SH VERSIONS .B AF_PACKET @@ -561,7 +561,7 @@ via although this covers only a subset of the .B AF_PACKET features. -.PP +.P The .B SOCK_DGRAM packet sockets make no attempt to create or parse the IEEE 802.2 LLC @@ -582,17 +582,17 @@ bind to instead and do the protocol multiplex yourself. The default for sending is the standard Ethernet DIX encapsulation with the protocol filled in. -.PP +.P Packet sockets are not subject to the input or output firewall chains. .SS Compatibility In Linux 2.0, the only way to get a packet socket was with the call: -.PP +.P .in +4n .EX socket(AF_INET, SOCK_PACKET, protocol) .EE .in -.PP +.P This is still supported, but deprecated and strongly discouraged. The main difference between the two methods is that .B SOCK_PACKET @@ -600,7 +600,7 @@ uses the old .I struct sockaddr_pkt to specify an interface, which doesn't provide physical-layer independence. -.PP +.P .in +4n .EX struct sockaddr_pkt { @@ -610,7 +610,7 @@ struct sockaddr_pkt { }; .EE .in -.PP +.P .I spkt_family contains the device type, @@ -620,7 +620,7 @@ is the IEEE 802.3 protocol type as defined in and .I spkt_device is the device name as a null-terminated string, for example, eth0. -.PP +.P This structure is obsolete and should not be used in new code. .SH BUGS .SS LLC header handling @@ -648,12 +648,12 @@ This means the names of network devices longer than 14 bytes will be truncated to fit into .IR spkt_device . All these lengths include the terminating null byte (\[aq]\e0\[aq])). -.PP +.P Issues from this with old code typically show up with very long interface names used by the .B Predictable Network Interface Names feature enabled by default in many modern Linux distributions. -.PP +.P The preferred solution is to rewrite code to avoid .BR SOCK_PACKET . Possible user solutions are to disable @@ -676,14 +676,14 @@ Socket filters are not documented. .BR raw (7), .BR socket (7), .BR ip (8), -.PP +.P RFC\ 894 for the standard IP Ethernet encapsulation. RFC\ 1700 for the IEEE 802.3 IP encapsulation. -.PP +.P The .I <linux/if_ether.h> include file for physical-layer protocols. -.PP +.P The Linux kernel source tree. .I Documentation/networking/filter.rst describes how to apply Berkeley Packet Filters to packet sockets. diff --git a/man7/path_resolution.7 b/man7/path_resolution.7 index 1704603..ac814ed 100644 --- a/man7/path_resolution.7 +++ b/man7/path_resolution.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH path_resolution 7 2023-02-05 "Linux man-pages 6.05.01" +.TH path_resolution 7 2024-02-18 "Linux man-pages 6.7" .SH NAME path_resolution \- how a pathname is resolved to a file .SH DESCRIPTION @@ -20,7 +20,7 @@ system call, or may temporarily use a different root directory by using with the .B RESOLVE_IN_ROOT flag set. -.PP +.P A process may get an entirely private mount namespace in case it\[em]or one of its ancestors\[em]was started by an invocation of the .BR clone (2) @@ -28,7 +28,7 @@ system call that had the .B CLONE_NEWNS flag set. This handles the \[aq]/\[aq] part of the pathname. -.PP +.P If the pathname does not start with the \[aq]/\[aq] character, the starting lookup directory of the resolution process is the current working directory of the process \[em] or in the case of @@ -44,7 +44,7 @@ The current working directory is inherited from the parent, and can be changed by use of the .BR chdir (2) system call. -.PP +.P Pathnames starting with a \[aq]/\[aq] character are called absolute pathnames. Pathnames not starting with a \[aq]/\[aq] are called relative pathnames. .SS Step 2: walk along the path @@ -52,27 +52,27 @@ Set the current lookup directory to the starting lookup directory. Now, for each nonfinal component of the pathname, where a component is a substring delimited by \[aq]/\[aq] characters, this component is looked up in the current lookup directory. -.PP +.P If the process does not have search permission on the current lookup directory, an .B EACCES error is returned ("Permission denied"). -.PP +.P If the component is not found, an .B ENOENT error is returned ("No such file or directory"). -.PP +.P If the component is found, but is neither a directory nor a symbolic link, an .B ENOTDIR error is returned ("Not a directory"). -.PP +.P If the component is found and is a directory, we set the current lookup directory to that directory, and go to the next component. -.PP +.P If the component is found and is a symbolic link, we first resolve this symbolic link (with the current lookup directory @@ -96,7 +96,7 @@ An .B ELOOP error is returned when the maximum is exceeded ("Too many levels of symbolic links"). -.PP +.P .\" .\" presently: max recursion depth during symlink resolution: 5 .\" max total number of symbolic links followed: 40 @@ -114,7 +114,7 @@ the kernel's pathname-resolution code was reworked to eliminate the use of recursion, so that the only limit that remains is the maximum of 40 resolutions for the entire pathname. -.PP +.P The resolution of symbolic links during this stage can be blocked by using .BR openat2 (2), with the @@ -132,15 +132,15 @@ we are just creating it. The details on the treatment of the final entry are described in the manual pages of the specific system calls. -.SS . and .. +.SS "\&. and .." By convention, every directory has the entries "." and "..", which refer to the directory itself and to its parent directory, respectively. -.PP +.P The path resolution process will assume that these entries have their conventional meanings, regardless of whether they are actually present in the physical filesystem. -.PP +.P One cannot walk up past the root: "/.." is the same as "/". .SS Mount points After a @@ -148,11 +148,11 @@ After a command, the pathname "path" refers to the root of the filesystem hierarchy on the device "dev", and no longer to whatever it referred to earlier. -.PP +.P One can walk out of a mounted filesystem: "path/.." refers to the parent directory of "path", outside of the filesystem hierarchy on "dev". -.PP +.P Traversal of mount points can be blocked by using .BR openat2 (2), with the @@ -202,16 +202,16 @@ effective group ID of the calling process, or is one of the supplementary group IDs of the calling process (as set by .BR setgroups (2)). When neither holds, the third group is used. -.PP +.P Of the three bits used, the first bit determines read permission, the second write permission, and the last execute permission in case of ordinary files, or search permission in case of directories. -.PP +.P Linux uses the fsuid instead of the effective user ID in permission checks. Ordinarily the fsuid will equal the effective user ID, but the fsuid can be changed by the system call .BR setfsuid (2). -.PP +.P (Here "fsuid" stands for something like "filesystem user ID". The concept was required for the implementation of a user space NFS server at a time when processes could send a signal to a process @@ -219,7 +219,7 @@ with the same effective user ID. It is obsolete now. Nobody should use .BR setfsuid (2).) -.PP +.P Similarly, Linux uses the fsgid ("filesystem group ID") instead of the effective group ID. See @@ -236,7 +236,7 @@ when accessing files. .\" on some implementations (e.g., Solaris, FreeBSD), .\" access(X_OK) by superuser will report success, regardless .\" of the file's execute permission bits. -- MTK (Oct 05) -.PP +.P On Linux, superuser privileges are divided into capabilities (see .BR capabilities (7)). Two capabilities are relevant for file permissions checks: @@ -244,13 +244,13 @@ Two capabilities are relevant for file permissions checks: and .BR CAP_DAC_READ_SEARCH . (A process has these capabilities if its fsuid is 0.) -.PP +.P The .B CAP_DAC_OVERRIDE capability overrides all permission checking, but grants execute permission only when at least one of the file's three execute permission bits is set. -.PP +.P The .B CAP_DAC_READ_SEARCH capability grants read and search permission diff --git a/man7/persistent-keyring.7 b/man7/persistent-keyring.7 index 472782a..0db4940 100644 --- a/man7/persistent-keyring.7 +++ b/man7/persistent-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH persistent-keyring 7 2023-02-08 "Linux man-pages 6.05.01" +.TH persistent-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME persistent-keyring \- per-user persistent keyring .SH DESCRIPTION @@ -15,7 +15,7 @@ The persistent keyring has a name (description) of the form where .I <UID> is the user ID of the corresponding user. -.PP +.P The persistent keyring may not be accessed directly, even by processes with the appropriate UID. .\" FIXME The meaning of the preceding sentence isn't clear. What is meant? @@ -25,34 +25,34 @@ by virtue of its possessor permits. This linking is done with the .BR keyctl_get_persistent (3) function. -.PP +.P If a persistent keyring does not exist when it is accessed by the .BR keyctl_get_persistent (3) operation, it will be automatically created. -.PP +.P Each time the .BR keyctl_get_persistent (3) operation is performed, the persistent keyring's expiration timer is reset to the value in: -.PP +.P .in +4n .EX /proc/sys/kernel/keys/persistent_keyring_expiry .EE .in -.PP +.P Should the timeout be reached, the persistent keyring will be removed and everything it pins can then be garbage collected. The keyring will then be re-created on a subsequent call to .BR keyctl_get_persistent (3). -.PP +.P The persistent keyring is not directly searched by .BR request_key (2); it is searched only if it is linked into one of the keyrings that is searched by .BR request_key (2). -.PP +.P The persistent keyring is independent of .BR clone (2), .BR fork (2), @@ -72,7 +72,7 @@ The persistent keyring can thus be used to hold authentication tokens for processes that run without user interaction, such as programs started by .BR cron (8). -.PP +.P The persistent keyring is used to store UID-specific objects that themselves have limited lifetimes (e.g., kerberos tokens). If those tokens cease to be used diff --git a/man7/pid_namespaces.7 b/man7/pid_namespaces.7 index b154fb4..90d062b 100644 --- a/man7/pid_namespaces.7 +++ b/man7/pid_namespaces.7 @@ -4,20 +4,20 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH pid_namespaces 7 2023-03-30 "Linux man-pages 6.05.01" +.TH pid_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME pid_namespaces \- overview of Linux PID namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P PID namespaces isolate the process ID number space, meaning that processes in different PID namespaces can have the same PID. PID namespaces allow containers to provide functionality such as suspending/resuming the set of processes in the container and migrating the container to a new host while the processes inside the container maintain the same PIDs. -.PP +.P PIDs in a new PID namespace start at 1, somewhat like a standalone system, and calls to .BR fork (2), @@ -25,7 +25,7 @@ somewhat like a standalone system, and calls to or .BR clone (2) will produce processes with PIDs that are unique within the namespace. -.PP +.P Use of PID namespaces requires a kernel that is configured with the .B CONFIG_PID_NS option. @@ -47,7 +47,7 @@ flag) has the PID 1, and is the "init" process for the namespace (see This process becomes the parent of any child processes that are orphaned because a process that resides in this PID namespace terminated (see below for further details). -.PP +.P If the "init" process of a PID namespace terminates, the kernel terminates all of the processes in the namespace via a .B SIGKILL @@ -74,13 +74,13 @@ terminates, then subsequent calls to .BR fork (2) fail with .BR ENOMEM . -.PP +.P Only signals for which the "init" process has established a signal handler can be sent to the "init" process by other members of the PID namespace. This restriction applies even to privileged processes, and prevents other members of the PID namespace from accidentally killing the "init" process. -.PP +.P Likewise, a process in an ancestor namespace can\[em]subject to the usual permission checks described in .BR kill (2)\[em]send @@ -100,7 +100,7 @@ these signals are forcibly delivered when sent from an ancestor PID namespace. Neither of these signals can be caught by the "init" process, and so will result in the usual actions associated with those signals (respectively, terminating and stopping the process). -.PP +.P Starting with Linux 3.4, the .BR reboot (2) system call causes a signal to be sent to the namespace "init" process. @@ -125,7 +125,7 @@ Since Linux 3.7, .\" commit f2302505775fd13ba93f034206f1e2a587017929 .\" The kernel constant MAX_PID_NS_LEVEL the kernel limits the maximum nesting depth for PID namespaces to 32. -.PP +.P A process is visible to other processes in its PID namespace, and to the processes in each direct ancestor PID namespace going back to the root PID namespace. @@ -140,7 +140,7 @@ set nice values with .BR setpriority (2), etc.) only processes contained in its own PID namespace and in descendants of that namespace. -.PP +.P A process has one process ID in each of the layers of the PID namespace hierarchy in which is visible, and walking back though each direct ancestor namespace @@ -152,7 +152,7 @@ A call to .BR getpid (2) always returns the PID associated with the namespace in which the process was created. -.PP +.P Some processes in a PID namespace may have parents that are outside of the namespace. For example, the parent of the initial process in the namespace @@ -167,7 +167,7 @@ PID namespace from the caller of Calls to .BR getppid (2) for such processes return 0. -.PP +.P While processes may freely descend into child PID namespaces (e.g., using .BR setns (2) @@ -176,7 +176,7 @@ they may not move in the other direction. That is to say, processes may not enter any ancestor namespaces (parent, grandparent, etc.). Changing PID namespaces is a one-way operation. -.PP +.P The .B NS_GET_PARENT .BR ioctl (2) @@ -206,7 +206,7 @@ because doing so would change the caller's idea of its own PID (as reported by .BR getpid ()), which would break many applications and libraries. -.PP +.P To put things another way: a process's PID namespace membership is determined when the process is created and cannot be changed thereafter. @@ -214,7 +214,7 @@ Among other things, this means that the parental relationship between processes mirrors the parental relationship between PID namespaces: the parent of a process is either in the same namespace or resides in the immediate parent PID namespace. -.PP +.P A process may call .BR unshare (2) with the @@ -268,7 +268,7 @@ type in Since this is computed when a signal is enqueued, a signal queue shared by processes in multiple PID namespaces would defeat that. -.PP +.P .\" Note these restrictions were all introduced in .\" 8382fcac1b813ad0a4e68a838fc7ae93fa39eda0 .\" when CLONE_NEWPID|CLONE_VM was disallowed @@ -297,7 +297,7 @@ directories) only processes visible in the PID namespace of the process that performed the mount, even if the .I /proc filesystem is viewed from processes in other namespaces. -.PP +.P After creating a new PID namespace, it is useful for the child to change its root directory and mount a new procfs instance at @@ -316,17 +316,17 @@ or then it isn't necessary to change the root directory: a new procfs instance can be mounted directly over .IR /proc . -.PP +.P From a shell, the command to mount .I /proc is: -.PP +.P .in +4n .EX $ mount \-t proc proc /proc .EE .in -.PP +.P Calling .BR readlink (2) on the path diff --git a/man7/pipe.7 b/man7/pipe.7 index baf05bc..bebb856 100644 --- a/man7/pipe.7 +++ b/man7/pipe.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pipe 7 2023-07-16 "Linux man-pages 6.05.01" +.TH pipe 7 2023-10-31 "Linux man-pages 6.7" .SH NAME pipe \- overview of pipes and FIFOs .SH DESCRIPTION @@ -14,7 +14,7 @@ and a .IR "write end" . Data written to the write end of a pipe can be read from the read end of the pipe. -.PP +.P A pipe is created using .BR pipe (2), which creates a new pipe and returns two file descriptors, @@ -24,7 +24,7 @@ Pipes can be used to create a communication channel between related processes; see .BR pipe (2) for an example. -.PP +.P A FIFO (short for First In First Out) has a name within the filesystem (created using .BR mkfifo (3)), @@ -48,7 +48,7 @@ The only difference between pipes and FIFOs is the manner in which they are created and opened. Once these tasks have been accomplished, I/O on pipes and FIFOs has exactly the same semantics. -.PP +.P If a process attempts to read from an empty pipe, then .BR read (2) will block until data is available. @@ -56,7 +56,7 @@ If a process attempts to write to a full pipe (see below), then .BR write (2) blocks until sufficient data has been read from the pipe to allow the write to complete. -.PP +.P Nonblocking I/O is possible by using the .BR fcntl (2) .B F_SETFL @@ -69,11 +69,11 @@ with If any process has the pipe open for writing, reads fail with .BR EAGAIN ; otherwise\[em]with no potential writers\[em]reads succeed and return empty. -.PP +.P The communication channel provided by a pipe is a .IR "byte stream" : there is no concept of message boundaries. -.PP +.P If all file descriptors referring to the write end of a pipe have been closed, then an attempt to .BR read (2) @@ -100,7 +100,7 @@ calls to close unnecessary duplicate file descriptors; this ensures that end-of-file and .BR SIGPIPE / EPIPE are delivered when appropriate. -.PP +.P It is not possible to apply .BR lseek (2) to a pipe. @@ -116,7 +116,7 @@ Applications should not rely on a particular capacity: an application should be designed so that a reading process consumes data as soon as it is available, so that a writing process does not remain blocked. -.PP +.P Before Linux 2.6.11, the capacity of a pipe was the same as the system page size (e.g., 4096 bytes on i386). Since Linux 2.6.11, the pipe capacity is 16 pages @@ -131,7 +131,7 @@ operations. See .BR fcntl (2) for more information. -.PP +.P The following .BR ioctl (2) operation, which can be applied to a file descriptor @@ -139,13 +139,13 @@ that refers to either end of a pipe, places a count of the number of unread bytes in the pipe in the .I int buffer pointed to by the final argument of the call: -.PP +.P .in +4n .EX ioctl(fd, FIONREAD, &nbytes); .EE .in -.PP +.P The .B FIONREAD operation is not specified in any standard, @@ -227,7 +227,7 @@ and attempts to increase a pipe's capacity will be denied. When the value of this limit is zero, no soft limit is applied. The default value for this file is 16384, which permits creating up to 1024 pipes with the default capacity. -.PP +.P Before Linux 4.9, some bugs affected the handling of the .I pipe\-user\-pages\-soft and @@ -310,7 +310,7 @@ a pipe or FIFO are .B O_NONBLOCK and .BR O_ASYNC . -.PP +.P Setting the .B O_ASYNC flag for the read end of a pipe causes a signal @@ -383,7 +383,7 @@ allocation could be pushed over the limit. 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 +.P 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 diff --git a/man7/pkeys.7 b/man7/pkeys.7 index 4f96f1e..660805c 100644 --- a/man7/pkeys.7 +++ b/man7/pkeys.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pkeys 7 2023-05-03 "Linux man-pages 6.05.01" +.TH pkeys 7 2023-10-31 "Linux man-pages 6.7" .SH NAME pkeys \- overview of Memory Protection Keys .SH DESCRIPTION @@ -14,13 +14,13 @@ when changing permissions. Memory Protection Keys provide a mechanism for changing protections without requiring modification of the page tables on every permission change. -.PP +.P To use pkeys, software must first "tag" a page in the page tables with a pkey. After this tag is in place, an application only has to change the contents of a register in order to remove write access, or all access to a tagged page. -.PP +.P Protection keys work in conjunction with the existing .BR PROT_READ , .BR PROT_WRITE , @@ -32,7 +32,7 @@ and .BR mmap (2), but always act to further restrict these traditional permission mechanisms. -.PP +.P If a process performs an access that violates pkey restrictions, it receives a .B SIGSEGV @@ -40,7 +40,7 @@ signal. See .BR sigaction (2) for details of the information available with that signal. -.PP +.P To use the pkeys feature, the processor must support it, and the kernel must contain support for the feature on a given processor. As of early 2016 only future Intel x86 processors are supported, @@ -50,7 +50,7 @@ are available for actual application use. The default key is assigned to any memory region for which a pkey has not been explicitly assigned via .BR pkey_mprotect (2). -.PP +.P Protection keys have the potential to add a layer of security and reliability to applications. But they have not been primarily designed as @@ -58,7 +58,7 @@ a security feature. For instance, WRPKRU is a completely unprivileged instruction, so pkeys are useless in any case that an attacker controls the PKRU register or can execute arbitrary instructions. -.PP +.P Applications should be very careful to ensure that they do not "leak" protection keys. For instance, before calling @@ -77,7 +77,7 @@ Applications may implement these checks by searching the file for memory regions with the pkey assigned. Further details can be found in .BR proc (5). -.PP +.P Any application wanting to use protection keys needs to be able to function without them. They might be unavailable because the hardware that the @@ -91,7 +91,7 @@ keys should simply call and test whether the call succeeds, instead of attempting to detect support for the feature in any other way. -.PP +.P Although unnecessary, hardware support for protection keys may be enumerated with the .I cpuid @@ -104,7 +104,7 @@ under the "flags" field. The string "pku" in this field indicates hardware support for protection keys and the string "ospke" indicates that the kernel contains and has enabled protection keys support. -.PP +.P Applications using threads and protection keys should be especially careful. Threads inherit the protection key rights of the parent at the time @@ -126,7 +126,7 @@ key rights upon entering a signal handler if the desired rights differ from the defaults. The rights of any interrupted context are restored when the signal handler returns. -.PP +.P This signal behavior is unusual and is due to the fact that the x86 PKRU register (which stores protection key access rights) is managed with the same hardware mechanism (XSAVE) that manages floating-point registers. @@ -138,7 +138,7 @@ The Linux kernel implements the following pkey-related system calls: .BR pkey_alloc (2), and .BR pkey_free (2). -.PP +.P The Linux pkey system calls are available only if the kernel was configured and built with the .B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS @@ -151,7 +151,7 @@ After that, it attempts to allocate a protection key and disallows access to the page by using the WRPKRU instruction. It then tries to access the page, which we now expect to cause a fatal signal to the application. -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man7/posixoptions.7 b/man7/posixoptions.7 index b0dea3d..2b3e3bc 100644 --- a/man7/posixoptions.7 +++ b/man7/posixoptions.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH posixoptions 7 2022-10-30 "Linux man-pages 6.05.01" +.TH posixoptions 7 2023-11-01 "Linux man-pages 6.7" .SH NAME posixoptions \- optional parts of the POSIX standard .SH DESCRIPTION @@ -19,7 +19,7 @@ From shell scripts one can use .BR getconf (1). For more detail, see .BR sysconf (3). -.PP +.P We give the name of the POSIX abbreviation, the option, the name of the .BR sysconf (3) parameter used to inquire about the option, and possibly @@ -28,7 +28,7 @@ Much more precise detail can be found in the POSIX standard itself, versions of which can nowadays be accessed freely on the web. .SS ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO The following advisory functions are present: -.PP +.P .nf .in +4n .IR posix_fadvise () @@ -42,7 +42,7 @@ The header .I <aio.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR aio_cancel () @@ -62,7 +62,7 @@ and .B _POSIX_THREAD_SAFE_FUNCTIONS options. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_barrier_destroy () @@ -80,8 +80,8 @@ The following functions are present: If this option is in effect (as it always is under POSIX.1-2001), then only root may change the owner of a file, and nonroot can set the group of a file only to one of the groups it belongs to. -This affects the following functions -.PP +This affects the following functions: +.P .nf .in +4n .IR chown () @@ -94,7 +94,7 @@ This option implies the .B _POSIX_TIMERS option. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_condattr_getclock () @@ -102,7 +102,7 @@ The following functions are present: .IR clock_nanosleep () .in .fi -.PP +.P If .B CLOCK_REALTIME is changed by the function @@ -136,7 +136,7 @@ Internet Protocol Version 6 is supported. If this option is in effect (as it always is under POSIX.1-2001), then the system implements POSIX-style job control, and the following functions are present: -.PP +.P .nf .in +4n .IR setpgid () @@ -154,7 +154,7 @@ The include file .I <sys/mman.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR mmap () @@ -165,7 +165,7 @@ The following functions are present: .SS ML - _POSIX_MEMLOCK - _SC_MEMLOCK Shared memory can be locked into core. The following functions are present: -.PP +.P .nf .in +4n .IR mlockall () @@ -175,7 +175,7 @@ The following functions are present: .SS MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE More precisely, ranges can be locked into core. The following functions are present: -.PP +.P .nf .in +4n .IR mlock () @@ -191,7 +191,7 @@ The include file .I <mqueue.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR mq_close () @@ -211,7 +211,7 @@ This option implies the .B _POSIX_TIMERS option. The following functions are affected: -.PP +.P .nf .in +4n .IR aio_suspend () @@ -236,7 +236,7 @@ This property may be dependent on the path prefix of the component. .SS PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO This option says that one can specify priorities for asynchronous I/O. This affects the functions -.PP +.P .nf .in +4n .IR aio_read () @@ -248,7 +248,7 @@ The include file .I <sched.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR sched_get_priority_max () @@ -261,11 +261,11 @@ The following functions are present: .IR sched_yield () .in .fi -.PP +.P If also .B _POSIX_SPAWN is in effect, then the following functions are present: -.PP +.P .nf .in +4n .IR posix_spawnattr_getschedparam () @@ -277,7 +277,7 @@ is in effect, then the following functions are present: .SS RS - _POSIX_RAW_SOCKETS Raw sockets are supported. The following functions are affected: -.PP +.P .nf .in +4n .IR getsockopt () @@ -292,9 +292,9 @@ Conversely, under POSIX.1-2001 the .B _POSIX_THREADS option implies this option. -.PP +.P The following functions are present: -.PP +.P .in +4n .nf .IR pthread_rwlock_destroy () @@ -311,7 +311,7 @@ The following functions are present: .SS RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS Realtime signals are supported. The following functions are present: -.PP +.P .nf .in +4n .IR sigqueue () @@ -323,7 +323,7 @@ The following functions are present: If this option is in effect (as it always is under POSIX.1-2001), then POSIX regular expressions are supported and the following functions are present: -.PP +.P .nf .in +4n .IR regcomp () @@ -336,7 +336,7 @@ and the following functions are present: If this option is in effect (as it always is under POSIX.1-2001), then a process has a saved set-user-ID and a saved set-group-ID. The following functions are affected: -.PP +.P .nf .in +4n .IR exec () @@ -354,7 +354,7 @@ The include file .I <semaphore.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR sem_close () @@ -370,7 +370,7 @@ The following functions are present: .fi .SS SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS The following functions are present: -.PP +.P .nf .in +4n .IR mmap () @@ -389,13 +389,13 @@ This option describes support for process creation in a context where it is difficult or impossible to use .IR fork (), for example, because no MMU is present. -.PP +.P If .B _POSIX_SPAWN is in effect, then the include file .I <spawn.h> and the following functions are present: -.PP +.P .nf .in +4n .IR posix_spawn () @@ -417,12 +417,12 @@ and the following functions are present: .IR posix_spawnp () .in .fi -.PP +.P If also .B _POSIX_PRIORITY_SCHEDULING is in effect, then the following functions are present: -.PP +.P .nf .in +4n .IR posix_spawnattr_getschedparam () @@ -438,7 +438,7 @@ and .B _POSIX_THREAD_SAFE_FUNCTIONS options. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_spin_destroy () @@ -456,7 +456,7 @@ This option implies the .B _POSIX_PRIORITY_SCHEDULING option. The following functions are affected: -.PP +.P .nf .in +4n .IR sched_setparam () @@ -465,7 +465,7 @@ The following functions are affected: .fi .SS SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO The following functions are affected: -.PP +.P .nf .in +4n .IR open () @@ -476,7 +476,7 @@ The following functions are affected: .fi .SS TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_attr_getstack () @@ -487,7 +487,7 @@ The following functions are affected: .fi .SS TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_attr_getstack () @@ -502,7 +502,7 @@ This option implies the .B _POSIX_TIMERS option. The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_getcpuclockid () @@ -514,7 +514,7 @@ The following functions are affected: .fi .SS TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_mutexattr_getprotocol () @@ -523,7 +523,7 @@ The following functions are affected: .fi .SS TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_mutex_getprioceiling () @@ -538,7 +538,7 @@ The following functions are affected: If this option is in effect, the different threads inside a process can run with different priorities and/or different schedulers. The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_attr_getinheritsched () @@ -554,7 +554,7 @@ The following functions are affected: .fi .SS TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_barrierattr_getpshared () @@ -569,7 +569,7 @@ The following functions are affected: .fi .SS TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS The following functions are affected: -.PP +.P .nf .in +4n .IR readdir_r () @@ -598,7 +598,7 @@ This option implies the .B _POSIX_THREAD_PRIORITY_SCHEDULING option. The following functions are affected: -.PP +.P .nf .in +4n .IR sched_getparam () @@ -609,7 +609,7 @@ The following functions are affected: .SS THR - _POSIX_THREADS - _SC_THREADS Basic support for POSIX threads is available. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_atfork () @@ -664,7 +664,7 @@ The following functions are present: .fi .SS TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS The following functions are present: -.PP +.P .nf .in +4n .IR mq_timedreceive () @@ -678,7 +678,7 @@ The following functions are present: .fi .SS TMR - _POSIX_TIMERS - _SC_TIMERS The following functions are present: -.PP +.P .nf .in +4n .IR clock_getres () @@ -695,7 +695,7 @@ The following functions are present: .SS TRC - _POSIX_TRACE - _SC_TRACE POSIX tracing is available. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_attr_destroy () @@ -736,7 +736,7 @@ This option implies the .B _POSIX_TRACE option. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_eventset_add () @@ -755,7 +755,7 @@ This option implies the .B _POSIX_TRACE option. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_attr_getinherited () @@ -767,7 +767,7 @@ This option implies the .B _POSIX_TRACE option. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_attr_getlogfullpolicy () @@ -782,7 +782,7 @@ The following functions are present: .fi .SS TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT The following functions are present: -.PP +.P .nf .in +4n .IR posix_mem_offset () @@ -797,7 +797,7 @@ character to indicate that it is disabled. .SH X/OPEN SYSTEM INTERFACE EXTENSIONS .SS XSI - _XOPEN_CRYPT - _SC_XOPEN_CRYPT The following functions are present: -.PP +.P .nf .in +4n .IR crypt () @@ -806,7 +806,7 @@ The following functions are present: .fi .SS XSI - _XOPEN_REALTIME - _SC_XOPEN_REALTIME This option implies the following options: -.PP +.P .PD 0 .TP .BR _POSIX_ASYNCHRONOUS_IO == 200112L @@ -841,7 +841,7 @@ This option implies the following options: .SS ADV - --- - --- The Advanced Realtime option group implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_ADVISORY_INFO @@ -872,7 +872,7 @@ are all defined to 200112L: .SS XSI - _XOPEN_REALTIME_THREADS - _SC_XOPEN_REALTIME_THREADS This option implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_THREAD_PRIO_INHERIT @@ -884,7 +884,7 @@ are all defined to 200112L: .SS ADVANCED REALTIME THREADS - --- - --- This option implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_BARRIERS @@ -909,7 +909,7 @@ are all defined to 200112L: .SS TRACING - --- - --- This option implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_TRACE @@ -922,7 +922,7 @@ are all defined to 200112L: .PD .SS STREAMS - _XOPEN_STREAMS - _SC_XOPEN_STREAMS The following functions are present: -.PP +.P .nf .in +4n .IR fattach () @@ -939,7 +939,7 @@ The following functions are present: Functions included in the legacy option group were previously mandatory, but are now optional in this version. The following functions are present: -.PP +.P .nf .in +4n .IR bcmp () @@ -959,7 +959,7 @@ The following functions are present: .fi .SS XSI - _XOPEN_UNIX - _SC_XOPEN_UNIX The following functions are present: -.PP +.P .nf .in +4n .IR mmap () @@ -967,9 +967,9 @@ The following functions are present: .IR msync () .in .fi -.PP +.P This option implies the following options: -.PP +.P .PD 0 .TP .B _POSIX_FSYNC @@ -988,9 +988,9 @@ This option implies the following options: .TP .B _POSIX_THREADS .PD -.PP +.P This option may imply the following options from the XSI option groups: -.PP +.P .PD 0 .TP .RB "Encryption (" _XOPEN_CRYPT ) diff --git a/man7/process-keyring.7 b/man7/process-keyring.7 index 53557a0..23a7722 100644 --- a/man7/process-keyring.7 +++ b/man7/process-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH process-keyring 7 2022-10-30 "Linux man-pages 6.05.01" +.TH process-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME process-keyring \- per-process shared keyring .SH DESCRIPTION @@ -11,19 +11,19 @@ The process keyring is a keyring used to anchor keys on behalf of a process. It is created only when a process requests it. The process keyring has the name (description) .IR _pid . -.PP +.P A special serial number value, .BR KEY_SPEC_PROCESS_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's process keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@p\fP' can be used instead of a numeric key ID in much the same way, but since .BR keyctl (1) is a program run after forking, this is of no utility. -.PP +.P A thread created using the .BR clone (2) .B CLONE_THREAD @@ -36,7 +36,7 @@ A process's process keyring is cleared on .BR execve (2). The process keyring is destroyed when the last thread that refers to it terminates. -.PP +.P If a process doesn't have a process keyring when it is accessed, then the process keyring will be created if the keyring is to be modified; otherwise, the error diff --git a/man7/pthreads.7 b/man7/pthreads.7 index 2c00798..6d4a5e3 100644 --- a/man7/pthreads.7 +++ b/man7/pthreads.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthreads 7 2023-03-18 "Linux man-pages 6.05.01" +.TH pthreads 7 2023-10-31 "Linux man-pages 6.7" .SH NAME pthreads \- POSIX threads .SH DESCRIPTION @@ -12,7 +12,7 @@ A single process can contain multiple threads, all of which are executing the same program. These threads share the same global memory (data and heap segments), but each thread has its own stack (automatic variables). -.PP +.P POSIX.1 also requires that threads share a range of other attributes (i.e., these attributes are process-wide rather than per-thread): .IP \[bu] 3 @@ -57,7 +57,7 @@ measurements of the consumption of CPU time .RB ( times (2)) and resources .RB ( getrusage (2)) -.PP +.P As well as the stack, POSIX.1 specifies that various other attributes are distinct for each thread, including: .IP \[bu] 3 @@ -77,7 +77,7 @@ alternate signal stack .IP \[bu] real-time scheduling policy and priority .RB ( sched (7)) -.PP +.P The following Linux-specific features are also per-thread: .IP \[bu] 3 capabilities (see @@ -104,12 +104,12 @@ This identifier is returned to the caller of .BR pthread_create (3), and a thread can obtain its own thread identifier using .BR pthread_self (3). -.PP +.P Thread IDs are guaranteed to be unique only within a process. (In all pthreads functions that accept a thread ID as an argument, that ID by definition refers to a thread in the same process as the caller.) -.PP +.P The system may reuse a thread ID after a terminated thread has been joined, or a detached thread has terminated. POSIX says: "If an application attempts to use a thread ID whose @@ -118,11 +118,11 @@ lifetime has ended, the behavior is undefined." A thread-safe function is one that can be safely (i.e., it will deliver the same results regardless of whether it is) called from multiple threads at the same time. -.PP +.P POSIX.1-2001 and POSIX.1-2008 require that all functions specified in the standard shall be thread-safe, except for the following functions: -.PP +.P .in +4n .EX asctime() @@ -224,10 +224,10 @@ wctomb() An async-cancel-safe function is one that can be safely called in an application where asynchronous cancelability is enabled (see .BR pthread_setcancelstate (3)). -.PP +.P Only the following functions are required to be async-cancel-safe by POSIX.1-2001 and POSIX.1-2008: -.PP +.P .in +4n .EX pthread_cancel() @@ -242,10 +242,10 @@ If a thread is cancelable, its cancelability type is deferred, and a cancelation request is pending for the thread, then the thread is canceled when it calls a function that is a cancelation point. -.PP +.P The following functions are required to be cancelation points by POSIX.1-2001 and/or POSIX.1-2008: -.PP +.P .\" FIXME .\" Document the list of all functions that are cancelation points in glibc .in +4n @@ -310,10 +310,10 @@ write() writev() .EE .in -.PP +.P The following functions may be cancelation points according to POSIX.1-2001 and/or POSIX.1-2008: -.PP +.P .in +4n .EX access() @@ -545,13 +545,13 @@ wprintf() wscanf() .EE .in -.PP +.P An implementation may also mark other functions not specified in the standard as cancelation points. In particular, an implementation is likely to mark any nonstandard function that may block as a cancelation point. (This includes most functions that can touch files.) -.PP +.P It should be noted that even if an application is not using asynchronous cancelation, that calling a function from the above list from an asynchronous signal handler may cause the equivalent of @@ -669,7 +669,7 @@ the requirements of the POSIX.1 specification and better performance when creating large numbers of threads. NPTL is available since glibc 2.3.2, and requires features that are present in the Linux 2.6 kernel. -.PP +.P Both of these are so-called 1:1 implementations, meaning that each thread maps to a kernel scheduling entity. Both threading implementations employ the Linux @@ -707,7 +707,7 @@ more information than usual, but which do not share a common process ID.) LinuxThreads threads (including the manager thread) are visible as separate processes using .BR ps (1). -.PP +.P The LinuxThreads implementation deviates from the POSIX.1 specification in a number of ways, including the following: .IP \[bu] 3 @@ -789,13 +789,13 @@ With NPTL, all of the threads in a process are placed in the same thread group; all members of a thread group share the same PID. NPTL does not employ a manager thread. -.PP +.P NPTL makes internal use of the first two real-time signals; these signals cannot be used in applications. See .BR nptl (7) for further details. -.PP +.P NPTL still has at least one nonconformance with POSIX.1: .IP \[bu] 3 Threads do not share a common nice value. @@ -804,7 +804,7 @@ Threads do not share a common nice value. .\" Sep 08: there is a patch by Denys Vlasenko to address this .\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension" .\" Monitor this to see if it makes it into mainline. -.PP +.P Some NPTL nonconformances occur only with older kernels: .IP \[bu] 3 The information returned by @@ -831,7 +831,7 @@ However, a new thread's alternate signal stack settings are copied from the thread that created it, so that the threads initially share an alternate signal stack (fixed in Linux 2.6.16). -.PP +.P Note the following further points about the NPTL implementation: .IP \[bu] 3 If the stack size soft resource limit (see the description of @@ -852,17 +852,17 @@ Since glibc 2.3.2, the .BR getconf (1) command can be used to determine the system's threading implementation, for example: -.PP +.P .in +4n .EX bash$ getconf GNU_LIBPTHREAD_VERSION NPTL 2.3.4 .EE .in -.PP +.P With older glibc versions, a command such as the following should be sufficient to determine the default threading implementation: -.PP +.P .in +4n .EX bash$ $( ldd /bin/ls | grep libc.so | awk \[aq]{print $3}\[aq] ) | \e @@ -885,7 +885,7 @@ of LinuxThreads. (broken) application that depends on some nonconformant behavior in LinuxThreads.) For example: -.PP +.P .in +4n .EX bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e @@ -904,9 +904,9 @@ bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e .BR attributes (7), .BR futex (7), .BR nptl (7), -.BR sigevent (7), +.BR sigevent (3type), .BR signal (7) -.PP +.P Various Pthreads manual pages, for example: .BR pthread_atfork (3), .BR pthread_attr_init (3), @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pty 7 2022-12-04 "Linux man-pages 6.05.01" +.TH pty 7 2023-11-19 "Linux man-pages 6.7" .SH NAME pty \- pseudoterminal interfaces .SH DESCRIPTION @@ -13,7 +13,7 @@ One end of the channel is called the .IR master ; the other end is called the .IR slave . -.PP +.P The slave end of the pseudoterminal provides an interface that behaves exactly like a classical terminal. A process that expects to be connected to a terminal, @@ -29,24 +29,24 @@ that is connected to the slave. Conversely, anything that is written to the slave end of the pseudoterminal can be read by the process that is connected to the master end. -.PP +.P Data flow between master and slave is handled asynchronously, much like data flow with a physical terminal. Data written to the slave will be available at the master promptly, but may not be available immediately. Similarly, there may be a small processing delay between a write to the master, and the effect being visible at the slave. -.PP +.P Historically, two pseudoterminal APIs have evolved: BSD and System V. SUSv1 standardized a pseudoterminal API based on the System V API, and this API should be employed in all new programs that use pseudoterminals. -.PP +.P Linux provides both BSD-style and (standardized) System V-style pseudoterminals. System V-style terminals are commonly called UNIX 98 pseudoterminals on Linux systems. -.PP +.P Since Linux 2.6.4, BSD-style pseudoterminals are considered deprecated: support can be disabled when building the kernel by disabling the .B CONFIG_LEGACY_PTYS @@ -71,7 +71,7 @@ the name returned by .BR ptsname (3) in a call to .BR open (2). -.PP +.P The Linux kernel imposes a limit on the number of available UNIX 98 pseudoterminals. Up to and including Linux 2.6.3, this limit is configured @@ -122,7 +122,10 @@ BSD master devices BSD slave devices .SH NOTES Pseudoterminals are used by applications such as network login services -.RB ( ssh "(1), " rlogin "(1), " telnet (1)), +(\c +.BR ssh (1), +.BR rlogin (1), +.BR telnet (1)), terminal emulators such as .BR xterm (1), .BR script (1), @@ -131,13 +134,13 @@ terminal emulators such as .BR unbuffer (1), and .BR expect (1). -.PP +.P A description of the .B TIOCPKT .BR ioctl (2), which controls packet mode operation, can be found in .BR ioctl_tty (2). -.PP +.P The BSD .BR ioctl (2) operations diff --git a/man7/queue.7 b/man7/queue.7 index 6f2d5ab..469974f 100644 --- a/man7/queue.7 +++ b/man7/queue.7 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" -.TH queue 7 2023-03-30 "Linux man-pages 6.05.01" +.TH queue 7 2023-10-31 "Linux man-pages 6.7" .SH NAME queue \- implementations of linked lists and queues .SH DESCRIPTION @@ -28,7 +28,7 @@ doubly linked tail queues .TP CIRCLEQ doubly linked circular queues -.PP +.P All structures support the following functionality: .IP \[bu] 3 Insertion of a new entry at the head of the list. @@ -38,9 +38,9 @@ Insertion of a new entry after any element in the list. O(1) removal of an entry from the head of the list. .IP \[bu] Forward traversal through the list. -.\".IP * +.\".IP \[bu] .\" Swapping the contents of two lists. -.PP +.P Code size and execution time depend on the complexity of the data structure being used, so programmers should take care to choose the appropriate one. @@ -61,13 +61,13 @@ Entries can be added at the end of a list. O(n) removal of any entry in the list. .IP \[bu] They may be concatenated. -.PP +.P However: .IP \[bu] 3 All list insertions must specify the head of the list. .IP \[bu] Each head entry requires two pointers rather than one. -.PP +.P Singly linked tail queues are ideal for applications with large datasets and few or no removals, or for implementing a FIFO queue. @@ -78,7 +78,7 @@ additionally allow: Insertion of a new entry before any element in the list. .IP \[bu] O(1) removal of any entry in the list. -.PP +.P However: .IP \[bu] 3 Each element requires two pointers rather than one. @@ -87,7 +87,7 @@ Linked lists are the simplest of the doubly linked data structures. They add the following functionality over the above: .IP \[bu] 3 They may be traversed backwards. -.PP +.P However: .IP \[bu] 3 To traverse backwards, an entry to begin the traversal and the list in @@ -100,7 +100,7 @@ Entries can be added at the end of a list. They may be traversed backwards, from tail to head. .IP \[bu] They may be concatenated. -.PP +.P However: .IP \[bu] 3 All list insertions and removals must specify the head of the list. @@ -110,7 +110,7 @@ Each head entry requires two pointers rather than one. Circular queues add the following functionality over the above: .IP \[bu] 3 The first and last entries are connected. -.PP +.P However: .IP \[bu] 3 The termination condition for traversal is more complex. diff --git a/man7/random.7 b/man7/random.7 index bca67ce..5ba6d33 100644 --- a/man7/random.7 +++ b/man7/random.7 @@ -9,7 +9,7 @@ .\" The following web page is quite informative: .\" http://www.2uo.de/myths-about-urandom/ .\" -.TH random 7 2023-02-10 "Linux man-pages 6.05.01" +.TH random 7 2023-10-31 "Linux man-pages 6.7" .SH NAME random \- overview of interfaces for obtaining randomness .SH DESCRIPTION @@ -17,7 +17,7 @@ The kernel random-number generator relies on entropy gathered from device drivers and other sources of environmental noise to seed a cryptographically secure pseudorandom number generator (CSPRNG). It is designed for security, rather than speed. -.PP +.P The following interfaces provide access to output from the kernel CSPRNG: .IP \[bu] 3 The @@ -77,7 +77,7 @@ flag. The cryptographic algorithms used for the .I urandom source are quite conservative, and so should be sufficient for all purposes. -.PP +.P The disadvantage of .B GRND_RANDOM and reads from @@ -194,7 +194,7 @@ or Diffie-Hellman private key has an effective key size of 128 bits (it requires about 2\[ha]128 operations to break) so a key generator needs only 128 bits (16 bytes) of seed material from .IR /dev/random . -.PP +.P While some safety margin above that minimum is reasonable, as a guard against flaws in the CSPRNG algorithm, no cryptographic primitive available today can hope to promise more than 256 bits of security, @@ -5,7 +5,7 @@ .\" .\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ .\" -.TH raw 7 2023-07-15 "Linux man-pages 6.05.01" +.TH raw 7 2023-10-31 "Linux man-pages 6.7" .SH NAME raw \- Linux IPv4 raw sockets .SH SYNOPSIS @@ -18,17 +18,17 @@ raw \- Linux IPv4 raw sockets Raw sockets allow new IPv4 protocols to be implemented in user space. A raw socket receives or sends the raw datagram not including link level headers. -.PP +.P The IPv4 layer generates an IP header when sending a packet unless the .B IP_HDRINCL socket option is enabled on the socket. When it is enabled, the packet must contain an IP header. For receiving, the IP header is always included in the packet. -.PP +.P In order to create a raw socket, a process must have the .B CAP_NET_RAW capability in the user namespace that governs its network namespace. -.PP +.P All packets or errors matching the .I protocol number specified @@ -39,7 +39,7 @@ see the IANA list of assigned protocol numbers at .UE and .BR getprotobyname (3). -.PP +.P A protocol of .B IPPROTO_RAW implies enabled @@ -61,7 +61,7 @@ Packet ID:Filled in when zero Total Length:Always filled in .TE .RE -.PP +.P If .B IP_HDRINCL is specified and the IP header has a nonzero destination address, then @@ -71,7 +71,7 @@ When is specified, the destination address should refer to a local interface, otherwise a routing table lookup is done anyway but gatewayed routes are ignored. -.PP +.P If .B IP_HDRINCL isn't set, then IP header options can be set on raw sockets with @@ -79,12 +79,12 @@ isn't set, then IP header options can be set on raw sockets with see .BR ip (7) for more information. -.PP +.P Starting with Linux 2.2, all IP header fields and options can be set using IP socket options. This means raw sockets are usually needed only for new protocols or protocols with no user interface (like ICMP). -.PP +.P When a packet is received, it is passed to any raw sockets which have been bound to its protocol before it is passed to other protocol handlers (e.g., kernel protocol modules). @@ -123,7 +123,7 @@ protocol. The value has a bit set for each ICMP message type which should be filtered out. The default is to filter no ICMP messages. -.PP +.P In addition, all .BR ip (7) .B IPPROTO_IP @@ -178,7 +178,7 @@ and .B ICMP_FILTER are new in Linux 2.2. They are Linux extensions and should not be used in portable programs. -.PP +.P Linux 2.0 enabled some bug-to-bug compatibility with BSD in the raw socket code when the .B SO_BSDCOMPAT @@ -202,7 +202,7 @@ When turned off, raw sockets will fragment outgoing packets that exceed the interface MTU. However, disabling it is not recommended for performance and reliability reasons. -.PP +.P A raw socket can be bound to a specific local address using the .BR bind (2) call. @@ -211,7 +211,7 @@ In addition, a raw socket can be bound to a specific network device using .BR SO_BINDTODEVICE ; see .BR socket (7). -.PP +.P An .B IPPROTO_RAW socket is send only. @@ -222,28 +222,28 @@ socket with the protocol. Note that packet sockets don't reassemble IP fragments, unlike raw sockets. -.PP +.P If you want to receive all ICMP packets for a datagram socket, it is often better to use .B IP_RECVERR on that particular socket; see .BR ip (7). -.PP +.P Raw sockets may tap all IP protocols in Linux, even protocols like ICMP or TCP which have a protocol module in the kernel. In this case, the packets are passed to both the kernel module and the raw socket(s). This should not be relied upon in portable programs, many other BSD socket implementation have limitations here. -.PP +.P Linux never changes headers passed from the user (except for filling in some zeroed fields as described for .BR IP_HDRINCL ). This differs from many other implementations of raw sockets. -.PP +.P Raw sockets are generally rather unportable and should be avoided in programs intended to be portable. -.PP +.P Sending on raw sockets should take the IP protocol from .IR sin_port ; this ability was lost in Linux 2.2. @@ -251,12 +251,12 @@ The workaround is to use .BR IP_HDRINCL . .SH BUGS Transparent proxy extensions are not described. -.PP +.P When the .B IP_HDRINCL option is set, datagrams will not be fragmented and are limited to the interface MTU. -.PP +.P Setting the IP protocol for sending in .I sin_port got lost in Linux 2.2. @@ -272,7 +272,7 @@ call is always used. .BR capabilities (7), .BR ip (7), .BR socket (7) -.PP +.P .B RFC\ 1191 for path MTU discovery. .B RFC\ 791 diff --git a/man7/regex.7 b/man7/regex.7 index 7a5b2d8..ad63573 100644 --- a/man7/regex.7 +++ b/man7/regex.7 @@ -35,14 +35,14 @@ .\" .ie t .ds dg \(dg .el .ds dg (!) -.TH regex 7 2023-03-08 "Linux man-pages 6.05.01" +.TH regex 7 2023-11-01 "Linux man-pages 6.7" .SH NAME regex \- POSIX.2 regular expressions .SH DESCRIPTION Regular expressions ("RE"s), as defined in POSIX.2, come in two forms: modern REs (roughly those of -.IR egrep ; +.BR egrep (1); POSIX.2 calls these "extended" REs) and obsolete REs (roughly those of .BR ed (1); @@ -52,15 +52,15 @@ they will be discussed at the end. POSIX.2 leaves some aspects of RE syntax and semantics open; "\*(dg" marks decisions on these aspects that may not be fully portable to other POSIX.2 implementations. -.PP +.P A (modern) RE is one\*(dg or more nonempty\*(dg \fIbranches\fR, separated by \[aq]|\[aq]. It matches anything that matches one of the branches. -.PP +.P A branch is one\*(dg or more \fIpieces\fR, concatenated. It matches a match for the first, followed by a match for the second, and so on. -.PP +.P A piece is an \fIatom\fR possibly followed by a single\*(dg \[aq]*\[aq], \[aq]+\[aq], \[aq]?\[aq], or \fIbound\fR. An atom followed by \[aq]*\[aq] @@ -69,7 +69,7 @@ An atom followed by \[aq]+\[aq] matches a sequence of 1 or more matches of the atom. An atom followed by \[aq]?\[aq] matches a sequence of 0 or 1 matches of the atom. -.PP +.P A \fIbound\fR is \[aq]{\[aq] followed by an unsigned decimal integer, possibly followed by \[aq],\[aq] possibly followed by another unsigned decimal integer, @@ -87,7 +87,7 @@ a sequence of \fIi\fR or more matches of the atom. An atom followed by a bound containing two integers \fIi\fR and \fIj\fR matches a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom. -.PP +.P An atom is a regular expression enclosed in "\fI()\fP" (matching a match for the regular expression), an empty set of "\fI()\fP" (matching the null string)\*(dg, @@ -105,7 +105,7 @@ A \[aq]{\[aq] followed by a character other than a digit is an ordinary character, not the beginning of a bound\*(dg. It is illegal to end an RE with \[aq]\e\[aq]. -.PP +.P A \fIbracket expression\fR is a list of characters enclosed in "\fI[]\fP". It normally matches any single character from the list (but see below). If the list begins with \[aq]\[ha]\[aq], @@ -119,7 +119,7 @@ It is illegal\*(dg for two ranges to share an endpoint, for example, "\fIa\-c\-e\fP". Ranges are very collating-sequence-dependent, and portable programs should avoid relying on them. -.PP +.P To include a literal \[aq]]\[aq] in the list, make it the first character (following a possible \[aq]\[ha]\[aq]). To include a literal \[aq]\-\[aq], make it the first or last character, @@ -130,7 +130,7 @@ to make it a collating element (see below). With the exception of these and some combinations using \[aq][\[aq] (see next paragraphs), all other special characters, including \[aq]\e\[aq], lose their special significance within a bracket expression. -.PP +.P Within a bracket expression, a collating element (a character, a multicharacter sequence that collates as if it were a single character, or a collating-sequence name for either) @@ -142,7 +142,7 @@ can thus match more than one character, for example, if the collating sequence includes a "ch" collating element, then the RE "\fI[[.ch.]]*c\fP" matches the first five characters of "chchcc". -.PP +.P Within a bracket expression, a collating element enclosed in "\fI[=\fP" and "\fI=]\fP" is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. @@ -154,13 +154,13 @@ then "\fI[[=o=]]\fP", "\fI[[=\(^o=]]\fP", and "\fI[o\(^o]\fP" are all synonymous. An equivalence class may not\*(dg be an endpoint of a range. -.PP +.P Within a bracket expression, the name of a \fIcharacter class\fR enclosed in "\fI[:\fP" and "\fI:]\fP" stands for the list of all characters belonging to that class. Standard character class names are: -.PP +.P .RS .TS l l l. @@ -170,14 +170,14 @@ blank lower upper cntrl print xdigit .TE .RE -.PP +.P These stand for the character classes defined in .BR wctype (3). A locale may provide others. A character class may not be used as an endpoint of a range. .\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 .\" The following does not seem to apply in the glibc implementation -.\" .PP +.\" .P .\" There are two special cases\*(dg of bracket expressions: .\" the bracket expressions "\fI[[:<:]]\fP" and "\fI[[:>:]]\fP" match .\" the null string at the beginning and end of a word respectively. @@ -194,7 +194,7 @@ A character class may not be used as an endpoint of a range. .\" compatible with but not specified by POSIX.2, .\" and should be used with .\" caution in software intended to be portable to other systems. -.PP +.P In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. @@ -206,7 +206,7 @@ with subexpressions starting earlier in the RE taking priority over ones starting later. Note that higher-level subexpressions thus take priority over their lower-level component subexpressions. -.PP +.P Match lengths are measured in characters, not collating elements. A null string is considered longer than no match at all. For example, @@ -218,7 +218,7 @@ matches all three characters, and when "\fI(a*)*\fP" is matched against "bc" both the whole RE and the parenthesized subexpression match the null string. -.PP +.P If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. @@ -229,13 +229,13 @@ for example, \[aq]x\[aq] becomes "\fI[xX]\fP". When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, so that, for example, "\fI[x]\fP" becomes "\fI[xX]\fP" and "\fI[\[ha]x]\fP" becomes "\fI[\[ha]xX]\fP". -.PP +.P No particular limit is imposed on the length of REs\*(dg. Programs intended to be portable should not employ REs longer than 256 bytes, as an implementation can refuse to accept such REs and remain POSIX-compliant. -.PP +.P Obsolete ("basic") regular expressions differ in several respects. \[aq]|\[aq], \[aq]+\[aq], and \[aq]?\[aq] are ordinary characters and there is no equivalent @@ -251,7 +251,7 @@ RE or\*(dg the end of a parenthesized subexpression, and \[aq]*\[aq] is an ordinary character if it appears at the beginning of the RE or the beginning of a parenthesized subexpression (after a possible leading \[aq]\[ha]\[aq]). -.PP +.P Finally, there is one new type of atom, a \fIback reference\fR: \[aq]\e\[aq] followed by a nonzero decimal digit \fId\fR matches the same sequence of characters @@ -261,26 +261,26 @@ left to right), so that, for example, "\fI\e([bc]\e)\e1\fP" matches "bb" or "cc" but not "bc". .SH BUGS Having two kinds of REs is a botch. -.PP +.P The current POSIX.2 spec says that \[aq])\[aq] is an ordinary character in the absence of an unmatched \[aq](\[aq]; this was an unintentional result of a wording error, and change is likely. Avoid relying on it. -.PP +.P Back references are a dreadful botch, posing major problems for efficient implementations. They are also somewhat vaguely defined (does "\fIa\e(\e(b\e)*\e2\e)*d\fP" match "abbbd"?). Avoid using them. -.PP +.P POSIX.2's specification of case-independent matching is vague. The "one case implies all cases" definition given above is current consensus among implementors as to the right interpretation. .\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 .\" The following does not seem to apply in the glibc implementation -.\" .PP +.\" .P .\" The syntax for word boundaries is incredibly ugly. .SH AUTHOR .\" Sigh... The page license means we must have the author's name @@ -289,5 +289,5 @@ This page was taken from Henry Spencer's regex package. .SH SEE ALSO .BR grep (1), .BR regex (3) -.PP +.P POSIX.2, section 2.8 (Regular Expression Notation). diff --git a/man7/rtld-audit.7 b/man7/rtld-audit.7 index df04a8c..67678b4 100644 --- a/man7/rtld-audit.7 +++ b/man7/rtld-audit.7 @@ -5,7 +5,7 @@ .\" .\" 2009-01-12, mtk, Created .\" -.TH RTLD-AUDIT 7 2023-05-03 "Linux man-pages 6.05.01" +.TH RTLD-AUDIT 7 2023-10-31 "Linux man-pages 6.7" .SH NAME rtld\-audit \- auditing API for the dynamic linker .SH SYNOPSIS @@ -21,14 +21,14 @@ This API is very similar to the auditing interface provided by the Solaris run-time linker. The necessary constants and prototypes are defined by including .IR <link.h> . -.PP +.P To use this interface, the programmer creates a shared library that implements a standard set of function names. Not all of the functions need to be implemented: in most cases, if the programmer is not interested in a particular class of auditing event, then no implementation needs to be provided for the corresponding auditing function. -.PP +.P To employ the auditing interface, the environment variable .B LD_AUDIT must be defined to contain a colon-separated list of shared libraries, @@ -41,7 +41,7 @@ in the order that the libraries are listed. .nf .BI "unsigned int la_version(unsigned int " version ); .fi -.PP +.P This is the only function that .I must be defined by an auditing library: @@ -50,7 +50,7 @@ the auditing library. When invoking this function, the dynamic linker passes, in .IR version , the highest version of the auditing interface that the linker supports. -.PP +.P A typical implementation of this function simply returns the constant .BR LAV_CURRENT , which indicates the version of @@ -61,7 +61,7 @@ not support this version of the audit interface, it will refuse to activate this audit module. If the function returns zero, the dynamic linker also does not activate this audit module. -.PP +.P In order to enable backwards compatibility with older dynamic linkers, an audit module can examine the .I version @@ -83,7 +83,7 @@ definitions used to build the audit module. .BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie , .BI " unsigned int " flag ); .fi -.PP +.P The dynamic linker invokes this function to inform the auditing library that it is about to search for a shared object. The @@ -130,7 +130,7 @@ was found via a search of one of the default directories. .B LA_SER_SECURE .I name is specific to a secure object (unused on Linux). -.PP +.P As its function result, .BR la_objsearch () returns the pathname that the dynamic linker should use @@ -144,7 +144,7 @@ should be returned. .nf .BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag ); .fi -.PP +.P The dynamic linker calls this function to inform the auditing library that link-map activity is occurring. .I cookie @@ -167,7 +167,7 @@ Link-map activity has been completed: the map is once again consistent. .BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid , .BI " uintptr_t *" cookie ); .fi -.PP +.P The dynamic linker calls this function when a new shared object is loaded. The .I map @@ -182,7 +182,7 @@ Link map is part of the initial namespace. .B LM_ID_NEWLM Link map is part of a new namespace requested via .BR dlmopen (3). -.PP +.P .I cookie is a pointer to an identifier for this object. The identifier is provided to later calls to functions @@ -190,7 +190,7 @@ in the auditing library in order to identify this object. This identifier is initialized to point to object's link map, but the audit library can change the identifier to some other value that it may prefer to use to identify the object. -.PP +.P As its return value, .BR la_objopen () returns a bit mask created by ORing zero or more of the @@ -203,7 +203,7 @@ Audit symbol bindings to this object. .TP .B LA_FLG_BINDFROM Audit symbol bindings from this object. -.PP +.P A return value of 0 from .BR la_objopen () indicates that no symbol bindings should be audited for this object. @@ -212,7 +212,7 @@ indicates that no symbol bindings should be audited for this object. .nf .BI "unsigned int la_objclose(uintptr_t *" cookie ); .fi -.PP +.P The dynamic linker invokes this function after any finalization code for the object has been executed, before the object is unloaded. @@ -220,7 +220,7 @@ The .I cookie argument is the identifier obtained from a previous invocation of .BR la_objopen (). -.PP +.P In the current implementation, the value returned by .BR la_objclose () is ignored. @@ -229,7 +229,7 @@ is ignored. .nf .BI "void la_preinit(uintptr_t *" cookie ); .fi -.PP +.P The dynamic linker invokes this function after all shared objects have been loaded, before control is passed to the application (i.e., before calling @@ -248,7 +248,7 @@ may still later dynamically load objects using .BI " uintptr_t *" refcook ", uintptr_t *" defcook , .BI " unsigned int *" flags ", const char *" symname ); .fi -.PP +.P The dynamic linker invokes one of these functions when a symbol binding occurs between two shared objects that have been marked for auditing notification by @@ -259,7 +259,7 @@ function is employed on 32-bit platforms; the .BR la_symbind64 () function is employed on 64-bit platforms. -.PP +.P The .I sym argument is a pointer to a structure @@ -269,12 +269,12 @@ The structure definition is shown in Among the fields of this structure, .I st_value indicates the address to which the symbol is bound. -.PP +.P The .I ndx argument gives the index of the symbol in the symbol table of the bound shared object. -.PP +.P The .I refcook argument identifies the shared object that is making the symbol reference; @@ -289,11 +289,11 @@ this is the same identifier that is provided to the .BR la_objopen () function that returned .BR LA_FLG_BINDTO . -.PP +.P The .I symname argument points a string containing the name of the symbol. -.PP +.P The .I flags argument is a bit mask that both provides information about the symbol @@ -310,7 +310,7 @@ The binding resulted from a call to A previous .BR la_symbind* () call returned an alternate value for this symbol. -.PP +.P By default, if the auditing library implements .BR la_pltenter () and @@ -334,7 +334,7 @@ for this symbol. Don't call .BR la_pltexit () for this symbol. -.PP +.P The return value of .BR la_symbind32 () and @@ -351,17 +351,17 @@ depend on the hardware platform. (The appropriate definition is supplied by .IR <link.h> .) Here is the definition for x86-32: -.PP +.P .nf .BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx , .BI " uintptr_t *" refcook ", uintptr_t *" defcook , .BI " La_i86_regs *" regs ", unsigned int *" flags , .BI " const char *" symname ", long *" framesizep ); .fi -.PP +.P This function is invoked just before a PLT entry is called, between two shared objects that have been marked for binding notification. -.PP +.P The .IR sym , .IR ndx , @@ -371,20 +371,20 @@ and .I symname are as for .BR la_symbind* (). -.PP +.P The .I regs argument points to a structure (defined in .IR <link.h> ) containing the values of registers to be used for the call to this PLT entry. -.PP +.P The .I flags argument points to a bit mask that conveys information about, and can be used to modify subsequent auditing of, this PLT entry, as for .BR la_symbind* (). -.PP +.P .\" FIXME . Is the following correct? The .I framesizep @@ -400,7 +400,7 @@ The .BR la_pltexit () function is called only if this buffer is explicitly set to a suitable value. -.PP +.P The return value of .BR la_pltenter () is as for @@ -411,20 +411,20 @@ depend on the hardware platform. (The appropriate definition is supplied by .IR <link.h> .) Here is the definition for x86-32: -.PP +.P .nf .BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx , .BI " uintptr_t *" refcook ", uintptr_t *" defcook , .BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs , .BI " const char *" symname ); .fi -.PP +.P This function is called when a PLT entry, made between two shared objects that have been marked for binding notification, returns. The function is called just before control returns to the caller of the PLT entry. -.PP +.P The .IR sym , .IR ndx , @@ -434,7 +434,7 @@ and .I symname are as for .BR la_symbind* (). -.PP +.P The .I inregs argument points to a structure (defined in @@ -447,7 +447,7 @@ argument points to a structure (defined in containing return values for the call to this PLT entry. These values can be modified by the caller, and the changes will be visible to the caller of the PLT entry. -.PP +.P In the current GNU implementation, the return value of .BR la_pltexit () is ignored. diff --git a/man7/rtnetlink.7 b/man7/rtnetlink.7 index 3b6465f..1ab355f 100644 --- a/man7/rtnetlink.7 +++ b/man7/rtnetlink.7 @@ -7,7 +7,7 @@ .\" help from Matthew Wilcox. .\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $ .\" -.TH rtnetlink 7 2023-07-15 "Linux man-pages 6.05.01" +.TH rtnetlink 7 2023-10-31 "Linux man-pages 6.7" .SH NAME rtnetlink \- Linux routing socket .SH SYNOPSIS @@ -16,7 +16,7 @@ rtnetlink \- Linux routing socket .B #include <linux/netlink.h> .B #include <linux/rtnetlink.h> .B #include <sys/socket.h> -.PP +.P .BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);" .fi .SH DESCRIPTION @@ -35,7 +35,7 @@ for more information. .\" FIXME . ? all these macros could be moved to rtnetlink(3) .SS Routing attributes Some rtnetlink messages have optional attributes after the initial header: -.PP +.P .in +4n .EX struct rtattr { @@ -45,7 +45,7 @@ struct rtattr { }; .EE .in -.PP +.P These attributes should be manipulated using only the RTA_* macros or libnetlink, see .BR rtnetlink (3). @@ -53,7 +53,11 @@ or libnetlink, see Rtnetlink consists of these message types (in addition to standard netlink messages): .TP -.BR RTM_NEWLINK ", " RTM_DELLINK ", " RTM_GETLINK +.B RTM_NEWLINK +.TQ +.B RTM_DELLINK +.TQ +.B RTM_GETLINK Create, remove, or get information about a specific network interface. These messages contain an .I ifinfomsg @@ -112,7 +116,11 @@ is .RI ( "struct net_device_stats" in Linux 2.4 and earlier). .TP -.BR RTM_NEWADDR ", " RTM_DELADDR ", " RTM_GETADDR +.B RTM_NEWADDR +.TQ +.B RTM_DELADDR +.TQ +.B RTM_GETADDR Add, remove, or receive information about an IP address associated with an interface. In Linux 2.2, an interface can carry multiple IP addresses, @@ -170,7 +178,11 @@ IFA_CACHEINFO:struct ifa_cacheinfo:Address information .TE .\" FIXME Document struct ifa_cacheinfo .TP -.BR RTM_NEWROUTE ", " RTM_DELROUTE ", " RTM_GETROUTE +.B RTM_NEWROUTE +.TQ +.B RTM_DELROUTE +.TQ +.B RTM_GETROUTE Create, remove, or receive information about a network route. These messages contain an .I rtmsg @@ -242,7 +254,7 @@ RTPROT_KERNEL:by the kernel RTPROT_BOOT:during boot RTPROT_STATIC:by the administrator .TE -.sp 1 +.IP Values larger than .B RTPROT_STATIC are not interpreted by the kernel, they are just for user information. @@ -265,7 +277,7 @@ RT_SCOPE_LINK:route on this link RT_SCOPE_HOST:route on the local host RT_SCOPE_NOWHERE:destination doesn't exist .TE -.sp 1 +.IP The values between .B RT_SCOPE_UNIVERSE and @@ -284,7 +296,7 @@ T} RTM_F_CLONED:route is cloned from another route RTM_F_EQUALIZE:a multipath equalizer (not yet implemented) .TE -.sp 1 +.IP .I rtm_table specifies the routing table .TS @@ -295,7 +307,7 @@ RT_TABLE_DEFAULT:the default table RT_TABLE_MAIN:the main table RT_TABLE_LOCAL:the local table .TE -.sp 1 +.IP The user may assign arbitrary values between .B RT_TABLE_UNSPEC and @@ -423,7 +435,11 @@ defined in .IP .B Fill these values in! .TP -.BR RTM_NEWNEIGH ", " RTM_DELNEIGH ", " RTM_GETNEIGH +.B RTM_NEWNEIGH +.TQ +.B RTM_DELNEIGH +.TQ +.B RTM_GETNEIGH Add, remove, or receive information about a neighbor table entry (e.g., an ARP entry). The message contains an @@ -461,7 +477,7 @@ NUD_FAILED:an invalid cache entry NUD_NOARP:a device with no destination cache NUD_PERMANENT:a static entry .TE -.sp 1 +.IP Valid .I ndm_flags are: @@ -471,7 +487,7 @@ lb l. NTF_PROXY:a proxy arp entry NTF_ROUTER:an IPv6 router .TE -.sp 1 +.IP .\" FIXME . .\" document the members of the struct better The @@ -487,7 +503,7 @@ NDA_DST:a neighbor cache n/w layer destination address NDA_LLADDR:a neighbor cache link layer address NDA_CACHEINFO:cache statistics .TE -.sp 1 +.IP If the .I rta_type field is @@ -496,12 +512,20 @@ then a .I struct nda_cacheinfo header follows. .TP -.BR RTM_NEWRULE ", " RTM_DELRULE ", " RTM_GETRULE +.B RTM_NEWRULE +.TQ +.B RTM_DELRULE +.TQ +.B RTM_GETRULE Add, delete, or retrieve a routing rule. Carries a .I struct rtmsg .TP -.BR RTM_NEWQDISC ", " RTM_DELQDISC ", " RTM_GETQDISC +.B RTM_NEWQDISC +.TQ +.B RTM_DELQDISC +.TQ +.B RTM_GETQDISC Add, remove, or get a queueing discipline. The message contains a .I struct tcmsg @@ -531,17 +555,25 @@ TCA_STATS:struct tc_stats:Qdisc statistics TCA_XSTATS:qdisc-specific:Module-specific statistics TCA_RATE:struct tc_estimator:Rate limit .TE -.sp 1 +.IP In addition, various other qdisc-module-specific attributes are allowed. For more information see the appropriate include files. .TP -.BR RTM_NEWTCLASS ", " RTM_DELTCLASS ", " RTM_GETTCLASS +.B RTM_NEWTCLASS +.TQ +.B RTM_DELTCLASS +.TQ +.B RTM_GETTCLASS Add, remove, or get a traffic class. These messages contain a .I struct tcmsg as described above. .TP -.BR RTM_NEWTFILTER ", " RTM_DELTFILTER ", " RTM_GETTFILTER +.B RTM_NEWTFILTER +.TQ +.B RTM_DELTFILTER +.TQ +.B RTM_GETTFILTER Add, remove, or receive information about a traffic filter. These messages contain a .I struct tcmsg diff --git a/man7/sched.7 b/man7/sched.7 index 7854505..7e1212f 100644 --- a/man7/sched.7 +++ b/man7/sched.7 @@ -10,7 +10,7 @@ .\" .\" Worth looking at: http://rt.wiki.kernel.org/index.php .\" -.TH sched 7 2023-02-10 "Linux man-pages 6.05.01" +.TH sched 7 2024-02-18 "Linux man-pages 6.7" .SH NAME sched \- overview of CPU scheduling .SH DESCRIPTION @@ -91,12 +91,12 @@ scheduling priority, .IR sched_priority . The scheduler makes its decisions based on knowledge of the scheduling policy and static priority of all threads on the system. -.PP +.P For threads scheduled under one of the normal scheduling policies (\fBSCHED_OTHER\fP, \fBSCHED_IDLE\fP, \fBSCHED_BATCH\fP), \fIsched_priority\fP is not used in scheduling decisions (it must be specified as 0). -.PP +.P Processes scheduled under one of the real-time policies (\fBSCHED_FIFO\fP, \fBSCHED_RR\fP) have a \fIsched_priority\fP value in the range 1 (low) to 99 (high). @@ -110,17 +110,17 @@ Portable programs should use and .BR sched_get_priority_max (2) to find the range of priorities supported for a particular policy. -.PP +.P Conceptually, the scheduler maintains a list of runnable threads for each possible \fIsched_priority\fP value. In order to determine which thread runs next, the scheduler looks for the nonempty list with the highest static priority and selects the thread at the head of this list. -.PP +.P A thread's scheduling policy determines where it will be inserted into the list of threads with equal static priority and how it will move inside this list. -.PP +.P All scheduling is preemptive: if a thread with a higher static priority becomes ready to run, the currently running thread will be preempted and @@ -158,7 +158,7 @@ changes the priority of the running or runnable thread identified by .I pid the effect on the thread's position in the list depends on -the direction of the change to threads priority: +the direction of the change to the thread's priority: .RS .IP (a) 5 If the thread's priority is raised, @@ -184,11 +184,11 @@ the list for its priority. A thread calling .BR sched_yield (2) will be put at the end of the list. -.PP +.P No other events will move a thread scheduled under the \fBSCHED_FIFO\fP policy in the wait list of runnable threads with equal static priority. -.PP +.P A \fBSCHED_FIFO\fP thread runs until either it is blocked by an I/O request, it is preempted by a higher priority thread, or it calls @@ -224,7 +224,7 @@ one must use the Linux-specific and .BR sched_getattr (2) system calls. -.PP +.P A sporadic task is one that has a sequence of jobs, where each job is activated at most once per period. Each job also has a @@ -242,9 +242,9 @@ is the time at which a task starts its execution. The .I absolute deadline is thus obtained by adding the relative deadline to the arrival time. -.PP +.P The following diagram clarifies these terms: -.PP +.P .in +4n .EX arrival/wakeup absolute deadline @@ -257,7 +257,7 @@ arrival/wakeup absolute deadline |<-------------- period ------------------->| .EE .in -.PP +.P When setting a .B SCHED_DEADLINE policy for a thread using @@ -274,7 +274,7 @@ Deadline to the relative deadline, and Period to the period of the task. Thus, for .B SCHED_DEADLINE scheduling, we have: -.PP +.P .in +4n .EX arrival/wakeup absolute deadline @@ -287,7 +287,7 @@ arrival/wakeup absolute deadline |<-------------- Period ------------------->| .EE .in -.PP +.P The three deadline-scheduling parameters correspond to the .IR sched_runtime , .IR sched_deadline , @@ -305,15 +305,15 @@ If .I sched_period is specified as 0, then it is made the same as .IR sched_deadline . -.PP +.P The kernel requires that: -.PP +.P .in +4n .EX sched_runtime <= sched_deadline <= sched_period .EE .in -.PP +.P .\" See __checkparam_dl in kernel/sched/core.c In addition, under the current implementation, all of the parameter values must be at least 1024 @@ -323,10 +323,10 @@ If any of these checks fails, .BR sched_setattr (2) fails with the error .BR EINVAL . -.PP +.P The CBS guarantees non-interference between tasks, by throttling threads that attempt to over-run their specified Runtime. -.PP +.P To ensure deadline scheduling guarantees, the kernel must prevent situations where the set of .B SCHED_DEADLINE @@ -339,13 +339,13 @@ if it is not, .BR sched_setattr (2) fails with the error .BR EBUSY . -.PP +.P For example, it is required (but not necessarily sufficient) for the total utilization to be less than or equal to the total number of CPUs available, where, since each thread can maximally run for Runtime per Period, that thread's utilization is its Runtime divided by its Period. -.PP +.P In order to fulfill the guarantees that are made when a thread is admitted to the .B SCHED_DEADLINE @@ -356,7 +356,7 @@ system; if any .B SCHED_DEADLINE thread is runnable, it will preempt any thread scheduled under one of the other policies. -.PP +.P A call to .BR fork (2) by a thread scheduled under the @@ -364,7 +364,7 @@ by a thread scheduled under the policy fails with the error .BR EAGAIN , unless the thread has its reset-on-fork flag set (see below). -.PP +.P A .B SCHED_DEADLINE thread that calls @@ -383,7 +383,7 @@ processes). \fBSCHED_OTHER\fP is the standard Linux time-sharing scheduler that is intended for all threads that do not require the special real-time mechanisms. -.PP +.P The thread to run is chosen from the static priority 0 list based on a \fIdynamic\fP priority that is determined only inside this list. @@ -391,7 +391,7 @@ The dynamic priority is based on the nice value (see below) and is increased for each time quantum the thread is ready to run, but denied to run by the scheduler. This ensures fair progress among all \fBSCHED_OTHER\fP threads. -.PP +.P In the Linux kernel source code, the .B SCHED_OTHER policy is actually named @@ -411,12 +411,12 @@ The nice value can be modified using .BR setpriority (2), or .BR sched_setattr (2). -.PP +.P According to POSIX.1, the nice value is a per-process attribute; that is, the threads in a process should share a nice value. However, on Linux, the nice value is a per-thread attribute: different threads in the same process may have different nice values. -.PP +.P The range of the nice value varies across UNIX systems. On modern Linux, the range is \-20 (high priority) to +19 (low priority). @@ -424,12 +424,12 @@ On some other systems, the range is \-20..20. Very early Linux kernels (before Linux 2.0) had the range \-infinity..15. .\" Linux before 1.3.36 had \-infinity..15. .\" Since Linux 1.3.43, Linux has the range \-20..19. -.PP +.P The degree to which the nice value affects the relative scheduling of .B SCHED_OTHER processes likewise varies across UNIX systems and across Linux kernel versions. -.PP +.P With the advent of the CFS scheduler in Linux 2.6.23, Linux adopted an algorithm that causes relative differences in nice values to have a much stronger effect. @@ -441,14 +441,14 @@ to a process whenever there is any other higher priority load on the system, and makes high nice values (\-20) deliver most of the CPU to applications that require it (e.g., some audio applications). -.PP +.P On Linux, the .B RLIMIT_NICE resource limit can be used to define a limit to which an unprivileged process's nice value can be raised; see .BR setrlimit (2) for details. -.PP +.P For further details on the nice value, see the subsections on the autogroup feature and group scheduling, below. .\" @@ -464,7 +464,7 @@ that the thread is CPU-intensive. Consequently, the scheduler will apply a small scheduling penalty with respect to wakeup behavior, so that this thread is mildly disfavored in scheduling decisions. -.PP +.P .\" The following paragraph is drawn largely from the text that .\" accompanied Ingo Molnar's patch for the implementation of .\" SCHED_BATCH. @@ -478,7 +478,7 @@ interactivity causing extra preemptions (between the workload's tasks). (Since Linux 2.6.23.) \fBSCHED_IDLE\fP can be used only at static priority 0; the process nice value has no influence for this policy. -.PP +.P This policy is intended for running jobs at extremely low priority (lower even than a +19 nice value with the .B SCHED_OTHER @@ -508,20 +508,20 @@ flag in .I attr.sched_flags when calling .BR sched_setattr (2). -.PP +.P Note that the constants used with these two APIs have different names. The state of the reset-on-fork flag can analogously be retrieved using .BR sched_getscheduler (2) and .BR sched_getattr (2). -.PP +.P The reset-on-fork feature is intended for media-playback applications, and can be used to prevent applications evading the .B RLIMIT_RTTIME resource limit (see .BR getrlimit (2)) by creating multiple child processes. -.PP +.P More precisely, if the reset-on-fork flag is set, the following rules apply for subsequently created children: .IP \[bu] 3 @@ -535,7 +535,7 @@ in child processes. .IP \[bu] If the calling process has a negative nice value, the nice value is reset to zero in child processes. -.PP +.P After the reset-on-fork flag has been enabled, it can be reset only if the thread has the .B CAP_SYS_NICE @@ -555,13 +555,13 @@ matches the real or effective user ID of the target thread (i.e., the thread specified by .IR pid ) whose policy is being changed. -.PP +.P A thread must be privileged .RB ( CAP_SYS_NICE ) in order to set or modify a .B SCHED_DEADLINE policy. -.PP +.P Since Linux 2.6.12, the .B RLIMIT_RTPRIO resource limit defines a ceiling on an unprivileged thread's @@ -608,7 +608,7 @@ policy so long as its nice value falls within the range permitted by its .B RLIMIT_NICE resource limit (see .BR getrlimit (2)). -.PP +.P Privileged .RB ( CAP_SYS_NICE ) threads ignore the @@ -632,7 +632,7 @@ process from freezing the system was to run (at the console) a shell scheduled under a higher static priority than the tested application. This allows an emergency kill of tested real-time applications that do not block or terminate as expected. -.PP +.P Since Linux 2.6.25, there are other techniques for dealing with runaway real-time and deadline processes. One of these is to use the @@ -642,7 +642,7 @@ a real-time process may consume. See .BR getrlimit (2) for details. -.PP +.P Since Linux 2.6.25, Linux also provides two .I /proc files that can be used to reserve a certain amount of CPU time @@ -684,7 +684,7 @@ Child processes inherit the scheduling policy and parameters across a .BR fork (2). The scheduling policy and parameters are preserved across .BR execve (2). -.PP +.P Memory locking is usually needed for real-time processes to avoid paging delays; this can be done with .BR mlock (2) @@ -701,7 +701,7 @@ parallel build processes (i.e., the .BR make (1) .B \-j flag). -.PP +.P This feature operates in conjunction with the CFS scheduler and requires a kernel that is configured with .BR CONFIG_SCHED_AUTOGROUP . @@ -711,7 +711,7 @@ a value of 0 disables the feature, while a value of 1 enables it. The default value in this file is 1, unless the kernel was booted with the .I noautogroup parameter. -.PP +.P A new autogroup is created when a new session is created via .BR setsid (2); this happens, for example, when a new terminal window is started. @@ -721,14 +721,14 @@ inherits its parent's autogroup membership. Thus, all of the processes in a session are members of the same autogroup. An autogroup is automatically destroyed when the last process in the group terminates. -.PP +.P When autogrouping is enabled, all of the members of an autogroup are placed in the same kernel scheduler "task group". The CFS scheduler employs an algorithm that equalizes the distribution of CPU cycles across task groups. The benefits of this for interactive desktop performance can be described via the following example. -.PP +.P Suppose that there are two autogroups competing for the same CPU (i.e., presume either a single CPU system or the use of .BR taskset (1) @@ -759,17 +759,17 @@ the scheduler distributes CPU cycles across task groups such that an autogroup that contains a large number of CPU-bound processes does not end up hogging CPU cycles at the expense of the other jobs on the system. -.PP +.P A process's autogroup (task group) membership can be viewed via the file .IR /proc/ pid /autogroup : -.PP +.P .in +4n .EX $ \fBcat /proc/1/autogroup\fP /autogroup\-1 nice 0 .EE .in -.PP +.P This file can also be used to modify the CPU bandwidth allocated to an autogroup. This is done by writing a number in the "nice" range to the file @@ -791,7 +791,7 @@ to fail with the error .\" A patch was posted on 23 Nov 2016 .\" ("sched/autogroup: Fix 64bit kernel nice adjustment"; .\" check later to see in which kernel version it lands. -.PP +.P The autogroup nice setting has the same meaning as the process nice value, but applies to distribution of CPU cycles to the autogroup as a whole, based on the relative nice values of other autogroups. @@ -800,12 +800,12 @@ will be a product of the autogroup's nice value (compared to other autogroups) and the process's nice value (compared to other processes in the same autogroup. -.PP +.P The use of the .BR cgroups (7) CPU controller to place processes in cgroups other than the root CPU cgroup overrides the effect of autogrouping. -.PP +.P The autogroup feature groups only processes scheduled under non-real-time policies .RB ( SCHED_OTHER , @@ -826,7 +826,7 @@ policies), the CFS scheduler employs a technique known as "group scheduling", if the kernel was configured with the .B CONFIG_FAIR_GROUP_SCHED option (which is typical). -.PP +.P Under group scheduling, threads are scheduled in "task groups". Task groups have a hierarchical relationship, rooted under the initial task group on the system, @@ -856,7 +856,7 @@ 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 in a single task group. -.PP +.P Under group scheduling, a thread's nice value has an effect for scheduling decisions .IR "only relative to other threads in the same task group" . @@ -870,7 +870,7 @@ or on a process has an effect only for scheduling relative to other processes executed in the same session (typically: the same terminal window). -.PP +.P Conversely, for two processes that are (for example) the sole CPU-bound processes in different sessions (e.g., different terminal windows, @@ -886,7 +886,7 @@ A possibly useful workaround here is to use a command such as the following to modify the autogroup nice value for .I all of the processes in a terminal session: -.PP +.P .in +4n .EX $ \fBecho 10 > /proc/self/autogroup\fP @@ -904,17 +904,17 @@ Until the patches have been completely merged into the mainline kernel, they must be installed to achieve the best real-time performance. These patches are named: -.PP +.P .in +4n .EX patch\-\fIkernelversion\fP\-rt\fIpatchversion\fP .EE .in -.PP +.P and can be downloaded from .UR http://www.kernel.org\:/pub\:/linux\:/kernel\:/projects\:/rt/ .UE . -.PP +.P Without the patches and prior to their full inclusion into the mainline kernel, the kernel configuration offers only the three preemption classes .BR CONFIG_PREEMPT_NONE , @@ -923,7 +923,7 @@ and .B CONFIG_PREEMPT_DESKTOP which respectively provide no, some, and considerable reduction of the worst-case scheduling latency. -.PP +.P With the patches applied or after their full inclusion into the mainline kernel, the additional configuration item .B CONFIG_PREEMPT_RT @@ -937,7 +937,7 @@ The .BR cgroups (7) CPU controller can be used to limit the CPU consumption of groups of processes. -.PP +.P Originally, Standard Linux was intended as a general-purpose operating system being able to handle background processes, interactive applications, and less demanding real-time applications (applications that @@ -980,10 +980,10 @@ was not possible up to Linux 2.6.17. .BR capabilities (7), .BR cpuset (7) .ad -.PP +.P .I Programming for the real world \- POSIX.4 by Bill O.\& Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0. -.PP +.P The Linux kernel source files .IR \%Documentation/\:scheduler/\:sched\-deadline\:.txt , .IR \%Documentation/\:scheduler/\:sched\-rt\-group\:.txt , diff --git a/man7/sem_overview.7 b/man7/sem_overview.7 index c452a1c..67f2e41 100644 --- a/man7/sem_overview.7 +++ b/man7/sem_overview.7 @@ -2,12 +2,12 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_overview 7 2022-12-04 "Linux man-pages 6.05.01" +.TH sem_overview 7 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_overview \- overview of POSIX semaphores .SH DESCRIPTION POSIX semaphores allow processes and threads to synchronize their actions. -.PP +.P A semaphore is an integer whose value is never allowed to fall below zero. Two operations can be performed on semaphores: increment the semaphore value by one @@ -17,7 +17,7 @@ and decrement the semaphore value by one If the value of a semaphore is currently zero, then a .BR sem_wait (3) operation will block until the value becomes greater than zero. -.PP +.P POSIX semaphores come in two forms: named semaphores and unnamed semaphores. .TP @@ -81,7 +81,7 @@ When the semaphore is no longer required, and before the memory in which it is located is deallocated, the semaphore should be destroyed using .BR sem_destroy (3). -.PP +.P The remainder of this section describes some specific details of the Linux implementation of POSIX semaphores. .SS Versions @@ -111,7 +111,7 @@ with names of the form rather than .B NAME_MAX characters.) -.PP +.P Since Linux 2.6.19, ACLs can be placed on files under this directory, to control object permissions on a per-user and per-group basis. .SH NOTES diff --git a/man7/session-keyring.7 b/man7/session-keyring.7 index d8a950f..d67de25 100644 --- a/man7/session-keyring.7 +++ b/man7/session-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH session-keyring 7 2023-03-12 "Linux man-pages 6.05.01" +.TH session-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME session-keyring \- session shared process keyring .SH DESCRIPTION @@ -18,17 +18,17 @@ may revoke the session keyring on logout. (In typical configurations, PAM does do this revocation.) The session keyring has the name (description) .IR _ses . -.PP +.P A special serial number value, .BR KEY_SPEC_SESSION_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's session keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@s\fP' can be used instead of a numeric key ID in much the same way. -.PP +.P A process's session keyring is inherited across .BR clone (2), .BR fork (2), @@ -40,7 +40,7 @@ is preserved across even when the executable is set-user-ID or set-group-ID or has capabilities. The session keyring is destroyed when the last process that refers to it exits. -.PP +.P If a process doesn't have a session keyring when it is accessed, then, under certain circumstances, the .BR user\-session\-keyring (7) @@ -76,11 +76,11 @@ identical security attributes and must be single threaded. .BR keyctl (2) .B KEYCTL_SESSION_TO_PARENT operation.) -.PP +.P These operations are also exposed through the .BR keyctl (1) utility as: -.PP +.P .in +4n .EX keyctl session @@ -88,9 +88,9 @@ keyctl session \- [<prog> <arg1> <arg2> ...] keyctl session <name> [<prog> <arg1> <arg2> ...] .EE .in -.PP +.P and: -.PP +.P .in +4n .EX keyctl new_session diff --git a/man7/shm_overview.7 b/man7/shm_overview.7 index 9a33ea0..a049e4c 100644 --- a/man7/shm_overview.7 +++ b/man7/shm_overview.7 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH shm_overview 7 2022-12-04 "Linux man-pages 6.05.01" +.TH shm_overview 7 2023-10-31 "Linux man-pages 6.7" .SH NAME shm_overview \- overview of POSIX shared memory .SH DESCRIPTION The POSIX shared memory API allows processes to communicate information by sharing a region of memory. -.PP +.P The interfaces employed in the API are: .TP 15 .BR shm_open (3) @@ -80,7 +80,7 @@ to control the permissions of objects in the virtual filesystem. .SH NOTES Typically, processes must synchronize their access to a shared memory object, using, for example, POSIX semaphores. -.PP +.P System V shared memory .RB ( shmget (2), .BR shmop (2), diff --git a/man7/sigevent.7 b/man7/sigevent.7 index 1ae860f..b43f1bb 100644 --- a/man7/sigevent.7 +++ b/man7/sigevent.7 @@ -1,120 +1 @@ -.\" Copyright (C) 2006, 2010 Michael Kerrisk <mtk.manpages@gmail.com> -.\" Copyright (C) 2009 Petr Baudis <pasky@suse.cz> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH sigevent 7 2022-10-30 "Linux man-pages 6.05.01" -.SH NAME -sigevent \- structure for notification from asynchronous routines -.SH SYNOPSIS -.nf -#include <signal.h> -.PP -union sigval { /* Data passed with notification */ - int sival_int; /* Integer value */ - void *sival_ptr; /* Pointer value */ -}; -.PP -struct sigevent { - int sigev_notify; /* Notification method */ - int sigev_signo; /* Notification signal */ - union sigval sigev_value; - /* Data passed with notification */ - void (*sigev_notify_function)(union sigval); - /* Function used for thread - notification (SIGEV_THREAD) */ - void *sigev_notify_attributes; - /* Attributes for notification thread - (SIGEV_THREAD) */ - pid_t sigev_notify_thread_id; - /* ID of thread to signal - (SIGEV_THREAD_ID); Linux-specific */ -}; -.fi -.SH DESCRIPTION -The -.I sigevent -structure is used by various APIs -to describe the way a process is to be notified about an event -(e.g., completion of an asynchronous request, expiration of a timer, -or the arrival of a message). -.PP -The definition shown in the SYNOPSIS is approximate: -some of the fields in the -.I sigevent -structure may be defined as part of a union. -Programs should employ only those fields relevant -to the value specified in -.IR sigev_notify . -.PP -The -.I sigev_notify -field specifies how notification is to be performed. -This field can have one of the following values: -.TP -.B SIGEV_NONE -A "null" notification: don't do anything when the event occurs. -.TP -.B SIGEV_SIGNAL -Notify the process by sending the signal specified in -.IR sigev_signo . -.IP -If the signal is caught with a signal handler that was registered using the -.BR sigaction (2) -.B SA_SIGINFO -flag, then the following fields are set in the -.I siginfo_t -structure that is passed as the second argument of the handler: -.RS -.TP 10 -.I si_code -This field is set to a value that depends on the API -delivering the notification. -.TP -.I si_signo -This field is set to the signal number (i.e., the same value as in -.IR sigev_signo ). -.TP -.I si_value -This field is set to the value specified in -.IR sigev_value . -.RE -.IP -Depending on the API, other fields may also be set in the -.I siginfo_t -structure. -.IP -The same information is also available if the signal is accepted using -.BR sigwaitinfo (2). -.TP -.B SIGEV_THREAD -Notify the process by invoking -.I sigev_notify_function -"as if" it were the start function of a new thread. -(Among the implementation possibilities here are that -each timer notification could result in the creation of a new thread, -or that a single thread is created to receive all notifications.) -The function is invoked with -.I sigev_value -as its sole argument. -If -.I sigev_notify_attributes -is not NULL, it should point to a -.I pthread_attr_t -structure that defines attributes for the new thread (see -.BR pthread_attr_init (3)). -.TP -.BR SIGEV_THREAD_ID " (Linux-specific)" -.\" | SIGEV_SIGNAL vs not? -Currently used only by POSIX timers; see -.BR timer_create (2). -.SH SEE ALSO -.BR timer_create (2), -.BR aio_fsync (3), -.BR aio_read (3), -.BR aio_write (3), -.BR getaddrinfo_a (3), -.BR lio_listio (3), -.BR mq_notify (3), -.BR aio (7), -.BR pthreads (7) +.so man3type/sigevent.3type diff --git a/man7/signal-safety.7 b/man7/signal-safety.7 index 4bcb478..d307dda 100644 --- a/man7/signal-safety.7 +++ b/man7/signal-safety.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH signal-safety 7 2023-02-05 "Linux man-pages 6.05.01" +.TH signal-safety 7 2023-10-31 "Linux man-pages 6.7" .SH NAME signal-safety \- async-signal-safe functions .SH DESCRIPTION @@ -15,13 +15,13 @@ Many functions are async-signal-safe. In particular, nonreentrant functions are generally unsafe to call from a signal handler. -.PP +.P The kinds of issues that render a function unsafe can be quickly understood when one considers the implementation of the .I stdio library, all of whose functions are not async-signal-safe. -.PP +.P When performing buffered I/O on a file, the .I stdio functions must maintain a statically allocated data buffer @@ -38,7 +38,7 @@ the program is interrupted by a signal handler that also calls then the second call to .BR printf (3) will operate on inconsistent data, with unpredictable results. -.PP +.P To avoid problems with unsafe functions, there are two possible choices: .IP (a) 5 Ensure that @@ -50,26 +50,26 @@ with respect to global variables in the main program. 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. -.PP +.P Generally, the second choice is difficult in programs of any complexity, so the first choice is taken. -.PP +.P POSIX.1 specifies a set of functions that an implementation must make async-signal-safe. (An implementation may provide safe implementations of additional functions, but this is not required by the standard and other implementations may not provide the same guarantees.) -.PP +.P In general, a function is async-signal-safe either because it is reentrant or because it is atomic with respect to signals (i.e., its execution can't be interrupted by a signal handler). -.PP +.P The set of functions required to be async-signal-safe by POSIX.1 is shown in the following table. The functions not otherwise noted were required to be async-signal-safe in POSIX.1-2001; the table details changes in the subsequent standards. -.PP +.P .TS lb lb l l. @@ -272,7 +272,7 @@ T} \fBwmemset\fP(3) Added in POSIX.1-2008 TC2 \fBwrite\fP(2) .TE -.PP +.P Notes: .IP \[bu] 3 POSIX.1-2001 and POSIX.1-2001 TC2 required the functions diff --git a/man7/signal.7 b/man7/signal.7 index 6f6f9c9..39281e5 100644 --- a/man7/signal.7 +++ b/man7/signal.7 @@ -23,7 +23,7 @@ .\" Added section on stop/cont signals interrupting syscalls. .\" 2008-10-05, mtk: various additions .\" -.TH signal 7 2023-04-03 "Linux man-pages 6.05.01" +.TH signal 7 2023-10-31 "Linux man-pages 6.7" .SH NAME signal \- overview of signals .SH DESCRIPTION @@ -34,7 +34,7 @@ Each signal has a current .IR disposition , which determines how the process behaves when it is delivered the signal. -.PP +.P The entries in the "Action" column of the table below specify the default disposition for each signal, as follows: .TP @@ -53,7 +53,7 @@ Default action is to stop the process. .TP Cont Default action is to continue the process if it is currently stopped. -.PP +.P A process can change the disposition of a signal using .BR sigaction (2) or @@ -69,18 +69,18 @@ or catch the signal with a .IR "signal handler" , a programmer-defined function that is automatically invoked when the signal is delivered. -.PP +.P By default, a signal handler is invoked on the normal process stack. It is possible to arrange that the signal handler uses an alternate stack; see .BR sigaltstack (2) for a discussion of how to do this and when it might be useful. -.PP +.P The signal disposition is a per-process attribute: in a multithreaded application, the disposition of a particular signal is the same for all threads. -.PP +.P A child created via .BR fork (2) inherits a copy of its parent's signal dispositions. @@ -164,7 +164,7 @@ which means that it will not be delivered until it is later unblocked. Between the time when it is generated and when it is delivered a signal is said to be .IR pending . -.PP +.P Each thread in a process has an independent .IR "signal mask" , which indicates the set of signals that the thread is currently blocking. @@ -173,13 +173,13 @@ A thread can manipulate its signal mask using In a traditional single-threaded application, .BR sigprocmask (2) can be used to manipulate the signal mask. -.PP +.P A child created via .BR fork (2) inherits a copy of its parent's signal mask; the signal mask is preserved across .BR execve (2). -.PP +.P A signal may be process-directed or thread-directed. A process-directed signal is one that is targeted at (and thus pending for) the process as a whole. @@ -202,7 +202,7 @@ interfaces such as .BR tgkill (2) or .BR pthread_kill (3). -.PP +.P A process-directed signal may be delivered to any one of the threads that does not currently have the signal blocked. .\" Joseph C. Sible notes: @@ -225,14 +225,14 @@ threads that does not currently have the signal blocked. .\" If more than one of the threads has the signal unblocked, then the kernel chooses an arbitrary thread to which to deliver the signal. -.PP +.P A thread can obtain the set of signals that it currently has pending using .BR sigpending (2). This set will consist of the union of the set of pending process-directed signals and the set of signals pending for the calling thread. -.PP +.P A child created via .BR fork (2) initially has an empty pending signal set; @@ -320,7 +320,7 @@ Upon completion of the call to the kernel transfers control back to user space, and the thread recommences execution at the point where it was interrupted by the signal handler. -.PP +.P Note that if the signal handler does not return (e.g., control is transferred out of the handler using .BR siglongjmp (3), @@ -338,7 +338,7 @@ may or may not restore the signal mask, depending on the .I savesigs value that was specified in the corresponding call to .BR sigsetjmp (3).) -.PP +.P From the kernel's point of view, execution of the signal handler code is exactly the same as the execution of any other user-space code. @@ -405,13 +405,13 @@ SIGXFSZ P2001 Core File size limit exceeded (4.2BSD); see \fBsetrlimit\fP(2) SIGWINCH \- Ign Window resize signal (4.3BSD, Sun) .TE -.PP +.P The signals .B SIGKILL and .B SIGSTOP cannot be caught, blocked, or ignored. -.PP +.P Up to and including Linux 2.2, the default behavior for .BR SIGSYS ", " SIGXCPU ", " SIGXFSZ , and (on architectures other than SPARC and MIPS) @@ -422,17 +422,17 @@ was to terminate the process (without a core dump). is to terminate the process without a core dump.) Linux 2.4 conforms to the POSIX.1-2001 requirements for these signals, terminating the process with a core dump. -.PP +.P .B SIGEMT is not specified in POSIX.1-2001, but nevertheless appears on most other UNIX systems, where its default action is typically to terminate the process with a core dump. -.PP +.P .B SIGPWR (which is not specified in POSIX.1-2001) is typically ignored by default on those other UNIX systems where it appears. -.PP +.P .B SIGIO (which is not specified in POSIX.1-2001) is ignored by default on several other UNIX systems. @@ -440,7 +440,7 @@ on several other UNIX systems. .SS Queueing and delivery semantics for standard signals If multiple standard signals are pending for a process, the order in which the signals are delivered is unspecified. -.PP +.P Standard signals do not queue. If multiple instances of a standard signal are generated while that signal is blocked, @@ -510,7 +510,7 @@ SIGLOST \- \-/29 \- \- SIGSYS 31 12 12 31 SIGUNUSED 31 \- \- 31 .TE -.PP +.P Note the following: .IP \[bu] 3 Where defined, @@ -538,7 +538,7 @@ and POSIX.1-2001 requires that an implementation support at least .B _POSIX_RTSIG_MAX (8) real-time signals. -.PP +.P The Linux kernel supports a range of 33 different real-time signals, numbered 32 to 64. However, the glibc POSIX threads implementation internally uses @@ -560,14 +560,14 @@ and include suitable (run-time) checks that .BR SIGRTMIN +n does not exceed .BR SIGRTMAX . -.PP +.P Unlike standard signals, real-time signals have no predefined meanings: the entire set of real-time signals can be used for application-defined purposes. -.PP +.P The default action for an unhandled real-time signal is to terminate the receiving process. -.PP +.P Real-time signals are distinguished by the following: .IP \[bu] 3 Multiple instances of real-time signals can be queued. @@ -602,12 +602,12 @@ starting with the lowest-numbered signal. (I.e., low-numbered signals have highest priority.) By contrast, if multiple standard signals are pending for a process, the order in which they are delivered is unspecified. -.PP +.P If both standard and real-time signals are pending for a process, POSIX leaves it unspecified which is delivered first. Linux, like many other implementations, gives priority to standard signals in this case. -.PP +.P According to POSIX, an implementation should permit at least .B _POSIX_SIGQUEUE_MAX (32) real-time signals to be queued to @@ -630,7 +630,7 @@ resource limit, which specifies a per-user limit for queued signals; see .BR setrlimit (2) for further details. -.PP +.P The addition of real-time signals required the widening of the signal set structure .RI ( sigset_t ) @@ -658,7 +658,7 @@ the call is automatically restarted after the signal handler returns; or .IP \[bu] the call fails with the error .BR EINTR . -.PP +.P Which of these two behaviors occurs depends on the interface and whether or not the signal handler was established using the .B SA_RESTART @@ -666,7 +666,7 @@ flag (see .BR sigaction (2)). The details vary across UNIX systems; below, the details for Linux. -.PP +.P If a blocked call to one of the following interfaces is interrupted by a signal handler, then the call is automatically restarted after the signal handler returns if the @@ -771,7 +771,7 @@ file descriptor .\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06 beforehand, always failed with .BR EINTR ). -.PP +.P The following interfaces are never restarted after being interrupted by a signal handler, regardless of the use of @@ -838,12 +838,12 @@ and .BR usleep (3). .IP \[bu] .BR io_getevents (2). -.PP +.P The .BR sleep (3) function is also never restarted if interrupted by a handler, but gives a success return: the number of seconds remaining to sleep. -.PP +.P In certain circumstances, the .BR seccomp (2) user-space notification feature can lead to restarting of system calls @@ -861,7 +861,7 @@ and then resumed via .BR SIGCONT . This behavior is not sanctioned by POSIX.1, and doesn't occur on other systems. -.PP +.P The Linux interfaces that display this behavior are: .IP \[bu] 3 "Input" socket interfaces, when a timeout @@ -925,7 +925,7 @@ POSIX.1, except as noted. .SH NOTES For a discussion of async-signal-safe functions, see .BR signal\-safety (7). -.PP +.P The .IR /proc/ pid /task/ tid /status file contains various fields that show the signals @@ -961,13 +961,13 @@ and Which of these signals is delivered, for any given hardware exception, is not documented and does not always make sense. -.PP +.P For example, an invalid memory access that causes delivery of .B SIGSEGV on one CPU architecture may cause delivery of .B SIGBUS on another architecture, or vice versa. -.PP +.P For another example, using the x86 .I int instruction with a forbidden argument @@ -1016,4 +1016,4 @@ because of how the CPU reports the forbidden operation to the kernel. .BR proc (5), .BR nptl (7), .BR pthreads (7), -.BR sigevent (7) +.BR sigevent (3type) diff --git a/man7/sock_diag.7 b/man7/sock_diag.7 index adf47b7..3da3b4a 100644 --- a/man7/sock_diag.7 +++ b/man7/sock_diag.7 @@ -2,7 +2,7 @@ .\" Copyright (c) 2016 Dmitry V. Levin <ldv@altlinux.org> .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH sock_diag 7 2023-05-03 "Linux man-pages 6.05.01" +.TH sock_diag 7 2023-10-31 "Linux man-pages 6.7" .SH NAME sock_diag \- obtaining information about sockets .SH SYNOPSIS @@ -11,7 +11,7 @@ sock_diag \- obtaining information about sockets .B #include <linux/sock_diag.h> .BR "#include <linux/unix_diag.h>" " /* for UNIX domain sockets */" .BR "#include <linux/inet_diag.h>" " /* for IPv4 and IPv6 sockets */" -.PP +.P .BI "diag_socket = socket(AF_NETLINK, " socket_type ", NETLINK_SOCK_DIAG);" .fi .SH DESCRIPTION @@ -19,16 +19,16 @@ The sock_diag netlink subsystem provides a mechanism for obtaining information about sockets of various address families from the kernel. This subsystem can be used to obtain information about individual sockets or request a list of sockets. -.PP +.P In the request, the caller can specify additional information it would like to obtain about the socket, for example, memory information or information specific to the address family. -.PP +.P When requesting a list of sockets, the caller can specify filters that would be applied by the kernel to select a subset of sockets to report. For now, there is only the ability to filter sockets by state (connected, listening, and so on.) -.PP +.P Note that sock_diag reports only those sockets that have a name; that is, either sockets bound explicitly with .BR bind (2) @@ -51,7 +51,7 @@ field set to .BR SOCK_DIAG_BY_FAMILY . It is followed by a header specific to the address family that starts with a common part shared by all address families: -.PP +.P .in +4n .EX struct sock_diag_req { @@ -60,7 +60,7 @@ struct sock_diag_req { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I sdiag_family @@ -79,7 +79,7 @@ constant for and .BR AF_INET6 , and to 0 otherwise. -.PP +.P If the .I nlmsg_flags field of the @@ -98,7 +98,7 @@ The array is to be accessed with the standard macros from the .BR netlink (3) API. -.PP +.P Each object is the NLA (netlink attributes) list that is to be accessed with the .B RTA_* @@ -108,7 +108,7 @@ API. .\" .SS UNIX domain sockets For UNIX domain sockets the request is represented in the following structure: -.PP +.P .in +4n .EX struct unix_diag_req { @@ -122,13 +122,13 @@ struct unix_diag_req { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I sdiag_family The address family; it should be set to .BR AF_UNIX . -.PP +.P .I sdiag_protocol .PD 0 .TP @@ -141,11 +141,11 @@ This is a bit mask that defines a filter of sockets states. Only those sockets whose states are in this mask will be reported. Ignored when querying for an individual socket. Supported values are: -.PP +.P .RS 12 1 << .B TCP_ESTABLISHED -.PP +.P 1 << .B TCP_LISTEN .RE @@ -253,7 +253,7 @@ The attribute reported in answer to this request is .BR UNIX_DIAG_MEMINFO . The payload associated with this attribute is an array of __u32 values described below in the subsection "Socket memory information". -.PP +.P The following attributes are reported back without any specific request: .TP .B UNIX_DIAG_SHUTDOWN @@ -269,9 +269,9 @@ This is an array of opaque identifiers that could be used along with to specify an individual socket. It is ignored when querying for a list of sockets, as well as when all its elements are set to \-1. -.PP +.P The response to a query for UNIX domain sockets is represented as an array of -.PP +.P .in +4n .EX struct unix_diag_msg { @@ -284,9 +284,9 @@ struct unix_diag_msg { }; .EE .in -.PP +.P followed by netlink attributes. -.PP +.P The fields of this structure are as follows: .TP .I udiag_family @@ -319,7 +319,7 @@ queries. .SS IPv4 and IPv6 sockets For IPv4 and IPv6 sockets, the request is represented in the following structure: -.PP +.P .in +4n .EX struct inet_diag_req_v2 { @@ -332,11 +332,11 @@ struct inet_diag_req_v2 { }; .EE .in -.PP +.P where .I "struct inet_diag_sockid" is defined as follows: -.PP +.P .in +4n .EX struct inet_diag_sockid { @@ -349,7 +349,7 @@ struct inet_diag_sockid { }; .EE .in -.PP +.P The fields of .I "struct inet_diag_req_v2" are as follows: @@ -447,7 +447,7 @@ about individual sockets, and is reported back in each response. Unlike UNIX domain sockets, IPv4 and IPv6 sockets are identified using addresses and ports. All values are in network byte order. -.PP +.P The fields of .I "struct inet_diag_sockid" are as follows: @@ -472,9 +472,9 @@ This is an array of opaque identifiers that could be used along with other fields of this structure to specify an individual socket. It is ignored when querying for a list of sockets, as well as when all its elements are set to \-1. -.PP +.P The response to a query for IPv4 or IPv6 sockets is represented as an array of -.PP +.P .in +4n .EX struct inet_diag_msg { @@ -493,9 +493,9 @@ struct inet_diag_msg { }; .EE .in -.PP +.P followed by netlink attributes. -.PP +.P The fields of this structure are as follows: .TP .I idiag_family @@ -611,7 +611,7 @@ In Linux 3.3, it was renamed to and extended to support .B AF_UNIX sockets. -.PP +.P .B UNIX_DIAG_MEMINFO and .B INET_DIAG_SKMEMINFO @@ -621,7 +621,7 @@ Linux. .SH EXAMPLES The following example program prints inode number, peer's inode number, and name of all UNIX domain sockets in the current namespace. -.PP +.P .EX #include <errno.h> #include <stdio.h> diff --git a/man7/socket.7 b/man7/socket.7 index 2cc24d9..619139e 100644 --- a/man7/socket.7 +++ b/man7/socket.7 @@ -47,13 +47,13 @@ .\" commit ea02f9411d9faa3553ed09ce0ec9f00ceae9885e .\" Author: Michal Sekletar <msekleta@redhat.com> .\" -.TH socket 7 2023-07-15 "Linux man-pages 6.05.01" +.TH socket 7 2024-01-16 "Linux man-pages 6.7" .SH NAME socket \- Linux socket interface .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .IB sockfd " = socket(int " socket_family ", int " socket_type ", int " protocol ); .fi .SH DESCRIPTION @@ -79,7 +79,7 @@ for more information on families and types. These functions are used by the user process to send or receive packets and to do other socket operations. For more information, see their respective manual pages. -.PP +.P .BR socket (2) creates a socket, .BR connect (2) @@ -95,7 +95,7 @@ is used to get a new socket with a new incoming connection. returns two connected anonymous sockets (implemented only for a few local families like .BR AF_UNIX ) -.PP +.P .BR send (2), .BR sendto (2), and @@ -117,7 +117,7 @@ In addition, the standard I/O operations like and .BR readv (2) can be used to read and write data. -.PP +.P .BR getsockname (2) returns the local socket address and .BR getpeername (2) @@ -128,18 +128,18 @@ and are used to set or get socket layer or protocol options. .BR ioctl (2) can be used to set or read some other options. -.PP +.P .BR close (2) is used to close a socket. .BR shutdown (2) closes parts of a full-duplex socket connection. -.PP +.P Seeking, or calling .BR pread (2) or .BR pwrite (2) with a nonzero position is not supported on sockets. -.PP +.P It is possible to do nonblocking I/O on sockets by setting the .B O_NONBLOCK flag on a socket file descriptor using @@ -208,7 +208,7 @@ T} .\" or .\" .BR close (2). .TE -.PP +.P An alternative to .BR poll (2) and @@ -244,7 +244,7 @@ the various system calls (e.g., .BR getpeername (2)), which are generic to all socket domains, to determine the domain of a particular socket address. -.PP +.P To allow any type of socket address to be passed to interfaces in the sockets API, the type @@ -254,7 +254,7 @@ The purpose of this type is purely to allow casting of domain-specific socket address types to a "generic" type, so as to avoid compiler warnings about type mismatches in calls to the sockets API. -.PP +.P In addition, the sockets API provides the data type .IR "struct sockaddr_storage". This type @@ -264,13 +264,13 @@ address structures; it is large enough and is aligned properly. IPv6 socket addresses.) The structure includes the following field, which can be used to identify the type of socket address actually stored in the structure: -.PP +.P .in +4n .EX sa_family_t ss_family; .EE .in -.PP +.P The .I sockaddr_storage structure is useful in programs that must handle socket addresses @@ -303,7 +303,9 @@ The value 0 indicates that this is not a listening socket, the value 1 indicates that this is a listening socket. This socket option is read-only. .TP -.BR SO_ATTACH_FILTER " (since Linux 2.2), " SO_ATTACH_BPF " (since Linux 3.19)" +.BR SO_ATTACH_FILTER " (since Linux 2.2)" +.TQ +.BR SO_ATTACH_BPF " (since Linux 3.19)" Attach a classic BPF .RB ( SO_ATTACH_FILTER ) or an extended BPF @@ -348,7 +350,9 @@ never has more than one filter defined. Both classic and extended BPF are explained in the kernel source file .I Documentation/networking/filter.txt .TP -.BR SO_ATTACH_REUSEPORT_CBPF ", " SO_ATTACH_REUSEPORT_EBPF +.B SO_ATTACH_REUSEPORT_CBPF +.TQ +.B SO_ATTACH_REUSEPORT_EBPF For use with the .B SO_REUSEPORT option, these options allow the user to set a classic BPF @@ -451,7 +455,9 @@ Allowed only for processes with the .B CAP_NET_ADMIN capability or an effective user ID of 0. .TP -.BR SO_DETACH_FILTER " (since Linux 2.2), " SO_DETACH_BPF " (since Linux 3.19)" +.BR SO_DETACH_FILTER " (since Linux 2.2)" +.TQ +.BR SO_DETACH_BPF " (since Linux 3.19)" These two options, which are synonyms, may be used to remove the classic or extended BPF program attached to a socket with either @@ -608,7 +614,9 @@ Changing the mark can be used for mark-based routing without netfilter or for packet filtering. Setting this option requires the .B CAP_NET_ADMIN -capability. +or +.B CAP_NET_RAW +(since Linux 5.17) capability. .TP .B SO_OOBINLINE If this option is enabled, @@ -1054,7 +1062,7 @@ The signal is not sent when the write call specified the .B MSG_NOSIGNAL flag. -.PP +.P When requested with the .B FIOSETOWN .BR fcntl (2) @@ -1079,7 +1087,7 @@ field of its See .BR fcntl (2) for more information. -.PP +.P Under some circumstances (e.g., multiple processes accessing a single socket), the condition that caused the .B SIGIO @@ -1124,7 +1132,7 @@ per socket. .SS Ioctls These operations can be accessed using .BR ioctl (2): -.PP +.P .in +4n .EX .IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");" @@ -1198,7 +1206,7 @@ or signals, or 0 when none is set. -.PP +.P Valid .BR fcntl (2) operations: @@ -1231,7 +1239,7 @@ Linux assumes that half of the send/receive buffer is used for internal kernel structures; thus the values in the corresponding .I /proc files are twice what can be observed on the wire. -.PP +.P Linux will allow port reuse only with the .B SO_REUSEADDR option diff --git a/man7/spufs.7 b/man7/spufs.7 index fc3b424..3e8c2ed 100644 --- a/man7/spufs.7 +++ b/man7/spufs.7 @@ -10,14 +10,14 @@ .\" 2007-07-10, quite a lot of polishing by mtk .\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org> .\" -.TH spufs 7 2023-02-05 "Linux man-pages 6.05.01" +.TH spufs 7 2023-10-31 "Linux man-pages 6.7" .SH NAME spufs \- SPU filesystem .SH DESCRIPTION The SPU filesystem is used on PowerPC machines that implement the Cell Broadband Engine Architecture in order to access Synergistic Processor Units (SPUs). -.PP +.P The filesystem provides a name space similar to POSIX shared memory or message queues. Users that have write permissions @@ -26,7 +26,7 @@ on the filesystem can use to establish SPU contexts under the .B spufs root directory. -.PP +.P Every SPU context is represented by a directory containing a predefined set of files. These files can be @@ -58,7 +58,7 @@ supported on regular filesystems. This list details the supported operations and the deviations from the standard behavior described in the respective man pages. -.PP +.P All files that support the .BR read (2) operation also support @@ -80,7 +80,7 @@ structure that contain reliable information are .IR st_uid , and .IR st_gid . -.PP +.P All files support the .BR chmod (2)/\c .BR fchmod (2) @@ -91,7 +91,7 @@ operations, but will not be able to grant permissions that contradict the possible operations (e.g., read access on the .I wbox file). -.PP +.P The current set of files is: .TP .I /capabilities @@ -105,7 +105,7 @@ This context may be scheduled. .TP .B step This context can be run in single-step mode, for debugging. -.PP +.P New capabilities flags may be added in the future. .RE .TP @@ -119,7 +119,15 @@ The possible operations on an open file are: .RS .TP -.BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2) +.BR read (2) +.TQ +.BR pread (2) +.TQ +.BR write (2) +.TQ +.BR pwrite (2) +.TQ +.BR lseek (2) These operate as usual, with the exception that .BR lseek (2), .BR write (2), @@ -289,7 +297,11 @@ file returns whenever space is available for writing. .RE .TP -.IR /mbox_stat ", " /ibox_stat ", " /wbox_stat +.I /mbox_stat +.TQ +.I /ibox_stat +.TQ +.I /wbox_stat These are read-only files that contain the length of the current queue of each mailbox\[em]that is, how many words can be read from .IR mbox " or " ibox @@ -324,8 +336,21 @@ the respective mailbox without blocking or returning an error. .RE .TP -.IR /npc ", " /decr ", " /decr_status ", " /spu_tag_mask ", " \ -/event_mask ", " /event_status ", " /srr0 ", " /lslr +.I /npc +.TQ +.I /decr +.TQ +.I /decr_status +.TQ +.I /spu_tag_mask +.TQ +.I /event_mask +.TQ +.I /event_status +.TQ +.I /srr0 +.TQ +.I /lslr Internal registers of the SPU. These files contain an ASCII string representing the hex value of the specified register. @@ -433,7 +458,9 @@ updating the value of the register. .RE .TP -.IR /signal1 ", " /signal2 +.I /signal1 +.TQ +.I /signal2 The files provide access to the two signal notification channels of an SPU. These are read-write files that operate on four-byte words. @@ -484,7 +511,9 @@ or files respectively. .RE .TP -.IR /signal1_type ", " /signal2_type +.I /signal1_type +.TQ +.I /signal2_type These two files change the behavior of the .I signal1 and @@ -524,7 +553,15 @@ Subsequent writes to the same file descriptor overwrite the previous setting. .RE .TP -.IR /mbox_info ", " /ibox_info ", " /wbox_info ", " /dma_into ", " /proxydma_info +.I /mbox_info +.TQ +.I /ibox_info +.TQ +.I /wbox_info +.TQ +.I /dma_into +.TQ +.I /proxydma_info Read-only files that contain the saved state of the SPU mailboxes and DMA queues. This allows the SPU status to be inspected, mainly for debugging. @@ -763,5 +800,5 @@ none /spu spufs gid=spu 0 0 .BR spu_create (2), .BR spu_run (2), .BR capabilities (7) -.PP +.P .I The Cell Broadband Engine Architecture (CBEA) specification diff --git a/man7/standards.7 b/man7/standards.7 index c1df6f8..a058b92 100644 --- a/man7/standards.7 +++ b/man7/standards.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH standards 7 2023-03-13 "Linux man-pages 6.05.01" +.TH standards 7 2023-10-31 "Linux man-pages 6.7" .SH NAME standards \- C and UNIX Standards .SH DESCRIPTION @@ -183,7 +183,9 @@ See also .UR http://www.unix.org\:/version2/ .UE .) .TP -.B POSIX.1-2001, SUSv3 +.B POSIX.1-2001 +.TQ +.B SUSv3 This was a 2001 revision and consolidation of the POSIX.1, POSIX.2, and SUS standards into a single document, conducted under the auspices of the Austin Group @@ -233,7 +235,9 @@ of the original 2001 standard have occurred: TC1 in 2003 and TC2 in 2004. .TP -.B POSIX.1-2008, SUSv4 +.B POSIX.1-2008 +.TQ +.B SUSv4 Work on the next revision of POSIX.1/SUS was completed and ratified in 2008. The standard is available online at @@ -286,7 +290,7 @@ Technical Corrigenda 1 and 2 applied. .B SUSv4 2018 edition This is equivalent to POSIX.1-2017, with the addition of the XCurses specification. -.PP +.P The interfaces documented in POSIX.1/SUS are available as manual pages under sections 0p (header files), 1p (commands), and 3p (functions); diff --git a/man7/string_copying.7 b/man7/string_copying.7 index 814eabd..43bc00d 100644 --- a/man7/string_copying.7 +++ b/man7/string_copying.7 @@ -2,18 +2,17 @@ .\" .\" SPDX-License-Identifier: BSD-3-Clause .\" -.TH string_copying 7 2023-07-29 "Linux man-pages 6.05.01" +.TH string_copying 7 2023-12-17 "Linux man-pages 6.7" .\" ----- NAME :: -----------------------------------------------------/ .SH NAME stpcpy, strcpy, strcat, stpecpy, +strtcpy, strlcpy, strlcat, stpncpy, strncpy, -zustr2ustp, zustr2stp, -strncat, -ustpcpy, ustr2stp +strncat \- copying strings and character sequences .\" ----- SYNOPSIS :: -------------------------------------------------/ .SH SYNOPSIS @@ -22,63 +21,57 @@ ustpcpy, ustr2stp .nf // Chain-copy a string. .BI "char *stpcpy(char *restrict " dst ", const char *restrict " src ); -.PP +.P // Copy/catenate a string. .BI "char *strcpy(char *restrict " dst ", const char *restrict " src ); .BI "char *strcat(char *restrict " dst ", const char *restrict " src ); -.PP +.P // Chain-copy a string with truncation. .BI "char *stpecpy(char *" dst ", char " end "[0], const char *restrict " src ); -.PP +.P // Copy/catenate a string with truncation. -.BI "size_t strlcpy(char " dst "[restrict ." sz "], \ +.BI "ssize_t strtcpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.BI "size_t strlcat(char " dst "[restrict ." sz "], \ +.BI " size_t " dsize ); +.BI "size_t strlcpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); +.BI " size_t " dsize ); +.BI "size_t strlcat(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); .fi .\" ----- SYNOPSIS :: Null-padded character sequences --------/ .SS Null-padded character sequences .nf -// Zero a fixed-width buffer, and -// copy a string into a character sequence with truncation. -.BI "char *stpncpy(char " dst "[restrict ." sz "], \ +// Fill a fixed-size buffer with characters from a string +// and pad with null bytes. +.BI "char *strncpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.PP -// Zero a fixed-width buffer, and -// copy a string into a character sequence with truncation. -.BI "char *strncpy(char " dst "[restrict ." sz "], \ +.BI " size_t " dsize ); +.BI "char *stpncpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.PP +.BI " size_t " dsize ); +.P // Chain-copy a null-padded character sequence into a character sequence. -.BI "char *zustr2ustp(char *restrict " dst ", \ -const char " src "[restrict ." sz ], -.BI " size_t " sz ); -.PP +.I mempcpy(dst, src, strnlen(src, NITEMS(src))); +.P // Chain-copy a null-padded character sequence into a string. -.BI "char *zustr2stp(char *restrict " dst ", \ -const char " src "[restrict ." sz ], -.BI " size_t " sz ); -.PP +.I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq]); +.P // Catenate a null-padded character sequence into a string. -.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ], -.BI " size_t " sz ); +.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ], +.BI " size_t " ssize ); .fi -.\" ----- SYNOPSIS :: Measured character sequences --------------------/ -.SS Measured character sequences +.\" ----- SYNOPSIS :: Known-length character sequences --------------------/ +.SS Known-length character sequences .nf -// Chain-copy a measured character sequence. -.BI "char *ustpcpy(char *restrict " dst ", \ -const char " src "[restrict ." len ], -.BI " size_t " len ); -.PP -// Chain-copy a measured character sequence into a string. -.BI "char *ustr2stp(char *restrict " dst ", \ -const char " src "[restrict ." len ], +// Chain-copy a known-length character sequence. +.BI "void *mempcpy(void " dst "[restrict ." len "], \ +const void " src "[restrict ." len ], .BI " size_t " len ); +.P +// Chain-copy a known-length character sequence into a string. +.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]); .fi .SH DESCRIPTION .\" ----- DESCRIPTION :: Terms (and abbreviations) :: -----------------/ @@ -86,7 +79,7 @@ const char " src "[restrict ." len ], .\" ----- DESCRIPTION :: Terms (and abbreviations) :: string (str) ----/ .TP .IR "string " ( str ) -is a sequence of zero or more non-null characters followed by a null byte. +is a sequence of zero or more non-null characters followed by a null character. .\" ----- DESCRIPTION :: Terms (and abbreviations) :: null-padded character seq .TP .I character sequence @@ -96,15 +89,18 @@ However, with appropriate care, a string can be used in the place of a character sequence. .RS .TP -.IR "null-padded character sequence " ( zustr ) -Character sequences can be contained in fixed-width buffers, +.I null-padded character sequence +Character sequences can be contained in fixed-size buffers, which contain padding null bytes after the character sequence, to fill the rest of the buffer without affecting the character sequence; however, those padding null bytes are not part of the character sequence. -.\" ----- DESCRIPTION :: Terms (and abbreviations) :: measured character sequence +Don't confuse null-padded with null-terminated: +null-padded means 0 or more padding null bytes, +while null-terminated means exactly 1 terminating null character. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: known-length character sequence .TP -.IR "measured character sequence " ( ustr ) +.I known-length character sequence Character sequence delimited by its length. It may be a slice of a larger character sequence, or even of a string. @@ -116,10 +112,10 @@ is the number of non-null characters in a string or character sequence. It is the return value of .I strlen(str) and of -.IR "strnlen(ustr, sz)" . -.\" ----- DESCRIPTION :: Terms (and abbreviations) :: size (sz) -------/ +.IR "strnlen(buf, size)" . +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: size ------------/ .TP -.IR "size " ( sz ) +.I size refers to the entire buffer where the string or character sequence is contained. .\" ----- DESCRIPTION :: Terms (and abbreviations) :: end -------------/ @@ -127,7 +123,7 @@ where the string or character sequence is contained. .I end is the name of a pointer to one past the last element of a buffer. It is equivalent to -.IR &str[sz] . +.IR &str[size] . It is used as a sentinel value, to be able to truncate strings or character sequences instead of overrunning the containing buffer. @@ -141,7 +137,7 @@ the writing starts at the first element pointed to by .TP .I catenate This term is used when -a function first finds the terminating null byte in +a function first finds the terminating null character in .IR dst , and then starts writing at that position. .\" ----- DESCRIPTION :: Terms (and abbreviations) :: chain -----------/ @@ -149,12 +145,12 @@ and then starts writing at that position. .I chain This term is used when it's the programmer who provides -a pointer to the terminating null byte in the string +a pointer to the terminating null character in the string .I dst (or one after the last character in a character sequence), and the function starts writing at that location. The function returns -a pointer to the new location of the terminating null byte +a pointer to the new location of the terminating null character (or one after the last character in a character sequence) after the call, so that the programmer can use it to chain such calls. @@ -166,11 +162,11 @@ However, newer functions that copy while allowing chaining cover both use cases with a single API. They are also algorithmically faster, since they don't need to search for -the terminating null byte of the existing string. +the terminating null character of the existing string. However, functions that catenate have a much simpler use, so if performance is not important, it can make sense to use them for improving readability. -.PP +.P The pointer returned by functions that allow chaining is a byproduct of the copy operation, so it has no performance costs. @@ -180,7 +176,7 @@ have names of the form .RB * stp *(), since it's common to name the pointer just .IR p . -.PP +.P Chain-copying functions that truncate should accept a pointer to the end of the destination buffer, and have names of the form @@ -191,14 +187,14 @@ This allows not having to recalculate the remaining size after each call. The first thing to note is that programmers should be careful with buffers, so they always have the correct size, and truncation is not necessary. -.PP +.P In most cases, truncation is not desired, and it is simpler to just do the copy. Simpler code is safer code. Programming against programming mistakes by adding more code just adds more points where mistakes can be made. -.PP +.P Nowadays, compilers can detect most programmer errors with features like compiler warnings, @@ -208,22 +204,25 @@ static analyzers, and .BR ftm (7)). Keeping the code simple helps these overflow-detection features be more precise. -.PP +.P When validating user input, +code should normally not truncate, +but instead fail and prevent the copy at all. +.P +In some cases, however, it makes sense to truncate. -Remember to check the return value of such function calls. -.PP +.P Functions that truncate: .IP \[bu] 3 -.BR stpecpy (3) -is the most efficient string copy function that performs truncation. -It only requires to check for truncation once after all chained calls. +.BR stpecpy () +.IP \[bu] +.BR strtcpy () .IP \[bu] .BR strlcpy (3bsd) and .BR strlcat (3bsd) -are similar, but less efficient when chained. +are similar, but have important performance problems; see BUGS. .IP \[bu] .BR stpncpy (3) and @@ -233,30 +232,29 @@ but rather null-padded character sequences. .\" ----- DESCRIPTION :: Null-padded character sequences --------------/ .SS Null-padded character sequences For historic reasons, -some standard APIs, +some standard APIs and file formats, such as -.BR utmpx (5), -use null-padded character sequences in fixed-width buffers. +.BR utmpx (5) +and +.BR tar (1), +use null-padded character sequences in fixed-size buffers. To interface with them, specialized functions need to be used. -.PP -To copy strings into them, use -.BR stpncpy (3). -.PP -To copy from an unterminated string within a fixed-width buffer into a string, -ignoring any trailing null bytes in the source fixed-width buffer, -you should use -.BR zustr2stp (3) +.P +To copy bytes from strings into these buffers, use +.BR strncpy (3) or -.BR strncat (3). -.PP -To copy from an unterminated string within a fixed-width buffer -into a character sequence, -ignoring any trailing null bytes in the source fixed-width buffer, -you should use -.BR zustr2ustp (3). -.\" ----- DESCRIPTION :: Measured character sequences -----------------/ -.SS Measured character sequences +.BR stpncpy (3). +.P +To read a null-padded character sequence, +use +.IR "strnlen(src,\ NITEMS(src))" , +and then you can treat it as a known-length character sequence; +or use +.BR strncat (3) +directly. +.\" ----- DESCRIPTION :: Known-length character sequences -----------------/ +.SS Known-length character sequences The simplest character sequence copying function is .BR mempcpy (3). It requires always knowing the length of your character sequences, @@ -266,39 +264,34 @@ since you always know the length of your character sequences, and can do the minimal copies and length measurements. .BR mempcpy (3) copies character sequences, -so you need to explicitly set the terminating null byte if you need a string. -.PP -However, -for keeping type safety, -it's good to add a wrapper that uses -.I char\~* -instead of -.IR void\~* : -.BR ustpcpy (3). -.PP +so you need to explicitly set the terminating null character +if you need a string. +.P In programs that make considerable use of strings or character sequences, and need the best performance, using overlapping character sequences can make a big difference. It allows holding subsequences of a larger character sequence, while not duplicating memory nor using time to do a copy. -.PP +.P However, this is delicate, since it requires using character sequences. C library APIs use strings, so programs that use character sequences will have to take care of differentiating strings from character sequences. -.PP -To copy a measured character sequence, use -.BR ustpcpy (3). -.PP -To copy a measured character sequence into a string, use -.BR ustr2stp (3). -.PP -Because these functions ask for the length, -and a string is by nature composed of a character sequence of the same length -plus a terminating null byte, -a string is also accepted as input. +.P +To copy a known-length character sequence, use +.BR mempcpy (3). +.P +To copy a known-length character sequence into a string, use +.IR "\%stpcpy(mempcpy(dst,\ src,\ len),\ \[dq]\[dq])" . +.P +A string is also accepted as input, +because +.BR mempcpy (3) +asks for the length, +and a string is composed of a character sequence of the same length +plus a terminating null character. .\" ----- DESCRIPTION :: String vs character sequence -----------------/ .SS String vs character sequence Some functions only operate on strings. @@ -319,12 +312,14 @@ List of functions: .BR strcpy (3), .BR strcat (3) .IP \[bu] -.BR stpecpy (3) +.BR stpecpy () +.IP \[bu] +.BR strtcpy () .IP \[bu] .BR strlcpy (3bsd), .BR strlcat (3bsd) .PD -.PP +.P Other functions require an input string, but create a character sequence as output. These functions have confusing names, @@ -336,7 +331,7 @@ List of functions: .IP \[bu] .BR strncpy (3) .PD -.PP +.P Other functions operate on an input character sequence, and create an output string. Functions that catenate @@ -347,29 +342,19 @@ holds a string before the call. has an even more misleading name than the functions above. List of functions: .IP \[bu] 3 -.PD 0 -.BR zustr2stp (3) -.IP \[bu] .BR strncat (3) -.IP \[bu] -.BR ustr2stp (3) -.PD -.PP +.P Other functions operate on an input character sequence to create an output character sequence. List of functions: .IP \[bu] 3 -.PD 0 -.BR ustpcpy (3) -.IP \[bu] -.BR zustr2stp (3) -.PD +.BR mempcpy (3) .\" ----- DESCRIPTION :: Functions :: ---------------------------------/ .SS Functions .\" ----- DESCRIPTION :: Functions :: stpcpy(3) -----------------------/ .TP .BR stpcpy (3) -This function copies the input string into a destination string. +Copy the input string into a destination string. The programmer is responsible for allocating a buffer large enough. It returns a pointer suitable for chaining. .\" ----- DESCRIPTION :: Functions :: strcpy(3), strcat(3) ------------/ @@ -377,16 +362,16 @@ It returns a pointer suitable for chaining. .BR strcpy (3) .TQ .BR strcat (3) -These functions copy and catenate the input string into a destination string. +Copy and catenate the input string into a destination string. The programmer is responsible for allocating a buffer large enough. The return value is useless. .IP .BR stpcpy (3) is a faster alternative to these functions. -.\" ----- DESCRIPTION :: Functions :: stpecpy(3) ----------------------/ +.\" ----- DESCRIPTION :: Functions :: stpecpy() -----------------------/ .TP -.BR stpecpy (3) -This function copies the input string into a destination string. +.BR stpecpy () +Chain-copy the input string into a destination string. If the destination buffer, limited by a pointer to its end, isn't large enough to hold the copy, @@ -397,12 +382,24 @@ Truncation needs to be detected only once after the last chained call. .IP This function is not provided by any library; see EXAMPLES for a reference implementation. +.\" ----- DESCRIPTION :: Functions :: strtcpy() -----------------------/ +.TP +.BR strtcpy () +Copy the input string into a destination string. +If the destination buffer isn't large enough to hold the copy, +the resulting string is truncated +(but it is guaranteed to be null-terminated). +It returns the length of the string, +or \-1 if it truncated. +.IP +This function is not provided by any library; +see EXAMPLES for a reference implementation. .\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ .TP .BR strlcpy (3bsd) .TQ .BR strlcat (3bsd) -These functions copy and catenate the input string into a destination string. +Copy and catenate the input string into a destination string. If the destination buffer, limited by its size, isn't large enough to hold the copy, @@ -410,19 +407,23 @@ the resulting string is truncated (but it is guaranteed to be null-terminated). They return the length of the total string they tried to create. .IP -.BR stpecpy (3) -is a simpler alternative to these functions. +Check BUGS before using these functions. +.IP +.BR strtcpy () +and +.BR stpecpy () +are better alternatives to these functions. .\" ----- DESCRIPTION :: Functions :: stpncpy(3) ----------------------/ .TP .BR stpncpy (3) -This function copies the input string into -a destination null-padded character sequence in a fixed-width buffer. +Copy the input string into +a destination null-padded character sequence in a fixed-size buffer. If the destination buffer, limited by its size, isn't large enough to hold the copy, the resulting character sequence is truncated. Since it creates a character sequence, -it doesn't need to write a terminating null byte. +it doesn't need to write a terminating null character. It's impossible to distinguish truncation by the result of the call, from a character sequence that just fits the destination buffer; truncation should be detected by @@ -437,147 +438,105 @@ except for the useless return value. .IP .BR stpncpy (3) is a more useful alternative to this function. -.\" ----- DESCRIPTION :: Functions :: zustr2ustp(3) --------------------/ -.TP -.BR zustr2ustp (3) -This function copies the input character sequence, -contained in a null-padded fixed-width buffer, -into a destination character sequence. -The programmer is responsible for allocating a buffer large enough. -It returns a pointer suitable for chaining. -.IP -A truncating version of this function doesn't exist, -since the size of the original character sequence is always known, -so it wouldn't be very useful. -.IP -This function is not provided by any library; -see EXAMPLES for a reference implementation. -.\" ----- DESCRIPTION :: Functions :: zustr2stp(3) --------------------/ +.\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ .TP -.BR zustr2stp (3) -This function copies the input character sequence, -contained in a null-padded fixed-width buffer, +.BR strncat (3) +Catenate the input character sequence, +contained in a null-padded fixed-size buffer, into a destination string. The programmer is responsible for allocating a buffer large enough. -It returns a pointer suitable for chaining. -.IP -A truncating version of this function doesn't exist, -since the size of the original character sequence is always known, -so it wouldn't be very useful. +The return value is useless. .IP -This function is not provided by any library; -see EXAMPLES for a reference implementation. -.\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ -.TP -.BR strncat (3) Do not confuse this function with .BR strncpy (3); they are not related at all. .IP -This function catenates the input character sequence, -contained in a null-padded fixed-width buffer, -into a destination string. -The programmer is responsible for allocating a buffer large enough. -The return value is useless. -.IP -.BR zustr2stp (3) +.I \%stpcpy(mempcpy(dst,\ src,\ strnlen(src,\ NITEMS(src))),\ \[dq]\[dq]) is a faster alternative to this function. -.\" ----- DESCRIPTION :: Functions :: ustpcpy(3) ----------------------/ +.\" ----- DESCRIPTION :: Functions :: mempcpy(3) ----------------------/ .TP -.BR ustpcpy (3) -This function copies the input character sequence, +.BR mempcpy (3) +Copy the input character sequence, limited by its length, into a destination character sequence. The programmer is responsible for allocating a buffer large enough. It returns a pointer suitable for chaining. -.\" ----- DESCRIPTION :: Functions :: ustr2stp(3) ---------------------/ -.TP -.BR ustr2stp (3) -This function copies the input character sequence, -limited by its length, -into a destination string. -The programmer is responsible for allocating a buffer large enough. -It returns a pointer suitable for chaining. .\" ----- RETURN VALUE :: ---------------------------------------------/ .SH RETURN VALUE -The following functions return -a pointer to the terminating null byte in the destination string. -.IP \[bu] 3 -.PD 0 +.TP .BR stpcpy (3) -.IP \[bu] -.BR ustr2stp (3) -.IP \[bu] -.BR zustr2stp (3) -.PD -.PP -The following function returns -a pointer to the terminating null byte in the destination string, -except when truncation occurs; -if truncation occurs, -it returns a pointer to the end of the destination buffer. -.IP \[bu] 3 -.BR stpecpy (3) -.PP -The following function returns -a pointer to one after the last character -in the destination character sequence; -if truncation occurs, -that pointer is equivalent to -a pointer to the end of the destination buffer. -.IP \[bu] 3 +A pointer to the terminating null character in the destination string. +.TP +.BR stpecpy () +A pointer to the terminating null character in the destination string, +on success. +On error, +NULL is returned, +and +.I errno +is set to indicate the error. +.TP +.BR mempcpy (3) +.TQ .BR stpncpy (3) -.PP -The following functions return -a pointer to one after the last character +A pointer to one after the last character in the destination character sequence. -.IP \[bu] 3 -.PD 0 -.BR zustr2ustp (3) -.IP \[bu] -.BR ustpcpy (3) -.PD -.PP -The following functions return -the length of the total string that they tried to create -(as if truncation didn't occur). -.IP \[bu] 3 -.BR strlcpy (3bsd), +.TP +.BR strtcpy () +The length of the string, +on success. +On error, +\-1 is returned, +and +.I errno +is set to indicate the error. +.TP +.BR strlcpy (3bsd) +.TQ .BR strlcat (3bsd) -.PP -The following functions return the -.I dst -pointer, -which is useless. -.IP \[bu] 3 -.PD 0 -.BR strcpy (3), +The length of the total string that they tried to create +(as if truncation didn't occur). +.TP +.BR strcpy (3) +.TQ .BR strcat (3) -.IP \[bu] +.TQ .BR strncpy (3) -.IP \[bu] +.TQ .BR strncat (3) -.PD +The +.I dst +pointer, +which is useless. +.\" ----- ERRORS ------------------------------------------------------/ +.SH ERRORS +Most of these functions don't set +.IR errno . +.TP +.BR stpecpy () +.TQ +.BR strtcpy () +.RS +.TP +.B ENOBUFS +.I dsize +was +.BR 0 . +.TP +.B E2BIG +The string has been truncated. +.RE .\" ----- NOTES :: strscpy(9) -----------------------------------------/ .SH NOTES The Linux kernel has an internal function for copying strings, -which is similar to -.BR stpecpy (3), -except that it can't be chained: -.TP -.BR strscpy (9) -This function copies the input string into a destination string. -If the destination buffer, -limited by its size, -isn't large enough to hold the copy, -the resulting string is truncated -(but it is guaranteed to be null-terminated). -It returns the length of the destination string, or +.BR strscpy (9), +which is identical to +.BR strtcpy (), +except that it returns .B \-E2BIG -on truncation. -.IP -.BR stpecpy (3) -is a simpler and faster alternative to this function. +instead of \-1 +and it doesn't set +.IR errno . .\" ----- CAVEATS :: --------------------------------------------------/ .SH CAVEATS Don't mix chain calls to truncating and non-truncating functions. @@ -591,8 +550,28 @@ Calling a non-truncating function after a truncating one is necessarily wrong. .SH BUGS All catenation functions share the same performance problem: .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ -Shlemiel the painter +Shlemiel the painter .UE . +As a mitigation, +compilers are able to transform some calls to catenation functions +into normal copy functions, +since +.I strlen(dst) +is usually a byproduct of the previous copy. +.P +.BR strlcpy (3) +and +.BR strlcat (3) +need to read the entire +.I src +string, +even if the destination buffer is small. +This makes them vulnerable to Denial of Service (DoS) attacks +if an attacker can control the length of the +.I src +string. +And if not, +they're still unnecessarily slow. .\" ----- EXAMPLES :: -------------------------------------------------/ .SH EXAMPLES The following are examples of correct use of each of these functions. @@ -619,43 +598,43 @@ strcat(buf, "!"); len = strlen(buf); puts(buf); .EE -.\" ----- EXAMPLES :: stpecpy(3) --------------------------------------/ +.\" ----- EXAMPLES :: stpecpy() ---------------------------------------/ .TP -.BR stpecpy (3) +.BR stpecpy () .EX -end = buf + sizeof(buf); +end = buf + NITEMS(buf); p = buf; p = stpecpy(p, end, "Hello "); p = stpecpy(p, end, "world"); p = stpecpy(p, end, "!"); -if (p == end) { - p\-\-; +if (p == NULL) { + len = NITEMS(buf) \- 1; goto toolong; } len = p \- buf; puts(buf); .EE +.\" ----- EXAMPLES :: strtcpy() ---------------------------------------/ +.TP +.BR strtcpy () +.EX +len = strtcpy(buf, "Hello world!", NITEMS(buf)); +if (len == \-1) + goto toolong; +puts(buf); +.EE .\" ----- EXAMPLES :: strlcpy(3bsd), strlcat(3bsd) --------------------/ .TP .BR strlcpy (3bsd) .TQ .BR strlcat (3bsd) .EX -if (strlcpy(buf, "Hello ", sizeof(buf)) >= sizeof(buf)) +if (strlcpy(buf, "Hello ", NITEMS(buf)) >= NITEMS(buf)) goto toolong; -if (strlcat(buf, "world", sizeof(buf)) >= sizeof(buf)) +if (strlcat(buf, "world", NITEMS(buf)) >= NITEMS(buf)) goto toolong; -len = strlcat(buf, "!", sizeof(buf)); -if (len >= sizeof(buf)) - goto toolong; -puts(buf); -.EE -.\" ----- EXAMPLES :: strscpy(9) --------------------------------------/ -.TP -.BR strscpy (9) -.EX -len = strscpy(buf, "Hello world!", sizeof(buf)); -if (len == \-E2BIG) +len = strlcat(buf, "!", NITEMS(buf)); +if (len >= NITEMS(buf)) goto toolong; puts(buf); .EE @@ -663,43 +642,40 @@ puts(buf); .TP .BR stpncpy (3) .EX -p = stpncpy(buf, "Hello world!", sizeof(buf)); -if (sizeof(buf) < strlen("Hello world!")) +p = stpncpy(u->ut_user, "alx", NITEMS(u->ut_user)); +if (NITEMS(u->ut_user) < strlen("alx")) goto toolong; -len = p \- buf; -for (size_t i = 0; i < sizeof(buf); i++) - putchar(buf[i]); +len = p \- u->ut_user; +fwrite(u->ut_user, 1, len, stdout); .EE .\" ----- EXAMPLES :: strncpy(3) --------------------------------------/ .TP .BR strncpy (3) .EX -strncpy(buf, "Hello world!", sizeof(buf)); -if (sizeof(buf) < strlen("Hello world!")) +strncpy(u->ut_user, "alx", NITEMS(u->ut_user)); +if (NITEMS(u->ut_user) < strlen("alx")) goto toolong; -len = strnlen(buf, sizeof(buf)); -for (size_t i = 0; i < sizeof(buf); i++) - putchar(buf[i]); +len = strnlen(u->ut_user, NITEMS(u->ut_user)); +fwrite(u->ut_user, 1, len, stdout); .EE -.\" ----- EXAMPLES :: zustr2ustp(3) -----------------------------------/ +.\" ----- EXAMPLES :: mempcpy(dst, src, strnlen(src, NITEMS(src))) ----/ .TP -.BR zustr2ustp (3) +.I mempcpy(dst, src, strnlen(src, NITEMS(src))) .EX +char buf[NITEMS(u->ut_user)]; p = buf; -p = zustr2ustp(p, "Hello ", 6); -p = zustr2ustp(p, "world", 42); // Padding null bytes ignored. -p = zustr2ustp(p, "!", 1); +p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user))); len = p \- buf; -printf("%.*s\en", (int) len, buf); +fwrite(buf, 1, len, stdout); .EE -.\" ----- EXAMPLES :: zustr2stp(3) ------------------------------------/ +.\" ----- EXAMPLES :: stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), "") .TP -.BR zustr2stp (3) +.I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq]) .EX +char buf[NITEMS(u->ut_user) + 1]; p = buf; -p = zustr2stp(p, "Hello ", 6); -p = zustr2stp(p, "world", 42); // Padding null bytes ignored. -p = zustr2stp(p, "!", 1); +p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user))); +p = stpcpy(p, ""); len = p \- buf; puts(buf); .EE @@ -707,102 +683,77 @@ puts(buf); .TP .BR strncat (3) .EX -buf[0] = \[aq]\e0\[aq]; // There's no 'cpy' function to this 'cat'. -strncat(buf, "Hello ", 6); -strncat(buf, "world", 42); // Padding null bytes ignored. -strncat(buf, "!", 1); +char buf[NITEMS(u->ut_user) + 1]; +strcpy(buf, ""); +strncat(buf, u->ut_user, NITEMS(u->ut_user)); len = strlen(buf); puts(buf); .EE -.\" ----- EXAMPLES :: ustpcpy(3) --------------------------------------/ +.\" ----- EXAMPLES :: mempcpy(3) --------------------------------------/ .TP -.BR ustpcpy (3) +.BR mempcpy (3) .EX p = buf; -p = ustpcpy(p, "Hello ", 6); -p = ustpcpy(p, "world", 5); -p = ustpcpy(p, "!", 1); +p = mempcpy(p, "Hello ", 6); +p = mempcpy(p, "world", 5); +p = mempcpy(p, "!", 1); len = p \- buf; -printf("%.*s\en", (int) len, buf); +fwrite(buf, 1, len, stdout); .EE -.\" ----- EXAMPLES :: ustr2stp(3) -------------------------------------/ +.\" ----- EXAMPLES :: stpcpy(mempcpy(), "") ---------------------------/ .TP -.BR ustr2stp (3) +.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]) .EX p = buf; -p = ustr2stp(p, "Hello ", 6); -p = ustr2stp(p, "world", 5); -p = ustr2stp(p, "!", 1); +p = mempcpy(p, "Hello ", 6); +p = mempcpy(p, "world", 5); +p = mempcpy(p, "!", 1); +p = stpcpy(p, ""); len = p \- buf; puts(buf); .EE .\" ----- EXAMPLES :: Implementations :: ------------------------------/ .SS Implementations Here are reference implementations for functions not provided by libc. -.PP +.P .in +4n .EX /* This code is in the public domain. */ \& -.\" ----- EXAMPLES :: Implementations :: stpecpy(3) -------------------/ +.\" ----- EXAMPLES :: Implementations :: stpecpy() --------------------/ char * .IR stpecpy "(char *dst, char end[0], const char *restrict src)" { - char *p; + size_t dlen; \& if (dst == NULL) return NULL; - if (dst == end) - return end; -\& - p = memccpy(dst, src, \[aq]\e0\[aq], end \- dst); - if (p != NULL) - return p \- 1; \& - /* truncation detected */ - end[\-1] = \[aq]\e0\[aq]; - return end; + dlen = strtcpy(dst, src, end \- dst); + return (dlen == \-1) ? NULL : dst + dlen; } \& -.\" ----- EXAMPLES :: Implementations :: zustr2ustp(3) ----------------/ -char * -.IR zustr2ustp "(char *restrict dst, const char *restrict src, size_t sz)" +.\" ----- EXAMPLES :: Implementations :: strtcpy() --------------------/ +ssize_t +.IR strtcpy "(char *restrict dst, const char *restrict src, size_t dsize)" { - return ustpcpy(dst, src, strnlen(src, sz)); -} + bool trunc; + size_t dlen, slen; \& -.\" ----- EXAMPLES :: Implementations :: zustr2stp(3) -----------------/ -char * -.IR zustr2stp "(char *restrict dst, const char *restrict src, size_t sz)" -{ - char *p; + if (dsize == 0) { + errno = ENOBUFS; + return \-1; + } \& - p = zustr2ustp(dst, src, sz); - *p = \[aq]\e0\[aq]; + slen = strnlen(src, dsize); + trunc = (slen == dsize); + dlen = slen \- trunc; \& - return p; + stpcpy(mempcpy(dst, src, dlen), ""); + if (trunc) + errno = E2BIG; + return trunc ? \-1 : slen; } -\& -.\" ----- EXAMPLES :: Implementations :: ustpcpy(3) -------------------/ -char * -.IR ustpcpy "(char *restrict dst, const char *restrict src, size_t len)" -{ - return mempcpy(dst, src, len); -} -\& -.\" ----- EXAMPLES :: Implementations :: ustr2stp(3) ------------------/ -char * -.IR ustr2stp "(char *restrict dst, const char *restrict src, size_t len)" -{ - char *p; -\& - p = ustpcpy(dst, src, len); - *p = \[aq]\e0\[aq]; -\& - return p; -} -.EE -.in .\" ----- SEE ALSO :: -------------------------------------------------/ .SH SEE ALSO .BR bzero (3), diff --git a/man7/suffixes.7 b/man7/suffixes.7 index 5e970f4..3352a9c 100644 --- a/man7/suffixes.7 +++ b/man7/suffixes.7 @@ -14,7 +14,7 @@ .\" Modified Thu Nov 16 23:28:25 2000 by David A. Wheeler .\" <dwheeler@dwheeler.com> .\" -.TH SUFFIXES 7 2023-03-17 "Linux man-pages 6.05.01" +.TH SUFFIXES 7 2023-10-31 "Linux man-pages 6.7" .SH NAME suffixes \- list of file suffixes .SH DESCRIPTION @@ -25,10 +25,10 @@ file they are dealing with. The .BR make (1) utility is driven by rules based on file suffix. -.PP +.P Following is a list of suffixes which are likely to be found on a Linux system. -.PP +.P .TS l | l _ | _ diff --git a/man7/symlink.7 b/man7/symlink.7 index 9c238b2..737bb1f 100644 --- a/man7/symlink.7 +++ b/man7/symlink.7 @@ -10,14 +10,14 @@ .\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and heavily edited for .\" specific Linux details, improved readability, and man-pages style. .\" -.TH symlink 7 2023-04-03 "Linux man-pages 6.05.01" +.TH symlink 7 2023-10-31 "Linux man-pages 6.7" .SH NAME symlink \- symbolic link handling .SH DESCRIPTION Symbolic links are files that act as pointers to other files. To understand their behavior, you must first understand how hard links work. -.PP +.P A hard link to a file is indistinguishable from the original file because it is a reference to the object underlying the original filename. (To be precise: each of the hard links to a file is a reference to @@ -33,7 +33,7 @@ Hard links may not refer to directories which would confuse many programs) and may not refer to files on different filesystems (because inode numbers are not unique across filesystems). -.PP +.P A symbolic link is a special type of file whose contents are a string that is the pathname of another file, the file to which the link refers. (The contents of a symbolic link can be read using @@ -42,13 +42,13 @@ In other words, a symbolic link is a pointer to another name, and not to an underlying object. For this reason, symbolic links may refer to directories and may cross filesystem boundaries. -.PP +.P There is no requirement that the pathname referred to by a symbolic link should exist. A symbolic link that refers to a pathname that does not exist is said to be a .IR "dangling link" . -.PP +.P Because a symbolic link and its referenced object coexist in the filesystem name space, confusion can arise in distinguishing between the link itself and the referenced object. @@ -76,7 +76,7 @@ representation of a file handle. As such, these magic links allow users to access files which cannot be referenced with normal paths (such as unlinked files still referenced by a running program ). -.PP +.P Because they can bypass ordinary .BR mount_namespaces (7)-based restrictions, @@ -94,22 +94,22 @@ and when the .I fs.protected_symlinks sysctl is set (see .BR proc (5)). -.PP +.P The last access and last modification timestamps of a symbolic link can be changed using .BR utimensat (2) or .BR lutimes (3). -.PP +.P .\" Linux does not currently implement an lchmod(2). On Linux, the permissions of an ordinary symbolic link are not used in any operations; the permissions are always 0777 (read, write, and execute for all user categories), and can't be changed. -.PP +.P However, magic links do not follow this rule. They can have a non-0777 mode, though this mode is not currently used in any permission checks. -.\" .PP +.\" .P .\" The .\" 4.4BSD .\" system differs from historical @@ -140,7 +140,7 @@ and .BR readlinkat (2), in order to operate on the symbolic link itself (rather than the file to which it refers). -.PP +.P By default (i.e., if the .B AT_SYMLINK_FOLLOW @@ -171,7 +171,7 @@ or a loop is detected. (Loop detection is done by placing an upper limit on the number of links that may be followed, and an error results if this limit is exceeded.) -.PP +.P There are three separate areas that need to be discussed. They are as follows: .IP \[bu] 3 @@ -183,7 +183,7 @@ are not traversing a file tree. 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). -.PP +.P Before describing the treatment of symbolic links by system calls and commands, we require some terminology. Given a pathname of the form @@ -201,7 +201,7 @@ component. .SS Treatment of symbolic links in system calls The first area is symbolic links used as filename arguments for system calls. -.PP +.P The treatment of symbolic links within a pathname passed to a system call is as follows: .IP (1) 5 @@ -224,7 +224,7 @@ the system call .I "open(""slink"" ...\&)" would return a file descriptor referring to the file .IR afile . -.PP +.P Various system calls do not follow links in the basename component of a pathname, and operate on the symbolic link itself. @@ -240,7 +240,7 @@ They are: .BR rmdir (2), and .BR unlink (2). -.PP +.P Certain other system calls optionally follow symbolic links in the basename component of a pathname. They are: @@ -265,7 +265,7 @@ When .BR rmdir (2) is applied to a symbolic link, it fails with the error .BR ENOTDIR . -.PP +.P .BR link (2) warrants special discussion. POSIX.1-2001 specifies that @@ -282,7 +282,7 @@ either behavior in an implementation. .SS Commands not traversing a file tree The second area is symbolic links, specified as command-line filename arguments, to commands which are not traversing a file tree. -.PP +.P Except as noted below, commands follow symbolic links named as command-line arguments. For example, if there were a symbolic link @@ -293,7 +293,7 @@ the command .I "cat slink" would display the contents of the file .IR afile . -.PP +.P It is important to realize that this rule includes commands which may optionally traverse file trees; for example, the command .I "chown file" @@ -301,7 +301,7 @@ is included in this rule, while the command .IR "chown\ \-R file" , which performs a tree traversal, is not. (The latter is described in the third area, below.) -.PP +.P If it is explicitly intended that the command operate on the symbolic link instead of following the symbolic link\[em]for example, it is desired that .I "chown slink" @@ -319,7 +319,7 @@ while would change the ownership of .I slink itself. -.PP +.P There are some exceptions to this rule: .IP \[bu] 3 The @@ -392,16 +392,16 @@ The following commands either optionally or always traverse file trees: .BR rm (1), and .BR tar (1). -.PP +.P It is important to realize that the following rules apply equally to symbolic links encountered during the file tree traversal and symbolic links listed as command-line arguments. -.PP +.P The \fIfirst rule\fP applies to symbolic links that reference files other than directories. Operations that apply to symbolic links are performed on the links themselves, but otherwise the links are ignored. -.PP +.P The command .I "rm\ \-r slink directory" will remove @@ -413,12 +413,12 @@ In no case will .BR rm (1) affect the file referred to by .IR slink . -.PP +.P The \fIsecond rule\fP applies to symbolic links that refer to directories. Symbolic links that refer to directories are never followed by default. This is often referred to as a "physical" walk, as opposed to a "logical" walk (where symbolic links that refer to directories are followed). -.PP +.P Certain conventions are (should be) followed as consistently as possible by commands that perform file tree walks: .IP \[bu] 3 @@ -486,7 +486,7 @@ provide the default behavior by specifying the (for "physical") flag. This flag is intended to make the entire name space look like the physical name space. -.PP +.P For commands that do not by default do file tree traversals, the .IR \-H , .IR \-L , @@ -504,7 +504,7 @@ options more than once; the last one specified determines the command's behavior. This is intended to permit you to alias commands to behave one way or the other, and then override that behavior on the command line. -.PP +.P The .BR ls (1) and diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 index c4b3925..f79b65d 100644 --- a/man7/system_data_types.7 +++ b/man7/system_data_types.7 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH system_data_types 7 2023-05-20 "Linux man-pages 6.05.01" +.TH system_data_types 7 2023-10-31 "Linux man-pages 6.7" .SH NAME system_data_types \- overview of system data types .SH DESCRIPTION @@ -62,53 +62,6 @@ system_data_types \- overview of system data types .\"------------------------------------- regmatch_t -------------------/ .\"------------------------------------- regoff_t ---------------------/ .\"------------------------------------- sigevent ---------------------/ -.TP -.I sigevent -.RS -.IR Include : -.IR <signal.h> . -Alternatively, -.IR <aio.h> , -.IR <mqueue.h> , -or -.IR <time.h> . -.PP -.EX -struct sigevent { - int sigev_notify; /* Notification type */ - int sigev_signo; /* Signal number */ - union sigval sigev_value; /* Signal value */ - void (*sigev_notify_function)(union sigval); - /* Notification function */ - pthread_attr_t *sigev_notify_attributes; - /* Notification attributes */ -}; -.EE -.PP -For further details about this type, see -.BR sigevent (7). -.PP -.IR Versions : -.I <aio.h> -and -.I <time.h> -define -.I sigevent -since POSIX.1-2008. -.PP -.IR "Conforming to" : -POSIX.1-2001 and later. -.PP -.IR "See also" : -.BR timer_create (2), -.BR getaddrinfo_a (3), -.BR lio_listio (3), -.BR mq_notify (3) -.PP -See also the -.I aiocb -structure in this page. -.RE .\"------------------------------------- siginfo_t --------------------/ .TP .I siginfo_t @@ -117,27 +70,27 @@ structure in this page. .IR <signal.h> . Alternatively, .IR <sys/wait.h> . -.PP +.P .EX typedef struct { int si_signo; /* Signal number */ int si_code; /* Signal code */ pid_t si_pid; /* Sending process ID */ uid_t si_uid; /* Real user ID of sending process */ - void *si_addr; /* Address of faulting instruction */ + void *si_addr; /* Memory location which caused fault */ int si_status; /* Exit value or signal */ union sigval si_value; /* Signal value */ } siginfo_t; .EE -.PP +.P Information associated with a signal. For further details on this structure (including additional, Linux-specific fields), see .BR sigaction (2). -.PP +.P .IR "Conforming to" : POSIX.1-2001 and later. -.PP +.P .IR "See also" : .BR pidfd_send_signal (2), .BR rt_sigqueueinfo (2), @@ -155,13 +108,13 @@ Alternatively, .IR <spawn.h> , or .IR <sys/select.h> . -.PP +.P This is a type that represents a set of signals. According to POSIX, this shall be an integer or structure type. -.PP +.P .IR "Conforming to" : POSIX.1-2001 and later. -.PP +.P .IR "See also" : .BR epoll_pwait (2), .BR ppoll (2), @@ -175,37 +128,6 @@ POSIX.1-2001 and later. .BR signal (7) .RE .\"------------------------------------- sigval -----------------------/ -.TP -.I sigval -.RS -.IR Include : -.IR <signal.h> . -.PP -.EX -union sigval { - int sival_int; /* Integer value */ - void *sival_ptr; /* Pointer value */ -}; -.EE -.PP -Data passed with a signal. -.PP -.IR "Conforming to" : -POSIX.1-2001 and later. -.PP -.IR "See also" : -.BR pthread_sigqueue (3), -.BR sigqueue (3), -.BR sigevent (7) -.PP -See also the -.I sigevent -structure -and the -.I siginfo_t -type -in this page. -.RE .\"------------------------------------- size_t -----------------------/ .\"------------------------------------- sockaddr ---------------------/ .\"------------------------------------- socklen_t --------------------/ @@ -227,7 +149,7 @@ in this page. .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. -.PP +.P Most of the integer types described in this page don't have a corresponding length modifier for the .BR printf (3) @@ -258,7 +180,7 @@ In "Conforming to" we only concern ourselves with C99 and later and POSIX.1-2001 and later. Some types may be specified in earlier versions of one of these standards, but in the interests of simplicity we omit details from earlier standards. -.PP +.P In "Include", we first note the "primary" header(s) that define the type according to either the C or POSIX.1 standards. Under "Alternatively", we note additional headers that @@ -270,7 +192,7 @@ The appropriate conversions from and to .IR intmax_t , and the appropriate range checks, are used as explained in the notes section above. -.PP +.P .EX #include <stdint.h> #include <stdio.h> diff --git a/man7/sysvipc.7 b/man7/sysvipc.7 index 307292c..11c08ab 100644 --- a/man7/sysvipc.7 +++ b/man7/sysvipc.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sysvipc 7 2022-10-30 "Linux man-pages 6.05.01" +.TH sysvipc 7 2023-10-31 "Linux man-pages 6.7" .SH NAME sysvipc \- System V interprocess communication mechanisms .SH DESCRIPTION @@ -16,7 +16,7 @@ Each message can have an associated priority. POSIX message queues provide an alternative API for achieving the same result; see .BR mq_overview (7). -.PP +.P The System V message queue API consists of the following system calls: .TP .BR msgget (2) @@ -39,7 +39,7 @@ each semaphore in a set is a counting semaphore. POSIX semaphores provide an alternative API for achieving the same result; see .BR sem_overview (7). -.PP +.P The System V semaphore API consists of the following system calls: .TP .BR semget (2) @@ -57,7 +57,7 @@ System V shared memory allows processes to share a region a memory (a "segment"). POSIX shared memory is an alternative API for achieving the same result; see .BR shm_overview (7). -.PP +.P The System V shared memory API consists of the following system calls: .TP .BR shmget (2) @@ -88,7 +88,7 @@ .\" commit cd8ae85299d54155702a56811b2e035e63064d3d .\" Author: Eric Dumazet <edumazet@google.com> .\" -.TH tcp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH tcp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME tcp \- TCP protocol .SH SYNOPSIS @@ -96,7 +96,7 @@ tcp \- TCP protocol .B #include <sys/socket.h> .B #include <netinet/in.h> .B #include <netinet/tcp.h> -.PP +.P .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" .fi .SH DESCRIPTION @@ -112,7 +112,7 @@ retransmits lost packets. It generates and checks a per-packet checksum to catch transmission errors. TCP does not preserve record boundaries. -.PP +.P A newly created TCP socket has no remote or local address and is not fully specified. To create an outgoing TCP connection use @@ -131,7 +131,7 @@ or .BR connect (2) successfully called on it is fully specified and may transmit data. Data cannot be transmitted on listening or not yet connected sockets. -.PP +.P Linux supports RFC\ 1323 TCP high performance extensions. These include Protection Against Wrapped @@ -151,7 +151,7 @@ and socket options with the .BR setsockopt (2) call. -.PP +.P The maximum sizes for socket buffers declared via the .B SO_SNDBUF and @@ -182,7 +182,7 @@ calls in order to have it take effect. See .BR socket (7) for more information. -.PP +.P TCP supports urgent data. Urgent data is used to signal the receiver that some important message is part of the data @@ -214,7 +214,7 @@ flag is set for .BR recv (2) or .BR recvmsg (2). -.PP +.P When out-of-band data is present, .BR select (2) indicates the file descriptor as having an exceptional condition and @@ -222,7 +222,7 @@ indicates the file descriptor as having an exceptional condition and indicates a .B POLLPRI event. -.PP +.P Linux 2.4 introduced a number of changes for improved throughput and scaling, as well as enhanced functionality. Some of these features include support for zero-copy @@ -1068,7 +1068,7 @@ most socket options are valid on TCP sockets. For more information see .BR ip (7). -.PP +.P Following is a list of TCP-specific socket options. For details of some other socket options that are also applicable for TCP sockets, see @@ -1368,19 +1368,19 @@ the stream (even when .B SO_OOBINLINE is not set). This differs from BSD-based stacks. -.PP +.P Linux uses the BSD compatible interpretation of the urgent pointer field by default. This violates RFC\ 1122, but is required for interoperability with other stacks. It can be changed via .IR /proc/sys/net/ipv4/tcp_stdurg . -.PP +.P It is possible to peek at out-of-band data using the .BR recv (2) .B MSG_PEEK flag. -.PP +.P Since Linux 2.4, Linux supports the use of .B MSG_TRUNC in the @@ -1402,14 +1402,14 @@ The following calls return information in .IR value . The correct syntax is: -.PP +.P .RS .nf .BI int " value"; .IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");" .fi .RE -.PP +.P .I ioctl_type is one of the following: .TP @@ -1484,7 +1484,7 @@ When a network error occurs, TCP tries to resend the packet. If it doesn't succeed after some time, either .B ETIMEDOUT or the last received error on this connection is reported. -.PP +.P Some applications require a quicker error notification. This can be enabled with the .B IPPROTO_IP @@ -1509,7 +1509,7 @@ executed on a shut down socket. .TP .B ETIMEDOUT The other end didn't acknowledge retransmitted data after some time. -.PP +.P Any errors defined for .BR ip (7) or the generic socket layer may also be returned for TCP. @@ -1522,7 +1522,7 @@ Support for forward acknowledgement (FACK), TIME_WAIT recycling, and per-connection keepalive socket options were introduced in Linux 2.3. .SH BUGS Not all errors are documented. -.PP +.P IPv6 is not described. .\" Only a single Linux kernel version is described .\" Info for 2.2 was lost. Should be added again, @@ -1544,10 +1544,10 @@ IPv6 is not described. .BR socket (2), .BR ip (7), .BR socket (7) -.PP +.P The kernel source file .IR Documentation/networking/ip\-sysctl.txt . -.PP +.P RFC\ 793 for the TCP specification. .br RFC\ 1122 for the TCP requirements and a description of the Nagle algorithm. diff --git a/man7/termio.7 b/man7/termio.7 index 08bba54..bff1d9f 100644 --- a/man7/termio.7 +++ b/man7/termio.7 @@ -4,7 +4,7 @@ .\" .\" 28 Dec 2006 - Initial Creation .\" -.TH termio 7 2022-10-30 "Linux man-pages 6.05.01" +.TH termio 7 2023-10-31 "Linux man-pages 6.7" .SH NAME termio \- System V terminal driver interface .SH DESCRIPTION @@ -15,7 +15,7 @@ This interface defined a structure used to store terminal settings, and a range of .BR ioctl (2) operations to get and set terminal attributes. -.PP +.P The .B termio interface is now obsolete: POSIX.1-1990 standardized a modified @@ -30,7 +30,7 @@ operations that existed in System V. .BR ioctl (2) was unstandardized, and its variadic third argument does not allow argument type checking.) -.PP +.P If you're looking for a page called "termio", then you can probably find most of the information that you seek in either .BR termios (3) diff --git a/man7/thread-keyring.7 b/man7/thread-keyring.7 index 524bf22..703f083 100644 --- a/man7/thread-keyring.7 +++ b/man7/thread-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH thread-keyring 7 2022-10-30 "Linux man-pages 6.05.01" +.TH thread-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME thread-keyring \- per-thread keyring .SH DESCRIPTION @@ -11,19 +11,19 @@ The thread keyring is a keyring used to anchor keys on behalf of a process. It is created only when a thread requests it. The thread keyring has the name (description) .IR _tid . -.PP +.P A special serial number value, .BR KEY_SPEC_THREAD_KEYRING , is defined that can be used in lieu of the actual serial number of the calling thread's thread keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@t\fP' can be used instead of a numeric key ID in much the same way, but as .BR keyctl (1) is a program run after forking, this is of no utility. -.PP +.P Thread keyrings are not inherited across .BR clone (2) and @@ -31,7 +31,7 @@ and and are cleared by .BR execve (2). A thread keyring is destroyed when the thread that refers to it terminates. -.PP +.P Initially, a thread does not have a thread keyring. If a thread doesn't have a thread keyring when it is accessed, then it will be created if it is to be modified; diff --git a/man7/time.7 b/man7/time.7 index ee0db5d..7259feb 100644 --- a/man7/time.7 +++ b/man7/time.7 @@ -5,7 +5,7 @@ .\" 2008-06-24, mtk: added some details about where jiffies come into .\" play; added section on high-resolution timers. .\" -.TH time 7 2023-01-22 "Linux man-pages 6.05.01" +.TH time 7 2023-10-31 "Linux man-pages 6.7" .SH NAME time \- overview of time and timers .SH DESCRIPTION @@ -16,7 +16,7 @@ either from a standard point in the past (see the description of the Epoch and calendar time below), or from some point (e.g., the start) in the life of a process .RI ( "elapsed time" ). -.PP +.P .I "Process time" is defined as the amount of CPU time used by a process. This is sometimes divided into @@ -58,7 +58,7 @@ a clock maintained by the kernel which measures time in .IR jiffies . The size of a jiffy is determined by the value of the kernel constant .IR HZ . -.PP +.P The value of .I HZ varies across kernel versions and hardware platforms. @@ -75,7 +75,7 @@ yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds. Since Linux 2.6.20, a further frequency is available: 300, a number that divides evenly for the common video frame rates (PAL, 25 Hz; NTSC, 30 Hz). -.PP +.P The .BR times (2) system call is a special case. @@ -99,7 +99,7 @@ The values of certain clocks are virtualized by time namespaces; see .SS High-resolution timers Before Linux 2.6.21, the accuracy of timer and sleep system calls (see below) was also limited by the size of the jiffy. -.PP +.P Since Linux 2.6.21, Linux supports high-resolution timers (HRTs), optionally configurable via .BR CONFIG_HIGH_RES_TIMERS . @@ -112,14 +112,14 @@ checking the resolution returned by a call to .BR clock_getres (2) or looking at the "resolution" entries in .IR /proc/timer_list . -.PP +.P HRTs are not supported on all hardware architectures. (Support is provided on x86, ARM, and PowerPC, among others.) .SS The Epoch UNIX systems represent time in seconds since the .IR Epoch , 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P A program can determine the .I "calendar time" via the @@ -159,7 +159,7 @@ Various system calls and functions allow a program to sleep .BR clock_nanosleep (2), and .BR sleep (3). -.PP +.P Various system calls allow a process to set a timer that expires at some point in the future, and optionally at repeated intervals; see diff --git a/man7/time_namespaces.7 b/man7/time_namespaces.7 index 6e29996..4c85001 100644 --- a/man7/time_namespaces.7 +++ b/man7/time_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH time_namespaces 7 2023-03-12 "Linux man-pages 6.05.01" +.TH time_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME time_namespaces \- overview of Linux time namespaces .SH DESCRIPTION @@ -23,7 +23,7 @@ described by POSIX\[em]"some unspecified point in the past". a nonsettable clock that is identical to .BR CLOCK_MONOTONIC , except that it also includes any time that the system is suspended. -.PP +.P Thus, the processes in a time namespace share per-namespace values for these clocks. This affects various APIs that measure against these clocks, including: @@ -34,7 +34,7 @@ This affects various APIs that measure against these clocks, including: .BR timerfd_settime (2), and .IR /proc/uptime . -.PP +.P Currently, the only way to create a time namespace is by calling .BR unshare (2) with the @@ -66,13 +66,13 @@ These offsets are exposed via the file Within this file, the offsets are expressed as lines consisting of three space-delimited fields: -.PP +.P .in +4n .EX <clock-id> <offset-secs> <offset-nanosecs> .EE .in -.PP +.P The .I clock-id is a string that identifies the clock whose offsets are being shown. @@ -93,11 +93,11 @@ The value can be negative, subject to restrictions noted below; .I offset-nanosecs is an unsigned value. -.PP +.P In the initial time namespace, the contents of the .I timens_offsets file are as follows: -.PP +.P .in +4n .EX $ \fBcat /proc/self/timens_offsets\fP @@ -105,7 +105,7 @@ monotonic 0 0 boottime 0 0 .EE .in -.PP +.P In a new time namespace that has had no member processes, the clock offsets can be modified by writing newline-terminated records of the same form to the @@ -121,7 +121,7 @@ In order to write to the file, a process must have the .B CAP_SYS_TIME capability in the user namespace that owns the time namespace. -.PP +.P Writes to the .I timens_offsets file can fail with the following errors: @@ -158,7 +158,7 @@ inside the namespace would exceed half of the value of the kernel constant .B KTIME_SEC_MAX (this limits the clock value to a maximum of approximately 146 years). .RE -.PP +.P In a new time namespace created by .BR unshare (2), the contents of the @@ -168,13 +168,13 @@ file are inherited from the time namespace of the creating process. Use of time namespaces requires a kernel that is configured with the .B CONFIG_TIME_NS option. -.PP +.P Note that time namespaces do not virtualize the .B CLOCK_REALTIME clock. Virtualization of this clock was avoided for reasons of complexity and overhead within the kernel. -.PP +.P For compatibility with the initial implementation, when writing a .I clock-id to the @@ -185,7 +185,7 @@ instead of the symbolic names show above; i.e., 1 instead of and 7 instead of .IR boottime . For readability, the use of the symbolic names over the numbers is preferred. -.PP +.P The motivation for adding time namespaces was to allow the monotonic and boot-time clocks to maintain consistent values during container migration and checkpoint/restore. @@ -193,14 +193,14 @@ during container migration and checkpoint/restore. The following shell session demonstrates the operation of time namespaces. We begin by displaying the inode number of the time namespace of a shell in the initial time namespace: -.PP +.P .in +4n .EX $ \fBreadlink /proc/$$/ns/time\fP time:[4026531834] .EE .in -.PP +.P Continuing in the initial time namespace, we display the system uptime using .BR uptime (1) and use the @@ -208,7 +208,7 @@ and use the example program shown in .BR clock_getres (2) to display the values of various clocks: -.PP +.P .in +4n .EX $ \fBuptime \-\-pretty\fP @@ -220,7 +220,7 @@ CLOCK_MONOTONIC: 56338.247 (15h 38m 58s) CLOCK_BOOTTIME : 76633.544 (21h 17m 13s) .EE .in -.PP +.P We then use .BR unshare (1) to create a time namespace and execute a @@ -236,7 +236,7 @@ clock forward 2 days and the offset for the .B CLOCK_BOOTTIME clock forward 7 days: -.PP +.P .in +4n .EX $ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP @@ -244,7 +244,7 @@ ns2# \fBecho "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets\fP ns2# \fBecho "boottime $((7*24*60*60)) 0" > /proc/$$/timens_offsets\fP .EE .in -.PP +.P Above, we started the .BR bash (1) shell with the @@ -254,7 +254,7 @@ This ensures that no child processes are created from the shell before we have a chance to update the .I timens_offsets file. -.PP +.P We then use .BR cat (1) to display the contents of the @@ -266,7 +266,7 @@ creates the first process in the new time namespace, after which further attempts to update the .I timens_offsets file produce an error. -.PP +.P .in +4n .EX ns2# \fBcat /proc/$$/timens_offsets\fP @@ -276,13 +276,13 @@ ns2# \fBecho "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets\fP bash: echo: write error: Permission denied .EE .in -.PP +.P Continuing in the new namespace, we execute .BR uptime (1) and the .I clock_times example program: -.PP +.P .in +4n .EX ns2# \fBuptime \-\-pretty\fP @@ -294,17 +294,17 @@ CLOCK_MONOTONIC: 229193.332 (2 days + 15h 39m 53s) CLOCK_BOOTTIME : 681488.629 (7 days + 21h 18m 8s) .EE .in -.PP +.P From the above output, we can see that the monotonic and boot-time clocks have different values in the new time namespace. -.PP +.P Examining the .IR /proc/ pid /ns/time and .IR /proc/ pid /ns/time_for_children symbolic links, we see that the shell is a member of the initial time namespace, but its children are created in the new namespace. -.PP +.P .in +4n .EX ns2# \fBreadlink /proc/$$/ns/time\fP @@ -315,13 +315,13 @@ ns2# \fBreadlink /proc/self/ns/time\fP # Creates a child process time:[4026532900] .EE .in -.PP +.P Returning to the shell in the initial time namespace, we see that the monotonic and boot-time clocks are unaffected by the .I timens_offsets changes that were made in the other time namespace: -.PP +.P .in +4n .EX $ \fBuptime \-\-pretty\fP @@ -4,7 +4,7 @@ .\" .\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ .\" -.TH udp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH udp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME udp \- User Datagram Protocol for IPv4 .SH SYNOPSIS @@ -12,7 +12,7 @@ udp \- User Datagram Protocol for IPv4 .B #include <sys/socket.h> .B #include <netinet/in.h> .B #include <netinet/udp.h> -.PP +.P .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" .fi .SH DESCRIPTION @@ -21,7 +21,7 @@ described in RFC\ 768. It implements a connectionless, unreliable datagram packet service. Packets may be reordered or duplicated before they arrive. UDP generates and checks checksums to catch transmission errors. -.PP +.P When a UDP socket is created, its local and remote addresses are unspecified. Datagrams can be sent immediately using @@ -50,7 +50,7 @@ a free local port out of the range defined by .I /proc/sys/net/ipv4/ip_local_port_range and bind the socket to .BR INADDR_ANY . -.PP +.P All receive operations return only one packet. When the packet is smaller than the passed buffer, only that much data is returned; when it is bigger, the packet is truncated and the @@ -58,7 +58,7 @@ data is returned; when it is bigger, the packet is truncated and the flag is set. .B MSG_WAITALL is not supported. -.PP +.P IP options may be sent or received using the socket options described in .BR ip (7). They are processed by the kernel only when the appropriate @@ -67,12 +67,12 @@ parameter is enabled (but still passed to the user even when it is turned off). See .BR ip (7). -.PP +.P When the .B MSG_DONTROUTE flag is set on sending, the destination address must refer to a local interface address and the packet is sent only to that interface. -.PP +.P By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery. This means the kernel will keep track of the MTU to a specific target IP address and return @@ -106,7 +106,7 @@ This behavior differs from many other BSD socket implementations which don't pass any errors unless the socket is connected. Linux's behavior is mandated by .BR RFC\ 1122 . -.PP +.P For compatibility with legacy code, in Linux 2.0 and 2.2 it was possible to set the .B SO_BSDCOMPAT @@ -120,7 +120,7 @@ Locally generated errors are always passed. Support for this socket option was removed in later kernels; see .BR socket (7) for further information. -.PP +.P When the .B IP_RECVERR option is enabled, all errors are stored in the socket error queue, @@ -181,7 +181,7 @@ Unless otherwise noted, .I optval is a pointer to an .IR int . -.PP +.P Following is a list of UDP-specific socket options. For details of some other socket options that are also applicable for UDP sockets, see @@ -246,7 +246,7 @@ This option should not be used in code intended to be portable. These ioctls can be accessed using .BR ioctl (2). The correct syntax is: -.PP +.P .RS .nf .BI int " value"; @@ -275,7 +275,7 @@ to distinguish these cases. .BR TIOCOUTQ " (" SIOCOUTQ ) Returns the number of data bytes in the local send queue. Supported only with Linux 2.4 and above. -.PP +.P In addition, all ioctls documented in .BR ip (7) and @@ -301,10 +301,10 @@ is a new feature in Linux 2.2. .BR raw (7), .BR socket (7), .BR udplite (7) -.PP +.P The kernel source file .IR Documentation/networking/ip\-sysctl.txt . -.PP +.P RFC\ 768 for the User Datagram Protocol. .br RFC\ 1122 for the host requirements. diff --git a/man7/udplite.7 b/man7/udplite.7 index 36a2db8..4ba4266 100644 --- a/man7/udplite.7 +++ b/man7/udplite.7 @@ -4,7 +4,7 @@ .\" .\" $Id: udplite.7,v 1.12 2008/07/23 15:22:22 gerrit Exp gerrit $ .\" -.TH udplite 7 2023-02-10 "Linux man-pages 6.05.01" +.TH udplite 7 2023-10-31 "Linux man-pages 6.7" .SH NAME udplite \- Lightweight User Datagram Protocol .SH SYNOPSIS @@ -13,25 +13,25 @@ udplite \- Lightweight User Datagram Protocol .\" FIXME . see #defines under `BUGS', .\" when glibc supports this, add .\" #include <netinet/udplite.h> -.PP +.P .B sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE); .fi .SH DESCRIPTION This is an implementation of the Lightweight User Datagram Protocol (UDP-Lite), as described in RFC\ 3828. -.PP +.P UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length checksums. This has advantages for some types of multimedia transport that may be able to make use of slightly damaged datagrams, rather than having them discarded by lower-layer protocols. -.PP +.P The variable-length checksum coverage is set via a .BR setsockopt (2) option. If this option is not set, the only difference from UDP is in using a different IP protocol identifier (IANA number 136). -.PP +.P The UDP-Lite implementation is a full extension of .BR udp (7)\[em]that is, it shares the same API and API behavior, and in addition @@ -58,7 +58,7 @@ socket options are valid on a UDP-Lite socket. See .BR udp (7) for more information. -.PP +.P The following two options are specific to UDP-Lite. .TP .B UDPLITE_SEND_CSCOV @@ -93,7 +93,7 @@ exceeds the actual packet coverage, incoming packets are silently dropped, but may generate a warning message in the system log. .\" SO_NO_CHECK exists and is supported by UDPv4, but is .\" commented out in socket(7), hence also commented out here -.\".PP +.\".P .\"Since UDP-Lite mandates checksums, checksumming can not be disabled .\"via the .\".B SO_NO_CHECK @@ -116,7 +116,7 @@ UDP-Litev4/v6 first appeared in Linux 2.6.20. .SH BUGS .\" FIXME . remove this section once glibc supports UDP-Lite Where glibc support is missing, the following definitions are needed: -.PP +.P .in +4n .EX #define IPPROTO_UDPLITE 136 @@ -130,8 +130,8 @@ Where glibc support is missing, the following definitions are needed: .BR ipv6 (7), .BR socket (7), .BR udp (7) -.PP +.P RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite). -.PP +.P .I Documentation/networking/udplite.txt in the Linux kernel source tree diff --git a/man7/unicode.7 b/man7/unicode.7 index f65a9b2..fe38909 100644 --- a/man7/unicode.7 +++ b/man7/unicode.7 @@ -7,7 +7,7 @@ .\" 2001-05-11 Markus Kuhn <mgk25@cl.cam.ac.uk> .\" Update .\" -.TH unicode 7 2023-03-12 "Linux man-pages 6.05.01" +.TH unicode 7 2024-01-28 "Linux man-pages 6.7" .SH NAME unicode \- universal character set .SH DESCRIPTION @@ -18,7 +18,7 @@ It also guarantees "round-trip compatibility"; in other words, conversion tables can be built such that no information is lost when a string is converted from any other encoding to UCS and back. -.PP +.P UCS contains the characters required to represent practically all known languages. This includes not only the Latin, Greek, Cyrillic, @@ -40,7 +40,7 @@ graphical, typographical, mathematical, and scientific symbols, including those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, Macintosh, OCR fonts, as well as many word processing and publishing systems, and more are being added. -.PP +.P The UCS standard (ISO/IEC 10646) describes a 31-bit character set architecture consisting of 128 24-bit @@ -71,7 +71,7 @@ The supplemental planes added by ISO/IEC 10646-2 cover only more exotic characters for special scientific, dictionary printing, publishing industry, higher-level protocol and enthusiast needs. -.PP +.P The representation of each UCS character as a 2-byte word is referred to as the UCS-2 form (only for BMP characters), whereas UCS-4 is the representation of each character by a 4-byte word. @@ -79,12 +79,12 @@ In addition, there exist two encoding forms UTF-8 for backward compatibility with ASCII processing software and UTF-16 for the backward-compatible handling of non-BMP characters up to 0x10ffff by UCS-2 software. -.PP +.P The UCS characters 0x0000 to 0x007f are identical to those of the classic US-ASCII character set and the characters in the range 0x0000 to 0x00ff are identical to those in -ISO 8859-1 (Latin-1). +ISO/IEC\~8859-1 (Latin-1). .SS Combining characters Some code points in UCS have been assigned to @@ -101,7 +101,7 @@ character Umlaut-A ("Latin capital letter A with diaeresis") can either be represented by the precomposed UCS code 0x00c4, or alternatively as the combination of a normal "Latin capital letter A" followed by a "combining diaeresis": 0x0041 0x0308. -.PP +.P Combining characters are essential for instance for encoding the Thai script or for mathematical typesetting and users of the International Phonetic Alphabet. @@ -124,7 +124,7 @@ Arabic, Devanagari, Malayalam). .TP Level 3 All UCS characters are supported. -.PP +.P The Unicode 3.0 Standard published by the Unicode Consortium contains exactly the UCS Basic Multilingual Plane @@ -147,7 +147,7 @@ code values (in all locales), a convention that is signaled by the GNU C library to applications by defining the constant .B __STDC_ISO_10646__ as specified in the ISO C99 standard. -.PP +.P UCS/Unicode can be used just like ASCII in input/output streams, terminal communication, plaintext files, filenames, and environment variables in the ASCII compatible UTF-8 multibyte encoding. @@ -156,7 +156,7 @@ encoding to all applications, a suitable .I locale has to be selected via environment variables (e.g., "LANG=en_GB.UTF-8"). -.PP +.P The .B nl_langinfo(CODESET) function returns the name of the selected encoding. @@ -189,7 +189,7 @@ in the Linux kernel sources (or .I Documentation/unicode.txt before Linux 4.10). -.PP +.P Two other planes are reserved for private usage, plane 15 (Supplementary Private Use Area-A, range 0xf0000 to 0xffffd) and plane 16 (Supplementary Private Use Area-B, range diff --git a/man7/units.7 b/man7/units.7 index ca2bd2d..da0492f 100644 --- a/man7/units.7 +++ b/man7/units.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH units 7 2023-02-10 "Linux man-pages 6.05.01" +.TH units 7 2023-10-31 "Linux man-pages 6.7" .SH NAME units \- decimal and binary prefixes .SH DESCRIPTION @@ -41,7 +41,7 @@ R ronna 10\[ha]27 = 1000000000000000000000000000 Q quetta 10\[ha]30 = 1000000000000000000000000000000 .TE .RE -.PP +.P The symbol for micro is the Greek letter mu, often written u in an ASCII context where this Greek letter is not available. .SS Binary prefixes @@ -70,7 +70,7 @@ Before these binary prefixes were introduced, it was fairly common to use k=1000 and K=1024, just like b=bit, B=byte. Unfortunately, the M is capital already, and cannot be capitalized to indicate binary-ness. -.PP +.P At first that didn't matter too much, since memory modules and disks came in sizes that were powers of two, so everyone knew that in such contexts "kilobyte" and "megabyte" meant @@ -81,26 +81,26 @@ regarded as the "real true meaning" when computers were involved. But then disk technology changed, and disk sizes became arbitrary numbers. After a period of uncertainty all disk manufacturers settled on the standard, namely k=1000, M=1000\ k, G=1000\ M. -.PP +.P The situation was messy: in the 14k4 modems, k=1000; in the 1.44\ MB .\" also common: 14.4k modem diskettes, M=1024000; and so on. In 1998 the IEC approved the standard that defines the binary prefixes given above, enabling people to be precise and unambiguous. -.PP +.P Thus, today, MB = 1000000\ B and MiB = 1048576\ B. -.PP +.P In the free software world programs are slowly being changed to conform. When the Linux kernel boots and says -.PP +.P .in +4n .EX hda: 120064896 sectors (61473 MB) w/2048KiB Cache .EE .in -.PP +.P the MB are megabytes and the KiB are kibibytes. .SH SEE ALSO .UR https://www.bipm.org/\:documents/\:20126/\:41483022/\:SI\-Brochure\-9.pdf diff --git a/man7/unix.7 b/man7/unix.7 index cfa4188..426a430 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -12,14 +12,14 @@ .\" address that can appear in the sockaddr_un structure: pathname, .\" unnamed, and abstract. .\" -.TH UNIX 7 2023-07-15 "Linux man-pages 6.05.01" +.TH UNIX 7 2024-03-16 "Linux man-pages 6.7" .SH NAME unix \- sockets for local interprocess communication .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <sys/un.h> -.PP +.P .IB unix_socket " = socket(AF_UNIX, type, 0);" .IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");" .fi @@ -34,7 +34,7 @@ Traditionally, UNIX domain sockets can be either unnamed, or bound to a filesystem pathname (marked as being of type socket). Linux also supports an abstract namespace which is independent of the filesystem. -.PP +.P Valid socket types in the UNIX domain are: .BR SOCK_STREAM , for a stream-oriented socket; @@ -47,12 +47,12 @@ and (since Linux 2.6.4) for a sequenced-packet socket that is connection-oriented, preserves message boundaries, and delivers messages in the order that they were sent. -.PP +.P UNIX domain sockets support passing file descriptors or process credentials to other processes using ancillary data. .SS Address format A UNIX domain socket address is represented in the following structure: -.PP +.P .in +4n .EX .\" #define UNIX_PATH_MAX 108 @@ -63,7 +63,7 @@ struct sockaddr_un { }; .EE .in -.PP +.P The .I sun_family field always contains @@ -71,8 +71,8 @@ field always contains On Linux, .I sun_path is 108 bytes in size; see also BUGS, below. -.PP -Various systems calls (for example, +.P +Various system calls (for example, .BR bind (2), .BR connect (2), and @@ -87,7 +87,7 @@ Some other system calls (for example, and .BR accept (2)) return an argument of this type. -.PP +.P Three types of address are distinguished in the .I sockaddr_un structure: @@ -186,7 +186,7 @@ or, more simply, .I addrlen can be specified as .IR "sizeof(struct sockaddr_un)" . -.PP +.P There is some variation in how implementations handle UNIX domain socket addresses that do not follow the above rules. For example, some (but not all) implementations @@ -194,7 +194,7 @@ For example, some (but not all) implementations .\" is 108 bytes append a null terminator if none is present in the supplied .IR sun_path . -.PP +.P When coding portable applications, keep in mind that some implementations .\" HP-UX @@ -203,7 +203,7 @@ have as short as 92 bytes. .\" Modern BSDs generally have 104, Tru64 and AIX have 104, .\" Solaris and Irix have 108 -.PP +.P Various system calls .RB ( accept (2), .BR recvfrom (2), @@ -227,7 +227,7 @@ In the Linux implementation, pathname sockets honor the permissions of the directory they are in. Creation of a new socket fails if the process does not have write and search (execute) permission on the directory in which the socket is created. -.PP +.P On Linux, connecting to a stream socket object requires write permission on that socket; sending a datagram to a datagram socket likewise @@ -237,13 +237,13 @@ on a socket file, and on some systems (e.g., older BSDs), the socket permissions are ignored. Portable programs should not rely on this feature for security. -.PP +.P When creating a new socket, the owner and group of the socket file are set according to the usual rules. The socket file has all permissions enabled, other than those that are turned off by the process .BR umask (2). -.PP +.P The owner, group, and permissions of a pathname socket can be changed (using .BR chown (2) and @@ -260,10 +260,10 @@ and changing the ownership and permissions of the object (via and .BR fchmod (2)) has no effect on the accessibility of the socket. -.PP +.P Abstract sockets automatically disappear when all open references to the socket are closed. -.PP +.P The abstract socket namespace is a nonportable Linux extension. .\" .SS Socket options @@ -331,7 +331,8 @@ This read-only socket option returns the credentials of the peer process connected to this socket. The returned credentials are those that were in effect at the time of the call to -.BR connect (2) +.BR connect (2), +.BR listen (2), or .BR socketpair (2). .IP @@ -418,7 +419,7 @@ The change to 5 bytes came in Linux 2.3.15.) .SS Sockets API The following paragraphs describe domain-specific details and unsupported features of the sockets API for UNIX domain sockets on Linux. -.PP +.P UNIX domain sockets do not support the transmission of out-of-band data (the .B MSG_OOB @@ -426,12 +427,12 @@ flag for .BR send (2) and .BR recv (2)). -.PP +.P The .BR send (2) .B MSG_MORE flag is not supported by UNIX domain sockets. -.PP +.P Before Linux 3.4, .\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f the use of @@ -441,7 +442,7 @@ in the argument of .BR recv (2) was not supported by UNIX domain sockets. -.PP +.P The .B SO_SNDBUF socket option does have an effect for UNIX domain sockets, but the @@ -573,11 +574,11 @@ bytes in the data portion of the ancillary message for this data. To receive the security context, the .B SO_PASSSEC option must be enabled on the socket (see above). -.PP +.P When sending ancillary data with .BR sendmsg (2), only one item of each of the above types may be included in the sent message. -.PP +.P At least one byte of real data should be sent when sending ancillary data. On Linux, this is required to successfully send ancillary data over a UNIX domain stream socket. @@ -585,11 +586,11 @@ When sending ancillary data over a UNIX domain datagram socket, it is not necessary on Linux to send any accompanying real data. However, portable applications should also include at least one byte of real data when sending ancillary data over a datagram socket. -.PP +.P When receiving from a stream socket, ancillary data forms a kind of barrier for the received data. For example, suppose that the sender transmits as follows: -.PP +.P .RS .PD 0 .IP (1) 5 @@ -603,7 +604,7 @@ of one byte, with ancillary data. of four bytes, with no ancillary data. .PD .RE -.PP +.P Suppose that the receiver now performs .BR recvmsg (2) calls each with a buffer size of 20 bytes. @@ -612,7 +613,7 @@ along with the ancillary data sent by the second .BR sendmsg (2) call. The next call will receive the remaining four bytes of data. -.PP +.P If the space allocated for receiving incoming ancillary data is too small then the ancillary data is truncated to the number of headers that will fit in the supplied buffer (or, in the case of an @@ -639,14 +640,14 @@ The following calls return information in .IR value . The correct syntax is: -.PP +.P .RS .nf .BI int " value"; .IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");" .fi .RE -.PP +.P .I ioctl_type can be: .TP @@ -800,7 +801,7 @@ by sending each file descriptor with and then closing the file descriptor so that it was not accounted against the .B RLIMIT_NOFILE resource limit. -.PP +.P Other errors can be generated by the generic socket layer or by the filesystem while generating a filesystem socket object. See the appropriate manual pages for more information. @@ -818,7 +819,7 @@ longer needed (using The usual UNIX close-behind semantics apply; the socket can be unlinked at any time and will be finally removed from the filesystem when the last reference to it is closed. -.PP +.P To pass file descriptors or credentials over a .B SOCK_STREAM socket, you must @@ -827,12 +828,12 @@ send or receive at least one byte of nonancillary data in the same or .BR recvmsg (2) call. -.PP +.P UNIX domain stream sockets do not support the notion of out-of-band data. .\" .SH BUGS When binding a socket to an address, -Linux is one of the implementations that appends a null terminator +Linux is one of the implementations that append a null terminator if none is supplied in .IR sun_path . In most cases this is unproblematic: @@ -855,7 +856,7 @@ then the returned address structure .I won't have a null terminator in .IR sun_path . -.PP +.P In addition, some implementations .\" i.e., traditional BSD don't require a null terminator when binding a socket (the @@ -865,12 +866,12 @@ argument is used to determine the length of and when the socket address is retrieved on these implementations, there is no null terminator in .IR sun_path . -.PP +.P Applications that retrieve socket addresses can (portably) code to handle the possibility that there is no null terminator in .I sun_path by respecting the fact that the number of valid bytes in the pathname is: -.PP +.P .in +4n .EX strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) @@ -886,7 +887,7 @@ strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) .\" 2012-04-18 .\" .\" FIXME . Track http://austingroupbugs.net/view.php?id=561 -.PP +.P Alternatively, an application can retrieve the socket address by allocating a buffer of size .I "sizeof(struct sockaddr_un)+1" @@ -898,7 +899,7 @@ as and the extra zero byte ensures that there will be a null terminator for the string returned in .IR sun_path : -.PP +.P .in +4n .EX void *addrp; @@ -915,7 +916,7 @@ if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1) printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path); .EE .in -.PP +.P This sort of messiness can be avoided if it is guaranteed that the applications that .I create @@ -933,7 +934,7 @@ The server sends back a message containing the sum of the client's integers. The client prints the sum and exits. The server waits for the next client to connect. To stop the server, the client is called with the command-line argument "DOWN". -.PP +.P The following output was recorded while running the server in the background and repeatedly executing the client. Execution of the server program ends when it receives the "DOWN" command. @@ -954,6 +955,7 @@ $ .in .SS Program source \& +.\" SRC BEGIN (connection.h) .EX /* * File connection.h @@ -961,7 +963,11 @@ $ \& #define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket" #define BUFFER_SIZE 12 -\& +.EE +.\" SRC END +.P +.\" SRC BEGIN (server.c) +.EX /* * File server.c */ @@ -972,18 +978,20 @@ $ #include <sys/socket.h> #include <sys/un.h> #include <unistd.h> +\& #include "connection.h" \& int -main(int argc, char *argv[]) +main(void) { - struct sockaddr_un name; - int down_flag = 0; - int ret; - int connection_socket; - int data_socket; - int result; - char buffer[BUFFER_SIZE]; + int down_flag = 0; + int ret; + int connection_socket; + int data_socket; + int result; + ssize_t r, w; + struct sockaddr_un name; + char buffer[BUFFER_SIZE]; \& /* Create local socket. */ \& @@ -1042,8 +1050,8 @@ main(int argc, char *argv[]) \& /* Wait for next data packet. */ \& - ret = read(data_socket, buffer, sizeof(buffer)); - if (ret == \-1) { + r = read(data_socket, buffer, sizeof(buffer)); + if (r == \-1) { perror("read"); exit(EXIT_FAILURE); } @@ -1056,13 +1064,17 @@ main(int argc, char *argv[]) \& if (!strncmp(buffer, "DOWN", sizeof(buffer))) { down_flag = 1; - break; + continue; } \& if (!strncmp(buffer, "END", sizeof(buffer))) { break; } \& + if (down_flag) { + continue; + } +\& /* Add received summand. */ \& result += atoi(buffer); @@ -1071,8 +1083,8 @@ main(int argc, char *argv[]) /* Send result. */ \& sprintf(buffer, "%d", result); - ret = write(data_socket, buffer, sizeof(buffer)); - if (ret == \-1) { + w = write(data_socket, buffer, sizeof(buffer)); + if (w == \-1) { perror("write"); exit(EXIT_FAILURE); } @@ -1096,27 +1108,32 @@ main(int argc, char *argv[]) \& exit(EXIT_SUCCESS); } -\& +.EE +.\" SRC END +.P +.\" SRC BEGIN (client.c) +.EX /* * File client.c */ \& -#include <errno.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <sys/socket.h> #include <sys/un.h> #include <unistd.h> +\& #include "connection.h" \& int main(int argc, char *argv[]) { - struct sockaddr_un addr; - int ret; - int data_socket; - char buffer[BUFFER_SIZE]; + int ret; + int data_socket; + ssize_t r, w; + struct sockaddr_un addr; + char buffer[BUFFER_SIZE]; \& /* Create local socket. */ \& @@ -1148,9 +1165,9 @@ main(int argc, char *argv[]) \& /* Send arguments. */ \& - for (size_t i = 1; i < argc; ++i) { - ret = write(data_socket, argv[i], strlen(argv[i]) + 1); - if (ret == \-1) { + for (int i = 1; i < argc; ++i) { + w = write(data_socket, argv[i], strlen(argv[i]) + 1); + if (w == \-1) { perror("write"); break; } @@ -1159,16 +1176,16 @@ main(int argc, char *argv[]) /* Request result. */ \& strcpy(buffer, "END"); - ret = write(data_socket, buffer, strlen(buffer) + 1); - if (ret == \-1) { + w = write(data_socket, buffer, strlen(buffer) + 1); + if (w == \-1) { perror("write"); exit(EXIT_FAILURE); } \& /* Receive result. */ \& - ret = read(data_socket, buffer, sizeof(buffer)); - if (ret == \-1) { + r = read(data_socket, buffer, sizeof(buffer)); + if (r == \-1) { perror("read"); exit(EXIT_FAILURE); } @@ -1186,7 +1203,8 @@ main(int argc, char *argv[]) exit(EXIT_SUCCESS); } .EE -.PP +.\" SRC END +.P For examples of the use of .BR SCM_RIGHTS , see @@ -25,7 +25,7 @@ .\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) .\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com) .\" -.TH uri 7 2023-04-30 "Linux man-pages 6.05.01" +.TH uri 7 2023-10-31 "Linux man-pages 6.7" .SH NAME uri, url, urn \- uniform resource identifier (URI), including a URL or URN .SH SYNOPSIS @@ -36,7 +36,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] # \[dq]\~\c .IR fragment \~] .YS -.PP +.P .SY "\fIabsoluteURI\fP \fR=\fP" .I scheme\~\c .RB \[dq] : \[dq] @@ -44,7 +44,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN | .IR opaque_part \~) .YS -.PP +.P .SY "\fIrelativeURI\fP \fR=\fP" .RI (\~ net_path | @@ -54,7 +54,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] ? \[dq]\~\c .IR query \~] .YS -.PP +.P .SY "\fIscheme\fP \fR=\fP" .RB \[dq] http \[dq] | @@ -83,7 +83,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB \[dq] wais \[dq] | \&... .YS -.PP +.P .SY "\fIhierarchical_part\fP \fR=\fP" .RI (\~ net_path | @@ -91,18 +91,18 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] ? \[dq]\~\c .IR query \~] .YS -.PP +.P .SY "\fInet_path\fP \fR=\fP" .RB \[dq] // \[dq]\~\c .I authority .RI [\~ absolute_path \~] .YS -.PP +.P .SY "\fIabsolute_path\fP \fR=\fP" .RB \[dq] / \[dq]\~\c .I path_segments .YS -.PP +.P .SY "\fIrelative_path\fP \fR=\fP" .I relative_segment .RI [\~ absolute_path \~] @@ -117,14 +117,14 @@ by name or some other attribute of that resource. A Uniform Resource Name (URN) is a URI that must remain globally unique and persistent even when the resource ceases to exist or becomes unavailable. -.PP +.P URIs are the standard way to name hypertext link destinations for tools such as web browsers. The string "http://www.kernel.org" is a URL (and thus it is also a URI). Many people use the term URL loosely as a synonym for URI (though technically URLs are a subset of URIs). -.PP +.P URIs can be absolute or relative. An absolute identifier refers to a resource independent of context, while a relative @@ -140,7 +140,7 @@ character can't be used as the first segment of a relative URI path precede such segments with ./ (e.g., "./this:that"). Note that descendants of MS-DOS (e.g., Microsoft Windows) replace devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|". -.PP +.P A fragment identifier, if included, refers to a particular named portion (fragment) of a resource; @@ -155,9 +155,9 @@ For example, many URL schemes permit the authority to be the following format, called here an .I ip_server (square brackets show what's optional): -.PP +.P .IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ] -.PP +.P This format allows you to optionally insert a username, a user plus password, and/or a port number. The @@ -173,18 +173,18 @@ security risks of having a password written down. If the URL supplies a username but no password, and the remote server requests a password, the program interpreting the URL should request one from the user. -.PP +.P Here are some of the most common schemes in use on UNIX-like systems that are understood by many tools. Note that many tools using URIs also have internal schemes or specialized schemes; see those tools' documentation for information on those schemes. -.PP +.P .B "http \- Web (HTTP) server" -.PP +.P .RI http:// ip_server / path .br .RI http:// ip_server / path ? query -.PP +.P This is a URL accessing a web (HTTP) server. The default port is 80. If the path refers to a directory, the web server will choose what @@ -192,7 +192,7 @@ to return; usually if there is a file named "index.html" or "index.htm" its content is returned, otherwise, a list of the files in the current directory (with appropriate links) is generated and returned. An example is <http://lwn.net>. -.PP +.P A query can be given in the archaic "isindex" format, consisting of a word or phrase and not including an equal sign (=). A query can also be in the longer "GET" format, which has one or more @@ -215,11 +215,11 @@ See the Common Gateway Interface specification at .UR http://www.w3.org\:/CGI .UE for more information. -.PP +.P .B "ftp \- File Transfer Protocol (FTP)" -.PP +.P .RI ftp:// ip_server / path -.PP +.P This is a URL accessing a file through the file transfer protocol (FTP). The default port (for control) is 21. If no username is included, the username "anonymous" is supplied, and @@ -227,16 +227,16 @@ in that case many clients provide as the password the requestor's Internet email address. An example is <ftp://ftp.is.co.za/rfc/rfc1808.txt>. -.PP +.P .B "gopher \- Gopher server" -.PP +.P .RI gopher:// ip_server / "gophertype selector" .br .RI gopher:// ip_server / "gophertype selector" %09 search .br .RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string .br -.PP +.P The default gopher port is 70. .I gophertype is a single-character field to denote the @@ -245,18 +245,18 @@ which the URL refers. The entire path may also be empty, in which case the delimiting "/" is also optional and the gophertype defaults to "1". -.PP +.P .I selector is the Gopher selector string. In the Gopher protocol, Gopher selector strings are a sequence of octets which may contain any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal (US-ASCII character LF), and 0D (US-ASCII character CR). -.PP +.P .B "mailto \- Email address" -.PP +.P .RI mailto: email-address -.PP +.P This is an email address, usually of the form .IR name @ hostname . See @@ -264,13 +264,13 @@ See for more information on the correct format of an email address. Note that any % character must be rewritten as %25. An example is <mailto:dwheeler@dwheeler.com>. -.PP +.P .B "news \- Newsgroup or News message" -.PP +.P .RI news: newsgroup-name .br .RI news: message-id -.PP +.P A .I newsgroup-name is a period-delimited hierarchical name, such as @@ -278,7 +278,7 @@ is a period-delimited hierarchical name, such as If <newsgroup-name> is "*" (as in <news:*>), it is used to refer to "all available news groups". An example is <news:comp.lang.ada>. -.PP +.P A .I message-id corresponds to the Message-ID of @@ -290,23 +290,23 @@ and ">"; it takes the form .IR unique @ full_domain_name . A message identifier may be distinguished from a news group name by the presence of the "@" character. -.PP +.P .B "telnet \- Telnet login" -.PP +.P .RI telnet:// ip_server / -.PP +.P The Telnet URL scheme is used to designate interactive text services that may be accessed by the Telnet protocol. The final "/" character may be omitted. The default port is 23. An example is <telnet://melvyl.ucop.edu/>. -.PP +.P .B "file \- Normal file" -.PP +.P .RI file:// ip_server / path_segments .br .RI file: path_segments -.PP +.P This represents a file or directory accessible locally. As a special case, .I ip_server @@ -323,7 +323,7 @@ the filename via filename globbing .BR glob (7) and .BR glob (3)). -.PP +.P The second format (e.g., <file:/etc/passwd>) is a correct format for referring to a local file. @@ -337,13 +337,13 @@ Note that if you really mean to say "start from the current location", don't specify the scheme at all; use a relative address like <../test.txt>, which has the side-effect of being scheme-independent. An example of this scheme is <file:///etc/passwd>. -.PP +.P .B "man \- Man page documentation" -.PP +.P .RI man: command-name .br .RI man: command-name ( section ) -.PP +.P This refers to local online manual (man) reference pages. The command name can optionally be followed by a parenthesis and section number; see @@ -352,9 +352,9 @@ for more information on the meaning of the section numbers. This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. An example is <man:ls(1)>. -.PP +.P .B "info \- Info page documentation" -.PP +.P .RI info: virtual-filename .br .RI info: virtual-filename # nodename @@ -362,7 +362,7 @@ An example is <man:ls(1)>. .RI info:( virtual-filename ) .br .RI info:( virtual-filename ) nodename -.PP +.P This scheme refers to online info reference pages (generated from texinfo files), a documentation format used by programs such as the GNU tools. @@ -381,11 +381,11 @@ In both GNOME and KDE, if the form without the nodename is used the nodename is assumed to be "Top". Examples of the GNOME format are <info:gcc> and <info:gcc#G++_and_GCC>. Examples of the KDE format are <info:(gcc)> and <info:(gcc)G++ and GCC>. -.PP +.P .B "whatis \- Documentation search" -.PP +.P .RI whatis: string -.PP +.P This scheme searches the database of short (one-line) descriptions of commands and returns a list of descriptions containing that string. Only complete word matches are returned. @@ -393,16 +393,16 @@ See .BR whatis (1). This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. -.PP +.P .B "ghelp \- GNOME help documentation" -.PP +.P .RI ghelp: name-of-application -.PP +.P This loads GNOME help for the given application. Note that not much documentation currently exists in this format. -.PP +.P .B "ldap \- Lightweight Directory Access Protocol" -.PP +.P .RI ldap:// hostport .br .RI ldap:// hostport / @@ -416,7 +416,7 @@ Note that not much documentation currently exists in this format. .RI ldap:// hostport / dn ? attributes ? scope ? filter .br .RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions -.PP +.P This scheme supports queries to the Lightweight Directory Access Protocol (LDAP), a protocol for querying a set of servers for hierarchically organized information @@ -469,36 +469,36 @@ pairs, where the =value portion may be omitted for options not requiring it. An extension prefixed with a \[aq]!\[aq] is critical (must be supported to be valid), otherwise it is noncritical (optional). -.PP +.P LDAP queries are easiest to explain by example. Here's a query that asks ldap.itd.umich.edu for information about the University of Michigan in the U.S.: -.PP +.P .nf ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US .fi -.PP +.P To just get its postal address attribute, request: -.PP +.P .nf ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress .fi -.PP +.P To ask a host.com at port 6666 for information about the person with common name (cn) "Babs Jensen" at University of Michigan, request: -.PP +.P .nf ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen) .fi -.PP +.P .B "wais \- Wide Area Information Servers" -.PP +.P .RI wais:// hostport / database .br .RI wais:// hostport / database ? search .br .RI wais:// hostport / database / wtype / wpath -.PP +.P This scheme designates a WAIS database, search, or document (see .UR http://www.ietf.org\:/rfc\:/rfc1625.txt @@ -507,7 +507,7 @@ IETF RFC\ 1625 for more information on WAIS). Hostport is the hostname, optionally followed by a colon and port number (the default port number is 210). -.PP +.P The first form designates a WAIS database for searching. The second form designates a particular search of the WAIS database .IR database . @@ -517,9 +517,9 @@ database to be retrieved. is the WAIS designation of the type of the object and .I wpath is the WAIS document-id. -.PP +.P .B "other schemes" -.PP +.P There are many other URI schemes. Most tools that accept URIs support a set of internal URIs (e.g., Mozilla has the about: scheme for internal information, @@ -536,7 +536,7 @@ Not all tools support all schemes. .SS Character encoding URIs use a limited number of characters so that they can be typed in and used in a variety of situations. -.PP +.P The following characters are reserved, that is, they may appear in a URI but their use is limited to their reserved purpose (conflicting data must be escaped before forming the URI): @@ -546,7 +546,7 @@ URI but their use is limited to their reserved purpose ; / ? : @ & = + $ , .EE .in -.PP +.P Unreserved characters may be included in a URI. Unreserved characters include uppercase and lowercase Latin letters, @@ -558,7 +558,7 @@ limited set of punctuation marks and symbols: \- _ . ! \[ti] * ' ( ) .EE .in -.PP +.P All other characters must be escaped. An escaped octet is encoded as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits @@ -573,13 +573,13 @@ in query text; this practice isn't uniformly defined in the relevant RFCs (which recommend %20 instead) but any tool accepting URIs with query text should be prepared for them. A URI is always shown in its "escaped" form. -.PP +.P Unreserved characters can be escaped without changing the semantics of the URI, but this should not be done unless the URI is being used in a context that does not allow the unescaped character to appear. For example, "%7e" is sometimes used instead of "\[ti]" in an HTTP URL path, but the two are equivalent for an HTTP URL. -.PP +.P 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) @@ -609,7 +609,7 @@ This latter system, called the 'new' or 'logical' quoting system by is preferred practice in Great Britain and in various European languages. Older documents suggested inserting the prefix "URL:" just before the URI, but this form has never caught on. -.PP +.P The URI syntax was designed to be unambiguous. However, as URIs have become commonplace, traditional media (television, radio, newspapers, billboards, etc.) have increasingly @@ -644,9 +644,9 @@ be able to handle (directly or indirectly) all of the schemes described here, including the man: and info: schemes. Handling them by invoking some other program is fine and in fact encouraged. -.PP +.P Technically the fragment isn't part of the URI. -.PP +.P For information on how to embed URIs (including URLs) in a data format, see documentation on that format. HTML uses the format <A HREF="\fIuri\fP"> @@ -655,7 +655,7 @@ HTML uses the format <A HREF="\fIuri\fP"> Texinfo files use the format @uref{\fIuri\fP}. Man and mdoc have the recently added UR macro, or just include the URI in the text (viewers should be able to detect :// as part of a URI). -.PP +.P The GNOME and KDE desktop environments currently vary in the URIs they accept, in particular in their respective help browsers. To list man pages, GNOME uses <toc:man> while KDE uses <man:(index)>, and @@ -685,7 +685,7 @@ guarantee that a URL will not locate a different resource at some later point in time; such a guarantee can be obtained only from the person(s) controlling that namespace and the resource in question. -.PP +.P It is sometimes possible to construct a URL such that an attempt to perform a seemingly harmless operation, such as the retrieval of an entity associated with the resource, will in fact @@ -700,11 +700,11 @@ interpreted according to this other protocol, cause an unexpected operation. An example has been the use of a gopher URL to cause an unintended or impersonating message to be sent via a SMTP server. -.PP +.P Caution should be used when using any URL that specifies a port number other than the default for the protocol, especially when it is a number within the reserved space. -.PP +.P Care should be taken when a URI contains escaped delimiters for a given protocol (for example, CR and LF characters for telnet protocols) that these are not unescaped before transmission. @@ -712,7 +712,7 @@ This might violate the protocol, but avoids the potential for such characters to be used to simulate an extra operation or parameter in that protocol, which might lead to an unexpected and possibly harmful remote operation to be performed. -.PP +.P It is clearly unwise to use a URI that contains a password which is intended to be secret. In particular, the use of a password within @@ -739,10 +739,10 @@ without having to know the exact location of that documentation. Alternatively, a future version of the filesystem specification may specify file locations sufficiently so that the file: scheme will be able to locate documentation. -.PP +.P Many programs and file formats don't include a way to incorporate or implement links using URIs. -.PP +.P Many programs can't handle all of these different URI formats; there should be a standard mechanism to load an arbitrary URI that automatically detects the users' environment (e.g., text or graphics, @@ -755,7 +755,7 @@ tools) and invokes the right tool for any URI. .BR man2html (1), .BR mailaddr (7), .BR utf\-8 (7) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc2255.txt IETF RFC\ 2255 .UE diff --git a/man7/user-keyring.7 b/man7/user-keyring.7 index 7468cc5..137c691 100644 --- a/man7/user-keyring.7 +++ b/man7/user-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH user-keyring 7 2023-02-05 "Linux man-pages 6.05.01" +.TH user-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME user-keyring \- per-user keyring .SH DESCRIPTION @@ -15,7 +15,7 @@ The user keyring has a name (description) of the form where .I <UID> is the user ID of the corresponding user. -.PP +.P The user keyring is associated with the record that the kernel maintains for the UID. It comes into existence upon the first attempt to access either the @@ -27,28 +27,28 @@ The keyring remains pinned in existence so long as there are processes running with that real UID or files opened by those processes remain open. (The keyring can also be pinned indefinitely by linking it into another keyring.) -.PP +.P Typically, the user keyring is created by .BR pam_keyinit (8) when a user logs in. -.PP +.P The user keyring is not searched by default by .BR request_key (2). When .BR pam_keyinit (8) creates a session keyring, it adds to it a link to the user keyring so that the user keyring will be searched when the session keyring is. -.PP +.P A special serial number value, .BR KEY_SPEC_USER_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's user keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@u\fP' can be used instead of a numeric key ID in much the same way. -.PP +.P User keyrings are independent of .BR clone (2), .BR fork (2), @@ -58,14 +58,14 @@ and .BR _exit (2) excepting that the keyring is destroyed when the UID record is destroyed when the last process pinning it exits. -.PP +.P If it is necessary for a key associated with a user to exist beyond the UID record being garbage collected\[em]for example, for use by a .BR cron (8) script\[em]then the .BR persistent\-keyring (7) should be used instead. -.PP +.P If a user keyring does not exist when it is accessed, it will be created. .SH SEE ALSO .ad l diff --git a/man7/user-session-keyring.7 b/man7/user-session-keyring.7 index 3fc8795..7af56f0 100644 --- a/man7/user-session-keyring.7 +++ b/man7/user-session-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH user-session-keyring 7 2023-02-05 "Linux man-pages 6.05.01" +.TH user-session-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME user-session-keyring \- per-user default session keyring .SH DESCRIPTION @@ -15,7 +15,7 @@ The user session keyring has a name (description) of the form where .I <UID> is the user ID of the corresponding user. -.PP +.P The user session keyring is associated with the record that the kernel maintains for the UID. It comes into existence upon the first attempt to access either the @@ -28,7 +28,7 @@ The keyring remains pinned in existence so long as there are processes running with that real UID or files opened by those processes remain open. (The keyring can also be pinned indefinitely by linking it into another keyring.) -.PP +.P The user session keyring is created on demand when a thread requests it or when a thread asks for its .BR session\-keyring (7) @@ -36,22 +36,22 @@ and that keyring doesn't exist. In the latter case, a user session keyring will be created and, if the session keyring wasn't to be created, the user session keyring will be set as the process's actual session keyring. -.PP +.P The user session keyring is searched by .BR request_key (2) if the actual session keyring does not exist and is ignored otherwise. -.PP +.P A special serial number value, .BR KEY_SPEC_USER_SESSION_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's user session keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@us\fP' can be used instead of a numeric key ID in much the same way. -.PP +.P User session keyrings are independent of .BR clone (2), .BR fork (2), @@ -61,10 +61,10 @@ and .BR _exit (2) excepting that the keyring is destroyed when the UID record is destroyed when the last process pinning it exits. -.PP +.P If a user session keyring does not exist when it is accessed, it will be created. -.PP +.P Rather than relying on the user session keyring, it is strongly recommended\[em]especially if the process is running as root\[em]that a diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7 index 0c29f93..94e0785 100644 --- a/man7/user_namespaces.7 +++ b/man7/user_namespaces.7 @@ -4,13 +4,13 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH user_namespaces 7 2023-05-03 "Linux man-pages 6.05.01" +.TH user_namespaces 7 2024-02-25 "Linux man-pages 6.7" .SH NAME user_namespaces \- overview of Linux user namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P User namespaces isolate security-related identifiers and attributes, in particular, user IDs and group IDs (see @@ -46,7 +46,7 @@ or with the .B CLONE_NEWUSER flag. -.PP +.P The kernel imposes (since Linux 3.11) a limit of 32 nested levels of .\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8 user namespaces. @@ -57,7 +57,7 @@ or .BR clone (2) that would cause this limit to be exceeded fail with the error .BR EUSERS . -.PP +.P Each process is a member of exactly one user namespace. A process created via .BR fork (2) @@ -72,7 +72,7 @@ if it has the .B CAP_SYS_ADMIN in that namespace; upon doing so, it gains a full set of capabilities in that namespace. -.PP +.P A call to .BR clone (2) or @@ -84,14 +84,14 @@ flag makes the new child process (for or the caller (for .BR unshare (2)) a member of the new user namespace created by the call. -.PP +.P The .B NS_GET_PARENT .BR ioctl (2) operation can be used to discover the parental relationship between user namespaces; see .BR ioctl_ns (2). -.PP +.P A task that changes one of its effective IDs will have its dumpability reset to the value in .IR /proc/sys/fs/suid_dumpable . @@ -134,7 +134,7 @@ and user namespace, even if the new namespace is created or joined by the root user (i.e., a process with user ID 0 in the root namespace). -.PP +.P Note that a call to .BR execve (2) will cause a process's capabilities to be recalculated in the usual way (see @@ -144,7 +144,7 @@ unless the process has a user ID of 0 within the namespace, or the executable file has a nonempty inheritable capabilities mask, the process will lose all capabilities. See the discussion of user and group ID mappings, below. -.PP +.P A call to .BR clone (2) or @@ -172,7 +172,7 @@ retaining its user namespace membership by using a pair of .BR setns (2) calls to move to another user namespace and then return to its original user namespace. -.PP +.P The rules for determining whether or not a process has a capability in a particular user namespace are as follows: .IP \[bu] 3 @@ -230,7 +230,7 @@ In other words, having a capability in a user namespace permits a process to perform privileged operations on resources that are governed by (nonuser) namespaces owned by (associated with) the user namespace (see the next subsection). -.PP +.P On the other hand, there are many privileged operations that affect resources that are not associated with any namespace type, for example, changing the system (i.e., calendar) time (governed by @@ -242,14 +242,14 @@ and creating a device (governed by Only a process with privileges in the .I initial user namespace can perform such operations. -.PP +.P Holding .B CAP_SYS_ADMIN within the user namespace that owns a process's mount namespace allows that process to create bind mounts and mount the following types of filesystems: .\" fs_flags = FS_USERNS_MOUNT in kernel sources -.PP +.P .RS 4 .PD 0 .IP \[bu] 3 @@ -281,7 +281,7 @@ and mount the following types of filesystems: (since Linux 5.11) .PD .RE -.PP +.P Holding .B CAP_SYS_ADMIN within the user namespace that owns a process's cgroup namespace @@ -289,9 +289,9 @@ allows (since Linux 4.6) that process to the mount the cgroup version 2 filesystem and cgroup version 1 named hierarchies (i.e., cgroup filesystems mounted with the -.I """none,name=""" +.I \[dq]none,name=\[dq] option). -.PP +.P Holding .B CAP_SYS_ADMIN within the user namespace that owns a process's PID namespace @@ -299,7 +299,7 @@ allows (since Linux 3.8) that process to mount .I /proc filesystems. -.PP +.P Note, however, that mounting block-based filesystems can be done only by a process that holds .B CAP_SYS_ADMIN @@ -312,14 +312,14 @@ Starting in Linux 3.8, unprivileged processes can create user namespaces, and the other types of namespaces can be created with just the .B CAP_SYS_ADMIN capability in the caller's user namespace. -.PP +.P When a nonuser namespace is created, it is owned by the user namespace in which the creating process was a member at the time of the creation of the namespace. Privileged operations on resources governed by the nonuser namespace require that the process has the necessary capabilities in the user namespace that owns the nonuser namespace. -.PP +.P If .B CLONE_NEWUSER is specified along with other @@ -336,7 +336,7 @@ or caller privileges over the remaining namespaces created by the call. Thus, it is possible for an unprivileged caller to specify this combination of flags. -.PP +.P When a new namespace (other than a user namespace) is created via .BR clone (2) or @@ -358,7 +358,7 @@ the process's UTS namespace, and check whether the process has the required capability .RB ( CAP_SYS_ADMIN ) in that user namespace. -.PP +.P The .B NS_GET_USERNS .BR ioctl (2) @@ -383,13 +383,13 @@ inside the user namespace for the process .IR pid . These files can be read to view the mappings in a user namespace and written to (once) to define the mappings. -.PP +.P The description in the following paragraphs explains the details for .IR uid_map ; .I gid_map is exactly the same, but each instance of "user ID" is replaced by "group ID". -.PP +.P The .I uid_map file exposes the mapping of user IDs from the user namespace @@ -403,7 +403,7 @@ will potentially see different values when reading from a particular .I uid_map file, depending on the user ID mappings for the user namespaces of the reading processes. -.PP +.P Each line in the .I uid_map file specifies a 1-to-1 mapping of a range of contiguous @@ -448,14 +448,14 @@ that created this user namespace. .IP (3) The length of the range of user IDs that is mapped between the two user namespaces. -.PP +.P System calls that return user IDs (group IDs)\[em]for example, .BR getuid (2), .BR getgid (2), and the credential fields in the structure returned by .BR stat (2)\[em]return the user ID (group ID) mapped into the caller's user namespace. -.PP +.P When a process accesses a file, its user and group IDs are mapped into the initial user namespace for the purpose of permission checking and assigning IDs when creating a file. @@ -463,7 +463,7 @@ When a process retrieves file user and group IDs via .BR stat (2), the IDs are mapped in the opposite direction, to produce values relative to the process user and group ID mappings. -.PP +.P The initial user namespace has no parent namespace, but, for consistency, the kernel provides dummy user and group ID mapping files for this namespace. @@ -472,14 +472,14 @@ Looking at the file .RI ( gid_map is the same) from a shell in the initial namespace shows: -.PP +.P .in +4n .EX $ \fBcat /proc/$$/uid_map\fP 0 0 4294967295 .EE .in -.PP +.P This mapping tells us that the range starting at user ID 0 in this namespace maps to a range starting at 0 in the (nonexistent) parent namespace, @@ -512,7 +512,7 @@ file in a user namespace fails with the error Similar rules apply for .I gid_map files. -.PP +.P The lines written to .I uid_map .RI ( gid_map ) @@ -552,10 +552,10 @@ Linux 3.9 and later fix this limitation, allowing any valid set of nonoverlapping maps. .IP \[bu] At least one line must be written to the file. -.PP +.P Writes that violate the above rules fail with the error .BR EINVAL . -.PP +.P In order for a process to write to the .IR /proc/ pid /uid_map .RI ( /proc/ pid /gid_map ) @@ -661,7 +661,7 @@ file (see below) before writing to .IR gid_map . .RE .RE -.PP +.P Writes that violate the above rules fail with the error .BR EPERM . .\" @@ -674,13 +674,13 @@ it is possible to create project ID mappings for a user namespace. .BR setquota (8) and .BR quotactl (2).) -.PP +.P Project ID mappings are defined by writing to the .IR /proc/ pid /projid_map file (present since .\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d Linux 3.7). -.PP +.P The validity rules for writing to the .IR /proc/ pid /projid_map file are as for writing to the @@ -689,7 +689,7 @@ file; violation of these rules causes .BR write (2) to fail with the error .BR EINVAL . -.PP +.P The permission rules for writing to the .IR /proc/ pid /projid_map file are as follows: @@ -701,7 +701,7 @@ or be in the parent user namespace of the process .IP \[bu] The mapped project IDs must in turn have a mapping in the parent user namespace. -.PP +.P Violation of these rules causes .BR write (2) to fail with the error @@ -722,7 +722,7 @@ and .I gid_map files have been written, only the mapped values may be used in system calls that change user and group IDs. -.PP +.P For user IDs, the relevant system calls include .BR setuid (2), .BR setfsuid (2), @@ -736,7 +736,7 @@ For group IDs, the relevant system calls include .BR setresgid (2), and .BR setgroups (2). -.PP +.P Writing .RI \[dq] deny \[dq] to the @@ -784,7 +784,7 @@ file (and regardless of the process's capabilities), calls to are also not permitted if .IR /proc/ pid /gid_map has not yet been set. -.PP +.P A privileged process (one with the .B CAP_SYS_ADMIN capability in the namespace) may write either of the strings @@ -800,7 +800,7 @@ Writing the string .RI \[dq] deny \[dq] prevents any process in the user namespace from employing .BR setgroups (2). -.PP +.P The essence of the restrictions described in the preceding paragraph is that it is permitted to write to .IR /proc/ pid /setgroups @@ -819,10 +819,10 @@ a process can transition only from being disallowed to .BR setgroups (2) being allowed. -.PP +.P The default value of this file in the initial user namespace is .RI \[dq] allow \[dq]. -.PP +.P Once .IR /proc/ pid /gid_map has been written to @@ -837,11 +837,11 @@ to .IR /proc/ pid /setgroups (the write fails with the error .BR EPERM ). -.PP +.P A child user namespace inherits the .IR /proc/ pid /setgroups setting from its parent. -.PP +.P If the .I setgroups file has the value @@ -855,7 +855,7 @@ to the file) in this user namespace. .BR EPERM .) This restriction also propagates down to all child user namespaces of this user namespace. -.PP +.P The .IR /proc/ pid /setgroups file was added in Linux 3.19, @@ -913,7 +913,7 @@ and .I /proc/sys/kernel/overflowgid in .BR proc (5). -.PP +.P The cases where unmapped IDs are mapped in this fashion include system calls that return user IDs .RB ( getuid (2), @@ -941,7 +941,7 @@ credentials written to the process accounting file (see .BR acct (5)), and credentials returned with POSIX message queue notifications (see .BR mq_notify (3)). -.PP +.P There is one notable case where unmapped user and group IDs are .I not .\" from_kuid(), from_kgid() @@ -978,7 +978,7 @@ These capabilities are: .BR CAP_FOWNER , and .BR CAP_FSETID . -.PP +.P Within a user namespace, these capabilities allow a process to bypass the rules if the process has the relevant capability over the file, @@ -988,7 +988,7 @@ the process has the relevant effective capability in its user namespace; and .IP \[bu] the file's user ID and group ID both have valid mappings in the user namespace. -.PP +.P The .B CAP_FOWNER capability is treated somewhat exceptionally: @@ -1057,7 +1057,7 @@ User namespaces require support in a range of subsystems across the kernel. When an unsupported subsystem is configured into the kernel, it is not possible to configure user namespaces support. -.PP +.P As at Linux 3.8, most relevant subsystems supported user namespaces, but a number of filesystems did not have the infrastructure needed to map user and group IDs between user namespaces. @@ -1077,9 +1077,9 @@ The comments and .IR usage () function inside the program provide a full explanation of the program. The following shell session demonstrates its use. -.PP +.P First, we look at the run-time environment: -.PP +.P .in +4n .EX $ \fBuname \-rs\fP # Need Linux 3.8 or later @@ -1090,7 +1090,7 @@ $ \fBid \-g\fP 1000 .EE .in -.PP +.P Now start a new shell in new user .RI ( \-U ), mount @@ -1102,29 +1102,29 @@ namespaces, with user ID and group ID .RI ( \-G ) 1000 mapped to 0 inside the user namespace: -.PP +.P .in +4n .EX $ \fB./userns_child_exec \-p \-m \-U \-M \[aq]0 1000 1\[aq] \-G \[aq]0 1000 1\[aq] bash\fP .EE .in -.PP +.P The shell has PID 1, because it is the first process in the new PID namespace: -.PP +.P .in +4n .EX bash$ \fBecho $$\fP 1 .EE .in -.PP +.P Mounting a new .I /proc filesystem and listing all of the processes visible in the new PID namespace shows that the shell can't see any processes outside the PID namespace: -.PP +.P .in +4n .EX bash$ \fBmount \-t proc proc /proc\fP @@ -1134,10 +1134,10 @@ bash$ \fBps ax\fP 22 pts/3 R+ 0:00 ps ax .EE .in -.PP +.P Inside the user namespace, the shell has user and group ID 0, and a full set of permitted and effective capabilities: -.PP +.P .in +4n .EX bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha][UG]id\[aq]\fP @@ -1464,6 +1464,6 @@ main(int argc, char *argv[]) .BR credentials (7), .BR namespaces (7), .BR pid_namespaces (7) -.PP +.P The kernel source file .IR Documentation/admin\-guide/namespaces/resource\-control.rst . diff --git a/man7/utf-8.7 b/man7/utf-8.7 index 8a5f7ab..077fa42 100644 --- a/man7/utf-8.7 +++ b/man7/utf-8.7 @@ -7,7 +7,7 @@ .\" 2001-05-11 Markus Kuhn <mgk25@cl.cam.ac.uk> .\" Update .\" -.TH UTF-8 7 2023-03-12 "Linux man-pages 6.05.01" +.TH UTF-8 7 2024-03-14 "Linux man-pages 6.7" .SH NAME UTF-8 \- an ASCII compatible multibyte Unicode encoding .SH DESCRIPTION @@ -27,14 +27,13 @@ The ISO/IEC 10646 Universal Character Set (UCS), a superset of Unicode, occupies an even larger code space\[em]31\ bits\[em]and the obvious UCS-4 encoding for it (a sequence of 32-bit words) has the same problems. -.PP +.P The UTF-8 encoding of Unicode and UCS does not have these problems and is the common way in which Unicode is used on UNIX-style operating systems. .SS Properties The UTF-8 encoding has the following nice properties: -.TP 0.2i -* +.IP \[bu] 3 UCS characters 0x00000000 to 0x0000007f (the classic US-ASCII characters) are encoded simply as bytes 0x00 to 0x7f (ASCII @@ -43,24 +42,19 @@ This means that files and strings which contain only 7-bit ASCII characters have the same encoding under both ASCII and -UTF-8 . -.TP -* +UTF-8. +.IP \[bu] All UCS characters greater than 0x7f are encoded as a multibyte sequence consisting only of bytes in the range 0x80 to 0xfd, so no ASCII byte can appear as part of another character and there are no problems with, for example, \[aq]\e0\[aq] or \[aq]/\[aq]. -.TP -* +.IP \[bu] The lexicographic sorting order of UCS-4 strings is preserved. -.TP -* +.IP \[bu] All possible 2\[ha]31 UCS codes can be encoded using UTF-8. -.TP -* +.IP \[bu] The bytes 0xc0, 0xc1, 0xfe, and 0xff are never used in the UTF-8 encoding. -.TP -* +.IP \[bu] The first byte of a multibyte sequence which represents a single non-ASCII UCS character is always in the range 0xc2 to 0xfd and indicates how long this multibyte sequence is. @@ -68,8 +62,7 @@ All further bytes in a multibyte sequence are in the range 0x80 to 0xbf. This allows easy resynchronization and makes the encoding stateless and robust against missing bytes. -.TP -* +.IP \[bu] UTF-8 encoded UCS characters may be up to six bytes long, however the Unicode standard specifies no characters above 0x10ffff, so Unicode characters can be only up to four bytes long in @@ -77,7 +70,7 @@ UTF-8. .SS Encoding The following byte sequences are used to represent a character. The sequence to be used depends on the UCS code number of the character: -.TP 0.4i +.TP 0x00000000 \- 0x0000007F: .RI 0 xxxxxxx .TP @@ -110,14 +103,14 @@ The sequence to be used depends on the UCS code number of the character: .RI 10 xxxxxx .RI 10 xxxxxx .RI 10 xxxxxx -.PP +.P The .I xxx bit positions are filled with the bits of the character code number in binary representation, most significant bit first (big-endian). Only the shortest possible multibyte sequence which can represent the code number of the character can be used. -.PP +.P The UCS code values 0xd800\[en]0xdfff (UTF-16 surrogates) as well as 0xfffe and 0xffff (UCS noncharacters) should not appear in conforming UTF-8 streams. According to RFC 3629 no point above U+10FFFF should be used, @@ -125,45 +118,46 @@ which limits characters to four bytes. .SS Example The Unicode character 0xa9 = 1010 1001 (the copyright sign) is encoded in UTF-8 as -.PP +.P .RS 11000010 10101001 = 0xc2 0xa9 .RE -.PP +.P and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is encoded as: -.PP +.P .RS 11100010 10001001 10100000 = 0xe2 0x89 0xa0 .RE .SS Application notes Users have to select a UTF-8 locale, for example with -.PP +.P .RS export LANG=en_GB.UTF-8 .RE -.PP +.P in order to activate the UTF-8 support in applications. -.PP +.P Application software that has to be aware of the used character encoding should always set the locale with for example -.PP +.P .RS setlocale(LC_CTYPE, "") .RE -.PP +.P and programmers can then test the expression -.PP +.P .RS strcmp(nl_langinfo(CODESET), "UTF-8") == 0 .RE -.PP +.P to determine whether a UTF-8 locale has been selected and whether therefore all plaintext standard input and output, terminal communication, plaintext file content, filenames, and environment variables are encoded in UTF-8. -.PP -Programmers accustomed to single-byte encodings such as US-ASCII or ISO 8859 +.P +Programmers accustomed to single-byte encodings +such as US-ASCII or ISO/IEC\~8859 have to be aware that two assumptions made so far are no longer valid in UTF-8 locales. Firstly, a single byte does not necessarily correspond any @@ -178,14 +172,14 @@ Library functions such as and .BR wcswidth (3) should be used today to count characters and cursor positions. -.PP -The official ESC sequence to switch from an ISO 2022 +.P +The official ESC sequence to switch from an ISO/IEC\~2022 encoding scheme (as used for instance by VT100 terminals) to UTF-8 is ESC % G ("\ex1b%G"). The corresponding return sequence from -UTF-8 to ISO 2022 is ESC % @ ("\ex1b%@"). -Other ISO 2022 sequences (such as +UTF-8 to ISO/IEC\~2022 is ESC % @ ("\ex1b%@"). +Other ISO/IEC\~2022 sequences (such as for switching the G0 and G1 sets) are not applicable in UTF-8 mode. .SS Security The Unicode and UCS standards require that producers of UTF-8 diff --git a/man7/uts_namespaces.7 b/man7/uts_namespaces.7 index 670d19e..0b2a9a0 100644 --- a/man7/uts_namespaces.7 +++ b/man7/uts_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH uts_namespaces 7 2022-12-04 "Linux man-pages 6.05.01" +.TH uts_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME uts_namespaces \- overview of Linux UTS namespaces .SH DESCRIPTION @@ -21,7 +21,7 @@ and Changes made to these identifiers are visible to all other processes in the same UTS namespace, but are not visible to processes in other UTS namespaces. -.PP +.P When a process creates a new UTS namespace using .BR clone (2) or @@ -30,7 +30,7 @@ with the .B CLONE_NEWUTS flag, the hostname and domain name of the new UTS namespace are copied from the corresponding values in the caller's UTS namespace. -.PP +.P Use of UTS namespaces requires a kernel that is configured with the .B CONFIG_UTS_NS option. diff --git a/man7/vdso.7 b/man7/vdso.7 index 338ef72..d37360c 100644 --- a/man7/vdso.7 +++ b/man7/vdso.7 @@ -11,13 +11,13 @@ .\" http://www.linuxjournal.com/content/creating-vdso-colonels-other-chicken .\" http://www.trilithium.com/johan/2005/08/linux-gate/ .\" -.TH vDSO 7 2023-05-03 "Linux man-pages 6.05.01" +.TH vDSO 7 2024-02-18 "Linux man-pages 6.7" .SH NAME vdso \- overview of the virtual ELF dynamic shared object .SH SYNOPSIS .nf .B #include <sys/auxv.h> -.PP +.P .B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR); .fi .SH DESCRIPTION @@ -29,7 +29,7 @@ as the vDSO is most commonly called by the C library. This way you can code in the normal way using standard functions and the C library will take care of using any functionality that is available via the vDSO. -.PP +.P Why does the vDSO exist at all? There are some system calls the kernel provides that user-space code ends up using frequently, @@ -37,7 +37,7 @@ to the point that such calls can dominate overall performance. This is due both to the frequency of the call as well as the context-switch overhead that results from exiting user space and entering the kernel. -.PP +.P The rest of this documentation is geared toward the curious and/or C library writers rather than general developers. If you're trying to call the vDSO in your own application rather than using @@ -56,14 +56,14 @@ Rather than require the C library to figure out if this functionality is available at run time, the C library can use functions provided by the kernel in the vDSO. -.PP +.P Note that the terminology can be confusing. On x86 systems, the vDSO function used to determine the preferred method of making a system call is named "__kernel_vsyscall", but on x86-64, the term "vsyscall" also refers to an obsolete way to ask the kernel what time it is or what CPU the caller is on. -.PP +.P One frequently used system call is .BR gettimeofday (2). This system call is called both directly by user-space applications @@ -86,7 +86,7 @@ each program in the initial auxiliary vector (see via the .B AT_SYSINFO_EHDR tag. -.PP +.P You must not assume the vDSO is mapped at any particular location in the user's memory map. The base address will usually be randomized at run time every time a new @@ -95,7 +95,7 @@ process image is created (at time). This is done for security reasons, to prevent "return-to-libc" attacks. -.PP +.P For some architectures, there is also an .B AT_SYSINFO tag. @@ -111,7 +111,7 @@ and allows the C library to detect available functionality at run time when running under different kernel versions. Oftentimes the C library will do detection with the first call and then cache the result for subsequent calls. -.PP +.P All symbols are also versioned (using the GNU version format). This allows the kernel to update the function signature without breaking backward compatibility. @@ -120,12 +120,12 @@ return value. Thus, when looking up a symbol in the vDSO, you must always include the version to match the ABI you expect. -.PP +.P Typically the vDSO follows the naming convention of prefixing all symbols with "__vdso_" or "__kernel_" so as to distinguish them from other standard symbols. For example, the "gettimeofday" function is named "__vdso_gettimeofday". -.PP +.P You use the standard C calling conventions when calling any of these functions. No need to worry about weird register or stack behavior. @@ -134,7 +134,7 @@ No need to worry about weird register or stack behavior. When you compile the kernel, it will automatically compile and link the vDSO code for you. You will frequently find it under the architecture-specific directory: -.PP +.P .in +4n .EX find arch/$ARCH/ \-name \[aq]*vdso*.so*\[aq] \-o \-name \[aq]*gate*.so*\[aq] @@ -173,7 +173,7 @@ x86/x32 linux\-vdso.so.1 .ft P \} .SS strace(1), seccomp(2), and the vDSO -When tracing systems calls with +When tracing system calls with .BR strace (1), symbols (system calls) that are exported by the vDSO will .I not @@ -184,7 +184,7 @@ filters. .SH ARCHITECTURE-SPECIFIC NOTES The subsections below provide architecture-specific notes on the vDSO. -.PP +.P Note that the vDSO that is used is based on the ABI of your user-space code and not the ABI of the kernel. Thus, for example, @@ -211,14 +211,14 @@ __vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1) .in .ft P \} -.PP +.P .\" See linux/arch/arm/kernel/entry-armv.S .\" See linux/Documentation/arm/kernel_user_helpers.rst Additionally, the ARM port has a code page full of utility functions. Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. It does provide support for different versions though. -.PP +.P For information on this code page, it's best to refer to the kernel documentation as it's extremely detailed and covers everything you need to know: @@ -254,7 +254,7 @@ There is no provision for backward compatibility beyond sniffing raw opcodes, but as this is an embedded CPU, it can get away with things\[em]some of the object formats it runs aren't even ELF based (they're bFLT/FLAT). -.PP +.P For information on this code page, it's best to refer to the public documentation: .br @@ -295,7 +295,7 @@ __kernel_syscall_via_epc LINUX_2.5 .in .ft P \} -.PP +.P The Itanium port is somewhat tricky. In addition to the vDSO above, it also has "light-weight system calls" (also known as "fast syscalls" or "fsys"). @@ -337,12 +337,12 @@ the page to the process via the SR2 register. The permissions on the page are such that merely executing those addresses automatically executes with kernel privileges and not in user space. This is done to match the way HP-UX works. -.PP +.P Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. Simply call into the appropriate offset via the branch instruction, for example: -.PP +.P .in +4n .EX ble <offset>(%sr2, %r0) @@ -394,7 +394,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15 .in .ft P \} -.PP +.P Before Linux 5.6, .\" commit 654abc69ef2e69712e6d4e8a6cb9292b97a4aa39 the @@ -434,7 +434,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15 .in .ft P \} -.PP +.P Before Linux 4.16, .\" commit 5c929885f1bb4b77f85b1769c49405a0e0f154a1 the @@ -598,15 +598,15 @@ to user space, so it was reconceived as a vDSO in the current format. .BR syscalls (2), .BR getauxval (3), .BR proc (5) -.PP +.P The documents, examples, and source code in the Linux source code tree: -.PP +.P .in +4n .EX Documentation/ABI/stable/vdso Documentation/ia64/fsys.rst Documentation/vDSO/* (includes examples of using the vDSO) -.PP +.P find arch/ \-iname \[aq]*vdso*\[aq] \-o \-iname \[aq]*gate*\[aq] .EE .in diff --git a/man7/vsock.7 b/man7/vsock.7 index f6c3711..3d679c0 100644 --- a/man7/vsock.7 +++ b/man7/vsock.7 @@ -2,14 +2,14 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH vsock 7 2022-10-30 "Linux man-pages 6.05.01" +.TH vsock 7 2024-02-25 "Linux man-pages 6.7" .SH NAME vsock \- Linux VSOCK address family .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <linux/vm_sockets.h> -.PP +.P .IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);" .IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);" .fi @@ -19,7 +19,7 @@ the host they are running on. This address family is used by guest agents and hypervisor services that need a communications channel that is independent of virtual machine network configuration. -.PP +.P Valid socket types are .B SOCK_STREAM and @@ -31,26 +31,26 @@ provides a connectionless datagram packet service with best-effort delivery and best-effort ordering. Availability of these socket types is dependent on the underlying hypervisor. -.PP +.P A new socket is created with -.PP +.P .in +4n .EX socket(AF_VSOCK, socket_type, 0); .EE .in -.PP +.P When a process wants to establish a connection, it calls .BR connect (2) with a given destination socket address. The socket is automatically bound to a free port if unbound. -.PP +.P A process can listen for incoming connections by first binding to a socket address using .BR bind (2) and then calling .BR listen (2). -.PP +.P Data is transmitted using the .BR send (2) or @@ -67,7 +67,7 @@ The CID identifies the source or destination, which is either a virtual machine or the host. The port number differentiates between multiple services running on a single machine. -.PP +.P .in +4n .EX struct sockaddr_vm { @@ -83,7 +83,7 @@ struct sockaddr_vm { }; .EE .in -.PP +.P .I svm_family is always set to .BR AF_VSOCK . @@ -100,7 +100,7 @@ capability may to these port numbers. .I svm_zero must be zero-filled. -.PP +.P There are several special addresses: .B VMADDR_CID_ANY (\-1U) @@ -112,7 +112,7 @@ means any address for binding; .B VMADDR_CID_HOST (2) is the well-known address of the host. -.PP +.P The special constant .B VMADDR_PORT_ANY (\-1U) @@ -123,7 +123,7 @@ Connected .B SOCK_STREAM sockets become disconnected when the virtual machine migrates to a new host. Applications must reconnect when this happens. -.PP +.P The local CID may change across live migration if the old CID is not available on the new host. Bound sockets are automatically updated to the new CID. @@ -152,11 +152,11 @@ when binding instead of getting the local CID with (1) directs packets to the same host that generated them. This is useful for testing applications on a single host and for debugging. -.PP +.P The local CID obtained with .B IOCTL_VM_SOCKETS_GET_LOCAL_CID can be used for the same purpose, but it is preferable to use -.B VMADDR_CID_LOCAL . +.BR VMADDR_CID_LOCAL . .SH ERRORS .TP .B EACCES @@ -215,7 +215,7 @@ are valid. Support for VMware (VMCI) has been available since Linux 3.9. KVM (virtio) is supported since Linux 4.8. Hyper-V is supported since Linux 4.14. -.PP +.P .B VMADDR_CID_LOCAL is supported since Linux 5.6. .\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe @@ -4,14 +4,16 @@ .\" .\" $Id: x25.7,v 1.4 1999/05/18 10:35:12 freitag Exp $ .\" -.TH x25 7 2023-07-15 "Linux man-pages 6.05.01" +.TH x25 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -x25 \- ITU-T X.25 / ISO-8208 protocol interface +x25 +\- +ITU-T X.25 / ISO/IEC\~8208 protocol interface .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <linux/x25.h> -.PP +.P .IB x25_socket " = socket(AF_X25, SOCK_SEQPACKET, 0);" .fi .SH DESCRIPTION @@ -22,8 +24,8 @@ International Telecommunication Union's recommendation X.25 (X.25 DTE-DCE mode). X25 sockets can also be used for communication without an intermediate X.25 network (X.25 DTE-DTE mode) as described -in ISO-8208. -.PP +in ISO/IEC\~8208. +.P Message boundaries are preserved \[em] a .BR read (2) from a socket will @@ -47,7 +49,7 @@ socket address family uses the .I struct sockaddr_x25 for representing network addresses as defined in ITU-T recommendation X.121. -.PP +.P .in +4n .EX struct sockaddr_x25 { @@ -56,7 +58,7 @@ struct sockaddr_x25 { }; .EE .in -.PP +.P .I sx25_addr contains a char array .I x25_addr[] @@ -98,23 +100,23 @@ The AF_X25 protocol family is a new feature of Linux 2.2. .SH BUGS Plenty, as the X.25 PLP implementation is .BR CONFIG_EXPERIMENTAL . -.PP +.P This man page is incomplete. -.PP +.P There is no dedicated application programmer's header file yet; you need to include the kernel header file .IR <linux/x25.h> . .B CONFIG_EXPERIMENTAL might also imply that future versions of the interface are not binary compatible. -.PP +.P X.25 N-Reset events are not propagated to the user process yet. Thus, if a reset occurred, data might be lost without notice. .SH SEE ALSO .BR socket (2), .BR socket (7) -.PP +.P Jonathan Simon Naylor: \[lq]The Re-Analysis and Re-Implementation of X.25.\[rq] The URL is diff --git a/man7/xattr.7 b/man7/xattr.7 index c2f12c9..c90aaf8 100644 --- a/man7/xattr.7 +++ b/man7/xattr.7 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH xattr 7 2023-02-05 "Linux man-pages 6.05.01" +.TH xattr 7 2023-10-31 "Linux man-pages 6.7" .SH NAME xattr \- Extended attributes .SH DESCRIPTION @@ -15,7 +15,7 @@ files and directories, similar to the environment strings associated with a process. An attribute may be defined or undefined. If it is defined, its value may be empty or non-empty. -.PP +.P Extended attributes are extensions to the normal attributes which are associated with all inodes in the system (i.e., the .BR stat (2) @@ -23,11 +23,11 @@ data). They are often used to provide additional functionality to a filesystem\[em]for example, additional security features such as Access Control Lists (ACLs) may be implemented using extended attributes. -.PP +.P Users with search access to a file or directory may use .BR listxattr (2) to retrieve a list of attribute names defined for that file or directory. -.PP +.P Extended attributes are accessed as atomic objects. Reading .RB ( getxattr (2)) @@ -35,7 +35,7 @@ retrieves the whole value of an attribute and stores it in a buffer. Writing .RB ( setxattr (2)) replaces any previous value with the new value. -.PP +.P Space consumed for extended attributes may be counted towards the disk quotas of the file owner and file group. .SS Extended attribute namespaces @@ -48,14 +48,14 @@ form, for example, .IR system.posix_acl_access , or .IR security.selinux . -.PP +.P The namespace mechanism is used to define different classes of extended attributes. These different classes exist for several reasons; for example, the permissions and capabilities required for manipulating extended attributes of one namespace may differ to another. -.PP +.P Currently, the .IR security , .IR system , @@ -97,7 +97,7 @@ The access permissions for user attributes are defined by the file permission bits: read permission is required to retrieve the attribute value, and writer permission is required to change it. -.PP +.P The file permission bits of regular files and directories are interpreted differently from the file permission bits of special files and symbolic links. @@ -108,7 +108,7 @@ The file permissions of symbolic links are not used in access checks. These differences would allow users to consume filesystem resources in a way not controllable by disk quotas for group or world writable special files and directories. -.PP +.P For this reason, user extended attributes are allowed only for regular files and directories, and access to user extended attributes is restricted to the @@ -125,26 +125,26 @@ The list of attribute names that can be returned is also limited to 64\ kB (see BUGS in .BR listxattr (2)). -.PP +.P Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), require the filesystem to be mounted with the .B user_xattr mount option in order for user extended attributes to be used. -.PP +.P In the current ext2, ext3, and ext4 filesystem implementations, the total bytes used by the names and values of all of a file's extended attributes must fit in a single filesystem block (1024, 2048 or 4096 bytes, depending on the block size specified when the filesystem was created). -.PP +.P In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no practical limit on the number of extended attributes associated with a file, and the algorithms used to store extended attribute information on disk are scalable. -.PP +.P In the JFS, XFS, and Reiserfs filesystem implementations, the limit on bytes used in an EA value is the ceiling imposed by the VFS. -.PP +.P In the Btrfs filesystem implementation, the total bytes used for the name, value, and implementation overhead bytes is limited to the filesystem @@ -158,7 +158,7 @@ Since the filesystems on which extended attributes are stored might also be used on architectures with a different byte order and machine word size, care should be taken to store attribute values in an architecture-independent format. -.PP +.P This page was formerly named .BR attr (5). .\" .SH AUTHORS |