aboutsummaryrefslogtreecommitdiffstats
path: root/man7
diff options
context:
space:
mode:
authorAlejandro Colomar <alx@kernel.org>2023-03-17 17:08:01 +0100
committerAlejandro Colomar <alx@kernel.org>2023-03-30 15:14:55 +0200
commit4131356cdab8d37fc395ca5466a0401c8573380c (patch)
tree8c4c6f1c3172358b735b481cbbfdd9cc04b00ed9 /man7
parentfd00f831b52d61a91d59cb3b46182869145d9700 (diff)
downloadman-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 'man7')
-rw-r--r--man7/aio.77
-rw-r--r--man7/cgroup_namespaces.72
-rw-r--r--man7/credentials.71
-rw-r--r--man7/epoll.720
-rw-r--r--man7/fanotify.78
-rw-r--r--man7/feature_test_macros.76
-rw-r--r--man7/inode.79
-rw-r--r--man7/inotify.76
-rw-r--r--man7/man-pages.756
-rw-r--r--man7/mount_namespaces.76
-rw-r--r--man7/numa.72
-rw-r--r--man7/pid_namespaces.72
-rw-r--r--man7/queue.74
-rw-r--r--man7/rtld-audit.76
-rw-r--r--man7/sock_diag.72
-rw-r--r--man7/user_namespaces.72
16 files changed, 74 insertions, 65 deletions
diff --git a/man7/aio.7 b/man7/aio.7
index 5a9dc4ff19..84613b622a 100644
--- a/man7/aio.7
+++ b/man7/aio.7
@@ -139,10 +139,11 @@ field of the
structure was less than 0,
or was greater than the limit returned by the call
.IR sysconf(_SC_AIO_PRIO_DELTA_MAX) .
-.SH VERSIONS
-The POSIX AIO interfaces are provided by glibc since glibc 2.1.
.SH STANDARDS
-POSIX.1-2001, POSIX.1-2008.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+glibc 2.1.
.SH NOTES
It is a good idea to zero out the control block buffer before use (see
.BR memset (3)).
diff --git a/man7/cgroup_namespaces.7 b/man7/cgroup_namespaces.7
index b1b0c41294..cb7778695e 100644
--- a/man7/cgroup_namespaces.7
+++ b/man7/cgroup_namespaces.7
@@ -161,7 +161,7 @@ sh2# \fBcat /proc/self/mountinfo | grep freezer\fP
.in
.\"
.SH STANDARDS
-Namespaces are a Linux-specific feature.
+Linux.
.SH NOTES
Use of cgroup namespaces requires a kernel that is configured with the
.B CONFIG_CGROUPS
diff --git a/man7/credentials.7 b/man7/credentials.7
index 02f8f8aa31..77cb5e0ef2 100644
--- a/man7/credentials.7
+++ b/man7/credentials.7
@@ -302,6 +302,7 @@ Process IDs, parent process IDs, process group IDs, and session IDs
are specified in POSIX.1.
The real, effective, and saved set user and groups IDs,
and the supplementary group IDs, are specified in POSIX.1.
+.PP
The filesystem user and group IDs are a Linux extension.
.SH NOTES
Various fields in the
diff --git a/man7/epoll.7 b/man7/epoll.7
index ffb409a51e..1e86799461 100644
--- a/man7/epoll.7
+++ b/man7/epoll.7
@@ -574,20 +574,18 @@ event for file descriptor 13 in your batch processing,
you will discover the file descriptor had been
previously removed and there will be no confusion.
.SH VERSIONS
-The
-.B epoll
-API was introduced in Linux kernel 2.5.44.
-.\" Its interface should be finalized in Linux kernel 2.5.66.
-Support was added in glibc 2.3.2.
-.SH STANDARDS
-The
-.B epoll
-API is Linux-specific.
-Some other systems provide similar
-mechanisms, for example, FreeBSD has
+Some other systems provide similar mechanisms;
+for example,
+FreeBSD has
.IR kqueue ,
and Solaris has
.IR /dev/poll .
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.5.44.
+.\" Its interface should be finalized in Linux 2.5.66.
+glibc 2.3.2.
.SH NOTES
The set of file descriptors that is being monitored via
an epoll file descriptor can be viewed via the entry for
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 6ebb98adac..3963e74203 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -906,12 +906,12 @@ The file descriptor
in the response structure is not valid.
This may occur when a response for the permission event has already been
written.
-.SH VERSIONS
+.SH STANDARDS
+Linux.
+.SH HISTORY
The fanotify API was introduced in Linux 2.6.36 and
enabled in Linux 2.6.37.
-Fdinfo support was added in Linux 3.8.
-.SH STANDARDS
-The fanotify API is Linux-specific.
+fdinfo support was added in Linux 3.8.
.SH NOTES
The fanotify API is available only if the kernel was built with the
.B CONFIG_FANOTIFY
diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7
index 4dc9b9594c..344c7e47a5 100644
--- a/man7/feature_test_macros.7
+++ b/man7/feature_test_macros.7
@@ -765,8 +765,6 @@ POSIX.1 specifies
and
.BR _XOPEN_SOURCE .
.PP
-.B _XOPEN_SOURCE_EXTENDED
-was specified by XPG4v2 (aka SUSv1), but is not present in SUSv2 and later.
.B _FILE_OFFSET_BITS
is not specified by any standard,
but is employed on some other implementations.
@@ -781,6 +779,10 @@ but is employed on some other implementations.
and
.B _THREAD_SAFE
are specific to glibc.
+.SH HISTORY
+.PP
+.B _XOPEN_SOURCE_EXTENDED
+was specified by XPG4v2 (aka SUSv1), but is not present in SUSv2 and later.
.SH NOTES
.I <features.h>
is a Linux/glibc-specific header file.
diff --git a/man7/inode.7 b/man7/inode.7
index c97fb6ab30..dc2c38d1df 100644
--- a/man7/inode.7
+++ b/man7/inode.7
@@ -426,6 +426,10 @@ in that directory can be renamed or deleted only by the owner
of the file, by the owner of the directory, and by a privileged
process.
.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.PP
POSIX.1-1990 did not describe the
.BR S_IFMT ,
.BR S_IFSOCK ,
@@ -441,16 +445,13 @@ constants, but instead specified the use of
the macros
.BR S_ISDIR ()
and so on.
-The
-.B S_IF*
-constants are present in POSIX.1-2001 and later.
.PP
The
.BR S_ISLNK ()
and
.BR S_ISSOCK ()
macros were not in
-POSIX.1-1996, but both are present in POSIX.1-2001;
+POSIX.1-1996;
the former is from SVID 4, the latter from SUSv2.
.PP
UNIX\ V7 (and later systems) had
diff --git a/man7/inotify.7 b/man7/inotify.7
index 4b9fa0200c..78ec0317f9 100644
--- a/man7/inotify.7
+++ b/man7/inotify.7
@@ -575,7 +575,9 @@ that can be created per real user ID.
.I /proc/sys/fs/inotify/max_user_watches
This specifies an upper limit on the number of watches
that can be created per real user ID.
-.SH VERSIONS
+.SH STANDARDS
+Linux.
+.SH HISTORY
Inotify was merged into Linux 2.6.13.
The required library interfaces were added in glibc 2.4.
.RB ( IN_DONT_FOLLOW ,
@@ -583,8 +585,6 @@ The required library interfaces were added in glibc 2.4.
and
.B IN_ONLYDIR
were added in glibc 2.5.)
-.SH STANDARDS
-The inotify API is Linux-specific.
.SH NOTES
Inotify file descriptors can be monitored using
.BR select (2),
diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 610171e4b8..d63f2d8f2b 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -151,6 +151,7 @@ FILES
ATTRIBUTES [Normally only in Sections 2, 3]
VERSIONS [Normally only in Sections 2, 3]
STANDARDS
+HISTORY
NOTES
CAVEATS
BUGS
@@ -341,12 +342,35 @@ See
for further details.
.TP
.B VERSIONS
+A summary of systems where the API performs differently,
+or where there's a similar API.
+.TP
+.B STANDARDS
+A description of any standards or conventions that relate to the function
+or command described by the manual page.
+.IP
+The preferred terms to use for the various standards are listed as
+headings in
+.BR standards (7).
+.IP
+This section should note the current standards to which the API conforms to.
+.IP
+If the API is not governed by any standards but commonly
+exists on other systems, note them.
+If the call is Linux-specific or GNU-specific, note this.
+If it's available in the BSDs, note that.
+.IP
+If this section consists of just a list of standards
+(which it commonly does),
+terminate the list with a period (\[aq].\[aq]).
+.TP
+.B HISTORY
A brief summary of the Linux kernel or glibc versions where a
system call or library function appeared,
or changed significantly in its operation.
.IP
As a general rule, every new interface should
-include a VERSIONS section in its manual page.
+include a HISTORY section in its manual page.
Unfortunately,
many existing manual pages don't include this information
(since there was no policy to do so when they were written).
@@ -362,31 +386,11 @@ The
.BR syscalls (2)
manual page also provides information about kernel versions
in which various system calls first appeared.
-.TP
-.B STANDARDS
-A description of any standards or conventions that relate to the function
-or command described by the manual page.
-.IP
-The preferred terms to use for the various standards are listed as
-headings in
-.BR standards (7).
-.IP
-For a page in Section 2 or 3,
-this section should note the POSIX.1
-version(s) that the call conforms to,
-and also whether the call is specified in C99.
-(Don't worry too much about other standards like SUS, SUSv2, and XPG,
-or the SVr4 and 4.xBSD implementation standards,
-unless the call was specified in those standards,
-but isn't in the current version of POSIX.1.)
-.IP
-If the call is not governed by any standards but commonly
-exists on other systems, note them.
-If the call is Linux-specific, note this.
-.IP
-If this section consists of just a list of standards
-(which it commonly does),
-terminate the list with a period (\[aq].\[aq]).
+.PP
+Old versions of standards should be mentioned here,
+rather than in STANDARDS,
+for example,
+SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD implementation standards.
.TP
.B NOTES
Miscellaneous notes.
diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7
index c40aae96b1..b17f86a4ca 100644
--- a/man7/mount_namespaces.7
+++ b/man7/mount_namespaces.7
@@ -977,10 +977,10 @@ mount point before the
.BR chroot (1)
was performed).
.\"
-.SH VERSIONS
-Mount namespaces first appeared in Linux 2.4.19.
.SH STANDARDS
-Namespaces are a Linux-specific feature.
+Linux.
+.SH HISTORY
+Linux 2.4.19.
.\"
.SH NOTES
The propagation type assigned to a new mount depends
diff --git a/man7/numa.7 b/man7/numa.7
index f5a314b565..c6ea675142 100644
--- a/man7/numa.7
+++ b/man7/numa.7
@@ -126,7 +126,7 @@ removed from memory by the swapper soon.
.I writeback=<pages>
Number of pages that are currently being written out to disk.
.SH STANDARDS
-No standards govern NUMA interfaces.
+None.
.SH NOTES
The Linux NUMA system calls and
.I /proc
diff --git a/man7/pid_namespaces.7 b/man7/pid_namespaces.7
index d329854854..78d0e0986a 100644
--- a/man7/pid_namespaces.7
+++ b/man7/pid_namespaces.7
@@ -370,7 +370,7 @@ in
it is translated into the corresponding PID value in
the receiving process's PID namespace.
.SH STANDARDS
-Namespaces are a Linux-specific feature.
+Linux.
.SH EXAMPLES
See
.BR user_namespaces (7).
diff --git a/man7/queue.7 b/man7/queue.7
index 83851c7a14..128fa8a5af 100644
--- a/man7/queue.7
+++ b/man7/queue.7
@@ -115,8 +115,8 @@ However:
.IP \[bu] 3
The termination condition for traversal is more complex.
.SH STANDARDS
-Not in POSIX.1, POSIX.1-2001, or POSIX.1-2008.
-Present on the BSDs.
+BSD.
+.SH HISTORY
.I <sys/queue.h>
macros first appeared in 4.4BSD.
.SH NOTES
diff --git a/man7/rtld-audit.7 b/man7/rtld-audit.7
index ca47427c3d..c5d4fdddcb 100644
--- a/man7/rtld-audit.7
+++ b/man7/rtld-audit.7
@@ -455,12 +455,14 @@ is ignored.
.\" symbol binding should return the value of the 'retval' argument
.\" (not provided by GNU, but equivalent to returning outregs->lrv_eax
.\" on (say) x86-32).
-.SH STANDARDS
-This API is nonstandard, but very similar to the Solaris API,
+.SH VERSIONS
+This API is very similar to the Solaris API
described in the Solaris
.IR "Linker and Libraries Guide" ,
in the chapter
.IR "Runtime Linker Auditing Interface" .
+.SH STANDARDS
+None.
.SH NOTES
Note the following differences from the Solaris dynamic linker
auditing API:
diff --git a/man7/sock_diag.7 b/man7/sock_diag.7
index e75dc4d1a0..6dfed2c352 100644
--- a/man7/sock_diag.7
+++ b/man7/sock_diag.7
@@ -617,7 +617,7 @@ and
.B INET_DIAG_SKMEMINFO
were introduced in Linux 3.6.
.SH STANDARDS
-The NETLINK_SOCK_DIAG API is Linux-specific.
+Linux.
.SH EXAMPLES
The following example program prints inode number, peer's inode number,
and name of all UNIX domain sockets in the current namespace.
diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7
index 737dd54ad9..3c376a9f01 100644
--- a/man7/user_namespaces.7
+++ b/man7/user_namespaces.7
@@ -1013,7 +1013,7 @@ they are translated into the corresponding values as per the
receiving process's user and group ID mappings.
.\"
.SH STANDARDS
-Namespaces are a Linux-specific feature.
+Linux.
.\"
.SH NOTES
Over the years, there have been a lot of features that have been added
generated by cgit 1.2.3-korg (git 2.43.0) at 2025-11-28 19:30:30 +0000