diff options
| author | Alejandro Colomar <alx@kernel.org> | 2023-03-17 17:08:01 +0100 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2023-03-30 15:14:55 +0200 |
| commit | 4131356cdab8d37fc395ca5466a0401c8573380c (patch) | |
| tree | 8c4c6f1c3172358b735b481cbbfdd9cc04b00ed9 /man2 | |
| parent | fd00f831b52d61a91d59cb3b46182869145d9700 (diff) | |
| download | man-pages-4131356cdab8.tar.gz | |
man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY: Reorganize sections
- Add a new HISTORY section that covers the history of an API, both
regarding implementations and regarding old standards. This was
previously covered in VERSIONS, and in some cases in STANDARDS.
- Repurpose VERSIONS to cover differing implementations in _current_
systems.
- STANDARDS is reduced to only cover current versions of standards.
That basically means only C11 (C99 has been superseeded by C11; C17
is just a bugfix of C11, so not really a new version), and
POSIX.1-2008 (*-2001 was superseeded by *-2008; *-2017 was just a
bugfix for *-2008). The section also mentions for example 'Linux',
'GNU' or 'BSD' when a non-standard API is Linux- or GNU-only or if
it's (de-facto) standard in the BSDs.
- In some cases content that should go into one of these sections was
in NOTES. Move it from there to where it corresponds.
- In the SYNOPSIS, I added [[deprecated]] in some functions that I
found are deprecated by the relevant standards.
- A few other related changes...
Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Diffstat (limited to 'man2')
265 files changed, 3101 insertions, 3079 deletions
diff --git a/man2/_exit.2 b/man2/_exit.2 index 10a3addc5a..b4bb34ccaf 100644 --- a/man2/_exit.2 +++ b/man2/_exit.2 @@ -60,8 +60,15 @@ is equivalent to .SH RETURN VALUE These functions do not return. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. -The function +.TP +.BR _exit () +POSIX.1-2008. +.TP +.BR _Exit () +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.PP .BR _Exit () was introduced by C99. .SH NOTES diff --git a/man2/_syscall.2 b/man2/_syscall.2 index efb7e802d5..cd9ebb6140 100644 --- a/man2/_syscall.2 +++ b/man2/_syscall.2 @@ -68,9 +68,9 @@ you call the system call by .SH FILES .I /usr/include/linux/unistd.h .SH STANDARDS -The use of these macros is Linux-specific, and deprecated. -.SH NOTES -Starting around kernel 2.6.18, the _syscall macros were removed +Linux. +.SH HISTORY +Starting around Linux 2.6.18, the _syscall macros were removed from header files supplied to user space. Use .BR syscall (2) @@ -79,7 +79,7 @@ instead. on those architectures, .BR syscall (2) was always required.) -.PP +.SH NOTES The _syscall() macros .I "do not" produce a prototype. diff --git a/man2/accept.2 b/man2/accept.2 index d852212e54..2832519f17 100644 --- a/man2/accept.2 +++ b/man2/accept.2 @@ -254,26 +254,6 @@ The value .B ERESTARTSYS may be seen during a trace. .SH VERSIONS -The -.BR accept4 () -system call is available starting with Linux 2.6.28; -support in glibc is available starting with glibc 2.10. -.SH STANDARDS -.BR accept (): -POSIX.1-2001, POSIX.1-2008, -SVr4, 4.4BSD -.RB ( accept () -first appeared in 4.2BSD). -.\" The BSD man page documents five possible error returns -.\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT). -.\" POSIX.1-2001 documents errors -.\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE, -.\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. -.\" In addition, SUSv2 documents EFAULT and ENOSR. -.PP -.BR accept4 () -is a nonstandard Linux extension. -.PP On Linux, the new socket returned by .BR accept () does \fInot\fP inherit file status flags such as @@ -288,6 +268,30 @@ Portable programs should not rely on inheritance or noninheritance of file status flags and always explicitly set all required flags on the socket returned from .BR accept (). +.SH STANDARDS +.TP +.BR accept () +POSIX.1-2008. +.TP +.BR accept4 () +Linux. +.PP +.SH HISTORY +.TP +.BR accept () +POSIX.1-2001, SVr4, 4.4BSD +.RB ( accept () +first appeared in 4.2BSD). +.\" The BSD man page documents five possible error returns +.\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT). +.\" POSIX.1-2001 documents errors +.\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE, +.\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. +.\" In addition, SUSv2 documents EFAULT and ENOSR. +.TP +.BR accept4 () +Linux 2.6.28, +glibc 2.10. .SH NOTES There may not always be a connection waiting after a .B SIGIO diff --git a/man2/access.2 b/man2/access.2 index d3deeecba0..b80b201d87 100644 --- a/man2/access.2 +++ b/man2/access.2 @@ -275,21 +275,65 @@ Write permission was requested for a file on a read-only filesystem. Write access was requested to an executable which is being executed. .SH VERSIONS +If the calling process has appropriate privileges (i.e., is superuser), +POSIX.1-2001 permits an implementation to indicate success for an +.B X_OK +check even if none of the execute file permission bits are set. +.\" HPU-UX 11 and Tru64 5.1 do this. +Linux does not do this. +.\" +.SS C library/kernel differences +The raw .BR faccessat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. -.PP -.BR faccessat2 () -was added in Linux 5.8. +system call takes only the first three arguments. +The +.B AT_EACCESS +and +.B AT_SYMLINK_NOFOLLOW +flags are actually implemented within the glibc wrapper function for +.BR faccessat (). +If either of these flags is specified, then the wrapper function employs +.BR fstatat (2) +to determine access permissions, but see BUGS. +.\" +.SS glibc notes +On older kernels where +.BR faccessat () +is unavailable (and when the +.B AT_EACCESS +and +.B AT_SYMLINK_NOFOLLOW +flags are not specified), +the glibc wrapper function falls back to the use of +.BR access (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I dirfd +argument. .SH STANDARDS -.BR access (): -SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. -.PP -.BR faccessat (): +.TP +.BR access () +.TQ +.BR faccessat () POSIX.1-2008. -.PP -.BR faccessat2 (): -Linux-specific. +.TP +.BR faccessat2 () +Linux. +.SH HISTORY +.TP +.BR access () +SVr4, 4.3BSD, POSIX.1-2001. +.TP +.BR faccessat () +Linux 2.6.16, +glibc 2.4. +.TP +.BR faccessat2 () +Linux 5.8. .SH NOTES .BR Warning : Using these calls to check if a user is authorized to, for example, @@ -316,13 +360,6 @@ is denied, even if some of the other access types in .I mode are permitted. .PP -If the calling process has appropriate privileges (i.e., is superuser), -POSIX.1-2001 permits an implementation to indicate success for an -.B X_OK -check even if none of the execute file permission bits are set. -.\" HPU-UX 11 and Tru64 5.1 do this. -Linux does not do this. -.PP A file is accessible only if the permissions on each of the directories in the path prefix of .I pathname @@ -346,39 +383,6 @@ which checks permissions. (NFS versions 3 and higher perform the check on the server.) Similar problems can occur to FUSE mounts. .\" -.\" -.SS C library/kernel differences -The raw -.BR faccessat () -system call takes only the first three arguments. -The -.B AT_EACCESS -and -.B AT_SYMLINK_NOFOLLOW -flags are actually implemented within the glibc wrapper function for -.BR faccessat (). -If either of these flags is specified, then the wrapper function employs -.BR fstatat (2) -to determine access permissions, but see BUGS. -.\" -.SS glibc notes -On older kernels where -.BR faccessat () -is unavailable (and when the -.B AT_EACCESS -and -.B AT_SYMLINK_NOFOLLOW -flags are not specified), -the glibc wrapper function falls back to the use of -.BR access (). -When -.I pathname -is a relative pathname, -glibc constructs a pathname based on the symbolic link in -.I /proc/self/fd -that corresponds to the -.I dirfd -argument. .SH BUGS Because the Linux kernel's .BR faccessat () diff --git a/man2/acct.2 b/man2/acct.2 index f9fc1cd5c8..8b7d943b0b 100644 --- a/man2/acct.2 +++ b/man2/acct.2 @@ -118,7 +118,9 @@ refers to a file on a read-only filesystem. .B EUSERS There are no more free file structures or we ran out of memory. .SH STANDARDS -SVr4, 4.3BSD (but not POSIX). +None. +.SH HISTORY +SVr4, 4.3BSD. .\" SVr4 documents an EBUSY error condition, but no EISDIR or ENOSYS. .\" Also AIX and HP-UX document EBUSY (attempt is made .\" to enable accounting when it is already enabled), as does Solaris diff --git a/man2/add_key.2 b/man2/add_key.2 index 56fc6d198d..10120c9413 100644 --- a/man2/add_key.2 +++ b/man2/add_key.2 @@ -208,10 +208,10 @@ and the started with a period (\[aq].\[aq]). Keyrings with descriptions (names) that begin with a period are reserved to the implementation. -.SH VERSIONS -This system call first appeared in Linux 2.6.10. .SH STANDARDS -This system call is a nonstandard Linux extension. +Linux. +.SH HISTORY +Linux 2.6.10. .SH NOTES glibc does not provide a wrapper for this system call. A wrapper is provided in the diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 index 155a4e2447..523347de23 100644 --- a/man2/adjtimex.2 +++ b/man2/adjtimex.2 @@ -548,13 +548,11 @@ T} Thread safety MT-Safe .TE .sp 1 .SH STANDARDS -None of these interfaces is described in POSIX.1 -.PP +.TP .BR adjtimex () -and +.TQ .BR clock_adjtime () -are Linux-specific and should not be used in programs -intended to be portable. +Linux. .PP The preferred API for the NTP daemon is .BR ntp_adjtime (). diff --git a/man2/alarm.2 b/man2/alarm.2 index 43c01a7a7b..dbc97b6327 100644 --- a/man2/alarm.2 +++ b/man2/alarm.2 @@ -40,7 +40,9 @@ returns the number of seconds remaining until any previously scheduled alarm was due to be delivered, or zero if there was no previously scheduled alarm. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. .SH NOTES .BR alarm () and diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2 index 8903cbe06e..1e470c6199 100644 --- a/man2/alloc_hugepages.2 +++ b/man2/alloc_hugepages.2 @@ -114,10 +114,11 @@ This can be read and written. Gives info on the number of configured hugetlb pages and on their size in the three variables HugePages_Total, HugePages_Free, Hugepagesize. .SH STANDARDS -These extinct system calls were specific to Linux on Intel processors. -.SH NOTES +Linux on Intel processors. +.SH HISTORY These system calls are gone; they existed only in Linux 2.5.36 through to Linux 2.5.54. +.SH NOTES Now the hugetlbfs filesystem can be used instead. Memory backed by huge pages (if the CPU supports them) is obtained by using diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2 index 0a82e81005..edb94989b3 100644 --- a/man2/arch_prctl.2 +++ b/man2/arch_prctl.2 @@ -133,9 +133,7 @@ is outside the process address space. .\" .SH AUTHOR .\" Man page written by Andi Kleen. .SH STANDARDS -.BR arch_prctl () -is a Linux/x86-64 extension and should not be used in programs intended -to be portable. +Linux/x86-64. .SH NOTES .BR arch_prctl () is supported only on Linux/x86-64 for 64-bit programs currently. diff --git a/man2/bdflush.2 b/man2/bdflush.2 index 6bc8442ad9..50b45084a7 100644 --- a/man2/bdflush.2 +++ b/man2/bdflush.2 @@ -93,12 +93,10 @@ or to write an invalid value to a parameter. Caller does not have the .B CAP_SYS_ADMIN capability. -.SH VERSIONS -Since glibc 2.23, glibc no longer supports this obsolete system call. .SH STANDARDS -.BR bdflush () -is Linux-specific and should not be used in programs -intended to be portable. +Linux. +.SH HISTORY +Since glibc 2.23, glibc no longer supports this obsolete system call. .SH SEE ALSO .BR sync (1), .BR fsync (2), diff --git a/man2/bind.2 b/man2/bind.2 index 47ca62f32f..1f635cb83c 100644 --- a/man2/bind.2 +++ b/man2/bind.2 @@ -185,7 +185,9 @@ A component of the path prefix is not a directory. .B EROFS The socket inode would reside on a read-only filesystem. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD .RB ( bind () first appeared in 4.2BSD). .\" SVr4 documents an additional diff --git a/man2/bpf.2 b/man2/bpf.2 index 445038e6a4..a5d08703a3 100644 --- a/man2/bpf.2 +++ b/man2/bpf.2 @@ -1052,14 +1052,10 @@ The call was made without sufficient privilege (without the .B CAP_SYS_ADMIN capability). -.SH VERSIONS -The -.BR bpf () -system call first appeared in Linux 3.18. .SH STANDARDS -The -.BR bpf () -system call is Linux-specific. +Linux. +.SH HISTORY +Linux 3.18. .SH NOTES Prior to Linux 4.4, all .BR bpf () diff --git a/man2/brk.2 b/man2/brk.2 index 31c167c569..42b32a21ae 100644 --- a/man2/brk.2 +++ b/man2/brk.2 @@ -95,6 +95,8 @@ is returned, and is set to .BR ENOMEM . .SH STANDARDS +None. +.SH HISTORY 4.3BSD; SUSv1, marked LEGACY in SUSv2, removed in POSIX.1-2001. .\" .\" .BR brk () diff --git a/man2/cacheflush.2 b/man2/cacheflush.2 index 6d44e8d6a8..aa2ea6e454 100644 --- a/man2/cacheflush.2 +++ b/man2/cacheflush.2 @@ -61,20 +61,13 @@ is not one of or .B BCACHE (but see BUGS). -.SH STANDARDS -Historically, this system call was available on all MIPS UNIX variants -including RISC/os, IRIX, Ultrix, NetBSD, OpenBSD, and FreeBSD -(and also on some non-UNIX MIPS operating systems), so that -the existence of this call in MIPS operating systems is a de-facto -standard. -.SS Caveat +.SH VERSIONS .BR cacheflush () should not be used in programs intended to be portable. On Linux, this call first appeared on the MIPS architecture, but nowadays, Linux provides a .BR cacheflush () system call on some other architectures, but with different arguments. -.SH NOTES .SS Architecture-specific variants glibc provides a wrapper for this system call, with the prototype shown in SYNOPSIS, @@ -127,6 +120,12 @@ the prototype for this built-in function uses instead of .I void * for the parameters. +.SH STANDARDS +Historically, this system call was available on all MIPS UNIX variants +including RISC/os, IRIX, Ultrix, NetBSD, OpenBSD, and FreeBSD +(and also on some non-UNIX MIPS operating systems), so that +the existence of this call in MIPS operating systems is a de-facto +standard. .SH BUGS Linux kernels older than Linux 2.6.11 ignore the .I addr diff --git a/man2/capget.2 b/man2/capget.2 index 909f8bfe0d..68d0ab672c 100644 --- a/man2/capget.2 +++ b/man2/capget.2 @@ -245,7 +245,7 @@ instead of 0.) .B ESRCH No such thread. .SH STANDARDS -These system calls are Linux-specific. +Linux. .SH NOTES The portable interface to the capability querying and setting functions is provided by the diff --git a/man2/chdir.2 b/man2/chdir.2 index 0bbff4e878..9224d336e8 100644 --- a/man2/chdir.2 +++ b/man2/chdir.2 @@ -109,7 +109,9 @@ is not a valid file descriptor. .I fd does not refer to a directory. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD. +POSIX.1-2008. +.SH HISTORY +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]). diff --git a/man2/chmod.2 b/man2/chmod.2 index 8b5db74ed7..8903901d79 100644 --- a/man2/chmod.2 +++ b/man2/chmod.2 @@ -300,17 +300,6 @@ The file is marked immutable or append-only. .B EROFS The named file resides on a read-only filesystem. .SH VERSIONS -.BR fchmodat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. -.SH STANDARDS -.BR chmod (), -.BR fchmod (): -4.4BSD, SVr4, POSIX.1-2001i, POSIX.1-2008. -.PP -.BR fchmodat (): -POSIX.1-2008. -.SH NOTES .SS C library/kernel differences The GNU C library .BR fchmodat () @@ -334,6 +323,19 @@ glibc constructs a pathname based on the symbolic link in that corresponds to the .I dirfd argument. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR chmod () +.TQ +.BR fchmod () +4.4BSD, SVr4, POSIX.1-2001. +.TP +.BR fchmodat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. .SH SEE ALSO .BR chmod (1), .BR chown (2), diff --git a/man2/chown.2 b/man2/chown.2 index d66b66f544..fe1906b7d7 100644 --- a/man2/chown.2 +++ b/man2/chown.2 @@ -278,15 +278,6 @@ The file is marked immutable or append-only. .B EROFS The named file resides on a read-only filesystem. .SH VERSIONS -.BR fchownat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. -.SH STANDARDS -.BR chown (), -.BR fchown (), -.BR lchown (): -4.4BSD, SVr4, POSIX.1-2001, POSIX.1-2008. -.PP The 4.4BSD version can be used only by the superuser (that is, ordinary users cannot give away files). .\" chown(): @@ -295,9 +286,21 @@ used only by the superuser (that is, ordinary users cannot give away files). .\" fchown(): .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK .\" error conditions. -.PP -.BR fchownat (): +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR chown () +.TQ +.BR fchown () +.TQ +.BR lchown () +4.4BSD, SVr4, POSIX.1-2001. +.TP +.BR fchownat () POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. .SH NOTES .SS Ownership of new files When a new file is created (by, for example, diff --git a/man2/chroot.2 b/man2/chroot.2 index 5f24ec4f01..9e99b1bae5 100644 --- a/man2/chroot.2 +++ b/man2/chroot.2 @@ -136,6 +136,8 @@ is not a directory. .B EPERM The caller has insufficient privilege. .SH STANDARDS +None. +.SH HISTORY SVr4, 4.4BSD, SUSv2 (marked LEGACY). This function is not part of POSIX.1-2001. .\" SVr4 documents additional EINTR, ENOLINK and EMULTIHOP error conditions. diff --git a/man2/clock_getres.2 b/man2/clock_getres.2 index ae514e622e..86a0e9afee 100644 --- a/man2/clock_getres.2 +++ b/man2/clock_getres.2 @@ -327,25 +327,6 @@ T} Thread safety MT-Safe .ad .sp 1 .SH VERSIONS -These system calls first appeared in Linux 2.6. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SUSv2. -.PP -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. -The symbols -.BR _POSIX_MONOTONIC_CLOCK , -.BR _POSIX_CPUTIME , -.B _POSIX_THREAD_CPUTIME -indicate that -.BR CLOCK_MONOTONIC , -.BR CLOCK_PROCESS_CPUTIME_ID , -.B CLOCK_THREAD_CPUTIME_ID -are available. -(See also -.BR sysconf (3).) -.SH NOTES POSIX.1 specifies the following: .RS .PP @@ -370,12 +351,32 @@ clocks using On Linux, these clocks are not settable (i.e., no process has "appropriate privileges"). .\" See http://bugzilla.kernel.org/show_bug.cgi?id=11972 -.\" .SS C library/kernel differences On some architectures, an implementation of .BR clock_gettime () is provided in the .BR vdso (7). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SUSv2. +Linux 2.6. +.PP +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. +The symbols +.BR _POSIX_MONOTONIC_CLOCK , +.BR _POSIX_CPUTIME , +.B _POSIX_THREAD_CPUTIME +indicate that +.BR CLOCK_MONOTONIC , +.BR CLOCK_PROCESS_CPUTIME_ID , +.B CLOCK_THREAD_CPUTIME_ID +are available. +(See also +.BR sysconf (3).) +POSIX.1-2008 makes thes APIs mandatory. .\" .SS Historical note for SMP systems Before Linux added kernel support for diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2 index 5da8d15699..38abca6dee 100644 --- a/man2/clock_nanosleep.2 +++ b/man2/clock_nanosleep.2 @@ -172,13 +172,12 @@ is not a permitted value for .B ENOTSUP The kernel does not support sleeping against this .IR clockid . -.SH VERSIONS -The -.BR clock_nanosleep () -system call first appeared in Linux 2.6. -Support is available since glibc 2.1. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +Linux 2.6, +glibc 2.1. .SH NOTES If the interval specified in .I request diff --git a/man2/clone.2 b/man2/clone.2 index be802a2800..42ee3fee8b 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -1553,25 +1553,7 @@ See the discussion of the .B ENOSPC error above. .SH VERSIONS -The -.BR clone3 () -system call first appeared in Linux 5.3. -.\" There is no entry for -.\" .BR clone () -.\" in libc5. -.\" glibc2 provides -.\" .BR clone () -.\" as described in this manual page. -.SH STANDARDS -These system calls -are Linux-specific and should not be used in programs -intended to be portable. -.SH NOTES -One use of these systems calls -is to implement threads: multiple flows of control in a program that -run concurrently in a shared address space. -.PP -Note that the glibc +The glibc .BR clone () wrapper function makes some changes in the memory pointed to by @@ -1587,31 +1569,10 @@ is used to recursively create children, do not use the buffer employed for the parent's stack as the stack of the child. .PP -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 -Handlers registered using -.BR pthread_atfork (3) -are not executed during a clone call. -.PP -In the Linux 2.4.x series, -.B CLONE_THREAD -generally does not make the parent of the new thread the same -as the parent of the calling process. -However, from Linux 2.4.7 to Linux 2.4.18 the -.B CLONE_THREAD -flag implied the -.B CLONE_PARENT -flag (as in Linux 2.6.0 and later). -.PP On i386, .BR clone () should not be called through vsyscall, but directly through .IR "int $0x80" . -.\" .SS C library/kernel differences The raw .BR clone () @@ -1748,7 +1709,29 @@ and .I stack_size specifies the size of the stack pointed to by .IR stack_base . +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR clone3 () +Linux 5.3. +.\" There is no entry for +.\" .BR clone () +.\" in libc5. +.\" glibc2 provides +.\" .BR clone () +.\" as described in this manual page. .SS Linux 2.4 and earlier +In the Linux 2.4.x series, +.B CLONE_THREAD +generally does not make the parent of the new thread the same +as the parent of the calling process. +However, from Linux 2.4.7 to Linux 2.4.18 the +.B CLONE_THREAD +flag implied the +.B CLONE_PARENT +flag (as in Linux 2.6.0 and later). +.PP In Linux 2.4 and earlier, .BR clone () does not take arguments @@ -1756,6 +1739,20 @@ does not take arguments .IR tls , and .IR child_tid . +.SH NOTES +One use of these systems calls +is to implement threads: multiple flows of control in a program that +run concurrently in a shared address space. +.PP +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 +Handlers registered using +.BR pthread_atfork (3) +are not executed during a clone call. .SH BUGS GNU C library versions 2.3.4 up to and including 2.24 contained a wrapper function for diff --git a/man2/close.2 b/man2/close.2 index 2fe28e003f..68211bc58c 100644 --- a/man2/close.2 +++ b/man2/close.2 @@ -81,7 +81,9 @@ See NOTES for a discussion of why .BR close () should not be retried after an error. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. .\" SVr4 documents an additional ENOLINK error condition. .SH NOTES A successful close does not guarantee that the data has been successfully diff --git a/man2/close_range.2 b/man2/close_range.2 index 9dd7ccb8a9..782719de08 100644 --- a/man2/close_range.2 +++ b/man2/close_range.2 @@ -72,13 +72,12 @@ flag is specified. .TP .B ENOMEM Insufficient kernel memory was available. -.SH VERSIONS -.BR close_range () -first appeared in Linux 5.9. -Library support was added in glibc 2.34. .SH STANDARDS -.BR close_range () -is a nonstandard function that is also present on FreeBSD. +None. +.SH HISTORY +FreeBSD. +Linux 5.9, +glibc 2.34. .SH NOTES .SS Closing all open file descriptors .\" 278a5fbaed89dacd04e9d052f4594ffd0e0585de diff --git a/man2/connect.2 b/man2/connect.2 index abd480fef8..2db2711803 100644 --- a/man2/connect.2 +++ b/man2/connect.2 @@ -213,7 +213,9 @@ busy to accept new connections. Note that for IP sockets the timeout may be very long when syncookies are enabled on the server. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD, +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD, .RB (connect () first appeared in 4.2BSD). .\" SVr4 documents the additional @@ -229,11 +231,6 @@ first appeared in 4.2BSD). .\" It also .\" documents many additional error conditions not described here. .SH NOTES -For background on the -.I socklen_t -type, see -.BR accept (2). -.PP If .BR connect () fails, consider the state of the socket as unspecified. diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2 index 34cd565177..1bade7bf73 100644 --- a/man2/copy_file_range.2 +++ b/man2/copy_file_range.2 @@ -185,12 +185,6 @@ are not on the same filesystem, and the source and target filesystems are not of the same type, or do not support cross-filesystem copy. .SH VERSIONS -The -.BR copy_file_range () -system call first appeared in Linux 4.5, but glibc 2.27 provides a user-space -emulation when it is not available. -.\" https://sourceware.org/git/?p=glibc.git;a=commit;f=posix/unistd.h;h=bad7a0c81f501fbbcc79af9eaa4b8254441c4a1f -.PP 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. @@ -204,9 +198,12 @@ See BUGS for behavior prior to Linux 5.19. Applications should target the behaviour and requirements of Linux 5.19, that was also backported to earlier stable kernels. .SH STANDARDS -The -.BR copy_file_range () -system call is a nonstandard Linux and GNU extension. +Linux, GNU. +.SH HISTORY +Linux 4.5, +but glibc 2.27 provides a user-space +emulation when it is not available. +.\" https://sourceware.org/git/?p=glibc.git;a=commit;f=posix/unistd.h;h=bad7a0c81f501fbbcc79af9eaa4b8254441c4a1f .SH NOTES If .I fd_in diff --git a/man2/create_module.2 b/man2/create_module.2 index b9163ec112..2239f05cdd 100644 --- a/man2/create_module.2 +++ b/man2/create_module.2 @@ -53,14 +53,12 @@ The caller was not privileged (did not have the .B CAP_SYS_MODULE capability). -.SH VERSIONS -This system call is present only up until Linux 2.4; -it was removed in Linux 2.6. -.\" Removed in Linux 2.5.48 .SH STANDARDS -.BR create_module () -is Linux-specific. -.SH NOTES +Linux. +.SH HISTORY +Removed in Linux 2.6. +.\" Removed in Linux 2.5.48 +.PP 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 0e0a67596a..99c26c5ef5 100644 --- a/man2/delete_module.2 +++ b/man2/delete_module.2 @@ -160,9 +160,8 @@ but the reference count of this module is nonzero and was not specified in .IR flags . .SH STANDARDS -.BR delete_module () -is Linux-specific. -.SH NOTES +Linux. +.SH HISTORY The .BR delete_module () system call is not supported by glibc. @@ -173,16 +172,6 @@ it is (before glibc 2.23) sufficient to manually declare the interface in your code; alternatively, you can invoke the system call using .BR syscall (2). -.PP -The uninterruptible sleep that may occur if -.B O_NONBLOCK -is omitted from -.I flags -is considered undesirable, because the sleeping process is left -in an unkillable state. -As at Linux 3.7, specifying -.B O_NONBLOCK -is optional, but in future kernels it is likely to become mandatory. .SS Linux 2.4 and earlier In Linux 2.4 and earlier, the system call took only one argument: .PP @@ -197,6 +186,16 @@ Some further details of differences in the behavior of in Linux 2.4 and earlier are .I not currently explained in this manual page. +.SH NOTES +The uninterruptible sleep that may occur if +.B O_NONBLOCK +is omitted from +.I flags +is considered undesirable, because the sleeping process is left +in an unkillable state. +As at Linux 3.7, specifying +.B O_NONBLOCK +is optional, but in future kernels it is likely to become mandatory. .SH SEE ALSO .BR create_module (2), .BR init_module (2), diff --git a/man2/dup.2 b/man2/dup.2 index af291c3ec3..f69922be45 100644 --- a/man2/dup.2 +++ b/man2/dup.2 @@ -197,20 +197,28 @@ The per-process limit on the number of open file descriptors has been reached .B RLIMIT_NOFILE in .BR getrlimit (2)). -.SH VERSIONS -.BR dup3 () -was added in Linux 2.6.27; -glibc support is available since glibc 2.9. .SH STANDARDS -.BR dup (), -.BR dup2 (): -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. -.PP +.TP +.BR dup () +.TQ +.BR dup2 () +POSIX.1-2008. +.TP .BR dup3 () -is Linux-specific. +Linux. +.SH HISTORY +.TP +.BR dup () +.TQ +.BR dup2 () +POSIX.1-2001, SVr4, 4.3BSD. .\" SVr4 documents additional .\" EINTR and ENOLINK error conditions. POSIX.1 adds EINTR. .\" The EBUSY return is Linux-specific. +.TP +.BR dup3 () +Linux 2.6.27, +glibc 2.9. .SH NOTES The error returned by .BR dup2 () diff --git a/man2/epoll_create.2 b/man2/epoll_create.2 index d7d92d917b..4d3566a791 100644 --- a/man2/epoll_create.2 +++ b/man2/epoll_create.2 @@ -28,7 +28,7 @@ creates a new instance. Since Linux 2.6.8, the .I size -argument is ignored, but must be greater than zero; see NOTES. +argument is ignored, but must be greater than zero; see HISTORY. .PP .BR epoll_create () returns a file descriptor referring to the new epoll instance. @@ -98,22 +98,20 @@ The system-wide limit on the total number of open files has been reached. .TP .B ENOMEM There was insufficient memory to create the kernel object. -.SH VERSIONS +.SH STANDARDS +Linux. +.SH HISTORY +.TP .BR epoll_create () -was added in Linux 2.6. -Library support is provided in glibc 2.3.2. -.PP +Linux 2.6, +glibc 2.3.2. .\" To be precise: kernel 2.5.44. .\" The interface should be finalized by Linux kernel 2.5.66. +.TP .BR epoll_create1 () -was added in Linux 2.6.27. -Library support is provided in glibc 2.9. -.SH STANDARDS -.BR epoll_create () -and -.BR epoll_create1 () -are Linux-specific. -.SH NOTES +Linux 2.6.27, +glibc 2.9. +.PP In the initial .BR epoll_create () implementation, the diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2 index f02e5ff45d..afbafee110 100644 --- a/man2/epoll_ctl.2 +++ b/man2/epoll_ctl.2 @@ -369,15 +369,13 @@ does not support This error can occur if .I fd refers to, for example, a regular file or a directory. -.SH VERSIONS -.BR epoll_ctl () -was added to in Linux 2.6. -.\" To be precise: kernel 2.5.44. -.\" The interface should be finalized by Linux kernel 2.5.66. -Library support is provided in glibc 2.3.2. .SH STANDARDS -.BR epoll_ctl () -is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6, +.\" To be precise: Linux 2.5.44. +.\" The interface should be finalized by Linux 2.5.66. +glibc 2.3.2. .SH NOTES The .B epoll diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2 index 1620cff9df..7c79afdfaa 100644 --- a/man2/epoll_wait.2 +++ b/man2/epoll_wait.2 @@ -207,25 +207,22 @@ is not an file descriptor, or .I maxevents is less than or equal to zero. -.SH VERSIONS +.SH STANDARDS +Linux. +.SH HISTORY +.TP .BR epoll_wait () -was added in Linux 2.6. -.\" To be precise: kernel 2.5.44. +Linux 2.6, +.\" To be precise: Linux 2.5.44. .\" The interface should be finalized by Linux 2.5.66. -Library support is provided in glibc 2.3.2. -.PP +glibc 2.3.2. +.TP .BR epoll_pwait () -was added in Linux 2.6.19. -Library support is provided in glibc 2.6. -.PP -.BR epoll_pwait2 () -was added in Linux 5.11. -.SH STANDARDS -.BR epoll_wait (), -.BR epoll_pwait (), -and +Linux 2.6.19, +glibc 2.6. +.TP .BR epoll_pwait2 () -are Linux-specific. +Linux 5.11. .SH NOTES While one thread is blocked in a call to .BR epoll_wait (), diff --git a/man2/eventfd.2 b/man2/eventfd.2 index 169ca9d1cd..9b7ab22b34 100644 --- a/man2/eventfd.2 +++ b/man2/eventfd.2 @@ -264,23 +264,54 @@ T} Thread safety MT-Safe .ad .sp 1 .SH VERSIONS +.SS C library/kernel differences +There are two underlying Linux system calls: +.BR eventfd () +and the more recent +.BR eventfd2 (). +The former system call does not implement a +.I flags +argument. +The latter system call implements the +.I flags +values described above. +The glibc wrapper function will use +.BR eventfd2 () +where it is available. +.SS Additional glibc features +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 +.in +4n +.EX +typedef uint64_t eventfd_t; + +int eventfd_read(int fd, eventfd_t *value); +int eventfd_write(int fd, eventfd_t value); +.EE +.in +.PP +The functions perform the read and write operations on an +eventfd file descriptor, +returning 0 if the correct number of bytes was transferred, +or \-1 otherwise. +.SH STANDARDS +Linux, GNU. +.SH HISTORY +.TP .BR eventfd () -is available since Linux 2.6.22. -Working support is provided since glibc 2.8. +Linux 2.6.22, +glibc 2.8. .\" eventfd() is in glibc 2.7, but reportedly does not build -The +.TP .BR eventfd2 () -system call (see NOTES) is available since Linux 2.6.27. +Linux 2.6.27 (see VERSIONS). Since glibc 2.9, the .BR eventfd () wrapper will employ the .BR eventfd2 () system call, if it is supported by the kernel. -.SH STANDARDS -.BR eventfd () -and -.BR eventfd2 () -are Linux-specific. .SH NOTES Applications can use an eventfd file descriptor instead of a pipe (see .BR pipe (2)) @@ -320,39 +351,6 @@ directory. See .BR proc (5) for further details. -.\" -.SS C library/kernel differences -There are two underlying Linux system calls: -.BR eventfd () -and the more recent -.BR eventfd2 (). -The former system call does not implement a -.I flags -argument. -The latter system call implements the -.I flags -values described above. -The glibc wrapper function will use -.BR eventfd2 () -where it is available. -.SS Additional glibc features -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 -.in +4n -.EX -typedef uint64_t eventfd_t; - -int eventfd_read(int fd, eventfd_t *value); -int eventfd_write(int fd, eventfd_t value); -.EE -.in -.PP -The functions perform the read and write operations on an -eventfd file descriptor, -returning 0 if the correct number of bytes was transferred, -or \-1 otherwise. .SH EXAMPLES The following program creates an eventfd file descriptor and then forks to create a child process. diff --git a/man2/execve.2 b/man2/execve.2 index 819cba3c13..20804ead73 100644 --- a/man2/execve.2 +++ b/man2/execve.2 @@ -552,44 +552,9 @@ See .TP .B ETXTBSY The specified executable was open for writing by one or more processes. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH VERSIONS POSIX does not document the #! behavior, but it exists (with some variations) on other UNIX systems. -.\" SVr4 documents additional error -.\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not -.\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, -.\" EISDIR or ELIBBAD error conditions. -.SH NOTES -One sometimes sees -.BR execve () -(and the related functions described in -.BR exec (3)) -described as "executing a -.I new -process" (or similar). -This is a highly misleading description: -there is no new process; -many attributes of the calling process remain unchanged -(in particular, its PID). -All that -.BR execve () -does is arrange for an existing process (the calling process) -to execute a new program. -.PP -Set-user-ID and set-group-ID processes can not be -.BR ptrace (2)d. -.PP -The result of mounting a filesystem -.I nosuid -varies across Linux kernel versions: -some will refuse execution of set-user-ID and set-group-ID -executables when this would -give the user powers they did not have already (and return -.BR EPERM ), -some will just ignore the set-user-ID and set-group-ID bits and -.BR exec () -successfully. .PP On Linux, .I argv @@ -623,23 +588,6 @@ resource limit changes, then the value reported by will also change, to reflect the fact that the limit on space for holding command-line arguments and environment variables has changed. -.PP -In most cases where -.BR execve () -fails, control returns to the original executable image, -and the caller of -.BR execve () -can then handle the error. -However, in (rare) cases (typically caused by resource exhaustion), -failure may occur past the point of no return: -the original executable image has been torn down, -but the new image could not be completely built. -In such cases, the kernel kills the process with a -.\" commit 19d860a140beac48a1377f179e693abe86a9dac9 -.B SIGSEGV -.RB ( SIGKILL -until Linux 3.17) -signal. .\" .SS Interpreter scripts The kernel imposes a maximum length on the text that follows the @@ -671,15 +619,72 @@ are used to delimit the arguments. .PP Linux (like most other modern UNIX systems) ignores the set-user-ID and set-group-ID bits on scripts. -.\" -.\" .SH BUGS -.\" Some Linux versions have failed to check permissions on ELF -.\" interpreters. This is a security hole, because it allows users to -.\" open any file, such as a rewinding tape device, for reading. Some -.\" Linux versions have also had other security holes in -.\" .BR execve () -.\" that could be exploited for denial of service by a suitably crafted -.\" ELF binary. There are no known problems with Linux 2.0.34 or Linux 2.2.15. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.\" SVr4 documents additional error +.\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not +.\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, +.\" EISDIR or ELIBBAD error conditions. +.PP +With UNIX\ V6, the argument list of an +.BR exec () +call was ended by 0, +while the argument list of +.I main +was ended by \-1. +Thus, this argument list was not directly usable in a further +.BR exec () +call. +Since UNIX\ V7, both are NULL. +.SH NOTES +One sometimes sees +.BR execve () +(and the related functions described in +.BR exec (3)) +described as "executing a +.I new +process" (or similar). +This is a highly misleading description: +there is no new process; +many attributes of the calling process remain unchanged +(in particular, its PID). +All that +.BR execve () +does is arrange for an existing process (the calling process) +to execute a new program. +.PP +Set-user-ID and set-group-ID processes can not be +.BR ptrace (2)d. +.PP +The result of mounting a filesystem +.I nosuid +varies across Linux kernel versions: +some will refuse execution of set-user-ID and set-group-ID +executables when this would +give the user powers they did not have already (and return +.BR EPERM ), +some will just ignore the set-user-ID and set-group-ID bits and +.BR exec () +successfully. +.PP +In most cases where +.BR execve () +fails, control returns to the original executable image, +and the caller of +.BR execve () +can then handle the error. +However, in (rare) cases (typically caused by resource exhaustion), +failure may occur past the point of no return: +the original executable image has been torn down, +but the new image could not be completely built. +In such cases, the kernel kills the process with a +.\" commit 19d860a140beac48a1377f179e693abe86a9dac9 +.B SIGSEGV +.RB ( SIGKILL +until Linux 3.17) +signal. .SS execve() and EAGAIN A more detailed explanation of the .B EAGAIN @@ -755,17 +760,6 @@ process flag. The flag is also cleared if a subsequent call to .BR fork (2) by this process succeeds. -.SS Historical -With UNIX\ V6, the argument list of an -.BR exec () -call was ended by 0, -while the argument list of -.I main -was ended by \-1. -Thus, this argument list was not directly usable in a further -.BR exec () -call. -Since UNIX\ V7, both are NULL. .\" .\" .SH BUGS .\" Some Linux versions have failed to check permissions on ELF diff --git a/man2/execveat.2 b/man2/execveat.2 index a25b3c5700..2dc45c0fde 100644 --- a/man2/execveat.2 +++ b/man2/execveat.2 @@ -145,14 +145,11 @@ See BUGS. is relative and .I dirfd is a file descriptor referring to a file other than a directory. -.SH VERSIONS -.BR execveat () -was added in Linux 3.19. -Library support was added in glibc 2.34. .SH STANDARDS -The -.BR execveat () -system call is Linux-specific. +Linux. +.SH HISTORY +Linux 3.19, +glibc 2.34. .SH NOTES In addition to the reasons explained in .BR openat (2), diff --git a/man2/exit_group.2 b/man2/exit_group.2 index f8b56d3d62..073b5135be 100644 --- a/man2/exit_group.2 +++ b/man2/exit_group.2 @@ -26,10 +26,10 @@ This system call terminates all threads in the calling process's thread group. .SH RETURN VALUE This system call does not return. -.SH VERSIONS -This call is present since Linux 2.5.35. .SH STANDARDS -This call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.5.35. .SH NOTES Since glibc 2.3, this is the system call invoked when the .BR _exit (2) diff --git a/man2/fallocate.2 b/man2/fallocate.2 index 209e1ec8b4..b9a788e4a1 100644 --- a/man2/fallocate.2 +++ b/man2/fallocate.2 @@ -463,17 +463,17 @@ or but the file referred to by .I fd is currently being executed. -.SH VERSIONS +.SH STANDARDS +Linux. +.SH HISTORY +.TP .BR fallocate () -is available since Linux 2.6.23. -Support is provided since glibc 2.10. -The +Linux 2.6.23, +glibc 2.10. +.TP .B FALLOC_FL_* -flags are defined in glibc headers only since glibc 2.18. +glibc 2.18. .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964 -.SH STANDARDS -.BR fallocate () -is Linux-specific. .SH SEE ALSO .BR fallocate (1), .BR ftruncate (2), diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 index e9c65c2806..65d73565fa 100644 --- a/man2/fanotify_init.2 +++ b/man2/fanotify_init.2 @@ -460,9 +460,6 @@ The fanotify API is available only if the kernel was configured with .B EPERM The operation is not permitted because the caller lacks a required capability. .SH VERSIONS -.BR fanotify_init () -was introduced in Linux 2.6.36 and enabled in Linux 2.6.37. -.PP Prior to Linux 5.13, .\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7 calling @@ -516,7 +513,10 @@ A user will also not receive the pid that generated the event, unless the listening process itself generated the event. .RE .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.37. +.\" was introduced in Linux 2.6.36 and enabled in Linux 2.6.37. .SH BUGS The following bug was present before Linux 3.18: .IP \[bu] 3 diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 index 5577a3888d..3f85deb23b 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -761,11 +761,11 @@ which uses a different than its root superblock. This error can be returned only with an fanotify group that identifies filesystem objects by file handles. -.SH VERSIONS -.BR fanotify_mark () -was introduced in Linux 2.6.36 and enabled in Linux 2.6.37. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.37. +.\" was introduced in Linux 2.6.36 and enabled in Linux 2.6.37. .SH NOTES .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM When using either diff --git a/man2/fcntl.2 b/man2/fcntl.2 index 3ec52dc4dc..7bb9099124 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -1810,38 +1810,7 @@ was not open for writing or the current set of seals on the file already includes .BR F_SEAL_SEAL . .SH STANDARDS -SVr4, 4.3BSD, POSIX.1-2001. -Only the operations -.BR F_DUPFD , -.BR F_GETFD , -.BR F_SETFD , -.BR F_GETFL , -.BR F_SETFL , -.BR F_GETLK , -.BR F_SETLK , -and -.B F_SETLKW -are specified in POSIX.1-2001. -.PP -.B F_GETOWN -and -.B F_SETOWN -are specified in POSIX.1-2001. -(To get their definitions, define either -.\" .BR _BSD_SOURCE , -.\" or -.B _XOPEN_SOURCE -with the value 500 or greater, or -.B _POSIX_C_SOURCE -with the value 200809L or greater.) -.PP -.B F_DUPFD_CLOEXEC -is specified in POSIX.1-2008. -(To get this definition, define -.B _POSIX_C_SOURCE -with the value 200809L or greater, or -.B _XOPEN_SOURCE -with the value 700 or greater.) +POSIX.1-2008. .PP .BR F_GETOWN_EX , .BR F_SETOWN_EX , @@ -1874,6 +1843,40 @@ and .B F_GET_SEALS are Linux-specific. .\" FIXME . Once glibc adds support, add a note about FTM requirements +.SH HISTORY +SVr4, 4.3BSD, POSIX.1-2001. +.PP +Only the operations +.BR F_DUPFD , +.BR F_GETFD , +.BR F_SETFD , +.BR F_GETFL , +.BR F_SETFL , +.BR F_GETLK , +.BR F_SETLK , +and +.B F_SETLKW +are specified in POSIX.1-2001. +.PP +.B F_GETOWN +and +.B F_SETOWN +are specified in POSIX.1-2001. +(To get their definitions, define either +.\" .BR _BSD_SOURCE , +.\" or +.B _XOPEN_SOURCE +with the value 500 or greater, or +.B _POSIX_C_SOURCE +with the value 200809L or greater.) +.PP +.B F_DUPFD_CLOEXEC +is specified in POSIX.1-2008. +(To get this definition, define +.B _POSIX_C_SOURCE +with the value 200809L or greater, or +.B _XOPEN_SOURCE +with the value 700 or greater.) .SH NOTES The errors returned by .BR dup2 (2) diff --git a/man2/flock.2 b/man2/flock.2 index 42fc1c5952..a136bcfe8d 100644 --- a/man2/flock.2 +++ b/man2/flock.2 @@ -121,16 +121,7 @@ The kernel ran out of memory for allocating lock records. The file is locked and the .B LOCK_NB flag was selected. -.SH STANDARDS -4.4BSD (the -.BR flock () -call first appeared in 4.2BSD). -A version of -.BR flock (), -possibly implemented in terms of -.BR fcntl (2), -appears on most UNIX systems. -.SH NOTES +.SH VERSIONS Since Linux 2.0, .BR flock () is implemented as a system call in its own right rather @@ -153,38 +144,43 @@ and locks .I do interact with one another.) -.PP -.BR flock () -places advisory locks only; given suitable permissions on a file, -a process is free to ignore the use of +.SS CIFS details +Up to Linux 5.4, .BR flock () -and perform I/O on the file. +is not propagated over SMB. +A file with such locks will not appear locked for remote clients. .PP +Since Linux 5.5, .BR flock () -and +locks are emulated with SMB byte-range locks on the entire file. +Similarly to NFS, this means that .BR fcntl (2) -locks have different semantics with respect to forked processes and -.BR dup (2). -On systems that implement -.BR flock () -using -.BR fcntl (2), -the semantics of +and .BR flock () -will be different from those described in this manual page. +locks interact with one another. +Another important side-effect is that the locks are not advisory anymore: +any IO on a locked file will always fail with +.B EACCES +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 -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. -Between these two steps, -a pending lock request by another process may be granted, -with the result that the conversion either blocks, or fails if -.B LOCK_NB -was specified. -(This is the original BSD behavior, -and occurs on many other implementations.) -.\" Kernel 2.5.21 changed things a little: during lock conversion -.\" it is now the highest priority process that will get the lock -- mtk +Remote and mandatory locking semantics may vary with +SMB protocol, mount options and server type. +See +.BR mount.cifs (8) +for additional information. +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD (the +.BR flock () +call first appeared in 4.2BSD). +A version of +.BR flock (), +possibly implemented in terms of +.BR fcntl (2), +appears on most UNIX systems. .SS NFS details Up to Linux 2.6.11, .BR flock () @@ -222,32 +218,38 @@ see the discussion of the .I "local_lock" option in .BR nfs (5). -.SS CIFS details -Up to Linux 5.4, +.SH NOTES .BR flock () -is not propagated over SMB. -A file with such locks will not appear locked for remote clients. +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 -Since Linux 5.5, .BR flock () -locks are emulated with SMB byte-range locks on the entire file. -Similarly to NFS, this means that -.BR fcntl (2) and +.BR fcntl (2) +locks have different semantics with respect to forked processes and +.BR dup (2). +On systems that implement .BR flock () -locks interact with one another. -Another important side-effect is that the locks are not advisory anymore: -any IO on a locked file will always fail with -.B EACCES -when done from a separate file descriptor. -This difference originates from the design of locks in the SMB protocol, -which provides mandatory locking semantics. +using +.BR fcntl (2), +the semantics of +.BR flock () +will be different from those described in this manual page. .PP -Remote and mandatory locking semantics may vary with -SMB protocol, mount options and server type. -See -.BR mount.cifs (8) -for additional information. +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. +Between these two steps, +a pending lock request by another process may be granted, +with the result that the conversion either blocks, or fails if +.B LOCK_NB +was specified. +(This is the original BSD behavior, +and occurs on many other implementations.) +.\" Kernel 2.5.21 changed things a little: during lock conversion +.\" it is now the highest priority process that will get the lock -- mtk .SH SEE ALSO .BR flock (1), .BR close (2), diff --git a/man2/fork.2 b/man2/fork.2 index 1b2498af74..15d23fef5e 100644 --- a/man2/fork.2 +++ b/man2/fork.2 @@ -259,14 +259,7 @@ hardware without a Memory-Management Unit). .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 System call was interrupted by a signal and will be restarted. (This can be seen only during a trace.) -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. -.SH NOTES -Under Linux, -.BR fork () -is implemented using copy-on-write pages, so the only penalty that it incurs -is the time and memory required to duplicate the parent's page tables, -and to create a unique task structure for the child. +.SH VERSIONS .SS C library/kernel differences Since glibc 2.3.3, .\" nptl/sysdeps/unix/sysv/linux/fork.c @@ -291,6 +284,16 @@ The glibc wrapper invokes any fork handlers that have been established using .BR pthread_atfork (3). .\" and does some magic to ensure that getpid(2) returns the right value. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +Under Linux, +.BR fork () +is implemented using copy-on-write pages, so the only penalty that it incurs +is the time and memory required to duplicate the parent's page tables, +and to create a unique task structure for the child. .SH EXAMPLES See .BR pipe (2) diff --git a/man2/fsync.2 b/man2/fsync.2 index 9dc99a15a2..1043e6a1ba 100644 --- a/man2/fsync.2 +++ b/man2/fsync.2 @@ -142,9 +142,7 @@ space at the time of a .BR write (2) system call, and some previous write failed due to insufficient storage space. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.3BSD. -.PP +.SH VERSIONS On POSIX systems on which .BR fdatasync () is available, @@ -157,12 +155,16 @@ 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. -.SH NOTES +.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 In Linux 2.2 and earlier, .BR fdatasync () diff --git a/man2/futex.2 b/man2/futex.2 index cd52254bad..92eccde5b1 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -1738,9 +1738,10 @@ and the timeout expired before the operation completed. .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .\" -.SH VERSIONS -Futexes were first made available in a stable kernel release -with Linux 2.6.0. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.0. .PP Initial futex support was merged in Linux 2.5.7 but with different semantics from what was described above. @@ -1748,19 +1749,6 @@ A four-argument system call with the semantics described in this page was introduced in Linux 2.5.40. A fifth argument was added in Linux 2.5.70, and a sixth argument was added in Linux 2.6.7. -.SH STANDARDS -This system call is Linux-specific. -.SH NOTES -Several higher-level programming abstractions are implemented via futexes, -including POSIX semaphores and -various POSIX threads synchronization mechanisms -(mutexes, condition variables, read-write locks, and barriers). -.\" TODO FIXME(Torvald) Above, we cite this section and claim it contains -.\" details on the synchronization semantics; add the C11 equivalents -.\" here (or whatever we find consensus for). -.\" -.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.\" .SH EXAMPLES The program below demonstrates use of futexes in a program where a parent process and a child process use a pair of futexes located inside a diff --git a/man2/futimesat.2 b/man2/futimesat.2 index fc25608211..6b349ce8bb 100644 --- a/man2/futimesat.2 +++ b/man2/futimesat.2 @@ -100,25 +100,26 @@ is relative and .I dirfd is a file descriptor referring to a file other than a directory. .SH VERSIONS +.SS glibc +If +.I pathname +is NULL, then the glibc .BR futimesat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. +wrapper function updates the times for the file referred to by +.IR dirfd . +.\" The Solaris futimesat() also has this strangeness. .SH STANDARDS -This system call is nonstandard. +None. +.SH HISTORY +Linux 2.6.16, +glibc 2.4. +.PP 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 A similar system call exists on Solaris. .SH NOTES -.SS glibc notes -If -.I pathname -is NULL, then the glibc -.BR futimesat () -wrapper function updates the times for the file referred to by -.IR dirfd . -.\" The Solaris futimesat() also has this strangeness. .SH SEE ALSO .BR stat (2), .BR utimensat (2), diff --git a/man2/get_kernel_syms.2 b/man2/get_kernel_syms.2 index 15e59d99ea..04f9e85e83 100644 --- a/man2/get_kernel_syms.2 +++ b/man2/get_kernel_syms.2 @@ -55,14 +55,12 @@ There is only one possible error return: .B ENOSYS .BR get_kernel_syms () is not supported in this version of the kernel. -.SH VERSIONS -This system call is present only up until Linux 2.4; -it was removed in Linux 2.6. -.\" Removed in Linux 2.5.48 .SH STANDARDS -.BR get_kernel_syms () -is Linux-specific. -.SH NOTES +Linux. +.SH HISTORY +Removed in Linux 2.6. +.\" Removed in Linux 2.5.48 +.PP 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/get_mempolicy.2 b/man2/get_mempolicy.2 index e3b942f4c7..d1c7c667ee 100644 --- a/man2/get_mempolicy.2 +++ b/man2/get_mempolicy.2 @@ -235,12 +235,10 @@ or (And there are other .B EINVAL cases.) -.SH VERSIONS -The -.BR get_mempolicy () -system call was added in Linux 2.6.7. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.7. .SH NOTES For information on library support, see .BR numa (7). diff --git a/man2/getcpu.2 b/man2/getcpu.2 index 2ef34b7c3c..629f6f15c6 100644 --- a/man2/getcpu.2 +++ b/man2/getcpu.2 @@ -64,24 +64,11 @@ is set to indicate the error. .TP .B EFAULT Arguments point outside the calling process's address space. -.SH VERSIONS -.BR getcpu () -was added in Linux 2.6.19 for x86-64 and i386. -Library support was added in glibc 2.29 -(Earlier glibc versions did not provide a wrapper for this system call, -necessitating the use of -.BR syscall (2).) .SH STANDARDS -.BR getcpu () -is Linux-specific. -.SH NOTES -Linux makes a best effort to make this call as fast as possible. -(On some architectures, this is done via an implementation in the -.BR vdso (7).) -The intention of -.BR getcpu () -is to allow programs to make optimizations with per-CPU data -or for NUMA optimization. +Linux. +.SH HISTORY +Linux 2.6.19 (x86-64 and i386), +glibc 2.29. .\" .SS C library/kernel differences The kernel system call has a third argument: @@ -148,6 +135,14 @@ migrating threads between CPUs, and so the argument is now ignored. .\" although in practice the scheduler's attempt to maintain .\" soft CPU affinity means that the information is unlikely to change .\" over the course of the caching interval. +.SH NOTES +Linux makes a best effort to make this call as fast as possible. +(On some architectures, this is done via an implementation in the +.BR vdso (7).) +The intention of +.BR getcpu () +is to allow programs to make optimizations with per-CPU data +or for NUMA optimization. .SH SEE ALSO .BR mbind (2), .BR sched_setaffinity (2), diff --git a/man2/getdents.2 b/man2/getdents.2 index 27beb7a66a..38024c33ab 100644 --- a/man2/getdents.2 +++ b/man2/getdents.2 @@ -198,19 +198,19 @@ No such directory. .B ENOTDIR File descriptor does not refer to a directory. .SH STANDARDS +None. +.SH HISTORY SVr4. .\" SVr4 documents additional ENOLINK, EIO error conditions. -.SH NOTES -Library support for +.TP .BR getdents64 () -was added in glibc 2.30; +glibc 2.30. +.SH NOTES glibc does not provide a wrapper for .BR getdents (); call .BR getdents () -(or -.BR getdents64 () -on earlier glibc versions) using +using .BR syscall (2). In that case you will need to define the .I linux_dirent diff --git a/man2/getdomainname.2 b/man2/getdomainname.2 index c26cd368f5..b5dd066e2c 100644 --- a/man2/getdomainname.2 +++ b/man2/getdomainname.2 @@ -98,14 +98,7 @@ is NULL or is longer than .I len bytes. -.SH STANDARDS -POSIX does not specify these calls. -.\" But they appear on most systems... -.SH NOTES -Since Linux 1.0, the limit on the length of a domain name, -including the terminating null byte, is 64 bytes. -In older kernels, it was 8 bytes. -.PP +.SH VERSIONS On most Linux architectures (including x86), there is no .BR getdomainname () @@ -115,6 +108,13 @@ as a library function that returns a copy of the .I domainname field returned from a call to .BR uname (2). +.SH STANDARDS +None. +.\" But they appear on most systems... +.SH HISTORY +Since Linux 1.0, the limit on the length of a domain name, +including the terminating null byte, is 64 bytes. +In older kernels, it was 8 bytes. .SH SEE ALSO .BR gethostname (2), .BR sethostname (2), diff --git a/man2/getgid.2 b/man2/getgid.2 index c76495107a..6c771bff00 100644 --- a/man2/getgid.2 +++ b/man2/getgid.2 @@ -27,9 +27,27 @@ and never modify .\" https://www.austingroupbugs.net/view.php?id=511 .\" 0000511: getuid and friends should not modify errno .IR errno . +.SH VERSIONS +On Alpha, instead of a pair of +.BR getgid () +and +.BR getegid () +system calls, a single +.BR getxgid () +system call is provided, which returns a pair of real and effective GIDs. +The glibc +.BR getgid () +and +.BR getegid () +wrapper functions transparently deal with this. +See +.BR syscall (2) +for details regarding register mapping. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.3BSD. -.SH NOTES +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.PP The original Linux .BR getgid () and @@ -45,22 +63,6 @@ The glibc and .BR getegid () wrapper functions transparently deal with the variations across kernel versions. -.PP -On Alpha, instead of a pair of -.BR getgid () -and -.BR getegid () -system calls, a single -.BR getxgid () -system call is provided, which returns a pair of real and effective GIDs. -The glibc -.BR getgid () -and -.BR getegid () -wrapper functions transparently deal with this. -See -.BR syscall (2) -for details regarding register mapping. .SH SEE ALSO .BR getresgid (2), .BR setgid (2), diff --git a/man2/getgroups.2 b/man2/getgroups.2 index 36300bf61b..83a1508efb 100644 --- a/man2/getgroups.2 +++ b/man2/getgroups.2 @@ -138,15 +138,48 @@ See the description of .IR /proc/ pid /setgroups in .BR user_namespaces (7). +.SH VERSIONS +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including the one for +.BR setgroups ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). .SH STANDARDS -.BR getgroups (): -SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. -.PP -.BR setgroups (): +.TP +.BR getgroups () +POSIX.1-2008. +.TP +.BR setgroups () +None. +.SH HISTORY +.TP +.BR getgroups () +SVr4, 4.3BSD, POSIX.1-2001. +.TP +.BR setgroups () SVr4, 4.3BSD. Since .BR setgroups () requires privilege, it is not covered by POSIX.1. +.PP +The original Linux +.BR getgroups () +system call supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR getgroups32 (), +supporting 32-bit IDs. +The glibc +.BR getgroups () +wrapper function transparently deals with the variation across kernel versions. .SH NOTES A process can have up to .B NGROUPS_MAX @@ -176,31 +209,6 @@ cannot be larger than one more than this value. Since Linux 2.6.4, the maximum number of supplementary group IDs is also exposed via the Linux-specific read-only file, .IR /proc/sys/kernel/ngroups_max . -.PP -The original Linux -.BR getgroups () -system call supported only 16-bit group IDs. -Subsequently, Linux 2.4 added -.BR getgroups32 (), -supporting 32-bit IDs. -The glibc -.BR getgroups () -wrapper function transparently deals with the variation across kernel versions. -.\" -.SS C library/kernel differences -At the kernel level, user IDs and group IDs are a per-thread attribute. -However, POSIX requires that all threads in a process -share the same credentials. -The NPTL threading implementation handles the POSIX requirements by -providing wrapper functions for -the various system calls that change process UIDs and GIDs. -These wrapper functions (including the one for -.BR setgroups ()) -employ a signal-based technique to ensure -that when one thread changes credentials, -all of the other threads in the process also change their credentials. -For details, see -.BR nptl (7). .SH SEE ALSO .BR getgid (2), .BR setgid (2), diff --git a/man2/gethostname.2 b/man2/gethostname.2 index bc74610c9c..8c32a7f688 100644 --- a/man2/gethostname.2 +++ b/man2/gethostname.2 @@ -109,13 +109,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)). -.SH STANDARDS -SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). -POSIX.1-2001 and POSIX.1-2008 specify -.BR gethostname () -but not -.BR sethostname (). -.SH NOTES +.SH VERSIONS SUSv2 guarantees that "Host names are limited to 255 bytes". POSIX.1 guarantees that "Host names (not including the terminating null byte) are limited to @@ -148,6 +142,19 @@ set to .BR ENAMETOOLONG ; in this case, a terminating null byte is not included in the returned .IR name . +.SH STANDARDS +.TP +.BR gethostname () +POSIX.1-2008. +.TP +.BR sethostname () +None. +.SH HISTORY +SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). +POSIX.1-2001 and POSIX.1-2008 specify +.BR gethostname () +but not +.BR sethostname (). .PP Versions of glibc before glibc 2.2 .\" At least glibc 2.0 and glibc 2.1, older versions not checked diff --git a/man2/getitimer.2 b/man2/getitimer.2 index f092a2fc4d..3af439efa8 100644 --- a/man2/getitimer.2 +++ b/man2/getitimer.2 @@ -159,7 +159,32 @@ or (since Linux 2.6.22) one of the fields in the structure pointed to by .I new_value contains a value outside the range [0, 999999]. +.SH VERSIONS +The standards are silent on the meaning of the call: +.PP +.in +4n +.EX +setitimer(which, NULL, &old_value); +.EE +.in +.PP +Many systems (Solaris, the BSDs, and perhaps others) +treat this as equivalent to: +.PP +.in +4n +.EX +getitimer(which, &old_value); +.EE +.in +.PP +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. +.IR "Don't use this Linux misfeature" : +it is nonportable and unnecessary. .SH STANDARDS +POSIX.1-2008. +.SH HISTORY POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD). POSIX.1-2008 marks .BR getitimer () @@ -194,29 +219,6 @@ and the three interfaces and .BR usleep (3) unspecified. -.PP -The standards are silent on the meaning of the call: -.PP -.in +4n -.EX -setitimer(which, NULL, &old_value); -.EE -.in -.PP -Many systems (Solaris, the BSDs, and perhaps others) -treat this as equivalent to: -.PP -.in +4n -.EX -getitimer(which, &old_value); -.EE -.in -.PP -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. -.IR "Don't use this Linux misfeature" : -it is nonportable and unnecessary. .SH BUGS The generation and delivery of a signal are distinct, and only one instance of each of the signals listed above may be pending diff --git a/man2/getpagesize.2 b/man2/getpagesize.2 index 39af55619b..e1c4a57556 100644 --- a/man2/getpagesize.2 +++ b/man2/getpagesize.2 @@ -37,9 +37,10 @@ returns the number of bytes in a memory page, where "page" is a fixed-length block, the unit for memory allocation and file mapping performed by .BR mmap (2). -.\" .SH HISTORY -.\" This call first appeared in 4.2BSD. .SH STANDARDS +None. +.SH HISTORY +This call first appeared in 4.2BSD. SVr4, 4.4BSD, SUSv2. In SUSv2 the .BR getpagesize () diff --git a/man2/getpeername.2 b/man2/getpeername.2 index 0a228fe143..2e79177192 100644 --- a/man2/getpeername.2 +++ b/man2/getpeername.2 @@ -76,9 +76,10 @@ The file descriptor .I sockfd does not refer to a socket. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD -.RB ( getpeername () -first appeared in 4.2BSD). +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD +(first appeared in 4.2BSD). .SH NOTES For background on the .I socklen_t diff --git a/man2/getpid.2 b/man2/getpid.2 index 49c4b7ec76..9084b261f9 100644 --- a/man2/getpid.2 +++ b/man2/getpid.2 @@ -34,26 +34,26 @@ or a "subreaper" process defined via the operation). .SH ERRORS These functions are always successful. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.3BSD, SVr4. -.SH NOTES -If the caller's parent is in a different PID namespace (see -.BR pid_namespaces (7)), +.SH VERSIONS +On Alpha, instead of a pair of +.BR getpid () +and .BR getppid () -returns 0. -.PP -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). -This contrasts with the kernel thread ID (TID), -which is unique for each thread. -For further details, see -.BR gettid (2) -and the discussion of the -.B CLONE_THREAD -flag in -.BR clone (2). -.\" +system calls, a single +.BR getxpid () +system call is provided, which returns a pair of PID and parent PID. +The glibc +.BR getpid () +and +.BR getppid () +wrapper functions transparently deal with this. +See +.BR syscall (2) +for details regarding register mapping. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD, SVr4. .SS C library/kernel differences From glibc 2.3.4 up to and including glibc 2.24, the glibc wrapper function for @@ -119,22 +119,23 @@ calls to always invoke the actual system call, rather than returning a cached value. .\" FIXME . .\" Review progress of https://bugzilla.redhat.com/show_bug.cgi?id=1469757 -.PP -On Alpha, instead of a pair of -.BR getpid () -and -.BR getppid () -system calls, a single -.BR getxpid () -system call is provided, which returns a pair of PID and parent PID. -The glibc -.BR getpid () -and +.SH NOTES +If the caller's parent is in a different PID namespace (see +.BR pid_namespaces (7)), .BR getppid () -wrapper functions transparently deal with this. -See -.BR syscall (2) -for details regarding register mapping. +returns 0. +.PP +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). +This contrasts with the kernel thread ID (TID), +which is unique for each thread. +For further details, see +.BR gettid (2) +and the discussion of the +.B CLONE_THREAD +flag in +.BR clone (2). .SH SEE ALSO .BR clone (2), .BR fork (2), diff --git a/man2/getpriority.2 b/man2/getpriority.2 index 75f8b5fc40..d27d7f9550 100644 --- a/man2/getpriority.2 +++ b/man2/getpriority.2 @@ -147,7 +147,9 @@ and .I who values specified. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). .SH NOTES For further details on the nice value, see diff --git a/man2/getrandom.2 b/man2/getrandom.2 index fb5db32bd3..dbd23a0a6c 100644 --- a/man2/getrandom.2 +++ b/man2/getrandom.2 @@ -155,12 +155,11 @@ An invalid flag was specified in The glibc wrapper function for .BR getrandom () determined that the underlying kernel does not implement this system call. -.SH VERSIONS -.BR getrandom () -was introduced in Linux 3.17. -Support was added in glibc 2.25. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 3.17, +glibc 2.25. .SH NOTES For an overview and comparison of the various interfaces that can be used to obtain randomness, see diff --git a/man2/getresuid.2 b/man2/getresuid.2 index da441d17fc..b107238c75 100644 --- a/man2/getresuid.2 +++ b/man2/getresuid.2 @@ -40,17 +40,13 @@ is set to indicate the error. .B EFAULT One of the arguments specified an address outside the calling program's address space. -.SH VERSIONS -These system calls were added on Linux 2.1.44. -.PP -The prototypes are given since glibc 2.3.2, -provided -.B _GNU_SOURCE -is defined. .SH STANDARDS -These calls are nonstandard; -they also appear on HP-UX and some of the BSDs. -.SH NOTES +None. +These calls also appear on HP-UX and some of the BSDs. +.SH HISTORY +Linux 2.1.44, +glibc 2.3.2. +.PP The original Linux .BR getresuid () and diff --git a/man2/getrlimit.2 b/man2/getrlimit.2 index fdcc9c96fe..3b923ca2a9 100644 --- a/man2/getrlimit.2 +++ b/man2/getrlimit.2 @@ -559,18 +559,15 @@ T} Thread safety MT-Safe .hy .ad .sp 1 -.SH VERSIONS -The -.BR prlimit () -system call is available since Linux 2.6.36. -Library support is available since glibc 2.13. .SH STANDARDS -.BR getrlimit (), -.BR setrlimit (): -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. -.PP -.BR prlimit (): -Linux-specific. +.TP +.BR getrlimit () +.TQ +.BR setrlimit () +POSIX.1-2008. +.TP +.BR prlimit () +Linux. .PP .B RLIMIT_MEMLOCK and @@ -587,6 +584,16 @@ it is nevertheless present on most implementations. and .B RLIMIT_SIGPENDING are Linux-specific. +.SH HISTORY +.TP +.BR getrlimit () +.TQ +.BR setrlimit () +POSIX.1-2001, SVr4, 4.3BSD. +.TP +.BR prlimit () +Linux 2.6.36, +glibc 2.13. .SH NOTES A child process created via .BR fork (2) diff --git a/man2/getrusage.2 b/man2/getrusage.2 index cbf8b2c32f..f8b3b35919 100644 --- a/man2/getrusage.2 +++ b/man2/getrusage.2 @@ -199,7 +199,8 @@ T} Thread safety MT-Safe .ad .sp 1 .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX.1-2008. +.PP POSIX.1 specifies .BR getrusage (), but specifies only the fields @@ -209,9 +210,8 @@ and .PP .B RUSAGE_THREAD is Linux-specific. -.SH NOTES -Resource usage metrics are preserved across an -.BR execve (2). +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. .PP Before Linux 2.6.9, if the disposition of .B SIGCHLD @@ -239,6 +239,9 @@ All new applications should be written using (Since Linux 2.33, glibc no longer provides an .BR vtimes () implementation.) +.SH NOTES +Resource usage metrics are preserved across an +.BR execve (2). .PP See also the description of .IR /proc/ pid /stat diff --git a/man2/getsid.2 b/man2/getsid.2 index 3afccbd9d6..eccbd47b10 100644 --- a/man2/getsid.2 +++ b/man2/getsid.2 @@ -56,15 +56,16 @@ No process with process ID .I pid was found. .SH VERSIONS -This system call is available since Linux 2.0. +Linux does not return +.BR EPERM . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +Linux 2.0. .\" Linux has this system call since Linux 1.3.44. .\" There is libc support since libc 5.2.19. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. .SH NOTES -Linux does not return -.BR EPERM . -.PP See .BR credentials (7) for a description of sessions and session IDs. diff --git a/man2/getsockname.2 b/man2/getsockname.2 index 331dadaeea..f21f43cb5f 100644 --- a/man2/getsockname.2 +++ b/man2/getsockname.2 @@ -70,9 +70,10 @@ The file descriptor .I sockfd does not refer to a socket. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD -.RB ( getsockname () -first appeared in 4.2BSD). +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD +(first appeared in 4.2BSD). .\" SVr4 documents additional ENOMEM .\" and ENOSR error codes. .SH NOTES diff --git a/man2/getsockopt.2 b/man2/getsockopt.2 index d209413a49..5031012966 100644 --- a/man2/getsockopt.2 +++ b/man2/getsockopt.2 @@ -148,8 +148,10 @@ The file descriptor .I sockfd does not refer to a socket. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, -SVr4, 4.4BSD (these system calls first appeared in 4.2BSD). +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +SVr4, 4.4BSD (first appeared in 4.2BSD). .\" SVr4 documents additional ENOMEM and ENOSR error codes, but does .\" not document the .\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO diff --git a/man2/gettid.2 b/man2/gettid.2 index ba721da488..c1fa3006fe 100644 --- a/man2/gettid.2 +++ b/man2/gettid.2 @@ -32,18 +32,11 @@ in On success, returns the thread ID of the calling thread. .SH ERRORS This call is always successful. -.SH VERSIONS -The -.BR gettid () -system call first appeared in Linux 2.4.11. -Library support was added in glibc 2.30. -(Earlier glibc versions did not provide a wrapper for this system call, -necessitating the use of -.BR syscall (2).) .SH STANDARDS -.BR gettid () -is Linux-specific and should not be used in programs that -are intended to be portable. +Linux. +.SH HISTORY +Linux 2.4.11, +glibc 2.30. .SH NOTES The thread ID returned by this call is not the same thing as a POSIX thread ID (i.e., the opaque value returned by diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2 index d7f1dbe2b9..9d134fa49d 100644 --- a/man2/gettimeofday.2 +++ b/man2/gettimeofday.2 @@ -169,7 +169,20 @@ The calling process has insufficient privilege to call under Linux the .B CAP_SYS_TIME capability is required. +.SH VERSIONS +.SS C library/kernel differences +On some architectures, an implementation of +.BR gettimeofday () +is provided in the +.BR vdso (7). .SH STANDARDS +.TP +.BR gettimeofday () +POSIX.1-2008 (obsolete). +.TP +.BR settimeofday () +None. +.SH HISTORY SVr4, 4.3BSD. POSIX.1-2001 describes .BR gettimeofday () @@ -180,31 +193,12 @@ POSIX.1-2008 marks as obsolete, recommending the use of .BR clock_gettime (2) instead. -.SH NOTES -The time returned by -.BR gettimeofday () -.I is -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 -Macros for operating on -.I timeval -structures are described in -.BR timeradd (3). .PP Traditionally, the fields of .I struct timeval were of type .IR long . .\" -.SS C library/kernel differences -On some architectures, an implementation of -.BR gettimeofday () -is provided in the -.BR vdso (7). -.\" .SS The tz_dsttime field On a non-Linux kernel, with glibc, the .I tz_dsttime @@ -264,6 +258,19 @@ this period is determined by unpredictable political decisions. So this method of representing timezones has been abandoned. +.SH NOTES +The time returned by +.BR gettimeofday () +.I is +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 +Macros for operating on +.I timeval +structures are described in +.BR timeradd (3). .SH SEE ALSO .BR date (1), .BR adjtimex (2), diff --git a/man2/getuid.2 b/man2/getuid.2 index 2ae5c73bb4..a5f3d6fe50 100644 --- a/man2/getuid.2 +++ b/man2/getuid.2 @@ -29,9 +29,10 @@ and never modify .\" 0000511: getuid and friends should not modify errno .IR errno . .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.3BSD. -.SH NOTES -.SS History +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.PP In UNIX\ V6 the .BR getuid () call returned diff --git a/man2/getunwind.2 b/man2/getunwind.2 index 99eae71212..1a2cc3ebc9 100644 --- a/man2/getunwind.2 +++ b/man2/getunwind.2 @@ -75,12 +75,11 @@ fails with the error .B EFAULT if the unwind info can't be stored in the space specified by .IR buf . -.SH VERSIONS -This system call is available since Linux 2.4. .SH STANDARDS -This system call is Linux-specific, -and is available only on the IA-64 architecture. -.SH NOTES +Linux on IA-64. +.SH HISTORY +Linux 2.4. +.PP 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 82d8c711d2..ab83421819 100644 --- a/man2/getxattr.2 +++ b/man2/getxattr.2 @@ -118,11 +118,11 @@ buffer is too small to hold the result. In addition, the errors documented in .BR stat (2) can also occur. -.SH VERSIONS -These system calls have been available since Linux 2.4; -glibc support is provided since glibc 2.3. .SH STANDARDS -These system calls are Linux-specific. +Linux. +.SH HISTORY +Linux 2.4, +glibc 2.3. .\" .SH AUTHORS .\" Andreas Gruenbacher, .\" .RI < a.gruenbacher@computer.org > diff --git a/man2/idle.2 b/man2/idle.2 index 37b936816c..689183025d 100644 --- a/man2/idle.2 +++ b/man2/idle.2 @@ -16,7 +16,7 @@ idle \- make process 0 idle .nf .B #include <unistd.h> .PP -.B int idle(void); +.B [[deprecated]] int idle(void); .fi .SH DESCRIPTION .BR idle () @@ -38,8 +38,7 @@ never returns for process 0, and always returns \-1 for a user process. .TP .B EPERM Always, for a user process. -.SH VERSIONS -Since Linux 2.3.13, this system call does not exist anymore. .SH STANDARDS -This function is Linux-specific, and should not be used in programs -intended to be portable. +Linux. +.SH HISTORY +Removed in Linux 2.3.13. diff --git a/man2/init_module.2 b/man2/init_module.2 index 0deb15ac4a..8d4831abb7 100644 --- a/man2/init_module.2 +++ b/man2/init_module.2 @@ -244,15 +244,13 @@ fails and is set to the value returned by the .I init function. -.SH VERSIONS -.BR finit_module () -is available since Linux 3.8. .SH STANDARDS -.BR init_module () -and +Linux. +.SH HISTORY +.TP .BR finit_module () -are Linux-specific. -.SH NOTES +Linux 3.8. +.PP The .BR init_module () system call is not supported by glibc. @@ -263,15 +261,6 @@ it is (before glibc 2.23) sufficient to manually declare the interface in your code; alternatively, you can invoke the system call using .BR syscall (2). -.PP -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 -See the Linux kernel source file -.I include/linux/module.h -for some useful background information. .SS Linux 2.4 and earlier In Linux 2.4 and earlier, the .BR init_module () @@ -336,6 +325,15 @@ and are expected to point within the module body and be initialized as appropriate for kernel space, that is, relocated with the rest of the module. +.SH NOTES +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 +See the Linux kernel source file +.I include/linux/module.h +for some useful background information. .SH SEE ALSO .BR create_module (2), .BR delete_module (2), diff --git a/man2/inotify_add_watch.2 b/man2/inotify_add_watch.2 index 7d60c8bd9f..548d7c9240 100644 --- a/man2/inotify_add_watch.2 +++ b/man2/inotify_add_watch.2 @@ -122,10 +122,10 @@ contains and .I pathname is not a directory. -.SH VERSIONS -Inotify was merged into the 2.6.13 Linux kernel. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.13. .SH EXAMPLES See .BR inotify (7). diff --git a/man2/inotify_init.2 b/man2/inotify_init.2 index 4f24543efe..cce298f6a5 100644 --- a/man2/inotify_init.2 +++ b/man2/inotify_init.2 @@ -80,15 +80,17 @@ The system-wide limit on the total number of open files has been reached. .TP .B ENOMEM Insufficient kernel memory is available. -.SH VERSIONS +.SH STANDARDS +Linux. +.SH HISTORY +.TP .BR inotify_init () -first appeared in Linux 2.6.13; -library support was added in glibc 2.4. +Linux 2.6.13, +glibc 2.4. +.TP .BR inotify_init1 () -was added in Linux 2.6.27; -library support was added in glibc 2.9. -.SH STANDARDS -These system calls are Linux-specific. +Linux 2.6.27, +glibc 2.9. .SH SEE ALSO .BR inotify_add_watch (2), .BR inotify_rm_watch (2), diff --git a/man2/inotify_rm_watch.2 b/man2/inotify_rm_watch.2 index 6ec0fd667c..e3dddf9058 100644 --- a/man2/inotify_rm_watch.2 +++ b/man2/inotify_rm_watch.2 @@ -50,10 +50,10 @@ The watch descriptor is not valid; or .I fd is not an inotify file descriptor. -.SH VERSIONS -Inotify was merged into the 2.6.13 Linux kernel. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.13. .SH SEE ALSO .BR inotify_add_watch (2), .BR inotify_init (2), diff --git a/man2/io_cancel.2 b/man2/io_cancel.2 index b5ad9cd2b9..5df4fb091b 100644 --- a/man2/io_cancel.2 +++ b/man2/io_cancel.2 @@ -11,7 +11,7 @@ Standard C library .PP Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); -see NOTES. +see VERSIONS. .SH SYNOPSIS .nf .BR "#include <linux/aio_abi.h>" " /* Definition of needed types */" @@ -29,7 +29,7 @@ The wrapper function provided by uses a different type for the .I ctx_id argument. -See NOTES. +See VERSIONS. .PP The .BR io_cancel () @@ -50,7 +50,7 @@ completion queue. On success, .BR io_cancel () returns 0. -For the failure return, see NOTES. +For the failure return, see VERSIONS. .SH ERRORS .TP .B EAGAIN @@ -66,12 +66,6 @@ The AIO context specified by \fIctx_id\fP is invalid. .BR io_cancel () is not implemented on this architecture. .SH VERSIONS -The asynchronous I/O system calls first appeared in Linux 2.5. -.SH STANDARDS -.BR io_cancel () -is Linux-specific and should not be used -in programs that are intended to be portable. -.SH NOTES You probably want to use the .BR io_cancel () wrapper function provided by @@ -98,6 +92,10 @@ then the return value follows the usual conventions for indicating an error: \-1, with .I errno set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. .SH SEE ALSO .BR io_destroy (2), .BR io_getevents (2), diff --git a/man2/io_destroy.2 b/man2/io_destroy.2 index 783d57397c..a94600c5f1 100644 --- a/man2/io_destroy.2 +++ b/man2/io_destroy.2 @@ -30,7 +30,7 @@ The wrapper function provided by uses a different type for the .I ctx_id argument. -See NOTES. +See VERSIONS. .PP The .BR io_destroy () @@ -44,7 +44,7 @@ that could not be canceled, and will destroy the On success, .BR io_destroy () returns 0. -For the failure return, see NOTES. +For the failure return, see VERSIONS. .SH ERRORS .TP .B EFAULT @@ -57,12 +57,6 @@ The AIO context specified by \fIctx_id\fP is invalid. .BR io_destroy () is not implemented on this architecture. .SH VERSIONS -The asynchronous I/O system calls first appeared in Linux 2.5. -.SH STANDARDS -.BR io_destroy () -is Linux-specific and should not be used in programs -that are intended to be portable. -.SH NOTES You probably want to use the .BR io_destroy () wrapper function provided by @@ -89,6 +83,10 @@ then the return value follows the usual conventions for indicating an error: \-1, with .I errno set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. .SH SEE ALSO .BR io_cancel (2), .BR io_getevents (2), diff --git a/man2/io_getevents.2 b/man2/io_getevents.2 index 489a6a8aa4..0f7c7eea62 100644 --- a/man2/io_getevents.2 +++ b/man2/io_getevents.2 @@ -8,6 +8,10 @@ io_getevents \- read asynchronous I/O events from the completion queue .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) +.PP +Alternatively, Asynchronous I/O library +.RI ( libaio ", " \-laio ); +see VERSIONS. .SH SYNOPSIS .nf .BR "#include <linux/aio_abi.h>" " /* Definition of " *io_* " types */" @@ -32,7 +36,7 @@ The wrapper function provided by uses a different type for the .I ctx_id argument. -See NOTES. +See VERSIONS. .PP The .BR io_getevents () @@ -67,7 +71,7 @@ It may also be a nonzero value less than .IR min_nr , if the call was interrupted by a signal handler. .PP -For the failure return, see NOTES. +For the failure return, see VERSIONS. .SH ERRORS .TP .B EFAULT @@ -86,12 +90,6 @@ out of range. .BR io_getevents () is not implemented on this architecture. .SH VERSIONS -The asynchronous I/O system calls first appeared in Linux 2.5. -.SH STANDARDS -.BR io_getevents () -is Linux-specific and should not be used in -programs that are intended to be portable. -.SH NOTES You probably want to use the .BR io_getevents () wrapper function provided by @@ -118,6 +116,10 @@ then the return value follows the usual conventions for indicating an error: \-1, with .I errno set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. .SH BUGS An invalid .I ctx_id diff --git a/man2/io_setup.2 b/man2/io_setup.2 index 006f4964f6..2c3a760bde 100644 --- a/man2/io_setup.2 +++ b/man2/io_setup.2 @@ -11,7 +11,7 @@ Standard C library .PP Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); -see NOTES. +see VERSIONS. .SH SYNOPSIS .nf .BR "#include <linux/aio_abi.h>" " /* Defines needed types */" @@ -20,7 +20,7 @@ see NOTES. .fi .PP .IR Note : -There is no glibc wrapper for this system call; see NOTES. +There is no glibc wrapper for this system call; see VERSIONS. .SH DESCRIPTION .IR Note : this page describes the raw Linux system call interface. @@ -29,7 +29,7 @@ The wrapper function provided by uses a different type for the .I ctx_idp argument. -See NOTES. +See VERSIONS. .PP The .BR io_setup () @@ -46,7 +46,7 @@ with the resulting handle. On success, .BR io_setup () returns 0. -For the failure return, see NOTES. +For the failure return, see VERSIONS. .SH ERRORS .TP .B EAGAIN @@ -71,12 +71,6 @@ Insufficient kernel resources are available. .BR io_setup () is not implemented on this architecture. .SH VERSIONS -The asynchronous I/O system calls first appeared in Linux 2.5. -.SH STANDARDS -.BR io_setup () -is Linux-specific and should not be used in programs -that are intended to be portable. -.SH NOTES glibc does not provide a wrapper for this system call. You could invoke it using .BR syscall (2). @@ -106,6 +100,10 @@ then the return value follows the usual conventions for indicating an error: \-1, with .I errno set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. .SH SEE ALSO .BR io_cancel (2), .BR io_destroy (2), diff --git a/man2/io_submit.2 b/man2/io_submit.2 index ab1011ebf8..879ae9d4c7 100644 --- a/man2/io_submit.2 +++ b/man2/io_submit.2 @@ -12,7 +12,7 @@ Standard C library .PP Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); -see NOTES. +see VERSIONS. .SH SYNOPSIS .nf .BR "#include <linux/aio_abi.h>" " /* Defines needed types */" @@ -22,7 +22,7 @@ see NOTES. .fi .PP .IR Note : -There is no glibc wrapper for this system call; see NOTES. +There is no glibc wrapper for this system call; see VERSIONS. .SH DESCRIPTION .IR Note : this page describes the raw Linux system call interface. @@ -31,7 +31,7 @@ The wrapper function provided by uses a different type for the .I ctx_id argument. -See NOTES. +See VERSIONS. .PP The .BR io_submit () @@ -211,7 +211,7 @@ On success, .BR io_submit () returns the number of \fIiocb\fPs submitted (which may be less than \fInr\fP, or 0 if \fInr\fP is zero). -For the failure return, see NOTES. +For the failure return, see VERSIONS. .SH ERRORS .TP .B EAGAIN @@ -246,12 +246,6 @@ but the submitting context does not have the .B CAP_SYS_ADMIN capability. .SH VERSIONS -The asynchronous I/O system calls first appeared in Linux 2.5. -.SH STANDARDS -.BR io_submit () -is Linux-specific and should not be used in -programs that are intended to be portable. -.SH NOTES glibc does not provide a wrapper for this system call. You could invoke it using .BR syscall (2). @@ -281,6 +275,10 @@ then the return value follows the usual conventions for indicating an error: \-1, with .I errno set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. .SH SEE ALSO .BR io_cancel (2), .BR io_destroy (2), diff --git a/man2/ioctl.2 b/man2/ioctl.2 index f33f2c57c1..6b55d47c99 100644 --- a/man2/ioctl.2 +++ b/man2/ioctl.2 @@ -94,17 +94,16 @@ The specified request does not apply to the kind of object that the file descriptor .I fd references. -.SH STANDARDS -No single standard. +.SH VERSIONS Arguments, returns, and semantics of .BR ioctl () vary according to the device driver in question (the call is used as a catch-all for operations that don't cleanly fit the UNIX stream I/O model). -.PP -The -.BR ioctl () -system call appeared in Version 7 AT&T UNIX. +.SH STANDARDS +None. +.SH HISTORY +Version\~7 AT&T UNIX. .SH NOTES In order to use this call, one needs an open file descriptor. Often the diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2 index 24b383f679..d00855095b 100644 --- a/man2/ioctl_fat.2 +++ b/man2/ioctl_fat.2 @@ -208,25 +208,24 @@ does not refer to an object in a FAT filesystem. .PP For further error values, see .BR ioctl (2). -.SH VERSIONS +.SH STANDARDS +Linux. +.SH HISTORY +.TP .B VFAT_IOCTL_READDIR_BOTH -and +.TQ .B VFAT_IOCTL_READDIR_SHORT -first appeared in Linux 2.0. -.PP +Linux 2.0. +.TP .B FAT_IOCTL_GET_ATTRIBUTES -and +.TQ .B FAT_IOCTL_SET_ATTRIBUTES -first appeared .\" just before we got Git history -in Linux 2.6.12. -.PP +Linux 2.6.12. +.TP .B FAT_IOCTL_GET_VOLUME_ID -was introduced in version 3.11 +Linux 3.11. .\" commit 6e5b93ee55d401f1619092fb675b57c28c9ed7ec -of the Linux kernel. -.SH STANDARDS -This API is Linux-specific. .SH EXAMPLES .SS Toggling the archive flag The following program demonstrates the usage of diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2 index bd6f4220ee..7d823dde76 100644 --- a/man2/ioctl_ficlonerange.2 +++ b/man2/ioctl_ficlonerange.2 @@ -110,15 +110,16 @@ Swap files cannot share storage. .B EXDEV .IR dest_fd " and " src_fd are not on the same mounted filesystem. -.SH VERSIONS -These ioctl operations first appeared in Linux 4.5. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.5. +.PP They were previously known as .B BTRFS_IOC_CLONE and .BR BTRFS_IOC_CLONE_RANGE , and were private to Btrfs. -.SH STANDARDS -This API is Linux-specific. .SH NOTES Because a copy-on-write operation requires the allocation of new storage, the .BR fallocate (2) diff --git a/man2/ioctl_fideduperange.2 b/man2/ioctl_fideduperange.2 index 117e85d73f..34623cf7b6 100644 --- a/man2/ioctl_fideduperange.2 +++ b/man2/ioctl_fideduperange.2 @@ -181,19 +181,20 @@ and .I src_fd are not on the same mounted filesystem. .SH VERSIONS -This ioctl operation first appeared in Linux 4.5. +Some filesystems may limit the amount of data that can be deduplicated in a +single call. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.5. +.PP It was previously known as .B BTRFS_IOC_FILE_EXTENT_SAME and was private to Btrfs. -.SH STANDARDS -This API is Linux-specific. .SH NOTES Because a copy-on-write operation requires the allocation of new storage, the .BR fallocate (2) operation may unshare shared blocks to guarantee that subsequent writes will not fail because of lack of disk space. -.PP -Some filesystems may limit the amount of data that can be deduplicated in a -single call. .SH SEE ALSO .BR ioctl (2) diff --git a/man2/ioctl_fslabel.2 b/man2/ioctl_fslabel.2 index a614c800e7..a7c854c6aa 100644 --- a/man2/ioctl_fslabel.2 +++ b/man2/ioctl_fslabel.2 @@ -46,17 +46,16 @@ This can appear if the filesystem does not support online label manipulation. .TP .B EPERM The calling process does not have sufficient permissions to set the label. -.SH VERSIONS -These -.BR ioctl (2) -operations first appeared in Linux 4.18. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.18. +.PP They were previously known as .B BTRFS_IOC_GET_FSLABEL and .B BTRFS_IOC_SET_FSLABEL and were private to Btrfs. -.SH STANDARDS -This API is Linux-specific. .SH NOTES The maximum string length for this interface is .BR FSLABEL_MAX , diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2 index 36d284d452..093f206919 100644 --- a/man2/ioctl_getfsmap.2 +++ b/man2/ioctl_getfsmap.2 @@ -335,13 +335,12 @@ The filesystem does not support this command. .TP .B EUCLEAN The filesystem metadata is corrupt and needs repair. -.SH VERSIONS -The -.B FS_IOC_GETFSMAP -operation first appeared in Linux 4.12. .SH STANDARDS -This API is Linux-specific. +Linux. +.PP Not all filesystems support it. +.SH HISTORY +Linux 4.12. .SH EXAMPLES See .I io/fsmap.c diff --git a/man2/ioctl_iflags.2 b/man2/ioctl_iflags.2 index bf3840ecb6..19d2461477 100644 --- a/man2/ioctl_iflags.2 +++ b/man2/ioctl_iflags.2 @@ -171,7 +171,7 @@ which is not inheritable, and .BR FS_DIRSYNC_FL , which is inherited only by subdirectories. .SH STANDARDS -Inode flags are a nonstandard Linux extension. +Linux. .SH NOTES In order to change the inode flags of a file using the .B FS_IOC_SETFLAGS diff --git a/man2/ioctl_ns.2 b/man2/ioctl_ns.2 index b55c4df193..ff2df48357 100644 --- a/man2/ioctl_ns.2 +++ b/man2/ioctl_ns.2 @@ -165,7 +165,7 @@ does not refer to a .I /proc/[pid]/ns/* file. .SH STANDARDS -Namespaces and the operations described on this page are a Linux-specific. +Linux. .SH EXAMPLES The example shown below uses the .BR ioctl (2) diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 index a78353c548..06e754cea0 100644 --- a/man2/ioctl_userfaultfd.2 +++ b/man2/ioctl_userfaultfd.2 @@ -876,9 +876,7 @@ The userfaultfd object has not yet been enabled (via the .B UFFDIO_API operation). .SH STANDARDS -These -.BR ioctl (2) -operations are Linux-specific. +Linux. .SH BUGS In order to detect available userfault features and enable some subset of those features diff --git a/man2/ioperm.2 b/man2/ioperm.2 index 3e30159c4f..41c451ef1d 100644 --- a/man2/ioperm.2 +++ b/man2/ioperm.2 @@ -81,19 +81,7 @@ Out of memory. .TP .B EPERM The calling thread has insufficient privilege. -.SH STANDARDS -.BR ioperm () -is Linux-specific and should not be used in programs -intended to be portable. -.SH NOTES -The -.I /proc/ioports -file shows the I/O ports that are currently allocated on the system. -.PP -Before Linux 2.4, -permissions were not inherited by a child created by -.BR fork (2). -.PP +.SH VERSIONS glibc has an .BR ioperm () prototype both in @@ -101,6 +89,16 @@ prototype both in and in .IR <sys/perm.h> . Avoid the latter, it is available on i386 only. +.SH STANDARDS +Linux. +.SH HISTORY +Before Linux 2.4, +permissions were not inherited by a child created by +.BR fork (2). +.SH NOTES +The +.I /proc/ioports +file shows the I/O ports that are currently allocated on the system. .SH SEE ALSO .BR iopl (2), .BR outb (2), diff --git a/man2/iopl.2 b/man2/iopl.2 index abf1bef675..2ed1d038c0 100644 --- a/man2/iopl.2 +++ b/man2/iopl.2 @@ -59,11 +59,7 @@ the .B CAP_SYS_RAWIO capability is required to raise the I/O privilege level above its current value. -.SH STANDARDS -.BR iopl () -is Linux-specific and should not be used in programs that are -intended to be portable. -.SH NOTES +.SH VERSIONS .\" Libc5 treats it as a system call and has a prototype in .\" .IR <unistd.h> . .\" glibc1 does not have a prototype. @@ -72,7 +68,9 @@ glibc2 has a prototype both in and in .IR <sys/perm.h> . Avoid the latter, it is available on i386 only. -.PP +.SH STANDARDS +Linux. +.SH HISTORY Prior to Linux 5.5 .BR iopl () allowed the thread to disable interrupts while running diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2 index 8f964af68d..3cd15b47d8 100644 --- a/man2/ioprio_set.2 +++ b/man2/ioprio_set.2 @@ -188,11 +188,10 @@ No process(es) could be found that matched the specification in .I which and .IR who . -.SH VERSIONS -These system calls have been available on Linux since -kernel 2.6.13. .SH STANDARDS -These system calls are Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.13. .SH NOTES Two or more processes or threads can share an I/O context. This will be the case when diff --git a/man2/ipc.2 b/man2/ipc.2 index ca61cda682..45671dd93f 100644 --- a/man2/ipc.2 +++ b/man2/ipc.2 @@ -37,11 +37,7 @@ the other arguments are passed through to the appropriate call. 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 (). -.SH STANDARDS -.BR ipc () -is Linux-specific, and should not be used in programs -intended to be portable. -.SH NOTES +.SH VERSIONS On some architectures\[em]for example x86-64 and ARM\[em]there is no .BR ipc () system call; instead, @@ -49,6 +45,8 @@ system call; instead, .BR semctl (2), .BR shmctl (2), and so on really are implemented as separate system calls. +.SH STANDARDS +Linux. .SH SEE ALSO .BR msgctl (2), .BR msgget (2), diff --git a/man2/kcmp.2 b/man2/kcmp.2 index f9b177f632..7c02b5c442 100644 --- a/man2/kcmp.2 +++ b/man2/kcmp.2 @@ -287,14 +287,11 @@ Process or .I pid2 does not exist. -.SH VERSIONS -The -.BR kcmp () -system call first appeared in Linux 3.5. .SH STANDARDS -.BR kcmp () -is Linux-specific and should not be used in programs intended to be portable. -.SH NOTES +Linux. +.SH HISTORY +Linux 3.5. +.PP Before Linux 5.12, this system call is available only if the kernel is configured with .BR CONFIG_CHECKPOINT_RESTORE , @@ -307,7 +304,7 @@ filesystem; this was deemed to be unsuitable for security reasons.) Since Linux 5.12, this system call is also available if the kernel is configured with .BR CONFIG_KCMP . -.PP +.SH NOTES See .BR clone (2) for some background information on the shared resources diff --git a/man2/kexec_load.2 b/man2/kexec_load.2 index b5a9935db9..3063f4364d 100644 --- a/man2/kexec_load.2 +++ b/man2/kexec_load.2 @@ -311,15 +311,15 @@ Could not allocate memory. The caller does not have the .B CAP_SYS_BOOT capability. -.SH VERSIONS -The +.SH STANDARDS +Linux. +.SH HISTORY +.TP .BR kexec_load () -system call first appeared in Linux 2.6.13. -The +Linux 2.6.13. +.TP .BR kexec_file_load () -system call first appeared in Linux 3.17. -.SH STANDARDS -These system calls are Linux-specific. +Linux 3.17. .SH SEE ALSO .BR reboot (2), .BR syscall (2), diff --git a/man2/keyctl.2 b/man2/keyctl.2 index 4ce87dcf31..ef0729de6b 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -14,7 +14,7 @@ Standard C library .PP Alternatively, Linux Key Management Utilities .RI ( libkeyutils ", " \-lkeyutils ); -see NOTES. +see VERSIONS. .SH SYNOPSIS .nf .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */" @@ -1947,10 +1947,6 @@ was .B KEYCTL_DH_COMPUTE and the initialization of crypto modules has timed out. .SH VERSIONS -This system call first appeared in Linux 2.6.10. -.SH STANDARDS -This system call is a nonstandard Linux extension. -.SH NOTES A wrapper is provided in the .I libkeyutils library. @@ -1960,6 +1956,10 @@ header file.) However, rather than using this system call directly, you probably want to use the various library functions mentioned in the descriptions of individual operations above. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.10. .SH EXAMPLES The program below provide subset of the functionality of the .BR request\-key (8) diff --git a/man2/kill.2 b/man2/kill.2 index def4a99b66..b3a6e012d2 100644 --- a/man2/kill.2 +++ b/man2/kill.2 @@ -100,7 +100,23 @@ has not yet been .BR wait (2)ed for. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SS Linux notes +Across different kernel versions, Linux has enforced different rules +for the permissions required for an unprivileged process +to send a signal to another process. +.\" In the 0.* kernels things chopped and changed quite +.\" a bit - MTK, 24 Jul 02 +In Linux 1.0 to 1.2.2, a signal could be sent if the +effective user ID of the sender matched effective user ID of the target, +or the real user ID of the sender matched the real user ID of the target. +From Linux 1.2.3 until 1.3.77, a signal could be sent if the +effective user ID of the sender matched either the real or effective +user ID of the target. +The current rules, which conform to POSIX.1, were adopted +in Linux 1.3.78. .SH NOTES The only signals that can be sent to process ID 1, the .I init @@ -125,20 +141,6 @@ at least one unblocked signal must be delivered to the sending thread before the .BR kill () returns. -.SS Linux notes -Across different kernel versions, Linux has enforced different rules -for the permissions required for an unprivileged process -to send a signal to another process. -.\" In the 0.* kernels things chopped and changed quite -.\" a bit - MTK, 24 Jul 02 -In Linux 1.0 to 1.2.2, a signal could be sent if the -effective user ID of the sender matched effective user ID of the target, -or the real user ID of the sender matched the real user ID of the target. -From Linux 1.2.3 until 1.3.77, a signal could be sent if the -effective user ID of the sender matched either the real or effective -user ID of the target. -The current rules, which conform to POSIX.1, were adopted -in Linux 1.3.78. .SH BUGS In Linux 2.6 up to and including Linux 2.6.7, there was a bug that meant that when sending signals to a process group, diff --git a/man2/landlock_add_rule.2 b/man2/landlock_add_rule.2 index 871621348e..43a70a2a56 100644 --- a/man2/landlock_add_rule.2 +++ b/man2/landlock_add_rule.2 @@ -118,10 +118,10 @@ has no write access to the underlying ruleset. .B EFAULT .I rule_attr was not a valid address. -.SH VERSIONS -Landlock was added in Linux 5.13. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 5.13. .SH EXAMPLES See .BR landlock (7). diff --git a/man2/landlock_create_ruleset.2 b/man2/landlock_create_ruleset.2 index 8c83813ec9..902862f7f7 100644 --- a/man2/landlock_create_ruleset.2 +++ b/man2/landlock_create_ruleset.2 @@ -111,10 +111,10 @@ was not a valid address. Empty accesses (i.e., .I attr\->handled_access_fs is 0). -.SH VERSIONS -Landlock was added in Linux 5.13. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 5.13. .SH EXAMPLES See .BR landlock (7). diff --git a/man2/landlock_restrict_self.2 b/man2/landlock_restrict_self.2 index 1c41bb6109..6cf900f0b6 100644 --- a/man2/landlock_restrict_self.2 +++ b/man2/landlock_restrict_self.2 @@ -103,10 +103,10 @@ in its user namespace. .B E2BIG The maximum number of composed rulesets is reached for the calling thread. This limit is currently 64. -.SH VERSIONS -Landlock was added in Linux 5.13. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 5.13. .SH EXAMPLES See .BR landlock (7). diff --git a/man2/link.2 b/man2/link.2 index 60b739eba1..6271934bdd 100644 --- a/man2/link.2 +++ b/man2/link.2 @@ -335,26 +335,6 @@ is an empty string, and .I olddirfd refers to a directory. .SH VERSIONS -.BR linkat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. -.SH STANDARDS -.BR link (): -SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES), POSIX.1-2008. -.\" SVr4 documents additional ENOLINK and -.\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP. -.\" X/OPEN does not document EFAULT, ENOMEM or EIO. -.PP -.BR linkat (): -POSIX.1-2008. -.SH NOTES -Hard links, as created by -.BR link (), -cannot span filesystems. -Use -.BR symlink (2) -if this is required. -.PP POSIX.1-2001 says that .BR link () should dereference @@ -385,7 +365,7 @@ is dereferenced if it is a symbolic link. For precise control over the treatment of symbolic links when creating a link, use .BR linkat (). -.SS glibc notes +.SS glibc On older kernels where .BR linkat () is unavailable, the glibc wrapper function falls back to the use of @@ -405,6 +385,29 @@ that correspond to the and .I newdirfd arguments. +.SH STANDARDS +.TP +.BR link () +POSIX.1-2008. +.SH HISTORY +.TP +.BR link () +SVr4, 4.3BSD, POSIX.1-2001 (but see VERSIONS). +.\" SVr4 documents additional ENOLINK and +.\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP. +.\" X/OPEN does not document EFAULT, ENOMEM or EIO. +.TP +.BR linkat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.SH NOTES +Hard links, as created by +.BR link (), +cannot span filesystems. +Use +.BR symlink (2) +if this is required. .SH BUGS On NFS filesystems, the return code may be wrong in case the NFS server performs the link creation and dies before it can say so. diff --git a/man2/listen.2 b/man2/listen.2 index 615ded424f..4823143579 100644 --- a/man2/listen.2 +++ b/man2/listen.2 @@ -90,9 +90,10 @@ The socket is not of a type that supports the .BR listen () operation. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.4BSD -.RB ( listen () -first appeared in 4.2BSD). +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.4BSD +(first appeared in 4.2BSD). .SH NOTES To accept connections, the following steps are performed: .RS 4 diff --git a/man2/listxattr.2 b/man2/listxattr.2 index f1580573f2..3387c64939 100644 --- a/man2/listxattr.2 +++ b/man2/listxattr.2 @@ -133,11 +133,11 @@ buffer is too small to hold the result. In addition, the errors documented in .BR stat (2) can also occur. -.SH VERSIONS -These system calls have been available since Linux 2.4; -glibc support is provided since glibc 2.3. .SH STANDARDS -These system calls are Linux-specific. +Linux. +.SH HISTORY +Linux 2.4, +glibc 2.3. .\" .SH AUTHORS .\" Andreas Gruenbacher, .\" .RI < a.gruenbacher@computer.org > diff --git a/man2/llseek.2 b/man2/llseek.2 index 49b5808530..d317ed1e1a 100644 --- a/man2/llseek.2 +++ b/man2/llseek.2 @@ -80,13 +80,12 @@ Problem with copying results to user space. .B EINVAL .I whence is invalid. -.SH STANDARDS -This function is Linux-specific, and should not be used in programs -intended to be portable. -.SH NOTES +.SH VERSIONS You probably want to use the .BR lseek (2) wrapper function instead. +.SH STANDARDS +Linux. .SH SEE ALSO .BR lseek (2), .BR open (2), diff --git a/man2/lookup_dcookie.2 b/man2/lookup_dcookie.2 index d151465071..82c1ef3a75 100644 --- a/man2/lookup_dcookie.2 +++ b/man2/lookup_dcookie.2 @@ -65,14 +65,14 @@ required to look up cookie values. .TP .B ERANGE The buffer was not large enough to hold the path of the directory entry. -.SH VERSIONS -Available since Linux 2.5.43. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5.43. +.PP The .B ENAMETOOLONG -error return was added in Linux 2.5.70. -.SH STANDARDS -.BR lookup_dcookie () -is Linux-specific. +error was added in Linux 2.5.70. .SH NOTES .BR lookup_dcookie () is a special-purpose system call, currently used only by the diff --git a/man2/lseek.2 b/man2/lseek.2 index 8b184cecea..ae46244af3 100644 --- a/man2/lseek.2 +++ b/man2/lseek.2 @@ -205,8 +205,17 @@ The resulting file offset cannot be represented in an .B ESPIPE .I fd is associated with a pipe, socket, or FIFO. +.SH VERSIONS +On Linux, using +.BR lseek () +on a terminal device fails with the error +.BR ESPIPE . +.\" Other systems return the number of written characters, +.\" using SEEK_SET to set the counter. (Of written characters.) .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. .PP .B SEEK_DATA and @@ -230,20 +239,9 @@ then a moves the file offset to the end of the file, regardless of the use of .BR lseek (). .PP -The -.I off_t -data type is a signed integer data type specified by POSIX.1. -.PP Some devices are incapable of seeking and POSIX does not specify which devices must support .BR lseek (). -.PP -On Linux, using -.BR lseek () -on a terminal device fails with the error -\fBESPIPE\fP. -.\" Other systems return the number of written characters, -.\" using SEEK_SET to set the counter. (Of written characters.) .SH SEE ALSO .BR dup (2), .BR fallocate (2), diff --git a/man2/madvise.2 b/man2/madvise.2 index 9b4652a635..46fd8763be 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -838,15 +838,6 @@ be created using the flag described elsewhere in this page) was encountered. .SH VERSIONS -Since Linux 3.18, -.\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb -support for this system call is optional, -depending on the setting of the -.B CONFIG_ADVISE_SYSCALLS -configuration option. -.SH STANDARDS -.BR madvise () -is not specified by any standards. Versions of this system call, implementing a wide variety of .I advice values, exist on many other implementations. @@ -865,8 +856,7 @@ with constants and .BR POSIX_MADV_DONTNEED , and so on, with behavior close to the similarly named flags listed above. -.SH NOTES -.SS Linux notes +.SS Linux The Linux implementation requires that the address .I addr be page-aligned, and allows @@ -883,10 +873,17 @@ from the system call, as it should). will return zero iff .I advice is supported by the kernel and can be relied on to probe for support. -.\" .SH HISTORY -.\" The -.\" .BR madvise () -.\" function first appeared in 4.4BSD. +.SH STANDARDS +None. +.SH HISTORY +First appeared in 4.4BSD. +.PP +Since Linux 3.18, +.\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb +support for this system call is optional, +depending on the setting of the +.B CONFIG_ADVISE_SYSCALLS +configuration option. .SH SEE ALSO .BR getrlimit (2), .BR memfd_secret (2), diff --git a/man2/mbind.2 b/man2/mbind.2 index 5eecb11f6d..d540bbe232 100644 --- a/man2/mbind.2 +++ b/man2/mbind.2 @@ -420,12 +420,24 @@ flag and the caller does not have the .B CAP_SYS_NICE privilege. .\" --------------------------------------------------------------- -.SH VERSIONS -The -.BR mbind () -system call was added in Linux 2.6.7. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.7. +.PP +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 +Before Linux 5.7. +.\" commit dcf1763546d76c372f3136c8d6b2b6e77f140cf0 +.B MPOL_MF_STRICT +was ignored on huge page mappings. +.PP +.B MPOL_MF_MOVE +and +.B MPOL_MF_MOVE_ALL +are available only on Linux 2.6.16 and later. .SH NOTES For information on library support, see .BR numa (7). @@ -468,20 +480,6 @@ with an empty set of nodes. This method will work for .BR set_mempolicy (2), as well. -.PP -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 -Before Linux 5.7. -.\" commit dcf1763546d76c372f3136c8d6b2b6e77f140cf0 -.B MPOL_MF_STRICT -was ignored on huge page mappings. -.PP -.B MPOL_MF_MOVE -and -.B MPOL_MF_MOVE_ALL -are available only on Linux 2.6.16 and later. .SH SEE ALSO .BR get_mempolicy (2), .BR getcpu (2), diff --git a/man2/membarrier.2 b/man2/membarrier.2 index 390c774b9f..1df4249b5e 100644 --- a/man2/membarrier.2 +++ b/man2/membarrier.2 @@ -280,27 +280,18 @@ system call is not implemented by this kernel. .B EPERM The current process was not registered prior to using private expedited commands. -.SH VERSIONS -The -.BR membarrier () -system call was added in Linux 4.3. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.3. .PP -Before Linux 5.10, the prototype for -.BR membarrier () -was: +Before Linux 5.10, the prototype was: .PP .in +4n .EX .BI "int membarrier(int " cmd ", int " flags ); .EE .in -.SH STANDARDS -.BR membarrier () -is Linux-specific. -.\" .SH SEE ALSO -.\" FIXME See if the following syscalls make it into Linux 4.15 or later -.\" .BR cpu_opv (2), -.\" .BR rseq (2) .SH NOTES A memory barrier instruction is part of the instruction set of architectures with weakly ordered memory models. @@ -463,3 +454,7 @@ main(int argc, char *argv[]) } .EE .in +.\" .SH SEE ALSO +.\" FIXME See if the following syscalls make it into Linux 4.15 or later +.\" .BR cpu_opv (2), +.\" .BR rseq (2) diff --git a/man2/memfd_create.2 b/man2/memfd_create.2 index 786b7c41f3..fcf2fab4d0 100644 --- a/man2/memfd_create.2 +++ b/man2/memfd_create.2 @@ -184,11 +184,6 @@ The system-wide limit on the total number of open files has been reached. .TP .B ENOMEM There was insufficient memory to create a new anonymous file. -.SH VERSIONS -The -.BR memfd_create () -system call first appeared in Linux 3.17; -glibc support was added in glibc 2.27. .TP .B EPERM The @@ -203,9 +198,10 @@ group; see the description of in .BR proc (5). .SH STANDARDS -The -.BR memfd_create () -system call is Linux-specific. +Linux. +.SH HISTORY +Linux 3.17, +glibc 2.27. .SH NOTES .\" See also http://lwn.net/Articles/593918/ .\" and http://lwn.net/Articles/594919/ and http://lwn.net/Articles/591108/ diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2 index 1e68a0bd20..552985c510 100644 --- a/man2/memfd_secret.2 +++ b/man2/memfd_secret.2 @@ -132,14 +132,10 @@ There was insufficient memory to create a new anonymous file. is not implemented on this architecture, or has not been enabled on the kernel command-line with .BR secretmem_enable =1. -.SH VERSIONS -The -.BR memfd_secret () -system call first appeared in Linux 5.14. .SH STANDARDS -The -.BR memfd_secret () -system call is Linux-specific. +Linux. +.SH HISTORY +Linux 5.14. .SH NOTES The .BR memfd_secret () diff --git a/man2/migrate_pages.2 b/man2/migrate_pages.2 index e9e95b4f63..babc08b837 100644 --- a/man2/migrate_pages.2 +++ b/man2/migrate_pages.2 @@ -134,12 +134,10 @@ No process matching .I pid could be found. .\" FIXME Document the other errors that can occur for migrate_pages() -.SH VERSIONS -The -.BR migrate_pages () -system call first appeared in Linux 2.6.16. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.16. .SH NOTES For information on library support, see .BR numa (7). diff --git a/man2/mincore.2 b/man2/mincore.2 index 9f967ad7d3..167841aace 100644 --- a/man2/mincore.2 +++ b/man2/mincore.2 @@ -117,18 +117,16 @@ to + .I length contained unmapped memory. -.SH VERSIONS -Available since Linux 2.3.99pre1 and glibc 2.2. .SH STANDARDS -.BR mincore () -is not specified in POSIX.1, -and it is not available on all UNIX implementations. -.\" It is on at least NetBSD, FreeBSD, OpenBSD, Solaris 8, -.\" AIX 5.1, SunOS 4.1 -.\" .SH HISTORY -.\" The -.\" .BR mincore () -.\" function first appeared in 4.4BSD. +None. +.SH HISTORY +Linux 2.3.99pre1, +glibc 2.2. +.PP +First appeared in 4.4BSD. +.PP +NetBSD, FreeBSD, OpenBSD, Solaris 8, +AIX 5.1, SunOS 4.1. .SH BUGS Before Linux 2.6.21, .BR mincore () diff --git a/man2/mkdir.2 b/man2/mkdir.2 index b1339a49a5..3d643fbbf5 100644 --- a/man2/mkdir.2 +++ b/man2/mkdir.2 @@ -204,25 +204,10 @@ does not support the creation of directories. .I pathname refers to a file on a read-only filesystem. .SH VERSIONS -.BR mkdirat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. -.SH STANDARDS -.BR mkdir (): -SVr4, BSD, POSIX.1-2001, POSIX.1-2008. -.\" SVr4 documents additional EIO, EMULTIHOP -.PP -.BR mkdirat (): -POSIX.1-2008. -.SH NOTES Under Linux, apart from the permission bits, the .B S_ISVTX .I mode bit is also honored. -.PP -There are many infelicities in the protocol underlying NFS. -Some of these affect -.BR mkdir (). .SS glibc notes On older kernels where .BR mkdirat () @@ -236,6 +221,21 @@ glibc constructs a pathname based on the symbolic link in that corresponds to the .I dirfd argument. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR mkdir () +SVr4, BSD, POSIX.1-2001. +.\" SVr4 documents additional EIO, EMULTIHOP +.TP +.BR mkdirat () +Linux 2.6.16, +glibc 2.4. +.SH NOTES +There are many infelicities in the protocol underlying NFS. +Some of these affect +.BR mkdir (). .SH SEE ALSO .BR mkdir (1), .BR chmod (2), diff --git a/man2/mknod.2 b/man2/mknod.2 index 25657a9d11..30f256c444 100644 --- a/man2/mknod.2 +++ b/man2/mknod.2 @@ -241,19 +241,6 @@ does not support the type of node requested. .I pathname refers to a file on a read-only filesystem. .SH VERSIONS -.BR mknodat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. -.SH STANDARDS -.BR mknod (): -SVr4, 4.4BSD, POSIX.1-2001 (but see below), POSIX.1-2008. -.\" The Linux version differs from the SVr4 version in that it -.\" does not require root permission to create pipes, also in that no -.\" EMULTIHOP, ENOLINK, or EINTR error is documented. -.PP -.BR mknodat (): -POSIX.1-2008. -.SH NOTES POSIX.1-2001 says: "The only portable use of .BR mknod () is to create a FIFO-special file. @@ -278,7 +265,21 @@ cannot be used to create directories. One should make directories with .BR mkdir (2). .\" and one should make UNIX domain sockets with socket(2) and bind(2). -.PP +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR mknod () +SVr4, 4.4BSD, POSIX.1-2001 (but see VERSIONS). +.\" The Linux version differs from the SVr4 version in that it +.\" does not require root permission to create pipes, also in that no +.\" EMULTIHOP, ENOLINK, or EINTR error is documented. +.TP +.BR mknodat () +Linux 2.6.16, +glibc 2.4. +POSIX.1-2008. +.SH NOTES There are many infelicities in the protocol underlying NFS. Some of these affect .BR mknod () diff --git a/man2/mlock.2 b/man2/mlock.2 index 3b3c7e2a3a..d36e8680ca 100644 --- a/man2/mlock.2 +++ b/man2/mlock.2 @@ -256,19 +256,49 @@ to perform the requested operation. (Linux 2.6.8 and earlier) The caller was not privileged .RB ( CAP_IPC_LOCK ). .SH VERSIONS -.BR mlock2 () -is available since Linux 4.4; -glibc support was added in glibc 2.27. -.SH STANDARDS +.SS Linux +Under Linux, .BR mlock (), -.BR munlock (), -.BR mlockall (), +.BR mlock2 (), and -.BR munlockall (): -POSIX.1-2001, POSIX.1-2008, SVr4. +.BR munlock () +automatically round +.I addr +down to the nearest page boundary. +However, the POSIX.1 specification of +.BR mlock () +and +.BR munlock () +allows an implementation to require that +.I addr +is page aligned, so portable applications should ensure this. .PP +The +.I VmLck +field of the Linux-specific +.I /proc/[pid]/status +file shows how many kilobytes of memory the process with ID +.I PID +has locked using +.BR mlock (), +.BR mlock2 (), +.BR mlockall (), +and +.BR mmap (2) +.BR MAP_LOCKED . +.SH STANDARDS +.TP +.BR mlock () +.TQ +.BR munlock () +.TQ +.BR mlockall () +.TQ +.BR munlockall () +POSIX.1-2008. +.TP .BR mlock2 () -is Linux specific. +Linux. .PP On POSIX systems on which .BR mlock () @@ -294,6 +324,20 @@ is defined in \fI<unistd.h>\fP 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 it to 1. +.SH HISTORY +.TP +.BR mlock () +.TQ +.BR munlock () +.TQ +.BR mlockall () +.TQ +.BR munlockall () +POSIX.1-2001, POSIX.1-2008, SVr4. +.TP +.BR mlock2 () +Linux 4.4, +glibc 2.27. .SH NOTES Memory locking has two main applications: real-time algorithms and high-security data processing. @@ -392,36 +436,6 @@ flag allow efficient memory locking for applications that deal with large mappings where only a (small) portion of pages in the mapping are touched. In such cases, locking all of the pages in a mapping would incur a significant penalty for memory locking. -.SS Linux notes -Under Linux, -.BR mlock (), -.BR mlock2 (), -and -.BR munlock () -automatically round -.I addr -down to the nearest page boundary. -However, the POSIX.1 specification of -.BR mlock () -and -.BR munlock () -allows an implementation to require that -.I addr -is page aligned, so portable applications should ensure this. -.PP -The -.I VmLck -field of the Linux-specific -.I /proc/[pid]/status -file shows how many kilobytes of memory the process with ID -.I PID -has locked using -.BR mlock (), -.BR mlock2 (), -.BR mlockall (), -and -.BR mmap (2) -.BR MAP_LOCKED . .SS Limits and permissions In Linux 2.6.8 and earlier, a process must be privileged diff --git a/man2/mmap.2 b/man2/mmap.2 index 6a9395d2c2..04f117e02d 100644 --- a/man2/mmap.2 +++ b/man2/mmap.2 @@ -665,41 +665,7 @@ T} Thread safety MT-Safe .hy .ad .sp 1 -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD. -.\" SVr4 documents additional error codes ENXIO and ENODEV. -.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. -.PP -On POSIX systems on which -.BR mmap (), -.BR msync (2), -and -.BR munmap () -are available, -.B _POSIX_MAPPED_FILES -is defined in \fI<unistd.h>\fP to a value greater than 0. -(See also -.BR sysconf (3).) -.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. -.\" -1: unavailable, 0: ask using sysconf(). -.\" glibc defines it to 1. -.SH NOTES -Memory mapped by -.BR mmap () -is preserved across -.BR fork (2), -with the same attributes. -.PP -A file is mapped in multiples of the page size. -For a file that is not -a multiple of the page size, -the remaining bytes in the partial page at the end of the mapping -are zeroed when mapped, -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 +.SH VERSIONS On some hardware architectures (e.g., i386), .B PROT_WRITE implies @@ -760,6 +726,57 @@ The relevant flags are: .BR MAP_POPULATE , and .BR MAP_STACK . +.SS C library/kernel differences +This page describes the interface provided by the glibc +.BR mmap () +wrapper function. +Originally, this function invoked a system call of the same name. +Since Linux 2.4, that system call has been superseded by +.BR mmap2 (2), +and nowadays +.\" Since around glibc 2.1/2.2, depending on the platform. +the glibc +.BR mmap () +wrapper function invokes +.BR mmap2 (2) +with a suitably adjusted value for +.IR offset . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD. +.\" SVr4 documents additional error codes ENXIO and ENODEV. +.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. +.PP +On POSIX systems on which +.BR mmap (), +.BR msync (2), +and +.BR munmap () +are available, +.B _POSIX_MAPPED_FILES +is defined in \fI<unistd.h>\fP to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines it to 1. +.SH NOTES +Memory mapped by +.BR mmap () +is preserved across +.BR fork (2), +with the same attributes. +.PP +A file is mapped in multiples of the page size. +For a file that is not +a multiple of the page size, +the remaining bytes in the partial page at the end of the mapping +are zeroed when mapped, +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 An application can determine which pages of a mapping are currently resident in the buffer/page cache using @@ -860,21 +877,6 @@ and .I length must both be a multiple of the underlying huge page size. .\" -.SS C library/kernel differences -This page describes the interface provided by the glibc -.BR mmap () -wrapper function. -Originally, this function invoked a system call of the same name. -Since Linux 2.4, that system call has been superseded by -.BR mmap2 (2), -and nowadays -.\" Since around glibc 2.1/2.2, depending on the platform. -the glibc -.BR mmap () -wrapper function invokes -.BR mmap2 (2) -with a suitably adjusted value for -.IR offset . .SH BUGS On Linux, there are no guarantees like those suggested above under .BR MAP_NORESERVE . diff --git a/man2/mmap2.2 b/man2/mmap2.2 index 1fd5732ad4..dfddef0afc 100644 --- a/man2/mmap2.2 +++ b/man2/mmap2.2 @@ -58,11 +58,6 @@ is not a multiple of the system page size. can also return any of the errors described in .BR mmap (2). .SH VERSIONS -.BR mmap2 () -is available since Linux 2.3.31. -.SH STANDARDS -This system call is Linux-specific. -.SH NOTES On architectures where this system call is present, the glibc .BR mmap () @@ -78,6 +73,10 @@ is actually the system page size, rather than 4096 bytes. .\" ia64 can have page sizes ranging from 4 kB to 64 kB. .\" On cris, it looks like the unit might also be the page size, .\" which is 8192 bytes. -- mtk, June 2007 +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.3.31. .SH SEE ALSO .BR getpagesize (2), .BR mmap (2), diff --git a/man2/modify_ldt.2 b/man2/modify_ldt.2 index e8ae9c9d0a..07f3cddb04 100644 --- a/man2/modify_ldt.2 +++ b/man2/modify_ldt.2 @@ -157,8 +157,7 @@ is 1 or 0x11 and the new LDT entry has invalid values. .I func is neither 0, 1, 2, nor 0x11. .SH STANDARDS -This call is Linux-specific and should not be used in programs intended -to be portable. +Linux. .SH NOTES .BR modify_ldt () should not be used for thread-local storage, as it slows down context diff --git a/man2/mount.2 b/man2/mount.2 index a818b89b14..bab18bcaeb 100644 --- a/man2/mount.2 +++ b/man2/mount.2 @@ -831,7 +831,10 @@ flag. See .BR EACCES , above. -.SH VERSIONS +.\" +.SH STANDARDS +Linux. +.SH HISTORY The definitions of .BR MS_DIRSYNC , .BR MS_MOVE , @@ -844,11 +847,7 @@ The definitions of and .B MS_UNBINDABLE were added to glibc headers in glibc 2.12. -.\" -.SH STANDARDS -This function is Linux-specific and should not be used in -programs intended to be portable. -.SH NOTES +.PP 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. @@ -884,6 +883,7 @@ Since Linux 2.4 the set-user-ID and set-group-ID bits are just silently ignored in this case. .\" The change is in patch-2.4.0-prerelease. .\" +.SH NOTES .SS Mount namespaces Starting with Linux 2.4.19, Linux provides mount namespaces. A mount namespace is the set of filesystem mounts that diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2 index b171597cf9..f89eccbaae 100644 --- a/man2/mount_setattr.2 +++ b/man2/mount_setattr.2 @@ -581,15 +581,13 @@ An attempt was made to add an ID mapping to a mount that is already ID mapped. The caller does not have .B CAP_SYS_ADMIN in the initial user namespace. -.SH VERSIONS -.BR mount_setattr () -first appeared in Linux 5.12. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.12. .\" commit 7d6beb71da3cc033649d641e1e608713b8220290 .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af -.SH STANDARDS -.BR mount_setattr () -is Linux-specific. .SH NOTES .SS ID-mapped mounts Creating an ID-mapped mount makes it possible to diff --git a/man2/move_pages.2 b/man2/move_pages.2 index 1c0851531b..c98edf7ff8 100644 --- a/man2/move_pages.2 +++ b/man2/move_pages.2 @@ -216,11 +216,10 @@ to another user but did not have privilege to do so .TP .B ESRCH Process does not exist. -.SH VERSIONS -.BR move_pages () -first appeared in Linux 2.6.18. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.18. .SH NOTES For information on library support, see .BR numa (7). diff --git a/man2/mprotect.2 b/man2/mprotect.2 index 2bf3098d06..52c14da058 100644 --- a/man2/mprotect.2 +++ b/man2/mprotect.2 @@ -192,12 +192,6 @@ in the middle of a region currently protected as would result in three mappings: two read/write mappings at each end and a read-only mapping in the middle.) .SH VERSIONS -.BR pkey_mprotect () -first appeared in Linux 4.9; -library support was added in glibc 2.27. -.SH STANDARDS -.BR mprotect (): -POSIX.1-2001, POSIX.1-2008, SVr4. .\" SVr4 defines an additional error .\" code EAGAIN. The SVr4 error conditions don't map neatly onto Linux's. POSIX says that the behavior of @@ -206,9 +200,6 @@ is unspecified if it is applied to a region of memory that was not obtained via .BR mmap (2). .PP -.BR pkey_mprotect () -is a nonportable Linux extension. -.SH NOTES On Linux, it is always permissible to call .BR mprotect () on any address in a process's address space (except for the @@ -266,6 +257,22 @@ When called this way, the operation of .BR pkey_mprotect () is equivalent to .BR mprotect (). +.SH STANDARDS +.TP +.BR mprotect () +POSIX.1-2008. +.TP +.BR pkey_mprotect () +Linux. +.SH HISTORY +.TP +.BR mprotect () +POSIX.1-2001, SVr4. +.TP +.BR pkey_mprotect () +Linux 4.9, +glibc 2.27. +.SH NOTES .SH EXAMPLES .\" sigaction.2 refers to this example The program below demonstrates the use of diff --git a/man2/mq_getsetattr.2 b/man2/mq_getsetattr.2 index c53919c669..ebdb42e79e 100644 --- a/man2/mq_getsetattr.2 +++ b/man2/mq_getsetattr.2 @@ -25,7 +25,7 @@ For an explanation of how this system call operates, see the description of .BR mq_setattr (3). .SH STANDARDS -This interface is nonstandard; avoid its use. +None. .SH NOTES Never call it unless you are writing a C library! .SH SEE ALSO diff --git a/man2/mremap.2 b/man2/mremap.2 index b8e65cd2f3..be215f34d3 100644 --- a/man2/mremap.2 +++ b/man2/mremap.2 @@ -243,11 +243,19 @@ was used causing a new mapping to be created that would exceed the Or, it would exceed the maximum number of allowed mappings. .RE .SH STANDARDS -This call is Linux-specific, and should not be used in programs -intended to be portable. +Linux. +.SH HISTORY .\" 4.2BSD had a (never actually implemented) .\" .BR mremap (2) .\" call with completely different semantics. +.\" .PP +Prior to glibc 2.4, glibc did not expose the definition of +.BR MREMAP_FIXED , +and the prototype for +.BR mremap () +did not allow for the +.I new_address +argument. .SH NOTES .BR mremap () changes the @@ -279,14 +287,6 @@ call will make a best effort to populate the new area but will not fail with .B ENOMEM if the area cannot be populated. -.PP -Prior to glibc 2.4, glibc did not expose the definition of -.BR MREMAP_FIXED , -and the prototype for -.BR mremap () -did not allow for the -.I new_address -argument. .\" .SS MREMAP_DONTUNMAP use cases Possible applications for diff --git a/man2/msgctl.2 b/man2/msgctl.2 index ce534dc2ab..926f683a9c 100644 --- a/man2/msgctl.2 +++ b/man2/msgctl.2 @@ -385,20 +385,10 @@ but the caller is not privileged (Linux: does not have the .B CAP_SYS_RESOURCE capability). .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. .\" SVID does not document the EIDRM error condition. -.SH NOTES -The -.BR IPC_INFO , -.BR MSG_STAT , -and -.B MSG_INFO -operations are used by the -.BR ipcs (1) -program to provide information on allocated resources. -In the future these may modified or moved to a -.I /proc -filesystem interface. .PP Various fields in the \fIstruct msqid_ds\fP were typed as @@ -413,6 +403,18 @@ a recompilation under glibc-2.1.91 or later should suffice. .B IPC_64 flag in .IR cmd .) +.SH NOTES +The +.BR IPC_INFO , +.BR MSG_STAT , +and +.B MSG_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future these may modified or moved to a +.I /proc +filesystem interface. .SH SEE ALSO .BR msgget (2), .BR msgrcv (2), diff --git a/man2/msgget.2 b/man2/msgget.2 index fb6caee487..60c9aa52d9 100644 --- a/man2/msgget.2 +++ b/man2/msgget.2 @@ -168,7 +168,15 @@ number of message queues .RB ( MSGMNI ) would be exceeded. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.SS Linux +Until Linux 2.3.20, Linux would return +.B EIDRM +for a +.BR msgget () +on a message queue scheduled for deletion. .SH NOTES .B IPC_PRIVATE isn't a flag field but a @@ -193,12 +201,6 @@ based on available system memory. Since Linux 3.19, the default value is 32,000. On Linux, this limit can be read and modified via .IR /proc/sys/kernel/msgmni . -.SS Linux notes -Until Linux 2.3.20, Linux would return -.B EIDRM -for a -.BR msgget () -on a message queue scheduled for deletion. .SH BUGS The name choice .B IPC_PRIVATE diff --git a/man2/msgop.2 b/man2/msgop.2 index 964889ae5a..ee4f114193 100644 --- a/man2/msgop.2 +++ b/man2/msgop.2 @@ -450,7 +450,7 @@ were specified in and this kernel was configured without .BR CONFIG_CHECKPOINT_RESTORE . .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. +POSIX.1-2008. .PP The .B MSG_EXCEPT @@ -461,14 +461,16 @@ their definitions can be obtained by defining the .B _GNU_SOURCE .\" MSG_COPY since glibc 2.18 feature test macro. -.SH NOTES +.SH HISTORY +POSIX.1-2001, SVr4. +.PP The .I msgp argument is declared as \fIstruct msgbuf\ *\fP in glibc 2.0 and 2.1. It is declared as \fIvoid\ *\fP in glibc 2.2 and later, as required by SUSv2 and SUSv3. -.PP +.SH NOTES The following limits on message queue resources affect the .BR msgsnd () call: diff --git a/man2/msync.2 b/man2/msync.2 index e650f79888..4cd38d19a8 100644 --- a/man2/msync.2 +++ b/man2/msync.2 @@ -81,31 +81,7 @@ are set in .TP .B ENOMEM The indicated memory (or part of it) was not mapped. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008. -.PP -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 -On POSIX systems on which -.BR msync () -is available, both -.B _POSIX_MAPPED_FILES -and -.B _POSIX_SYNCHRONIZED_IO -are defined in -.I <unistd.h> -to a value greater than 0. -(See also -.BR sysconf (3).) -.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. -.\" -1: unavailable, 0: ask using sysconf(). -.\" glibc defines them to 1. -.SH NOTES +.SH VERSIONS According to POSIX, either .B MS_SYNC or @@ -132,6 +108,32 @@ or .B MS_ASYNC in .IR flags . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.PP +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 +On POSIX systems on which +.BR msync () +is available, both +.B _POSIX_MAPPED_FILES +and +.B _POSIX_SYNCHRONIZED_IO +are defined in +.I <unistd.h> +to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines them to 1. .SH SEE ALSO .BR mmap (2) .PP diff --git a/man2/nanosleep.2 b/man2/nanosleep.2 index 12e0cee84b..1224192961 100644 --- a/man2/nanosleep.2 +++ b/man2/nanosleep.2 @@ -109,27 +109,7 @@ The value in the field was not in the range [0, 999999999] or .I tv_sec was negative. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008. -.SH NOTES -If the interval specified in -.I req -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 -The fact that -.BR nanosleep () -sleeps for a relative interval can be problematic if the call -is repeatedly restarted after being interrupted by signals, -since the time between the interruptions and restarts of the call -will lead to drift in the time when the sleep finally completes. -This problem can be avoided by using -.BR clock_nanosleep (2) -with an absolute time value. -.PP +.SH VERSIONS POSIX.1 specifies that .BR nanosleep () should measure time against the @@ -161,7 +141,11 @@ function; ... Consequently, these time services shall expire when the requested relative interval elapses, independently of the new or old value of the clock. .RE -.SS Old behavior +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.PP In order to support applications requiring much more precise pauses (e.g., in order to control some time-critical hardware), .BR nanosleep () @@ -173,6 +157,24 @@ or .BR SCHED_RR . 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 +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 +The fact that +.BR nanosleep () +sleeps for a relative interval can be problematic if the call +is repeatedly restarted after being interrupted by signals, +since the time between the interruptions and restarts of the call +will lead to drift in the time when the sleep finally completes. +This problem can be avoided by using +.BR clock_nanosleep (2) +with an absolute time value. .SH BUGS If a program that catches signals and uses .BR nanosleep () diff --git a/man2/nfsservctl.2 b/man2/nfsservctl.2 index c9ecc069cd..7e0996f331 100644 --- a/man2/nfsservctl.2 +++ b/man2/nfsservctl.2 @@ -61,10 +61,10 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.SH VERSIONS -This system call was removed in Linux 3.1. -Library support was removed in glibc 2.28. .SH STANDARDS -This call is Linux-specific. +Linux. +.SH HISTORY +Removed in Linux 3.1. +Removed in glibc 2.28. .SH SEE ALSO .BR nfsd (7) diff --git a/man2/nice.2 b/man2/nice.2 index c6ba8c752c..c97fb09355 100644 --- a/man2/nice.2 +++ b/man2/nice.2 @@ -76,23 +76,7 @@ capability is required. .B RLIMIT_NICE resource limit in .BR setrlimit (2).) -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. -However, the raw system call and (g)libc -(earlier than glibc 2.2.4) return value is nonstandard, see below. -.\" SVr4 documents an additional -.\" .B EINVAL -.\" error code. -.SH NOTES -For further details on the nice value, see -.BR sched (7). -.PP -.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). -.\" +.SH VERSIONS .SS C library/kernel differences POSIX.1 specifies that .BR nice () @@ -107,6 +91,22 @@ Since glibc 2.2.4, the wrapper function provided by glibc provides conformance to POSIX.1 by calling .BR getpriority (2) to obtain the new nice value, which is then returned to the caller. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.\" SVr4 documents an additional +.\" .B EINVAL +.\" error code. +.SH NOTES +For further details on the nice value, see +.BR sched (7). +.PP +.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). .SH SEE ALSO .BR nice (1), .BR renice (1), diff --git a/man2/open.2 b/man2/open.2 index aefcae1e60..d9386c48fb 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -1285,19 +1285,133 @@ flag was specified, and an incompatible lease was held on the file (see .BR fcntl (2)). .SH VERSIONS +The (undefined) effect of +.B O_RDONLY | O_TRUNC +varies among implementations. +On many systems the file is actually truncated. +.\" Linux 2.0, 2.5: truncate +.\" Solaris 5.7, 5.8: truncate +.\" Irix 6.5: truncate +.\" Tru64 5.1B: truncate +.\" HP-UX 11.22: truncate +.\" FreeBSD 4.7: truncate +.SS Synchronized I/O +The POSIX.1-2008 "synchronized I/O" option +specifies different variants of synchronized I/O, +and specifies the +.BR open () +flags +.BR O_SYNC , +.BR O_DSYNC , +and +.B O_RSYNC +for controlling the behavior. +Regardless of whether an implementation supports this option, +it must at least support the use of +.B O_SYNC +for regular files. +.PP +Linux implements +.B O_SYNC +and +.BR O_DSYNC , +but not +.BR O_RSYNC . +Somewhat incorrectly, glibc defines +.B O_RSYNC +to have the same value as +.BR O_SYNC . +.RB ( O_RSYNC +is defined in the Linux header file +.I <asm/fcntl.h> +on HP PA-RISC, but it is not used.) +.PP +.B O_SYNC +provides synchronized I/O +.I file +integrity completion, +meaning write operations will flush data and all associated metadata +to the underlying hardware. +.B O_DSYNC +provides synchronized I/O +.I data +integrity completion, +meaning write operations will flush data +to the underlying hardware, +but will only flush metadata updates that are required +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 +To understand the difference between the two types of completion, +consider two pieces of file metadata: +the file last modification timestamp +.RI ( st_mtime ) +and the file length. +All write operations will update the last file modification timestamp, +but only writes that add data to the end of the +file will change the file length. +The last modification timestamp is not needed to ensure that +a read completes successfully, but the file length is. +Thus, +.B O_DSYNC +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 +Before Linux 2.6.33, Linux implemented only the +.B O_SYNC +flag for +.BR open (). +However, when that flag was specified, +most filesystems actually provided the equivalent of synchronized I/O +.I data +integrity completion (i.e., +.B O_SYNC +was actually implemented as the equivalent of +.BR O_DSYNC ). +.PP +Since Linux 2.6.33, proper +.B O_SYNC +support is provided. +However, to ensure backward binary compatibility, +.B O_DSYNC +was defined with the same value as the historical +.BR O_SYNC , +and +.B O_SYNC +was defined as a new (two-bit) flag value that includes the +.B O_DSYNC +flag value. +This ensures that applications compiled against +new headers get at least +.B O_DSYNC +semantics before Linux 2.6.33. +.\" +.SS C library/kernel differences +Since glibc 2.26, +the glibc wrapper function for +.BR open () +employs the .BR openat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. +system call, rather than the kernel's +.BR open () +system call. +For certain architectures, this is also true before glibc 2.26. +.\" .SH STANDARDS -.BR open (), +.TP +.BR open () +.TQ .BR creat () -SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. -.PP -.BR openat (): +.TQ +.BR openat () POSIX.1-2008. .PP .BR openat2 (2) -is Linux-specific. +Linux. .PP The .BR O_DIRECT , @@ -1324,17 +1438,17 @@ with a value greater than or equal to 200809L or with a value greater than or equal to 700. In glibc 2.11 and earlier, one obtains the definitions by defining .BR _GNU_SOURCE . -.PP -As noted in -.BR feature_test_macros (7), -feature test macros such as -.BR _POSIX_C_SOURCE , -.BR _XOPEN_SOURCE , -and -.B _GNU_SOURCE -must be defined before including -.I any -header files. +.SH HISTORY +.TP +.BR open () +.TQ +.BR creat () +SVr4, 4.3BSD, POSIX.1-2001. +.TP +.BR openat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. .SH NOTES Under Linux, the .B O_NONBLOCK @@ -1345,17 +1459,6 @@ this may be used to open a device in order to get a file descriptor for use with .BR ioctl (2). .PP -The (undefined) effect of -.B O_RDONLY | O_TRUNC -varies among implementations. -On many systems the file is actually truncated. -.\" Linux 2.0, 2.5: truncate -.\" Solaris 5.7, 5.8: truncate -.\" Irix 6.5: truncate -.\" Tru64 5.1B: truncate -.\" HP-UX 11.22: truncate -.\" FreeBSD 4.7: truncate -.PP Note that .BR open () can open device special files, but @@ -1442,113 +1545,6 @@ operation to test whether two file descriptors (in the same process or in two different processes) refer to the same open file description. .\" -.\" -.SS Synchronized I/O -The POSIX.1-2008 "synchronized I/O" option -specifies different variants of synchronized I/O, -and specifies the -.BR open () -flags -.BR O_SYNC , -.BR O_DSYNC , -and -.B O_RSYNC -for controlling the behavior. -Regardless of whether an implementation supports this option, -it must at least support the use of -.B O_SYNC -for regular files. -.PP -Linux implements -.B O_SYNC -and -.BR O_DSYNC , -but not -.BR O_RSYNC . -Somewhat incorrectly, glibc defines -.B O_RSYNC -to have the same value as -.BR O_SYNC . -.RB ( O_RSYNC -is defined in the Linux header file -.I <asm/fcntl.h> -on HP PA-RISC, but it is not used.) -.PP -.B O_SYNC -provides synchronized I/O -.I file -integrity completion, -meaning write operations will flush data and all associated metadata -to the underlying hardware. -.B O_DSYNC -provides synchronized I/O -.I data -integrity completion, -meaning write operations will flush data -to the underlying hardware, -but will only flush metadata updates that are required -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 -To understand the difference between the two types of completion, -consider two pieces of file metadata: -the file last modification timestamp -.RI ( st_mtime ) -and the file length. -All write operations will update the last file modification timestamp, -but only writes that add data to the end of the -file will change the file length. -The last modification timestamp is not needed to ensure that -a read completes successfully, but the file length is. -Thus, -.B O_DSYNC -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 -Before Linux 2.6.33, Linux implemented only the -.B O_SYNC -flag for -.BR open (). -However, when that flag was specified, -most filesystems actually provided the equivalent of synchronized I/O -.I data -integrity completion (i.e., -.B O_SYNC -was actually implemented as the equivalent of -.BR O_DSYNC ). -.PP -Since Linux 2.6.33, proper -.B O_SYNC -support is provided. -However, to ensure backward binary compatibility, -.B O_DSYNC -was defined with the same value as the historical -.BR O_SYNC , -and -.B O_SYNC -was defined as a new (two-bit) flag value that includes the -.B O_DSYNC -flag value. -This ensures that applications compiled against -new headers get at least -.B O_DSYNC -semantics before Linux 2.6.33. -.\" -.SS C library/kernel differences -Since glibc 2.26, -the glibc wrapper function for -.BR open () -employs the -.BR openat () -system call, rather than the kernel's -.BR open () -system call. -For certain architectures, this is also true before glibc 2.26. -.\" .SS NFS There are many infelicities in the protocol underlying NFS, affecting amongst others diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2 index 20fd4519f9..bbdafb76dd 100644 --- a/man2/open_by_handle_at.2 +++ b/man2/open_by_handle_at.2 @@ -366,15 +366,15 @@ The specified is not valid. This error will occur if, for example, the file has been deleted. .SH VERSIONS -These system calls first appeared in Linux 2.6.39. -Library support is provided since glibc 2.14. -.SH STANDARDS -These system calls are nonstandard Linux extensions. -.PP FreeBSD has a broadly similar pair of system calls in the form of .BR getfh () and .BR openfh (). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.39, +glibc 2.14. .SH NOTES A file handle can be generated in one process using .BR name_to_handle_at () diff --git a/man2/openat2.2 b/man2/openat2.2 index 3ffd06ae72..e90211fadb 100644 --- a/man2/openat2.2 +++ b/man2/openat2.2 @@ -466,12 +466,11 @@ and an escape from the root during path resolution was detected. contains .BR RESOLVE_NO_XDEV , and a path component crosses a mount point. -.SH VERSIONS -.BR openat2 () -first appeared in Linux 5.6. -.\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179 .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 5.6. +.\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179 .PP The semantics of .B RESOLVE_BENEATH diff --git a/man2/outb.2 b/man2/outb.2 index 90bedebd44..11aafcdcef 100644 --- a/man2/outb.2 +++ b/man2/outb.2 @@ -68,7 +68,7 @@ to tell the kernel to allow the user space application to access the I/O ports in question. Failure to do this will cause the application to receive a segmentation fault. -.SH STANDARDS +.SH VERSIONS .BR outb () and friends are hardware-specific. The @@ -77,6 +77,8 @@ argument is passed first and the .I port argument is passed second, which is the opposite order from most DOS implementations. +.SH STANDARDS +None. .SH SEE ALSO .BR ioperm (2), .BR iopl (2) diff --git a/man2/pause.2 b/man2/pause.2 index 1a4f3cb910..7cc7b0b8de 100644 --- a/man2/pause.2 +++ b/man2/pause.2 @@ -40,7 +40,9 @@ is set to .B EINTR a signal was caught and the signal-catching function returned. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. .SH SEE ALSO .BR kill (2), .BR select (2), diff --git a/man2/pciconfig_read.2 b/man2/pciconfig_read.2 index 64de37f53b..1f5d512a37 100644 --- a/man2/pciconfig_read.2 +++ b/man2/pciconfig_read.2 @@ -115,6 +115,8 @@ capability. This does not apply to .BR pciconfig_iobase (). .SH STANDARDS -These calls are Linux-specific, available since Linux 2.0.26/2.1.11. +Linux. +.SH HISTORY +Linux 2.0.26/2.1.11. .SH SEE ALSO .BR capabilities (7) diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index 4d3469c383..ee65d20d08 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -3816,18 +3816,15 @@ and (since Linux 3.13) setting a kernel function-trace tracepoint. .TP .B ESRCH Returned if attempting to attach to a process that does not exist. -.SH VERSION +.SH STANDARDS +Linux. +.SH HISTORY .BR perf_event_open () was introduced in Linux 2.6.31 but was called .\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e .BR perf_counter_open (). It was renamed in Linux 2.6.32. .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6 -.SH STANDARDS -This -.BR perf_event_open () -system call Linux-specific -and should not be used in programs intended to be portable. .SH NOTES The official way of knowing if .BR perf_event_open () diff --git a/man2/perfmonctl.2 b/man2/perfmonctl.2 index 1adbba4920..d6d36a0a04 100644 --- a/man2/perfmonctl.2 +++ b/man2/perfmonctl.2 @@ -16,7 +16,7 @@ perfmonctl \- interface to IA-64 performance monitoring unit .fi .PP .IR Note : -There is no glibc wrapper for this system call; see NOTES. +There is no glibc wrapper for this system call; see HISTORY. .SH DESCRIPTION The IA-64-specific .BR perfmonctl () @@ -174,15 +174,13 @@ returns zero when the operation is successful. On error, \-1 is returned and .I errno is set to indicate the error. -.SH VERSIONS -.BR perfmonctl () -was added in Linux 2.4; -.\" commit ecf5b72d5f66af843f189dfe9ce31598c3e48ad7 -it was removed in Linux 5.10. .SH STANDARDS -.BR perfmonctl () -is Linux-specific and is available only on the IA-64 architecture. -.SH NOTES +Linux on IA-64. +.SH HISTORY +Added in Linux 2.4; +.\" commit ecf5b72d5f66af843f189dfe9ce31598c3e48ad7 +removed in Linux 5.10. +.PP This system call was broken for many years, and ultimately removed in Linux 5.10. .PP diff --git a/man2/personality.2 b/man2/personality.2 index 4be1b97f5d..caca709b8a 100644 --- a/man2/personality.2 +++ b/man2/personality.2 @@ -243,15 +243,13 @@ is set to indicate the error. .TP .B EINVAL The kernel was unable to change the personality. -.SH VERSIONS -This system call first appeared in Linux 1.1.20 -(and thus first in a stable kernel release with Linux 1.2.0); -library support was added in glibc 2.3. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 1.1.20, +.\" (and thus first in a stable kernel release with Linux 1.2.0) +glibc 2.3. .\" personality wrapper first appeared in glibc 1.90, .\" <sys/personality.h> was added later in glibc 2.2.91. -.SH STANDARDS -.BR personality () -is Linux-specific and should not be used in programs intended to -be portable. .SH SEE ALSO .BR setarch (8) diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2 index 097ec27e89..fe4831b58b 100644 --- a/man2/pidfd_getfd.2 +++ b/man2/pidfd_getfd.2 @@ -103,13 +103,11 @@ The process referred to by .I pidfd does not exist (i.e., it has terminated and been waited on). -.SH VERSIONS -.BR pidfd_getfd () -first appeared in Linux 5.6. -.\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09 .SH STANDARDS -.BR pidfd_getfd () -is Linux specific. +Linux. +.SH HISTORY +Linux 5.6. +.\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09 .SH NOTES For a description of PID file descriptors, see .BR pidfd_open (2). diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2 index f0ba89cdb9..68e4c23fa0 100644 --- a/man2/pidfd_open.2 +++ b/man2/pidfd_open.2 @@ -80,12 +80,10 @@ Insufficient kernel memory was available. The process specified by .I pid does not exist. -.SH VERSIONS -.BR pidfd_open () -first appeared in Linux 5.3. .SH STANDARDS -.BR pidfd_open () -is Linux specific. +Linux. +.SH HISTORY +Linux 5.3. .SH NOTES The following code sequence can be used to obtain a file descriptor for the child of diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2 index 30ccfa4469..d44a369f38 100644 --- a/man2/pidfd_send_signal.2 +++ b/man2/pidfd_send_signal.2 @@ -118,12 +118,10 @@ is invalid (see .B ESRCH The target process does not exist (i.e., it has terminated and been waited on). -.SH VERSIONS -.BR pidfd_send_signal () -first appeared in Linux 5.1. .SH STANDARDS -.BR pidfd_send_signal () -is Linux specific. +Linux. +.SH HISTORY +Linux 5.1. .SH NOTES .SS PID file descriptors The diff --git a/man2/pipe.2 b/man2/pipe.2 index 26e7df626e..adf6d73bf2 100644 --- a/man2/pipe.2 +++ b/man2/pipe.2 @@ -193,16 +193,6 @@ and support for notifications .RB ( CONFIG_WATCH_QUEUE ) is not compiled into the kernel. .SH VERSIONS -.BR pipe2 () -was added in Linux 2.6.27; -glibc support is available starting with glibc 2.9. -.SH STANDARDS -.BR pipe (): -POSIX.1-2001, POSIX.1-2008. -.PP -.BR pipe2 () -is Linux-specific. -.SH NOTES .\" See http://math-atlas.sourceforge.net/devel/assembly/64.psabi.1.33.ps.Z .\" for example, section 3.2.1 "Registers and the Stack Frame". The System V ABI on some architectures allows the use of more than one register @@ -219,6 +209,21 @@ wrapper function transparently deals with this. See .BR syscall (2) for information regarding registers used for storing second file descriptor. +.SH STANDARDS +.TP +.BR pipe () +POSIX.1-2008. +.TP +.BR pipe2 () +Linux. +.SH HISTORY +.TP +.BR pipe () +POSIX.1-2001. +.TP +.BR pipe2 () +Linux 2.6.27, +glibc 2.9. .SH EXAMPLES .\" fork.2 refers to this example program. The following program creates a pipe, and then diff --git a/man2/pivot_root.2 b/man2/pivot_root.2 index ee5b1fae6e..6fa240c060 100644 --- a/man2/pivot_root.2 +++ b/man2/pivot_root.2 @@ -151,12 +151,10 @@ is a mount point and has the propagation type The calling process does not have the .B CAP_SYS_ADMIN capability. -.SH VERSIONS -.BR pivot_root () -was introduced in Linux 2.3.41. .SH STANDARDS -.BR pivot_root () -is Linux-specific and hence is not portable. +Linux. +.SH HISTORY +Linux 2.3.41. .SH NOTES A command-line interface for this system call is provided by .BR pivot_root (8). diff --git a/man2/pkey_alloc.2 b/man2/pkey_alloc.2 index d6d33e8d65..f0c9149f77 100644 --- a/man2/pkey_alloc.2 +++ b/man2/pkey_alloc.2 @@ -83,18 +83,11 @@ does not support protection keys. Applications should always be prepared to handle this error, since factors outside of the application's control can reduce the number of available pkeys. -.SH VERSIONS -.BR pkey_alloc () -and -.BR pkey_free () -were added in Linux 4.9; -library support was added in glibc 2.27. .SH STANDARDS -The -.BR pkey_alloc () -and -.BR pkey_free () -system calls are Linux-specific. +Linux. +.SH HISTORY +Linux 4.9, +glibc 2.27. .SH NOTES .BR pkey_alloc () is always safe to call regardless of whether or not the operating system diff --git a/man2/poll.2 b/man2/poll.2 index be6de06076..4e26e62d40 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -358,39 +358,6 @@ is invalid (negative). .B ENOMEM Unable to allocate memory for kernel data structures. .SH VERSIONS -The -.BR poll () -system call was introduced in Linux 2.1.23. -On older kernels that lack this system call, -the glibc -.BR poll () -wrapper function provides emulation using -.BR select (2). -.PP -The -.BR ppoll () -system call was added in Linux 2.6.16. -The -.BR ppoll () -library call was added in glibc 2.4. -.SH STANDARDS -.BR poll () -conforms to POSIX.1-2001 and POSIX.1-2008. -.BR ppoll () -is Linux-specific. -.\" FIXME . -.\" ppoll() is proposed for inclusion in POSIX: -.\" https://www.austingroupbugs.net/view.php?id=1263 -.\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). -.SH NOTES -The operation of -.BR poll () -and -.BR ppoll () -is not affected by the -.B O_NONBLOCK -flag. -.PP On some other UNIX systems, .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett .BR poll () @@ -412,11 +379,6 @@ with the value \-1 for use as a for .BR poll (). This constant is not provided in glibc. -.PP -For a discussion of what may happen if a file descriptor being monitored by -.BR poll () -is closed in another thread, see -.BR select (2). .SS C library/kernel differences The Linux .BR ppoll () @@ -448,6 +410,45 @@ See .BR sigprocmask (2) for a discussion on the differences between the kernel and the libc notion of the sigset. +.SH STANDARDS +.TP +.BR poll () +POSIX.1-2008. +.TP +.BR ppoll () +Linux. +.\" FIXME . +.\" ppoll() is proposed for inclusion in POSIX: +.\" https://www.austingroupbugs.net/view.php?id=1263 +.\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). +.SH HISTORY +.TP +.BR poll () +POSIX.1-2001. +Linux 2.1.23. +.IP +On older kernels that lack this system call, +the glibc +.BR poll () +wrapper function provides emulation using +.BR select (2). +.TP +.BR ppoll () +Linux 2.6.16, +glibc 2.4. +.SH NOTES +The operation of +.BR poll () +and +.BR ppoll () +is not affected by the +.B O_NONBLOCK +flag. +.PP +For a discussion of what may happen if a file descriptor being monitored by +.BR poll () +is closed in another thread, see +.BR select (2). .SH BUGS See the discussion of spurious readiness notifications under the BUGS section of diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 index 57c65c8107..64ba39227c 100644 --- a/man2/posix_fadvise.2 +++ b/man2/posix_fadvise.2 @@ -127,47 +127,11 @@ Linux returned .B EINVAL in this case.) .SH VERSIONS -Kernel support first appeared in Linux 2.5.60; -the underlying system call is called -.BR fadvise64 (). -.\" of fadvise64_64() -Library support has been provided since glibc 2.2, -via the wrapper function -.BR posix_fadvise (). -.PP -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. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008. -Note that the type of the -.I len -argument was changed from -.I size_t -to -.I off_t -in POSIX.1-2001 TC1. -.SH NOTES Under Linux, \fBPOSIX_FADV_NORMAL\fP sets the readahead window to the default size for the backing device; \fBPOSIX_FADV_SEQUENTIAL\fP doubles this size, and \fBPOSIX_FADV_RANDOM\fP disables file readahead entirely. These changes affect the entire file, not just the specified region (but other open file handles to the same file are unaffected). -.PP -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 -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), -and then applying -.BR mincore (2) -to the mapping. .SS C library/kernel differences The name of the wrapper function in the C library is .BR posix_fadvise (). @@ -210,6 +174,45 @@ hidden from applications by the glibc .BR posix_fadvise () wrapper function, which invokes the appropriate architecture-specific system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.PP +Kernel support first appeared in Linux 2.5.60; +the underlying system call is called +.BR fadvise64 (). +.\" of fadvise64_64() +Library support has been provided since glibc 2.2, +via the wrapper function +.BR posix_fadvise (). +.PP +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 +The type of the +.I len +argument was changed from +.I size_t +to +.I off_t +in POSIX.1-2001 TC1. +.SH NOTES +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 +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), +and then applying +.BR mincore (2) +to the mapping. .SH BUGS Before Linux 2.6.6, if .I len diff --git a/man2/prctl.2 b/man2/prctl.2 index 2212331af0..bfd52b50c8 100644 --- a/man2/prctl.2 +++ b/man2/prctl.2 @@ -2502,12 +2502,6 @@ is not nor .BR PR_SPEC_DISABLE_NOEXEC . .SH VERSIONS -The -.BR prctl () -system call was introduced in Linux 2.1.57. -.\" The library interface was added in glibc 2.0.6 -.SH STANDARDS -This call is Linux-specific. IRIX has a .BR prctl () system call (also introduced in Linux 2.1.44 @@ -2524,6 +2518,11 @@ and options 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. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.1.57, +glibc 2.0.6 .SH SEE ALSO .BR signal (2), .BR core (5) diff --git a/man2/pread.2 b/man2/pread.2 index 9a97633235..5d4e0969ab 100644 --- a/man2/pread.2 +++ b/man2/pread.2 @@ -88,27 +88,16 @@ to any error specified for .BR write (2) or .BR lseek (2). -.SH VERSIONS -The -.BR pread () -and -.BR pwrite () -system calls were added in Linux 2.1.60; +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.PP +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 .BR lseek (2) on older kernels without the system calls) was added in glibc 2.1. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008. -.SH NOTES -The -.BR pread () -and -.BR pwrite () -system calls are especially useful in multithreaded applications. -They allow multiple threads to perform I/O on the same file descriptor -without being affected by changes to the file offset by other threads. -.\" .SS C library/kernel differences On Linux, the underlying system calls were renamed in Linux 2.6: @@ -130,6 +119,14 @@ On some 32-bit architectures, the calling signature for these system calls differ, for the reasons described in .BR syscall (2). +.SH NOTES +The +.BR pread () +and +.BR pwrite () +system calls are especially useful in multithreaded applications. +They allow multiple threads to perform I/O on the same file descriptor +without being affected by changes to the file offset by other threads. .SH BUGS POSIX requires that opening a file with the .B O_APPEND diff --git a/man2/process_madvise.2 b/man2/process_madvise.2 index 92878286b0..1cee5be246 100644 --- a/man2/process_madvise.2 +++ b/man2/process_madvise.2 @@ -183,18 +183,17 @@ See for .IR advice -specific errors. -.SH VERSIONS -This system call first appeared in Linux 5.10. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.10. .\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc +.PP Support for this system call is optional, depending on the setting of the .B CONFIG_ADVISE_SYSCALLS configuration option. -.SH STANDARDS -The -.BR process_madvise () -system call is Linux-specific. -.SH NOTES +.PP 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 712a19dd22..4ce4ec86ae 100644 --- a/man2/process_vm_readv.2 +++ b/man2/process_vm_readv.2 @@ -249,11 +249,11 @@ The caller does not have permission to access the address space of the process No process with ID .I pid exists. -.SH VERSIONS -These system calls were added in Linux 3.2. -Support is provided since glibc 2.15. .SH STANDARDS -These system calls are nonstandard Linux extensions. +Linux. +.SH HISTORY +Linux 3.2, +glibc 2.15. .SH NOTES The data transfers performed by .BR process_vm_readv () diff --git a/man2/ptrace.2 b/man2/ptrace.2 index 9737b38258..34152c09c0 100644 --- a/man2/ptrace.2 +++ b/man2/ptrace.2 @@ -2435,7 +2435,14 @@ 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). .SH STANDARDS +None. +.SH HISTORY SVr4, 4.3BSD. +.PP +Before Linux 2.6.26, +.\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb +.BR init (1), +the process with PID 1, may not be traced. .SH NOTES Although arguments to .BR ptrace () @@ -2452,11 +2459,6 @@ setting unused/ignored arguments to or .IR "(void\ *)\ 0". .PP -Before Linux 2.6.26, -.\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb -.BR init (1), -the process with PID 1, may not be traced. -.PP A tracees parent continues to be the tracer even if that tracer calls .BR execve (2). .PP diff --git a/man2/query_module.2 b/man2/query_module.2 index 6d6317f921..9cc7349db7 100644 --- a/man2/query_module.2 +++ b/man2/query_module.2 @@ -162,14 +162,12 @@ is set to the minimum size needed. .BR query_module () is not supported in this version of the kernel (e.g., Linux 2.6 or later). +.SH STANDARDS +Linux. .SH VERSIONS -This system call is present only up until Linux 2.4; -it was removed in Linux 2.6. +Removed in Linux 2.6. .\" Removed in Linux 2.5.48 -.SH STANDARDS -.BR query_module () -is Linux-specific. -.SH NOTES +.PP Some of the information that was formerly available via .BR query_module () can be obtained from diff --git a/man2/read.2 b/man2/read.2 index 13f999e7ba..0430b9d1ec 100644 --- a/man2/read.2 +++ b/man2/read.2 @@ -164,6 +164,8 @@ refers to a directory. Other errors may occur, depending on the object connected to .IR fd . .SH STANDARDS +POSIX.1-2008. +.SH HISTORY SVr4, 4.3BSD, POSIX.1-2001. .SH NOTES The types diff --git a/man2/readahead.2 b/man2/readahead.2 index 11f850726f..d697959791 100644 --- a/man2/readahead.2 +++ b/man2/readahead.2 @@ -64,20 +64,15 @@ does not refer to a file type to which .BR readahead () can be applied. .SH VERSIONS -The -.BR readahead () -system call appeared in Linux 2.4.13; -glibc support has been provided since glibc 2.3. -.SH STANDARDS -The -.BR readahead () -system call is Linux-specific, and its use should be avoided -in portable applications. -.SH NOTES On some 32-bit architectures, the calling signature for this system call differs, for the reasons described in .BR syscall (2). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.4.13, +glibc 2.3. .SH BUGS .BR readahead () attempts to schedule the reads in the background and return immediately. diff --git a/man2/readdir.2 b/man2/readdir.2 index 39cc4377ae..106f0e68fc 100644 --- a/man2/readdir.2 +++ b/man2/readdir.2 @@ -100,9 +100,7 @@ No such directory. .TP .B ENOTDIR File descriptor does not refer to a directory. -.SH STANDARDS -This system call is Linux-specific. -.SH NOTES +.SH VERSIONS You will need to define the .I old_linux_dirent structure yourself. @@ -111,6 +109,8 @@ However, probably you should use instead. .PP This system call does not exist on x86-64. +.SH STANDARDS +Linux. .SH SEE ALSO .BR getdents (2), .BR readdir (3) diff --git a/man2/readlink.2 b/man2/readlink.2 index de158da7e3..c911c4a7b4 100644 --- a/man2/readlink.2 +++ b/man2/readlink.2 @@ -186,20 +186,20 @@ A component of the path prefix is not a directory. is relative and .I dirfd is a file descriptor referring to a file other than a directory. -.SH VERSIONS -.BR readlinkat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. .SH STANDARDS -.BR readlink (): +POSIX.1-2008. +.SH HISTORY +.TP +.BR readlink () 4.4BSD -.RB ( readlink () -first appeared in 4.2BSD), +(first appeared in 4.2BSD), POSIX.1-2001, POSIX.1-2008. -.PP -.BR readlinkat (): +.TP +.BR readlinkat () POSIX.1-2008. -.SH NOTES +Linux 2.6.16, +glibc 2.4. +.PP Up to and including glibc 2.4, the return type of .BR readlink () was declared as @@ -207,7 +207,20 @@ was declared as Nowadays, the return type is declared as .IR ssize_t , as (newly) required in POSIX.1-2001. -.PP +.SS glibc +On older kernels where +.BR readlinkat () +is unavailable, the glibc wrapper function falls back to the use of +.BR readlink (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I dirfd +argument. +.SH NOTES Using a statically sized buffer might not provide enough room for the symbolic link contents. The required size for the buffer can be obtained from the @@ -230,19 +243,6 @@ also addresses a common portability problem when using for the buffer size, as this constant is not guaranteed to be defined per POSIX if the system does not have such limit. -.SS glibc notes -On older kernels where -.BR readlinkat () -is unavailable, the glibc wrapper function falls back to the use of -.BR readlink (). -When -.I pathname -is a relative pathname, -glibc constructs a pathname based on the symbolic link in -.I /proc/self/fd -that corresponds to the -.I dirfd -argument. .SH EXAMPLES The following program allocates the buffer needed by .BR readlink () diff --git a/man2/readv.2 b/man2/readv.2 index 76a94edd5c..b80d7ff028 100644 --- a/man2/readv.2 +++ b/man2/readv.2 @@ -287,21 +287,44 @@ is less than zero or greater than the permitted maximum. .B EOPNOTSUPP An unknown flag is specified in \fIflags\fP. .SH VERSIONS +.SS C library/kernel differences +The raw .BR preadv () and .BR pwritev () -first appeared in Linux 2.6.30; library support was added in glibc 2.10. +system calls have call signatures that differ slightly from that of the +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 +.BI " unsigned long " pos_l ", unsigned long " pos .PP +These arguments contain, respectively, the low order and high order 32 bits of +.IR offset . +.SH STANDARDS +.TP +.BR readv () +.TQ +.BR writev () +POSIX.1-2008. +.TP +.BR preadv () +.TQ +.BR pwritev () +BSD. +.TP .BR preadv2 () -and +.TQ .BR pwritev2 () -first appeared in Linux 4.6. -Library support was added in glibc 2.26. -.SH STANDARDS -.BR readv (), -.BR writev (): -POSIX.1-2001, POSIX.1-2008, -4.4BSD (these system calls first appeared in 4.2BSD). +Linux. +.SH HISTORY +.TP +.BR readv () +.TQ +.BR writev () +POSIX.1-2001, +4.4BSD (first appeared in 4.2BSD). .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument, .\" and \fIint\fP as the return type. .\" The readv/writev system calls were buggy before Linux 1.3.40. @@ -309,40 +332,13 @@ POSIX.1-2001, POSIX.1-2008, .PP .BR preadv (), .BR pwritev (): -nonstandard, but present also on the modern BSDs. +Linux 2.6.30, +glibc 2.10. .PP .BR preadv2 (), .BR pwritev2 (): -nonstandard Linux extension. -.SH NOTES -POSIX.1 allows an implementation to place a limit on -the number of items that can be passed in -.IR iov . -An implementation can advertise its limit by defining -.B IOV_MAX -in -.I <limits.h> -or at run time via the return value from -.IR sysconf(_SC_IOV_MAX) . -On modern Linux systems, the limit is 1024. -Back in Linux 2.0 days, this limit was 16. -.\" -.\" -.SS C library/kernel differences -The raw -.BR preadv () -and -.BR pwritev () -system calls have call signatures that differ slightly from that of the -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 -.BI " unsigned long " pos_l ", unsigned long " pos -.PP -These arguments contain, respectively, the low order and high order 32 bits of -.IR offset . +Linux 4.6, +glibc 2.26. .SS Historical C library/kernel differences To deal with the fact that .B IOV_MAX @@ -380,6 +376,20 @@ that the system is running a Linux kernel older than Linux 2.6.18 And since glibc 2.20 (which requires a minimum of Linux 2.6.32), the glibc wrapper functions always just directly invoke the system calls. +.SH NOTES +POSIX.1 allows an implementation to place a limit on +the number of items that can be passed in +.IR iov . +An implementation can advertise its limit by defining +.B IOV_MAX +in +.I <limits.h> +or at run time via the return value from +.IR sysconf(_SC_IOV_MAX) . +On modern Linux systems, the limit is 1024. +Back in Linux 2.0 days, this limit was 16. +.\" +.\" .SH BUGS Linux 5.9 and Linux 5.10 have a bug where .BR preadv2 () diff --git a/man2/reboot.2 b/man2/reboot.2 index 6fed0a076c..2896ed5170 100644 --- a/man2/reboot.2 +++ b/man2/reboot.2 @@ -223,9 +223,7 @@ the caller must have the .B CAP_SYS_BOOT inside its user namespace. .SH STANDARDS -.BR reboot () -is Linux-specific, -and should not be used in programs intended to be portable. +Linux. .SH SEE ALSO .BR systemctl (1), .BR systemd (1), diff --git a/man2/recv.2 b/man2/recv.2 index 81cd1957cb..31899df825 100644 --- a/man2/recv.2 +++ b/man2/recv.2 @@ -480,9 +480,32 @@ and The file descriptor .I sockfd does not refer to a socket. +.SH VERSIONS +According to POSIX.1, +.\" POSIX.1-2001, POSIX.1-2008 +the +.I msg_controllen +field of the +.I msghdr +structure should be typed as +.IR socklen_t , +and the +.I msg_iovlen +field should be typed as +.IR int , +but glibc currently types both as +.IR size_t . +.\" glibc bug for msg_controllen raised 12 Mar 2006 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 +.\" The problem is an underlying kernel issue: the size of the +.\" __kernel_size_t type used to type these fields varies +.\" across architectures, but socklen_t is always 32 bits, +.\" as (at least with GCC) is int. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, -4.4BSD (these interfaces first appeared in 4.2BSD). +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +4.4BSD (first appeared in 4.2BSD). .PP POSIX.1 describes only the .BR MSG_OOB , @@ -510,27 +533,6 @@ type was invented by POSIX. See also .BR accept (2). .PP -According to POSIX.1, -.\" POSIX.1-2001, POSIX.1-2008 -the -.I msg_controllen -field of the -.I msghdr -structure should be typed as -.IR socklen_t , -and the -.I msg_iovlen -field should be typed as -.IR int , -but glibc currently types both as -.IR size_t . -.\" glibc bug for msg_controllen raised 12 Mar 2006 -.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 -.\" The problem is an underlying kernel issue: the size of the -.\" __kernel_size_t type used to type these fields varies -.\" across architectures, but socklen_t is always 32 bits, -.\" as (at least with GCC) is int. -.PP See .BR recvmmsg (2) for information about a Linux-specific system call diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2 index 63a03bd39d..b1d9f2a286 100644 --- a/man2/recvmmsg.2 +++ b/man2/recvmmsg.2 @@ -145,14 +145,11 @@ In addition, the following error can occur: is invalid. .PP See also BUGS. -.SH VERSIONS -The -.BR recvmmsg () -system call was added in Linux 2.6.33. -Support in glibc was added in glibc 2.12. .SH STANDARDS -.BR recvmmsg () -is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.33, +glibc 2.12. .SH BUGS The .I timeout diff --git a/man2/remap_file_pages.2 b/man2/remap_file_pages.2 index f6f69c078b..8f9b5b394e 100644 --- a/man2/remap_file_pages.2 +++ b/man2/remap_file_pages.2 @@ -143,15 +143,11 @@ or .I pgoff is invalid. .\" And possibly others from vma->vm_ops->populate() -.SH VERSIONS -The -.BR remap_file_pages () -system call appeared in Linux 2.5.46; -glibc support was added in glibc 2.3.3. .SH STANDARDS -The -.BR remap_file_pages () -system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.5.46, +glibc 2.3.3. .SH NOTES Since Linux 2.6.23, .\" commit 3ee6dafc677a68e461a7ddafc94a580ebab80735 diff --git a/man2/removexattr.2 b/man2/removexattr.2 index 626ad515d7..159061e4af 100644 --- a/man2/removexattr.2 +++ b/man2/removexattr.2 @@ -77,11 +77,11 @@ Extended attributes are not supported by the filesystem, or are disabled. In addition, the errors documented in .BR stat (2) can also occur. -.SH VERSIONS -These system calls have been available since Linux 2.4; -glibc support is provided since glibc 2.3. .SH STANDARDS -These system calls are Linux-specific. +Linux. +.SH HISTORY +Linux 2.4, +glibc 2.3. .\" .SH AUTHORS .\" Andreas Gruenbacher, .\" .RI < a.gruenbacher@computer.org > diff --git a/man2/rename.2 b/man2/rename.2 index 5007ef6b65..1391e20230 100644 --- a/man2/rename.2 +++ b/man2/rename.2 @@ -488,24 +488,28 @@ was specified in but the caller does not have the .B CAP_MKNOD capability. -.SH VERSIONS -.BR renameat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. -.PP -.BR renameat2 () -was added in Linux 3.15; library support was added in glibc 2.28. .SH STANDARDS -.BR rename (): -4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008. -.PP -.BR renameat (): +.TP +.BR rename () +C11, POSIX.1-2008. +.TP +.BR renameat () POSIX.1-2008. -.PP +.TP .BR renameat2 () -is Linux-specific. -.SH NOTES -.\" +Linux. +.SH HISTORY +.TP +.BR rename () +4.3BSD, C89, POSIX.1-2001. +.TP +.BR renameat () +Linux 2.6.16, +glibc 2.4. +.TP +.BR renameat2 () +Linux 3.15, +glibc 2.28. .SS glibc notes On older kernels where .BR renameat () diff --git a/man2/request_key.2 b/man2/request_key.2 index e78321e3c2..2d9416ba84 100644 --- a/man2/request_key.2 +++ b/man2/request_key.2 @@ -425,13 +425,14 @@ Insufficient memory to create a key. The .I type argument started with a period (\[aq].\[aq]). -.SH VERSIONS -This system call first appeared in Linux 2.6.10. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.10. +.PP The ability to instantiate keys upon request was added .\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a in Linux 2.6.13. -.SH STANDARDS -This system call is a nonstandard Linux extension. .SH EXAMPLES The program below demonstrates the use of .BR request_key (). diff --git a/man2/restart_syscall.2 b/man2/restart_syscall.2 index 1ed8c55685..64e28b0631 100644 --- a/man2/restart_syscall.2 +++ b/man2/restart_syscall.2 @@ -75,12 +75,10 @@ is the return value of whatever system call is being restarted. .I errno is set as per the errors for whatever system call is being restarted by .BR restart_syscall (). -.SH VERSIONS -The -.BR restart_syscall () -system call is present since Linux 2.6. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6. .SH NOTES There is no glibc wrapper for this system call, because it is intended for use only by the kernel and diff --git a/man2/rmdir.2 b/man2/rmdir.2 index b06349e2c1..73b7d690d8 100644 --- a/man2/rmdir.2 +++ b/man2/rmdir.2 @@ -111,7 +111,9 @@ does not support the removal of directories. .I pathname refers to a directory on a read-only filesystem. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. .SH BUGS Infelicities in the protocol underlying NFS can cause the unexpected disappearance of directories which are still being used. diff --git a/man2/rt_sigqueueinfo.2 b/man2/rt_sigqueueinfo.2 index 0f6a2e19e2..046b5f382e 100644 --- a/man2/rt_sigqueueinfo.2 +++ b/man2/rt_sigqueueinfo.2 @@ -165,15 +165,15 @@ No thread matching and .I tid was found. -.SH VERSIONS -The +.SH STANDARDS +Linux. +.SH HISTORY +.TP .BR rt_sigqueueinfo () -system call was added in Linux 2.2. -The +Linux 2.2. +.TP .BR rt_tgsigqueueinfo () -system call was added in Linux 2.6.31. -.SH STANDARDS -These system calls are Linux-specific. +Linux 2.6.31. .SH NOTES Since these system calls are not intended for application use, there are no glibc wrapper functions; use diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2 index 678de36e9f..4fa085c97c 100644 --- a/man2/s390_guarded_storage.2 +++ b/man2/s390_guarded_storage.2 @@ -126,13 +126,12 @@ and the allocation of a new guarded storage control block has failed. .TP .B EOPNOTSUPP The guarded storage facility is not supported by the hardware. -.SH VERSIONS -.\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2 -This system call is available since Linux 4.12. .SH STANDARDS -This Linux-specific system call is available only on the s390 architecture. -.PP -The guarded storage facility is available beginning with System z14. +Linux on s390. +.SH HISTORY +.\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2 +Linux 4.12. +System z14. .SH NOTES The description of the guarded storage facility along with related instructions and Guarded Storage Control Block and diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2 index 6a55a6e525..be00755084 100644 --- a/man2/s390_pci_mmio_write.2 +++ b/man2/s390_pci_mmio_write.2 @@ -85,10 +85,10 @@ PCI support is not enabled. .TP .B ENOMEM Insufficient memory. -.SH VERSIONS -These system calls are available since Linux 3.19. .SH STANDARDS -This Linux-specific system call is available only on the s390 architecture. -The required PCI support is available beginning with System z EC12. +Linux on s390. +.SH HISTORY +Linux 3.19. +System z EC12. .SH SEE ALSO .BR syscall (2) diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2 index 575d8c138c..da256bb60d 100644 --- a/man2/s390_runtime_instr.2 +++ b/man2/s390_runtime_instr.2 @@ -79,12 +79,11 @@ Allocating memory for the run-time instrumentation control block failed. .TP .B EOPNOTSUPP The run-time instrumentation facility is not available. -.SH VERSIONS -This system call is available since Linux 3.7. .SH STANDARDS -This Linux-specific system call is available only on the s390 architecture. -The run-time instrumentation facility is available -beginning with System z EC12. +Linux on s390. +.SH HISTORY +Linux 3.7. +System z EC12. .SH NOTES The .I asm/runtime_instr.h diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2 index b44d940bcd..4c3c3ba2e1 100644 --- a/man2/s390_sthyi.2 +++ b/man2/s390_sthyi.2 @@ -113,10 +113,10 @@ Allocating memory for handling the CPU capacity information failed. The value specified in .I function_code is not valid. -.SH VERSIONS -This system call is available since Linux 4.15. .SH STANDARDS -This Linux-specific system call is available only on the s390 architecture. +Linux on s390. +.SH HISTORY +Linux 4.15. .SH NOTES 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 diff --git a/man2/sched_get_priority_max.2 b/man2/sched_get_priority_max.2 index 70922ee3bc..5185e60398 100644 --- a/man2/sched_get_priority_max.2 +++ b/man2/sched_get_priority_max.2 @@ -97,7 +97,9 @@ The argument .I policy does not identify a defined scheduling policy. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. .SH SEE ALSO .ad l .nh diff --git a/man2/sched_rr_get_interval.2 b/man2/sched_rr_get_interval.2 index be2a246ab7..328e4a4f74 100644 --- a/man2/sched_rr_get_interval.2 +++ b/man2/sched_rr_get_interval.2 @@ -64,16 +64,21 @@ The system call is not yet implemented (only on rather old kernels). .B ESRCH Could not find a process with the ID .IR pid . +.SH VERSIONS +.SS Linux +Linux 3.9 added +.\" commit ce0dbbbb30aee6a835511d5be446462388ba9eee +a new mechanism for adjusting (and viewing) the +.B SCHED_RR +quantum: the +.I /proc/sys/kernel/sched_rr_timeslice_ms +file exposes the quantum as a millisecond value, whose default is 100. +Writing 0 to this file resets the quantum to the default value. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. -.SH NOTES -POSIX systems on which -.BR sched_rr_get_interval () -is available define -.B _POSIX_PRIORITY_SCHEDULING -in -.IR <unistd.h> . -.SS Linux notes +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SS Linux POSIX does not specify any mechanism for controlling the size of the round-robin time quantum. Older Linux kernels provide a (nonportable) method of doing this. @@ -87,15 +92,13 @@ quantum has varied somewhat across kernel versions. This method of adjusting the quantum was removed .\" commit a4ec24b48ddef1e93f7578be53270f0b95ad666c starting with Linux 2.6.24. -.PP -Linux 3.9 added -.\" commit ce0dbbbb30aee6a835511d5be446462388ba9eee -a new mechanism for adjusting (and viewing) the -.B SCHED_RR -quantum: the -.I /proc/sys/kernel/sched_rr_timeslice_ms -file exposes the quantum as a millisecond value, whose default is 100. -Writing 0 to this file resets the quantum to the default value. +.SH NOTES +POSIX systems on which +.BR sched_rr_get_interval () +is available define +.B _POSIX_PRIORITY_SCHEDULING +in +.IR <unistd.h> . .\" .SH BUGS .\" As of Linux 1.3.81 .\" .BR sched_rr_get_interval () diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2 index 86a9353913..01e4a4f9e5 100644 --- a/man2/sched_setaffinity.2 +++ b/man2/sched_setaffinity.2 @@ -134,9 +134,12 @@ capability in the user namespace of the thread .TP .B ESRCH The thread whose ID is \fIpid\fP could not be found. -.SH VERSIONS -The CPU affinity system calls were introduced in Linux kernel 2.5.8. -The system call wrappers were introduced in glibc 2.3. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5.8, +glibc 2.3. +.PP Initially, the glibc interfaces included a .I cpusetsize argument, typed as @@ -145,8 +148,6 @@ In glibc 2.3.3, the .I cpusetsize argument was removed, but was then restored in glibc 2.3.4, with type .IR size_t . -.SH STANDARDS -These system calls are Linux-specific. .SH NOTES After a call to .BR sched_setaffinity (), diff --git a/man2/sched_setattr.2 b/man2/sched_setattr.2 index f610c73fde..fd92a86b26 100644 --- a/man2/sched_setattr.2 +++ b/man2/sched_setattr.2 @@ -372,11 +372,11 @@ The CPU affinity mask of the thread specified by does not include all CPUs in the system (see .BR sched_setaffinity (2)). -.SH VERSIONS -These system calls first appeared in Linux 3.14. -.\" FIXME . Add glibc version .SH STANDARDS -These system calls are nonstandard Linux extensions. +Linux. +.SH HISTORY +Linux 3.14. +.\" FIXME . Add glibc version .SH NOTES glibc does not provide wrappers for these system calls; call them using .BR syscall (2). diff --git a/man2/sched_setparam.2 b/man2/sched_setparam.2 index 25d7b580bb..9aafc2ebbc 100644 --- a/man2/sched_setparam.2 +++ b/man2/sched_setparam.2 @@ -100,7 +100,9 @@ capability). .B ESRCH The thread whose ID is \fIpid\fP could not be found. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. .SH SEE ALSO .ad l .nh diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2 index 19a1f040f1..a6333c1abb 100644 --- a/man2/sched_setscheduler.2 +++ b/man2/sched_setscheduler.2 @@ -147,27 +147,7 @@ The calling thread does not have appropriate privileges. .TP .B ESRCH The thread whose ID is \fIpid\fP could not be found. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008 (but see BUGS below). -The \fBSCHED_BATCH\fP and \fBSCHED_IDLE\fP policies are Linux-specific. -.SH NOTES -Further details of the semantics of all of the above "normal" -and "real-time" scheduling policies can be found in the -.BR sched (7) -manual page. -That page also describes an additional policy, -.BR SCHED_DEADLINE , -which is settable only via -.BR sched_setattr (2). -.PP -POSIX systems on which -.BR sched_setscheduler () -and -.BR sched_getscheduler () -are available define -.B _POSIX_PRIORITY_SCHEDULING -in \fI<unistd.h>\fP. -.PP +.SH VERSIONS POSIX.1 does not detail the permissions that an unprivileged thread requires in order to call .BR sched_setscheduler (), @@ -196,6 +176,32 @@ and instead of the .BR sched_* (2) system calls.) +.SH STANDARDS +POSIX.1-2008 (but see BUGS below). +.PP +.B SCHED_BATCH +and +.B SCHED_IDLE +are Linux-specific. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Further details of the semantics of all of the above "normal" +and "real-time" scheduling policies can be found in the +.BR sched (7) +manual page. +That page also describes an additional policy, +.BR SCHED_DEADLINE , +which is settable only via +.BR sched_setattr (2). +.PP +POSIX systems on which +.BR sched_setscheduler () +and +.BR sched_getscheduler () +are available define +.B _POSIX_PRIORITY_SCHEDULING +in \fI<unistd.h>\fP. .SH BUGS POSIX.1 says that on success, .BR sched_setscheduler () diff --git a/man2/sched_yield.2 b/man2/sched_yield.2 index b58448a09a..f1024762af 100644 --- a/man2/sched_yield.2 +++ b/man2/sched_yield.2 @@ -36,7 +36,9 @@ In the Linux implementation, .BR sched_yield () always succeeds. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. .SH NOTES If the calling thread is the only thread in the highest priority list at that time, diff --git a/man2/seccomp.2 b/man2/seccomp.2 index 32706397f0..ecfdb8696a 100644 --- a/man2/seccomp.2 +++ b/man2/seccomp.2 @@ -861,15 +861,11 @@ but the kernel does not support the filter return action specified by .B ESRCH Another thread caused a failure during thread sync, but its ID could not be determined. -.SH VERSIONS -The -.BR seccomp () -system call first appeared in Linux 3.17. -.\" FIXME . Add glibc version .SH STANDARDS -The -.BR seccomp () -system call is a nonstandard Linux extension. +Linux. +.SH HISTORY +Linux 3.17. +.\" FIXME . Add glibc version .SH NOTES Rather than hand-coding seccomp filters as shown in the example below, you may prefer to employ the diff --git a/man2/select.2 b/man2/select.2 index 7718b75067..fd592a3b23 100644 --- a/man2/select.2 +++ b/man2/select.2 @@ -421,29 +421,44 @@ is invalid. .B ENOMEM Unable to allocate memory for internal tables. .SH VERSIONS -.BR pselect () -was added in Linux 2.6.16. -Prior to this, -.BR pselect () -was emulated in glibc (but see BUGS). +On some other UNIX systems, +.\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett +.BR select () +can fail with the error +.B EAGAIN +if the system fails to allocate kernel-internal resources, rather than +.B ENOMEM +as Linux does. +POSIX specifies this error for +.BR poll (2), +but not for +.BR select (). +Portable programs may wish to check for +.B EAGAIN +and loop, just as with +.BR EINTR . .SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP .BR select () -conforms to POSIX.1-2001, POSIX.1-2008, and -4.4BSD -.RB ( select () -first appeared in 4.2BSD). +POSIX.1-2001, 4.4BSD (first appeared in 4.2BSD). +.IP Generally portable to/from non-BSD systems supporting clones of the BSD socket layer (including System\ V variants). However, note that the System\ V variant typically sets the timeout variable before returning, but the BSD variant does not. -.PP +.TP .BR pselect () -is defined in POSIX.1g, and in -POSIX.1-2001 and POSIX.1-2008. -.PP +Linux 2.6.16. +POSIX.1g, POSIX.1-2001. +.IP +Prior to this, +it was emulated in glibc (but see BUGS). +.TP .B fd_set -is defined in POSIX.1-2001 and later. +POSIX.1-2001. .SH NOTES The following header also provides the .I fd_set @@ -474,23 +489,6 @@ and is not affected by the .B O_NONBLOCK flag. -.PP -On some other UNIX systems, -.\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett -.BR select () -can fail with the error -.B EAGAIN -if the system fails to allocate kernel-internal resources, rather than -.B ENOMEM -as Linux does. -POSIX specifies this error for -.BR poll (2), -but not for -.BR select (). -Portable programs may wish to check for -.B EAGAIN -and loop, just as with -.BR EINTR . .\" .SS The self-pipe trick On systems that lack diff --git a/man2/semctl.2 b/man2/semctl.2 index 6190628582..1cb71ab55f 100644 --- a/man2/semctl.2 +++ b/man2/semctl.2 @@ -503,10 +503,7 @@ and the value to which is to be set (for some semaphore of the set) is less than 0 or greater than the implementation limit .BR SEMVMX . -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. -.\" SVr4 documents more error conditions EINVAL and EOVERFLOW. -.PP +.SH VERSIONS POSIX.1 specifies the .\" POSIX.1-2001, POSIX.1-2008 .I sem_nsems @@ -518,54 +515,6 @@ and the field is so defined on most other systems. It was also so defined on Linux 2.2 and earlier, but, since Linux 2.4, the field has the type .IR "unsigned\ long" . -.SH NOTES -The -.BR IPC_INFO , -.BR SEM_STAT , -and -.B SEM_INFO -operations are used by the -.BR ipcs (1) -program to provide information on allocated resources. -In the future these may modified or moved to a -.I /proc -filesystem interface. -.PP -Various fields in a \fIstruct semid_ds\fP were typed as -.I short -under Linux 2.2 -and have become -.I long -under Linux 2.4. -To take advantage of this, -a recompilation under glibc-2.1.91 or later should suffice. -(The kernel distinguishes old and new calls by an -.B IPC_64 -flag in -.IR cmd .) -.PP -In some earlier versions of glibc, the -.I semun -union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires -.\" POSIX.1-2001, POSIX.1-2008 -that the caller define this union. -On versions of glibc where this union is \fInot\fP defined, -the macro -.B _SEM_SEMUN_UNDEFINED -is defined in \fI<sys/sem.h>\fP. -.PP -The following system limit on semaphore sets affects a -.BR semctl () -call: -.TP -.B SEMVMX -Maximum value for -.BR semval : -implementation dependent (32767). -.PP -For greater portability, it is best to always call -.BR semctl () -with four arguments. .\" .SS The sempid value POSIX.1 defines @@ -609,6 +558,59 @@ operations. This was rectified .\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f in Linux 4.6. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVr4 documents more error conditions EINVAL and EOVERFLOW. +.PP +Various fields in a \fIstruct semid_ds\fP were typed as +.I short +under Linux 2.2 +and have become +.I long +under Linux 2.4. +To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an +.B IPC_64 +flag in +.IR cmd .) +.PP +In some earlier versions of glibc, the +.I semun +union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires +.\" POSIX.1-2001, POSIX.1-2008 +that the caller define this union. +On versions of glibc where this union is \fInot\fP defined, +the macro +.B _SEM_SEMUN_UNDEFINED +is defined in \fI<sys/sem.h>\fP. +.SH NOTES +The +.BR IPC_INFO , +.BR SEM_STAT , +and +.B SEM_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future these may modified or moved to a +.I /proc +filesystem interface. +.PP +The following system limit on semaphore sets affects a +.BR semctl () +call: +.TP +.B SEMVMX +Maximum value for +.BR semval : +implementation dependent (32767). +.PP +For greater portability, it is best to always call +.BR semctl () +with four arguments. .SH EXAMPLES See .BR shmop (2). diff --git a/man2/semget.2 b/man2/semget.2 index a22ebcd753..a895505859 100644 --- a/man2/semget.2 +++ b/man2/semget.2 @@ -197,6 +197,8 @@ or the system wide maximum number of semaphores .RB ( SEMMNS ), would be exceeded. .SH STANDARDS +POSIX.1-2008. +.SH HISTORY SVr4, POSIX.1-2001. .\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN, .\" ERANGE, EFAULT. diff --git a/man2/semop.2 b/man2/semop.2 index 7a1416a268..fe2906be43 100644 --- a/man2/semop.2 +++ b/man2/semop.2 @@ -355,15 +355,12 @@ is greater than .BR SEMVMX , the implementation dependent maximum value for .IR semval . -.SH VERSIONS -.BR semtimedop () -first appeared in Linux 2.5.52, -and was subsequently backported into Linux 2.4.22. -glibc support for -.BR semtimedop () -first appeared in Linux 2.3.3. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. +POSIX.1-2008. +.SH VERSIONS +Linux 2.5.52 (backported into Linux 2.4.22), +glibc 2.3.3. +POSIX.1-2001, SVr4. .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC. .SH NOTES The diff --git a/man2/send.2 b/man2/send.2 index 3f0b744301..bea22da15f 100644 --- a/man2/send.2 +++ b/man2/send.2 @@ -437,21 +437,7 @@ will also receive a unless .B MSG_NOSIGNAL is set. -.SH STANDARDS -4.4BSD, SVr4, POSIX.1-2001. -These interfaces first appeared in 4.2BSD. -.PP -POSIX.1-2001 describes only the -.B MSG_OOB -and -.B MSG_EOR -flags. -POSIX.1-2008 adds a specification of -.BR MSG_NOSIGNAL . -The -.B MSG_CONFIRM -flag is a Linux extension. -.SH NOTES +.SH VERSIONS According to POSIX.1-2001, the .I msg_controllen field of the @@ -470,7 +456,23 @@ but glibc currently types both as .\" __kernel_size_t type used to type these fields varies .\" across architectures, but socklen_t is always 32 bits, .\" as (at least with GCC) is int. +.SH STANDARDS +POSIX.1-2008. +.PP +.B MSG_CONFIRM +is a Linux extension. +.SH HISTORY +4.4BSD, SVr4, POSIX.1-2001. +(first appeared in 4.2BSD). .PP +POSIX.1-2001 describes only the +.B MSG_OOB +and +.B MSG_EOR +flags. +POSIX.1-2008 adds a specification of +.BR MSG_NOSIGNAL . +.SH NOTES See .BR sendmmsg (2) for information about a Linux-specific system call diff --git a/man2/sendfile.2 b/man2/sendfile.2 index 07a2c5b35d..5574eff2b4 100644 --- a/man2/sendfile.2 +++ b/man2/sendfile.2 @@ -165,34 +165,15 @@ the input file or the output file. .I offset is not NULL but the input file is not seekable. .SH VERSIONS -.BR sendfile () -first appeared in Linux 2.2. -The include file -.I <sys/sendfile.h> -is present since glibc 2.1. -.SH STANDARDS -Not specified in POSIX.1-2001, nor in other standards. -.PP Other UNIX systems implement .BR sendfile () with different semantics and prototypes. It should not be used in portable programs. -.SH NOTES -.BR sendfile () -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 -If you plan to use -.BR sendfile () -for sending files to a TCP socket, but need -to send some header data in front of the file contents, you will find -it useful to employ the -.B TCP_CORK -option, described in -.BR tcp (7), -to minimize the number of packets and to tune performance. +.SH STANDARDS +None. +.SH HISTORY +Linux 2.2, +glibc 2.1. .PP In Linux 2.4 and earlier, .I out_fd @@ -211,6 +192,22 @@ argument. The glibc .BR sendfile () wrapper function transparently deals with the kernel differences. +.SH NOTES +.BR sendfile () +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 +If you plan to use +.BR sendfile () +for sending files to a TCP socket, but need +to send some header data in front of the file contents, you will find +it useful to employ the +.B TCP_CORK +option, described in +.BR tcp (7), +to minimize the number of packets and to tune performance. .PP Applications may wish to fall back to .BR read (2) diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2 index 4e5475c45a..b9f4786acf 100644 --- a/man2/sendmmsg.2 +++ b/man2/sendmmsg.2 @@ -126,14 +126,11 @@ See also BUGS. .\" .\" This matches the behavior of other syscalls like read/write - it .\" is not an error if less than the requested number of elements are sent. -.SH VERSIONS -The -.BR sendmmsg () -system call was added in Linux 3.0. -Support in glibc was added in Linux 2.14. .SH STANDARDS -.BR sendmmsg () -is Linux-specific. +Linux. +.SH HISTORY +Linux 3.0, +glibc 2.14. .SH NOTES The value specified in .I vlen diff --git a/man2/set_mempolicy.2 b/man2/set_mempolicy.2 index 844fa08393..7b32ee1dc7 100644 --- a/man2/set_mempolicy.2 +++ b/man2/set_mempolicy.2 @@ -319,12 +319,10 @@ other than .TP .B ENOMEM Insufficient kernel memory was available. -.SH VERSIONS -The -.BR set_mempolicy () -system call was added in Linux 2.6.7. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.7. .SH NOTES 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 diff --git a/man2/set_thread_area.2 b/man2/set_thread_area.2 index ccfacc70dd..02f65e0418 100644 --- a/man2/set_thread_area.2 +++ b/man2/set_thread_area.2 @@ -164,17 +164,15 @@ was invoked as a 64-bit system call. .B ESRCH .RB ( set_thread_area ()) A free TLS entry could not be located. -.SH VERSIONS -.BR set_thread_area () -first appeared in Linux 2.5.29. -.BR get_thread_area () -first appeared in Linux 2.5.32. .SH STANDARDS +Linux. +.SH HISTORY +.TP .BR set_thread_area () -and +Linux 2.5.29. +.TP .BR get_thread_area () -are Linux-specific and should not be used in programs that are intended -to be portable. +Linux 2.5.32. .SH NOTES These system calls are generally intended for use only by threading libraries. .PP diff --git a/man2/set_tid_address.2 b/man2/set_tid_address.2 index a766d5bef5..9c4c68da0d 100644 --- a/man2/set_tid_address.2 +++ b/man2/set_tid_address.2 @@ -85,11 +85,12 @@ always returns the caller's thread ID. .SH ERRORS .BR set_tid_address () always succeeds. -.SH VERSIONS -This call is present since Linux 2.5.48. -Details as given here are valid since Linux 2.5.49. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.5.48. +.PP +Details as given here are valid since Linux 2.5.49. .SH SEE ALSO .BR clone (2), .BR futex (2), diff --git a/man2/seteuid.2 b/man2/seteuid.2 index 14b23b3f40..3e9d1efabe 100644 --- a/man2/seteuid.2 +++ b/man2/seteuid.2 @@ -80,9 +80,7 @@ capability in its user namespace) and .I egid does not match the current real group ID, current effective group ID, or current saved set-group-ID. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.3BSD. -.SH NOTES +.SH VERSIONS 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). @@ -122,6 +120,10 @@ are implemented as library functions that call, respectively, .BR setreuid (2) and .BR setregid (2). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. .SH SEE ALSO .BR geteuid (2), .BR setresuid (2), diff --git a/man2/setfsgid.2 b/man2/setfsgid.2 index eb35af7e1d..bd17d69999 100644 --- a/man2/setfsgid.2 +++ b/man2/setfsgid.2 @@ -19,7 +19,7 @@ Standard C library .nf .B #include <sys/fsuid.h> .PP -.BI "int setfsgid(gid_t " fsgid ); +.BI "[[deprecated]] int setfsgid(gid_t " fsgid ); .fi .SH DESCRIPTION On Linux, a process has both a filesystem group ID and an effective group ID. @@ -48,14 +48,21 @@ saved set-group-ID, or current the filesystem user ID. .SH RETURN VALUE On both success and failure, this call returns the previous filesystem group ID of the caller. -.SH VERSIONS -This system call is present since Linux 1.2. -.\" This system call is present since Linux 1.1.44 -.\" and in libc since libc 4.7.6. .SH STANDARDS -.BR setfsgid () -is Linux-specific and should not be used in programs intended -to be portable. +Linux. +.SH HISTORY +Linux 1.2. +.\" Linux 1.1.44 +.\" and in libc since libc 4.7.6. +.SS C library/kernel differences +In glibc 2.15 and earlier, +when the wrapper for this system call determines that the argument can't be +passed to the kernel without integer truncation (because the kernel +is old and does not support 32-bit group IDs), +it will return \-1 and set \fIerrno\fP to +.B EINVAL +without attempting +the system call. .SH NOTES The filesystem group ID concept and the .BR setfsgid () @@ -78,15 +85,6 @@ supporting 32-bit IDs. The glibc .BR setfsgid () wrapper function transparently deals with the variation across kernel versions. -.SS C library/kernel differences -In glibc 2.15 and earlier, -when the wrapper for this system call determines that the argument can't be -passed to the kernel without integer truncation (because the kernel -is old and does not support 32-bit group IDs), -it will return \-1 and set \fIerrno\fP to -.B EINVAL -without attempting -the system call. .SH BUGS No error indications of any kind are returned to the caller, and the fact that both successful and unsuccessful calls return diff --git a/man2/setfsuid.2 b/man2/setfsuid.2 index 167eca1e3b..9f0b941ca2 100644 --- a/man2/setfsuid.2 +++ b/man2/setfsuid.2 @@ -19,7 +19,7 @@ Standard C library .nf .B #include <sys/fsuid.h> .PP -.BI "int setfsuid(uid_t " fsuid ); +.BI "[[deprecated]] int setfsuid(uid_t " fsuid ); .fi .SH DESCRIPTION On Linux, a process has both a filesystem user ID and an effective user ID. @@ -59,15 +59,13 @@ saved set-user-ID, or current filesystem user ID. .SH RETURN VALUE On both success and failure, this call returns the previous filesystem user ID of the caller. -.SH VERSIONS -This system call is present since Linux 1.2. -.\" This system call is present since Linux 1.1.44 -.\" and in libc since libc 4.7.6. .SH STANDARDS -.BR setfsuid () -is Linux-specific and should not be used in programs intended -to be portable. -.SH NOTES +Linux. +.SH HISTORY +Linux 1.2. +.\" Linux 1.1.44 +.\" and in libc since libc 4.7.6. +.PP 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 diff --git a/man2/setgid.2 b/man2/setgid.2 index 1e14a7271a..6012295231 100644 --- a/man2/setgid.2 +++ b/man2/setgid.2 @@ -54,19 +54,7 @@ The calling process is not privileged (does not have the .I gid does not match the real group ID or saved set-group-ID of the calling process. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. -.SH NOTES -The original Linux -.BR setgid () -system call supported only 16-bit group IDs. -Subsequently, Linux 2.4 added -.BR setgid32 () -supporting 32-bit IDs. -The glibc -.BR setgid () -wrapper function transparently deals with the variation across kernel versions. -.\" +.SH VERSIONS .SS C library/kernel differences At the kernel level, user IDs and group IDs are a per-thread attribute. However, POSIX requires that all threads in a process @@ -81,6 +69,20 @@ that when one thread changes credentials, all of the other threads in the process also change their credentials. For details, see .BR nptl (7). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.PP +The original Linux +.BR setgid () +system call supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR setgid32 () +supporting 32-bit IDs. +The glibc +.BR setgid () +wrapper function transparently deals with the variation across kernel versions. .SH SEE ALSO .BR getgid (2), .BR setegid (2), diff --git a/man2/setns.2 b/man2/setns.2 index 4de32d5c57..93e9933fc5 100644 --- a/man2/setns.2 +++ b/man2/setns.2 @@ -302,15 +302,11 @@ for this operation. .I fd is a PID file descriptor but the process it refers to no longer exists (i.e., it has terminated and been waited on). -.SH VERSIONS -The -.BR setns () -system call first appeared in Linux 3.0; -library support was added in glibc 2.14. .SH STANDARDS -The -.BR setns () -system call is Linux-specific. +Linux. +.SH VERSIONS +Linux 3.0, +glibc 2.14. .SH NOTES For further information on the .IR /proc/ pid /ns/ diff --git a/man2/setpgid.2 b/man2/setpgid.2 index ad4ea38dc8..fb67d2ab5f 100644 --- a/man2/setpgid.2 +++ b/man2/setpgid.2 @@ -229,27 +229,37 @@ For .I pid is not the calling process and not a child of the calling process. .SH STANDARDS +.TP +.BR getpgid () +.TQ .BR setpgid () -and the version of -.BR getpgrp () -with no arguments -conform to POSIX.1-2001. -.PP -POSIX.1-2001 also specifies +.TQ +.BR getpgrp "() (no args)" +.TQ +.BR setpgrp "() (no args)" +POSIX.1-2008 (but see HISTORY). +.TP +.BR setpgrp "() (2 args)" +.TQ +.BR getpgrp "() (1 arg)" +None. +.SH HISTORY +.TP .BR getpgid () -and the version of -.BR setpgrp () -that takes no arguments. -(POSIX.1-2008 marks this -.BR setpgrp () -specification as obsolete.) -.PP -The version of -.BR getpgrp () -with one argument and the version of -.BR setpgrp () -that takes two arguments derive from 4.2BSD, -and are not specified by POSIX.1. +.TQ +.BR setpgid () +.TQ +.BR getpgrp "() (no args)" +POSIX.1-2001. +.TP +.BR setpgrp "() (no args)" +POSIX.1-2001. +POSIX.1-2008 marks it as obsolete. +.TP +.BR setpgrp "() (2 args)" +.TQ +.BR getpgrp "() (1 arg)" +4.2BSD. .SH NOTES A child created via .BR fork (2) diff --git a/man2/setresuid.2 b/man2/setresuid.2 index 081a8e920a..874db6f25f 100644 --- a/man2/setresuid.2 +++ b/man2/setresuid.2 @@ -97,14 +97,28 @@ for it is .BR CAP_SETGID . .SH VERSIONS -These calls are available under Linux since Linux 2.1.44. +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including those for +.BR setresuid () +and +.BR setresgid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). .SH STANDARDS -These calls are nonstandard; -they also appear on HP-UX and some of the BSDs. -.SH NOTES -Under HP-UX and FreeBSD, the prototype is found in -.IR <unistd.h> . -Under Linux, the prototype is provided since glibc 2.3.2. +None. +.SH HISTORY +Linux 2.1.44, +glibc 2.3.2. +HP-UX, FreeBSD. .PP The original Linux .BR setresuid () @@ -121,23 +135,6 @@ The glibc and .BR setresgid () wrapper functions transparently deal with the variations across kernel versions. -.\" -.SS C library/kernel differences -At the kernel level, user IDs and group IDs are a per-thread attribute. -However, POSIX requires that all threads in a process -share the same credentials. -The NPTL threading implementation handles the POSIX requirements by -providing wrapper functions for -the various system calls that change process UIDs and GIDs. -These wrapper functions (including those for -.BR setresuid () -and -.BR setresgid ()) -employ a signal-based technique to ensure -that when one thread changes credentials, -all of the other threads in the process also change their credentials. -For details, see -.BR nptl (7). .SH SEE ALSO .BR getresuid (2), .BR getuid (2), diff --git a/man2/setreuid.2 b/man2/setreuid.2 index 842c2dc2b5..702d3b4e03 100644 --- a/man2/setreuid.2 +++ b/man2/setreuid.2 @@ -120,17 +120,7 @@ swapping the effective user (group) ID with the real user (group) ID, or (ii) setting one to the value of the other or (iii) setting the effective user (group) ID to the value of the saved set-user-ID (saved set-group-ID) was specified. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.3BSD -.RB ( setreuid () -and -.BR setregid () -first appeared in 4.2BSD). -.SH NOTES -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 +.SH VERSIONS POSIX.1 does not specify all of the UID changes that Linux permits for an unprivileged process. For @@ -150,6 +140,14 @@ across implementations. .PP 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 +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 The original Linux .BR setreuid () diff --git a/man2/setsid.2 b/man2/setsid.2 index 493e3567b2..fe86939e2b 100644 --- a/man2/setsid.2 +++ b/man2/setsid.2 @@ -52,7 +52,9 @@ Thus, in particular, .BR setsid () fails if the calling process is already a process group leader. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. .SH NOTES A child created via .BR fork (2) diff --git a/man2/setuid.2 b/man2/setuid.2 index 6293ddd15e..c124ff4fc3 100644 --- a/man2/setuid.2 +++ b/man2/setuid.2 @@ -100,11 +100,39 @@ The user is not privileged (Linux: does not have the capability in its user namespace) and .I uid does not match the real UID or saved set-user-ID of the calling process. +.SH VERSIONS +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including the one for +.BR setuid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.PP 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 +The original Linux +.BR setuid () +system call supported only 16-bit user IDs. +Subsequently, Linux 2.4 added +.BR setuid32 () +supporting 32-bit IDs. +The glibc +.BR setuid () +wrapper function transparently deals with the variation across kernel versions. .SH NOTES Linux has the concept of the filesystem user ID, normally equal to the effective user ID. @@ -118,31 +146,6 @@ If .I uid is different from the old effective UID, the process will be forbidden from leaving core dumps. -.PP -The original Linux -.BR setuid () -system call supported only 16-bit user IDs. -Subsequently, Linux 2.4 added -.BR setuid32 () -supporting 32-bit IDs. -The glibc -.BR setuid () -wrapper function transparently deals with the variation across kernel versions. -.\" -.SS C library/kernel differences -At the kernel level, user IDs and group IDs are a per-thread attribute. -However, POSIX requires that all threads in a process -share the same credentials. -The NPTL threading implementation handles the POSIX requirements by -providing wrapper functions for -the various system calls that change process UIDs and GIDs. -These wrapper functions (including the one for -.BR setuid ()) -employ a signal-based technique to ensure -that when one thread changes credentials, -all of the other threads in the process also change their credentials. -For details, see -.BR nptl (7). .SH SEE ALSO .BR getuid (2), .BR seteuid (2), diff --git a/man2/setup.2 b/man2/setup.2 index a8c94c4b2c..24e0253d19 100644 --- a/man2/setup.2 +++ b/man2/setup.2 @@ -21,7 +21,7 @@ Standard C library .nf .B #include <unistd.h> .PP -.B int setup(void); +.B [[deprecated]] int setup(void); .fi .SH DESCRIPTION .BR setup () @@ -42,12 +42,11 @@ always returns \-1 for a user process. .TP .B EPERM Always, for a user process. -.SH VERSIONS -Since Linux 2.1.121, no such function exists anymore. .SH STANDARDS -This function is Linux-specific, and should not be used in programs -intended to be portable, or indeed in any programs at all. -.SH NOTES +Linux. +.SH VERSIONS +Removed in Linux 2.1.121. +.PP 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 8c658223cc..43151ebd5e 100644 --- a/man2/setxattr.2 +++ b/man2/setxattr.2 @@ -137,11 +137,11 @@ The size of or .I value exceeds a filesystem-specific limit. -.SH VERSIONS -These system calls have been available since Linux 2.4; -glibc support is provided since glibc 2.3. .SH STANDARDS -These system calls are Linux-specific. +Linux. +.SH HISTORY +Linux 2.4, +glibc 2.3. .\" .SH AUTHORS .\" Andreas Gruenbacher, .\" .RI < a.gruenbacher@computer.org > diff --git a/man2/sgetmask.2 b/man2/sgetmask.2 index d342076db6..a1af77c157 100644 --- a/man2/sgetmask.2 +++ b/man2/sgetmask.2 @@ -46,15 +46,15 @@ always successfully returns the signal mask. always succeeds, and returns the previous signal mask. .SH ERRORS These system calls always succeed. -.SH VERSIONS +.SH STANDARDS +Linux. +.SH HISTORY Since Linux 3.16, .\" f6187769dae48234f3877df3c4d99294cc2254fa support for these system calls is optional, depending on whether the kernel was built with the .B CONFIG_SGETMASK_SYSCALL option. -.SH STANDARDS -These system calls are Linux-specific. .SH NOTES These system calls are unaware of signal numbers greater than 31 (i.e., real-time signals). diff --git a/man2/shmctl.2 b/man2/shmctl.2 index bc456849d3..e1c5a9aff4 100644 --- a/man2/shmctl.2 +++ b/man2/shmctl.2 @@ -441,24 +441,7 @@ capability). (Since Linux 2.6.9, this error can also occur if the .B RLIMIT_MEMLOCK is 0 and the caller is not privileged.) -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. -.\" SVr4 documents additional error conditions EINVAL, -.\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents -.\" an EIDRM error condition. -.SH NOTES -The -.BR IPC_INFO , -.BR SHM_STAT , -and -.B SHM_INFO -operations are used by the -.BR ipcs (1) -program to provide information on allocated resources. -In the future, these may modified or moved to a -.I /proc -filesystem interface. -.PP +.SH VERSIONS Linux permits a process to attach .RB ( shmat (2)) a shared memory segment that has already been marked for deletion @@ -466,6 +449,13 @@ using .IR shmctl(IPC_RMID) . This feature is not available on other UNIX implementations; portable applications should avoid relying on it. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVr4 documents additional error conditions EINVAL, +.\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents +.\" an EIDRM error condition. .PP Various fields in a \fIstruct shmid_ds\fP were typed as .I short @@ -479,6 +469,18 @@ a recompilation under glibc-2.1.91 or later should suffice. .B IPC_64 flag in .IR cmd .) +.SH NOTES +The +.BR IPC_INFO , +.BR SHM_STAT , +and +.B SHM_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future, these may modified or moved to a +.I /proc +filesystem interface. .SH SEE ALSO .BR mlock (2), .BR setrlimit (2), diff --git a/man2/shmget.2 b/man2/shmget.2 index c4d8df8ed6..c0b1a669c9 100644 --- a/man2/shmget.2 +++ b/man2/shmget.2 @@ -262,13 +262,15 @@ group; see the description of in .BR proc (5). .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. -.\" SVr4 documents an additional error condition EEXIST. +POSIX.1-2008. .PP .B SHM_HUGETLB and .B SHM_NORESERVE are Linux extensions. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVr4 documents an additional error condition EEXIST. .SH NOTES .B IPC_PRIVATE isn't a flag field but a diff --git a/man2/shmop.2 b/man2/shmop.2 index 6ab2e063a0..a28d249e10 100644 --- a/man2/shmop.2 +++ b/man2/shmop.2 @@ -201,7 +201,9 @@ or, .I shmaddr is not aligned on a page boundary. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. .\" SVr4 documents an additional error condition EMFILE. .PP In SVID 3 (or perhaps earlier), diff --git a/man2/shutdown.2 b/man2/shutdown.2 index 82411180b9..41fcc61d42 100644 --- a/man2/shutdown.2 +++ b/man2/shutdown.2 @@ -67,9 +67,10 @@ The file descriptor .I sockfd does not refer to a socket. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.4BSD -.RB ( shutdown () -first appeared in 4.2BSD). +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.4BSD +(first appeared in 4.2BSD). .SH NOTES The constants .BR SHUT_RD , diff --git a/man2/sigaction.2 b/man2/sigaction.2 index c352da8b5c..6c241561b3 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -942,35 +942,63 @@ This will also be generated if an attempt is made to change the action for .BR SIGKILL " or " SIGSTOP , which cannot be caught or ignored. +.SH VERSIONS +.SS C library/kernel differences +The glibc wrapper function for +.BR sigaction () +gives an error +.RB ( EINVAL ) +on attempts to change the disposition of the two real-time signals +used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.PP +On architectures where the signal trampoline resides in the C library, +the glibc wrapper function for +.BR sigaction () +places the address of the trampoline code in the +.I act.sa_restorer +field and sets the +.B SA_RESTORER +flag in the +.I act.sa_flags +field. +See +.BR sigreturn (2). +.PP +The original Linux system call was named +.BR sigaction (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.I sigset_t +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigaction (), +was added to support an enlarged +.I sigset_t +type. +The new system call takes a fourth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal sets in +.I act.sa_mask +and +.IR oldact.sa_mask . +This argument is currently required to have the value +.I sizeof(sigset_t) +(or the error +.B EINVAL +results). +The glibc +.BR sigaction () +wrapper function hides these details from us, transparently calling +.BR rt_sigaction () +when the kernel provides it. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. .\" SVr4 does not document the EINTR condition. -.SH NOTES -A child created via -.BR fork (2) -inherits a copy of its parent's signal dispositions. -During an -.BR execve (2), -the dispositions of handled signals are reset to the default; -the dispositions of ignored signals are left unchanged. -.PP -According to POSIX, the behavior of a process is undefined after it -ignores a -.BR SIGFPE , -.BR SIGILL , -or -.B SIGSEGV -signal that was not generated by -.BR kill (2) -or -.BR raise (3). -Integer division by zero has undefined result. -On some architectures it will generate a -.B SIGFPE -signal. -(Also dividing the most negative integer by \-1 may generate -.BR SIGFPE .) -Ignoring this signal might lead to an endless loop. .PP POSIX.1-1990 disallowed setting the action for .B SIGCHLD @@ -1018,6 +1046,32 @@ allowed the receipt of any signal, not just the one we are installing (effectively overriding any .I sa_mask settings). +.SH NOTES +A child created via +.BR fork (2) +inherits a copy of its parent's signal dispositions. +During an +.BR execve (2), +the dispositions of handled signals are reset to the default; +the dispositions of ignored signals are left unchanged. +.PP +According to POSIX, the behavior of a process is undefined after it +ignores a +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +signal that was not generated by +.BR kill (2) +or +.BR raise (3). +Integer division by zero has undefined result. +On some architectures it will generate a +.B SIGFPE +signal. +(Also dividing the most negative integer by \-1 may generate +.BR SIGFPE .) +Ignoring this signal might lead to an endless loop. .PP .BR sigaction () can be called with a NULL second argument to query the current signal @@ -1040,58 +1094,6 @@ See for a list of the async-signal-safe functions that can be safely called inside from inside a signal handler. .\" -.SS C library/kernel differences -The glibc wrapper function for -.BR sigaction () -gives an error -.RB ( EINVAL ) -on attempts to change the disposition of the two real-time signals -used internally by the NPTL threading implementation. -See -.BR nptl (7) -for details. -.PP -On architectures where the signal trampoline resides in the C library, -the glibc wrapper function for -.BR sigaction () -places the address of the trampoline code in the -.I act.sa_restorer -field and sets the -.B SA_RESTORER -flag in the -.I act.sa_flags -field. -See -.BR sigreturn (2). -.PP -The original Linux system call was named -.BR sigaction (). -However, with the addition of real-time signals in Linux 2.2, -the fixed-size, 32-bit -.I sigset_t -type supported by that system call was no longer fit for purpose. -Consequently, a new system call, -.BR rt_sigaction (), -was added to support an enlarged -.I sigset_t -type. -The new system call takes a fourth argument, -.IR "size_t sigsetsize" , -which specifies the size in bytes of the signal sets in -.I act.sa_mask -and -.IR oldact.sa_mask . -This argument is currently required to have the value -.I sizeof(sigset_t) -(or the error -.B EINVAL -results). -The glibc -.BR sigaction () -wrapper function hides these details from us, transparently calling -.BR rt_sigaction () -when the kernel provides it. -.\" .SS Undocumented Before the introduction of .BR SA_SIGINFO , diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 index cdc8a8e39f..095c95742b 100644 --- a/man2/sigaltstack.2 +++ b/man2/sigaltstack.2 @@ -211,11 +211,12 @@ T} Thread safety MT-Safe .ad .sp 1 .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SUSv2, SVr4. +POSIX.1-2008. .PP -The .B SS_AUTODISARM -flag is a Linux extension. +is a Linux extension. +.SH HISTORY +POSIX.1-2001, SUSv2, SVr4. .SH NOTES The most common usage of an alternate signal stack is to handle the .B SIGSEGV diff --git a/man2/signal.2 b/man2/signal.2 index d340c734b0..c05b0ee452 100644 --- a/man2/signal.2 +++ b/man2/signal.2 @@ -93,43 +93,7 @@ is set to indicate the error. .B EINVAL .I signum is invalid. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, C89, C99. -.SH NOTES -The effects of -.BR signal () -in a multithreaded process are unspecified. -.PP -According to POSIX, the behavior of a process is undefined after it -ignores a -.BR SIGFPE , -.BR SIGILL , -or -.B SIGSEGV -signal that was not generated by -.BR kill (2) -or -.BR raise (3). -Integer division by zero has undefined result. -On some architectures it will generate a -.B SIGFPE -signal. -(Also dividing the most negative integer by \-1 may generate -.BR SIGFPE .) -Ignoring this signal might lead to an endless loop. -.PP -See -.BR sigaction (2) -for details on what happens when the disposition -.B SIGCHLD -is set to -.BR SIG_IGN . -.PP -See -.BR signal\-safety (7) -for a list of the async-signal-safe functions that can be -safely called from inside a signal handler. -.PP +.SH VERSIONS The use of .I sighandler_t is a GNU extension, exposed if @@ -173,6 +137,10 @@ POSIX.1 solved the portability mess by specifying which provides explicit control of the semantics when a signal handler is invoked; use that interface instead of .BR signal (). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. .PP In the original UNIX systems, when a handler that was established using .BR signal () @@ -257,6 +225,40 @@ provides System\ V semantics. .\" then .\" .BR signal () .\" provides BSD semantics. +.SH NOTES +The effects of +.BR signal () +in a multithreaded process are unspecified. +.PP +According to POSIX, the behavior of a process is undefined after it +ignores a +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +signal that was not generated by +.BR kill (2) +or +.BR raise (3). +Integer division by zero has undefined result. +On some architectures it will generate a +.B SIGFPE +signal. +(Also dividing the most negative integer by \-1 may generate +.BR SIGFPE .) +Ignoring this signal might lead to an endless loop. +.PP +See +.BR sigaction (2) +for details on what happens when the disposition +.B SIGCHLD +is set to +.BR SIG_IGN . +.PP +See +.BR signal\-safety (7) +for a list of the async-signal-safe functions that can be +safely called from inside a signal handler. .SH SEE ALSO .BR kill (1), .BR alarm (2), diff --git a/man2/signalfd.2 b/man2/signalfd.2 index f0c27991bb..8e86d65285 100644 --- a/man2/signalfd.2 +++ b/man2/signalfd.2 @@ -328,18 +328,43 @@ Could not mount (internal) anonymous inode device. .B ENOMEM There was insufficient memory to create a new signalfd file descriptor. .SH VERSIONS +.SS C library/kernel differences +The underlying Linux system call requires an additional argument, +.IR "size_t sizemask" , +which specifies the size of the +.I mask +argument. +The glibc .BR signalfd () -is available since Linux 2.6.22. -Working support is provided since glibc 2.8. -.\" signalfd() is in glibc 2.7, but reportedly does not build -The +wrapper function does not include this argument, +since it provides the required value for the underlying system call. +.PP +There are two underlying Linux system calls: +.BR signalfd () +and the more recent +.BR signalfd4 (). +The former system call does not implement a +.I flags +argument. +The latter system call implements the +.I flags +values described above. +Starting with glibc 2.9, the +.BR signalfd () +wrapper function will use .BR signalfd4 () -system call (see NOTES) is available since Linux 2.6.27. +where it is available. .SH STANDARDS +Linux. +.SH HISTORY +.TP .BR signalfd () -and +Linux 2.6.22, +glibc 2.8. +.\" signalfd() is in glibc 2.7, but reportedly does not build +.TP .BR signalfd4 () -are Linux-specific. +Linux 2.6.27. .SH NOTES A process can create multiple signalfd file descriptors. This makes it possible to accept different signals @@ -400,33 +425,6 @@ handler that writes to a file descriptor monitored by .BR poll (2), or .BR epoll (7). -.\" -.SS C library/kernel differences -The underlying Linux system call requires an additional argument, -.IR "size_t sizemask" , -which specifies the size of the -.I mask -argument. -The glibc -.BR signalfd () -wrapper function does not include this argument, -since it provides the required value for the underlying system call. -.PP -There are two underlying Linux system calls: -.BR signalfd () -and the more recent -.BR signalfd4 (). -The former system call does not implement a -.I flags -argument. -The latter system call implements the -.I flags -values described above. -Starting with glibc 2.9, the -.BR signalfd () -wrapper function will use -.BR signalfd4 () -where it is available. .SH BUGS Before Linux 2.6.25, the .I ssi_ptr diff --git a/man2/sigpending.2 b/man2/sigpending.2 index 517058b9eb..b0a9c247e3 100644 --- a/man2/sigpending.2 +++ b/man2/sigpending.2 @@ -46,27 +46,9 @@ is set to indicate the error. .I set points to memory which is not a valid part of the process address space. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. -.SH NOTES -See -.BR sigsetops (3) -for details on manipulating signal sets. -.PP -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 -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 -A child created via -.BR fork (2) -initially has an empty pending signal set; -the pending signal set is preserved across an -.BR execve (2). -.\" +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. .SS C library/kernel differences The original Linux system call was named .BR sigpending (). @@ -93,7 +75,25 @@ The glibc wrapper function hides these details from us, transparently calling .BR rt_sigpending () when the kernel provides it. -.\" +.SH NOTES +See +.BR sigsetops (3) +for details on manipulating signal sets. +.PP +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 +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 +A child created via +.BR fork (2) +initially has an empty pending signal set; +the pending signal set is preserved across an +.BR execve (2). .SH BUGS Up to and including glibc 2.2.1, there is a bug in the wrapper function for diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2 index ae65e3400c..692ce601ff 100644 --- a/man2/sigprocmask.2 +++ b/man2/sigprocmask.2 @@ -116,45 +116,7 @@ Either the value specified in .I how was invalid or the kernel does not support the size passed in .I sigsetsize. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008. -.SH NOTES -It is not possible to block -.BR SIGKILL " or " SIGSTOP . -Attempts to do so are silently ignored. -.PP -Each of the threads in a process has its own signal mask. -.PP -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 -If -.BR SIGBUS , -.BR SIGFPE , -.BR SIGILL , -or -.B SIGSEGV -are generated -while they are blocked, the result is undefined, -unless the signal was generated by -.BR kill (2), -.BR sigqueue (3), -or -.BR raise (3). -.PP -See -.BR sigsetops (3) -for details on manipulating signal sets. -.PP -Note that it is permissible (although not very useful) to specify both -.I set -and -.I oldset -as NULL. -.\" +.SH VERSIONS .SS C library/kernel differences The kernel's definition of .I sigset_t @@ -209,6 +171,46 @@ wrapper function hides these details from us, transparently calling .BR rt_sigprocmask () when the kernel provides it. .\" +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +It is not possible to block +.BR SIGKILL " or " SIGSTOP . +Attempts to do so are silently ignored. +.PP +Each of the threads in a process has its own signal mask. +.PP +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 +If +.BR SIGBUS , +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +are generated +while they are blocked, the result is undefined, +unless the signal was generated by +.BR kill (2), +.BR sigqueue (3), +or +.BR raise (3). +.PP +See +.BR sigsetops (3) +for details on manipulating signal sets. +.PP +Note that it is permissible (although not very useful) to specify both +.I set +and +.I oldset +as NULL. .SH SEE ALSO .BR kill (2), .BR pause (2), diff --git a/man2/sigreturn.2 b/man2/sigreturn.2 index a4f0e13150..861e8d25da 100644 --- a/man2/sigreturn.2 +++ b/man2/sigreturn.2 @@ -52,12 +52,14 @@ at the point where it was interrupted by the signal. .SH RETURN VALUE .BR sigreturn () never returns. -.SH STANDARDS +.SH VERSIONS Many UNIX-type systems have a .BR sigreturn () system call or near equivalent. However, this call is not specified in POSIX, and details of its behavior vary across systems. +.SH STANDARDS +None. .SH NOTES .BR sigreturn () exists only to allow the implementation of signal handlers. diff --git a/man2/sigsuspend.2 b/man2/sigsuspend.2 index 8493d29691..c5c22c2c13 100644 --- a/man2/sigsuspend.2 +++ b/man2/sigsuspend.2 @@ -68,29 +68,9 @@ points to memory which is not a valid part of the process address space. The call was interrupted by a signal; .BR signal (7). .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. -.SH NOTES -Normally, -.BR sigsuspend () -is used in conjunction with -.BR sigprocmask (2) -in order to prevent delivery of a signal during the execution of a -critical code section. -The caller first blocks the signals with -.BR sigprocmask (2). -When the critical code has completed, the caller then waits for the -signals by calling -.BR sigsuspend () -with the signal mask that was returned by -.BR sigprocmask (2) -(in the -.I oldset -argument). -.PP -See -.BR sigsetops (3) -for details on manipulating signal sets. -.\" +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. .SS C library/kernel differences The original Linux system call was named .BR sigsuspend (). @@ -118,6 +98,27 @@ wrapper function hides these details from us, transparently calling .BR rt_sigsuspend () when the kernel provides it. .\" +.SH NOTES +Normally, +.BR sigsuspend () +is used in conjunction with +.BR sigprocmask (2) +in order to prevent delivery of a signal during the execution of a +critical code section. +The caller first blocks the signals with +.BR sigprocmask (2). +When the critical code has completed, the caller then waits for the +signals by calling +.BR sigsuspend () +with the signal mask that was returned by +.BR sigprocmask (2) +(in the +.I oldset +argument). +.PP +See +.BR sigsetops (3) +for details on manipulating signal sets. .SH SEE ALSO .BR kill (2), .BR pause (2), diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2 index 42209c1806..fb797e8036 100644 --- a/man2/sigwaitinfo.2 +++ b/man2/sigwaitinfo.2 @@ -110,8 +110,53 @@ The wait was interrupted by a signal handler; see .B EINVAL .I timeout was invalid. +.SH VERSIONS +.SS C library/kernel differences +On Linux, +.BR sigwaitinfo () +is a library function implemented on top of +.BR sigtimedwait (). +.PP +The glibc wrapper functions for +.BR sigwaitinfo () +and +.BR sigtimedwait () +silently ignore attempts to wait for the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.PP +The original Linux system call was named +.BR sigtimedwait (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.I sigset_t +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigtimedwait (), +was added to support an enlarged +.I sigset_t +type. +The new system call takes a fourth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal set in +.IR set . +This argument is currently required to have the value +.I sizeof(sigset_t) +(or the error +.B EINVAL +results). +The glibc +.BR sigtimedwait () +wrapper function hides these details from us, transparently calling +.BR rt_sigtimedwait () +when the kernel provides it. +.\" .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. .SH NOTES In normal usage, the calling program blocks the signals in .I set @@ -171,49 +216,6 @@ unspecified, permitting the possibility that this has the same meaning as a call to .BR sigwaitinfo (), and indeed this is what is done on Linux. -.\" -.SS C library/kernel differences -On Linux, -.BR sigwaitinfo () -is a library function implemented on top of -.BR sigtimedwait (). -.PP -The glibc wrapper functions for -.BR sigwaitinfo () -and -.BR sigtimedwait () -silently ignore attempts to wait for the two real-time signals that -are used internally by the NPTL threading implementation. -See -.BR nptl (7) -for details. -.PP -The original Linux system call was named -.BR sigtimedwait (). -However, with the addition of real-time signals in Linux 2.2, -the fixed-size, 32-bit -.I sigset_t -type supported by that system call was no longer fit for purpose. -Consequently, a new system call, -.BR rt_sigtimedwait (), -was added to support an enlarged -.I sigset_t -type. -The new system call takes a fourth argument, -.IR "size_t sigsetsize" , -which specifies the size in bytes of the signal set in -.IR set . -This argument is currently required to have the value -.I sizeof(sigset_t) -(or the error -.B EINVAL -results). -The glibc -.BR sigtimedwait () -wrapper function hides these details from us, transparently calling -.BR rt_sigtimedwait () -when the kernel provides it. -.\" .SH SEE ALSO .BR kill (2), .BR sigaction (2), diff --git a/man2/socket.2 b/man2/socket.2 index 0caf77c506..2c681020b6 100644 --- a/man2/socket.2 +++ b/man2/socket.2 @@ -428,20 +428,21 @@ supported within this domain. .PP Other errors may be generated by the underlying protocol modules. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.4BSD. +POSIX.1-2008. .PP -The .B SOCK_NONBLOCK and .B SOCK_CLOEXEC -flags are Linux-specific. +are Linux-specific. +.SH HISTORY +POSIX.1-2001, 4.4BSD. .PP .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). -.SH NOTES +.PP The manifest constants used under 4.x BSD for protocol families are .BR PF_UNIX , diff --git a/man2/socketcall.2 b/man2/socketcall.2 index a5803eea68..b4c0960851 100644 --- a/man2/socketcall.2 +++ b/man2/socketcall.2 @@ -142,10 +142,7 @@ T}:T{ .BR sendmmsg (2) T} .TE -.SH STANDARDS -This call is specific to Linux, and should not be used in programs -intended to be portable. -.SH NOTES +.SH VERSIONS On some architectures\[em]for example, x86-64 and ARM\[em]there is no .BR socketcall () system call; instead @@ -153,6 +150,8 @@ system call; instead .BR accept (2), .BR bind (2), and so on really are implemented as separate system calls. +.SH STANDARDS +Linux. .PP On x86-32, .BR socketcall () diff --git a/man2/socketpair.2 b/man2/socketpair.2 index bc80614a1f..9831c9715a 100644 --- a/man2/socketpair.2 +++ b/man2/socketpair.2 @@ -77,14 +77,7 @@ The specified protocol does not support creation of socket pairs. .TP .B EPROTONOSUPPORT The specified protocol is not supported on this machine. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, 4.4BSD. -.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). -.SH NOTES +.SH VERSIONS On Linux, the only supported domains for this call are .B AF_UNIX (or synonymously, @@ -93,6 +86,16 @@ and .B AF_TIPC .\" commit: 70b03759e9ecfae400605fa34f3d7154cccbbba3 (since Linux 4.12). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.4BSD. +.PP +.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 Since Linux 2.6.27, .BR socketpair () diff --git a/man2/splice.2 b/man2/splice.2 index 38d8f703b1..dd78e8cd4c 100644 --- a/man2/splice.2 +++ b/man2/splice.2 @@ -176,13 +176,21 @@ Either or .I off_out was not NULL, but the corresponding file descriptor refers to a pipe. -.SH VERSIONS -The -.BR splice () -system call first appeared in Linux 2.6.17; -library support was added in glibc 2.5. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.17, +glibc 2.5. +.PP +In Linux 2.6.30 and earlier, +exactly one of +.I fd_in +and +.I fd_out +was required to be a pipe. +Since Linux 2.6.31, +.\" commit 7c77f0b3f9208c339a4b40737bb2cb0f0319bb8d +both arguments may refer to pipes. .SH NOTES The three system calls .BR splice (), @@ -234,16 +242,6 @@ 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 -In Linux 2.6.30 and earlier, -exactly one of -.I fd_in -and -.I fd_out -was required to be a pipe. -Since Linux 2.6.31, -.\" commit 7c77f0b3f9208c339a4b40737bb2cb0f0319bb8d -both arguments may refer to pipes. .SH EXAMPLES See .BR tee (2). diff --git a/man2/spu_create.2 b/man2/spu_create.2 index d7215fd781..2e4abeac9e 100644 --- a/man2/spu_create.2 +++ b/man2/spu_create.2 @@ -244,22 +244,10 @@ must point to a location beneath the mount point of .BR spufs . By convention, it gets mounted in .IR /spu . -.SH VERSIONS -The -.BR spu_create () -system call was added in Linux 2.6.16. .SH STANDARDS -This call is Linux-specific and implemented only on the PowerPC -architecture. -Programs using this system call are not portable. -.SH NOTES -.BR spu_create () -is meant to be used from libraries that implement a more abstract -interface to SPUs, not to be used from regular applications. -See -.UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ -.UE -for the recommended libraries. +Linux on PowerPC. +.SH HISTORY +Linux 2.6.16. .PP Prior to the addition of the .B SPU_CREATE_AFFINITY_SPU @@ -268,6 +256,14 @@ flag in Linux 2.6.23, the system call took only three arguments (i.e., there was no .I neighbor_fd argument). +.SH NOTES +.BR spu_create () +is meant to be used from libraries that implement a more abstract +interface to SPUs, not to be used from regular applications. +See +.UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ +.UE +for the recommended libraries. .SH EXAMPLES See .BR spu_run (2) diff --git a/man2/spu_run.2 b/man2/spu_run.2 index 720a49997c..c3df3ad63a 100644 --- a/man2/spu_run.2 +++ b/man2/spu_run.2 @@ -181,14 +181,10 @@ resulting from a Memory Flow Controller (MFC) direct memory access. The functionality is not provided by the current system, because either the hardware does not provide SPUs or the spufs module is not loaded. -.SH VERSIONS -The -.BR spu_run () -system call was added in Linux 2.6.16. .SH STANDARDS -This call is Linux-specific and implemented only by the PowerPC -architecture. -Programs using this system call are not portable. +Linux on PowerPC. +.SH HISTORY +Linux 2.6.16. .SH NOTES .BR spu_run () is meant to be used from libraries that implement a more abstract diff --git a/man2/stat.2 b/man2/stat.2 index 8479befccd..546e80ab43 100644 --- a/man2/stat.2 +++ b/man2/stat.2 @@ -306,15 +306,16 @@ calls on a file whose size exceeds .I (1<<31)\-1 bytes. -.SH VERSIONS -.BR fstatat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. .SH STANDARDS -.BR stat (), -.BR fstat (), -.BR lstat (): -SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008. +POSIX.1-2008. +.SH HISTORY +.TP +.BR stat () +.TQ +.BR fstat () +.TQ +.BR lstat () +SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional .\" .BR fstat () .\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4 @@ -323,9 +324,11 @@ SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008. .\" and .\" .BR lstat () .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW. -.PP -.BR fstatat (): +.TP +.BR fstatat () POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. .PP According to POSIX.1-2001, .BR lstat () @@ -349,7 +352,6 @@ fields may be less portable. (They were introduced in BSD. The interpretation differs between systems, and possibly on a single system when NFS mounts are involved.) -.SH NOTES .SS C library/kernel differences Over time, increases in the size of the .I stat diff --git a/man2/statfs.2 b/man2/statfs.2 index 8c4d6236f2..0496ab6c91 100644 --- a/man2/statfs.2 +++ b/man2/statfs.2 @@ -267,61 +267,7 @@ is not a directory. .TP .B EOVERFLOW Some values were too large to be represented in the returned struct. -.SH STANDARDS -Linux-specific. -The Linux -.BR statfs () -was inspired by the 4.4BSD one -(but they do not use the same structure). -.SH NOTES -The -.I __fsword_t -type used for various fields in the -.I statfs -structure definition is a glibc internal type, -not intended for public use. -This leaves the programmer in a bit of a conundrum when trying to copy -or compare these fields to local variables in a program. -Using -.I "unsigned\ int" -for such variables suffices on most systems. -.PP -The original Linux -.BR statfs () -and -.BR fstatfs () -system calls were not designed with extremely large file sizes in mind. -Subsequently, Linux 2.6 -added new -.BR statfs64 () -and -.BR fstatfs64 () -system calls that employ a new structure, -.IR statfs64 . -The new structure contains the same fields as the original -.I statfs -structure, but the sizes of various fields are increased, -to accommodate large file sizes. -The glibc -.BR statfs () -and -.BR fstatfs () -wrapper functions transparently deal with the kernel differences. -.PP -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 -including the former is the best choice. -.PP -LSB has deprecated the library calls -.BR statfs () -and -.BR fstatfs () -and tells us to use -.BR statvfs (3) -and -.BR fstatvfs (3) -instead. +.SH VERSIONS .SS The f_fsid field Solaris, Irix, and POSIX have a system call .BR statvfs (2) @@ -366,6 +312,62 @@ Under some operating systems, the can be used as the second argument to the .BR sysfs (2) system call. +.SH STANDARDS +Linux. +.SH HISTORY +The Linux +.BR statfs () +was inspired by the 4.4BSD one +(but they do not use the same structure). +.PP +The original Linux +.BR statfs () +and +.BR fstatfs () +system calls were not designed with extremely large file sizes in mind. +Subsequently, Linux 2.6 +added new +.BR statfs64 () +and +.BR fstatfs64 () +system calls that employ a new structure, +.IR statfs64 . +The new structure contains the same fields as the original +.I statfs +structure, but the sizes of various fields are increased, +to accommodate large file sizes. +The glibc +.BR statfs () +and +.BR fstatfs () +wrapper functions transparently deal with the kernel differences. +.PP +LSB has deprecated the library calls +.BR statfs () +and +.BR fstatfs () +and tells us to use +.BR statvfs (3) +and +.BR fstatvfs (3) +instead. +.SH NOTES +The +.I __fsword_t +type used for various fields in the +.I statfs +structure definition is a glibc internal type, +not intended for public use. +This leaves the programmer in a bit of a conundrum when trying to copy +or compare these fields to local variables in a program. +Using +.I "unsigned\ int" +for such variables suffices on most systems. +.PP +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 +including the former is the best choice. .SH BUGS From Linux 2.6.38 up to and including Linux 3.1, .\" broken in commit ff0c7d15f9787b7e8c601533c015295cc68329f8 diff --git a/man2/statx.2 b/man2/statx.2 index c79f3c219d..ef35efd981 100644 --- a/man2/statx.2 +++ b/man2/statx.2 @@ -589,12 +589,11 @@ is not a directory or is relative and .I dirfd is a file descriptor referring to a file other than a directory. -.SH VERSIONS -.BR statx () -was added in Linux 4.11; library support was added in glibc 2.28. .SH STANDARDS -.BR statx () -is Linux-specific. +Linux. +.SH HISTORY +Linux 4.11, +glibc 2.28. .SH SEE ALSO .BR ls (1), .BR stat (1), diff --git a/man2/stime.2 b/man2/stime.2 index fd77385d1d..ec0a9d02b1 100644 --- a/man2/stime.2 +++ b/man2/stime.2 @@ -59,8 +59,10 @@ Under Linux, the .B CAP_SYS_TIME privilege is required. .SH STANDARDS +None. +.SH HISTORY SVr4. -.SH NOTES +.PP 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 374ddce9d8..2719e9ceba 100644 --- a/man2/subpage_prot.2 +++ b/man2/subpage_prot.2 @@ -76,14 +76,13 @@ address space of the process or to a region that consists of huge pages. .TP .B ENOMEM Out of memory. -.SH VERSIONS -This system call is provided on the PowerPC architecture -since Linux 2.6.25. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.25 (PowerPC). +.PP The system call is provided only if the kernel is configured with .BR CONFIG_PPC_64K_PAGES . -No library support is provided. -.SH STANDARDS -This system call is Linux-specific. .SH NOTES Normal page protections (at the 64-kB page level) also apply; the subpage protection mechanism is an additional constraint, diff --git a/man2/swapon.2 b/man2/swapon.2 index db9dc3dff7..8f798ef7bb 100644 --- a/man2/swapon.2 +++ b/man2/swapon.2 @@ -148,9 +148,9 @@ capability. Alternatively, the maximum number of swap files are already in use; see NOTES below. .SH STANDARDS -These functions are Linux-specific and should not be used in programs -intended to be portable. -The second +Linux. +.SH HISTORY +The .I swapflags argument was introduced in Linux 1.3.2. .SH NOTES diff --git a/man2/symlink.2 b/man2/symlink.2 index 13b2ed1ccd..4475bcb90a 100644 --- a/man2/symlink.2 +++ b/man2/symlink.2 @@ -214,29 +214,21 @@ does not support the creation of symbolic links. .B EROFS .I linkpath is on a read-only filesystem. -.SH VERSIONS -.BR symlinkat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. .SH STANDARDS -.BR symlink (): -SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +.TP +.BR symlink () +SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional error codes EDQUOT and ENOSYS. .\" See .\" .BR open (2) .\" re multiple files with the same name, and NFS. -.PP -.BR symlinkat (): +.TP +.BR symlinkat () POSIX.1-2008. -.SH NOTES -No checking of -.I target -is done. -.PP -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 -.BR link (2). +Linux 2.6.16, +glibc 2.4. .SS glibc notes On older kernels where .BR symlinkat () @@ -250,6 +242,15 @@ glibc constructs a pathname based on the symbolic link in that corresponds to the .I newdirfd argument. +.SH NOTES +No checking of +.I target +is done. +.PP +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 +.BR link (2). .SH SEE ALSO .BR ln (1), .BR namei (1), diff --git a/man2/sync.2 b/man2/sync.2 index 24576ec37f..c1257fdc25 100644 --- a/man2/sync.2 +++ b/man2/sync.2 @@ -88,25 +88,6 @@ allocate space at the time of a system call, and some previous write failed due to insufficient storage space. .SH VERSIONS -.BR syncfs () -first appeared in Linux 2.6.39; -library support was added in glibc 2.14. -.SH STANDARDS -.BR sync (): -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. -.PP -.BR syncfs () -is Linux-specific. -.SH NOTES -Since glibc 2.2.2, the Linux prototype for -.BR sync () -is as listed above, -following the various standards. -In glibc 2.2.1 and earlier, -it was "int sync(void)", and -.BR sync () -always returned 0. -.PP According to the standard specification (e.g., POSIX.1-2001), .BR sync () schedules the writes, but may return before the actual @@ -120,6 +101,30 @@ provide the same guarantees as .BR fsync () called on every file in the system or filesystem respectively. +.SH STANDARDS +.TP +.BR sync () +POSIX.1-2008. +.TP +.BR syncfs () +Linux. +.SH HISTORY +.TP +.BR sync () +POSIX.1-2001, SVr4, 4.3BSD. +.TP +.BR syncfs () +Linux 2.6.39, +glibc 2.14. +.PP +Since glibc 2.2.2, the Linux prototype for +.BR sync () +is as listed above, +following the various standards. +In glibc 2.2.1 and earlier, +it was "int sync(void)", and +.BR sync () +always returned 0. .PP In mainline kernel versions prior to Linux 5.8, .BR syncfs () diff --git a/man2/sync_file_range.2 b/man2/sync_file_range.2 index 7557cad448..d633b08ffe 100644 --- a/man2/sync_file_range.2 +++ b/man2/sync_file_range.2 @@ -155,12 +155,6 @@ Out of disk space. refers to something other than a regular file, a block device, or a directory. .SH VERSIONS -.BR sync_file_range () -appeared in Linux 2.6.17. -.SH STANDARDS -This system call is Linux-specific, and should be avoided -in portable programs. -.SH NOTES .SS sync_file_range2() Some architectures (e.g., PowerPC, ARM) need 64-bit arguments to be aligned in a suitable pair of registers. @@ -188,7 +182,11 @@ system call that orders the arguments suitably: .PP The behavior of this system call is otherwise exactly the same as .BR sync_file_range (). -.PP +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.17. +.SS sync_file_range2() A system call with this signature first appeared on the ARM architecture in Linux 2.6.20, with the name .BR arm_sync_file_range (). @@ -199,6 +197,7 @@ glibc transparently wraps .BR sync_file_range2 () under the name .BR sync_file_range (). +.SH NOTES .SH SEE ALSO .BR fdatasync (2), .BR fsync (2), diff --git a/man2/sysctl.2 b/man2/sysctl.2 index 679b20a74d..83af5efd4c 100644 --- a/man2/sysctl.2 +++ b/man2/sysctl.2 @@ -73,12 +73,12 @@ non-NULL, but allowed zero room in .B ENOTDIR .I name was not found. -.SH VERSIONS -This system call first appeared in Linux 1.3.57. -It was removed in Linux 5.5; glibc support was removed in glibc 2.32. .SH STANDARDS -This call is Linux-specific, and should not be used in programs -intended to be portable. +Linux. +.SH HISTORY +Linux 1.3.57. +Removed in Linux 5.5, glibc 2.32. +.PP It originated in 4.4BSD. Only Linux has the diff --git a/man2/sysfs.2 b/man2/sysfs.2 index d2303a7d86..2e51426fe4 100644 --- a/man2/sysfs.2 +++ b/man2/sysfs.2 @@ -79,8 +79,10 @@ is out-of-bounds; .I option is invalid. .SH STANDARDS +None. +.SH HISTORY SVr4. -.SH NOTES +.PP 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 2e40351221..69fe280b62 100644 --- a/man2/sysinfo.2 +++ b/man2/sysinfo.2 @@ -93,12 +93,10 @@ is set to indicate the error. .B EFAULT .I info is not a valid address. -.SH VERSIONS -.BR sysinfo () -first appeared in Linux 0.98.pl6. .SH STANDARDS -This function is Linux-specific, and should not be used in programs -intended to be portable. +Linux. +.SH HISTORY +Linux 0.98.pl6. .SH NOTES All of the information provided by this system call is also available via .I /proc/meminfo diff --git a/man2/syslog.2 b/man2/syslog.2 index 09c086f181..99403ceb0c 100644 --- a/man2/syslog.2 +++ b/man2/syslog.2 @@ -363,9 +363,8 @@ capability). System call was interrupted by a signal; nothing was read. (This can be seen only during a trace.) .SH STANDARDS -This system call is Linux-specific and should not be used in programs -intended to be portable. -.SH NOTES +Linux. +.SH HISTORY From the very start, people noted that it is unfortunate that a system call and a library routine of the same name are entirely different animals. diff --git a/man2/tee.2 b/man2/tee.2 index 6c412a475b..35975badf6 100644 --- a/man2/tee.2 +++ b/man2/tee.2 @@ -100,13 +100,11 @@ refer to the same pipe. .TP .B ENOMEM Out of memory. -.SH VERSIONS -The -.BR tee () -system call first appeared in Linux 2.6.17; -library support was added in glibc 2.5. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.17, +glibc 2.5. .SH NOTES Conceptually, .BR tee () diff --git a/man2/time.2 b/man2/time.2 index 2be79cf782..65db67a341 100644 --- a/man2/time.2 +++ b/man2/time.2 @@ -47,12 +47,7 @@ wrapper function invokes an implementation provided by the an invalid address may instead trigger a .B SIGSEGV signal. -.SH STANDARDS -SVr4, 4.3BSD, C89, C99, POSIX.1-2001. -.\" Under 4.3BSD, this call is obsoleted by -.\" .BR gettimeofday (2). -POSIX does not specify any error conditions. -.SH NOTES +.SH VERSIONS POSIX.1 defines .I seconds since the Epoch using a formula that approximates the number of seconds between a @@ -88,6 +83,17 @@ range. Applications intended to run after 2038 should use ABIs with .I time_t wider than 32 bits. +.SS C library/kernel differences +On some architectures, an implementation of +.BR time () +is provided in the +.BR vdso (7). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +SVr4, 4.3BSD, C89, POSIX.1-2001. +.\" Under 4.3BSD, this call is obsoleted by +.\" .BR gettimeofday (2). .SH BUGS Error returns from this system call are indistinguishable from successful reports that the time is a few seconds @@ -102,12 +108,6 @@ argument is obsolescent and should always be NULL in new code. When .I tloc is NULL, the call cannot fail. -.\" -.SS C library/kernel differences -On some architectures, an implementation of -.BR time () -is provided in the -.BR vdso (7). .SH SEE ALSO .BR date (1), .BR gettimeofday (2), diff --git a/man2/timer_create.2 b/man2/timer_create.2 index 6d49da17f8..ba5ad78fb3 100644 --- a/man2/timer_create.2 +++ b/man2/timer_create.2 @@ -222,9 +222,51 @@ but the caller did not have the .B CAP_WAKE_ALARM capability. .SH VERSIONS -This system call is available since Linux 2.6. +.SS C library/kernel differences +Part of the implementation of the POSIX timers API is provided by glibc. +.\" See nptl/sysdeps/unix/sysv/linux/timer_create.c +In particular: +.IP \[bu] 3 +Much of the functionality for +.B SIGEV_THREAD +is implemented within glibc, rather than the kernel. +(This is necessarily so, +since the thread involved in handling the notification is one +that must be managed by the C library POSIX threads implementation.) +Although the notification delivered to the process is via a thread, +internally the NPTL implementation uses a +.I sigev_notify +value of +.B SIGEV_THREAD_ID +along with a real-time signal that is reserved by the implementation (see +.BR nptl (7)). +.IP \[bu] +The implementation of the default case where +.I evp +is NULL is handled inside glibc, +which invokes the underlying system call with a suitably populated +.I sigevent +structure. +.IP \[bu] +The timer IDs presented at user level are maintained by glibc, +which maps these IDs to the timer IDs employed by the kernel. +.\" See the glibc source file kernel-posix-timers.h for the structure +.\" that glibc uses to map user-space timer IDs to kernel timer IDs +.\" The kernel-level timer ID is exposed via siginfo.si_tid. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +Linux 2.6. +POSIX.1-2001. +.PP +Prior to Linux 2.6, +glibc provided an incomplete user-space implementation +.RB ( CLOCK_REALTIME +timers only) using POSIX threads, +and before glibc 2.17, +.\" glibc commit 93a78ac437ba44f493333d7e2a4b0249839ce460 +the implementation falls back to this technique on systems +running kernels older than Linux 2.6. .SH NOTES A program may create multiple interval timers using .BR timer_create (). @@ -277,48 +319,6 @@ support for POSIX timers is a configurable option that is enabled by default. Kernel support can be disabled via the .B CONFIG_POSIX_TIMERS option. -.\" -.SS C library/kernel differences -Part of the implementation of the POSIX timers API is provided by glibc. -.\" See nptl/sysdeps/unix/sysv/linux/timer_create.c -In particular: -.IP \[bu] 3 -Much of the functionality for -.B SIGEV_THREAD -is implemented within glibc, rather than the kernel. -(This is necessarily so, -since the thread involved in handling the notification is one -that must be managed by the C library POSIX threads implementation.) -Although the notification delivered to the process is via a thread, -internally the NPTL implementation uses a -.I sigev_notify -value of -.B SIGEV_THREAD_ID -along with a real-time signal that is reserved by the implementation (see -.BR nptl (7)). -.IP \[bu] -The implementation of the default case where -.I evp -is NULL is handled inside glibc, -which invokes the underlying system call with a suitably populated -.I sigevent -structure. -.IP \[bu] -The timer IDs presented at user level are maintained by glibc, -which maps these IDs to the timer IDs employed by the kernel. -.\" See the glibc source file kernel-posix-timers.h for the structure -.\" that glibc uses to map user-space timer IDs to kernel timer IDs -.\" The kernel-level timer ID is exposed via siginfo.si_tid. -.PP -The POSIX timers system calls first appeared in Linux 2.6. -Prior to this, -glibc provided an incomplete user-space implementation -.RB ( CLOCK_REALTIME -timers only) using POSIX threads, -and before glibc 2.17, -.\" glibc commit 93a78ac437ba44f493333d7e2a4b0249839ce460 -the implementation falls back to this technique on systems -running kernels older than Linux 2.6. .SH EXAMPLES The program below takes two arguments: a sleep period in seconds, and a timer frequency in nanoseconds. diff --git a/man2/timer_delete.2 b/man2/timer_delete.2 index c489d9ec0d..7db4ce1fdf 100644 --- a/man2/timer_delete.2 +++ b/man2/timer_delete.2 @@ -45,10 +45,11 @@ is set to indicate the error. .B EINVAL .I timerid is not a valid timer ID. -.SH VERSIONS -This system call is available since Linux 2.6. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +Linux 2.6. +POSIX.1-2001. .SH SEE ALSO .BR clock_gettime (2), .BR timer_create (2), diff --git a/man2/timer_getoverrun.2 b/man2/timer_getoverrun.2 index 3591e5de5d..90d9e00400 100644 --- a/man2/timer_getoverrun.2 +++ b/man2/timer_getoverrun.2 @@ -76,10 +76,6 @@ is set to indicate the error. .I timerid is not a valid timer ID. .SH VERSIONS -This system call is available since Linux 2.6. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008. -.SH NOTES When timer notifications are delivered via signals .RB ( SIGEV_SIGNAL ), on Linux it is also possible to obtain the overrun count via the @@ -96,6 +92,11 @@ POSIX.1 discusses timer overruns only in the context of timer notifications using signals. .\" FIXME . Austin bug filed, 11 Feb 09 .\" https://www.austingroupbugs.net/view.php?id=95 +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +Linux 2.6. +POSIX.1-2001. .SH BUGS POSIX.1 specifies that if the timer overrun count is equal to or greater than an implementation-defined maximum, diff --git a/man2/timer_settime.2 b/man2/timer_settime.2 index c026365543..589da08c51 100644 --- a/man2/timer_settime.2 +++ b/man2/timer_settime.2 @@ -172,10 +172,11 @@ may fail with the following errors: is negative; or .I new_value.it_value.tv_nsec is negative or greater than 999,999,999. -.SH VERSIONS -These system calls are available since Linux 2.6. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +Linux 2.6. +POSIX.1-2001. .SH EXAMPLES See .BR timer_create (2). diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2 index 315f3fe353..516e050b35 100644 --- a/man2/timerfd_create.2 +++ b/man2/timerfd_create.2 @@ -468,11 +468,11 @@ falls outside the range zero to 999,999,999). .\" In older kernel versions, no check was made for invalid flags. .I flags is invalid. -.SH VERSIONS -These system calls are available since Linux 2.6.25. -Library support is provided since glibc 2.8. .SH STANDARDS -These system calls are Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.25, +glibc 2.8. .SH NOTES Suppose the following scenario for .B CLOCK_REALTIME diff --git a/man2/times.2 b/man2/times.2 index 6c4d4ce8e9..0c14bd6e98 100644 --- a/man2/times.2 +++ b/man2/times.2 @@ -101,19 +101,25 @@ is set to indicate the error. .B EFAULT .I tms points outside the process's address space. +.SH VERSIONS +On Linux, +the +.I buf +argument can be specified as NULL, +with the result that +.BR times () +just returns a function result. +However, +POSIX does not specify this behavior, +and most +other UNIX implementations require a non-NULL value for +.IR buf . .SH STANDARDS +POSIX.1-2008. +.SH HISTORY POSIX.1-2001, -POSIX.1-2008, SVr4, 4.3BSD. -.SH NOTES -The number of clock ticks per second can be obtained using: -.PP -.in +4n -.EX -sysconf(_SC_CLK_TCK); -.EE -.in .PP In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in .IR <time.h> ) @@ -141,28 +147,6 @@ This nonconformance is rectified in Linux 2.6.9 and later. .\" or waitpid() returns the process ID of this terminated child. .PP On Linux, -the -.I buf -argument can be specified as NULL, -with the result that -.BR times () -just returns a function result. -However, -POSIX does not specify this behavior, -and most -other UNIX implementations require a non-NULL value for -.IR buf . -.PP -Note that -.BR clock (3) -also returns a value of type -.IR clock_t , -but this value is measured in units of -.BR CLOCKS_PER_SEC , -not the clock ticks used by -.BR times (). -.PP -On Linux, the \[lq]arbitrary point in the past\[rq] from which the return value of .BR times () @@ -183,7 +167,7 @@ instead. .\" .PP .\" On older systems the number of clock ticks per second is given .\" by the variable HZ. -.SS Historical +.PP SVr1-3 returns .I long and the struct members are of type @@ -196,6 +180,23 @@ for the struct members, because it had no type .I time_t yet. +.SH NOTES +The number of clock ticks per second can be obtained using: +.PP +.in +4n +.EX +sysconf(_SC_CLK_TCK); +.EE +.in +.PP +Note that +.BR clock (3) +also returns a value of type +.IR clock_t , +but this value is measured in units of +.BR CLOCKS_PER_SEC , +not the clock ticks used by +.BR times (). .SH BUGS A limitation of the Linux system call conventions on some architectures (notably i386) means that on Linux 2.6 there is a small time window diff --git a/man2/tkill.2 b/man2/tkill.2 index 05e19e295a..d5c55ef528 100644 --- a/man2/tkill.2 +++ b/man2/tkill.2 @@ -107,30 +107,22 @@ For the required permissions, see .TP .B ESRCH No process with the specified thread ID (and thread group ID) exists. -.SH VERSIONS -.BR tkill () -is supported since Linux 2.4.19 / 2.5.4. -.BR tgkill () -was added in Linux 2.5.75. -.PP -Library support for -.BR tgkill () -was added in glibc 2.30. .SH STANDARDS +Linux. +.SH HISTORY +.TP .BR tkill () -and +Linux 2.4.19 / 2.5.4. +.TP .BR tgkill () -are Linux-specific and should not be used -in programs that are intended to be portable. +Linux 2.5.75, +glibc 2.30. .SH NOTES See the description of .B CLONE_THREAD in .BR clone (2) for an explanation of thread groups. -.PP -Before glibc 2.30, there was also no wrapper function for -.BR tgkill (). .SH SEE ALSO .BR clone (2), .BR gettid (2), diff --git a/man2/truncate.2 b/man2/truncate.2 index 8a00ec3ffb..703f598b3d 100644 --- a/man2/truncate.2 +++ b/man2/truncate.2 @@ -176,25 +176,7 @@ POSIX permits, and portable applications should handle, either error for this case. (Linux produces .BR EINVAL .) -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, -4.4BSD, SVr4 (these calls first appeared in 4.2BSD). -.\" POSIX.1-1996 has -.\" .BR ftruncate (). -.\" POSIX.1-2001 also has -.\" .BR truncate (), -.\" as an XSI extension. -.\" .LP -.\" SVr4 documents additional -.\" .BR truncate () -.\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for -.\" .BR ftruncate () -.\" an additional EAGAIN error condition. -.SH NOTES -.BR ftruncate () -can also be used to set the size of a POSIX shared memory object; see -.BR shm_open (3). -.PP +.SH VERSIONS The details in DESCRIPTION are for XSI-compliant systems. For non-XSI-compliant systems, the POSIX standard allows two behaviors for @@ -216,6 +198,27 @@ 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 +On some 32-bit architectures, +the calling signature for these system calls differ, +for the reasons described in +.BR syscall (2). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +4.4BSD, SVr4 (first appeared in 4.2BSD). +.\" POSIX.1-1996 has +.\" .BR ftruncate (). +.\" POSIX.1-2001 also has +.\" .BR truncate (), +.\" as an XSI extension. +.\" .LP +.\" SVr4 documents additional +.\" .BR truncate () +.\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for +.\" .BR ftruncate () +.\" an additional EAGAIN error condition. +.PP The original Linux .BR truncate () and @@ -229,11 +232,10 @@ system calls that handle large files. However, these details can be ignored by applications using glibc, whose wrapper functions transparently employ the more recent system calls where they are available. -.PP -On some 32-bit architectures, -the calling signature for these system calls differ, -for the reasons described in -.BR syscall (2). +.SH NOTES +.BR ftruncate () +can also be used to set the size of a POSIX shared memory object; see +.BR shm_open (3). .SH BUGS A header file bug in glibc 2.12 meant that the minimum value of .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037 diff --git a/man2/umask.2 b/man2/umask.2 index 541d81c665..07e0b5e769 100644 --- a/man2/umask.2 +++ b/man2/umask.2 @@ -100,7 +100,9 @@ resulting file will be: This system call always succeeds and the previous value of the mask is returned. .SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. .SH NOTES A child process created via .BR fork (2) diff --git a/man2/umount.2 b/man2/umount.2 index fc0e32feec..3defe48ac9 100644 --- a/man2/umount.2 +++ b/man2/umount.2 @@ -154,15 +154,25 @@ The kernel could not allocate a free page to copy filenames or data into. .TP .B EPERM The caller does not have the required privileges. -.SH VERSIONS +.SH STANDARDS +Linux. +.SH HISTORY .B MNT_DETACH and .B MNT_EXPIRE .\" http://sourceware.org/bugzilla/show_bug.cgi?id=10092 are available since glibc 2.11. -.SH STANDARDS -These functions are Linux-specific and should not be used in -programs intended to be portable. +.PP +The original +.BR umount () +function was called as \fIumount(device)\fP and would return +.B ENOTBLK +when called with something other than a block device. +In Linux 0.98p4, a call \fIumount(dir)\fP was added, in order to +support anonymous devices. +In Linux 2.3.99-pre7, the call \fIumount(device)\fP was removed, +leaving only \fIumount(dir)\fP (since now devices can be mounted +in more than one place, so specifying the device does not suffice). .SH NOTES .SS umount() and shared mounts Shared mounts cause any mount activity on a mount, including @@ -196,17 +206,6 @@ and prior to .BR umount () being called. -.SS Historical details -The original -.BR umount () -function was called as \fIumount(device)\fP and would return -.B ENOTBLK -when called with something other than a block device. -In Linux 0.98p4, a call \fIumount(dir)\fP was added, in order to -support anonymous devices. -In Linux 2.3.99-pre7, the call \fIumount(device)\fP was removed, -leaving only \fIumount(dir)\fP (since now devices can be mounted -in more than one place, so specifying the device does not suffice). .SH SEE ALSO .BR mount (2), .BR mount_namespaces (7), diff --git a/man2/uname.2 b/man2/uname.2 index c44f9cf26d..4a274a2383 100644 --- a/man2/uname.2 +++ b/man2/uname.2 @@ -56,24 +56,10 @@ is set to indicate the error. .B EFAULT .I buf is not valid. -.SH STANDARDS -POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD. -.PP +.SH VERSIONS The .I domainname member (the NIS or YP domain name) is a GNU extension. -.SH NOTES -The kernel has the name, release, version, and supported machine type built in. -Conversely, the -.I nodename -field is configured by the administrator to match the network -(this is what the BSD historically calls the "hostname", -and is set via -.BR sethostname (2)). -Similarly, the -.I domainname -field is set via -.BR setdomainname (2). .PP The length of the fields in the struct varies. Some operating systems @@ -90,13 +76,10 @@ Clearly, it is a bad idea to use any of these constants; just use sizeof(...). SVr4 uses 257, "to support Internet hostnames" \[em] this is the largest value likely to be encountered in the wild. -.PP -Part of the utsname information is also accessible via -.IR /proc/sys/kernel/ { ostype , -.IR hostname , -.IR osrelease , -.IR version , -.IR domainname }. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD. .SS C library/kernel differences Over time, increases in the size of the .I utsname @@ -125,6 +108,25 @@ The glibc .BR uname () wrapper function hides these details from applications, invoking the most recent version of the system call provided by the kernel. +.SH NOTES +The kernel has the name, release, version, and supported machine type built in. +Conversely, the +.I nodename +field is configured by the administrator to match the network +(this is what the BSD historically calls the "hostname", +and is set via +.BR sethostname (2)). +Similarly, the +.I domainname +field is set via +.BR setdomainname (2). +.PP +Part of the utsname information is also accessible via +.IR /proc/sys/kernel/ { ostype , +.IR hostname , +.IR osrelease , +.IR version , +.IR domainname }. .SH SEE ALSO .BR uname (1), .BR getdomainname (2), diff --git a/man2/unlink.2 b/man2/unlink.2 index 954a19f153..1f66aca8f0 100644 --- a/man2/unlink.2 +++ b/man2/unlink.2 @@ -252,20 +252,20 @@ was not specified in is relative and .I dirfd is a file descriptor referring to a file other than a directory. -.SH VERSIONS -.BR unlinkat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. .SH STANDARDS -.BR unlink (): -SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. +POSIX.1-2008. +.SH HISTORY +.TP +.BR unlink () +SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional error .\" conditions EINTR, EMULTIHOP, ETXTBSY, ENOLINK. -.PP -.BR unlinkat (): +.TP +.BR unlinkat () POSIX.1-2008. -.SH NOTES -.SS glibc notes +Linux 2.6.16, +glibc 2.4. +.SS glibc On older kernels where .BR unlinkat () is unavailable, the glibc wrapper function falls back to the use of diff --git a/man2/unshare.2 b/man2/unshare.2 index 2c5c0b8590..229e065c80 100644 --- a/man2/unshare.2 +++ b/man2/unshare.2 @@ -419,14 +419,10 @@ and the limit on the number of nested user namespaces would be exceeded. See the discussion of the .B ENOSPC error above. -.SH VERSIONS -The -.BR unshare () -system call was added in Linux 2.6.16. .SH STANDARDS -The -.BR unshare () -system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.16. .SH NOTES Not all of the process attributes that can be shared when a new process is created using diff --git a/man2/uselib.2 b/man2/uselib.2 index 34365cc845..449e8d5779 100644 --- a/man2/uselib.2 +++ b/man2/uselib.2 @@ -56,10 +56,8 @@ The file specified by is not an executable of a known type; for example, it does not have the correct magic numbers. .SH STANDARDS -.BR uselib () -is Linux-specific, and should not be used in programs -intended to be portable. -.SH NOTES +Linux. +.SH HISTORY This obsolete system call is not supported by glibc. No declaration is provided in glibc headers, but, through a quirk of history, glibc before glibc 2.23 did export an ABI for this system call. diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2 index 7a0181f2a3..4fe404edd0 100644 --- a/man2/userfaultfd.2 +++ b/man2/userfaultfd.2 @@ -632,17 +632,13 @@ The caller is not privileged (does not have the capability in the initial user namespace), and .I /proc/sys/vm/unprivileged_userfaultfd has the value 0. -.SH VERSIONS -The -.BR userfaultfd () -system call first appeared in Linux 4.3. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.3. .PP -The support for hugetlbfs and shared memory areas and +Support for hugetlbfs and shared memory areas and non-page-fault events was added in Linux 4.11 -.SH STANDARDS -.BR userfaultfd () -is Linux-specific and should not be used in programs intended to be -portable. .SH NOTES The userfaultfd mechanism can be used as an alternative to traditional user-space paging techniques based on the use of the diff --git a/man2/ustat.2 b/man2/ustat.2 index 8a96239a49..b52dea303e 100644 --- a/man2/ustat.2 +++ b/man2/ustat.2 @@ -72,13 +72,14 @@ The mounted filesystem referenced by .I dev does not support this operation, or any version of Linux before Linux 1.3.16. -.SH VERSIONS -Since glibc 2.28, glibc no longer provides a wrapper for this system call. .SH STANDARDS +None. +.SH HISTORY SVr4. +Removed in glibc 2.28. .\" SVr4 documents additional error conditions ENOLINK, ECOMM, and EINTR .\" but has no ENOSYS condition. -.SH NOTES +.PP .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 c364c43903..5edbf97dea 100644 --- a/man2/utime.2 +++ b/man2/utime.2 @@ -149,13 +149,14 @@ capability). .I path resides on a read-only filesystem. .SH STANDARDS -.BR utime (): -SVr4, POSIX.1-2001. -POSIX.1-2008 marks +POSIX.1-2008. +.SH HISTORY +.TP .BR utime () -as obsolete. -.PP -.BR utimes (): +SVr4, POSIX.1-2001. +POSIX.1-2008 marks it as obsolete. +.TP +.BR utimes () 4.3BSD, POSIX.1-2001. .SH NOTES Linux does not allow changing the timestamps on an immutable file, diff --git a/man2/utimensat.2 b/man2/utimensat.2 index 803828e31f..9a1fb840d1 100644 --- a/man2/utimensat.2 +++ b/man2/utimensat.2 @@ -387,43 +387,6 @@ T} Thread safety MT-Safe .ad .sp 1 .SH VERSIONS -.BR utimensat () -was added in Linux 2.6.22; -glibc support was added with glibc 2.6. -.PP -Support for -.BR futimens () -first appeared in glibc 2.6. -.SH STANDARDS -.BR futimens () -and -.BR utimensat () -are specified in POSIX.1-2008. -.SH NOTES -.BR utimensat () -obsoletes -.BR futimesat (2). -.PP -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. -(This is consistent with the historical behavior of -.BR utime (2) -and -.BR utimes (2) -on Linux.) -.PP -If both -.I tv_nsec -fields are specified as -.BR UTIME_OMIT , -then the Linux implementation of -.BR utimensat () -succeeds even if the file referred to by -.I dirfd -and -.I pathname -does not exist. .SS C library/kernel ABI differences On Linux, .BR futimens () @@ -455,6 +418,43 @@ disallows passing NULL as the value for the wrapper function returns the error .B EINVAL in this case. +.SH STANDARDS +POSIX.1-2008. +.SH VERSIONS +.TP +.BR utimensat () +Linux 2.6.22, +glibc 2.6. +POSIX.1-2008. +.TP +.BR futimens () +glibc 2.6. +POSIX.1-2008. +.SH NOTES +.BR utimensat () +obsoletes +.BR futimesat (2). +.PP +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. +(This is consistent with the historical behavior of +.BR utime (2) +and +.BR utimes (2) +on Linux.) +.PP +If both +.I tv_nsec +fields are specified as +.BR UTIME_OMIT , +then the Linux implementation of +.BR utimensat () +succeeds even if the file referred to by +.I dirfd +and +.I pathname +does not exist. .SH BUGS Several bugs afflict .BR utimensat () diff --git a/man2/vfork.2 b/man2/vfork.2 index 5e6b8226c3..3a65010cab 100644 --- a/man2/vfork.2 +++ b/man2/vfork.2 @@ -134,11 +134,7 @@ The use of was tricky: for example, not modifying data in the parent process depended on knowing which variables were held in a register. -.SH STANDARDS -4.3BSD; POSIX.1-2001 (but marked OBSOLETE). -POSIX.1-2008 removes the specification of -.BR vfork (). -.PP +.SH VERSIONS The requirements put on .BR vfork () by the standards are weaker than those put on @@ -149,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. -.SH NOTES +.PP Some consider the semantics of .BR vfork () to be an architectural blemish, and the 4.2BSD man page stated: @@ -205,44 +201,6 @@ in this scenario requires either committing an amount of memory equal to the size of the parent process (if strict overcommitting is in force) or overcommitting memory with the risk that a process is terminated by the out-of-memory (OOM) killer. -.\" -.SS Caveats -The child process should take care not to modify the memory in unintended ways, -since such changes will be seen by the parent process once -the child terminates or executes another program. -In this regard, signal handlers can be especially problematic: -if a signal handler that is invoked in the child of -.BR vfork () -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 -When -.BR vfork () -is called in a multithreaded process, -only the calling thread is suspended until the child terminates -or executes a new program. -This means that the child is sharing an address space with other running code. -This can be dangerous if another thread in the parent process -changes credentials (using -.BR setuid (2) -or similar), -since there are now two processes with different privilege levels -running in the same address space. -As an example of the dangers, -suppose that a multithreaded program running as root creates a child using -.BR vfork (). -After the -.BR vfork (), -a thread in the parent process drops the process to an unprivileged user -in order to run some untrusted code -(e.g., perhaps via plug-in opened with -.BR dlopen (3)). -In this case, attacks are possible where the parent process uses -.BR mmap (2) -to map in code that will be executed by the privileged child process. -.\" .SS Linux notes Fork handlers established using .BR pthread_atfork (3) @@ -268,7 +226,13 @@ specified as: CLONE_VM | CLONE_VFORK | SIGCHLD .EE .in -.SS History +.SH STANDARDS +None. +.SH HISTORY +4.3BSD; POSIX.1-2001 (but marked OBSOLETE). +POSIX.1-2008 removes the specification of +.BR vfork (). +.PP The .BR vfork () system call appeared in 3.0BSD. @@ -286,6 +250,44 @@ until Linux 2.2.0-pre6 or so. Since Linux 2.2.0-pre9 (on i386, somewhat later on other architectures) it is an independent system call. Support was added in glibc 2.0.112. +.\" +.SH CAVEATS +The child process should take care not to modify the memory in unintended ways, +since such changes will be seen by the parent process once +the child terminates or executes another program. +In this regard, signal handlers can be especially problematic: +if a signal handler that is invoked in the child of +.BR vfork () +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 +When +.BR vfork () +is called in a multithreaded process, +only the calling thread is suspended until the child terminates +or executes a new program. +This means that the child is sharing an address space with other running code. +This can be dangerous if another thread in the parent process +changes credentials (using +.BR setuid (2) +or similar), +since there are now two processes with different privilege levels +running in the same address space. +As an example of the dangers, +suppose that a multithreaded program running as root creates a child using +.BR vfork (). +After the +.BR vfork (), +a thread in the parent process drops the process to an unprivileged user +in order to run some untrusted code +(e.g., perhaps via plug-in opened with +.BR dlopen (3)). +In this case, attacks are possible where the parent process uses +.BR mmap (2) +to map in code that will be executed by the privileged child process. +.\" .SH BUGS Details of the signal handling are obscure and differ between systems. The BSD man page states: diff --git a/man2/vhangup.2 b/man2/vhangup.2 index 78ece4600b..9bf304831e 100644 --- a/man2/vhangup.2 +++ b/man2/vhangup.2 @@ -52,8 +52,7 @@ the .B CAP_SYS_TTY_CONFIG capability is required. .SH STANDARDS -This call is Linux-specific, and should not be used in programs -intended to be portable. +Linux. .SH SEE ALSO .BR init (1), .BR capabilities (7) diff --git a/man2/vm86.2 b/man2/vm86.2 index 9c9102dc3e..437f68fa74 100644 --- a/man2/vm86.2 +++ b/man2/vm86.2 @@ -55,5 +55,4 @@ Saved kernel stack exists. (This is a kernel sanity check; the saved stack should exist only within vm86 mode itself.) .SH STANDARDS -This call is specific to Linux on 32-bit Intel processors, -and should not be used in programs intended to be portable. +Linux on 32-bit Intel processors. diff --git a/man2/vmsplice.2 b/man2/vmsplice.2 index 01ac37b358..569d0ddd16 100644 --- a/man2/vmsplice.2 +++ b/man2/vmsplice.2 @@ -132,13 +132,11 @@ set. .TP .B ENOMEM Out of memory. -.SH VERSIONS -The -.BR vmsplice () -system call first appeared in Linux 2.6.17; -library support was added in glibc 2.5. .SH STANDARDS -This system call is Linux-specific. +Linux. +.SH HISTORY +Linux 2.6.17, +glibc 2.5. .SH NOTES .BR vmsplice () follows the other vectorized read/write type functions when it comes to diff --git a/man2/wait.2 b/man2/wait.2 index e2dcd59bda..7386dffef9 100644 --- a/man2/wait.2 +++ b/man2/wait.2 @@ -460,7 +460,34 @@ or .I pid is equal to .BR INT_MIN . +.SH VERSIONS +.SS C library/kernel differences +.BR wait () +is actually a library function that (in glibc) is implemented as a call to +.BR wait4 (2). +.PP +On some architectures, there is no +.BR waitpid () +system call; +.\" e.g., i386 has the system call, but not x86-64 +instead, this interface is implemented via a C library +wrapper function that calls +.BR wait4 (2). +.PP +The raw +.BR waitid () +system call takes a fifth argument, of type +.IR "struct rusage\ *" . +If this argument is non-NULL, +then it is used to return resource usage information about the child, +in the same manner as +.BR wait4 (2). +See +.BR getrusage (2) +for details. .SH STANDARDS +POSIX.1-2008. +.SH HISTORY SVr4, 4.3BSD, POSIX.1-2001. .SH NOTES A child that terminates, but has not been waited for becomes a "zombie". @@ -577,30 +604,6 @@ Since Linux 4.7, the .B __WALL flag is automatically implied if the child is being ptraced. -.SS C library/kernel differences -.BR wait () -is actually a library function that (in glibc) is implemented as a call to -.BR wait4 (2). -.PP -On some architectures, there is no -.BR waitpid () -system call; -.\" e.g., i386 has the system call, but not x86-64 -instead, this interface is implemented via a C library -wrapper function that calls -.BR wait4 (2). -.PP -The raw -.BR waitid () -system call takes a fifth argument, of type -.IR "struct rusage\ *" . -If this argument is non-NULL, -then it is used to return resource usage information about the child, -in the same manner as -.BR wait4 (2). -See -.BR getrusage (2) -for details. .SH BUGS According to POSIX.1-2008, an application calling .BR waitid () diff --git a/man2/wait4.2 b/man2/wait4.2 index a5b38108d3..fe0c175f90 100644 --- a/man2/wait4.2 +++ b/man2/wait4.2 @@ -132,6 +132,8 @@ As for As for .BR waitpid (2). .SH STANDARDS +None. +.SH HISTORY 4.3BSD. .PP SUSv1 included a specification of @@ -140,7 +142,7 @@ SUSv2 included .BR wait3 (), but marked it LEGACY; SUSv3 removed it. -.SH NOTES +.PP Including .I <sys/time.h> is not required these days, but increases portability. diff --git a/man2/write.2 b/man2/write.2 index 9f4a814b6a..6160e91fa0 100644 --- a/man2/write.2 +++ b/man2/write.2 @@ -226,6 +226,8 @@ catches, blocks or ignores this signal.) Other errors may occur, depending on the object connected to .IR fd . .SH STANDARDS +POSIX.1-2008. +.SH HISTORY SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional error .\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE. |