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

Alejandro Colomar wrote:
>
> Hi Mark,
>
> > Date: 2026-08-03 13:14:35-0700
> > From: Mark Harris <[email protected]>
> >
> > 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_macr=
os(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=E2=
=80=90
>              turns 0 on error.  Since Linux systems do not usually have
>              "/etc/ttys", it will always return 0.
>
>              On BSD=E2=80=90like systems and Linux, the  declaration  of =
 ttys=E2=80=90
>              lot()  is  provided  by <unistd.h>.  On System V=E2=80=90lik=
e sys=E2=80=90
>              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 >=3D 500 ||
>                          (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED))
>                      && ! (_POSIX_C_SOURCE >=3D 200112L || _XOPEN_SOURCE =
>=3D 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.

I wasn't asking about your comment "// See STANDARDS".  I understand
that you had more to share that was too long for the SYNOPSIS section,
so you added the comment.  I was asking about why you wrote an
inaccurate include directive in the SYNOPSIS section that does not
reflect the supported API of any implementation.  Even after reading
the STANDARDS section, the implication is that the supported API is
memory.h, but POSIX says it should be string.h.  However, even if you
had your own libc implementation, it would be inaccurate to claim that
the supported API is memory.h for any more than your own libc; you
obviously cannot unilaterally change the supported API for
implementations supported by other groups.


 - Mark