[PATCH v2] man/man3/mem*(): SYNOPSIS: Document non-standard mem*() functions as provided by <memory.h>

[Alejandro Colomar]

Hi Bruno!

> Date: 2026-08-02 00:22:34+0200
> From: Bruno Haible <bruno@clisp.org>
>
> Hi Alejandro,
> 
> All proposed ISO C changes need to be evaluated according to (at least)
> these three dimensions:
> 
>   * Benefit (for the community of C programmers),
>   * Cost of adoption (for the community of C programmers),
>   * Consistency.
> 
> Your previous proposal "alx-0097r1 - <memory.h>, the legitimate header for
> memcpy(3) et al." evaluates like this, IMO:
>   * Benefit: Small.
>   * Cost of adoption: Huge
>     (there are more than 700000 references to memcpy() alone in Debian sources
>     [1]).

There's literally no change.  The proposal includes this:

    7.28  String handling <string.h>
	@@ New subsection after title
	+7.28.<0+1>  General
	+1
	+	The header <string.h>
	+	includes the headers <memory.h> and <nonstring.h>.

Which means that <string.h> is still a valid provider of memcpy(3), and
thus absolutely no existing code breaks.

This is really a documentation change only.  libc implementations that
don't already have <memory.h> --i.e., Illumos gate, and gnulib, in the
POSIX-ish world-- will have to do some work, but users won't.

>   * Consistency: Reasonable (you have explained why strncpy is actually a "mem"
>     function).
> 
> This proposal [v2] is no longer for ISO C, but — if you want to teach the
> community something by modifying the man pages — needs to be evaluated according
> to the same criteria.
>   * Benefit: None.
>   * Cost of adoption: Moderate
>     (because these 5 functions are not frequently used).
>   * Consistency: Totally negative.
>       - memmem() is a generalization of memchr(), therefore it belongs in the
>         same header file, namely <string.h>.
>       - memrchr() is an analogue to memchr(), therefore likewise it belongs in
>         <string.h>.
>       - mempcpy() is a variant of memcpy(), therefore likewise it belongs in
>         <string.h>.
>       - strndupa() is a variant of strndup() which is declared in <string.h>,
>         therefore it belongs in <string.h> as well.

Indeed, I've decided to do the entire set of v1, except I'll add some
more text to NOTES documenting that <string.h> provides all of them too.

> Please do us the favour to evaluate your proposals according to these
> dimensions by yourself, before spreading them.

Sure!  Thanks!

> And, of course, for man page changes, consider the authoritative source.
> For example, memfrob() exists only in glibc [2], therefore its authoritative
> documentation is in the glibc manual [3], and it says "It is declared in
> string.h." The man pages MUST say the same thing.

Yes, in v3 (which I'll send soon), they'll say the same thing.  That is,
all the functions --standard or not-- will have text clarifying that the
functions are also provided in <string.h>.  This covers what glibc says.
What goes in the SYNOPSIS is something I'll diverge from glibc, but
that's fair game.

Thanks for the feedback!


Have a lovely night!
Alex

> Thanks.
> 
>       Bruno
> 
> [1] https://codesearch.debian.net/search?q=%5Cbmemcpy%5Cb&literal=0
> [2] https://gitweb.git.savannah.gnu.org/gitweb/?p=gnulib/maint-tools.git;a=tree;f=platforms/various-symlists
> [3] https://sourceware.org/glibc/manual/2.44/html_node/Obfuscating-Data.html
> 
> 
> 

-- 
<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/20260802/7fdd9fd1/attachment.sig>