Re: [PATCH v1 00/15] man/man3type/*: Update history of types A-INTN

[Alejandro Colomar <alx@kernel.org>]

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

Hi Seth,

On Tue, Jan 06, 2026 at 05:07:49PM +1000, Seth McDonald wrote:
> Hello again!
> 
> My next few patch sets should update datatypes in the 3type section.
> There are 48 patches total for this section, though I will be
> partitioning them into three separate sets according to alphabetical
> order.  This is primarily based on Linux's documentation recommending
> patch sets of at most ~15 patches.[1]  But if this mailing list has
> different preferences, let me know and I'll adjust accordingly.

We have no bounds on the size of patch sets.  On the other hand, it may
be good for you not sending a lot of patches that will be rejected due
to some small detail, so you may choose to self-restrict to some size.
As far as I'm concerned, you could send the 48 patches just fine.

> This patch set regards types whose identifiers start with A-INTN (case
> insensitive, of course).
> 
> Regarding the order of the listed standards in HISTORY sections, I've
> seen man pages with the same set of standards listed in different
> orders.  But I have found a general ordering that a good number of pages
> adhere to.  That being:
> 
> SVrX, X.XBSD, SUSvX, POSIX.1-YYYY, POSIX.2, Linux X.X, glibc X.X[.X],
> others (e.g. OpenBSD, Solaris, AIX).

I think it would be better to use chronologic order.  I leave it up to
you if you want to keep the patches as they are, and (optionally)
improve the order afterwards, or fix the patches to use chronologic
order.  Since, as you say, there's no existing consistency, I'll accept
the patches in any order; just let me know what you prefer.

> I call this a 'general' ordering because very rarely (if ever) are all
> seven standards/systems listed (excluding 'others').  But subsets of
> them tend to follow their relative ordering above, at least from what
> I've seen.  So for consistency, I tended to use this ordering when
> adding/updating standards.  That is, listing SUS and POSIX.1 after SV
> and BSD, and before Linux, glibc, and other systems.
> 
> I also followed a few more guidelines when editing these lists that may
> be noteworthy:
> - Since POSIX and SUS merged into the same document in POSIX.1-2001/
>   SUSv3, only POSIX.1-2001 is listed for functions in these standards
>   (or later), but with XSI appended if the function was part of the XSI
>   extension (e.g. POSIX.1-2008 XSI).

LGTM

> - Since SUSv1 is aligned with POSIX.1-1990,[2] if a function's first
>   POSIX appearance was in POSIX.1-1988 or POSIX.1-1990, then it's first
>   appearance in SUSv1 is not also listed due to being implied by its
>   POSIX appearance.

This should be documented in standards(7).

> - Similarly, since SUSv2 is aligned with POSIX.1-1996,[3] the same is
>   true for functions first appearing in POSIX.1-1996 and SUSv2.

This should be documented in standards(7).

> So in general, SUS is listed if the function (or constant/type) appeared
> in SUSv1 or SUSv2 before it appeared in POSIX.1.

LGTM.

> [1] <https://www.kernel.org/doc/Documentation/process/submitting-patches.rst>
> [2] X/Open CAE Specification, System Interfaces and Headers Issue 4,
> Version 2, Chapter 1.6 "Relationship to Formal Standards", p. 10.

Do you have a link?

> [3] CAE Specification, System Interfaces and Headers, Issue 5, Chapter
> 1.6 "Relationship to Formal Standards", p. 11.

Do you have a link?

> Seth McDonald (15):
>   man/man3type/aiocb.3type: HISTORY: Update first POSIX appearance of
>     aiocb(3type)
>   man/man3type/blk{cnt,size}_t.3type: HISTORY: Update first SUS
>     appearance of blk{cnt,size}_t(3type)
>   man/man3type/cc_t.3type: HISTORY: Update first POSIX appearance of
>     types
>   man/man3type/clockid_t.3type: HISTORY: Update first POSIX appearance
>     of clockid_t(3type)
>   man/man3type/clock_t.3type: HISTORY: Update first POSIX appearance of
>     clock_t(3type)
>   man/man3type/dev_t.3type: HISTORY: Update first POSIX appearance of
>     dev_t(3type)
>   man/man3type/div_t.3type: HISTORY: Split [l]div_t(3type) and
>     {ll,imax}div_t(3type)
>   man/man3type/div_t.3type: HISTORY: Update first SUS appearance of
>     [l]div_t(3type)
>   man/man3type/FILE.3type: HISTORY: Update first POSIX appearance of
>     FILE(3type)
>   man/man3type/id_t.3type: HISTORY: Split id_t(3type) from
>     [pug]id_t(3type)
>   man/man3type/id_t.3type: HISTORY: Update first POSIX appearance of
>     [pug]id_t(3type)
>   man/man3type/id_t.3type: HISTORY: Mention change in datatypes of
>     [pug]id_t(3type)
>   man/man3type/id_t.3type: HISTORY: Update first POSIX appearance of
>     id_t(3type)
>   man/man3type/intN_t.3type: HISTORY: Split types and macros
>   man/man3type/intN_t.3type: HISTORY: Update first SUS appearance of
>     [u]intN_t(3type)

I'll ignore all of these patches for now, waiting for your feedback.


Have a lovely day!
Alex

> 
>  man/man3type/FILE.3type      |  3 ++-
>  man/man3type/aiocb.3type     |  2 +-
>  man/man3type/blkcnt_t.3type  |  1 +
>  man/man3type/blksize_t.3type |  1 +
>  man/man3type/cc_t.3type      |  2 +-
>  man/man3type/clock_t.3type   |  3 ++-
>  man/man3type/clockid_t.3type |  2 +-
>  man/man3type/dev_t.3type     |  2 +-
>  man/man3type/div_t.3type     | 11 +++++++++++
>  man/man3type/id_t.3type      | 22 +++++++++++++++++++++-
>  man/man3type/intN_t.3type    | 20 ++++++++++++++++++++
>  11 files changed, 62 insertions(+), 7 deletions(-)
> 
> Range-diff against v0:
>  -:  ------------ >  1:  9d2453196924 man/man3type/aiocb.3type: HISTORY: Update first POSIX appearance of aiocb(3type)
>  -:  ------------ >  2:  3e3cdf605fad man/man3type/blk{cnt,size}_t.3type: HISTORY: Update first SUS appearance of blk{cnt,size}_t(3type)
>  -:  ------------ >  3:  eb523868fce1 man/man3type/cc_t.3type: HISTORY: Update first POSIX appearance of types
>  -:  ------------ >  4:  75786342c4cc man/man3type/clockid_t.3type: HISTORY: Update first POSIX appearance of clockid_t(3type)
>  -:  ------------ >  5:  24395294f63b man/man3type/clock_t.3type: HISTORY: Update first POSIX appearance of clock_t(3type)
>  -:  ------------ >  6:  2bb3f33e65b7 man/man3type/dev_t.3type: HISTORY: Update first POSIX appearance of dev_t(3type)
>  -:  ------------ >  7:  417e53f6394a man/man3type/div_t.3type: HISTORY: Split [l]div_t(3type) and {ll,imax}div_t(3type)
>  -:  ------------ >  8:  feb8d662b9fe man/man3type/div_t.3type: HISTORY: Update first SUS appearance of [l]div_t(3type)
>  -:  ------------ >  9:  77b4c360910f man/man3type/FILE.3type: HISTORY: Update first POSIX appearance of FILE(3type)
>  -:  ------------ > 10:  18896b1be985 man/man3type/id_t.3type: HISTORY: Split id_t(3type) from [pug]id_t(3type)
>  -:  ------------ > 11:  d32b6148d2a9 man/man3type/id_t.3type: HISTORY: Update first POSIX appearance of [pug]id_t(3type)
>  -:  ------------ > 12:  00eec0f9aa43 man/man3type/id_t.3type: HISTORY: Mention change in datatypes of [pug]id_t(3type)
>  -:  ------------ > 13:  e5992856df9c man/man3type/id_t.3type: HISTORY: Update first POSIX appearance of id_t(3type)
>  -:  ------------ > 14:  903b6a6dee42 man/man3type/intN_t.3type: HISTORY: Split types and macros
>  -:  ------------ > 15:  43f013547fbe man/man3type/intN_t.3type: HISTORY: Update first SUS appearance of [u]intN_t(3type)
> -- 
> 2.47.3
> 

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

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