Hi Alex, At 2026-08-02T01:24:28+0200, Alejandro Colomar wrote: > > Date: 2026-08-02 00:44:46+0200 > > From: Alejandro Colomar <[email protected]> > > > [...] > > > 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.
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.
> +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.
If you care about SVID, this point may bear further research. Matt G.
of TUHS might have a line on older editions of SVID.
> +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>.
+
+ 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).
If you like the foregoing, consider it:
Signed-off-by: G. Branden Robinson <[email protected]>
Regards,
Branden
[1] As one does with "all the glue", when one doesn't want a "major
award" to be readily repaired...
signature.asc
Description: PGP signature
