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

--o3bks3oxj25plxii
Content-Type: text/plain; protected-headers=v1; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
From: Alejandro Colomar <[email protected]>
To: Bruno Haible <[email protected]>
Cc: [email protected], Sam James <[email protected]>, 
	"G. Branden Robinson" <[email protected]>, Joseph Myers <[email protected]>, 
	Keith Bostic <[email protected]>, Mark Harris <[email protected]>, 
	Nevin Liber <[email protected]>, Collin Funk <[email protected]>, 
	JeanHeyd Meneide <[email protected]>, Christopher Bazley <[email protected]>, 
	Serge Hallyn <[email protected]>, Iker Pedrosa <[email protected]>, Evgeny Grin <[email protected]>, 
	Kees Cook <[email protected]>, bug-gnulib-mXXj517/[email protected], libc-alpha-9JcytcrH/[email protected]
Subject: Re: [PATCH v2] man/man3/mem*(): SYNOPSIS: Document non-standard
 mem*() functions as provided by <memory.h>
Message-ID: <am56ZBzNM5J07AUa@devuan>
References: <[email protected]>
 <3556566.BddDVKsqQX@cagnes>
 <am50AM0bdufHa9W3@devuan>
 <15288158.RDIVbhacDa@cagnes>
MIME-Version: 1.0
In-Reply-To: <15288158.RDIVbhacDa@cagnes>

Hi Bruno,

> Date: 2026-08-02 00:55:46+0200
> From: Bruno Haible <[email protected]>
>
[...]
> > Which means that <string.h> is still a valid provider of memcpy(3), and
> > thus absolutely no existing code breaks.
>=20
> Still, for the next 10 years, C programmers would debate whether they sho=
uld
> #include <string.h> or #include <memory.h>. Different C programmers in the
> same team will have different personal opinions. Thus, programmer team le=
ads
> 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.
>=20
> > > And, of course, for man page changes, consider the authoritative sour=
ce.
> > > For example, memfrob() exists only in glibc [2], therefore its author=
itative
> > > documentation is in the glibc manual [3], and it says "It is declared=
 in
> > > string.h." The man pages MUST say the same thing.
> >=20
> > 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.
>=20
> 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 th=
an
> the authoritative source.

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

> Bruno


Cheers,
Alex

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

--o3bks3oxj25plxii
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEES7Jt9u9GbmlWADAi64mZXMKQwqkFAmpufNQACgkQ64mZXMKQ
wqnO6Q/+JcNAwkwO1RUrLetJApHKj8yMx77iqYI/j+I82j4Leze3rH5NVXKBT9Ay
TzwKn2MetoxEfpj5sniCdhzJvUFx9LqfauRwxHsSZxdv26gpov5In7icc/Zh1TLf
Julfkgj1cOG187knEbzcnrXjza8tn8W0g6llrhW8lJrQk/U9zwlnZ7UnMiKu9Uul
bYsvUr+DckY7R833WOL7nfj0r4+ExgluiTLel4b3aC9+PYFr6+fs6/Ech6Mqh0Gv
OKdl8nou947dMnipA/wPmT+xjLe3lEy7iLKENl7Xnr1sfcSJ3+UtDkatoj9AEjyr
YAFswshWWnNSIzjFD0CD2kX1glmPN2yGqnCjR1tWMaWKvjrXDhLa3SLaj5Qm8w6q
AFUXdOCkCz84svPUlfwLDAN9yrsoUjiVMD1IJBL8Xfo9NZHik1018lq0QaoK6DvM
FjsHwbiss0qs6raPW6PemnyV3h7ayBnhYeFuTzrGwDSSrrkK+ixvSw417CpzX5LA
l/JqOmwCu+zWWyWVkmxbOaEvuuOxq9vD0Ta7tuypw8LIuX7rQkA5AgsLxfBvE+6E
6mfThecvmLyHqhfK8hDkwe5HTBDbdSHLUCVvoxHgof7O2kSN6cn91OpzSv/jXAPT
zP3dLCIIctuIMBhYTXsnkqe3+u2tgi8ufjuLpYR04hoMrfB6bE0=
=6LVP
-----END PGP SIGNATURE-----

--o3bks3oxj25plxii--