The goal of the Linux man-pages project
Alejandro Colomar
alx@kernel.org
Wed Aug 5 14:15:07 GMT 2026
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>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://sourceware.org/pipermail/libc-alpha/attachments/20260805/db71b864/attachment.sig>
More information about the Libc-alpha
mailing list