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 /man2 | |
| 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 'man2')
277 files changed, 4943 insertions, 4204 deletions
diff --git a/man2/_exit.2 b/man2/_exit.2 index 22cccd9..ea3ca63 100644 --- a/man2/_exit.2 +++ b/man2/_exit.2 @@ -6,7 +6,7 @@ .\" Modified Wed Jul 21 23:02:38 1993 by Rik Faith <faith@cs.unc.edu> .\" Modified 2001-11-17, aeb .\" -.TH _exit 2 2023-03-30 "Linux man-pages 6.05.01" +.TH _exit 2 2023-10-31 "Linux man-pages 6.7" .SH NAME _exit, _Exit \- terminate the calling process .SH LIBRARY @@ -15,19 +15,19 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "[[noreturn]] void _exit(int " status ); -.PP +.P .B #include <stdlib.h> -.PP +.P .BI "[[noreturn]] void _Exit(int " status ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR _Exit (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -45,14 +45,14 @@ operation). The process's parent is sent a .B SIGCHLD signal. -.PP +.P The value .I "status & 0xFF" is returned to the parent process as the process's exit status, and can be collected by the parent using one of the .BR wait (2) family of calls. -.PP +.P The function .BR _Exit () is equivalent to @@ -68,14 +68,14 @@ POSIX.1-2008. C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P .BR _Exit () was introduced by C99. .SH NOTES For a discussion on the effects of an exit, the transmission of exit status, zombie processes, signals sent, and so on, see .BR exit (3). -.PP +.P The function .BR _exit () is like @@ -108,7 +108,7 @@ which is to terminate a process, and these are the semantics specified by POSIX.1 and implemented by the C library wrapper function. On modern systems, this means termination of all threads in the process. -.PP +.P By contrast with the C library wrapper function, the raw Linux .BR _exit () system call terminates only the calling thread, and actions such as @@ -117,7 +117,7 @@ reparenting child processes or sending to the parent process are performed only if this is the last thread in the thread group. .\" _exit() is used by pthread_exit() to terminate the calling thread -.PP +.P Up to glibc 2.3, the .BR _exit () wrapper function invoked the kernel system call of the same name. diff --git a/man2/_syscall.2 b/man2/_syscall.2 index ef6542f..84612a1 100644 --- a/man2/_syscall.2 +++ b/man2/_syscall.2 @@ -16,15 +16,15 @@ .\" 2007-10-23 mtk: created as a new page, by taking the content .\" specific to the _syscall() macros from intro(2). .\" -.TH _syscall 2 2023-05-03 "Linux man-pages 6.05.01" +.TH _syscall 2 2024-02-26 "Linux man-pages 6.7" .SH NAME _syscall \- invoking a system call without library support (OBSOLETE) .SH SYNOPSIS .nf .B #include <linux/unistd.h> -.PP +.P A _syscall macro -.PP +.P desired system call .fi .SH DESCRIPTION @@ -33,13 +33,13 @@ You need to know how many arguments, their types, and the function return type. There are seven macros that make the actual call into the system easier. They have the form: -.PP +.P .in +4n .EX .RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...) .EE .in -.PP +.P where .IP .I X @@ -57,7 +57,7 @@ is the Nth argument's type .IP .I argN is the name of the Nth argument -.PP +.P These macros create a function called .I name with the arguments you @@ -85,7 +85,7 @@ The _syscall() macros produce a prototype. You may have to create one, especially for C++ users. -.PP +.P System calls are not required to return only positive or negative error codes. You need to read the source to be sure how it will return errors. @@ -106,7 +106,7 @@ when is negative. For the error codes, see .BR errno (3). -.PP +.P When defining a system call, the argument types .I must be @@ -123,7 +123,7 @@ passed by-value or by-pointer (for aggregates like structs). .\" Otherwise, the use of a _syscall macro is required. .\" .SH EXAMPLES -.\" [[deprecated]] SRC BEGIN (_syscall.c) +.\" SRC BEGIN (_syscall.c) .EX #include <stdio.h> #include <stdlib.h> diff --git a/man2/accept.2 b/man2/accept.2 index 340fdb8..bc73416 100644 --- a/man2/accept.2 +++ b/man2/accept.2 @@ -10,7 +10,7 @@ .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> .\" 2008-12-04, mtk, Add documentation of accept4() .\" -.TH accept 2 2023-04-05 "Linux man-pages 6.05.01" +.TH accept 2 2023-10-31 "Linux man-pages 6.7" .SH NAME accept, accept4 \- accept a connection on a socket .SH LIBRARY @@ -19,13 +19,13 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int accept(int " sockfd ", struct sockaddr *_Nullable restrict " addr , .BI " socklen_t *_Nullable restrict " addrlen ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sys/socket.h> -.PP +.P .BI "int accept4(int " sockfd ", struct sockaddr *_Nullable restrict " addr , .BI " socklen_t *_Nullable restrict " addrlen ", int " flags ); .fi @@ -44,7 +44,7 @@ The newly created socket is not in the listening state. The original socket .I sockfd is unaffected by this call. -.PP +.P The argument .I sockfd is a socket that has been created with @@ -53,7 +53,7 @@ bound to a local address with .BR bind (2), and is listening for connections after a .BR listen (2). -.PP +.P The argument .I addr is a pointer to a @@ -71,7 +71,7 @@ When is NULL, nothing is filled in; in this case, .I addrlen is not used, and should also be NULL. -.PP +.P The .I addrlen argument is a value-result argument: @@ -79,12 +79,12 @@ the caller must initialize it to contain the size (in bytes) of the structure pointed to by .IR addr ; on return it will contain the actual size of the peer address. -.PP +.P The returned address is truncated if the buffer provided is too small; in this case, .I addrlen will return a value greater than was supplied to the call. -.PP +.P If no pending connections are present on the queue, and the socket is not marked as nonblocking, @@ -97,7 +97,7 @@ fails with the error .B EAGAIN or .BR EWOULDBLOCK . -.PP +.P In order to be notified of incoming connections on a socket, you can use .BR select (2), .BR poll (2), @@ -112,7 +112,7 @@ Alternatively, you can set the socket to deliver when activity occurs on a socket; see .BR socket (7) for details. -.PP +.P If .I flags is 0, then @@ -222,7 +222,9 @@ The per-process limit on the number of open file descriptors has been reached. .B ENFILE The system-wide limit on the total number of open files has been reached. .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. @@ -241,7 +243,7 @@ Firewall rules forbid connection. .TP .B EPROTO Protocol error. -.PP +.P In addition, network errors for the new socket and as defined for the protocol may be returned. Various Linux kernels can @@ -313,7 +315,7 @@ needs to have the .B O_NONBLOCK flag set (see .BR socket (7)). -.PP +.P For certain protocols which require an explicit confirmation, such as DECnet, .BR accept () diff --git a/man2/access.2 b/man2/access.2 index 3f492d2..7e60a33 100644 --- a/man2/access.2 +++ b/man2/access.2 @@ -20,7 +20,7 @@ .\" Modified 2004-06-23 by Michael Kerrisk .\" 2007-06-10, mtk, various parts rewritten, and added BUGS section. .\" -.TH access 2 2023-03-30 "Linux man-pages 6.05.01" +.TH access 2 2024-01-01 "Linux man-pages 6.7" .SH NAME access, faccessat, faccessat2 \- check user's permissions for a file .SH LIBRARY @@ -29,30 +29,30 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int access(const char *" pathname ", int " mode ); -.PP +.P .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int faccessat(int " dirfd ", const char *" pathname ", int " \ mode ", int " flags ); /* But see C library/kernel differences, below */ -.PP +.P .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .B int syscall(SYS_faccessat2, .BI " int " dirfd ", const char *" pathname ", int " mode \ ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR faccessat (): .nf Since glibc 2.10: @@ -67,7 +67,7 @@ checks whether the calling process can access the file If .I pathname is a symbolic link, it is dereferenced. -.PP +.P The .I mode specifies the accessibility check(s) to be performed, @@ -81,7 +81,7 @@ tests for the existence of the file. .BR R_OK ", " W_OK ", and " X_OK test whether the file exists and grants read, write, and execute permissions, respectively. -.PP +.P The check is done using the calling process's .I real UID and GID, rather than the effective IDs as is done when @@ -92,7 +92,7 @@ Similarly, for the root user, the check uses the set of permitted capabilities rather than the set of effective capabilities; and for non-root users, the check uses an empty set of capabilities. -.PP +.P This allows set-user-ID programs and capability-endowed programs to easily determine the invoking user's authority. In other words, @@ -105,7 +105,7 @@ read/write/execute this file?", which gives set-user-ID programs the possibility to prevent malicious users from causing them to read files which users shouldn't be able to read. -.PP +.P If the calling process is privileged (i.e., its real UID is zero), then an .B X_OK @@ -116,7 +116,7 @@ is enabled for any of the file owner, group, or other. operates in exactly the same way as .BR access (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -126,7 +126,7 @@ referred to by the file descriptor the calling process, as is done by .BR access () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -138,13 +138,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR access ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P .I flags is constructed by ORing together zero or more of the following values: .TP @@ -155,12 +155,33 @@ By default, uses the real IDs (like .BR access ()). .TP +.BR AT_EMPTY_PATH " (since Linux 5.8)" +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +to obtain its definition. +.TP .B AT_SYMLINK_NOFOLLOW If .I pathname is a symbolic link, do not dereference it: instead return information about the link itself. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -346,20 +367,20 @@ interval between checking and opening the file to manipulate it. a safer alternative would be to temporarily switch the process's effective user ID to the real ID and then call .BR open (2).) -.PP +.P .BR access () always dereferences symbolic links. If you need to check the permissions on a symbolic link, use .BR faccessat () with the flag .BR AT_SYMLINK_NOFOLLOW . -.PP +.P These calls return an error if any of the access types in .I mode is denied, even if some of the other access types in .I mode are permitted. -.PP +.P A file is accessible only if the permissions on each of the directories in the path prefix of .I pathname @@ -367,7 +388,7 @@ grant search (i.e., execute) access. If any directory is inaccessible, then the .BR access () call fails, regardless of the permissions on the file itself. -.PP +.P Only access bits are checked, not the file type or contents. Therefore, if a directory is found to be writable, it probably means that files can be created in the directory, @@ -375,7 +396,7 @@ and not that the directory can be written as a file. Similarly, a DOS file may be reported as executable, but the .BR execve (2) call will still fail. -.PP +.P These calls may not work correctly on NFSv2 filesystems with UID mapping enabled, because UID mapping is done on the server and hidden from the client, @@ -401,7 +422,7 @@ Starting with glibc 2.33, the wrapper function avoids this bug by making use of the .BR faccessat2 () system call where it is provided by the underlying kernel. -.PP +.P In Linux 2.4 (and earlier) there is some strangeness in the handling of .B X_OK tests for superuser. @@ -424,7 +445,7 @@ returns 0 for such files. .\" This behavior appears to have been an implementation accident. Early Linux 2.6 (up to and including Linux 2.6.3) also behaved in the same way as Linux 2.4. -.PP +.P Before Linux 2.6.20, these calls ignored the effect of the .B MS_NOEXEC diff --git a/man2/acct.2 b/man2/acct.2 index de03a0e..d3ce589 100644 --- a/man2/acct.2 +++ b/man2/acct.2 @@ -9,7 +9,7 @@ .\" Modified 1998-11-04 by Tigran Aivazian <tigran@sco.com> .\" Modified 2004-05-27, 2004-06-17, 2004-06-23 by Michael Kerrisk .\" -.TH acct 2 2023-03-30 "Linux man-pages 6.05.01" +.TH acct 2 2023-10-31 "Linux man-pages 6.7" .SH NAME acct \- switch process accounting on or off .SH LIBRARY @@ -18,15 +18,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int acct(const char *_Nullable " filename ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR acct (): .nf Since glibc 2.21: @@ -129,7 +129,7 @@ SVr4, 4.3BSD. .SH NOTES No accounting is produced for programs running when a system crash occurs. In particular, nonterminating processes are never accounted for. -.PP +.P The structure of the records written to the accounting file is described in .BR acct (5). .SH SEE ALSO diff --git a/man2/add_key.2 b/man2/add_key.2 index 570db11..6e81ec9 100644 --- a/man2/add_key.2 +++ b/man2/add_key.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH add_key 2 2023-05-03 "Linux man-pages 6.05.01" +.TH add_key 2 2024-02-25 "Linux man-pages 6.7" .SH NAME add_key \- add a key to the kernel's key management facility .SH LIBRARY @@ -13,12 +13,12 @@ Standard C library .SH SYNOPSIS .nf .B #include <keyutils.h> -.PP +.P .BI "key_serial_t add_key(const char *" type ", const char *" description , .BI " const void " payload [. plen "], size_t " plen , .BI " key_serial_t " keyring ");" .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see NOTES. .SH DESCRIPTION @@ -34,10 +34,10 @@ of length attaches it to the nominated .IR keyring , and returns the key's serial number. -.PP +.P The key may be rejected if the provided data is in the wrong format or it is invalid in some other way. -.PP +.P If the destination .I keyring already contains a key that matches the specified @@ -55,7 +55,7 @@ and it will displace the link to the extant key from the keyring. .\" is consequently unlinked, then keys that it was anchoring .\" will have their reference count decreased by one (and may .\" consequently be garbage collected). Is this all correct? -.PP +.P The destination .I keyring serial number may be that of a valid keyring for which the caller has @@ -96,7 +96,7 @@ argument to .BR add_key () are the following: .TP -.I """keyring""" +.I \[dq]keyring\[dq] Keyrings are special key types that may contain links to sequences of other keys of any type. If this interface is used to create a keyring, then @@ -105,21 +105,21 @@ should be NULL and .I plen should be zero. .TP -.I """user""" +.I \[dq]user\[dq] This is a general purpose key type whose payload may be read and updated by user-space applications. The key is kept entirely within kernel memory. The payload for keys of this type is a blob of arbitrary data of up to 32,767 bytes. .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 permit the key to read. This is suitable for storing payloads that you do not want to be readable from user space. -.PP +.P This key type vets the .I description to ensure that it is qualified by a "service" prefix, @@ -127,15 +127,15 @@ by checking to ensure that the .I description contains a ':' that is preceded by other characters. .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 -.IR """user""" , +.IR \[dq]user\[dq] , but may hold a payload of up to 1\ MiB. If the key payload is large enough, then it may be stored encrypted in tmpfs (which can be swapped out) rather than kernel memory. -.PP +.P For further details on these key types, see .BR keyrings (7). .SH RETURN VALUE @@ -175,11 +175,11 @@ The payload data was invalid. .B EINVAL .I type was -.I """logon""" +.I \[dq]logon\[dq] and the .I description was not qualified with a prefix string of the form -.IR """service:""" . +.IR \[dq]service:\[dq] . .TP .B EKEYEXPIRED The keyring has expired. @@ -202,7 +202,7 @@ Key types that begin with a period are reserved to the implementation. .B EPERM .I type was -.I """keyring""" +.I \[dq]keyring\[dq] and the .I description started with a period (\[aq].\[aq]). @@ -227,7 +227,7 @@ The program below creates a key with the type, description, and payload specified in its command-line arguments, and links that key into the session keyring. The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX $ \fB./a.out user mykey "Some payload"\fP @@ -285,7 +285,7 @@ main(int argc, char *argv[]) .BR thread\-keyring (7), .BR user\-keyring (7), .BR user\-session\-keyring (7) -.PP +.P The kernel source files .I Documentation/security/keys/core.rst and diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 index c850a3d..e5264df 100644 --- a/man2/adjtimex.2 +++ b/man2/adjtimex.2 @@ -8,7 +8,7 @@ .\" Modified 1997-07-30 by Paul Slootman <paul@wurtel.demon.nl> .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH adjtimex 2 2023-07-20 "Linux man-pages 6.05.01" +.TH adjtimex 2 2023-10-31 "Linux man-pages 6.7" .SH NAME adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock .SH LIBRARY @@ -17,11 +17,11 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/timex.h> -.PP +.P .BI "int adjtimex(struct timex *" "buf" ); -.PP +.P .BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" ); -.PP +.P .BI "int ntp_adjtime(struct timex *" buf ); .fi .SH DESCRIPTION @@ -34,7 +34,7 @@ It takes a pointer to a structure, updates kernel parameters from (selected) field values, and returns the same structure updated with the current kernel values. This structure is declared as follows: -.PP +.P .in +4n .EX struct timex { @@ -81,7 +81,7 @@ struct timex { }; .EE .in -.PP +.P The .I modes field determines which parameters, if any, to set. @@ -204,7 +204,7 @@ and the difference between TAI and UTC, see .B ADJ_TICK Set tick value from .IR buf.tick . -.PP +.P Alternatively, .I modes can be specified as either of the following (multibit mask) values, @@ -236,13 +236,13 @@ This feature was added in Linux 2.6.24, but did not work correctly .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1 until Linux 2.6.28. -.PP +.P Ordinary users are restricted to a value of either 0 or .B ADJ_OFFSET_SS_READ for .IR modes . Only the superuser may set any parameters. -.PP +.P The .I buf.status field is a bit mask that is used to set and/or retrieve status @@ -346,7 +346,7 @@ Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop). .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db .\" Author: Roman Zippel <zippel@linux-m68k.org> Clock source (0 = A, 1 = B); currently unused. -.PP +.P Attempts to set read-only .I status bits are silently ignored. @@ -452,13 +452,13 @@ The symbolic name is a synonym for .BR TIME_ERROR , provided for backward compatibility. -.PP +.P Note that starting with Linux 3.4, .\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous .\" operation, so we can no longer rely on the return code. the call operates asynchronously and the return value usually will not reflect a state change caused by the call itself. -.PP +.P On failure, these calls return \-1 and set .I errno to indicate the error. @@ -548,14 +548,13 @@ T{ .BR \%ntp_adjtime () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR adjtimex () .TQ .BR clock_adjtime () Linux. -.PP +.P The preferred API for the NTP daemon is .BR ntp_adjtime (). .SH NOTES @@ -571,7 +570,7 @@ actually means 2\[ha]-16 ppm, and 2\[ha]16=65536 is 1 ppm. This is the case for both input values (in the case of .IR freq ) and output values. -.PP +.P The leap-second processing triggered by .B STA_INS and @@ -589,7 +588,7 @@ for the leap second to be inserted or deleted. .BR time (7), .BR adjtimex (8), .BR hwclock (8) -.PP +.P .ad l .UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm NTP "Kernel Application Program Interface" diff --git a/man2/alarm.2 b/man2/alarm.2 index cae0890..18a93ad 100644 --- a/man2/alarm.2 +++ b/man2/alarm.2 @@ -7,7 +7,7 @@ .\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer <aeb@cwi.nl> .\" Modified Wed Nov 6 03:46:05 1996 by Eric S. Raymond <esr@thyrsus.com> .\" -.TH alarm 2 2023-03-30 "Linux man-pages 6.05.01" +.TH alarm 2 2023-10-31 "Linux man-pages 6.7" .SH NAME alarm \- set an alarm clock for delivery of a signal .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "unsigned int alarm(unsigned int " seconds ); .fi .SH DESCRIPTION @@ -26,11 +26,11 @@ arranges for a signal to be delivered to the calling process in .I seconds seconds. -.PP +.P If .I seconds is zero, any pending alarm is canceled. -.PP +.P In any event any previously set .BR alarm () is canceled. @@ -49,14 +49,14 @@ and .BR setitimer (2) share the same timer; calls to one will interfere with use of the other. -.PP +.P Alarms created by .BR alarm () are preserved across .BR execve (2) and are not inherited by children created via .BR fork (2). -.PP +.P .BR sleep (3) may be implemented using .BR SIGALRM ; @@ -65,7 +65,7 @@ mixing calls to and .BR sleep (3) is a bad idea. -.PP +.P Scheduling delays can, as ever, cause the execution of the process to be delayed by an arbitrary amount of time. .SH SEE ALSO diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2 index 33671da..0aba97e 100644 --- a/man2/alloc_hugepages.2 +++ b/man2/alloc_hugepages.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH alloc_hugepages 2 2023-03-30 "Linux man-pages 6.05.01" +.TH alloc_hugepages 2 2023-10-31 "Linux man-pages 6.7" .SH NAME alloc_hugepages, free_hugepages \- allocate or free huge pages .SH SYNOPSIS @@ -15,7 +15,7 @@ size_t " len , .BI "int syscall(SYS_free_hugepages, void *" addr ); .\" asmlinkage int sys_free_hugepages(unsigned long addr); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -31,7 +31,7 @@ They existed only on i386 and ia64 (when built with In Linux 2.4.20, the syscall numbers exist, but the calls fail with the error .BR ENOSYS . -.PP +.P On i386 the memory management hardware knows about ordinary pages (4\ KiB) and huge pages (2 or 4\ MiB). Similarly ia64 knows about huge pages of @@ -39,7 +39,7 @@ several sizes. These system calls serve to map huge pages into the process's memory or to free them again. Huge pages are locked into memory, and are not swapped. -.PP +.P The .I key argument is an identifier. @@ -48,7 +48,7 @@ not inherited by children. When positive the pages are shared with other applications using the same .IR key , and inherited by child processes. -.PP +.P The .I addr argument of @@ -63,12 +63,12 @@ argument of .BR alloc_hugepages () is a hint, that the kernel may or may not follow. Addresses must be properly aligned. -.PP +.P The .I len argument is the length of the required segment. It must be a multiple of the huge page size. -.PP +.P The .I prot argument specifies the memory protection of the segment. @@ -76,7 +76,7 @@ It is one of .BR PROT_READ , .BR PROT_WRITE , .BR PROT_EXEC . -.PP +.P The .I flag argument is ignored, unless @@ -124,11 +124,11 @@ Memory backed by huge pages (if the CPU supports them) is obtained by using .BR mmap (2) to map files in this virtual filesystem. -.PP +.P The maximal number of huge pages can be specified using the .B hugepages= boot parameter. -.\".PP +.\".P .\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features") .\" and CONFIG_HUGETLBFS (under "Filesystems"). .\" mount \-t hugetlbfs hugetlbfs /huge diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2 index 04a3633..6981ec3 100644 --- a/man2/arch_prctl.2 +++ b/man2/arch_prctl.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH arch_prctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH arch_prctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME arch_prctl \- set architecture-specific thread state .SH LIBRARY @@ -13,11 +13,11 @@ Standard C library .BR "#include <asm/prctl.h>" " /* Definition of " ARCH_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP -.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long " addr ); -.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long *" addr ); +.P +.BI "int syscall(SYS_arch_prctl, int " op ", unsigned long " addr ); +.BI "int syscall(SYS_arch_prctl, int " op ", unsigned long *" addr ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR arch_prctl (), @@ -26,8 +26,8 @@ necessitating the use of .SH DESCRIPTION .BR arch_prctl () sets architecture-specific process or thread state. -.I code -selects a subfunction +.I op +selects an operation and passes argument .I addr to it; @@ -37,7 +37,7 @@ is interpreted as either an for the "set" operations, or as an .IR "unsigned long\ *" , for the "get" operations. -.PP +.P Subfunctions for both x86 and x86-64 are: .TP .BR ARCH_SET_CPUID " (since Linux 4.12)" @@ -120,8 +120,8 @@ is set to indicate the error. points to an unmapped address or is outside the process address space. .TP .B EINVAL -.I code -is not a valid subcommand. +.I op +is not a valid operation. .TP .B ENODEV .B ARCH_SET_CPUID @@ -137,12 +137,12 @@ Linux/x86-64. .SH NOTES .BR arch_prctl () is supported only on Linux/x86-64 for 64-bit programs currently. -.PP +.P The 64-bit base changes when a new 32-bit segment selector is loaded. -.PP +.P .B ARCH_SET_GS is disabled in some kernels. -.PP +.P Context switches for 64-bit segment bases are rather expensive. As an optimization, if a 32-bit TLS base address is used, .BR arch_prctl () @@ -154,14 +154,14 @@ Memory in the first 2\ GB of address space can be allocated by using with the .B MAP_32BIT flag. -.PP +.P Because of the aforementioned optimization, using .BR arch_prctl () and .BR set_thread_area (2) in the same thread is dangerous, as they may overwrite each other's TLS entries. -.PP +.P .I FS may be already used by the threading library. Programs that use @@ -172,5 +172,5 @@ directly are very likely to crash. .BR modify_ldt (2), .BR prctl (2), .BR set_thread_area (2) -.PP +.P AMD X86-64 Programmer's manual diff --git a/man2/bdflush.2 b/man2/bdflush.2 index d97949e..0f1ccca 100644 --- a/man2/bdflush.2 +++ b/man2/bdflush.2 @@ -5,13 +5,13 @@ .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH bdflush 2 2023-03-30 "Linux man-pages 6.05.01" +.TH bdflush 2 2023-10-31 "Linux man-pages 6.7" .SH NAME bdflush \- start, flush, or tune buffer-dirty-flush daemon .SH SYNOPSIS .nf .B #include <sys/kdaemon.h> -.PP +.P .BI "[[deprecated]] int bdflush(int " func ", long *" address ); .BI "[[deprecated]] int bdflush(int " func ", long " data ); .fi @@ -26,25 +26,25 @@ Nowadays, the task performed by is handled by the kernel .I pdflush thread. -.PP +.P .BR bdflush () starts, flushes, or tunes the buffer-dirty-flush daemon. Only a privileged process (one with the .B CAP_SYS_ADMIN capability) may call .BR bdflush (). -.PP +.P If .I func is negative or 0, and no daemon has been started, then .BR bdflush () enters the daemon code and never returns. -.PP +.P If .I func is 1, some dirty buffers are written to disk. -.PP +.P If .I func is 2 or more and is even (low bit is 0), then @@ -53,7 +53,7 @@ is the address of a long word, and the tuning parameter numbered .RI "(" "func" "\-2)/2" is returned to the caller in that address. -.PP +.P If .I func is 3 or more and is odd (low bit is 1), then @@ -62,7 +62,7 @@ is a long word, and the kernel sets tuning parameter numbered .RI "(" "func" "\-3)/2" to that value. -.PP +.P The set of parameters, their values, and their valid ranges are defined in the Linux kernel source file .IR fs/buffer.c . diff --git a/man2/bind.2 b/man2/bind.2 index 6288c41..0fc3308 100644 --- a/man2/bind.2 +++ b/man2/bind.2 @@ -18,7 +18,7 @@ .\" $Id: bind.2,v 1.3 1999/04/23 19:56:07 freitag Exp $ .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH bind 2 2023-05-03 "Linux man-pages 6.05.01" +.TH bind 2 2023-10-31 "Linux man-pages 6.7" .SH NAME bind \- bind a name to a socket .SH LIBRARY @@ -27,7 +27,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int bind(int " sockfd ", const struct sockaddr *" addr , .BI " socklen_t " addrlen ); .fi @@ -44,14 +44,14 @@ to the socket referred to by the file descriptor specifies the size, in bytes, of the address structure pointed to by .IR addr . Traditionally, this operation is called \[lq]assigning a name to a socket\[rq]. -.PP +.P It is normally necessary to assign a local address using .BR bind () before a .B SOCK_STREAM socket may receive connections (see .BR accept (2)). -.PP +.P The rules used in name binding vary between address families. Consult the manual entries in Section 7 for detailed information. For @@ -82,14 +82,14 @@ and for .BR AF_NETLINK , see .BR netlink (7). -.PP +.P The actual structure passed for the .I addr argument will depend on the address family. The .I sockaddr structure is defined as something like: -.PP +.P .in +4n .EX struct sockaddr { @@ -98,7 +98,7 @@ struct sockaddr { } .EE .in -.PP +.P The only purpose of this structure is to cast the structure pointer passed in .I addr @@ -147,7 +147,7 @@ is not a valid address for this socket's domain. The file descriptor .I sockfd does not refer to a socket. -.PP +.P The following errors are specific to UNIX domain .RB ( AF_UNIX ) sockets: @@ -206,14 +206,14 @@ An example of the use of .BR bind () with Internet domain sockets can be found in .BR getaddrinfo (3). -.PP +.P The following example shows how to bind a stream socket in the UNIX .RB ( AF_UNIX ) domain, and accept connections: .\" listen.7 refers to this example. .\" accept.7 refers to this example. .\" unix.7 refers to this example. -.PP +.P .\" SRC BEGIN (bind.c) .EX #include <stdio.h> @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH bpf 2 2023-07-28 "Linux man-pages 6.05.01" +.TH bpf 2 2024-03-18 "Linux man-pages 6.7" .SH NAME bpf \- perform a command on an extended BPF map or program .SH SYNOPSIS .nf .B #include <linux/bpf.h> -.PP +.P .BI "int bpf(int " cmd ", union bpf_attr *" attr ", unsigned int " size ); .fi .SH DESCRIPTION @@ -22,7 +22,7 @@ the original ("classic") BPF (cBPF) used to filter network packets. For both cBPF and eBPF programs, the kernel statically analyzes the programs before loading them, in order to ensure that they cannot harm the running system. -.PP +.P eBPF extends cBPF in multiple ways, including the ability to call a fixed set of in-kernel helper functions .\" See 'enum bpf_func_id' in include/uapi/linux/bpf.h @@ -36,13 +36,13 @@ eBPF maps are a generic data structure for storage of different data types. Data types are generally treated as binary blobs, so a user just specifies the size of the key and the size of the value at map-creation time. In other words, a key/value for a given map can have an arbitrary structure. -.PP +.P A user process can create multiple maps (with key/value-pairs being opaque bytes of data) and access them via file descriptors. Different eBPF programs can access the same maps in parallel. It's up to the user process and eBPF program to decide what they store inside maps. -.PP +.P There's one special map type, called a program array. This type of map stores file descriptors referring to other eBPF programs. When a lookup in the map is performed, the program flow is @@ -60,7 +60,7 @@ If a map lookup fails, the current program continues its execution. See .B BPF_MAP_TYPE_PROG_ARRAY below for further details. -.PP +.P Generally, eBPF programs are loaded by the user process and automatically unloaded when the process exits. In some cases, for example, @@ -74,7 +74,7 @@ Thus, whether a specific program continues to live inside the kernel depends on how it is further attached to a given kernel subsystem after it was loaded via .BR bpf (). -.PP +.P Each eBPF program is a set of instructions that is safe to run until its completion. An in-kernel verifier statically determines that the eBPF program @@ -82,7 +82,7 @@ terminates and is safe to execute. During verification, the kernel increments reference counts for each of the maps that the eBPF program uses, so that the attached maps can't be removed until the program is unloaded. -.PP +.P eBPF programs can be attached to different events. These events can be the arrival of network packets, tracing events, classification events by network queueing disciplines @@ -93,10 +93,10 @@ A new event triggers execution of the eBPF program, which may store information about the event in eBPF maps. Beyond storing data, eBPF programs may call a fixed set of in-kernel helper functions. -.PP +.P The same eBPF program can be attached to multiple events and different eBPF programs can access the same map: -.PP +.P .in +4n .EX tracing tracing tracing packet packet packet @@ -128,7 +128,7 @@ The .I size argument is the size of the union pointed to by .IR attr . -.PP +.P The value provided in .I cmd is one of the following: @@ -164,7 +164,7 @@ The union consists of various anonymous structures that are used by different .BR bpf () commands: -.PP +.P .in +4n .EX union bpf_attr { @@ -209,7 +209,7 @@ union bpf_attr { Maps are a generic data structure for storage of different types of data. They allow sharing of data between eBPF kernel programs, and also between kernel and user-space applications. -.PP +.P Each map type has the following attributes: .IP \[bu] 3 type @@ -219,7 +219,7 @@ maximum number of elements key size in bytes .IP \[bu] value size in bytes -.PP +.P The following wrapper functions demonstrate how various .BR bpf () commands can be used to access the maps. @@ -710,7 +710,7 @@ The command is used to load an eBPF program into the kernel. The return value for this command is a new file descriptor associated with this eBPF program. -.PP +.P .in +4n .EX char bpf_log_buf[LOG_BUF_SIZE]; @@ -734,7 +734,7 @@ bpf_prog_load(enum bpf_prog_type type, } .EE .in -.PP +.P .I prog_type is one of the available program types: .IP @@ -769,9 +769,9 @@ enum bpf_prog_type { }; .EE .in -.PP +.P For further details of eBPF program types, see below. -.PP +.P The remaining fields of .I bpf_attr are set as follows: @@ -814,16 +814,16 @@ verbosity level of the verifier. A value of zero means that the verifier will not provide a log; in this case, .I log_buf -must be a NULL pointer, and +must be a null pointer, and .I log_size must be zero. -.PP +.P Applying .BR close (2) to the file descriptor returned by .B BPF_PROG_LOAD will unload the eBPF program (but see NOTES). -.PP +.P Maps are accessible from eBPF programs and are used to exchange data between eBPF programs and between eBPF programs and user-space programs. For example, @@ -849,17 +849,17 @@ format of .\" Somewhere in this page we need a general introduction to the .\" bpf_context. For example, how does a BPF program access the .\" context? -.PP +.P For example, a tracing program does not have the exact same subset of helper functions as a socket filter program (though they may have some helpers in common). Similarly, the input (context) for a tracing program is a set of register values, while for a socket filter it is a network packet. -.PP +.P The set of functions available to eBPF programs of a given type may increase in the future. -.PP +.P The following program types are supported: .TP .BR BPF_PROG_TYPE_SOCKET_FILTER " (since Linux 3.19)" @@ -918,7 +918,7 @@ argument is a pointer to a .SS Events Once a program is loaded, it can be attached to an event. Various kernel subsystems have different ways to do so. -.PP +.P Since Linux 3.19, .\" commit 89aa075832b0da4402acebd698d0411dcc82d03e the following call will attach the program @@ -927,14 +927,14 @@ to the socket .IR sockfd , which was created by an earlier call to .BR socket (2): -.PP +.P .in +4n .EX setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF, &prog_fd, sizeof(prog_fd)); .EE .in -.PP +.P Since Linux 4.1, .\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 the following call may be used to attach @@ -944,7 +944,7 @@ to a perf event file descriptor, .IR event_fd , that was created by a previous call to .BR perf_event_open (2): -.PP +.P .in +4n .EX ioctl(event_fd, PERF_EVENT_IOC_SET_BPF, prog_fd); @@ -963,7 +963,7 @@ The new file descriptor associated with the eBPF program. .TP All other commands Zero. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -1091,10 +1091,10 @@ tail_call .IP \[bu] ktime_get_ns .PD -.PP +.P Unprivileged access may be blocked by writing the value 1 to the file .IR /proc/sys/kernel/unprivileged_bpf_disabled . -.PP +.P eBPF objects (maps and programs) can be shared between processes. For example, after .BR fork (2), @@ -1107,7 +1107,7 @@ in the usual way, using and similar calls. An eBPF object is deallocated only after all file descriptors referring to the object have been closed. -.PP +.P eBPF programs can be written in a restricted C that is compiled (using the .B clang compiler) into eBPF bytecode. @@ -1119,7 +1119,7 @@ Some examples can be found in the files in the kernel source tree. .\" There are also examples for the tc classifier, in the iproute2 .\" project, in examples/bpf -.PP +.P The kernel contains a just-in-time (JIT) compiler that translates eBPF bytecode into native machine code for better performance. Before Linux 4.15, @@ -1140,10 +1140,10 @@ The generated opcodes are dumped in hexadecimal into the kernel log. These opcodes can then be disassembled using the program .I tools/net/bpf_jit_disasm.c provided in the kernel source tree. -.PP +.P Since Linux 4.15, .\" commit 290af86629b25ffd1ed6232c4e9107da031705cb -the kernel may configured with the +the kernel may be configured with the .B CONFIG_BPF_JIT_ALWAYS_ON option. In this case, the JIT compiler is always enabled, and the @@ -1151,7 +1151,7 @@ In this case, the JIT compiler is always enabled, and the is initialized to 1 and is immutable. (This kernel configuration option was provided as a mitigation for one of the Spectre attacks against the BPF interpreter.) -.PP +.P The JIT compiler for eBPF is currently .\" Last reviewed in Linux 4.18-rc by grepping for BPF_ALU64 in arch/ .\" and by checking the documentation for bpf_jit_enable in @@ -1192,7 +1192,7 @@ riscv (since Linux 5.1). .\" commit 2353ecc6f91fd15b893fa01bf85a1c7a823ee4f2 .PD .SH EXAMPLES -.\" [[FIXME]] SRC BEGIN (bpf.c) +.\" SRC BEGIN (bpf.c) .EX /* bpf+sockets example: * 1. create array map of 256 elements @@ -1258,7 +1258,7 @@ main(int argc, char *argv[]) } .EE .\" SRC END -.PP +.P Some complete working code can be found in the .I samples/bpf directory in the kernel source tree. @@ -1268,6 +1268,6 @@ directory in the kernel source tree. .BR socket (7), .BR tc (8), .BR tc\-bpf (8) -.PP +.P Both classic and extended BPF are explained in the kernel source file .IR Documentation/networking/filter.txt . @@ -7,7 +7,7 @@ .\" Modified Wed Jul 21 19:52:58 1993 by Rik Faith <faith@cs.unc.edu> .\" Modified Sun Aug 21 17:40:38 1994 by Rik Faith <faith@cs.unc.edu> .\" -.TH brk 2 2023-03-30 "Linux man-pages 6.05.01" +.TH brk 2 2023-10-31 "Linux man-pages 6.7" .SH NAME brk, sbrk \- change data segment size .SH LIBRARY @@ -16,16 +16,16 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int brk(void *" addr ); .BI "void *sbrk(intptr_t " increment ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR brk (), .BR sbrk (): .nf @@ -57,14 +57,14 @@ uninitialized data segment). Increasing the program break has the effect of allocating memory to the process; decreasing the break deallocates memory. -.PP +.P .BR brk () sets the end of the data segment to the value specified by .IR addr , when that value is reasonable, the system has enough memory, and the process does not exceed its maximum data size (see .BR setrlimit (2)). -.PP +.P .BR sbrk () increments the program's data space by .I increment @@ -82,7 +82,7 @@ On error, \-1 is returned, and .I errno is set to .BR ENOMEM . -.PP +.P On success, .BR sbrk () returns the previous program break. @@ -113,7 +113,7 @@ the .BR malloc (3) memory allocation package is the portable and comfortable way of allocating memory. -.PP +.P Various systems use various types for the argument of .BR sbrk (). Common are \fIint\fP, \fIssize_t\fP, \fIptrdiff_t\fP, \fIintptr_t\fP. @@ -139,7 +139,7 @@ The glibc wrapper function does some work (i.e., checks whether the new break is less than .IR addr ) to provide the 0 and \-1 return values described above. -.PP +.P On Linux, .BR sbrk () is implemented as a library function that uses the diff --git a/man2/cacheflush.2 b/man2/cacheflush.2 index 733462e..b2a5f26 100644 --- a/man2/cacheflush.2 +++ b/man2/cacheflush.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH cacheflush 2 2023-03-30 "Linux man-pages 6.05.01" +.TH cacheflush 2 2023-10-31 "Linux man-pages 6.7" .SH NAME cacheflush \- flush contents of instruction and/or data cache .SH LIBRARY @@ -12,10 +12,10 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/cachectl.h> -.PP +.P .BI "int cacheflush(void " addr [. nbytes "], int "nbytes ", int "cache ); .fi -.PP +.P .IR Note : On some architectures, there is no glibc wrapper for this system call; see NOTES. @@ -73,7 +73,7 @@ glibc provides a wrapper for this system call, with the prototype shown in SYNOPSIS, for the following architectures: ARC, CSKY, MIPS, and NIOS2. -.PP +.P On some other architectures, Linux provides this system call, with different arguments: .TP @@ -92,7 +92,7 @@ NDS32: .nf .BI "int cacheflush(unsigned int " start ", unsigned int " end ", int " cache ); .fi -.PP +.P On the above architectures, glibc does not provide a wrapper for this system call; call it using .BR syscall (2). @@ -102,17 +102,17 @@ you probably want to use the GCC built-in function .BR __builtin___clear_cache (), which provides a portable interface across platforms supported by GCC and compatible compilers: -.PP +.P .in +4n .EX .BI "void __builtin___clear_cache(void *" begin ", void *" end ); .EE .in -.PP +.P On platforms that don't require instruction cache flushes, .BR __builtin___clear_cache () has no effect. -.PP +.P .IR Note : On some GCC-compatible compilers, the prototype for this built-in function uses @@ -133,7 +133,7 @@ and .I nbytes arguments, making this function fairly expensive. Therefore, the whole cache is always flushed. -.PP +.P This function always behaves as if .B BCACHE has been passed for the diff --git a/man2/capget.2 b/man2/capget.2 index 9c4ba7d..db9ad25 100644 --- a/man2/capget.2 +++ b/man2/capget.2 @@ -11,7 +11,7 @@ .\" 64-bit capability sets in Linux 2.6.2[45]. .\" Modified 2009-01-26, andi kleen .\" -.TH capget 2 2023-05-03 "Linux man-pages 6.05.01" +.TH capget 2 2023-10-31 "Linux man-pages 6.7" .SH NAME capget, capset \- set/get capabilities of thread(s) .SH LIBRARY @@ -23,13 +23,13 @@ Standard C library .BR " _LINUX_CAPABILITY_*" " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_capget, cap_user_header_t " hdrp , .BI " cap_user_data_t " datap ); .BI "int syscall(SYS_capset, cap_user_header_t " hdrp , .BI " const cap_user_data_t " datap ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -43,7 +43,7 @@ these system calls (in particular the format of the .I cap_user_*_t types) is subject to extension with each kernel revision, but old programs will keep working. -.PP +.P The portable interfaces are .BR cap_set_proc (3) and @@ -53,7 +53,7 @@ if possible, you should use those interfaces in applications; see NOTES. .SS Current details Now that you have been warned, some current kernel details. The structures are defined as follows. -.PP +.P .in +4n .EX #define _LINUX_CAPABILITY_VERSION_1 0x19980330 @@ -82,7 +82,7 @@ typedef struct __user_cap_data_struct { } *cap_user_data_t; .EE .in -.PP +.P The .IR effective , .IR permitted , @@ -99,7 +99,7 @@ To define the structures for passing to the system call, you have to use the and .I struct __user_cap_data_struct names because the typedefs are only pointers. -.PP +.P Kernels prior to Linux 2.6.25 prefer 32-bit capabilities with version .BR _LINUX_CAPABILITY_VERSION_1 . @@ -108,26 +108,26 @@ Linux 2.6.25 added 64-bit capability sets, with version There was, however, an API glitch, and Linux 2.6.26 added .B _LINUX_CAPABILITY_VERSION_3 to fix the problem. -.PP +.P Note that 64-bit capabilities use .I datap[0] and .IR datap[1] , whereas 32-bit capabilities use only .IR datap[0] . -.PP +.P On kernels that support file capabilities (VFS capabilities support), these system calls behave slightly differently. This support was added as an option in Linux 2.6.24, and became fixed (nonoptional) in Linux 2.6.33. -.PP +.P For .BR capget () calls, one can probe the capabilities of any process by specifying its process ID with the .I hdrp\->pid field value. -.PP +.P For details on the data, see .BR capabilities (7). .\" @@ -179,7 +179,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P The calls fail with the error .BR EINVAL , and set the diff --git a/man2/chdir.2 b/man2/chdir.2 index 5aca7bf..33e7473 100644 --- a/man2/chdir.2 +++ b/man2/chdir.2 @@ -10,7 +10,7 @@ .\" Modified 1997-08-21 by Joseph S. Myers <jsm28@cam.ac.uk> .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH chdir 2 2023-03-30 "Linux man-pages 6.05.01" +.TH chdir 2 2023-10-31 "Linux man-pages 6.7" .SH NAME chdir, fchdir \- change working directory .SH LIBRARY @@ -19,16 +19,16 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int chdir(const char *" path ); .BI "int fchdir(int " fd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fchdir (): .nf _XOPEN_SOURCE >= 500 @@ -41,7 +41,7 @@ Feature Test Macro Requirements for glibc (see changes the current working directory of the calling process to the directory specified in .IR path . -.PP +.P .BR fchdir () is identical to .BR chdir (); @@ -92,7 +92,7 @@ Insufficient kernel memory was available. A component of .I path is not a directory. -.PP +.P The general errors for .BR fchdir () are listed below: @@ -115,7 +115,7 @@ POSIX.1-2001, SVr4, 4.4BSD. .SH NOTES The current working directory is the starting point for interpreting relative pathnames (those not starting with \[aq]/\[aq]). -.PP +.P A child process created via .BR fork (2) inherits its parent's current working directory. diff --git a/man2/chmod.2 b/man2/chmod.2 index b1c130e..d7b9694 100644 --- a/man2/chmod.2 +++ b/man2/chmod.2 @@ -9,7 +9,7 @@ .\" <michael@cantor.informatik.rwth-aachen.de>: NFS details .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH chmod 2 2023-03-30 "Linux man-pages 6.05.01" +.TH chmod 2 2023-10-31 "Linux man-pages 6.7" .SH NAME chmod, fchmod, fchmodat \- change permissions of a file .SH LIBRARY @@ -18,22 +18,22 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/stat.h> -.PP +.P .BI "int chmod(const char *" pathname ", mode_t " mode ); .BI "int fchmod(int " fd ", mode_t " mode ); -.PP +.P .BR "#include <fcntl.h>" " /* Definition of AT_* constants */" .B #include <sys/stat.h> -.PP +.P .BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \ mode ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .nf .BR fchmod (): Since glibc 2.24: @@ -50,7 +50,7 @@ Feature Test Macro Requirements for glibc (see _BSD_SOURCE || _XOPEN_SOURCE >= 500 .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) .fi -.PP +.P .BR fchmodat (): .nf Since glibc 2.10: @@ -76,7 +76,7 @@ which is dereferenced if it is a symbolic link. .BR fchmod () changes the mode of the file referred to by the open file descriptor .IR fd . -.PP +.P The new file mode is specified in .IR mode , which is a bit mask created by ORing together zero or @@ -127,12 +127,12 @@ write by others .TP .BR S_IXOTH " (00001)" execute/search by others -.PP +.P The effective UID of the calling process must match the owner of the file, or the process must be privileged (Linux: it must have the .B CAP_FOWNER capability). -.PP +.P If the calling process is not privileged (Linux: does not have the .B CAP_FSETID capability), and the group of the file does not match @@ -141,7 +141,7 @@ supplementary group IDs, the .B S_ISGID bit will be turned off, but this will not cause an error to be returned. -.PP +.P As a security measure, depending on the filesystem, the set-user-ID and set-group-ID execution bits may be turned off if a file is written. @@ -153,7 +153,7 @@ which may have a special meaning. For the sticky bit, and for set-user-ID and set-group-ID bits on directories, see .BR inode (7). -.PP +.P On NFS filesystems, restricting the permissions will immediately influence already open files, because the access control is done on the server, but open files are maintained by the client. @@ -167,7 +167,7 @@ The system call operates in exactly the same way as .BR chmod (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -177,7 +177,7 @@ referred to by the file descriptor the calling process, as is done by .BR chmod () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -189,13 +189,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR chmod ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P .I flags can either be 0, or include the following flag: .TP @@ -205,7 +205,7 @@ If is a symbolic link, do not dereference it: instead operate on the link itself. This flag is not currently implemented. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -218,7 +218,7 @@ is set to indicate the error. .SH ERRORS Depending on the filesystem, errors other than those listed below can be returned. -.PP +.P The more general errors for .BR chmod () are listed below: diff --git a/man2/chown.2 b/man2/chown.2 index ff7c6dd..f71030d 100644 --- a/man2/chown.2 +++ b/man2/chown.2 @@ -15,7 +15,7 @@ .\" (bsdgroups versus sysvgroups, and the effect of the parent .\" directory's set-group-ID mode bit). .\" -.TH chown 2 2023-05-03 "Linux man-pages 6.05.01" +.TH chown 2 2023-10-31 "Linux man-pages 6.7" .SH NAME chown, fchown, lchown, fchownat \- change ownership of a file .SH LIBRARY @@ -24,23 +24,23 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group ); .BI "int fchown(int " fd ", uid_t " owner ", gid_t " group ); .BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group ); -.PP +.P .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" .B #include <unistd.h> -.PP +.P .BI "int fchownat(int " dirfd ", const char *" pathname , .BI " uid_t " owner ", gid_t " group ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fchown (), .BR lchown (): .nf @@ -49,7 +49,7 @@ Feature Test Macro Requirements for glibc (see .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR fchownat (): .nf Since glibc 2.10: @@ -79,7 +79,7 @@ changes the ownership of the file referred to by the open file descriptor is like .BR chown (), but does not dereference symbolic links. -.PP +.P Only a privileged process (Linux: one with the .B CAP_CHOWN capability) may change the owner of a file. @@ -88,13 +88,13 @@ to any group of which that owner is a member. A privileged process (Linux: with .BR CAP_CHOWN ) may change the group arbitrarily. -.PP +.P If the .I owner or .I group is specified as \-1, then that ID is not changed. -.PP +.P When the owner or group of an executable file is changed by an unprivileged user, the .B S_ISUID @@ -115,7 +115,7 @@ bit is not set) the .B S_ISGID bit indicates mandatory locking, and is not cleared by a .BR chown (). -.PP +.P When the owner or group of an executable file is changed (by any user), all capability sets for the file are cleared. .\" @@ -125,7 +125,7 @@ The system call operates in exactly the same way as .BR chown (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -135,7 +135,7 @@ referred to by the file descriptor the calling process, as is done by .BR chown () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -147,13 +147,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR chown ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P The .I flags argument is a bit mask created by ORing together @@ -192,7 +192,7 @@ instead operate on the link itself, like .BR fchownat () dereferences symbolic links, like .BR chown ().) -.PP +.P See .BR openat (2) for an explanation of the need for @@ -205,7 +205,7 @@ is set to indicate the error. .SH ERRORS Depending on the filesystem, errors other than those listed below can be returned. -.PP +.P The more general errors for .BR chown () are listed below. @@ -341,7 +341,7 @@ If the filesystem is mounted with and the set-group-ID bit is enabled on the parent directory, then the group of a new file is made the same as that of the parent directory. -.PP +.P As at Linux 4.12, the .B \-o\ grpid @@ -398,7 +398,7 @@ The glibc and .BR lchown () wrapper functions transparently deal with the variations across kernel versions. -.PP +.P Before Linux 2.1.81 (except 2.1.46), .BR chown () did not follow symbolic links. diff --git a/man2/chroot.2 b/man2/chroot.2 index d872b8a..bdba54f 100644 --- a/man2/chroot.2 +++ b/man2/chroot.2 @@ -10,7 +10,7 @@ .\" Modified 1997-08-21 by Joseph S. Myers <jsm28@cam.ac.uk> .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH chroot 2 2023-04-03 "Linux man-pages 6.05.01" +.TH chroot 2 2023-10-31 "Linux man-pages 6.7" .SH NAME chroot \- change root directory .SH LIBRARY @@ -19,15 +19,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int chroot(const char *" path ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR chroot (): .nf Since glibc 2.2.2: @@ -43,12 +43,12 @@ changes the root directory of the calling process to that specified in .IR path . This directory will be used for pathnames beginning with \fI/\fP. The root directory is inherited by all children of the calling process. -.PP +.P Only a privileged process (Linux: one with the .B CAP_SYS_CHROOT capability in its user namespace) may call .BR chroot (). -.PP +.P This call changes an ingredient in the pathname resolution process and does nothing else. In particular, it is not intended to be used @@ -65,7 +65,7 @@ The easiest way to do that is to .BR chdir (2) to the to-be-moved directory, wait for it to be moved out, then open a path like ../../../etc/passwd. -.PP +.P .\" This is how the "slightly trickier variation" works: .\" https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-014-2015.txt#L142 A slightly @@ -76,19 +76,19 @@ If a daemon allows a "chroot directory" to be specified, that usually means that if you want to prevent remote users from accessing files outside the chroot directory, you must ensure that folders are never moved out of it. -.PP +.P This call does not change the current working directory, so that after the call \[aq]\fI.\fP\[aq] can be outside the tree rooted at \[aq]\fI/\fP\[aq]. In particular, the superuser can escape from a "chroot jail" by doing: -.PP +.P .in +4n .EX mkdir foo; chroot foo; cd .. .EE .in -.PP +.P This call does not close open file descriptors, and such file descriptors may allow access to files outside the chroot tree. .SH RETURN VALUE @@ -148,13 +148,13 @@ A child process created via inherits its parent's root directory. The root directory is left unchanged by .BR execve (2). -.PP +.P The magic symbolic link, .IR /proc/ pid /root , can be used to discover a process's root directory; see .BR proc (5) for details. -.PP +.P FreeBSD has a stronger .BR jail () system call. diff --git a/man2/clock_getres.2 b/man2/clock_getres.2 index 170215d..ec1e327 100644 --- a/man2/clock_getres.2 +++ b/man2/clock_getres.2 @@ -9,32 +9,32 @@ .\" 2003-08-24 aeb, large parts rewritten .\" 2004-08-06 Christoph Lameter <clameter@sgi.com>, SMP note .\" -.TH clock_getres 2 2023-07-20 "Linux man-pages 6.05.01" +.TH clock_getres 2 2024-03-05 "Linux man-pages 6.7" .SH NAME clock_getres, clock_gettime, clock_settime \- clock and time functions .SH LIBRARY Standard C library .RI ( libc ", " \-lc ), since glibc 2.17 -.PP +.P Before glibc 2.17, Real-time library .RI ( librt ", " \-lrt ) .SH SYNOPSIS .nf .B #include <time.h> -.PP +.P .BI "int clock_getres(clockid_t " clockid ", struct timespec *_Nullable " res ); -.PP +.P .BI "int clock_gettime(clockid_t " clockid ", struct timespec *" tp ); .BI "int clock_settime(clockid_t " clockid ", const struct timespec *" tp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR clock_getres (), .BR clock_gettime (), .BR clock_settime (): @@ -60,14 +60,14 @@ is not a multiple of .IR res , then it is truncated to a multiple of .IR res . -.PP +.P The functions .BR clock_gettime () and .BR clock_settime () retrieve and set the time of the specified clock .IR clockid . -.PP +.P The .I res and @@ -75,24 +75,24 @@ and arguments are .BR timespec (3) structures. -.PP +.P The .I clockid argument is the identifier of the particular clock on which to act. A clock may be system-wide and hence visible for all processes, or per-process if it measures time only within a single process. -.PP +.P All implementations support the system-wide real-time clock, which is identified by .BR CLOCK_REALTIME . Its time represents seconds and nanoseconds since the Epoch. When its time is changed, timers for a relative interval are unaffected, but timers for an absolute point in time are affected. -.PP +.P More clocks may be implemented. The interpretation of the corresponding time values and the effect on timers is unspecified. -.PP +.P Sufficiently recent versions of glibc and the Linux kernel support the following clocks: .TP @@ -101,9 +101,17 @@ A settable system-wide clock that measures real (i.e., wall-clock) time. Setting this clock requires appropriate privileges. This clock is affected by discontinuous jumps in the system time (e.g., if the system administrator manually changes the clock), -and by the incremental adjustments performed by -.BR adjtime (3) -and NTP. +and by frequency adjustments performed by NTP and similar applications via +.BR adjtime (3), +.BR adjtimex (2), +.BR clock_adjtime (2), +and +.BR ntp_adjtime (3). +This clock normally counts the number of seconds since +1970-01-01 00:00:00 Coordinated Universal Time (UTC) +except that it ignores leap seconds; +near a leap second it is typically adjusted by NTP +to stay roughly in sync with UTC. .TP .BR CLOCK_REALTIME_ALARM " (since Linux 3.0; Linux-specific)" Like @@ -126,9 +134,9 @@ and probably also architecture support for this flag in the .BR CLOCK_TAI " (since Linux 3.10; Linux-specific)" .\" commit 1ff3c9677bff7e468e0c487d0ffefe4e901d33f4 A nonsettable system-wide clock derived from wall-clock time -but ignoring leap seconds. +but counting leap seconds. This clock does -not experience discontinuities and backwards jumps caused by NTP +not experience discontinuities or frequency adjustments caused by inserting leap seconds as .B CLOCK_REALTIME does. @@ -146,9 +154,7 @@ The .B CLOCK_MONOTONIC clock is not affected by discontinuous jumps in the system time (e.g., if the system administrator manually changes the clock), -but is affected by the incremental adjustments performed by -.BR adjtime (3) -and NTP. +but is affected by frequency adjustments. This clock does not count time that the system is suspended. All .B CLOCK_MONOTONIC @@ -170,9 +176,7 @@ and probably also architecture support for this flag in the Similar to .BR CLOCK_MONOTONIC , but provides access to a raw hardware-based time -that is not subject to NTP adjustments or -the incremental adjustments performed by -.BR adjtime (3). +that is not subject to frequency adjustments. This clock does not count time that the system is suspended. .TP .BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)" @@ -203,7 +207,7 @@ On Linux, this clock is not settable. .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" This is a clock that measures CPU time consumed by this thread. On Linux, this clock is not settable. -.PP +.P Linux also implements dynamic clock instances as described below. .SS Dynamic clocks In addition to the hard-coded System-V style clock IDs described above, @@ -211,7 +215,7 @@ Linux also supports POSIX clock operations on certain character devices. Such devices are called "dynamic" clocks, and are supported since Linux 2.6.39. -.PP +.P Using the appropriate macros, open file descriptors may be converted into clock IDs and passed to .BR clock_gettime (), @@ -220,7 +224,7 @@ and .BR clock_adjtime (2). The following example shows how to convert a file descriptor into a dynamic clock ID. -.PP +.P .in +4n .EX #define CLOCKFD 3 @@ -304,6 +308,17 @@ has disappeared after its character device was opened. The operation is not supported by the dynamic POSIX clock device specified. .TP +.B EOVERFLOW +The timestamp would not fit in +.I time_t +range. +This can happen if an executable with 32-bit +.I time_t +is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later. +However, when the system time is out of +.I time_t +range in other situations, the behavior is undefined. +.TP .B EPERM .BR clock_settime () does not have permission to set the clock indicated. @@ -323,11 +338,10 @@ T{ .BR clock_settime () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS POSIX.1 specifies the following: .RS -.PP +.P Setting the value of the .B CLOCK_REALTIME clock via @@ -339,7 +353,7 @@ function; nor on the expiration of relative timers based upon this clock. Consequently, these time services shall expire when the requested relative interval elapses, independently of the new or old value of the clock. .RE -.PP +.P According to POSIX.1-2001, a process with "appropriate privileges" may set the .B CLOCK_PROCESS_CPUTIME_ID and @@ -359,10 +373,12 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SUSv2. Linux 2.6. -.PP +.P On POSIX systems on which these functions are available, the symbol .B _POSIX_TIMERS is defined in \fI<unistd.h>\fP to a value greater than 0. +POSIX.1-2008 makes these functions mandatory. +.P The symbols .BR _POSIX_MONOTONIC_CLOCK , .BR _POSIX_CPUTIME , @@ -374,7 +390,6 @@ indicate that are available. (See also .BR sysconf (3).) -POSIX.1-2008 makes these APIs mandatory. .\" .SS Historical note for SMP systems Before Linux added kernel support for @@ -388,7 +403,7 @@ These registers may differ between CPUs and as a consequence these clocks may return .B bogus results if a process is migrated to another CPU. -.PP +.P If the CPUs in an SMP system have different clock sources, then there is no way to maintain a correlation between the timer registers since each CPU will run at a slightly different frequency. @@ -399,7 +414,7 @@ will return to signify this condition. The two clocks will then be useful only if it can be ensured that a process stays on a certain CPU. -.PP +.P The processors in an SMP system do not start all at exactly the same time and therefore the timer registers are typically running at an offset. Some architectures include code that attempts to limit these offsets on bootup. @@ -408,7 +423,7 @@ glibc contains no provisions to deal with these offsets (unlike the Linux Kernel). Typically these offsets are small and therefore the effects may be negligible in most cases. -.PP +.P Since glibc 2.4, the wrapper functions for the system calls described in this page avoid the abovementioned problems by employing the kernel implementation of @@ -424,7 +439,7 @@ and .BR clock_getres () with various clocks. This is an example of what we might see when running the program: -.PP +.P .in +4n .EX $ \fB./clock_times x\fP diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2 index d1e53a6..12948c7 100644 --- a/man2/clock_nanosleep.2 +++ b/man2/clock_nanosleep.2 @@ -3,31 +3,31 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH clock_nanosleep 2 2023-03-30 "Linux man-pages 6.05.01" +.TH clock_nanosleep 2 2024-03-05 "Linux man-pages 6.7" .SH NAME clock_nanosleep \- high-resolution sleep with specifiable clock .SH LIBRARY Standard C library .RI ( libc ", " \-lc ), since glibc 2.17 -.PP +.P Before glibc 2.17, Real-time library .RI ( librt ", " \-lrt ) .SH SYNOPSIS .B #include <time.h> .nf -.PP +.P .BI "int clock_nanosleep(clockid_t " clockid ", int " flags , -.BI " const struct timespec *" request , +.BI " const struct timespec *" t , .BI " struct timespec *_Nullable " remain ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR clock_nanosleep (): .nf _POSIX_C_SOURCE >= 200112L @@ -42,11 +42,11 @@ It differs in allowing the caller to select the clock against which the sleep interval is to be measured, and in allowing the sleep interval to be specified as either an absolute or a relative value. -.PP +.P The time values passed to and returned by this call are specified using .BR timespec (3) structures. -.PP +.P The .I clockid argument specifies the clock against which the sleep interval @@ -59,7 +59,7 @@ This argument can have one of the following values: A settable system-wide real-time clock. .TP .BR CLOCK_TAI " (since Linux 3.10)" -A system-wide clock derived from wall-clock time but ignoring leap seconds. +A system-wide clock derived from wall-clock time but counting leap seconds. .TP .B CLOCK_MONOTONIC A nonsettable, monotonically increasing clock that measures time @@ -77,7 +77,7 @@ A settable per-process clock that measures CPU time consumed by all threads in the process. .\" There is some trickery between glibc and the kernel .\" to deal with the CLOCK_PROCESS_CPUTIME_ID case. -.PP +.P See .BR clock_getres (2) for further details on these clocks. @@ -90,38 +90,38 @@ can also be passed in .\" Sleeping against CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM .\" is also possible (tested), with CAP_WAKE_ALARM, but I'm not .\" sure if this is useful or needs to be documented. -.PP +.P If .I flags is 0, then the value specified in -.I request +.I t is interpreted as an interval relative to the current value of the clock specified by .IR clockid . -.PP +.P If .I flags is .BR TIMER_ABSTIME , then -.I request +.I t is interpreted as an absolute time as measured by the clock, .IR clockid . If -.I request +.I t is less than or equal to the current value of the clock, then .BR clock_nanosleep () returns immediately without suspending the calling thread. -.PP +.P .BR clock_nanosleep () suspends the execution of the calling thread until either at least the time specified by -.I request +.I t has elapsed, or a signal is delivered that causes a signal handler to be called or that terminates the process. -.PP +.P If the call is interrupted by a signal handler, .BR clock_nanosleep () fails with the error @@ -146,7 +146,7 @@ then it returns one of the positive error number listed in ERRORS. .SH ERRORS .TP .B EFAULT -.I request +.I t or .I remain specified an invalid address. @@ -180,13 +180,13 @@ Linux 2.6, glibc 2.1. .SH NOTES If the interval specified in -.I request +.I t is not an exact multiple of the granularity underlying clock (see .BR time (7)), then the interval will be rounded up to the next multiple. Furthermore, after the sleep completes, there may still be a delay before the CPU becomes free to once again execute the calling thread. -.PP +.P Using an absolute timer is useful for preventing timer drift problems of the type described in .BR nanosleep (2). @@ -201,14 +201,14 @@ and then call with the .B TIMER_ABSTIME flag. -.PP +.P .BR clock_nanosleep () is never restarted after being interrupted by a signal handler, regardless of the use of the .BR sigaction (2) .B SA_RESTART flag. -.PP +.P The .I remain argument is unused, and unnecessary, when @@ -216,13 +216,13 @@ argument is unused, and unnecessary, when is .BR TIMER_ABSTIME . (An absolute sleep can be restarted using the same -.I request +.I t argument.) -.PP +.P POSIX.1 specifies that .BR clock_nanosleep () has no effect on signals dispositions or the signal mask. -.PP +.P POSIX.1 specifies that after changing the value of the .B CLOCK_REALTIME clock via @@ -234,7 +234,7 @@ will wake up; if the new clock value falls past the end of the sleep interval, then the .BR clock_nanosleep () call will return immediately. -.PP +.P POSIX.1 specifies that changing the value of the .B CLOCK_REALTIME diff --git a/man2/clone.2 b/man2/clone.2 index 38d2b90..69e4547 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -38,7 +38,7 @@ .\" 2008-11-19, mtk, document CLONE_NEWIPC .\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO .\" -.TH clone 2 2023-05-03 "Linux man-pages 6.05.01" +.TH clone 2 2024-02-18 "Linux man-pages 6.7" .SH NAME clone, __clone2, clone3 \- create a child process .SH LIBRARY @@ -47,27 +47,27 @@ Standard C library .SH SYNOPSIS .nf /* Prototype for the glibc wrapper function */ -.PP +.P .B #define _GNU_SOURCE .B #include <sched.h> -.PP +.P .BI "int clone(int (*" "fn" ")(void *_Nullable), void *" stack \ ", int " flags , .BI " void *_Nullable " "arg" ", ..." \ " \fR/*\fP" " pid_t *_Nullable " parent_tid , .BI " void *_Nullable " tls , .BI " pid_t *_Nullable " child_tid " \fR*/\fP );" -.PP +.P /* For the prototype of the raw clone() system call, see NOTES */ -.PP +.P .BR "#include <linux/sched.h>" " /* Definition of " "struct clone_args" " */" .BR "#include <sched.h>" " /* Definition of " CLONE_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR clone3 (), @@ -77,7 +77,7 @@ necessitating the use of These system calls create a new ("child") process, in a manner similar to .BR fork (2). -.PP +.P By contrast with .BR fork (2), these system calls provide more precise control over what pieces of execution @@ -88,7 +88,7 @@ the table of file descriptors, and the table of signal handlers. These system calls also allow the new child process to be placed in separate .BR namespaces (7). -.PP +.P Note that in this manual page, "calling process" normally corresponds to "parent process". But see the descriptions of @@ -96,7 +96,7 @@ But see the descriptions of and .B CLONE_THREAD below. -.PP +.P This page describes the following interfaces: .IP \[bu] 3 The glibc @@ -109,9 +109,9 @@ are described toward the end of this page. The newer .BR clone3 () system call. -.PP +.P In the remainder of this page, the terminology "the clone call" is used -when noting details that apply to all of these interfaces, +when noting details that apply to all of these interfaces. .\" .SS The clone() wrapper function When the child process is created with the @@ -129,7 +129,7 @@ The .I arg argument is passed as the argument of the function .IR fn . -.PP +.P When the .IR fn ( arg ) function returns, the child process terminates. @@ -139,7 +139,7 @@ is the exit status for the child process. The child process may also terminate explicitly by calling .BR exit (2) or after receiving a fatal signal. -.PP +.P The .I stack argument specifies the location of the stack used by the child process. @@ -159,7 +159,7 @@ Note that .BR clone () does not provide a means whereby the caller can inform the kernel of the size of the stack area. -.PP +.P The remaining arguments to .BR clone () are discussed below. @@ -174,20 +174,20 @@ It also provides a number of API improvements, including: space for additional flags bits; cleaner separation in the use of various arguments; and the ability to specify the size of the child's stack area. -.PP +.P As with .BR fork (2), .BR clone3 () returns in both the parent and the child. It returns 0 in the child process and returns the PID of the child in the parent. -.PP +.P The .I cl_args argument of .BR clone3 () is a structure of the following form: -.PP +.P .in +4n .EX struct clone_args { @@ -212,7 +212,7 @@ struct clone_args { }; .EE .in -.PP +.P The .I size argument that is supplied to @@ -223,7 +223,7 @@ should be initialized to the size of this structure. argument permits future extensions to the .I clone_args structure.) -.PP +.P The stack for the child process is specified via .IR cl_args.stack , which points to the lowest byte of the stack area, @@ -237,7 +237,7 @@ and specified. Otherwise, these two fields can be specified as NULL and 0, which causes the child to use the same stack area as the parent (in the child's own virtual address space). -.PP +.P The remaining fields in the .I cl_args argument are discussed below. @@ -253,7 +253,7 @@ structure shown above. This structure allows for a superset of the information passed via the .BR clone () arguments. -.PP +.P The following table shows the equivalence between the arguments of .BR clone () and the fields in the @@ -322,7 +322,7 @@ then the first element in the array has to be the desired PID and .I set_tid_size needs to be 1. -.PP +.P If the PID of the newly created process should have a certain value in multiple PID namespaces, then the .I set_tid @@ -335,7 +335,7 @@ The number of PID namespaces in which a PID should be set is defined by .I set_tid_size which cannot be larger than the number of currently nested PID namespaces. -.PP +.P To create a process with the following PIDs in a PID namespace hierarchy: .RS 4 .TS @@ -347,9 +347,9 @@ PID NS level Requested PID Notes 2 7 Innermost PID namespace .TE .RE -.PP +.P Set the array to: -.PP +.P .in +4n .EX set_tid[0] = 7; @@ -358,10 +358,10 @@ set_tid[2] = 31496; set_tid_size = 3; .EE .in -.PP +.P If only the PIDs in the two innermost PID namespaces need to be specified, set the array to: -.PP +.P .in +4n .EX set_tid[0] = 7; @@ -369,10 +369,10 @@ set_tid[1] = 42; set_tid_size = 2; .EE .in -.PP +.P The PID in the PID namespaces outside the two innermost PID namespaces is selected the same way as any other PID is selected. -.PP +.P The .I set_tid feature requires @@ -383,7 +383,7 @@ or .\" commit 1caef81da05a84a40dbf02110e967ce6d1135ff6 .B CAP_CHECKPOINT_RESTORE in all owning user namespaces of the target PID namespaces. -.PP +.P Callers may only choose a PID greater than 1 in a given PID namespace if an .B init @@ -410,7 +410,7 @@ field passed to referred to as the .I flags mask in the remainder of this page. -.PP +.P The .I flags mask is specified as a bitwise OR of zero or more of @@ -456,6 +456,8 @@ By default, signal dispositions in the child thread are the same as in the parent. If this flag is specified, then all signals that are handled in the parent +(and not set to +.BR SIG_IGN ) are reset to their default dispositions .RB ( SIG_DFL ) in the child. @@ -736,9 +738,7 @@ Only a privileged process can employ .BR CLONE_NEWPID . This flag can't be specified in conjunction with -.B CLONE_THREAD -or -.BR CLONE_PARENT . +.BR CLONE_THREAD . .TP .B CLONE_NEWUSER (This flag first became meaningful for @@ -1317,10 +1317,7 @@ were specified in the mask. .TP .B EINVAL -One (or both) of .B CLONE_NEWPID -or -.B CLONE_NEWUSER and one (or both) of .B CLONE_THREAD or @@ -1329,6 +1326,14 @@ were specified in the .I flags mask. .TP +.B EINVAL +.B CLONE_NEWUSER +and +.B CLONE_THREAD +were specified in the +.I flags +mask. +.TP .BR EINVAL " (since Linux 2.6.32)" .\" commit 123be07b0b399670a7cc3d82fef0cb4f93ef885c .B CLONE_PARENT @@ -1444,7 +1449,7 @@ or was specified in the .I flags mask, but a signal was specified in -.I exit_signal. +.IR exit_signal . .TP .BR EINVAL " (AArch64 only, Linux 4.6 and earlier)" .I stack @@ -1568,7 +1573,7 @@ So, in cases where is used to recursively create children, do not use the buffer employed for the parent's stack as the stack of the child. -.PP +.P On i386, .BR clone () should not be called through vsyscall, but directly through @@ -1587,7 +1592,7 @@ and arguments of the .BR clone () wrapper function are omitted. -.PP +.P In contrast to the glibc wrapper, the raw .BR clone () system call accepts NULL as a @@ -1609,14 +1614,14 @@ the parent's memory because of the use of the .B CLONE_VM flag, then no copy-on-write duplication occurs and chaos is likely to result.) -.PP +.P The order of the arguments also differs in the raw system call, and there are variations in the arguments across architectures, as detailed in the following paragraphs. -.PP +.P The raw system call interface on x86-64 and some other architectures (including sh, tile, and alpha) is: -.PP +.P .in +4n .EX .BI "long clone(unsigned long " flags ", void *" stack , @@ -1624,13 +1629,13 @@ The raw system call interface on x86-64 and some other architectures .BI " unsigned long " tls ); .EE .in -.PP +.P On x86-32, and several other common architectures (including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, and MIPS), .\" CONFIG_CLONE_BACKWARDS the order of the last two arguments is reversed: -.PP +.P .in +4n .EX .BI "long clone(unsigned long " flags ", void *" stack , @@ -1638,11 +1643,11 @@ the order of the last two arguments is reversed: .BI " int *" child_tid ); .EE .in -.PP +.P On the cris and s390 architectures, .\" CONFIG_CLONE_BACKWARDS2 the order of the first two arguments is reversed: -.PP +.P .in +4n .EX .BI "long clone(void *" stack ", unsigned long " flags , @@ -1650,11 +1655,11 @@ the order of the first two arguments is reversed: .BI " unsigned long " tls ); .EE .in -.PP +.P On the microblaze architecture, .\" CONFIG_CLONE_BACKWARDS3 an additional argument is supplied: -.PP +.P .in +4n .EX .BI "long clone(unsigned long " flags ", void *" stack , @@ -1673,7 +1678,7 @@ blackfin, m68k, and sparc are different from the descriptions above. For details, see the kernel (and glibc) source. .SS ia64 On ia64, a different interface is used: -.PP +.P .in +4n .EX .BI "int __clone2(int (*" "fn" ")(void *)," @@ -1683,13 +1688,13 @@ On ia64, a different interface is used: .BI " pid_t *" child_tid " */ );" .EE .in -.PP +.P The prototype shown above is for the glibc wrapper function; for the system call itself, the prototype can be described as follows (it is identical to the .BR clone () prototype on microblaze): -.PP +.P .in +4n .EX .BI "long clone2(unsigned long " flags ", void *" stack_base , @@ -1698,7 +1703,7 @@ prototype on microblaze): .BI " unsigned long " tls ); .EE .in -.PP +.P .BR __clone2 () operates in the same way as .BR clone (), @@ -1731,7 +1736,7 @@ However, from Linux 2.4.7 to Linux 2.4.18 the flag implied the .B CLONE_PARENT flag (as in Linux 2.6.0 and later). -.PP +.P In Linux 2.4 and earlier, .BR clone () does not take arguments @@ -1740,16 +1745,16 @@ does not take arguments and .IR child_tid . .SH NOTES -One use of these systems calls +One use of these system calls is to implement threads: multiple flows of control in a program that run concurrently in a shared address space. -.PP +.P The .BR kcmp (2) system call can be used to test whether two processes share various resources such as a file descriptor table, System V semaphore undo operations, or a virtual address space. -.PP +.P Handlers registered using .BR pthread_atfork (3) are not executed during a clone call. @@ -1784,7 +1789,7 @@ The stale-cache problem also does not occur if the argument includes .BR CLONE_VM .) To get the truth, it was sometimes necessary to use code such as the following: -.PP +.P .in +4n .EX #include <syscall.h> @@ -1797,7 +1802,7 @@ mypid = syscall(SYS_getpid); .\" See also the following bug reports .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910 -.PP +.P Because of the stale-cache problem, as well as other problems noted in .BR getpid (2), the PID caching feature was removed in glibc 2.25. @@ -1811,7 +1816,7 @@ making it possible to see that the hostname differs in the UTS namespaces of the parent and child. For an example of the use of this program, see .BR setns (2). -.PP +.P Within the sample program, we allocate the memory that is to be used for the child's stack using .BR mmap (2) diff --git a/man2/close.2 b/man2/close.2 index 239979b..c653acb 100644 --- a/man2/close.2 +++ b/man2/close.2 @@ -13,7 +13,7 @@ .\" Modified 2000-07-22 by Nicolás Lichtmaier <nick@debian.org> .\" added note about close(2) not guaranteeing that data is safe on close. .\" -.TH close 2 2023-03-30 "Linux man-pages 6.05.01" +.TH close 2 2023-10-31 "Linux man-pages 6.7" .SH NAME close \- close a file descriptor .SH LIBRARY @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int close(int " fd ); .fi .SH DESCRIPTION @@ -32,9 +32,15 @@ may be reused. Any record locks (see .BR fcntl (2)) held on the file it was associated with, -and owned by the process, are removed (regardless of the file -descriptor that was used to obtain the lock). -.PP +and owned by the process, +are removed regardless of the file descriptor that was used to obtain the lock. +This has some unfortunate consequences +and one should be extra careful when using advisory record locking. +See +.BR fcntl (2) +for discussion of the risks and consequences +as well as for the (probably preferred) open file description locks. +.P If .I fd is the last file descriptor referring to the underlying @@ -68,7 +74,9 @@ call was interrupted by a signal; see .B EIO An I/O error occurred. .TP -.BR ENOSPC ", " EDQUOT +.B ENOSPC +.TQ +.B EDQUOT On NFS, these errors are not normally reported against the first write which exceeds the available storage space, but instead against a subsequent @@ -76,7 +84,7 @@ subsequent .BR fsync (2), or .BR close (). -.PP +.P See NOTES for a discussion of why .BR close () should not be retried after an error. @@ -93,7 +101,7 @@ If you need to be sure that the data is physically stored on the underlying disk, use .BR fsync (2). (It will depend on the disk hardware at this point.) -.PP +.P The close-on-exec file descriptor flag can be used to ensure that a file descriptor is automatically closed upon a successful .BR execve (2); @@ -116,7 +124,7 @@ that may cause unintended side effects. .\" call has restarted after ERESTARTSYS, the original system call will .\" later restart with the reused file descriptor. This is most likely a .\" serious programming error. -.PP +.P Furthermore, consider the following scenario where two threads are performing operations on the same file descriptor: .IP (1) 5 @@ -128,11 +136,11 @@ to a pipe that is already full, or trying to from a stream socket which currently has no available data. .IP (2) Another thread closes the file descriptor. -.PP +.P The behavior in this situation varies across systems. On some systems, when the file descriptor is closed, the blocking system call returns immediately with an error. -.PP +.P On Linux (and possibly some other systems), the behavior is different: the blocking I/O system call holds a reference to the underlying open file description, and this reference keeps the description open @@ -158,13 +166,13 @@ Failing to check the return value when closing a file may lead to .I silent loss of data. This can especially be observed with NFS and with disk quota. -.PP +.P Note, however, that a failure return should be used only for diagnostic purposes (i.e., a warning to the application that there may still be I/O pending or there may have been failed I/O) or remedial purposes (e.g., writing the file once more or creating a backup). -.PP +.P Retrying the .BR close () after a failure return is the wrong thing to do, @@ -185,7 +193,7 @@ the steps that may return an error, .\" filp_close() such as flushing data to the filesystem or device, occur only later in the close operation. -.PP +.P Many other implementations similarly always close the file descriptor .\" FreeBSD documents this explicitly. From the look of the source code .\" SVR4, ancient SunOS, later Solaris, and AIX all do this. @@ -198,19 +206,19 @@ POSIX.1 is currently silent on this point, but there are plans to mandate this behavior in the next major release .\" Issue 8 of the standard. -.PP +.P A careful programmer who wants to know about I/O errors may precede .BR close () with a call to .BR fsync (2). -.PP +.P The .B EINTR error is a somewhat special case. Regarding the .B EINTR error, POSIX.1-2008 says: -.PP +.P .RS If .BR close () @@ -222,7 +230,7 @@ and the state of .I fildes is unspecified. .RE -.PP +.P This permits the behavior that occurs on Linux and many other implementations, where, as with other errors that may be reported by diff --git a/man2/close_range.2 b/man2/close_range.2 index c1aa3db..d9582b0 100644 --- a/man2/close_range.2 +++ b/man2/close_range.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH close_range 2 2023-05-03 "Linux man-pages 6.05.01" +.TH close_range 2 2024-02-25 "Linux man-pages 6.7" .SH NAME close_range \- close all file descriptors in a given range .SH LIBRARY @@ -11,10 +11,14 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.B #include <linux/close_range.h> -.PP -.BI "int close_range(unsigned int " first ", unsigned int " last , -.BI " unsigned int " flags ); +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <unistd.h> +.P +.BR "#include <linux/close_range.h>" " /* Definition of " CLOSE_RANGE_* +.BR "" " constants */" +.P +.BI "int close_range(unsigned int " first ", unsigned int " last \ +", int " flags ); .fi .SH DESCRIPTION The @@ -24,9 +28,9 @@ system call closes all open file descriptors from to .I last (included). -.PP +.P Errors closing a given file descriptor are currently ignored. -.PP +.P .I flags is a bit mask containing 0 or more of the following: .TP @@ -53,7 +57,7 @@ is not valid, or .I first is greater than .IR last . -.PP +.P The following can occur with .B CLOSE_RANGE_UNSHARE (when constructing the new descriptor table): @@ -97,7 +101,7 @@ which provides significant performance benefits. .SS Closing file descriptors before exec .\" 60997c3d45d9a67daf01c56d805ae4fec37e0bd8 File descriptors can be closed safely using -.PP +.P .in +4n .EX /* we don't want anything past stderr here */ @@ -105,17 +109,17 @@ close_range(3, \[ti]0U, CLOSE_RANGE_UNSHARE); execve(....); .EE .in -.PP +.P .B CLOSE_RANGE_UNSHARE is conceptually equivalent to -.PP +.P .in +4n .EX unshare(CLONE_FILES); close_range(first, last, 0); .EE .in -.PP +.P but can be more efficient: if the unshared range extends past the current maximum number of file descriptors allocated @@ -168,7 +172,7 @@ uses to close all file descriptors greater than or equal to 3, and then once more displays the process's list of open files. The following example demonstrates the use of the program: -.PP +.P .in +4n .EX $ \fBtouch /tmp/a /tmp/b /tmp/c\fP @@ -190,7 +194,7 @@ $ \fB./a.out /tmp/a /tmp/b /tmp/c\fP /proc/self/fd/3 ==> /proc/9005/fd .EE .in -.PP +.P Note that the lines showing the pathname .I /proc/9005/fd result from the calls to @@ -205,7 +209,6 @@ result from the calls to #include <limits.h> #include <stdio.h> #include <stdlib.h> -#include <sys/syscall.h> #include <unistd.h> \& /* Show the contents of the symbolic links in /proc/self/fd */ @@ -259,7 +262,7 @@ main(int argc, char *argv[]) \& printf("========= About to call close_range() =======\en"); \& - if (syscall(SYS_close_range, 3, \[ti]0U, 0) == \-1) { + if (close_range(3, \[ti]0U, 0) == \-1) { perror("close_range"); exit(EXIT_FAILURE); } diff --git a/man2/connect.2 b/man2/connect.2 index abd9e87..ad8888a 100644 --- a/man2/connect.2 +++ b/man2/connect.2 @@ -16,7 +16,7 @@ .\" Modified 1998, 1999 by Andi Kleen .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH connect 2 2023-03-30 "Linux man-pages 6.05.01" +.TH connect 2 2023-11-01 "Linux man-pages 6.7" .SH NAME connect \- initiate a connection on a socket .SH LIBRARY @@ -25,7 +25,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int connect(int " sockfd ", const struct sockaddr *" addr , .BI " socklen_t " addrlen ); .fi @@ -47,7 +47,7 @@ is determined by the address space of the socket see .BR socket (2) for further details. -.PP +.P If the socket .I sockfd is of type @@ -63,18 +63,18 @@ or this call attempts to make a connection to the socket that is bound to the address specified by .IR addr . -.PP +.P Some protocol sockets (e.g., UNIX domain stream sockets) may successfully .BR connect () only once. -.PP +.P Some protocol sockets (e.g., datagram sockets in the UNIX and Internet domains) may use .BR connect () multiple times to change their association. -.PP +.P Some protocol sockets (e.g., TCP sockets as well as datagram sockets in the UNIX and Internet domains) @@ -104,7 +104,9 @@ in the path prefix. (See also .BR path_resolution (7).) .TP -.BR EACCES ", " EPERM +.B EACCES +.TQ +.B EPERM The user tried to connect to a broadcast address without having the socket broadcast flag enabled or the connection request failed because of a local firewall rule. @@ -216,7 +218,7 @@ be very long when syncookies are enabled on the server. POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4, 4.4BSD, -.RB (connect () +.RB ( connect () first appeared in 4.2BSD). .\" SVr4 documents the additional .\" general error codes diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2 index 8bea2e8..aee9801 100644 --- a/man2/copy_file_range.2 +++ b/man2/copy_file_range.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH copy_file_range 2 2023-07-15 "Linux man-pages 6.05.01" +.TH copy_file_range 2 2023-10-31 "Linux man-pages 6.7" .SH NAME copy_file_range \- Copy a range of data from one file to another .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .B #define _GNU_SOURCE .B #define _FILE_OFFSET_BITS 64 .B #include <unistd.h> -.PP +.P .BI "ssize_t copy_file_range(int " fd_in ", off_t *_Nullable " off_in , .BI " int " fd_out ", off_t *_Nullable " off_out , .BI " size_t " len ", unsigned int " flags ); @@ -31,7 +31,7 @@ bytes of data from the source file descriptor to the target file descriptor .IR fd_out , overwriting any data that exists within the requested range of the target file. -.PP +.P The following semantics apply for .IR off_in , and similar statements apply to @@ -57,14 +57,14 @@ The file offset of is not changed, but .I off_in is adjusted appropriately. -.PP +.P .I fd_in and .I fd_out can refer to the same file. If they refer to the same file, then the source and target ranges are not allowed to overlap. -.PP +.P The .I flags argument is provided to allow for future extensions @@ -79,7 +79,7 @@ If the file offset of is at or past the end of file, no bytes are copied, and .BR copy_file_range () returns zero. -.PP +.P On error, .BR copy_file_range () returns \-1 and @@ -189,13 +189,13 @@ or do not support cross-filesystem copy. A major rework of the kernel implementation occurred in Linux 5.3. Areas of the API that weren't clearly defined were clarified and the API bounds are much more strictly checked than on earlier kernels. -.PP +.P Since Linux 5.19, cross-filesystem copies can be achieved when both filesystems are of the same type, and that filesystem implements support for it. See BUGS for behavior prior to Linux 5.19. -.PP +.P Applications should target the behaviour and requirements of Linux 5.19, that was also backported to earlier stable kernels. .SH STANDARDS @@ -219,13 +219,13 @@ in a loop, and using the and .B SEEK_HOLE operations to find the locations of data segments. -.PP +.P .BR copy_file_range () gives filesystems an opportunity to implement "copy acceleration" techniques, such as the use of reflinks (i.e., two or more inodes that share pointers to the same copy-on-write disk blocks) or server-side-copy (in the case of NFS). -.PP +.P .B _FILE_OFFSET_BITS should be defined to be 64 in code that uses non-null .I off_in diff --git a/man2/create_module.2 b/man2/create_module.2 index d159cb1..153acc2 100644 --- a/man2/create_module.2 +++ b/man2/create_module.2 @@ -5,19 +5,19 @@ .\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" -.TH create_module 2 2023-03-30 "Linux man-pages 6.05.01" +.TH create_module 2 2023-10-31 "Linux man-pages 6.7" .SH NAME create_module \- create a loadable module entry .SH SYNOPSIS .nf .B #include <linux/module.h> -.PP +.P .BI "[[deprecated]] caddr_t create_module(const char *" name ", size_t " size ); .fi .SH DESCRIPTION .IR Note : This system call is present only before Linux 2.6. -.PP +.P .BR create_module () attempts to create a loadable module entry and reserve the kernel memory that will be needed to hold the module. @@ -58,7 +58,7 @@ Linux. .SH HISTORY Removed in Linux 2.6. .\" Removed in Linux 2.5.48 -.PP +.P This obsolete system call is not supported by glibc. No declaration is provided in glibc headers, but, through a quirk of history, glibc versions before glibc 2.23 did export an ABI for this system call. diff --git a/man2/delete_module.2 b/man2/delete_module.2 index a909729..bbee49b 100644 --- a/man2/delete_module.2 +++ b/man2/delete_module.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH delete_module 2 2023-03-30 "Linux man-pages 6.05.01" +.TH delete_module 2 2023-10-31 "Linux man-pages 6.7" .SH NAME delete_module \- unload a kernel module .SH LIBRARY @@ -13,10 +13,10 @@ Standard C library .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR delete_module (), @@ -36,7 +36,7 @@ The argument is used to modify the behavior of the system call, as described below. This system call requires privilege. -.PP +.P Module removal is attempted according to the following rules: .IP (1) 5 If there are other loaded modules that depend on @@ -88,7 +88,7 @@ until the reference count is zero, at which point the call unblocks. The module is unloaded in the usual way. .RE .RE -.PP +.P The .B O_TRUNC flag has one further effect on the rules described above. @@ -100,7 +100,7 @@ function, then an attempt to remove the module fails. However, if .B O_TRUNC was specified, this requirement is bypassed. -.PP +.P Using the .B O_TRUNC flag is dangerous! @@ -174,13 +174,13 @@ alternatively, you can invoke the system call using .BR syscall (2). .SS Linux 2.4 and earlier In Linux 2.4 and earlier, the system call took only one argument: -.PP +.P .BI " int delete_module(const char *" name ); -.PP +.P If .I name is NULL, all unused modules marked auto-clean are removed. -.PP +.P Some further details of differences in the behavior of .BR delete_module () in Linux 2.4 and earlier are @@ -14,7 +14,7 @@ .\" details for dup2(). .\" 2008-10-09, mtk: add description of dup3() .\" -.TH dup 2 2023-05-03 "Linux man-pages 6.05.01" +.TH dup 2 2023-10-31 "Linux man-pages 6.7" .SH NAME dup, dup2, dup3 \- duplicate a file descriptor .SH LIBRARY @@ -23,14 +23,14 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int dup(int " oldfd ); .BI "int dup2(int " oldfd ", int " newfd ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int dup3(int " oldfd ", int " newfd ", int " flags ); .fi .SH DESCRIPTION @@ -43,7 +43,7 @@ open file description as the descriptor .BR open (2).) The new file descriptor number is guaranteed to be the lowest-numbered file descriptor that was unused in the calling process. -.PP +.P After a successful return, the old and new file descriptors may be used interchangeably. Since the two file descriptors refer to the same open file description, @@ -52,7 +52,7 @@ for example, if the file offset is modified by using .BR lseek (2) on one of the file descriptors, the offset is also changed for the other file descriptor. -.PP +.P The two file descriptors do not share file descriptor flags (the close-on-exec flag). The close-on-exec flag @@ -74,14 +74,14 @@ the file descriptor .I newfd is adjusted so that it now refers to the same open file description as .IR oldfd . -.PP +.P If the file descriptor .I newfd was previously open, it is closed before being reused; the close is performed silently (i.e., any errors during the close are not reported by .BR dup2 ()). -.PP +.P The steps of closing and reusing the file descriptor .I newfd are performed @@ -97,7 +97,7 @@ might be reused between the two steps. Such reuse could happen because the main program is interrupted by a signal handler that allocates a file descriptor, or because a parallel thread allocates a file descriptor. -.PP +.P Note the following points: .IP \[bu] 3 If @@ -233,7 +233,7 @@ also sometimes returns .B EINVAL like .BR F_DUPFD . -.PP +.P If .I newfd was open, any errors that would have been reported at @@ -249,7 +249,7 @@ before calling .BR dup2 (), because of the race condition described above. Instead, code something like the following could be used: -.PP +.P .in +4n .EX /* Obtain a duplicate of \[aq]newfd\[aq] that can subsequently diff --git a/man2/epoll_create.2 b/man2/epoll_create.2 index 8d2c0be..c6369f4 100644 --- a/man2/epoll_create.2 +++ b/man2/epoll_create.2 @@ -8,7 +8,7 @@ .\" Modified 2005-04-04 by Marko Kohtala <marko.kohtala@gmail.com> .\" 2008-10-10, mtk: add description of epoll_create1() .\" -.TH epoll_create 2 2023-07-16 "Linux man-pages 6.05.01" +.TH epoll_create 2 2023-10-31 "Linux man-pages 6.7" .SH NAME epoll_create, epoll_create1 \- open an epoll file descriptor .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/epoll.h> -.PP +.P .BI "int epoll_create(int " size ); .BI "int epoll_create1(int " flags ); .fi @@ -29,7 +29,7 @@ instance. Since Linux 2.6.8, the .I size argument is ignored, but must be greater than zero; see HISTORY. -.PP +.P .BR epoll_create () returns a file descriptor referring to the new epoll instance. This file descriptor is used for all the subsequent calls to the @@ -103,7 +103,7 @@ glibc 2.3.2. .BR epoll_create1 () Linux 2.6.27, glibc 2.9. -.PP +.P In the initial .BR epoll_create () implementation, the @@ -126,7 +126,7 @@ must still be greater than zero, in order to ensure backward compatibility when new .B epoll applications are run on older kernels. -.PP +.P Prior to Linux 2.6.29, .\" commit 9df04e1f25effde823a600e755b51475d438f56b a diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2 index e8ee1e6..73a0446 100644 --- a/man2/epoll_ctl.2 +++ b/man2/epoll_ctl.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH epoll_ctl 2 2023-04-03 "Linux man-pages 6.05.01" +.TH epoll_ctl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME epoll_ctl \- control interface for an epoll file descriptor .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/epoll.h> -.PP +.P .BI "int epoll_ctl(int " epfd ", int " op ", int " fd , .BI " struct epoll_event *_Nullable " event ); .fi @@ -28,7 +28,7 @@ It requests that the operation .I op be performed for the target file descriptor, .IR fd . -.PP +.P Valid values for the .I op argument are: @@ -58,7 +58,7 @@ from the interest list. The .I event argument is ignored and can be NULL (but see BUGS below). -.PP +.P The .I event argument describes the object linked to the file descriptor @@ -67,7 +67,7 @@ The .I struct epoll_event is described in .BR epoll_event (3type). -.PP +.P The .I data member of the @@ -75,7 +75,7 @@ member of the structure specifies data that the kernel should save and then return (via .BR epoll_wait (2)) when this file descriptor becomes ready. -.PP +.P The .I events member of the @@ -133,7 +133,7 @@ Note that when reading from a channel such as a pipe or a stream socket, this event merely indicates that the peer closed its end of the channel. Subsequent reads from the channel will return 0 (end of file) only after all outstanding data in the channel has been consumed. -.PP +.P And the available input flags are: .TP .B EPOLLET @@ -395,7 +395,7 @@ when using Applications that need to be portable to kernels before Linux 2.6.9 should specify a non-null pointer in .IR event . -.PP +.P If .B EPOLLWAKEUP is specified in diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2 index 5efaada..72d6fab 100644 --- a/man2/epoll_wait.2 +++ b/man2/epoll_wait.2 @@ -6,7 +6,7 @@ .\" .\" 2007-04-30: mtk, Added description of epoll_pwait() .\" -.TH epoll_wait 2 2023-05-03 "Linux man-pages 6.05.01" +.TH epoll_wait 2 2024-03-03 "Linux man-pages 6.7" .SH NAME epoll_wait, epoll_pwait, epoll_pwait2 \- wait for an I/O event on an epoll file descriptor @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/epoll.h> -.PP +.P .BI "int epoll_wait(int " epfd ", struct epoll_event *" events , .BI " int " maxevents ", int " timeout ); .BI "int epoll_pwait(int " epfd ", struct epoll_event *" events , @@ -46,7 +46,7 @@ are returned by The .I maxevents argument must be greater than zero. -.PP +.P The .I timeout argument specifies the number of milliseconds that @@ -55,7 +55,7 @@ will block. Time is measured against the .B CLOCK_MONOTONIC clock. -.PP +.P A call to .BR epoll_wait () will block until either: @@ -65,7 +65,7 @@ a file descriptor delivers an event; the call is interrupted by a signal handler; or .IP \[bu] the timeout expires. -.PP +.P Note that the .I timeout interval will be rounded up to the system clock granularity, @@ -77,15 +77,15 @@ of \-1 causes .BR epoll_wait () to block indefinitely, while specifying a .I timeout -equal to zero cause +equal to zero causes .BR epoll_wait () to return immediately, even if no events are available. -.PP +.P The .I struct epoll_event is described in .BR epoll_event (3type). -.PP +.P The .I data field of each returned @@ -95,7 +95,7 @@ in the most recent call to .BR epoll_ctl (2) .RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD ) for the corresponding open file descriptor. -.PP +.P The .I events field is a bit mask that indicates the events that have occurred for the @@ -118,21 +118,21 @@ like .BR epoll_pwait () allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. -.PP +.P The following .BR epoll_pwait () call: -.PP +.P .in +4n .EX ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask); .EE .in -.PP +.P is equivalent to .I atomically executing the following calls: -.PP +.P .in +4n .EX sigset_t origmask; @@ -142,7 +142,7 @@ ready = epoll_wait(epfd, &events, maxevents, timeout); pthread_sigmask(SIG_SETMASK, &origmask, NULL); .EE .in -.PP +.P The .I sigmask argument may be specified as NULL, in which case @@ -173,8 +173,8 @@ can block indefinitely. .SH RETURN VALUE On success, .BR epoll_wait () -returns the number of file descriptors ready for the requested I/O, or zero -if no file descriptor became ready during the requested +returns the number of file descriptors ready for the requested I/O operation, +or zero if no file descriptor became ready during the requested .I timeout milliseconds. On failure, @@ -233,7 +233,7 @@ If the new file descriptor becomes ready, it will cause the .BR epoll_wait () call to unblock. -.PP +.P If more than .I maxevents file descriptors are ready when @@ -245,7 +245,7 @@ This behavior helps avoid starvation scenarios, where a process fails to notice that additional file descriptors are ready because it focuses on a set of file descriptors that are already known to be ready. -.PP +.P Note that it is possible to call .BR epoll_wait () on an diff --git a/man2/eventfd.2 b/man2/eventfd.2 index 7be6a3a..2de063e 100644 --- a/man2/eventfd.2 +++ b/man2/eventfd.2 @@ -6,7 +6,7 @@ .\" .\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC .\" -.TH eventfd 2 2023-07-20 "Linux man-pages 6.05.01" +.TH eventfd 2 2023-10-31 "Linux man-pages 6.7" .SH NAME eventfd \- create a file descriptor for event notification .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/eventfd.h> -.PP +.P .BI "int eventfd(unsigned int " initval ", int " flags ); .fi .SH DESCRIPTION @@ -28,12 +28,12 @@ The object contains an unsigned 64-bit integer counter that is maintained by the kernel. This counter is initialized with the value specified in the argument .IR initval . -.PP +.P As its return value, .BR eventfd () returns a new file descriptor that can be used to refer to the eventfd object. -.PP +.P The following values may be bitwise ORed in .I flags to change the behavior of @@ -62,11 +62,11 @@ to achieve the same result. .BR EFD_SEMAPHORE " (since Linux 2.6.30)" Provide semaphore-like semantics for reads from the new file descriptor. See below. -.PP +.P Up to Linux 2.6.26, the .I flags argument is unused, and must be specified as zero. -.PP +.P The following operations can be performed on the file descriptor returned by .BR eventfd (): .TP @@ -142,7 +142,11 @@ fails with the error if the size of the supplied buffer is less than 8 bytes, or if an attempt is made to write the value 0xffffffffffffffff. .TP -.BR poll "(2), " select "(2) (and similar)" +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) The returned file descriptor supports .BR poll (2) (and analogously @@ -203,7 +207,7 @@ and When the file descriptor is no longer required it should be closed. When all file descriptors associated with the same eventfd object have been closed, the resources for object are freed by the kernel. -.PP +.P A copy of the file descriptor created by .BR eventfd () is inherited by the child produced by @@ -260,7 +264,6 @@ T{ .BR eventfd () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS C library/kernel differences There are two underlying Linux system calls: @@ -280,7 +283,7 @@ where it is available. The GNU C library defines an additional type, and two functions that attempt to abstract some of the details of reading and writing on an eventfd file descriptor: -.PP +.P .in +4n .EX typedef uint64_t eventfd_t; @@ -289,7 +292,7 @@ int eventfd_read(int fd, eventfd_t *value); int eventfd_write(int fd, eventfd_t value); .EE .in -.PP +.P The functions perform the read and write operations on an eventfd file descriptor, returning 0 if the correct number of bytes was transferred, @@ -318,13 +321,13 @@ The kernel overhead of an eventfd file descriptor is much lower than that of a pipe, and only one file descriptor is required (versus the two required for a pipe). -.PP +.P When used in the kernel, an eventfd file descriptor can provide a bridge from kernel to user space, allowing, for example, functionalities like KAIO (kernel AIO) .\" or eventually syslets/threadlets to signal to a file descriptor that some operation is complete. -.PP +.P A key point about an eventfd file descriptor is that it can be monitored just like any other file descriptor using .BR select (2), @@ -341,7 +344,7 @@ interface, these mechanisms could not be multiplexed via .BR poll (2), or .BR epoll (7).) -.PP +.P The current value of an eventfd counter can be viewed via the entry for the corresponding file descriptor in the process's .IR /proc/ pid /fdinfo @@ -357,9 +360,9 @@ the child writes each of the integers supplied in the program's command-line arguments to the eventfd file descriptor. When the parent has finished sleeping, it reads from the eventfd file descriptor. -.PP +.P The following shell session shows a sample run of the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out 1 2 4 7 14" diff --git a/man2/execve.2 b/man2/execve.2 index ae1863c..23404b5 100644 --- a/man2/execve.2 +++ b/man2/execve.2 @@ -14,7 +14,7 @@ .\" 2007-09-14 Ollie Wild <aaw@google.com>, mtk .\" Add text describing limits on command-line arguments + environment .\" -.TH execve 2 2023-05-03 "Linux man-pages 6.05.01" +.TH execve 2 2023-11-01 "Linux man-pages 6.7" .SH NAME execve \- execute program .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int execve(const char *" pathname ", char *const _Nullable " argv [], .BI " char *const _Nullable " envp []); .fi @@ -33,18 +33,18 @@ executes the program referred to by \fIpathname\fP. This causes the program that is currently being run by the calling process to be replaced with a new program, with newly initialized stack, heap, and (initialized and uninitialized) data segments. -.PP +.P \fIpathname\fP must be either a binary executable, or a script starting with a line of the form: -.PP +.P .in +4n .EX \fB#!\fP\fIinterpreter \fP[optional-arg] .EE .in -.PP +.P For details of the latter case, see "Interpreter scripts" below. -.PP +.P .I argv is an array of pointers to strings passed to the new program as its command-line arguments. @@ -53,19 +53,19 @@ By convention, the first of these strings (i.e., should contain the filename associated with the file being executed. The .I argv -array must be terminated by a NULL pointer. +array must be terminated by a null pointer. (Thus, in the new program, .I argv[argc] -will be NULL.) -.PP +will be a null pointer.) +.P .I envp is an array of pointers to strings, conventionally of the form .BR key=value , which are passed as the environment of the new program. The .I envp -array must be terminated by a NULL pointer. -.PP +array must be terminated by a null pointer. +.P This manual page describes the Linux system call in detail; for an overview of the nomenclature and the many, often preferable, standardised variants of this function provided by libc, @@ -73,31 +73,31 @@ including ones that search the .B PATH environment variable, see .BR exec (3). -.PP +.P The argument vector and environment can be accessed by the new program's main function, when it is defined as: -.PP +.P .in +4n .EX int main(int argc, char *argv[], char *envp[]) .EE .in -.PP +.P Note, however, that the use of a third argument to the main function is not specified in POSIX.1; according to POSIX.1, the environment should be accessed via the external variable .BR environ (7). -.PP +.P .BR execve () does not return on success, and the text, initialized data, uninitialized data (bss), and stack of the calling process are overwritten according to the contents of the newly loaded program. -.PP +.P If the current program is being ptraced, a \fBSIGTRAP\fP signal is sent to it after a successful .BR execve (). -.PP +.P If the set-user-ID bit is set on the program file referred to by \fIpathname\fP, then the effective user ID of the calling process is changed @@ -105,7 +105,7 @@ to that of the owner of the program file. Similarly, if the set-group-ID bit is set on the program file, then the effective group ID of the calling process is set to the group of the program file. -.PP +.P The aforementioned transformations of the effective IDs are .I not performed (i.e., the set-user-ID and set-group-ID bits are ignored) @@ -125,20 +125,20 @@ flag for or .IP \[bu] the calling process is being ptraced. -.PP +.P The capabilities of the program file (see .BR capabilities (7)) are also ignored if any of the above are true. -.PP +.P The effective user ID of the process is copied to the saved set-user-ID; similarly, the effective group ID is copied to the saved set-group-ID. This copying takes place after any effective ID changes that occur because of the set-user-ID and set-group-ID mode bits. -.PP +.P The process's real UID and real GID, as well as its supplementary group IDs, are unchanged by a call to .BR execve (). -.PP +.P If the executable is an a.out dynamically linked binary executable containing shared-library stubs, the Linux dynamic linker @@ -146,7 +146,7 @@ shared-library stubs, the Linux dynamic linker is called at the start of execution to bring needed shared objects into memory and link the executable with them. -.PP +.P If the executable is a dynamically linked ELF executable, the interpreter named in the PT_INTERP segment is used to load the needed shared objects. @@ -198,7 +198,7 @@ Exit handlers are not preserved .IP \[bu] The floating-point environment is reset to the default (see .BR fenv (3)). -.PP +.P The process attributes in the preceding list are all specified in POSIX.1. The following Linux-specific process attributes are also @@ -257,7 +257,7 @@ The file descriptor table is unshared, undoing the effect of the .B CLONE_FILES flag of .BR clone (2). -.PP +.P Note the following further points: .IP \[bu] 3 All threads other than the calling thread are destroyed during an @@ -313,17 +313,17 @@ closed across an .SS Interpreter scripts An interpreter script is a text file that has execute permission enabled and whose first line is of the form: -.PP +.P .in +4n .EX \fB#!\fP\fIinterpreter \fP[optional-arg] .EE .in -.PP +.P The .I interpreter must be a valid pathname for an executable file. -.PP +.P If the .I pathname argument of @@ -331,13 +331,13 @@ argument of specifies an interpreter script, then .I interpreter will be invoked with the following arguments: -.PP +.P .in +4n .EX \fIinterpreter\fP [optional-arg] \fIpathname\fP arg... .EE .in -.PP +.P where .I pathname is the pathname of the file specified as the first argument of @@ -358,12 +358,12 @@ call. .\" See the P - preserve-argv[0] option. .\" Documentation/admin-guide/binfmt-misc.rst .\" https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html -.PP +.P For portable use, .I optional-arg should either be absent, or be specified as a single word (i.e., it should not contain white space); see NOTES below. -.PP +.P Since Linux 2.6.28, .\" commit bf2a9a39639b8b51377905397a5005f444e9a892 the kernel permits the interpreter of a script to itself be a script. @@ -383,14 +383,14 @@ constant (either defined in .I <limits.h> or available at run time using the call .IR "sysconf(_SC_ARG_MAX)" ). -.PP +.P Before Linux 2.6.23, the memory used to store the environment and argument strings was limited to 32 pages (defined by the kernel constant .BR MAX_ARG_PAGES ). On architectures with a 4-kB page size, this yields a maximum size of 128\ kB. -.PP +.P On Linux 2.6.23 and later, most architectures support a size limit derived from the soft .B RLIMIT_STACK @@ -443,7 +443,12 @@ The total number of bytes in the environment .RI ( envp ) and argument list .RI ( argv ) -is too large. +is too large, +an argument or environment string is too long, +or the full +.I pathname +of the executable is too long. +The terminating null byte is counted as part of the string length. .TP .B EACCES Search permission is denied on a component of the path prefix of @@ -555,7 +560,7 @@ The specified executable was open for writing by one or more processes. .SH VERSIONS POSIX does not document the #! behavior, but it exists (with some variations) on other UNIX systems. -.PP +.P On Linux, .I argv and @@ -577,7 +582,7 @@ case the same as Linux. .\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408 .\" Bug rejected (because fix would constitute an ABI change). .\" -.PP +.P POSIX.1 says that values returned by .BR sysconf (3) should be invariant over the lifetime of a process. @@ -597,7 +602,7 @@ Before Linux 5.1, the limit is 127 characters. Since Linux 5.1, .\" commit 6eb3c3d0a52dca337e327ae8868ca1f44a712e02 the limit is 255 characters. -.PP +.P The semantics of the .I optional-arg argument of an interpreter script vary across implementations. @@ -616,7 +621,7 @@ an interpreter script can have multiple arguments, and white spaces in .I optional-arg are used to delimit the arguments. -.PP +.P Linux (like most other modern UNIX systems) ignores the set-user-ID and set-group-ID bits on scripts. .SH STANDARDS @@ -627,7 +632,7 @@ POSIX.1-2001, SVr4, 4.3BSD. .\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not .\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, .\" EISDIR or ELIBBAD error conditions. -.PP +.P With UNIX\ V6, the argument list of an .BR exec () call was ended by 0, @@ -654,10 +659,10 @@ All that .BR execve () does is arrange for an existing process (the calling process) to execute a new program. -.PP +.P Set-user-ID and set-group-ID processes can not be .BR ptrace (2)d. -.PP +.P The result of mounting a filesystem .I nosuid varies across Linux kernel versions: @@ -668,7 +673,7 @@ give the user powers they did not have already (and return some will just ignore the set-user-ID and set-group-ID bits and .BR exec () successfully. -.PP +.P In most cases where .BR execve () fails, control returns to the original executable image, @@ -691,7 +696,7 @@ A more detailed explanation of the error that can occur (since Linux 3.1) when calling .BR execve () is as follows. -.PP +.P The .B EAGAIN error can occur when a @@ -713,7 +718,7 @@ call to fail. .\" commit 909cc4ae86f3380152a18e2a3c44523893ee11c4 the resource limit was not imposed on processes that changed their user IDs.) -.PP +.P Since Linux 3.1, the scenario just described no longer causes the .BR set*uid () call to fail, @@ -744,7 +749,7 @@ common privileged daemon workflow\[em]namely, .BR set*uid () + .BR execve (). -.PP +.P If the resource limit was not still exceeded at the time of the .BR execve () call @@ -772,7 +777,7 @@ by this process succeeds. .SH EXAMPLES The following program is designed to be execed by the second program below. It just echoes its command-line arguments, one per line. -.PP +.P .in +4n .\" SRC BEGIN (myecho.c) .EX @@ -792,10 +797,10 @@ main(int argc, char *argv[]) .EE .\" SRC END .in -.PP +.P This program can be used to exec the program named in its command-line argument: -.PP +.P .in +4n .\" SRC BEGIN (execve.c) .EX @@ -825,9 +830,9 @@ main(int argc, char *argv[]) .EE .\" SRC END .in -.PP +.P We can use the second program to exec the first as follows: -.PP +.P .in +4n .EX .RB "$" " cc myecho.c \-o myecho" @@ -838,13 +843,13 @@ argv[1]: hello argv[2]: world .EE .in -.PP +.P We can also use these programs to demonstrate the use of a script interpreter. To do this we create a script whose "interpreter" is our .I myecho program: -.PP +.P .in +4n .EX .RB "$" " cat > script" @@ -853,9 +858,9 @@ program: .RB "$" " chmod +x script" .EE .in -.PP +.P We can then use our program to exec the script: -.PP +.P .in +4n .EX .RB "$" " ./execve ./script" diff --git a/man2/execveat.2 b/man2/execveat.2 index 22c468a..3a612ae 100644 --- a/man2/execveat.2 +++ b/man2/execveat.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH execveat 2 2023-03-30 "Linux man-pages 6.05.01" +.TH execveat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME execveat \- execute program relative to a directory file descriptor .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int execveat(int " dirfd ", const char *" pathname , .BI " char *const _Nullable " argv [], .BI " char *const _Nullable " envp [], @@ -30,7 +30,7 @@ and It operates in exactly the same way as .BR execve (2), except for the differences described in this manual page. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -40,7 +40,7 @@ referred to by the file descriptor the calling process, as is done by .BR execve (2) for a relative pathname). -.PP +.P If .I pathname is relative and @@ -52,13 +52,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR execve (2)). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P If .I pathname is an empty string and the @@ -68,7 +68,7 @@ flag is specified, then the file descriptor specifies the file to be executed (i.e., .I dirfd refers to an executable file, rather than a directory). -.PP +.P The .I flags argument is a bit mask that can include zero or more of the following flags: @@ -160,7 +160,7 @@ system call is also needed to allow to be implemented on systems that do not have the .I /proc filesystem mounted. -.PP +.P When asked to execute a script file, the .I argv[0] that is passed to the script interpreter is a string of the form @@ -183,7 +183,7 @@ in this case, .I P is the value given in .IR pathname . -.PP +.P For the same reasons described in .BR fexecve (3), the natural idiom when using @@ -196,13 +196,13 @@ The .B ENOENT error described above means that it is not possible to set the close-on-exec flag on the file descriptor given to a call of the form: -.PP +.P .in +4n .EX execveat(fd, "", argv, envp, AT_EMPTY_PATH); .EE .in -.PP +.P However, the inability to set the close-on-exec flag means that a file descriptor referring to the script leaks through to the script itself. As well as wasting a file descriptor, diff --git a/man2/exit_group.2 b/man2/exit_group.2 index 3515406..af66e6a 100644 --- a/man2/exit_group.2 +++ b/man2/exit_group.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH exit_group 2 2023-03-30 "Linux man-pages 6.05.01" +.TH exit_group 2 2023-10-31 "Linux man-pages 6.7" .SH NAME exit_group \- exit all threads in a process .SH LIBRARY @@ -12,10 +12,10 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "[[noreturn]] void syscall(SYS_exit_group, int " status ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR exit_group (), diff --git a/man2/fallocate.2 b/man2/fallocate.2 index e462658..bedc533 100644 --- a/man2/fallocate.2 +++ b/man2/fallocate.2 @@ -6,7 +6,7 @@ .\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE .\" 2011-09-19: Substantial restructuring of the page .\" -.TH fallocate 2 2023-03-30 "Linux man-pages 6.05.01" +.TH fallocate 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fallocate \- manipulate file space .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <fcntl.h> -.PP +.P .BI "int fallocate(int " fd ", int " mode ", off_t " offset \ ", off_t " len ");" .fi @@ -25,7 +25,7 @@ This is a nonportable, Linux-specific system call. For the portable, POSIX.1-specified method of ensuring that space is allocated for a file, see .BR posix_fallocate (3). -.PP +.P .BR fallocate () allows the caller to directly manipulate the allocated disk space for the file referred to by @@ -35,7 +35,7 @@ for the byte range starting at and continuing for .I len bytes. -.PP +.P The .I mode argument determines the operation to be performed on the given range. @@ -63,13 +63,13 @@ This default behavior closely resembles the behavior of the .BR posix_fallocate (3) library function, and is intended as a method of optimally implementing that function. -.PP +.P After a successful call, subsequent writes into the range specified by .I offset and .I len are guaranteed not to fail because of lack of disk space. -.PP +.P If the .B FALLOC_FL_KEEP_SIZE flag is specified in @@ -80,7 +80,7 @@ but the file size will not be changed even if is greater than the file size. Preallocating zeroed blocks beyond the end of the file in this manner is useful for optimizing append workloads. -.PP +.P If the .B FALLOC_FL_UNSHARE_RANGE flag is specified in @@ -90,7 +90,7 @@ that a subsequent write will not fail due to lack of space. Typically, this will be done by performing a copy-on-write operation on all shared data in the file. This flag may not be supported by all filesystems. -.PP +.P Because allocation is done in block size chunks, .BR fallocate () may allocate a larger range of disk space than was specified. @@ -109,7 +109,7 @@ Within the specified range, partial filesystem blocks are zeroed, and whole filesystem blocks are removed from the file. After a successful call, subsequent reads from this range will return zeros. -.PP +.P The .B FALLOC_FL_PUNCH_HOLE flag must be ORed with @@ -120,7 +120,7 @@ in other words, even when punching off the end of the file, the file size (as reported by .BR stat (2)) does not change. -.PP +.P Not all filesystems support .BR FALLOC_FL_PUNCH_HOLE ; if a filesystem doesn't support the operation, an error is returned. @@ -160,7 +160,7 @@ will be appended at the location and the file will be .I len bytes smaller. -.PP +.P A filesystem may place limitations on the granularity of the operation, in order to ensure efficient implementation. Typically, @@ -174,7 +174,7 @@ If a filesystem has such a requirement, fails with the error .B EINVAL if this requirement is violated. -.PP +.P If the region specified by .I offset plus @@ -183,12 +183,12 @@ reaches or passes the end of file, an error is returned; instead, use .BR ftruncate (2) to truncate a file. -.PP +.P No other flags may be specified in .I mode in conjunction with .BR FALLOC_FL_COLLAPSE_RANGE . -.PP +.P As at Linux 3.15, .B FALLOC_FL_COLLAPSE_RANGE is supported by @@ -212,13 +212,13 @@ Within the specified range, blocks are preallocated for the regions that span the holes in the file. After a successful call, subsequent reads from this range will return zeros. -.PP +.P Zeroing is done within the filesystem preferably by converting the range into unwritten extents. This approach means that the specified range will not be physically zeroed out on the device (except for partial blocks at the either end of the range), and I/O is (otherwise) required only to update metadata. -.PP +.P If the .B FALLOC_FL_KEEP_SIZE flag is additionally specified in @@ -230,7 +230,7 @@ is greater than the file size. This behavior is the same as when preallocating space with .B FALLOC_FL_KEEP_SIZE specified. -.PP +.P Not all filesystems support .BR FALLOC_FL_ZERO_RANGE ; if a filesystem doesn't support the operation, an error is returned. @@ -270,7 +270,7 @@ bytes. Inserting a hole inside a file increases the file size by .I len bytes. -.PP +.P This mode has the same limitations as .B FALLOC_FL_COLLAPSE_RANGE regarding the granularity of the operation. @@ -284,12 +284,12 @@ is equal to or greater than the end of file, an error is returned. For such operations (i.e., inserting a hole at the end of file), .BR ftruncate (2) should be used. -.PP +.P No other flags may be specified in .I mode in conjunction with .BR FALLOC_FL_INSERT_RANGE . -.PP +.P .B FALLOC_FL_INSERT_RANGE requires filesystem support. Filesystems that support this operation include diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 index f48e43a..8a9667b 100644 --- a/man2/fanotify_init.2 +++ b/man2/fanotify_init.2 @@ -1,7 +1,7 @@ .\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de> .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH fanotify_init 2 2023-07-08 "Linux man-pages 6.05.01" +.TH fanotify_init 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fanotify_init \- create and initialize fanotify group .SH LIBRARY @@ -11,17 +11,17 @@ Standard C library .nf .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" .B #include <sys/fanotify.h> -.PP +.P .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags ); .fi .SH DESCRIPTION For an overview of the fanotify API, see .BR fanotify (7). -.PP +.P .BR fanotify_init () initializes a new fanotify group and returns a file descriptor for the event queue associated with the group. -.PP +.P The file descriptor is used in calls to .BR fanotify_mark (2) to specify the files, directories, mounts, or filesystems for which fanotify @@ -32,25 +32,25 @@ Other events can be used to determine whether another application is permitted to access a file or directory. Permission to access filesystem objects is granted by writing to the file descriptor. -.PP +.P Multiple programs may be using the fanotify interface at the same time to monitor the same files. -.PP +.P The number of fanotify groups per user is limited. See .BR fanotify (7) for details about this limit. -.PP +.P The .I flags argument contains a multi-bit field defining the notification class of the listening application and further single bit fields specifying the behavior of the file descriptor. -.PP +.P If multiple listeners for permission events exist, the notification class is used to establish the sequence in which the listeners receive the events. -.PP +.P Only one of the following notification classes may be specified in .IR flags : .TP @@ -82,7 +82,7 @@ It does not need to be specified. This value only allows the receipt of events notifying that a file has been accessed. Permission decisions before the file is accessed are not possible. -.PP +.P Listeners with different notification classes will receive events in the order .BR FAN_CLASS_PRE_CONTENT , @@ -90,7 +90,7 @@ order .BR FAN_CLASS_NOTIF . The order of notification for listeners in the same notification class is undefined. -.PP +.P The following bits can additionally be set in .IR flags : .TP @@ -364,7 +364,7 @@ so this restriction may eventually be lifted. For more details on information records, see .BR fanotify (7). -.PP +.P The .I event_f_flags argument @@ -386,7 +386,7 @@ This value allows only write access. .TP .B O_RDWR This value allows read and write access. -.PP +.P Additional bits can be set in .IR event_f_flags . The most useful values are: @@ -406,7 +406,7 @@ See the description of the flag in .BR open (2) for reasons why this may be useful. -.PP +.P The following are also allowable: .BR O_APPEND , .BR O_DSYNC , @@ -525,7 +525,7 @@ The .B O_CLOEXEC is ignored when passed in .IR event_f_flags . -.PP +.P The following bug was present before Linux 3.14: .IP \[bu] 3 .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580 diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 index d1f7eec..c942b0b 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -1,7 +1,7 @@ .\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de> .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH fanotify_mark 2 2023-03-30 "Linux man-pages 6.05.01" +.TH fanotify_mark 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem object @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/fanotify.h> -.PP +.P .BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags , .BI " uint64_t " mask ", int " dirfd , .BI " const char *_Nullable " pathname ); @@ -19,17 +19,17 @@ Standard C library .SH DESCRIPTION For an overview of the fanotify API, see .BR fanotify (7). -.PP +.P .BR fanotify_mark () adds, removes, or modifies an fanotify mark on a filesystem object. The caller must have read permission on the filesystem object that is to be marked. -.PP +.P The .I fanotify_fd argument is a file descriptor returned by .BR fanotify_init (2). -.PP +.P .I flags is a bit mask describing the modification to perform. It must include exactly one of the following values: @@ -74,11 +74,11 @@ can be used in conjunction with .BR FAN_MARK_FLUSH . .I mask is ignored. -.PP +.P If none of the values above is specified, or more than one is specified, the call fails with the error .BR EINVAL . -.PP +.P In addition, zero or more of the following values may be ORed into .IR flags : @@ -311,7 +311,7 @@ and if it is not, the listener sets a mark with an ignore mask on the directory. Evictable inode marks allow using this method for a large number of directories without the concern of pinning all inodes and exhausting the system's memory. -.PP +.P .I mask defines which events shall be listened for (or which shall be ignored). It is a bit mask composed of the following values: @@ -486,7 +486,7 @@ and are not generated for children of marked directories. To monitor complete directory trees it is necessary to mark the relevant mount or filesystem. -.PP +.P The following composed values are defined: .TP .B FAN_CLOSE @@ -496,7 +496,7 @@ A file is closed .B FAN_MOVE A file or directory has been moved .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ). -.PP +.P The filesystem object to be marked is determined by the file descriptor .I dirfd and the pathname specified in @@ -743,10 +743,17 @@ do not specify a directory. .B EOPNOTSUPP The object indicated by .I pathname -is associated with a filesystem that does not support the encoding of file -handles. +is associated with a filesystem +that does not support the encoding of file handles. This error can be returned only with an fanotify group that identifies filesystem objects by file handles. +Calling +.BR name_to_handle_at (2) +with the flag +.BR AT_HANDLE_FID " (since Linux 6.5)" +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8 +can be used as a test +to check if a filesystem supports reporting events with file handles. .TP .B EPERM The operation is not permitted because the caller lacks a required capability. @@ -784,28 +791,28 @@ or .BR uselib (2). Events of these types will not be raised in the situation where an interpreter is passed (or reads) a file for interpretation. -.PP +.P Additionally, if a mark has also been placed on the Linux dynamic linker, a user should also expect to receive an event for it when an ELF object has been successfully opened using .BR execve (2) or .BR execveat (2). -.PP +.P For example, if the following ELF binary were to be invoked and a .B FAN_OPEN_EXEC mark has been placed on /: -.PP +.P .in +4n .EX $ /bin/echo foo .EE .in -.PP +.P The listening application in this case would receive .B FAN_OPEN_EXEC events for both the ELF binary and interpreter, respectively: -.PP +.P .in +4n .EX /bin/echo diff --git a/man2/fcntl.2 b/man2/fcntl.2 index 9362044..01d18aa 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -44,7 +44,7 @@ .\" 2017-06-26, Jens Axboe <axboe@kernel.dk> .\" Document F_{GET,SET}_RW_HINT and F_{GET,SET}_FILE_RW_HINT .\" -.TH fcntl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH fcntl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME fcntl \- manipulate file descriptor .SH LIBRARY @@ -53,22 +53,22 @@ Standard C library .SH SYNOPSIS .nf .B #include <fcntl.h> -.PP -.BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );" +.P +.BI "int fcntl(int " fd ", int " op ", ... /* " arg " */ );" .fi .SH DESCRIPTION .BR fcntl () performs one of the operations described below on the open file descriptor .IR fd . The operation is determined by -.IR cmd . -.PP +.IR op . +.P .BR fcntl () can take an optional third argument. Whether or not this argument is required is determined by -.IR cmd . +.IR op . The required argument type is indicated in parentheses after each -.I cmd +.I op name (in most cases, the required type is .IR int , and we identify the argument using the name @@ -76,14 +76,14 @@ and we identify the argument using the name or .I void is specified if the argument is not required. -.PP +.P Certain of the operations below are supported only since a particular Linux kernel version. The preferred method of checking whether the host kernel supports a particular operation is to invoke .BR fcntl () with the desired -.I cmd +.I op value and then test whether the call failed with .BR EINVAL , indicating that the kernel does not recognize this value. @@ -121,7 +121,7 @@ see the description of in .BR open (2). .SS File descriptor flags -The following commands manipulate the flags associated with +The following operations manipulate the flags associated with a file descriptor. Currently, only one such flag is defined: .BR FD_CLOEXEC , @@ -147,7 +147,7 @@ is ignored. .BR F_SETFD " (\fIint\fP)" Set the file descriptor flags to the value specified by .IR arg . -.PP +.P In multithreaded programs, using .BR fcntl () .B F_SETFD @@ -177,7 +177,7 @@ Duplicated file descriptors .BR fork (2), etc.) refer to the same open file description, and thus share the same file status flags. -.PP +.P The file status flags and their semantics are described in .BR open (2). .TP @@ -198,7 +198,7 @@ and file creation flags in .I arg are ignored. -On Linux, this command can change only the +On Linux, this operation can change only the .BR O_APPEND , .BR O_ASYNC , .BR O_DIRECT , @@ -216,7 +216,7 @@ Linux implements traditional ("process-associated") UNIX record locks, as standardized by POSIX. For a Linux-specific alternative with better semantics, see the discussion of open file description locks below. -.PP +.P .BR F_SETLK , .BR F_SETLKW , and @@ -227,7 +227,7 @@ The third argument, .IR lock , is a pointer to a structure that has at least the following fields (in unspecified order). -.PP +.P .in +4n .EX struct flock { @@ -244,13 +244,13 @@ struct flock { }; .EE .in -.PP +.P The .IR l_whence ", " l_start ", and " l_len fields of this structure specify the range of bytes we wish to lock. Bytes past the end of the file may be locked, but not bytes before the start of the file. -.PP +.P .I l_start is the starting offset for the lock, and is interpreted relative to either: @@ -270,7 +270,7 @@ In the final two cases, .I l_start can be a negative number provided the offset does not lie before the start of the file. -.PP +.P .I l_len specifies the number of bytes to be locked. If @@ -285,7 +285,7 @@ has the special meaning: lock all bytes starting at the location specified by .IR l_whence " and " l_start through to the end of file, no matter how large the file grows. -.PP +.P POSIX.1-2001 allows (but does not require) an implementation to support a negative .I l_len @@ -298,7 +298,7 @@ covers bytes up to and including .IR l_start \-1. This is supported since Linux 2.4.21 and Linux 2.5.49. -.PP +.P The .I l_type field can be used to place a read @@ -387,7 +387,7 @@ If the conflicting lock is an open file description lock, then is set to \-1. Note that the returned information may already be out of date by the time the caller inspects it. -.PP +.P In order to place a read lock, .I fd must be open for reading. @@ -395,7 +395,7 @@ In order to place a write lock, .I fd must be open for writing. To place both types of lock, open a file read-write. -.PP +.P When placing locks with .BR F_SETLKW , the kernel detects @@ -418,16 +418,16 @@ attempting regain the locks that it requires. Circular deadlocks involving more than two processes are also detected. Note, however, that there are limitations to the kernel's deadlock-detection algorithm; see BUGS. -.PP +.P As well as being removed by an explicit .BR F_UNLCK , record locks are automatically released when the process terminates. -.PP +.P Record locks are not inherited by a child created via .BR fork (2), but are preserved across an .BR execve (2). -.PP +.P Because of the buffering performed by the .BR stdio (3) library, the use of record locking with routines in that package @@ -436,7 +436,7 @@ should be avoided; use and .BR write (2) instead. -.PP +.P The record locks described above are associated with the process (unlike the open file description locks described below). This has some unfortunate consequences: @@ -461,7 +461,7 @@ The threads in a process share locks. In other words, a multithreaded program can't use record locking to ensure that threads don't simultaneously access the same region of a file. -.PP +.P Open file description locks solve both of these problems. .SS Open file description locks (non-POSIX) Open file description locks are advisory byte-range locks whose operation is @@ -474,7 +474,7 @@ and available since Linux 3.15. to include this lock type in the next revision of POSIX.1.) For an explanation of open file descriptions, see .BR open (2). -.PP +.P The principal difference between the two lock types is that whereas traditional record locks are associated with a process, @@ -492,13 +492,13 @@ with and are only automatically released on the last close of the open file description, instead of being released on any close of the file. -.PP +.P Conflicting lock combinations (i.e., a read lock and a write lock or two write locks) where one lock is an open file description lock and the other is a traditional record lock conflict even when they are acquired by the same process on the same file descriptor. -.PP +.P Open file description locks placed via the same open file description (i.e., via the same file descriptor, or via a duplicate of the file descriptor created by @@ -511,7 +511,7 @@ if a new lock is placed on an already locked region, then the existing lock is converted to the new lock type. (Such conversions may result in splitting, shrinking, or coalescing with an existing lock as discussed above.) -.PP +.P On the other hand, open file description locks may conflict with each other when they are acquired via different open file descriptions. Thus, the threads in a multithreaded program can use @@ -519,7 +519,7 @@ open file description locks to synchronize access to a file region by having each thread perform its own .BR open (2) on the file and applying locks via the resulting file descriptor. -.PP +.P As with traditional advisory locks, the third argument to .BR fcntl (), .IR lock , @@ -529,9 +529,9 @@ structure. By contrast with traditional record locks, the .I l_pid field of that structure must be set to zero -when using the commands described below. -.PP -The commands for working with open file description locks are analogous +when using the operations described below. +.P +The operations for working with open file description locks are analogous to those used with traditional locks: .TP .BR F_OFD_SETLK " (\fIstruct flock *\fP)" @@ -587,7 +587,7 @@ then details about one of these locks are returned via .IR lock , as described above for .BR F_GETLK . -.PP +.P In the current implementation, .\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7 no deadlock detection is performed for open file description locks. @@ -604,12 +604,12 @@ since Linux 4.5, mandatory locking has been made an optional feature, governed by a configuration option .RB ( CONFIG_MANDATORY_FILE_LOCKING ). This feature is no longer supported at all in Linux 5.15 and above. -.PP +.P By default, both traditional (process-associated) and open file description record locks are advisory. Advisory locks are not enforced and are useful only between cooperating processes. -.PP +.P Both lock types can also be mandatory. Mandatory locks are enforced for all processes. If a process tries to perform an incompatible access (e.g., @@ -629,7 +629,7 @@ If the .B O_NONBLOCK flag is enabled, then the system call fails with the error .BR EAGAIN . -.PP +.P To make use of mandatory locks, mandatory locking must be enabled both on the filesystem that contains the file to be locked, and on the file itself. @@ -646,7 +646,7 @@ permission bit (see .BR chmod (1) and .BR chmod (2)). -.PP +.P Mandatory locking is not specified by POSIX. Some other systems also support mandatory locking, although the details of how to enable it vary across systems. @@ -658,7 +658,7 @@ This may happen due to administrative action on the server, or due to a network partition (i.e., loss of network connectivity with the server) which lasts long enough for the server to assume that the client is no longer functioning. -.PP +.P When the filesystem determines that a lock has been lost, future .BR read (2) or @@ -670,7 +670,7 @@ descriptor is closed. Since Linux 3.12, .\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d this happens at least for NFSv4 (including all minor versions). -.PP +.P Some versions of UNIX send a signal .RB ( SIGLOST ) in this circumstance. @@ -722,7 +722,7 @@ one must also enable generation of signals on the file descriptor. This is done by using the .BR fcntl () .B F_SETFL -command to set the +operation to set the .B O_ASYNC file status flag on the file descriptor. Subsequently, a @@ -732,7 +732,7 @@ on the file descriptor. The .BR fcntl () .B F_SETSIG -command can be used to obtain delivery of a signal other than +operation can be used to obtain delivery of a signal other than .BR SIGIO . .IP Sending a signal to the owner process (group) specified by @@ -1002,14 +1002,14 @@ delivering and this signal is delivered to the entire process rather than to a specific thread. .\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05 -.PP +.P Using these mechanisms, a program can implement fully asynchronous I/O without using .BR select (2) or .BR poll (2) most of the time. -.PP +.P The use of .B O_ASYNC is specific to BSD and Linux. @@ -1074,7 +1074,7 @@ other open file descriptors for the file. .B F_UNLCK Remove our lease from the file. .RE -.PP +.P Leases are associated with an open file description (see .BR open (2)). This means that duplicate file descriptors (created by, for example, @@ -1087,7 +1087,7 @@ Furthermore, the lease is released by either an explicit .B F_UNLCK operation on any of these duplicate file descriptors, or when all such file descriptors have been closed. -.PP +.P Leases may be taken out only on regular files. An unprivileged process may take out a lease only on a file whose UID (owner) matches the filesystem UID of the process. @@ -1103,7 +1103,7 @@ by returning either indicating, respectively, a read lease , a write lease, or no lease. .I arg is ignored. -.PP +.P When a process (the "lease breaker") performs an .BR open (2) or @@ -1120,7 +1120,7 @@ accessed by another process (e.g., flushing cached buffers) and then either remove or downgrade its lease. A lease is removed by performing an .B F_SETLEASE -command specifying +operation specifying .I arg as .BR F_UNLCK . @@ -1130,16 +1130,16 @@ then it is sufficient for the lease holder to downgrade the lease to a read lease. This is done by performing an .B F_SETLEASE -command specifying +operation specifying .I arg as .BR F_RDLCK . -.PP +.P If the lease holder fails to downgrade or remove the lease within the number of seconds specified in .IR /proc/sys/fs/lease\-break\-time , then the kernel forcibly removes or downgrades the lease holder's lease. -.PP +.P Once a lease break has been initiated, .B F_GETLEASE returns the target lease type (either @@ -1149,11 +1149,11 @@ or depending on what would be compatible with the lease breaker) until the lease holder voluntarily downgrades or removes the lease or the kernel forcibly does so after the lease break timer expires. -.PP +.P Once the lease has been voluntarily or forcibly removed or downgraded, and assuming the lease breaker has not unblocked its system call, the kernel permits the lease breaker's system call to proceed. -.PP +.P If the lease breaker's blocked .BR open (2) or @@ -1174,16 +1174,16 @@ flag when calling then the call immediately fails with the error .BR EWOULDBLOCK , but the other steps still occur as described above. -.PP +.P The default signal used to notify the lease holder is .BR SIGIO , but this can be changed using the .B F_SETSIG -command to +operation to .BR fcntl (). If a .B F_SETSIG -command is performed (even one specifying +operation is performed (even one specifying .BR SIGIO ), and the signal handler is established using @@ -1206,7 +1206,7 @@ The events to be notified are specified in .IR arg , which is a bit mask specified by ORing together zero or more of the following bits: -.PP +.P .RS .PD 0 .TP @@ -1289,7 +1289,7 @@ The default signal is .BR SIGIO , but this can be changed using the .B F_SETSIG -command to +operation to .BR fcntl (). (Note that .B SIGIO @@ -1377,7 +1377,7 @@ file and filesystem. For an overview of file sealing, a discussion of its purpose, and some code examples, see .BR memfd_create (2). -.PP +.P Currently, file seals can be applied only to a file descriptor returned by .BR memfd_create (2) @@ -1388,7 +1388,7 @@ On other filesystems, all .BR fcntl () operations that operate on seals will return .BR EINVAL . -.PP +.P Seals are a property of an inode. Thus, all open file descriptors referring to the same inode share the same set of seals. @@ -1421,7 +1421,7 @@ If the file does not support sealing, \-1 is returned and .I errno is set to .BR EINVAL . -.PP +.P The following seals are available: .TP .B F_SEAL_SEAL @@ -1534,7 +1534,7 @@ for an explanation of open file descriptions.) In this context, the term "write lifetime" means the expected time the data will live on media, before being overwritten or erased. -.PP +.P An application may use the different hint values specified below to separate writes into different write classes, so that multiple users or applications running on a single storage back-end @@ -1542,7 +1542,7 @@ can aggregate their I/O patterns in a consistent manner. However, there are no functional semantics implied by these flags, and different I/O classes can use the write lifetime hints in arbitrary ways, so long as the hints are used consistently. -.PP +.P The following operations can be applied to the file descriptor, .IR fd : .TP @@ -1567,10 +1567,10 @@ the open file description referred to by Sets the read/write hint value associated with the open file description referred to by .IR fd . -.PP +.P If an open file description has not been assigned a read/write hint, then it shall use the value assigned to the inode, if any. -.PP +.P The following read/write hints are valid since Linux 4.13: .TP @@ -1602,7 +1602,7 @@ Data written to this inode or via this open file description is expected to have a lifetime longer than data written with .BR RWH_WRITE_LIFE_LONG . -.PP +.P All the write-specific hints are relative to each other, and no individual absolute meaning should be attributed to them. .SH RETURN VALUE @@ -1629,7 +1629,9 @@ for traditional .B SIGIO behavior. .TP -.BR F_GETPIPE_SZ ", " F_SETPIPE_SZ +.B F_GETPIPE_SZ +.TQ +.B F_SETPIPE_SZ The pipe capacity. .TP .B F_GET_SEALS @@ -1637,9 +1639,9 @@ A bit mask identifying the seals that have been set for the inode referred to by .IR fd . .TP -All other commands +All other operations Zero. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -1657,7 +1659,7 @@ another process. is not an open file descriptor .TP .B EBADF -.I cmd +.I op is .B F_SETLK or @@ -1666,7 +1668,7 @@ and the file descriptor open mode doesn't match with the type of lock requested. .TP .B EBUSY -.I cmd +.I op is .B F_SETPIPE_SZ and the new pipe capacity specified in @@ -1675,7 +1677,7 @@ is smaller than the amount of buffer space currently used to store data in the pipe. .TP .B EBUSY -.I cmd +.I op is .BR F_ADD_SEALS , .I arg @@ -1687,14 +1689,14 @@ and there exists a writable, shared mapping on the file referred to by .B EDEADLK It was detected that the specified .B F_SETLKW -command would cause a deadlock. +operation would cause a deadlock. .TP .B EFAULT .I lock is outside your accessible address space. .TP .B EINTR -.I cmd +.I op is .B F_SETLKW or @@ -1703,7 +1705,7 @@ and the operation was interrupted by a signal; see .BR signal (7). .TP .B EINTR -.I cmd +.I op is .BR F_GETLK , .BR F_SETLK , @@ -1717,11 +1719,11 @@ NFS), but can sometimes happen locally. .TP .B EINVAL The value specified in -.I cmd +.I op is not recognized by this kernel. .TP .B EINVAL -.I cmd +.I op is .B F_ADD_SEALS and @@ -1729,7 +1731,7 @@ and includes an unrecognized sealing bit. .TP .B EINVAL -.I cmd +.I op is .B F_ADD_SEALS or @@ -1739,7 +1741,7 @@ and the filesystem containing the inode referred to by does not support sealing. .TP .B EINVAL -.I cmd +.I op is .B F_DUPFD and @@ -1751,7 +1753,7 @@ in .BR getrlimit (2)). .TP .B EINVAL -.I cmd +.I op is .B F_SETSIG and @@ -1759,7 +1761,7 @@ and is not an allowable signal number. .TP .B EINVAL -.I cmd +.I op is .BR F_OFD_SETLK , .BR F_OFD_SETLKW , @@ -1770,7 +1772,7 @@ and was not specified as zero. .TP .B EMFILE -.I cmd +.I op is .B F_DUPFD and the per-process limit on the number of open file descriptors @@ -1783,13 +1785,13 @@ protocol failed (e.g., locking over NFS). .B ENOTDIR .B F_NOTIFY was specified in -.IR cmd , +.IR op , but .I fd does not refer to a directory. .TP .B EPERM -.I cmd +.I op is .B F_SETPIPE_SZ and the soft or hard user pipe limit has been reached; see @@ -1801,7 +1803,7 @@ Attempted to clear the flag on a file that has the append-only attribute set. .TP .B EPERM -.I cmd +.I op was .BR F_ADD_SEALS , but @@ -1811,7 +1813,7 @@ or the current set of seals on the file already includes .BR F_SEAL_SEAL . .SH STANDARDS POSIX.1-2008. -.PP +.P .BR F_GETOWN_EX , .BR F_SETOWN_EX , .BR F_SETPIPE_SZ , @@ -1826,9 +1828,9 @@ are Linux-specific. (Define the .B _GNU_SOURCE macro to obtain these definitions.) -.\" .PP +.\" .P .\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. -.PP +.P .BR F_OFD_SETLK , .BR F_OFD_SETLKW , and @@ -1837,7 +1839,7 @@ are Linux-specific (and one must define .B _GNU_SOURCE to obtain their definitions), but work is being done to have them included in the next version of POSIX.1. -.PP +.P .B F_ADD_SEALS and .B F_GET_SEALS @@ -1845,7 +1847,7 @@ are Linux-specific. .\" FIXME . Once glibc adds support, add a note about FTM requirements .SH HISTORY SVr4, 4.3BSD, POSIX.1-2001. -.PP +.P Only the operations .BR F_DUPFD , .BR F_GETFD , @@ -1857,7 +1859,7 @@ Only the operations and .B F_SETLKW are specified in POSIX.1-2001. -.PP +.P .B F_GETOWN and .B F_SETOWN @@ -1869,7 +1871,7 @@ are specified in POSIX.1-2001. with the value 500 or greater, or .B _POSIX_C_SOURCE with the value 200809L or greater.) -.PP +.P .B F_DUPFD_CLOEXEC is specified in POSIX.1-2008. (To get this definition, define @@ -1895,7 +1897,7 @@ Consequently, an system call was added in Linux 2.4. The newer system call employs a different structure for file locking, .IR flock64 , -and corresponding commands, +and corresponding operations, .BR F_GETLK64 , .BR F_SETLK64 , and @@ -1911,7 +1913,7 @@ placed by .BR flock (2) and .BR fcntl (). -.PP +.P Several systems have more fields in .I "struct flock" such as, for example, @@ -1926,7 +1928,7 @@ alone is not going to be very useful if the process holding the lock may live on a different machine; on Linux, while present on some architectures (such as MIPS32), this field is not used. -.PP +.P The original Linux .BR fcntl () system call was not designed to handle large file offsets @@ -1938,7 +1940,7 @@ Consequently, an system call was added in Linux 2.4. The newer system call employs a different structure for file locking, .IR flock64 , -and corresponding commands, +and corresponding operations, .BR F_GETLK64 , .BR F_SETLK64 , and @@ -1975,7 +1977,7 @@ The default value for this file is 90.) This scenario potentially risks data corruption, since another process might acquire a lock in the intervening period and perform file I/O. -.PP +.P Since Linux 3.12, .\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d if an NFSv4 client loses contact with the server, @@ -2096,7 +2098,7 @@ It is therefore inadvisable to rely on mandatory locking. .BR capabilities (7), .BR feature_test_macros (7), .BR lslocks (8) -.PP +.P .IR locks.txt , .IR mandatory\-locking.txt , and diff --git a/man2/flock.2 b/man2/flock.2 index 5f2917f..c2c93ca 100644 --- a/man2/flock.2 +++ b/man2/flock.2 @@ -12,7 +12,7 @@ .\" FIXME Maybe document LOCK_MAND, LOCK_RW, LOCK_READ, LOCK_WRITE .\" which only have effect for SAMBA. .\" -.TH flock 2 2023-03-30 "Linux man-pages 6.05.01" +.TH flock 2 2024-03-03 "Linux man-pages 6.7" .SH NAME flock \- apply or remove an advisory lock on an open file .SH LIBRARY @@ -21,14 +21,14 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/file.h> -.PP -.BI "int flock(int " fd ", int " operation ); +.P +.BI "int flock(int " fd ", int " op ); .fi .SH DESCRIPTION Apply or remove an advisory lock on the open file specified by .IR fd . The argument -.I operation +.I op is one of the following: .RS 4 .TP 9 @@ -45,7 +45,7 @@ file at a given time. .B LOCK_UN Remove an existing lock held by this process. .RE -.PP +.P A call to .BR flock () may block if an incompatible lock is held by another process. @@ -53,9 +53,9 @@ To make a nonblocking request, include .B LOCK_NB (by ORing) with any of the above operations. -.PP +.P A single file may not simultaneously have both shared and exclusive locks. -.PP +.P Locks created by .BR flock () are associated with an open file description (see @@ -70,7 +70,7 @@ Furthermore, the lock is released either by an explicit .B LOCK_UN operation on any of these duplicate file descriptors, or when all such file descriptors have been closed. -.PP +.P If a process uses .BR open (2) (or similar) to obtain more than one file descriptor for the same file, @@ -79,19 +79,19 @@ these file descriptors are treated independently by An attempt to lock the file using one of these file descriptors may be denied by a lock that the calling process has already placed via another file descriptor. -.PP +.P A process may hold only one type of lock (shared or exclusive) on a file. Subsequent .BR flock () calls on an already locked file will convert an existing lock to the new lock mode. -.PP +.P Locks created by .BR flock () are preserved across an .BR execve (2). -.PP +.P A shared or exclusive lock can be placed on a file regardless of the mode in which the file was opened. .SH RETURN VALUE @@ -111,7 +111,7 @@ delivery of a signal caught by a handler; see .BR signal (7). .TP .B EINVAL -.I operation +.I op is invalid. .TP .B ENOLCK @@ -149,7 +149,7 @@ Up to Linux 5.4, .BR flock () is not propagated over SMB. A file with such locks will not appear locked for remote clients. -.PP +.P Since Linux 5.5, .BR flock () locks are emulated with SMB byte-range locks on the entire file. @@ -164,7 +164,7 @@ any IO on a locked file will always fail with when done from a separate file descriptor. This difference originates from the design of locks in the SMB protocol, which provides mandatory locking semantics. -.PP +.P Remote and mandatory locking semantics may vary with SMB protocol, mount options and server type. See @@ -191,7 +191,7 @@ Instead, one could use byte-range locking, which does work over NFS, given a sufficiently recent version of Linux and a server which supports locking. -.PP +.P Since Linux 2.6.12, NFS clients support .BR flock () locks by emulating them as @@ -206,7 +206,7 @@ locks interact with one another over NFS. It also means that in order to place an exclusive lock, the file must be opened for writing. -.PP +.P Since Linux 2.6.37, .\" commit 5eebde23223aeb0ad2d9e3be6590ff8bbfab0fc2 the kernel supports a compatibility mode that allows @@ -224,7 +224,7 @@ places advisory locks only; given suitable permissions on a file, a process is free to ignore the use of .BR flock () and perform I/O on the file. -.PP +.P .BR flock () and .BR fcntl (2) @@ -237,7 +237,7 @@ using the semantics of .BR flock () will be different from those described in this manual page. -.PP +.P Converting a lock (shared to exclusive, or vice versa) is not guaranteed to be atomic: the existing lock is first removed, and then a new lock is established. @@ -260,7 +260,7 @@ and occurs on many other implementations.) .BR open (2), .BR lockf (3), .BR lslocks (8) -.PP +.P .I Documentation/filesystems/locks.txt in the Linux kernel source tree .RI ( Documentation/locks.txt diff --git a/man2/fork.2 b/man2/fork.2 index 607a86b..abfbbed 100644 --- a/man2/fork.2 +++ b/man2/fork.2 @@ -16,7 +16,7 @@ .\" Greatly expanded, to describe all attributes that differ .\" parent and child. .\" -.TH fork 2 2023-05-03 "Linux man-pages 6.05.01" +.TH fork 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fork \- create a child process .SH LIBRARY @@ -25,7 +25,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B pid_t fork(void); .fi .SH DESCRIPTION @@ -37,7 +37,7 @@ process. The calling process is referred to as the .I parent process. -.PP +.P The child process and the parent process run in separate memory spaces. At the time of .BR fork () @@ -47,7 +47,7 @@ Memory writes, file mappings and unmappings .RB ( munmap (2)) performed by one of the processes do not affect the other. -.PP +.P The child process is an exact duplicate of the parent process except for the following points: .IP \[bu] 3 @@ -93,7 +93,7 @@ from its parent .BR aio_write (3)), nor does it inherit any asynchronous I/O contexts from its parent (see .BR io_setup (2)). -.PP +.P The process attributes in the preceding list are all specified in POSIX.1. The parent and child also differ with respect to the following @@ -144,7 +144,7 @@ The port access permission bits set by are not inherited by the child; the child must turn on any bits that it requires using .BR ioperm (2). -.PP +.P Note the following further points: .IP \[bu] 3 The child process is created with a single thread\[em]the @@ -300,7 +300,7 @@ See and .BR wait (2) for more examples. -.PP +.P .\" SRC BEGIN (fork.c) .EX #include <signal.h> diff --git a/man2/fsync.2 b/man2/fsync.2 index 623e7ca..8566ef7 100644 --- a/man2/fsync.2 +++ b/man2/fsync.2 @@ -15,7 +15,7 @@ .\" 2006-04-28, mtk, substantial rewrite of various parts. .\" 2012-02-27 Various changes by Christoph Hellwig <hch@lst.de> .\" -.TH fsync 2 2023-03-30 "Linux man-pages 6.05.01" +.TH fsync 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fsync, fdatasync \- synchronize a file's in-core state with storage device .SH LIBRARY @@ -24,17 +24,17 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int fsync(int " fd ); -.PP +.P .BI "int fdatasync(int " fd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .nf .BR fsync (): glibc 2.16 and later: @@ -43,7 +43,7 @@ Feature Test Macro Requirements for glibc (see _BSD_SOURCE || _XOPEN_SOURCE || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L .fi -.PP +.P .BR fdatasync (): .nf _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500 @@ -59,12 +59,12 @@ changed information can be retrieved even if the system crashes or is rebooted. This includes writing through or flushing a disk cache if present. The call blocks until the device reports that the transfer has completed. -.PP +.P As well as flushing the file data, .BR fsync () also flushes the metadata information associated with the file (see .BR inode (7)). -.PP +.P Calling .BR fsync () does not necessarily ensure @@ -72,7 +72,7 @@ that the entry in the directory containing the file has also reached disk. For that an explicit .BR fsync () on a file descriptor for the directory is also needed. -.PP +.P .BR fdatasync () is similar to .BR fsync (), @@ -93,7 +93,7 @@ On the other hand, a change to the file size as made by say .BR ftruncate (2)), would require a metadata flush. -.PP +.P The aim of .BR fdatasync () is to reduce disk activity for applications that do not @@ -130,12 +130,16 @@ all file descriptors that were open on the file when the error was recorded. .B ENOSPC Disk space was exhausted while synchronizing. .TP -.BR EROFS ", " EINVAL +.B EROFS +.TQ +.B EINVAL .I fd is bound to a special file (e.g., a pipe, FIFO, or socket) which does not support synchronization. .TP -.BR ENOSPC ", " EDQUOT +.B ENOSPC +.TQ +.B EDQUOT .I fd is bound to a file on NFS or another filesystem which does not allocate space at the time of a @@ -155,23 +159,17 @@ to a value greater than 0. .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. .\" -1: unavailable, 0: ask using sysconf(). .\" glibc defines them to 1. -.PP -On some UNIX systems (but not Linux), -.I fd -must be a -.I writable -file descriptor. .SH STANDARDS POSIX.1-2008. .SH HISTORY -POSIX.1-2001, 4.3BSD. -.PP +POSIX.1-2001, 4.2BSD. +.P In Linux 2.2 and earlier, .BR fdatasync () is equivalent to .BR fsync (), and so has no performance advantage. -.PP +.P The .BR fsync () implementations in older kernels and lesser used filesystems @@ -181,6 +179,13 @@ In these cases disk caches need to be disabled using or .BR sdparm (8) to guarantee safe operation. +.P +Under AT&T UNIX System V Release 4 +.I fd +needs to be opened for writing. +This is by itself incompatible with the original BSD interface +and forbidden by POSIX, +but nevertheless survives in HP-UX and AIX. .SH SEE ALSO .BR sync (1), .BR bdflush (2), diff --git a/man2/futex.2 b/man2/futex.2 index 43b1075..2ff300b 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -19,7 +19,7 @@ .\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail .\" http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242 .\" -.TH futex 2 2023-05-03 "Linux man-pages 6.05.01" +.TH futex 2 2023-10-31 "Linux man-pages 6.7" .SH NAME futex \- fast user-space locking .SH LIBRARY @@ -27,18 +27,18 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.PP +.P .BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " futex_op \ ", uint32_t " val , .BI " const struct timespec *" timeout , \ " \fR /* or: \fBuint32_t \fIval2\fP */" .BI " uint32_t *" uaddr2 ", uint32_t " val3 ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR futex (), @@ -61,7 +61,7 @@ Other .BR futex () operations can be used to wake any processes or threads waiting for a particular condition. -.PP +.P A futex is a 32-bit value\[em]referred to below as a .IR "futex word" \[em]whose address is supplied to the @@ -80,7 +80,7 @@ virtual addresses in different processes, but these addresses all refer to the same location in physical memory.) In a multithreaded program, it is sufficient to place the futex word in a global variable shared by all threads. -.PP +.P When executing a futex operation that requests to block a thread, the kernel will block only if the futex word has the value that the calling thread supplied (as one of the arguments of the @@ -113,7 +113,7 @@ blocking via a futex is an atomic compare-and-block operation. .\" the reference in the following sentence .\" See NOTES for a detailed specification of .\" the synchronization semantics. -.PP +.P One use of futexes is for implementing locks. The state of the lock (i.e., acquired or not acquired) can be represented as an atomically accessed flag in shared memory. @@ -140,10 +140,10 @@ operation that wakes threads blocked on the lock flag used as a futex word See .BR futex (7) for more detail on how to use futexes. -.PP +.P Besides the basic wait and wake-up futex functionality, there are further futex operations aimed at supporting more complex use cases. -.PP +.P Note that no explicit initialization or destruction is necessary to use futexes; the kernel maintains a futex @@ -164,7 +164,7 @@ argument; .I val is a value whose meaning and purpose depends on .IR futex_op . -.PP +.P The remaining arguments .RI ( timeout , .IR uaddr2 , @@ -172,7 +172,7 @@ and .IR val3 ) are required only for certain of the futex operations described below. Where one of these arguments is not required, it is ignored. -.PP +.P For several blocking operations, the .I timeout argument is a pointer to a @@ -190,12 +190,12 @@ then to and in the remainder of this page, this argument is referred to as .I val2 when interpreted in this fashion. -.PP +.P Where it is required, the .I uaddr2 argument is a pointer to a second futex word that is employed by the operation. -.PP +.P The interpretation of the final integer argument, .IR val3 , depends on the operation. @@ -264,7 +264,7 @@ If this option is not set, the kernel measures the against the .B CLOCK_MONOTONIC clock. -.PP +.P The operation specified in .I futex_op is one of the following: @@ -835,7 +835,7 @@ while tasks at an intermediate priority continuously preempt the low-priority task from the CPU. Consequently, the low-priority task makes no progress toward releasing the lock, and the high-priority task remains blocked. -.PP +.P Priority inheritance is a mechanism for dealing with the priority-inversion problem. With this mechanism, when a high-priority task becomes blocked @@ -852,7 +852,7 @@ held by another intermediate-priority task then both of those tasks (or more generally, all of the tasks in a lock chain) have their priorities raised to be the same as the high-priority task. -.PP +.P From a user-space perspective, what makes a futex PI-aware is a policy agreement (described below) between user space and the kernel about the value of the futex word, @@ -868,7 +868,7 @@ for the implementation of very specific IPC mechanisms.) .\" talk about a PI aware pthread_mutex, than a PI aware futex, since .\" there is a lot of policy and scaffolding that has to be built up .\" around it to use it properly (this is what a PI pthread_mutex is). -.PP +.P .\" mtk: The following text is drawn from the Hart/Guniguntala paper .\" (listed in SEE ALSO), but I have reworded some pieces .\" significantly. @@ -899,7 +899,7 @@ FUTEX_WAITERS | TID (Note that is invalid for a PI futex word to have no owner and .B FUTEX_WAITERS set.) -.PP +.P With this policy in place, a user-space application can acquire an unacquired lock or release a lock using atomic instructions executed in user mode @@ -910,7 +910,7 @@ Acquiring a lock simply consists of using compare-and-swap to atomically set the futex word's value to the caller's TID if its previous value was 0. Releasing a lock requires using compare-and-swap to set the futex word's value to 0 if the previous value was the expected TID. -.PP +.P If a futex is already acquired (i.e., has a nonzero value), waiters must employ the .B FUTEX_LOCK_PI @@ -923,7 +923,7 @@ bit is set in the futex value; in this case, the lock owner must employ the .B FUTEX_UNLOCK_PI operation to release the lock. -.PP +.P In the cases where callers are forced into the kernel (i.e., required to perform a .BR futex () @@ -933,7 +933,7 @@ a kernel locking mechanism which implements the required priority-inheritance semantics. After the RT-mutex is acquired, the futex value is updated accordingly, before the calling thread returns to user space. -.PP +.P It is important to note .\" tglx (July 2015): .\" If there are multiple waiters on a pi futex then a wake pi operation @@ -950,7 +950,7 @@ up in an invalid state, such as having an owner but the value being 0, or having waiters but not having the .B FUTEX_WAITERS bit set.) -.PP +.P If a futex has an associated RT-mutex in the kernel (i.e., there are blocked waiters) and the owner of the futex/RT-mutex dies unexpectedly, @@ -969,7 +969,7 @@ the dead owner. .\" mechanism. In that case the futex value will be set to .\" FUTEX_OWNER_DIED. The robust futex mechanism is also available for non .\" PI futexes. -.PP +.P PI futexes are operated on by specifying one of the values listed below in .IR futex_op . Note that the PI futex operations must be used as paired operations @@ -1000,7 +1000,7 @@ Additionally, (or the error .B EINVAL results). -.PP +.P The PI futex operations are as follows: .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -1362,7 +1362,7 @@ was invoked via all operations return \-1 and set .I errno to indicate the error. -.PP +.P The return value on success depends on the operation, as described in the following list: .TP @@ -1742,7 +1742,7 @@ and the timeout expired before the operation completed. Linux. .SH HISTORY Linux 2.6.0. -.PP +.P Initial futex support was merged in Linux 2.5.7 but with different semantics from what was described above. A four-argument system call with the semantics @@ -1760,7 +1760,7 @@ The two processes each write messages to the terminal and employ a synchronization protocol that ensures that they alternate in writing messages. Upon running this program we see output such as the following: -.PP +.P .in +4n .EX $ \fB./futex_demo\fP @@ -1931,7 +1931,7 @@ main(int argc, char *argv[]) .BR pthread_mutexattr_getprotocol (3), .BR futex (7), .BR sched (7) -.PP +.P The following kernel source files: .IP \[bu] 3 .I Documentation/pi\-futex.txt @@ -1943,28 +1943,28 @@ The following kernel source files: .I Documentation/locking/rt\-mutex\-design.txt .IP \[bu] .I Documentation/robust\-futex\-ABI.txt -.PP +.P Franke, H., Russell, R., and Kirwood, M., 2002. \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP (from proceedings of the Ottawa Linux Symposium 2002), .br .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002\-pages\-479\-495.pdf .UE -.PP +.P Hart, D., 2009. \fIA futex overview and update\fP, .UR http://lwn.net/Articles/360699/ .UE -.PP +.P Hart, D.\& and Guniguntala, D., 2009. \fIRequeue-PI: Making glibc Condvars PI-Aware\fP (from proceedings of the 2009 Real-Time Linux Workshop), .UR http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf .UE -.PP +.P Drepper, U., 2011. \fIFutexes Are Tricky\fP, .UR http://www.akkadia.org/drepper/futex.pdf .UE -.PP +.P Futex example library, futex\-*.tar.bz2 at .br .UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ diff --git a/man2/futimesat.2 b/man2/futimesat.2 index 4a120cd..b2a18ab 100644 --- a/man2/futimesat.2 +++ b/man2/futimesat.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH futimesat 2 2023-03-30 "Linux man-pages 6.05.01" +.TH futimesat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME futimesat \- change timestamps of a file relative to a \ directory file descriptor @@ -13,16 +13,16 @@ Standard C library .nf .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */" .B #include <sys/time.h> -.PP +.P .BI "[[deprecated]] int futimesat(int " dirfd ", const char *" pathname , .BI " const struct timeval " times [2]); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR futimesat (): .nf _GNU_SOURCE @@ -32,13 +32,13 @@ This system call is obsolete. Use .BR utimensat (2) instead. -.PP +.P The .BR futimesat () system call operates in exactly the same way as .BR utimes (2), except for the differences described in this manual page. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -48,7 +48,7 @@ referred to by the file descriptor the calling process, as is done by .BR utimes (2) for a relative pathname). -.PP +.P If .I pathname is relative and @@ -60,7 +60,7 @@ then is interpreted relative to the current working directory of the calling process (like .BR utimes (2)). -.PP +.P If .I pathname is absolute, then @@ -113,11 +113,11 @@ None. .SH HISTORY Linux 2.6.16, glibc 2.4. -.PP +.P It was implemented from a specification that was proposed for POSIX.1, but that specification was replaced by the one for .BR utimensat (2). -.PP +.P A similar system call exists on Solaris. .SH NOTES .SH SEE ALSO diff --git a/man2/get_kernel_syms.2 b/man2/get_kernel_syms.2 index 307d9ca..a1029b1 100644 --- a/man2/get_kernel_syms.2 +++ b/man2/get_kernel_syms.2 @@ -5,26 +5,26 @@ .\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" -.TH get_kernel_syms 2 2023-03-30 "Linux man-pages 6.05.01" +.TH get_kernel_syms 2 2023-10-31 "Linux man-pages 6.7" .SH NAME get_kernel_syms \- retrieve exported kernel and module symbols .SH SYNOPSIS .nf .B #include <linux/module.h> -.PP +.P .BI "[[deprecated]] int get_kernel_syms(struct kernel_sym *" table ); .fi .SH DESCRIPTION .BR Note : This system call is present only before Linux 2.6. -.PP +.P If .I table is NULL, .BR get_kernel_syms () returns the number of symbols available for query. Otherwise, it fills in a table of structures: -.PP +.P .in +4n .EX struct kernel_sym { @@ -33,13 +33,13 @@ struct kernel_sym { }; .EE .in -.PP +.P The symbols are interspersed with magic symbols of the form .BI # module-name with the kernel having an empty name. The value associated with a symbol of this form is the address at which the module is loaded. -.PP +.P The symbols exported from each module follow their magic module tag and the modules are returned in the reverse of the order in which they were loaded. @@ -60,7 +60,7 @@ Linux. .SH HISTORY Removed in Linux 2.6. .\" Removed in Linux 2.5.48 -.PP +.P This obsolete system call is not supported by glibc. No declaration is provided in glibc headers, but, through a quirk of history, glibc versions before glibc 2.23 did export an ABI for this system call. @@ -73,9 +73,9 @@ There is no way to indicate the size of the buffer allocated for .IR table . If symbols have been added to the kernel since the program queried for the symbol table size, memory will be corrupted. -.PP +.P The length of exported symbol names is limited to 59 characters. -.PP +.P Because of these limitations, this system call is deprecated in favor of .BR query_module (2) diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2 index 45b8f2f..3846bcc 100644 --- a/man2/get_mempolicy.2 +++ b/man2/get_mempolicy.2 @@ -7,7 +7,7 @@ .\" 2007-08-27, Lee Schermerhorn <Lee.Schermerhorn@hp.com> .\" more precise specification of behavior. .\" -.TH get_mempolicy 2 2023-07-16 "Linux man-pages 6.05.01" +.TH get_mempolicy 2 2023-10-31 "Linux man-pages 6.7" .SH NAME get_mempolicy \- retrieve NUMA memory policy for a thread .SH LIBRARY @@ -16,7 +16,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .B "#include <numaif.h>" .nf -.PP +.P .BI "long get_mempolicy(int *" mode , .BI " unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)" .B " / ULONG_WIDTH]," @@ -28,12 +28,12 @@ NUMA (Non-Uniform Memory Access) policy library retrieves the NUMA policy of the calling thread or of a memory address, depending on the setting of .IR flags . -.PP +.P A NUMA machine has different memory controllers with different distances to specific CPUs. The memory policy defines from which node memory is allocated for the thread. -.PP +.P If .I flags is specified as 0, @@ -55,7 +55,7 @@ When is 0, .I addr must be specified as NULL. -.PP +.P If .I flags specifies @@ -77,7 +77,7 @@ with either .B MPOL_F_ADDR or .BR MPOL_F_NODE . -.PP +.P If .I flags specifies @@ -91,7 +91,7 @@ or one of the helper functions described in .BR numa (3) has been used to establish a policy for the memory range containing .IR addr . -.PP +.P If the .I mode argument is not NULL, then @@ -112,7 +112,7 @@ The value specified by .I maxnode is always rounded to a multiple of .IR "sizeof(unsigned\ long)*8" . -.PP +.P If .I flags specifies both @@ -129,7 +129,7 @@ If no page has yet been allocated for the specified address, will allocate a page as if the thread had performed a read (load) access to that address, and return the ID of the node where that page was allocated. -.PP +.P If .I flags specifies @@ -154,9 +154,9 @@ call with the flag for read accesses, and in memory ranges mapped with the .B MAP_SHARED flag for all accesses. -.PP +.P Other flag values are reserved. -.PP +.P For an overview of the possible policies see .BR set_mempolicy (2). .SH RETURN VALUE diff --git a/man2/get_robust_list.2 b/man2/get_robust_list.2 index 7ca4817..bd8682a 100644 --- a/man2/get_robust_list.2 +++ b/man2/get_robust_list.2 @@ -7,7 +7,7 @@ .\" FIXME Something could be added to this page (or exit(2)) .\" about exit_robust_list processing .\" -.TH get_robust_list 2 2022-10-30 "Linux man-pages 6.05.01" +.TH get_robust_list 2 2023-10-31 "Linux man-pages 6.7" .SH NAME get_robust_list, set_robust_list \- get/set list of robust futexes .SH LIBRARY @@ -19,13 +19,13 @@ Standard C library " /* Definition of " "struct robust_list_head" " */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(SYS_get_robust_list, int " pid , .BI " struct robust_list_head **" head_ptr ", size_t *" len_ptr ); .B long syscall(SYS_set_robust_list, .BI " struct robust_list_head *" head ", size_t " len ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -38,7 +38,7 @@ A thread can inform the kernel of the location of its robust futex list using .BR set_robust_list (). The address of a thread's robust futex list can be obtained using .BR get_robust_list (). -.PP +.P The purpose of the robust futex list is to ensure that if a thread accidentally fails to unlock a futex before terminating or calling .BR execve (2), @@ -50,7 +50,7 @@ bit is set in the futex word, and the kernel performs a .BR futex (2) .B FUTEX_WAKE operation on one of the threads waiting on the futex. -.PP +.P The .BR get_robust_list () system call returns the head of the robust futex list of the thread @@ -66,14 +66,14 @@ The size of the object pointed to by .I **head_ptr is stored in .IR len_ptr . -.PP +.P Permission to employ .BR get_robust_list () is governed by a ptrace access mode .B PTRACE_MODE_READ_REALCREDS check; see .BR ptrace (2). -.PP +.P The .BR set_robust_list () system call requests the kernel to record the head of the list of @@ -101,7 +101,7 @@ system call can fail with the following error: .I len does not equal .IR "sizeof(struct\ robust_list_head)" . -.PP +.P The .BR get_robust_list () system call can fail with the following errors: @@ -126,11 +126,11 @@ could be found. These system calls were added in Linux 2.6.17. .SH NOTES These system calls are not needed by normal applications. -.PP +.P A thread can have only one robust futex list; therefore applications that wish to use this functionality should use the robust mutexes provided by glibc. -.PP +.P In the initial implementation, a thread waiting on a futex was notified that the owner had died only if the owner terminated. @@ -138,7 +138,7 @@ Starting with Linux 2.6.28, .\" commit 8141c7f3e7aee618312fa1c15109e1219de784a7 notification was extended to include the case where the owner performs an .BR execve (2). -.PP +.P The thread IDs mentioned in the main text are .I kernel thread IDs of the kind returned by @@ -148,7 +148,7 @@ and .SH SEE ALSO .BR futex (2), .BR pthread_mutexattr_setrobust (3) -.PP +.P .I Documentation/robust\-futexes.txt and .I Documentation/robust\-futex\-ABI.txt diff --git a/man2/getcpu.2 b/man2/getcpu.2 index f90401f..4525470 100644 --- a/man2/getcpu.2 +++ b/man2/getcpu.2 @@ -4,7 +4,7 @@ .\" .\" 2008, mtk, various edits .\" -.TH getcpu 2 2023-07-15 "Linux man-pages 6.05.01" +.TH getcpu 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getcpu \- determine CPU and NUMA node on which the calling thread is running .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sched.h> -.PP +.P .BI "int getcpu(unsigned int *_Nullable " cpu ", \ unsigned int *_Nullable " node ); .fi @@ -35,7 +35,7 @@ When either or .I node is NULL nothing is written to the respective pointer. -.PP +.P The information placed in .I cpu is guaranteed to be current only at the time of the call: @@ -67,21 +67,21 @@ glibc 2.29. .\" .SS C library/kernel differences The kernel system call has a third argument: -.PP +.P .in +4n .nf .BI "int getcpu(unsigned int *" cpu ", unsigned int *" node , .BI " struct getcpu_cache *" tcache ); .fi .in -.PP +.P The .I tcache argument is unused since Linux 2.6.24, and (when invoking the system call directly) should be specified as NULL, unless portability to Linux 2.6.23 or earlier is required. -.PP +.P .\" commit 4307d1e5ada595c87f9a4d16db16ba5edb70dcb1 .\" Author: Ingo Molnar <mingo@elte.hu> .\" Date: Wed Nov 7 18:37:48 2007 +0100 diff --git a/man2/getdents.2 b/man2/getdents.2 index 604a6ef..728d4d7 100644 --- a/man2/getdents.2 +++ b/man2/getdents.2 @@ -8,7 +8,7 @@ .\" Derived from 'readdir.2'. .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> .\" -.TH getdents 2 2023-05-03 "Linux man-pages 6.05.01" +.TH getdents 2 2024-02-25 "Linux man-pages 6.7" .SH NAME getdents, getdents64 \- get directory entries .SH LIBRARY @@ -18,23 +18,23 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(SYS_getdents, unsigned int " fd \ ", struct linux_dirent *" dirp , .BI " unsigned int " count ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <dirent.h> -.PP +.P .BI "ssize_t getdents64(int " fd ", void " dirp [. count "], size_t " count ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR getdents (), necessitating the use of .BR syscall (2). -.PP +.P .IR Note : There is no definition of .I struct linux_dirent @@ -58,16 +58,16 @@ into the buffer pointed to by The argument .I count specifies the size of that buffer. -.PP +.P The .I linux_dirent structure is declared as follows: -.PP +.P .in +4n .EX struct linux_dirent { unsigned long d_ino; /* Inode number */ - unsigned long d_off; /* Offset to next \fIlinux_dirent\fP */ + unsigned long d_off; /* Not an offset; see below */ unsigned short d_reclen; /* Length of this \fIlinux_dirent\fP */ char d_name[]; /* Filename (null\-terminated) */ /* length is actually (d_reclen \- 2 \- @@ -80,18 +80,22 @@ struct linux_dirent { } .EE .in -.PP +.P .I d_ino is an inode number. .I d_off -is the distance from the start of the directory to the start of the next -.IR linux_dirent . +is a filesystem-specific value with no specific meaning to user space, +though on older filesystems it used to be +the distance from the start of the directory to the start of the next +.IR linux_dirent ; +see +.BR readdir (3) . .I d_reclen is the size of this entire .IR linux_dirent . .I d_name is a null-terminated filename. -.PP +.P .I d_type is a byte at the end of the structure that indicates the file type. It contains one of the following values (defined in @@ -120,7 +124,7 @@ This is a UNIX domain socket. .TP .B DT_UNKNOWN The file type is unknown. -.PP +.P The .I d_type field is implemented since Linux 2.6.4. @@ -130,7 +134,7 @@ structure. Thus, on kernels up to and including Linux 2.6.3, attempting to access this field always provides the value 0 .RB ( DT_UNKNOWN ). -.PP +.P Currently, .\" kernel 2.6.27 .\" The same sentence is in readdir.2 @@ -155,19 +159,19 @@ In addition, supports an explicit .I d_type field. -.PP +.P The .BR getdents64 () system call is like .BR getdents (), except that its second argument is a pointer to a buffer containing structures of the following type: -.PP +.P .in +4n .EX struct linux_dirent64 { ino64_t d_ino; /* 64\-bit inode number */ - off64_t d_off; /* 64\-bit offset to next structure */ + off64_t d_off; /* Not an offset; see getdents() */ unsigned short d_reclen; /* Size of this dirent */ unsigned char d_type; /* File type */ char d_name[]; /* Filename (null\-terminated) */ @@ -217,11 +221,11 @@ In that case you will need to define the or .I linux_dirent64 structure yourself. -.PP +.P Probably, you want to use .BR readdir (3) instead of these system calls. -.PP +.P These calls supersede .BR readdir (2). .SH EXAMPLES @@ -231,7 +235,7 @@ The program below demonstrates the use of .BR getdents (). The following output shows an example of what we see when running this program on an ext2 directory: -.PP +.P .in +4n .EX .RB "$" " ./a.out /testfs/" diff --git a/man2/getdomainname.2 b/man2/getdomainname.2 index b65cbfb..9c3b6e5 100644 --- a/man2/getdomainname.2 +++ b/man2/getdomainname.2 @@ -6,7 +6,7 @@ .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> .\" Modified 2008-11-27 by mtk .\" -.TH getdomainname 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getdomainname 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getdomainname, setdomainname \- get/set NIS domain name .SH LIBRARY @@ -15,16 +15,16 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int getdomainname(char *" name ", size_t " len ); .BI "int setdomainname(const char *" name ", size_t " len ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getdomainname (), .BR setdomainname (): .nf @@ -41,7 +41,7 @@ These functions are used to access or to change the NIS domain name of the host system. More precisely, they operate on the NIS domain name associated with the calling process's UTS namespace. -.PP +.P .BR setdomainname () sets the domain name to the value given in the character array .IR name . @@ -52,7 +52,7 @@ argument specifies the number of bytes in (Thus, .I name does not require a terminating null byte.) -.PP +.P .BR getdomainname () returns the null-terminated domain name in the character array .IR name , @@ -84,7 +84,7 @@ The caller did not have the .B CAP_SYS_ADMIN capability in the user namespace associated with its UTS namespace (see .BR namespaces (7)). -.PP +.P .BR getdomainname () can fail with the following errors: .TP diff --git a/man2/getgid.2 b/man2/getgid.2 index a1f64e0..74394a1 100644 --- a/man2/getgid.2 +++ b/man2/getgid.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getgid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getgid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getgid, getegid \- get group identity .SH LIBRARY @@ -11,14 +11,14 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B gid_t getgid(void); .B gid_t getegid(void); .fi .SH DESCRIPTION .BR getgid () returns the real group ID of the calling process. -.PP +.P .BR getegid () returns the effective group ID of the calling process. .SH ERRORS @@ -47,7 +47,7 @@ for details regarding register mapping. POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.3BSD. -.PP +.P The original Linux .BR getgid () and diff --git a/man2/getgroups.2 b/man2/getgroups.2 index eb282b9..d00dc9e 100644 --- a/man2/getgroups.2 +++ b/man2/getgroups.2 @@ -9,7 +9,7 @@ .\" 2008-05-03, mtk, expanded and rewrote parts of DESCRIPTION and RETURN .\" VALUE, made style of page more consistent with man-pages style. .\" -.TH getgroups 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getgroups 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getgroups, setgroups \- get/set list of supplementary group IDs .SH LIBRARY @@ -18,19 +18,19 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int getgroups(int " size ", gid_t " list []); -.PP +.P .B #include <grp.h> -.PP +.P .BI "int setgroups(size_t " size ", const gid_t *_Nullable " list ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR setgroups (): .nf Since glibc 2.19: @@ -50,13 +50,13 @@ buffer pointed to by If the calling process is a member of more than .I size supplementary groups, then an error results. -.PP +.P It is unspecified whether the effective group ID of the calling process is included in the returned list. (Thus, an application should also call .BR getegid (2) and add or remove the resulting value.) -.PP +.P If .I size is zero, @@ -67,7 +67,7 @@ This allows the caller to determine the size of a dynamically allocated .I list to be used in a further call to .BR getgroups (). -.PP +.P .BR setgroups () sets the supplementary group IDs for the calling process. Appropriate privileges are required (see the description of the @@ -79,7 +79,7 @@ argument specifies the number of supplementary group IDs in the buffer pointed to by .IR list . A process can drop all of its supplementary groups with the call: -.PP +.P .in +4n .EX setgroups(0, NULL); @@ -92,7 +92,7 @@ returns the number of supplementary group IDs. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P On success, .BR setgroups () returns 0. @@ -104,14 +104,14 @@ is set to indicate the error. .B EFAULT .I list has an invalid address. -.PP +.P .BR getgroups () can additionally fail with the following error: .TP .B EINVAL .I size is less than the number of supplementary group IDs, but is not zero. -.PP +.P .BR setgroups () can additionally fail with the following errors: .TP @@ -170,7 +170,7 @@ SVr4, 4.3BSD. Since .BR setgroups () requires privilege, it is not covered by POSIX.1. -.PP +.P The original Linux .BR getgroups () system call supported only 16-bit group IDs. @@ -192,17 +192,17 @@ is defined in The set of supplementary group IDs is inherited from the parent process, and preserved across an .BR execve (2). -.PP +.P The maximum number of supplementary group IDs can be found at run time using .BR sysconf (3): -.PP +.P .in +4n .EX long ngroups_max; ngroups_max = sysconf(_SC_NGROUPS_MAX); .EE .in -.PP +.P The maximum return value of .BR getgroups () cannot be larger than one more than this value. diff --git a/man2/gethostname.2 b/man2/gethostname.2 index 26b8df3..0e3ed70 100644 --- a/man2/gethostname.2 +++ b/man2/gethostname.2 @@ -9,7 +9,7 @@ .\" Modified 2004-06-17 by mtk .\" Modified 2008-11-27 by mtk .\" -.TH gethostname 2 2023-03-30 "Linux man-pages 6.05.01" +.TH gethostname 2 2023-10-31 "Linux man-pages 6.7" .SH NAME gethostname, sethostname \- get/set hostname .SH LIBRARY @@ -18,16 +18,16 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int gethostname(char *" name ", size_t " len ); .BI "int sethostname(const char *" name ", size_t " len ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR gethostname (): .nf _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L @@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see .\" The above is something of a simplification .\" also before glibc 2.3 there was a bit churn .fi -.PP +.P .BR sethostname (): .nf Since glibc 2.21: @@ -50,7 +50,7 @@ Feature Test Macro Requirements for glibc (see These system calls are used to access or to change the system hostname. More precisely, they operate on the hostname associated with the calling process's UTS namespace. -.PP +.P .BR sethostname () sets the hostname to the value given in the character array .IR name . @@ -61,7 +61,7 @@ argument specifies the number of bytes in (Thus, .I name does not require a terminating null byte.) -.PP +.P .BR gethostname () returns the null-terminated hostname in the character array .IR name , @@ -155,7 +155,7 @@ POSIX.1-2001 and POSIX.1-2008 specify .BR gethostname () but not .BR sethostname (). -.PP +.P Versions of glibc before glibc 2.2 .\" At least glibc 2.0 and glibc 2.1, older versions not checked handle the case where the length of the diff --git a/man2/getitimer.2 b/man2/getitimer.2 index 422a04e..6674117 100644 --- a/man2/getitimer.2 +++ b/man2/getitimer.2 @@ -10,7 +10,7 @@ .\" 2005-04-06 mtk, Matthias Lang <matthias@corelatus.se> .\" Noted MAX_SEC_IN_JIFFIES ceiling .\" -.TH getitimer 2 2023-05-03 "Linux man-pages 6.05.01" +.TH getitimer 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getitimer, setitimer \- get or set value of an interval timer .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/time.h> -.PP +.P .BI "int getitimer(int " which ", struct itimerval *" curr_value ); .BI "int setitimer(int " which ", const struct itimerval *restrict " new_value , .BI " struct itimerval *_Nullable restrict " old_value ); @@ -31,7 +31,7 @@ and (optionally) at regular intervals after that. When a timer expires, a signal is generated for the calling process, and the timer is reset to the specified interval (if the interval is nonzero). -.PP +.P Three types of timers\[em]specified via the .I which argument\[em]are provided, @@ -63,11 +63,11 @@ In conjunction with .BR ITIMER_VIRTUAL , this timer can be used to profile user and system CPU time consumed by the process. -.PP +.P A process has only one of each of the three types of timers. -.PP +.P Timer values are defined by the following structures: -.PP +.P .in +4n .EX struct itimerval { @@ -89,7 +89,7 @@ places the current value of the timer specified by .I which in the buffer pointed to by .IR curr_value . -.PP +.P The .I it_value substructure is populated with the amount of time remaining until @@ -100,7 +100,7 @@ when the timer expires. If both fields of .I it_value are zero, then this timer is currently disarmed (inactive). -.PP +.P The .I it_interval substructure is populated with the timer interval. @@ -120,7 +120,7 @@ is non-NULL, the buffer it points to is used to return the previous value of the timer (i.e., the same information that is returned by .BR getitimer ()). -.PP +.P If either field in .I new_value.it_value is nonzero, @@ -128,7 +128,7 @@ then the timer is armed to initially expire at the specified time. If both fields in .I new_value.it_value are zero, then the timer is disarmed. -.PP +.P The .I new_value.it_interval field specifies the new interval for the timer; @@ -161,22 +161,22 @@ fields in the structure pointed to by contains a value outside the range [0, 999999]. .SH VERSIONS The standards are silent on the meaning of the call: -.PP +.P .in +4n .EX setitimer(which, NULL, &old_value); .EE .in -.PP +.P Many systems (Solaris, the BSDs, and perhaps others) treat this as equivalent to: -.PP +.P .in +4n .EX getitimer(which, &old_value); .EE .in -.PP +.P In Linux, this is treated as being equivalent to a call in which the .I new_value fields are zero; that is, the timer is disabled. @@ -203,13 +203,13 @@ on the system timer resolution and on the system load; see If the timer expires while the process is active (always true for .BR ITIMER_VIRTUAL ), the signal will be delivered immediately when generated. -.PP +.P A child created via .BR fork (2) does not inherit its parent's interval timers. Interval timers are preserved across an .BR execve (2). -.PP +.P POSIX.1 leaves the interaction between .BR setitimer () @@ -228,7 +228,7 @@ Under very heavy loading, an timer may expire before the signal from a previous expiration has been delivered. The second signal in such an event will be lost. -.PP +.P Before Linux 2.6.16, timer values are represented in jiffies. If a request is made set a timer with a value whose jiffies representation exceeds @@ -243,14 +243,14 @@ approximately 99.42 days. Since Linux 2.6.16, the kernel uses a different internal representation for times, and this ceiling is removed. -.PP +.P On certain systems (including i386), Linux kernels before Linux 2.6.12 have a bug which will produce premature timer expirations of up to one jiffy under some circumstances. This bug is fixed in Linux 2.6.12. .\" 4 Jul 2005: It looks like this bug may remain in Linux 2.4.x. .\" http://lkml.org/lkml/2005/7/1/165 -.PP +.P POSIX.1-2001 says that .BR setitimer () should fail if a diff --git a/man2/getpagesize.2 b/man2/getpagesize.2 index 6f3b54b..25fcbcd 100644 --- a/man2/getpagesize.2 +++ b/man2/getpagesize.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getpagesize 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getpagesize 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getpagesize \- get memory page size .SH LIBRARY @@ -11,15 +11,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B int getpagesize(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getpagesize (): .nf Since glibc 2.20: @@ -52,19 +52,19 @@ Portable applications should employ .I sysconf(_SC_PAGESIZE) instead of .BR getpagesize (): -.PP +.P .in +4n .EX #include <unistd.h> long sz = sysconf(_SC_PAGESIZE); .EE .in -.PP +.P (Most systems allow the synonym .B _SC_PAGE_SIZE for .BR _SC_PAGESIZE .) -.PP +.P Whether .BR getpagesize () is present as a Linux system call depends on the architecture. diff --git a/man2/getpeername.2 b/man2/getpeername.2 index d150617..b738e9e 100644 --- a/man2/getpeername.2 +++ b/man2/getpeername.2 @@ -11,7 +11,7 @@ .\" Modified 17 Jul 2002, Michael Kerrisk <mtk.manpages@gmail.com> .\" Added 'socket' to NAME, so that "man -k socket" will show this page. .\" -.TH getpeername 2 2023-04-03 "Linux man-pages 6.05.01" +.TH getpeername 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getpeername \- get name of connected peer socket .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int getpeername(int " sockfd ", struct sockaddr *restrict " addr , .BI " socklen_t *restrict " addrlen ); .fi @@ -37,7 +37,7 @@ by .IR addr . On return it contains the actual size of the name returned (in bytes). The name is truncated if the buffer provided is too small. -.PP +.P The returned address is truncated if the buffer provided is too small; in this case, .I addrlen diff --git a/man2/getpid.2 b/man2/getpid.2 index 3b78823..5166035 100644 --- a/man2/getpid.2 +++ b/man2/getpid.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getpid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getpid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getpid, getppid \- get process identification .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B pid_t getpid(void); .B pid_t getppid(void); .fi @@ -20,7 +20,7 @@ Standard C library returns the process ID (PID) of the calling process. (This is often used by routines that generate unique temporary filenames.) -.PP +.P .BR getppid () returns the process ID of the parent of the calling process. This will be either the ID of the process that created this process using @@ -109,7 +109,7 @@ via the glibc wrapper function. .BR clone (2).) Furthermore, the complexity of the caching code had been the source of a few bugs within glibc over the years. -.PP +.P Because of the aforementioned problems, since glibc 2.25, the PID cache is removed: .\" commit c579f48edba88380635ab98cb612030e3ed8691e @@ -124,7 +124,7 @@ If the caller's parent is in a different PID namespace (see .BR pid_namespaces (7)), .BR getppid () returns 0. -.PP +.P From a kernel perspective, the PID (which is shared by all of the threads in a multithreaded process) is sometimes also known as the thread group ID (TGID). diff --git a/man2/getpriority.2 b/man2/getpriority.2 index 723d3d4..e4aa4f0 100644 --- a/man2/getpriority.2 +++ b/man2/getpriority.2 @@ -14,7 +14,7 @@ .\" Clarified meaning of 0 value for 'who' argument .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH getpriority 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getpriority 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getpriority, setpriority \- get/set program scheduling priority .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/resource.h> -.PP +.P .BI "int getpriority(int " which ", id_t " who ); .BI "int setpriority(int " which ", id_t " who ", int " prio ); .fi @@ -41,7 +41,7 @@ call. The process attribute dealt with by these system calls is the same attribute (also known as the "nice" value) that is dealt with by .BR nice (2). -.PP +.P The value .I which is one of @@ -64,7 +64,7 @@ A zero value for .I who denotes (respectively) the calling process, the process group of the calling process, or the real user ID of the calling process. -.PP +.P The .I prio argument is a value in the range \-20 to 19 (but see NOTES below), @@ -73,7 +73,7 @@ Attempts to set a priority outside this range are silently clamped to the range. The default priority is 0; lower values give a process a higher scheduling priority. -.PP +.P The .BR getpriority () call returns the highest priority (lowest numerical value) @@ -82,7 +82,7 @@ The .BR setpriority () call sets the priorities of all of the specified processes to the specified value. -.PP +.P Traditionally, only a privileged process could lower the nice value (i.e., set a higher priority). However, since Linux 2.6.12, an unprivileged process can decrease @@ -98,7 +98,7 @@ returns the calling thread's nice value, which may be a negative number. On error, it returns \-1 and sets .I errno to indicate the error. -.PP +.P Since a successful call to .BR getpriority () can legitimately return the value \-1, it is necessary @@ -109,7 +109,7 @@ call, then check .I errno afterward to determine if \-1 is an error or a legitimate value. -.PP +.P .BR setpriority () returns 0 on success. On failure, it returns \-1 and sets @@ -154,19 +154,19 @@ SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). .SH NOTES For further details on the nice value, see .BR sched (7). -.PP +.P .IR Note : the addition of the "autogroup" feature in Linux 2.6.38 means that the nice value no longer has its traditional effect in many circumstances. For details, see .BR sched (7). -.PP +.P A child created by .BR fork (2) inherits its parent's nice value. The nice value is preserved across .BR execve (2). -.PP +.P The details on the condition for .B EPERM depend on the system. @@ -204,6 +204,6 @@ which may be made standards conformant in the future. .BR fork (2), .BR capabilities (7), .BR sched (7) -.PP +.P .I Documentation/scheduler/sched\-nice\-design.txt in the Linux kernel source tree (since Linux 2.6.23) diff --git a/man2/getrandom.2 b/man2/getrandom.2 index 565763b..e4c63a8 100644 --- a/man2/getrandom.2 +++ b/man2/getrandom.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getrandom 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getrandom 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getrandom \- obtain a series of random bytes .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/random.h> -.PP +.P .BI "ssize_t getrandom(void " buf [. buflen "], size_t " buflen ", \ unsigned int " flags ); .fi @@ -27,7 +27,7 @@ with up to random bytes. These bytes can be used to seed user-space random number generators or for cryptographic purposes. -.PP +.P By default, .BR getrandom () draws entropy from the @@ -38,7 +38,7 @@ device). This behavior can be changed via the .I flags argument. -.PP +.P If the .I urandom source has been initialized, @@ -48,7 +48,7 @@ No such guarantees apply for larger buffer sizes. For example, if the call is interrupted by a signal handler, it may return a partially filled buffer, or fail with the error .BR EINTR . -.PP +.P If the .I urandom source has not yet been initialized, then @@ -57,7 +57,7 @@ will block, unless .B GRND_NONBLOCK is specified in .IR flags . -.PP +.P The .I flags argument is a bit mask that can contain zero or more of the following values @@ -119,7 +119,7 @@ was specified in and insufficient entropy was present in the .I random source or the system call was interrupted by a signal. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -164,7 +164,7 @@ glibc 2.25. For an overview and comparison of the various interfaces that can be used to obtain randomness, see .BR random (7). -.PP +.P Unlike .I /dev/random and @@ -222,7 +222,7 @@ will block until some random bytes become available (unless the .B GRND_NONBLOCK flag was specified). -.PP +.P The behavior when a call to .BR getrandom () that is blocked while reading from the @@ -247,26 +247,26 @@ then will not fail with .BR EINTR . Instead, it will return all of the bytes that have been requested. -.PP +.P When reading from the .I random source, blocking requests of any size can be interrupted by a signal handler (the call fails with the error .BR EINTR ). -.PP +.P Using .BR getrandom () to read small buffers (<=\ 256 bytes) from the .I urandom source is the preferred mode of usage. -.PP +.P The special treatment of small values of .I buflen was designed for compatibility with OpenBSD's .BR getentropy (3), which is nowadays supported by glibc. -.PP +.P The user of .BR getrandom () .I must diff --git a/man2/getresuid.2 b/man2/getresuid.2 index d5cadd7..9b4a1ff 100644 --- a/man2/getresuid.2 +++ b/man2/getresuid.2 @@ -5,7 +5,7 @@ .\" .\" Modified, 2003-05-26, Michael Kerrisk, <mtk.manpages@gmail.com> .\" -.TH getresuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getresuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getresuid, getresgid \- get real, effective, and saved user/group IDs .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <unistd.h> -.PP +.P .BI "int getresuid(uid_t *" ruid ", uid_t *" euid ", uid_t *" suid ); .BI "int getresgid(gid_t *" rgid ", gid_t *" egid ", gid_t *" sgid ); .fi @@ -46,7 +46,7 @@ These calls also appear on HP-UX and some of the BSDs. .SH HISTORY Linux 2.1.44, glibc 2.3.2. -.PP +.P The original Linux .BR getresuid () and diff --git a/man2/getrlimit.2 b/man2/getrlimit.2 index afc2c22..ece8e97 100644 --- a/man2/getrlimit.2 +++ b/man2/getrlimit.2 @@ -42,7 +42,7 @@ .\" 2008-05-07, mtk / Peter Zijlstra, Added description of RLIMIT_RTTIME .\" 2010-11-06, mtk: Added documentation of prlimit() .\" -.TH getrlimit 2 2023-07-20 "Linux man-pages 6.05.01" +.TH getrlimit 2 2024-02-25 "Linux man-pages 6.7" .SH NAME getrlimit, setrlimit, prlimit \- get/set resource limits .SH LIBRARY @@ -51,20 +51,20 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/resource.h> -.PP +.P .BI "int getrlimit(int " resource ", struct rlimit *" rlim ); .BI "int setrlimit(int " resource ", const struct rlimit *" rlim ); -.PP +.P .BI "int prlimit(pid_t " pid ", int " resource , .BI " const struct rlimit *_Nullable " new_limit , .BI " struct rlimit *_Nullable " old_limit ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR prlimit (): .nf _GNU_SOURCE @@ -78,7 +78,7 @@ system calls get and set resource limits. Each resource has an associated soft and hard limit, as defined by the .I rlimit structure: -.PP +.P .in +4n .EX struct rlimit { @@ -87,7 +87,7 @@ struct rlimit { }; .EE .in -.PP +.P The soft limit is the value that the kernel enforces for the corresponding resource. The hard limit acts as a ceiling for the soft limit: @@ -97,14 +97,14 @@ A privileged process (under Linux: one with the .B CAP_SYS_RESOURCE capability in the initial user namespace) may make arbitrary changes to either limit value. -.PP +.P The value .B RLIM_INFINITY denotes no limit on a resource (both in the structure returned by .BR getrlimit () and in the structure passed to .BR setrlimit ()). -.PP +.P The .I resource argument must be one of: @@ -450,14 +450,14 @@ system call combines and extends the functionality of and .BR getrlimit (). It can be used to both set and get the resource limits of an arbitrary process. -.PP +.P The .I resource argument has the same meaning as for .BR setrlimit () and .BR getrlimit (). -.PP +.P If the .I new_limit argument is not NULL, then the @@ -475,7 +475,7 @@ in the .I rlimit structure pointed to by .IR old_limit . -.PP +.P The .I pid argument specifies the ID of the process on which the call is to operate. @@ -556,7 +556,6 @@ T{ .BR prlimit () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR getrlimit () @@ -566,7 +565,7 @@ POSIX.1-2008. .TP .BR prlimit () Linux. -.PP +.P .B RLIMIT_MEMLOCK and .B RLIMIT_NPROC @@ -598,15 +597,15 @@ A child process created via inherits its parent's resource limits. Resource limits are preserved across .BR execve (2). -.PP +.P Resource limits are per-process attributes that are shared by all of the threads in a process. -.PP +.P Lowering the soft limit for a resource below the process's current consumption of that resource will succeed (but will prevent the process from further increasing its consumption of the resource). -.PP +.P One can set the resource limits of the shell using the built-in .I ulimit command @@ -615,12 +614,12 @@ in .BR csh (1)). The shell's resource limits are inherited by the processes that it creates to execute commands. -.PP +.P Since Linux 2.6.24, the resource limits of any process can be inspected via .IR /proc/ pid /limits ; see .BR proc (5). -.PP +.P Ancient systems provided a .BR vlimit () function with a similar purpose to @@ -638,7 +637,7 @@ wrapper functions no longer invoke the corresponding system calls, but instead employ .BR prlimit (), for the reasons described in BUGS. -.PP +.P The name of the glibc wrapper function is .BR prlimit (); the underlying system call is @@ -652,7 +651,7 @@ signals delivered when a process encountered the soft and hard .B RLIMIT_CPU limits were delivered one (CPU) second later than they should have been. This was fixed in Linux 2.6.8. -.PP +.P In Linux 2.6.x kernels before Linux 2.6.17, a .B RLIMIT_CPU limit of 0 is wrongly treated as "no limit" (like @@ -660,12 +659,12 @@ limit of 0 is wrongly treated as "no limit" (like Since Linux 2.6.17, setting a limit of 0 does have an effect, but is actually treated as a limit of 1 second. .\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=114008066530167&w=2 -.PP +.P A kernel bug means that .\" See https://lwn.net/Articles/145008/ .B RLIMIT_RTPRIO does not work in Linux 2.6.12; the problem is fixed in Linux 2.6.13. -.PP +.P In Linux 2.6.12, there was an off-by-one mismatch between the priority ranges returned by .BR getpriority (2) @@ -676,7 +675,7 @@ was calculated as .IR "19\ \-\ rlim_cur" . This was fixed in Linux 2.6.13. .\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=112256338703880&w=2 -.PP +.P Since Linux 2.6.12, .\" The relevant patch, sent to LKML, seems to be .\" http://thread.gmane.org/gmane.linux.kernel/273462 @@ -703,7 +702,7 @@ portable applications should avoid relying on this Linux-specific behavior. The Linux-specific .B RLIMIT_RTTIME limit exhibits the same behavior when the soft limit is encountered. -.PP +.P Kernels before Linux 2.4.22 did not diagnose the error .B EINVAL for @@ -713,12 +712,12 @@ when was greater than .IR rlim\->rlim_max . .\" d3561f78fd379a7110e46c87964ba7aa4120235c -.PP +.P Linux doesn't return an error when an attempt to set .B RLIMIT_CPU has failed, for compatibility reasons. .\" -.SS Representation of """large""" resource limit values on 32-bit platforms +.SS Representation of \[dq]large\[dq] resource limit values on 32-bit platforms The glibc .BR getrlimit () and @@ -753,7 +752,7 @@ represent file offsets\[em]that is, as wide as a 64-bit .B off_t (assuming a program compiled with .IR _FILE_OFFSET_BITS=64 ). -.PP +.P To work around this kernel limitation, if a program tried to set a resource limit to a value larger than can be represented in a 32-bit @@ -763,7 +762,7 @@ then the glibc wrapper function silently converted the limit value to .BR RLIM_INFINITY . In other words, the requested resource limit setting was silently ignored. -.PP +.P Since glibc 2.13, .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201 glibc works around the limitations of the @@ -779,7 +778,7 @@ as wrapper functions that call .SH EXAMPLES The program below demonstrates the use of .BR prlimit (). -.PP +.P .\" SRC BEGIN (getrlimit.c) .EX #define _GNU_SOURCE diff --git a/man2/getrusage.2 b/man2/getrusage.2 index 8966295..97c144f 100644 --- a/man2/getrusage.2 +++ b/man2/getrusage.2 @@ -17,7 +17,7 @@ .\" document ru_maxrss .\" 2010-05-24, mtk, enhanced description of various fields .\" -.TH getrusage 2 2023-07-20 "Linux man-pages 6.05.01" +.TH getrusage 2 2024-03-14 "Linux man-pages 6.7" .SH NAME getrusage \- get resource usage .SH LIBRARY @@ -26,7 +26,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/resource.h> -.PP +.P .BI "int getrusage(int " who ", struct rusage *" usage ); .fi .SH DESCRIPTION @@ -55,11 +55,11 @@ feature test macro must be defined (before including header file) in order to obtain the definition of this constant from .IR <sys/resource.h> . -.PP +.P The resource usages are returned in the structure pointed to by .IR usage , which has the following form: -.PP +.P .in +4n .EX struct rusage { @@ -82,7 +82,7 @@ struct rusage { }; .EE .in -.PP +.P Not all fields are completed; unmaintained fields are set to zero by the kernel. (The unmaintained fields are provided for compatibility with other systems, @@ -195,22 +195,21 @@ T{ .BR getrusage () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. -.PP +.P POSIX.1 specifies .BR getrusage (), but specifies only the fields .I ru_utime and .IR ru_stime . -.PP +.P .B RUSAGE_THREAD is Linux-specific. .SH HISTORY POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P Before Linux 2.6.9, if the disposition of .B SIGCHLD is set to @@ -222,10 +221,10 @@ although POSIX.1-2001 explicitly prohibits this. This nonconformance is rectified in Linux 2.6.9 and later. .\" See the description of getrusage() in XSH. .\" A similar statement was also in SUSv2. -.PP +.P The structure definition shown at the start of this page was taken from 4.3BSD Reno. -.PP +.P Ancient systems provided a .BR vtimes () function with a similar purpose to @@ -240,15 +239,12 @@ implementation.) .SH NOTES Resource usage metrics are preserved across an .BR execve (2). -.PP -See also the description of -.IR /proc/ pid /stat -in -.BR proc (5). .SH SEE ALSO .BR clock_gettime (2), .BR getrlimit (2), .BR times (2), .BR wait (2), .BR wait4 (2), -.BR clock (3) +.BR clock (3), +.BR proc_pid_stat (5), +.BR proc_pid_io (5) diff --git a/man2/getsid.2 b/man2/getsid.2 index 842c980..25f0b2d 100644 --- a/man2/getsid.2 +++ b/man2/getsid.2 @@ -5,7 +5,7 @@ .\" .\" Modified Thu Oct 31 14:18:40 1996 by Eric S. Raymond <esr@y\thyrsus.com> .\" Modified 2001-12-17, aeb -.TH getsid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getsid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getsid \- get session ID .SH LIBRARY @@ -14,15 +14,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "pid_t getsid(pid_t" " pid" ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getsid (): .nf _XOPEN_SOURCE >= 500 diff --git a/man2/getsockname.2 b/man2/getsockname.2 index e2cc11e..6d4a9f6 100644 --- a/man2/getsockname.2 +++ b/man2/getsockname.2 @@ -9,7 +9,7 @@ .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> .\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer <aeb@cwi.nl> .\" -.TH getsockname 2 2023-04-03 "Linux man-pages 6.05.01" +.TH getsockname 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getsockname \- get socket name .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int getsockname(int " sockfd ", struct sockaddr *restrict " addr , .BI " socklen_t *restrict " addrlen ); .fi @@ -34,7 +34,7 @@ argument should be initialized to indicate the amount of space (in bytes) pointed to by .IR addr . On return it contains the actual size of the socket address. -.PP +.P The returned address is truncated if the buffer provided is too small; in this case, .I addrlen diff --git a/man2/getsockopt.2 b/man2/getsockopt.2 index f80900a..baf3395 100644 --- a/man2/getsockopt.2 +++ b/man2/getsockopt.2 @@ -13,7 +13,7 @@ .\" Modified 1999 by Andi Kleen <ak@muc.de>. .\" Removed most stuff because it is in socket.7 now. .\" -.TH getsockopt 2 2023-04-03 "Linux man-pages 6.05.01" +.TH getsockopt 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getsockopt, setsockopt \- get and set options on sockets .SH LIBRARY @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int getsockopt(int " sockfd ", int " level ", int " optname , .BI " void " optval "[restrict *." optlen ], .BI " socklen_t *restrict " optlen ); @@ -39,7 +39,7 @@ manipulate options for the socket referred to by the file descriptor Options may exist at multiple protocol levels; they are always present at the uppermost socket level. -.PP +.P When manipulating socket options, the level at which the option resides and the name of the option must be specified. To manipulate options at the sockets API level, @@ -58,7 +58,7 @@ should be set to the protocol number of .BR TCP ; see .BR getprotoent (3). -.PP +.P The arguments .I optval and @@ -80,7 +80,7 @@ the value returned. If no option value is to be supplied or returned, .I optval may be NULL. -.PP +.P .I Optname and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. @@ -90,7 +90,7 @@ contains definitions for socket level options, described below. Options at other protocol levels vary in format and name; consult the appropriate entries in section 4 of the manual. -.PP +.P Most socket-level options utilize an .I int argument for @@ -99,7 +99,7 @@ For .BR setsockopt (), the argument should be nonzero to enable a boolean option, or zero if the option is to be disabled. -.PP +.P For a description of the available socket options see .BR socket (7) and the appropriate protocol man pages. @@ -108,7 +108,7 @@ On success, zero is returned for the standard options. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P Netfilter allows the programmer to define custom socket options with associated handlers; for such options, the return value on success is the value returned by the handler. diff --git a/man2/gettid.2 b/man2/gettid.2 index d4ca4d0..297a902 100644 --- a/man2/gettid.2 +++ b/man2/gettid.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH gettid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH gettid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME gettid \- get thread identification .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .B #define _GNU_SOURCE .B #include <unistd.h> -.PP +.P .B pid_t gettid(void); .fi .SH DESCRIPTION @@ -41,7 +41,7 @@ glibc 2.30. The thread ID returned by this call is not the same thing as a POSIX thread ID (i.e., the opaque value returned by .BR pthread_self (3)). -.PP +.P In a new thread group created by a .BR clone (2) call that does not specify the diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2 index 8381cc0..cd8bc84 100644 --- a/man2/gettimeofday.2 +++ b/man2/gettimeofday.2 @@ -17,7 +17,7 @@ .\" Modified, 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> .\" Added notes on capability requirement. .\" -.TH gettimeofday 2 2023-07-28 "Linux man-pages 6.05.01" +.TH gettimeofday 2 2023-10-31 "Linux man-pages 6.7" .SH NAME gettimeofday, settimeofday \- get / set time .SH LIBRARY @@ -26,18 +26,18 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/time.h> -.PP +.P .BI "int gettimeofday(struct timeval *restrict " tv , .BI " struct timezone *_Nullable restrict " tz ); .BI "int settimeofday(const struct timeval *" tv , .BI " const struct timezone *_Nullable " tz ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR settimeofday (): .nf Since glibc 2.19: @@ -51,14 +51,14 @@ The functions and .BR settimeofday () can get and set the time as well as a timezone. -.PP +.P The .I tv argument is a .I struct timeval (as specified in .IR <sys/time.h> ): -.PP +.P .in +4n .EX struct timeval { @@ -67,15 +67,15 @@ struct timeval { }; .EE .in -.PP +.P and gives the number of seconds and microseconds since the Epoch (see .BR time (2)). -.PP +.P The .I tz argument is a .IR "struct timezone" : -.PP +.P .in +4n .EX struct timezone { @@ -84,7 +84,7 @@ struct timezone { }; .EE .in -.PP +.P If either .I tv or @@ -96,17 +96,17 @@ is NULL, the corresponding structure is not set or returned. .I tv is NULL.) .\" The following is covered under EPERM below: -.\" .PP +.\" .P .\" Only the superuser may use .\" .BR settimeofday (). -.PP +.P The use of the .I timezone structure is obsolete; the .I tz argument should normally be specified as NULL. (See NOTES below.) -.PP +.P Under Linux, there are some peculiar "warp clock" semantics associated with the .BR settimeofday () @@ -175,11 +175,11 @@ On some architectures, an implementation of .BR gettimeofday () is provided in the .BR vdso (7). -.PP +.P The kernel accepts NULL for both .I tv and -.IR tz. +.IR tz . The timezone argument is ignored by glibc and musl, and not passed to/from the kernel. Android's bionic passes the timezone argument to/from the kernel, @@ -204,7 +204,7 @@ POSIX.1-2008 marks as obsolete, recommending the use of .BR clock_gettime (2) instead. -.PP +.P Traditionally, the fields of .I struct timeval were of type @@ -235,7 +235,7 @@ or .\" Each and every occurrence of this field in the kernel source .\" (other than the declaration) is a bug. Thus, the following is purely of historical interest. -.PP +.P On old systems, the field .I tz_dsttime contains a symbolic constant (values are given below) @@ -245,7 +245,7 @@ is in force. it does not indicate that DST is in force, it just selects an algorithm.) The daylight saving time algorithms defined are as follows: -.PP +.P .in +4n .EX \fBDST_NONE\fP /* not on DST */ @@ -261,7 +261,7 @@ The daylight saving time algorithms defined are as follows: \fBDST_AUSTALT\fP /* Australian style with shift in 1986 */ .EE .in -.PP +.P Of course it turned out that the period in which Daylight Saving Time is in force cannot be given by a simple algorithm, one per country; indeed, @@ -277,7 +277,7 @@ affected by discontinuous jumps in the system time (e.g., if the system administrator manually changes the system time). If you need a monotonically increasing clock, see .BR clock_gettime (2). -.PP +.P Macros for operating on .I timeval structures are described in diff --git a/man2/getuid.2 b/man2/getuid.2 index 1b94158..978b8ec 100644 --- a/man2/getuid.2 +++ b/man2/getuid.2 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Historical remark, aeb, 2004-06-05 -.TH getuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getuid, geteuid \- get user identity .SH LIBRARY @@ -12,14 +12,14 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B uid_t getuid(void); .B uid_t geteuid(void); .fi .SH DESCRIPTION .BR getuid () returns the real user ID of the calling process. -.PP +.P .BR geteuid () returns the effective user ID of the calling process. .SH ERRORS @@ -32,7 +32,7 @@ and never modify POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.3BSD. -.PP +.P In UNIX\ V6 the .BR getuid () call returned @@ -41,7 +41,7 @@ UNIX\ V7 introduced separate calls .BR getuid () and .BR geteuid (). -.PP +.P The original Linux .BR getuid () and @@ -57,7 +57,7 @@ The glibc and .BR geteuid () wrapper functions transparently deal with the variations across kernel versions. -.PP +.P On Alpha, instead of a pair of .BR getuid () and diff --git a/man2/getunwind.2 b/man2/getunwind.2 index eaf7117..1a904b7 100644 --- a/man2/getunwind.2 +++ b/man2/getunwind.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getunwind 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getunwind 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getunwind \- copy the unwind data to caller's buffer .SH LIBRARY @@ -15,13 +15,13 @@ Standard C library .B #include <linux/unwind.h> .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "[[deprecated]] long syscall(SYS_getunwind, void " buf [. buf_size ], .BI " size_t " buf_size ); .fi .SH DESCRIPTION .I Note: this system call is obsolete. -.PP +.P The IA-64-specific .BR getunwind () @@ -31,7 +31,7 @@ unwind data into the buffer pointed to by and returns the size of the unwind data; this data describes the gate page (kernel code that is mapped into user space). -.PP +.P The size of the buffer .I buf is specified in @@ -43,11 +43,11 @@ is greater than or equal to the size of the unwind data and is not NULL; otherwise, no data is copied, and the call succeeds, returning the size that would be needed to store the unwind data. -.PP +.P The first part of the unwind data contains an unwind table. The rest contains the associated unwind information, in no particular order. The unwind table contains entries of the following form: -.PP +.P .in +4n .EX u64 start; (64\-bit address of start of function) @@ -55,7 +55,7 @@ u64 end; (64\-bit address of end of function) u64 info; (BUF\-relative offset to unwind info) .EE .in -.PP +.P An entry whose .I start value is zero indicates the end of the table. @@ -79,7 +79,7 @@ if the unwind info can't be stored in the space specified by Linux on IA-64. .SH HISTORY Linux 2.4. -.PP +.P This system call has been deprecated. The modern way to obtain the kernel's unwind data is via the .BR vdso (7). diff --git a/man2/getxattr.2 b/man2/getxattr.2 index 21df6ca..6d7a0ee 100644 --- a/man2/getxattr.2 +++ b/man2/getxattr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH getxattr 2 2023-07-28 "Linux man-pages 6.05.01" +.TH getxattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getxattr, lgetxattr, fgetxattr \- retrieve an extended attribute value .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/xattr.h> -.PP +.P .BI "ssize_t getxattr(const char *" path ", const char *" name , .BI " void " value [. size "], size_t " size ); .BI "ssize_t lgetxattr(const char *" path ", const char *" name , @@ -30,7 +30,7 @@ with all inodes in the system (i.e., the data). A complete overview of extended attributes concepts can be found in .BR xattr (7). -.PP +.P .BR getxattr () retrieves the value of the extended attribute identified by .I name @@ -43,13 +43,13 @@ The attribute value is placed in the buffer pointed to by specifies the size of that buffer. The return value of the call is the number of bytes placed in .IR value . -.PP +.P .BR lgetxattr () is identical to .BR getxattr (), except in the case of a symbolic link, where the link itself is interrogated, not the file that it refers to. -.PP +.P .BR fgetxattr () is identical to .BR getxattr (), @@ -59,7 +59,7 @@ only the open file referred to by .BR open (2)) is interrogated in place of .IR path . -.PP +.P An extended attribute .I name is a null-terminated string. @@ -68,7 +68,7 @@ namespaces associated with an individual inode. The value of an extended attribute is a chunk of arbitrary textual or binary data that was assigned using .BR setxattr (2). -.PP +.P If .I size is specified as zero, these calls return the current size of the @@ -113,7 +113,7 @@ The of the .I value buffer is too small to hold the result. -.PP +.P In addition, the errors documented in .BR stat (2) can also occur. diff --git a/man2/idle.2 b/man2/idle.2 index 197f366..c32b3d7 100644 --- a/man2/idle.2 +++ b/man2/idle.2 @@ -9,13 +9,13 @@ .\" N.B. calling "idle" from user process used to hang process! .\" Modified Thu Oct 31 14:41:15 1996 by Eric S. Raymond <esr@thyrsus.com> .\" " -.TH idle 2 2023-03-30 "Linux man-pages 6.05.01" +.TH idle 2 2023-10-31 "Linux man-pages 6.7" .SH NAME idle \- make process 0 idle .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B [[deprecated]] int idle(void); .fi .SH DESCRIPTION @@ -25,7 +25,7 @@ It marks the process's pages as swappable, lowers its priority, and enters the main scheduling loop. .BR idle () never returns. -.PP +.P Only process 0 may call .BR idle (). Any user process, even a process with superuser permission, diff --git a/man2/init_module.2 b/man2/init_module.2 index a5fed4d..5cc61d0 100644 --- a/man2/init_module.2 +++ b/man2/init_module.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH init_module 2 2023-03-30 "Linux man-pages 6.05.01" +.TH init_module 2 2023-10-31 "Linux man-pages 6.7" .SH NAME init_module, finit_module \- load a kernel module .SH LIBRARY @@ -15,14 +15,14 @@ Standard C library .BR "#include <linux/module.h>" " /* Definition of " MODULE_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_init_module, void " module_image [. len "], \ unsigned long " len , .BI " const char *" param_values ); .BI "int syscall(SYS_finit_module, int " fd , .BI " const char *" param_values ", int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -36,7 +36,7 @@ and then runs the module's .I init function. This system call requires privilege. -.PP +.P The .I module_image argument points to a buffer containing the binary image @@ -44,7 +44,7 @@ to be loaded; .I len specifies the size of that buffer. The module image should be a valid ELF image, built for the running kernel. -.PP +.P The .I param_values argument is a string containing space-delimited specifications of the @@ -55,12 +55,12 @@ and The kernel parses this string and initializes the specified parameters. Each of the parameter specifications has the form: -.PP +.P .RI " " name [\c .BI = value\c .RB [ ,\c .IR value ...]] -.PP +.P The parameter .I name is one of those defined within the module using @@ -93,7 +93,7 @@ The .I param_values argument is as for .BR init_module (). -.PP +.P The .I flags argument modifies the operation of @@ -107,7 +107,7 @@ Ignore symbol version hashes. .TP .B MODULE_INIT_IGNORE_VERMAGIC Ignore kernel version magic. -.PP +.P There are some safety checks built into a module to ensure that it matches the kernel against which it is loaded. .\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html @@ -125,7 +125,7 @@ for the function named by the symbol. In this case, the kernel version number within the "vermagic" string is ignored, as the symbol version hashes are assumed to be sufficiently reliable. -.PP +.P Using the .B MODULE_INIT_IGNORE_VERMAGIC flag indicates that the "vermagic" string is to be ignored, and the @@ -177,7 +177,7 @@ or module loading is disabled .I /proc/sys/kernel/modules_disabled in .BR proc (5)). -.PP +.P The following errors may additionally occur for .BR init_module (): .TP @@ -205,7 +205,7 @@ The binary image supplied in .I module_image is not an ELF image, or is an ELF image that is invalid or for a different architecture. -.PP +.P The following errors may additionally occur for .BR finit_module (): .TP @@ -232,7 +232,7 @@ does not refer to an open file. The file referred to by .I fd is opened for read-write. -.PP +.P In addition to the above errors, if the module's .I init function is executed and returns an error, then @@ -250,7 +250,7 @@ Linux. .TP .BR finit_module () Linux 3.8. -.PP +.P The .BR init_module () system call is not supported by glibc. @@ -265,11 +265,11 @@ alternatively, you can invoke the system call using In Linux 2.4 and earlier, the .BR init_module () system call was rather different: -.PP +.P .B " #include <linux/module.h>" -.PP +.P .BI " int init_module(const char *" name ", struct module *" image ); -.PP +.P (User-space applications can detect which version of .BR init_module () is available by calling @@ -277,7 +277,7 @@ is available by calling the latter call fails with the error .B ENOSYS on Linux 2.6 and later.) -.PP +.P The older version of the system call loads the relocated module image pointed to by .I image @@ -288,11 +288,11 @@ The caller is responsible for providing the relocated image (since Linux 2.6, the .BR init_module () system call does the relocation). -.PP +.P The module image begins with a module structure and is followed by code and data as appropriate. Since Linux 2.2, the module structure is defined as follows: -.PP +.P .in +4n .EX struct module { @@ -317,7 +317,7 @@ struct module { }; .EE .in -.PP +.P All of the pointer fields, with the exception of .I next and @@ -330,7 +330,7 @@ Information about currently loaded modules can be found in .I /proc/modules and in the file trees under the per-module subdirectories under .IR /sys/module . -.PP +.P See the Linux kernel source file .I include/linux/module.h for some useful background information. diff --git a/man2/inotify_add_watch.2 b/man2/inotify_add_watch.2 index 2604115..b86328b 100644 --- a/man2/inotify_add_watch.2 +++ b/man2/inotify_add_watch.2 @@ -6,7 +6,7 @@ .\" 2005-07-19 Robert Love <rlove@rlove.org> - initial version .\" 2006-02-07 mtk, various changes .\" -.TH inotify_add_watch 2 2023-03-30 "Linux man-pages 6.05.01" +.TH inotify_add_watch 2 2023-10-31 "Linux man-pages 6.7" .SH NAME inotify_add_watch \- add a watch to an initialized inotify instance .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/inotify.h> -.PP +.P .BI "int inotify_add_watch(int " fd ", const char *" pathname ", uint32_t " mask ); .fi .SH DESCRIPTION @@ -37,7 +37,7 @@ See .BR inotify (7) for a description of the bits that can be set in .IR mask . -.PP +.P A successful call to .BR inotify_add_watch () returns a unique watch descriptor for this inotify instance, @@ -49,7 +49,7 @@ then the watch descriptor is newly allocated. If the filesystem object was already being watched (perhaps via a different link to the same object), then the descriptor for the existing watch is returned. -.PP +.P The watch descriptor is returned by later .BR read (2)s from the inotify file descriptor. diff --git a/man2/inotify_init.2 b/man2/inotify_init.2 index e6be9c3..16694cf 100644 --- a/man2/inotify_init.2 +++ b/man2/inotify_init.2 @@ -7,7 +7,7 @@ .\" 2006-02-07 mtk, minor changes .\" 2008-10-10 mtk: add description of inotify_init1() .\" -.TH inotify_init 2 2023-03-30 "Linux man-pages 6.05.01" +.TH inotify_init 2 2023-10-31 "Linux man-pages 6.7" .SH NAME inotify_init, inotify_init1 \- initialize an inotify instance .SH LIBRARY @@ -16,18 +16,18 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/inotify.h> -.PP +.P .B "int inotify_init(void);" .BI "int inotify_init1(int " flags ); .fi .SH DESCRIPTION For an overview of the inotify API, see .BR inotify (7). -.PP +.P .BR inotify_init () initializes a new inotify instance and returns a file descriptor associated with a new inotify event queue. -.PP +.P If .I flags is 0, then diff --git a/man2/inotify_rm_watch.2 b/man2/inotify_rm_watch.2 index 8e1b283..9fb5238 100644 --- a/man2/inotify_rm_watch.2 +++ b/man2/inotify_rm_watch.2 @@ -5,7 +5,7 @@ .\" 2005-07-19 Robert Love <rlove@rlove.org> - initial version .\" 2006-02-07 mtk, minor changes .\" -.TH inotify_rm_watch 2 2023-03-30 "Linux man-pages 6.05.01" +.TH inotify_rm_watch 2 2023-10-31 "Linux man-pages 6.7" .SH NAME inotify_rm_watch \- remove an existing watch from an inotify instance .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/inotify.h> -.PP +.P .BI "int inotify_rm_watch(int " fd ", int " wd ); .\" Before glibc 2.10, the second argument was types as uint32_t. .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=7040 @@ -25,7 +25,7 @@ removes the watch associated with the watch descriptor .I wd from the inotify instance associated with the file descriptor .IR fd . -.PP +.P Removing a watch causes an .B IN_IGNORED event to be generated for this watch descriptor. diff --git a/man2/intro.2 b/man2/intro.2 index ef3d8cf..74af07c 100644 --- a/man2/intro.2 +++ b/man2/intro.2 @@ -6,7 +6,7 @@ .\" new _syscall(2) page, and substantially enhanced and rewrote .\" the remaining material on this page. .\" -.TH intro 2 2023-02-05 "Linux man-pages 6.05.01" +.TH intro 2 2023-10-31 "Linux man-pages 6.7" .SH NAME intro \- introduction to system calls .SH DESCRIPTION @@ -19,7 +19,7 @@ wrapper functions which perform the steps required the system call. Thus, making a system call looks the same as invoking a normal library function. -.PP +.P In many cases, the C library wrapper function does nothing more than: .IP \[bu] 3 copying arguments and the unique system call number to the @@ -32,7 +32,7 @@ setting .I errno if the system call returns an error number when the kernel returns the CPU to user mode. -.PP +.P However, in a few cases, a wrapper function may do rather more than this, for example, performing some preprocessing of the arguments before trapping to kernel mode, @@ -42,7 +42,7 @@ try to note the details of both the (usually GNU) C library API interface and the raw system call. Most commonly, the main DESCRIPTION will focus on the C library interface, and differences for the system call are covered in the NOTES section. -.PP +.P For a list of the Linux system calls, see .BR syscalls (2). .SH RETURN VALUE @@ -54,12 +54,12 @@ system call returns a negative value, the wrapper copies the absolute value into the .I errno variable, and returns \-1 as the return value of the wrapper. -.PP +.P The value returned by a successful system call depends on the call. Many system calls return 0 on success, but some can return nonzero values from a successful call. The details are described in the individual manual pages. -.PP +.P In some cases, the programmer must define a feature test macro in order to obtain the declaration of a system call from the header file specified diff --git a/man2/io_cancel.2 b/man2/io_cancel.2 index 1b413e2..7cce965 100644 --- a/man2/io_cancel.2 +++ b/man2/io_cancel.2 @@ -2,13 +2,13 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_cancel 2 2023-03-30 "Linux man-pages 6.05.01" +.TH io_cancel 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_cancel \- cancel an outstanding asynchronous I/O operation .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); see VERSIONS. @@ -17,7 +17,7 @@ see VERSIONS. .BR "#include <linux/aio_abi.h>" " /* Definition of needed types */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_io_cancel, aio_context_t " ctx_id ", struct iocb *" iocb , .BI " struct io_event *" result ); .fi @@ -30,7 +30,7 @@ uses a different type for the .I ctx_id argument. See VERSIONS. -.PP +.P The .BR io_cancel () system call @@ -71,7 +71,7 @@ You probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/io_destroy.2 b/man2/io_destroy.2 index 4f513e5..b22be59 100644 --- a/man2/io_destroy.2 +++ b/man2/io_destroy.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_destroy 2 2023-03-30 "Linux man-pages 6.05.01" +.TH io_destroy 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_destroy \- destroy an asynchronous I/O context .SH LIBRARY @@ -13,10 +13,10 @@ Standard C library .BR "#include <linux/aio_abi.h>" " /* Definition of " aio_context_t " */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_io_destroy, aio_context_t " ctx_id ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR io_destroy (), @@ -31,7 +31,7 @@ uses a different type for the .I ctx_id argument. See VERSIONS. -.PP +.P The .BR io_destroy () system call @@ -62,7 +62,7 @@ You probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/io_getevents.2 b/man2/io_getevents.2 index 3cf506c..05332f3 100644 --- a/man2/io_getevents.2 +++ b/man2/io_getevents.2 @@ -2,13 +2,13 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_getevents 2 2023-03-30 "Linux man-pages 6.05.01" +.TH io_getevents 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_getevents \- read asynchronous I/O events from the completion queue .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); see VERSIONS. @@ -17,12 +17,12 @@ see VERSIONS. .BR "#include <linux/aio_abi.h>" " /* Definition of " *io_* " types */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_io_getevents, aio_context_t " ctx_id , .BI " long " min_nr ", long " nr ", struct io_event *" events , .BI " struct timespec *" timeout ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR io_getevents (), @@ -37,22 +37,22 @@ uses a different type for the .I ctx_id argument. See VERSIONS. -.PP +.P The .BR io_getevents () system call attempts to read at least \fImin_nr\fP events and up to \fInr\fP events from the completion queue of the AIO context specified by \fIctx_id\fP. -.PP +.P The \fItimeout\fP argument specifies the amount of time to wait for events, and is specified as a relative timeout in a .BR timespec (3) structure. -.PP +.P The specified time will be rounded up to the system clock granularity and is guaranteed not to expire early. -.PP +.P Specifying .I timeout as NULL means block indefinitely until at least @@ -70,7 +70,7 @@ expired. It may also be a nonzero value less than .IR min_nr , if the call was interrupted by a signal handler. -.PP +.P For the failure return, see VERSIONS. .SH ERRORS .TP @@ -95,7 +95,7 @@ You probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/io_setup.2 b/man2/io_setup.2 index 0745456..8fba0ba 100644 --- a/man2/io_setup.2 +++ b/man2/io_setup.2 @@ -2,23 +2,23 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_setup 2 2023-03-30 "Linux man-pages 6.05.01" +.TH io_setup 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_setup \- create an asynchronous I/O context .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); see VERSIONS. .SH SYNOPSIS .nf .BR "#include <linux/aio_abi.h>" " /* Defines needed types */" -.PP +.P .BI "long io_setup(unsigned int " nr_events ", aio_context_t *" ctx_idp ); .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see VERSIONS. .SH DESCRIPTION @@ -30,7 +30,7 @@ uses a different type for the .I ctx_idp argument. See VERSIONS. -.PP +.P The .BR io_setup () system call @@ -79,7 +79,7 @@ But instead, you probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/io_submit.2 b/man2/io_submit.2 index 51efb6b..215701e 100644 --- a/man2/io_submit.2 +++ b/man2/io_submit.2 @@ -3,24 +3,24 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_submit 2 2023-05-03 "Linux man-pages 6.05.01" +.TH io_submit 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_submit \- submit asynchronous I/O blocks for processing .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); see VERSIONS. .SH SYNOPSIS .nf .BR "#include <linux/aio_abi.h>" " /* Defines needed types */" -.PP +.P .BI "int io_submit(aio_context_t " ctx_id ", long " nr \ ", struct iocb **" iocbpp ); .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see VERSIONS. .SH DESCRIPTION @@ -32,7 +32,7 @@ uses a different type for the .I ctx_id argument. See VERSIONS. -.PP +.P The .BR io_submit () system call @@ -42,13 +42,13 @@ The .I iocbpp argument should be an array of \fInr\fP AIO control blocks, which will be submitted to context \fIctx_id\fP. -.PP +.P The .I iocb (I/O control block) structure defined in .I linux/aio_abi.h defines the parameters that control the I/O operation. -.PP +.P .in +4n .EX #include <linux/aio_abi.h> @@ -68,7 +68,7 @@ struct iocb { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I aio_data @@ -254,7 +254,7 @@ But instead, you probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/ioctl.2 b/man2/ioctl.2 index d6c0701..518712b 100644 --- a/man2/ioctl.2 +++ b/man2/ioctl.2 @@ -10,7 +10,7 @@ .\" Modified 1999-06-25 by Rachael Munns <vashti@dream.org.uk> .\" Modified 2000-09-21 by Andries Brouwer <aeb@cwi.nl> .\" -.TH ioctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl \- control device .SH LIBRARY @@ -19,10 +19,9 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/ioctl.h> -.PP -.BI "int ioctl(int " fd ", unsigned long " request ", ...);" -.\" POSIX says 'request' is int, but glibc has the above -.\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705 +.P +.BI "int ioctl(int " fd ", unsigned long " op ", ...);" "\f[R] /* glibc, BSD */\f[]" +.BI "int ioctl(int " fd ", int " op ", ...);" "\f[R] /* musl, other UNIX */\f[]" .fi .SH DESCRIPTION The @@ -31,22 +30,22 @@ system call manipulates the underlying device parameters of special files. In particular, many operating characteristics of character special files (e.g., terminals) may be controlled with .BR ioctl () -requests. +operations. The argument .I fd must be an open file descriptor. -.PP -The second argument is a device-dependent request code. +.P +The second argument is a device-dependent operation code. The third argument is an untyped pointer to memory. It's traditionally .BI "char *" argp (from the days before .B "void *" was valid C), and will be so named for this discussion. -.PP +.P An .BR ioctl () -.I request +.I op has encoded in it whether the argument is an .I in parameter or @@ -56,7 +55,7 @@ parameter, and the size of the argument in bytes. Macros and defines used in specifying an .BR ioctl () -.I request +.I op are located in the file .IR <sys/ioctl.h> . See NOTES. @@ -64,7 +63,7 @@ See NOTES. Usually, on success zero is returned. A few .BR ioctl () -requests use the return value as an output parameter +operations use the return value as an output parameter and return a nonnegative value on success. On error, \-1 is returned, and .I errno @@ -80,7 +79,7 @@ is not a valid file descriptor. references an inaccessible memory area. .TP .B EINVAL -.I request +.I op or .I argp is not valid. @@ -90,7 +89,7 @@ is not valid. is not associated with a character special device. .TP .B ENOTTY -The specified request does not apply to the kind of object that the +The specified operation does not apply to the kind of object that the file descriptor .I fd references. @@ -103,7 +102,52 @@ model). .SH STANDARDS None. .SH HISTORY -Version\~7 AT&T UNIX. +Version\~7 AT&T UNIX has +.PD 0 +.in +4n +.nf +.BI "ioctl(int " fildes ", int " op ", struct sgttyb *" argp ); +.fi +.in +.P +.PD +(where +.B struct sgttyb +has historically been used by +.BR stty (2) +and +.BR gtty (2), +and is polymorphic by operation type (like a +.B void * +would be, if it had been available)). +.P +SysIII documents +.I arg +without a type at all. +.P +4.3BSD has +.PD 0 +.in +4n +.nf +.BI "ioctl(int " d ", unsigned long " op ", char *" argp ); +.fi +.in +.P +.PD +(with +.B char * +similarly in for +.BR "void *" ). +.P +SysVr4 has +.PD 0 +.in +4n +.nf +.BI "int ioctl(int " fildes ", int " op ", ... /* " arg " */);" +.fi +.in +.P +.PD .SH NOTES In order to use this call, one needs an open file descriptor. Often the @@ -115,10 +159,12 @@ flag. .\" .SS ioctl structure .\" added two sections - aeb -Ioctl command values are 32-bit constants. +Ioctl +.I op +values are 32-bit constants. In principle these constants are completely arbitrary, but people have tried to build some structure into them. -.PP +.P The old Linux situation was that of mostly 16-bit constants, where the last byte is a serial number, and the preceding byte(s) give a type indicating the driver. @@ -137,7 +183,7 @@ has value .B CYGETTIMEOUT has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq] indicating the cyclades driver. -.PP +.P Later (0.98p5) some more information was built into the number. One has 2 direction bits (00: none, 01: write, 10: read, 11: read/write) @@ -145,7 +191,7 @@ followed by 14 size bits (giving the size of the argument), followed by an 8-bit type (collecting the ioctls in groups for a common purpose or a common driver), and an 8-bit serial number. -.PP +.P The macros describing this structure live in .I <asm/ioctl.h> and are @@ -156,12 +202,12 @@ They use .I sizeof(size) so that size is a misnomer here: this third argument is a data type. -.PP +.P Note that the size bits are very unreliable: in lots of cases they are wrong, either because of buggy macros using .IR sizeof(sizeof(struct)) , or because of legacy values. -.PP +.P Thus, it seems that the new structure only gave disadvantages: it does not help in checking, but it causes varying values for the various architectures. diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2 index 455be75..f06725f 100644 --- a/man2/ioctl_console.2 +++ b/man2/ioctl_console.2 @@ -19,14 +19,14 @@ .\" VT_UNLOCKSWITCH (since Linux 1.3.47, needs CAP_SYS_TTY_CONFIG) .\" VT_GETHIFONTMASK (since Linux 2.6.18) .\" -.TH ioctl_console 2 2023-01-22 "Linux man-pages 6.05.01" +.TH ioctl_console 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_console \- ioctls for console terminal and virtual consoles .SH DESCRIPTION The following Linux-specific .BR ioctl (2) -requests are supported for console terminals and virtual consoles. -Each requires a third argument, assumed here to be +operations are supported for console terminals and virtual consoles. +Each operation requires a third argument, assumed here to be .IR argp . .TP .B KDGETLED @@ -53,7 +53,7 @@ unsigned long integer in However, if a higher order bit is set, the LEDs revert to normal: displaying the state of the keyboard functions of caps lock, num lock, and scroll lock. -.PP +.P Before Linux 1.1.54, the LEDs just reflected the state of the corresponding keyboard flags, and KDGETLED/KDSETLED would also change the keyboard flags. @@ -546,7 +546,7 @@ points to a struct vt_mode { char mode; /* vt mode */ char waitv; /* if set, hang on writes if not active */ - short relsig; /* signal to raise on release req */ + short relsig; /* signal to raise on release op */ short acqsig; /* signal to raise on acquisition */ short frsig; /* unused (set to 0) */ }; @@ -657,7 +657,7 @@ Note that this does not change the videomode. See .BR resizecons (8). (Since Linux 1.3.3.) -.PP +.P The action of the following ioctls depends on the first byte in the struct pointed to by .IR argp , @@ -715,12 +715,20 @@ is 0 for character-by-character selection, or 2 for line-by-line selection. The indicated screen characters are highlighted and saved in a kernel buffer. +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. .TP .BR TIOCLINUX ", " subcode = TIOCL_PASTESEL Paste selection. The characters in the selection buffer are written to .IR fd . +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. .TP .BR TIOCLINUX ", " subcode = TIOCL_UNBLANKSCREEN Unblank the screen. @@ -729,6 +737,10 @@ Unblank the screen. Sets contents of a 256-bit look up table defining characters in a "word", for word-by-word selection. (Since Linux 1.1.32.) +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. .TP .BR TIOCLINUX ", " subcode = TIOCL_GETSHIFTSTATE .I argp @@ -849,7 +861,7 @@ is invalid. .TP .B ENOTTY The file descriptor is not associated with a character special device, -or the specified request does not apply to it. +or the specified operation does not apply to it. .TP .B EPERM Insufficient permission. @@ -864,16 +876,16 @@ without warning. situation as of kernel version 1.1.94; there are many minor and not-so-minor differences with earlier versions.) -.PP +.P Very often, ioctls are introduced for communication between the kernel and one particular well-known program (fdisk, hdparm, setserial, tunelp, loadkeys, selection, setfont, etc.), and their behavior will be changed when required by this particular program. -.PP +.P Programs using these ioctls will not be portable to other versions of UNIX, will not work on older versions of Linux, and will not work on future versions of Linux. -.PP +.P Use POSIX functions. .SH SEE ALSO .BR dumpkeys (1), @@ -898,6 +910,6 @@ Use POSIX functions. .BR mapscrn (8), .BR resizecons (8), .BR setfont (8) -.PP +.P .IR /usr/include/linux/kd.h , .I /usr/include/linux/vt.h diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2 index 67b5a2c..a690cf1 100644 --- a/man2/ioctl_fat.2 +++ b/man2/ioctl_fat.2 @@ -1,7 +1,7 @@ .\" Copyright (C) 2014, Heinrich Schuchardt <xypron.glpk@gmx.de> .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH ioctl_fat 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_fat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_fat \- manipulating the FAT filesystem .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .BR "#include <linux/msdos_fs.h>" " /* Definition of [" V ] FAT_* " and" .BR " ATTR_* " constants */" .B #include <sys/ioctl.h> -.PP +.P .BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t *" attr ); .BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t *" attr ); .BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t *" id ); @@ -32,7 +32,7 @@ can be read with .B FAT_IOCTL_GET_ATTRIBUTES and written with .BR FAT_IOCTL_SET_ATTRIBUTES . -.PP +.P The .I fd argument contains a file descriptor for a file or directory. @@ -41,7 +41,7 @@ It is sufficient to create the file descriptor by calling with the .B O_RDONLY flag. -.PP +.P The .I attr argument contains a pointer to a bit mask. @@ -68,7 +68,7 @@ This attribute is read-only. This bit indicates that this file or directory should be archived. It is set when a file is created or modified. It is reset by an archiving system. -.PP +.P The zero value .B ATTR_NONE can be used to indicate that no attribute bit is set. @@ -76,7 +76,7 @@ can be used to indicate that no attribute bit is set. FAT filesystems are identified by a volume ID. The volume ID can be read with .BR FAT_IOCTL_GET_VOLUME_ID . -.PP +.P The .I fd argument can be a file descriptor for any file or directory of the @@ -86,13 +86,13 @@ It is sufficient to create the file descriptor by calling with the .B O_RDONLY flag. -.PP +.P The .I id argument is a pointer to the field that will be filled with the volume ID. Typically the volume ID is displayed to the user as a group of two 16-bit fields: -.PP +.P .in +4n .EX printf("Volume ID %04x\-%04x\en", id >> 16, id & 0xFFFF); @@ -104,12 +104,12 @@ consisting of up to 8 capital letters, optionally followed by a period and up to 3 capital letters for the file extension. If the actual filename does not fit into this scheme, it is stored as a long filename of up to 255 UTF-16 characters. -.PP +.P The short filenames in a directory can be read with .BR VFAT_IOCTL_READDIR_SHORT . .B VFAT_IOCTL_READDIR_BOTH reads both the short and the long filenames. -.PP +.P The .I fd argument must be a file descriptor for a directory. @@ -122,11 +122,11 @@ The file descriptor can be used only once to iterate over the directory entries by calling .BR ioctl (2) repeatedly. -.PP +.P The .I entry argument is a two-element array of the following structures: -.PP +.P .in +4n .EX struct __fat_dirent { @@ -137,10 +137,10 @@ struct __fat_dirent { }; .EE .in -.PP +.P The first entry in the array is for the short filename. The second entry is for the long filename. -.PP +.P The .I d_ino and @@ -154,7 +154,7 @@ The field holds the offset of the file entry in the directory. As these values are not available for short filenames, the user code should simply ignore them. -.PP +.P The field .I d_reclen contains the length of the filename in the field @@ -174,7 +174,7 @@ is a character string of length 0 for the long filename. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P For .B VFAT_IOCTL_READDIR_BOTH and @@ -205,7 +205,7 @@ does not refer to a directory. The file descriptor .I fd does not refer to an object in a FAT filesystem. -.PP +.P For further error values, see .BR ioctl (2). .SH STANDARDS @@ -234,10 +234,10 @@ to manipulate file attributes. The program reads and displays the archive attribute of a file. After inverting the value of the attribute, the program reads and displays the attribute again. -.PP +.P The following was recorded when applying the program for the file .IR /mnt/user/foo : -.PP +.P .in +4n .EX # ./toggle_fat_archive_flag /mnt/user/foo @@ -335,11 +335,11 @@ main(int argc, char *argv[]) The following program demonstrates the use of .BR ioctl (2) to display the volume ID of a FAT filesystem. -.PP +.P The following output was recorded when applying the program for directory .IR /mnt/user : -.PP +.P .in +4n .EX $ ./display_fat_volume_id /mnt/user @@ -400,10 +400,10 @@ main(int argc, char *argv[]) The following program demonstrates the use of .BR ioctl (2) to list a directory. -.PP +.P The following was recorded when applying the program to the directory .IR /mnt/user : -.PP +.P .in +4n .EX $ \fB./fat_dir /mnt/user\fP diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2 index 68cfc67..b2c5e6b 100644 --- a/man2/ioctl_ficlonerange.2 +++ b/man2/ioctl_ficlonerange.2 @@ -1,7 +1,7 @@ .\" Copyright (c) 2016, Oracle. All rights reserved. .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH ioctl_ficlonerange 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioctl_ficlonerange 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file @@ -12,7 +12,7 @@ Standard C library .nf .BR "#include <linux/fs.h>" " /* Definition of " FICLONE* " constants */" .B #include <sys/ioctl.h> -.PP +.P .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg ); .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd ); .fi @@ -31,7 +31,7 @@ If a file write should occur to a shared region, the filesystem must ensure that the changes remain private to the file being written. This behavior is commonly referred to as "copy on write". -.PP +.P This ioctl reflinks up to .I src_length bytes from file descriptor @@ -48,7 +48,7 @@ If is zero, the ioctl reflinks to the end of the source file. This information is conveyed in a structure of the following form: -.PP +.P .in +4n .EX struct file_clone_range { @@ -59,10 +59,10 @@ struct file_clone_range { }; .EE .in -.PP +.P Clones are atomic with regards to concurrent writes, so no locks need to be taken to obtain a consistent cloned copy. -.PP +.P The .B FICLONE ioctl clones entire files. @@ -114,7 +114,7 @@ are not on the same mounted filesystem. Linux. .SH HISTORY Linux 4.5. -.PP +.P They were previously known as .B BTRFS_IOC_CLONE and diff --git a/man2/ioctl_fideduperange.2 b/man2/ioctl_fideduperange.2 index 5388c5d..84fd2e8 100644 --- a/man2/ioctl_fideduperange.2 +++ b/man2/ioctl_fideduperange.2 @@ -1,7 +1,7 @@ .\" Copyright (c) 2016, Oracle. All rights reserved. .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH ioctl_fideduperange 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioctl_fideduperange 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_fideduperange \- share some the data of one file with another file .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .BR "#include <linux/fs.h>" " /* Definition of " FIDEDUPERANGE " and" .BR " FILE_DEDUPE_* " constants */ .B #include <sys/ioctl.h> -.PP +.P .BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg ); .fi .SH DESCRIPTION @@ -32,7 +32,7 @@ If a file write should occur to a shared region, the filesystem must ensure that the changes remain private to the file being written. This behavior is commonly referred to as "copy on write". -.PP +.P This ioctl performs the "compare and share if identical" operation on up to .I src_length bytes from file descriptor @@ -40,7 +40,7 @@ bytes from file descriptor at offset .IR src_offset . This information is conveyed in a structure of the following form: -.PP +.P .in +4n .EX struct file_dedupe_range { @@ -53,20 +53,20 @@ struct file_dedupe_range { }; .EE .in -.PP +.P Deduplication is atomic with regards to concurrent writes, so no locks need to be taken to obtain a consistent deduplicated copy. -.PP +.P The fields .IR reserved1 " and " reserved2 must be zero. -.PP +.P Destinations for the deduplication operation are conveyed in the array at the end of the structure. The number of destinations is given in .IR dest_count , and the destination information is conveyed in the following form: -.PP +.P .in +4n .EX struct file_dedupe_range_info { @@ -78,7 +78,7 @@ struct file_dedupe_range_info { }; .EE .in -.PP +.P Each deduplication operation targets .I src_length bytes in file descriptor @@ -109,14 +109,14 @@ is mapped into and the previous contents in .I dest_fd are freed. -.PP +.P Upon successful completion of this ioctl, the number of bytes successfully deduplicated is returned in .I bytes_deduped and a status code for the deduplication operation is returned in .IR status . If even a single byte in the range does not match, the deduplication -request will be ignored and +operation request will be ignored and .I status set to .BR FILE_DEDUPE_RANGE_DIFFERS . @@ -187,7 +187,7 @@ single call. Linux. .SH HISTORY Linux 4.5. -.PP +.P It was previously known as .B BTRFS_IOC_FILE_EXTENT_SAME and was private to Btrfs. diff --git a/man2/ioctl_fslabel.2 b/man2/ioctl_fslabel.2 index 885a43c..7fcde80 100644 --- a/man2/ioctl_fslabel.2 +++ b/man2/ioctl_fslabel.2 @@ -1,7 +1,7 @@ .\" Copyright (c) 2018, Red Hat, Inc. All rights reserved. .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH ioctl_fslabel 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioctl_fslabel 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_fslabel \- get or set a filesystem label .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .nf .BR "#include <linux/fs.h>" " /* Definition of " *FSLABEL* " constants */" .B #include <sys/ioctl.h> -.PP +.P .BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]); .BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]); .fi @@ -50,7 +50,7 @@ The calling process does not have sufficient permissions to set the label. Linux. .SH HISTORY Linux 4.18. -.PP +.P They were previously known as .B BTRFS_IOC_GET_FSLABEL and diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2 index e80c1d9..97fbc67 100644 --- a/man2/ioctl_getfsmap.2 +++ b/man2/ioctl_getfsmap.2 @@ -1,7 +1,7 @@ .\" Copyright (c) 2017, Oracle. All rights reserved. .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH ioctl_getfsmap 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_getfsmap 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_getfsmap \- retrieve the physical layout of the filesystem .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .BR "#include <linux/fsmap.h> " "/* Definition of " FS_IOC_GETFSMAP , .BR " FM?_OF_*" ", and " *FMR_OWN_* " constants */" .B #include <sys/ioctl.h> -.PP +.P .BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg ); .fi .SH DESCRIPTION @@ -21,10 +21,10 @@ This operation retrieves physical extent mappings for a filesystem. This information can be used to discover which files are mapped to a physical block, examine free space, or find known bad blocks, among other things. -.PP +.P The sole argument to this operation should be a pointer to a single .IR "struct fsmap_head" ":" -.PP +.P .in +4n .EX struct fsmap { @@ -50,7 +50,7 @@ struct fsmap_head { }; .EE .in -.PP +.P The two .I fmh_keys array elements specify the lowest and highest reverse-mapping @@ -60,7 +60,7 @@ A reverse mapping key consists of the tuple (device, block, owner, offset). The owner and offset fields are part of the key because some filesystems support sharing physical blocks between multiple files and therefore may return multiple mappings for a given physical block. -.PP +.P Filesystem mappings are copied into the .I fmh_recs array, which immediately follows the header data. @@ -70,7 +70,7 @@ The .I fmh_iflags field is a bit mask passed to the kernel to alter the output. No flags are currently defined, so the caller must set this value to zero. -.PP +.P The .I fmh_oflags field is a bit mask of flags set by the kernel concerning the returned mappings. @@ -81,7 +81,7 @@ is set, then the field represents a .I dev_t structure containing the major and minor numbers of the block device. -.PP +.P The .I fmh_count field contains the number of elements in the array being passed to the @@ -91,13 +91,13 @@ If this value is 0, will be set to the number of records that would have been returned had the array been large enough; no mapping information will be returned. -.PP +.P The .I fmh_entries field contains the number of elements in the .I fmh_recs array that contain useful information. -.PP +.P The .I fmh_reserved fields must be set to zero. @@ -124,8 +124,8 @@ By convention, the field .I fsmap_head.fmh_keys[0] must contain the low key and .I fsmap_head.fmh_keys[1] -must contain the high key for the request. -.PP +must contain the high key for the operation. +.P For convenience, if .I fmr_length is set in the low key, it will be added to @@ -154,11 +154,11 @@ field, this field contains a from which major and minor numbers can be extracted. If the flag is not set, this field contains a value that must be unique for each unique storage device. -.PP +.P The .I fmr_physical field contains the disk address of the extent in bytes. -.PP +.P The .I fmr_owner field contains the owner of the extent. @@ -168,7 +168,7 @@ is set in the .I fmr_flags field, in which case the value is determined by the filesystem. See the section below about owner values for more details. -.PP +.P The .I fmr_offset field contains the logical address in the mapping record in bytes. @@ -176,11 +176,11 @@ This field has no meaning if the .BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP flags are set in .IR fmr_flags "." -.PP +.P The .I fmr_length field contains the length of the extent in bytes. -.PP +.P The .I fmr_flags field is a bit mask of extent state flags. @@ -207,7 +207,7 @@ field contains a special value instead of an inode number. .B FMR_OF_LAST This is the last record in the data set. .RE -.PP +.P The .I fmr_reserved field will be set to zero. @@ -239,7 +239,7 @@ This extent is in use but its owner is not known or not easily retrieved. .B FMR_OWN_METADATA This extent is filesystem metadata. .RE -.PP +.P XFS can return the following special owner values: .RS 0.4i .TP @@ -276,7 +276,7 @@ This extent is being used to stage a copy-on-write. This extent has been marked defective either by the filesystem or the underlying device. .RE -.PP +.P ext4 can return the following special owner values: .RS 0.4i .TP @@ -328,16 +328,16 @@ physical storage address space than the high key, or a nonzero value was passed in one of the fields that must be zero. .TP .B ENOMEM -Insufficient memory to process the request. +Insufficient memory to process the operation. .TP .B EOPNOTSUPP -The filesystem does not support this command. +The filesystem does not support this operation. .TP .B EUCLEAN The filesystem metadata is corrupt and needs repair. .SH STANDARDS Linux. -.PP +.P Not all filesystems support it. .SH HISTORY Linux 4.12. diff --git a/man2/ioctl_iflags.2 b/man2/ioctl_iflags.2 index d2c3300..e6cc7cb 100644 --- a/man2/ioctl_iflags.2 +++ b/man2/ioctl_iflags.2 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ioctl_iflags 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_iflags 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_iflags \- ioctl() operations for inode flags .SH DESCRIPTION @@ -13,7 +13,7 @@ that modify the semantics of files and directories. These flags can be retrieved and modified using two .BR ioctl (2) operations: -.PP +.P .in +4n .EX int attr; @@ -26,14 +26,14 @@ ioctl(fd, FS_IOC_SETFLAGS, &attr); /* Update flags for inode referred to by \[aq]fd\[aq] */ .EE .in -.PP +.P The .BR lsattr (1) and .BR chattr (1) shell commands provide interfaces to these two operations, allowing a user to view and modify the inode flags associated with a file. -.PP +.P The following flags are supported (shown along with the corresponding letter used to indicate the flag by .BR lsattr (1) @@ -160,7 +160,7 @@ has an effect only for ext2, ext3, and ext4. Allow the file to be undeleted if it is deleted. This feature is not implemented by any filesystem, since it is possible to implement file-recovery mechanisms outside the kernel. -.PP +.P In most cases, when any of the above flags is set on a directory, the flag is inherited by files and subdirectories @@ -180,7 +180,7 @@ the effective user ID of the caller must match the owner of the file, or the caller must have the .B CAP_FOWNER capability. -.PP +.P The type of the argument given to the .B FS_IOC_GETFLAGS and diff --git a/man2/ioctl_ns.2 b/man2/ioctl_ns.2 index a11e54b..a21c14a 100644 --- a/man2/ioctl_ns.2 +++ b/man2/ioctl_ns.2 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ioctl_ns 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_ns 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_ns \- ioctl() operations for Linux namespaces .SH DESCRIPTION @@ -17,13 +17,13 @@ operations are provided to allow discovery of namespace relationships (see and .BR pid_namespaces (7)). The form of the calls is: -.PP +.P .in +4n .EX -new_fd = ioctl(fd, request); +new_fd = ioctl(fd, op); .EE .in -.PP +.P In each case, .I fd refers to a @@ -49,7 +49,7 @@ For user namespaces, .B NS_GET_PARENT is synonymous with .BR NS_GET_USERNS . -.PP +.P The new file descriptor returned by these operations is opened with the .B O_RDONLY and @@ -57,7 +57,7 @@ and (close-on-exec; see .BR fcntl (2)) flags. -.PP +.P By applying .BR fstat (2) to the returned file descriptor, one obtains a @@ -70,7 +70,7 @@ structure whose This inode number can be matched with the inode number of another .IR /proc/ pid /ns/ { pid , user } file to determine whether that is the owning/parent namespace. -.PP +.P Either of these .BR ioctl (2) operations can fail with the following errors: @@ -84,7 +84,7 @@ user or PID namespace. .TP .B ENOTTY The operation is not supported by this kernel version. -.PP +.P Additionally, the .B NS_GET_PARENT operation can fail with the following error: @@ -92,7 +92,7 @@ operation can fail with the following error: .B EINVAL .I fd refers to a nonhierarchical namespace. -.PP +.P See the EXAMPLES section for an example of the use of these operations. .\" ============================================================ .\" @@ -103,18 +103,18 @@ The operation (available since Linux 4.11) can be used to discover the type of namespace referred to by the file descriptor .IR fd : -.PP +.P .in +4n .EX nstype = ioctl(fd, NS_GET_NSTYPE); .EE .in -.PP +.P .I fd refers to a .IR /proc/ pid /ns/* file. -.PP +.P The return value is one of the .B CLONE_NEW* values that can be specified to @@ -132,23 +132,23 @@ operation (available since Linux 4.11) can be used to discover the owner user ID of a user namespace (i.e., the effective user ID of the process that created the user namespace). The form of the call is: -.PP +.P .in +4n .EX uid_t uid; ioctl(fd, NS_GET_OWNER_UID, &uid); .EE .in -.PP +.P .I fd refers to a .IR /proc/ pid /ns/user file. -.PP +.P The owner user ID is returned in the .I uid_t pointed to by the third argument. -.PP +.P This operation can fail with the following error: .TP .B EINVAL @@ -173,22 +173,22 @@ operations described above to perform simple discovery of namespace relationships. The following shell sessions show various examples of the use of this program. -.PP +.P Trying to get the parent of the initial user namespace fails, since it has no parent: -.PP +.P .in +4n .EX $ \fB./ns_show /proc/self/ns/user p\fP The parent namespace is outside your namespace scope .EE .in -.PP +.P Create a process running .BR sleep (1) that resides in new user and UTS namespaces, and show that the new UTS namespace is associated with the new user namespace: -.PP +.P .in +4n .EX $ \fBunshare \-Uu sleep 1000 &\fP @@ -199,10 +199,10 @@ $ \fBreadlink /proc/23235/ns/user\fP user:[4026532448] .EE .in -.PP +.P Then show that the parent of the new user namespace in the preceding example is the initial user namespace: -.PP +.P .in +4n .EX $ \fBreadlink /proc/self/ns/user\fP @@ -211,13 +211,13 @@ $ \fB./ns_show /proc/23235/ns/user p\fP Device/Inode of parent namespace is: [0,3] / 4026531837 .EE .in -.PP +.P Start a shell in a new user namespace, and show that from within this shell, the parent user namespace can't be discovered. Similarly, the UTS namespace (which is associated with the initial user namespace) can't be discovered. -.PP +.P .in +4n .EX $ \fBPS1="sh2$ " unshare \-U bash\fP diff --git a/man2/ioctl_pagemap_scan.2 b/man2/ioctl_pagemap_scan.2 new file mode 100644 index 0000000..fcd9bdc --- /dev/null +++ b/man2/ioctl_pagemap_scan.2 @@ -0,0 +1,206 @@ +.\" This manpage is Copyright (C) 2023 Collabora; +.\" Written by Muhammad Usama Anjum <usama.anjum@collabora.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ioctl_pagemap_scan 2 2024-01-28 "Linux man-pages 6.7" +.SH NAME +ioctl_pagemap_scan \- get and/or clear page flags +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <linux/fs.h>" " /* Definition of " "struct pm_scan_arg" , +.BR " struct page_region" ", and " PAGE_IS_* " constants */" +.B #include <sys/ioctl.h> +.P +.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg ); +.fi +.SH DESCRIPTION +This +.BR ioctl (2) +is used to get and optionally clear some specific flags from page table entries. +The information is returned with +.B PAGE_SIZE +granularity. +.P +To start tracking the written state (flag) of a page or range of memory, +the +.B UFFD_FEATURE_WP_ASYNC +must be enabled by +.B UFFDIO_API +.BR ioctl (2) +on +.B userfaultfd +and memory range must be registered with +.B UFFDIO_REGISTER +.BR ioctl (2) +in +.B UFFDIO_REGISTER_MODE_WP +mode. +.SS Supported page flags +The following page table entry flags are supported: +.TP +.B PAGE_IS_WPALLOWED +The page has asynchronous write-protection enabled. +.TP +.B PAGE_IS_WRITTEN +The page has been written to from the time it was write protected. +.TP +.B PAGE_IS_FILE +The page is file backed. +.TP +.B PAGE_IS_PRESENT +The page is present in the memory. +.TP +.B PAGE_IS_SWAPPED +The page is swapped. +.TP +.B PAGE_IS_PFNZERO +The page has zero PFN. +.TP +.B PAGE_IS_HUGE +The page is THP or Hugetlb backed. +.SS Supported operations +The get operation is always performed +if the output buffer is specified. +The other operations are as following: +.TP +.B PM_SCAN_WP_MATCHING +Write protect the matched pages. +.TP +.B PM_SCAN_CHECK_WPASYNC +Abort the scan +when a page is found +which doesn't have the Userfaultfd Asynchronous Write protection enabled. +.SS The \f[I]struct pm_scan_arg\f[] argument +.EX +struct pm_scan_arg { + __u64 size; + __u64 flags; + __u64 start; + __u64 end; + __u64 walk_end; + __u64 vec; + __u64 vec_len; + __u64 max_pages + __u64 category_inverted; + __u64 category_mask; + __u64 category_anyof_mask + __u64 return_mask; +}; +.EE +.TP +.B size +This field should be set to the size of the structure in bytes, +as in +.IR sizeof(struct\~pm_scan_arg) . +.TP +.B flags +The operations to be performed are specified in it. +.TP +.B start +The starting address of the scan is specified in it. +.TP +.B end +The ending address of the scan is specified in it. +.TP +.B walk_end +The kernel returns the scan's ending address in it. +The +.I walk_end +equal to +.I end +means that scan has completed on the entire range. +.TP +.B vec +The address of +.I page_region +array for output. +.IP +.in +4n +.EX +struct page_region { + __u64 start; + __u64 end; + __u64 categories; +}; +.EE +.in +.TP +.B vec_len +The length of the +.I page_region +struct array. +.TP +.B max_pages +It is the optional limit for the number of output pages required. +.TP +.B category_inverted +.BI PAGE_IS_ * +categories which values match if 0 instead of 1. +.TP +.B category_mask +Skip pages for which any +.BI PAGE_IS_ * +category doesn't match. +.TP +.B category_anyof_mask +Skip pages for which no +.BI PAGE_IS_ * +category matches. +.TP +.B return_mask +.BI PAGE_IS_ * +categories that are to be reported in +.IR page_region . +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Error codes can be one of, but are not limited to, the following: +.TP +.B EINVAL +Invalid arguments i.e., +invalid +.I size +of the argument, +invalid +.IR flags , +invalid +.IR categories , +the +.I start +address isn't aligned with +.BR PAGE_SIZE , +or +.I vec_len +is specified when +.I vec +is NULL. +.TP +.B EFAULT +Invalid +.I arg +pointer, +invalid +.I vec +pointer, +or invalid address range specified by +.I start +and +.IR end . +.TP +.B ENOMEM +No memory is available. +.TP +.B EINTR +Fetal signal is pending. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 6.7. +.SH SEE ALSO +.BR ioctl (2) diff --git a/man2/ioctl_pipe.2 b/man2/ioctl_pipe.2 index 31e02bb..d08efa1 100644 --- a/man2/ioctl_pipe.2 +++ b/man2/ioctl_pipe.2 @@ -2,14 +2,14 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH ioctl_pipe 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_pipe 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_pipe \- ioctl() operations for General notification mechanism .SH SYNOPSIS .nf .BR "#include <linux/watch_queue.h>" " /* Definition of " IOC_WATCH_QUEUE_ "* */" .B #include <sys/ioctl.h> -.PP +.P .BI "int ioctl(int " pipefd "[1], IOC_WATCH_QUEUE_SET_SIZE, int " size ); .BI "int ioctl(int " pipefd "[1], IOC_WATCH_QUEUE_SET_FILTER," .BI " struct watch_notification_filter *" filter ); diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 index dfbd9a8..9d247ed 100644 --- a/man2/ioctl_tty.2 +++ b/man2/ioctl_tty.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH ioctl_tty 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_tty 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_tty \- ioctls for terminals and serial lines .SH LIBRARY @@ -17,25 +17,25 @@ Standard C library .BR " struct termios2" ", and" .BR " Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL , .BR " TC*" { FLUSH , ON , OFF "} and other constants */" -.PP -.BI "int ioctl(int " fd ", int " cmd ", ...);" +.P +.BI "int ioctl(int " fd ", int " op ", ...);" .fi .SH DESCRIPTION The .BR ioctl (2) -call for terminals and serial ports accepts many possible command arguments. +call for terminals and serial ports accepts many possible operation arguments. Most require a third argument, of varying type, here called .I argp or .IR arg . -.PP +.P Use of .BR ioctl () makes for nonportable programs. Use the POSIX interface described in .BR termios (3) whenever possible. -.PP +.P Please note that .B struct termios from @@ -87,7 +87,7 @@ Equivalent to .IP Allow the output buffer to drain, discard pending input, and set the current serial port settings. -.PP +.P The following four ioctls, added in Linux 2.6.20, .\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6 .\" commit 592ee3a5e5e2a981ef2829a0380093006d045661 @@ -119,7 +119,7 @@ TCSETSW2 \fBconst struct termios2 *\fPargp TCSETSF2 \fBconst struct termios2 *\fPargp .TE .RE -.PP +.P The following four ioctls are just like .BR TCGETS , .BR TCSETS , @@ -182,9 +182,9 @@ Argument: .BI "const struct winsize\~*" argp .IP Set window size. -.PP +.P The struct used by these ioctls is defined as -.PP +.P .in +4n .EX struct winsize { @@ -195,7 +195,7 @@ struct winsize { }; .EE .in -.PP +.P When the window size changes, a .B SIGWINCH signal is sent to the @@ -334,6 +334,15 @@ Argument: .BI "const char\~*" argp .IP Insert the given byte in the input queue. +.IP +Since Linux 6.2, +.\" commit 690c8b804ad2eafbd35da5d3c95ad325ca7d5061 +.\" commit 83efeeeb3d04b22aaed1df99bc70a48fe9d22c4d +this operation may require the +.B CAP_SYS_ADMIN +capability (if the +.I dev.tty.legacy_tiocsti +sysctl variable is set to false). .SS Redirecting console output .TP .B TIOCCONS @@ -594,7 +603,7 @@ and similar library functions that have insecure APIs. .BR ptsname (3) with a pathname where a devpts filesystem has been mounted in a different mount namespace.) -.PP +.P The BSD ioctls .BR TIOCSTOP , .BR TIOCSTART , @@ -627,9 +636,9 @@ Argument: .BI "const int\~*" argp .IP Set the indicated modem bits. -.PP +.P The following bits are used by the above ioctls: -.PP +.P .TS lb l. TIOCM_LE DSR (data set ready/line enable) @@ -695,7 +704,7 @@ Set the CLOCAL flag in the structure when .RI * argp is nonzero, and clear it otherwise. -.PP +.P If the .B CLOCAL flag for a line is off, the hardware carrier detect (DCD) @@ -726,7 +735,7 @@ Get the .I tty_struct corresponding to .IR fd . -This command was removed in Linux 2.5.67. +This operation was removed in Linux 2.5.67. .\" commit b3506a09d15dc5aee6d4bb88d759b157016e1864 .\" Author: Andries E. Brouwer <andries.brouwer@cwi.nl> .\" Date: Tue Apr 1 04:42:46 2003 -0800 @@ -738,7 +747,7 @@ This command was removed in Linux 2.5.67. .\" .\" .SS Serial info .\" .BR "#include <linux/serial.h>" -.\" .PP +.\" .P .\" .TP .\" .BI "TIOCGSERIAL struct serial_struct *" argp .\" Get serial info. @@ -755,10 +764,10 @@ to indicate the error. .SH ERRORS .TP .B EINVAL -Invalid command parameter. +Invalid operation parameter. .TP .B ENOIOCTLCMD -Unknown command. +Unknown operation. .TP .B ENOTTY Inappropriate @@ -768,7 +777,7 @@ Inappropriate Insufficient permission. .SH EXAMPLES Check the condition of DTR on the serial port. -.PP +.P .\" SRC BEGIN (tiocmget.c) .EX #include <fcntl.h> @@ -791,9 +800,9 @@ main(void) } .EE .\" SRC END -.PP +.P Get or set arbitrary baudrate on the serial port. -.PP +.P .\" SRC BEGIN (tcgets.c) .EX /* SPDX-License-Identifier: GPL-2.0-or-later */ diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 index 6ab9c11..08e52e6 100644 --- a/man2/ioctl_userfaultfd.2 +++ b/man2/ioctl_userfaultfd.2 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ioctl_userfaultfd 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_userfaultfd 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_userfaultfd \- create a file descriptor for handling page faults in user space @@ -16,8 +16,8 @@ Standard C library .nf .BR "#include <linux/userfaultfd.h>" " /* Definition of " UFFD* " constants */" .B #include <sys/ioctl.h> -.PP -.BI "int ioctl(int " fd ", int " cmd ", ...);" +.P +.BI "int ioctl(int " fd ", int " op ", ...);" .fi .SH DESCRIPTION Various @@ -25,21 +25,22 @@ Various operations can be performed on a userfaultfd object (created by a call to .BR userfaultfd (2)) using calls of the form: -.PP +.P .in +4n .EX -ioctl(fd, cmd, argp); +ioctl(fd, op, argp); .EE .in +.P In the above, .I fd is a file descriptor referring to a userfaultfd object, -.I cmd -is one of the commands listed below, and +.I op +is one of the operations listed below, and .I argp is a pointer to a data structure that is specific to -.IR cmd . -.PP +.IR op . +.P The various .BR ioctl (2) operations are described below. @@ -62,13 +63,13 @@ events. .SS UFFDIO_API (Since Linux 4.3.) Enable operation of the userfaultfd and perform API handshake. -.PP +.P The .I argp argument is a pointer to a .I uffdio_api structure, defined as: -.PP +.P .in +4n .EX struct uffdio_api { @@ -78,11 +79,10 @@ struct uffdio_api { }; .EE .in -.PP +.P The .I api field denotes the API version requested by the application. -.PP The kernel verifies that it can support the requested API version, and sets the .I features @@ -91,7 +91,26 @@ and fields to bit masks representing all the available features and the generic .BR ioctl (2) operations available. -.PP +.P +Since Linux 4.11, +applications should use the +.I features +field to perform a two-step handshake. +First, +.B UFFDIO_API +is called with the +.I features +field set to zero. +The kernel responds by setting all supported feature bits. +.P +Applications which do not require any specific features +can begin using the userfaultfd immediately. +Applications which do need specific features +should call +.B UFFDIO_API +again with a subset of the reported feature bits set +to enable those features. +.P Before Linux 4.11, the .I features field must be initialized to zero before the call to @@ -100,26 +119,13 @@ and zero (i.e., no feature bits) is placed in the .I features field by the kernel upon return from .BR ioctl (2). -.PP -Starting from Linux 4.11, the -.I features -field can be used to ask whether particular features are supported -and explicitly enable userfaultfd features that are disabled by default. -The kernel always reports all the available features in the -.I features -field. -.PP -To enable userfaultfd features the application should set -a bit corresponding to each feature it wants to enable in the -.I features -field. -If the kernel supports all the requested features it will enable them. -Otherwise it will zero out the returned +.P +If the application sets unsupported feature bits, +the kernel will zero out the returned .I uffdio_api structure and return .BR EINVAL . -.\" FIXME add more details about feature negotiation and enablement -.PP +.P The following feature bits may be set: .TP .BR UFFD_FEATURE_EVENT_FORK " (since Linux 4.11)" @@ -198,6 +204,13 @@ If this feature bit is set, .I uffd_msg.pagefault.feat.ptid will be set to the faulted thread ID for each page-fault message. .TP +.BR UFFD_FEATURE_PAGEFAULT_FLAG_WP " (since Linux 5.10)" +If this feature bit is set, +userfaultfd supports write-protect faults +for anonymous memory. +(Note that shmem / hugetlbfs support +is indicated by a separate feature.) +.TP .BR UFFD_FEATURE_MINOR_HUGETLBFS " (since Linux 5.13)" If this feature bit is set, the kernel supports registering userfaultfd ranges @@ -215,7 +228,28 @@ will be set to the exact page-fault address that was reported by the hardware, and will not mask the offset within the page. Note that old Linux versions might indicate the exact address as well, even though the feature bit is not set. -.PP +.TP +.BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM " (since Linux 5.19)" +If this feature bit is set, +userfaultfd supports write-protect faults +for hugetlbfs and shmem / tmpfs memory. +.TP +.BR UFFD_FEATURE_WP_UNPOPULATED " (since Linux 6.4)" +If this feature bit is set, +the kernel will handle anonymous memory the same way as file memory, +by allowing the user to write-protect unpopulated page table entries. +.TP +.BR UFFD_FEATURE_POISON " (since Linux 6.6)" +If this feature bit is set, +the kernel supports resolving faults with the +.B UFFDIO_POISON +ioctl. +.TP +.BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)" +If this feature bit is set, +the write protection faults would be asynchronously resolved +by the kernel. +.P The returned .I ioctls field can contain the following bits: @@ -236,13 +270,21 @@ operation is supported. The .B UFFDIO_UNREGISTER operation is supported. -.PP +.P This .BR ioctl (2) operation returns 0 on success. On error, \-1 is returned and .I errno is set to indicate the error. +If an error occurs, +the kernel may zero the provided +.I uffdio_api +structure. +The caller should treat its contents as unspecified, +and reinitialize it before re-attempting another +.B UFFDIO_API +call. Possible errors include: .TP .B EFAULT @@ -251,38 +293,44 @@ refers to an address that is outside the calling process's accessible address space. .TP .B EINVAL -The userfaultfd has already been enabled by a previous -.B UFFDIO_API -operation. -.TP -.B EINVAL The API version requested in the .I api field is not supported by this kernel, or the .I features field passed to the kernel includes feature bits that are not supported by the current kernel version. -.\" FIXME In the above error case, the returned 'uffdio_api' structure is -.\" zeroed out. Why is this done? This should be explained in the manual page. -.\" -.\" Mike Rapoport: -.\" In my understanding the uffdio_api -.\" structure is zeroed to allow the caller -.\" to distinguish the reasons for -EINVAL. -.\" +.TP +.B EINVAL +A previous +.B UFFDIO_API +call already enabled one or more features for this userfaultfd. +Calling +.B UFFDIO_API +twice, +the first time with no features set, +is explicitly allowed +as per the two-step feature detection handshake. +.TP +.B EPERM +The +.B UFFD_FEATURE_EVENT_FORK +feature was enabled, +but the calling process doesn't have the +.B CAP_SYS_PTRACE +capability. .SS UFFDIO_REGISTER (Since Linux 4.3.) Register a memory address range with the userfaultfd object. -The pages in the range must be "compatible". +The pages in the range must be \[lq]compatible\[rq]. Please refer to the list of register modes below for the compatible memory backends for each mode. -.PP +.P The .I argp argument is a pointer to a .I uffdio_register structure, defined as: -.PP +.P .in +4n .EX struct uffdio_range { @@ -297,7 +345,7 @@ struct uffdio_register { }; .EE .in -.PP +.P The .I range field defines a memory range starting at @@ -305,7 +353,7 @@ field defines a memory range starting at and continuing for .I len bytes that should be handled by the userfaultfd. -.PP +.P The .I mode field defines the mode of operation desired for this memory region. @@ -330,7 +378,7 @@ Since Linux 5.13, only hugetlbfs ranges are compatible. Since Linux 5.14, compatibility with shmem ranges was added. -.PP +.P If the operation is successful, the kernel modifies the .I ioctls bit-mask field to indicate which @@ -351,6 +399,7 @@ operation is supported. .B 1 << _UFFDIO_WRITEPROTECT The .B UFFDIO_WRITEPROTECT +operation is supported. .TP .B 1 << _UFFDIO_ZEROPAGE The @@ -361,7 +410,12 @@ operation is supported. The .B UFFDIO_CONTINUE operation is supported. -.PP +.TP +.B 1 << _UFFDIO_POISON +The +.B UFFDIO_POISON +operation is supported. +.P This .BR ioctl (2) operation returns 0 on success. @@ -407,14 +461,15 @@ There as an incompatible mapping in the specified address range. .SS UFFDIO_UNREGISTER (Since Linux 4.3.) Unregister a memory address range from userfaultfd. -The pages in the range must be "compatible" (see the description of -.BR UFFDIO_REGISTER .) -.PP +The pages in the range must be \[lq]compatible\[rq] +(see the description of +.BR UFFDIO_REGISTER .) +.P The address range to unregister is specified in the .I uffdio_range structure pointed to by .IR argp . -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -446,12 +501,15 @@ Atomically copy a continuous memory chunk into the userfault registered range and optionally wake up the blocked thread. The source and destination addresses and the number of bytes to copy are specified by the -.IR src ", " dst ", and " len +.IR src , +.IR dst , +and +.I len fields of the .I uffdio_copy structure pointed to by .IR argp : -.PP +.P .in +4n .EX struct uffdio_copy { @@ -463,7 +521,7 @@ struct uffdio_copy { }; .EE .in -.PP +.P The following value may be bitwise ORed in .I mode to change the behavior of the @@ -482,7 +540,7 @@ This is used only when both and .B UFFDIO_REGISTER_MODE_WP modes are enabled for the registered range. -.PP +.P The .I copy field is used by the kernel to return the number of bytes @@ -503,7 +561,7 @@ field is output-only; it is not read by the .B UFFDIO_COPY operation. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -560,14 +618,14 @@ operation. .SS UFFDIO_ZEROPAGE (Since Linux 4.3.) Zero out a memory range registered with userfaultfd. -.PP +.P The requested range is specified by the .I range field of the .I uffdio_zeropage structure pointed to by .IR argp : -.PP +.P .in +4n .EX struct uffdio_zeropage { @@ -577,7 +635,7 @@ struct uffdio_zeropage { }; .EE .in -.PP +.P The following value may be bitwise ORed in .I mode to change the behavior of the @@ -586,7 +644,7 @@ operation: .TP .B UFFDIO_ZEROPAGE_MODE_DONTWAKE Do not wake up the thread that waits for page-fault resolution. -.PP +.P The .I zeropage field is used by the kernel to return the number of bytes @@ -607,7 +665,7 @@ field is output-only; it is not read by the .B UFFDIO_ZEROPAGE operation. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -648,7 +706,7 @@ operation. (Since Linux 4.3.) Wake up the thread waiting for page-fault resolution on a specified memory address range. -.PP +.P The .B UFFDIO_WAKE operation is used in conjunction with @@ -668,13 +726,13 @@ and .B UFFDIO_ZEROPAGE operations in a batch and then explicitly wake up the faulting thread using .BR UFFDIO_WAKE . -.PP +.P The .I argp argument is a pointer to a .I uffdio_range structure (shown above) that specifies the address range. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -693,17 +751,18 @@ field of the structure was not a multiple of the system page size; or .I len was zero; or the specified range was otherwise invalid. -.SS UFFDIO_WRITEPROTECT (Since Linux 5.7) +.SS UFFDIO_WRITEPROTECT +(Since Linux 5.7.) Write-protect or write-unprotect a userfaultfd-registered memory range registered with mode .BR UFFDIO_REGISTER_MODE_WP . -.PP +.P The .I argp argument is a pointer to a .I uffdio_range structure as shown below: -.PP +.P .in +4n .EX struct uffdio_writeprotect { @@ -712,7 +771,7 @@ struct uffdio_writeprotect { }; .EE .in -.PP +.P There are two mode bits that are supported in this structure: .TP .B UFFDIO_WRITEPROTECT_MODE_WP @@ -729,7 +788,7 @@ page-fault resolution after the operation. This can be specified only if .B UFFDIO_WRITEPROTECT_MODE_WP is not specified. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -767,13 +826,13 @@ Encountered a generic fault during processing. Resolve a minor page fault by installing page table entries for existing pages in the page cache. -.PP +.P The .I argp argument is a pointer to a .I uffdio_continue structure as shown below: -.PP +.P .in +4n .EX struct uffdio_continue { @@ -784,7 +843,7 @@ struct uffdio_continue { }; .EE .in -.PP +.P The following value may be bitwise ORed in .I mode to change the behavior of the @@ -793,7 +852,7 @@ operation: .TP .B UFFDIO_CONTINUE_MODE_DONTWAKE Do not wake up the thread that waits for page-fault resolution. -.PP +.P The .I mapped field is used by the kernel @@ -812,7 +871,7 @@ field is output-only; it is not read by the .B UFFDIO_CONTINUE operation. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -832,6 +891,12 @@ does not equal the value that was specified in the .I range.len field. .TP +.B EEXIST +One or more pages were already mapped in the given range. +.TP +.B EFAULT +No existing page could be found in the page cache for the given range. +.TP .B EINVAL Either .I range.start @@ -846,9 +911,6 @@ An invalid bit was specified in the .I mode field. .TP -.B EEXIST -One or more pages were already mapped in the given range. -.TP .B ENOENT The faulting process has changed its virtual memory layout simultaneously with an outstanding @@ -858,14 +920,118 @@ operation. .B ENOMEM Allocating memory needed to setup the page table mappings failed. .TP -.B EFAULT -No existing page could be found in the page cache for the given range. -.TP .B ESRCH The faulting process has exited at the time of a .B UFFDIO_CONTINUE operation. .\" +.SS UFFDIO_POISON +(Since Linux 6.6.) +Mark an address range as "poisoned". +Future accesses to these addresses will raise a +.B SIGBUS +signal. +Unlike +.B MADV_HWPOISON +this works by installing page table entries, +rather than "really" poisoning the underlying physical pages. +This means it only affects this particular address space. +.P +The +.I argp +argument is a pointer to a +.I uffdio_poison +structure as shown below: +.P +.in +4n +.EX +struct uffdio_poison { + struct uffdio_range range; + /* Range to install poison PTE markers in */ + __u64 mode; /* Flags controlling the behavior of poison */ + __s64 updated; /* Number of bytes poisoned, or negated error */ +}; +.EE +.in +.P +The following value may be bitwise ORed in +.I mode +to change the behavior of the +.B UFFDIO_POISON +operation: +.TP +.B UFFDIO_POISON_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution. +.P +The +.I updated +field is used by the kernel +to return the number of bytes that were actually poisoned, +or an error in the same manner as +.BR UFFDIO_COPY . +If the value returned in the +.I updated +field doesn't match the value that was specified in +.IR range.len , +the operation fails with the error +.BR EAGAIN . +The +.I updated +field is output-only; +it is not read by the +.B UFFDIO_POISON +operation. +.P +This +.BR ioctl (2) +operation returns 0 on success. +In this case, +the entire area was poisoned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EAGAIN +The number of bytes mapped +(i.e., the value returned in the +.I updated +field) +does not equal the value that was specified in the +.I range.len +field. +.TP +.B EINVAL +Either +.I range.start +or +.I range.len +was not a multiple of the system page size; or +.I range.len +was zero; or the range specified was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.I mode +field. +.TP +.B EEXIST +One or more pages were already mapped in the given range. +.TP +.B ENOENT +The faulting process has changed its virtual memory layout simultaneously with +an outstanding +.B UFFDIO_POISON +operation. +.TP +.B ENOMEM +Allocating memory for page table entries failed. +.TP +.B ESRCH +The faulting process has exited at the time of a +.B UFFDIO_POISON +operation. +.\" .SH RETURN VALUE See descriptions of the individual operations, above. .SH ERRORS @@ -901,6 +1067,6 @@ See .BR ioctl (2), .BR mmap (2), .BR userfaultfd (2) -.PP +.P .I Documentation/admin\-guide/mm/userfaultfd.rst in the Linux kernel source tree diff --git a/man2/ioperm.2 b/man2/ioperm.2 index dcbad6c..dd62ce5 100644 --- a/man2/ioperm.2 +++ b/man2/ioperm.2 @@ -12,7 +12,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> .\" Added notes on capability requirements .\" -.TH ioperm 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioperm 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioperm \- set port input/output permissions .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/io.h> -.PP +.P .BI "int ioperm(unsigned long " from ", unsigned long " num ", int " turn_on ); .fi .SH DESCRIPTION @@ -38,7 +38,7 @@ If .I turn_on is nonzero, the calling thread must be privileged .RB ( CAP_SYS_RAWIO ). -.PP +.P Before Linux 2.6.8, only the first 0x3ff I/O ports could be specified in this manner. For more ports, the @@ -47,7 +47,7 @@ system call had to be used (with a .I level argument of 3). Since Linux 2.6.8, 65,536 I/O ports can be specified. -.PP +.P Permissions are inherited by the child created by .BR fork (2) (but see NOTES). @@ -55,7 +55,7 @@ Permissions are preserved across .BR execve (2); this is useful for giving port access permissions to unprivileged programs. -.PP +.P This call is mostly for the i386 architecture. On many other architectures it does not exist or will always return an error. diff --git a/man2/iopl.2 b/man2/iopl.2 index 239d206..b2211e2 100644 --- a/man2/iopl.2 +++ b/man2/iopl.2 @@ -10,7 +10,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> .\" Added notes on capability requirements .\" -.TH iopl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH iopl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME iopl \- change I/O privilege level .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/io.h> -.PP +.P .BI "[[deprecated]] int iopl(int " level ); .fi .SH DESCRIPTION @@ -27,10 +27,10 @@ Standard C library changes the I/O privilege level of the calling thread, as specified by the two least significant bits in .IR level . -.PP +.P The I/O privilege level for a normal thread is 0. Permissions are inherited from parents to children. -.PP +.P This call is deprecated, is significantly slower than .BR ioperm (2), and is only provided for older X servers which require @@ -76,7 +76,7 @@ Prior to Linux 5.5 allowed the thread to disable interrupts while running at a higher I/O privilege level. This will probably crash the system, and is not recommended. -.PP +.P Prior to Linux 3.7, on some architectures (such as i386), permissions .I were diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2 index 7770cbc..629d2df 100644 --- a/man2/ioprio_set.2 +++ b/man2/ioprio_set.2 @@ -7,7 +7,7 @@ .\" with various additions by Michael Kerrisk <mtk.manpages@gmail.com> .\" .\" -.TH ioprio_set 2 2023-04-03 "Linux man-pages 6.05.01" +.TH ioprio_set 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioprio_get, ioprio_set \- get/set I/O scheduling class and priority .SH LIBRARY @@ -18,11 +18,11 @@ Standard C library .BR "#include <linux/ioprio.h> " "/* Definition of " IOPRIO_* " constants */" .BR "#include <sys/syscall.h> " "/* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_ioprio_get, int " which ", int " who ); .BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -34,7 +34,7 @@ and .BR ioprio_set () system calls get and set the I/O scheduling class and priority of one or more threads. -.PP +.P The .I which and @@ -67,7 +67,7 @@ is a user ID identifying all of the processes that have a matching real UID. .\" FIXME . Need to document the behavior when 'who" is specified as 0 .\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443 -.PP +.P If .I which is specified as @@ -90,7 +90,7 @@ is the lowest) or if it belongs to the same priority class as the other process but has a higher priority level (a lower priority number means a higher priority level). -.PP +.P The .I ioprio argument given to @@ -130,13 +130,13 @@ Given value), this macro returns its priority .RI ( data ) component. -.PP +.P See the NOTES section for more information on scheduling classes and priorities, as well as the meaning of specifying .I ioprio as 0. -.PP +.P I/O priorities are supported for reads and for synchronous .RB ( O_DIRECT , .BR O_SYNC ) @@ -157,7 +157,7 @@ and On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P On success, .BR ioprio_set () returns 0. @@ -211,12 +211,12 @@ is the one that is returned by .BR gettid (2) or .BR clone (2). -.PP +.P These system calls have an effect only when used in conjunction with an I/O scheduler that supports I/O priorities. As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing (CFQ) I/O scheduler. -.PP +.P If no I/O scheduler has been set for a thread, then by default the I/O priority will follow the CPU nice value .RB ( setpriority (2)). @@ -233,20 +233,20 @@ as 0 can be used to reset to the default I/O scheduling behavior. I/O schedulers are selected on a per-device basis via the special file .IR /sys/block/ device /queue/scheduler . -.PP +.P One can view the current I/O scheduler via the .I /sys filesystem. For example, the following command displays a list of all schedulers currently loaded in the kernel: -.PP +.P .in +4n .EX .RB "$" " cat /sys/block/sda/queue/scheduler" noop anticipatory deadline [cfq] .EE .in -.PP +.P The scheduler surrounded by brackets is the one actually in use for the device .RI ( sda @@ -258,7 +258,7 @@ scheduler for the .I sda device to .IR cfq : -.PP +.P .in +4n .EX .RB "$" " su" @@ -310,7 +310,7 @@ The idle class has no class data. Attention is required when assigning this priority class to a process, since it may become starved if higher priority processes are constantly accessing the disk. -.PP +.P Refer to the kernel source file .I Documentation/block/ioprio.txt for more information on the CFQ I/O Scheduler and an example program. @@ -337,7 +337,7 @@ Up to Linux 2.6.24 also required to set a very low priority .RB ( IOPRIO_CLASS_IDLE ), but since Linux 2.6.25, this is no longer required. -.PP +.P A call to .BR ioprio_set () must follow both rules, or the call will fail with the error @@ -357,6 +357,6 @@ Suitable definitions can be found in .BR open (2), .BR capabilities (7), .BR cgroups (7) -.PP +.P .I Documentation/block/ioprio.txt in the Linux kernel source tree @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> -.TH ipc 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ipc 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ipc \- System V IPC system calls .SH LIBRARY @@ -14,13 +14,13 @@ Standard C library .BR "#include <linux/ipc.h>" " /* Definition of needed constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_ipc, unsigned int " call ", int " first , .BI " unsigned long " second ", unsigned long " third \ ", void *" ptr , .BI " long " fifth ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR ipc (), @@ -33,7 +33,7 @@ for messages, semaphores, and shared memory. .I call determines which IPC function to invoke; the other arguments are passed through to the appropriate call. -.PP +.P User-space programs should call the appropriate functions by their usual names. Only standard library implementors and kernel hackers need to know about .BR ipc (). diff --git a/man2/kcmp.2 b/man2/kcmp.2 index 98a29f1..cfd65df 100644 --- a/man2/kcmp.2 +++ b/man2/kcmp.2 @@ -5,7 +5,7 @@ .\" .\" Kernel commit d97b46a64674a267bc41c9e16132ee2a98c3347d .\" -.TH kcmp 2 2023-05-03 "Linux man-pages 6.05.01" +.TH kcmp 2 2023-10-31 "Linux man-pages 6.7" .SH NAME kcmp \- compare two processes to determine if they share a kernel resource .SH LIBRARY @@ -16,11 +16,11 @@ Standard C library .BR "#include <linux/kcmp.h>" " /* Definition of " KCMP_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_kcmp, pid_t " pid1 ", pid_t " pid2 ", int " type , .BI " unsigned long " idx1 ", unsigned long " idx2 ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR kcmp (), @@ -35,7 +35,7 @@ and .I pid2 share a kernel resource such as virtual memory, file descriptors, and so on. -.PP +.P Permission to employ .BR kcmp () is governed by ptrace access mode @@ -46,7 +46,7 @@ and .IR pid2 ; see .BR ptrace (2). -.PP +.P The .I type argument specifies which resource is to be compared in the two processes. @@ -161,7 +161,7 @@ The argument .I idx2 is a pointer to a structure where the target file is described. This structure has the form: -.PP +.P .in +4n .EX struct kcmp_epoll_slot { @@ -171,7 +171,7 @@ struct kcmp_epoll_slot { }; .EE .in -.PP +.P Within this structure, .I efd is an epoll file descriptor returned from @@ -183,7 +183,7 @@ is a target file offset counted from zero. Several different targets may be registered with the same file descriptor number and setting a specific offset helps to investigate each of them. -.PP +.P Note the .BR kcmp () is not protected against false positives which may occur if @@ -199,7 +199,7 @@ The return value of a successful call to is simply the result of arithmetic comparison of kernel pointers (when the kernel compares resources, it uses their memory addresses). -.PP +.P The easiest way to explain is to consider an example. Suppose that .I v1 @@ -231,11 +231,11 @@ is not equal to .IR v2 , but ordering information is unavailable. .RE -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .BR kcmp () was designed to return values suitable for sorting. This is particularly handy if one needs to compare @@ -291,7 +291,7 @@ does not exist. Linux. .SH HISTORY Linux 3.5. -.PP +.P Before Linux 5.12, this system call is available only if the kernel is configured with .BR CONFIG_CHECKPOINT_RESTORE , @@ -317,7 +317,7 @@ the same open file description. The program tests different cases for the file descriptor pairs, as described in the program output. An example run of the program is as follows: -.PP +.P .in +4n .EX $ \fB./a.out\fP diff --git a/man2/kexec_load.2 b/man2/kexec_load.2 index 604fa1c..499f6ca 100644 --- a/man2/kexec_load.2 +++ b/man2/kexec_load.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH kexec_load 2 2023-03-30 "Linux man-pages 6.05.01" +.TH kexec_load 2 2023-10-31 "Linux man-pages 6.7" .SH NAME kexec_load, kexec_file_load \- load a new kernel for later execution .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .BR "#include <linux/kexec.h>" " /* Definition of " KEXEC_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(SYS_kexec_load, unsigned long " entry , .BI " unsigned long " nr_segments \ ", struct kexec_segment *" segments , @@ -24,7 +24,7 @@ Standard C library .BI " unsigned long " cmdline_len ", const char *" cmdline , .BI " unsigned long " flags ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -34,7 +34,7 @@ The .BR kexec_load () system call loads a new kernel that can be executed later by .BR reboot (2). -.PP +.P The .I flags argument is a bit mask that controls the operation of the call. @@ -66,7 +66,7 @@ This flag is available only if the kernel was configured with and is effective only if .I nr_segments is greater than 0. -.PP +.P The high-order bits (corresponding to the mask 0xffff0000) of .I flags contain the architecture of the to-be-executed kernel. @@ -87,7 +87,7 @@ or one of the following architecture constants and .BR KEXEC_ARCH_MIPS_LE . The architecture must be executable on the CPU of the system. -.PP +.P The .I entry argument is the physical entry address in the kernel image. @@ -102,7 +102,7 @@ The argument is an array of .I kexec_segment structures which define the kernel layout: -.PP +.P .in +4n .EX struct kexec_segment { @@ -113,7 +113,7 @@ struct kexec_segment { }; .EE .in -.PP +.P The kernel image defined by .I segments is copied from the calling process into @@ -154,7 +154,7 @@ If is less than .IR memsz , then the excess bytes in the kernel buffer are zeroed out. -.PP +.P In case of a normal kexec (i.e., the .B KEXEC_ON_CRASH flag is not set), the segment data is loaded in any available memory @@ -163,13 +163,13 @@ and is moved to the final destination at kexec reboot time (e.g., when the command is executed with the .I \-e option). -.PP +.P In case of kexec on panic (i.e., the .B KEXEC_ON_CRASH flag is set), the segment data is loaded to reserved memory at the time of the call, and, after a crash, the kexec mechanism simply passes control to that kernel. -.PP +.P The .BR kexec_load () system call is available only if the kernel was configured with @@ -194,7 +194,7 @@ The .I cmdline_len argument specifies size of the buffer. The last byte in the buffer must be a null byte (\[aq]\e0\[aq]). -.PP +.P The .I flags argument is a bit mask which modifies the behavior of the call. @@ -216,7 +216,7 @@ Specify this flag if no initramfs is being loaded. If this flag is set, the value passed in .I initrd_fd is ignored. -.PP +.P The .BR kexec_file_load () .\" See also http://lwn.net/Articles/603116/ @@ -324,7 +324,7 @@ Linux 3.17. .BR reboot (2), .BR syscall (2), .BR kexec (8) -.PP +.P The kernel source files .I Documentation/kdump/kdump.txt and diff --git a/man2/keyctl.2 b/man2/keyctl.2 index d7bd83d..8f8ec19 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -5,13 +5,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH keyctl 2 2023-05-03 "Linux man-pages 6.05.01" +.TH keyctl 2 2024-02-25 "Linux man-pages 6.7" .SH NAME keyctl \- manipulate the kernel's key management facility .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Linux Key Management Utilities .RI ( libkeyutils ", " \-lkeyutils ); see VERSIONS. @@ -20,12 +20,12 @@ see VERSIONS. .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(SYS_keyctl, int " operation ", unsigned long " arg2 , .BI " unsigned long " arg3 ", unsigned long " arg4 , .BI " unsigned long " arg5 ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR keyctl (), @@ -34,7 +34,7 @@ necessitating the use of .SH DESCRIPTION .BR keyctl () allows user-space programs to perform key manipulation. -.PP +.P The operation performed by .BR keyctl () is determined by the value of the @@ -46,7 +46,7 @@ library (provided by the .I keyutils package) into individual functions (noted below) to permit the compiler to check types. -.PP +.P The permitted values for .I operation are: @@ -847,7 +847,7 @@ the size of that buffer is specified in (cast to .IR size_t ). .IP -The payload may be a NULL pointer and the buffer size may be 0 +The payload may be a null pointer and the buffer size may be 0 if this is supported by the key type (e.g., it is a keyring). .IP The operation may be fail if the payload data is in the wrong format @@ -1415,7 +1415,7 @@ The .I arg2 argument is a pointer to a set of parameters containing serial numbers for three -.I """user""" +.I \[dq]user\[dq] keys used in the Diffie-Hellman calculation, packaged in a structure of the following form: .IP @@ -1653,7 +1653,7 @@ is 0, the required buffer size. .TP All other operations Zero. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -1897,7 +1897,7 @@ was .B KEYCTL_READ and the key type does not support reading (e.g., the type is -.IR """login""" ). +.IR \[dq]login\[dq] ). .TP .B EOPNOTSUPP .I operation @@ -1968,7 +1968,7 @@ program provided by the package. For informational purposes, the program records various information in a log file. -.PP +.P As described in .BR request_key (2), the @@ -1978,7 +1978,7 @@ describe a key that is to be instantiated. The example program fetches and logs these arguments. The program assumes authority to instantiate the requested key, and then instantiates that key. -.PP +.P The following shell session demonstrates the use of this program. In the session, we compile the program and then use it to temporarily replace the standard @@ -1991,7 +1991,7 @@ While our example program is installed, we use the example program shown in .BR request_key (2) to request a key. -.PP +.P .in +4n .EX $ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP @@ -2002,10 +2002,10 @@ Key ID is 20d035bf $ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP .EE .in -.PP +.P Looking at the log file created by this program, we can see the command-line arguments supplied to our example program: -.PP +.P .in +4n .EX $ \fBcat /tmp/key_instantiate.log\fP @@ -2027,7 +2027,7 @@ Destination keyring: 256e6a6 Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf .EE .in -.PP +.P The last few lines of the above output show that the example program was able to fetch: .IP \[bu] 3 @@ -2048,7 +2048,7 @@ the description of the authorization key, where we can see that the name of the authorization key matches the ID of the key that is to be instantiated .RI ( 20d035bf ). -.PP +.P The example program in .BR request_key (2) specified the destination keyring as @@ -2062,7 +2062,7 @@ we can also see the newly created key with the name .I mykey and ID .IR 20d035bf . -.PP +.P .in +4n .EX $ \fBcat /proc/keys | egrep \[aq]mykey|256e6a6\[aq]\fP @@ -2290,7 +2290,7 @@ main(int argc, char *argv[]) .BR user_namespaces (7), .BR user\-session\-keyring (7), .BR request\-key (8) -.PP +.P The kernel source files under .I Documentation/security/keys/ (or, before Linux 4.13, in the file diff --git a/man2/kill.2 b/man2/kill.2 index d0a2e6f..1260ee0 100644 --- a/man2/kill.2 +++ b/man2/kill.2 @@ -21,7 +21,7 @@ .\" Modified 2004-06-24 by aeb .\" Modified, 2004-11-30, after idea from emmanuel.colbus@ensimag.imag.fr .\" -.TH kill 2 2023-03-30 "Linux man-pages 6.05.01" +.TH kill 2 2023-10-31 "Linux man-pages 6.7" .SH NAME kill \- send signal to a process .SH LIBRARY @@ -30,15 +30,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <signal.h> -.PP +.P .BI "int kill(pid_t " pid ", int " sig ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR kill (): .nf _POSIX_C_SOURCE @@ -48,25 +48,25 @@ The .BR kill () system call can be used to send any signal to any process group or process. -.PP +.P If \fIpid\fP is positive, then signal \fIsig\fP is sent to the process with the ID specified by \fIpid\fP. -.PP +.P If \fIpid\fP equals 0, then \fIsig\fP is sent to every process in the process group of the calling process. -.PP +.P If \fIpid\fP equals \-1, then \fIsig\fP is sent to every process for which the calling process has permission to send signals, except for process 1 (\fIinit\fP), but see below. -.PP +.P If \fIpid\fP is less than \-1, then \fIsig\fP is sent to every process in the process group whose ID is \fI\-pid\fP. -.PP +.P If \fIsig\fP is 0, then no signal is sent, but existence and permission checks are still performed; this can be used to check for the existence of a process ID or process group ID that the caller is permitted to signal. -.PP +.P For a process to have permission to send a signal, it must either be privileged (under Linux: have the .B CAP_KILL @@ -125,13 +125,13 @@ process, are those for which has explicitly installed signal handlers. This is done to assure the system is not brought down accidentally. -.PP +.P POSIX.1 requires that \fIkill(\-1,sig)\fP send \fIsig\fP to all processes that the calling process may send signals to, except possibly for some implementation-defined system processes. Linux allows a process to signal itself, but on Linux the call \fIkill(\-1,sig)\fP does not signal the calling process. -.PP +.P POSIX.1 requires that if a process sends a signal to itself, and the sending thread does not have the signal blocked, and no other thread diff --git a/man2/landlock_add_rule.2 b/man2/landlock_add_rule.2 index 28d5417..2858fa3 100644 --- a/man2/landlock_add_rule.2 +++ b/man2/landlock_add_rule.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH landlock_add_rule 2 2023-07-08 "Linux man-pages 6.05.01" +.TH landlock_add_rule 2 2023-10-31 "Linux man-pages 6.7" .SH NAME landlock_add_rule \- add a new Landlock rule to a ruleset .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" -.PP +.P .BI "int syscall(SYS_landlock_add_rule, int " ruleset_fd , .BI " enum landlock_rule_type " rule_type , .BI " const void *" rule_attr ", uint32_t " flags ); @@ -32,11 +32,11 @@ created with See .BR landlock (7) for a global overview. -.PP +.P .I ruleset_fd is a Landlock ruleset file descriptor obtained with .BR landlock_create_ruleset (2). -.PP +.P .I rule_type identifies the structure type pointed to by .IR rule_attr . @@ -72,7 +72,7 @@ is an opened file descriptor, preferably with the flag, which identifies the parent directory of the file hierarchy or just a file. -.PP +.P .I flags must be 0. .SH RETURN VALUE diff --git a/man2/landlock_create_ruleset.2 b/man2/landlock_create_ruleset.2 index faadb57..0c69027 100644 --- a/man2/landlock_create_ruleset.2 +++ b/man2/landlock_create_ruleset.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH landlock_create_ruleset 2 2023-03-30 "Linux man-pages 6.05.01" +.TH landlock_create_ruleset 2 2023-10-31 "Linux man-pages 6.7" .SH NAME landlock_create_ruleset \- create a new Landlock ruleset .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" -.PP +.P .B int syscall(SYS_landlock_create_ruleset, .BI " const struct landlock_ruleset_attr *" attr , .BI " size_t " size " , uint32_t " flags ); @@ -31,7 +31,7 @@ and See .BR landlock (7) for a global overview. -.PP +.P .I attr specifies the properties of the new ruleset. It points to the following structure: @@ -53,12 +53,12 @@ in .BR landlock (7)). This enables simply restricting ambient rights (e.g., global filesystem access) and is needed for compatibility reasons. -.PP +.P .I size must be specified as .I sizeof(struct landlock_ruleset_attr) for compatibility reasons. -.PP +.P .I flags must be 0 if .I attr diff --git a/man2/landlock_restrict_self.2 b/man2/landlock_restrict_self.2 index f02c3a1..c82181b 100644 --- a/man2/landlock_restrict_self.2 +++ b/man2/landlock_restrict_self.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH landlock_restrict_self 2 2023-03-30 "Linux man-pages 6.05.01" +.TH landlock_restrict_self 2 2023-10-31 "Linux man-pages 6.7" .SH NAME landlock_restrict_self \- enforce a Landlock ruleset .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" -.PP +.P .BI "int syscall(SYS_landlock_restrict_self, int " ruleset_fd , .BI " uint32_t " flags ); .SH DESCRIPTION @@ -24,7 +24,7 @@ system call enables enforcing this ruleset on the calling thread. See .BR landlock (7) for a global overview. -.PP +.P A thread can be restricted with multiple rulesets that are then composed together to form the thread's Landlock domain. This can be seen as a stack of rulesets but @@ -43,7 +43,7 @@ composed rulesets limit. Instead, developers are encouraged to build a tailored ruleset thanks to multiple calls to .BR landlock_add_rule (2). -.PP +.P In order to enforce a ruleset, either the caller must have the .B CAP_SYS_ADMIN capability in its user namespace, or the thread must already have the @@ -59,13 +59,13 @@ the thread must make the following call: .EX prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0); .EE -.PP +.P .I ruleset_fd is a Landlock ruleset file descriptor obtained with .BR landlock_create_ruleset (2) and fully populated with a set of calls to .BR landlock_add_rule (2). -.PP +.P .I flags must be 0. .SH RETURN VALUE diff --git a/man2/link.2 b/man2/link.2 index 1533409..74437a0 100644 --- a/man2/link.2 +++ b/man2/link.2 @@ -9,7 +9,7 @@ .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2 .\" -.TH link 2 2023-03-30 "Linux man-pages 6.05.01" +.TH link 2 2023-10-31 "Linux man-pages 6.7" .SH NAME link, linkat \- make a new name for a file .SH LIBRARY @@ -18,21 +18,21 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int link(const char *" oldpath ", const char *" newpath ); -.PP +.P .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int linkat(int " olddirfd ", const char *" oldpath , .BI " int " newdirfd ", const char *" newpath ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR linkat (): .nf Since glibc 2.10: @@ -43,13 +43,13 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION .BR link () creates a new link (also known as a hard link) to an existing file. -.PP +.P If .I newpath exists, it will .I not be overwritten. -.PP +.P This new name may be used exactly as the old one for any operation; both names refer to the same file (and so have the same permissions and ownership) and it is impossible to tell which name was the @@ -60,7 +60,7 @@ The system call operates in exactly the same way as .BR link (), except for the differences described here. -.PP +.P If the pathname given in .I oldpath is relative, then it is interpreted relative to the directory @@ -70,7 +70,7 @@ referred to by the file descriptor the calling process, as is done by .BR link () for a relative pathname). -.PP +.P If .I oldpath is relative and @@ -82,13 +82,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR link ()). -.PP +.P If .I oldpath is absolute, then .I olddirfd is ignored. -.PP +.P The interpretation of .I newpath is as for @@ -96,7 +96,7 @@ is as for except that a relative pathname is interpreted relative to the directory referred to by the file descriptor .IR newdirfd . -.PP +.P The following values can be bitwise ORed in .IR flags : .TP @@ -152,11 +152,11 @@ linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd, newname, AT_SYMLINK_FOLLOW); .EE .in -.PP +.P Before Linux 2.6.18, the .I flags argument was unused, and had to be specified as 0. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -260,7 +260,7 @@ are not on the same mounted filesystem. .BR link () does not work across different mounts, even if the same filesystem is mounted on both.) -.PP +.P The following additional errors can occur for .BR linkat (): .TP diff --git a/man2/listen.2 b/man2/listen.2 index 9512366..94f0b2c 100644 --- a/man2/listen.2 +++ b/man2/listen.2 @@ -14,7 +14,7 @@ .\" Modified 11 May 2001 by Sam Varshavchik <mrsam@courier-mta.com> .\" .\" -.TH listen 2 2023-03-30 "Linux man-pages 6.05.01" +.TH listen 2 2023-10-31 "Linux man-pages 6.7" .SH NAME listen \- listen for connections on a socket .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int listen(int " sockfd ", int " backlog ); .fi .SH DESCRIPTION @@ -33,14 +33,14 @@ marks the socket referred to by as a passive socket, that is, as a socket that will be used to accept incoming connection requests using .BR accept (2). -.PP +.P The .I sockfd argument is a file descriptor that refers to a socket of type .B SOCK_STREAM or .BR SOCK_SEQPACKET . -.PP +.P The .I backlog argument defines the maximum length @@ -114,7 +114,7 @@ connections are specified with Connections are accepted with .BR accept (2). .RE -.PP +.P The behavior of the .I backlog argument on TCP sockets changed with Linux 2.2. @@ -130,7 +130,7 @@ length and this setting is ignored. See .BR tcp (7) for more information. -.PP +.P If the .I backlog argument is greater than the value in diff --git a/man2/listxattr.2 b/man2/listxattr.2 index 58f5ce0..71a8e53 100644 --- a/man2/listxattr.2 +++ b/man2/listxattr.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH listxattr 2 2023-05-03 "Linux man-pages 6.05.01" +.TH listxattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME listxattr, llistxattr, flistxattr \- list extended attribute names .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/xattr.h> -.PP +.P .BI "ssize_t listxattr(const char *" path ", char *_Nullable " list \ ", size_t " size ); .BI "ssize_t llistxattr(const char *" path ", char *_Nullable " list \ @@ -30,7 +30,7 @@ with all inodes in the system (i.e., the data). A complete overview of extended attributes concepts can be found in .BR xattr (7). -.PP +.P .BR listxattr () retrieves the list of extended attribute names associated with the given @@ -46,14 +46,14 @@ have access may be omitted from the list. The length of the attribute name .I list is returned. -.PP +.P .BR llistxattr () is identical to .BR listxattr (), except in the case of a symbolic link, where the list of names of extended attributes associated with the link itself is retrieved, not the file that it refers to. -.PP +.P .BR flistxattr () is identical to .BR listxattr (), @@ -63,13 +63,13 @@ only the open file referred to by .BR open (2)) is interrogated in place of .IR path . -.PP +.P A single extended attribute .I name is a null-terminated string. The name includes a namespace prefix; there may be several, disjoint namespaces associated with an individual inode. -.PP +.P If .I size is specified as zero, these calls return the current size of the @@ -88,18 +88,18 @@ The of names is returned as an unordered array of null-terminated character strings (attribute names are separated by null bytes (\[aq]\e0\[aq])), like this: -.PP +.P .in +4n .EX user.name1\e0system.name1\e0user.name2\e0 .EE .in -.PP +.P Filesystems that implement POSIX ACLs using extended attributes might return a .I list like this: -.PP +.P .in +4n .EX system.posix_acl_access\e0system.posix_acl_default\e0 @@ -129,7 +129,7 @@ The of the .I list buffer is too small to hold the result. -.PP +.P In addition, the errors documented in .BR stat (2) can also occur. @@ -160,7 +160,7 @@ and .BR getxattr (2). For the file whose pathname is provided as a command-line argument, it lists all extended file attributes and their values. -.PP +.P To keep the code simple, the program assumes that attribute keys and values are constant during the execution of the program. A production program should expect and handle changes during @@ -177,7 +177,7 @@ with a larger buffer each time it fails with the error Calls to .BR getxattr (2) could be handled similarly. -.PP +.P The following output was recorded by first creating a file, setting some extended file attributes, and then listing the attributes with the example program. diff --git a/man2/llseek.2 b/man2/llseek.2 index 64de504..3ac742f 100644 --- a/man2/llseek.2 +++ b/man2/llseek.2 @@ -6,7 +6,7 @@ .\" .\" Modified Thu Oct 31 15:16:23 1996 by Eric S. Raymond <esr@thyrsus.com> .\" -.TH _llseek 2 2023-03-30 "Linux man-pages 6.05.01" +.TH _llseek 2 2023-10-31 "Linux man-pages 6.7" .SH NAME _llseek \- reposition read/write file offset .SH LIBRARY @@ -16,12 +16,12 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS__llseek, unsigned int " fd ", unsigned long " offset_high , .BI " unsigned long " offset_low ", loff_t *" result , .BI " unsigned int " whence ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR _llseek (), @@ -32,7 +32,7 @@ Note: for information about the .BR llseek (3) library function, see .BR lseek64 (3). -.PP +.P The .BR _llseek () system call repositions the offset of the open file description associated @@ -41,7 +41,7 @@ with the file descriptor to the value .IP (offset_high << 32) | offset_low -.PP +.P This new offset is a byte offset relative to the beginning of the file, the current file offset, or the end of the file, depending on whether @@ -52,13 +52,13 @@ is or .BR SEEK_END , respectively. -.PP +.P The new file offset is returned in the argument .IR result . The type .I loff_t is a 64-bit signed type. -.PP +.P This system call exists on various 32-bit platforms to support seeking to large file offsets. .SH RETURN VALUE diff --git a/man2/lookup_dcookie.2 b/man2/lookup_dcookie.2 index 4543e45..006afe2 100644 --- a/man2/lookup_dcookie.2 +++ b/man2/lookup_dcookie.2 @@ -4,7 +4,7 @@ .\" .\" Modified 2004-06-17 Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH lookup_dcookie 2 2023-03-30 "Linux man-pages 6.05.01" +.TH lookup_dcookie 2 2023-10-31 "Linux man-pages 6.7" .SH NAME lookup_dcookie \- return a directory entry's path .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_lookup_dcookie, uint64_t " cookie ", char *" buffer , .BI " size_t " len ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR lookup_dcookie (), @@ -30,7 +30,7 @@ Look up the full path of the directory entry specified by the value The cookie is an opaque identifier uniquely identifying a particular directory entry. The buffer given is filled in with the full path of the directory entry. -.PP +.P For .BR lookup_dcookie () to return successfully, @@ -69,7 +69,7 @@ The buffer was not large enough to hold the path of the directory entry. Linux. .SH HISTORY Linux 2.5.43. -.PP +.P The .B ENAMETOOLONG error was added in Linux 2.5.70. @@ -79,7 +79,7 @@ is a special-purpose system call, currently used only by the .BR oprofile (1) profiler. It relies on a kernel driver to register cookies for directory entries. -.PP +.P The path returned may be suffixed by the string " (deleted)" if the directory entry has been removed. .SH SEE ALSO diff --git a/man2/lseek.2 b/man2/lseek.2 index 7ef7930..93b3f6d 100644 --- a/man2/lseek.2 +++ b/man2/lseek.2 @@ -15,7 +15,7 @@ .\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl> .\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE .\" -.TH lseek 2 2023-03-30 "Linux man-pages 6.05.01" +.TH lseek 2 2023-10-31 "Linux man-pages 6.7" .SH NAME lseek \- reposition read/write file offset .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); .fi .SH DESCRIPTION @@ -52,7 +52,7 @@ bytes. The file offset is set to the size of the file plus .I offset bytes. -.PP +.P .BR lseek () allows the file offset to be set beyond the end of the file (but this does not change the size of the file). @@ -87,19 +87,19 @@ If there is no hole past .IR offset , then the file offset is adjusted to the end of the file (i.e., there is an implicit hole at the end of any file). -.PP +.P In both of the above cases, .BR lseek () fails if .I offset points past the end of the file. -.PP +.P These operations allow applications to map holes in a sparsely allocated file. This can be useful for applications such as file backup tools, which can save space when creating backups and preserve holes, if they have a mechanism for discovering holes. -.PP +.P For the purposes of these operations, a hole is a sequence of zeros that (normally) has not been allocated in the underlying file storage. However, a filesystem is not obliged to report holes, @@ -122,7 +122,7 @@ it can be considered to consist of data that is a sequence of zeros). .\" https://lkml.org/lkml/2011/4/22/79 .\" http://lwn.net/Articles/440255/ .\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data -.PP +.P The .B _GNU_SOURCE feature test macro must be defined in order to obtain the definitions of @@ -131,7 +131,7 @@ and .B SEEK_HOLE from .IR <unistd.h> . -.PP +.P The .B SEEK_HOLE and @@ -216,7 +216,7 @@ on a terminal device fails with the error POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P .B SEEK_DATA and .B SEEK_HOLE @@ -229,7 +229,7 @@ See .BR open (2) for a discussion of the relationship between file descriptors, open file descriptions, and files. -.PP +.P If the .B O_APPEND file status flag is set on the open file description, @@ -238,7 +238,7 @@ then a .I always moves the file offset to the end of the file, regardless of the use of .BR lseek (). -.PP +.P Some devices are incapable of seeking and POSIX does not specify which devices must support .BR lseek (). diff --git a/man2/madvise.2 b/man2/madvise.2 index 5782574..c30ec4c 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -12,7 +12,7 @@ .\" 2011-09-18, Doug Goldstein <cardoe@cardoe.com> .\" Document MADV_HUGEPAGE and MADV_NOHUGEPAGE .\" -.TH madvise 2 2023-04-03 "Linux man-pages 6.05.01" +.TH madvise 2 2023-10-31 "Linux man-pages 6.7" .SH NAME madvise \- give advice about use of memory .SH LIBRARY @@ -21,15 +21,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/mman.h> -.PP +.P .BI "int madvise(void " addr [. length "], size_t " length ", int " advice ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR madvise (): .nf Since glibc 2.19: @@ -54,7 +54,7 @@ The value of is rounded up to a multiple of page size. In most cases, the goal of such advice is to improve system or application performance. -.PP +.P Initially, the system call supported a set of "conventional" .I advice values, which are also available on several other implementations. @@ -86,7 +86,7 @@ values listed here have analogs in the POSIX-specified .BR posix_madvise (3) function, and the values have the same meanings, with the exception of .BR MADV_DONTNEED . -.PP +.P The advice is indicated in the .I advice argument, which is one of the following: @@ -845,7 +845,7 @@ Other implementations typically implement at least the flags listed above under .IR "Conventional advice flags" , albeit with some variation in semantics. -.PP +.P POSIX.1-2001 describes .BR posix_madvise (3) with constants @@ -868,7 +868,7 @@ that are not mapped, the Linux version of ignores them and applies the call to the rest (but returns .B ENOMEM from the system call, as it should). -.PP +.P .I madvise(0,\ 0,\ advice) will return zero iff .I advice @@ -877,7 +877,7 @@ is supported by the kernel and can be relied on to probe for support. None. .SH HISTORY First appeared in 4.4BSD. -.PP +.P Since Linux 3.18, .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb support for this system call is optional, diff --git a/man2/mbind.2 b/man2/mbind.2 index 064b8a1..4b43aca 100644 --- a/man2/mbind.2 +++ b/man2/mbind.2 @@ -15,7 +15,7 @@ .\" Author: Lee Schermerhorn <lee.schermerhorn@hp.com> .\" Date: Thu Oct 25 14:16:32 2012 +0200 .\" -.TH mbind 2 2023-07-16 "Linux man-pages 6.05.01" +.TH mbind 2 2023-12-09 "Linux man-pages 6.7" .SH NAME mbind \- set memory policy for a memory range .SH LIBRARY @@ -24,7 +24,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .nf .B "#include <numaif.h>" -.PP +.P .BI "long mbind(void " addr [. len "], unsigned long " len ", int " mode , .BI " const unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)" .B " / ULONG_WIDTH]," @@ -40,7 +40,7 @@ and continuing for .I len bytes. The memory policy defines from which node memory is allocated. -.PP +.P If the memory range specified by the .IR addr " and " len arguments includes an "anonymous" region of memory\[em]that is @@ -62,7 +62,7 @@ an initial read access will allocate pages according to the memory policy of the thread that causes the page to be allocated. This may not be the thread that called .BR mbind (). -.PP +.P The specified policy will be ignored for any .B MAP_SHARED mappings in the specified memory range. @@ -70,7 +70,7 @@ Rather the pages will be allocated according to the memory policy of the thread that caused the page to be allocated. Again, this may not be the thread that called .BR mbind (). -.PP +.P If the specified memory range includes a shared memory region created using the .BR shmget (2) @@ -87,7 +87,7 @@ the huge pages will be allocated according to the policy specified only if the page allocation is caused by the process that calls .BR mbind () for that region. -.PP +.P By default, .BR mbind () has an effect only for new allocations; if the pages inside @@ -98,7 +98,7 @@ This default behavior may be overridden by the and .B MPOL_MF_MOVE_ALL flags described below. -.PP +.P The .I mode argument must specify one of @@ -115,7 +115,7 @@ require the caller to specify the node or nodes to which the mode applies, via the .I nodemask argument. -.PP +.P The .I mode argument may also include an optional @@ -124,6 +124,23 @@ The supported .I "mode flags" are: .TP +.BR MPOL_F_NUMA_BALANCING " (since Linux 5.15)" +.\" commit bda420b985054a3badafef23807c4b4fa38a3dff +.\" commit 6d2aec9e123bb9c49cb5c7fc654f25f81e688e8c +When +.I mode +is +.BR MPOL_BIND , +enable the kernel NUMA balancing for the task if it is supported by the kernel. +If the flag isn't supported by the kernel, or is used with +.I mode +other than +.BR MPOL_BIND , +\-1 is returned and +.I errno +is set to +.BR EINVAL . +.TP .BR MPOL_F_STATIC_NODES " (since Linux-2.6.26)" A nonempty .I nodemask @@ -139,7 +156,7 @@ A nonempty .I nodemask specifies node IDs that are relative to the set of node IDs allowed by the thread's current cpuset. -.PP +.P .I nodemask points to a bit mask of nodes containing up to .I maxnode @@ -167,7 +184,7 @@ allowed by the thread's current cpuset context .B MPOL_F_STATIC_NODES mode flag is specified), and contains memory. -.PP +.P The .I mode argument must include one of the following values: @@ -265,7 +282,7 @@ By contrast, reverts to the memory policy of the thread (which may be set via .BR set_mempolicy (2)); that policy may be something other than "local allocation". -.PP +.P If .B MPOL_MF_STRICT is passed in @@ -281,7 +298,7 @@ if the existing pages in the memory range don't follow the policy. .\" --Lee Schermerhorn .\" In Linux 2.6.16 or later the kernel will also try to move pages .\" to the requested node with this flag. -.PP +.P If .B MPOL_MF_MOVE is specified in @@ -299,7 +316,7 @@ If the policy was specified, pages already residing on the specified nodes will not be moved such that they are interleaved. -.PP +.P If .B MPOL_MF_MOVE_ALL is passed in @@ -417,16 +434,16 @@ privilege. Linux. .SH HISTORY Linux 2.6.7. -.PP +.P Support for huge page policy was added with Linux 2.6.16. For interleave policy to be effective on huge page mappings the policied memory needs to be tens of megabytes or larger. -.PP +.P Before Linux 5.7. .\" commit dcf1763546d76c372f3136c8d6b2b6e77f140cf0 .B MPOL_MF_STRICT was ignored on huge page mappings. -.PP +.P .B MPOL_MF_MOVE and .B MPOL_MF_MOVE_ALL @@ -434,12 +451,12 @@ are available only on Linux 2.6.16 and later. .SH NOTES For information on library support, see .BR numa (7). -.PP +.P NUMA policy is not supported on a memory-mapped file range that was mapped with the .B MAP_SHARED flag. -.PP +.P The .B MPOL_DEFAULT mode can have different effects for diff --git a/man2/membarrier.2 b/man2/membarrier.2 index f118fd0..ce5a9de 100644 --- a/man2/membarrier.2 +++ b/man2/membarrier.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH membarrier 2 2023-05-03 "Linux man-pages 6.05.01" +.TH membarrier 2 2023-10-31 "Linux man-pages 6.7" .SH NAME membarrier \- issue memory barriers on a set of threads .SH LIBRARY @@ -11,16 +11,16 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.PP +.P .BR "#include <linux/membarrier.h>" \ " /* Definition of " MEMBARRIER_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_membarrier, int " cmd ", unsigned int " flags \ ", int " cpu_id ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR membarrier (), @@ -36,12 +36,12 @@ effectively is .I not as simple as replacing memory barriers with this system call, but requires understanding of the details below. -.PP +.P Use of memory barriers needs to be done taking into account that a memory barrier always needs to be either matched with its memory barrier counterparts, or that the architecture's memory model doesn't require the matching barriers. -.PP +.P There are cases where one side of the matching barriers (which we will refer to as "fast side") is executed much more often than the other (which we will refer to as "slow side"). @@ -50,22 +50,22 @@ This is a prime target for the use of The key idea is to replace, for these matching barriers, the fast-side memory barriers by simple compiler barriers, for example: -.PP +.P .in +4n .EX asm volatile ("" : : : "memory") .EE .in -.PP +.P and replace the slow-side memory barriers by calls to .BR membarrier (). -.PP +.P This will add overhead to the slow side, and remove overhead from the fast side, thus resulting in an overall performance increase as long as the slow side is infrequent enough that the overhead of the .BR membarrier () calls does not outweigh the performance gain on the fast side. -.PP +.P The .I cmd argument is one of the following: @@ -183,7 +183,7 @@ Register the process's intent to use This is an alias for .B MEMBARRIER_CMD_GLOBAL that exists for header backward compatibility. -.PP +.P The .I flags argument must be specified as 0 unless the command is @@ -192,7 +192,7 @@ in which case .I flags can be either 0 or .BR MEMBARRIER_CMD_FLAG_CPU . -.PP +.P The .I cpu_id argument is ignored unless @@ -201,11 +201,11 @@ is .BR MEMBARRIER_CMD_FLAG_CPU , in which case it must specify the CPU targeted by this membarrier command. -.PP +.P All memory accesses performed in program order from each targeted thread are guaranteed to be ordered with respect to .BR membarrier (). -.PP +.P If we use the semantic .I barrier() to represent a compiler barrier forcing memory @@ -219,7 +219,7 @@ each pairing of and .IR smp_mb() . The pair ordering is detailed as (O: ordered, X: not ordered): -.PP +.P .RS .TS l c c c. @@ -246,7 +246,7 @@ On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P For a given command, with .I flags set to 0, this system call is @@ -284,9 +284,9 @@ commands. Linux. .SH HISTORY Linux 4.3. -.PP +.P Before Linux 5.10, the prototype was: -.PP +.P .in +4n .EX .BI "int membarrier(int " cmd ", int " flags ); @@ -301,10 +301,10 @@ matching barriers on other cores. For instance, a load fence can order loads prior to and following that fence with respect to stores ordered by store fences. -.PP +.P Program order is the order in which instructions are ordered in the program assembly code. -.PP +.P Examples where .BR membarrier () can be useful include implementations @@ -314,7 +314,7 @@ Assuming a multithreaded application where "fast_path()" is executed very frequently, and where "slow_path()" is executed infrequently, the following code (x86) can be transformed using .BR membarrier (): -.PP +.P .in +4n .\" SRC BEGIN (membarrier.c) .EX @@ -365,11 +365,11 @@ main(void) .EE .\" SRC END .in -.PP +.P The code above transformed to use .BR membarrier () becomes: -.PP +.P .in +4n .EX #define _GNU_SOURCE diff --git a/man2/memfd_create.2 b/man2/memfd_create.2 index fb18abc..c7cf859 100644 --- a/man2/memfd_create.2 +++ b/man2/memfd_create.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH memfd_create 2 2023-05-03 "Linux man-pages 6.05.01" +.TH memfd_create 2 2023-10-31 "Linux man-pages 6.7" .SH NAME memfd_create \- create an anonymous file .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sys/mman.h> -.PP +.P .BI "int memfd_create(const char *" name ", unsigned int " flags ");" .fi .SH DESCRIPTION @@ -39,14 +39,14 @@ memory allocations such as those allocated using with the .B MAP_ANONYMOUS flag. -.PP +.P The initial size of the file is set to 0. Following the call, the file size should be set using .BR ftruncate (2). (Alternatively, the file may be populated by calls to .BR write (2) or similar.) -.PP +.P The name supplied in .I name is used as a filename and will be displayed @@ -57,7 +57,7 @@ The displayed name is always prefixed with and serves only for debugging purposes. Names do not affect the behavior of the file descriptor, and as such multiple files can have the same name without any side effects. -.PP +.P The following values may be bitwise ORed in .I flags to change the behavior of @@ -105,7 +105,11 @@ in .I flags is supported since Linux 4.16. .TP -.BR MFD_HUGE_2MB ", " MFD_HUGE_1GB ", " "..." +.B MFD_HUGE_2MB +.TQ +.B MFD_HUGE_1GB +.TQ +\&.\|.\|. Used in conjunction with .B MFD_HUGETLB to select alternative hugetlb page sizes (respectively, 2\ MB, 1\ GB, ...) @@ -117,11 +121,11 @@ huge page sizes are included in the header file For details on encoding huge page sizes not included in the header file, see the discussion of the similarly named constants in .BR mmap (2). -.PP +.P Unused bits in .I flags must be 0. -.PP +.P As its return value, .BR memfd_create () returns a new file descriptor that can be used to refer to the file. @@ -130,7 +134,7 @@ This file descriptor is opened for both reading and writing and .B O_LARGEFILE is set for the file descriptor. -.PP +.P With respect to .BR fork (2) and @@ -215,7 +219,7 @@ The primary purpose of is to create files and associated file descriptors that are used with the file-sealing APIs provided by .BR fcntl (2). -.PP +.P The .BR memfd_create () system call also has uses without file sealing @@ -247,13 +251,13 @@ location in the shared memory region. (Dealing with this possibility necessitates the use of a handler for the .B SIGBUS signal.) -.PP +.P Dealing with untrusted peers imposes extra complexity on code that employs shared memory. Memory sealing enables that extra complexity to be eliminated, by allowing a process to operate secure in the knowledge that its peer can't modify the shared memory in an undesired fashion. -.PP +.P An example of the usage of the sealing mechanism is as follows: .IP (1) 5 The first process creates a @@ -342,7 +346,7 @@ seal has not yet been applied). Below are shown two example programs that demonstrate the use of .BR memfd_create () and the file sealing API. -.PP +.P The first program, .IR t_memfd_create.c , creates a @@ -357,18 +361,18 @@ The first argument is the name to associate with the file, the second argument is the size to be set for the file, and the optional third argument is a string of characters that specify seals to be set on the file. -.PP +.P The second program, .IR t_get_seals.c , can be used to open an existing file that was created via .BR memfd_create () and inspect the set of seals that have been applied to that file. -.PP +.P The following shell session demonstrates the use of these programs. First we create a .BR tmpfs (5) file and set some seals on it: -.PP +.P .in +4n .EX $ \fB./t_memfd_create my_memfd_file 4096 sw &\fP @@ -376,7 +380,7 @@ $ \fB./t_memfd_create my_memfd_file 4096 sw &\fP PID: 11775; fd: 3; /proc/11775/fd/3 .EE .in -.PP +.P At this point, the .I t_memfd_create program continues to run in the background. @@ -392,7 +396,7 @@ Using that pathname, we inspect the content of the symbolic link, and use our .I t_get_seals program to view the seals that have been placed on the file: -.PP +.P .in +4n .EX $ \fBreadlink /proc/11775/fd/3\fP diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2 index fcc39f6..8b4fb48 100644 --- a/man2/memfd_secret.2 +++ b/man2/memfd_secret.2 @@ -7,7 +7,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH memfd_secret 2 2023-03-30 "Linux man-pages 6.05.01" +.TH memfd_secret 2 2023-10-31 "Linux man-pages 6.7" .SH NAME memfd_secret \- create an anonymous RAM-based file to access secret memory regions @@ -16,13 +16,13 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.PP +.P .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_memfd_secret, unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR memfd_secret (), @@ -40,7 +40,7 @@ it is automatically released. The initial size of the file is set to 0. Following the call, the file size should be set using .BR ftruncate (2). -.PP +.P The memory areas backing the file created with .BR memfd_secret (2) are visible only to the processes that have access to the file descriptor. @@ -50,7 +50,7 @@ map the corresponding physical memory. (Thus, the pages in the region can't be accessed by the kernel itself, so that, for example, pointers to the region can't be passed to system calls.) -.PP +.P The following values may be bitwise ORed in .I flags to control the behavior of @@ -64,7 +64,7 @@ See the description of the .B O_CLOEXEC flag in .BR open (2) -.PP +.P As its return value, .BR memfd_secret () returns a new file descriptor that refers to an anonymous file. @@ -73,7 +73,7 @@ This file descriptor is opened for both reading and writing and .B O_LARGEFILE is set for the file descriptor. -.PP +.P With respect to .BR fork (2) and @@ -86,7 +86,7 @@ and refers to the same file. The file descriptor is preserved across .BR execve (2), unless the close-on-exec flag has been set. -.PP +.P The memory region is locked into memory in the same way as with .BR mlock (2), so that it will never be written into swap, @@ -147,7 +147,7 @@ memory ranges backed by .BR memfd_secret () in any circumstances, but nevertheless, it is much harder to exfiltrate data from these regions. -.PP +.P .BR memfd_secret () provides the following protections: .IP \[bu] 3 @@ -181,14 +181,14 @@ either walk the page tables and create new ones, or spawn a new privileged user-space process to perform secrets exfiltration using .BR ptrace (2). -.PP +.P The way .BR memfd_secret () allocates and locks the memory may impact overall system performance, therefore the system call is disabled by default and only available if the system administrator turned it on using "secretmem.enable=y" kernel parameter. -.PP +.P To prevent potential data leaks of memory regions backed by .BR memfd_secret () from a hybernation image, diff --git a/man2/migrate_pages.2 b/man2/migrate_pages.2 index 177f463..8f2ee8e 100644 --- a/man2/migrate_pages.2 +++ b/man2/migrate_pages.2 @@ -6,7 +6,7 @@ .\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc. .\" Christoph Lameter .\" -.TH migrate_pages 2 2023-07-15 "Linux man-pages 6.05.01" +.TH migrate_pages 2 2023-10-31 "Linux man-pages 6.7" .SH NAME migrate_pages \- move all pages in a process to another set of nodes .SH LIBRARY @@ -15,7 +15,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .nf .B #include <numaif.h> -.PP +.P .BI "long migrate_pages(int " pid ", unsigned long " maxnode, .BI " const unsigned long *" old_nodes, .BI " const unsigned long *" new_nodes ); @@ -36,7 +36,7 @@ the kernel maintains the relative topology relationship inside .I old_nodes during the migration to .IR new_nodes . -.PP +.P The .I old_nodes and @@ -58,7 +58,7 @@ as in .BR mbind (2), but different from .BR select (2)). -.PP +.P The .I pid argument is the ID of the process whose pages are to be moved. @@ -72,7 +72,7 @@ If is 0, then .BR migrate_pages () moves pages of the calling process. -.PP +.P Pages shared with another process will be moved only if the initiating process has the .B CAP_SYS_NICE @@ -132,7 +132,7 @@ Linux 2.6.16. .SH NOTES For information on library support, see .BR numa (7). -.PP +.P Use .BR get_mempolicy (2) with the @@ -141,7 +141,7 @@ flag to obtain the set of nodes that are allowed by the calling process's cpuset. Note that this information is subject to change at any time by manual or automatic reconfiguration of the cpuset. -.PP +.P Use of .BR migrate_pages () may result in pages whose location @@ -153,7 +153,7 @@ and/or the specified process (see That is, memory policy does not constrain the destination nodes used by .BR migrate_pages (). -.PP +.P The .I <numaif.h> header is not included with glibc, but requires installing @@ -169,6 +169,6 @@ or a similar package. .BR numa (7), .BR migratepages (8), .BR numastat (8) -.PP +.P .I Documentation/vm/page_migration.rst in the Linux kernel source tree diff --git a/man2/mincore.2 b/man2/mincore.2 index 9ffca56..efba7fc 100644 --- a/man2/mincore.2 +++ b/man2/mincore.2 @@ -11,7 +11,7 @@ .\" after message from <gordon.jin@intel.com> .\" 2007-01-08 mtk, rewrote various parts .\" -.TH mincore 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mincore 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mincore \- determine whether pages are resident in memory .SH LIBRARY @@ -20,15 +20,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/mman.h> -.PP +.P .BI "int mincore(void " addr [. length "], size_t " length ", unsigned char *" vec ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mincore (): .nf Since glibc 2.19: @@ -47,7 +47,7 @@ starting at the address and continuing for .I length bytes. -.PP +.P The .I addr argument must be a multiple of the system page size. @@ -61,7 +61,7 @@ One may obtain the page size .RB ( PAGE_SIZE ) using .IR sysconf(_SC_PAGESIZE) . -.PP +.P The .I vec argument must point to an array containing at least @@ -122,9 +122,9 @@ None. .SH HISTORY Linux 2.3.99pre1, glibc 2.2. -.PP +.P First appeared in 4.4BSD. -.PP +.P NetBSD, FreeBSD, OpenBSD, Solaris 8, AIX 5.1, SunOS 4.1. .SH BUGS diff --git a/man2/mkdir.2 b/man2/mkdir.2 index c3342bd..d63059f 100644 --- a/man2/mkdir.2 +++ b/man2/mkdir.2 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH mkdir 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mkdir 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mkdir, mkdirat \- create a directory .SH LIBRARY @@ -15,20 +15,20 @@ Standard C library .nf .B #include <sys/stat.h> .\" .B #include <unistd.h> -.PP +.P .BI "int mkdir(const char *" pathname ", mode_t " mode ); -.PP +.P .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" .B #include <sys/stat.h> -.PP +.P .BI "int mkdirat(int " dirfd ", const char *" pathname ", mode_t " mode ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mkdirat (): .nf Since glibc 2.10: @@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see .BR mkdir () attempts to create a directory named .IR pathname . -.PP +.P The argument .I mode specifies the mode for the new directory (see @@ -54,7 +54,7 @@ Whether other .I mode bits are honored for the created directory depends on the operating system. For Linux, see NOTES below. -.PP +.P The newly created directory will be owned by the effective user ID of the process. If the directory containing the file has the set-group-ID @@ -64,7 +64,7 @@ or, synonymously .IR "mount \-o grpid" ), the new directory will inherit the group ownership from its parent; otherwise it will be owned by the effective group ID of the process. -.PP +.P If the parent directory has the set-group-ID bit set, then so will the newly created directory. .\" @@ -75,7 +75,7 @@ The system call operates in exactly the same way as .BR mkdir (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -85,7 +85,7 @@ referred to by the file descriptor the calling process, as is done by .BR mkdir () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -97,13 +97,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR mkdir ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P See .BR openat (2) for an explanation of the need for diff --git a/man2/mknod.2 b/man2/mknod.2 index 0925aea..dd7905c 100644 --- a/man2/mknod.2 +++ b/man2/mknod.2 @@ -9,7 +9,7 @@ .\" Modified 2003-04-23 by Michael Kerrisk .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH mknod 2 2023-03-31 "Linux man-pages 6.05.01" +.TH mknod 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mknod, mknodat \- create a special or ordinary file .SH LIBRARY @@ -18,21 +18,21 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/stat.h> -.PP +.P .BI "int mknod(const char *" pathname ", mode_t " mode ", dev_t " dev ); -.PP +.P .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" .B #include <sys/stat.h> -.PP +.P .BI "int mknodat(int " dirfd ", const char *" pathname ", mode_t " mode \ ", dev_t " dev ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mknod (): .nf _XOPEN_SOURCE >= 500 @@ -50,7 +50,7 @@ with attributes specified by .I mode and .IR dev . -.PP +.P The .I mode argument specifies both the file mode to use and the type of node @@ -58,13 +58,13 @@ to be created. It should be a combination (using bitwise OR) of one of the file types listed below and zero or more of the file mode bits listed in .BR inode (7). -.PP +.P The file mode is modified by the process's .I umask in the usual way: in the absence of a default ACL, the permissions of the created node are .RI ( mode " & \[ti]" umask ). -.PP +.P The file type must be one of .BR S_IFREG , .BR S_IFCHR , @@ -78,7 +78,7 @@ special file, block special file, FIFO (named pipe), or UNIX domain socket, respectively. (Zero file type is equivalent to type .BR S_IFREG .) -.PP +.P If the file type is .B S_IFCHR or @@ -91,13 +91,13 @@ special file may be useful to build the value for .IR dev ); otherwise it is ignored. -.PP +.P If .I pathname already exists, or is a symbolic link, this call fails with an .B EEXIST error. -.PP +.P The newly created node will be owned by the effective user ID of the process. If the directory containing the node has the set-group-ID @@ -112,7 +112,7 @@ The system call operates in exactly the same way as .BR mknod (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -122,7 +122,7 @@ referred to by the file descriptor the calling process, as is done by .BR mknod () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -134,13 +134,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR mknod ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -258,7 +258,7 @@ However, nowadays one should never use for this purpose; one should use .BR mkfifo (3), a function especially defined for this purpose. -.PP +.P Under Linux, .BR mknod () cannot be used to create directories. diff --git a/man2/mlock.2 b/man2/mlock.2 index 1efe3dd..965e018 100644 --- a/man2/mlock.2 +++ b/man2/mlock.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH mlock 2 2023-04-08 "Linux man-pages 6.05.01" +.TH mlock 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory .SH LIBRARY @@ -13,12 +13,12 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/mman.h> -.PP +.P .BI "int mlock(const void " addr [. len "], size_t " len ); .BI "int mlock2(const void " addr [. len "], size_t " len ", \ unsigned int " flags ); .BI "int munlock(const void " addr [. len "], size_t " len ); -.PP +.P .BI "int mlockall(int " flags ); .B int munlockall(void); .fi @@ -30,7 +30,7 @@ and lock part or all of the calling process's virtual address space into RAM, preventing that memory from being paged to the swap area. -.PP +.P .BR munlock () and .BR munlockall () @@ -38,7 +38,7 @@ perform the converse operation, unlocking part or all of the calling process's virtual address space, so that pages in the specified virtual address range can be swapped out again if required by the kernel memory manager. -.PP +.P Memory locking and unlocking are performed in units of whole pages. .SS mlock(), mlock2(), and munlock() .BR mlock () @@ -50,7 +50,7 @@ bytes. All pages that contain a part of the specified address range are guaranteed to be resident in RAM when the call returns successfully; the pages are guaranteed to stay in RAM until later unlocked. -.PP +.P .BR mlock2 () .\" commit a8ca5d0ecbdde5cc3d7accacbd69968b0c98764e .\" commit de60f5f10c58d4f34b68622442c0e04180367f3f @@ -64,7 +64,7 @@ However, the state of the pages contained in that range after the call returns successfully will depend on the value in the .I flags argument. -.PP +.P The .I flags argument can be either 0 or the following constant: @@ -73,14 +73,14 @@ argument can be either 0 or the following constant: Lock pages that are currently resident and mark the entire range so that the remaining nonresident pages are locked when they are populated by a page fault. -.PP +.P If .I flags is 0, .BR mlock2 () behaves exactly the same as .BR mlock (). -.PP +.P .BR munlock () unlocks pages in the address range starting at .I addr @@ -99,7 +99,7 @@ memory, and memory-mapped files. All mapped pages are guaranteed to be resident in RAM when the call returns successfully; the pages are guaranteed to stay in RAM until later unlocked. -.PP +.P The .I flags argument is constructed as the bitwise OR of one or more of the @@ -142,7 +142,7 @@ must be used with either or .B MCL_FUTURE or both. -.PP +.P If .B MCL_FUTURE has been specified, then a later system call (e.g., @@ -155,7 +155,7 @@ In the same circumstances, stack growth may likewise fail: the kernel will deny stack expansion and deliver a .B SIGSEGV signal to the process. -.PP +.P .BR munlockall () unlocks all pages mapped into the address space of the calling process. @@ -272,7 +272,7 @@ and allows an implementation to require that .I addr is page aligned, so portable applications should ensure this. -.PP +.P The .I VmLck field of the Linux-specific @@ -299,7 +299,7 @@ POSIX.1-2008. .TP .BR mlock2 () Linux. -.PP +.P On POSIX systems on which .BR mlock () and @@ -311,7 +311,7 @@ can be determined from the constant .B PAGESIZE (if defined) in \fI<limits.h>\fP or by calling .IR sysconf(_SC_PAGESIZE) . -.PP +.P On POSIX systems on which .BR mlockall () and @@ -356,7 +356,7 @@ software has erased the secrets in RAM and terminated. (But be aware that the suspend mode on laptops and some desktop computers will save a copy of the system's RAM to disk, regardless of memory locks.) -.PP +.P Real-time processes that are using .BR mlockall () to prevent delays on page faults should reserve enough @@ -369,7 +369,7 @@ This way, enough pages will be mapped for the stack and can be locked into RAM. The dummy writes ensure that not even copy-on-write page faults can occur in the critical section. -.PP +.P Memory locks are not inherited by a child created via .BR fork (2) and are automatically removed (unlocked) during an @@ -384,7 +384,7 @@ settings are not inherited by a child created via .BR fork (2) and are cleared during an .BR execve (2). -.PP +.P Note that .BR fork (2) will prepare the address space for a copy-on-write operation. @@ -398,11 +398,11 @@ or .BR mlock () operation\[em]not even from a thread which runs at a low priority within a process which also has a thread running at elevated priority. -.PP +.P The memory lock on an address range is automatically removed if the address range is unmapped via .BR munmap (2). -.PP +.P Memory locks do not stack, that is, pages which have been locked several times by calls to .BR mlock (), @@ -416,7 +416,7 @@ for the corresponding range or by Pages which are mapped to several locations or by several processes stay locked into RAM as long as they are locked at least at one location or by at least one process. -.PP +.P If a call to .BR mlockall () which uses the @@ -425,7 +425,7 @@ flag is followed by another call that does not specify this flag, the changes made by the .B MCL_FUTURE call will be lost. -.PP +.P The .BR mlock2 () .B MLOCK_ONFAULT @@ -443,7 +443,7 @@ a process must be privileged in order to lock memory and the .B RLIMIT_MEMLOCK soft resource limit defines a limit on how much memory the process may lock. -.PP +.P Since Linux 2.6.9, no limits are placed on the amount of memory that a privileged process can lock and the .B RLIMIT_MEMLOCK @@ -472,7 +472,7 @@ would fail on requests that should have succeeded. This bug was fixed .\" commit 0cf2f6f6dc605e587d2c1120f295934c77e810e8 in Linux 4.9. -.PP +.P In Linux 2.4 series of kernels up to and including Linux 2.4.17, a bug caused the .BR mlockall () @@ -480,7 +480,7 @@ a bug caused the flag to be inherited across a .BR fork (2). This was rectified in Linux 2.4.18. -.PP +.P Since Linux 2.6.9, if a privileged process calls .I mlockall(MCL_FUTURE) and later drops privileges (loses the diff --git a/man2/mmap.2 b/man2/mmap.2 index 3d9a887..300eb2b 100644 --- a/man2/mmap.2 +++ b/man2/mmap.2 @@ -18,7 +18,7 @@ .\" 2007-07-10, mtk, Added an example program. .\" 2008-11-18, mtk, document MAP_STACK .\" -.TH mmap 2 2023-07-20 "Linux man-pages 6.05.01" +.TH mmap 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mmap, munmap \- map or unmap files or devices into memory .SH LIBRARY @@ -27,13 +27,13 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/mman.h> -.PP +.P .BI "void *mmap(void " addr [. length "], size_t " length \ ", int " prot ", int " flags , .BI " int " fd ", off_t " offset ); .BI "int munmap(void " addr [. length "], size_t " length ); .fi -.PP +.P See NOTES for information on feature test macro requirements. .SH DESCRIPTION .BR mmap () @@ -44,7 +44,7 @@ The starting address for the new mapping is specified in The .I length argument specifies the length of the mapping (which must be greater than 0). -.PP +.P If .I addr is NULL, @@ -64,7 +64,7 @@ may or may not depend on the hint. .\" Before Linux 2.6.24, the address was rounded up to the next page .\" boundary; since Linux 2.6.24, it is rounded down! The address of the new mapping is returned as the result of the call. -.PP +.P The contents of a file mapping (as opposed to an anonymous mapping; see .B MAP_ANONYMOUS below), are initialized using @@ -76,13 +76,13 @@ in the file (or other object) referred to by the file descriptor .I offset must be a multiple of the page size as returned by .IR sysconf(_SC_PAGE_SIZE) . -.PP +.P After the .BR mmap () call has returned, the file descriptor, .IR fd , can be closed immediately without invalidating the mapping. -.PP +.P The .I prot argument describes the desired memory protection of the mapping @@ -147,7 +147,7 @@ the underlying file. It is unspecified whether changes made to the file after the .BR mmap () call are visible in the mapped region. -.PP +.P Both .B MAP_SHARED and @@ -155,7 +155,7 @@ and are described in POSIX.1-2001 and POSIX.1-2008. .B MAP_SHARED_VALIDATE is a Linux extension. -.PP +.P In addition, zero or more of the following values can be ORed in .IR flags : .TP @@ -299,7 +299,9 @@ See the Linux kernel source file .I Documentation/admin\-guide/mm/hugetlbpage.rst for further information, as well as NOTES, below. .TP -.BR MAP_HUGE_2MB ", " MAP_HUGE_1GB " (since Linux 3.8)" +.B MAP_HUGE_2MB +.TQ +.BR MAP_HUGE_1GB " (since Linux 3.8)" .\" See https://lwn.net/Articles/533499/ Used in conjunction with .B MAP_HUGETLB @@ -443,7 +445,7 @@ option. Because of the security implications, that option is normally enabled only on embedded devices (i.e., devices where one has complete control of the contents of user memory). -.PP +.P Of the above flags, only .B MAP_FIXED is specified in POSIX.1-2001 and POSIX.1-2008. @@ -465,7 +467,7 @@ The region is also automatically unmapped when the process is terminated. On the other hand, closing the file descriptor does not unmap the region. -.PP +.P The address .I addr must be a multiple of the page size (but @@ -488,7 +490,7 @@ On error, the value is returned, and .I errno is set to indicate the error. -.PP +.P On success, .BR munmap () returns 0. @@ -629,13 +631,14 @@ and is not a member of the group; see the description of .I /proc/sys/vm/sysctl_hugetlb_shm_group in +.BR proc_sys (5). .TP .B ETXTBSY .B MAP_DENYWRITE was set but the object specified by .I fd is open for writing. -.PP +.P Use of a mapped region can result in these signals: .TP .B SIGSEGV @@ -662,7 +665,6 @@ T{ .BR munmap () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On some hardware architectures (e.g., i386), .B PROT_WRITE @@ -676,7 +678,7 @@ or not. Portable programs should always set .B PROT_EXEC if they intend to execute code in the new mapping. -.PP +.P The portable way to create a mapping is to specify .I addr as 0 (NULL), and omit @@ -691,7 +693,7 @@ If the flag is specified, and .I addr is 0 (NULL), then the mapped address will be 0 (NULL). -.PP +.P Certain .I flags constants are defined only if suitable feature test macros are defined @@ -745,7 +747,7 @@ POSIX.1-2008. POSIX.1-2001, SVr4, 4.4BSD. .\" SVr4 documents additional error codes ENXIO and ENODEV. .\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. -.PP +.P On POSIX systems on which .BR mmap (), .BR msync (2), @@ -765,7 +767,7 @@ Memory mapped by is preserved across .BR fork (2), with the same attributes. -.PP +.P A file is mapped in multiples of the page size. For a file that is not a multiple of the page size, @@ -775,7 +777,7 @@ and modifications to that region are not written out to the file. The effect of changing the size of the underlying file of a mapping on the pages that correspond to added or removed regions of the file is unspecified. -.PP +.P An application can determine which pages of a mapping are currently resident in the buffer/page cache using .BR mincore (2). @@ -792,7 +794,7 @@ otherwise, the use of .B MAP_FIXED is hazardous because it forcibly removes preexisting mappings, making it easy for a multithreaded process to corrupt its own address space. -.PP +.P For example, suppose that thread A looks through .IR /proc/ pid /maps in order to locate an unused address range that it can map using @@ -820,7 +822,7 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . -.PP +.P Since Linux 4.17, a multithreaded program can use the .B MAP_FIXED_NOREPLACE flag to avoid the hazard described above @@ -834,7 +836,7 @@ field for the mapped file may be updated at any time between the .BR mmap () and the corresponding unmapping; the first reference to a mapped page will update the field if it has not been already. -.PP +.P The .I st_ctime and @@ -859,7 +861,7 @@ and .BR munmap () differ somewhat from the requirements for mappings that use the native system page size. -.PP +.P For .BR mmap (), .I offset @@ -867,7 +869,7 @@ must be a multiple of the underlying huge page size. The system automatically aligns .I length to be a multiple of the underlying huge page size. -.PP +.P For .BR munmap (), .IR addr , @@ -880,14 +882,14 @@ On Linux, there are no guarantees like those suggested above under .BR MAP_NORESERVE . By default, any process can be killed at any moment when the system runs out of memory. -.PP +.P Before Linux 2.6.7, the .B MAP_POPULATE flag has effect only if .I prot is specified as .BR PROT_NONE . -.PP +.P SUSv3 specifies that .BR mmap () should fail if @@ -902,7 +904,7 @@ Since Linux 2.6.12, fails with the error .B EINVAL for this case. -.PP +.P POSIX specifies that the system shall always zero fill any partial page at the end of the object and that system will never write any modification of the @@ -1021,14 +1023,14 @@ main(int argc, char *argv[]) .BR userfaultfd (2), .BR shm_open (3), .BR shm_overview (7) -.PP +.P The descriptions of the following files in .BR proc (5): .IR /proc/ pid /maps , .IR /proc/ pid /map_files , and .IR /proc/ pid /smaps . -.PP +.P B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391. .\" .\" Repeat after me: private read-only mappings are 100% equivalent to diff --git a/man2/mmap2.2 b/man2/mmap2.2 index e1704e3..e406c20 100644 --- a/man2/mmap2.2 +++ b/man2/mmap2.2 @@ -6,7 +6,7 @@ .\" Added description of mmap2 .\" Modified, 2004-11-25, mtk -- removed stray #endif in prototype .\" -.TH mmap2 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mmap2 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mmap2 \- map files or devices into memory .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .BR "#include <sys/mman.h>" " /* Definition of " MAP_* " and " PROT_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "void *syscall(SYS_mmap2, unsigned long " addr ", unsigned long " length , .BI " unsigned long " prot ", unsigned long " flags , .BI " unsigned long " fd ", unsigned long " pgoffset ); @@ -26,7 +26,7 @@ Standard C library This is probably not the system call that you are interested in; instead, see .BR mmap (2), which describes the glibc wrapper function that invokes this system call. -.PP +.P The .BR mmap2 () system call provides the same interface as @@ -53,7 +53,7 @@ Problem with getting the data from user space. (Various platforms where the page size is not 4096 bytes.) .I "offset\ *\ 4096" is not a multiple of the system page size. -.PP +.P .BR mmap2 () can also return any of the errors described in .BR mmap (2). @@ -64,9 +64,9 @@ the glibc wrapper function invokes this system call rather than the .BR mmap (2) system call. -.PP +.P This system call does not exist on x86-64. -.PP +.P On ia64, the unit for .I offset is actually the system page size, rather than 4096 bytes. diff --git a/man2/modify_ldt.2 b/man2/modify_ldt.2 index 0364289..7ef2722 100644 --- a/man2/modify_ldt.2 +++ b/man2/modify_ldt.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH modify_ldt 2 2023-03-30 "Linux man-pages 6.05.01" +.TH modify_ldt 2 2023-10-31 "Linux man-pages 6.7" .SH NAME modify_ldt \- get or set a per-process LDT entry .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .BR "#include <asm/ldt.h>" " /* Definition of " "struct user_desc" " */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_modify_ldt, int " func ", void " ptr [. bytecount ], .BI " unsigned long " bytecount ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR modify_ldt (), @@ -32,7 +32,7 @@ is an array of segment descriptors that can be referenced by user code. Linux allows processes to configure a per-process (actually per-mm) LDT. For more information about the LDT, see the Intel Software Developer's Manual or the AMD Architecture Programming Manual. -.PP +.P When .I func is 0, @@ -46,7 +46,7 @@ the LDT is padded with additional trailing zero bytes. On success, .BR modify_ldt () will return the number of bytes read. -.PP +.P When .I func is 1 or 0x11, @@ -60,11 +60,11 @@ structure and .I bytecount must equal the size of this structure. -.PP +.P The .I user_desc structure is defined in \fI<asm/ldt.h>\fP as: -.PP +.P .in +4n .EX struct user_desc { @@ -80,10 +80,10 @@ struct user_desc { }; .EE .in -.PP +.P In Linux 2.4 and earlier, this structure was named .IR modify_ldt_ldt_s . -.PP +.P The .I contents field is the segment type (data, expand-down data, non-conforming code, or @@ -91,7 +91,7 @@ conforming code). The other fields match their descriptions in the CPU manual, although .BR modify_ldt () cannot set the hardware-defined "accessed" bit described in the CPU manual. -.PP +.P A .I user_desc is considered "empty" if @@ -108,7 +108,7 @@ is 1, by setting both and .I limit to 0. -.PP +.P A conforming code segment (i.e., one with .IR contents==3 ) will be rejected if @@ -117,7 +117,7 @@ func is 1 or if .I seg_not_present is 0. -.PP +.P When .I func is 2, @@ -168,12 +168,12 @@ or .BR arch_prctl (2) instead, except on extremely old kernels that do not support those system calls. -.PP +.P The normal use for .BR modify_ldt () is to run legacy 16-bit or segmented 32-bit code. Not all kernels allow 16-bit segments to be installed, however. -.PP +.P Even on 64-bit kernels, .BR modify_ldt () cannot be used to create a long mode (i.e., 64-bit) code segment. diff --git a/man2/mount.2 b/man2/mount.2 index 916b68c..f2511c4 100644 --- a/man2/mount.2 +++ b/man2/mount.2 @@ -17,7 +17,7 @@ .\" 2008-10-06, mtk: move umount*() material into separate umount.2 page. .\" 2008-10-06, mtk: Add discussion of namespaces. .\" -.TH mount 2 2023-04-03 "Linux man-pages 6.05.01" +.TH mount 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mount \- mount filesystem .SH LIBRARY @@ -26,7 +26,7 @@ Standard C library .SH SYNOPSIS .nf .B "#include <sys/mount.h>" -.PP +.P .BI "int mount(const char *" source ", const char *" target , .BI " const char *" filesystemtype ", unsigned long " mountflags , .BI " const void *_Nullable " data ); @@ -40,11 +40,11 @@ but can also be the pathname of a directory or file, or a dummy string) to the location (a directory or file) specified by the pathname in .IR target . -.PP +.P Appropriate privilege (Linux: the .B CAP_SYS_ADMIN capability) is required to mount filesystems. -.PP +.P Values for the .I filesystemtype argument supported by the kernel are listed in @@ -53,7 +53,7 @@ argument supported by the kernel are listed in "tmpfs", "cgroup", "proc", "mqueue", "nfs", "cifs", "iso9660"). Further types may become available when the appropriate modules are loaded. -.PP +.P The .I data argument is interpreted by the different filesystems. @@ -63,7 +63,7 @@ See .BR mount (8) for details of the options available for each filesystem type. This argument may be specified as NULL, if there are no options. -.PP +.P A call to .BR mount () performs one of a number of general types of operation, @@ -101,7 +101,7 @@ includes Create a new mount: .I mountflags includes none of the above flags. -.PP +.P Each of these operations is detailed later in this page. Further flags may be specified in .I mountflags @@ -284,13 +284,13 @@ and and .BR realpath (3) all still work properly. -.PP +.P From Linux 2.4 onward, some of the above flags are settable on a per-mount basis, while others apply to the superblock of the mounted filesystem, meaning that all mounts of the same filesystem share those flags. (Previously, all of the flags were per-superblock.) -.PP +.P The per-mount-point flags are as follows: .IP \[bu] 3 Since Linux 2.4: @@ -304,7 +304,7 @@ and .IP \[bu] Additionally, since Linux 2.6.20: .BR MS_RELATIME . -.PP +.P The following flags are per-superblock: .BR MS_DIRSYNC , .BR MS_LAZYTIME , @@ -320,7 +320,7 @@ Subsequently, the settings of the flags can be changed via a remount operation (see below). Such changes will be visible via all mounts associated with the filesystem. -.PP +.P Since Linux 2.6.16, .B MS_RDONLY can be set or cleared on a per-mount-point basis as well as on @@ -342,13 +342,13 @@ of an existing mount without having to unmount and remount the filesystem. should be the same value specified in the initial .BR mount () call. -.PP +.P The .I source and .I filesystemtype arguments are ignored. -.PP +.P The .I mountflags and @@ -356,7 +356,7 @@ and arguments should match the values used in the original .BR mount () call, except for those parameters that are being deliberately changed. -.PP +.P The following .I mountflags can be changed: @@ -398,7 +398,7 @@ flags during a remount are silently ignored. Note that changes to per-superblock flags are visible via all mounts of the associated filesystem (because the per-superblock flags are shared by all mounts). -.PP +.P Since Linux 3.17, .\" commit ffbc6f0ead47fa5a1dc9642b0331cb75c20a640e if none of @@ -412,7 +412,7 @@ is specified in then the remount operation preserves the existing values of these flags (rather than defaulting to .BR MS_RELATIME ). -.PP +.P Since Linux 2.6.26, the .B MS_REMOUNT flag can be used with @@ -424,13 +424,13 @@ flag on a mount without changing the underlying filesystem. Specifying .I mountflags as: -.PP +.P .in +4n .EX MS_REMOUNT | MS_BIND | MS_RDONLY .EE .in -.PP +.P will make access through this mountpoint read-only, without affecting other mounts. .\" @@ -447,13 +447,13 @@ another point within the single directory hierarchy. Bind mounts may cross filesystem boundaries and span .BR chroot (2) jails. -.PP +.P The .I filesystemtype and .I data arguments are ignored. -.PP +.P The remaining bits (other than .BR MS_REC , described below) in the @@ -463,7 +463,7 @@ argument are also ignored. the underlying mount.) However, see the discussion of remounting above, for a method of making an existing bind mount read-only. -.PP +.P By default, when a directory is bind mounted, only that directory is mounted; if there are any submounts under the directory tree, @@ -490,21 +490,21 @@ or (all available since Linux 2.6.15), then the propagation type of an existing mount is changed. If more than one of these flags is specified, an error results. -.PP +.P The only other flags that can be specified while changing the propagation type are .B MS_REC (described below) and .B MS_SILENT (which is ignored). -.PP +.P The .IR source , .IR filesystemtype , and .I data arguments are ignored. -.PP +.P The meanings of the propagation type flags are as follows: .TP .B MS_SHARED @@ -550,7 +550,7 @@ flags) is performed on a directory subtree, any unbindable mounts within the subtree are automatically pruned (i.e., not replicated) when replicating that subtree to produce the target subtree. -.PP +.P By default, changing the propagation type affects only the .I target mount. @@ -561,7 +561,7 @@ flag is also specified in then the propagation type of all mounts under .I target is also changed. -.PP +.P For further details regarding mount propagation types (including the default propagation type assigned to new mounts), see .BR mount_namespaces (7). @@ -578,7 +578,7 @@ specifies an existing mount and .I target specifies the new location to which that mount is to be relocated. The move is atomic: at no point is the subtree unmounted. -.PP +.P The remaining bits in the .I mountflags argument are ignored, as are the @@ -606,7 +606,7 @@ performs its default action: creating a new mount. specifies the source for the new mount, and .I target specifies the directory at which to create the mount point. -.PP +.P The .I filesystemtype and @@ -847,12 +847,12 @@ The definitions of and .B MS_UNBINDABLE were added to glibc headers in glibc 2.12. -.PP +.P Since Linux 2.4 a single filesystem can be mounted at multiple mount points, and multiple mounts can be stacked on the same mount point. .\" Multiple mounts on same mount point: since Linux 2.3.99pre7. -.PP +.P The .I mountflags argument may have the magic number 0xC0ED (\fBMS_MGC_VAL\fP) @@ -864,7 +864,7 @@ Specifying .B MS_MGC_VAL was required before Linux 2.4, but since Linux 2.4 is no longer required and is ignored if specified. -.PP +.P The original .B MS_SYNC flag was renamed @@ -873,7 +873,7 @@ in 1.1.69 when a different .B MS_SYNC was added to \fI<mman.h>\fP. -.PP +.P Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID program on a filesystem mounted with .B MS_NOSUID @@ -894,13 +894,13 @@ and changes to the namespace (i.e., mounts and unmounts) by one process are visible to all other processes sharing the same namespace. (The pre-2.4.19 Linux situation can be considered as one in which a single namespace was shared by every process on the system.) -.PP +.P A child process created by .BR fork (2) shares its parent's mount namespace; the mount namespace is preserved across an .BR execve (2). -.PP +.P A process can obtain a private mount namespace if: it was created using the .BR clone (2) @@ -920,7 +920,7 @@ of the namespace that it was previously sharing with other processes, so that future mounts and unmounts by the caller are invisible to other processes (except child processes that the caller subsequently creates) and vice versa. -.PP +.P For further details on mount namespaces, see .BR mount_namespaces (7). .\" @@ -928,7 +928,7 @@ For further details on mount namespaces, see Each mount has a parent mount. The overall parental relationship of all mounts defines the single directory hierarchy seen by the processes within a mount namespace. -.PP +.P The parent of a new mount is defined when the mount is created. In the usual case, the parent of a new mount is the mount of the filesystem @@ -936,7 +936,7 @@ containing the directory or file at which the new mount is attached. In the case where a new mount is stacked on top of an existing mount, the parent of the new mount is the previous mount that was stacked at that location. -.PP +.P The parental relationship between mounts can be discovered via the .IR /proc/ pid /mountinfo file (see below). diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2 index fafaba2..d59994b 100644 --- a/man2/mount_setattr.2 +++ b/man2/mount_setattr.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mount_setattr 2 2023-05-03 "Linux man-pages 6.05.01" +.TH mount_setattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mount_setattr \- change properties of a mount or mount tree .SH LIBRARY @@ -14,12 +14,12 @@ Standard C library .BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" pathname , .BI " unsigned int " flags ", struct mount_attr *" attr \ ", size_t " size ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR mount_setattr (), @@ -57,7 +57,7 @@ are changed. for an explanation of why the .I dirfd argument is useful.) -.PP +.P The .BR mount_setattr () system call uses an extensible structure @@ -75,7 +75,7 @@ zero-fill this structure on initialization. See the "Extensibility" subsection under .B NOTES for more details. -.PP +.P The .I size argument should usually be specified as @@ -96,7 +96,7 @@ For example, the macro for the size of the initial version of .I struct mount_attr is .BR MOUNT_ATTR_SIZE_VER0 . -.PP +.P The .I flags argument can be used to alter the pathname resolution behavior. @@ -118,13 +118,13 @@ Don't follow trailing symbolic links. .TP .B AT_NO_AUTOMOUNT Don't trigger automounts. -.PP +.P The .I attr argument of .BR mount_setattr () is a structure of the following form: -.PP +.P .in +4n .EX struct mount_attr { @@ -135,7 +135,7 @@ struct mount_attr { }; .EE .in -.PP +.P The .I attr_set and @@ -148,7 +148,7 @@ enable a property on a mount or mount tree, and flags set in .I attr_clr remove a property from a mount or mount tree. -.PP +.P When changing mount properties, the kernel will first clear the flags specified in the @@ -158,7 +158,7 @@ and then set the flags specified in the .I attr_set field. For example, these settings: -.PP +.P .in +4n .EX struct mount_attr attr = { @@ -167,9 +167,9 @@ struct mount_attr attr = { }; .EE .in -.PP +.P are equivalent to the following steps: -.PP +.P .in +4n .EX unsigned int current_mnt_flags = mnt\->mnt_flags; @@ -189,18 +189,18 @@ current_mnt_flags |= attr\->attr_set; mnt\->mnt_flags = current_mnt_flags; .EE .in -.PP +.P As a result of this change, the mount or mount tree (a) is read-only; (b) blocks the execution of set-user-ID and set-group-ID programs; (c) allows execution of programs; and (d) allows access to devices. -.PP +.P Multiple changes with the same set of flags requested in .I attr_clr and .I attr_set are guaranteed to be idempotent after the changes have been applied. -.PP +.P The following mount attributes can be specified in the .I attr_set or @@ -361,7 +361,7 @@ in .IR attr_clr . .IP For further details, see the subsection "ID-mapped mounts" under NOTES. -.PP +.P The .I propagation field is used to specify the propagation type of the mount or mount tree. @@ -380,7 +380,7 @@ Turn all mounts into dependent mounts. .TP .B MS_UNBINDABLE Turn all mounts into unbindable mounts. -.PP +.P For further details on the above propagation types, see .BR mount_namespaces (7). .SH RETURN VALUE @@ -597,7 +597,7 @@ visible only via a specific mount. All other users and locations where the filesystem is exposed are unaffected. It is a temporary change because the ownership changes are tied to the lifetime of the mount. -.PP +.P Whenever callers interact with the filesystem through an ID-mapped mount, the ID mapping of the mount will be applied to user and group IDs associated with filesystem objects. @@ -623,7 +623,7 @@ whenever user IDs or group IDs are stored in or .B ACL_GROUP entries. -.PP +.P The following conditions must be met in order to create an ID-mapped mount: .IP \[bu] 3 The caller must have the @@ -687,7 +687,7 @@ flag and it must not already have been visible in a mount namespace. the mount must not have been attached to the filesystem hierarchy with a system call such as .BR move_mount (2).) -.PP +.P ID mappings can be created for user IDs, group IDs, and project IDs. An ID mapping is essentially a mapping of a range of user or group IDs into another or the same range of user or group IDs. @@ -702,15 +702,15 @@ user ID 1000 in the caller's user namespace is mapped to user ID 1001 in its ancestor user namespace. Since the map range is 1, only user ID 1000 is mapped. -.PP +.P It is possible to specify up to 340 ID mappings for each ID mapping type. If any user IDs or group IDs are not mapped, all files owned by that unmapped user or group ID will appear as being owned by the overflow user ID or overflow group ID respectively. -.PP +.P Further details on setting up ID mappings can be found in .BR user_namespaces (7). -.PP +.P In the common case, the user namespace passed in .I userns_fd (together with @@ -723,7 +723,7 @@ a user's login session as is the case for portable home directories in .BR systemd-homed.service (8)). It is also perfectly fine to create a dedicated user namespace for the sake of ID mapping a mount. -.PP +.P ID-mapped mounts can be useful in the following and a variety of other scenarios: .IP \[bu] 3 @@ -808,7 +808,7 @@ This extensibility design is very similar to other system calls such as .BR clone3 (2) and .BR openat2 (2). -.PP +.P Let .I usize be the size of the structure as specified by the user-space application, @@ -852,7 +852,7 @@ then \-1 is returned and is set to .BR E2BIG . This provides forwards-compatibility. -.PP +.P Because the definition of .I struct mount_attr may change in the future @@ -862,7 +862,7 @@ user-space applications should zero-fill to ensure that recompiling the program with new headers will not result in spurious errors at run time. The simplest way is to use a designated initializer: -.PP +.P .in +4n .EX struct mount_attr attr = { @@ -871,11 +871,11 @@ struct mount_attr attr = { }; .EE .in -.PP +.P Alternatively, the structure can be zero-filled using .BR memset (3) or similar functions: -.PP +.P .in +4n .EX struct mount_attr attr; @@ -884,7 +884,7 @@ attr.attr_set = MOUNT_ATTR_RDONLY; attr.attr_clr = MOUNT_ATTR_NODEV; .EE .in -.PP +.P A user-space application that wishes to determine which extensions the running kernel supports can do so by conducting a binary search on .I size diff --git a/man2/move_pages.2 b/man2/move_pages.2 index c2be4bb..e9627d1 100644 --- a/man2/move_pages.2 +++ b/man2/move_pages.2 @@ -1,4 +1,4 @@ -.\" SPDX-License-Identifier: Linux-man-pages-copyleft-2-para +.\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc. .\" Christoph Lameter @@ -8,7 +8,7 @@ .\" (e.g., compare with recommendation in mbind(2)). .\" Does this page need to give advice on this topic? .\" -.TH move_pages 2 2023-07-15 "Linux man-pages 6.05.01" +.TH move_pages 2 2023-10-31 "Linux man-pages 6.7" .SH NAME move_pages \- move individual pages of a process to another node .SH LIBRARY @@ -17,7 +17,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .nf .B #include <numaif.h> -.PP +.P .BI "long move_pages(int " pid ", unsigned long " count ", \ void *" pages [. count ], .BI " const int " nodes [. count "], int " status [. count "], \ @@ -36,7 +36,7 @@ The result of the move is reflected in The .I flags indicate constraints on the pages to be moved. -.PP +.P .I pid is the ID of the process in which pages are to be moved. If @@ -44,7 +44,7 @@ If is 0, then .BR move_pages () moves pages of the calling process. -.PP +.P To move pages in another process requires the following privileges: .IP \[bu] 3 Up to and including Linux 4.12: @@ -64,7 +64,7 @@ permission is governed by a ptrace access mode .B PTRACE_MODE_READ_REALCREDS check with respect to the target process; see .BR ptrace (2). -.PP +.P .I count is the number of pages to move. It defines the size of the three arrays @@ -72,7 +72,7 @@ It defines the size of the three arrays .IR nodes , and .IR status . -.PP +.P .I pages is an array of pointers to the pages that should be moved. These are pointers that should be aligned to page boundaries. @@ -80,7 +80,7 @@ These are pointers that should be aligned to page boundaries. .\" not aligned to page boundaries Addresses are specified as seen by the process specified by .IR pid . -.PP +.P .I nodes is an array of integers that specify the desired location for each page. Each element in the array is a node number. @@ -93,7 +93,7 @@ where each page currently resides, in the array. Obtaining the status of each page may be necessary to determine pages that need to be moved. -.PP +.P .I status is an array of integers that return the status of each page. The array contains valid values only if @@ -102,7 +102,7 @@ did not return an error. Preinitialization of the array to a value which cannot represent a real numa node or valid error of status array could help to identify pages that have been migrated. -.PP +.P .I flags specify what types of pages to move. .B MPOL_MF_MOVE @@ -214,7 +214,7 @@ Linux 2.6.18. .SH NOTES For information on library support, see .BR numa (7). -.PP +.P Use .BR get_mempolicy (2) with the @@ -225,7 +225,7 @@ flag to obtain the set of nodes that are allowed by the current cpuset. Note that this information is subject to change at any time by manual or automatic reconfiguration of the cpuset. -.PP +.P Use of this function may result in pages whose location (node) violates the memory policy established for the specified addresses (See @@ -235,7 +235,7 @@ and/or the specified process (See That is, memory policy does not constrain the destination nodes used by .BR move_pages (). -.PP +.P The .I <numaif.h> header is not included with glibc, but requires installing diff --git a/man2/mprotect.2 b/man2/mprotect.2 index 22aa42b..91812f5 100644 --- a/man2/mprotect.2 +++ b/man2/mprotect.2 @@ -10,7 +10,7 @@ .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and .\" a much improved example program. .\" -.TH mprotect 2 2023-05-03 "Linux man-pages 6.05.01" +.TH mprotect 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mprotect, pkey_mprotect \- set protection on a region of memory .SH LIBRARY @@ -19,12 +19,12 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/mman.h> -.PP +.P .BI "int mprotect(void " addr [. len "], size_t " len ", int " prot ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sys/mman.h> -.PP +.P .BI "int pkey_mprotect(void " addr [. len "], size_t " len ", int " prot ", int " pkey ");" .fi .SH DESCRIPTION @@ -34,12 +34,12 @@ containing any part of the address range in the interval [\fIaddr\fP,\ \fIaddr\fP+\fIlen\fP\-1]. .I addr must be aligned to a page boundary. -.PP +.P If the calling process tries to access memory in a manner that violates the protections, then the kernel generates a .B SIGSEGV signal for the process. -.PP +.P .I prot is a combination of the following access flags: .B PROT_NONE @@ -74,7 +74,7 @@ This feature is specific to the PowerPC architecture (version 2.06 of the architecture specification adds the SAO CPU feature, and it is available on POWER 7 or PowerPC A2, for example). -.PP +.P Additionally (since Linux 2.6.0), .I prot can have one of the following flags set: @@ -100,7 +100,7 @@ that grows downward (which should be a stack segment or a segment mapped with the .B MAP_GROWSDOWN flag set). -.PP +.P Like .BR mprotect (), .BR pkey_mprotect () @@ -199,14 +199,14 @@ POSIX says that the behavior of is unspecified if it is applied to a region of memory that was not obtained via .BR mmap (2). -.PP +.P On Linux, it is always permissible to call .BR mprotect () on any address in a process's address space (except for the kernel vsyscall area). In particular, it can be used to change existing code mappings to be writable. -.PP +.P Whether .B PROT_EXEC has any effect different from @@ -220,12 +220,12 @@ specifying .B PROT_READ will implicitly add .BR PROT_EXEC . -.PP +.P On some hardware architectures (e.g., i386), .B PROT_WRITE implies .BR PROT_READ . -.PP +.P POSIX.1 says that an implementation may permit access other than that specified in .IR prot , @@ -234,7 +234,7 @@ but at a minimum can allow write access only if has been set, and must not allow any access if .B PROT_NONE has been set. -.PP +.P Applications should be careful when mixing use of .BR mprotect () and @@ -247,7 +247,7 @@ set to .B PROT_EXEC a pkey may be allocated and set on the memory implicitly by the kernel, but only when the pkey was 0 previously. -.PP +.P On systems that do not support protection keys in hardware, .BR pkey_mprotect () may still be used, but @@ -280,10 +280,10 @@ The program below demonstrates the use of The program allocates four pages of memory, makes the third of these pages read-only, and then executes a loop that walks upward through the allocated region modifying bytes. -.PP +.P An example of what we might see when running the program is the following: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man2/mq_getsetattr.2 b/man2/mq_getsetattr.2 index b47e264..0fca73b 100644 --- a/man2/mq_getsetattr.2 +++ b/man2/mq_getsetattr.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_getsetattr 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mq_getsetattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_getsetattr \- get/set message queue attributes .SH SYNOPSIS @@ -10,13 +10,13 @@ mq_getsetattr \- get/set message queue attributes .BR "#include <mqueue.h>" " /* Definition of " "struct mq_attr" " */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_mq_getsetattr, mqd_t " mqdes , .BI " const struct mq_attr *" newattr ", struct mq_attr *" oldattr ); .fi .SH DESCRIPTION Do not use this system call. -.PP +.P This is the low-level system call used to implement .BR mq_getattr (3) and diff --git a/man2/mremap.2 b/man2/mremap.2 index f2b2b98..aa635dd 100644 --- a/man2/mremap.2 +++ b/man2/mremap.2 @@ -8,7 +8,7 @@ .\" Update for Linux 1.3.87 and later .\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text. .\" -.TH mremap 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mremap 2 2024-01-16 "Linux man-pages 6.7" .SH NAME mremap \- remap a virtual memory address .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sys/mman.h> -.PP +.P .BI "void *mremap(void " old_address [. old_size "], size_t " old_size , .BI " size_t " new_size ", int " flags ", ... /* void *" new_address " */);" .fi @@ -27,7 +27,7 @@ Standard C library expands (or shrinks) an existing memory mapping, potentially moving it at the same time (controlled by the \fIflags\fP argument and the available virtual address space). -.PP +.P \fIold_address\fP is the old address of the virtual memory block that you want to expand (or shrink). Note that \fIold_address\fP has to be page @@ -41,11 +41,13 @@ An optional fifth argument, may be provided; see the description of .B MREMAP_FIXED below. -.PP +.P If the value of \fIold_size\fP is zero, and \fIold_address\fP refers to -a shareable mapping (see -.BR mmap (2) -.BR MAP_SHARED ), +a shareable mapping +(see the description of +.B MAP_SHARED +in +.BR mmap (2)), then .BR mremap () will create a new mapping of the same pages. @@ -57,7 +59,7 @@ below. If a new mapping is requested via this method, then the .B MREMAP_MAYMOVE flag must also be specified. -.PP +.P The \fIflags\fP bit-mask argument may be 0, or include the following flags: .TP .B MREMAP_MAYMOVE @@ -131,7 +133,7 @@ flag may be used to atomically move a mapping while leaving the source mapped. See NOTES for some possible applications of .BR MREMAP_DONTUNMAP . -.PP +.P If the memory segment specified by .I old_address and @@ -248,7 +250,7 @@ Linux. .\" 4.2BSD had a (never actually implemented) .\" .BR mremap (2) .\" call with completely different semantics. -.\" .PP +.\" .P Prior to glibc 2.4, glibc did not expose the definition of .BR MREMAP_FIXED , and the prototype for @@ -262,7 +264,7 @@ changes the mapping between virtual addresses and memory pages. This can be used to implement a very efficient .BR realloc (3). -.PP +.P In Linux, memory is divided into pages. A process has (one or) several linear virtual memory segments. @@ -276,7 +278,7 @@ if the memory is accessed incorrectly (e.g., writing to a read-only segment). Accessing virtual memory outside of the segments will also cause a segmentation violation. -.PP +.P If .BR mremap () is used to move or expand an area locked with @@ -321,7 +323,10 @@ if was zero and the mapping referred to by .I old_address was a private mapping -.RB ( mmap "(2) " MAP_PRIVATE ), +(see the description of +.B MAP_PRIVATE +in +.BR mmap (2)), .BR mremap () created a new private mapping unrelated to the original mapping. This behavior was unintended @@ -344,7 +349,7 @@ in this scenario. .BR sbrk (2), .BR malloc (3), .BR realloc (3) -.PP +.P Your favorite text book on operating systems for more information on paged memory (e.g., \fIModern Operating Systems\fP by Andrew S.\& Tanenbaum, diff --git a/man2/msgctl.2 b/man2/msgctl.2 index b905b0f..27aca82 100644 --- a/man2/msgctl.2 +++ b/man2/msgctl.2 @@ -16,7 +16,7 @@ .\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions .\" 2018-03-20, dbueso: Added MSG_STAT_ANY description. .\" -.TH msgctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH msgctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME msgctl \- System V message control operations .SH LIBRARY @@ -25,20 +25,20 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/msg.h> -.PP -.BI "int msgctl(int " msqid ", int " cmd ", struct msqid_ds *" buf ); +.P +.BI "int msgctl(int " msqid ", int " op ", struct msqid_ds *" buf ); .fi .SH DESCRIPTION .BR msgctl () performs the control operation specified by -.I cmd +.I op on the System\ V message queue with identifier .IR msqid . -.PP +.P The .I msqid_ds data structure is defined in \fI<sys/msg.h>\fP as follows: -.PP +.P .in +4n .EX struct msqid_ds { @@ -55,7 +55,7 @@ struct msqid_ds { }; .EE .in -.PP +.P The fields of the .I msqid_ds structure are as follows: @@ -102,13 +102,13 @@ system call. ID of the process that performed the last .BR msgrcv (2) system call. -.PP +.P The .I ipc_perm structure is defined as follows (the highlighted fields are settable using .BR IPC_SET ): -.PP +.P .in +4n .EX struct ipc_perm { @@ -122,7 +122,7 @@ struct ipc_perm { }; .EE .in -.PP +.P The least significant 9 bits of the .I mode field of the @@ -138,11 +138,11 @@ l l. 0004 Read by others 0002 Write by others .TE -.PP +.P Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. -.PP +.P Valid values for -.I cmd +.I op are: .TP .B IPC_STAT @@ -312,7 +312,7 @@ or .B MSG_STAT_ANY operation returns the identifier of the queue whose index was given in .IR msqid . -.PP +.P On failure, \-1 is returned and .I errno is set to indicate the error. @@ -320,7 +320,7 @@ is set to indicate the error. .TP .B EACCES The argument -.I cmd +.I op is equal to .B IPC_STAT or @@ -333,7 +333,7 @@ capability in the user namespace that governs its IPC namespace. .TP .B EFAULT The argument -.I cmd +.I op has the value .B IPC_SET or @@ -347,7 +347,7 @@ The message queue was removed. .TP .B EINVAL Invalid value for -.I cmd +.I op or .IR msqid . Or: for a @@ -358,7 +358,7 @@ referred to an array slot that is currently unused. .TP .B EPERM The argument -.I cmd +.I op has the value .B IPC_SET or @@ -389,7 +389,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. .\" SVID does not document the EIDRM error condition. -.PP +.P Various fields in the \fIstruct msqid_ds\fP were typed as .I short @@ -402,7 +402,7 @@ a recompilation under glibc-2.1.91 or later should suffice. (The kernel distinguishes old and new calls by an .B IPC_64 flag in -.IR cmd .) +.IR op .) .SH NOTES The .BR IPC_INFO , diff --git a/man2/msgget.2 b/man2/msgget.2 index 0774f49..4a871d8 100644 --- a/man2/msgget.2 +++ b/man2/msgget.2 @@ -12,7 +12,7 @@ .\" Language and formatting clean-ups .\" Added notes on /proc files .\" -.TH msgget 2 2023-03-30 "Linux man-pages 6.05.01" +.TH msgget 2 2023-10-31 "Linux man-pages 6.7" .SH NAME msgget \- get a System V message queue identifier .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/msg.h> -.PP +.P .BI "int msgget(key_t " key ", int " msgflg ); .fi .SH DESCRIPTION @@ -39,7 +39,7 @@ is zero and does not have the value .BR IPC_PRIVATE ), or to create a new set. -.PP +.P A new message queue is created if .I key has the value @@ -54,7 +54,7 @@ exists, and .B IPC_CREAT is specified in .IR msgflg . -.PP +.P If .I msgflg specifies both @@ -73,7 +73,7 @@ set to .B O_CREAT | O_EXCL for .BR open (2).) -.PP +.P Upon creation, the least significant bits of the argument .I msgflg define the permissions of the message queue. @@ -83,7 +83,7 @@ as the permissions specified for the argument of .BR open (2). (The execute permissions are not used.) -.PP +.P If a new message queue is created, then its associated data structure .I msqid_ds @@ -120,7 +120,7 @@ is set to the current time. .I msg_qbytes is set to the system limit .BR MSGMNB . -.PP +.P If the message queue already exists the permissions are verified, and a check is made to see if it is marked for destruction. @@ -187,7 +187,7 @@ If this special value is used for the system call ignores everything but the least significant 9 bits of .I msgflg and creates a new message queue (on success). -.PP +.P The following is a system limit on message queue resources affecting a .BR msgget () call: diff --git a/man2/msgop.2 b/man2/msgop.2 index 381875e..e09c632 100644 --- a/man2/msgop.2 +++ b/man2/msgop.2 @@ -17,7 +17,7 @@ .\" Language and formatting clean-ups .\" Added notes on /proc files .\" -.TH MSGOP 2 2023-05-03 "Linux man-pages 6.05.01" +.TH MSGOP 2 2023-10-31 "Linux man-pages 6.7" .SH NAME msgrcv, msgsnd \- System V message queue operations .SH LIBRARY @@ -26,10 +26,10 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/msg.h> -.PP +.P .BI "int msgsnd(int " msqid ", const void " msgp [. msgsz "], size_t " msgsz , .BI " int " msgflg ); -.PP +.P .BI "ssize_t msgrcv(int " msqid ", void " msgp [. msgsz "], size_t " msgsz \ ", long " msgtyp , .BI " int " msgflg ); @@ -43,12 +43,12 @@ system calls are used to send messages to, and receive messages from, a System\ V message queue. The calling process must have write permission on the message queue in order to send a message, and read permission to receive a message. -.PP +.P The .I msgp argument is a pointer to a caller-defined structure of the following general form: -.PP +.P .in +4n .EX struct msgbuf { @@ -57,7 +57,7 @@ struct msgbuf { }; .EE .in -.PP +.P The .I mtext field is an array (or other structure) whose size is specified by @@ -82,7 +82,7 @@ system call appends a copy of the message pointed to by to the message queue whose identifier is specified by .IR msqid . -.PP +.P If sufficient space is available in the queue, .BR msgsnd () succeeds immediately. @@ -109,7 +109,7 @@ This check is necessary to prevent an unlimited number of zero-length messages being placed on the queue. Although such messages contain no data, they nevertheless consume (locked) kernel memory. -.PP +.P If insufficient space is available in the queue, then the default behavior of .BR msgsnd () @@ -120,7 +120,7 @@ is specified in .IR msgflg , then the call instead fails with the error .BR EAGAIN . -.PP +.P A blocked .BR msgsnd () call may also fail if: @@ -143,7 +143,7 @@ is never automatically restarted after being interrupted by a signal handler, regardless of the setting of the .B SA_RESTART flag when establishing a signal handler.) -.PP +.P Upon successful completion the message queue data structure is updated as follows: .IP \[bu] 3 @@ -163,7 +163,7 @@ system call removes a message from the queue specified by and places it in the buffer pointed to by .IR msgp . -.PP +.P The argument .I msgsz specifies the maximum size in bytes for the member @@ -189,7 +189,7 @@ the system call fails returning \-1 with .I errno set to .BR E2BIG . -.PP +.P Unless .B MSG_COPY is specified in @@ -225,7 +225,7 @@ then the first message in the queue with the lowest type less than or equal to the absolute value of .I msgtyp will be read. -.PP +.P The .I msgflg argument is a bit mask constructed by ORing together zero or more @@ -279,7 +279,7 @@ from To truncate the message text if longer than .I msgsz bytes. -.PP +.P If no message of the requested type is available and .B IPC_NOWAIT isn't specified in @@ -304,7 +304,7 @@ is never automatically restarted after being interrupted by a signal handler, regardless of the setting of the .B SA_RESTART flag when establishing a signal handler.) -.PP +.P Upon successful completion the message queue data structure is updated as follows: .IP @@ -372,7 +372,7 @@ value (less than 0 or greater than the system value The system does not have enough memory to make a copy of the message pointed to by .IR msgp . -.PP +.P .BR msgrcv () can fail with the following errors: .TP @@ -451,7 +451,7 @@ and this kernel was configured without .BR CONFIG_CHECKPOINT_RESTORE . .SH STANDARDS POSIX.1-2008. -.PP +.P The .B MSG_EXCEPT and @@ -463,7 +463,7 @@ their definitions can be obtained by defining the feature test macro. .SH HISTORY POSIX.1-2001, SVr4. -.PP +.P The .I msgp argument is declared as \fIstruct msgbuf\ *\fP in @@ -495,7 +495,7 @@ using the .BR msgctl (2) .B IPC_SET operation. -.PP +.P The implementation has no intrinsic system-wide limits on the number of message headers .RB ( MSGTQL ) @@ -521,7 +521,7 @@ of whether that message was at the ordinal position This bug is fixed .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c in Linux 3.14. -.PP +.P Specifying both .B MSG_COPY and @@ -542,18 +542,18 @@ The program below demonstrates the use of .BR msgsnd () and .BR msgrcv (). -.PP +.P The example program is first run with the \fB\-s\fP option to send a message and then run again with the \fB\-r\fP option to receive a message. -.PP +.P The following shell session shows a sample run of the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out \-s" sent: a message at Wed Mar 4 16:25:45 2015 -.PP +.P .RB "$" " ./a.out \-r" message received: a message at Wed Mar 4 16:25:45 2015 .EE diff --git a/man2/msync.2 b/man2/msync.2 index baa328d..64dffbd 100644 --- a/man2/msync.2 +++ b/man2/msync.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH msync 2 2023-03-30 "Linux man-pages 6.05.01" +.TH msync 2 2023-10-31 "Linux man-pages 6.7" .SH NAME msync \- synchronize a file with a memory map .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/mman.h> -.PP +.P .BI "int msync(void " addr [. length "], size_t " length ", int " flags ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ corresponds to the memory area starting at and having length .I length is updated. -.PP +.P The .I flags argument should specify exactly one of @@ -112,14 +112,14 @@ in POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P This call was introduced in Linux 1.3.21, and then used .B EFAULT instead of .BR ENOMEM . In Linux 2.4.19, this was changed to the POSIX value .BR ENOMEM . -.PP +.P On POSIX systems on which .BR msync () is available, both @@ -136,5 +136,5 @@ to a value greater than 0. .\" glibc defines them to 1. .SH SEE ALSO .BR mmap (2) -.PP +.P B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391. diff --git a/man2/nanosleep.2 b/man2/nanosleep.2 index 4693dc8..61242ea 100644 --- a/man2/nanosleep.2 +++ b/man2/nanosleep.2 @@ -12,7 +12,7 @@ .\" NOTES: describe case where clock_nanosleep() can be preferable. .\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP .\" Replace crufty discussion of HZ with a pointer to time(7). -.TH nanosleep 2 2023-03-30 "Linux man-pages 6.05.01" +.TH nanosleep 2 2024-03-03 "Linux man-pages 6.7" .SH NAME nanosleep \- high-resolution sleep .SH LIBRARY @@ -21,16 +21,16 @@ Standard C library .SH SYNOPSIS .nf .B #include <time.h> -.PP -.BI "int nanosleep(const struct timespec *" req , +.P +.BI "int nanosleep(const struct timespec *" duration , .BI " struct timespec *_Nullable " rem ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR nanosleep (): .nf _POSIX_C_SOURCE >= 199309L @@ -39,11 +39,11 @@ Feature Test Macro Requirements for glibc (see .BR nanosleep () suspends the execution of the calling thread until either at least the time specified in -.I *req +.I *duration has elapsed, or the delivery of a signal that triggers the invocation of a handler in the calling thread or that terminates the process. -.PP +.P If the call is interrupted by a signal handler, .BR nanosleep () returns \-1, sets @@ -60,14 +60,14 @@ The value of can then be used to call .BR nanosleep () again and complete the specified pause (but see NOTES). -.PP +.P The .BR timespec (3) structure is used to specify intervals of time with nanosecond precision. -.PP +.P The value of the nanoseconds field must be in the range [0, 999999999]. -.PP +.P Compared to .BR sleep (3) and @@ -80,7 +80,7 @@ does not interact with signals; and it makes the task of resuming a sleep that has been interrupted by a signal handler easier. .SH RETURN VALUE -On successfully sleeping for the requested interval, +On successfully sleeping for the requested duration, .BR nanosleep () returns 0. If the call is interrupted by a signal handler or encounters an error, @@ -128,7 +128,7 @@ says that discontinuous changes in should not affect .BR nanosleep (): .RS -.PP +.P Setting the value of the .B CLOCK_REALTIME clock via @@ -138,14 +138,15 @@ have no effect on threads that are blocked waiting for a relative time service based upon this clock, including the .BR nanosleep () function; ... -Consequently, these time services shall expire when the requested relative -interval elapses, independently of the new or old value of the clock. +Consequently, +these time services shall expire when the requested duration elapses, +independently of the new or old value of the clock. .RE .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P In order to support applications requiring much more precise pauses (e.g., in order to control some time-critical hardware), .BR nanosleep () @@ -158,14 +159,14 @@ or This special extension was removed in Linux 2.5.39, and is thus not available in Linux 2.6.0 and later kernels. .SH NOTES -If the interval specified in -.I req +If the +.I duration is not an exact multiple of the granularity underlying clock (see .BR time (7)), then the interval will be rounded up to the next multiple. Furthermore, after the sleep completes, there may still be a delay before the CPU becomes free to once again execute the calling thread. -.PP +.P The fact that .BR nanosleep () sleeps for a relative interval can be problematic if the call @@ -194,7 +195,7 @@ To avoid such problems, use with the .B TIMER_ABSTIME flag to sleep to an absolute deadline. -.PP +.P In Linux 2.4, if .BR nanosleep () is stopped by a signal (e.g., diff --git a/man2/nfsservctl.2 b/man2/nfsservctl.2 index 5267f81..c0d4965 100644 --- a/man2/nfsservctl.2 +++ b/man2/nfsservctl.2 @@ -2,7 +2,7 @@ .\" This text is in the public domain. .\" %%%LICENSE_END .\" -.TH nfsservctl 2 2023-05-03 "Linux man-pages 6.05.01" +.TH nfsservctl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME nfsservctl \- syscall interface to kernel nfs daemon .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <linux/nfsd/syscall.h> -.PP +.P .BI "long nfsservctl(int " cmd ", struct nfsctl_arg *" argp , .BI " union nfsctl_res *" resp ); .fi @@ -22,7 +22,7 @@ It has been replaced by a set of files in the .I nfsd filesystem; see .BR nfsd (7). -.PP +.P .in +4n .EX /* diff --git a/man2/nice.2 b/man2/nice.2 index d26a1be..3e5854b 100644 --- a/man2/nice.2 +++ b/man2/nice.2 @@ -8,7 +8,7 @@ .\" Modified 2001-06-04 by aeb .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH nice 2 2023-03-30 "Linux man-pages 6.05.01" +.TH nice 2 2023-10-31 "Linux man-pages 6.7" .SH NAME nice \- change process priority .SH LIBRARY @@ -17,15 +17,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int nice(int " inc ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR nice (): .nf _XOPEN_SOURCE @@ -38,10 +38,10 @@ adds .I inc to the nice value for the calling thread. (A higher nice value means a lower priority.) -.PP +.P The range of the nice value is +19 (low priority) to \-20 (high priority). Attempts to set a nice value outside the range are clamped to the range. -.PP +.P Traditionally, only a privileged process could lower the nice value (i.e., set a higher priority). However, since Linux 2.6.12, an unprivileged process can decrease @@ -55,7 +55,7 @@ On success, the new nice value is returned (but see NOTES below). On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P A successful call can legitimately return \-1. To detect an error, set .I errno @@ -85,7 +85,7 @@ However, the raw Linux system call returns 0 on success. Likewise, the .BR nice () wrapper function provided in glibc 2.2.3 and earlier returns 0 on success. -.PP +.P Since glibc 2.2.4, the .BR nice () wrapper function provided by glibc provides conformance to POSIX.1 by calling @@ -101,7 +101,7 @@ POSIX.1-2001, SVr4, 4.3BSD. .SH NOTES For further details on the nice value, see .BR sched (7). -.PP +.P .IR Note : the addition of the "autogroup" feature in Linux 2.6.38 means that the nice value no longer has its traditional effect in many circumstances. diff --git a/man2/open.2 b/man2/open.2 index 52286f6..a6982fa 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -28,7 +28,7 @@ .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and .\" O_TTYINIT. Eventually these may need to be documented. --mtk .\" -.TH open 2 2023-05-20 "Linux man-pages 6.05.01" +.TH open 2 2024-01-16 "Linux man-pages 6.7" .SH NAME open, openat, creat \- open and possibly create a file .SH LIBRARY @@ -37,25 +37,27 @@ Standard C library .SH SYNOPSIS .nf .B #include <fcntl.h> -.PP +.P .BI "int open(const char *" pathname ", int " flags ", ..." .BI " \fR/*\fP mode_t " mode " \fR*/\fP );" -.PP +.P .BI "int creat(const char *" pathname ", mode_t " mode ); -.PP +.P .BI "int openat(int " dirfd ", const char *" pathname ", int " flags ", ..." .BI " \fR/*\fP mode_t " mode " \fR*/\fP );" -.PP -/* Documented separately, in \fBopenat2\fP(2): */ +.P +/* Documented separately, in \c +.BR openat2 (2):\c +\& */ .BI "int openat2(int " dirfd ", const char *" pathname , .BI " const struct open_how *" how ", size_t " size ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR openat (): .nf Since glibc 2.10: @@ -75,18 +77,23 @@ is specified in .IR flags ) be created by .BR open (). -.PP +.P The return value of .BR open () is a file descriptor, a small, nonnegative integer that is an index to an entry in the process's table of open file descriptors. The file descriptor is used in subsequent system calls -.RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2), -etc.) to refer to the open file. +(\c +.BR read (2), +.BR write (2), +.BR lseek (2), +.BR fcntl (2), +etc.) +to refer to the open file. The file descriptor returned by a successful call will be the lowest-numbered file descriptor not currently open for the process. -.PP +.P By default, the new file descriptor is set to remain open across an .BR execve (2) (i.e., the @@ -98,7 +105,7 @@ is initially disabled); the flag, described below, can be used to change this default. The file offset is set to the beginning of the file (see .BR lseek (2)). -.PP +.P A call to .BR open () creates a new @@ -111,7 +118,7 @@ this reference is unaffected if .I pathname is subsequently removed or modified to refer to a different file. For further details on open file descriptions, see NOTES. -.PP +.P The argument .I flags must include one of the following @@ -119,7 +126,7 @@ must include one of the following .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR . These request opening the file read-only, write-only, or read/write, respectively. -.PP +.P In addition, zero or more file creation flags and file status flags can be bitwise ORed @@ -159,7 +166,7 @@ The file status flags can be retrieved and (in some cases) modified; see .BR fcntl (2) for details. -.PP +.P The full list of file creation flags and file status flags is as follows: .TP .B O_APPEND @@ -907,7 +914,7 @@ The system call operates in exactly the same way as .BR open (), except for the differences described here. -.PP +.P The .I dirfd argument is used in conjunction with the @@ -948,7 +955,7 @@ must be a directory that was opened for reading or using the .B O_PATH flag. -.PP +.P If the pathname given in .I pathname is relative, and @@ -1309,7 +1316,7 @@ Regardless of whether an implementation supports this option, it must at least support the use of .B O_SYNC for regular files. -.PP +.P Linux implements .B O_SYNC and @@ -1324,7 +1331,7 @@ to have the same value as is defined in the Linux header file .I <asm/fcntl.h> on HP PA-RISC, but it is not used.) -.PP +.P .B O_SYNC provides synchronized I/O .I file @@ -1342,7 +1349,7 @@ to allow a subsequent read operation to complete successfully. Data integrity completion can reduce the number of disk operations that are required for applications that don't need the guarantees of file integrity completion. -.PP +.P To understand the difference between the two types of completion, consider two pieces of file metadata: the file last modification timestamp @@ -1359,7 +1366,7 @@ would only guarantee to flush updates to the file length metadata (whereas .B O_SYNC would also always flush the last modification timestamp metadata). -.PP +.P Before Linux 2.6.33, Linux implemented only the .B O_SYNC flag for @@ -1371,7 +1378,7 @@ integrity completion (i.e., .B O_SYNC was actually implemented as the equivalent of .BR O_DSYNC ). -.PP +.P Since Linux 2.6.33, proper .B O_SYNC support is provided. @@ -1408,10 +1415,10 @@ For certain architectures, this is also true before glibc 2.26. .TQ .BR openat () POSIX.1-2008. -.PP +.P .BR openat2 (2) Linux. -.PP +.P The .BR O_DIRECT , .BR O_NOATIME , @@ -1422,7 +1429,7 @@ flags are Linux-specific. One must define .B _GNU_SOURCE to obtain their definitions. -.PP +.P The .BR O_CLOEXEC , .BR O_DIRECTORY , @@ -1457,7 +1464,7 @@ For example, this may be used to open a device in order to get a file descriptor for use with .BR ioctl (2). -.PP +.P Note that .BR open () can open device special files, but @@ -1465,7 +1472,7 @@ can open device special files, but cannot create them; use .BR mknod (2) instead. -.PP +.P If the file is newly created, its .IR st_atime , .IR st_ctime , @@ -1488,7 +1495,7 @@ flag, its and .I st_mtime fields are set to the current time. -.PP +.P The files in the .IR /proc/ pid /fd directory show the open file descriptors of the process with the PID @@ -1499,7 +1506,7 @@ directory show even more information about these file descriptors. See .BR proc (5) for further details of both of these directories. -.PP +.P The Linux header file .B <asm/fcntl.h> doesn't define @@ -1517,7 +1524,7 @@ variously also called an "open file object", a "file handle", an "open file table entry", or\[em]in kernel-developer parlance\[em]a .IR "struct file" . -.PP +.P When a file descriptor is duplicated (using .BR dup (2) or similar), @@ -1530,13 +1537,13 @@ a child process created via .BR fork (2) inherits duplicates of its parent's file descriptors, and those duplicates refer to the same open file descriptions. -.PP +.P Each .BR open () of a file creates a new open file description; thus, there may be multiple open file descriptions corresponding to a file inode. -.PP +.P On Linux, one can use the .BR kcmp (2) .B KCMP_FILE @@ -1548,7 +1555,7 @@ refer to the same open file description. There are many infelicities in the protocol underlying NFS, affecting amongst others .BR O_SYNC " and " O_NDELAY . -.PP +.P On NFS filesystems with UID mapping enabled, .BR open () may @@ -1587,7 +1594,7 @@ In other words, the combination .B "O_RDONLY | O_WRONLY" is a logical error, and certainly does not have the same meaning as .BR O_RDWR . -.PP +.P Linux reserves the special, nonstandard access mode 3 (binary 11) in .I flags to mean: @@ -1639,7 +1646,7 @@ address two problems with the older interfaces that preceded them. Here, the explanation is in terms of the .BR openat () call, but the rationale is analogous for the other interfaces. -.PP +.P First, .BR openat () allows an application to avoid race conditions that could @@ -1680,7 +1687,7 @@ even if the directory is renamed; and the open file descriptor prevents the underlying filesystem from being dismounted, just as when a process has a current working directory on a filesystem. -.PP +.P Second, .BR openat () allows the implementation of a per-thread "current working @@ -1689,7 +1696,7 @@ directory", via file descriptor(s) maintained by the application. on the use of .IR /proc/self/fd/ dirfd, but less efficiently.) -.PP +.P The .I dirfd argument for these APIs can be obtained by using @@ -1705,7 +1712,7 @@ Alternatively, such a file descriptor can be obtained by applying .BR dirfd (3) to a directory stream created using .BR opendir (3). -.PP +.P When these APIs are given a .I dirfd argument of @@ -1733,7 +1740,7 @@ I/Os also varies; they can either fail with .B EINVAL or fall back to buffered I/O. -.PP +.P Since Linux 6.1, .B O_DIRECT support and alignment restrictions for a file can be queried using @@ -1746,7 +1753,7 @@ Support for varies by filesystem; see .BR statx (2). -.PP +.P Some filesystems provide their own interfaces for querying .B O_DIRECT alignment restrictions, @@ -1756,7 +1763,7 @@ operation in .BR xfsctl (3). .B STATX_DIOALIGN should be used instead when it is available. -.PP +.P If none of the above is available, then direct I/O support and alignment restrictions can only be assumed from known characteristics of the filesystem, @@ -1775,13 +1782,13 @@ A block device's logical block size can be determined using the .BR ioctl (2) .B BLKSSZGET operation or from the shell using the command: -.PP +.P .in +4n .EX blockdev \-\-getss .EE .in -.PP +.P .B O_DIRECT I/Os should never be run concurrently with the .BR fork (2) @@ -1815,7 +1822,7 @@ with ensuring that it will not be available to the child after .BR fork (2). -.PP +.P The .B O_DIRECT flag was introduced in SGI IRIX, where it has alignment @@ -1825,7 +1832,7 @@ IRIX has also a call to query appropriate alignments, and sizes. FreeBSD 4.x introduced a flag of the same name, but without alignment restrictions. -.PP +.P .B O_DIRECT support was added in Linux 2.4.10. Older Linux kernels simply ignore this flag. @@ -1834,7 +1841,7 @@ Some filesystems may not implement the flag, in which case fails with the error .B EINVAL if it is used. -.PP +.P Applications should avoid mixing .B O_DIRECT and normal I/O to the same file, @@ -1845,7 +1852,7 @@ using either mode alone. Likewise, applications should avoid mixing .BR mmap (2) of files with direct I/O to the same files. -.PP +.P The behavior of .B O_DIRECT with NFS will differ from local filesystems. @@ -1867,7 +1874,7 @@ in the event of server power failure. The Linux NFS client places no alignment restrictions on .B O_DIRECT I/O. -.PP +.P In summary, .B O_DIRECT is a potentially powerful tool that should be used with caution. @@ -1885,7 +1892,7 @@ use to enable this flag. .\" FIXME . Check bugzilla report on open(O_ASYNC) .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 -.PP +.P One must check for two different error codes, .B EISDIR and @@ -1893,7 +1900,7 @@ and when trying to determine whether the kernel supports .B O_TMPFILE functionality. -.PP +.P When both .B O_CREAT and diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2 index b5e3d75..26bb9c2 100644 --- a/man2/open_by_handle_at.2 +++ b/man2/open_by_handle_at.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH open_by_handle_at 2 2023-05-03 "Linux man-pages 6.05.01" +.TH open_by_handle_at 2 2023-10-31 "Linux man-pages 6.7" .SH NAME name_to_handle_at, open_by_handle_at \- obtain handle for a pathname and open file via a handle @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <fcntl.h> -.PP +.P .BI "int name_to_handle_at(int " dirfd ", const char *" pathname , .BI " struct file_handle *" handle , .BI " int *" mount_id ", int " flags ); @@ -48,7 +48,7 @@ arguments. The file handle is returned via the argument .IR handle , which is a pointer to a structure of the following form: -.PP +.P .in +4n .EX struct file_handle { @@ -59,7 +59,7 @@ struct file_handle { }; .EE .in -.PP +.P It is the caller's responsibility to allocate the structure with a size large enough to hold the handle returned in .IR f_handle . @@ -78,7 +78,7 @@ Upon successful return, the .I handle_bytes field is updated to contain the number of bytes actually written to .IR f_handle . -.PP +.P The caller can discover the required size for the .I file_handle structure by making a call in which @@ -100,7 +100,7 @@ This case can be detected when the error is returned without .I handle_bytes being increased. -.PP +.P Other than the use of the .I handle_bytes field, the caller should treat the @@ -109,17 +109,44 @@ structure as an opaque data type: the .I handle_type and .I f_handle -fields are needed only by a subsequent call to +fields can be used in a subsequent call to .BR open_by_handle_at (). -.PP +The caller can also use the opaque +.I file_handle +to compare the identity of filesystem objects +that were queried at different times and possibly +at different paths. +The +.BR fanotify (7) +subsystem can report events +with an information record containing a +.I file_handle +to identify the filesystem object. +.P The .I flags argument is a bit mask constructed by ORing together zero or more of -.B AT_EMPTY_PATH +.BR AT_HANDLE_FID , +.BR AT_EMPTY_PATH , and .BR AT_SYMLINK_FOLLOW , described below. -.PP +.P +When +.I flags +contain the +.BR AT_HANDLE_FID " (since Linux 6.5)" +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8 +flag, the caller indicates that the returned +.I file_handle +is needed to identify the filesystem object, +and not for opening the file later, +so it should be expected that a subsequent call to +.BR open_by_handle_at () +with the returned +.I file_handle +may fail. +.P Together, the .I pathname and @@ -172,7 +199,7 @@ or .BR AT_FDCWD , meaning the current working directory, and a handle is returned for the file to which it refers. -.PP +.P The .I mount_id argument returns an identifier for the filesystem @@ -188,7 +215,7 @@ that file descriptor can be used in a subsequent call to is returned both for a successful call and for a call that results in the error .BR EOVERFLOW . -.PP +.P By default, .BR name_to_handle_at () does not dereference @@ -201,7 +228,7 @@ is specified in .I pathname is dereferenced if it is a symbolic link (so that the call returns a handle for the file referred to by the link). -.PP +.P .BR name_to_handle_at () does not trigger a mount when the final component of the pathname is an automount point. @@ -225,7 +252,7 @@ system call opens the file referred to by .IR handle , a file handle returned by a previous call to .BR name_to_handle_at (). -.PP +.P The .I mount_fd argument is a file descriptor for any object (file, directory, etc.) @@ -235,7 +262,7 @@ should be interpreted. The special value .B AT_FDCWD can be specified, meaning the current working directory of the caller. -.PP +.P The .I flags argument @@ -248,7 +275,7 @@ refers to a symbolic link, the caller must specify the flag, and the symbolic link is not dereferenced; the .B O_NOFOLLOW flag, if specified, is ignored. -.PP +.P The caller must have the .B CAP_DAC_READ_SEARCH capability to invoke @@ -260,7 +287,7 @@ returns 0, and .BR open_by_handle_at () returns a file descriptor (a nonnegative integer). -.PP +.P In the event of an error, both system calls return \-1 and set .I errno to indicate the error. @@ -271,7 +298,7 @@ and can fail for the same errors as .BR openat (2). In addition, they can fail with the errors noted below. -.PP +.P .BR name_to_handle_at () can fail with the following errors: .TP @@ -322,7 +349,7 @@ When this error occurs, is updated to indicate the required size for the handle. .\" .\" -.PP +.P .BR open_by_handle_at () can fail with the following errors: .TP @@ -363,8 +390,14 @@ capability. .B ESTALE The specified .I handle -is not valid. +is not valid for opening a file. This error will occur if, for example, the file has been deleted. +This error can also occur if the +.I handle +was acquired using the +.B AT_HANDLE_FID +flag and the filesystem does not support +.BR open_by_handle_at (). .SH VERSIONS FreeBSD has a broadly similar pair of system calls in the form of .BR getfh () @@ -380,20 +413,23 @@ A file handle can be generated in one process using .BR name_to_handle_at () and later used in a different process that calls .BR open_by_handle_at (). -.PP +.P Some filesystem don't support the translation of pathnames to file handles, for example, .IR /proc , .IR /sys , and various network filesystems. -.PP +Some filesystems support the translation of pathnames to +file handles, but do not support using those file handles in +.BR open_by_handle_at (). +.P A file handle may become invalid ("stale") if a file is deleted, or for other filesystem-specific reasons. Invalid handles are notified by an .B ESTALE error from .BR open_by_handle_at (). -.PP +.P These system calls are designed for use by user-space file servers. For example, a user-space NFS server might generate a file handle and pass it to an NFS client. @@ -403,7 +439,7 @@ it could pass the handle back to the server. .\" "Open by handle" - Jonathan Corbet, 2010-02-23 This sort of functionality allows a user-space file server to operate in a stateless fashion with respect to the files it serves. -.PP +.P If .I pathname refers to a symbolic link and @@ -439,7 +475,7 @@ However, an application can use the information in the .I mountinfo record that corresponds to the mount ID to derive a persistent identifier. -.PP +.P For example, one can use the device name in the fifth field of the .I mountinfo record to search for the corresponding device UUID via the symbolic links in @@ -467,7 +503,7 @@ uses to obtain the file handle and mount ID for the file specified in its command-line argument; the handle and mount ID are written to standard output. -.PP +.P The second program .RI ( t_open_by_handle_at.c ) reads a mount ID and file handle from standard input. @@ -487,9 +523,9 @@ to find a record whose mount ID matches the mount ID read from standard input, and the mount directory specified in that record is opened. (These programs do not deal with the fact that mount IDs are not persistent.) -.PP +.P The following shell session demonstrates the use of these two programs: -.PP +.P .in +4n .EX $ \fBecho \[aq]Can you please think about it?\[aq] > cecilia.txt\fP @@ -501,7 +537,7 @@ Read 31 bytes $ \fBrm cecilia.txt\fP .EE .in -.PP +.P Now we delete and (quickly) re-create the file so that it has the same content and (by chance) the same inode. Nevertheless, @@ -510,7 +546,7 @@ Nevertheless, .\" counter that gets incremented in this case. recognizes that the original file referred to by the file handle no longer exists. -.PP +.P .in +4n .EX $ \fBstat \-\-printf="%i\en" cecilia.txt\fP # Display inode number @@ -739,7 +775,7 @@ main(int argc, char *argv[]) .BR blkid (8), .BR findfs (8), .BR mount (8) -.PP +.P The .I libblkid and diff --git a/man2/openat2.2 b/man2/openat2.2 index b98bbaf..4a19439 100644 --- a/man2/openat2.2 +++ b/man2/openat2.2 @@ -1,7 +1,7 @@ .\" Copyright (C) 2019 Aleksa Sarai <cyphar@cyphar.com> .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH openat2 2 2023-04-23 "Linux man-pages 6.05.01" +.TH openat2 2 2024-02-25 "Linux man-pages 6.7" .SH NAME openat2 \- open and possibly create a file (extended) .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .BR "#include <linux/openat2.h>" " /* Definition of " RESOLVE_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(SYS_openat2, int " dirfd ", const char *" pathname , .BI " struct open_how *" how ", size_t " size ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR openat2 (), @@ -30,7 +30,7 @@ The system call is an extension of .BR openat (2) and provides a superset of its functionality. -.PP +.P The .BR openat2 () system call opens the file specified by @@ -40,7 +40,7 @@ If the specified file does not exist, it may optionally (if is specified in .IR how.flags ) be created. -.PP +.P As with .BR openat (2), if @@ -64,7 +64,7 @@ in which case .I pathname is resolved relative to .IR dirfd ). -.PP +.P Rather than taking a single .I flags argument, an extensible structure (\fIhow\fP) is passed to allow for @@ -90,7 +90,7 @@ This argument is a pointer to an structure, described in .BR open_how (2type). -.PP +.P Any future extensions to .BR openat2 () will be implemented as new fields appended to the @@ -105,7 +105,7 @@ initialization. (See the "Extensibility" section of the .B NOTES for more detail on why this is necessary.) -.PP +.P The fields of the .I open_how structure are as follows: @@ -374,7 +374,7 @@ in the kernel's lookup cache. If any kind of revalidation or I/O is needed to satisfy the lookup, .BR openat2 () fails with the error -.B EAGAIN . +.BR EAGAIN . This is useful in providing a fast-path open that can be performed without resorting to thread offload, or other mechanisms that an application might use to offload slower operations. @@ -421,7 +421,7 @@ information. The caller should retry without .B RESOLVE_CACHED set in -.I how.resolve . +.IR how.resolve . .TP .B EINVAL An unknown flag or invalid value was specified in @@ -471,7 +471,7 @@ Linux. .SH HISTORY Linux 5.6. .\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179 -.PP +.P The semantics of .B RESOLVE_BENEATH were modeled after FreeBSD's @@ -495,7 +495,7 @@ This extensibility design is very similar to other system calls such as .BR perf_event_open (2), and .BR clone3 (2). -.PP +.P If we let .I usize be the size of the structure as specified by the user-space application, and @@ -538,7 +538,7 @@ If any unsupported extension fields are nonzero, then \-1 is returned and is set to .BR E2BIG . This provides forwards-compatibility. -.PP +.P Because the definition of .I struct open_how may change in the future (with new fields being added when system headers are @@ -548,18 +548,18 @@ to ensure that recompiling the program with new headers will not result in spurious errors at run time. The simplest way is to use a designated initializer: -.PP +.P .in +4n .EX struct open_how how = { .flags = O_RDWR, .resolve = RESOLVE_IN_ROOT }; .EE .in -.PP +.P or explicitly using .BR memset (3) or similar: -.PP +.P .in +4n .EX struct open_how how; @@ -568,7 +568,7 @@ how.flags = O_RDWR; how.resolve = RESOLVE_IN_ROOT; .EE .in -.PP +.P A user-space application that wishes to determine which extensions the running kernel supports can do so by conducting a binary search on .I size diff --git a/man2/outb.2 b/man2/outb.2 index 4a3f877..ce39f5a 100644 --- a/man2/outb.2 +++ b/man2/outb.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH outb 2 2023-03-30 "Linux man-pages 6.05.01" +.TH outb 2 2023-10-31 "Linux man-pages 6.7" .SH NAME outb, outw, outl, outsb, outsw, outsl, inb, inw, inl, insb, insw, insl, @@ -15,21 +15,21 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/io.h> -.PP +.P .BI "unsigned char inb(unsigned short " port ); .BI "unsigned char inb_p(unsigned short " port ); .BI "unsigned short inw(unsigned short " port ); .BI "unsigned short inw_p(unsigned short " port ); .BI "unsigned int inl(unsigned short " port ); .BI "unsigned int inl_p(unsigned short " port ); -.PP +.P .BI "void outb(unsigned char " value ", unsigned short " port ); .BI "void outb_p(unsigned char " value ", unsigned short " port ); .BI "void outw(unsigned short " value ", unsigned short " port ); .BI "void outw_p(unsigned short " value ", unsigned short " port ); .BI "void outl(unsigned int " value ", unsigned short " port ); .BI "void outl_p(unsigned int " value ", unsigned short " port ); -.PP +.P .BI "void insb(unsigned short " port ", void " addr [. count ], .BI " unsigned long " count ); .BI "void insw(unsigned short " port ", void " addr [. count ], @@ -48,18 +48,18 @@ This family of functions is used to do low-level port input and output. The out* functions do port output, the in* functions do port input; the b-suffix functions are byte-width and the w-suffix functions word-width; the _p-suffix functions pause until the I/O completes. -.PP +.P They are primarily designed for internal kernel use, but can be used from user space. .\" , given the following information .\" in addition to that given in .\" .BR outb (9). -.PP +.P You must compile with \fB\-O\fP or \fB\-O2\fP or similar. The functions are defined as inline macros, and will not be substituted in without optimization enabled, causing unresolved references at link time. -.PP +.P You use .BR ioperm (2) or alternatively diff --git a/man2/pause.2 b/man2/pause.2 index 0e7bbcd..59e9345 100644 --- a/man2/pause.2 +++ b/man2/pause.2 @@ -7,7 +7,7 @@ .\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) .\" Modified 2000 by aeb, following Michael Kerrisk .\" -.TH pause 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pause 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pause \- wait for signal .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B int pause(void); .fi .SH DESCRIPTION diff --git a/man2/pciconfig_read.2 b/man2/pciconfig_read.2 index 7913ba0..4c894aa 100644 --- a/man2/pciconfig_read.2 +++ b/man2/pciconfig_read.2 @@ -5,7 +5,7 @@ .\" May be freely distributed and modified. .\" %%%LICENSE_END .\" -.TH pciconfig_read 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pciconfig_read 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pciconfig_read, pciconfig_write, pciconfig_iobase \- pci device information handling @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <pci.h> -.PP +.P .BI "int pciconfig_read(unsigned long " bus ", unsigned long " dfn , .BI " unsigned long " off ", unsigned long " len , .BI " unsigned char *" buf ); diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index d9e7877..7af8e35 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -5,7 +5,7 @@ .\" This document is based on the perf_event.h header file, the .\" tools/perf/design.txt file, and a lot of bitter experience. .\" -.TH perf_event_open 2 2023-05-03 "Linux man-pages 6.05.01" +.TH perf_event_open 2 2023-11-19 "Linux man-pages 6.7" .SH NAME perf_event_open \- set up performance monitoring .SH LIBRARY @@ -17,12 +17,12 @@ Standard C library .BR "#include <linux/hw_breakpoint.h>" " /* Definition of " HW_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_perf_event_open, struct perf_event_attr *" attr , .BI " pid_t " pid ", int " cpu ", int " group_fd \ ", unsigned long " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR perf_event_open (), @@ -32,7 +32,12 @@ necessitating the use of Given a list of parameters, .BR perf_event_open () returns a file descriptor, for use in subsequent system calls -.RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)." +(\c +.BR read (2), +.BR mmap (2), +.BR prctl (2), +.BR fcntl (2), +etc.). .PP A call to .BR perf_event_open () @@ -41,14 +46,14 @@ information. Each file descriptor corresponds to one event that is measured; these can be grouped together to measure multiple events simultaneously. -.PP +.P Events can be enabled and disabled in two ways: via .BR ioctl (2) and via .BR prctl (2). When an event is disabled it does not count or generate overflows but does continue to exist and maintain its count value. -.PP +.P Events come in two flavors: counting and sampled. A .I counting @@ -95,7 +100,7 @@ value of less than 1. .TP .BR "pid == \-1" " and " "cpu == \-1" This setting is invalid and will return an error. -.PP +.P When .I pid is greater than zero, permission to perform this system call @@ -105,7 +110,7 @@ is governed by .B PTRACE_MODE_READ_REALCREDS check on older Linux versions; see .BR ptrace (2). -.PP +.P The .I group_fd argument allows event groups to be created. @@ -127,7 +132,7 @@ This means that the values of the member events can be meaningfully compared \[em]added, divided (to get ratios), and so on\[em] with each other, since they have counted events for the same set of executed instructions. -.PP +.P The .I flags argument is formed by ORing together zero or more of the following values: @@ -186,12 +191,12 @@ must be passed as the parameter. cgroup monitoring is available only for system-wide events and may therefore require extra permissions. -.PP +.P The .I perf_event_attr structure provides detailed configuration information for the event being created. -.PP +.P .in +4n .EX struct perf_event_attr { @@ -291,7 +296,7 @@ struct perf_event_attr { }; .EE .in -.PP +.P The fields of the .I perf_event_attr structure are described in more detail below: @@ -562,7 +567,7 @@ This counts context switches to a task in a different cgroup. In other words, if the next task is in the same cgroup, it won't count the switch. .RE -.PP +.P .RS If .I type @@ -575,7 +580,7 @@ can be obtained from under debugfs .I tracing/events/*/*/id if ftrace is enabled in the kernel. .RE -.PP +.P .RS If .I type @@ -586,7 +591,7 @@ To calculate the appropriate .I config value, use the following equation: .RS 4 -.PP +.P .in +4n .EX config = (perf_hw_cache_id) | @@ -594,7 +599,7 @@ config = (perf_hw_cache_id) | (perf_hw_cache_op_result_id << 16); .EE .in -.PP +.P where .I perf_hw_cache_id is one of: @@ -622,7 +627,7 @@ for measuring the branch prediction unit .\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477 for measuring local memory accesses .RE -.PP +.P and .I perf_hw_cache_op_id is one of: @@ -637,7 +642,7 @@ for write accesses .B PERF_COUNT_HW_CACHE_OP_PREFETCH for prefetch accesses .RE -.PP +.P and .I perf_hw_cache_op_result_id is one of: @@ -650,7 +655,7 @@ to measure accesses to measure misses .RE .RE -.PP +.P If .I type is @@ -666,7 +671,7 @@ The libpfm4 library can be used to translate from the name in the architectural manuals to the raw hex value .BR perf_event_open () expects in this field. -.PP +.P If .I type is @@ -675,7 +680,7 @@ then leave .I config set to zero. Its parameters are set in other places. -.PP +.P If .I type is @@ -698,7 +703,13 @@ and for more details. .RE .TP -.IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset +.I kprobe_func +.TQ +.I uprobe_path +.TQ +.I kprobe_addr +.TQ +.I probe_offset These fields describe the kprobe/uprobe for dynamic PMUs .B kprobe and @@ -721,7 +732,9 @@ use and .IR probe_offset . .TP -.IR sample_period ", " sample_freq +.I sample_period +.TQ +.I sample_freq A "sampling" event is one that generates an overflow notification every N events, where N is given by .IR sample_period . @@ -925,7 +938,7 @@ not both. It has the following format and the meaning of each field is dependent on the hardware implementation. -.PP +.P .in +4n .EX union perf_sample_weight { @@ -1354,7 +1367,9 @@ This enables synchronous signal delivery of .B SIGTRAP on event overflow. .TP -.IR wakeup_events ", " wakeup_watermark +.I wakeup_events +.TQ +.I wakeup_watermark This union sets how many samples .RI ( wakeup_events ) or bytes @@ -1400,7 +1415,7 @@ Count when we read or write the memory location. .TP .B HW_BREAKPOINT_X Count when we execute code at the memory location. -.PP +.P The values can be combined via a bitwise or, but the combination of .B HW_BREAKPOINT_R @@ -1474,7 +1489,7 @@ Branch target is in hypervisor. .TP .B PERF_SAMPLE_BRANCH_PLM_ALL A convenience value that is the three preceding values ORed together. -.PP +.P In addition to the privilege value, at least one or more of the following bits must be set. .TP @@ -1591,12 +1606,12 @@ The values that are there are specified by the field in the .I attr structure at open time. -.PP +.P If you attempt to read into a buffer that is not big enough to hold the data, the error .B ENOSPC results. -.PP +.P Here is the layout of the data returned by a read: .IP \[bu] 3 If @@ -1635,7 +1650,7 @@ struct read_format { }; .EE .in -.PP +.P The values read are as follows: .TP .I nr @@ -1644,7 +1659,9 @@ Available only if .B PERF_FORMAT_GROUP was specified. .TP -.IR time_enabled ", " time_running +.I time_enabled +.TQ +.I time_running Total time the event was enabled and running. Normally these values are the same. Multiplexing happens if the number of events is more than the @@ -1680,18 +1697,18 @@ mmap tracking) are logged into a ring-buffer. This ring-buffer is created and accessed through .BR mmap (2). -.PP +.P The mmap size should be 1+2\[ha]n pages, where the first page is a metadata page .RI ( "struct perf_event_mmap_page" ) that contains various bits of information such as where the ring-buffer head is. -.PP +.P Before Linux 2.6.39, there is a bug that means you must allocate an mmap ring buffer when sampling even if you do not plan to access it. -.PP +.P The structure of the first metadata mmap page is as follows: -.PP +.P .in +4n .EX struct perf_event_mmap_page { @@ -1729,7 +1746,7 @@ struct perf_event_mmap_page { } .EE .in -.PP +.P The following list describes the fields in the .I perf_event_mmap_page structure in more detail: @@ -1861,7 +1878,11 @@ count += pmc; .EE .in .TP -.IR time_shift ", " time_mult ", " time_offset +.I time_shift +.TQ +.I time_mult +.TQ +.I time_offset .IP If .IR cap_usr_time , @@ -1966,7 +1987,13 @@ where perf sample data begins. Contains the size of the perf sample region within the mmap buffer. .TP -.IR aux_head ", " aux_tail ", " aux_offset ", " aux_size " (since Linux 4.1)" +.I aux_head +.TQ +.I aux_tail +.TQ +.I aux_offset +.TQ +.I aux_size " (since Linux 4.1)" .\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff The AUX region allows .BR mmap (2)-ing @@ -2011,9 +2038,9 @@ rules as the previous described .I data_head and .IR data_tail . -.PP +.P The following 2^n ring-buffer pages have the layout described below. -.PP +.P If .I perf_event_attr.sample_id_all is set, then all event types will @@ -2027,9 +2054,9 @@ fields, that is, at the end of the payload. This allows a newer perf.data file to be supported by older perf tools, with the new optional fields being ignored. -.PP +.P The mmap values start with a header: -.PP +.P .in +4n .EX struct perf_event_header { @@ -2039,7 +2066,7 @@ struct perf_event_header { }; .EE .in -.PP +.P Below, we describe the .I perf_event_header fields in more detail. @@ -2080,7 +2107,7 @@ Sample happened in the guest kernel. .\" commit 39447b386c846bbf1c56f6403c5282837486200f Sample happened in guest user code. .RE -.PP +.P .RS Since the following three statuses are generated by different record types, they alias to the same bit: @@ -2109,7 +2136,7 @@ record is generated, this bit indicates that the context switch is away from the current process (instead of into the current process). .RE -.PP +.P .RS In addition, the following bits can be set: .TP @@ -2260,7 +2287,9 @@ struct { .EE .in .TP -.BR PERF_RECORD_THROTTLE ", " PERF_RECORD_UNTHROTTLE +.B PERF_RECORD_THROTTLE +.TQ +.B PERF_RECORD_UNTHROTTLE This record indicates a throttle/unthrottle event. .IP .in +4n @@ -2373,7 +2402,9 @@ If is enabled, then a 64-bit instruction pointer value is included. .TP -.IR pid ", " tid +.I pid +.TQ +.I tid If .B PERF_SAMPLE_TID is enabled, then a 32-bit process ID @@ -2412,7 +2443,9 @@ the actual ID is returned, not the group leader. This ID is the same as the one returned by .BR PERF_FORMAT_ID . .TP -.IR cpu ", " res +.I cpu +.TQ +.I res If .B PERF_SAMPLE_CPU is enabled, this is a 32-bit value indicating @@ -2436,7 +2469,9 @@ value used at .BR perf_event_open () time. .TP -.IR nr ", " ips[nr] +.I nr +.TQ +.I ips[nr] If .B PERF_SAMPLE_CALLCHAIN is enabled, then a 64-bit number is included @@ -2444,7 +2479,9 @@ which indicates how many following 64-bit instruction pointers will follow. This is the current callchain. .TP -.IR size ", " data[size] +.I size +.TQ +.I data[size] If .B PERF_SAMPLE_RAW is enabled, then a 32-bit value indicating size @@ -2456,7 +2493,9 @@ The ABI doesn't make any promises with respect to the stability of its content, it may vary depending on event, hardware, and kernel version. .TP -.IR bnr ", " lbr[bnr] +.I bnr +.TQ +.I lbr[bnr] If .B PERF_SAMPLE_BRANCH_STACK is enabled, then a 64-bit value indicating @@ -2490,10 +2529,10 @@ The branch was in an aborted transactional memory transaction. .\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f This reports the number of cycles elapsed since the previous branch stack update. -.PP +.P The entries are from most to least recent, so the first entry has the most recent branch. -.PP +.P Support for .IR mispred , .IR predicted , @@ -2501,13 +2540,15 @@ and .I cycles is optional; if not supported, those values will be 0. -.PP +.P The type of branches recorded is specified by the .I branch_sample_type field. .RE .TP -.IR abi ", " regs[weight(mask)] +.I abi +.TQ +.I regs[weight(mask)] If .B PERF_SAMPLE_REGS_USER is enabled, then the user CPU registers are recorded. @@ -2530,7 +2571,11 @@ The number of values is the number of bits set in the .I sample_regs_user bit mask. .TP -.IR size ", " data[size] ", " dyn_size +.I size +.TQ +.I data[size] +.TQ +.I dyn_size If .B PERF_SAMPLE_STACK_USER is enabled, then the user stack is recorded. @@ -2754,7 +2799,9 @@ the high 32 bits of the field by shifting right by and masking with the value .BR PERF_TXN_ABORT_MASK . .TP -.IR abi ", " regs[weight(mask)] +.I abi +.TQ +.I regs[weight(mask)] If .B PERF_SAMPLE_REGS_INTR is enabled, then the user CPU registers are recorded. @@ -3254,13 +3301,13 @@ and .B F_SETSIG operations in .BR fcntl (2). -.PP +.P Overflows are generated only by sampling events .RI ( sample_period must have a nonzero value). -.PP +.P There are two ways to generate overflow notifications. -.PP +.P The first is to set a .I wakeup_events or @@ -3270,7 +3317,7 @@ or bytes have been written to the mmap ring buffer. In this case, .B POLL_IN is indicated. -.PP +.P The other way is by use of the .B PERF_EVENT_IOC_REFRESH ioctl. @@ -3282,13 +3329,13 @@ once the counter reaches 0 .B POLL_HUP is indicated and the underlying event is disabled. -.PP +.P Refreshing an event group leader refreshes all siblings and refreshing with a parameter of 0 currently enables infinite refreshes; these behaviors are unsupported and should not be relied on. .\" See https://lkml.org/lkml/2011/5/24/337 -.PP +.P Starting with Linux 3.18, .\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883 .B POLL_HUP @@ -3302,12 +3349,12 @@ instruction to get low-latency reads without having to enter the kernel. Note that using .I rdpmc is not necessarily faster than other methods for reading event values. -.PP +.P Support for this can be detected with the .I cap_usr_rdpmc field in the mmap page; documentation on how to calculate event values can be found in that section. -.PP +.P Originally, when rdpmc support was enabled, any process (not just ones with an active perf event) could use the rdpmc instruction to access the counters. @@ -3567,10 +3614,10 @@ Maximum number of pages an unprivileged user can .BR mlock (2). The default is 516 (kB). .RE -.PP +.P Files in .I /sys/bus/event_source/devices/ -.PP +.P .RS 4 Since Linux 2.6.34, the kernel supports having multiple PMUs available for monitoring. @@ -3831,7 +3878,7 @@ The official way of knowing if support is enabled is checking for the existence of the file .IR /proc/sys/kernel/perf_event_paranoid . -.PP +.P .B CAP_PERFMON capability (since Linux 5.8) provides secure approach to performance monitoring and observability operations in a system @@ -3855,7 +3902,7 @@ option to is needed to properly get overflow signals in threads. This was introduced in Linux 2.6.32. .\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5 -.PP +.P Prior to Linux 2.6.33 (at least for x86), .\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1 the kernel did not check @@ -3865,40 +3912,40 @@ This means to see if a given set of events works you have to .BR perf_event_open (), start, then read before you know for sure you can get valid measurements. -.PP +.P Prior to Linux 2.6.34, .\" FIXME . cannot find a kernel commit for this one event constraints were not enforced by the kernel. In that case, some events would silently return "0" if the kernel scheduled them in an improper counter slot. -.PP +.P Prior to Linux 2.6.34, there was a bug when multiplexing where the wrong results could be returned. .\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8 -.PP +.P Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if "inherit" is enabled and many threads are started. .\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd -.PP +.P Prior to Linux 2.6.35, .\" commit 050735b08ca8a016bbace4445fa025b88fee770b .B PERF_FORMAT_GROUP did not work with attached processes. -.PP +.P There is a bug in the kernel code between Linux 2.6.36 and Linux 3.0 that ignores the "watermark" field and acts as if a wakeup_event was chosen if the union has a nonzero value in it. .\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02 -.PP +.P From Linux 2.6.31 to Linux 3.4, the .B PERF_IOC_FLAG_GROUP ioctl argument was broken and would repeatedly operate on the event specified rather than iterating across all sibling events in a group. .\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e -.PP +.P From Linux 3.4 to Linux 3.11, the mmap .\" commit fa7315871046b9a4c48627905691dbde57e51033 .I cap_usr_rdpmc @@ -3910,7 +3957,7 @@ Code should migrate to the new and .I cap_user_time fields instead. -.PP +.P Always double-check your results! Various generalized events have had wrong values. For example, retired branches measured @@ -3920,7 +3967,7 @@ the wrong thing on AMD machines until Linux 2.6.35. The following is a short example that measures the total instruction count of a call to .BR printf (3). -.PP +.P .\" SRC BEGIN (perf_event_open.c) .EX #include <linux/perf_event.h> @@ -3984,6 +4031,6 @@ main(void) .BR open (2), .BR prctl (2), .BR read (2) -.PP +.P .I Documentation/admin\-guide/perf\-security.rst in the kernel source tree diff --git a/man2/perfmonctl.2 b/man2/perfmonctl.2 index 2155bb4..fac1aa1 100644 --- a/man2/perfmonctl.2 +++ b/man2/perfmonctl.2 @@ -4,17 +4,17 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH perfmonctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH perfmonctl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME perfmonctl \- interface to IA-64 performance monitoring unit .SH SYNOPSIS .nf .B #include <syscall.h> .B #include <perfmon.h> -.PP +.P .BI "long perfmonctl(int " fd ", int " cmd ", void " arg [. narg "], int " narg ");" .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see HISTORY. .SH DESCRIPTION @@ -25,7 +25,7 @@ PMU (performance monitoring unit). The PMU consists of PMD (performance monitoring data) registers and PMC (performance monitoring control) registers, which gather hardware statistics. -.PP +.P .BR perfmonctl () applies the operation .I cmd @@ -35,7 +35,7 @@ The number of arguments is defined by \fInarg\fR. The .I fd argument specifies the perfmon context to operate on. -.PP +.P Supported values for .I cmd are: @@ -180,14 +180,14 @@ Linux on IA-64. Added in Linux 2.4; .\" commit ecf5b72d5f66af843f189dfe9ce31598c3e48ad7 removed in Linux 5.10. -.PP +.P This system call was broken for many years, and ultimately removed in Linux 5.10. -.PP +.P glibc does not provide a wrapper for this system call; on kernels where it exists, call it using .BR syscall (2). .SH SEE ALSO .BR gprof (1) -.PP +.P The perfmon2 interface specification diff --git a/man2/personality.2 b/man2/personality.2 index e76af79..ae8db10 100644 --- a/man2/personality.2 +++ b/man2/personality.2 @@ -10,7 +10,7 @@ .\" changed prototype, documented 0xffffffff, aeb, 030101 .\" Modified 2004-11-03 patch from Martin Schulze <joey@infodrom.org> .\" -.TH personality 2 2023-04-29 "Linux man-pages 6.05.01" +.TH personality 2 2023-10-31 "Linux man-pages 6.7" .SH NAME personality \- set the process execution domain .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/personality.h> -.PP +.P .BI "int personality(unsigned long " persona ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ signal numbers into signal actions. The execution domain system allows Linux to provide limited support for binaries compiled under other UNIX-like operating systems. -.PP +.P If .I persona is not @@ -42,7 +42,7 @@ Specifying .I persona as 0xffffffff provides a way of retrieving the current persona without changing it. -.PP +.P A list of the available execution domains can be found in .IR <sys/personality.h> . The execution domain is a 32-bit value in which the top three @@ -108,7 +108,7 @@ kernel version-numbering switch from Linux 2.6.x to Linux 3.x. .TP .BR WHOLE_SECONDS " (since Linux 1.2.0)" No effect. -.PP +.P The available execution domains are: .TP .BR PER_BSD " (since Linux 1.2.0)" diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2 index 9e3af2a..918f1d2 100644 --- a/man2/pidfd_getfd.2 +++ b/man2/pidfd_getfd.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pidfd_getfd 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pidfd_getfd 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pidfd_getfd \- obtain a duplicate of another process's file descriptor .SH LIBRARY @@ -12,11 +12,11 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_pidfd_getfd, int " pidfd ", int " targetfd , .BI " unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR pidfd_getfd (), @@ -30,7 +30,7 @@ This new file descriptor is a duplicate of an existing file descriptor, .IR targetfd , in the process referred to by the PID file descriptor .IR pidfd . -.PP +.P The duplicate file descriptor refers to the same open file description (see .BR open (2)) as the original file descriptor in the process referred to by @@ -40,19 +40,19 @@ Furthermore, operations on the underlying file object (for example, assigning an address to a socket object using .BR bind (2)) can equally be performed via the duplicate file descriptor. -.PP +.P The close-on-exec flag .RB ( FD_CLOEXEC ; see .BR fcntl (2)) is set on the file descriptor returned by .BR pidfd_getfd (). -.PP +.P The .I flags argument is reserved for future use. Currently, it must be specified as 0. -.PP +.P Permission to duplicate another process's file descriptor is governed by a ptrace access mode .B PTRACE_MODE_ATTACH_REALCREDS @@ -111,7 +111,7 @@ Linux 5.6. .SH NOTES For a description of PID file descriptors, see .BR pidfd_open (2). -.PP +.P The effect of .BR pidfd_getfd () is similar to the use of diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2 index 8321e82..32e92c0 100644 --- a/man2/pidfd_open.2 +++ b/man2/pidfd_open.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pidfd_open 2 2023-05-03 "Linux man-pages 6.05.01" +.TH pidfd_open 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pidfd_open \- obtain a file descriptor that refers to a process .SH LIBRARY @@ -12,10 +12,10 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_pidfd_open, pid_t " pid ", unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR pidfd_open (), @@ -29,7 +29,7 @@ the process whose PID is specified in .IR pid . The file descriptor is returned as the function result; the close-on-exec flag is set on the file descriptor. -.PP +.P The .I flags argument either has the value 0, or contains the following flag: @@ -88,7 +88,7 @@ Linux 5.3. The following code sequence can be used to obtain a file descriptor for the child of .BR fork (2): -.PP +.P .in +4n .EX pid = fork(); @@ -98,7 +98,7 @@ if (pid > 0) { /* If parent */ } .EE .in -.PP +.P Even if the child has already terminated by the time of the .BR pidfd_open () call, its PID will not have been recycled and the returned @@ -127,7 +127,7 @@ the zombie process was not reaped elsewhere in the program (e.g., either by an asynchronously executed signal handler or by .BR wait (2) or similar in another thread). -.PP +.P If any of these conditions does not hold, then the child process (along with a PID file descriptor that refers to it) should instead be created using @@ -181,7 +181,7 @@ A PID file descriptor can be used as the argument of .BR process_madvise (2) in order to provide advice on the memory usage patterns of the process referred to by the file descriptor. -.PP +.P The .BR pidfd_open () system call is the preferred way of obtaining a PID file descriptor diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2 index 670ea71..ae884b8 100644 --- a/man2/pidfd_send_signal.2 +++ b/man2/pidfd_send_signal.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pidfd_send_signal 2 2023-05-03 "Linux man-pages 6.05.01" +.TH pidfd_send_signal 2 2023-11-01 "Linux man-pages 6.7" .SH NAME pidfd_send_signal \- send a signal to a process specified by a file descriptor .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .BR "#include <signal.h>" " /* Definition of " SI_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_pidfd_send_signal, int " pidfd ", int " sig , .BI " siginfo_t *_Nullable " info ", unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR pidfd_send_signal (), @@ -34,23 +34,23 @@ to the target process referred to by a PID file descriptor that refers to a process. .\" See the very detailed commit message for kernel commit .\" 3eb39f47934f9d5a3027fe00d906a45fe3a15fad -.PP +.P If the .I info argument points to a .I siginfo_t buffer, that buffer should be populated as described in .BR rt_sigqueueinfo (2). -.PP +.P If the .I info -argument is a NULL pointer, +argument is a null pointer, this is equivalent to specifying a pointer to a .I siginfo_t buffer whose fields match the values that are implicitly supplied when a signal is sent using .BR kill (2): -.PP +.P .PD 0 .IP \[bu] 3 .I si_signo @@ -69,12 +69,12 @@ is set to the caller's PID; and .I si_uid is set to the caller's real user ID. .PD -.PP +.P The calling process must either be in the same PID namespace as the process referred to by .IR pidfd , or be in an ancestor of that namespace. -.PP +.P The .I flags argument is reserved for future use; @@ -145,7 +145,7 @@ or that specifies the .B CLONE_PIDFD flag. -.PP +.P The .BR pidfd_send_signal () system call allows the avoidance of race conditions that occur diff --git a/man2/pipe.2 b/man2/pipe.2 index d8142f9..55e631d 100644 --- a/man2/pipe.2 +++ b/man2/pipe.2 @@ -13,7 +13,7 @@ .\" to EXAMPLE text. .\" 2008-10-10, mtk: add description of pipe2() .\" -.TH pipe 2 2023-07-30 "Linux man-pages 6.05.01" +.TH pipe 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pipe, pipe2 \- create pipe .SH LIBRARY @@ -22,20 +22,20 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int pipe(int " pipefd [2]); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int pipe2(int " pipefd "[2], int " flags ); -.PP +.P /* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the following prototype; see VERSIONS */ -.PP +.P .B #include <unistd.h> -.PP +.P .B struct fd_pair { .B " long fd[2];" .B "};" @@ -56,7 +56,7 @@ Data written to the write end of the pipe is buffered by the kernel until it is read from the read end of the pipe. For further details, see .BR pipe (7). -.PP +.P If .I flags is 0, then @@ -148,7 +148,7 @@ On error, \-1 is returned, is set to indicate the error, and .I pipefd is left unchanged. -.PP +.P On Linux (and other systems), .BR pipe () does not modify diff --git a/man2/pivot_root.2 b/man2/pivot_root.2 index a4077ef..3e0e55e 100644 --- a/man2/pivot_root.2 +++ b/man2/pivot_root.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pivot_root 2 2023-05-03 "Linux man-pages 6.05.01" +.TH pivot_root 2 2024-02-25 "Linux man-pages 6.7" .SH NAME pivot_root \- change the root mount .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_pivot_root, const char *" new_root \ ", const char *" put_old ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR pivot_root (), @@ -32,7 +32,7 @@ directory \fIput_old\fP and makes \fInew_root\fP the new root mount. The calling process must have the .B CAP_SYS_ADMIN capability in the user namespace that owns the caller's mount namespace. -.PP +.P .BR pivot_root () changes the root directory and the current working directory of each process or thread in the same mount namespace to @@ -45,7 +45,7 @@ does not change the caller's current working directory (unless it is on the old root directory), and thus it should be followed by a \fBchdir("/")\fP call. -.PP +.P The following restrictions apply: .IP \[bu] 3 .I new_root @@ -66,7 +66,7 @@ must yield the same directory as \fInew_root\fP. .IP \[bu] .I new_root must be a path to a mount point, but can't be -.IR """/""" . +.IR \[dq]/\[dq] . A path that is not already a mount point can be converted into one by bind mounting the path onto itself. .IP \[bu] @@ -115,7 +115,7 @@ is on the current root mount. (This error covers the pathological case where .I new_root is -.IR """/""" .) +.IR \[dq]/\[dq] .) .TP .B EINVAL .I new_root @@ -158,7 +158,7 @@ Linux 2.3.41. .SH NOTES A command-line interface for this system call is provided by .BR pivot_root (8). -.PP +.P .BR pivot_root () allows the caller to switch to a new root filesystem while at the same time placing the old root mount at a location under @@ -168,7 +168,7 @@ from where it can subsequently be unmounted. or current working directory on the old root directory to the new root frees the old root directory of users, allowing the old root mount to be unmounted more easily.) -.PP +.P One use of .BR pivot_root () is during system startup, when the @@ -178,7 +178,7 @@ then mounts the real root filesystem, and eventually turns the latter into the root directory of all relevant processes and threads. A modern use is to set up a root filesystem during the creation of a container. -.PP +.P The fact that .BR pivot_root () modifies process root and current working directories in the @@ -187,7 +187,7 @@ is necessary in order to prevent kernel threads from keeping the old root mount busy with their root and current working directories, even if they never access the filesystem in any way. -.PP +.P The rootfs (initial ramfs) cannot be .BR pivot_root ()ed. The recommended method of changing the root filesystem in this case is @@ -207,7 +207,7 @@ and may be the same directory. In particular, the following sequence allows a pivot-root operation without needing to create and remove a temporary directory: -.PP +.P .in +4n .EX chdir(new_root); @@ -215,7 +215,7 @@ pivot_root(".", "."); umount2(".", MNT_DETACH); .EE .in -.PP +.P This sequence succeeds because the .BR pivot_root () call stacks the old root mount point @@ -227,7 +227,7 @@ working directory refer to the new root mount point During the subsequent .BR umount () call, resolution of -.I """.""" +.I \[dq].\[dq] starts with .I new_root and then moves up the list of mounts stacked at @@ -237,7 +237,7 @@ with the result that old root mount point is unmounted. .SS Historical notes For many years, this manual page carried the following text: .RS -.PP +.P .BR pivot_root () may or may not change the current root and the current working directory of any processes or threads which use the old @@ -250,7 +250,7 @@ An easy way to ensure this is to change their root and current working directory to \fInew_root\fP before invoking .BR pivot_root (). .RE -.PP +.P This text, written before the system call implementation was even finalized in the kernel, was probably intended to warn users at that time that the implementation might change before final release. @@ -269,12 +269,12 @@ After pivoting to the root directory named in the program's first command-line argument, the child created by .BR clone (2) then executes the program named in the remaining command-line arguments. -.PP +.P We demonstrate the program by creating a directory that will serve as the new root filesystem and placing a copy of the (statically linked) .BR busybox (1) executable in that directory. -.PP +.P .in +4n .EX $ \fBmkdir /tmp/rootfs\fP @@ -296,7 +296,7 @@ hello world .in .SS Program source \& -.PP +.P .\" SRC BEGIN (pivot_root.c) .EX /* pivot_root_demo.c */ diff --git a/man2/pkey_alloc.2 b/man2/pkey_alloc.2 index 53d8f2a..5d72fb9 100644 --- a/man2/pkey_alloc.2 +++ b/man2/pkey_alloc.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pkey_alloc 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pkey_alloc 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pkey_alloc, pkey_free \- allocate or free a protection key .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sys/mman.h> -.PP +.P .BI "int pkey_alloc(unsigned int " flags ", unsigned int " access_rights ");" .BI "int pkey_free(int " pkey ");" .fi @@ -20,12 +20,12 @@ Standard C library .BR pkey_alloc () allocates a protection key (pkey) and allows it to be passed to .BR pkey_mprotect (2). -.PP +.P The .BR pkey_alloc () .I flags is reserved for future use and currently must always be specified as 0. -.PP +.P The .BR pkey_alloc () .I access_rights @@ -36,13 +36,13 @@ Disable all data access to memory covered by the returned protection key. .TP .B PKEY_DISABLE_WRITE Disable write access to memory covered by the returned protection key. -.PP +.P .BR pkey_free () frees a protection key and makes it available for later allocations. After a protection key has been freed, it may no longer be used in any protection-key-related operations. -.PP +.P An application should not call .BR pkey_free () on any protection key which has been assigned to an address @@ -96,7 +96,7 @@ It can be used in lieu of any other mechanism for detecting pkey support and will simply fail with the error .B ENOSPC if the operating system has no pkey support. -.PP +.P The kernel guarantees that the contents of the hardware rights register (PKRU) will be preserved only for allocated protection keys. diff --git a/man2/poll.2 b/man2/poll.2 index 2b024d3..36e89f8 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -7,7 +7,7 @@ .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and .\" formatting changes. .\" -.TH poll 2 2023-07-08 "Linux man-pages 6.05.01" +.TH poll 2 2023-10-31 "Linux man-pages 6.7" .SH NAME poll, ppoll \- wait for some event on a file descriptor .SH LIBRARY @@ -16,12 +16,12 @@ Standard C library .SH SYNOPSIS .nf .B #include <poll.h> -.PP +.P .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <poll.h> -.PP +.P .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds , .BI " const struct timespec *_Nullable " tmo_p , .BI " const sigset_t *_Nullable " sigmask ); @@ -36,11 +36,11 @@ The Linux-specific .BR epoll (7) API performs a similar task, but offers features beyond those found in .BR poll (). -.PP +.P The set of file descriptors to be monitored is specified in the .I fds argument, which is an array of structures of the following form: -.PP +.P .in +4n .EX struct pollfd { @@ -50,12 +50,12 @@ struct pollfd { }; .EE .in -.PP +.P The caller should specify the number of items in the .I fds array in .IR nfds . -.PP +.P The field .I fd contains a file descriptor for an open file. @@ -70,7 +70,7 @@ file descriptor for a single call: simply set the .I fd field to its bitwise complement.) -.PP +.P The field .I events is an input parameter, a bit mask specifying the events the application @@ -85,7 +85,7 @@ are and .B POLLNVAL (see below). -.PP +.P The field .I revents is an output parameter, filled by the kernel with the events that @@ -104,12 +104,12 @@ or field, and will be set in the .I revents field whenever the corresponding condition is true.) -.PP +.P If none of the events requested (and no error) has occurred for any of the file descriptors, then .BR poll () blocks until one of the events occurs. -.PP +.P The .I timeout argument specifies the number of milliseconds that @@ -122,7 +122,7 @@ a file descriptor becomes ready; the call is interrupted by a signal handler; or .IP \[bu] the timeout expires. -.PP +.P Being "ready" means that the requested operation will not block; thus, .BR poll ()ing regular files, @@ -130,7 +130,7 @@ block devices, and other files with no reasonable polling semantic .I always returns instantly as ready to read and write. -.PP +.P Note that the .I timeout interval will be rounded up to the system clock granularity, @@ -144,7 +144,7 @@ Specifying a of zero causes .BR poll () to return immediately, even if no file descriptors are ready. -.PP +.P The bits that may be set/returned in .I events and @@ -214,7 +214,7 @@ not open (only returned in .IR revents ; ignored in .IR events ). -.PP +.P When compiling with .B _XOPEN_SOURCE defined, one also has the following, @@ -234,7 +234,7 @@ Equivalent to .TP .B POLLWRBAND Priority data may be written. -.PP +.P Linux also knows about, but does not use .BR POLLMSG . .SS ppoll() @@ -251,23 +251,23 @@ like .BR ppoll () allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. -.PP +.P Other than the difference in the precision of the .I timeout argument, the following .BR ppoll () call: -.PP +.P .in +4n .EX ready = ppoll(&fds, nfds, tmo_p, &sigmask); .EE .in -.PP +.P is nearly equivalent to .I atomically executing the following calls: -.PP +.P .in +4n .EX sigset_t origmask; @@ -280,7 +280,7 @@ ready = poll(&fds, nfds, timeout); pthread_sigmask(SIG_SETMASK, &origmask, NULL); .EE .in -.PP +.P The above code segment is described as .I nearly equivalent because whereas a negative @@ -291,13 +291,13 @@ is interpreted as an infinite timeout, a negative value expressed in .I *tmo_p results in an error from .BR ppoll (). -.PP +.P See the description of .BR pselect (2) for an explanation of why .BR ppoll () is necessary. -.PP +.P If the .I sigmask argument is specified as NULL, then @@ -309,7 +309,7 @@ differs from only in the precision of the .I timeout argument). -.PP +.P The .I tmo_p argument specifies an upper limit on the amount of time that @@ -318,7 +318,7 @@ will block. This argument is a pointer to a .BR timespec (3) structure. -.PP +.P If .I tmo_p is specified as NULL, then @@ -334,7 +334,7 @@ whose fields have been set to a nonzero value (indicating an event or an error). A return value of zero indicates that the system call timed out before any file descriptors became ready. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -379,7 +379,7 @@ Portable programs may wish to check for .B EAGAIN and loop, just as with .BR EINTR . -.PP +.P Some implementations define the nonstandard constant .B INFTIM with the value \-1 for use as a @@ -401,7 +401,7 @@ Thus, the glibc function does not modify its .I tmo_p argument. -.PP +.P The raw .BR ppoll () system call has a fifth argument, @@ -452,7 +452,7 @@ and is not affected by the .B O_NONBLOCK flag. -.PP +.P For a discussion of what may happen if a file descriptor being monitored by .BR poll () is closed in another thread, see @@ -482,27 +482,27 @@ if the file descriptor was not readable, but some other event occurred (presumably .BR POLLHUP ), closes the file descriptor. -.PP +.P Suppose we run the program in one terminal, asking it to open a FIFO: -.PP +.P .in +4n .EX $ \fBmkfifo myfifo\fP $ \fB./poll_input myfifo\fP .EE .in -.PP +.P In a second terminal window, we then open the FIFO for writing, write some data to it, and close the FIFO: -.PP +.P .in +4n .EX $ \fBecho aaaaabbbbbccccc > myfifo\fP .EE .in -.PP +.P In the terminal where we are running the program, we would then see: -.PP +.P .in +4n .EX Opened "myfifo" on fd 3 @@ -522,7 +522,7 @@ Ready: 1 All file descriptors closed; bye .EE .in -.PP +.P In the above output, we see that .BR poll () returned three times: diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 index 38e9745..96c06a7 100644 --- a/man2/posix_fadvise.2 +++ b/man2/posix_fadvise.2 @@ -6,7 +6,7 @@ .\" 2005-04-08 mtk, noted kernel version and added BUGS .\" 2010-10-09, mtk, document arm_fadvise64_64() .\" -.TH posix_fadvise 2 2023-03-30 "Linux man-pages 6.05.01" +.TH posix_fadvise 2 2023-10-31 "Linux man-pages 6.7" .SH NAME posix_fadvise \- predeclare an access pattern for file data .SH LIBRARY @@ -15,17 +15,17 @@ Standard C library .SH SYNOPSIS .nf .B #include <fcntl.h> -.PP +.P .BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \ ", int " advice ");" .fi -.PP +.P .ad l .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR posix_fadvise (): .nf _POSIX_C_SOURCE >= 200112L @@ -36,14 +36,14 @@ Programs can use to announce an intention to access file data in a specific pattern in the future, thus allowing the kernel to perform appropriate optimizations. -.PP +.P The \fIadvice\fP applies to a (not necessarily existent) region starting at \fIoffset\fP and extending for \fIlen\fP bytes (or until the end of the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP. The \fIadvice\fP is not binding; it merely constitutes an expectation on behalf of the application. -.PP +.P Permissible values for \fIadvice\fP include: .TP .B POSIX_FADV_NORMAL @@ -159,16 +159,16 @@ Therefore, these architectures define a version of the system call that orders the arguments suitably, but is otherwise exactly the same as .BR posix_fadvise (). -.PP +.P For example, since Linux 2.6.14, ARM has the following system call: -.PP +.P .in +4n .EX .BI "long arm_fadvise64_64(int " fd ", int " advice , .BI " loff_t " offset ", loff_t " len ); .EE .in -.PP +.P These architecture-specific details are generally hidden from applications by the glibc .BR posix_fadvise () @@ -178,7 +178,7 @@ which invokes the appropriate architecture-specific system call. POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Kernel support first appeared in Linux 2.5.60; the underlying system call is called .BR fadvise64 (). @@ -186,14 +186,14 @@ the underlying system call is called Library support has been provided since glibc 2.2, via the wrapper function .BR posix_fadvise (). -.PP +.P Since Linux 3.18, .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb support for the underlying system call is optional, depending on the setting of the .B CONFIG_ADVISE_SYSCALLS configuration option. -.PP +.P The type of the .I len argument was changed from @@ -206,7 +206,7 @@ The contents of the kernel buffer cache can be cleared via the .I /proc/sys/vm/drop_caches interface described in .BR proc (5). -.PP +.P One can obtain a snapshot of which pages of a file are resident in the buffer cache by opening a file, mapping it with .BR mmap (2), diff --git a/man2/prctl.2 b/man2/prctl.2 index a592bba..c6dae6d 100644 --- a/man2/prctl.2 +++ b/man2/prctl.2 @@ -36,7 +36,7 @@ .\" 2014-11-10 Dave Hansen, document PR_MPX_{EN,DIS}ABLE_MANAGEMENT .\" .\" -.TH prctl 2 2023-07-28 "Linux man-pages 6.05.01" +.TH prctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME prctl \- operations on a process or thread .SH LIBRARY @@ -45,8 +45,8 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/prctl.h> -.PP -.BI "int prctl(int " option ", ..." +.P +.BI "int prctl(int " op ", ..." .BI " \fR/*\fP unsigned long " arg2 ", unsigned long " arg3 , .BI " unsigned long " arg4 ", unsigned long " arg5 " \fR*/\fP );" .fi @@ -54,12 +54,12 @@ Standard C library .BR prctl () manipulates various aspects of the behavior of the calling thread or process. -.PP +.P Note that careless use of some .BR prctl () operations can confuse the user-space run-time environment, so these operations should be used with care. -.PP +.P .BR prctl () is called with a first argument describing what to do (with values defined in \fI<linux/prctl.h>\fP), and further @@ -379,7 +379,7 @@ can operate only when this bit is Applications that use the O32 FPXX ABI can operate with either .B FR=0 or -.B FR=1 . +.BR FR=1 . .TP .B PR_FP_MODE_FRE Enable emulation of 32-bit floating-point mode. @@ -414,7 +414,7 @@ so FPU emulation is not required and the FPU always operates in .B FR=1 mode. .IP -This option is mainly intended for use by the dynamic linker +This operation is mainly intended for use by the dynamic linker .RB ( ld.so (8)). .IP The arguments @@ -674,7 +674,7 @@ value. The requirements for the address are the same as for the .B PR_SET_MM_START_BRK option. -.PP +.P The following options are available since Linux 3.5. .\" commit fe8c7f5cbf91124987106faa3bdf0c8b955c4cf7 .TP @@ -741,7 +741,7 @@ This restriction was enforced for security reasons that were subsequently deemed specious, and the restriction was removed in Linux 4.10 because some user-space applications needed to perform this operation more than once. -.PP +.P The following options are available since Linux 3.18. .\" commit f606b77f1a9e362451aca8f81d8f36a3a112139e .TP @@ -806,7 +806,9 @@ except \[aq][\[aq], \[aq]]\[aq], \[aq]\e\[aq], \[aq]$\[aq], and \[aq]\[ga]\[aq]. .RE .\" prctl PR_MPX_ENABLE_MANAGEMENT .TP -.BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19, removed in Linux 5.4; only on x86)" +.B PR_MPX_ENABLE_MANAGEMENT +.TQ +.BR PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19, removed in Linux 5.4; only on x86)" .\" commit fe3d197f84319d3bce379a9c0dc17b1f48ad358c .\" See also http://lwn.net/Articles/582712/ .\" See also https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler @@ -2041,6 +2043,36 @@ the copy will be truncated. Return (as the function result) the full length of the auxiliary vector. \fIarg4\fP and \fIarg5\fP must be 0. +.TP +.BR PR_SET_MDWE " (since Linux 6.3)" +.\" commit b507808ebce23561d4ff8c2aa1fb949fe402bc61 +Set the calling process' Memory-Deny-Write-Execute protection mask. +Once protection bits are set, +they can not be changed. +.I arg2 +must be a bit mask of: +.RS +.TP +.B PR_MDWE_REFUSE_EXEC_GAIN +New memory mapping protections can't be writable and executable. +Non-executable mappings can't become executable. +.TP +.B PR_MDWE_NO_INHERIT " (since Linux 6.6)" +.\" commit 2a87e5520554034e8c423479740f95bea4a086a0 +Do not propagate MDWE protection to child processes on +.BR fork (2). +Setting this bit requires setting +.B PR_MDWE_REFUSE_EXEC_GAIN +too. +.RE +.TP +.BR PR_GET_MDWE " (since Linux 6.3)" +.\" commit b507808ebce23561d4ff8c2aa1fb949fe402bc61 +Return (as the function result) the Memory-Deny-Write-Execute protection mask +of the calling process. +(See +.B PR_SET_MDWE +for information on the protection mask bits.) .SH RETURN VALUE On success, .BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET , @@ -2064,7 +2096,7 @@ and (if it returns) .B PR_GET_SECCOMP return the nonnegative values described above. All other -.I option +.I op values return 0 on success. On error, \-1 is returned, and .I errno @@ -2072,7 +2104,7 @@ is set to indicate the error. .SH ERRORS .TP .B EACCES -.I option +.I op is .B PR_SET_SECCOMP and @@ -2088,7 +2120,7 @@ attribute (see the discussion of above). .TP .B EACCES -.I option +.I op is .BR PR_SET_MM , and @@ -2098,7 +2130,7 @@ is the file is not executable. .TP .B EBADF -.I option +.I op is .BR PR_SET_MM , .I arg3 @@ -2109,7 +2141,7 @@ and the file descriptor passed in is not valid. .TP .B EBUSY -.I option +.I op is .BR PR_SET_MM , .I arg3 @@ -2124,7 +2156,7 @@ symbolic link, which is prohibited. is an invalid address. .TP .B EFAULT -.I option +.I op is .BR PR_SET_SECCOMP , .I arg2 @@ -2137,7 +2169,7 @@ and is an invalid address. .TP .B EFAULT -.I option +.I op is .B PR_SET_SYSCALL_USER_DISPATCH and @@ -2146,12 +2178,12 @@ has an invalid address. .TP .B EINVAL The value of -.I option +.I op is not recognized, or not supported on this system. .TP .B EINVAL -.I option +.I op is .B PR_MCE_KILL or @@ -2165,10 +2197,10 @@ arguments were not specified as zero. .B EINVAL .I arg2 is not valid value for this -.IR option . +.IR op . .TP .B EINVAL -.I option +.I op is .B PR_SET_SECCOMP or @@ -2177,7 +2209,7 @@ and the kernel was not configured with .BR CONFIG_SECCOMP . .TP .B EINVAL -.I option +.I op is .BR PR_SET_SECCOMP , .I arg2 @@ -2187,7 +2219,7 @@ and the kernel was not configured with .BR CONFIG_SECCOMP_FILTER . .TP .B EINVAL -.I option +.I op is .BR PR_SET_MM , and one of the following is true @@ -2227,7 +2259,7 @@ resource limit to be exceeded. .RE .TP .B EINVAL -.I option +.I op is .B PR_SET_PTRACER and @@ -2237,7 +2269,7 @@ is not 0, or the PID of an existing process. .TP .B EINVAL -.I option +.I op is .B PR_SET_PDEATHSIG and @@ -2245,7 +2277,7 @@ and is not a valid signal number. .TP .B EINVAL -.I option +.I op is .B PR_SET_DUMPABLE and @@ -2256,7 +2288,7 @@ nor .BR SUID_DUMP_USER . .TP .B EINVAL -.I option +.I op is .B PR_SET_TIMING and @@ -2265,7 +2297,7 @@ is not .BR PR_TIMING_STATISTICAL . .TP .B EINVAL -.I option +.I op is .B PR_SET_NO_NEW_PRIVS and @@ -2279,7 +2311,7 @@ or is nonzero. .TP .B EINVAL -.I option +.I op is .B PR_GET_NO_NEW_PRIVS and @@ -2291,7 +2323,7 @@ or is nonzero. .TP .B EINVAL -.I option +.I op is .B PR_SET_THP_DISABLE and @@ -2302,7 +2334,7 @@ or is nonzero. .TP .B EINVAL -.I option +.I op is .B PR_GET_THP_DISABLE and @@ -2314,7 +2346,7 @@ or is nonzero. .TP .B EINVAL -.I option +.I op is .B PR_CAP_AMBIENT and an unused argument @@ -2339,7 +2371,7 @@ and does not specify a valid capability. .TP .B EINVAL -.I option +.I op was .B PR_GET_SPECULATION_CTRL or @@ -2347,8 +2379,9 @@ or and unused arguments to .BR prctl () are not 0. +.TP .B EINVAL -.I option +.I op is .B PR_PAC_RESET_KEYS and the arguments are invalid or unsupported. @@ -2357,7 +2390,7 @@ See the description of above for details. .TP .B EINVAL -.I option +.I op is .B PR_SVE_SET_VL and the arguments are invalid or unsupported, @@ -2367,13 +2400,13 @@ See the description of above for details. .TP .B EINVAL -.I option +.I op is .B PR_SVE_GET_VL and SVE is not available on this platform. .TP .B EINVAL -.I option +.I op is .B PR_SET_SYSCALL_USER_DISPATCH and one of the following is true: @@ -2395,7 +2428,7 @@ is invalid. .RE .TP .B EINVAL -.I option +.I op is .B PR_SET_TAGGED_ADDR_CTRL and the arguments are invalid or unsupported. @@ -2404,7 +2437,7 @@ See the description of above for details. .TP .B EINVAL -.I option +.I op is .B PR_GET_TAGGED_ADDR_CTRL and the arguments are invalid or unsupported. @@ -2413,13 +2446,13 @@ See the description of above for details. .TP .B ENODEV -.I option +.I op was .B PR_SET_SPECULATION_CTRL the kernel or CPU does not support the requested speculation misfeature. .TP .B ENXIO -.I option +.I op was .B PR_MPX_ENABLE_MANAGEMENT or @@ -2428,7 +2461,7 @@ and the kernel or the CPU does not support MPX management. Check that the kernel and processor have MPX support. .TP .B ENXIO -.I option +.I op was .B PR_SET_SPECULATION_CTRL implies that the control of the selected speculation misfeature is not possible. @@ -2437,7 +2470,7 @@ See for the bit fields to determine which option is available. .TP .B EOPNOTSUPP -.I option +.I op is .B PR_SET_FP_MODE and @@ -2445,7 +2478,7 @@ and has an invalid or unsupported value. .TP .B EPERM -.I option +.I op is .BR PR_SET_SECUREBITS , and the caller does not have the @@ -2457,7 +2490,7 @@ or tried to set a flag whose corresponding locked flag was set .BR capabilities (7)). .TP .B EPERM -.I option +.I op is .B PR_SET_SPECULATION_CTRL wherein the speculation was disabled with @@ -2465,7 +2498,7 @@ wherein the speculation was disabled with and caller tried to enable it again. .TP .B EPERM -.I option +.I op is .BR PR_SET_KEEPCAPS , and the caller's @@ -2475,7 +2508,7 @@ flag is set .BR capabilities (7)). .TP .B EPERM -.I option +.I op is .BR PR_CAPBSET_DROP , and the caller does not have the @@ -2483,7 +2516,7 @@ and the caller does not have the capability. .TP .B EPERM -.I option +.I op is .BR PR_SET_MM , and the caller does not have the @@ -2491,7 +2524,7 @@ and the caller does not have the capability. .TP .B EPERM -.I option +.I op is .B PR_CAP_AMBIENT and @@ -2506,7 +2539,7 @@ or the securebit has been set. .TP .B ERANGE -.I option +.I op was .B PR_SET_SPECULATION_CTRL and @@ -2523,14 +2556,14 @@ IRIX has a system call (also introduced in Linux 2.1.44 as irix_prctl on the MIPS architecture), with prototype -.PP +.P .in +4n .EX -.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 ); +.BI "ptrdiff_t prctl(int " op ", int " arg2 ", int " arg3 ); .EE .in -.PP -and options to get the maximum number of processes per user, +.P +and operations to get the maximum number of processes per user, get the maximum number of processors the calling process can use, find out whether a specified process is currently blocked, get or set the maximum stack size, and so on. diff --git a/man2/pread.2 b/man2/pread.2 index 9764e53..4ff94c0 100644 --- a/man2/pread.2 +++ b/man2/pread.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pread 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pread 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pread, pwrite \- read from or write to a file descriptor at a given offset .SH LIBRARY @@ -11,18 +11,18 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "ssize_t pread(int " fd ", void " buf [. count "], size_t " count , .BI " off_t " offset ); .BI "ssize_t pwrite(int " fd ", const void " buf [. count "], size_t " count , .BI " off_t " offset ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pread (), .BR pwrite (): .nf @@ -40,7 +40,7 @@ at offset (from the start of the file) into the buffer starting at .IR buf . The file offset is not changed. -.PP +.P .BR pwrite () writes up to .I count @@ -51,7 +51,7 @@ to the file descriptor at offset .IR offset . The file offset is not changed. -.PP +.P The file referenced by .I fd must be capable of seeking. @@ -63,13 +63,13 @@ returns the number of bytes read and .BR pwrite () returns the number of bytes written. -.PP +.P Note that it is not an error for a successful call to transfer fewer bytes than requested (see .BR read (2) and .BR write (2)). -.PP +.P On error, \-1 is returned and .I errno is set to indicate the error. @@ -92,7 +92,7 @@ or POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Added in Linux 2.1.60; the entries in the i386 system call table were added in Linux 2.1.69. C library support (including emulation using @@ -114,7 +114,7 @@ The glibc and .BR pwrite () wrapper functions transparently deal with the change. -.PP +.P On some 32-bit architectures, the calling signature for these system calls differ, for the reasons described in diff --git a/man2/process_madvise.2 b/man2/process_madvise.2 index b95f4e3..37ec5fd 100644 --- a/man2/process_madvise.2 +++ b/man2/process_madvise.2 @@ -5,7 +5,7 @@ .\" .\" Commit ecb8ac8b1f146915aa6b96449b66dd48984caacc .\" -.TH process_madvise 2 2023-03-30 "Linux man-pages 6.05.01" +.TH process_madvise 2 2024-02-28 "Linux man-pages 6.7" .SH NAME process_madvise \- give advice about use of memory to a process .SH LIBRARY @@ -13,23 +13,12 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.BR "#include <sys/mman.h>" " /* Definition of " MADV_* " constants */" -.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" -.BR "#include <sys/uio.h>" " /* Definition of " "struct iovec" " type */" -.B #include <unistd.h> -.PP -.BI "ssize_t syscall(SYS_process_madvise, int " pidfd , -.BI " const struct iovec *" iovec ", size_t " vlen \ -", int " advice , -.BI " unsigned int " flags ");" +.B #include <sys/mman.h> +.P +.BI "ssize_t process_madvise(int " pidfd ", const struct iovec " iovec [. n ], +.BI " size_t " n ", int " advice \ +", unsigned int " flags ); .fi -.PP -.IR Note : -glibc provides no wrapper for -.BR process_madvise (), -necessitating the use of -.BR syscall (2). -.\" FIXME: See <https://sourceware.org/bugzilla/show_bug.cgi?id=27380> .SH DESCRIPTION The .BR process_madvise () @@ -38,23 +27,23 @@ address ranges of another process or of the calling process. It provides the advice for the address ranges described by .I iovec and -.IR vlen . +.IR n . The goal of such advice is to improve system or application performance. -.PP +.P The .I pidfd argument is a PID file descriptor (see .BR pidfd_open (2)) that specifies the process to which the advice is to be applied. -.PP +.P The pointer .I iovec points to an array of .I iovec structures, described in .BR iovec (3type). -.PP -.I vlen +.P +.I n specifies the number of elements in the array of .I iovec structures. @@ -64,7 +53,7 @@ This value must be less than or equal to .I <limits.h> or accessible via the call .IR sysconf(_SC_IOV_MAX) ). -.PP +.P The .I advice argument is one of the following values: @@ -84,31 +73,31 @@ See .B MADV_WILLNEED See .BR madvise (2). -.PP +.P The .I flags argument is reserved for future use; currently, this argument must be specified as 0. -.PP +.P The -.I vlen +.I n and .I iovec arguments are checked before applying any advice. If -.I vlen +.I n is too big, or .I iovec is invalid, then an error will be returned immediately and no advice will be applied. -.PP +.P The advice might be applied to only a part of .I iovec if one of its elements points to an invalid memory region in the remote process. No further elements will be processed beyond that point. (See the discussion regarding partial advice in RETURN VALUE.) -.PP +.P .\" commit 96cfe2c0fd23ea7c2368d14f769d287e7ae1082e Starting in Linux 5.12, permission to apply advice to another process is governed by @@ -133,7 +122,7 @@ if an error occurred after some elements were already processed. The caller should check the return value to determine whether a partial advice occurred. -.PP +.P On error, \-1 is returned and .I errno is set to indicate the error. @@ -163,7 +152,7 @@ overflows a value. .TP .B EINVAL -.I vlen +.I n is too large. .TP .B ENOMEM @@ -177,7 +166,7 @@ The caller does not have permission to access the address space of the process .TP .B ESRCH The target process does not exist (i.e., it has terminated and been waited on). -.PP +.P See .BR madvise (2) for @@ -187,13 +176,15 @@ errors. Linux. .SH HISTORY Linux 5.10. -.\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc -.PP +.\" Linux commit ecb8ac8b1f146915aa6b96449b66dd48984caacc +glibc 2.36. +.\" glibc commit d19ee3473d68ca0e794f3a8b7677a0983ae1342e +.P Support for this system call is optional, depending on the setting of the .B CONFIG_ADVISE_SYSCALLS configuration option. -.PP +.P When this system call first appeared in Linux 5.10, permission to apply advice to another process was entirely governed by ptrace access mode diff --git a/man2/process_vm_readv.2 b/man2/process_vm_readv.2 index 86da35c..23c9111 100644 --- a/man2/process_vm_readv.2 +++ b/man2/process_vm_readv.2 @@ -6,7 +6,7 @@ .\" .\" Commit fcf634098c00dd9cd247447368495f0b79be12d1 .\" -.TH process_vm_readv 2 2023-05-03 "Linux man-pages 6.05.01" +.TH process_vm_readv 2 2023-10-31 "Linux man-pages 6.7" .SH NAME process_vm_readv, process_vm_writev \- transfer data between process address spaces @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/uio.h> -.PP +.P .BI "ssize_t process_vm_readv(pid_t " pid , .BI " const struct iovec *" local_iov , .BI " unsigned long " liovcnt , @@ -30,12 +30,12 @@ Standard C library .BI " unsigned long " riovcnt , .BI " unsigned long " flags ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR process_vm_readv (), .BR process_vm_writev (): .nf @@ -48,7 +48,7 @@ of the calling process ("the local process") and the process identified by ("the remote process"). The data moves directly between the address spaces of the two processes, without passing through kernel space. -.PP +.P The .BR process_vm_readv () system call transfers data from the remote process to the local process. @@ -73,7 +73,7 @@ and .I liovcnt specifies the number of elements in .IR local_iov . -.PP +.P The .BR process_vm_writev () system call is the converse of @@ -87,7 +87,7 @@ and .I remote_iov have the same meaning as for .BR process_vm_readv (). -.PP +.P The .I local_iov and @@ -96,7 +96,7 @@ arguments point to an array of .I iovec structures, described in .BR iovec (3type). -.PP +.P Buffers are processed in array order. This means that .BR process_vm_readv () @@ -110,7 +110,7 @@ Likewise, is completely read before proceeding to .IR remote_iov[1] , and so on. -.PP +.P Similarly, .BR process_vm_writev () writes out the entire contents of @@ -121,7 +121,7 @@ and it completely fills .I remote_iov[0] before proceeding to .IR remote_iov[1] . -.PP +.P The lengths of .I remote_iov[i].iov_len and @@ -129,11 +129,11 @@ and do not have to be the same. Thus, it is possible to split a single local buffer into multiple remote buffers, or vice versa. -.PP +.P The .I flags argument is currently unused and must be set to 0. -.PP +.P The values specified in the .I liovcnt and @@ -146,7 +146,7 @@ or accessible via the call .IR sysconf(_SC_IOV_MAX) ). .\" In time, glibc might provide a wrapper that works around this limit, .\" as is done for readv()/writev() -.PP +.P The count arguments and .I local_iov are checked before doing any transfers. @@ -156,7 +156,7 @@ is invalid, or the addresses refer to regions that are inaccessible to the local process, none of the vectors will be processed and an error will be returned immediately. -.PP +.P Note, however, that these system calls do not check the memory regions in the remote process until just before doing the read/write. Consequently, a partial read/write (see RETURN VALUE) @@ -176,7 +176,7 @@ elements and have them merge back into a single write entry. The first read entry goes up to the page boundary, while the second starts on the next page boundary.) -.PP +.P Permission to read from or write to another process is governed by a ptrace access mode .B PTRACE_MODE_ATTACH_REALCREDS @@ -198,7 +198,7 @@ These system calls won't perform a partial transfer that splits a single element.) The caller should check the return value to determine whether a partial read/write occurred. -.PP +.P On error, \-1 is returned and .I errno is set to indicate the error. @@ -260,7 +260,7 @@ The data transfers performed by and .BR process_vm_writev () are not guaranteed to be atomic in any way. -.PP +.P These system calls were designed to permit fast message passing by allowing messages to be exchanged with a single copy operation (rather than the double copy that would be required @@ -276,7 +276,7 @@ and writes the first 10 bytes into .I buf1 and the second 10 bytes into .IR buf2 . -.PP +.P .\" SRC BEGIN (process_vm_readv.c) .EX #define _GNU_SOURCE diff --git a/man2/ptrace.2 b/man2/ptrace.2 index 4149a32..1cd9966 100644 --- a/man2/ptrace.2 +++ b/man2/ptrace.2 @@ -83,7 +83,7 @@ .\" .\" and others that can be found in the arch/*/include/uapi/asm/ptrace files .\" -.TH ptrace 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ptrace 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ptrace \- process trace .SH LIBRARY @@ -92,8 +92,8 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/ptrace.h> -.PP -.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid , +.P +.BI "long ptrace(enum __ptrace_request " op ", pid_t " pid , .BI " void *" addr ", void *" data ); .fi .SH DESCRIPTION @@ -104,7 +104,7 @@ may observe and control the execution of another process (the "tracee"), and examine and change the tracee's memory and registers. It is primarily used to implement breakpoint debugging and system call tracing. -.PP +.P A tracee first needs to be attached to the tracer. Attachment and subsequent commands are per thread: in a multithreaded process, @@ -115,23 +115,23 @@ Therefore, "tracee" always means "(one) thread", never "a (possibly multithreaded) process". Ptrace commands are always sent to a specific tracee using a call of the form -.PP +.P .in +4n .EX ptrace(PTRACE_foo, pid, ...) .EE .in -.PP +.P where .I pid is the thread ID of the corresponding Linux thread. -.PP +.P (Note that in this page, a "multithreaded process" means a thread group consisting of threads created using the .BR clone (2) .B CLONE_THREAD flag.) -.PP +.P A process can initiate a trace by calling .BR fork (2) and having the resulting child do a @@ -142,7 +142,7 @@ Alternatively, one process may commence tracing another process using .B PTRACE_ATTACH or .BR PTRACE_SEIZE . -.PP +.P While being traced, the tracee will stop each time a signal is delivered, even if the signal is being ignored. (An exception is @@ -155,11 +155,11 @@ The tracer will be notified at its next call to value containing information that indicates the cause of the stop in the tracee. While the tracee is stopped, -the tracer can use various ptrace requests to inspect and modify the tracee. +the tracer can use various ptrace operations to inspect and modify the tracee. The tracer then causes the tracee to continue, optionally ignoring the delivered signal (or even delivering a different signal instead). -.PP +.P If the .B PTRACE_O_TRACEEXEC option is not in effect, all successful calls to @@ -169,18 +169,18 @@ by the traced process will cause it to be sent a signal, giving the parent a chance to gain control before the new program begins execution. -.PP +.P When the tracer is finished tracing, it can cause the tracee to continue executing in a normal, untraced mode via .BR PTRACE_DETACH . -.PP +.P The value of -.I request -determines the action to be performed: +.I op +determines the operation to be performed: .TP .B PTRACE_TRACEME Indicate that this process is to be traced by its parent. -A process probably shouldn't make this request if its parent +A process probably shouldn't make this operation if its parent isn't expecting to trace it. .RI ( pid , .IR addr , @@ -190,12 +190,12 @@ are ignored.) .IP The .B PTRACE_TRACEME -request is used only by the tracee; -the remaining requests are used only by the tracer. -In the following requests, +operation is used only by the tracee; +the remaining operations are used only by the tracer. +In the following operations, .I pid specifies the thread ID of the tracee to be acted on. -For requests other than +For operations other than .BR PTRACE_ATTACH , .BR PTRACE_SEIZE , .BR PTRACE_INTERRUPT , @@ -203,14 +203,16 @@ and .BR PTRACE_KILL , the tracee must be stopped. .TP -.BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA +.B PTRACE_PEEKTEXT +.TQ +.B PTRACE_PEEKDATA Read a word at the address .I addr in the tracee's memory, returning the word as the result of the .BR ptrace () call. Linux does not have separate text and data address spaces, -so these two requests are currently equivalent. +so these two operations are currently equivalent. .RI ( data is ignored; but see NOTES.) .TP @@ -232,7 +234,9 @@ See NOTES. .RI ( data is ignored; but see NOTES.) .TP -.BR PTRACE_POKETEXT ", " PTRACE_POKEDATA +.B PTRACE_POKETEXT +.TQ +.B PTRACE_POKEDATA Copy the word .I data to the address @@ -242,7 +246,7 @@ As for .B PTRACE_PEEKTEXT and .BR PTRACE_PEEKDATA , -these two requests are currently equivalent. +these two operations are currently equivalent. .TP .B PTRACE_POKEUSER .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER, @@ -260,7 +264,9 @@ some modifications to the USER area are disallowed. .\" FIXME In the preceding sentence, which modifications are disallowed, .\" and when they are disallowed, how does user space discover that fact? .TP -.BR PTRACE_GETREGS ", " PTRACE_GETFPREGS +.B PTRACE_GETREGS +.TQ +.B PTRACE_GETFPREGS Copy the tracee's general-purpose or floating-point registers, respectively, to the address .I data @@ -304,7 +310,9 @@ On return, the kernel modifies .B iov.len to indicate the actual number of bytes returned. .TP -.BR PTRACE_SETREGS ", " PTRACE_SETFPREGS +.B PTRACE_SETREGS +.TQ +.B PTRACE_SETFPREGS Modify the tracee's general-purpose or floating-point registers, respectively, from the address .I data @@ -391,7 +399,7 @@ field includes information .RB ( __SI_CHLD , .BR __SI_FAULT , etc.) that are not otherwise exposed to user space. -.PP +.P .in +4n .EX struct ptrace_peeksiginfo_args { @@ -696,7 +704,9 @@ whether a signal sent to the tracee is delivered or not. .RI ( addr is ignored.) .TP -.BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP +.B PTRACE_SYSCALL +.TQ +.B PTRACE_SINGLESTEP Restart the stopped tracee as for .BR PTRACE_CONT , but arrange for the tracee to be stopped at @@ -730,7 +740,7 @@ argument. The .I addr argument is ignored. -This request is currently +This operation is currently .\" As of 4.19-rc2 supported only on arm (and arm64, though only for backwards compatibility), .\" commit 27aa55c5e5123fa8b8ad0156559d34d7edff58ca @@ -740,7 +750,9 @@ system call number in). .\" see change_syscall in tools/testing/selftests/seccomp/seccomp_bpf.c .\" and also strace's linux/*/set_scno.c files. .TP -.BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" +.B PTRACE_SYSEMU +.TQ +.BR PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" For .BR PTRACE_SYSEMU , continue and stop on entry to the next system call, @@ -758,7 +770,7 @@ argument is treated as for The .I addr argument is ignored. -These requests are currently +These operations are currently .\" As at 3.7 supported only on x86. .TP @@ -1130,7 +1142,7 @@ all threads exit. Tracees report their death to their tracer(s). Notification of this event is delivered via .BR waitpid (2). -.PP +.P Note that the killing signal will first cause signal-delivery-stop (on one tracee only), and only after it is injected by the tracer @@ -1139,7 +1151,7 @@ will death from the signal happen on .I all tracees within a multithreaded process. (The term "signal-delivery-stop" is explained below.) -.PP +.P .B SIGKILL does not generate signal-delivery-stop and therefore the tracer can't suppress it. @@ -1151,16 +1163,16 @@ The net effect is that .B SIGKILL always kills the process (all its threads), even if some threads of the process are ptraced. -.PP +.P When the tracee calls .BR _exit (2), it reports its death to its tracer. Other threads are not affected. -.PP +.P When any thread executes .BR exit_group (2), every tracee in its thread group reports its death to its tracer. -.PP +.P If the .B PTRACE_O_TRACEEXIT option is on, @@ -1175,7 +1187,7 @@ depending on the kernel version; see BUGS below), and when threads are torn down on .BR execve (2) in a multithreaded process. -.PP +.P The tracer cannot assume that the ptrace-stopped tracee exists. There are many scenarios when the tracee may die while stopped (such as .BR SIGKILL ). @@ -1199,8 +1211,8 @@ ptrace operation returned .I waitpid(WNOHANG) may return 0 instead. In other words, the tracee may be "not yet fully dead", -but already refusing ptrace requests. -.PP +but already refusing ptrace operations. +.P The tracer can't assume that the tracee .I always ends its life by reporting @@ -1236,11 +1248,11 @@ in group-stop before it will not respond to signals until .B SIGCONT is received. -.PP +.P There are many kinds of states when the tracee is stopped, and in ptrace discussions they are often conflated. Therefore, it is important to use precise terms. -.PP +.P In this manual page, any stopped state in which the tracee is ready to accept ptrace commands from the tracer is called .IR ptrace-stop . @@ -1252,18 +1264,18 @@ be further subdivided into .IR "PTRACE_EVENT stops" , and so on. These stopped states are described in detail below. -.PP +.P When the running tracee enters ptrace-stop, it notifies its tracer using .BR waitpid (2) (or one of the other "wait" system calls). Most of this manual page assumes that the tracer waits with: -.PP +.P .in +4n .EX pid = waitpid(pid_or_minus_1, &status, __WALL); .EE .in -.PP +.P Ptrace-stopped tracees are reported as returns with .I pid greater than 0 and @@ -1275,7 +1287,7 @@ true. .\" rules different if user wants to use waitid? Will waitid require .\" WEXITED? .\" -.PP +.P The .B __WALL flag does not include the @@ -1283,14 +1295,14 @@ flag does not include the and .B WEXITED flags, but implies their functionality. -.PP +.P Setting the .B WCONTINUED flag when calling .BR waitpid (2) is not recommended: the "continued" state is per-process and consuming it can confuse the real parent of the tracee. -.PP +.P Use of the .B WNOHANG flag may cause @@ -1298,7 +1310,7 @@ flag may cause to return 0 ("no wait results available yet") even if the tracer knows there should be a notification. Example: -.PP +.P .in +4n .EX errno = 0; @@ -1313,7 +1325,7 @@ if (errno == ESRCH) { .\" FIXME . .\" waitid usage? WNOWAIT? .\" describe how wait notifications queue (or not queue) -.PP +.P The following kinds of ptrace-stops exist: signal-delivery-stops, group-stops, .B PTRACE_EVENT @@ -1343,7 +1355,7 @@ If the selected thread is traced, it enters signal-delivery-stop. At this point, the signal is not yet delivered to the process, and can be suppressed by the tracer. If the tracer doesn't suppress the signal, -it passes the signal to the tracee in the next ptrace restart request. +it passes the signal to the tracee in the next ptrace restart operation. This second step of signal delivery is called .I "signal injection" in this manual page. @@ -1352,7 +1364,7 @@ signal-delivery-stop doesn't happen until the signal is unblocked, with the usual exception that .B SIGSTOP can't be blocked. -.PP +.P Signal-delivery-stop is observed by the tracer as .BR waitpid (2) returning with @@ -1369,16 +1381,16 @@ returns a stopping signal, this may be a group-stop; see below. .SS Signal injection and suppression After signal-delivery-stop is observed by the tracer, the tracer should restart the tracee with the call -.PP +.P .in +4n .EX ptrace(PTRACE_restart, pid, 0, sig) .EE .in -.PP +.P where .B PTRACE_restart -is one of the restarting ptrace requests. +is one of the restarting ptrace operations. If .I sig is 0, then a signal is not delivered. @@ -1388,13 +1400,13 @@ is delivered. This operation is called .I "signal injection" in this manual page, to distinguish it from signal-delivery-stop. -.PP +.P The .I sig value may be different from the .I WSTOPSIG(status) value: the tracer can cause a different signal to be injected. -.PP +.P Note that a suppressed signal still causes system calls to return prematurely. In this case, system calls will be restarted: the tracer will @@ -1410,7 +1422,7 @@ signal is suppressed; however, kernel bugs exist which cause some system calls to fail with .B EINTR even though no observable signal is injected to the tracee. -.PP +.P Restarting ptrace commands issued in ptrace-stops other than signal-delivery-stop are not guaranteed to inject a signal, even if .I sig @@ -1421,26 +1433,26 @@ may simply be ignored. Ptrace users should not try to "create a new signal" this way: use .BR tgkill (2) instead. -.PP -The fact that signal injection requests may be ignored +.P +The fact that signal injection operations may be ignored when restarting the tracee after ptrace stops that are not signal-delivery-stops is a cause of confusion among ptrace users. One typical scenario is that the tracer observes group-stop, mistakes it for signal-delivery-stop, restarts the tracee with -.PP +.P .in +4n .EX ptrace(PTRACE_restart, pid, 0, stopsig) .EE .in -.PP +.P with the intention of injecting .IR stopsig , but .I stopsig gets ignored and the tracee continues to run. -.PP +.P The .B SIGCONT signal has a side effect of waking up (all threads of) @@ -1460,11 +1472,11 @@ was delivered. In other words, .B SIGCONT may be not the first signal observed by the tracee after it was sent. -.PP +.P Stopping signals cause (all threads of) a process to enter group-stop. This side effect happens after signal injection, and therefore can be suppressed by the tracer. -.PP +.P In Linux 2.4 and earlier, the .B SIGSTOP signal can't be injected. @@ -1474,7 +1486,7 @@ signal can't be injected. .\" /* The debugger continued. Ignore SIGSTOP. */ .\" if (signr == SIGSTOP) .\" continue; -.PP +.P .B PTRACE_GETSIGINFO can be used to retrieve a .I siginfo_t @@ -1503,7 +1515,7 @@ will group-stop be initiated on tracees within the multithreaded process. As usual, every tracee reports its group-stop separately to the corresponding tracer. -.PP +.P Group-stop is observed by the tracer as .BR waitpid (2) returning with @@ -1512,13 +1524,13 @@ true, with the stopping signal available via .IR WSTOPSIG(status) . The same result is returned by some other classes of ptrace-stops, therefore the recommended practice is to perform the call -.PP +.P .in +4n .EX ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo) .EE .in -.PP +.P The call can be avoided if the signal is not .BR SIGSTOP , .BR SIGTSTP , @@ -1539,7 +1551,7 @@ then it is definitely a group-stop. ("no such process") if a .B SIGKILL killed the tracee.) -.PP +.P If tracee was attached using .BR PTRACE_SEIZE , group-stop is indicated by @@ -1549,7 +1561,7 @@ This allows detection of group-stops without requiring an extra .B PTRACE_GETSIGINFO call. -.PP +.P As of Linux 2.6.38, after the tracer sees the tracee ptrace-stop and until it restarts or kills it, the tracee will not run, @@ -1558,7 +1570,7 @@ and will not send notifications (except death) to the tracer, even if the tracer enters into another .BR waitpid (2) call. -.PP +.P The kernel behavior described in the previous paragraph causes a problem with transparent handling of stopping signals. If the tracer restarts the tracee after group-stop, @@ -1572,7 +1584,7 @@ signals will not be reported to the tracer; this would cause the .B SIGCONT signals to have no effect on the tracee. -.PP +.P Since Linux 3.4, there is a method to overcome this problem: instead of .BR PTRACE_CONT , a @@ -1589,7 +1601,7 @@ If the tracer sets options, the tracee will enter ptrace-stops called .B PTRACE_EVENT stops. -.PP +.P .B PTRACE_EVENT stops are observed by the tracer as .BR waitpid (2) @@ -1606,13 +1618,13 @@ An additional bit is set in the higher byte of the status word: the value .I status>>8 will be -.PP +.P .in +4n .EX ((PTRACE_EVENT_foo<<8) | SIGTRAP). .EE .in -.PP +.P The following events exist: .TP .B PTRACE_EVENT_VFORK @@ -1649,7 +1661,7 @@ with the .B CLONE_VFORK flag, but after the child unblocked this tracee by exiting or execing. -.PP +.P For all four stops described above, the stop occurs in the parent (i.e., the tracee), not in the newly created thread. @@ -1698,7 +1710,7 @@ portion of the seccomp filter rule) can be retrieved with .BR PTRACE_GETEVENTMSG . The semantics of this stop are described in detail in a separate section below. -.PP +.P .B PTRACE_GETSIGINFO on .B PTRACE_EVENT @@ -1737,7 +1749,7 @@ Note that all mentions .B PTRACE_SYSEMU apply equally to .BR PTRACE_SYSEMU_SINGLESTEP . -.PP +.P However, even if the tracee was continued using .BR PTRACE_SYSCALL , it is not guaranteed that the next stop will be a syscall-exit-stop. @@ -1754,7 +1766,7 @@ or die silently (if it is a thread group leader, the happened in another thread, and that thread is not traced by the same tracer; this situation is discussed later). -.PP +.P Syscall-enter-stop and syscall-exit-stop are observed by the tracer as .BR waitpid (2) returning with @@ -1769,7 +1781,7 @@ option was set by the tracer, then .I WSTOPSIG(status) will give the value .IR "(SIGTRAP\ |\ 0x80)" . -.PP +.P Syscall-stops can be distinguished from signal-delivery-stop with .B SIGTRAP by querying @@ -1786,7 +1798,7 @@ for example, a system call etc.), expiration of a POSIX timer, change of state on a POSIX message queue, -or completion of an asynchronous I/O request. +or completion of an asynchronous I/O operation. .TP .IR si_code " == SI_KERNEL (0x80)" .B SIGTRAP @@ -1794,12 +1806,12 @@ was sent by the kernel. .TP .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)" This is a syscall-stop. -.PP +.P However, syscall-stops happen very often (twice per system call), and performing .B PTRACE_GETSIGINFO for every syscall-stop may be somewhat expensive. -.PP +.P Some architectures allow the cases to be distinguished by examining registers. For example, on x86, @@ -1822,13 +1834,13 @@ looks like "syscall-stop which is not syscall-enter-stop"; in other words, it looks like a "stray syscall-exit-stop" and can be detected this way. But such detection is fragile and is best avoided. -.PP +.P Using the .B PTRACE_O_TRACESYSGOOD option is the recommended method to distinguish syscall-stops from other kinds of ptrace-stops, since it is reliable and does not incur a performance penalty. -.PP +.P Syscall-enter-stop and syscall-exit-stop are indistinguishable from each other by the tracer. The tracer needs to keep track of the sequence of @@ -1843,12 +1855,12 @@ However, note that seccomp stops (see below) can cause syscall-exit-stops, without preceding syscall-entry-stops. If seccomp is in use, care needs to be taken not to misinterpret such stops as syscall-entry-stops. -.PP +.P If after syscall-enter-stop, the tracer uses a restarting command other than .BR PTRACE_SYSCALL , syscall-exit-stop is not generated. -.PP +.P .B PTRACE_GETSIGINFO on syscall-stops returns .B SIGTRAP @@ -1869,7 +1881,7 @@ of ptrace stops has changed between kernel versions. This documents the behavior from their introduction until Linux 4.7 (inclusive). The behavior in later kernel versions is documented in the next section. -.PP +.P A .B PTRACE_EVENT_SECCOMP stop occurs whenever a @@ -1879,7 +1891,7 @@ This is independent of which methods was used to restart the system call. Notably, seccomp still runs even if the tracee was restarted using .B PTRACE_SYSEMU and this system call is unconditionally skipped. -.PP +.P Restarts from this stop will behave as if the stop had occurred right before the system call in question. In particular, both @@ -1909,7 +1921,7 @@ Note that seccomp no longer runs (and no .B PTRACE_EVENT_SECCOMP will be reported) if the system call is skipped due to .BR PTRACE_SYSEMU . -.PP +.P Functionally, a .B PTRACE_EVENT_SECCOMP stop functions comparably @@ -1920,7 +1932,7 @@ the system call number may be changed and any other modified registers are visible to the to-be-executed system call as well). Note that there may be, but need not have been a preceding syscall-entry-stop. -.PP +.P After a .B PTRACE_EVENT_SECCOMP stop, seccomp will be rerun, with a @@ -1947,12 +1959,12 @@ and .BR PTRACE_KILL ) require the tracee to be in a ptrace-stop, otherwise they fail with .BR ESRCH . -.PP +.P When the tracee is in ptrace-stop, the tracer can read and write data to the tracee using informational commands. These commands leave the tracee in ptrace-stopped state: -.PP +.P .in +4n .EX ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0); @@ -1967,7 +1979,7 @@ ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var); ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); .EE .in -.PP +.P Note that some errors are not reported. For example, setting signal information .RI ( siginfo ) @@ -1978,15 +1990,15 @@ querying .B PTRACE_GETEVENTMSG may succeed and return some random value if current ptrace-stop is not documented as returning a meaningful event message. -.PP +.P The call -.PP +.P .in +4n .EX ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); .EE .in -.PP +.P affects one tracee. The tracee's current flags are replaced. Flags are inherited by new tracees created and "auto-attached" via active @@ -1995,16 +2007,16 @@ Flags are inherited by new tracees created and "auto-attached" via active or .B PTRACE_O_TRACECLONE options. -.PP +.P Another group of commands makes the ptrace-stopped tracee run. They have the form: -.PP +.P .in +4n .EX ptrace(cmd, pid, 0, sig); .EE .in -.PP +.P where .I cmd is @@ -2027,21 +2039,21 @@ recommended practice is to always pass 0 in .IR sig .) .SS Attaching and detaching A thread can be attached to the tracer using the call -.PP +.P .in +4n .EX ptrace(PTRACE_ATTACH, pid, 0, 0); .EE .in -.PP +.P or -.PP +.P .in +4n .EX ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags); .EE .in -.PP +.P .B PTRACE_ATTACH sends .B SIGSTOP @@ -2065,14 +2077,14 @@ may race and the concurrent may be lost. .\" .\" FIXME Describe how to attach to a thread which is already group-stopped. -.PP +.P Since attaching sends .B SIGSTOP and the tracer usually suppresses it, this may cause a stray .B EINTR return from the currently executing system call in the tracee, as described in the "Signal injection and suppression" section. -.PP +.P Since Linux 3.4, .B PTRACE_SEIZE can be used instead of @@ -2084,30 +2096,30 @@ it after attach (or at any other time) without sending it any signals, use .B PTRACE_INTERRUPT command. -.PP -The request -.PP +.P +The operation +.P .in +4n .EX ptrace(PTRACE_TRACEME, 0, 0, 0); .EE .in -.PP +.P turns the calling thread into a tracee. The thread continues to run (doesn't enter ptrace-stop). A common practice is to follow the .B PTRACE_TRACEME with -.PP +.P .in +4n .EX raise(SIGSTOP); .EE .in -.PP +.P and allow the parent (which is our tracer now) to observe our signal-delivery-stop. -.PP +.P If the .BR PTRACE_O_TRACEFORK , .BR PTRACE_O_TRACEVFORK , @@ -2131,15 +2143,15 @@ are automatically attached to the same tracer which traced their parent. .B SIGSTOP is delivered to the children, causing them to enter signal-delivery-stop after they exit the system call which created them. -.PP +.P Detaching of the tracee is performed by: -.PP +.P .in +4n .EX ptrace(PTRACE_DETACH, pid, 0, sig); .EE .in -.PP +.P .B PTRACE_DETACH is a restarting operation; therefore it requires the tracee to be in ptrace-stop. @@ -2147,7 +2159,7 @@ If the tracee is in signal-delivery-stop, a signal can be injected. Otherwise, the .I sig parameter may be silently ignored. -.PP +.P If the tracee is running when the tracer wants to detach it, the usual solution is to send .B SIGSTOP @@ -2171,7 +2183,7 @@ because no signal delivery happens while it is\[em]not even .BR SIGSTOP . .\" FIXME Describe how to detach from a group-stopped tracee so that it .\" doesn't run, but continues to wait for SIGCONT. -.PP +.P If the tracer dies, all tracees are automatically detached and restarted, unless they were in group-stop. Handling of restart from group-stop is currently buggy, @@ -2243,10 +2255,10 @@ If the thread group leader was not traced .BR execve (2) it will appear as if it has become a tracee of the tracer of the execing tracee. -.PP +.P All of the above effects are the artifacts of the thread ID change in the tracee. -.PP +.P The .B PTRACE_O_TRACEEXEC option is the recommended tool for dealing with this situation. @@ -2266,13 +2278,13 @@ option disables legacy .B SIGTRAP generation on .BR execve (2). -.PP +.P When the tracer receives .B PTRACE_EVENT_EXEC stop notification, it is guaranteed that except this tracee and the thread group leader, no other threads from the process are alive. -.PP +.P On receiving the .B PTRACE_EVENT_EXEC stop notification, @@ -2280,17 +2292,17 @@ the tracer should clean up all its internal data structures describing the threads of this process, and retain only one data structure\[em]one which describes the single still running tracee, with -.PP +.P .in +4n .EX thread ID == thread group ID == process ID. .EE .in -.PP +.P Example: two threads call .BR execve (2) at the same time: -.PP +.P .nf *** we get syscall-enter-stop in thread 1: ** PID1 execve("/bin/foo", "foo" <unfinished ...> @@ -2302,7 +2314,7 @@ PID2 execve("/bin/bar", "bar" <unfinished ...> *** we get syscall-exit-stop for PID0: ** PID0 <... execve resumed> ) = 0 .fi -.PP +.P If the .B PTRACE_O_TRACEEXEC option is @@ -2329,7 +2341,7 @@ set to 0 .RI ( SI_USER ). This signal may be blocked by signal mask, and thus may be delivered (much) later. -.PP +.P Usually, the tracer (for example, .BR strace (1)) would not want to show this extra post-execve @@ -2357,10 +2369,10 @@ This used to cause the real parent of the process to stop receiving several kinds of .BR waitpid (2) notifications when the child process is traced by some other process. -.PP +.P Many of these bugs have been fixed, but as of Linux 2.6.38 several still exist; see BUGS below. -.PP +.P As of Linux 2.6.38, the following is believed to work correctly: .IP \[bu] 3 exit/death by signal is reported first to the tracer, then, @@ -2373,21 +2385,21 @@ the report is sent only once. .SH RETURN VALUE On success, the .B PTRACE_PEEK* -requests return the requested data (but see NOTES), +operations return the requested data (but see NOTES), the .B PTRACE_SECCOMP_GET_FILTER -request returns the number of instructions in the BPF program, +operation returns the number of instructions in the BPF program, the .B PTRACE_GET_SYSCALL_INFO -request returns the number of bytes available to be written by the kernel, -and other requests return zero. -.PP -On error, all requests return \-1, and +operation returns the number of bytes available to be written by the kernel, +and other operations return zero. +.P +On error, all operations return \-1, and .I errno is set to indicate the error. Since the value returned by a successful .B PTRACE_PEEK* -request may be \-1, the caller must clear +operation may be \-1, the caller must clear .I errno before the call, and then check it afterward to determine whether or not an error occurred. @@ -2411,11 +2423,11 @@ more or less arbitrarily. An attempt was made to set an invalid option. .TP .B EIO -.I request +.I op is invalid, or an attempt was made to read from or write to an invalid area in the tracer's or the tracee's memory, or there was a word-alignment violation, -or an invalid signal was specified during a restart request. +or an invalid signal was specified during a restart operation. .TP .B EPERM The specified process cannot be traced. @@ -2433,12 +2445,12 @@ or (before Linux 2.6.26) be .B ESRCH The specified process does not exist, or is not currently being traced by the caller, or is not stopped -(for requests that require a stopped tracee). +(for operations that require a stopped tracee). .SH STANDARDS None. .SH HISTORY SVr4, 4.3BSD. -.PP +.P Before Linux 2.6.26, .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb .BR init (1), @@ -2450,7 +2462,7 @@ are interpreted according to the prototype given, glibc currently declares .BR ptrace () as a variadic function with only the -.I request +.I op argument fixed. It is recommended to always supply four arguments, even if the requested operation does not use them, @@ -2458,20 +2470,20 @@ setting unused/ignored arguments to .I 0L or .IR "(void\ *)\ 0". -.PP +.P A tracees parent continues to be the tracer even if that tracer calls .BR execve (2). -.PP +.P The layout of the contents of memory and the USER area are quite operating-system- and architecture-specific. The offset supplied, and the data returned, might not entirely match with the definition of .IR "struct user" . .\" See http://lkml.org/lkml/2008/5/8/375 -.PP +.P The size of a "word" is determined by the operating-system variant (e.g., for 32-bit Linux it is 32 bits). -.PP +.P This page documents the way the .BR ptrace () call works currently in Linux. @@ -2497,7 +2509,7 @@ whether or not the "target" process is dumpable, and the results of checks performed by any enabled Linux Security Module (LSM)\[em]for example, SELinux, Yama, or Smack\[em]and by the commoncap LSM (which is always invoked). -.PP +.P Prior to Linux 2.6.27, all access checks were of a single type. Since Linux 2.6.27, .\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd @@ -2541,7 +2553,7 @@ was effectively the default before Linux 2.6.27.) .\" about proper handling of /proc/pid/fd. Arguably that one might belong .\" back in the _ATTACH camp. .\" -.PP +.P Since Linux 4.5, .\" commit caaee6234d05a58c5b4d05e7bf766131b810a657 the above access mode checks are combined (ORed) with @@ -2555,7 +2567,7 @@ or effective capabilities for LSM checks. .B PTRACE_MODE_REALCREDS Use the caller's real UID and GID or permitted capabilities for LSM checks. This was effectively the default before Linux 4.5. -.PP +.P Because combining one of the credential modifiers with one of the aforementioned access modes is typical, some macros are defined in the kernel sources for the combinations: @@ -2575,7 +2587,7 @@ Defined as .B PTRACE_MODE_ATTACH_REALCREDS Defined as .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" . -.PP +.P One further modifier can be ORed with the access mode: .TP .BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)" @@ -2591,7 +2603,7 @@ In these cases, accessing the file is not a security violation and there is no reason to generate a security audit record. This modifier suppresses the generation of such an audit record for the particular access check. -.PP +.P Note that all of the .B PTRACE_MODE_* constants described in this subsection are kernel-internal, @@ -2602,7 +2614,7 @@ and accesses to various pseudofiles (e.g., under .IR /proc ). These names are used in other manual pages to provide a simple shorthand for labeling the different kernel checks. -.PP +.P The algorithm employed for ptrace access mode checking determines whether the calling process is allowed to perform the corresponding action on the target process. @@ -2724,7 +2736,7 @@ a compromised process can ptrace-attach to other sensitive processes (e.g., a GPG agent or an SSH session) owned by the user in order to gain additional credentials that may exist in memory and thus expand the scope of the attack. -.PP +.P More precisely, the Yama LSM limits two types of operations: .IP \[bu] 3 Any operation that performs a ptrace access mode @@ -2736,7 +2748,7 @@ check\[em]for example, .IP \[bu] .BR ptrace () .BR PTRACE_TRACEME . -.PP +.P A process that has the .B CAP_SYS_PTRACE capability can update the @@ -2796,7 +2808,7 @@ operations or trace children that employ .BR PTRACE_TRACEME . .IP Once this value has been written to the file, it cannot be changed. -.PP +.P With respect to values 1 and 2, note that creating a new user namespace effectively removes the protection offered by Yama. @@ -2817,7 +2829,7 @@ At the system call level, the .BR PTRACE_PEEKDATA , and .B PTRACE_PEEKUSER -requests have a different API: they store the result +operations have a different API: they store the result at the address specified by the .I data parameter, and the return value is the error flag. @@ -2834,10 +2846,10 @@ This can be worked around by redefining to .BR PTRACE_OLDSETOPTIONS , if that is defined. -.PP +.P Group-stop notifications are sent to the tracer, but not to real parent. Last confirmed on 2.6.38.6. -.PP +.P If a thread group leader is traced and exits by calling .BR _exit (2), .\" Note from Denys Vlasenko: @@ -2868,7 +2880,7 @@ One possible workaround is to the thread group leader instead of restarting it in this case. Last confirmed on 2.6.38.6. .\" FIXME . need to test/verify this scenario -.PP +.P A .B SIGKILL signal may still cause a @@ -2878,7 +2890,7 @@ This may be changed in the future; .B SIGKILL is meant to always immediately kill tasks even under ptrace. Last confirmed on Linux 3.13. -.PP +.P Some system calls return with .B EINTR if a signal was sent to a tracee, but delivery was suppressed by the tracer. @@ -2896,40 +2908,40 @@ from an file descriptor. The usual symptom of this bug is that when you attach to a quiescent process with the command -.PP +.P .in +4n .EX strace \-p <process\-ID> .EE .in -.PP +.P then, instead of the usual and expected one-line output such as -.PP +.P .in +4n .EX restart_syscall(<... resuming interrupted call ...>_ .EE .in -.PP +.P or -.PP +.P .in +4n .EX select(6, [5], NULL, [5], NULL_ .EE .in -.PP +.P ('_' denotes the cursor position), you observe more than one line. For example: -.PP +.P .in +4n .EX clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0 epoll_wait(4,_ .EE .in -.PP +.P What is not visible here is that the process was blocked in .BR epoll_wait (2) before @@ -2949,7 +2961,7 @@ again. errors may behave in an unintended way upon an .BR strace (1) attach.) -.PP +.P Contrary to the normal rules, the glibc wrapper for .BR ptrace () can set diff --git a/man2/query_module.2 b/man2/query_module.2 index 519650a..f2b163a 100644 --- a/man2/query_module.2 +++ b/man2/query_module.2 @@ -5,13 +5,13 @@ .\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" -.TH query_module 2 2023-03-30 "Linux man-pages 6.05.01" +.TH query_module 2 2023-10-31 "Linux man-pages 6.7" .SH NAME query_module \- query the kernel for various bits pertaining to modules .SH SYNOPSIS .nf .B #include <linux/module.h> -.PP +.P .BI "[[deprecated]] int query_module(const char *" name ", int " which , .BI " void " buf [. bufsize "], \ size_t " bufsize , @@ -20,7 +20,7 @@ size_t " bufsize , .SH DESCRIPTION .IR Note : This system call is present only before Linux 2.6. -.PP +.P .BR query_module () requests information from the kernel about loadable modules. The returned information is placed in the buffer pointed to by @@ -37,7 +37,7 @@ Some operations require to identify a currently loaded module, some allow .I name to be NULL, indicating the kernel proper. -.PP +.P The following values can be specified for .IR which : .TP @@ -167,7 +167,7 @@ Linux. .SH VERSIONS Removed in Linux 2.6. .\" Removed in Linux 2.5.48 -.PP +.P Some of the information that was formerly available via .BR query_module () can be obtained from @@ -175,7 +175,7 @@ can be obtained from .IR /proc/kallsyms , and the files under the directory .IR /sys/module . -.PP +.P The .BR query_module () system call is not supported by glibc. diff --git a/man2/quotactl.2 b/man2/quotactl.2 index 716f934..3cfaaf5 100644 --- a/man2/quotactl.2 +++ b/man2/quotactl.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH quotactl 2 2023-05-03 "Linux man-pages 6.05.01" +.TH quotactl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME quotactl \- manipulate disk quotas .SH LIBRARY @@ -16,8 +16,8 @@ Standard C library .BR "#include <xfs/xqm.h>" " /* Definition of " Q_X* " and " XFS_QUOTA_* \ " constants" .RB " (or " <linux/dqblk_xfs.h> "; see NOTES) */" -.PP -.BI "int quotactl(int " cmd ", const char *_Nullable " special ", int " id , +.P +.BI "int quotactl(int " op ", const char *_Nullable " special ", int " id , .BI " caddr_t " addr ); .fi .SH DESCRIPTION @@ -30,19 +30,19 @@ The soft limit can be exceeded, but warnings will ensue. Moreover, the user can't exceed the soft limit for more than grace period duration (one week by default) at a time; after this, the soft limit counts as a hard limit. -.PP +.P The .BR quotactl () call manipulates disk quotas. The -.I cmd -argument indicates a command to be applied to the user or +.I op +argument indicates an operation to be applied to the user or group ID specified in .IR id . To initialize the -.I cmd +.I op argument, use the -.I QCMD(subcmd, type) +.I QCMD(subop, type) macro. The .I type @@ -55,24 +55,24 @@ for group quotas, or (since Linux 4.1) .BR PRJQUOTA , for project quotas. The -.I subcmd +.I subop value is described below. -.PP +.P The .I special argument is a pointer to a null-terminated string containing the pathname of the (mounted) block special device for the filesystem being manipulated. -.PP +.P The .I addr -argument is the address of an optional, command-specific, data structure +argument is the address of an optional, operation-specific, data structure that is copied in or out of the system. The interpretation of .I addr is given with each operation below. -.PP +.P The -.I subcmd +.I subop value is one of the following operations: .TP .B Q_QUOTAON @@ -380,7 +380,7 @@ This operation is obsolete and was removed in Linux 2.4.22. Files in .I /proc/sys/fs/quota/ carry the information instead. -.PP +.P For XFS filesystems making use of the XFS Quota Manager (XQM), the above operations are bypassed and the following operations are used: .TP @@ -649,7 +649,7 @@ structure) which identify what types of quota should be removed. (Note that the quota type passed in the -.I cmd +.I op argument is ignored, but should remain valid in order to pass preliminary quotactl syscall handler checks.) .IP @@ -681,7 +681,7 @@ is set to indicate the error. .SH ERRORS .TP .B EACCES -.I cmd +.I op is .BR Q_QUOTAON , and the quota file pointed to by @@ -691,7 +691,7 @@ is not on the filesystem pointed to by .IR special . .TP .B EBUSY -.I cmd +.I op is .BR Q_QUOTAON , but another @@ -705,20 +705,20 @@ or is invalid. .TP .B EINVAL -.I cmd +.I op or .I type is invalid. .TP .B EINVAL -.I cmd +.I op is .BR Q_QUOTAON , but the specified quota file is corrupted. .TP .BR EINVAL " (since Linux 5.5)" .\" 3dd4d40b420846dd35869ccc8f8627feef2cff32 -.I cmd +.I op is .BR Q_XQUOTARM , but @@ -747,7 +747,7 @@ The caller lacked the required privilege for the specified operation. .TP .B ERANGE -.I cmd +.I op is .BR Q_SETQUOTA , but the specified limits are out of the range allowed by the quota format. @@ -757,13 +757,13 @@ No disk quota is found for the indicated user. Quotas have not been turned on for this filesystem. .TP .B ESRCH -.I cmd +.I op is .BR Q_QUOTAON , but the specified quota format was not found. .TP .B ESRCH -.I cmd +.I op is .B Q_GETNEXTQUOTA or diff --git a/man2/read.2 b/man2/read.2 index 955efa4..973993e 100644 --- a/man2/read.2 +++ b/man2/read.2 @@ -13,7 +13,7 @@ .\" Modified Sat Jul 12 20:45:39 1997 by Michael Haardt .\" <michael@cantor.informatik.rwth-aachen.de> .\" -.TH read 2 2023-04-03 "Linux man-pages 6.05.01" +.TH read 2 2024-03-12 "Linux man-pages 6.7" .SH NAME read \- read from a file descriptor .SH LIBRARY @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "ssize_t read(int " fd ", void " buf [. count "], size_t " count ); .fi .SH DESCRIPTION @@ -33,7 +33,7 @@ bytes from file descriptor .I fd into the buffer starting at .IR buf . -.PP +.P On files that support seeking, the read operation commences at the file offset, and the file offset is incremented by the number of bytes read. @@ -41,7 +41,7 @@ If the file offset is at or past the end of file, no bytes are read, and .BR read () returns zero. -.PP +.P If .I count is zero, @@ -56,7 +56,7 @@ does not check for errors, a with a .I count of 0 returns zero and has no other effects. -.PP +.P According to POSIX.1, if .I count is greater than @@ -73,7 +73,7 @@ because we are reading from a pipe, or from a terminal), or because .BR read () was interrupted by a signal. See also NOTES. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -160,7 +160,7 @@ for further details. .B EISDIR .I fd refers to a directory. -.PP +.P Other errors may occur, depending on the object connected to .IR fd . .SH STANDARDS @@ -175,7 +175,7 @@ On Linux, returning the number of bytes actually transferred. .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 (This is true on both 32-bit and 64-bit systems.) -.PP +.P On NFS filesystems, reading small amounts of data will update the timestamp only the first time, subsequent calls may not do so. This is caused @@ -194,13 +194,13 @@ increase server load and decrease performance. .SH BUGS According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 ("Thread Interactions with Regular File Operations"): -.PP +.P .RS 4 All of the following functions shall be atomic with respect to each other in the effects specified in POSIX.1-2008 when they operate on regular files or symbolic links: ... .RE -.PP +.P Among the APIs subsequently listed are .BR read () and @@ -216,7 +216,7 @@ perform a (or .BR readv (2)) at the same time, then the I/O operations were not atomic -with respect updating the file offset, +with respect to updating the file offset, with the result that the reads in the two processes might (incorrectly) overlap in the blocks of data that they obtained. This problem was fixed in Linux 3.14. diff --git a/man2/readahead.2 b/man2/readahead.2 index b97f085..701efde 100644 --- a/man2/readahead.2 +++ b/man2/readahead.2 @@ -5,7 +5,7 @@ .\" 2004-05-40 Created by Michael Kerrisk <mtk.manpages@gmail.com> .\" 2004-10-05 aeb, minor correction .\" -.TH readahead 2 2023-07-15 "Linux man-pages 6.05.01" +.TH readahead 2 2023-10-31 "Linux man-pages 6.7" .SH NAME readahead \- initiate file readahead into page cache .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #define _FILE_OFFSET_BITS 64 .B #include <fcntl.h> -.PP +.P .BI "ssize_t readahead(int " fd ", off_t " offset ", size_t " count ); .fi .SH DESCRIPTION @@ -25,7 +25,7 @@ initiates readahead on a file so that subsequent reads from that file will be satisfied from the cache, and not block on disk I/O (assuming the readahead was initiated early enough and that other activity on the system did not in the meantime flush pages from the cache). -.PP +.P The .I fd argument is a file descriptor identifying the file which is diff --git a/man2/readdir.2 b/man2/readdir.2 index 6b06ff4..dbb91e1 100644 --- a/man2/readdir.2 +++ b/man2/readdir.2 @@ -7,7 +7,7 @@ .\" In 1.3.X, returns only one entry each time; return value is different. .\" Modified 2004-12-01, mtk, fixed headers listed in SYNOPSIS .\" -.TH readdir 2 2023-03-30 "Linux man-pages 6.05.01" +.TH readdir 2 2023-10-31 "Linux man-pages 6.7" .SH NAME readdir \- read directory entry .SH LIBRARY @@ -17,11 +17,11 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_readdir, unsigned int " fd , .BI " struct old_linux_dirent *" dirp ", unsigned int " count ); .fi -.PP +.P .IR Note : There is no definition of .BR "struct old_linux_dirent" ; @@ -34,7 +34,7 @@ for the POSIX conforming C library interface. This page documents the bare kernel system call interface, which is superseded by .BR getdents (2). -.PP +.P .BR readdir () reads one .I old_linux_dirent @@ -48,13 +48,13 @@ The argument is ignored; at most one .I old_linux_dirent structure is read. -.PP +.P The .I old_linux_dirent structure is declared (privately in Linux kernel file .BR fs/readdir.c ) as follows: -.PP +.P .in +4n .EX struct old_linux_dirent { @@ -65,7 +65,7 @@ struct old_linux_dirent { } .EE .in -.PP +.P .I d_ino is an inode number. .I d_offset @@ -107,7 +107,7 @@ structure yourself. However, probably you should use .BR readdir (3) instead. -.PP +.P This system call does not exist on x86-64. .SH STANDARDS Linux. diff --git a/man2/readlink.2 b/man2/readlink.2 index fe2369d..c476091 100644 --- a/man2/readlink.2 +++ b/man2/readlink.2 @@ -13,7 +13,7 @@ .\" 2011-09-20, Guillem Jover <guillem@hadrons.org>: .\" Added text on dynamically allocating buffer + example program .\" -.TH readlink 2 2023-05-03 "Linux man-pages 6.05.01" +.TH readlink 2 2023-11-01 "Linux man-pages 6.7" .SH NAME readlink, readlinkat \- read value of a symbolic link .SH LIBRARY @@ -22,29 +22,29 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "ssize_t readlink(const char *restrict " pathname ", char *restrict " buf , .BI " size_t " bufsiz ); -.PP +.P .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" .B #include <unistd.h> -.PP +.P .BI "ssize_t readlinkat(int " dirfd ", const char *restrict " pathname , .BI " char *restrict " buf ", size_t " bufsiz ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR readlink (): .nf _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR readlinkat (): .nf Since glibc 2.10: @@ -72,7 +72,7 @@ The system call operates in exactly the same way as .BR readlink (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -82,7 +82,7 @@ referred to by the file descriptor the calling process, as is done by .BR readlink () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -94,13 +94,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR readlink ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P Since Linux 2.6.39, .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d .I pathname @@ -114,7 +114,7 @@ with the and .B O_NOFOLLOW flags). -.PP +.P See .BR openat (2) for an explanation of the need for @@ -199,7 +199,7 @@ POSIX.1-2001, POSIX.1-2008. POSIX.1-2008. Linux 2.6.16, glibc 2.4. -.PP +.P Up to and including glibc 2.4, the return type of .BR readlink () was declared as @@ -253,7 +253,7 @@ falling back to a buffer of size in cases where .BR lstat (2) reports a size of zero. -.PP +.P .\" SRC BEGIN (readlink.c) .EX #include <limits.h> @@ -307,7 +307,7 @@ main(int argc, char *argv[]) null byte (\[aq]\e0\[aq]). */ printf("\[aq]%s\[aq] points to \[aq]%.*s\[aq]\en", argv[1], (int) nbytes, buf); \& - /* If the return value was equal to the buffer size, then the + /* If the return value was equal to the buffer size, then the link target was larger than expected (perhaps because the target was changed between the call to lstat() and the call to readlink()). Warn the user that the returned target may have diff --git a/man2/readv.2 b/man2/readv.2 index db6abbc..c1295cd 100644 --- a/man2/readv.2 +++ b/man2/readv.2 @@ -9,7 +9,7 @@ .\" add more details. .\" 2010-11-16, mtk, Added documentation of preadv() and pwritev() .\" -.TH readv 2 2023-05-03 "Linux man-pages 6.05.01" +.TH readv 2 2023-10-31 "Linux man-pages 6.7" .SH NAME readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into multiple buffers @@ -19,26 +19,26 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/uio.h> -.PP +.P .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); -.PP +.P .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ); .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ); -.PP +.P .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ", int " flags ); .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR preadv (), .BR pwritev (): .nf @@ -57,7 +57,7 @@ buffers from the file associated with the file descriptor into the buffers described by .I iov ("scatter input"). -.PP +.P The .BR writev () system call writes @@ -67,7 +67,7 @@ buffers of data described by to the file associated with the file descriptor .I fd ("gather output"). -.PP +.P The pointer .I iov points to an array of @@ -75,19 +75,19 @@ points to an array of structures, described in .BR iovec (3type). -.PP +.P The .BR readv () system call works just like .BR read (2) except that multiple buffers are filled. -.PP +.P The .BR writev () system call works just like .BR write (2) except that multiple buffers are written out. -.PP +.P Buffers are processed in array order. This means that .BR readv () @@ -106,7 +106,7 @@ writes out the entire contents of before proceeding to .IR iov[1] , and so on. -.PP +.P The data transfers performed by .BR readv () and @@ -136,7 +136,7 @@ but adds a fourth argument, .IR offset , which specifies the file offset at which the input operation is to be performed. -.PP +.P The .BR pwritev () system call combines the functionality of @@ -149,7 +149,7 @@ but adds a fourth argument, .IR offset , which specifies the file offset at which the output operation is to be performed. -.PP +.P The file offset is not changed by these system calls. The file referred to by .I fd @@ -162,7 +162,7 @@ and calls, but add a fifth argument, .IR flags , which modifies the behavior on a per-call basis. -.PP +.P Unlike .BR preadv () and @@ -170,7 +170,7 @@ and if the .I offset argument is \-1, then the current file offset is used and updated. -.PP +.P The .I flags argument contains a bitwise OR of zero or more of the following flags: @@ -249,13 +249,13 @@ return the number of bytes read; and .BR pwritev2 () return the number of bytes written. -.PP +.P Note that it is not an error for a successful call to transfer fewer bytes than requested (see .BR read (2) and .BR write (2)). -.PP +.P On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. .SH ERRORS The errors are as given for @@ -297,9 +297,9 @@ corresponding GNU C library wrapper functions shown in the SYNOPSIS. The final argument, .IR offset , is unpacked by the wrapper functions into two arguments in the system calls: -.PP +.P .BI " unsigned long " pos_l ", unsigned long " pos -.PP +.P These arguments contain, respectively, the low order and high order 32 bits of .IR offset . .SH STANDARDS @@ -329,12 +329,12 @@ POSIX.1-2001, .\" and \fIint\fP as the return type. .\" The readv/writev system calls were buggy before Linux 1.3.40. .\" (Says release.libc.) -.PP +.P .BR preadv (), .BR pwritev (): Linux 2.6.30, glibc 2.10. -.PP +.P .BR preadv2 (), .BR pwritev2 (): Linux 4.6, @@ -365,7 +365,7 @@ The wrapper function for .BR writev () performed the analogous task using a temporary buffer and a call to .BR write (2). -.PP +.P The need for this extra effort in the glibc wrapper functions went away with Linux 2.2 and later. However, glibc continued to provide this behavior until glibc 2.10. @@ -405,7 +405,7 @@ flag may return 0 even when not at end of file. .SH EXAMPLES The following code sample demonstrates the use of .BR writev (): -.PP +.P .in +4n .EX char *str0 = "hello "; diff --git a/man2/reboot.2 b/man2/reboot.2 index 681087f..7ca639c 100644 --- a/man2/reboot.2 +++ b/man2/reboot.2 @@ -5,7 +5,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> .\" Added notes on capability requirements .\" -.TH reboot 2 2023-03-30 "Linux man-pages 6.05.01" +.TH reboot 2 2024-03-03 "Linux man-pages 6.7" .SH NAME reboot \- reboot or enable/disable Ctrl-Alt-Del .SH LIBRARY @@ -15,23 +15,23 @@ Standard C library .nf .RB "/* Since Linux 2.1.30 there are symbolic names " LINUX_REBOOT_* for the constants and a fourth argument to the call: */ -.PP +.P .BR "#include <linux/reboot.h> " \ "/* Definition of " LINUX_REBOOT_* " constants */" .BR "#include <sys/syscall.h> " "/* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP -.BI "int syscall(SYS_reboot, int " magic ", int " magic2 ", int " cmd ", void *" arg ); -.PP +.P +.BI "int syscall(SYS_reboot, int " magic ", int " magic2 ", int " op ", void *" arg ); +.P /* Under glibc and most alternative libc's (including uclibc, dietlibc, musl and a few others), some of the constants involved have gotten .RB " symbolic names " RB_* ", and the library call is a 1-argument" wrapper around the system call: */ -.PP +.P .BR "#include <sys/reboot.h> " "/* Definition of " RB_* " constants */" .B #include <unistd.h> -.PP -.BI "int reboot(int " cmd ); +.P +.BI "int reboot(int " op ); .fi .SH DESCRIPTION The @@ -40,7 +40,7 @@ call reboots the system, or enables/disables the reboot keystroke (abbreviated CAD, since the default is Ctrl-Alt-Delete; it can be changed using .BR loadkeys (1)). -.PP +.P This system call fails (with the error .BR EINVAL ) unless @@ -64,9 +64,9 @@ and since Linux 2.5.71 also are permitted as values for .IR magic2 . (The hexadecimal values of these constants are meaningful.) -.PP +.P The -.I cmd +.I op argument can have the following values: .TP .B LINUX_REBOOT_CMD_CAD_OFF @@ -138,10 +138,10 @@ data will be lost. The system is suspended (hibernated) to disk. This option is available only if the kernel was configured with .BR CONFIG_HIBERNATION . -.PP +.P Only the superuser may call .BR reboot (). -.PP +.P The precise effect of the above actions depends on the architecture. For the i386 architecture, the additional argument does not do anything at present (2.1.122), but the type of reboot can be @@ -157,20 +157,22 @@ if is called from a PID namespace other than the initial PID namespace with one of the -.I cmd +.I op values listed below, it performs a "reboot" of that namespace: the "init" process of the PID namespace is immediately terminated, with the effects described in .BR pid_namespaces (7). -.PP +.P The values that can be supplied in -.I cmd +.I op when calling .BR reboot () in this case are as follows: .TP -.BR LINUX_REBOOT_CMD_RESTART ", " LINUX_REBOOT_CMD_RESTART2 +.B LINUX_REBOOT_CMD_RESTART +.TQ +.B LINUX_REBOOT_CMD_RESTART2 The "init" process is terminated, and .BR wait (2) @@ -178,16 +180,18 @@ in the parent process reports that the child was killed with a .B SIGHUP signal. .TP -.BR LINUX_REBOOT_CMD_POWER_OFF ", " LINUX_REBOOT_CMD_HALT +.B LINUX_REBOOT_CMD_POWER_OFF +.TQ +.B LINUX_REBOOT_CMD_HALT The "init" process is terminated, and .BR wait (2) in the parent process reports that the child was killed with a .B SIGINT signal. -.PP +.P For the other -.I cmd +.I op values, .BR reboot () returns \-1 and @@ -196,13 +200,13 @@ is set to .BR EINVAL . .SH RETURN VALUE For the values of -.I cmd +.I op that stop or restart the system, a successful call to .BR reboot () does not return. For the other -.I cmd +.I op values, zero is returned on success. In all cases, \-1 is returned on failure, and .I errno @@ -214,7 +218,8 @@ Problem with getting user-space data under .BR LINUX_REBOOT_CMD_RESTART2 . .TP .B EINVAL -Bad magic numbers or \fIcmd\fP. +Bad magic numbers or +.IR op . .TP .B EPERM The calling process has insufficient privilege to call diff --git a/man2/recv.2 b/man2/recv.2 index 395236d..916cca3 100644 --- a/man2/recv.2 +++ b/man2/recv.2 @@ -10,7 +10,7 @@ .\" Modified 1998,1999 by Andi Kleen .\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin .\" -.TH recv 2 2023-07-18 "Linux man-pages 6.05.01" +.TH recv 2 2024-02-18 "Linux man-pages 6.7" .SH NAME recv, recvfrom, recvmsg \- receive a message from a socket .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "ssize_t recv(int " sockfd ", void " buf [. len "], size_t " len , .BI " int " flags ); .BI "ssize_t recvfrom(int " sockfd ", void " buf "[restrict ." len "], size_t " len , @@ -39,7 +39,7 @@ They may be used to receive data on both connectionless and connection-oriented sockets. This page first describes common features of all three system calls, and then describes the differences between the calls. -.PP +.P The only difference between .BR recv () and @@ -54,27 +54,27 @@ is generally equivalent to .BR read (2) (but see NOTES). Also, the following call -.PP +.P .in +4n .EX recv(sockfd, buf, len, flags); .EE .in -.PP +.P is equivalent to -.PP +.P .in +4n .EX recvfrom(sockfd, buf, len, flags, NULL, NULL); .EE .in -.PP +.P All three calls return the length of the message on successful completion. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from. -.PP +.P If no messages are available at the socket, the receive calls wait for a message to arrive, unless the socket is nonblocking (see .BR fcntl (2)), @@ -84,7 +84,7 @@ is set to .BR EAGAIN " or " EWOULDBLOCK . The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested. -.PP +.P An application can use .BR select (2), .BR poll (2), @@ -123,7 +123,7 @@ is a per-call option, whereas is a setting on the open file description (see .BR open (2)), which will affect all threads in the calling process -and as well as other processes that hold file descriptors +as well as other processes that hold file descriptors referring to the same open file description. .TP .BR MSG_ERRQUEUE " (since Linux 2.2)" @@ -250,7 +250,7 @@ places the received message into the buffer .IR buf . The caller must specify the size of the buffer in .IR len . -.PP +.P If .I src_addr is not NULL, @@ -278,7 +278,7 @@ The returned address is truncated if the buffer provided is too small; in this case, .I addrlen will return a value greater than was supplied to the call. -.PP +.P If the caller is not interested in the source address, .I src_addr and @@ -293,7 +293,7 @@ call is normally used only on a socket (see .BR connect (2)). It is equivalent to the call: -.PP +.P .in +4n .EX recvfrom(fd, buf, len, flags, NULL, 0); @@ -308,7 +308,7 @@ call uses a structure to minimize the number of directly supplied arguments. This structure is defined as follows in .IR <sys/socket.h> : -.PP +.P .in +4n .EX struct msghdr { @@ -322,7 +322,7 @@ struct msghdr { }; .EE .in -.PP +.P The .I msg_name field points to a caller-allocated buffer that is used to @@ -336,14 +336,14 @@ will contain the length of the returned address. If the application does not need to know the source address, .I msg_name can be specified as NULL. -.PP +.P The fields .I msg_iov and .I msg_iovlen describe scatter-gather locations, as discussed in .BR readv (2). -.PP +.P The field .IR msg_control , which has length @@ -358,9 +358,9 @@ should contain the length of the available buffer in .IR msg_control ; upon return from a successful call it will contain the length of the control message sequence. -.PP +.P The messages are of the form: -.PP +.P .in +4n .EX struct cmsghdr { @@ -373,10 +373,10 @@ struct cmsghdr { }; .EE .in -.PP +.P Ancillary data should be accessed only by the macros defined in .BR cmsg (3). -.PP +.P As an example, Linux uses this ancillary data mechanism to pass extended errors, IP options, or file descriptors over UNIX domain sockets. For further information on the use of ancillary data in various @@ -384,7 +384,7 @@ socket domains, see .BR unix (7) and .BR ip (7). -.PP +.P The .I msg_flags field in the @@ -427,14 +427,14 @@ if an error occurred. In the event of an error, .I errno is set to indicate the error. -.PP +.P When a stream socket peer has performed an orderly shutdown, the return value will be 0 (the traditional "end-of-file" return). -.PP +.P Datagram sockets in various domains (e.g., the UNIX and Internet domains) permit zero-length datagrams. When such a datagram is received, the return value is 0. -.PP +.P The value 0 may also be returned if the requested number of bytes to receive from a stream socket was 0. .SH ERRORS @@ -515,7 +515,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.4BSD (first appeared in 4.2BSD). -.PP +.P POSIX.1 describes only the .BR MSG_OOB , .BR MSG_PEEK , @@ -535,7 +535,7 @@ In this circumstance, has no effect (the datagram remains pending), while .BR recv () consumes the pending datagram. -.PP +.P See .BR recvmmsg (2) for information about a Linux-specific system call diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2 index d5b0f5a..f732d03 100644 --- a/man2/recvmmsg.2 +++ b/man2/recvmmsg.2 @@ -8,7 +8,7 @@ .\" Author: Arnaldo Carvalho de Melo <acme@redhat.com> .\" Date: Mon Oct 12 23:40:10 2009 -0700 .\" -.TH recvmmsg 2 2023-05-03 "Linux man-pages 6.05.01" +.TH recvmmsg 2 2023-10-31 "Linux man-pages 6.7" .SH NAME recvmmsg \- receive multiple messages on a socket .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sys/socket.h> -.PP +.P .BI "int recvmmsg(int " sockfd ", struct mmsghdr *" msgvec \ ", unsigned int " vlen "," .BI " int " flags ", struct timespec *" timeout ");" @@ -34,11 +34,11 @@ using a single system call. A further extension over .BR recvmsg (2) is support for a timeout on the receive operation. -.PP +.P The .I sockfd argument is the file descriptor of the socket to receive data from. -.PP +.P The .I msgvec argument is a pointer to an array of @@ -46,13 +46,13 @@ argument is a pointer to an array of structures. The size of this array is specified in .IR vlen . -.PP +.P The .I mmsghdr structure is defined in .I <sys/socket.h> as: -.PP +.P .in +4n .EX struct mmsghdr { @@ -61,7 +61,7 @@ struct mmsghdr { }; .EE .in -.PP +.P The .I msg_hdr field is a @@ -74,7 +74,7 @@ field is the number of bytes returned for the message in the entry. This field has the same value as the return value of a single .BR recvmsg (2) on the header. -.PP +.P The .I flags argument contains flags ORed together. @@ -86,7 +86,7 @@ with the following addition: Turns on .B MSG_DONTWAIT after the first message has been received. -.PP +.P The .I timeout argument points to a @@ -101,7 +101,7 @@ may overrun by a small amount.) If .I timeout is NULL, then the operation blocks indefinitely. -.PP +.P A blocking .BR recvmmsg () call blocks until @@ -112,7 +112,7 @@ A nonblocking call reads as many messages as are available (up to the limit specified by .IR vlen ) and returns immediately. -.PP +.P On return from .BR recvmmsg (), successive elements of @@ -143,7 +143,7 @@ In addition, the following error can occur: .B EINVAL .I timeout is invalid. -.PP +.P See also BUGS. .SH STANDARDS Linux. @@ -161,7 +161,7 @@ so that if up to .I vlen\-1 datagrams are received before the timeout expires, but then no further datagrams are received, the call will block forever. -.PP +.P If an error occurs after at least one message has been received, the call succeeds, and returns the number of messages received. The error code is expected to be returned on a subsequent call to @@ -176,20 +176,20 @@ to receive multiple messages on a socket and stores them in multiple buffers. The call returns if all buffers are filled or if the timeout specified has expired. -.PP +.P The following snippet periodically generates UDP datagrams containing a random number: -.PP +.P .in +4n .EX .RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234;" .B " sleep 0.25; done" .EE .in -.PP +.P These datagrams are read by the example application, which can give the following output: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man2/remap_file_pages.2 b/man2/remap_file_pages.2 index ab4ee51..f662c46 100644 --- a/man2/remap_file_pages.2 +++ b/man2/remap_file_pages.2 @@ -5,7 +5,7 @@ .\" 2003-12-10 Initial creation, Michael Kerrisk <mtk.manpages@gmail.com> .\" 2004-10-28 aeb, corrected prototype, prot must be 0 .\" -.TH remap_file_pages 2 2023-03-30 "Linux man-pages 6.05.01" +.TH remap_file_pages 2 2023-10-31 "Linux man-pages 6.7" .SH NAME remap_file_pages \- create a nonlinear file mapping .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sys/mman.h> -.PP +.P .BI "[[deprecated]] int remap_file_pages(void " addr [. size "], size_t " size , .BI " int " prot ", size_t " pgoff ", \ int " flags ); @@ -34,7 +34,7 @@ This change was made because the kernel code for this system call was complex, and it is believed to be little used or perhaps even completely unused. While it had some use cases in database applications on 32-bit systems, those use cases don't exist on 64-bit systems. -.PP +.P The .BR remap_file_pages () system call is used to create a nonlinear mapping, that is, a mapping @@ -46,7 +46,7 @@ over using repeated calls to .BR mmap (2) is that the former approach does not require the kernel to create additional VMA (Virtual Memory Area) data structures. -.PP +.P To create a nonlinear mapping we perform the following steps: .TP 3 1. @@ -64,7 +64,7 @@ to rearrange the correspondence between the pages of the mapping and the pages of the file. It is possible to map the same page of a file into multiple locations within the mapped region. -.PP +.P The .I pgoff and @@ -75,7 +75,7 @@ within the mapping: is a file offset in units of the system page size; .I size is the length of the region in bytes. -.PP +.P The .I addr argument serves two purposes. @@ -93,7 +93,7 @@ identified by and .I size will be placed. -.PP +.P The values specified in .I addr and @@ -107,11 +107,11 @@ to the nearest multiple of the page size. .\" This rounding is weird, and not consistent with the treatment of .\" the analogous arguments for munmap()/mprotect() and for mlock(). .\" MTK, 14 Sep 2005 -.PP +.P The .I prot argument must be specified as 0. -.PP +.P The .I flags argument has the same meaning as for diff --git a/man2/removexattr.2 b/man2/removexattr.2 index 1a9f53f..50a567e 100644 --- a/man2/removexattr.2 +++ b/man2/removexattr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH removexattr 2 2023-04-08 "Linux man-pages 6.05.01" +.TH removexattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME removexattr, lremovexattr, fremovexattr \- remove an extended attribute .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/xattr.h> -.PP +.P .BI "int removexattr(const char *" path ", const char *" name ); .BI "int lremovexattr(const char *" path ", const char *" name ); .BI "int fremovexattr(int " fd ", const char *" name ); @@ -27,20 +27,20 @@ with all inodes in the system (i.e., the data). A complete overview of extended attributes concepts can be found in .BR xattr (7). -.PP +.P .BR removexattr () removes the extended attribute identified by .I name and associated with the given .I path in the filesystem. -.PP +.P .BR lremovexattr () is identical to .BR removexattr (), except in the case of a symbolic link, where the extended attribute is removed from the link itself, not the file that it refers to. -.PP +.P .BR fremovexattr () is identical to .BR removexattr (), @@ -50,7 +50,7 @@ only the extended attribute is removed from the open file referred to by .BR open (2)) in place of .IR path . -.PP +.P An extended attribute name is a null-terminated string. The .I name @@ -73,7 +73,7 @@ The named attribute does not exist. .TP .B ENOTSUP Extended attributes are not supported by the filesystem, or are disabled. -.PP +.P In addition, the errors documented in .BR stat (2) can also occur. diff --git a/man2/rename.2 b/man2/rename.2 index 9963af6..6b538d4 100644 --- a/man2/rename.2 +++ b/man2/rename.2 @@ -10,7 +10,7 @@ .\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt <michael@moria.de> .\" 2007-03-25, mtk, added various text to DESCRIPTION. .\" -.TH rename 2 2023-03-30 "Linux man-pages 6.05.01" +.TH rename 2 2023-10-31 "Linux man-pages 6.7" .SH NAME rename, renameat, renameat2 \- change the name or location of a file .SH LIBRARY @@ -19,31 +19,31 @@ Standard C library .SH SYNOPSIS .nf .B #include <stdio.h> -.PP +.P .BI "int rename(const char *" oldpath ", const char *" newpath ); -.PP +.P .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" .B #include <stdio.h> -.PP +.P .BI "int renameat(int " olddirfd ", const char *" oldpath , .BI " int " newdirfd ", const char *" newpath ); .BI "int renameat2(int " olddirfd ", const char *" oldpath , .BI " int " newdirfd ", const char *" newpath \ ", unsigned int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .nf .BR renameat (): Since glibc 2.10: _POSIX_C_SOURCE >= 200809L Before glibc 2.10: _ATFILE_SOURCE -.PP +.P .BR renameat2 (): _GNU_SOURCE .fi @@ -56,10 +56,10 @@ are unaffected. Open file descriptors for .I oldpath are also unaffected. -.PP +.P Various restrictions determine whether or not the rename operation succeeds: see ERRORS below. -.PP +.P If .I newpath already exists, it will be atomically replaced, so that there is @@ -71,7 +71,7 @@ However, there will probably be a window in which both and .I newpath refer to the file being renamed. -.PP +.P If .I oldpath and @@ -79,7 +79,7 @@ and are existing hard links referring to the same file, then .BR rename () does nothing, and returns a success status. -.PP +.P If .I newpath exists but the operation fails for some reason, @@ -87,13 +87,13 @@ exists but the operation fails for some reason, guarantees to leave an instance of .I newpath in place. -.PP +.P .I oldpath can specify a directory. In this case, .I newpath must either not exist, or it must specify an empty directory. -.PP +.P If .I oldpath refers to a symbolic link, the link is renamed; if @@ -105,7 +105,7 @@ The system call operates in exactly the same way as .BR rename (), except for the differences described here. -.PP +.P If the pathname given in .I oldpath is relative, then it is interpreted relative to the directory @@ -115,7 +115,7 @@ referred to by the file descriptor the calling process, as is done by .BR rename () for a relative pathname). -.PP +.P If .I oldpath is relative and @@ -127,13 +127,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR rename ()). -.PP +.P If .I oldpath is absolute, then .I olddirfd is ignored. -.PP +.P The interpretation of .I newpath is as for @@ -141,7 +141,7 @@ is as for except that a relative pathname is interpreted relative to the directory referred to by the file descriptor .IR newdirfd . -.PP +.P See .BR openat (2) for an explanation of the need for @@ -157,7 +157,7 @@ call with a zero .I flags argument is equivalent to .BR renameat (). -.PP +.P The .I flags argument is a bit mask consisting of zero or more of the following flags: @@ -414,7 +414,7 @@ are not on the same mounted filesystem. .BR rename () does not work across different mount points, even if the same filesystem is mounted on both.) -.PP +.P The following additional errors can occur for .BR renameat () and @@ -437,7 +437,7 @@ or similar for .I newpath and .I newdirfd -.PP +.P The following additional errors can occur for .BR renameat2 (): .TP diff --git a/man2/request_key.2 b/man2/request_key.2 index 80187d1..dd2e39d 100644 --- a/man2/request_key.2 +++ b/man2/request_key.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH request_key 2 2023-05-03 "Linux man-pages 6.05.01" +.TH request_key 2 2024-02-25 "Linux man-pages 6.7" .SH NAME request_key \- request a key from the kernel's key management facility .SH LIBRARY @@ -13,7 +13,7 @@ Linux Key Management Utilities .SH SYNOPSIS .nf .B #include <keyutils.h> -.PP +.P .BI "key_serial_t request_key(const char *" type ", const char *" description , .BI " const char *_Nullable " callout_info , .BI " key_serial_t " dest_keyring ); @@ -30,13 +30,13 @@ If the key is found or created, attaches it to the keyring whose ID is specified in .I dest_keyring and returns the key's serial number. -.PP +.P .BR request_key () first recursively searches for a matching key in all of the keyrings attached to the calling process. The keyrings are searched in the order: thread-specific keyring, process-specific keyring, and then session keyring. -.PP +.P If .BR request_key () is called from a program invoked by @@ -48,7 +48,7 @@ supplementary group IDs, and security context to determine access. .\" David Howells: we can then have an arbitrarily long sequence .\" of "recursive" request-key upcalls. There is no limit, other .\" than number of PIDs, etc. -.PP +.P The search of the keyring tree is breadth-first: the keys in each keyring searched are checked for a match before any child keyrings are recursed into. @@ -57,18 +57,18 @@ Only keys for which the caller has permission be found, and only keyrings for which the caller has .I search permission may be searched. -.PP +.P If the key is not found and .I callout is NULL, then the call fails with the error .BR ENOKEY . -.PP +.P If the key is not found and .I callout is not NULL, then the kernel attempts to invoke a user-space program to instantiate the key. The details are given below. -.PP +.P The .I dest_keyring serial number may be that of a valid keyring for which the caller has @@ -94,13 +94,13 @@ This specifies the caller's UID-specific keyring (see .B KEY_SPEC_USER_SESSION_KEYRING This specifies the caller's UID-session keyring (see .BR user\-session\-keyring (7)). -.PP +.P When the .I dest_keyring is specified as 0 and no key construction has been performed, then no additional linking is done. -.PP +.P Otherwise, if .I dest_keyring is 0 and a new key is constructed, the new key will be linked @@ -180,7 +180,7 @@ This keyring is also expected to always exist. .\" .\" will all create a keyring under some circumstances. Whereas the rest, .\" such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't. -.PP +.P If the .BR keyctl (2) .B KEYCTL_SET_REQKEY_KEYRING @@ -227,7 +227,7 @@ The authorization key is constructed as follows: .RS .IP \[bu] 3 The key type is -.IR """.request_key_auth""" . +.IR \[dq].request_key_auth\[dq] . .IP \[bu] The key's UID and GID are the same as the corresponding filesystem IDs of the requesting process. @@ -263,10 +263,10 @@ This program is supplied with the following command-line arguments: .RS .IP [0] 5 The string -.IR """/sbin/request\-key""" . +.IR \[dq]/sbin/request\-key\[dq] . .IP [1] The string -.I """create""" +.I \[dq]create\[dq] (indicating that a key is to be created). .IP [2] The ID of the key that is to be instantiated. @@ -337,7 +337,7 @@ At this point, the .BR request_key () call completes, and the requesting program can continue execution. .RE -.PP +.P If these steps are unsuccessful, then an .B ENOKEY error will be returned to the caller of @@ -353,7 +353,7 @@ The purpose of this negatively instantiated key is to prevent (that require expensive .BR request\-key (8) upcalls) for a key that can't (at the moment) be positively instantiated. -.PP +.P Once the key has been instantiated, the authorization key .RB ( KEY_SPEC_REQKEY_AUTH_KEY ) is revoked, and the destination keyring @@ -361,7 +361,7 @@ is revoked, and the destination keyring is no longer accessible from the .BR request\-key (8) program. -.PP +.P If a key is created, then\[em]regardless of whether it is a valid key or a negatively instantiated key\[em]it will displace any other key with the same type and description from the keyring specified in @@ -429,7 +429,7 @@ argument started with a period (\[aq].\[aq]). Linux. .SH HISTORY Linux 2.6.10. -.PP +.P The ability to instantiate keys upon request was added .\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a in Linux 2.6.13. @@ -444,11 +444,11 @@ and arguments for the system call are taken from the values supplied in the command-line arguments. The call specifies the session keyring as the target keyring. -.PP +.P In order to demonstrate this program, we first create a suitable entry in the file .IR /etc/request\-key.conf . -.PP +.P .in +4n .EX $ sudo sh @@ -457,7 +457,7 @@ $ sudo sh # \fBexit\fP .EE .in -.PP +.P This entry specifies that when a new "user" key with the prefix "mtk:" must be instantiated, that task should be performed via the .BR keyctl (1) @@ -482,11 +482,11 @@ See for details of these .I % specifiers. -.PP +.P Then we run the program and check the contents of .I /proc/keys to verify that the requested key has been instantiated: -.PP +.P .in +4n .EX $ \fB./t_request_key user mtk:key1 "Payload data"\fP @@ -494,7 +494,7 @@ $ \fBgrep \[aq]2dddaf50\[aq] /proc/keys\fP 2dddaf50 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mtk:key1: 12 .EE .in -.PP +.P For another example of the use of this program, see .BR keyctl (2). .SS Program source @@ -549,7 +549,7 @@ main(int argc, char *argv[]) .BR user\-keyring (7), .BR user\-session\-keyring (7), .BR request\-key (8) -.PP +.P The kernel source files .I Documentation/security/keys/core.rst and diff --git a/man2/restart_syscall.2 b/man2/restart_syscall.2 index 4b0e101..87e8705 100644 --- a/man2/restart_syscall.2 +++ b/man2/restart_syscall.2 @@ -10,14 +10,14 @@ .\" .\" See also Section 11.3.3 of Understanding the Linux Kernel, 3rd edition .\" -.TH restart_syscall 2 2023-03-30 "Linux man-pages 6.05.01" +.TH restart_syscall 2 2023-10-31 "Linux man-pages 6.7" .SH NAME restart_syscall \- restart a system call after interruption by a stop signal .SH SYNOPSIS .nf .B long restart_syscall(void); .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see NOTES. .SH DESCRIPTION @@ -32,7 +32,7 @@ is later resumed after receiving a .B SIGCONT signal. This system call is designed only for internal use by the kernel. -.PP +.P .BR restart_syscall () is used for restarting only those system calls that, when restarted, should adjust their time-related parameters\[em]namely @@ -83,7 +83,7 @@ Linux 2.6. There is no glibc wrapper for this system call, because it is intended for use only by the kernel and should never be called by applications. -.PP +.P The kernel uses .BR restart_syscall () to ensure that when a system call is restarted @@ -105,7 +105,7 @@ Notable examples of system calls that suffer this problem are .BR select (2), and .BR pselect (2). -.PP +.P From user space, the operation of .BR restart_syscall () is largely invisible: diff --git a/man2/rmdir.2 b/man2/rmdir.2 index 5bd7370..a1dc594 100644 --- a/man2/rmdir.2 +++ b/man2/rmdir.2 @@ -7,7 +7,7 @@ .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH rmdir 2 2023-03-30 "Linux man-pages 6.05.01" +.TH rmdir 2 2023-10-31 "Linux man-pages 6.7" .SH NAME rmdir \- delete a directory .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int rmdir(const char *" pathname ); .fi .SH DESCRIPTION diff --git a/man2/rt_sigqueueinfo.2 b/man2/rt_sigqueueinfo.2 index b8b0157..d2d2eec 100644 --- a/man2/rt_sigqueueinfo.2 +++ b/man2/rt_sigqueueinfo.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH rt_sigqueueinfo 2 2023-03-30 "Linux man-pages 6.05.01" +.TH rt_sigqueueinfo 2 2023-10-31 "Linux man-pages 6.7" .SH NAME rt_sigqueueinfo, rt_tgsigqueueinfo \- queue a signal and data .SH LIBRARY @@ -13,13 +13,13 @@ Standard C library .BR "#include <linux/signal.h>" " /* Definition of " SI_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_rt_sigqueueinfo, pid_t " tgid , .BI " int " sig ", siginfo_t *" info ); .BI "int syscall(SYS_rt_tgsigqueueinfo, pid_t " tgid ", pid_t " tid , .BI " int " sig ", siginfo_t *" info ); .fi -.PP +.P .IR Note : There are no glibc wrappers for these system calls; see NOTES. .SH DESCRIPTION @@ -34,13 +34,13 @@ by establishing a signal handler with the .BR sigaction (2) .B SA_SIGINFO flag. -.PP +.P These system calls are not intended for direct application use; they are provided to allow the implementation of .BR sigqueue (3) and .BR pthread_sigqueue (3). -.PP +.P The .BR rt_sigqueueinfo () system call sends the signal @@ -52,7 +52,7 @@ to the thread group with the ID corresponds to the traditional UNIX process ID.) The signal will be delivered to an arbitrary member of the thread group (i.e., one of the threads that is not currently blocking the signal). -.PP +.P The .I info argument specifies the data to accompany the signal. @@ -103,14 +103,14 @@ For more information, see the description of the last .RI ( "union sigval" ) argument of .BR sigqueue (3). -.PP +.P Internally, the kernel sets the .I si_signo field to the value specified in .IR sig , so that the receiver of the signal can also obtain the signal number via that field. -.PP +.P The .BR rt_tgsigqueueinfo () system call is like @@ -158,7 +158,7 @@ is invalid. No thread group matching .I tgid was found. -.PP +.P .BR rt_tgsigqueinfo (): No thread matching .I tgid @@ -179,7 +179,7 @@ Since these system calls are not intended for application use, there are no glibc wrapper functions; use .BR syscall (2) in the unlikely case that you want to call them directly. -.PP +.P As with .BR kill (2), the null signal (0) can be used to check if the specified process diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2 index 63d5c83..b2038e5 100644 --- a/man2/s390_guarded_storage.2 +++ b/man2/s390_guarded_storage.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH s390_guarded_storage 2 2023-03-30 "Linux man-pages 6.05.01" +.TH s390_guarded_storage 2 2023-10-31 "Linux man-pages 6.7" .SH NAME s390_guarded_storage \- operations with z/Architecture guarded storage facility .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .BR "#include <sys/syscall.h> " \ "/* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_s390_guarded_storage, int " command , .BI " struct gs_cb *" gs_cb ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR s390_guarded_storage (), @@ -29,7 +29,7 @@ The .BR s390_guarded_storage () system call enables the use of the Guarded Storage Facility (a z/Architecture-specific feature) for user-space processes. -.PP +.P .\" The description is based on .\" http://www-05.ibm.com/de/linux-on-z-ws-us/agenda/pdfs/8_-_Linux_Whats_New_-_Stefan_Raspl.pdf .\" and "z/Architecture Principles of Operation" obtained from @@ -40,7 +40,7 @@ reading a pointer with a newly introduced "Load Guarded" (LGG) or "Load Logical and Shift Guarded" (LLGFSG) instructions will cause a range check on the loaded value and invoke a (previously set up) user-space handler if one of the guarded regions is affected. -.PP +.P The .\" The command description is copied from v4.12-rc1~139^2~56^2 commit message .I command @@ -88,7 +88,7 @@ The broadcast guarded storage control block is consumed; a second broadcast without a refresh of the stored control block with .B GS_SET_BC_CB will not have any effect. -.PP +.P The .I gs_cb argument specifies the address of a guarded storage control block structure @@ -99,7 +99,7 @@ command; all other aforementioned commands ignore this argument. On success, the return value of .BR s390_guarded_storage () is 0. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -138,7 +138,7 @@ instructions and Guarded Storage Control Block and Guarded Storage Event Parameter List structure layouts is available in "z/Architecture Principles of Operations" beginning from the twelfth edition. -.PP +.P The .I gs_cb structure has a field @@ -153,7 +153,7 @@ field), and its layout is available as a structure type definition in the .I asm/guarded_storage.h header. -.\" .PP +.\" .P .\" For the example of using the guarded storage facility, see .\" .UR https://developer.ibm.com/javasdk/2017/09/25/concurrent-scavenge-using-guarded-storage-facility-works/ .\" the article with the description of its usage in the Java Garbage Collection diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2 index 07788e9..f6b8c46 100644 --- a/man2/s390_pci_mmio_write.2 +++ b/man2/s390_pci_mmio_write.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH s390_pci_mmio_write 2 2023-03-30 "Linux man-pages 6.05.01" +.TH s390_pci_mmio_write 2 2023-10-31 "Linux man-pages 6.7" .SH NAME s390_pci_mmio_write, s390_pci_mmio_read \- transfer data to/from PCI MMIO memory page @@ -14,14 +14,14 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_s390_pci_mmio_write, unsigned long " mmio_addr , .BI " const void " user_buffer [. length "], \ size_t " length ); .BI "int syscall(SYS_s390_pci_mmio_read, unsigned long " mmio_addr , .BI " void " user_buffer [. length "], size_t " length ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -44,7 +44,7 @@ data from the PCI MMIO memory location specified by .I mmio_addr to the user-space buffer .IR user_buffer . -.PP +.P These system calls must be used instead of the simple assignment or data-transfer operations that are used to access the PCI MMIO memory areas mapped to user space on the Linux System z platform. diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2 index fb1be13..a01421b 100644 --- a/man2/s390_runtime_instr.2 +++ b/man2/s390_runtime_instr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH s390_runtime_instr 2 2023-03-30 "Linux man-pages 6.05.01" +.TH s390_runtime_instr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation .SH LIBRARY @@ -14,10 +14,10 @@ Standard C library .BR "#include <asm/runtime_instr.h>" " /* Definition of " S390_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_s390_runtime_instr, int " command ", int " signum ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR s390_runtime_instr (), @@ -28,7 +28,7 @@ The .BR s390_runtime_instr () system call starts or stops CPU run-time instrumentation for the calling thread. -.PP +.P The .I command argument controls whether run-time instrumentation is started @@ -36,7 +36,7 @@ argument controls whether run-time instrumentation is started 1) or stopped .RB ( S390_RUNTIME_INSTR_STOP , 2) for the calling thread. -.PP +.P The .I signum argument specifies the number of a real-time signal. @@ -90,7 +90,7 @@ The header file is available .\" commit df2f815a7df7edb5335a3bdeee6a8f9f6f9c35c4 since Linux 4.16. -.PP +.P Starting with Linux 4.4, support for signalling was removed, as was the check whether .I signum diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2 index 9c6af82..1b0023e 100644 --- a/man2/s390_sthyi.2 +++ b/man2/s390_sthyi.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH s390_sthyi 2 2023-03-30 "Linux man-pages 6.05.01" +.TH s390_sthyi 2 2023-10-31 "Linux man-pages 6.7" .SH NAME s390_sthyi \- emulate STHYI instruction .SH LIBRARY @@ -14,12 +14,12 @@ Standard C library .BR "#include <asm/sthyi.h>" " /* Definition of " STHYI_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_s390_sthyi, unsigned long " function_code , .BI " void *" resp_buffer ", uint64_t *" return_code , .BI " unsigned long " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR s390_sthyi (), @@ -33,7 +33,7 @@ It provides hardware resource information for the machine and its virtualization levels. This includes CPU type and capacity, as well as the machine model and other metrics. -.PP +.P The .I function_code argument indicates which function to perform. @@ -42,7 +42,7 @@ The following code(s) are supported: .B STHYI_FC_CP_IFL_CAP Return CP (Central Processor) and IFL (Integrated Facility for Linux) capacity information. -.PP +.P The .I resp_buffer argument specifies the address of a response buffer. @@ -54,7 +54,7 @@ the buffer must be one page (4K) in size. If the system call returns 0, the response buffer will be filled with CPU capacity information. Otherwise, the response buffer's content is unchanged. -.PP +.P The .I return_code argument stores the return code of the STHYI instruction, @@ -65,14 +65,14 @@ Success. .TP 4 Unsupported function code. -.PP +.P For further details about .IR return_code , .IR function_code , and .IR resp_buffer , see the reference given in NOTES. -.PP +.P The .I flags argument is provided to allow for future extensions and currently @@ -88,7 +88,7 @@ A return value of 3 indicates "unsupported function code" and the content of .I *resp_buffer is unchanged. The return values 1 and 2 are reserved. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -122,11 +122,11 @@ For details of the STHYI instruction, see .UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm the documentation page .UE . -.PP +.P When the system call interface is used, the response buffer doesn't have to fulfill alignment requirements described in the STHYI instruction definition. -.PP +.P The kernel caches the response (for up to one second, as of Linux 4.16). Subsequent system call invocations may return the cached response. .SH SEE ALSO diff --git a/man2/sched_get_priority_max.2 b/man2/sched_get_priority_max.2 index 491e134..30a66fa 100644 --- a/man2/sched_get_priority_max.2 +++ b/man2/sched_get_priority_max.2 @@ -7,7 +7,7 @@ .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de> .\" revision .\" -.TH sched_get_priority_max 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_get_priority_max 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_get_priority_max, sched_get_priority_min \- get static priority range .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sched.h> -.PP +.P .BI "int sched_get_priority_max(int " policy ); .BI "int sched_get_priority_min(int " policy ); .fi @@ -41,7 +41,7 @@ and .BR SCHED_DEADLINE . Further details about these policies can be found in .BR sched (7). -.PP +.P Processes with numerically higher priority values are scheduled before processes with numerically lower priority values. Thus, the value @@ -50,7 +50,7 @@ returned by will be greater than the value returned by .BR sched_get_priority_min (). -.PP +.P Linux allows the static priority range 1 to 99 for the .B SCHED_FIFO and @@ -58,7 +58,7 @@ and policies, and the priority 0 for the remaining policies. Scheduling priority ranges for the various policies are not alterable. -.PP +.P The range of scheduling priorities may vary on other POSIX systems, thus it is a good idea for portable applications to use a virtual priority range and map it to the interval given by @@ -71,7 +71,7 @@ a spread of at least 32 between the maximum and the minimum values for .B SCHED_FIFO and .BR SCHED_RR . -.PP +.P POSIX systems on which .BR sched_get_priority_max () and diff --git a/man2/sched_rr_get_interval.2 b/man2/sched_rr_get_interval.2 index cbd6247..b547cf2 100644 --- a/man2/sched_rr_get_interval.2 +++ b/man2/sched_rr_get_interval.2 @@ -7,7 +7,7 @@ .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de> .\" revision .\" -.TH sched_rr_get_interval 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_rr_get_interval 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_rr_get_interval \- get the SCHED_RR interval for the named process .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sched.h> -.PP +.P .BI "int sched_rr_get_interval(pid_t " pid ", struct timespec *" tp ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ the round-robin time quantum for the process identified by The specified process should be running under the .B SCHED_RR scheduling policy. -.PP +.P If .I pid is zero, the time quantum for the calling process is written into diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2 index 9389e09..7512129 100644 --- a/man2/sched_setaffinity.2 +++ b/man2/sched_setaffinity.2 @@ -12,7 +12,7 @@ .\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a .\" separate CPU_SET(3) page. .\" -.TH sched_setaffinity 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sched_setaffinity 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_setaffinity, sched_getaffinity \- \ set and get a thread's CPU affinity mask @@ -23,7 +23,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sched.h> -.PP +.P .BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize , .BI " const cpu_set_t *" mask ); .BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize , @@ -43,14 +43,14 @@ Restricting a thread to run on a single CPU also avoids the performance cost caused by the cache invalidation that occurs when a thread ceases to execute on one CPU and then recommences execution on a different CPU. -.PP +.P A CPU affinity mask is represented by the .I cpu_set_t structure, a "CPU set", pointed to by .IR mask . A set of macros for manipulating CPU sets is described in .BR CPU_SET (3). -.PP +.P .BR sched_setaffinity () sets the CPU affinity mask of the thread whose ID is .I pid @@ -65,14 +65,14 @@ is the length (in bytes) of the data pointed to by .IR mask . Normally this argument would be specified as .IR "sizeof(cpu_set_t)" . -.PP +.P If the thread specified by .I pid is not currently running on one of the CPUs specified in .IR mask , then that thread is migrated to one of the CPUs specified in .IR mask . -.PP +.P .BR sched_getaffinity () writes the affinity mask of the thread whose ID is .I pid @@ -139,7 +139,7 @@ Linux. .SH HISTORY Linux 2.5.8, glibc 2.3. -.PP +.P Initially, the glibc interfaces included a .I cpusetsize argument, typed as @@ -161,7 +161,7 @@ runs if the "cpuset" mechanism described in is being used. These restrictions on the actual set of CPUs on which the thread will run are silently imposed by the kernel. -.PP +.P There are various ways of determining the number of CPUs available on the system, including: inspecting the contents of .IR /proc/cpuinfo ; @@ -173,10 +173,10 @@ and .B _SC_NPROCESSORS_ONLN parameters; and inspecting the list of CPU directories under .IR /sys/devices/system/cpu/ . -.PP +.P .BR sched (7) has a description of the Linux scheduling scheme. -.PP +.P The affinity mask is a per-thread attribute that can be adjusted independently for each of the threads in a thread group. The value returned from a call to @@ -193,7 +193,7 @@ will set the attribute for the main thread of the thread group. .BR pthread_setaffinity_np (3) instead of .BR sched_setaffinity ().) -.PP +.P The .I isolcpus boot option can be used to isolate one or more CPUs at boot time, @@ -211,7 +211,7 @@ As noted in that file, is the preferred mechanism of isolating CPUs (versus the alternative of manually setting the CPU affinity of all processes on the system). -.PP +.P A child created via .BR fork (2) inherits its parent's CPU affinity mask. @@ -225,7 +225,7 @@ being typed as .IR "unsigned long\ *" , reflecting the fact that the underlying implementation of CPU sets is a simple bit mask. -.PP +.P On success, the raw .BR sched_getaffinity () system call returns the number of bytes placed copied into the @@ -249,13 +249,13 @@ meaning that the maximum CPU number that can be represented is 1023. .\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html If the kernel CPU affinity mask is larger than 1024, then calls of the form: -.PP +.P .in +4n .EX sched_getaffinity(pid, sizeof(cpu_set_t), &mask); .EE .in -.PP +.P fail with the error .BR EINVAL , the error produced by the underlying system call for the case where the @@ -265,7 +265,7 @@ size specified in is smaller than the size of the affinity mask used by the kernel. (Depending on the system CPU topology, the kernel affinity mask can be substantially larger than the number of active CPUs in the system.) -.PP +.P When working on systems with large kernel CPU affinity masks, one must dynamically allocate the .I mask @@ -276,7 +276,7 @@ of the required mask using .BR sched_getaffinity () calls with increasing mask sizes (until the call does not fail with the error .BR EINVAL ). -.PP +.P Be aware that .BR CPU_ALLOC (3) may allocate a slightly larger CPU set than requested @@ -300,16 +300,16 @@ The program takes three command-line arguments: the CPU number for the parent, the CPU number for the child, and the number of loop iterations that both processes should perform. -.PP +.P As the sample runs below demonstrate, the amount of real and CPU time consumed when running the program will depend on intra-core caching effects and whether the processes are using the same CPU. -.PP +.P We first employ .BR lscpu (1) to determine that this (x86) system has two cores, each with two CPUs: -.PP +.P .in +4n .EX $ \fBlscpu | egrep \-i \[aq]core.*:|socket\[aq]\fP @@ -318,12 +318,12 @@ Core(s) per socket: 2 Socket(s): 1 .EE .in -.PP +.P We then time the operation of the example program for three cases: both processes running on the same CPU; both processes running on different CPUs on the same core; and both processes running on different CPUs on different cores. -.PP +.P .in +4n .EX $ \fBtime \-p ./a.out 0 0 100000000\fP diff --git a/man2/sched_setattr.2 b/man2/sched_setattr.2 index b4975c6..546ac31 100644 --- a/man2/sched_setattr.2 +++ b/man2/sched_setattr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sched_setattr 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_setattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_setattr, sched_getattr \- set and get scheduling policy and attributes @@ -15,14 +15,14 @@ Standard C library .BR "#include <sched.h>" " /* Definition of " SCHED_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_sched_setattr, pid_t " pid ", struct sched_attr *" attr , .BI " unsigned int " flags ); .BI "int syscall(SYS_sched_getattr, pid_t " pid ", struct sched_attr *" attr , .BI " unsigned int " size ", unsigned int " flags ); .fi .\" FIXME . Add feature test macro requirements -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -38,7 +38,7 @@ If .I pid equals zero, the scheduling policy and attributes of the calling thread will be set. -.PP +.P Currently, Linux supports the following "normal" (i.e., non-real-time) scheduling policies as values that may be specified in .IR policy : @@ -55,7 +55,7 @@ for "batch" style execution of processes; and for running .I very low priority background jobs. -.PP +.P Various "real-time" policies are also supported, for special time-critical applications that need precise control over the way in which runnable threads are selected for execution. @@ -70,20 +70,20 @@ a first-in, first-out policy; and .TP .B SCHED_RR a round-robin policy. -.PP +.P Linux also provides the following policy: .TP 14 .B SCHED_DEADLINE a deadline scheduling policy; see .BR sched (7) for details. -.PP +.P The .I attr argument is a pointer to a structure that defines the new scheduling policy and attributes for the specified thread. This structure has the following form: -.PP +.P .in +4n .EX struct sched_attr { @@ -101,7 +101,7 @@ struct sched_attr { }; .EE .in -.PP +.P The fields of the .I sched_attr structure are as follows: @@ -228,7 +228,7 @@ The value is expressed in nanoseconds. .I sched_period This field specifies the "Period" parameter for deadline scheduling. The value is expressed in nanoseconds. -.PP +.P The .I flags argument is provided to allow for future extensions to the interface; @@ -246,7 +246,7 @@ If equals zero, the scheduling policy and attributes of the calling thread will be retrieved. -.PP +.P The .I size argument should be set to the size of the @@ -256,7 +256,7 @@ The value must be at least as large as the size of the initially published .I sched_attr structure, or the call fails with the error .BR EINVAL . -.PP +.P The retrieved scheduling attributes are placed in the fields of the .I sched_attr structure pointed to by @@ -266,7 +266,7 @@ The kernel sets to the size of its .I sched_attr structure. -.PP +.P If the caller-provided .I attr buffer is larger than the kernel's @@ -280,7 +280,7 @@ outside the provided space. As with .BR sched_setattr (), these semantics allow for future extensibility of the interface. -.PP +.P The .I flags argument is provided to allow for future extensions to the interface; @@ -312,7 +312,7 @@ is not zero. The thread whose ID is .I pid could not be found. -.PP +.P In addition, .BR sched_getattr () can fail for the following reasons: @@ -329,7 +329,7 @@ is too small. is invalid; that is, it is smaller than the initial version of the .I sched_attr structure (48 bytes) or larger than the system page size. -.PP +.P In addition, .BR sched_setattr () can fail for the following reasons: @@ -380,7 +380,7 @@ Linux 3.14. .SH NOTES glibc does not provide wrappers for these system calls; call them using .BR syscall (2). -.PP +.P .BR sched_setattr () provides a superset of the functionality of .BR sched_setscheduler (2), @@ -406,7 +406,7 @@ failed with the error instead of .B E2BIG for the case described in ERRORS. -.PP +.P Up to Linux 5.3, .BR sched_getattr () failed with the error diff --git a/man2/sched_setparam.2 b/man2/sched_setparam.2 index f054f5d..3e69961 100644 --- a/man2/sched_setparam.2 +++ b/man2/sched_setparam.2 @@ -8,7 +8,7 @@ .\" revision .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH sched_setparam 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_setparam 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_setparam, sched_getparam \- set and get scheduling parameters .SH LIBRARY @@ -17,10 +17,10 @@ Standard C library .SH SYNOPSIS .nf .B #include <sched.h> -.PP +.P .BI "int sched_setparam(pid_t " pid ", const struct sched_param *" param ); .BI "int sched_getparam(pid_t " pid ", struct sched_param *" param ); -.PP +.P \fBstruct sched_param { ... int \fIsched_priority\fB; @@ -40,13 +40,13 @@ policy of the thread identified by See .BR sched (7) for a description of the scheduling policies supported under Linux. -.PP +.P .BR sched_getparam () retrieves the scheduling parameters for the thread identified by \fIpid\fP. If \fIpid\fP is zero, then the parameters of the calling thread are retrieved. -.PP +.P .BR sched_setparam () checks the validity of \fIparam\fP for the scheduling policy of the thread. @@ -55,11 +55,11 @@ range given by .BR sched_get_priority_min (2) and .BR sched_get_priority_max (2). -.PP +.P For a discussion of the privileges and resource limits related to scheduling priority and policy, see .BR sched (7). -.PP +.P POSIX systems on which .BR sched_setparam () and diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2 index 20ad5c2..ec67aef 100644 --- a/man2/sched_setscheduler.2 +++ b/man2/sched_setscheduler.2 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH sched_setscheduler 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_setscheduler 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_setscheduler, sched_getscheduler \- set and get scheduling policy/parameters @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sched.h> -.PP +.P .BI "int sched_setscheduler(pid_t " pid ", int " policy , .BI " const struct sched_param *" param ); .BI "int sched_getscheduler(pid_t " pid ); @@ -26,11 +26,11 @@ sets both the scheduling policy and parameters for the thread whose ID is specified in \fIpid\fP. If \fIpid\fP equals zero, the scheduling policy and parameters of the calling thread will be set. -.PP +.P The scheduling parameters are specified in the .I param argument, which is a pointer to a structure of the following form: -.PP +.P .in +4n .EX struct sched_param { @@ -40,13 +40,13 @@ struct sched_param { }; .EE .in -.PP +.P In the current implementation, the structure contains only one field, .IR sched_priority . The interpretation of .I param depends on the selected policy. -.PP +.P Currently, Linux supports the following "normal" (i.e., non-real-time) scheduling policies as values that may be specified in .IR policy : @@ -63,11 +63,11 @@ for "batch" style execution of processes; and for running .I very low priority background jobs. -.PP +.P For each of the above policies, .I param\->sched_priority must be 0. -.PP +.P Various "real-time" policies are also supported, for special time-critical applications that need precise control over the way in which runnable threads are selected for execution. @@ -82,7 +82,7 @@ a first-in, first-out policy; and .TP .B SCHED_RR a round-robin policy. -.PP +.P For each of the above policies, .I param\->sched_priority specifies a scheduling priority for the thread. @@ -93,7 +93,7 @@ and with the specified .IR policy . On Linux, these system calls return, respectively, 1 and 99. -.PP +.P Since Linux 2.6.32, the .B SCHED_RESET_ON_FORK flag can be ORed in @@ -106,7 +106,7 @@ do not inherit privileged scheduling policies. See .BR sched (7) for details. -.PP +.P .BR sched_getscheduler () returns the current scheduling policy of the thread identified by \fIpid\fP. @@ -155,7 +155,7 @@ and details vary across systems. For example, the Solaris 7 manual page says that the real or effective user ID of the caller must match the real user ID or the save set-user-ID of the target. -.PP +.P The scheduling policy and parameters are in fact per-thread attributes on Linux. The value returned from a call to @@ -178,7 +178,7 @@ instead of the system calls.) .SH STANDARDS POSIX.1-2008 (but see BUGS below). -.PP +.P .B SCHED_BATCH and .B SCHED_IDLE @@ -194,7 +194,7 @@ That page also describes an additional policy, .BR SCHED_DEADLINE , which is settable only via .BR sched_setattr (2). -.PP +.P POSIX systems on which .BR sched_setscheduler () and diff --git a/man2/sched_yield.2 b/man2/sched_yield.2 index 154fd4f..caf7792 100644 --- a/man2/sched_yield.2 +++ b/man2/sched_yield.2 @@ -7,7 +7,7 @@ .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de> .\" revision .\" -.TH sched_yield 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sched_yield 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_yield \- yield the processor .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sched.h> -.PP +.P .B int sched_yield(void); .fi .SH DESCRIPTION @@ -40,7 +40,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001 (but optional). POSIX.1-2008. -.PP +.P Before POSIX.1-2008, systems on which .BR sched_yield () @@ -59,12 +59,12 @@ Use of with nondeterministic scheduling policies such as .B SCHED_OTHER is unspecified and very likely means your application design is broken. -.PP +.P If the calling thread is the only thread in the highest priority list at that time, it will continue to run after a call to .BR sched_yield (). -.PP +.P Avoid calling .BR sched_yield () unnecessarily or inappropriately diff --git a/man2/seccomp.2 b/man2/seccomp.2 index 6b32eec..b3f8026 100644 --- a/man2/seccomp.2 +++ b/man2/seccomp.2 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH seccomp 2 2023-05-03 "Linux man-pages 6.05.01" +.TH seccomp 2 2023-10-31 "Linux man-pages 6.7" .SH NAME seccomp \- operate on Secure Computing state of the process .SH LIBRARY @@ -23,11 +23,11 @@ Standard C library .\" need <sys/ptrace.h> .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_seccomp, unsigned int " operation ", unsigned int " flags , .BI " void *" args ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR seccomp (), @@ -38,7 +38,7 @@ The .BR seccomp () system call operates on the Secure Computing (seccomp) state of the calling process. -.PP +.P Currently, Linux supports the following .I operation values: @@ -290,7 +290,7 @@ When adding filters via .BR SECCOMP_SET_MODE_FILTER , .I args points to a filter program: -.PP +.P .in +4n .EX struct sock_fprog { @@ -300,9 +300,9 @@ struct sock_fprog { }; .EE .in -.PP +.P Each program must contain one or more BPF instructions: -.PP +.P .in +4n .EX struct sock_filter { /* Filter block */ @@ -313,7 +313,7 @@ struct sock_filter { /* Filter block */ }; .EE .in -.PP +.P When executing the instructions, the BPF program operates on the system call information made available (i.e., use the .B BPF_ABS @@ -324,7 +324,7 @@ addressing mode) as a (read-only) .\" that would need to use ptrace to catch the call and directly .\" modify the registers before continuing with the call. buffer of the following form: -.PP +.P .in +4n .EX struct seccomp_data { @@ -336,7 +336,7 @@ struct seccomp_data { }; .EE .in -.PP +.P Because numbering of system calls varies between architectures and some architectures (e.g., x86-64) allow user-space code to use the calling conventions of multiple architectures @@ -346,7 +346,7 @@ to execute binaries that employ the different conventions), it is usually necessary to verify the value of the .I arch field. -.PP +.P It is strongly recommended to use an allow-list approach whenever possible because such an approach is more robust and simple. A deny-list will have to be updated whenever a potentially @@ -357,7 +357,7 @@ a deny-list bypass. See also .I Caveats below. -.PP +.P The .I arch field is not unique for all calling conventions. @@ -379,7 +379,7 @@ is used on the system call number to tell the two ABIs apart. .\" will have a value that is not all-ones, and this will trigger .\" an extra instruction in system_call to mask off the extra bit, .\" so that the syscall table indexing still works. -.PP +.P This means that a policy must either deny all syscalls with .B __X32_SYSCALL_BIT or it must recognize syscalls with and without @@ -393,7 +393,7 @@ values with .B __X32_SYSCALL_BIT set can be bypassed by a malicious program that sets .BR __X32_SYSCALL_BIT . -.PP +.P Additionally, kernels prior to Linux 5.4 incorrectly permitted .I nr in the ranges 512-547 as well as the corresponding non-x32 syscalls ORed @@ -415,7 +415,7 @@ On Linux 5.4 and newer, such system calls will fail with the error .BR ENOSYS , without doing anything. -.PP +.P The .I instruction_pointer field provides the address of the machine-language instruction that @@ -429,7 +429,7 @@ made the system call. and .BR mprotect (2) system calls to prevent the program from subverting such checks.) -.PP +.P When checking values from .IR args , keep in mind that arguments are often @@ -443,7 +443,7 @@ a system call that takes an argument of type .IR int , the more-significant half of the argument register is ignored by the system call, but visible in the seccomp data. -.PP +.P A seccomp filter returns a 32-bit value consisting of two parts: the most significant 16 bits (corresponding to the mask defined by the constant @@ -452,7 +452,7 @@ contain one of the "action" values listed below; the least significant 16-bits (defined by the constant .BR SECCOMP_RET_DATA ) are "data" to be associated with this return value. -.PP +.P If multiple filters exist, they are \fIall\fP executed, in reverse order of their addition to the filter tree\[em]that is, the most recently installed filter is executed first. @@ -476,7 +476,7 @@ avoiding a check for this uncommon case.) The return value for the evaluation of a given system call is the first-seen action value of highest precedence (along with its accompanying data) returned by execution of all of the filters. -.PP +.P In decreasing order of precedence, the action values that may be returned by a seccomp filter are: .TP @@ -680,7 +680,7 @@ file. .TP .B SECCOMP_RET_ALLOW This value results in the system call being executed. -.PP +.P If an action value other than one of the above is specified, then the filter action is treated as either .B SECCOMP_RET_KILL_PROCESS @@ -871,21 +871,21 @@ Rather than hand-coding seccomp filters as shown in the example below, you may prefer to employ the .I libseccomp library, which provides a front-end for generating seccomp filters. -.PP +.P The .I Seccomp field of the .IR /proc/ pid /status file provides a method of viewing the seccomp mode of a process; see .BR proc (5). -.PP +.P .BR seccomp () provides a superset of the functionality provided by the .BR prctl (2) .B PR_SET_SECCOMP operation (which does not support .IR flags ). -.PP +.P Since Linux 4.4, the .BR ptrace (2) .B PTRACE_SECCOMP_GET_FILTER @@ -966,14 +966,14 @@ but starting in glibc 2.26, the implementation switched to calling .BR openat (2) on all architectures. .RE -.PP +.P The consequence of the above points is that it may be necessary to filter for a system call other than might be expected. Various manual pages in Section 2 provide helpful details about the differences between wrapper functions and the underlying system calls in subsections entitled .IR "C library/kernel differences" . -.PP +.P Furthermore, note that the application of seccomp filters even risks causing bugs in an application, when the filters cause unexpected failures for legitimate operations @@ -1019,7 +1019,7 @@ If the program attempts to execute the system call with the specified number, the BPF filter causes the system call to fail, with .I errno being set to the specified error number. -.PP +.P The remaining command-line arguments specify the pathname and additional arguments of a program that the example program should attempt to execute using @@ -1028,11 +1028,11 @@ that the example program should attempt to execute using .BR execve (2) system call). Some example runs of the program are shown below. -.PP +.P First, we display the architecture that we are running on (x86-64) and then construct a shell function that looks up system call numbers on this architecture: -.PP +.P .in +4n .EX $ \fBuname \-m\fP @@ -1043,25 +1043,25 @@ $ \fBsyscall_nr() { }\fP .EE .in -.PP +.P When the BPF filter rejects a system call (case [2] above), it causes the system call to fail with the error number specified on the command line. In the experiments shown here, we'll use error number 99: -.PP +.P .in +4n .EX $ \fBerrno 99\fP EADDRNOTAVAIL 99 Cannot assign requested address .EE .in -.PP +.P In the following example, we attempt to run the command .BR whoami (1), but the BPF filter rejects the .BR execve (2) system call, so that the command is not even executed: -.PP +.P .in +4n .EX $ \fBsyscall_nr execve\fP @@ -1074,13 +1074,13 @@ $ \fB./a.out 59 0xC000003E 99 /bin/whoami\fP execv: Cannot assign requested address .EE .in -.PP +.P In the next example, the BPF filter rejects the .BR write (2) system call, so that, although it is successfully started, the .BR whoami (1) command is not able to write output: -.PP +.P .in +4n .EX $ \fBsyscall_nr write\fP @@ -1088,12 +1088,12 @@ $ \fBsyscall_nr write\fP $ \fB./a.out 1 0xC000003E 99 /bin/whoami\fP .EE .in -.PP +.P In the final example, the BPF filter rejects a system call that is not used by the .BR whoami (1) command, so it is able to successfully execute and produce output: -.PP +.P .in +4n .EX $ \fBsyscall_nr preadv\fP @@ -1218,7 +1218,7 @@ main(int argc, char *argv[]) .BR proc (5), .BR signal (7), .BR socket (7) -.PP +.P Various pages from the .I libseccomp library, including: @@ -1228,7 +1228,7 @@ library, including: .BR seccomp_load (3), and .BR seccomp_rule_add (3). -.PP +.P The kernel source files .I Documentation/networking/filter.txt and @@ -1237,7 +1237,7 @@ and (or .I Documentation/prctl/seccomp_filter.txt before Linux 4.13). -.PP +.P McCanne, S.\& and Jacobson, V.\& (1992) .IR "The BSD Packet Filter: A New Architecture for User-level Packet Capture" , Proceedings of the USENIX Winter 1993 Conference diff --git a/man2/seccomp_unotify.2 b/man2/seccomp_unotify.2 index 156fbce..7c2084b 100644 --- a/man2/seccomp_unotify.2 +++ b/man2/seccomp_unotify.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH seccomp_unotify 2 2023-05-03 "Linux man-pages 6.05.01" +.TH seccomp_unotify 2 2023-10-31 "Linux man-pages 6.7" .SH NAME seccomp_unotify \- Seccomp user-space notification mechanism .SH LIBRARY @@ -13,12 +13,12 @@ Standard C library .B #include <linux/seccomp.h> .B #include <linux/filter.h> .B #include <linux/audit.h> -.PP +.P .BI "int seccomp(unsigned int " operation ", unsigned int " flags \ ", void *" args ); -.PP +.P .B #include <sys/ioctl.h> -.PP +.P .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_RECV," .BI " struct seccomp_notif *" req ); .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_SEND," @@ -51,7 +51,7 @@ the handling of the system call to another user-space process. Note that this mechanism is explicitly .B not intended as a method implementing security policy; see NOTES. -.PP +.P In the discussion that follows, the thread(s) on which the seccomp filter is installed is (are) referred to as the @@ -59,7 +59,7 @@ referred to as the and the process that is notified by the user-space notification mechanism is referred to as the .IR supervisor . -.PP +.P A suitably privileged supervisor can use the user-space notification mechanism to perform actions on behalf of the target. The advantage of the user-space notification mechanism is that @@ -69,7 +69,7 @@ performed system call that the seccomp filter itself cannot. (A seccomp filter is limited in the information it can obtain and the actions that it can perform because it is running on a virtual machine inside the kernel.) -.PP +.P An overview of the steps performed by the target and the supervisor is as follows: .\"------------------------------------- @@ -285,7 +285,7 @@ the system call in the target thread unblocks, returning the information that was provided by the supervisor in the notification response. .\"------------------------------------- -.PP +.P As a variation on the last two steps, the supervisor can send a response that tells the kernel that it should execute the target thread's system call; see the discussion of @@ -317,7 +317,7 @@ The third argument is a pointer to a structure of the following form which contains information about the event. This structure must be zeroed out before the call. -.PP +.P .in +4n .EX struct seccomp_notif { @@ -328,7 +328,7 @@ struct seccomp_notif { }; .EE .in -.PP +.P The fields in this structure are as follows: .TP .I id @@ -367,7 +367,7 @@ This is the same structure that is passed to the seccomp filter. See .BR seccomp (2) for details of this structure. -.PP +.P On success, this operation returns 0; on failure, \-1 is returned, and .I errno is set to indicate the cause of the error. @@ -423,7 +423,7 @@ returned by an earlier operation is still valid (i.e., that the target still exists and its system call is still blocked waiting for a response). -.PP +.P The third .BR ioctl (2) argument is a pointer to the cookie @@ -431,7 +431,7 @@ argument is a pointer to the cookie returned by the .B SECCOMP_IOCTL_NOTIF_RECV operation. -.PP +.P This operation is necessary to avoid race conditions that can occur when the .I pid returned by the @@ -458,7 +458,7 @@ the file for the TID obtained in step 1, with the intention of (say) inspecting the memory location(s) that containing the argument(s) of the system call that triggered the notification in step 1. -.PP +.P In the above scenario, the risk is that the supervisor may try to access the memory of a process other than the target. This race can be avoided by following the call to @@ -478,11 +478,11 @@ from the file descriptor may return 0, indicating end of file.) .\" PID, or something like that. (Actually, it is associated .\" with the "struct pid", which is not reused, instead of the .\" numeric PID. -.PP +.P See NOTES for a discussion of other cases where .B SECCOMP_IOCTL_NOTIF_ID_VALID checks must be performed. -.PP +.P On success (i.e., the notification ID is still valid), this operation returns 0. On failure (i.e., the notification ID is no longer valid), @@ -499,7 +499,7 @@ is used to send a notification response back to the kernel. The third .BR ioctl (2) argument of this structure is a pointer to a structure of the following form: -.PP +.P .in +4n .EX struct seccomp_notif_resp { @@ -510,7 +510,7 @@ struct seccomp_notif_resp { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I id @@ -537,7 +537,7 @@ This is a bit mask that includes zero or more of the following flags: Tell the kernel to execute the target's system call. .\" commit fb3c5386b382d4097476ce9647260fc89b34afdb .RE -.PP +.P Two kinds of response are possible: .IP \[bu] 3 A response to the kernel telling it to execute the @@ -571,11 +571,11 @@ fields of the structure. The supervisor should set the fields of this structure as follows: .RS -.IP + 3 +.IP \[bu] 3 .I flags does not contain .BR SECCOMP_USER_NOTIF_FLAG_CONTINUE . -.IP + +.IP \[bu] .I error is set either to 0 for a spoofed "success" return or to a negative error number for a spoofed "failure" return. @@ -589,7 +589,7 @@ to return \-1, and is assigned the negated .I error value. -.IP + +.IP \[bu] .I val is set to a value that will be used as the return value for a spoofed "success" return for the target's system call. @@ -609,7 +609,7 @@ field contains a nonzero value. .\" verify that val and err are both 0 when CONTINUE is specified (as you .\" pointed out correctly above). .RE -.PP +.P On success, this operation returns 0; on failure, \-1 is returned, and .I errno is set to indicate the cause of the error. @@ -656,7 +656,7 @@ messages described in this operation is semantically equivalent to duplicating a file descriptor from the supervisor's file descriptor table into the target's file descriptor table. -.PP +.P The .B SECCOMP_IOCTL_NOTIF_ADDFD operation permits the supervisor to emulate a target system call (such as @@ -670,10 +670,10 @@ and then use this operation to allocate a file descriptor that refers to the same open file description in the target. (For an explanation of open file descriptions, see .BR open (2).) -.PP +.P Once this operation has been performed, the supervisor can close its copy of the file descriptor. -.PP +.P In the target, the received file descriptor is subject to the same Linux Security Module (LSM) checks as are applied to a file descriptor @@ -686,11 +686,11 @@ it inherits the cgroup version 1 network controller settings and .IR netprioidx ) of the target. -.PP +.P The third .BR ioctl (2) argument is a pointer to a structure of the following form: -.PP +.P .in +4n .EX struct seccomp_notif_addfd { @@ -704,7 +704,7 @@ struct seccomp_notif_addfd { }; .EE .in -.PP +.P The fields in this structure are as follows: .TP .I id @@ -774,7 +774,7 @@ Currently, only the following flag is implemented: .B O_CLOEXEC Set the close-on-exec flag on the received file descriptor. .RE -.PP +.P On success, this .BR ioctl (2) call returns the number of the file descriptor that was allocated @@ -787,11 +787,11 @@ this value can be used as the return value that is supplied in the response that is subsequently sent with the .B SECCOMP_IOCTL_NOTIF_SEND operation. -.PP +.P On error, \-1 is returned and .I errno is set to indicate the cause of the error. -.PP +.P This operation can fail with the following errors: .TP .B EBADF @@ -838,12 +838,12 @@ exceeds the limit specified in The blocked system call in the target has been interrupted by a signal handler or the target has terminated. -.PP +.P Here is some sample code (with error handling omitted) that uses the .B SECCOMP_ADDFD_FLAG_SETFD operation (here, to emulate a call to .BR openat (2)): -.PP +.P .EX .in +4n int fd, removeFd; @@ -942,12 +942,12 @@ to allow system calls to be performed on behalf of the target. The target's system call should either be handled by the supervisor or allowed to continue normally in the kernel (where standard security policies will be applied). -.PP +.P .BR "Note well" : this mechanism must not be used to make security policy decisions about the system call, which would be inherently race-prone for reasons described next. -.PP +.P The .B SECCOMP_USER_NOTIF_FLAG_CONTINUE flag must be used with caution. @@ -956,7 +956,7 @@ However, there is a time-of-check, time-of-use race here, since an attacker could exploit the interval of time where the target is blocked waiting on the "continue" response to do things such as rewriting the system call arguments. -.PP +.P Note furthermore that a user-space notifier can be bypassed if the existing filters allow the use of .BR seccomp (2) @@ -966,7 +966,7 @@ to install a filter that returns an action value with a higher precedence than .B SECCOMP_RET_USER_NOTIF (see .BR seccomp (2)). -.PP +.P It should thus be absolutely clear that the seccomp user-space notification mechanism .B can not @@ -994,7 +994,7 @@ However, the use of this .BR ioctl (2) operation is also necessary in other situations, as explained in the following paragraphs. -.PP +.P Consider the following scenario, where the supervisor tries to read the pathname argument of a target's blocked .BR mount (2) @@ -1031,7 +1031,7 @@ contain the pathname. The supervisor now calls .BR mount (2) with some arbitrary bytes obtained in the previous step. -.PP +.P The conclusion from the above scenario is this: since the target's blocked system call may be interrupted by a signal handler, the supervisor must be written to expect that the @@ -1040,7 +1040,7 @@ target may abandon its system call at time; in such an event, any information that the supervisor obtained from the target's memory must be considered invalid. -.PP +.P To prevent such scenarios, every read from the target's memory must be separated from use of the bytes so obtained by a @@ -1048,7 +1048,7 @@ the bytes so obtained by a check. In the above example, the check would be placed between the two final steps. An example of such a check is shown in EXAMPLES. -.PP +.P Following on from the above, it should be clear that a write by the supervisor into the target's memory can .B never @@ -1059,7 +1059,7 @@ Suppose that the target performs a blocking system call (e.g., .BR accept (2)) that the supervisor should handle. The supervisor might then in turn execute the same blocking system call. -.PP +.P In this scenario, it is important to note that if the target's system call is now interrupted by a signal, the supervisor is @@ -1077,7 +1077,7 @@ holding a port number that the target perhaps closed its listening socket) might expect to be able to reuse in a .BR bind (2) call. -.PP +.P Therefore, when the supervisor wishes to emulate a blocking system call, it must do so in such a way that it gets informed if the target's system call is interrupted by a signal handler. @@ -1095,7 +1095,7 @@ to monitor both the notification file descriptor .BR accept (2) call has been interrupted) and the listening file descriptor (so as to know when a connection is available). -.PP +.P If the target's system call is interrupted, the supervisor must take care to release resources (e.g., file descriptors) that it acquired on behalf of the target. @@ -1121,14 +1121,14 @@ When (if) the supervisor attempts to send a notification response, the operation will fail with the .B ENOENT error. -.PP +.P In this scenario, the kernel will restart the target's system call. Consequently, the supervisor will receive another user-space notification. Thus, depending on how many times the blocked system call is interrupted by a signal handler, the supervisor may receive multiple notifications for the same instance of a system call in the target. -.PP +.P One oddity is that system call restarting as described in this scenario will occur even for the blocking system calls listed in .BR signal (7) @@ -1156,7 +1156,7 @@ flag. .\" calls because it's impossible for the kernel to restart the call .\" with the right timeout value. I wonder what happens when those .\" system calls are restarted in the scenario we're discussing.) -.PP +.P Furthermore, if the supervisor response is a file descriptor added with .BR SECCOMP_IOCTL_NOTIF_ADDFD , @@ -1195,7 +1195,7 @@ The child process then calls once for each of the supplied command-line arguments, and reports the result returned by the call. After processing all arguments, the child process terminates. -.PP +.P The parent process acts as the supervisor, listening for the notifications that are generated when the target process calls .BR mkdir (2). @@ -1232,14 +1232,14 @@ call appears to fail with the error ("Operation not supported"). Additionally, if the specified pathname is exactly "/bye", then the supervisor terminates. -.PP +.P This program can be used to demonstrate various aspects of the behavior of the seccomp user-space notification mechanism. To help aid such demonstrations, the program logs various messages to show the operation of the target process (lines prefixed "T:") and the supervisor (indented lines prefixed "S:"). -.PP +.P In the following example, the target attempts to create the directory .IR /tmp/x . Upon receiving the notification, the supervisor creates the directory on the @@ -1247,7 +1247,7 @@ target's behalf, and spoofs a success return to be received by the target process's .BR mkdir (2) call. -.PP +.P .in +4n .EX $ \fB./seccomp_unotify /tmp/x\fP @@ -1264,14 +1264,14 @@ T: terminating S: target has terminated; bye .EE .in -.PP +.P In the above output, note that the spoofed return value seen by the target process is 6 (the length of the pathname .IR /tmp/x ), whereas a normal .BR mkdir (2) call returns 0 on success. -.PP +.P In the next example, the target attempts to create a directory using the relative pathname .IR ./sub . @@ -1282,7 +1282,7 @@ response to the kernel, and the kernel then (successfully) executes the target process's .BR mkdir (2) call. -.PP +.P .in +4n .EX $ \fB./seccomp_unotify ./sub\fP @@ -1298,7 +1298,7 @@ T: terminating S: target has terminated; bye .EE .in -.PP +.P If the target process attempts to create a directory with a pathname that doesn't start with "." and doesn't begin with the prefix "/tmp/", then the supervisor spoofs an error return @@ -1307,7 +1307,7 @@ a pathname that doesn't start with "." and doesn't begin with the prefix for the target's .BR mkdir (2) call (which is not executed): -.PP +.P .in +4n .EX $ \fB./seccomp_unotify /xxx\fP @@ -1323,7 +1323,7 @@ T: terminating S: target has terminated; bye .EE .in -.PP +.P In the next example, the target process attempts to create a directory with the pathname .BR /tmp/nosuchdir/b . @@ -1337,7 +1337,7 @@ Consequently, the supervisor spoofs an error return that passes the error that it received back to the target process's .BR mkdir (2) call. -.PP +.P .in +4n .EX $ \fB./seccomp_unotify /tmp/nosuchdir/b\fP @@ -1354,7 +1354,7 @@ T: terminating S: target has terminated; bye .EE .in -.PP +.P If the supervisor receives a notification and sees that the argument of the target's .BR mkdir (2) @@ -1370,7 +1370,7 @@ fail with the error .B ENOSYS ("Function not implemented"). This is demonstrated by the following example: -.PP +.P .in +4n .EX $ \fB./seccomp_unotify /bye /tmp/y\fP @@ -2006,6 +2006,6 @@ main(int argc, char *argv[]) .BR pidfd_getfd (2), .BR pidfd_open (2), .BR seccomp (2) -.PP +.P A further example program can be found in the kernel source file .IR samples/seccomp/user-trap.c . diff --git a/man2/select.2 b/man2/select.2 index 41cb7e6..e544918 100644 --- a/man2/select.2 +++ b/man2/select.2 @@ -17,7 +17,7 @@ .\" 2005-03-11, mtk, modified pselect() text (it is now a system .\" call in Linux 2.6.16. .\" -.TH select 2 2023-05-03 "Linux man-pages 6.05.01" +.TH select 2 2023-10-31 "Linux man-pages 6.7" .SH NAME select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO, fd_set \- synchronous I/O multiplexing @@ -27,31 +27,31 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/select.h> -.PP +.P .BR typedef " /* ... */ " fd_set; -.PP +.P .BI "int select(int " nfds ", fd_set *_Nullable restrict " readfds , .BI " fd_set *_Nullable restrict " writefds , .BI " fd_set *_Nullable restrict " exceptfds , .BI " struct timeval *_Nullable restrict " timeout ); -.PP +.P .BI "void FD_CLR(int " fd ", fd_set *" set ); .BI "int FD_ISSET(int " fd ", fd_set *" set ); .BI "void FD_SET(int " fd ", fd_set *" set ); .BI "void FD_ZERO(fd_set *" set ); -.PP +.P .BI "int pselect(int " nfds ", fd_set *_Nullable restrict " readfds , .BI " fd_set *_Nullable restrict " writefds , .BI " fd_set *_Nullable restrict " exceptfds , .BI " const struct timespec *_Nullable restrict " timeout , .BI " const sigset_t *_Nullable restrict " sigmask ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pselect (): .nf _POSIX_C_SOURCE >= 200112L @@ -68,7 +68,7 @@ All modern applications should instead use or .BR epoll (7), which do not suffer this limitation. -.PP +.P .BR select () allows a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become "ready" @@ -99,14 +99,14 @@ Each of the .I fd_set arguments may be specified as NULL if no file descriptors are to be watched for the corresponding class of events. -.PP +.P .BR "Note well" : Upon return, each of the file descriptor sets is modified in place to indicate which file descriptors are currently "ready". Thus, if using .BR select () within a loop, the sets \fImust be reinitialized\fP before each call. -.PP +.P The contents of a file descriptor set can be manipulated using the following macros: .TP @@ -237,7 +237,7 @@ The .BR pselect () system call allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. -.PP +.P The operation of .BR select () and @@ -267,7 +267,7 @@ argument, and behaves as .BR pselect () called with NULL .IR sigmask . -.PP +.P .I sigmask is a pointer to a signal mask (see .BR sigprocmask (2)); @@ -283,24 +283,24 @@ is NULL, the signal mask is not modified during the .BR pselect () call.) -.PP +.P Other than the difference in the precision of the .I timeout argument, the following .BR pselect () call: -.PP +.P .in +4n .EX ready = pselect(nfds, &readfds, &writefds, &exceptfds, timeout, &sigmask); .EE .in -.PP +.P is equivalent to .I atomically executing the following calls: -.PP +.P .in +4n .EX sigset_t origmask; @@ -310,7 +310,7 @@ ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); pthread_sigmask(SIG_SETMASK, &origmask, NULL); .EE .in -.PP +.P The reason that .BR pselect () is needed is that if one wants to wait for either a signal @@ -336,7 +336,7 @@ The argument for .BR select () is a structure of the following type: -.PP +.P .in +4n .EX struct timeval { @@ -345,13 +345,13 @@ struct timeval { }; .EE .in -.PP +.P The corresponding argument for .BR pselect () is a .BR timespec (3) structure. -.PP +.P On Linux, .BR select () modifies @@ -370,7 +370,7 @@ Consider to be undefined after .BR select () returns. -.\" .PP - it is rumored that: +.\" .P - it is rumored that: .\" On BSD, when a timeout occurs, the file descriptor bits are not changed. .\" - it is certainly true that: .\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. @@ -386,7 +386,7 @@ descriptor sets (that is, the total number of bits that are set in .IR exceptfds ). The return value may be zero if the timeout expired before any file descriptors became ready. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error; @@ -464,7 +464,7 @@ The following header also provides the .I fd_set type: .IR <sys/time.h> . -.PP +.P An .I fd_set is a fixed size buffer. @@ -481,7 +481,7 @@ in undefined behavior. Moreover, POSIX requires .I fd to be a valid file descriptor. -.PP +.P The operation of .BR select () and @@ -525,7 +525,7 @@ and the event notifications provided by .BR poll (2) and .BR epoll (7): -.PP +.P .in +4n .EX #define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN | @@ -564,7 +564,7 @@ However, in the glibc implementation, the .I fd_set type is fixed in size. See also BUGS. -.PP +.P The .BR pselect () interface described in this page is implemented by glibc. @@ -572,7 +572,7 @@ The underlying Linux system call is named .BR pselect6 (). This system call has somewhat different behavior from the glibc wrapper function. -.PP +.P The Linux .BR pselect6 () system call modifies its @@ -587,13 +587,13 @@ function does not modify its .I timeout argument; this is the behavior required by POSIX.1-2001. -.PP +.P The final argument of the .BR pselect6 () system call is not a .I "sigset_t\ *" pointer, but is instead a structure of the form: -.PP +.P .in +4n .EX struct { @@ -603,7 +603,7 @@ struct { }; .EE .in -.PP +.P This allows the system call to obtain both a pointer to the signal set and its size, while allowing for the fact that most architectures @@ -619,7 +619,7 @@ glibc 2.0 provided an incorrect version of that did not take a .I sigmask argument. -.PP +.P From glibc 2.1 to glibc 2.2.1, one must define .B _GNU_SOURCE @@ -645,14 +645,14 @@ To monitor file descriptors greater than 1023, use or .BR epoll (7) instead. -.PP +.P The implementation of the .I fd_set arguments as value-result arguments is a design error that is avoided in .BR poll (2) and .BR epoll (7). -.PP +.P According to POSIX, .BR select () should check all specified file descriptors in the three file descriptor sets, @@ -664,7 +664,7 @@ that the process currently has open. According to POSIX, any such file descriptor that is specified in one of the sets should result in the error .BR EBADF . -.PP +.P Starting with glibc 2.1, glibc provided an emulation of .BR pselect () that was implemented using @@ -677,7 +677,7 @@ was designed to prevent. Modern versions of glibc use the (race-free) .BR pselect () system call on kernels where it is provided. -.PP +.P On Linux, .BR select () may report a socket file descriptor as "ready for reading", while @@ -693,7 +693,7 @@ Thus it may be safer to use .B O_NONBLOCK on sockets that should not block. .\" Maybe the kernel should have returned EIO in such a situation? -.PP +.P On Linux, .BR select () also modifies @@ -760,6 +760,6 @@ main(void) .BR timespec (3), .BR epoll (7), .BR time (7) -.PP +.P For a tutorial with discussion and examples, see .BR select_tut (2). diff --git a/man2/select_tut.2 b/man2/select_tut.2 index e860de3..cbb6953 100644 --- a/man2/select_tut.2 +++ b/man2/select_tut.2 @@ -9,7 +9,7 @@ .\" various other changes .\" 2008-01-26, mtk, substantial changes and rewrites .\" -.TH SELECT_TUT 2 2023-05-03 "Linux man-pages 6.05.01" +.TH SELECT_TUT 2 2023-10-31 "Linux man-pages 6.7" .SH NAME select, pselect \- synchronous I/O multiplexing .SH LIBRARY @@ -27,7 +27,7 @@ system calls are used to efficiently monitor multiple file descriptors, to see if any of them is, or becomes, "ready"; that is, to see whether I/O becomes possible, or an "exceptional condition" has occurred on any of the file descriptors. -.PP +.P This page provides background and tutorial information on the use of these system calls. For details of the arguments and semantics of @@ -54,7 +54,7 @@ This behavior is essential so that signals can be processed in the main loop of the program, otherwise .BR select () would block indefinitely. -.PP +.P Now, somewhere in the main loop will be a conditional to check the global flag. So we must ask: @@ -82,7 +82,7 @@ call would enable .B SIGCHLD by using an empty signal mask. Our program would look like: -.PP +.P .EX static volatile sig_atomic_t got_SIGCHLD = 0; \& @@ -310,7 +310,7 @@ can be used to solve many problems in a portable and efficient way that naive programmers try to solve in a more complicated manner using threads, forking, IPCs, signals, memory sharing, and so on. -.PP +.P The .BR poll (2) system call has the same functionality as @@ -319,7 +319,7 @@ and is somewhat more efficient when monitoring sparse file descriptor sets. It is nowadays widely available, but historically was less portable than .BR select (). -.PP +.P The Linux-specific .BR epoll (7) API provides an interface that is more efficient than @@ -332,7 +332,7 @@ Here is an example that better demonstrates the true utility of .BR select (). The listing below is a TCP forwarding program that forwards from one TCP port to another. -.PP +.P .\" SRC BEGIN (select.c) .EX #include <arpa/inet.h> @@ -604,7 +604,7 @@ main(int argc, char *argv[]) } .EE .\" SRC END -.PP +.P The above program properly forwards most kinds of TCP connections including OOB signal data transmitted by \fBtelnet\fP servers. It handles the tricky problem of having data flow in both directions @@ -617,7 +617,7 @@ Another idea is to set nonblocking I/O using .BR fcntl (2). This also has its problems because you end up using inefficient timeouts. -.PP +.P The program does not handle more than one simultaneous connection at a time, although it could easily be extended to do this with a linked list of buffers\[em]one for each connection. diff --git a/man2/semctl.2 b/man2/semctl.2 index 6069169..c3724e4 100644 --- a/man2/semctl.2 +++ b/man2/semctl.2 @@ -20,7 +20,7 @@ .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. .\" 2018-03-20, dbueso: Added SEM_STAT_ANY description. .\" -.TH semctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH semctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME semctl \- System V semaphore control operations .SH LIBRARY @@ -29,26 +29,26 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/sem.h> -.PP -.BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" +.P +.BI "int semctl(int " semid ", int " semnum ", int " op ", ...);" .fi .SH DESCRIPTION .BR semctl () performs the control operation specified by -.I cmd +.I op on the System\ V semaphore set identified by .IR semid , or on the .IR semnum -th semaphore of that set. (The semaphores in a set are numbered starting at 0.) -.PP +.P This function has three or four arguments, depending on -.IR cmd . +.IR op . When there are four, the fourth has the type .IR "union semun" . The \fIcalling program\fP must define this union as follows: -.PP +.P .in +4n .EX union semun { @@ -60,11 +60,11 @@ union semun { }; .EE .in -.PP +.P The .I semid_ds data structure is defined in \fI<sys/sem.h>\fP as follows: -.PP +.P .in +4n .EX struct semid_ds { @@ -76,7 +76,7 @@ struct semid_ds { }; .EE .in -.PP +.P The fields of the .I semid_ds structure are as follows: @@ -108,13 +108,13 @@ ranging from .B 0 to .IR sem_nsems\-1 . -.PP +.P The .I ipc_perm structure is defined as follows (the highlighted fields are settable using .BR IPC_SET ): -.PP +.P .in +4n .EX struct ipc_perm { @@ -128,7 +128,7 @@ struct ipc_perm { }; .EE .in -.PP +.P The least significant 9 bits of the .I mode field of the @@ -144,12 +144,12 @@ l l. 0004 Read by others 0002 Write by others .TE -.PP +.P In effect, "write" means "alter" for a semaphore set. Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. -.PP +.P Valid values for -.I cmd +.I op are: .TP .B IPC_STAT @@ -380,7 +380,7 @@ The calling process must have alter permission on the semaphore set. On success, .BR semctl () returns a nonnegative value depending on -.I cmd +.I op as follows: .TP .B GETNCNT @@ -420,11 +420,11 @@ the identifier of the semaphore set whose index was given in .B SEM_STAT_ANY as for .BR SEM_STAT . -.PP +.P All other -.I cmd +.I op values return 0 on success. -.PP +.P On failure, .BR semctl () returns \-1 and sets @@ -434,7 +434,7 @@ to indicate the error. .TP .B EACCES The argument -.I cmd +.I op has one of the values .BR GETALL , .BR GETPID , @@ -464,7 +464,7 @@ The semaphore set was removed. .TP .B EINVAL Invalid value for -.I cmd +.I op or .IR semid . Or: for a @@ -475,7 +475,7 @@ referred to an array slot that is currently unused. .TP .B EPERM The argument -.I cmd +.I op has the value .B IPC_SET or @@ -493,7 +493,7 @@ capability. .TP .B ERANGE The argument -.I cmd +.I op has the value .B SETALL or @@ -525,7 +525,7 @@ and explicitly notes that this value is set by a successful call, with the implication that no other interface affects the .I sempid value. -.PP +.P While some implementations conform to the behavior specified in POSIX.1, others do not. (The fault here probably lies with POSIX.1 inasmuch as it likely failed @@ -543,7 +543,7 @@ on process termination as a consequence of the use of the .B SEM_UNDO flag (see .BR semop (2)). -.PP +.P Linux also updates .I sempid for @@ -563,7 +563,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. .\" SVr4 documents more error conditions EINVAL and EOVERFLOW. -.PP +.P Various fields in a \fIstruct semid_ds\fP were typed as .I short under Linux 2.2 @@ -575,8 +575,8 @@ a recompilation under glibc-2.1.91 or later should suffice. (The kernel distinguishes old and new calls by an .B IPC_64 flag in -.IR cmd .) -.PP +.IR op .) +.P In some earlier versions of glibc, the .I semun union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires @@ -598,7 +598,7 @@ program to provide information on allocated resources. In the future these may modified or moved to a .I /proc filesystem interface. -.PP +.P The following system limit on semaphore sets affects a .BR semctl () call: @@ -607,7 +607,7 @@ call: Maximum value for .BR semval : implementation dependent (32767). -.PP +.P For greater portability, it is best to always call .BR semctl () with four arguments. diff --git a/man2/semget.2 b/man2/semget.2 index bd2b693..50813ba 100644 --- a/man2/semget.2 +++ b/man2/semget.2 @@ -14,7 +14,7 @@ .\" Rewrote BUGS note about semget()'s failure to initialize .\" semaphore values .\" -.TH semget 2 2023-05-03 "Linux man-pages 6.05.01" +.TH semget 2 2023-10-31 "Linux man-pages 6.7" .SH NAME semget \- get a System V semaphore set identifier .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .nf .B #include <sys/sem.h> .fi -.PP +.P .BI "int semget(key_t " key , .BI "int " nsems , .BI "int " semflg ); @@ -42,7 +42,7 @@ is zero and does not have the value .BR IPC_PRIVATE ), or to create a new set. -.PP +.P A new set of .I nsems semaphores is created if @@ -55,7 +55,7 @@ and .B IPC_CREAT is specified in .IR semflg . -.PP +.P If .I semflg specifies both @@ -74,7 +74,7 @@ set to .B O_CREAT | O_EXCL for .BR open (2).) -.PP +.P Upon creation, the least significant 9 bits of the argument .I semflg define the permissions (for owner, group, and others) @@ -87,7 +87,7 @@ argument of (though the execute permissions are not meaningful for semaphores, and write permissions mean permission to alter semaphore values). -.PP +.P When creating a new semaphore set, .BR semget () initializes the set's associated data structure, @@ -120,7 +120,7 @@ is set to 0. .IP \[bu] .I sem_ctime is set to the current time. -.PP +.P The argument .I nsems can be 0 @@ -131,7 +131,7 @@ Otherwise, must be greater than 0 and less than or equal to the maximum number of semaphores per semaphore set .RB ( SEMMSL ). -.PP +.P If the semaphore set already exists, the permissions are verified. .\" and a check is made to see if it is marked for destruction. @@ -225,7 +225,7 @@ it should explicitly initialize the semaphores to the desired values. .\" In truth, every one of the many implementations that I've tested sets .\" the values to zero, but I suppose there is/was some obscure .\" implementation out there that does not. -.PP +.P Initialization can be done using .BR semctl (2) .B SETVAL @@ -310,12 +310,12 @@ and flags for the call to .BR semget (). The usage of this program is demonstrated below. -.PP +.P We first create two files that will be used to generate keys using .BR ftok (3), create two semaphore sets using those files, and then list the sets using .BR ipcs (1): -.PP +.P .in +4n .EX $ \fBtouch mykey mykey2\fP @@ -331,7 +331,7 @@ key semid owner perms nsems 0x70041368 10 mtk 600 2 .EE .in -.PP +.P Next, we demonstrate that when .BR semctl (2) is given the same @@ -339,20 +339,20 @@ is given the same (as generated by the same arguments to .BR ftok (3)), it returns the ID of the already existing semaphore set: -.PP +.P .in +4n .EX $ \fB./t_semget \-c mykey p 1\fP ID = 9 .EE .in -.PP +.P Finally, we demonstrate the kind of collision that can occur when .BR ftok (3) is given different .I pathname arguments that have the same inode number: -.PP +.P .in +4n .EX $ \fBln mykey link\fP diff --git a/man2/semop.2 b/man2/semop.2 index ece7a0e..b04fe6a 100644 --- a/man2/semop.2 +++ b/man2/semop.2 @@ -12,7 +12,7 @@ .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop() .\" 2007-07-09, mtk, Added an EXAMPLE code segment. .\" -.TH semop 2 2023-05-03 "Linux man-pages 6.05.01" +.TH semop 2 2023-10-31 "Linux man-pages 6.7" .SH NAME semop, semtimedop \- System V semaphore operations .SH LIBRARY @@ -21,17 +21,17 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/sem.h> -.PP +.P .BI "int semop(int " semid ", struct sembuf *" sops ", size_t " nsops ); .BI "int semtimedop(int " semid ", struct sembuf *" sops ", size_t " nsops , .BI " const struct timespec *_Nullable " timeout ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR semtimedop (): .nf _GNU_SOURCE @@ -39,7 +39,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION Each semaphore in a System\ V semaphore set has the following associated values: -.PP +.P .in +4n .EX unsigned short semval; /* semaphore value */ @@ -49,7 +49,7 @@ pid_t sempid; /* PID of process that last modified the semaphore value */ .EE .in -.PP +.P .BR semop () performs operations on selected semaphores in the set indicated by .IR semid . @@ -62,7 +62,7 @@ specifies an operation to be performed on a single semaphore. The elements of this structure are of type .IR "struct sembuf" , containing the following members: -.PP +.P .in +4n .EX unsigned short sem_num; /* semaphore number */ @@ -70,7 +70,7 @@ short sem_op; /* semaphore operation */ short sem_flg; /* operation flags */ .EE .in -.PP +.P Flags recognized in .I sem_flg are @@ -80,7 +80,7 @@ and If an operation specifies .BR SEM_UNDO , it will be automatically undone when the process terminates. -.PP +.P The set of operations contained in .I sops is performed in @@ -95,14 +95,14 @@ performed immediately depends on the presence of the flag in the individual .I sem_flg fields, as noted below. -.PP +.P Each operation is performed on the .IR sem_num \-th semaphore of the semaphore set, where the first semaphore of the set is numbered 0. There are three types of operation, distinguished by the value of .IR sem_op . -.PP +.P If .I sem_op is a positive integer, the operation adds this value to @@ -117,7 +117,7 @@ from the semaphore adjustment value for this semaphore. This operation can always proceed\[em]it never forces a thread to wait. The calling process must have alter permission on the semaphore set. -.PP +.P If .I sem_op is zero, the process must have read permission on the semaphore @@ -165,7 +165,7 @@ fails, with .I errno set to .BR EINTR . -.PP +.P If .I sem_op is less than zero, the process must have alter permission on the @@ -229,7 +229,7 @@ fails, with .I errno set to .BR EINTR . -.PP +.P On successful completion, the .I sempid value for each semaphore specified in the array pointed to by @@ -270,7 +270,7 @@ then .BR semtimedop () behaves exactly like .BR semop (). -.PP +.P Note that if .BR semtimedop () is interrupted by a signal, causing the call to fail with the error @@ -370,13 +370,13 @@ structures of a process aren't inherited by the child produced by but they are inherited across an .BR execve (2) system call. -.PP +.P .BR semop () is never automatically restarted after being interrupted by a signal handler, regardless of the setting of the .B SA_RESTART flag when establishing a signal handler. -.PP +.P A semaphore adjustment .RI ( semadj ) value is a per-process, per-semaphore integer that is the negated sum @@ -409,7 +409,7 @@ flag allows more than one process to share a list; see .BR clone (2) for details. -.PP +.P The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values for a semaphore can all be retrieved using appropriate .BR semctl (2) @@ -443,7 +443,7 @@ array. Maximum allowable value for .IR semval : implementation dependent (32767). -.PP +.P The implementation has no intrinsic limits for the adjust on exit maximum value .RB ( SEMAEM ), @@ -471,7 +471,7 @@ is specified for a semaphore operation). Linux adopts a third approach: decreasing the semaphore value as far as possible (i.e., to zero) and allowing process termination to proceed immediately. -.PP +.P In Linux 2.6.x, x <= 10, there is a bug that in some circumstances prevents a thread that is waiting for a semaphore value to become zero from being woken up when the value does actually become zero. @@ -485,7 +485,7 @@ The following code segment uses .BR semop () to atomically wait for the value of semaphore 0 to become zero, and then increment the semaphore value by one. -.PP +.P .in +4n .EX struct sembuf sops[2]; @@ -507,7 +507,7 @@ if (semop(semid, sops, 2) == \-1) { } .EE .in -.PP +.P A further example of the use of .BR semop () can be found in diff --git a/man2/send.2 b/man2/send.2 index 16c58b5..79abcc7 100644 --- a/man2/send.2 +++ b/man2/send.2 @@ -9,7 +9,7 @@ .\" Modified Oct 2003 by aeb .\" Modified 2004-07-01 by mtk .\" -.TH send 2 2023-03-30 "Linux man-pages 6.05.01" +.TH send 2 2024-02-18 "Linux man-pages 6.7" .SH NAME send, sendto, sendmsg \- send a message on a socket .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "ssize_t send(int " sockfd ", const void " buf [. len "], size_t " len \ ", int " flags ); .BI "ssize_t sendto(int " sockfd ", const void " buf [. len "], size_t " len \ @@ -34,7 +34,7 @@ The system calls and .BR sendmsg () are used to transmit a message to another socket. -.PP +.P The .BR send () call may be used only when the socket is in a @@ -53,25 +53,25 @@ argument, is equivalent to .BR write (2). Also, the following call -.PP +.P .in +4n .EX send(sockfd, buf, len, flags); .EE .in -.PP +.P is equivalent to -.PP +.P .in +4n .EX sendto(sockfd, buf, len, flags, NULL, 0); .EE .in -.PP +.P The argument .I sockfd is the file descriptor of the sending socket. -.PP +.P If .BR sendto () is used on a connection-mode @@ -99,7 +99,7 @@ the address of the target is given by with .I msg.msg_namelen specifying its size. -.PP +.P For .BR send () and @@ -115,16 +115,16 @@ the message is pointed to by the elements of the array The .BR sendmsg () call also allows sending ancillary data (also known as control information). -.PP +.P If the message is too long to pass atomically through the underlying protocol, the error .B EMSGSIZE is returned, and the message is not transmitted. -.PP +.P No indication of failure to deliver is implicit in a .BR send (). Locally detected errors are indicated by a return value of \-1. -.PP +.P When the message does not fit into the send buffer of the socket, .BR send () normally blocks, unless the socket has been placed in nonblocking I/O @@ -184,7 +184,7 @@ is a per-call option, whereas is a setting on the open file description (see .BR open (2)), which will affect all threads in the calling process -and as well as other processes that hold file descriptors +as well as other processes that hold file descriptors referring to the same open file description. .TP .BR MSG_EOR " (since Linux 2.2)" @@ -273,7 +273,7 @@ The definition of the structure employed by .BR sendmsg () is as follows: -.PP +.P .in +4n .EX struct msghdr { @@ -287,7 +287,7 @@ struct msghdr { }; .EE .in -.PP +.P The .I msg_name field is used on an unconnected socket to specify the target @@ -297,14 +297,14 @@ It points to a buffer containing the address; the field should be set to the size of the address. For a connected socket, these fields should be specified as NULL and 0, respectively. -.PP +.P The .I msg_iov and .I msg_iovlen fields specify scatter-gather locations, as for .BR writev (2). -.PP +.P You may send control information (ancillary data) using the .I msg_control and @@ -320,7 +320,7 @@ socket domains, see .BR unix (7) and .BR ip (7). -.PP +.P The .I msg_flags field is ignored. @@ -458,13 +458,13 @@ but glibc currently types both as .\" as (at least with GCC) is int. .SH STANDARDS POSIX.1-2008. -.PP +.P .B MSG_CONFIRM is a Linux extension. .SH HISTORY 4.4BSD, SVr4, POSIX.1-2001. (first appeared in 4.2BSD). -.PP +.P POSIX.1-2001 describes only the .B MSG_OOB and diff --git a/man2/sendfile.2 b/man2/sendfile.2 index d9c3451..e013fa6 100644 --- a/man2/sendfile.2 +++ b/man2/sendfile.2 @@ -11,7 +11,7 @@ .\" .\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements .\" -.TH sendfile 2 2023-07-15 "Linux man-pages 6.05.01" +.TH sendfile 2 2023-12-21 "Linux man-pages 6.7" .SH NAME sendfile \- transfer data between file descriptors .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/sendfile.h> -.PP +.P .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", \ off_t *_Nullable " offset , .BI " size_t" " count" ); @@ -48,12 +48,12 @@ is more efficient than the combination of and .BR write (2), which would require transferring data to and from user space. -.PP +.P .I in_fd should be a file descriptor opened for reading and .I out_fd should be a descriptor opened for writing. -.PP +.P If .I offset is not NULL, then it points @@ -74,29 +74,38 @@ does not modify the file offset of otherwise the file offset is adjusted to reflect the number of bytes read from .IR in_fd . -.PP +.P If .I offset is NULL, then data will be read from .I in_fd starting at the file offset, and the file offset will be updated by the call. -.PP +.P .I count is the number of bytes to copy between the file descriptors. -.PP +.P The .I in_fd argument must correspond to a file which supports .BR mmap (2)-like operations (i.e., it cannot be a socket). -.PP +Except since Linux 5.12 +.\" commit b964bf53e540262f2d12672b3cca10842c0172e7 +and if +.I out_fd +is a pipe, in which case +.BR sendfile () +desugars to a +.BR splice (2) +and its restrictions apply. +.P Before Linux 2.6.33, .I out_fd must refer to a socket. Since Linux 2.6.33 it can be any file. -If it is a regular file, then +If it's seekable, then .BR sendfile () changes the file offset appropriately. .SH RETURN VALUE @@ -108,7 +117,7 @@ Note that a successful call to may write fewer bytes than requested; the caller should be prepared to retry the call if there were unsent bytes. See also NOTES. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -169,13 +178,13 @@ None. .SH HISTORY Linux 2.2, glibc 2.1. -.PP +.P In Linux 2.4 and earlier, .I out_fd could also refer to a regular file; this possibility went away in the Linux 2.6.x kernel series, but was restored in Linux 2.6.33. -.PP +.P The original Linux .BR sendfile () system call was not designed to handle large file offsets. @@ -193,7 +202,7 @@ will transfer at most 0x7ffff000 (2,147,479,552) bytes, returning the number of bytes actually transferred. .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 (This is true on both 32-bit and 64-bit systems.) -.PP +.P If you plan to use .BR sendfile () for sending files to a TCP socket, but need @@ -203,7 +212,7 @@ it useful to employ the option, described in .BR tcp (7), to minimize the number of packets and to tune performance. -.PP +.P Applications may wish to fall back to .BR read (2) and @@ -214,7 +223,7 @@ fails with .B EINVAL or .BR ENOSYS . -.PP +.P If .I out_fd refers to a socket or pipe with zero-copy support, callers must ensure the @@ -223,7 +232,7 @@ transferred portions of the file referred to by remain unmodified until the reader on the other end of .I out_fd has consumed the transferred data. -.PP +.P The Linux-specific .BR splice (2) call supports transferring data between arbitrary file descriptors diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2 index 283c4a5..64a4da0 100644 --- a/man2/sendmmsg.2 +++ b/man2/sendmmsg.2 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sendmmsg 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sendmmsg 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sendmmsg \- send multiple messages on a socket .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sys/socket.h> -.PP +.P .BI "int sendmmsg(int " sockfd ", struct mmsghdr *" msgvec \ ", unsigned int " vlen "," .BI " int " flags ");" @@ -29,12 +29,12 @@ that allows the caller to transmit multiple messages on a socket using a single system call. (This has performance benefits for some applications.) .\" See commit 228e548e602061b08ee8e8966f567c12aa079682 -.PP +.P The .I sockfd argument is the file descriptor of the socket on which data is to be transmitted. -.PP +.P The .I msgvec argument is a pointer to an array of @@ -42,13 +42,13 @@ argument is a pointer to an array of structures. The size of this array is specified in .IR vlen . -.PP +.P The .I mmsghdr structure is defined in .I <sys/socket.h> as: -.PP +.P .in +4n .EX struct mmsghdr { @@ -57,7 +57,7 @@ struct mmsghdr { }; .EE .in -.PP +.P The .I msg_hdr field is a @@ -71,13 +71,13 @@ field is used to return the number of bytes sent from the message in (i.e., the same as the return value from a single .BR sendmsg (2) call). -.PP +.P The .I flags argument contains flags ORed together. The flags are the same as for .BR sendmsg (2). -.PP +.P A blocking .BR sendmmsg () call blocks until @@ -87,7 +87,7 @@ A nonblocking call sends as many messages as possible (up to the limit specified by .IR vlen ) and returns immediately. -.PP +.P On return from .BR sendmmsg (), the @@ -109,7 +109,7 @@ if this is less than the caller can retry with a further .BR sendmmsg () call to send the remaining messages. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -163,7 +163,7 @@ and .I three in two distinct UDP datagrams using one system call. The contents of the first datagram originates from a pair of buffers. -.PP +.P .\" SRC BEGIN (sendmmsg.c) .EX #define _GNU_SOURCE diff --git a/man2/set_mempolicy.2 b/man2/set_mempolicy.2 index a7f561d..58e3959 100644 --- a/man2/set_mempolicy.2 +++ b/man2/set_mempolicy.2 @@ -7,7 +7,7 @@ .\" 2007-08-27, Lee Schermerhorn <Lee.Schermerhorn@hp.com> .\" more precise specification of behavior. .\" -.TH set_mempolicy 2 2023-07-16 "Linux man-pages 6.05.01" +.TH set_mempolicy 2 2023-10-31 "Linux man-pages 6.7" .SH NAME set_mempolicy \- set default NUMA memory policy for a thread and its children .SH LIBRARY @@ -16,7 +16,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .nf .B "#include <numaif.h>" -.PP +.P .BI "long set_mempolicy(int " mode ", const unsigned long *" nodemask , .BI " unsigned long " maxnode ); .fi @@ -30,12 +30,12 @@ to the values specified by the and .I maxnode arguments. -.PP +.P A NUMA machine has different memory controllers with different distances to specific CPUs. The memory policy defines from which node memory is allocated for the thread. -.PP +.P This system call defines the default policy for the thread. The thread policy governs allocation of pages in the process's address space outside of memory ranges @@ -56,7 +56,7 @@ The policy is applied only when a new page is allocated for the thread. For anonymous memory this is when the page is first touched by the thread. -.PP +.P The .I mode argument must specify one of @@ -73,7 +73,7 @@ require the caller to specify the node or nodes to which the mode applies, via the .I nodemask argument. -.PP +.P The .I mode argument may also include an optional @@ -113,7 +113,7 @@ Linux will not remap the when the process moves to a different cpuset context, nor when the set of nodes allowed by the process's current cpuset context changes. -.PP +.P .I nodemask points to a bit mask of node IDs that contains up to .I maxnode @@ -133,7 +133,7 @@ is zero, the .I nodemask argument is ignored. -.PP +.P Where a .I nodemask is required, it must contain at least one node that is on-line, @@ -154,7 +154,7 @@ the memory policy reverts to This effectively overrides the specified policy until the process's cpuset context includes one or more of the nodes specified by .IR nodemask . -.PP +.P The .I mode argument must include one of the following values: @@ -234,7 +234,7 @@ If the "local node" is not allowed by the process's current cpuset context, the kernel will try to allocate memory from other nodes. The kernel will allocate memory from the "local node" whenever it becomes allowed by the process's current cpuset context. -.PP +.P The thread memory policy is preserved across an .BR execve (2), and is inherited by child threads created using @@ -311,7 +311,7 @@ Memory policy is not remembered if the page is swapped out. When such a page is paged back in, it will use the policy of the thread or memory range that is in effect at the time the page is allocated. -.PP +.P For information on library support, see .BR numa (7). .SH SEE ALSO diff --git a/man2/set_thread_area.2 b/man2/set_thread_area.2 index b982112..389d65b 100644 --- a/man2/set_thread_area.2 +++ b/man2/set_thread_area.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH set_thread_area 2 2023-03-30 "Linux man-pages 6.05.01" +.TH set_thread_area 2 2023-10-31 "Linux man-pages 6.7" .SH NAME get_thread_area, set_thread_area \- manipulate thread-local storage information .SH LIBRARY @@ -14,25 +14,25 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .B #if defined __i386__ || defined __x86_64__ .BR "# include <asm/ldt.h>" " /* Definition of " "struct user_desc" " */" -.PP +.P .BI "int syscall(SYS_get_thread_area, struct user_desc *" u_info ); .BI "int syscall(SYS_set_thread_area, struct user_desc *" u_info ); -.PP +.P .B #elif defined __m68k__ -.PP +.P .B "int syscall(SYS_get_thread_area);" .BI "int syscall(SYS_set_thread_area, unsigned long " tp ); -.PP -.B #elif defined __mips__ -.PP +.P +.B #elif defined __mips__ || defined __csky__ +.P .BI "int syscall(SYS_set_thread_area, unsigned long " addr ); -.PP +.P .B #endif .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -42,31 +42,31 @@ These calls provide architecture-specific support for a thread-local storage implementation. At the moment, .BR set_thread_area () -is available on m68k, MIPS, and x86 (both 32-bit and 64-bit variants); +is available on m68k, MIPS, C-SKY, and x86 (both 32-bit and 64-bit variants); .BR get_thread_area () is available on m68k and x86. -.PP -On m68k and MIPS, +.P +On m68k, MIPS and C-SKY, .BR set_thread_area () allows storing an arbitrary pointer (provided in the .B tp argument on m68k and in the .B addr -argument on MIPS) +argument on MIPS and C-SKY) in the kernel data structure associated with the calling thread; this pointer can later be retrieved using .BR get_thread_area () (see also NOTES for information regarding obtaining the thread pointer on MIPS). -.PP +.P On x86, Linux dedicates three global descriptor table (GDT) entries for thread-local storage. For more information about the GDT, see the Intel Software Developer's Manual or the AMD Architecture Programming Manual. -.PP +.P Both of these system calls take an argument that is a pointer to a structure of the following type: -.PP +.P .in +4n .EX struct user_desc { @@ -85,16 +85,16 @@ struct user_desc { }; .EE .in -.PP +.P .BR get_thread_area () reads the GDT entry indicated by .I u_info\->entry_number and fills in the rest of the fields in .IR u_info . -.PP +.P .BR set_thread_area () sets a TLS entry in the GDT. -.PP +.P The TLS array entry set by .BR set_thread_area () corresponds to the value of @@ -105,7 +105,7 @@ If this value is in bounds, writes the TLS descriptor pointed to by .I u_info into the thread's TLS array. -.PP +.P When .BR set_thread_area () is passed an @@ -116,7 +116,7 @@ If finds a free TLS entry, the value of .I u_info\->entry_number is set upon return to show which entry was changed. -.PP +.P A .I user_desc is considered "empty" if @@ -128,7 +128,7 @@ If an "empty" descriptor is passed to .BR set_thread_area (), the corresponding TLS entry will be cleared. See BUGS for additional details. -.PP +.P Since Linux 3.19, .BR set_thread_area () cannot be used to write non-present segments, 16-bit segments, or code @@ -138,8 +138,8 @@ On x86, these system calls return 0 on success, and \-1 on failure, with .I errno set to indicate the error. -.PP -On MIPS and m68k, +.P +On C-SKY, MIPS and m68k, .BR set_thread_area () always returns 0. On m68k, @@ -175,7 +175,7 @@ Linux 2.5.29. Linux 2.5.32. .SH NOTES These system calls are generally intended for use only by threading libraries. -.PP +.P .BR arch_prctl (2) can interfere with .BR set_thread_area () @@ -186,16 +186,16 @@ for more details. This is not normally a problem, as .BR arch_prctl (2) is normally used only by 64-bit programs. -.PP +.P On MIPS, the current value of the thread area pointer can be obtained using the instruction: -.PP +.P .in +4n .EX rdhwr dest, $29 .EE .in -.PP +.P This instruction traps and is handled by kernel. .SH BUGS On 64-bit kernels before Linux 3.19, @@ -219,7 +219,7 @@ consisting entirely of zeros except for .I entry_number will also be interpreted as a request to clear a TLS entry, but this behaved differently on older kernels. -.PP +.P Prior to Linux 3.19, the DS and ES segment registers must not reference TLS entries. .SH SEE ALSO diff --git a/man2/set_tid_address.2 b/man2/set_tid_address.2 index 180b909..d174105 100644 --- a/man2/set_tid_address.2 +++ b/man2/set_tid_address.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH set_tid_address 2 2023-03-30 "Linux man-pages 6.05.01" +.TH set_tid_address 2 2023-10-31 "Linux man-pages 6.7" .SH NAME set_tid_address \- set pointer to thread ID .SH LIBRARY @@ -12,10 +12,10 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "pid_t syscall(SYS_set_tid_address, int *" tidptr ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR set_tid_address (), @@ -54,14 +54,14 @@ flag, is set to the value passed in the .I ctid argument of that system call. -.PP +.P The system call .BR set_tid_address () sets the .I clear_child_tid value for the calling thread to .IR tidptr . -.PP +.P When a thread whose .I clear_child_tid is not NULL terminates, then, @@ -69,13 +69,13 @@ if the thread is sharing memory with other threads, then 0 is written at the address specified in .I clear_child_tid and the kernel performs the following operation: -.PP +.P .in +4n .EX futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0); .EE .in -.PP +.P The effect of this operation is to wake a single thread that is performing a futex wait on the memory location. Errors from the futex wake operation are ignored. @@ -89,7 +89,7 @@ always succeeds. Linux. .SH HISTORY Linux 2.5.48. -.PP +.P Details as given here are valid since Linux 2.5.49. .SH SEE ALSO .BR clone (2), diff --git a/man2/seteuid.2 b/man2/seteuid.2 index 0c47f6a..c1cae7c 100644 --- a/man2/seteuid.2 +++ b/man2/seteuid.2 @@ -6,7 +6,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> .\" Added notes on capability requirements .\" -.TH seteuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH seteuid 2 2024-02-11 "Linux man-pages 6.7" .SH NAME seteuid, setegid \- set effective user or group ID .SH LIBRARY @@ -15,16 +15,16 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int seteuid(uid_t " euid ); .BI "int setegid(gid_t " egid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR seteuid (), .BR setegid (): .nf @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see sets the effective user ID of the calling process. Unprivileged processes may only set the effective user ID to the real user ID, the effective user ID or the saved set-user-ID. -.PP +.P Precisely the same holds for .BR setegid () with "group" instead of "user". @@ -50,7 +50,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .IR Note : there are cases where .BR seteuid () @@ -86,7 +86,7 @@ saved set-user-ID (saved set-group-ID) is possible since Linux 1.1.37 (1.1.38). On an arbitrary system one should check .BR _POSIX_SAVED_IDS . -.PP +.P Under glibc 2.0, .BI seteuid( euid ) is equivalent to @@ -102,7 +102,7 @@ with the difference that the change in implementation from to .BI setresgid(\-1, " egid" ", \-1)" occurred in glibc 2.2 or 2.3 (depending on the hardware architecture). -.PP +.P According to POSIX.1, .BR seteuid () .RB ( setegid ()) @@ -117,9 +117,9 @@ On Linux, and .BR setegid () are implemented as library functions that call, respectively, -.BR setreuid (2) +.BR setresuid (2) and -.BR setregid (2). +.BR setresgid (2). .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man2/setfsgid.2 b/man2/setfsgid.2 index 43b5507..8cb8403 100644 --- a/man2/setfsgid.2 +++ b/man2/setfsgid.2 @@ -9,7 +9,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> .\" Added notes on capability requirements .\" -.TH setfsgid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setfsgid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setfsgid \- set group identity used for filesystem checks .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/fsuid.h> -.PP +.P .BI "[[deprecated]] int setfsgid(gid_t " fsgid ); .fi .SH DESCRIPTION @@ -28,7 +28,7 @@ for permissions checking when accessing filesystem objects, while the effective group ID is used for some other kinds of permissions checks (see .BR credentials (7)). -.PP +.P Normally, the value of the process's filesystem group ID is the same as the value of its effective group ID. This is so, because whenever a process's effective group ID is changed, @@ -39,7 +39,7 @@ from its effective group ID by using .BR setfsgid () to change its filesystem group ID to the value given in .IR fsgid . -.PP +.P .BR setfsgid () will succeed only if the caller is the superuser or if .I fsgid @@ -75,7 +75,7 @@ for a discussion of why the use of both and .BR setfsgid () is nowadays unneeded. -.PP +.P The original Linux .BR setfsgid () system call supported only 16-bit group IDs. diff --git a/man2/setfsuid.2 b/man2/setfsuid.2 index 56964b0..cd55bc3 100644 --- a/man2/setfsuid.2 +++ b/man2/setfsuid.2 @@ -9,7 +9,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> .\" Added notes on capability requirements .\" -.TH setfsuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setfsuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setfsuid \- set user identity used for filesystem checks .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/fsuid.h> -.PP +.P .BI "[[deprecated]] int setfsuid(uid_t " fsuid ); .fi .SH DESCRIPTION @@ -28,7 +28,7 @@ for permissions checking when accessing filesystem objects, while the effective user ID is used for various other kinds of permissions checks (see .BR credentials (7)). -.PP +.P Normally, the value of the process's filesystem user ID is the same as the value of its effective user ID. This is so, because whenever a process's effective user ID is changed, @@ -39,7 +39,7 @@ from its effective user ID by using .BR setfsuid () to change its filesystem user ID to the value given in .IR fsuid . -.PP +.P Explicit calls to .BR setfsuid () and @@ -50,7 +50,7 @@ corresponding change in the real and effective user and group IDs. A change in the normal user IDs for a program such as the NFS server is (was) a security hole that can expose it to unwanted signals. (However, this issue is historical; see below.) -.PP +.P .BR setfsuid () will succeed only if the caller is the superuser or if .I fsuid @@ -65,7 +65,7 @@ Linux. Linux 1.2. .\" Linux 1.1.44 .\" and in libc since libc 4.7.6. -.PP +.P At the time when this system call was introduced, one process could send a signal to another process with the same effective user ID. This meant that if a privileged process changed its effective user ID @@ -84,7 +84,7 @@ Thus, is nowadays unneeded and should be avoided in new applications (likewise for .BR setfsgid (2)). -.PP +.P The original Linux .BR setfsuid () system call supported only 16-bit user IDs. diff --git a/man2/setgid.2 b/man2/setgid.2 index f618887..cb65798 100644 --- a/man2/setgid.2 +++ b/man2/setgid.2 @@ -7,7 +7,7 @@ .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> .\" Modified 2002-03-09 by aeb .\" -.TH setgid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setgid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setgid \- set group identity .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int setgid(gid_t " gid ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ If the calling process is privileged (more precisely: has the .B CAP_SETGID capability in its user namespace), the real GID and saved set-group-ID are also set. -.PP +.P Under Linux, .BR setgid () is implemented like the POSIX version with the @@ -73,7 +73,7 @@ For details, see POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. -.PP +.P The original Linux .BR setgid () system call supported only 16-bit group IDs. diff --git a/man2/setns.2 b/man2/setns.2 index 13565de..5bd3385 100644 --- a/man2/setns.2 +++ b/man2/setns.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-only .\" -.TH setns 2 2023-05-03 "Linux man-pages 6.05.01" +.TH setns 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setns \- reassociate thread with a namespace .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <sched.h> -.PP +.P .BI "int setns(int " fd ", int " nstype ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ directory (or a bind mount to such a link); .IP \[bu] a PID file descriptor (see .BR pidfd_open (2)). -.PP +.P The .I nstype argument is interpreted differently in each case. @@ -49,7 +49,7 @@ argument. In this usage, each call to .BR setns () changes just one of the caller's namespace memberships. -.PP +.P The .I nstype argument specifies which type of namespace @@ -93,7 +93,7 @@ must refer to a user namespace. .BR CLONE_NEWUTS " (since Linux 3.0)" .I fd must refer to a UTS namespace. -.PP +.P Specifying .I nstype as 0 suffices if the caller knows (or does not care) @@ -121,7 +121,7 @@ In this usage, atomically moves the calling thread into one or more of the same namespaces as the thread referred to by .IR fd . -.PP +.P The .I nstype argument is a bit mask specified by ORing together @@ -133,11 +133,11 @@ The caller is moved into each of the target thread's namespaces that is specified in .IR nstype ; the caller's memberships in the remaining namespaces are left unchanged. -.PP +.P For example, the following code would move the caller into the same user, network, and UTS namespaces as PID 1234, but would leave the caller's other namespace memberships unchanged: -.PP +.P .in +4n .EX int fd = pidfd_open(1234, 0); @@ -312,7 +312,7 @@ For further information on the .IR /proc/ pid /ns/ magic links, see .BR namespaces (7). -.PP +.P Not all of the attributes that can be shared when a new thread is created using .BR clone (2) @@ -327,7 +327,7 @@ The remaining arguments specify a command and its arguments. The program opens the namespace file, joins that namespace using .BR setns (), and executes the specified command inside that namespace. -.PP +.P The following shell session demonstrates the use of this program (compiled as a binary named .IR ns_exec ) @@ -337,7 +337,7 @@ example program in the .BR clone (2) man page (complied as a binary named .IR newuts ). -.PP +.P We begin by executing the example program in .BR clone (2) in the background. @@ -345,7 +345,7 @@ That program creates a child in a separate UTS namespace. The child changes the hostname in its namespace, and then both processes display the hostnames in their UTS namespaces, so that we can see that they are different. -.PP +.P .in +4n .EX $ \fBsu\fP # Need privilege for namespace operations @@ -359,12 +359,12 @@ uts.nodename in parent: antero antero .EE .in -.PP +.P We then run the program shown below, using it to execute a shell. Inside that shell, we verify that the hostname is the one set by the child created by the first program: -.PP +.P .in +4n .EX # \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP diff --git a/man2/setpgid.2 b/man2/setpgid.2 index 2d8bc96..b3983c4 100644 --- a/man2/setpgid.2 +++ b/man2/setpgid.2 @@ -17,7 +17,7 @@ .\" 2007-07-25, mtk, fairly substantial rewrites and rearrangements .\" of text. .\" -.TH setpgid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setpgid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setpgid, getpgid, setpgrp, getpgrp \- set/get process group .SH LIBRARY @@ -26,29 +26,29 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int setpgid(pid_t " pid ", pid_t " pgid ); .BI "pid_t getpgid(pid_t " pid ); -.PP +.P .BR "pid_t getpgrp(void);" " /* POSIX.1 version */" .BI "[[deprecated]] pid_t getpgrp(pid_t " pid ");\fR /* BSD version */" -.PP +.P .BR "int setpgrp(void);" " /* System V version */" .BI "[[deprecated]] int setpgrp(pid_t " pid ", pid_t " pgid ");\fR /* BSD version */" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getpgid (): .nf _XOPEN_SOURCE >= 500 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L .fi -.PP +.P .BR setpgrp "() (POSIX.1):" .nf _XOPEN_SOURCE >= 500 @@ -56,7 +56,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE .fi -.PP +.P .BR setpgrp "() (BSD)," .BR getpgrp "() (BSD):" .nf @@ -74,7 +74,7 @@ The preferred, POSIX.1-specified ways of doing this are: for retrieving the calling process's PGID; and .BR setpgid (), for setting a process's PGID. -.PP +.P .BR setpgid () sets the PGID of the process specified by .I pid @@ -99,12 +99,12 @@ and In this case, the \fIpgid\fP specifies an existing process group to be joined and the session ID of that group must match the session ID of the joining process. -.PP +.P The POSIX.1 version of .BR getpgrp (), which takes no arguments, returns the PGID of the calling process. -.PP +.P .BR getpgid () returns the PGID of the process specified by .IR pid . @@ -115,12 +115,12 @@ is zero, the process ID of the calling process is used. necessary, and the POSIX.1 .BR getpgrp () is preferred for that task.) -.PP +.P The System\ V-style .BR setpgrp (), which takes no arguments, is equivalent to .IR "setpgid(0,\ 0)" . -.PP +.P The BSD-specific .BR setpgrp () call, which takes arguments @@ -128,13 +128,13 @@ call, which takes arguments and .IR pgid , is a wrapper function that calls -.PP +.P .in +4n .EX setpgid(pid, pgid) .EE .in -.PP +.P .\" The true BSD setpgrp() system call differs in allowing the PGID .\" to be set to arbitrary values, rather than being restricted to .\" PGIDs in the same session. @@ -145,19 +145,19 @@ function is no longer exposed by calls should be replaced with the .BR setpgid () call shown above. -.PP +.P The BSD-specific .BR getpgrp () call, which takes a single .I pid argument, is a wrapper function that calls -.PP +.P .in +4n .EX getpgid(pid) .EE .in -.PP +.P Since glibc 2.19, the BSD-specific .BR getpgrp () function is no longer exposed by @@ -177,11 +177,11 @@ return zero. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P The POSIX.1 .BR getpgrp () always returns the PGID of the caller. -.PP +.P .BR getpgid (), and the BSD-specific .BR getpgrp () @@ -266,12 +266,12 @@ A child created via inherits its parent's process group ID. The PGID is preserved across an .BR execve (2). -.PP +.P Each process group is a member of a session and each process is a member of the session of which its process group is a member. (See .BR credentials (7).) -.PP +.P A session can have a controlling terminal. At any time, one (and only one) of the process groups in the session can be the foreground process group @@ -298,7 +298,7 @@ and .BR tcsetpgrp (3) functions are used to get/set the foreground process group of the controlling terminal. -.PP +.P The .BR setpgid () and @@ -306,7 +306,7 @@ and calls are used by programs such as .BR bash (1) to create process groups in order to implement shell job control. -.PP +.P If the termination of a process causes a process group to become orphaned, and if any member of the newly orphaned process group is stopped, then a .B SIGHUP diff --git a/man2/setresuid.2 b/man2/setresuid.2 index 97f0af9..9c6499b 100644 --- a/man2/setresuid.2 +++ b/man2/setresuid.2 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified, 2003-05-26, Michael Kerrisk, <mtk.manpages@gmail.com> -.TH setresuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setresuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setresuid, setresgid \- set real, effective, and saved user or group ID .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <unistd.h> -.PP +.P .BI "int setresuid(uid_t " ruid ", uid_t " euid ", uid_t " suid ); .BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid ); .fi @@ -22,22 +22,22 @@ Standard C library .BR setresuid () sets the real user ID, the effective user ID, and the saved set-user-ID of the calling process. -.PP +.P An unprivileged process may change its real UID, effective UID, and saved set-user-ID, each to one of: the current real UID, the current effective UID, or the current saved set-user-ID. -.PP +.P A privileged process (on Linux, one having the \fBCAP_SETUID\fP capability) may set its real UID, effective UID, and saved set-user-ID to arbitrary values. -.PP +.P If one of the arguments equals \-1, the corresponding value is not changed. -.PP +.P Regardless of what changes are made to the real UID, effective UID, and saved set-user-ID, the filesystem UID is always set to the same value as the (possibly new) effective UID. -.PP +.P Completely analogously, .BR setresgid () sets the real GID, effective GID, and saved set-group-ID @@ -49,7 +49,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .IR Note : there are cases where .BR setresuid () @@ -119,7 +119,7 @@ None. Linux 2.1.44, glibc 2.3.2. HP-UX, FreeBSD. -.PP +.P The original Linux .BR setresuid () and diff --git a/man2/setreuid.2 b/man2/setreuid.2 index 121deb4..e887619 100644 --- a/man2/setreuid.2 +++ b/man2/setreuid.2 @@ -15,7 +15,7 @@ .\" 2004-07-04 by aeb .\" 2004-05-27 by Michael Kerrisk .\" -.TH setreuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setreuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setreuid, setregid \- set real and/or effective user or group ID .SH LIBRARY @@ -24,16 +24,16 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int setreuid(uid_t " ruid ", uid_t " euid ); .BI "int setregid(gid_t " rgid ", gid_t " egid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR setreuid (), .BR setregid (): .nf @@ -45,22 +45,22 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION .BR setreuid () sets real and effective user IDs of the calling process. -.PP +.P Supplying a value of \-1 for either the real or effective user ID forces the system to leave that ID unchanged. -.PP +.P Unprivileged processes may only set the effective user ID to the real user ID, the effective user ID, or the saved set-user-ID. -.PP +.P Unprivileged users may only set the real user ID to the real user ID or the effective user ID. -.PP +.P If the real user ID is set (i.e., .I ruid is not \-1) or the effective user ID is set to a value not equal to the previous real user ID, the saved set-user-ID will be set to the new effective user ID. -.PP +.P Completely analogously, .BR setregid () sets real and effective group ID's of the calling process, @@ -70,7 +70,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .IR Note : there are cases where .BR setreuid () @@ -137,18 +137,18 @@ and the effective group ID can be changed to the value of the real group ID or the saved set-group-ID. The precise details of what ID changes are permitted vary across implementations. -.PP +.P POSIX.1 makes no specification about the effect of these calls on the saved set-user-ID and saved set-group-ID. .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.3BSD (first appeared in 4.2BSD). -.PP +.P Setting the effective user (group) ID to the saved set-user-ID (saved set-group-ID) is possible since Linux 1.1.37 (1.1.38). -.PP +.P The original Linux .BR setreuid () and diff --git a/man2/setsid.2 b/man2/setsid.2 index ae04028..a437a1b 100644 --- a/man2/setsid.2 +++ b/man2/setsid.2 @@ -9,7 +9,7 @@ .\" tiny changes from a man page by Charles Livingston). .\" Modified Sun Jul 21 14:45:46 1996 <aeb@cwi.nl> .\" -.TH setsid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setsid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setsid \- creates a session and sets the process group ID .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B pid_t setsid(void); .fi .SH DESCRIPTION @@ -30,10 +30,10 @@ The calling process is the leader of the new session The calling process also becomes the process group leader of a new process group in the session (i.e., its process group ID is made the same as its process ID). -.PP +.P The calling process will be the only process in the new process group and in the new session. -.PP +.P Initially, the new session has no controlling terminal. For details of how a session acquires a controlling terminal, see .BR credentials (7). @@ -61,7 +61,7 @@ A child created via inherits its parent's session ID. The session ID is preserved across an .BR execve (2). -.PP +.P A process group leader is a process whose process group ID equals its PID. Disallowing a process group leader from calling .BR setsid () @@ -78,14 +78,14 @@ and have the parent .BR _exit (2), while the child (which by definition can't be a process group leader) calls .BR setsid (). -.PP +.P If a session has a controlling terminal, and the .B CLOCAL flag for that terminal is not set, and a terminal hangup occurs, then the session leader is sent a .B SIGHUP signal. -.PP +.P If a process that is a session leader terminates, then a .B SIGHUP signal is sent to each process in the foreground diff --git a/man2/setuid.2 b/man2/setuid.2 index 80284d6..e9a283e 100644 --- a/man2/setuid.2 +++ b/man2/setuid.2 @@ -8,7 +8,7 @@ .\" <richard@greenend.org.uk>, aeb 970616. .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> .\" Added notes on capability requirements -.TH setuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setuid \- set user identity .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int setuid(uid_t " uid ); .fi .SH DESCRIPTION @@ -28,7 +28,7 @@ If the calling process is privileged .B CAP_SETUID capability in its user namespace), the real UID and saved set-user-ID are also set. -.PP +.P Under Linux, .BR setuid () is implemented like the POSIX version with the @@ -37,7 +37,7 @@ feature. This allows a set-user-ID (other than root) program to drop all of its user privileges, do some un-privileged work, and then reengage the original effective user ID in a secure manner. -.PP +.P If the user is root or the program is set-user-ID-root, special care must be taken: .BR setuid () @@ -46,7 +46,7 @@ the superuser, all process-related user ID's are set to .IR uid . After this has occurred, it is impossible for the program to regain root privileges. -.PP +.P Thus, a set-user-ID-root program wishing to temporarily drop root privileges, assume the identity of an unprivileged user, and then regain root privileges afterward cannot use @@ -58,7 +58,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .IR Note : there are cases where .BR setuid () @@ -119,11 +119,11 @@ For details, see POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. -.PP +.P Not quite compatible with the 4.4BSD call, which sets all of the real, saved, and effective user IDs. .\" SVr4 documents an additional EINVAL error condition. -.PP +.P The original Linux .BR setuid () system call supported only 16-bit user IDs. @@ -141,7 +141,7 @@ The call also sets the filesystem user ID of the calling process. See .BR setfsuid (2). -.PP +.P If .I uid is different from the old effective UID, the process will diff --git a/man2/setup.2 b/man2/setup.2 index 61a6002..c2d0b52 100644 --- a/man2/setup.2 +++ b/man2/setup.2 @@ -11,7 +11,7 @@ .\" Modified Wed Nov 6 04:05:28 1996 by Eric S. Raymond <esr@thyrsus.com> .\" Modified Sat Jan 29 01:08:23 2000 by aeb .\" -.TH setup 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setup 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setup \- setup devices and filesystems, mount root filesystem .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B [[deprecated]] int setup(void); .fi .SH DESCRIPTION @@ -29,7 +29,7 @@ is called once from within .IR linux/init/main.c . It calls initialization functions for devices and filesystems configured into the kernel and then mounts the root filesystem. -.PP +.P No user process may call .BR setup (). Any user process, even a process with superuser permission, @@ -46,7 +46,7 @@ Always, for a user process. Linux. .SH VERSIONS Removed in Linux 2.1.121. -.PP +.P The calling sequence varied: at some times .BR setup () has had a single argument diff --git a/man2/setxattr.2 b/man2/setxattr.2 index cc2a6b0..636462e 100644 --- a/man2/setxattr.2 +++ b/man2/setxattr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH setxattr 2 2023-07-28 "Linux man-pages 6.05.01" +.TH setxattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setxattr, lsetxattr, fsetxattr \- set an extended attribute value .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/xattr.h> -.PP +.P .BI "int setxattr(const char *" path ", const char *" name , .BI " const void " value [. size "], size_t " size ", int " flags ); .BI "int lsetxattr(const char *" path ", const char *" name , @@ -30,7 +30,7 @@ with all inodes in the system (i.e., the data). A complete overview of extended attributes concepts can be found in .BR xattr (7). -.PP +.P .BR setxattr () sets the .I value @@ -44,13 +44,13 @@ The argument specifies the size (in bytes) of .IR value ; a zero-length value is permitted. -.PP +.P .BR lsetxattr () is identical to .BR setxattr (), except in the case of a symbolic link, where the extended attribute is set on the link itself, not the file that it refers to. -.PP +.P .BR fsetxattr () is identical to .BR setxattr (), @@ -60,7 +60,7 @@ only the extended attribute is set on the open file referred to by .BR open (2)) in place of .IR path . -.PP +.P An extended attribute name is a null-terminated string. The .I name @@ -70,7 +70,7 @@ The .I value of an extended attribute is a chunk of arbitrary textual or binary data of specified length. -.PP +.P By default (i.e., .I flags @@ -125,7 +125,7 @@ Extended attributes are not supported by the filesystem, or are disabled, The file is marked immutable or append-only. (See .BR ioctl_iflags (2).) -.PP +.P In addition, the errors documented in .BR stat (2) can also occur. diff --git a/man2/sgetmask.2 b/man2/sgetmask.2 index d0c99a2..e1701c2 100644 --- a/man2/sgetmask.2 +++ b/man2/sgetmask.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sgetmask 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sgetmask 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sgetmask, ssetmask \- manipulation of signal mask (obsolete) .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .B [[deprecated]] long syscall(SYS_sgetmask, void); .BI "[[deprecated]] long syscall(SYS_ssetmask, long " newmask ); .fi @@ -22,15 +22,15 @@ These system calls are obsolete. use .BR sigprocmask (2) instead. -.PP +.P .BR sgetmask () returns the signal mask of the calling process. -.PP +.P .BR ssetmask () sets the signal mask of the calling process to the value given in .IR newmask . The previous signal mask is returned. -.PP +.P The signal masks dealt with by these two system calls are plain bit masks (unlike the .I sigset_t @@ -58,9 +58,9 @@ option. .SH NOTES These system calls are unaware of signal numbers greater than 31 (i.e., real-time signals). -.PP +.P These system calls do not exist on x86-64. -.PP +.P It is not possible to block .B SIGSTOP or diff --git a/man2/shmctl.2 b/man2/shmctl.2 index 4bfb2c5..5d5176a 100644 --- a/man2/shmctl.2 +++ b/man2/shmctl.2 @@ -24,7 +24,7 @@ .\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions. .\" 2018-03-20, dbueso: Added SHM_STAT_ANY description. .\" -.TH shmctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH shmctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME shmctl \- System V shared memory control .SH LIBRARY @@ -33,21 +33,21 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/shm.h> -.PP -.BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf ); +.P +.BI "int shmctl(int " shmid ", int " op ", struct shmid_ds *" buf ); .fi .SH DESCRIPTION .BR shmctl () performs the control operation specified by -.I cmd +.I op on the System\ V shared memory segment whose identifier is given in .IR shmid . -.PP +.P The .I buf argument is a pointer to a \fIshmid_ds\fP structure, defined in \fI<sys/shm.h>\fP as follows: -.PP +.P .in +4n .EX struct shmid_ds { @@ -64,7 +64,7 @@ struct shmid_ds { }; .EE .in -.PP +.P The fields of the .I shmid_ds structure are as follows: @@ -106,13 +106,13 @@ system call on this segment. .TP .I shm_nattch Number of processes that have this segment attached. -.PP +.P The .I ipc_perm structure is defined as follows (the highlighted fields are settable using .BR IPC_SET ): -.PP +.P .in +4n .EX struct ipc_perm { @@ -127,7 +127,7 @@ struct ipc_perm { }; .EE .in -.PP +.P The least significant 9 bits of the .I mode field of the @@ -143,7 +143,7 @@ l l. 0004 Read by others 0002 Write by others .TE -.PP +.P Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. (It is not necessary to have execute permission on a segment in order to perform a @@ -151,9 +151,9 @@ in order to perform a call with the .B SHM_EXEC flag.) -.PP +.P Valid values for -.I cmd +.I op are: .TP .B IPC_STAT @@ -307,9 +307,11 @@ is not checked for read access for meaning that any user can employ this operation (just as any user may read .I /proc/sysvipc/shm to obtain the same information). -.PP +.P The caller can prevent or allow swapping of a shared -memory segment with the following \fIcmd\fP values: +memory segment with the following +.I op +values: .TP .BR SHM_LOCK " (Linux-specific)" Prevent swapping of the shared memory segment. @@ -325,7 +327,7 @@ will be set. .TP .BR SHM_UNLOCK " (Linux-specific)" Unlock the segment, allowing it to be swapped out. -.PP +.P Before Linux 2.6.10, only a privileged process could employ .B SHM_LOCK @@ -363,7 +365,7 @@ operation returns the identifier of the shared memory segment whose index was given in .IR shmid . Other operations return 0 on success. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -379,7 +381,7 @@ capability in the user namespace that governs its IPC namespace. .TP .B EFAULT The argument -.I cmd +.I op has value .B IPC_SET or @@ -392,8 +394,10 @@ isn't accessible. \fIshmid\fP points to a removed identifier. .TP .B EINVAL -\fIshmid\fP is not a valid identifier, or \fIcmd\fP -is not a valid command. +.I shmid +is not a valid identifier, or +.I op +is not a valid operation. Or: for a .B SHM_STAT or @@ -456,7 +460,7 @@ POSIX.1-2001, SVr4. .\" SVr4 documents additional error conditions EINVAL, .\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents .\" an EIDRM error condition. -.PP +.P Various fields in a \fIstruct shmid_ds\fP were typed as .I short under Linux 2.2 @@ -468,7 +472,7 @@ a recompilation under glibc-2.1.91 or later should suffice. (The kernel distinguishes old and new calls by an .B IPC_64 flag in -.IR cmd .) +.IR op .) .SH NOTES The .BR IPC_INFO , diff --git a/man2/shmget.2 b/man2/shmget.2 index 074e83e..685963a 100644 --- a/man2/shmget.2 +++ b/man2/shmget.2 @@ -15,7 +15,7 @@ .\" Language and formatting clean-ups .\" Added notes on /proc files .\" -.TH shmget 2 2023-03-30 "Linux man-pages 6.05.01" +.TH shmget 2 2023-10-31 "Linux man-pages 6.7" .SH NAME shmget \- allocates a System V shared memory segment .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/shm.h> -.PP +.P .BI "int shmget(key_t " key ", size_t " size ", int " shmflg ); .fi .SH DESCRIPTION @@ -40,7 +40,7 @@ is zero and does not have the value .BR IPC_PRIVATE ), or to create a new set. -.PP +.P A new shared memory segment, with size equal to the value of .I size rounded up to a multiple of @@ -59,7 +59,7 @@ exists, and .B IPC_CREAT is specified in .IR shmflg . -.PP +.P If .I shmflg specifies both @@ -78,7 +78,7 @@ set to .B O_CREAT | O_EXCL for .BR open (2).) -.PP +.P The value .I shmflg is composed of: @@ -102,7 +102,9 @@ See the Linux kernel source file .I Documentation/admin\-guide/mm/hugetlbpage.rst for further information. .TP -.BR SHM_HUGE_2MB ", " SHM_HUGE_1GB " (since Linux 3.8)" +.B SHM_HUGE_2MB +.TQ +.BR SHM_HUGE_1GB " (since Linux 3.8)" .\" See https://lwn.net/Articles/533499/ Used in conjunction with .B SHM_HUGETLB @@ -143,7 +145,7 @@ in .BR proc (5). .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also .\" specified. -.PP +.P In addition to the above flags, the least significant 9 bits of .I shmflg specify the permissions granted to the owner, group, and others. @@ -153,7 +155,7 @@ meaning, as the argument of .BR open (2). Presently, execute permissions are not used by the system. -.PP +.P When a new shared memory segment is created, its contents are initialized to zero values, and its associated data structure, @@ -190,7 +192,7 @@ are set to 0. .IP \[bu] .I shm_ctime is set to the current time. -.PP +.P If the shared memory segment already exists, the permissions are verified, and a check is made to see if it is marked for destruction. .SH RETURN VALUE @@ -263,7 +265,7 @@ in .BR proc (5). .SH STANDARDS POSIX.1-2008. -.PP +.P .B SHM_HUGETLB and .B SHM_NORESERVE @@ -380,7 +382,7 @@ On Linux, this limit can be read and modified via .\" Kernels between Linux 2.4.x and Linux 2.6.8 had an off-by-one error .\" that meant that we could create one more segment than SHMMNI -- MTK .\" This /proc file is not available in Linux 2.2 and earlier -- MTK -.PP +.P The implementation has no specific limits for the per-process maximum number of shared memory segments .RB ( SHMSEG ). diff --git a/man2/shmop.2 b/man2/shmop.2 index 09168ec..a763420 100644 --- a/man2/shmop.2 +++ b/man2/shmop.2 @@ -17,7 +17,7 @@ .\" Changed wording and placement of sentence regarding attachment .\" of segments marked for destruction .\" -.TH SHMOP 2 2023-05-03 "Linux man-pages 6.05.01" +.TH SHMOP 2 2023-10-31 "Linux man-pages 6.7" .SH NAME shmat, shmdt \- System V shared memory operations .SH LIBRARY @@ -26,7 +26,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/shm.h> -.PP +.P .BI "void *shmat(int " shmid ", const void *_Nullable " shmaddr ", \ int " shmflg ); .BI "int shmdt(const void *" shmaddr ); @@ -62,7 +62,7 @@ rounded down to the nearest multiple of Otherwise, .I shmaddr must be a page-aligned address at which the attach occurs. -.PP +.P In addition to .BR SHM_RND , the following flags may be specified in the @@ -93,14 +93,14 @@ error would result if a mapping already exists in this address range.) In this case, .I shmaddr must not be NULL. -.PP +.P The .BR brk (2) value of the calling process is not altered by the attach. The segment will automatically be detached at process exit. The same segment may be attached as a read and as a read-write one, and more than once, in the process's address space. -.PP +.P A successful .BR shmat () call updates the members of the @@ -129,7 +129,7 @@ attached with equal to the value returned by the attaching .BR shmat () call. -.PP +.P On a successful .BR shmdt () call, the system updates the members of the @@ -154,7 +154,7 @@ returns the address of the attached shared memory segment; on error, is returned, and .I errno is set to indicate the error. -.PP +.P On success, .BR shmdt () returns 0; on error \-1 is returned, and @@ -189,7 +189,7 @@ was NULL. .TP .B ENOMEM Could not allocate memory for the descriptor or for the page tables. -.PP +.P .BR shmdt () can fail with one of the following errors: .TP @@ -205,7 +205,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. .\" SVr4 documents an additional error condition EMFILE. -.PP +.P In SVID 3 (or perhaps earlier), the type of the \fIshmaddr\fP argument was changed from .I "char\ *" @@ -221,15 +221,15 @@ into After a .BR fork (2), the child inherits the attached shared memory segments. -.PP +.P After an .BR execve (2), all attached shared memory segments are detached from the process. -.PP +.P Upon .BR _exit (2), all attached shared memory segments are detached from the process. -.PP +.P Using .BR shmat () with @@ -241,12 +241,12 @@ may be attached at different addresses in different processes. Therefore, any pointers maintained within the shared memory must be made relative (typically to the starting address of the segment), rather than absolute. -.PP +.P On Linux, it is possible to attach a shared memory segment even if it is already marked to be deleted. However, POSIX.1 does not specify this behavior and many other implementations do not support it. -.PP +.P The following system parameter affects .BR shmat (): .TP @@ -264,7 +264,7 @@ is normally some multiple of the system page size. (On many Linux architectures, .B SHMLBA is the same as the system page size.) -.PP +.P The implementation places no intrinsic per-process limit on the number of shared memory segments .RB ( SHMSEG ). @@ -272,37 +272,37 @@ number of shared memory segments The two programs shown below exchange a string using a shared memory segment. Further details about the programs are given below. First, we show a shell session demonstrating their use. -.PP +.P In one terminal window, we run the "reader" program, which creates a System V shared memory segment and a System V semaphore set. The program prints out the IDs of the created objects, and then waits for the semaphore to change value. -.PP +.P .in +4n .EX $ \fB./svshm_string_read\fP shmid = 1114194; semid = 15 .EE .in -.PP +.P In another terminal window, we run the "writer" program. The "writer" program takes three command-line arguments: the IDs of the shared memory segment and semaphore set created by the "reader", and a string. It attaches the existing shared memory segment, copies the string to the shared memory, and modifies the semaphore value. -.PP +.P .in +4n .EX $ \fB./svshm_string_write 1114194 15 \[aq]Hello, world\[aq]\fP .EE .in -.PP +.P Returning to the terminal where the "reader" is running, we see that the program has ceased waiting on the semaphore and has printed the string that was copied into the shared memory segment by the writer: -.PP +.P .in +4n .EX Hello, world @@ -311,7 +311,7 @@ Hello, world .\" .SS Program source: svshm_string.h The following header file is included by the "reader" and "writer" programs: -.PP +.P .in +4n .\" SRC BEGIN (svshm_string.h) .EX @@ -352,7 +352,7 @@ and initializes the semaphore value to 1. Finally, the program waits for the semaphore value to become 0, and afterwards prints the string that has been copied into the shared memory segment by the "writer". -.PP +.P .in +4n .\" SRC BEGIN (svshm_string_read.c) .EX @@ -434,7 +434,7 @@ that have already been created by the "reader", and a string. It attaches the shared memory segment into its address space, and then decrements the semaphore value to 0 in order to inform the "reader" that it can now examine the contents of the shared memory. -.PP +.P .in +4n .\" SRC BEGIN (svshm_string_write.c) .EX diff --git a/man2/shutdown.2 b/man2/shutdown.2 index d9cbcc1..6f45f9f 100644 --- a/man2/shutdown.2 +++ b/man2/shutdown.2 @@ -9,7 +9,7 @@ .\" Modified Tue Oct 22 22:04:51 1996 by Eric S. Raymond <esr@thyrsus.com> .\" Modified 1998 by Andi Kleen .\" -.TH shutdown 2 2023-03-30 "Linux man-pages 6.05.01" +.TH shutdown 2 2023-10-31 "Linux man-pages 6.7" .SH NAME shutdown \- shut down part of a full-duplex connection .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int shutdown(int " sockfd ", int " how ); .fi .SH DESCRIPTION diff --git a/man2/sigaction.2 b/man2/sigaction.2 index 8edde42..bbe4d5a 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -25,7 +25,7 @@ .\" 2015-01-17, Kees Cook <keescook@chromium.org> .\" Added notes on ptrace SIGTRAP and SYS_SECCOMP. .\" -.TH sigaction 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sigaction 2 2024-02-25 "Linux man-pages 6.7" .SH NAME sigaction, rt_sigaction \- examine and change a signal action .SH LIBRARY @@ -34,22 +34,22 @@ Standard C library .SH SYNOPSIS .nf .B #include <signal.h> -.PP +.P .BI "int sigaction(int " signum , .BI " const struct sigaction *_Nullable restrict " act , .BI " struct sigaction *_Nullable restrict " oldact ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigaction (): .nf _POSIX_C_SOURCE .fi -.PP +.P .IR siginfo_t : .nf _POSIX_C_SOURCE >= 199309L @@ -62,13 +62,13 @@ receipt of a specific signal. (See .BR signal (7) for an overview of signals.) -.PP +.P .I signum specifies the signal and can be any valid signal except .B SIGKILL and .BR SIGSTOP . -.PP +.P If .I act is non-NULL, the new action for signal @@ -79,11 +79,11 @@ If .I oldact is non-NULL, the previous action is saved in .IR oldact . -.PP +.P The .I sigaction structure is defined as something like: -.PP +.P .in +4n .EX struct sigaction { @@ -95,12 +95,12 @@ struct sigaction { }; .EE .in -.PP +.P On some architectures a union is involved: do not assign to both .I sa_handler and .IR sa_sigaction . -.PP +.P The .I sa_restorer field is not intended for application use. @@ -109,7 +109,7 @@ field is not intended for application use. field.) Some further details of the purpose of this field can be found in .BR sigreturn (2). -.PP +.P .I sa_handler specifies the action to be associated with .I signum @@ -123,7 +123,7 @@ to ignore this signal. .IP \[bu] A pointer to a signal handling function. This function receives the signal number as its only argument. -.PP +.P If .B SA_SIGINFO is specified in @@ -135,7 +135,7 @@ then specifies the signal-handling function for .IR signum . This function receives three arguments, as described below. -.PP +.P .I sa_mask specifies a mask of signals which should be blocked (i.e., added to the signal mask of the thread in which @@ -145,7 +145,7 @@ In addition, the signal which triggered the handler will be blocked, unless the .B SA_NODEFER flag is used. -.PP +.P .I sa_flags specifies a set of flags which modify the behavior of the signal. It is formed by the bitwise OR of zero or more of the following: @@ -292,7 +292,7 @@ the signal handler address is passed via the .I act.sa_sigaction field. This handler takes three arguments, as follows: -.PP +.P .in +4n .EX void @@ -302,7 +302,7 @@ handler(int sig, siginfo_t *info, void *ucontext) } .EE .in -.PP +.P These three arguments are as follows .TP .I sig @@ -329,11 +329,11 @@ structure can be found in and .BR signal (7). Commonly, the handler function doesn't make any use of the third argument. -.PP +.P The .I siginfo_t data type is a structure with the following fields: -.PP +.P .in +4n .EX siginfo_t { @@ -380,7 +380,7 @@ siginfo_t { } .EE .in -.PP +.P .IR si_signo ", " si_errno " and " si_code are defined for all signals. .RI ( si_errno @@ -595,13 +595,13 @@ event, will contain .B SIGTRAP and have the ptrace event in the high byte: -.PP +.P .in +4n .EX (SIGTRAP | PTRACE_EVENT_foo << 8). .EE .in -.PP +.P For a .RB non- ptrace (2) event, the values that can appear in @@ -624,12 +624,12 @@ or .IP \[bu] .B _POSIX_C_SOURCE with the value 200809L or greater. -.PP +.P For the .B TRAP_* constants, the symbol definitions are provided only in the first two cases. Before glibc 2.20, no feature test macros were required to obtain these symbols. -.PP +.P For a regular signal, the following list shows the values which can be placed in .I si_code @@ -672,7 +672,7 @@ or .\" It appears to have been an idea that was tried during 2.5.6 .\" through to Linux 2.5.24 and then was backed out. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -704,7 +704,7 @@ Coprocessor error. .B ILL_BADSTK Internal stack error. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -736,7 +736,7 @@ Floating-point invalid operation. .B FPE_FLTSUB Subscript out of range. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -762,7 +762,7 @@ See The protection key which applied to this access is available via .IR si_pkey . .RE -.PP +.P The following values can be placed in .I si_code for a @@ -785,7 +785,7 @@ Hardware memory error consumed on a machine check; action required. .BR BUS_MCEERR_AO " (since Linux 2.6.32)" Hardware memory error detected in process but not consumed; action optional. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -805,7 +805,7 @@ Process taken branch trap. .BR TRAP_HWBKPT " (since Linux 2.4, IA64 only)" Hardware breakpoint/watchpoint. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -831,7 +831,7 @@ Child has stopped. .BR CLD_CONTINUED " (since Linux 2.6.9)" Stopped child has continued. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -857,7 +857,7 @@ High priority input available. .B POLL_HUP Device disconnected. .RE -.PP +.P The following value can be placed in .I si_code for a @@ -884,7 +884,7 @@ However, historically, a second .BR sigaction () call would typically leave those bits set in .IR oldact\->sa_flags . -.PP +.P This means that support for new flags cannot be detected simply by testing for a flag in .IR sa_flags , @@ -892,7 +892,7 @@ and a program must test that .B SA_UNSUPPORTED has been cleared before relying on the contents of .IR sa_flags . -.PP +.P Since the behavior of the signal handler cannot be guaranteed unless the check passes, it is wise to either block the affected signal @@ -901,12 +901,12 @@ or where this is not possible, for example if the signal is synchronous, to issue the second .BR sigaction () in the signal handler itself. -.PP +.P In kernels that do not support a specific flag, the kernel's behavior is as if the flag was not set, even if the flag was set in .IR act\->sa_flags . -.PP +.P The flags .BR SA_NOCLDSTOP , .BR SA_NOCLDWAIT , @@ -922,7 +922,7 @@ because they were introduced before Linux 5.11. However, in general, programs may assume that these flags are supported, since they have all been supported since Linux 2.6, which was released in the year 2003. -.PP +.P See EXAMPLES below for a demonstration of the use of .BR SA_UNSUPPORTED . .SH RETURN VALUE @@ -953,7 +953,7 @@ used internally by the NPTL threading implementation. See .BR nptl (7) for details. -.PP +.P On architectures where the signal trampoline resides in the C library, the glibc wrapper function for .BR sigaction () @@ -966,7 +966,7 @@ flag in the field. See .BR sigreturn (2). -.PP +.P The original Linux system call was named .BR sigaction (). However, with the addition of real-time signals in Linux 2.2, @@ -999,7 +999,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. .\" SVr4 does not document the EINTR condition. -.PP +.P POSIX.1-1990 disallowed setting the action for .B SIGCHLD to @@ -1016,27 +1016,34 @@ terminated children do not become zombies is to catch the signal and perform a .BR wait (2) or similar. -.PP +.P POSIX.1-1990 specified only .BR SA_NOCLDSTOP . POSIX.1-2001 added -.BR SA_NOCLDSTOP , .BR SA_NOCLDWAIT , .BR SA_NODEFER , .BR SA_ONSTACK , .BR SA_RESETHAND , .BR SA_RESTART , and -.BR SA_SIGINFO . +.B SA_SIGINFO +as XSI extensions. +POSIX.1-2008 moved +.BR SA_NODEFER , +.BR SA_RESETHAND , +.BR SA_RESTART , +and +.B SA_SIGINFO +to the base specifications. Use of these latter values in .I sa_flags may be less portable in applications intended for older UNIX implementations. -.PP +.P The .B SA_RESETHAND flag is compatible with the SVr4 flag of the same name. -.PP +.P The .B SA_NODEFER flag is compatible with the SVr4 flag of the same name under kernels @@ -1054,7 +1061,7 @@ During an .BR execve (2), the dispositions of handled signals are reset to the default; the dispositions of ignored signals are left unchanged. -.PP +.P According to POSIX, the behavior of a process is undefined after it ignores a .BR SIGFPE , @@ -1072,23 +1079,23 @@ signal. (Also dividing the most negative integer by \-1 may generate .BR SIGFPE .) Ignoring this signal might lead to an endless loop. -.PP +.P .BR sigaction () can be called with a NULL second argument to query the current signal handler. It can also be used to check whether a given signal is valid for the current machine by calling it with NULL second and third arguments. -.PP +.P It is not possible to block .BR SIGKILL " or " SIGSTOP (by specifying them in .IR sa_mask ). Attempts to do so are silently ignored. -.PP +.P See .BR sigsetops (3) for details on manipulating signal sets. -.PP +.P See .BR signal\-safety (7) for a list of the async-signal-safe functions that can be @@ -1119,7 +1126,7 @@ the kernel does not always provide meaningful values for all of the fields of the .I siginfo_t that are relevant for that signal. -.PP +.P Up to and including Linux 2.6.13, specifying .B SA_NODEFER in @@ -1140,7 +1147,7 @@ if is determined to be supported, and .B EXIT_FAILURE otherwise. -.PP +.P .\" SRC BEGIN (sigaction.c) .EX #include <signal.h> diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 index 0ebfebd..82ba812 100644 --- a/man2/sigaltstack.2 +++ b/man2/sigaltstack.2 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" aeb, various minor fixes -.TH sigaltstack 2 2023-07-20 "Linux man-pages 6.05.01" +.TH sigaltstack 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigaltstack \- set and/or get signal stack context .SH LIBRARY @@ -13,16 +13,16 @@ Standard C library .SH SYNOPSIS .nf .B #include <signal.h> -.PP +.P .BI "int sigaltstack(const stack_t *_Nullable restrict " ss , .BI " stack_t *_Nullable restrict " old_ss ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigaltstack (): .nf _XOPEN_SOURCE >= 500 @@ -39,7 +39,7 @@ An alternate signal stack is used during the execution of a signal handler if the establishment of that handler (see .BR sigaction (2)) requested it. -.PP +.P The normal sequence of events for using an alternate signal stack is the following: .TP 3 @@ -59,18 +59,18 @@ When establishing a signal handler using inform the system that the signal handler should be executed on the alternate signal stack by specifying the \fBSA_ONSTACK\fP flag. -.PP +.P The \fIss\fP argument is used to specify a new alternate signal stack, while the \fIold_ss\fP argument is used to retrieve information about the currently established signal stack. If we are interested in performing just one of these tasks, then the other argument can be specified as NULL. -.PP +.P The .I stack_t type used to type the arguments of this function is defined as follows: -.PP +.P .in +4n .EX typedef struct { @@ -80,7 +80,7 @@ typedef struct { } stack_t; .EE .in -.PP +.P To establish a new alternate signal stack, the fields of this structure are set as follows: .TP @@ -119,14 +119,14 @@ The constant \fBSIGSTKSZ\fP is defined to be large enough to cover the usual size requirements for an alternate signal stack, and the constant \fBMINSIGSTKSZ\fP defines the minimum size required to execute a signal handler. -.PP +.P To disable an existing stack, specify \fIss.ss_flags\fP as \fBSS_DISABLE\fP. In this case, the kernel ignores any other flags in .I ss.ss_flags and the remaining fields in \fIss\fP. -.PP +.P If \fIold_ss\fP is not NULL, then it is used to return information about the alternate signal stack which was in effect prior to the call to @@ -162,7 +162,7 @@ using a further call to .B SS_AUTODISARM The alternate signal stack has been marked to be autodisarmed as described above. -.PP +.P By specifying .I ss as NULL, and @@ -207,10 +207,9 @@ T{ .BR sigaltstack () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. -.PP +.P .B SS_AUTODISARM is a Linux extension. .SH HISTORY @@ -223,7 +222,7 @@ standard stack is exhausted: in this case, a signal handler for .B SIGSEGV cannot be invoked on the standard stack; if we wish to handle it, we must use an alternate signal stack. -.PP +.P Establishing an alternate signal stack is useful if a thread expects that it may exhaust its standard stack. This may occur, for example, because the stack grows so large @@ -233,13 +232,13 @@ If the standard stack is exhausted, the kernel sends the thread a \fBSIGSEGV\fP signal. In these circumstances the only way to catch this signal is on an alternate signal stack. -.PP +.P On most hardware architectures supported by Linux, stacks grow downward. .BR sigaltstack () automatically takes account of the direction of stack growth. -.PP +.P Functions called from a signal handler executing on an alternate signal stack will also use the alternate signal stack. (This also applies to any handlers invoked for other signals while @@ -248,7 +247,7 @@ Unlike the standard stack, the system does not automatically extend the alternate signal stack. Exceeding the allocated size of the alternate signal stack will lead to unpredictable results. -.PP +.P A successful call to .BR execve (2) removes any existing alternate @@ -264,7 +263,7 @@ and do not include .BR CLONE_VFORK , in which case any alternate signal stack that was established in the parent is disabled in the child process. -.PP +.P .BR sigaltstack () supersedes the older .BR sigstack () @@ -327,7 +326,7 @@ to install an alternate signal stack that is employed by a handler for the .B SIGSEGV signal: -.PP +.P .in +4n .EX stack_t ss; diff --git a/man2/signal.2 b/man2/signal.2 index 619babf..77f7b19 100644 --- a/man2/signal.2 +++ b/man2/signal.2 @@ -13,7 +13,7 @@ .\" various sections. .\" 2008-07-11, mtk: rewrote and expanded portability discussion. .\" -.TH signal 2 2023-03-30 "Linux man-pages 6.05.01" +.TH signal 2 2023-10-31 "Linux man-pages 6.7" .SH NAME signal \- ANSI C signal handling .SH LIBRARY @@ -22,9 +22,9 @@ Standard C library .SH SYNOPSIS .nf .B #include <signal.h> -.PP +.P .B typedef void (*sighandler_t)(int); -.PP +.P .BI "sighandler_t signal(int " signum ", sighandler_t " handler ); .fi .SH DESCRIPTION @@ -37,7 +37,7 @@ and has also varied historically across different versions of Linux. .BR sigaction (2) instead. See \fIPortability\fP below. -.PP +.P .BR signal () sets the disposition of the signal .I signum @@ -47,7 +47,7 @@ which is either .BR SIG_IGN , .BR SIG_DFL , or the address of a programmer-defined function (a "signal handler"). -.PP +.P If the signal .I signum is delivered to the process, then one of the following happens: @@ -74,7 +74,7 @@ is called with argument .IR signum . If invocation of the handler caused the signal to be blocked, then the signal is unblocked upon return from the handler. -.PP +.P The signals .B SIGKILL and @@ -113,7 +113,7 @@ is defined. Without use of such a type, the declaration of .BR signal () is the somewhat harder to read: -.PP +.P .in +4n .EX .BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);" @@ -131,7 +131,7 @@ The semantics when using to establish a signal handler vary across systems (and POSIX.1 explicitly permits this variation); .B do not use it for this purpose. -.PP +.P POSIX.1 solved the portability mess by specifying .BR sigaction (2), which provides explicit control of the semantics when a @@ -141,7 +141,7 @@ signal handler is invoked; use that interface instead of C11, POSIX.1-2008. .SH HISTORY C89, POSIX.1-2001. -.PP +.P In the original UNIX systems, when a handler that was established using .BR signal () was invoked by the delivery of a signal, @@ -151,20 +151,20 @@ and the system did not block delivery of further instances of the signal. This is equivalent to calling .BR sigaction (2) with the following flags: -.PP +.P .in +4n .EX sa.sa_flags = SA_RESETHAND | SA_NODEFER; .EE .in -.PP +.P System\ V also provides these semantics for .BR signal (). This was bad because the signal might be delivered again before the handler had a chance to reestablish itself. Furthermore, rapid deliveries of the same signal could result in recursive invocations of the handler. -.PP +.P BSD improved on this situation, but unfortunately also changed the semantics of the existing .BR signal () @@ -179,13 +179,13 @@ restarted if interrupted by a signal handler (see The BSD semantics are equivalent to calling .BR sigaction (2) with the following flags: -.PP +.P .in +4n .EX sa.sa_flags = SA_RESTART; .EE .in -.PP +.P The situation on Linux is as follows: .IP \[bu] 3 The kernel's @@ -214,7 +214,7 @@ provides System\ V semantics. .\" System V semantics are also provided if one uses the separate .\" .BR sysv_signal (3) .\" function. -.\" .IP * +.\" .IP \[bu] .\" The .\" .BR signal () .\" function in Linux libc4 and libc5 provide System\ V semantics. @@ -229,7 +229,7 @@ provides System\ V semantics. The effects of .BR signal () in a multithreaded process are unspecified. -.PP +.P According to POSIX, the behavior of a process is undefined after it ignores a .BR SIGFPE , @@ -247,14 +247,14 @@ signal. (Also dividing the most negative integer by \-1 may generate .BR SIGFPE .) Ignoring this signal might lead to an endless loop. -.PP +.P See .BR sigaction (2) for details on what happens when the disposition .B SIGCHLD is set to .BR SIG_IGN . -.PP +.P See .BR signal\-safety (7) for a list of the async-signal-safe functions that can be diff --git a/man2/signalfd.2 b/man2/signalfd.2 index 9af22b0..fba622c 100644 --- a/man2/signalfd.2 +++ b/man2/signalfd.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH signalfd 2 2023-05-03 "Linux man-pages 6.05.01" +.TH signalfd 2 2023-10-31 "Linux man-pages 6.7" .SH NAME signalfd \- create a file descriptor for accepting signals .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/signalfd.h> -.PP +.P .BI "int signalfd(int " fd ", const sigset_t *" mask ", int " flags ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ and has the advantage that the file descriptor may be monitored by .BR poll (2), and .BR epoll (7). -.PP +.P The .I mask argument specifies the set of signals that the caller @@ -46,7 +46,7 @@ or signals via a signalfd file descriptor; these signals are silently ignored if specified in .IR mask . -.PP +.P If the .I fd argument is \-1, @@ -60,7 +60,7 @@ is not \-1, then it must specify a valid existing signalfd file descriptor, and .I mask is used to replace the signal set associated with that file descriptor. -.PP +.P Starting with Linux 2.6.27, the following values may be bitwise ORed in .I flags to change the behavior of @@ -85,11 +85,11 @@ See the description of the flag in .BR open (2) for reasons why this may be useful. -.PP +.P Up to Linux 2.6.26, the .I flags argument is unused, and must be specified as zero. -.PP +.P .BR signalfd () returns a file descriptor that supports the following operations: .TP @@ -131,7 +131,11 @@ or fails with the error .B EAGAIN if the file descriptor has been made nonblocking. .TP -.BR poll "(2), " select "(2) (and similar)" +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) The file descriptor is readable (the .BR select (2) @@ -161,7 +165,7 @@ The format of the structure(s) returned by .BR read (2)s from a signalfd file descriptor is as follows: -.PP +.P .in +4n .EX struct signalfd_siginfo { @@ -192,7 +196,7 @@ struct signalfd_siginfo { }; .EE .in -.PP +.P Each of the fields in this structure is analogous to the similarly named field in the .I siginfo_t @@ -338,7 +342,7 @@ The glibc .BR signalfd () wrapper function does not include this argument, since it provides the required value for the underlying system call. -.PP +.P There are two underlying Linux system calls: .BR signalfd () and the more recent @@ -379,7 +383,7 @@ If a signal appears in the .I mask of more than one of the file descriptors, then occurrences of that signal can be read (once) from any one of the file descriptors. -.PP +.P Attempts to include .B SIGKILL and @@ -387,7 +391,7 @@ and in .I mask are silently ignored. -.PP +.P The signal mask employed by a signalfd file descriptor can be viewed via the entry for the corresponding file descriptor in the process's .IR /proc/ pid /fdinfo @@ -405,7 +409,7 @@ or the .B SIGFPE signal that results from an arithmetic error. Such signals can be caught only via signal handler. -.PP +.P As described above, in normal usage one blocks the signals that will be accepted via .BR signalfd (). @@ -443,7 +447,7 @@ The program terminates after accepting a .B SIGQUIT signal. The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX .RB "$" " ./signalfd_demo" diff --git a/man2/sigpending.2 b/man2/sigpending.2 index e1b3158..cd67531 100644 --- a/man2/sigpending.2 +++ b/man2/sigpending.2 @@ -6,7 +6,7 @@ .\" .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 .\" -.TH sigpending 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigpending 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigpending, rt_sigpending \- examine pending signals .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <signal.h> -.PP +.P .BI "int sigpending(sigset_t *" set ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigpending (): .nf _POSIX_C_SOURCE @@ -79,16 +79,16 @@ when the kernel provides it. See .BR sigsetops (3) for details on manipulating signal sets. -.PP +.P If a signal is both blocked and has a disposition of "ignored", it is .I not added to the mask of pending signals when generated. -.PP +.P The set of signals that is pending for a thread is the union of the set of signals that is pending for that thread and the set of signals that is pending for the process as a whole; see .BR signal (7). -.PP +.P A child created via .BR fork (2) initially has an empty pending signal set; diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2 index a89c1ed..f0017b4 100644 --- a/man2/sigprocmask.2 +++ b/man2/sigprocmask.2 @@ -6,7 +6,7 @@ .\" .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 .\" -.TH sigprocmask 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigprocmask 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigprocmask, rt_sigprocmask \- examine and change blocked signals .SH LIBRARY @@ -14,33 +14,33 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .B #include <signal.h> -.PP +.P .nf /* Prototype for the glibc wrapper function */ .BI "int sigprocmask(int " how ", const sigset_t *_Nullable restrict " set , .BI " sigset_t *_Nullable restrict " oldset ); -.PP +.P .BR "#include <signal.h>" " /* Definition of " SIG_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P /* Prototype for the underlying system call */ .BI "int syscall(SYS_rt_sigprocmask, int " how , .BI " const kernel_sigset_t *_Nullable " set , .BI " kernel_sigset_t *_Nullable " oldset , .BI " size_t " sigsetsize ); -.PP +.P /* Prototype for the legacy system call */ .BI "[[deprecated]] int syscall(SYS_sigprocmask, int " how , .BI " const old_kernel_sigset_t *_Nullable " set , .BI " old_kernel_sigset_t *_Nullable " oldset ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigprocmask (): .nf _POSIX_C_SOURCE @@ -53,7 +53,7 @@ blocked for the caller (see also .BR signal (7) for more details). -.PP +.P The behavior of the call is dependent on the value of .IR how , as follows. @@ -72,12 +72,12 @@ It is permissible to attempt to unblock a signal which is not blocked. .B SIG_SETMASK The set of blocked signals is set to the argument .IR set . -.PP +.P If .I oldset is non-NULL, the previous value of the signal mask is stored in .IR oldset . -.PP +.P If .I set is NULL, then the signal mask is unchanged (i.e., @@ -86,12 +86,12 @@ is ignored), but the current value of the signal mask is nevertheless returned in .I oldset (if it is not NULL). -.PP +.P A set of functions for modifying and inspecting variables of type .I sigset_t ("signal sets") is described in .BR sigsetops (3). -.PP +.P The use of .BR sigprocmask () is unspecified in a multithreaded process; see @@ -127,7 +127,7 @@ In this manual page, the former is referred to as (it is nevertheless named .I sigset_t in the kernel sources). -.PP +.P The glibc wrapper function for .BR sigprocmask () silently ignores attempts to block the two real-time signals that @@ -135,7 +135,7 @@ are used internally by the NPTL threading implementation. See .BR nptl (7) for details. -.PP +.P The original Linux system call was named .BR sigprocmask (). However, with the addition of real-time signals in Linux 2.2, @@ -164,7 +164,7 @@ This argument is currently required to have a fixed architecture specific value .IR sizeof(kernel_sigset_t) ). .\" sizeof(kernel_sigset_t) == _NSIG / 8, .\" which equals to 8 on most architectures, but e.g. on MIPS it's 16. -.PP +.P The glibc .BR sigprocmask () wrapper function hides these details from us, transparently calling @@ -179,15 +179,15 @@ POSIX.1-2001. It is not possible to block .BR SIGKILL " or " SIGSTOP . Attempts to do so are silently ignored. -.PP +.P Each of the threads in a process has its own 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 If .BR SIGBUS , .BR SIGFPE , @@ -201,11 +201,11 @@ unless the signal was generated by .BR sigqueue (3), or .BR raise (3). -.PP +.P See .BR sigsetops (3) for details on manipulating signal sets. -.PP +.P Note that it is permissible (although not very useful) to specify both .I set and diff --git a/man2/sigreturn.2 b/man2/sigreturn.2 index 03ce952..dd0935a 100644 --- a/man2/sigreturn.2 +++ b/man2/sigreturn.2 @@ -7,7 +7,7 @@ .\" 2008-06-26, mtk, added some more detail on the work done by sigreturn() .\" 2014-12-05, mtk, rewrote all of the rest of the original page .\" -.TH sigreturn 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigreturn 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame .SH LIBRARY @@ -27,14 +27,14 @@ it creates a new frame on the user-space stack where it saves various pieces of process context (processor status word, registers, signal mask, and signal stack settings). .\" See arch/x86/kernel/signal.c::__setup_frame() [in Linux 3.17 source code] -.PP +.P The kernel also arranges that, during the transition back to user mode, the signal handler is called, and that, upon return from the handler, control passes to a piece of user-space code commonly called the "signal trampoline". The signal trampoline code in turn calls .BR sigreturn (). -.PP +.P This .BR sigreturn () call undoes everything that was @@ -82,7 +82,7 @@ vary depending on the architecture. takes no arguments, since all of the information that it requires is available in the stack frame that was previously created by the kernel on the user-space stack.) -.PP +.P Once upon a time, UNIX systems placed the signal trampoline code onto the user stack. Nowadays, pages of the user stack are protected so as to @@ -107,7 +107,7 @@ and sets the flag in the .I sa_flags field. -.PP +.P The saved process context information is placed in a .I ucontext_t structure (see @@ -118,7 +118,7 @@ as the third argument of a handler established via with the .B SA_SIGINFO flag. -.PP +.P On some other UNIX systems, the operation of the signal trampoline differs a little. In particular, on some systems, upon transitioning back to user mode, diff --git a/man2/sigsuspend.2 b/man2/sigsuspend.2 index f89a6ca..9bb39f8 100644 --- a/man2/sigsuspend.2 +++ b/man2/sigsuspend.2 @@ -6,7 +6,7 @@ .\" .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 .\" -.TH sigsuspend 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigsuspend 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigsuspend, rt_sigsuspend \- wait for a signal .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <signal.h> -.PP +.P .BI "int sigsuspend(const sigset_t *" mask ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigsuspend (): .nf _POSIX_C_SOURCE @@ -35,7 +35,7 @@ mask given by .I mask and then suspends the thread until delivery of a signal whose action is to invoke a signal handler or to terminate a process. -.PP +.P If the signal terminates the process, then .BR sigsuspend () does not return. @@ -44,7 +44,7 @@ If the signal is caught, then returns after the signal handler returns, and the signal mask is restored to the state before the call to .BR sigsuspend (). -.PP +.P It is not possible to block .B SIGKILL or @@ -115,7 +115,7 @@ with the signal mask that was returned by (in the .I oldset argument). -.PP +.P See .BR sigsetops (3) for details on manipulating signal sets. diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2 index a5703fc..cf231bc 100644 --- a/man2/sigwaitinfo.2 +++ b/man2/sigwaitinfo.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sigwaitinfo 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigwaitinfo 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigwaitinfo, sigtimedwait, rt_sigtimedwait \- synchronously wait for queued signals @@ -12,19 +12,19 @@ Standard C library .SH SYNOPSIS .nf .B #include <signal.h> -.PP +.P .BI "int sigwaitinfo(const sigset_t *restrict " set , .BI " siginfo_t *_Nullable restrict " info ); .BI "int sigtimedwait(const sigset_t *restrict " set , .BI " siginfo_t *_Nullable restrict " info , .BI " const struct timespec *restrict " timeout ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigwaitinfo (), .BR sigtimedwait (): .nf @@ -40,7 +40,7 @@ is pending is already pending for the calling thread, .BR sigwaitinfo () will return immediately.) -.PP +.P .BR sigwaitinfo () removes the signal from the set of pending signals and returns the signal number as its function result. @@ -52,7 +52,7 @@ then the buffer that it points to is used to return a structure of type (see .BR sigaction (2)) containing information about the signal. -.PP +.P If multiple signals in .I set are pending for the caller, the signal that is retrieved by @@ -60,7 +60,7 @@ are pending for the caller, the signal that is retrieved by is determined according to the usual ordering rules; see .BR signal (7) for further details. -.PP +.P .BR sigtimedwait () operates in exactly the same way as .BR sigwaitinfo () @@ -74,7 +74,7 @@ may overrun by a small amount.) This argument is a .BR timespec (3) structure. -.PP +.P If both fields of this structure are specified as 0, a poll is performed: .BR sigtimedwait () returns immediately, either with information about a signal that @@ -116,7 +116,7 @@ On Linux, .BR sigwaitinfo () is a library function implemented on top of .BR sigtimedwait (). -.PP +.P The glibc wrapper functions for .BR sigwaitinfo () and @@ -126,7 +126,7 @@ are used internally by the NPTL threading implementation. See .BR nptl (7) for details. -.PP +.P The original Linux system call was named .BR sigtimedwait (). However, with the addition of real-time signals in Linux 2.2, @@ -175,18 +175,18 @@ a thread other than the one calling .BR sigwaitinfo () or .BR sigtimedwait ()). -.PP +.P The set of signals that is pending for a given thread is the union of the set of signals that is pending specifically for that thread and the set of signals that is pending for the process as a whole (see .BR signal (7)). -.PP +.P Attempts to wait for .B SIGKILL and .B SIGSTOP are silently ignored. -.PP +.P If multiple threads of a process are blocked waiting for the same signal(s) in .BR sigwaitinfo () @@ -195,7 +195,7 @@ or then exactly one of the threads will actually receive the signal if it becomes pending for the process as a whole; which of the threads receives the signal is indeterminate. -.PP +.P .BR sigwaitinfo () or .BR sigtimedwait (), @@ -207,7 +207,7 @@ or the .B SIGFPE signal that results from an arithmetic error. Such signals can be caught only via signal handler. -.PP +.P POSIX leaves the meaning of a NULL value for the .I timeout argument of diff --git a/man2/socket.2 b/man2/socket.2 index 2a35f2b..b83bd5b 100644 --- a/man2/socket.2 +++ b/man2/socket.2 @@ -12,7 +12,7 @@ .\" Modified 2002-07-17 by Michael Kerrisk <mtk.manpages@gmail.com> .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH socket 2 2023-03-30 "Linux man-pages 6.05.01" +.TH socket 2 2024-01-28 "Linux man-pages 6.7" .SH NAME socket \- create an endpoint for communication .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int socket(int " domain ", int " type ", int " protocol ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ creates an endpoint for communication and returns a file descriptor that refers to that endpoint. The file descriptor returned by a successful call will be the lowest-numbered file descriptor not currently open for the process. -.PP +.P The .I domain argument specifies a communication domain; this selects the protocol @@ -79,7 +79,7 @@ T}:AppleTalk:T{ T} T{ .B AF_X25 -T}:ITU-T X.25 / ISO-8208 protocol:T{ +T}:ITU-T X.25 / ISO/IEC\~8208 protocol:T{ .BR x25 (7) T} T{ @@ -193,11 +193,11 @@ T}:T{ XDP (express data path) interface T} .TE -.PP +.P Further details of the above address families, as well as information on several other address families, can be found in .BR address_families (7). -.PP +.P The socket has the indicated .IR type , which specifies the communication semantics. @@ -227,9 +227,9 @@ Provides a reliable datagram layer that does not guarantee ordering. Obsolete and should not be used in new programs; see .BR packet (7). -.PP +.P Some socket types may not be implemented by all protocol families. -.PP +.P Since Linux 2.6.27, the .I type argument serves a second purpose: @@ -257,7 +257,7 @@ See the description of the flag in .BR open (2) for reasons why this may be useful. -.PP +.P The .I protocol specifies a particular protocol to be used with the socket. @@ -273,7 +273,7 @@ in which communication is to take place; see See .BR getprotoent (3) on how to map protocol name strings to protocol numbers. -.PP +.P Sockets of type .B SOCK_STREAM are full-duplex byte streams. @@ -303,7 +303,7 @@ Out-of-band data may also be transmitted as described in .BR send (2) and received as described in .BR recv (2). -.PP +.P The communications protocols which implement a .B SOCK_STREAM ensure that data is not lost or duplicated. @@ -329,7 +329,7 @@ The only difference is that calls will return only the amount of data requested, and any data remaining in the arriving packet will be discarded. Also all message boundaries in incoming datagrams are preserved. -.PP +.P .B SOCK_DGRAM and .B SOCK_RAW @@ -339,14 +339,14 @@ calls. Datagrams are generally received with .BR recvfrom (2), which returns the next datagram along with the address of its sender. -.PP +.P .B SOCK_PACKET is an obsolete socket type to receive raw packets directly from the device driver. Use .BR packet (7) instead. -.PP +.P An .BR fcntl (2) .B F_SETOWN @@ -369,7 +369,7 @@ call with the or .B SIOCSPGRP argument. -.PP +.P When the network signals an error condition to the protocol module (e.g., using an ICMP message for IP) the pending error flag is set for the socket. The next operation on this socket will return the error code of the pending @@ -379,7 +379,7 @@ to retrieve detailed information about the error; see .B IP_RECVERR in .BR ip (7). -.PP +.P The operation of sockets is controlled by socket level .IR options . These options are defined in @@ -425,24 +425,24 @@ created until sufficient resources are freed. .B EPROTONOSUPPORT The protocol type or the specified protocol is not supported within this domain. -.PP +.P Other errors may be generated by the underlying protocol modules. .SH STANDARDS POSIX.1-2008. -.PP +.P .B SOCK_NONBLOCK and .B SOCK_CLOEXEC are Linux-specific. .SH HISTORY POSIX.1-2001, 4.4BSD. -.PP +.P .BR socket () appeared in 4.2BSD. It is generally portable to/from non-BSD systems supporting clones of the BSD socket layer (including System\ V variants). -.PP +.P The manifest constants used under 4.x BSD for protocol families are .BR PF_UNIX , @@ -485,7 +485,7 @@ is shown in .BR tcp (7), .BR udp (7), .BR unix (7) -.PP +.P \[lq]An Introductory 4.3BSD Interprocess Communication Tutorial\[rq] and \[lq]BSD Interprocess Communication Tutorial\[rq], diff --git a/man2/socketcall.2 b/man2/socketcall.2 index 24f7f6b..d536966 100644 --- a/man2/socketcall.2 +++ b/man2/socketcall.2 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Tue Oct 22 22:11:53 1996 by Eric S. Raymond <esr@thyrsus.com> -.TH socketcall 2 2023-03-30 "Linux man-pages 6.05.01" +.TH socketcall 2 2023-10-31 "Linux man-pages 6.7" .SH NAME socketcall \- socket system calls .SH LIBRARY @@ -15,10 +15,10 @@ Standard C library .BR "#include <linux/net.h>" " /* Definition of " SYS_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_socketcall " */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_socketcall, int " call ", unsigned long *" args ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR socketcall (), @@ -32,11 +32,11 @@ determines which socket function to invoke. .I args points to a block containing the actual arguments, which are passed through to the appropriate call. -.PP +.P User programs should call the appropriate functions by their usual names. Only standard library implementors and kernel hackers need to know about .BR socketcall (). -.PP +.P .TS tab(:); l l. @@ -152,7 +152,7 @@ system call; instead and so on really are implemented as separate system calls. .SH STANDARDS Linux. -.PP +.P On x86-32, .BR socketcall () was historically the only entry point for the sockets API. diff --git a/man2/socketpair.2 b/man2/socketpair.2 index 741596e..ae304e6 100644 --- a/man2/socketpair.2 +++ b/man2/socketpair.2 @@ -11,7 +11,7 @@ .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> .\" 2008-10-11, mtk: Add description of SOCK_NONBLOCK and SOCK_CLOEXEC .\" -.TH socketpair 2 2023-03-30 "Linux man-pages 6.05.01" +.TH socketpair 2 2023-10-31 "Linux man-pages 6.7" .SH NAME socketpair \- create a pair of connected sockets .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .BI "int socketpair(int " domain ", int " type ", int " protocol \ ", int " sv [2]); .fi @@ -35,7 +35,7 @@ and using the optionally specified .IR protocol . For further details of these arguments, see .BR socket (2). -.PP +.P The file descriptors used in referencing the new sockets are returned in .I sv[0] and @@ -48,7 +48,7 @@ On error, \-1 is returned, is set to indicate the error, and .I sv is left unchanged -.PP +.P On Linux (and other systems), .BR socketpair () does not modify @@ -90,13 +90,13 @@ and POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.4BSD. -.PP +.P .BR socketpair () first appeared in 4.2BSD. It is generally portable to/from non-BSD systems supporting clones of the BSD socket layer (including System\ V variants). -.PP +.P Since Linux 2.6.27, .BR socketpair () supports the diff --git a/man2/splice.2 b/man2/splice.2 index 88d4160..ff39e03 100644 --- a/man2/splice.2 +++ b/man2/splice.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH splice 2 2023-07-15 "Linux man-pages 6.05.01" +.TH splice 2 2023-10-31 "Linux man-pages 6.7" .SH NAME splice \- splice data to/from a pipe .SH LIBRARY @@ -12,9 +12,9 @@ Standard C library .SH SYNOPSIS .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" -.B "#define _FILE_OFFSET_BITS 64 +.B #define _FILE_OFFSET_BITS 64 .B #include <fcntl.h> -.PP +.P .BI "ssize_t splice(int " fd_in ", off_t *_Nullable " off_in , .BI " int " fd_out ", off_t *_Nullable " off_out , .BI " size_t " len ", unsigned int " flags ); @@ -31,7 +31,7 @@ bytes of data from the file descriptor to the file descriptor .IR fd_out , where one of the file descriptors must refer to a pipe. -.PP +.P The following semantics apply for .I fd_in and @@ -64,12 +64,12 @@ offset from which bytes will be read from in this case, the file offset of .I fd_in is not changed. -.PP +.P Analogous statements apply for .I fd_out and .IR off_out . -.PP +.P The .I flags argument is a bit mask that is composed by ORing together @@ -121,14 +121,14 @@ Upon successful completion, .BR splice () returns the number of bytes spliced to or from the pipe. -.PP +.P A return value of 0 means end of input. If .I fd_in refers to a pipe, then this means that there was no data to transfer, and it would not make sense to block because there are no writers connected to the write end of the pipe. -.PP +.P On error, .BR splice () returns \-1 and @@ -182,7 +182,7 @@ Linux. .SH HISTORY Linux 2.6.17, glibc 2.5. -.PP +.P In Linux 2.6.30 and earlier, exactly one of .I fd_in @@ -212,7 +212,7 @@ or from one buffer to another. .TP .BR vmsplice (2) "copies" data from user space into the buffer. -.PP +.P Though we talk of copying, actual copies are generally avoided. The kernel does this by implementing a pipe buffer as a set of reference-counted pointers to pages of kernel memory. @@ -243,7 +243,7 @@ only pointers are copied, not the pages of the buffer. .\" the data and choose to forward it to two or more different .\" users - for things like logging etc.). .\" -.PP +.P .B _FILE_OFFSET_BITS should be defined to be 64 in code that uses non-null .I off_in diff --git a/man2/spu_create.2 b/man2/spu_create.2 index 36d1bbd..38efa2c 100644 --- a/man2/spu_create.2 +++ b/man2/spu_create.2 @@ -8,7 +8,7 @@ .\" 2007-07-10, some polishing by mtk .\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org> .\" -.TH spu_create 2 2023-03-30 "Linux man-pages 6.05.01" +.TH spu_create 2 2023-10-31 "Linux man-pages 6.7" .SH NAME spu_create \- create a new spu context .SH LIBRARY @@ -19,12 +19,12 @@ Standard C library .BR "#include <sys/spu.h>" " /* Definition of " SPU_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_spu_create, const char *" pathname \ ", unsigned int " flags , .BI " mode_t " mode ", int " neighbor_fd ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR spu_create (), @@ -49,7 +49,7 @@ is successful, a directory is created at .I pathname and it is populated with the files described in .BR spufs (7). -.PP +.P When a context is created, the returned file descriptor can only be passed to .BR spu_run (2), @@ -68,7 +68,7 @@ directory) once the last reference to the context has gone; this usually occurs when the file descriptor returned by .BR spu_create () is closed. -.PP +.P The .I mode argument (minus any bits set in the process's @@ -80,13 +80,13 @@ See for a full list of the possible .I mode values. -.PP +.P The .I neighbor_fd is used only when the .B SPU_CREATE_AFFINITY_SPU flag is specified; see below. -.PP +.P The .I flags argument can be zero or any bitwise OR-ed @@ -248,7 +248,7 @@ By convention, it gets mounted in Linux on PowerPC. .SH HISTORY Linux 2.6.16. -.PP +.P Prior to the addition of the .B SPU_CREATE_AFFINITY_SPU flag in Linux 2.6.23, the diff --git a/man2/spu_run.2 b/man2/spu_run.2 index 0a9d229..5b70753 100644 --- a/man2/spu_run.2 +++ b/man2/spu_run.2 @@ -9,7 +9,7 @@ .\" 2007-09-28, updates for newer kernels, added example .\" by Jeremy Kerr <jk@ozlabs.org> .\" -.TH spu_run 2 2023-05-03 "Linux man-pages 6.05.01" +.TH spu_run 2 2023-10-31 "Linux man-pages 6.7" .SH NAME spu_run \- execute an SPU context .SH LIBRARY @@ -20,11 +20,11 @@ Standard C library .BR "#include <sys/spu.h>" " /* Definition of " SPU_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \ ", uint32_t *" event ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR spu_run (), @@ -44,7 +44,7 @@ that refers to a specific SPU context. When the context gets scheduled to a physical SPU, it starts execution at the instruction pointer passed in .IR npc . -.PP +.P Execution of SPU code happens synchronously, meaning that .BR spu_run () blocks while the SPU is still running. @@ -53,7 +53,7 @@ to execute SPU code in parallel with other code on either the main CPU or other SPUs, a new thread of execution must be created first (e.g., using .BR pthread_create (3)). -.PP +.P When .BR spu_run () returns, the current value of the SPU program counter is written to @@ -63,7 +63,7 @@ so successive calls to can use the same .I npc pointer. -.PP +.P The .I event argument provides a buffer for an extended status code. @@ -73,7 +73,7 @@ context was created with the flag, then this buffer is populated by the Linux kernel before .BR spu_run () returns. -.PP +.P The status code may be one (or more) of the following constants: .TP .B SPE_EVENT_DMA_ALIGNMENT @@ -89,7 +89,7 @@ A DMA storage error occurred. .TP .B SPE_EVENT_SPE_ERROR An illegal instruction was executed. -.PP +.P NULL is a valid value for the .I event @@ -104,7 +104,7 @@ register. On failure, it returns \-1 and sets .I errno is set to indicate the error. -.PP +.P The .I spu_status register value is a bit mask of status codes and @@ -141,7 +141,7 @@ The bits masked with this value contain the code returned from a .B stop-and-signal instruction. These bits are valid only if the 0x02 bit is set. -.PP +.P If .BR spu_run () has not returned an error, one or more bits among the lower eight @@ -198,7 +198,7 @@ The following is an example of running a simple, one-instruction SPU program with the .BR spu_run () system call. -.PP +.P .\" SRC BEGIN (spu_run.c) .EX #include <err.h> diff --git a/man2/stat.2 b/man2/stat.2 index f41daab..bb813ff 100644 --- a/man2/stat.2 +++ b/man2/stat.2 @@ -16,7 +16,7 @@ .\" 2007-06-08 mtk: Added example program .\" 2007-07-05 mtk: Added details on underlying system call interfaces .\" -.TH stat 2 2023-05-03 "Linux man-pages 6.05.01" +.TH stat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME stat, fstat, lstat, fstatat \- get file status .SH LIBRARY @@ -25,25 +25,25 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/stat.h> -.PP +.P .BI "int stat(const char *restrict " pathname , .BI " struct stat *restrict " statbuf ); .BI "int fstat(int " fd ", struct stat *" statbuf ); .BI "int lstat(const char *restrict " pathname , .BI " struct stat *restrict " statbuf ); -.PP +.P .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" .B #include <sys/stat.h> -.PP +.P .BI "int fstatat(int " dirfd ", const char *restrict " pathname , .BI " struct stat *restrict " statbuf ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR lstat (): .nf /* Since glibc 2.20 */ _DEFAULT_SOURCE @@ -52,7 +52,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L || /* glibc 2.19 and earlier */ _BSD_SOURCE .fi -.PP +.P .BR fstatat (): .nf Since glibc 2.10: @@ -71,7 +71,7 @@ and (search) permission is required on all of the directories in .I pathname that lead to the file. -.PP +.P .BR stat () and .BR fstatat () @@ -80,7 +80,7 @@ retrieve information about the file pointed to by the differences for .BR fstatat () are described below. -.PP +.P .BR lstat () is identical to .BR stat (), @@ -88,7 +88,7 @@ except that if .I pathname is a symbolic link, then it returns information about the link itself, not the file that the link refers to. -.PP +.P .BR fstat () is identical to .BR stat (), @@ -101,7 +101,7 @@ All of these system calls return a .I stat structure (see .BR stat (3type)). -.PP +.P .\" Background: inode attributes are modified with i_mutex held, but .\" read by stat() without taking the mutex. .IR Note : @@ -135,7 +135,7 @@ which can still provide exactly the behavior of each of .BR lstat (), and .BR fstat (). -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -147,7 +147,7 @@ the calling process, as is done by and .BR lstat () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -161,13 +161,13 @@ directory of the calling process (like .BR stat () and .BR lstat ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P .I flags can either be 0, or include one or more of the following flags ORed: .TP @@ -214,7 +214,7 @@ instead return information about the link itself, like .BR fstatat () dereferences symbolic links, like .BR stat ().) -.PP +.P See .BR openat (2) for an explanation of the need for @@ -329,7 +329,7 @@ SVr4, 4.3BSD, POSIX.1-2001. POSIX.1-2008. Linux 2.6.16, glibc 2.4. -.PP +.P According to POSIX.1-2001, .BR lstat () on a symbolic link need return valid information only in the @@ -343,7 +343,7 @@ POSIX.1-2008 tightens the specification, requiring .BR lstat () to return valid information in all fields except the mode bits in .IR st_mode . -.PP +.P Use of the .I st_blocks and @@ -377,7 +377,7 @@ Similar remarks apply for .BR fstat () and .BR lstat (). -.PP +.P The kernel-internal versions of the .I stat structure dealt with by the different versions are, respectively: @@ -404,7 +404,7 @@ and various other enlarged fields and further padding in the structure. (Various padding bytes were eventually consumed in Linux 2.6, with the advent of 32-bit device IDs and nanosecond components for the timestamp fields.) -.PP +.P The glibc .BR stat () wrapper function hides these details from applications, @@ -438,13 +438,13 @@ and repacking the returned information if required for old binaries. .\" interface, rather than the libc-kernel interface. .\" .\" (Note that the details depend on gcc being used as c compiler.) -.PP +.P On modern 64-bit systems, life is simpler: there is a single .BR stat () system call and the kernel deals with a .I stat structure that contains fields of a sufficient size. -.PP +.P The underlying system call employed by the glibc .BR fstatat () wrapper function is actually called @@ -458,7 +458,7 @@ The following program calls and displays selected fields in the returned .I stat structure. -.PP +.P .\" SRC BEGIN (stat.c) .EX #include <stdint.h> diff --git a/man2/statfs.2 b/man2/statfs.2 index 26dad7c..df633ae 100644 --- a/man2/statfs.2 +++ b/man2/statfs.2 @@ -5,7 +5,7 @@ .\" Modified 2003-08-17 by Walter Harms .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH statfs 2 2023-07-18 "Linux man-pages 6.05.01" +.TH statfs 2 2023-10-31 "Linux man-pages 6.7" .SH NAME statfs, fstatfs \- get filesystem statistics .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .SH SYNOPSIS .nf .BR "#include <sys/vfs.h> " "/* or <sys/statfs.h> */" -.PP +.P .BI "int statfs(const char *" path ", struct statfs *" buf ); .BI "int fstatfs(int " fd ", struct statfs *" buf ); .fi -.PP +.P Unless you need the .I f_type field, you should use the standard @@ -34,7 +34,7 @@ is the pathname of any file within the mounted filesystem. is a pointer to a .I statfs structure defined approximately as follows: -.PP +.P .in +4n .EX struct statfs { @@ -56,10 +56,10 @@ struct statfs { }; .EE .in -.PP +.P The following filesystem types may appear in .IR f_type : -.PP +.P .in +4n .EX ADFS_SUPER_MAGIC 0xadf5 @@ -150,11 +150,11 @@ XFS_SUPER_MAGIC 0x58465342 _XIAFS_SUPER_MAGIC 0x012fd16d /* Linux 2.0 and earlier */ .EE .in -.PP +.P Most of these MAGIC constants are defined in .IR /usr/include/linux/magic.h , and some are hardcoded in kernel sources. -.PP +.P The .I f_flags field is a bit mask indicating mount options for the filesystem. @@ -201,13 +201,13 @@ in .\" dab741e0e02bd3c4f5e2e97be74b39df2523fc6e Symbolic links are not followed when resolving paths; see .BR mount (2). -.PP +.P Nobody knows what .I f_fsid is supposed to contain (but see below). -.PP +.P Fields that are undefined for a particular filesystem are set to 0. -.PP +.P .BR fstatfs () returns the same information about an open file referenced by descriptor .IR fd . @@ -299,7 +299,7 @@ is defined as .IR "struct { int val[2]; }" . The same holds for FreeBSD, except that it uses the include file .IR <sys/mount.h> . -.PP +.P The general idea is that .I f_fsid contains some random stuff such that the pair @@ -312,7 +312,7 @@ Several operating systems restrict giving out the field to the superuser only (and zero it for unprivileged users), because this field is used in the filehandle of the filesystem when NFS-exported, and giving it out is a security concern. -.PP +.P Under some operating systems, the .I fsid can be used as the second argument to the @@ -325,7 +325,7 @@ The Linux .BR statfs () was inspired by the 4.4BSD one (but they do not use the same structure). -.PP +.P The original Linux .BR statfs () and @@ -347,7 +347,7 @@ The glibc and .BR fstatfs () wrapper functions transparently deal with the kernel differences. -.PP +.P LSB has deprecated the library calls .BR statfs () and @@ -369,7 +369,7 @@ or compare these fields to local variables in a program. Using .I "unsigned\ int" for such variables suffices on most systems. -.PP +.P Some systems have only \fI<sys/vfs.h>\fP, other systems also have \fI<sys/statfs.h>\fP, where the former includes the latter. So it seems diff --git a/man2/statx.2 b/man2/statx.2 index d7c36b8..ce79da2 100644 --- a/man2/statx.2 +++ b/man2/statx.2 @@ -8,7 +8,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH statx 2 2023-06-01 "Linux man-pages 6.05.01" +.TH statx 2 2023-10-31 "Linux man-pages 6.7" .SH NAME statx \- get file status (extended) .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */" .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" .B #include <sys/stat.h> -.PP +.P .BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags , .BI " unsigned int " mask ", struct statx *restrict " statxbuf ); .fi @@ -28,7 +28,7 @@ This function returns information about a file, storing it in the buffer pointed to by .IR statxbuf . The returned buffer is a structure of the following type: -.PP +.P .in +4n .EX struct statx { @@ -71,9 +71,9 @@ struct statx { }; .EE .in -.PP +.P The file timestamps are structures of the following type: -.PP +.P .in +4n .EX struct statx_timestamp { @@ -82,7 +82,7 @@ struct statx_timestamp { }; .EE .in -.PP +.P (Note that reserved space and padding is omitted.) .SS Invoking \fBstatx\fR(): @@ -93,7 +93,7 @@ with a pathname, execute (search) permission is required on all of the directories in .I pathname that lead to the file. -.PP +.P .BR statx () uses .IR pathname , @@ -147,7 +147,7 @@ flag is specified in (see below), then the target file is the one referred to by the file descriptor .IR dirfd . -.PP +.P .I flags can be used to influence a pathname-based lookup. A value for @@ -202,7 +202,7 @@ If is a symbolic link, do not dereference it: instead return information about the link itself, like .BR lstat (2). -.PP +.P .I flags can also be used to control what sort of synchronization the kernel will do when querying a file on a remote filesystem. @@ -225,7 +225,7 @@ the system has cached if possible. This may mean that the information returned is approximate, but, on a network filesystem, it may not involve a round trip to the server - even if no lease is held. -.PP +.P The .I mask argument to @@ -233,7 +233,7 @@ argument to is used to tell the kernel which fields the caller is interested in. .I mask is an ORed combination of the following constants: -.PP +.P .in +4n .TS lB l. @@ -257,7 +257,7 @@ STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align (since Linux 6.1; support varies by filesystem) .TE .in -.PP +.P Note that, in general, the kernel does .I not reject values in @@ -293,7 +293,7 @@ has the same format as the .I mask argument and bits are set in it to indicate which fields have been filled in. -.PP +.P It should be noted that the kernel may return fields that weren't requested and may fail to return fields that were requested, depending on what the backing filesystem supports. @@ -302,7 +302,7 @@ In either case, .I stx_mask will not be equal .IR mask . -.PP +.P If a filesystem does not support a field or if it has an unrepresentable value (for instance, a file with an exotic type), then the mask bit corresponding to that field will be cleared in @@ -310,12 +310,12 @@ then the mask bit corresponding to that field will be cleared in even if the user asked for it and a dummy value will be filled in for compatibility purposes if one is available (e.g., a dummy UID and GID may be specified to mount under some circumstances). -.PP +.P A filesystem may also fill in fields that the caller didn't ask for if it has values for them available and the information is available at no extra cost. If this happens, the corresponding bits will be set in .IR stx_mask . -.PP +.P .\" Background: inode attributes are modified with i_mutex held, but .\" read by stat() without taking the mutex. .IR Note : @@ -340,7 +340,7 @@ or the old .I stx_uid together with the new .IR stx_mode . -.PP +.P Apart from .I stx_mask (which is described above), the fields in the @@ -439,7 +439,7 @@ or 0 if direct I/O is not supported on this file. This will only be nonzero if .I stx_dio_mem_align is nonzero, and vice versa. -.PP +.P For further information on the above fields, see .BR inode (7). .\" @@ -455,7 +455,7 @@ The bits in .I stx_attributes_mask correspond bit-by-bit to .IR stx_attributes . -.PP +.P The flags are as follows: .TP .B STATX_ATTR_COMPRESSED diff --git a/man2/stime.2 b/man2/stime.2 index e4d1a38..1337889 100644 --- a/man2/stime.2 +++ b/man2/stime.2 @@ -7,21 +7,21 @@ .\" Modified 2001-03-16 by Andries Brouwer <aeb@cwi.nl> .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH stime 2 2023-03-30 "Linux man-pages 6.05.01" +.TH stime 2 2023-10-31 "Linux man-pages 6.7" .SH NAME stime \- set time .SH SYNOPSIS .nf .B #include <time.h> -.PP +.P .BI "[[deprecated]] int stime(const time_t *" t ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR stime (): .nf Since glibc 2.19: @@ -35,7 +35,7 @@ This function is deprecated; use .BR clock_settime (2) instead. -.PP +.P .BR stime () sets the system's idea of the time and date. The time, pointed @@ -62,7 +62,7 @@ privilege is required. None. .SH HISTORY SVr4. -.PP +.P Starting with glibc 2.31, this function is no longer available to newly linked applications and is no longer declared in diff --git a/man2/subpage_prot.2 b/man2/subpage_prot.2 index 4309a7d..aaeb883 100644 --- a/man2/subpage_prot.2 +++ b/man2/subpage_prot.2 @@ -7,7 +7,7 @@ .\" in Linux commit fa28237cfcc5827553044cbd6ee52e33692b0faa .\" both written by Paul Mackerras <paulus@samba.org> .\" -.TH subpage_prot 2 2023-03-30 "Linux man-pages 6.05.01" +.TH subpage_prot 2 2023-10-31 "Linux man-pages 6.7" .SH NAME subpage_prot \- define a subpage protection for an address range .SH LIBRARY @@ -17,11 +17,11 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_subpage_prot, unsigned long " addr ", unsigned long " len , .BI " uint32_t *" map ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR subpage_prot (), @@ -33,14 +33,14 @@ The PowerPC-specific system call provides the facility to control the access permissions on individual 4\ kB subpages on systems configured with a page size of 64\ kB. -.PP +.P The protection map is applied to the memory pages in the region starting at .I addr and continuing for .I len bytes. Both of these arguments must be aligned to a 64-kB boundary. -.PP +.P The protection map is specified in the buffer pointed to by .IR map . The map has 2 bits per 4\ kB subpage; @@ -80,7 +80,7 @@ Out of memory. Linux. .SH HISTORY Linux 2.6.25 (PowerPC). -.PP +.P The system call is provided only if the kernel is configured with .BR CONFIG_PPC_64K_PAGES . .SH NOTES @@ -113,6 +113,6 @@ hardware pages (on machines with hardware 64-kB page support). .SH SEE ALSO .BR mprotect (2), .BR syscall (2) -.PP +.P .I Documentation/admin\-guide/mm/hugetlbpage.rst in the Linux kernel source tree diff --git a/man2/swapon.2 b/man2/swapon.2 index 400f609..87bd6a0 100644 --- a/man2/swapon.2 +++ b/man2/swapon.2 @@ -22,7 +22,7 @@ .\" Author: Rafael Aquini <aquini@redhat.com> .\" Date: Wed Jul 3 15:02:46 2013 -0700 .\" -.TH swapon 2 2023-03-30 "Linux man-pages 6.05.01" +.TH swapon 2 2023-12-22 "Linux man-pages 6.7" .SH NAME swapon, swapoff \- start/stop swapping to file/device .SH LIBRARY @@ -31,7 +31,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/swap.h> -.PP +.P .BI "int swapon(const char *" path ", int " swapflags ); .BI "int swapoff(const char *" path ); .fi @@ -42,7 +42,7 @@ sets the swap area to the file or block device specified by .BR swapoff () stops swapping to the file or block device specified by .IR path . -.PP +.P If the .B SWAP_FLAG_PREFER flag is specified in the @@ -52,13 +52,13 @@ argument, the new swap area will have a higher priority than default. The priority is encoded within .I swapflags as: -.PP +.P .in +4n .EX .I "(prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK" .EE .in -.PP +.P If the .B SWAP_FLAG_DISCARD flag is specified in the @@ -69,7 +69,7 @@ if the swap device supports the discard or trim operation. (This may improve performance on some Solid State Devices, but often it does not.) See also NOTES. -.PP +.P These functions may be used only by a privileged process (one having the .B CAP_SYS_ADMIN capability). @@ -78,13 +78,13 @@ Each swap area has a priority, either high or low. The default priority is low. Within the low-priority areas, newer areas are even lower priority than older areas. -.PP +.P All priorities set with .I swapflags are high-priority, higher than default. They may have any nonnegative value chosen by the caller. Higher numbers mean higher priority. -.PP +.P Swap pages are allocated from areas in priority order, highest priority first. For areas with different priorities, @@ -92,7 +92,7 @@ a higher-priority area is exhausted before using a lower-priority area. If two or more areas have the same priority, and it is the highest priority available, pages are allocated on a round-robin basis between them. -.PP +.P As of Linux 1.3.6, the kernel usually follows these rules, but there are exceptions. .SH RETURN VALUE @@ -156,7 +156,7 @@ argument was introduced in Linux 1.3.2. .SH NOTES The partition or path must be prepared with .BR mkswap (8). -.PP +.P There is an upper limit on the number of swap files that may be used, defined by the kernel constant .BR MAX_SWAPFILES . @@ -164,7 +164,8 @@ Before Linux 2.4.10, .B MAX_SWAPFILES has the value 8; since Linux 2.4.10, it has the value 32. -Since Linux 2.6.18, the limit is decreased by 2 (thus: 30) +Since Linux 2.6.18, the limit is decreased by 2 (thus 30), +since Linux 5.19, the limit is decreased by 3 (thus: 29) if the kernel is built with the .B CONFIG_MIGRATION option @@ -180,7 +181,11 @@ Since Linux 5.14, the limit is further decreased by 4 if the kernel is built with the .B CONFIG_DEVICE_PRIVATE option. -.PP +Since Linux 5.19, the limit is further decreased by 1 +if the kernel is built with the +.B CONFIG_PTE_MARKER +option. +.P Discard of swap pages was introduced in Linux 2.6.29, then made conditional on the diff --git a/man2/symlink.2 b/man2/symlink.2 index dd87f2d..37db3c8 100644 --- a/man2/symlink.2 +++ b/man2/symlink.2 @@ -10,7 +10,7 @@ .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH symlink 2 2023-03-30 "Linux man-pages 6.05.01" +.TH symlink 2 2023-10-31 "Linux man-pages 6.7" .SH NAME symlink, symlinkat \- make a new name for a file .SH LIBRARY @@ -19,28 +19,28 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int symlink(const char *" target ", const char *" linkpath ); -.PP +.P .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int symlinkat(const char *" target ", int " newdirfd \ ", const char *" linkpath ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR symlink (): .nf _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR symlinkat (): .nf Since glibc 2.10: @@ -54,20 +54,20 @@ creates a symbolic link named .I linkpath which contains the string .IR target . -.PP +.P Symbolic links are interpreted at run time as if the contents of the link had been substituted into the path being followed to find a file or directory. -.PP +.P Symbolic links may contain .I .. path components, which (if used at the start of the link) refer to the parent directories of that in which the link resides. -.PP +.P A symbolic link (also known as a soft link) may point to an existing file or to a nonexistent one; the latter case is known as a dangling link. -.PP +.P The permissions of a symbolic link are irrelevant; the ownership is ignored when following the link (except when the @@ -79,7 +79,7 @@ renaming of the link is requested and the link is in a directory with the sticky bit .RB ( S_ISVTX ) set. -.PP +.P If .I linkpath exists, it will @@ -91,7 +91,7 @@ The system call operates in exactly the same way as .BR symlink (), except for the differences described here. -.PP +.P If the pathname given in .I linkpath is relative, then it is interpreted relative to the directory @@ -101,7 +101,7 @@ referred to by the file descriptor the calling process, as is done by .BR symlink () for a relative pathname). -.PP +.P If .I linkpath is relative and @@ -113,13 +113,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR symlink ()). -.PP +.P If .I linkpath is absolute, then .I newdirfd is ignored. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -246,7 +246,7 @@ argument. No checking of .I target is done. -.PP +.P Deleting the name referred to by a symbolic link will actually delete the file (unless it also has other hard links). If this behavior is not desired, use diff --git a/man2/sync.2 b/man2/sync.2 index 21f01d7..a556c8e 100644 --- a/man2/sync.2 +++ b/man2/sync.2 @@ -13,7 +13,7 @@ .\" Modified 2001-10-10 by aeb, following Michael Kerrisk. .\" 2011-09-07, mtk, Added syncfs() documentation, .\" -.TH sync 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sync 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sync, syncfs \- commit filesystem caches to disk .SH LIBRARY @@ -22,17 +22,17 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B void sync(void); -.PP +.P .BI "int syncfs(int " fd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sync (): .nf _XOPEN_SOURCE >= 500 @@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR syncfs (): .nf _GNU_SOURCE @@ -49,7 +49,7 @@ Feature Test Macro Requirements for glibc (see .BR sync () causes all pending modifications to filesystem metadata and cached file data to be written to the underlying filesystems. -.PP +.P .BR syncfs () is like .BR sync (), @@ -65,7 +65,7 @@ to indicate the error. .SH ERRORS .BR sync () is always successful. -.PP +.P .BR syncfs () can fail for at least the following reasons: .TP @@ -81,7 +81,9 @@ metadata related to the filesystem itself. .B ENOSPC Disk space was exhausted while synchronizing. .TP -.BR ENOSPC ", " EDQUOT +.B ENOSPC +.TQ +.B EDQUOT Data was written to a file on NFS or another filesystem which does not allocate space at the time of a .BR write (2) @@ -116,7 +118,7 @@ POSIX.1-2001, SVr4, 4.3BSD. .BR syncfs () Linux 2.6.39, glibc 2.14. -.PP +.P Since glibc 2.2.2, the Linux prototype for .BR sync () is as listed above, @@ -125,7 +127,7 @@ In glibc 2.2.1 and earlier, it was "int sync(void)", and .BR sync () always returned 0. -.PP +.P In mainline kernel versions prior to Linux 5.8, .BR syncfs () will fail only when passed a bad file descriptor diff --git a/man2/sync_file_range.2 b/man2/sync_file_range.2 index f324f75..becef29 100644 --- a/man2/sync_file_range.2 +++ b/man2/sync_file_range.2 @@ -7,7 +7,7 @@ .\" Andrew Morton's comments in fs/sync.c .\" 2010-10-09, mtk, Document sync_file_range2() .\" -.TH sync_file_range 2 2023-07-15 "Linux man-pages 6.05.01" +.TH sync_file_range 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sync_file_range \- sync a file segment with disk .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #define _FILE_OFFSET_BITS 64 .B #include <fcntl.h> -.PP +.P .BI "int sync_file_range(int " fd ", off_t " offset ", off_t " nbytes , .BI " unsigned int " flags ); .fi @@ -28,7 +28,7 @@ permits fine control when synchronizing the open file referred to by the file descriptor .I fd with disk. -.PP +.P .I offset is the starting byte of the file range to be synchronized. .I nbytes @@ -42,7 +42,7 @@ Synchronization is in units of the system page size: is rounded down to a page boundary; .I (offset+nbytes\-1) is rounded up to a page boundary. -.PP +.P The .I flags bit-mask argument can include any of the following values: @@ -61,7 +61,7 @@ write more than request queue size. .B SYNC_FILE_RANGE_WAIT_AFTER Wait upon write-out of all pages in the range after performing any write. -.PP +.P Specifying .I flags as 0 is permitted, as a no-op. @@ -89,7 +89,7 @@ will detect any I/O errors or .B ENOSPC conditions and will return these to the caller. -.PP +.P Useful combinations of the .I flags bits are: @@ -173,14 +173,14 @@ arguments. for details.) Therefore, these architectures define a different system call that orders the arguments suitably: -.PP +.P .in +4n .EX .BI "int sync_file_range2(int " fd ", unsigned int " flags , .BI " off_t " offset ", off_t " nbytes ); .EE .in -.PP +.P The behavior of this system call is otherwise exactly the same as .BR sync_file_range (). .SH STANDARDS diff --git a/man2/syscall.2 b/man2/syscall.2 index 43f054a..01229e8 100644 --- a/man2/syscall.2 +++ b/man2/syscall.2 @@ -12,7 +12,7 @@ .\" 2015-01-17, Kees Cook <keescook@chromium.org> .\" Added mips and arm64. .\" -.TH syscall 2 2023-05-03 "Linux man-pages 6.05.01" +.TH syscall 2 2023-10-31 "Linux man-pages 6.7" .SH NAME syscall \- indirect system call .SH LIBRARY @@ -22,15 +22,15 @@ Standard C library .nf .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(long " number ", ...);" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR syscall (): .nf Since glibc 2.19: @@ -49,13 +49,13 @@ Employing .BR syscall () is useful, for example, when invoking a system call that has no wrapper function in the C library. -.PP +.P .BR syscall () saves CPU registers before making the system call, restores the registers upon return from the system call, and stores any error returned by the system call in .BR errno (3). -.PP +.P Symbolic constants for system call numbers can be found in the header file .IR <sys/syscall.h> . .SH RETURN VALUE @@ -68,7 +68,7 @@ and an error number is stored in .TP .B ENOSYS The requested system call number is not implemented. -.PP +.P Other errors are specific to the invoked system call. .SH NOTES .BR syscall () @@ -85,7 +85,7 @@ However, when using to make a system call, the caller might need to handle architecture-dependent details; this requirement is most commonly encountered on certain 32-bit architectures. -.PP +.P For example, on the ARM architecture Embedded ABI (EABI), a 64-bit value (e.g., .IR "long long" ) @@ -97,7 +97,7 @@ the .BR readahead (2) system call would be invoked as follows on the ARM architecture with the EABI in little endian mode: -.PP +.P .in +4n .EX syscall(SYS_readahead, fd, 0, @@ -106,7 +106,7 @@ syscall(SYS_readahead, fd, 0, count); .EE .in -.PP +.P Since the offset argument is 64 bits, and the first argument .RI ( fd ) is passed in @@ -120,16 +120,16 @@ That means inserting a dummy value into (the second argument of 0). Care also must be taken so that the split follows endian conventions (according to the C ABI for the platform). -.PP +.P Similar issues can occur on MIPS with the O32 ABI, on PowerPC and parisc with the 32-bit ABI, and on Xtensa. .\" Mike Frysinger: this issue ends up forcing MIPS .\" O32 to take 7 arguments to syscall() -.PP +.P .\" See arch/parisc/kernel/sys_parisc.c. Note that while the parisc C ABI also uses aligned register pairs, it uses a shim layer to hide the issue from user space. -.PP +.P The affected system calls are .BR fadvise64_64 (2), .BR ftruncate64 (2), @@ -140,7 +140,7 @@ The affected system calls are .BR sync_file_range (2), and .BR truncate64 (2). -.PP +.P .\" You need to look up the syscalls directly in the kernel source to see if .\" they should be in this list. For example, look at fs/read_write.c and .\" the function signatures that do: @@ -159,7 +159,7 @@ Welcome to the wonderful world of historical baggage. Every architecture has its own way of invoking and passing arguments to the kernel. The details for various architectures are listed in the two tables below. -.PP +.P The first table lists the instruction used to transition to kernel mode (which might not be the fastest or best way to transition to the kernel, so you might have to refer to @@ -202,7 +202,7 @@ x86-64 syscall rax rax rdx - 5 x32 syscall rax rax rdx - 5 xtensa syscall a2 a2 - - .TE -.PP +.P Notes: .IP \[bu] 3 On a few architectures, @@ -292,7 +292,7 @@ in the system call interface, even if it is defined in the System V ABI. .in .ft P \} -.PP +.P The second table shows the registers used to pass the system call arguments. .if t \{\ .ft CW @@ -329,7 +329,7 @@ x86-64 rdi rsi rdx r10 r8 r9 - x32 rdi rsi rdx r10 r8 r9 - xtensa a6 a3 a4 a5 a8 a9 - .TE -.PP +.P Notes: .IP \[bu] 3 The mips/o32 system call convention passes @@ -338,7 +338,7 @@ arguments 5 through 8 on the user stack. .in .ft P \} -.PP +.P Note that these tables don't cover the entire calling convention\[em]some architectures may indiscriminately clobber other registers not listed here. .SH EXAMPLES diff --git a/man2/syscalls.2 b/man2/syscalls.2 index 1011c14..09535aa 100644 --- a/man2/syscalls.2 +++ b/man2/syscalls.2 @@ -9,7 +9,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH syscalls 2 2023-07-30 "Linux man-pages 6.05.01" +.TH syscalls 2 2024-02-18 "Linux man-pages 6.7" .SH NAME syscalls \- Linux system calls .SH SYNOPSIS @@ -29,7 +29,7 @@ as the name of the system call that it invokes. For example, glibc contains a function .BR chdir () which invokes the underlying "chdir" system call. -.PP +.P Often the glibc wrapper function is quite thin, doing little work other than copying arguments to the right registers before invoking the system call, @@ -49,7 +49,7 @@ the wrapper function negates the returned error number (to make it positive), copies it to .IR errno , and returns \-1 to the caller of the wrapper. -.PP +.P Sometimes, however, the wrapper function does some extra work before invoking the system call. For example, nowadays there are (for reasons described below) two @@ -76,8 +76,8 @@ the system call appeared in Linux 1.0 or earlier. Where a system call is marked "1.2" this means the system call probably appeared in a Linux 1.1.x kernel version, and first appeared in a stable kernel with 1.2. -(Development of the 1.2 kernel was initiated from a branch of kernel -1.0.6 via the 1.1.x unstable kernel series.) +(Development of the Linux 1.2 kernel was initiated from a branch of +Linux 1.0.6 via the Linux 1.1.x unstable kernel series.) .IP \[bu] Where a system call is marked "2.0" this means the system call probably appeared in a Linux 1.3.x kernel version, @@ -98,7 +98,7 @@ via the Linux 1.3.x unstable kernel series.) Where a system call is marked "2.2" this means the system call probably appeared in a Linux 2.1.x kernel version, and first appeared in a stable kernel with Linux 2.2.0. -(Development of the Linux 2.2 kernel was initiated from a branch of kernel +(Development of the Linux 2.2 kernel was initiated from a branch of Linux 2.0.21 via the Linux 2.1.x unstable kernel series.) .IP \[bu] Where a system call is marked "2.4" @@ -120,7 +120,8 @@ is shown. This convention continues with the Linux 3.x kernel series, which followed on from Linux 2.6.39; and the Linux 4.x kernel series, which followed on from Linux 3.19; and the Linux 5.x kernel series, -which followed on from Linux 4.20. +which followed on from Linux 4.20; and the Linux 6.x kernel series, +which followed on from Linux 5.19. .IP \[bu] In some cases, a system call was added to a stable kernel series after it branched from the previous stable kernel @@ -129,19 +130,19 @@ For example some system calls that appeared in Linux 2.6.x were also backported into a Linux 2.4.x release after Linux 2.4.15. When this is so, the version where the system call appeared in both of the major kernel series is listed. -.PP +.P The list of system calls that are available as at Linux 5.14 (or in a few cases only on older kernels) is as follows: +.P .\" .\" Looking at scripts/checksyscalls.sh in the kernel source is .\" instructive about x86 specifics. .\" .TS -l2 le l ---- -l l l. -\fBSystem call\fP \fBKernel\fP \fBNotes\fP - +Lb Lb Lb +L2 L L. +System call Kernel Notes +_ \fB_llseek\fP(2) 1.2 \fB_newselect\fP(2) 2.0 \fB_sysctl\fP(2) 2.0 Removed in 5.5 @@ -832,13 +833,13 @@ T} .\" 5a0015d62668e64c8b6e02e360fbbea121bfd5e6 \fBxtensa\fP(2) 2.6.13 Xtensa only .TE -.PP +.P On many platforms, including x86-32, socket calls are all multiplexed (via glibc wrapper functions) through .BR socketcall (2) and similarly System\ V IPC calls are multiplexed through .BR ipc (2). -.PP +.P Although slots are reserved for them in the system call table, the following system calls are not implemented in the standard kernel: .BR afs_syscall (2), \" __NR_afs_syscall is 53 on Linux 2.6.22/i386 @@ -883,7 +884,7 @@ and .BR putpmsg (2) calls are for kernels patched to support STREAMS, and may never be in the standard kernel. -.PP +.P There was briefly .BR set_zone_reclaim (2), added in Linux 2.6.13, and removed in Linux 2.6.16; @@ -967,7 +968,7 @@ proprietary operating-system emulation, such as sparc, sparc64, and alpha, there are many additional system calls; mips64 also contains a full set of 32-bit system calls. -.PP +.P Over time, changes to the interfaces of some system calls have been necessary. One reason for such changes was the need to increase the size of @@ -984,7 +985,7 @@ details such as the size of their arguments. the glibc wrapper functions do some work to ensure that the right system call is invoked, and that ABI compatibility is preserved for old binaries.) -Examples of systems calls that exist in multiple versions are +Examples of system calls that exist in multiple versions are the following: .IP \[bu] 3 By now there are three different versions of @@ -1111,7 +1112,7 @@ and similarly .IR __NR_mmap2 . s390x is the only 64-bit architecture that has .IR old_mmap (). -.\" .PP +.\" .P .\" Two system call numbers, .\" .IR __NR__llseek .\" and diff --git a/man2/sysctl.2 b/man2/sysctl.2 index fbe967f..082545e 100644 --- a/man2/sysctl.2 +++ b/man2/sysctl.2 @@ -7,27 +7,27 @@ .\" Modified Tue Oct 22 22:28:41 1996 by Eric S. Raymond <esr@thyrsus.com> .\" Modified Mon Jan 5 20:31:04 1998 by aeb. .\" -.TH sysctl 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sysctl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sysctl \- read/write system parameters .SH SYNOPSIS .nf .B #include <unistd.h> .B #include <linux/sysctl.h> -.PP +.P .BI "[[deprecated]] int _sysctl(struct __sysctl_args *" args ); .fi .SH DESCRIPTION .B This system call no longer exists on current kernels! See NOTES. -.PP +.P The .BR _sysctl () call reads and/or writes kernel parameters. For example, the hostname, or the maximum number of open files. The argument has the form -.PP +.P .in +4n .EX struct __sysctl_args { @@ -41,7 +41,7 @@ struct __sysctl_args { }; .EE .in -.PP +.P This call does a search in a tree structure, possibly resembling a directory tree under .IR /proc/sys , @@ -56,7 +56,9 @@ Otherwise, a value of \-1 is returned and is set to indicate the error. .SH ERRORS .TP -.BR EACCES ", " EPERM +.B EACCES +.TQ +.B EPERM No search permission for one of the encountered "directories", or no read permission where .I oldval @@ -78,7 +80,7 @@ Linux. .SH HISTORY Linux 1.3.57. Removed in Linux 5.5, glibc 2.32. -.PP +.P It originated in 4.4BSD. Only Linux has the @@ -95,7 +97,7 @@ and in Linux 5.5, the system call was finally removed. Use the .I /proc/sys interface instead. -.PP +.P Note that on older kernels where this system call still exists, it is available only if the kernel was configured with the .B CONFIG_SYSCTL_SYSCALL @@ -106,9 +108,9 @@ necessitating the use of .SH BUGS The object names vary between kernel versions, making this system call worthless for applications. -.PP +.P Not all available objects are properly documented. -.PP +.P It is not yet possible to change operating system by writing to .IR /proc/sys/kernel/ostype . .SH EXAMPLES diff --git a/man2/sysfs.2 b/man2/sysfs.2 index d650a9c..06507fd 100644 --- a/man2/sysfs.2 +++ b/man2/sysfs.2 @@ -4,7 +4,7 @@ .\" .\" Created Wed Aug 9 1995 Thomas K. Dyas <tdyas@eden.rutgers.edu> .\" -.TH sysfs 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sysfs 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sysfs \- get filesystem type information .SH SYNOPSIS @@ -21,7 +21,7 @@ filesystem that is normally mounted at .IR /sys , see .BR sysfs (5). -.PP +.P The (obsolete) .BR sysfs () system call returns information about the filesystem types @@ -51,7 +51,7 @@ has enough space to accept the string. .B 3 Return the total number of filesystem types currently present in the kernel. -.PP +.P The numbering of the filesystem type indexes begins with zero. .SH RETURN VALUE On success, @@ -82,7 +82,7 @@ is invalid. None. .SH HISTORY SVr4. -.PP +.P This System-V derived system call is obsolete; don't use it. On systems with .IR /proc , diff --git a/man2/sysinfo.2 b/man2/sysinfo.2 index fc44136..5566b4b 100644 --- a/man2/sysinfo.2 +++ b/man2/sysinfo.2 @@ -12,7 +12,7 @@ .\" Modified Tue Oct 22 22:29:51 1996 by Eric S. Raymond <esr@thyrsus.com> .\" Modified Mon Aug 25 16:06:11 1997 by Nicolás Lichtmaier <nick@debian.org> .\" -.TH sysinfo 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sysinfo 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sysinfo \- return system information .SH LIBRARY @@ -21,18 +21,18 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/sysinfo.h> -.PP +.P .BI "int sysinfo(struct sysinfo *" info ); .fi .SH DESCRIPTION .BR sysinfo () returns certain statistics on memory and swap usage, as well as the load average. -.PP +.P Until Linux 2.3.16, .BR sysinfo () returned information in the following structure: -.PP +.P .in +4n .EX struct sysinfo { @@ -49,13 +49,13 @@ struct sysinfo { }; .EE .in -.PP +.P In the above structure, the sizes of the memory and swap fields are given in bytes. -.PP +.P Since Linux 2.3.23 (i386) and Linux 2.3.48 (all architectures) the structure is: -.PP +.P .in +4n .EX struct sysinfo { @@ -76,7 +76,7 @@ struct sysinfo { }; .EE .in -.PP +.P In the above structure, sizes of the memory and swap fields are given as multiples of .I mem_unit diff --git a/man2/syslog.2 b/man2/syslog.2 index 4e90778..a799c82 100644 --- a/man2/syslog.2 +++ b/man2/syslog.2 @@ -10,7 +10,7 @@ .\" 2008-02-15, Michael Kerrisk <mtk.manpages@gmail.com> .\" Update LOG_BUF_LEN details; update RETURN VALUE section. .\" -.TH syslog 2 2023-03-30 "Linux man-pages 6.05.01" +.TH syslog 2 2023-10-31 "Linux man-pages 6.7" .SH NAME syslog, klogctl \- read and/or clear kernel message ring buffer; set console_loglevel @@ -22,12 +22,12 @@ Standard C library .BR "#include <sys/klog.h>" " /* Definition of " SYSLOG_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_syslog, int " type ", char *" bufp ", int " len ); -.PP +.P /* The glibc interface */ .B #include <sys/klog.h> -.PP +.P .BI "int klogctl(int " type ", char *" bufp ", int " len ); .fi .SH DESCRIPTION @@ -39,7 +39,7 @@ which talks to see .BR syslog (3) for details. -.PP +.P This page describes the kernel .BR syslog () system call, which is used to control the kernel @@ -208,7 +208,7 @@ The and .I len arguments are ignored. -.PP +.P All commands except 3 and 10 require privilege. In Linux kernels before Linux 2.6.37, command types 3 and 10 are allowed to unprivileged processes; @@ -300,7 +300,7 @@ T} KERN_INFO 6 Informational KERN_DEBUG 7 Debug-level messages .TE -.sp 1 +.P The kernel .I printk() routine will print a message on the @@ -319,7 +319,7 @@ For \fItype\fP 10, .BR syslog () returns the total size of the kernel log buffer. For other values of \fItype\fP, 0 is returned on success. -.PP +.P In case of error, \-1 is returned, and \fIerrno\fP is set to indicate the error. .SH ERRORS @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH tee 2 2023-05-03 "Linux man-pages 6.05.01" +.TH tee 2 2023-10-31 "Linux man-pages 6.7" .SH NAME tee \- duplicating pipe content .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <fcntl.h> -.PP +.P .BI "ssize_t tee(int " fd_in ", int " fd_out ", size_t " len \ ", unsigned int " flags ); .fi @@ -36,7 +36,7 @@ It does not consume the data that is duplicated from .IR fd_in ; therefore, that data can be copied by a subsequent .BR splice (2). -.PP +.P .I flags is a bit mask that is composed by ORing together zero or more of the following values: @@ -72,7 +72,7 @@ A return value of 0 means that there was no data to transfer, and it would not make sense to block, because there are no writers connected to the write end of the pipe referred to by .IR fd_in . -.PP +.P On error, .BR tee () returns \-1 and @@ -121,7 +121,7 @@ program using the .BR tee () system call. Here is an example of its use: -.PP +.P .in +4n .EX $ \fBdate | ./a.out out.log | cat\fP diff --git a/man2/time.2 b/man2/time.2 index f121e9c..5ac0bc4 100644 --- a/man2/time.2 +++ b/man2/time.2 @@ -6,7 +6,7 @@ .\" Modified Sat Jul 24 14:13:40 1993 by Rik Faith <faith@cs.unc.edu> .\" Additions by Joseph S. Myers <jsm28@cam.ac.uk>, 970909 .\" -.TH time 2 2023-03-30 "Linux man-pages 6.05.01" +.TH time 2 2023-11-11 "Linux man-pages 6.7" .SH NAME time \- get time in seconds .SH LIBRARY @@ -15,14 +15,14 @@ Standard C library .SH SYNOPSIS .nf .B #include <time.h> -.PP +.P .BI "time_t time(time_t *_Nullable " tloc ); .fi .SH DESCRIPTION .BR time () returns the time as the number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P If .I tloc is non-NULL, @@ -35,6 +35,17 @@ On error, \fI((time_t)\ \-1)\fP is returned, and is set to indicate the error. .SH ERRORS .TP +.B EOVERFLOW +The time cannot be represented as a +.I time_t +value. +This can happen if an executable with 32-bit +.I time_t +is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later. +However, when the system time is out of +.I time_t +range in other situations, the behavior is undefined. +.TP .B EFAULT .I tloc points outside your accessible address space (but see BUGS). @@ -60,29 +71,15 @@ in which case they are leap years. This value is not the same as the actual number of seconds between the time and the Epoch, because of leap seconds and because system clocks are not required to be synchronized to a standard reference. -The intention is that the interpretation of seconds since the Epoch values be -consistent; see POSIX.1-2008 Rationale A.4.15 for further rationale. -.PP -On Linux, a call to -.BR time () -with -.I tloc -specified as NULL cannot fail with the error -.BR EOVERFLOW , -even on ABIs where -.I time_t -is a signed 32-bit integer and the clock reaches or exceeds 2**31 seconds -(2038-01-19 03:14:08 UTC, ignoring leap seconds). -(POSIX.1 permits, but does not require, the -.B EOVERFLOW -error in the case where the seconds since the Epoch will not fit in -.IR time_t .) -Instead, the behavior on Linux is undefined when the system time is out of the -.I time_t -range. +Linux systems normally follow the POSIX requirement +that this value ignore leap seconds, +so that conforming systems interpret it consistently; +see POSIX.1-2018 Rationale A.4.16. +.P Applications intended to run after 2038 should use ABIs with .I time_t -wider than 32 bits. +wider than 32 bits; see +.BR time_t (3type). .SS C library/kernel differences On some architectures, an implementation of .BR time () @@ -101,7 +98,7 @@ successful reports that the time is a few seconds the Epoch, so the C library wrapper function never sets .I errno as a result of this call. -.PP +.P The .I tloc argument is obsolescent and should always be NULL in new code. diff --git a/man2/timer_create.2 b/man2/timer_create.2 index 3265b27..44d505d 100644 --- a/man2/timer_create.2 +++ b/man2/timer_create.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH timer_create 2 2023-05-03 "Linux man-pages 6.05.01" +.TH timer_create 2 2023-11-11 "Linux man-pages 6.7" .SH NAME timer_create \- create a POSIX per-process timer .SH LIBRARY @@ -13,17 +13,17 @@ Real-time library .nf .BR "#include <signal.h>" " /* Definition of " SIGEV_* " constants */" .B #include <time.h> -.PP +.P .BI "int timer_create(clockid_t " clockid , .BI " struct sigevent *_Nullable restrict " sevp , .BI " timer_t *restrict " timerid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR timer_create (): .nf _POSIX_C_SOURCE >= 199309L @@ -36,7 +36,7 @@ The ID of the new timer is returned in the buffer pointed to by which must be a non-null pointer. This ID is unique within the process, until the timer is deleted. The new timer is initially disarmed. -.PP +.P The .I clockid argument specifies the clock that the new timer uses to measure time. @@ -96,12 +96,12 @@ The caller must have the capability in order to set a timer against this clock. .TP .BR CLOCK_TAI " (since Linux 3.10)" -A system-wide clock derived from wall-clock time but ignoring leap seconds. -.PP +A system-wide clock derived from wall-clock time but counting leap seconds. +.P See .BR clock_getres (2) for some further details on the above clocks. -.PP +.P As well as the above values, .I clockid can be specified as the @@ -110,7 +110,7 @@ returned by a call to .BR clock_getcpuclockid (3) or .BR pthread_getcpuclockid (3). -.PP +.P The .I sevp argument points to a @@ -118,8 +118,8 @@ argument points to a structure that specifies how the caller should be notified when the timer expires. For the definition and general details of this structure, see -.BR sigevent (7). -.PP +.BR sigevent (3type). +.P The .I sevp.sigev_notify field can have the following values: @@ -134,7 +134,7 @@ Upon timer expiration, generate the signal .I sigev_signo for the process. See -.BR sigevent (7) +.BR sigevent (3type) for general details. The .I si_code @@ -152,7 +152,7 @@ Upon timer expiration, invoke .I sigev_notify_function as if it were the start function of a new thread. See -.BR sigevent (7) +.BR sigevent (3type) for details. .TP .BR SIGEV_THREAD_ID " (Linux-specific)" @@ -168,7 +168,7 @@ field specifies a kernel thread ID, that is, the value returned by or .BR gettid (2). This flag is intended only for use by threading libraries. -.PP +.P Specifying .I sevp as NULL is equivalent to specifying a pointer to a @@ -258,7 +258,7 @@ POSIX.1-2008. .SH HISTORY Linux 2.6. POSIX.1-2001. -.PP +.P Prior to Linux 2.6, glibc provided an incomplete user-space implementation .RB ( CLOCK_REALTIME @@ -270,12 +270,12 @@ running kernels older than Linux 2.6. .SH NOTES A program may create multiple interval timers using .BR timer_create (). -.PP +.P Timers are not inherited by the child of a .BR fork (2), and are disarmed and deleted during an .BR execve (2). -.PP +.P The kernel preallocates a "queued real-time signal" for each timer created using .BR timer_create (). @@ -283,7 +283,7 @@ Consequently, the number of timers is limited by the .B RLIMIT_SIGPENDING resource limit (see .BR setrlimit (2)). -.PP +.P The timers created by .BR timer_create () are commonly known as "POSIX (interval) timers". @@ -304,7 +304,7 @@ Return the overrun count for the last timer expiration. .TP .BR timer_delete (2) Disarm and delete a timer. -.PP +.P Since Linux 3.10, the .IR /proc/ pid /timers file can be used to list the POSIX timers for the process with PID @@ -312,7 +312,7 @@ file can be used to list the POSIX timers for the process with PID See .BR proc (5) for further information. -.PP +.P Since Linux 4.10, .\" baa73d9e478ff32d62f3f9422822b59dd9a95a21 support for POSIX timers is a configurable option that is enabled by default. @@ -331,12 +331,12 @@ Assuming that the timer expired at least once while the program slept, the signal handler will be invoked, and the handler displays some information about the timer notification. The program terminates after one invocation of the signal handler. -.PP +.P In the following example run, the program sleeps for 1 second, after creating a timer that has a frequency of 100 nanoseconds. By the time the signal is unblocked and delivered, there have been around ten million overruns. -.PP +.P .in +4n .EX $ \fB./a.out 1 100\fP @@ -482,6 +482,6 @@ main(int argc, char *argv[]) .BR clock_getcpuclockid (3), .BR pthread_getcpuclockid (3), .BR pthreads (7), -.BR sigevent (7), +.BR sigevent (3type), .BR signal (7), .BR time (7) diff --git a/man2/timer_delete.2 b/man2/timer_delete.2 index ee1468e..b08d736 100644 --- a/man2/timer_delete.2 +++ b/man2/timer_delete.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH timer_delete 2 2023-03-30 "Linux man-pages 6.05.01" +.TH timer_delete 2 2023-10-31 "Linux man-pages 6.7" .SH NAME timer_delete \- delete a POSIX per-process timer .SH LIBRARY @@ -12,15 +12,15 @@ Real-time library .SH SYNOPSIS .nf .B #include <time.h> -.PP +.P .BI "int timer_delete(timer_t " timerid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR timer_delete (): .nf _POSIX_C_SOURCE >= 199309L diff --git a/man2/timer_getoverrun.2 b/man2/timer_getoverrun.2 index 7521957..0f136b6 100644 --- a/man2/timer_getoverrun.2 +++ b/man2/timer_getoverrun.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH timer_getoverrun 2 2023-03-30 "Linux man-pages 6.05.01" +.TH timer_getoverrun 2 2023-10-31 "Linux man-pages 6.7" .SH NAME timer_getoverrun \- get overrun count for a POSIX per-process timer .SH LIBRARY @@ -12,15 +12,15 @@ Real-time library .SH SYNOPSIS .nf .B #include <time.h> -.PP +.P .BI "int timer_getoverrun(timer_t " timerid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR timer_getoverrun (): .nf _POSIX_C_SOURCE >= 199309L @@ -36,7 +36,7 @@ via signals .RB ( SIGEV_SIGNAL ), and via threads .RB ( SIGEV_THREAD ). -.PP +.P When expiration notifications are delivered via a signal, overruns can occur as follows. Regardless of whether or not a real-time signal is used for @@ -56,7 +56,7 @@ In this interval, further timer expirations may occur. The timer overrun count is the number of additional timer expirations that occurred between the time when the signal was generated and when it was delivered or accepted. -.PP +.P Timer overruns can also occur when expiration notifications are delivered via invocation of a thread, since there may be an arbitrary delay between an expiration of the timer @@ -87,7 +87,7 @@ structure (see This allows an application to avoid the overhead of making a system call to obtain the overrun count, but is a nonportable extension to POSIX.1. -.PP +.P POSIX.1 discusses timer overruns only in the context of timer notifications using signals. .\" FIXME . Austin bug filed, 11 Feb 09 diff --git a/man2/timer_settime.2 b/man2/timer_settime.2 index 030bab5..d222fe4 100644 --- a/man2/timer_settime.2 +++ b/man2/timer_settime.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH timer_settime 2 2023-03-30 "Linux man-pages 6.05.01" +.TH timer_settime 2 2023-10-31 "Linux man-pages 6.7" .SH NAME timer_settime, timer_gettime \- arm/disarm and fetch state of POSIX per-process timer @@ -13,18 +13,18 @@ Real-time library .SH SYNOPSIS .nf .B #include <time.h> -.PP +.P .BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value ); .BI "int timer_settime(timer_t " timerid ", int " flags , .BI " const struct itimerspec *restrict " new_value , .BI " struct itimerspec *_Nullable restrict " old_value ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR timer_settime (), .BR timer_gettime (): .nf @@ -44,7 +44,7 @@ The .I itimerspec structure is described in .BR itimerspec (3type). -.PP +.P Each of the substructures of the .I itimerspec structure is a @@ -54,7 +54,7 @@ in seconds and nanoseconds. These time values are measured according to the clock that was specified when the timer was created by .BR timer_create (2). -.PP +.P If .I new_value\->it_value specifies a nonzero value (i.e., either subfield is nonzero), then @@ -68,7 +68,7 @@ If specifies a zero value (i.e., both subfields are zero), then the timer is disarmed. -.PP +.P The .I new_value\->it_interval field specifies the period of the timer, in seconds and nanoseconds. @@ -80,7 +80,7 @@ If specifies a zero value, then the timer expires just once, at the time specified by .IR it_value . -.PP +.P By default, the initial expiration time specified in .I new_value\->it_value is interpreted relative to the current time on the timer's @@ -101,7 +101,7 @@ and the overrun count (see .BR timer_getoverrun (2)) will be set correctly. .\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME. -.PP +.P If the value of the .B CLOCK_REALTIME clock is adjusted while an absolute timer based on that clock is armed, @@ -111,7 +111,7 @@ Adjustments to the clock have no effect on relative timers based on that clock. .\" Similar remarks might apply with respect to process and thread CPU time .\" clocks, but these clocks are not currently (2.6.28) settable on Linux. -.PP +.P If .I old_value is not NULL, then it points to a buffer @@ -120,7 +120,7 @@ that is used to return the previous interval of the timer (in and the amount of time until the timer would previously have next expired (in .IR old_value\->it_value ). -.PP +.P .BR timer_gettime () returns the time until next expiration, and the interval, for the timer specified by @@ -163,7 +163,7 @@ is not a valid pointer. .I timerid is invalid. .\" FIXME . eventually: invalid value in flags -.PP +.P .BR timer_settime () may fail with the following errors: .TP diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2 index 6ceea56..1d6a0d2 100644 --- a/man2/timerfd_create.2 +++ b/man2/timerfd_create.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH timerfd_create 2 2023-05-03 "Linux man-pages 6.05.01" +.TH timerfd_create 2 2023-10-31 "Linux man-pages 6.7" .SH NAME timerfd_create, timerfd_settime, timerfd_gettime \- timers that notify via file descriptors @@ -12,9 +12,9 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/timerfd.h> -.PP +.P .BI "int timerfd_create(int " clockid ", int " flags ); -.PP +.P .BI "int timerfd_settime(int " fd ", int " flags , .BI " const struct itimerspec *" new_value , .BI " struct itimerspec *_Nullable " old_value ); @@ -32,7 +32,7 @@ with the advantage that the file descriptor may be monitored by .BR poll (2), and .BR epoll (7). -.PP +.P The use of these three system calls is analogous to the use of .BR timer_create (2), .BR timer_settime (2), @@ -93,14 +93,14 @@ but will wake the system if it is suspended. The caller must have the .B CAP_WAKE_ALARM capability in order to set a timer against this clock. -.PP +.P See .BR clock_getres (2) for some further details on the above clocks. -.PP +.P The current value of each of these clocks can be retrieved using .BR clock_gettime (2). -.PP +.P Starting with Linux 2.6.27, the following values may be bitwise ORed in .I flags to change the behavior of @@ -125,7 +125,7 @@ See the description of the flag in .BR open (2) for reasons why this may be useful. -.PP +.P In Linux versions up to and including 2.6.26, .I flags must be specified as zero. @@ -134,7 +134,7 @@ must be specified as zero. arms (starts) or disarms (stops) the timer referred to by the file descriptor .IR fd . -.PP +.P The .I new_value argument specifies the initial expiration and interval for the timer. @@ -142,7 +142,7 @@ The .I itimerspec structure used for this argument is described in .BR itimerspec (3type). -.PP +.P .I new_value.it_value specifies the initial expiration of the timer, in seconds and nanoseconds. @@ -152,7 +152,7 @@ to a nonzero value arms the timer. Setting both fields of .I new_value.it_value to zero disarms the timer. -.PP +.P Setting one or both fields of .I new_value.it_interval to nonzero values specifies the period, in seconds and nanoseconds, @@ -161,7 +161,7 @@ If both fields of .I new_value.it_interval are zero, the timer expires just once, at the time specified by .IR new_value.it_value . -.PP +.P By default, the initial expiration time specified in .I new_value @@ -173,7 +173,7 @@ specifies a time relative to the current value of the clock specified by An absolute timeout can be selected via the .I flags argument. -.PP +.P The .I flags argument is a bit mask that can include the following values: @@ -202,7 +202,7 @@ When such changes occur, a current or future .BR read (2) from the file descriptor will fail with the error .BR ECANCELED . -.PP +.P If the .I old_value argument is not NULL, then the @@ -222,7 +222,7 @@ an structure that contains the current setting of the timer referred to by the file descriptor .IR fd . -.PP +.P The .I it_value field returns the amount of time @@ -232,7 +232,7 @@ then the timer is currently disarmed. This field always contains a relative value, regardless of whether the .B TFD_TIMER_ABSTIME flag was specified when setting the timer. -.PP +.P The .I it_interval field returns the interval of the timer. @@ -317,7 +317,11 @@ but before the .BR read (2) on the file descriptor. .TP -.BR poll "(2), " select "(2) (and similar)" +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) The file descriptor is readable (the .BR select (2) @@ -384,7 +388,7 @@ returns a new file descriptor. On error, \-1 is returned and .I errno is set to indicate the error. -.PP +.P .BR timerfd_settime () and .BR timerfd_gettime () @@ -430,7 +434,7 @@ or but the caller did not have the .B CAP_WAKE_ALARM capability. -.PP +.P .BR timerfd_settime () and .BR timerfd_gettime () @@ -450,7 +454,7 @@ is not a valid pointer. .B EINVAL .I fd is not a valid timerfd file descriptor. -.PP +.P .BR timerfd_settime () can also fail with the following errors: .TP @@ -500,7 +504,7 @@ the caller once more calls to rearm the timer (without first doing a .BR read (2) on the file descriptor). -.PP +.P In this case the following occurs: .IP \[bu] 3 The @@ -534,9 +538,9 @@ The second argument specifies the interval for the timer, in seconds. The third argument specifies the number of times the program should allow the timer to expire before terminating. The second and third command-line arguments are optional. -.PP +.P The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX .RB "$" " a.out 3 1 100" diff --git a/man2/times.2 b/man2/times.2 index 1d85010..2dad5b5 100644 --- a/man2/times.2 +++ b/man2/times.2 @@ -15,7 +15,7 @@ .\" Added notes on nonstandard behavior: Linux allows 'buf' to .\" be NULL, but POSIX.1 doesn't specify this and it's nonportable. .\" -.TH times 2 2023-03-30 "Linux man-pages 6.05.01" +.TH times 2 2023-10-31 "Linux man-pages 6.7" .SH NAME times \- get process times .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/times.h> -.PP +.P .BI "clock_t times(struct tms *" buf ); .fi .SH DESCRIPTION @@ -38,7 +38,7 @@ The .I struct tms is as defined in .IR <sys/times.h> : -.PP +.P .in +4n .EX struct tms { @@ -49,7 +49,7 @@ struct tms { }; .EE .in -.PP +.P The .I tms_utime field contains the CPU time spent executing instructions @@ -58,7 +58,7 @@ The .I tms_stime field contains the CPU time spent executing inside the kernel while performing tasks on behalf of the calling process. -.PP +.P The .I tms_cutime field contains the sum of the @@ -73,7 +73,7 @@ field contains the sum of the and .I tms_cstime values for all waited-for terminated children. -.PP +.P Times for terminated children (and their descendants) are added in at the moment .BR wait (2) @@ -83,7 +83,7 @@ returns their process ID. In particular, times of grandchildren that the children did not wait for are never seen. -.PP +.P All times reported are in clock ticks. .SH RETURN VALUE .BR times () @@ -120,12 +120,12 @@ POSIX.1-2008. POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in .IR <time.h> ) is mentioned as obsolescent. It is obsolete now. -.PP +.P Before Linux 2.6.9, if the disposition of .B SIGCHLD @@ -145,7 +145,7 @@ This nonconformance is rectified in Linux 2.6.9 and later. .\" See the description of times() in XSH, which says: .\" The times of a terminated child process are included... when wait() .\" or waitpid() returns the process ID of this terminated child. -.PP +.P On Linux, the \[lq]arbitrary point in the past\[rq] from which the return value of @@ -164,10 +164,10 @@ To measure changes in elapsed time, use .BR clock_gettime (2) instead. -.\" .PP +.\" .P .\" On older systems the number of clock ticks per second is given .\" by the variable HZ. -.PP +.P SVr1-3 returns .I long and the struct members are of type @@ -182,13 +182,13 @@ because it had no type yet. .SH NOTES The number of clock ticks per second can be obtained using: -.PP +.P .in +4n .EX sysconf(_SC_CLK_TCK); .EE .in -.PP +.P Note that .BR clock (3) also returns a value of type diff --git a/man2/tkill.2 b/man2/tkill.2 index 8780e8a..78a1ce5 100644 --- a/man2/tkill.2 +++ b/man2/tkill.2 @@ -6,7 +6,7 @@ .\" 2004-05-31, added tgkill, ahu, aeb .\" 2008-01-15 mtk -- rewrote DESCRIPTION .\" -.TH tkill 2 2023-03-30 "Linux man-pages 6.05.01" +.TH tkill 2 2023-10-31 "Linux man-pages 6.7" .SH NAME tkill, tgkill \- send a signal to a thread .SH LIBRARY @@ -17,14 +17,14 @@ Standard C library .BR "#include <signal.h>" " /* Definition of " SIG* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "[[deprecated]] int syscall(SYS_tkill, pid_t " tid ", int " sig ); -.PP +.P .B #include <signal.h> -.PP +.P .BI "int tgkill(pid_t " tgid ", pid_t " tid ", int " sig ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR tkill (), @@ -43,7 +43,7 @@ in the thread group can be used to send a signal only to a process (i.e., thread group) as a whole, and the signal will be delivered to an arbitrary thread within that process.) -.PP +.P .BR tkill () is an obsolete predecessor to .BR tgkill (). @@ -76,7 +76,7 @@ Avoid using this system call. .\" measurable, one could exhaust all but 1-2 available pid values, .\" possibly by lowering the max pid parameter in /proc, forcing .\" the same tid to be reused rapidly. -.PP +.P These are the raw system call interfaces, meant for internal thread library use. .SH RETURN VALUE diff --git a/man2/truncate.2 b/man2/truncate.2 index 02a12e5..13ebec0 100644 --- a/man2/truncate.2 +++ b/man2/truncate.2 @@ -12,7 +12,7 @@ .\" Modified 2002-04-06 by Andries Brouwer <aeb@cwi.nl> .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH truncate 2 2023-03-30 "Linux man-pages 6.05.01" +.TH truncate 2 2023-10-31 "Linux man-pages 6.7" .SH NAME truncate, ftruncate \- truncate a file to a specified length .SH LIBRARY @@ -21,16 +21,16 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int truncate(const char *" path ", off_t " length ); .BI "int ftruncate(int " fd ", off_t " length ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR truncate (): .nf _XOPEN_SOURCE >= 500 @@ -38,7 +38,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR ftruncate (): .nf _XOPEN_SOURCE >= 500 @@ -58,20 +58,20 @@ or referenced by to be truncated to a size of precisely .I length bytes. -.PP +.P If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is extended, and the extended part reads as null bytes (\[aq]\e0\[aq]). -.PP +.P The file offset is not changed. -.PP +.P If the size changed, then the st_ctime and st_mtime fields (respectively, time of last status change and time of last modification; see .BR inode (7)) for the file are updated, and the set-user-ID and set-group-ID mode bits may be cleared. -.PP +.P With .BR ftruncate (), the file must be open for writing; with @@ -148,7 +148,7 @@ The named file resides on a read-only filesystem. .TP .B ETXTBSY The file is an executable file that is being executed. -.PP +.P For .BR ftruncate () the same errors apply, but instead of things that can be wrong with @@ -197,7 +197,7 @@ and to be used to extend a file beyond its current length: a notable example on Linux is VFAT. .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002 -.PP +.P On some 32-bit architectures, the calling signature for these system calls differ, for the reasons described in @@ -212,13 +212,13 @@ POSIX.1-2001, .\" POSIX.1-2001 also has .\" .BR truncate (), .\" as an XSI extension. -.\" .LP +.\" .P .\" SVr4 documents additional .\" .BR truncate () .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for .\" .BR ftruncate () .\" an additional EAGAIN error condition. -.PP +.P The original Linux .BR truncate () and diff --git a/man2/umask.2 b/man2/umask.2 index c920b55..bfea2e6 100644 --- a/man2/umask.2 +++ b/man2/umask.2 @@ -11,7 +11,7 @@ .\" <nick@debian.com> with Lars Wirzenius <liw@iki.fi> suggestion .\" 2006-05-13, mtk, substantial rewrite of description of 'mask' .\" 2008-01-09, mtk, a few rewrites and additions. -.TH umask 2 2023-03-30 "Linux man-pages 6.05.01" +.TH umask 2 2023-10-31 "Linux man-pages 6.7" .SH NAME umask \- set file mode creation mask .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/stat.h> -.PP +.P .BI "mode_t umask(mode_t " mask ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ sets the calling process's file mode creation mask (umask) to & 0777 (i.e., only the file permission bits of .I mask are used), and returns the previous value of the mask. -.PP +.P The umask is used by .BR open (2), .BR mkdir (2), @@ -45,7 +45,7 @@ argument to .BR open (2) and .BR mkdir (2). -.PP +.P Alternatively, if the parent directory has a default ACL (see .BR acl (5)), the umask is ignored, the default ACL is inherited, @@ -54,23 +54,23 @@ and permission bits absent in the .I mode argument are turned off. For example, the following default ACL is equivalent to a umask of 022: -.PP +.P .in +4n .EX u::rwx,g::r-x,o::r-x .EE .in -.PP +.P Combining the effect of this default ACL with a .I mode argument of 0666 (rw-rw-rw-), the resulting file permissions would be 0644 (rw-r--r--). -.PP +.P The constants that should be used to specify .I mask are described in .BR inode (7). -.PP +.P The typical default value for the process umask is .BR S_IWGRP " | " S_IWOTH (octal 022). @@ -79,22 +79,22 @@ In the usual case where the argument to .BR open (2) is specified as: -.PP +.P .in +4n .EX .BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH .EE .in -.PP +.P (octal 0666) when creating a new file, the permissions on the resulting file will be: -.PP +.P .in +4n .EX .BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IROTH .EE .in -.PP +.P (because 0666 & \[ti]022 = 0644; i.e. rw\-r\-\-r\-\-). .SH RETURN VALUE This system call always succeeds and the previous value of the mask @@ -109,7 +109,7 @@ A child process created via inherits its parent's umask. The umask is left unchanged by .BR execve (2). -.PP +.P It is impossible to use .BR umask () to fetch a process's umask without at the same time changing it. @@ -118,7 +118,7 @@ A second call to would then be needed to restore the umask. The nonatomicity of these two steps provides the potential for races in multithreaded programs. -.PP +.P Since Linux 4.7, the umask of any process can be viewed via the .I Umask field of @@ -126,7 +126,7 @@ field of Inspecting this field in .I /proc/self/status allows a process to retrieve its umask without at the same time changing it. -.PP +.P The umask setting also affects the permissions assigned to POSIX IPC objects .RB ( mq_open (3), .BR sem_open (3), diff --git a/man2/umount.2 b/man2/umount.2 index cba0abc..07e3a93 100644 --- a/man2/umount.2 +++ b/man2/umount.2 @@ -7,7 +7,7 @@ .\" 2008-10-06, mtk: Created this as a new page by splitting .\" umount/umount2 material out of mount.2 .\" -.TH umount 2 2023-03-30 "Linux man-pages 6.05.01" +.TH umount 2 2023-10-31 "Linux man-pages 6.7" .SH NAME umount, umount2 \- unmount filesystem .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B "#include <sys/mount.h>" -.PP +.P .BI "int umount(const char *" target ); .BI "int umount2(const char *" target ", int " flags ); .fi @@ -29,11 +29,11 @@ remove the attachment of the (topmost) filesystem mounted on .\" Note: the kernel naming differs from the glibc naming .\" umount2 is the glibc name for what the kernel now calls umount .\" and umount is the glibc name for oldumount -.PP +.P Appropriate privilege (Linux: the .B CAP_SYS_ADMIN capability) is required to unmount filesystems. -.PP +.P Linux 2.1.116 added the .BR umount2 () system call, which, like @@ -162,7 +162,7 @@ and .B MNT_EXPIRE .\" http://sourceware.org/bugzilla/show_bug.cgi?id=10092 are available since glibc 2.11. -.PP +.P The original .BR umount () function was called as \fIumount(device)\fP and would return @@ -183,7 +183,7 @@ This means that .BR umount () of any peer in a set of shared mounts will cause all of its peers to be unmounted and all of their slaves to be unmounted as well. -.PP +.P This propagation of unmount activity can be particularly surprising on systems where every mount is shared by default. On such systems, @@ -191,7 +191,7 @@ recursively bind mounting the root directory of the filesystem onto a subdirectory and then later unmounting that subdirectory with .B MNT_DETACH will cause every mount in the mount namespace to be lazily unmounted. -.PP +.P To ensure .BR umount () does not propagate in this fashion, diff --git a/man2/uname.2 b/man2/uname.2 index e84f3e7..e4f449f 100644 --- a/man2/uname.2 +++ b/man2/uname.2 @@ -4,7 +4,7 @@ .\" .\" 2007-07-05 mtk: Added details on underlying system call interfaces .\" -.TH uname 2 2023-03-30 "Linux man-pages 6.05.01" +.TH uname 2 2023-10-31 "Linux man-pages 6.7" .SH NAME uname \- get name and information about current kernel .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/utsname.h> -.PP +.P .BI "int uname(struct utsname *" buf ); .fi .SH DESCRIPTION @@ -24,7 +24,7 @@ The .I utsname struct is defined in .IR <sys/utsname.h> : -.PP +.P .in +4n .EX struct utsname { @@ -41,7 +41,7 @@ struct utsname { }; .EE .in -.PP +.P The length of the arrays in a .I struct utsname is unspecified (see NOTES); @@ -60,7 +60,7 @@ is not valid. The .I domainname member (the NIS or YP domain name) is a GNU extension. -.PP +.P The length of the fields in the struct varies. Some operating systems or libraries use a hardcoded 9 or 33 or 65 or 257. @@ -120,7 +120,7 @@ Similarly, the .I domainname field is set via .BR setdomainname (2). -.PP +.P Part of the utsname information is also accessible via .IR /proc/sys/kernel/ { ostype , .IR hostname , diff --git a/man2/unimplemented.2 b/man2/unimplemented.2 index 535d3e9..3daa030 100644 --- a/man2/unimplemented.2 +++ b/man2/unimplemented.2 @@ -4,7 +4,7 @@ .\" .\" Updated, aeb, 980612 .\" -.TH UNIMPLEMENTED 2 2022-10-09 "Linux man-pages 6.05.01" +.TH UNIMPLEMENTED 2 2023-10-31 "Linux man-pages 6.7" .SH NAME afs_syscall, break, fattach, fdetach, ftime, getmsg, getpmsg, gtty, isastream, lock, madvise1, mpx, prof, profil, putmsg, putpmsg, security, @@ -27,7 +27,7 @@ Note that and .BR ulimit (3) are implemented as library functions. -.PP +.P Some system calls, like .BR alloc_hugepages (2), .BR free_hugepages (2), @@ -36,7 +36,7 @@ Some system calls, like and .BR vm86 (2) exist only on certain architectures. -.PP +.P Some system calls, like .BR ipc (2), .BR create_module (2), diff --git a/man2/unlink.2 b/man2/unlink.2 index 85cb670..7485a32 100644 --- a/man2/unlink.2 +++ b/man2/unlink.2 @@ -10,7 +10,7 @@ .\" Modified 2001-05-17 by aeb .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" -.TH unlink 2 2023-03-30 "Linux man-pages 6.05.01" +.TH unlink 2 2024-02-18 "Linux man-pages 6.7" .SH NAME unlink, unlinkat \- delete a name and possibly the file it refers to .SH LIBRARY @@ -19,20 +19,20 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int unlink(const char *" pathname ); -.PP +.P .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR unlinkat (): .nf Since glibc 2.10: @@ -46,13 +46,13 @@ deletes a name from the filesystem. If that name was the last link to a file and no processes have the file open, the file is deleted and the space it was using is made available for reuse. -.PP +.P If the name was the last link to a file but any processes still have the file open, the file will remain in existence until the last file descriptor referring to it is closed. -.PP +.P If the name referred to a symbolic link, the link is removed. -.PP +.P If the name referred to a socket, FIFO, or device, the name for it is removed but processes which have the object open may continue to use it. @@ -69,7 +69,7 @@ includes the .B AT_REMOVEDIR flag) except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -81,7 +81,7 @@ the calling process, as is done by and .BR rmdir (2) for a relative pathname). -.PP +.P If the pathname given in .I pathname is relative and @@ -95,13 +95,13 @@ directory of the calling process (like .BR unlink () and .BR rmdir (2)). -.PP +.P If the pathname given in .I pathname is absolute, then .I dirfd is ignored. -.PP +.P .I flags is a bit mask that can either be specified as 0, or by ORing together flag values that control the operation of @@ -117,12 +117,12 @@ on .IR pathname . If the .B AT_REMOVEDIR -flag is specified, then +flag is specified, it performs the equivalent of .BR rmdir (2) on .IR pathname . -.PP +.P See .BR openat (2) for an explanation of the need for @@ -218,7 +218,7 @@ The file to be unlinked is marked immutable or append-only. .B EROFS .I pathname refers to a file on a read-only filesystem. -.PP +.P The same errors that occur for .BR unlink () and diff --git a/man2/unshare.2 b/man2/unshare.2 index b12afb5..ce2464d 100644 --- a/man2/unshare.2 +++ b/man2/unshare.2 @@ -15,7 +15,7 @@ .\" by clone, which would require porting and maintaining all commands .\" such as login, and su, that establish a user session. .\" -.TH unshare 2 2023-05-26 "Linux man-pages 6.05.01" +.TH unshare 2 2023-10-31 "Linux man-pages 6.7" .SH NAME unshare \- disassociate parts of the process execution context .SH LIBRARY @@ -25,7 +25,7 @@ Standard C library .nf .B #define _GNU_SOURCE .B #include <sched.h> -.PP +.P .BI "int unshare(int " flags ); .fi .SH DESCRIPTION @@ -40,12 +40,12 @@ or while other parts, such as virtual memory, may be shared by explicit request when creating a process or thread using .BR clone (2). -.PP +.P The main use of .BR unshare () is to allow a process to control its shared execution context without creating a new process. -.PP +.P The .I flags argument is a bit mask that specifies which parts of @@ -250,7 +250,7 @@ to the corresponding semaphores, as described in .BR semop (2). .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared .\" (i.e., current->signal->count > 1), force CLONE_THREAD. -.PP +.P In addition, .BR CLONE_THREAD , .BR CLONE_SIGHAND , @@ -277,7 +277,7 @@ automatically implies If the process is multithreaded, then the use of these flags results in an error. .\" See kernel/fork.c::check_unshare_flags() -.PP +.P If .I flags is specified as zero, then @@ -457,7 +457,7 @@ Such functionality may be added in the future, if required. .\"be incrementally added to unshare without affecting legacy .\"applications using unshare. .\" -.PP +.P Creating all kinds of namespace, except user namespaces, requires the .B CAP_SYS_ADMIN capability. @@ -477,7 +477,7 @@ Here's an example of the use of this program, running a shell in a new mount namespace, and verifying that the original shell and the new shell are in separate mount namespaces: -.PP +.P .in +4n .EX $ \fBreadlink /proc/$$/ns/mnt\fP @@ -487,7 +487,7 @@ $ \fBsudo ./unshare \-m /bin/bash\fP mnt:[4026532325] .EE .in -.PP +.P The differing output of the two .BR readlink (1) commands shows that the two shells are in different mount namespaces. @@ -563,7 +563,7 @@ main(int argc, char *argv[]) .BR setns (2), .BR vfork (2), .BR namespaces (7) -.PP +.P .I Documentation/userspace\-api/unshare.rst in the Linux kernel source tree .\" commit f504d47be5e8fa7ecf2bf660b18b42e6960c0eb2 diff --git a/man2/uselib.2 b/man2/uselib.2 index 1d6a072..cdd7fba 100644 --- a/man2/uselib.2 +++ b/man2/uselib.2 @@ -8,13 +8,13 @@ .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" Modified 2005-01-09 by aeb .\" -.TH uselib 2 2023-03-30 "Linux man-pages 6.05.01" +.TH uselib 2 2023-10-31 "Linux man-pages 6.7" .SH NAME uselib \- load shared library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "[[deprecated]] int uselib(const char *" library ); .fi .SH DESCRIPTION @@ -65,13 +65,13 @@ Therefore, in order to employ this system call, it was sufficient to manually declare the interface in your code; alternatively, you could invoke the system call using .BR syscall (2). -.PP +.P In ancient libc versions (before glibc 2.0), .BR uselib () was used to load the shared libraries with names found in an array of names in the binary. -.\" .PP +.\" .P .\" .\" libc 4.3.1f - changelog 1993-03-02 .\" Since libc 4.3.2, startup code tries to prefix these names .\" with "/usr/lib", "/lib" and "" before giving up. @@ -81,14 +81,14 @@ in the binary. .\" .BR LD_LIBRARY_PATH , .\" and if not found there, .\" prefixes "/usr/lib", "/lib" and "/" are tried. -.\" .PP +.\" .P .\" From libc 4.4.4 on only the library "/lib/ld.so" is loaded, .\" so that this dynamic library can load the remaining libraries needed .\" (again using this call). .\" This is also the state of affairs in libc5. -.\" .PP +.\" .P .\" glibc2 does not use this call. -.PP +.P Since Linux 3.15, .\" commit 69369a7003735d0d8ef22097e27a55a8bad9557a this system call is available only when the kernel is configured with the diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2 index 82903c6..27f4b69 100644 --- a/man2/userfaultfd.2 +++ b/man2/userfaultfd.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH userfaultfd 2 2023-05-03 "Linux man-pages 6.05.01" +.TH userfaultfd 2 2024-02-12 "Linux man-pages 6.7" .SH NAME userfaultfd \- create a file descriptor for handling page faults in user space .SH LIBRARY @@ -16,10 +16,10 @@ Standard C library .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .BR "#include <linux/userfaultfd.h>" " /* Definition of " UFFD_* " constants */" .B #include <unistd.h> -.PP +.P .BI "int syscall(SYS_userfaultfd, int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR userfaultfd (), @@ -32,7 +32,7 @@ handling to a user-space application, and returns a file descriptor that refers to the new object. The new userfaultfd object is configured using .BR ioctl (2). -.PP +.P Once the userfaultfd object is configured, the application can use .BR read (2) to receive userfaultfd notifications. @@ -41,7 +41,7 @@ depending on the value of .I flags used for the creation of the userfaultfd or subsequent calls to .BR fcntl (2). -.PP +.P The following values may be bitwise ORed in .I flags to change the behavior of @@ -69,12 +69,12 @@ When a kernel-originated fault was triggered on the registered range with this userfaultfd, a .B SIGBUS signal will be delivered. -.PP +.P When the last file descriptor referring to a userfaultfd object is closed, all memory ranges that were registered with the object are unregistered and unread events are flushed. .\" -.PP +.P Userfaultfd supports three modes of registration: .TP .BR UFFDIO_REGISTER_MODE_MISSING " (since Linux 4.10)" @@ -111,9 +111,9 @@ The faulted thread will be stopped from execution until user-space write-unprotects the page using an .B UFFDIO_WRITEPROTECT ioctl. -.PP +.P Multiple modes can be enabled at the same time for the same memory range. -.PP +.P Since Linux 4.14, a userfaultfd page-fault notification can selectively embed faulting thread ID information into the notification. One needs to enable this feature explicitly using the @@ -132,7 +132,7 @@ them using the operations described in .BR ioctl_userfaultfd (2). When servicing the page fault events, the fault-handling thread can trigger a wake-up for the sleeping thread. -.PP +.P It is possible for the faulting threads and the fault-handling threads to run in the context of different processes. In this case, these threads may belong to different programs, @@ -142,7 +142,7 @@ In such non-cooperative mode, the process that monitors userfaultfd and handles page faults needs to be aware of the changes in the virtual memory layout of the faulting process to avoid memory corruption. -.PP +.P Since Linux 4.11, userfaultfd can also notify the fault-handling threads about changes in the virtual memory layout of the faulting process. @@ -166,7 +166,7 @@ soon as the userfaultfd manager executes The userfaultfd manager should carefully synchronize calls to .B UFFDIO_COPY with the processing of events. -.PP +.P The current asynchronous model of the event delivery is optimal for single threaded non-cooperative userfaultfd manager implementations. .\" Regarding the preceding sentence, Mike Rapoport says: @@ -174,13 +174,13 @@ single threaded non-cooperative userfaultfd manager implementations. .\" problematic for multi-threaded monitor. I even suspect that it would be .\" impossible to ensure synchronization between page faults and non-page .\" fault events in multi-threaded monitor. -.\" .PP +.\" .P .\" FIXME elaborate about non-cooperating mode, describe its limitations .\" for kernels before Linux 4.11, features added in Linux 4.11 .\" and limitations remaining in Linux 4.11 .\" Maybe it's worth adding a dedicated sub-section... .\" -.PP +.P Since Linux 5.7, userfaultfd is able to do synchronous page dirty tracking using the new write-protect register mode. One should check against the feature bit @@ -200,14 +200,15 @@ the application must enable it using the .B UFFDIO_API .BR ioctl (2) operation. -This operation allows a handshake between the kernel and user space -to determine the API version and supported features. +This operation allows a two-step handshake between the kernel and user space +to determine what API version and features the kernel supports, +and then to enable those features user space wants. This operation must be performed before any of the other .BR ioctl (2) operations described below (or those operations fail with the .B EINVAL error). -.PP +.P After a successful .B UFFDIO_API operation, @@ -221,14 +222,14 @@ operation, a page fault occurring in the requested memory range, and satisfying the mode defined at the registration time, will be forwarded by the kernel to the user-space application. -The application can then use the -.B UFFDIO_COPY , -.B UFFDIO_ZEROPAGE , +The application can then use various (e.g., +.BR UFFDIO_COPY , +.BR UFFDIO_ZEROPAGE , or -.B UFFDIO_CONTINUE +.BR UFFDIO_CONTINUE ) .BR ioctl (2) operations to resolve the page fault. -.PP +.P Since Linux 4.14, if the application sets the .B UFFD_FEATURE_SIGBUS feature bit using the @@ -247,23 +248,23 @@ accesses. For example, this feature can be useful for applications that want to prevent the kernel from automatically allocating pages and filling holes in sparse files when the hole is accessed through a memory mapping. -.PP +.P The .B UFFD_FEATURE_SIGBUS feature is implicitly inherited through .BR fork (2) if used in combination with .BR UFFD_FEATURE_FORK . -.PP +.P Details of the various .BR ioctl (2) operations can be found in .BR ioctl_userfaultfd (2). -.PP +.P Since Linux 4.11, events other than page-fault may enabled during .B UFFDIO_API operation. -.PP +.P Up to Linux 4.11, userfaultfd can be used only with anonymous private memory mappings. Since Linux 4.11, @@ -276,13 +277,13 @@ The user needs to first check availability of this feature using ioctl against the feature bit .B UFFD_FEATURE_PAGEFAULT_FLAG_WP before using this feature. -.PP +.P Since Linux 5.19, the write-protection mode was also supported on shmem and hugetlbfs memory types. It can be detected with the feature bit .BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM . -.PP +.P To register with userfaultfd write-protect mode, the user needs to initiate the .B UFFDIO_REGISTER ioctl with mode @@ -300,7 +301,7 @@ registered, user-space will receive any notification when a missing page is written. Instead, user-space will receive a write-protect page-fault notification only when an existing but write-protected page got written. -.PP +.P After the .B UFFDIO_REGISTER ioctl completed with @@ -312,7 +313,7 @@ where .I uffdio_writeprotect.mode should be set to .BR UFFDIO_WRITEPROTECT_MODE_WP . -.PP +.P When a write-protect event happens, user-space will receive a page-fault notification whose .I uffd_msg.pagefault.flags @@ -325,7 +326,7 @@ write-protect notifications will always have the bit set along with the .B UFFD_PAGEFAULT_FLAG_WP bit. -.PP +.P To resolve a write-protection page fault, the user should initiate another .B UFFDIO_WRITEPROTECT ioctl, whose @@ -351,14 +352,14 @@ since Linux 5.13, or .B UFFD_FEATURE_MINOR_SHMEM since Linux 5.14. -.PP +.P To register with userfaultfd minor fault mode, the user needs to initiate the .B UFFDIO_REGISTER ioctl with mode .B UFFD_REGISTER_MODE_MINOR set. -.PP +.P When a minor fault occurs, user-space will receive a page-fault notification whose @@ -366,7 +367,7 @@ whose will have the .B UFFD_PAGEFAULT_FLAG_MINOR flag set. -.PP +.P To resolve a minor page fault, the handler should decide whether or not the existing page contents need to be modified first. @@ -382,7 +383,7 @@ ioctl, which installs the page table entries and (by default) wakes up the faulting thread(s). -.PP +.P Minor fault mode supports only hugetlbfs-backed (since Linux 5.13) and shmem-backed (since Linux 5.14) memory. .\" @@ -393,7 +394,7 @@ from the userfaultfd file descriptor returns one or more .I uffd_msg structures, each of which describes a page-fault event or an event required for the non-cooperative userfaultfd usage: -.PP +.P .in +4n .EX struct uffd_msg { @@ -430,7 +431,7 @@ struct uffd_msg { } __packed; .EE .in -.PP +.P If multiple events are available and the supplied buffer is large enough, .BR read (2) returns as many events as will fit in the supplied buffer. @@ -442,7 +443,7 @@ structure, the .BR read (2) fails with the error .BR EINVAL . -.PP +.P The fields set in the .I uffd_msg structure are as follows: @@ -532,7 +533,7 @@ If this flag is set, then the fault was a minor fault. .TP .B UFFD_PAGEFAULT_FLAG_WRITE If this flag is set, then the fault was a write fault. -.PP +.P If neither .B UFFD_PAGEFAULT_FLAG_WP nor @@ -569,7 +570,7 @@ or unmapped The end address of the memory range that was freed using .BR madvise (2) or unmapped -.PP +.P A .BR read (2) on a userfaultfd file descriptor can fail with the following errors: @@ -579,7 +580,7 @@ The userfaultfd object has not yet been enabled using the .B UFFDIO_API .BR ioctl (2) operation -.PP +.P If the .B O_NONBLOCK flag is enabled in the associated open file description, @@ -636,7 +637,7 @@ has the value 0. Linux. .SH HISTORY Linux 4.3. -.PP +.P Support for hugetlbfs and shared memory areas and non-page-fault events was added in Linux 4.11 .SH NOTES @@ -666,7 +667,7 @@ The program creates two threads, one of which acts as the page-fault handler for the process, for the pages in a demand-page zero region created using .BR mmap (2). -.PP +.P The program takes one command-line argument, which is the number of pages that will be created in a mapping whose page faults will be handled via userfaultfd. @@ -678,13 +679,13 @@ and registers the address range of that mapping using the operation. The program then creates a second thread that will perform the task of handling page faults. -.PP +.P The main thread then walks through the pages of the mapping fetching bytes from successive pages. Because the pages have not yet been accessed, the first access of a byte in each page will trigger a page-fault event on the userfaultfd file descriptor. -.PP +.P Each of the page-fault events is handled by the second thread, which sits in a loop processing input from the userfaultfd file descriptor. In each loop iteration, the second thread first calls @@ -699,9 +700,9 @@ the faulting region using the .B UFFDIO_COPY .BR ioctl (2) operation. -.PP +.P The following is an example of what we see when running the program: -.PP +.P .in +4n .EX $ \fB./userfaultfd_demo 3\fP @@ -879,6 +880,13 @@ main(int argc, char *argv[]) if (uffd == \-1) err(EXIT_FAILURE, "userfaultfd"); \& + /* NOTE: Two-step feature handshake is not needed here, since this + example doesn't require any specific features. +\& + Programs that *do* should call UFFDIO_API twice: once with + `features = 0` to detect features supported by this kernel, and + again with the subset of features the program actually wants to + enable. */ uffdio_api.api = UFFD_API; uffdio_api.features = 0; if (ioctl(uffd, UFFDIO_API, &uffdio_api) == \-1) @@ -938,6 +946,6 @@ main(int argc, char *argv[]) .BR ioctl_userfaultfd (2), .BR madvise (2), .BR mmap (2) -.PP +.P .I Documentation/admin\-guide/mm/userfaultfd.rst in the Linux kernel source tree diff --git a/man2/ustat.2 b/man2/ustat.2 index a894b13..6a682d7 100644 --- a/man2/ustat.2 +++ b/man2/ustat.2 @@ -7,7 +7,7 @@ .\" Modified 2001-03-22 by aeb .\" Modified 2003-08-04 by aeb .\" -.TH ustat 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ustat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ustat \- get filesystem statistics .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .B #include <sys/types.h> .BR "#include <unistd.h>" " /* libc[45] */" .BR "#include <ustat.h>" " /* glibc2 */" -.PP +.P .BI "[[deprecated]] int ustat(dev_t " dev ", struct ustat *" ubuf ); .fi .SH DESCRIPTION @@ -32,7 +32,7 @@ is a pointer to a .I ustat structure that contains the following members: -.PP +.P .in +4n .EX daddr_t f_tfree; /* Total free blocks */ @@ -41,7 +41,7 @@ char f_fname[6]; /* Filsys name */ char f_fpack[6]; /* Filsys pack name */ .EE .in -.PP +.P The last two fields, .I f_fname and @@ -79,7 +79,7 @@ SVr4. Removed in glibc 2.28. .\" SVr4 documents additional error conditions ENOLINK, ECOMM, and EINTR .\" but has no ENOSYS condition. -.PP +.P .BR ustat () is deprecated and has been provided only for compatibility. All new programs should use diff --git a/man2/utime.2 b/man2/utime.2 index 86760ab..51073d0 100644 --- a/man2/utime.2 +++ b/man2/utime.2 @@ -8,7 +8,7 @@ .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> .\" Modified 2004-10-10 by Andries Brouwer <aeb@cwi.nl> .\" -.TH utime 2 2023-03-30 "Linux man-pages 6.05.01" +.TH utime 2 2023-10-31 "Linux man-pages 6.7" .SH NAME utime, utimes \- change file last access and modification times .SH LIBRARY @@ -17,12 +17,12 @@ Standard C library .SH SYNOPSIS .nf .B #include <utime.h> -.PP +.P .BI "int utime(const char *" filename , .BI " const struct utimbuf *_Nullable " times ); -.PP +.P .B #include <sys/time.h> -.PP +.P .BI "int utimes(const char *" filename , .BI " const struct timeval " times "[_Nullable 2]);" .fi @@ -30,7 +30,7 @@ Standard C library .B Note: modern applications may prefer to use the interfaces described in .BR utimensat (2). -.PP +.P The .BR utime () system call @@ -43,23 +43,23 @@ fields of respectively. The status change time (ctime) will be set to the current time, even if the other time stamps don't actually change. -.PP +.P If .I times is NULL, then the access and modification times of the file are set to the current time. -.PP +.P Changing timestamps is permitted when: either the process has appropriate privileges, or the effective user ID equals the user ID of the file, or .I times is NULL and the process has write permission for the file. -.PP +.P The .I utimbuf structure is: -.PP +.P .in +4n .EX struct utimbuf { @@ -68,12 +68,12 @@ struct utimbuf { }; .EE .in -.PP +.P The .BR utime () system call allows specification of timestamps with a resolution of 1 second. -.PP +.P The .BR utimes () system call @@ -86,7 +86,7 @@ structures, which allow a precision of 1 microsecond for specifying timestamps. The .I timeval structure is: -.PP +.P .in +4n .EX struct timeval { @@ -95,7 +95,7 @@ struct timeval { }; .EE .in -.PP +.P .I times[0] specifies the new access time, and .I times[1] diff --git a/man2/utimensat.2 b/man2/utimensat.2 index 77456fc..d69539d 100644 --- a/man2/utimensat.2 +++ b/man2/utimensat.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH utimensat 2 2023-07-20 "Linux man-pages 6.05.01" +.TH utimensat 2 2024-01-01 "Linux man-pages 6.7" .SH NAME utimensat, futimens \- change file timestamps with nanosecond precision .SH LIBRARY @@ -14,17 +14,17 @@ Standard C library .nf .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */" .B #include <sys/stat.h> -.PP +.P .BI "int utimensat(int " dirfd ", const char *" pathname , .BI " const struct timespec " times "[_Nullable 2], int " flags ); .BI "int futimens(int " fd ", const struct timespec " times "[_Nullable 2]);" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR utimensat (): .nf Since glibc 2.10: @@ -32,7 +32,7 @@ Feature Test Macro Requirements for glibc (see Before glibc 2.10: _ATFILE_SOURCE .fi -.PP +.P .BR futimens (): .nf Since glibc 2.10: @@ -51,7 +51,7 @@ and .BR utimes (2), which permit only second and microsecond precision, respectively, when setting file timestamps. -.PP +.P With .BR utimensat () the file is specified via the pathname given in @@ -61,7 +61,7 @@ With the file whose timestamps are to be updated is specified via an open file descriptor, .IR fd . -.PP +.P For both calls, the new file timestamps are specified in the array .IR times : .I times[0] @@ -75,10 +75,10 @@ since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). This information is conveyed in a .BR timespec (3) structure. -.PP +.P Updated file timestamps are set to the greatest value supported by the filesystem that is not greater than the specified time. -.PP +.P If the .I tv_nsec field of one of the @@ -97,12 +97,12 @@ In both of these cases, the value of the corresponding .I tv_sec .\" 2.6.22 was broken: it is not ignored field is ignored. -.PP +.P If .I times is NULL, then both timestamps are set to the current time. .\" -.PP +.P The status change time (ctime) will be set to the current time, even if the other time stamps don't actually change. .SS Permissions requirements @@ -123,7 +123,7 @@ the caller must have write access to the file; the caller's effective user ID must match the owner of the file; or .IP \[bu] the caller must have appropriate privileges. -.PP +.P To make any change other than setting both timestamps to the current time (i.e., .I times @@ -138,7 +138,7 @@ and neither field is .BR UTIME_OMIT ), either condition 2 or 3 above must apply. -.PP +.P If both .I tv_nsec fields are specified as @@ -161,7 +161,7 @@ for a relative pathname). See .BR openat (2) for an explanation of why this can be useful. -.PP +.P If .I pathname is relative and @@ -173,19 +173,40 @@ then is interpreted relative to the current working directory of the calling process (like .BR utimes (2)). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P The .I flags -field is a bit mask that may be 0, or include the following constant, -defined in +argument is a bit mask created by ORing together zero or more of +the following values defined in .IR <fcntl.h> : .TP +.BR AT_EMPTY_PATH " (since Linux 5.8)" +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +to obtain its definition. +.TP .B AT_SYMLINK_NOFOLLOW If .I pathname @@ -383,7 +404,6 @@ T{ .BR futimens () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS C library/kernel ABI differences On Linux, @@ -402,13 +422,13 @@ the file referred to by the file descriptor Using this feature, the call .I "futimens(fd,\ times)" is implemented as: -.PP +.P .in +4n .EX utimensat(fd, NULL, times, 0); .EE .in -.PP +.P Note, however, that the glibc wrapper for .BR utimensat () disallows passing NULL as the value for @@ -432,7 +452,7 @@ POSIX.1-2008. .BR utimensat () obsoletes .BR futimesat (2). -.PP +.P On Linux, timestamps cannot be changed for a file marked immutable, and the only change permitted for files marked append-only is to set the timestamps to the current time. @@ -441,7 +461,7 @@ set the timestamps to the current time. and .BR utimes (2) on Linux.) -.PP +.P If both .I tv_nsec fields are specified as @@ -504,7 +524,7 @@ c) the wrong value is returned in case of an error. .\" Below, the long description of the errors from the previous bullet .\" point (abridged because it's too much detail for a man page). -.\" .IP * +.\" .IP \[bu] .\" If one of the .\" .I tv_nsec .\" fields is @@ -516,7 +536,7 @@ value is returned in case of an error. .\" should occur if the process's effective user ID does not match .\" the file owner and the process is not privileged. .\" Instead, the call successfully changes one of the timestamps. -.\" .IP * +.\" .IP \[bu] .\" If file is not writable by the effective user ID of the process and .\" the process's effective user ID does not match the file owner and .\" the process is not privileged, @@ -532,7 +552,7 @@ value is returned in case of an error. .\" fields are .\" .BR UTIME_NOW . .\" Instead the call succeeds. -.\" .IP * +.\" .IP \[bu] .\" If a file is marked as append-only (see .\" .BR chattr (1)), .\" then Linux traditionally @@ -554,7 +574,7 @@ value is returned in case of an error. .\" .BR UTIME_NOW . .\" Instead, the call fails with the error .\" .BR EPERM . -.\" .IP * +.\" .IP \[bu] .\" If a file is marked as immutable (see .\" .BR chattr (1)), .\" then Linux traditionally diff --git a/man2/vfork.2 b/man2/vfork.2 index 85c04d3..5d523ad 100644 --- a/man2/vfork.2 +++ b/man2/vfork.2 @@ -6,7 +6,7 @@ .\" 1999-11-10: Merged text taken from the page contributed by .\" Reed H. Petty (rhp@draper.net) .\" -.TH vfork 2 2023-07-28 "Linux man-pages 6.05.01" +.TH vfork 2 2023-10-31 "Linux man-pages 6.7" .SH NAME vfork \- create a child process and block parent .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B pid_t vfork(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR vfork (): .nf Since glibc 2.12: @@ -61,7 +61,7 @@ just like creates a child process of the calling process. For details and return value and errors, see .BR fork (2). -.PP +.P .BR vfork () is a special case of .BR clone (2). @@ -70,7 +70,7 @@ the parent process. It may be useful in performance-sensitive applications where a child is created which then immediately issues an .BR execve (2). -.PP +.P .BR vfork () differs from .BR fork (2) @@ -90,7 +90,7 @@ established by the parent process and flushing the parent's .BR stdio (3) buffers), but may call .BR _exit (2). -.PP +.P As with .BR fork (2), the child process created by @@ -101,7 +101,7 @@ the .BR vfork () call differs only in the treatment of the virtual address space, as described above. -.PP +.P Signals sent to the parent arrive after the child releases the parent's memory (i.e., after the child terminates @@ -145,7 +145,7 @@ remaining blocked until the child either terminates or calls .BR execve (2), and cannot rely on any specific behavior with respect to shared memory. .\" In AIXv3.1 vfork is equivalent to fork. -.PP +.P Some consider the semantics of .BR vfork () to be an architectural blemish, and the 4.2BSD man page stated: @@ -211,7 +211,7 @@ LinuxThreads threading library. (See .BR pthreads (7) for a description of Linux threading libraries.) -.PP +.P A call to .BR vfork () is equivalent to calling @@ -219,7 +219,7 @@ is equivalent to calling with .I flags specified as: -.PP +.P .in +4n .EX CLONE_VM | CLONE_VFORK | SIGCHLD @@ -231,7 +231,7 @@ None. 4.3BSD; POSIX.1-2001 (but marked OBSOLETE). POSIX.1-2008 removes the specification of .BR vfork (). -.PP +.P The .BR vfork () system call appeared in 3.0BSD. @@ -261,7 +261,7 @@ changes memory, those changes may result in an inconsistent process state from the perspective of the parent process (e.g., memory changes would be visible in the parent, but changes to the state of open file descriptors would not be visible). -.PP +.P When .BR vfork () is called in a multithreaded process, diff --git a/man2/vhangup.2 b/man2/vhangup.2 index af9853b..ed422b6 100644 --- a/man2/vhangup.2 +++ b/man2/vhangup.2 @@ -5,7 +5,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> .\" Added notes on capability requirements .\" -.TH vhangup 2 2023-03-30 "Linux man-pages 6.05.01" +.TH vhangup 2 2023-10-31 "Linux man-pages 6.7" .SH NAME vhangup \- virtually hangup the current terminal .SH LIBRARY @@ -14,15 +14,15 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .B int vhangup(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR vhangup (): .nf Since glibc 2.21: diff --git a/man2/vm86.2 b/man2/vm86.2 index 97595e8..fba1167 100644 --- a/man2/vm86.2 +++ b/man2/vm86.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH vm86 2 2023-03-30 "Linux man-pages 6.05.01" +.TH vm86 2 2023-10-31 "Linux man-pages 6.7" .SH NAME vm86old, vm86 \- enter virtual 8086 mode .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/vm86.h> -.PP +.P .BI "int vm86old(struct vm86_struct *" info ); .BI "int vm86(unsigned long " fn ", struct vm86plus_struct *" v86 ); .fi @@ -29,11 +29,11 @@ The definition of .I struct vm86_struct was changed in 1.1.8 and 1.1.9. -.PP +.P These calls cause the process to enter VM86 mode (virtual-8086 in Intel literature), and are used by .BR dosemu . -.PP +.P VM86 mode is an emulation of real mode within a protected mode task. .SH RETURN VALUE On success, zero is returned. diff --git a/man2/vmsplice.2 b/man2/vmsplice.2 index 4520b8a..ccbf2c6 100644 --- a/man2/vmsplice.2 +++ b/man2/vmsplice.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH vmsplice 2 2023-03-30 "Linux man-pages 6.05.01" +.TH vmsplice 2 2023-10-31 "Linux man-pages 6.7" .SH NAME vmsplice \- splice user pages to/from a pipe .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <fcntl.h> -.PP +.P .BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov , .BI " size_t " nr_segs ", unsigned int " flags ); .fi @@ -50,14 +50,14 @@ from a pipe. The file descriptor .I fd must refer to a pipe. -.PP +.P The pointer .I iov points to an array of .I iovec structures as described in .BR iovec (3type). -.PP +.P The .I flags argument is a bit mask that is composed by ORing together @@ -148,7 +148,7 @@ as defined in Currently, .\" UIO_MAXIOV in kernel source this limit is 1024. -.PP +.P .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7 .BR vmsplice () really supports true splicing only from user memory to a pipe. diff --git a/man2/wait.2 b/man2/wait.2 index cbd851e..e15ca87 100644 --- a/man2/wait.2 +++ b/man2/wait.2 @@ -26,7 +26,7 @@ .\" 2005-05-10, mtk, __W* flags can't be used with waitid() .\" 2008-07-04, mtk, removed erroneous text about SA_NOCLDSTOP .\" -.TH wait 2 2023-05-03 "Linux man-pages 6.05.01" +.TH wait 2 2023-10-31 "Linux man-pages 6.7" .SH NAME wait, waitpid, waitid \- wait for process to change state .SH LIBRARY @@ -35,21 +35,21 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/wait.h> -.PP +.P .BI "pid_t wait(int *_Nullable " "wstatus" ); .BI "pid_t waitpid(pid_t " pid ", int *_Nullable " wstatus ", int " options ); -.PP +.P .BI "int waitid(idtype_t " idtype ", id_t " id \ ", siginfo_t *" infop ", int " options ); /* This is the glibc and POSIX interface; see NOTES for information on the raw system call. */ .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR waitid (): .nf Since glibc 2.26: @@ -70,7 +70,7 @@ In the case of a terminated child, performing a wait allows the system to release the resources associated with the child; if a wait is not performed, then the terminated child remains in a "zombie" state (see NOTES below). -.PP +.P If a child has already changed state, then these calls return immediately. Otherwise, they block until either a child changes state or a signal handler interrupts the call (assuming that system calls @@ -90,13 +90,13 @@ children terminates. The call .I wait(&wstatus) is equivalent to: -.PP +.P .in +4n .EX waitpid(\-1, &wstatus, 0); .EE .in -.PP +.P The .BR waitpid () system call suspends execution of the calling thread until a @@ -109,7 +109,7 @@ waits only for terminated children, but this behavior is modifiable via the .I options argument, as described below. -.PP +.P The value of .I pid can be: @@ -131,7 +131,7 @@ equal to that of the calling process at the time of the call to meaning wait for the child whose process ID is equal to the value of .IR pid . -.PP +.P The value of .I options is an OR of zero or more of the following constants: @@ -151,9 +151,9 @@ even if this option is not specified. .BR WCONTINUED " (since Linux 2.6.10)" also return if a stopped child has been resumed by delivery of .BR SIGCONT . -.PP +.P (For Linux-only options, see below.) -.PP +.P If .I wstatus is not NULL, @@ -233,7 +233,7 @@ The .BR waitid () system call (available since Linux 2.6.9) provides more precise control over which child state changes to wait for. -.PP +.P The .I idtype and @@ -266,7 +266,7 @@ as the caller's process group at the time of the call. Wait for any child; .I id is ignored. -.PP +.P The child state changes to wait for are specified by ORing one or more of the following flags in .IR options : @@ -281,7 +281,7 @@ Wait for children that have been stopped by delivery of a signal. Wait for (previously stopped) children that have been resumed by delivery of .BR SIGCONT . -.PP +.P The following flags may additionally be ORed in .IR options : .TP @@ -292,7 +292,7 @@ As for .B WNOWAIT Leave the child in a waitable state; a later wait call can be used to again retrieve the child status information. -.PP +.P Upon successful return, .BR waitid () fills in the following fields of the @@ -337,7 +337,7 @@ Set to one of: .B CLD_CONTINUED (child continued by .BR SIGCONT ). -.PP +.P If .B WNOHANG was specified in @@ -355,7 +355,7 @@ waitable state, zero out the .I si_pid field before the call and check for a nonzero value in this field after the call returns. -.PP +.P POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that when .B WNOHANG is specified in @@ -382,7 +382,7 @@ not all implementations follow the POSIX.1 specification on this point. .BR wait (): on success, returns the process ID of the terminated child; on failure, \-1 is returned. -.PP +.P .BR waitpid (): on success, returns the process ID of the child whose state has changed; if @@ -391,7 +391,7 @@ was specified and one or more child(ren) specified by .I pid exist, but have not yet changed state, then 0 is returned. On failure, \-1 is returned. -.PP +.P .BR waitid (): returns 0 on success or if @@ -404,7 +404,7 @@ on failure, \-1 is returned. .\" returns the PID of the child. Either this is a bug, or it is intended .\" behavior that needs to be documented. See my Jan 2009 LKML mail .\" "waitid() return value strangeness when infop is NULL". -.PP +.P On failure, each of these calls sets .I errno to indicate the error. @@ -465,7 +465,7 @@ is equal to .BR wait () is actually a library function that (in glibc) is implemented as a call to .BR wait4 (2). -.PP +.P On some architectures, there is no .BR waitpid () system call; @@ -473,7 +473,7 @@ system call; instead, this interface is implemented via a C library wrapper function that calls .BR wait4 (2). -.PP +.P The raw .BR waitid () system call takes a fifth argument, of type @@ -507,7 +507,7 @@ are adopted by operation); .BR init (1) automatically performs a wait to remove the zombies. -.PP +.P POSIX.1-2001 specifies that if the disposition of .B SIGCHLD is set to @@ -536,7 +536,7 @@ Note that even though the default disposition of is "ignore", explicitly setting the disposition to .B SIG_IGN results in different treatment of zombie process children.) -.PP +.P Linux 2.6 conforms to the POSIX requirements. However, Linux 2.4 (and earlier) does not: if a @@ -565,7 +565,7 @@ of another thread, even when the latter belongs to the same thread group. However, POSIX prescribes such functionality, and since Linux 2.4 a thread can, and by default will, wait on children of other threads in the same thread group. -.PP +.P The following Linux-specific .I options are for use with children created using @@ -596,7 +596,7 @@ type ("clone" or "non-clone"). Do not wait for children of other threads in the same thread group. This was the default before Linux 2.4. -.PP +.P Since Linux 4.7, .\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c .\" prevents cases where an unreapable zombie is created if @@ -636,9 +636,9 @@ using the integer supplied on the command line as the exit status. The parent process executes a loop that monitors the child using .BR waitpid (), and uses the W*() macros described above to analyze the wait status value. -.PP +.P The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out &" diff --git a/man2/wait4.2 b/man2/wait4.2 index 7136d70..8e0798a 100644 --- a/man2/wait4.2 +++ b/man2/wait4.2 @@ -10,7 +10,7 @@ .\" Rewrote much of this page, and removed much duplicated text, .\" replacing with pointers to wait.2 .\" -.TH wait4 2 2023-03-30 "Linux man-pages 6.05.01" +.TH wait4 2 2023-10-31 "Linux man-pages 6.7" .SH NAME wait3, wait4 \- wait for process to change state, BSD style .SH LIBRARY @@ -19,18 +19,18 @@ Standard C library .SH SYNOPSIS .nf .B #include <sys/wait.h> -.PP +.P .BI "pid_t wait3(int *_Nullable " "wstatus" ", int " options , .BI " struct rusage *_Nullable " rusage ); .BI "pid_t wait4(pid_t " pid ", int *_Nullable " wstatus ", int " options , .BI " struct rusage *_Nullable " rusage ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wait3 (): .nf Since glibc 2.26: @@ -44,7 +44,7 @@ Feature Test Macro Requirements for glibc (see _BSD_SOURCE || _XOPEN_SOURCE >= 500 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED .fi -.PP +.P .BR wait4 (): .nf Since glibc 2.19: @@ -58,7 +58,7 @@ These functions are nonstandard; in new programs, the use of or .BR waitid (2) is preferable. -.PP +.P The .BR wait3 () and @@ -68,45 +68,45 @@ system calls are similar to but additionally return resource usage information about the child in the structure pointed to by .IR rusage . -.PP +.P Other than the use of the .I rusage argument, the following .BR wait3 () call: -.PP +.P .in +4n .EX wait3(wstatus, options, rusage); .EE .in -.PP +.P is equivalent to: -.PP +.P .in +4n .EX waitpid(\-1, wstatus, options); .EE .in -.PP +.P Similarly, the following .BR wait4 () call: -.PP +.P .in +4n .EX wait4(pid, wstatus, options, rusage); .EE .in -.PP +.P is equivalent to: -.PP +.P .in +4n .EX waitpid(pid, wstatus, options); .EE .in -.PP +.P In other words, .BR wait3 () waits of any child, while @@ -115,7 +115,7 @@ can be used to select a specific child, or children, on which to wait. See .BR wait (2) for further details. -.PP +.P If .I rusage is not NULL, the @@ -135,14 +135,14 @@ As for None. .SH HISTORY 4.3BSD. -.PP +.P SUSv1 included a specification of .BR wait3 (); SUSv2 included .BR wait3 (), but marked it LEGACY; SUSv3 removed it. -.PP +.P Including .I <sys/time.h> is not required these days, but increases portability. diff --git a/man2/write.2 b/man2/write.2 index d1dc273..fc22ae3 100644 --- a/man2/write.2 +++ b/man2/write.2 @@ -16,7 +16,7 @@ .\" gave some examples of why this might occur. .\" Noted what happens if write() is interrupted by a signal. .\" -.TH write 2 2023-04-03 "Linux man-pages 6.05.01" +.TH write 2 2023-10-31 "Linux man-pages 6.7" .SH NAME write \- write to a file descriptor .SH LIBRARY @@ -25,7 +25,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "ssize_t write(int " fd ", const void " buf [. count "], size_t " count ); .fi .SH DESCRIPTION @@ -36,7 +36,7 @@ bytes from the buffer starting at .I buf to the file referred to by the file descriptor .IR fd . -.PP +.P The number of bytes written may be less than .I count if, for example, @@ -50,7 +50,7 @@ handler after having written less than bytes. (See also .BR pipe (7).) -.PP +.P For a seekable file (i.e., one to which .BR lseek (2) may be applied, for example, a regular file) @@ -64,14 +64,14 @@ with the file offset is first set to the end of the file before writing. The adjustment of the file offset and the write operation are performed as an atomic step. -.PP +.P POSIX requires that a .BR read (2) that can be proved to occur after a .BR write () has returned will return the new data. Note that not all filesystems are POSIX conforming. -.PP +.P According to POSIX.1, if .I count is greater than @@ -82,7 +82,7 @@ see NOTES for the upper limit on Linux. On success, the number of bytes written is returned. On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. -.PP +.P Note that a successful .BR write () may transfer fewer than @@ -100,7 +100,7 @@ In the event of a partial write, the caller can make another call to transfer the remaining bytes. The subsequent call will either transfer further bytes or may result in an error (e.g., if the disk is now full). -.PP +.P If \fIcount\fP is zero and .I fd refers to a regular file, then @@ -222,7 +222,7 @@ When this happens the writing process will also receive a signal. (Thus, the write return value is seen only if the program catches, blocks or ignores this signal.) -.PP +.P Other errors may occur, depending on the object connected to .IR fd . .SH STANDARDS @@ -231,7 +231,7 @@ POSIX.1-2008. SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional error .\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE. -.PP +.P Under SVr4 a write may be interrupted and return .B EINTR at any point, @@ -251,7 +251,7 @@ or even The only way to be sure is to call .BR fsync (2) after you are done writing all your data. -.PP +.P If a .BR write () is interrupted by a signal handler before any bytes are written, @@ -259,7 +259,7 @@ then the call fails with the error .BR EINTR ; if it is interrupted after at least one byte has been written, the call succeeds, and returns the number of bytes written. -.PP +.P On Linux, .BR write () (and similar system calls) will transfer at most @@ -267,7 +267,7 @@ On Linux, returning the number of bytes actually transferred. .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 (This is true on both 32-bit and 64-bit systems.) -.PP +.P An error return value while performing .BR write () using direct I/O does not mean the @@ -279,13 +279,13 @@ was attempted should be considered inconsistent. .SH BUGS According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 ("Thread Interactions with Regular File Operations"): -.PP +.P .RS 4 All of the following functions shall be atomic with respect to each other in the effects specified in POSIX.1-2008 when they operate on regular files or symbolic links: ... .RE -.PP +.P Among the APIs subsequently listed are .BR write () and |