Re: The goal of the Linux man-pages project

[Alejandro Colomar <alx@kernel.org>]

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

Hi Arsen,

> Date: 2026-08-05 11:31:11+0200
> From: Arsen Arsenović <arsen@aarsen.me>
>
> Hi Alex,
> 
> Alejandro Colomar <alx@kernel.org> writes:
> 
> >> >     man/man3/: Put first <string.h> in SYNOPSIS, then comment about <memory.h>
> >> >     
> >> >     This is a compromise between the fact that <string.h> is the standard
> >> >     header and (only slightly) most portable header file for these
> >> >     functions, while hinting at the fact that it might be more appropriate
> >> >     to use <memory.h> where possible.
> >> >     
> >> >     Remove the STANDARDS and NOTES about this, since now the SYNOPSIS
> >> >     contains all the necessary information.  The extra info is in
> >> >     memory.h(3head), which is linked to in the SYNOPSIS.
> >> >
> >> > What do you think?
> >> 
> >> Why, though?
> >
> > To help guide programmers to understand these APIs, and consequentially
> > be able to write better code.  That's the goal of this project.  It's
> > the Linux Programmer's Manual, and its purpose is that programmers on
> > a Linux system are able to write correct programs.
> 
> First of, this doesn't answer the question I asked.  Why should this
> change, even the "compromise", be done?
> 
> But, ignoring that this doesn't answer the question posed, how exactly
> is hinting that it's "more appropriate to use <memory.h> where possible"
> accomplishing the goals of the project you've stated there?
> 
> It seems to me to just sow confusion.
> 
> I think the references to <memory.h> should be confined to a single page
> that documents what it is, memory.h(3head) or whatever, which should be
> honest and say only:
> 
>   <memory.h> is an obsolete header.  It exists for compatibility with
>   older programs, and is implemented as an alias of <string.h>.
> 
> This makes it clear that the header is never useful, and that it's
> strictly redundant with <string.h>, in a way that still lets someone
> reading old code discover it.

You've convinced me to further reduce the change.  I've removed any
explicit suggestions in the functions' pages about including <memory.h>.
They're not necessary for the purpose they were meant for.  Here's how
memcpy(3) looks like now:

	SYNOPSIS
	     #include <string.h>  // see memory.h(3head)

	     void *memcpy(size_t n;
			  void dest[restrict n], const void src[restrict n],
			  size_t n);

The only reference is a comment to read the memory.h(3head) manual page,
as it contains historic details that are relevant about this header
file.  The fact that <string.h> is the only header file included, and
there no "or ...", clearly says that programmers should include
<string.h>.

We (or at least I) still want to clarify --already at the point where
<string.h> is used-- that <string.h> is the right header for this
function as a result of a historical mistake --which we can't solve at
this point in time, but it still is an (ossified) mistake--.

This should accomplish the fundamental objective of this change, which
is to clarify users that these functions are not strictly string APIs
(even if they might be used for strings, in some cases, and with great
 care).  The pure string APIs don't have this comment, as they naturally
belong in <string.h>.

The <memory.h> manual page is now the only place that documents an
'#include <memory.h>', for obvious reasons, and tells a detailed history
of why things happened as they happened.

	memory.h(3head)                                 memory.h(3head)

	NAME
	     memory.h - memory operations

	LIBRARY
	     Standard C library (libc, -lc)

	SYNOPSIS
	     #include <memory.h>

	DESCRIPTION
	   Write
	     bzero(3)
	     memset(3)

	   Copy
	     memmove(3)
	     memcpy(3)
	     mempcpy(3)
	     memccpy(3)
	     strncpy(3)

	   Catenate
	     strncat(3)

	   Duplicate
	     strndup(3)
	     strndupa(3)

	   Compare
	     memcmp(3)
	     strncmp(3)
	     strncasecmp(3)

	   Search
	     memchr(3)
	     memrchr(3)
	     memmem(3)

	VERSIONS
	     In  some systems (Illumos), <memory.h> contains only a few
	     of these functions, and thus <string.h> is needed.

	STANDARDS
	     BSD.

	     These functions are also provided in <string.h>, as speci‐
	     fied by ISO C.  This is a historic mistake maintained  for
	     compatibility  reasons.   Don’t  let  that fool you; these
	     functions don’t necessarily operate on strings.

	HISTORY
	     SVr1, 4.3BSD.

	     System V (1983) introduced an initial set  of  mem*  func‐
	     tions  in a <memory.h> header file.  4.3BSD (1986) adopted
	     them.

	     SVID Issue 1 (1985) standardized  this  header  file,  but
	     stated that the functions would be moved to <string.h>.

	     XPG  Issue  3  (1989)  listed <memory.h> as WITHDRAWN, and
	     stated that the functions had been moved to <string.h>.

	     C89 didn’t standardize this header file and instead speci‐
	     fied all these functions in <string.h>.

	     This merge of header files has historically confused  pro‐
	     grammers about the real purpose of these functions.

	     Most C libraries, including the BSDs, glibc, musl, Bionic,
	     and Illumos continue to provide <memory.h>.

	     gnulib  doesn’t  provide  it,  though,  and  instead  uses
	     <string.h>.

	SEE ALSO
	     string(3), string_copying(7)

	Linux man‐pages 6.18‐18... 2026‐08‐04           memory.h(3head)

I believe this text is quite objective.  It doesn't anywhere suggest
that users keep using it, as glibc maintainers have strongly pushed for.
It doesn't subjectively discourage its use either, though.  It just
gives a detailed clarification of how portable it is (which might indeed
discourage its use).

I believe the way this is documented will result in readers being more
aware of this history, which would help for example programmers find
existing uses of <memory.h> and wondering if they can remove them.

Does this sound reasonable to you?

I might be persuaded of further tweaks to this, FWIW.


Have a lovely day!
Alex

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

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