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>

33 files changed, 160 insertions, 97 deletions

diff --git a/man3type/FILE.3type b/man3type/FILE.3type
index 82000d837..902557511 100644
--- a/man3type/FILE.3type
+++ b/man3type/FILE.3type
@@ -19,8 +19,9 @@ Standard C library
 .SH DESCRIPTION
 An object type used for streams.
 .SH STANDARDS
-C99 and later;
-POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C89, POSIX.1-2001.
 .SH NOTES
 The following header also provides this type:
 .IR <wchar.h> .
diff --git a/man3type/aiocb.3type b/man3type/aiocb.3type
index 7bfe97162..945561710 100644
--- a/man3type/aiocb.3type
+++ b/man3type/aiocb.3type
@@ -28,7 +28,9 @@ Standard C library
 For further information about this structure, see
 .BR aio (7).
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH SEE ALSO
 .BR aio_cancel (3),
 .BR aio_error (3),
diff --git a/man3type/blkcnt_t.3type b/man3type/blkcnt_t.3type
index c9bb2ed40..6b7836115 100644
--- a/man3type/blkcnt_t.3type
+++ b/man3type/blkcnt_t.3type
@@ -20,7 +20,9 @@ Standard C library
 Used for file block counts.
 It is a signed integer type.
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following header also provides this type:
 .IR <sys/stat.h> .
diff --git a/man3type/blksize_t.3type b/man3type/blksize_t.3type
index 0b1c82bcd..5c0a24e81 100644
--- a/man3type/blksize_t.3type
+++ b/man3type/blksize_t.3type
@@ -20,7 +20,9 @@ Standard C library
 Used for file block sizes.
 It is a signed integer type.
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following header also provides this type:
 .IR <sys/stat.h> .
diff --git a/man3type/cc_t.3type b/man3type/cc_t.3type
index ef0d44107..f0c7a490c 100644
--- a/man3type/cc_t.3type
+++ b/man3type/cc_t.3type
@@ -28,6 +28,8 @@ for modes.
 .PP
 All are unsigned integer types.
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH SEE ALSO
 .BR termios (3)
diff --git a/man3type/clock_t.3type b/man3type/clock_t.3type
index b3fdf0346..12da83de9 100644
--- a/man3type/clock_t.3type
+++ b/man3type/clock_t.3type
@@ -24,7 +24,9 @@ Used for system time in clock ticks or
 According to POSIX,
 it is an integer type or a real-floating type.
 .SH STANDARDS
-C99 and later; POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C89, POSIX.1-2001.
 .SH NOTES
 The following headers also provide this type:
 .I <sys/types.h>
diff --git a/man3type/clockid_t.3type b/man3type/clockid_t.3type
index 092a07c15..97ce86661 100644
--- a/man3type/clockid_t.3type
+++ b/man3type/clockid_t.3type
@@ -14,7 +14,9 @@ Standard C library
 Used for clock ID type in the clock and timer functions.
 It is defined as an arithmetic type.
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following header also provides this type:
 .IR <time.h> .
diff --git a/man3type/dev_t.3type b/man3type/dev_t.3type
index 898886b84..0a3df9353 100644
--- a/man3type/dev_t.3type
+++ b/man3type/dev_t.3type
@@ -22,7 +22,9 @@ It is an integer type.
 For further details of this type, see
 .BR makedev (3).
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following header also provides this type:
 .IR <sys/stat.h> .
diff --git a/man3type/div_t.3type b/man3type/div_t.3type
index fa4330709..d62ea2cca 100644
--- a/man3type/div_t.3type
+++ b/man3type/div_t.3type
@@ -48,7 +48,9 @@ is the type of the value returned by the
 .BR imaxdiv (3)
 function.
 .SH STANDARDS
-C99 and later; POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C99, POSIX.1-2001.
 .SH SEE ALSO
 .BR div (3),
 .BR imaxdiv (3),
diff --git a/man3type/double_t.3type b/man3type/double_t.3type
index e0f820582..1bf1946eb 100644
--- a/man3type/double_t.3type
+++ b/man3type/double_t.3type
@@ -48,7 +48,9 @@ and
 .I double_t
 are implementation-defined.
 .SH STANDARDS
-C99 and later; POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C99, POSIX.1-2001.
 .SH SEE ALSO
 .BR float.h (0p),
 .BR math.h (0p)
diff --git a/man3type/epoll_event.3type b/man3type/epoll_event.3type
index 4e4d34284..4806bca66 100644
--- a/man3type/epoll_event.3type
+++ b/man3type/epoll_event.3type
@@ -33,9 +33,7 @@ The
 .I epoll_event
 structure specifies data that the kernel should save and
 return when the corresponding file descriptor becomes ready.
-.SH STANDARDS
-This type is Linux-specific.
-.SH NOTES
+.SH VERSIONS
 .SS C library/kernel differences
 The Linux kernel headers also provide this type,
 with a slightly different definition:
@@ -50,6 +48,8 @@ struct epoll_event {
 };
 .EE
 .in
+.SH STANDARDS
+Linux.
 .SH SEE ALSO
 .BR epoll_wait (2),
 .BR epoll_ctl (7)
diff --git a/man3type/fenv_t.3type b/man3type/fenv_t.3type
index 086f1d977..9e2202257 100644
--- a/man3type/fenv_t.3type
+++ b/man3type/fenv_t.3type
@@ -28,6 +28,8 @@ represents the floating-point status flags collectively.
 For further details see
 .BR fenv (3).
 .SH STANDARDS
-C99 and later; POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C99, POSIX.1-2001.
 .SH SEE ALSO
 .BR fenv (3)
diff --git a/man3type/id_t.3type b/man3type/id_t.3type
index d6bc97b6f..4c76ad2f6 100644
--- a/man3type/id_t.3type
+++ b/man3type/id_t.3type
@@ -40,7 +40,9 @@ It is an integer type that can be used to contain a
 or
 .IR gid_t .
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following headers also provide
 .IR pid_t :
diff --git a/man3type/intN_t.3type b/man3type/intN_t.3type
index 09383cd65..3a1e51518 100644
--- a/man3type/intN_t.3type
+++ b/man3type/intN_t.3type
@@ -156,8 +156,13 @@ for scanning
 .I uint8_t
 values.
 .SH STANDARDS
-C99 and later;
-POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C99, POSIX.1-2001.
+.PP
+The
+.RB [ U ] INT \fIN\fP _WIDTH
+macros were added in C23.
 .SH NOTES
 The following header also provides these types:
 .IR <inttypes.h> .
diff --git a/man3type/intmax_t.3type b/man3type/intmax_t.3type
index 8c2f9ff0f..e5feb4c56 100644
--- a/man3type/intmax_t.3type
+++ b/man3type/intmax_t.3type
@@ -81,7 +81,9 @@ for printing
 .RI [ u ] intmax_t
 values.
 .SH STANDARDS
-C99 and later; POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C99, POSIX.1-2001.
 .SH NOTES
 The following header also provides these types:
 .IR <inttypes.h> .
diff --git a/man3type/intptr_t.3type b/man3type/intptr_t.3type
index 9b614fac6..9481baf91 100644
--- a/man3type/intptr_t.3type
+++ b/man3type/intptr_t.3type
@@ -96,7 +96,9 @@ for scanning
 .I uintptr_t
 values.
 .SH STANDARDS
-C99 and later; POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C99, POSIX.1-2001.
 .SH NOTES
 The following header also provides these types:
 .IR <inttypes.h> .
diff --git a/man3type/iovec.3type b/man3type/iovec.3type
index 5f3a7e3ef..559883183 100644
--- a/man3type/iovec.3type
+++ b/man3type/iovec.3type
@@ -38,7 +38,9 @@ is limited by
 or accessible via the call
 .IR sysconf(_SC_IOV_MAX) ).
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following header also provides this type:
 .IR <sys/socket.h> .
diff --git a/man3type/itimerspec.3type b/man3type/itimerspec.3type
index 9ed7faafd..5d645e2f7 100644
--- a/man3type/itimerspec.3type
+++ b/man3type/itimerspec.3type
@@ -23,7 +23,7 @@ Describes the initial expiration of a timer,
 and its interval,
 in seconds and nanoseconds.
 .SH STANDARDS
-Linux-specific.
+Linux.
 .SH NOTES
 The following header also provides this type:
 .IR <sys/timerfd.h> .
diff --git a/man3type/lconv.3type b/man3type/lconv.3type
index 7f860b4ab..5c326d7c9 100644
--- a/man3type/lconv.3type
+++ b/man3type/lconv.3type
@@ -46,7 +46,9 @@ Contains members related to the formatting of numeric values.
 In the "C" locale, its members have the values
 shown in the comments above.
 .SH STANDARDS
-C11 and later; POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH SEE ALSO
 .BR setlocale (3),
 .BR localeconv (3),
diff --git a/man3type/mode_t.3type b/man3type/mode_t.3type
index 2ea1784cc..c90a35fb0 100644
--- a/man3type/mode_t.3type
+++ b/man3type/mode_t.3type
@@ -20,7 +20,9 @@ Standard C library
 Used for some file attributes (e.g., file mode).
 It is an integer type.
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following headers also provide this type:
 .IR <fcntl.h> ,
diff --git a/man3type/off_t.3type b/man3type/off_t.3type
index 1e8734fa6..4d4bae143 100644
--- a/man3type/off_t.3type
+++ b/man3type/off_t.3type
@@ -38,24 +38,27 @@ used in glibc.
 .I loff_t
 is a 64-bit version of the type,
 introduced by the Linux kernel.
+.SH STANDARDS
+.TP
+.I off_t
+POSIX.1-2008.
+.TP
+.I off64_t
+GNU and some BSDs.
+.TP
+.I loff_t
+Linux.
 .SH VERSIONS
+.TP
+.I off_t
+POSIX.1-2001.
+.PP
 .I <aio.h>
 and
 .I <stdio.h>
 define
 .I off_t
 since POSIX.1-2008.
-.SH STANDARDS
-.PD 0
-.IR off_t :
-POSIX.1-2001 and later.
-.PP
-.IR off64_t :
-Present in glibc and some BSDs.
-.PP
-.IR loff_t :
-Linux-specific.
-.PD
 .SH NOTES
 On some architectures,
 the width of
diff --git a/man3type/ptrdiff_t.3type b/man3type/ptrdiff_t.3type
index a4d41e5e7..093e630bf 100644
--- a/man3type/ptrdiff_t.3type
+++ b/man3type/ptrdiff_t.3type
@@ -40,7 +40,8 @@ for printing
 .I ptrdiff_t
 values.
 .SH STANDARDS
-C99 and later;
-POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C89, POSIX.1-2001.
 .SH SEE ALSO
 .BR size_t (3type)
diff --git a/man3type/regex_t.3type b/man3type/regex_t.3type
index a87c1994a..176d2c7a6 100644
--- a/man3type/regex_t.3type
+++ b/man3type/regex_t.3type
@@ -47,7 +47,11 @@ capable of storing the largest value that can be stored in either an
 type or a
 .I ssize_t
 type.
-.SH VERSIONS
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.PP
 Prior to POSIX.1-2008,
 the type was
 capable of storing the largest value that can be stored in either an
@@ -55,7 +59,5 @@ capable of storing the largest value that can be stored in either an
 type or a
 .I ssize_t
 type.
-.SH STANDARDS
-POSIX.1-2001 and later.
 .SH SEE ALSO
 .BR regex (3)
diff --git a/man3type/size_t.3type b/man3type/size_t.3type
index 6a71be7a8..97633a976 100644
--- a/man3type/size_t.3type
+++ b/man3type/size_t.3type
@@ -84,9 +84,22 @@ by converting the value to
 .I intmax_t
 and using its length modifier
 .RB ( j ).
-.SH VERSIONS
+.SH STANDARDS
 .TP
 .I size_t
+C11, POSIX.1-2008.
+.TP
+.I ssize_t
+POSIX.1-2008.
+.PD
+.SH HISTORY
+.TP
+.I size_t
+C89, POSIX.1-2001.
+.TP
+.I ssize_t
+POSIX.1-2001.
+.PP
 .IR <aio.h> ,
 .IR <glob.h> ,
 .IR <grp.h> ,
@@ -99,8 +112,7 @@ and
 define
 .I size_t
 since POSIX.1-2008.
-.TP
-.I ssize_t
+.PP
 .IR <aio.h> ,
 .IR <mqueue.h> ,
 and
@@ -108,15 +120,6 @@ and
 define
 .I ssize_t
 since POSIX.1-2008.
-.SH STANDARDS
-.PD 0
-.IR size_t :
-C99 and later;
-POSIX.1-2001 and later.
-.PP
-.IR ssize_t :
-POSIX.1-2001 and later.
-.PD
 .SH NOTES
 .TP
 .I size_t
diff --git a/man3type/sockaddr.3type b/man3type/sockaddr.3type
index 319a5e552..32c3c5bd0 100644
--- a/man3type/sockaddr.3type
+++ b/man3type/sockaddr.3type
@@ -109,7 +109,9 @@ stored in network byte order.
 .I sockaddr_un
 Describes a UNIX domain socket address.
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 .I socklen_t
 is also defined in
diff --git a/man3type/stat.3type b/man3type/stat.3type
index 5f6e07886..c511b4337 100644
--- a/man3type/stat.3type
+++ b/man3type/stat.3type
@@ -116,7 +116,11 @@ This is the file's last status change timestamp
 .PP
 For further information on the above fields, see
 .BR inode (7).
-.SH VERSIONS
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.PP
 Old kernels and old standards did not support nanosecond timestamp fields.
 Instead, there were three timestamp
 .RI fields\[em] st_atime ,
@@ -150,8 +154,6 @@ is defined.
 If none of the aforementioned macros are defined,
 then the nanosecond values are exposed with names of the form
 .IR st_atimensec .
-.SH STANDARDS
-POSIX.1-2001 and later.
 .SH NOTES
 The following header also provides this type:
 .IR <ftw.h> .
diff --git a/man3type/time_t.3type b/man3type/time_t.3type
index 0808236c9..1b9607358 100644
--- a/man3type/time_t.3type
+++ b/man3type/time_t.3type
@@ -45,38 +45,43 @@ It is an unsigned integer type
 capable of storing values al least in the range
 .RB [ 0 ,
 .BR 1000000 ].
-.SH VERSIONS
+.SH STANDARDS
+.TP
+.I time_t
+C11, POSIX.1-2008.
+.TP
+.I suseconds_t
+.TQ
+.I useconds_t
+POSIX.1-2008.
+.PD
+.SH HISTORY
 .TP
 .I time_t
+C89, POSIX.1-2001.
+.TP
+.I suseconds_t
+.TQ
+.I useconds_t
+POSIX.1-2001.
+.PP
 .I <sched.h>
 defines
 .I time_t
 since POSIX.1-2008.
-.TP
-.I suseconds_t
+.PP
 POSIX.1-2001 defined
 .I useconds_t
 in
 .I <unistd.h>
 too.
-.SH STANDARDS
-.PD 0
-.IR time_t :
-C99 and later;
-POSIX.1-2001 and later.
-.PP
-.IR suseconds_t ,
-.IR useconds_t :
-POSIX.1-2001 and later.
-.PD
 .SH NOTES
 On some architectures,
 the width of
 .I time_t
 can be controlled with the feature test macro
 .BR _TIME_BITS .
-.TP
-.I time_t
+.PP
 The following headers also provide
 .IR time_t :
 .IR <sched.h> ,
@@ -89,8 +94,7 @@ The following headers also provide
 .IR <sys/types.h> ,
 and
 .IR <utime.h> .
-.TP
-.I suseconds_t
+.PP
 The following headers also provide
 .IR suseconds_t :
 .I <sys/select.h>
diff --git a/man3type/timer_t.3type b/man3type/timer_t.3type
index 1f5e8bcae..6470855f7 100644
--- a/man3type/timer_t.3type
+++ b/man3type/timer_t.3type
@@ -20,7 +20,9 @@ Standard C library
 Used for timer ID returned by
 .BR timer_create (2).
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following header also provides
 .IR timer_t :
diff --git a/man3type/timespec.3type b/man3type/timespec.3type
index 53a99de72..b5028a105 100644
--- a/man3type/timespec.3type
+++ b/man3type/timespec.3type
@@ -32,14 +32,15 @@ and
 .I long long
 on X32.
 It can be safely down-cast to any concrete 32-bit integer type for processing.
-.SH STANDARDS
-C11 and later;
-POSIX.1-2001 and later.
 .SH VERSIONS
 Prior to C23,
 .I tv_nsec
 was
 .IR long .
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following headers also provide this type:
 .IR <aio.h> ,
diff --git a/man3type/timeval.3type b/man3type/timeval.3type
index 36a7a4820..c8963ef4a 100644
--- a/man3type/timeval.3type
+++ b/man3type/timeval.3type
@@ -22,7 +22,9 @@ Standard C library
 .SH DESCRIPTION
 Describes times in seconds and microseconds.
 .SH STANDARDS
-POSIX.1-2001 and later.
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
 .SH NOTES
 The following headers also provide this type:
 .IR <sys/resource.h> ,
diff --git a/man3type/tm.3type b/man3type/tm.3type
index 79e0cfc25..e203b15e7 100644
--- a/man3type/tm.3type
+++ b/man3type/tm.3type
@@ -75,21 +75,6 @@ UTC doesn't permit double leap seconds,
 so it was limited to
 .B 60
 in C99.
-.SH STANDARDS
-C90 and later;
-POSIX.1-2001 and later.
-.PP
-.I tm_gmtoff
-and
-.I tm_zone
-originate from 4.3BSD-Tahoe (where
-.I tm_zone
-is a
-.IR "char *" ).
-.SH NOTES
-.I tm_sec
-can represent a leap second with the value
-.BR 60 .
 .PP
 .BR timezone (3),
 as a variable, is an XSI extension: some systems provide the V7-compatible
@@ -104,6 +89,22 @@ field provides an alternative (with the opposite sign) for those systems.
 points to static storage and may be overridden on subsequent calls to
 .BR localtime (3)
 and similar functions (however, this never happens under glibc).
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+C89, POSIX.1-2001.
+.PP
+.I tm_gmtoff
+and
+.I tm_zone
+originate from 4.3BSD-Tahoe (where
+.I tm_zone
+is a
+.IR "char *" ).
+.SH NOTES
+.I tm_sec
+can represent a leap second with the value
+.BR 60 .
 .SH SEE ALSO
 .BR ctime (3),
 .BR strftime (3),
diff --git a/man3type/va_list.3type b/man3type/va_list.3type
index 004860d5c..08b1abfdd 100644
--- a/man3type/va_list.3type
+++ b/man3type/va_list.3type
@@ -28,8 +28,9 @@ and
 .BR va_end (3)
 to traverse the list of arguments.
 .SH STANDARDS
-C99 and later;
-POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C89, POSIX.1-2001.
 .SH NOTES
 The following headers also provide
 .IR va_list :
diff --git a/man3type/void.3type b/man3type/void.3type
index ddcbf482f..c8a638a78 100644
--- a/man3type/void.3type
+++ b/man3type/void.3type
@@ -65,8 +65,9 @@ The POSIX requirement about compatibility between
 and function pointers was added in
 POSIX.1-2008 Technical Corrigendum 1 (2013).
 .SH STANDARDS
-C99 and later;
-POSIX.1-2001 and later.
+C11, POSIX.1-2008.
+.SH HISTORY
+C89, POSIX.1-2001.
 .SH SEE ALSO
 .BR malloc (3),
 .BR memcmp (3),