Re: on the irresponsibility of pursuing C language reform

[Alejandro Colomar <alx@kernel.org>]

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

Hi Joseph,

> Date: 2026-08-03 13:42:31+0000
> From: Joseph Myers <josmyers@redhat.com>
>
> On Sun, 2 Aug 2026, Alejandro Colomar wrote:
> 
> > Joseph was concerned that this documentation would conflict with many
> > documents saying that <memory.h> is deprecated.  Luckily, I've never
> > seen such a document, so we can assume they don't exist (unless people
> > show evidence).  I'll dismiss his negative vote, since his technical
> > reasons are incorrect.  Also, <memory.h> is undoubtedly more portable 
> > than a new <stdmem.h>.
> 
> The glibc manual nowhere mentions <memory.h>.  That's pretty clear 
> evidence the header is a relic of the days when glibc just took any 
> interface some 1980s Unix had rather than trying to have a cleaner API of 
> more current relevance.

I don't refute that.  But relics are sometimes useful and reusable.

> My main concern, in any case, is that man-pages should describe the world 
> as it is, not as you'd like it to be; they should follow, not lead, on any 
> proposed changes;

This has never been true.  I believe Michael did a great job maintaining
them, and that included promoting some APIs over others, even when that
goes against the standards.  See below.

> they should promote portable coding practices and using 
> existing standard interfaces in the absence of broad consensus (not just 
> your opinion; not just an opinion based on dismissing all the views 
> against) of a clear technical deficiency in those interfaces; that anyone 
> advocating for an interface change should avoid using man-pages as part of 
> that advocacy,

I'm not using the manual pages as part of advocating for an interface
change.  I'm advocating for an interface change as a consequence of the
research work I've done to improve the manual pages.

> only eventually updating it after the debate has concluded 
> once there is consensus on what the conclusion of the debate was but 
> ensuring the man-pages don't take any one side of the debate before then.

Would you mind expressing your feedback about the fact that str[n]cpy(3)
documented the non-standard strlcpy(3), and suggested that it'd be used
instead?  This is way before POSIX.1-2024 standardized it.  In fact,
POSIX.1-2008 had explicitly rejected these functions.

	commit bb96fc35a3b664ef3959eaefb095608846f89df7
	Author: Michael Kerrisk <mtk.manpages@gmail.com>
	Date:   2012-07-19 11:29:15 +0200

	    strcpy.3: NOTES: Add a discussion of strlcpy()
	    
	    Inspired by https://lwn.net/Articles/506530/
	    
	    Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

which introduced this text:

	$ MANWIDTH=64 diffman-git bb96fc35a3b664ef3959eaefb095608846f89df7
	--- bb96fc35a3b664ef3959eaefb095608846f89df7^:man3/strcpy.3
	+++ bb96fc35a3b664ef3959eaefb095608846f89df7:man3/strcpy.3
	@@ -54,6 +54,14 @@ NOTES
	      to test!)  that the size of dest is greater than the
	      length of src, then strcpy() can be used.
	 
	+     One valid (and intended) use of strncpy() is to copy a C
	+     string to a fixed‐length buffer while ensuring both that
	+     the buffer is not overflowed and that unused bytes in the
	+     target buffer are zeroed out (perhaps to prevent informa‐
	+     tion leaks if the buffer is to written to media or trans‐
	+     mitted to another process via an interprocess communica‐
	+     tion technique).
	+
	      If there is no terminating null byte in the first n bytes
	      of src, strncpy() produces an unterminated string in dest.
	      Programmers often prevent this mistake by forcing termina‐
	@@ -67,6 +75,27 @@ NOTES
	      formation contained in src is lost in the copying to
	      dest.)
	 
	+     Some systems (the BSDs, Solaris, and others) provide the
	+     following function:
	+
	+         size_t strlcpy(char *dest, const char *src, size_t
	+     size);
	+
	+     This function is similar to strncpy(), but it copies at
	+     most size-1 bytes to dest, always adds a terminating null
	+     byte, and does not pad the target with (further) null
	+     bytes.  This function fixes some of the problems of str‐
	+     cpy() and strncpy(), but the caller must still handle the
	+     possibility of data loss if size is too small.  The return
	+     value of the function is the length of src, which allows
	+     truncation to be easily detected: if the return value is
	+     greater than or equal to size, truncation occurred.  If
	+     loss of data matters, the caller must either check the ar‐
	+     guments before the call, or test the function return
	+     value.  strlcpy() is not present in glibc and is not stan‐
	+     dardized by POSIX, but is available on Linux via the
	+     libbsd library.
	+
	 BUGS
	      If the destination string of a strcpy() is not large
	      enough, then anything might happen.  Overflowing fixed‐
	@@ -82,4 +111,4 @@ SEE ALSO
	      bcopy(3), memccpy(3), memcpy(3), memmove(3), stpcpy(3),
	      stpncpy(3), strdup(3), string(3), wcscpy(3), wcsncpy(3)
	 
	-GNU                        2012‐07‐18                 STRCPY(3)
	+GNU                        2012‐07‐19                 STRCPY(3)

That commit was itself based on the LWN article it metions in the commit
message, and it contained a number of comments
<https://lwn.net/Articles/507319/#Comments> that cautioned that
strlcpy/cat(3) might not be the best interface, and I'd say there wasn't
consensus either back then.  There will never be consensus on this
topic, I believe.

Yet, some things have to be done.  Mistakes may be made when doing this,
and they should be eventually addressed.  But manual pages should not be
a copy of the standards.

If we go back further in time, man-pages-1.0 --the very first release,
in 1993-- already documented that gets(3) should never be used.  This
was certainly to the contrary of the existing standards, and indeed was
leading the removal that came later.  That page was written by
Thomas Koenig.  I don't think Thomas was wrong doing that.

Past times often feel better, but that's nostalgia, and often not based
on facts.

> I suggest we need to figure out how to generate man pages from the glibc 
> manual so that people who prefer documentation in that format can have 
> documentation of glibc interfaces that's maintained by a proper consensual 
> process rather than following one person's opinion.

The Linux manual pages are not strictly the glibc manual.  They also
document musl, for example.  Also, I believe it's good that it's
independent of glibc and GNU.  That puts a degree of criticism that is
necessary for avoiding endogamy.  Let's say it's a separation of powers.


Have a lovely day!
Alex

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

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