Re: proposed revision to memory.h(3head)

[Alejandro Colomar <alx@kernel.org>]

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

Hi Mark,

> Date: 2026-08-03 13:14:35-0700
> From: Mark Harris <mark.hsj@gmail.com>
>
> Alejandro Colomar wrote:
> >         SYNOPSIS
> >              #include <memory.h>  // See STANDARDS
> 
> intro(3) implies that the SYNOPSIS section intends to reflect the
> function's API; i.e., the interface that it has agreed to provide to
> applications.  Do you disagree?
> 
> If strndup(3)'s SYNOPSIS stated "int" instead of "size_t" for the
> second argument, it may work fine in many cases but that is not the
> API that it has agreed to provide so it is inaccurate.  Similarly if
> it states "memory.h" instead of "string.h", even if it happens to work
> on some systems, that is not the API it has agreed to provide so it is
> inaccurate.  If memory.h ceases to provide a usable declaration for
> strndup(), that is the problem of the person that relied on the
> inaccurate information because there was never any agreement to
> provide a usable declaration of strndup() in memory.h; they should
> have used a reliable source to determine the API that is actually
> supported.  I am having trouble figuring out where you disagree with
> this seemingly-straightforward logic.

There are already pages where we can't even consider a unified
interface.  Let's consider the case of ttyslot(3), once part of SUSv1,
then obsoleted in SUSv2, and then removed in POSIX.1-2001, but still
provided by the usual systems.

The SYNOPSIS says:

	SYNOPSIS
	     #include <unistd.h>       /* See NOTES */

	     int ttyslot(void);

	 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
		...

But then, of course, the actual #include is a real mess.

Funnily, there's no NOTES section, because I moved their contents to
more specific sections some years ago (we were never happy about the
NOTES section being so generic, and so I eventually put some order
there, but of course, some parts weren't perfectly moved).

Okay, let's ignore the fact that there's no NOTES, and assume the
comment meant to say 'See HISTORY'.  Here's what HISTORY has to say
about the #include's for this function:

	     The glibc2 implementation of this function reads the  file
	     _PATH_TTYS,  defined in <ttyent.h> as "/etc/ttys".  It re‐
	     turns 0 on error.  Since Linux systems do not usually have
	     "/etc/ttys", it will always return 0.

	     On BSD‐like systems and Linux, the  declaration  of  ttys‐
	     lot()  is  provided  by <unistd.h>.  On System V‐like sys‐
	     tems, the declaration is provided  by  <stdlib.h>.   Since
	     glibc  2.24, <stdlib.h> also provides the declaration with
	     the following feature test macro definitions:

		 (_XOPEN_SOURCE >= 500 ||
			 (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED))
		     && ! (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)

SYNOPSIS is kind of a TL;DR.  In some cases, what it says is all there
is.  In other cases, there's a lot of details.  When there are details,
tradition is that the SYNOPSIS at least hints that the user should
continue reading somewhere.

In the more than thousand pages we have, you can find counter-examples
for almost everything you could expect from a manual page.


Have a lovely night!
Alex

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

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