QChar and QVoid for strchr(3), memchr(3), et al.

[Alejandro Colomar <alx@kernel.org>]

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

Hi!

ISO C23 changed the specification of string search functions so that if
the const qualifier is present in the input, the APIs preserve it in the
output.
<https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#subsection.7.26.5>

For example, memchr(3) and strchr(3) were previously specified as

	alx@devuan:~$ stdc C11 memchr
	void *memchr(const void *s, int c, size_t n);
	alx@devuan:~$ stdc C11 strchr
	char *strchr(const char *s, int c);

They are now specified as

	QVoid *memchr(QVoid *s, int c, size_t n);
	QChar *strchr(QChar *s, int c);

The new specification is only possible through macros, and only in
calls.  Function pointers such as &memchr or &strchr, or calls that
avoid the macro, such as (memchr)(p,0) or (strchr)(s,0), do not use the
macro, and as such, still use the old function prototype.  However, the
ability to do this is declared obsolescent by both ISO C and the glibc
manual.  This means that the underlying functions might eventually be
removed from the headers.

glibc has implemented the C23 specification in glibc-2.43, in commit
glibc.git cd748a63ab1a (2025-11-20; "Implement C23 const-preserving standard library macros").

I've written a patch for musl, but it hasn't been applied yet:
<https://www.openwall.com/lists/musl/2026/02/23/1>

gnulib has recently added a new search function, strnul(3) --which we
already document in a manual page--, and didn't include an underlying
function, since it didn't make sense to add something already obsolete.
I documented the strnul(3) API as if it were a set of C++ overloads:

	char *strnul(char *s);
	const char *strnul(const char *s);

Now that I'm considering the documentation of the glibc changes, I'm
wondering what's the most appropriate way to document them.  I have
a few questions:

-  In the SYNOPSIS, do you prefer QChar/QVoid or overload style?

	QChar *strchr(QChar *s, int c);
   vs
	char *strnul(char *s);
	const char *strnul(const char *s);

-  If we document it as QChar/QVoid, I guess we should we add a
   QChar(3)/QVoid(3) manual page documenting all of the details, to
   avoid duplicating such details in each manual page.

-  How much should we document the old function?  Should we keep that as
   a historic detail in the QChar(3)/QVoid(3) page?

Any other comments?


Have a lovely day!
Alex

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

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