Re: proposed revision to memory.h(3head) (was: on the irresponsibility of pursuing C language reform)

[Alejandro Colomar <alx@kernel.org>]

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

Hi Branden,

> Date: 2026-08-01 18:53:32-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> At 2026-08-02T01:24:28+0200, Alejandro Colomar wrote:
> > > Date: 2026-08-02 00:44:46+0200
> > > From: Alejandro Colomar <alx@kernel.org>
> > >
> > [...]
> > > > Advocating for better usage in the documentation is a different
> > > > thing, and a good thing. The man pages can even go pretty hard,
> > > > that’s their job: “Notice the include file is string.h. That’s an
> > > > historic accident maintained for compatibility reasons; don’t let
> > > > that fool you, this function doesn’t operate on strings.”
> > > 
> > [...]
> > > I should probably expand the NOTES a little bit, to be more clear
> > > about why we ignore the standard in the SYNOPSIS.
> > 
> > I've put that text in a centralized place, in the memory.h(3head)
> > manual page:
> > 
> > 	$ MANWIDTH=64 diffman-git HEAD
> > 	--- HEAD^:man/man3head/memory.h.3
> > 	+++ HEAD:man/man3head/memory.h.3
> > 	@@ -10,6 +10,11 @@ SYNOPSIS
> > 	      #include <memory.h>
> > 	 
> > 	 DESCRIPTION
> > 	+     These functions are also provided in <string.h>, as speci‐
> > 	+     fied by ISO C.  This is a historic accident maintained for
> > 	+     compatibility reasons.  Don’t let that fool you; these
> > 	+     functions don’t necessarily operate on strings.
> > 	+
> 
> That's a heavy editorial slant.  I don't think it was a historical
> accident; it was a historical "on purpose"[1], with which you disagree.

[pasted [1] here]
> [1] As one does with "all the glue", when one doesn't want a "major
>     award" to be readily repaired...

The C89 Rationale document doesn't document this as an intentional
change (or even as a change at all).
<https://www.open-std.org/jtc1/sc22/wg14/www/C89Rationale.pdf>

I'd certainly be interested in hearing first-hand information,
if anyone has it.  Maybe Keith would be the best candidate for that.

> Here's a revision that goes a little less hard, favors active voice over
> passive, and is shorter.
> 
> 	+     ISO C mandates that <string.h> declare these functions.
> 	+     Be aware that they do not necessarily operate on strings.

I'll think about it.

> 
> > 	+STANDARDS
> > 	+     BSD.
> 
> If you're tracking SVID in the Linux man-pages project, I would guess
> that it was in the original SVID, which formalized/specified SVr2--but I
> can't find online any version of SVID older than its Fourth Edition.

Here's an online copy of SVID Issue 2:
<https://bitsavers.org/pdf/att/unix/SVID/System_V_Interface_Definition_Issue_2_Volume_1_1986.pdf>
It does indeed standardize <memory.h>.

I don't know of any copy of SVID Issue 1.

SVID is a withdrawn standard (having been superseded by the SUS/POSIX
standards, Issue 8 in the most recent revision), and thus not
appropriate for STANDARDS.  It'd be however appropriate for HISTORY.
However, the SVID 1 corresponds to SVr2 (1985), so that's actually too
late for this.  In HISTORY, I've documented this as SysV (maybe we
should coin SVr1?  It doesn't exist in standards(7), but it'd be
reasonable).

At the moment, I have it as:

	STANDARDS
	     BSD.

	HISTORY
	     SysV, 4.3BSD.

		...

Also, we don't document the SVID documents in HISTORY, because we
document the corresponding revision of SysV.

Interestingly, POSIX.1-1988 already moved everything to <string.h>
(C89 was almost finalized by then) and doesn't contain any references to
<memory.h>, as if it had never existed.
<https://nvlpubs.nist.gov/nistpubs/Legacy/FIPS/fipspub151-1.pdf>
I'd be curious to see whether XPG Issue 3 still kept <memory.h> (but
I suspect it won't, since it derives from POSIX.1-1988).
SVID Third Edition curiously removed any mentions of <memory.h>, as if
it had never existed (just like POSIx.1-1988).
<https://archive.org/details/systemvinterface0001unse/page/n149/mode/1up?q=memory.h>

(For anyone reading and wondering about the incestuous relationship of
 these old standards, here's a useful rough sketch I did some time ago):
<https://lore.kernel.org/linux-man/aWwzhLaG_aehhWOG@devuan/>

> If you care about SVID, this point may bear further research.  Matt G.
> of TUHS might have a line on older editions of SVID.

I'd be interesting to have a copy of those, for sure.  I am aware of
the copies of Issue 2 and Third Edition I linked above, but I'd
certainly be interested in a copy of Issue 1.  XPG 3 would also be nice.

> > 	+HISTORY
> > 	+     The <memory.h> header file is the original one which was
> > 	+     added in System V (1983), and was later adopted by 4.3BSD
> > 	+     (1986).  It contained the original mem* functions.
> > 	+
> > 	+     C89 didn’t standardize this header file, and instead
> > 	+     crammed all these functions in <string.h>, resulting in
> > 	+     confusing programmers about the real purpose of these
> > 	+     functions.
> 
> Again, you're going harder than you need to here.
> 
> I propose:
> 
> 	+HISTORY
> 	+     System V (1983) introduced an initial set of mem*
> 	+     functions in a <memory.h> file.  4.3BSD (1986) adopted
> 	+     them.  C89 specified them in <string.h>.

I like part of this paragraph.

> 	+     The programmer bears the burden of selecting appropriate
> 	+     functions for operations on memory buffers (which may
> 	+     contain any bytes, including nulls) versus strings (which
> 	+     null bytes terminate).

I'm not convinced.

> 
> If you like the foregoing, consider it:
> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

I'll probably modify it and note it as

	Suggested-by: ...


Cheers,
Alex

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

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