Early POSIX versions seldom included in history sections

Early POSIX versions seldom included in history sections

[Seth McDonald]

[-- Attachment #1.1: Type: text/plain, Size: 1505 bytes --]

Hello again!

I've noticed that in almost all man pages for POSIX functions, the
history section documents only as far back as POSIX.1-2001, even when
the function appeared in prior POSIX versions. For example, the man
pages for close(2), read(2), and malloc(3) all list POSIX.1-2001 as the
functions' first appearance in POSIX, when all three were included in
POSIX.1-1988 (though read(2) got its current function signature in
POSIX.1-1990).

But there are a few man pages that do actually go further back. By
grep-ing the repo with

$ grep -E -nr -e 'POSIX.1-19[0-9]{2}' man

I get 28 matches, some of which are from functions' history sections,
such as in the abs(3) and ctime(3) man pages. Which makes me think that
either the history sections were intended to start at POSIX.1-2001 and
these few exceptions were unintended/overlooked. Or the exact version of
POSIX that most functions were introduced in was not known, while
POSIX.1-2001 was freely available online as html to check.

If the reason is the latter, then I'd be happy to help here. I have
access to POSIX.1-1988, POSIX.1-1990, and POSIX.1-1996, as well as SUS
(1994) and SUSv2 (1997). So I can check each function and update their
man page's history section with an earlier POSIX (or SUS) version if
applicable. Though only if that's desirable for the man pages, of
course; let me know if so.

----
Seth McDonald.
sethmcmail at pm dot me (mailing lists)
2336 E8D2 FEB1 5300 692C  62A9 5839 6AD8 9243 D369

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 343 bytes --]

Re: Early POSIX versions seldom included in history sections

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2039 bytes --]

On Sat, Dec 20, 2025 at 04:17:44PM +0000, Seth McDonald wrote:
> Hello again!

Hi Seth!

> I've noticed that in almost all man pages for POSIX functions, the
> history section documents only as far back as POSIX.1-2001, even when
> the function appeared in prior POSIX versions. For example, the man
> pages for close(2), read(2), and malloc(3) all list POSIX.1-2001 as the
> functions' first appearance in POSIX, when all three were included in
> POSIX.1-1988 (though read(2) got its current function signature in
> POSIX.1-1990).
> 
> But there are a few man pages that do actually go further back. By
> grep-ing the repo with
> 
> $ grep -E -nr -e 'POSIX.1-19[0-9]{2}' man
> 
> I get 28 matches, some of which are from functions' history sections,
> such as in the abs(3) and ctime(3) man pages. Which makes me think that
> either the history sections were intended to start at POSIX.1-2001 and
> these few exceptions were unintended/overlooked. Or the exact version of
> POSIX that most functions were introduced in was not known, while
> POSIX.1-2001 was freely available online as html to check.

It's the latter.  In the cases where we know old details, we've
documented them.  Otherwise, we've checked the standards that are easily
available (i.e., POSIX.1-2001 and later), and if we learn some API was
older, we can always go back and document it.

> If the reason is the latter, then I'd be happy to help here. I have
> access to POSIX.1-1988, POSIX.1-1990, and POSIX.1-1996, as well as SUS
> (1994) and SUSv2 (1997). So I can check each function and update their
> man page's history section with an earlier POSIX (or SUS) version if
> applicable. Though only if that's desirable for the man pages, of
> course; let me know if so.

Yup!  Thanks a lot!  That would be helpful.  :)


Have a lovely night!
Alex

> 
> ----
> Seth McDonald.
> sethmcmail at pm dot me (mailing lists)
> 2336 E8D2 FEB1 5300 692C  62A9 5839 6AD8 9243 D369




-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Early POSIX versions seldom included in history sections

[Seth McDonald]

[-- Attachment #1.1: Type: text/plain, Size: 1707 bytes --]

On Sunday, 21 December 2025 at 03:44, Alejandro Colomar <alx@kernel.org> wrote:
> On Sat, Dec 20, 2025 at 04:17:44PM +0000, Seth McDonald wrote:
[...]
> > If the reason is the latter, then I'd be happy to help here. I have
> > access to POSIX.1-1988, POSIX.1-1990, and POSIX.1-1996, as well as SUS
> > (1994) and SUSv2 (1997). So I can check each function and update their
> > man page's history section with an earlier POSIX (or SUS) version if
> > applicable. Though only if that's desirable for the man pages, of
> > course; let me know if so.
> 

> Yup! Thanks a lot! That would be helpful. :)

Cool! So just to ensure that I conform to the man pages' preferences/
standards, I want to ask a few things about documenting POSIX and SUS.

POSIX and SUS converged to the same document in POSIX.1-2001/SUSv3. So
if, for example, a function was first introduced in SUSv2 and then first
appeared in a POSIX standard in POSIX.1-2001, should its history section
include SUSv2, POSIX.1-2001, or both?

Suppose instead a function was first introduced in SUSv2, included in
POSIX.1-2001 as an XSI extension, then in POSIX.1-2008 it was moved to
Base. Should its history section include POSIX.1-2001 or POSIX.1-2008 as
its first POSIX appearance (since XSI is SUS)?

Suppose a function appeared in POSIX.1-1988, but its function signature
then was different (e.g., returning 'int' instead of 'ssize_t', or
taking 'char*' instead of 'const char*'). And it only got its current
signature in POSIX.1-1990. Should its history section include
POSIX.1-1988 or POSIX.1-1990?

----
Seth McDonald.
sethmcmail at pm dot me (mailing lists)
2336 E8D2 FEB1 5300 692C  62A9 5839 6AD8 9243 D369

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 343 bytes --]

Re: Early POSIX versions seldom included in history sections

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2104 bytes --]

Hi Seth,

On Sun, Dec 21, 2025 at 08:17:07AM +0000, Seth McDonald wrote:
> On Sunday, 21 December 2025 at 03:44, Alejandro Colomar <alx@kernel.org> wrote:
> > On Sat, Dec 20, 2025 at 04:17:44PM +0000, Seth McDonald wrote:
> [...]
> > > If the reason is the latter, then I'd be happy to help here. I have
> > > access to POSIX.1-1988, POSIX.1-1990, and POSIX.1-1996, as well as SUS
> > > (1994) and SUSv2 (1997). So I can check each function and update their
> > > man page's history section with an earlier POSIX (or SUS) version if
> > > applicable. Though only if that's desirable for the man pages, of
> > > course; let me know if so.
> > 
> 
> > Yup! Thanks a lot! That would be helpful. :)
> 
> Cool! So just to ensure that I conform to the man pages' preferences/
> standards, I want to ask a few things about documenting POSIX and SUS.
> 
> POSIX and SUS converged to the same document in POSIX.1-2001/SUSv3. So
> if, for example, a function was first introduced in SUSv2 and then first
> appeared in a POSIX standard in POSIX.1-2001, should its history section
> include SUSv2, POSIX.1-2001, or both?

Both.

And for any similar questions, when in doubt, more information is
better.

> Suppose instead a function was first introduced in SUSv2, included in
> POSIX.1-2001 as an XSI extension, then in POSIX.1-2008 it was moved to
> Base. Should its history section include POSIX.1-2001 or POSIX.1-2008 as
> its first POSIX appearance (since XSI is SUS)?

I think you could do this:

SUSv2.
POSIX.1-2001 (XSI).
POSIX.1-2008.

> Suppose a function appeared in POSIX.1-1988, but its function signature
> then was different (e.g., returning 'int' instead of 'ssize_t', or
> taking 'char*' instead of 'const char*'). And it only got its current
> signature in POSIX.1-1990. Should its history section include
> POSIX.1-1988 or POSIX.1-1990?

I'd include both, and then include a paragraph clarifying that in
certain standards it had a different prototype (and show the prototype).


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Early POSIX versions seldom included in history sections

[Collin Funk]

[-- Attachment #1: Type: text/plain, Size: 848 bytes --]

Hi Seth and Alex,

Alejandro Colomar <alx@kernel.org> writes:

>> Suppose instead a function was first introduced in SUSv2, included in
>> POSIX.1-2001 as an XSI extension, then in POSIX.1-2008 it was moved to
>> Base. Should its history section include POSIX.1-2001 or POSIX.1-2008 as
>> its first POSIX appearance (since XSI is SUS)?
>
> I think you could do this:
>
> SUSv2.
> POSIX.1-2001 (XSI).
> POSIX.1-2008.

Just want to mention that I find all of these document names confusing.
Maybe because some of them predate me, or predate me using a computer, I
do not know.

Therefore, I thought I should mention the names are described in
standards(7) along with the full documents they correspond to. I would
stick to the names listed there for consistency. That is what I have
done when making changes to the glibc and gnulib manuals.

Collin


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Early POSIX versions seldom included in history sections

[Seth McDonald]

[-- Attachment #1.1: Type: text/plain, Size: 2669 bytes --]

G'day Collin,

On Monday, 22 December 2025 at 10:58, Collin Funk <collin.funk1@gmail.com> wrote:
> Hi Seth and Alex,
> 

> Alejandro Colomar alx@kernel.org writes:
> 

> > > Suppose instead a function was first introduced in SUSv2, included in
> > > POSIX.1-2001 as an XSI extension, then in POSIX.1-2008 it was moved to
> > > Base. Should its history section include POSIX.1-2001 or POSIX.1-2008 as
> > > its first POSIX appearance (since XSI is SUS)?
> > 

> > I think you could do this:
> > 

> > SUSv2.
> > POSIX.1-2001 (XSI).
> > POSIX.1-2008.
> 

> 

> Just want to mention that I find all of these document names confusing.
> Maybe because some of them predate me, or predate me using a computer, I
> do not know.
> 

> Therefore, I thought I should mention the names are described in
> standards(7) along with the full documents they correspond to. I would
> stick to the names listed there for consistency. That is what I have
> done when making changes to the glibc and gnulib manuals.
> 

> Collin

I do believe the standards(7) man page does describe these standards,
including XSI. From the POSIX.1-2001/SUSv3 section:

'The standard defines two levels of conformance: POSIX conformance,
which is a baseline set of interfaces required of a conforming system;
and XSI Conformance, which additionally mandates a set of interfaces
(the "XSI extension") which are only optional for POSIX conformance.
XSI-conformant systems can be branded UNIX 03.'

That said, I can certainly understand how just listing a bunch of
acronyms and numbers (SUSv2, POSIX.1-2001 XSI, POSIX.1-2008) would be
confusing for many not familiar with these standards. I can briefly
describe such a function's progression through the standards with a
short paragraph, if that would help. Using the function fchdir(2) as an
example, let me know how this sounds:

HISTORY
       fchdir()
              SUSv1, POSIX.1-2001.

   SUSv1
       fchdir(2)  was first introduced in SUSv1.  The function was then
       included in POSIX.1-2001, but as an XSI extension.   Finally  in
       POSIX.1-2008, it was moved to the base specification.

By the way, I too find these documents confusing as hell! I only have a
grasp of them because I happened study them due to a recent
hyperfixation on portable standards (my autism be like). So I certainly
get where you're coming from here. I just don't know how much more I can
describe in the added paragraph before intruding on the job of the
standards(7) man page.

----
Seth McDonald.
sethmcmail at pm dot me (mailing lists)
2336 E8D2 FEB1 5300 692C  62A9 5839 6AD8 9243 D369

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 343 bytes --]

Re: Early POSIX versions seldom included in history sections

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2183 bytes --]

Hi Seth,

On Tue, Dec 23, 2025 at 03:56:23AM +0000, Seth McDonald wrote:
> > > SUSv2.
> > > POSIX.1-2001 (XSI).
> > > POSIX.1-2008.
> 
> I do believe the standards(7) man page does describe these standards,
> including XSI. From the POSIX.1-2001/SUSv3 section:
> 
> 'The standard defines two levels of conformance: POSIX conformance,
> which is a baseline set of interfaces required of a conforming system;
> and XSI Conformance, which additionally mandates a set of interfaces
> (the "XSI extension") which are only optional for POSIX conformance.
> XSI-conformant systems can be branded UNIX 03.'
> 
> That said, I can certainly understand how just listing a bunch of
> acronyms and numbers (SUSv2, POSIX.1-2001 XSI, POSIX.1-2008) would be
> confusing for many not familiar with these standards. I can briefly
> describe such a function's progression through the standards with a
> short paragraph, if that would help. Using the function fchdir(2) as an
> example, let me know how this sounds:
> 
> HISTORY
>        fchdir()
>               SUSv1, POSIX.1-2001.

I'd make this

		SUSv1, POSIX.1-2001 XSI, POSIX.1-2008.

> 
>    SUSv1
>        fchdir(2)  was first introduced in SUSv1.  The function was then
>        included in POSIX.1-2001, but as an XSI extension.   Finally  in
>        POSIX.1-2008, it was moved to the base specification.

I tend to dislike paragraphs.  This would be interesting for the commit
message.  As you say, all of these names are documented in standards(7),
and I think the above should be readable once you know standards(7).

> 
> By the way, I too find these documents confusing as hell! I only have a
> grasp of them because I happened study them due to a recent
> hyperfixation on portable standards (my autism be like). So I certainly
> get where you're coming from here. I just don't know how much more I can
> describe in the added paragraph before intruding on the job of the
> standards(7) man page.

Agree!  It took me some years to know the standards' history (and
I still have some gaps in the older ones).  :)


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]