man7/, man-pages.7: VERSIONS, STANDARDS, HISTORY: Reorganize sections
PATCH 1/1 man7/, 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 other 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' or 'BSD' when a non-standard API is Linux-only or if it's standard in the BSDs.
Signed-off-by Alejandro Colomar <[email protected]>
---
Hi,
This is a preview of what I'm preparing. I've modified only man7/, but I plan to do the same in the rest of the pages. Please have a look at the patch.
Thanks,
Alex
man7/aio.7 | 7 ++--- man7/cgroup_namespaces.7 | 2 +- man7/credentials.7 | 1 + man7/epoll.7 | 20 +++++++------- man7/fanotify.7 | 8 +++--- man7/feature_test_macros.7 | 6 +++-- man7/inode.7 | 9 ++++--- man7/inotify.7 | 6 ++--- man7/man-pages.7 | 55 ++++++++++++++++++++------------------ man7/mount_namespaces.7 | 6 ++--- man7/numa.7 | 2 +- man7/pid_namespaces.7 | 2 +- man7/queue.7 | 5 ++-- man7/rtld-audit.7 | 6 +++-- man7/sock_diag.7 | 2 +- man7/user_namespaces.7 | 2 +- 16 files changed, 74 insertions(+), 65 deletions(-)
man7/aio.7 +4 -3
@@ -139,10 +139,11 @@ .SH ERRORS 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)).
man7/cgroup_namespaces.7 +1 -1
@@ -161,7 +161,7 @@ .SH DESCRIPTION .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
man7/credentials.7 +1 -0
@@ -302,6 +302,7 @@ .SH STANDARDS 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
man7/epoll.7 +9 -11
@@ -574,20 +574,18 @@ .SS Possible pitfalls and ways to avoid them 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
man7/fanotify.7 +4 -4
@@ -906,12 +906,12 @@ .SH ERRORS 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
man7/feature_test_macros.7 +4 -2
@@ -765,8 +765,6 @@ .SH STANDARDS 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 @@ .SH STANDARDS 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.
man7/inode.7 +5 -4
@@ -426,6 +426,10 @@ .SS The file type and mode 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 @@ .SH STANDARDS 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
man7/inotify.7 +3 -3
@@ -575,7 +575,9 @@ .SS /proc interfaces .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 @@ .SH VERSIONS 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),
man7/man-pages.7 +29 -26
78 lines not on this page · raw message
man7/mount_namespaces.7 +3 -3
@@ -977,10 +977,10 @@ .SS The /proc/ pid /mountinfo "propagate_from" tag .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
man7/numa.7 +1 -1
@@ -126,7 +126,7 @@ .SS /proc/[number]/numa_maps (since Linux 2.6.14) .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
man7/pid_namespaces.7 +1 -1
@@ -370,7 +370,7 @@ .SS Miscellaneous 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).
man7/queue.7 +3 -2
@@ -115,8 +115,9 @@ .SS Doubly linked circular queues (CIRCLEQ) .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. +Not in POSIX.1. +.SH HISTORY .I <sys/queue.h> macros first appeared in 4.4BSD. .SH NOTES
man7/rtld-audit.7 +4 -2
@@ -455,12 +455,14 @@ .SS la_pltexit() .\" 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:
man7/sock_diag.7 +1 -1
@@ -617,7 +617,7 @@ .SH VERSIONS .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.
man7/user_namespaces.7 +1 -1
@@ -1013,7 +1013,7 @@ .SS Miscellaneous 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
Signature · 1 line
2.39.2