Re: [PATCH 1/2] man/man3/{mem,strn}*(): SYNOPSIS, STANDARDS: Document these as provided by <memory.h>

[Alejandro Colomar <alx@kernel.org>]

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

Hi Sam,

> Date: 2026-07-31 22:54:27+0100
> From: Sam James <sam@gentoo.org>
>
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > Hi Joseph,
> >
> >> Date: 2026-07-31 21:23:35+0000
> >> From: Joseph Myers <josmyers@redhat.com>
> >>
> >> I think it's irresponsible to use the man-pages project to promote 
> >> personal idiosyncratic ideas like this in preference to what's been the 
> >> standard location of functions since 1989.
> >> 
> >> I'd rather we add a mandatory deprecation warning to memory.h in glibc.
> >
> > I hope you don't; it'd be a gratuitous breaking change.
> >
> 
> Yet this change has the same effect, just people will see it themselves
> rather than the compiler telling them, and go around sending patches to
> change it.

IME, people don't go changing includes unless they need something it's
not available in the already-included header files.

Analysis of includes is quite complex, and there are tools for that
--iwyu(1)--.  As long as those tools don't start complaining --and they
won't-- [1], I find it quite unlikely that people will start changing
includes in existing code.

This is rather something that will affect new code (new source files).

[1]	iwyu(1) works in a way that it allows a number of headers to
	provide a symbol.  If no header provides the symbol, then it
	will recommend the best header for it; but if a header that
	provides the symbol is already there, it won't complain.

> The man pages should reflect what the standard currently says, not what
> you'd like it to say.

Not exactly; the standard is a good guideline, but sometimes it's off.
We have vendor extensions, which are well documented, and when the
standard is bogus, the extensions take over the page.

FWIW, the information from the standard is still there.

	$ MANWIDTH=64 mansectf STANDARDS man3/memcpy.3 | cat
	memcpy(3)           Library Functions Manual          memcpy(3)

	STANDARDS
	     C11, POSIX.1‐2008.

	     ISO C and POSIX declare this function in <string.h>.

	Linux man‐pages (unreleased) (date)                   memcpy(3)

I've just removed it from the front of the page (SYNOPSIS), but it's
still there, because of course, we must document the standard alongside
the extension.

> We had the same problem with e.g. stripping "C89"
> everywhere.

Sorry for that one; it was a useful change, though.  Now we have better
manual pages than we had back then, regarding standards.  I hope you
realize about that.  It triggered discussion, and a careful review of
the text, which resulted in a good change after all.

> People want it to reflect what the standard says.

And it still does.


Have a lovely night!
Alex

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

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