Re: [PATCH v2] man/man3/mem*(): SYNOPSIS: Document non-standard mem*() functions as provided by <memory.h>

[Alejandro Colomar <alx@kernel.org>]

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

Hi Bruno,

> Date: 2026-08-02 00:55:46+0200
> From: Bruno Haible <bruno@clisp.org>
>
[...]
> > Which means that <string.h> is still a valid provider of memcpy(3), and
> > thus absolutely no existing code breaks.
> 
> Still, for the next 10 years, C programmers would debate whether they should
> #include <string.h> or #include <memory.h>. Different C programmers in the
> same team will have different personal opinions. Thus, programmer team leads
> will have to establish coding styles/guidelines which say which header to
> include in this case.

I find that an acceptable result.  #include's aren't that important.
When reading code, the section of #include's is unimportant as long as
it works.

I don't expect existing code to change, so this is a matter of what will
happen in new files, or when a file is changed to newly use such a
function.

Among the stylistic discussions that can happen, this is the least of
our concerns.  Also, if this triggers a discussion of _why_ this
changed, we might have achieved something.

> This is one of the challenges of language design: Each time the language
> offers several nearly equivalent ways of doing the same thing, different
> coding styles and the need for team guidelines are the consequence.
> C++ is particularly affected by this; Go hardly. Pushing C to become
> like C++, in this respect, would not be a good move.

We have precedent in <stdint.h> and <inttypes.h>.  The world hasn't
fallen over our heads so far.  :)

Actually, <stdint.h> is just the tip of the ideberg.  size_t is provided
by 27 headers, if I counted well.  And there's plenty of such examples.
Another curious one is that there's something that's specified by ISO C
to be defined in <time.h>, and by POSIX to be defined by <sys/time.h>.
I don't remember what it was, but it was funny when I found out.

I've been involved for a few years in iwyu(1), contributing code for
dealing with the standard includes from libc, and while we had our share
of discussion of which headers are preferred for each symbol (we're some
pedants, of course), I've never heard that such discussions reached the
general public.  The general public just wants a tool that says which
are the right headers, and go with it.

> The cost of adoption for this proposal is thus still big.
> 
> > > And, of course, for man page changes, consider the authoritative source.
> > > For example, memfrob() exists only in glibc [2], therefore its authoritative
> > > documentation is in the glibc manual [3], and it says "It is declared in
> > > string.h." The man pages MUST say the same thing.
> > 
> > Yes, in v3 (which I'll send soon), they'll say the same thing.  That is,
> > all the functions --standard or not-- will have text clarifying that the
> > functions are also provided in <string.h>.  This covers what glibc says.
> > What goes in the SYNOPSIS is something I'll diverge from glibc, but
> > that's fair game.
> 
> I don't agree with you that it's "fair game". The SYNOPSIS is the first
> eye-catcher, often the only part that a programmer reads. It would be a
> disgrace if the man page, in the SYNOPSIS, mentions a different header than
> the authoritative source.

Some would question the fact that the glibc manual is the authoritative
source for glibc documentation.  :)

> Bruno


Cheers,
Alex

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

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