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

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

[Alejandro Colomar]

[-- 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 --]

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

[Mark Harris]

Alejandro Colomar wrote:
>
> 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);

The second style is much more understandable.  The first style looks
like it operates on some kind of Unicode/wide character type and you
need to do some kind of conversion or at least a cast in order to use
it.  If QChar was italicized as it is in the C23 standard then it
would be more clear that it isn't an actual type name, but even then
it would require extra explanation as to what the actual type is.  The
user shouldn't have to go to another page just to find out that it
will work with a plain char * and they don't need to do anything
special.  The second form is fairly clear without any additional
explanation, although a brief mention in the description would be good
to avoid any potential confusion.

>
> -  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.

I don't see any value in introducing QChar/QVoid in the man pages,
since it is easy to explain without that.  I suggest the two-line
synopsis and a mention in the description, which could be even shorter
than explaining that QChar is not the actual type and to see some
other man page for details.  If there were more qualifier combinations
or they had complicated interactions, and so there was a reason to
have just one central place to explain it, then introducing a new
concept with its own man page might be worthwhile.

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

I suggest a sentence in the description stating that only the
non-const-qualified variant is used prior to C23 or when using a
function pointer.

 - Mark

>
> Any other comments?
>
>
> Have a lovely day!
> Alex
>
> --
> <https://www.alejandro-colomar.es>

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

[Paul Eggert]

On 2026-02-24 06:28, Alejandro Colomar wrote:
> -  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);
One documents strchr, the other strnul. And strchr and strnul do differ: 
strchr has an underlying obsolescent function, and strnul does not. This 
suggests strchr should be documented differently from strnul.

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

[Alejandro Colomar]

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

Hi Paul,

On 2026-02-24T09:14:04-0800, Paul Eggert wrote:
> On 2026-02-24 06:28, Alejandro Colomar wrote:
> > -  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);
> One documents strchr, the other strnul.

D'oh!  Copy/paste error.  I forgot to replace the function name.

> And strchr and strnul do differ:
> strchr has an underlying obsolescent function, and strnul does not. This
> suggests strchr should be documented differently from strnul.

How would you document strchr(3)?


Have a lovely night!
Alex

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

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

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

[Paul Eggert]

On 2026-02-24 13:31, Alejandro Colomar wrote:
> How would you document strchr(3)?

I'd do what the standard does rather than reinvent this particular wheel.

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

[Alejandro Colomar]

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

Hi Paul,

On 2026-02-24T15:04:03-0800, Paul Eggert wrote:
> On 2026-02-24 13:31, Alejandro Colomar wrote:
> > How would you document strchr(3)?
> 
> I'd do what the standard does rather than reinvent this particular wheel.

So, you'd use QChar?


Cheers,
Alex

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

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

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

[Paul Eggert]

On 2026-02-24 15:05, Alejandro Colomar wrote:
>>> How would you document strchr(3)?
>> I'd do what the standard does rather than reinvent this particular wheel.
> So, you'd use QChar?

Yes. As confusing as QChar/QVoid is, it'd likely be more confusing 
overall for us to invent our own notation. Whichever notation we use, we 
need to explain the business with void * arguments anyway.

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

[Alejandro Colomar]

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

Hi Paul,

On 2026-02-24T15:19:14-0800, Paul Eggert wrote:
> On 2026-02-24 15:05, Alejandro Colomar wrote:
> > > > How would you document strchr(3)?
> > > I'd do what the standard does rather than reinvent this particular wheel.
> > So, you'd use QChar?
> 
> Yes. As confusing as QChar/QVoid is, it'd likely be more confusing overall
> for us to invent our own notation.

Hmmmm, okay.  I see conflicting opinions (others prefer C++-like
overload notation).  I think I prefer QChar/QVoid, but am not convinced
of which to use.

Whichever we use, we need to distinguish cases like strnul(3) from cases
like strchr(3).  I think I'd do it like this:

	strchr(3)
	SYNOPSIS
		#include <string.h>

		QChar *strchr(QChar *s, int c);

		#undef strchr
		char *strchr(const char *s, int c);

The above documents that you can #undef the macro, which provides the
function with the different prototype.  And then strnul(3) would only
have the QChar prototype, as there's no function.

	strnul(3)
	SYNOPSIS
		#include <string.h>

		QChar *strnul(QChar *s);

What do you think?

> Whichever notation we use, we need to
> explain the business with void * arguments anyway.

Hmmm, yeah, this and other corner cases lead me to think QChar/QVoid
would be better.  It would allow me to write a manual page describing
those.  And I expect people will eventually get used to that syntax;
it's a matter of time.


Have a lovely night!
Alex

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

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

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

[Mark Harris]

Alejandro Colomar wrote:
>
> Hi Paul,
>
> On 2026-02-24T15:19:14-0800, Paul Eggert wrote:
> > On 2026-02-24 15:05, Alejandro Colomar wrote:
> > > > > How would you document strchr(3)?
> > > > I'd do what the standard does rather than reinvent this particular wheel.
> > > So, you'd use QChar?
> >
> > Yes. As confusing as QChar/QVoid is, it'd likely be more confusing overall
> > for us to invent our own notation.
>
> Hmmmm, okay.  I see conflicting opinions (others prefer C++-like
> overload notation).  I think I prefer QChar/QVoid, but am not convinced
> of which to use.
>
> Whichever we use, we need to distinguish cases like strnul(3) from cases
> like strchr(3).  I think I'd do it like this:
>
>         strchr(3)
>         SYNOPSIS
>                 #include <string.h>
>
>                 QChar *strchr(QChar *s, int c);
>
>                 #undef strchr
>                 char *strchr(const char *s, int c);

I don't see how anyone would understand what this is trying to convey,
unless they were already familiar with the C23 changes to strchr.  The
#undef in the middle makes it worse, because it appears to be going
out of its way to describe the function using strict C syntax, even to
the point of sacrificing normal synopsis conventions and clarity.
However QChar is not a C type or macro, so by making it appear that
the synopsis is supposed to be interpreted strictly as C code it just
ends up making it more confusing.  The C23 style only works if you can
put QChar in italics, as in C23, or some other style that clearly
distinguishes it from a type name or C code.  If you don't like the
two-line synopsis it would be better to just leave the synopsis as it
was, and add a sentence to the description that in C23 a
const-qualified argument propagates the const qualification to the
result type.

 - Mark

>
> The above documents that you can #undef the macro, which provides the
> function with the different prototype.  And then strnul(3) would only
> have the QChar prototype, as there's no function.
>
>         strnul(3)
>         SYNOPSIS
>                 #include <string.h>
>
>                 QChar *strnul(QChar *s);
>
> What do you think?
>
> > Whichever notation we use, we need to
> > explain the business with void * arguments anyway.
>
> Hmmm, yeah, this and other corner cases lead me to think QChar/QVoid
> would be better.  It would allow me to write a manual page describing
> those.  And I expect people will eventually get used to that syntax;
> it's a matter of time.
>
>
> Have a lovely night!
> Alex
>
> --
> <https://www.alejandro-colomar.es>

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

[Alejandro Colomar]

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

Hi Mark,

On 2026-02-24T17:03:02-0800, Mark Harris wrote:
> >         strchr(3)
> >         SYNOPSIS
> >                 #include <string.h>
> >
> >                 QChar *strchr(QChar *s, int c);
> >
> >                 #undef strchr
> >                 char *strchr(const char *s, int c);
> 
> I don't see how anyone would understand what this is trying to convey,
> unless they were already familiar with the C23 changes to strchr.  The
> #undef in the middle makes it worse, because it appears to be going
> out of its way to describe the function using strict C syntax, even to
> the point of sacrificing normal synopsis conventions and clarity.

While it would be new to use #undef in SYNOPSIS, we already have #define
in many places (as a way to document necessary feature test macros).
Here's an example, which uses it in the middle of the section (more
often, it goes before the first #include):

	SYNOPSIS
	     #include <string.h>

	     char *strstr(const char *haystack, const char *needle);

	     #define _GNU_SOURCE         /* See feature_test_macros(7) */
	     #include <string.h>

	     char *strcasestr(const char *haystack, const char *needle);

Using #undef wouldn't be too extraneous compared to this, I think.

> However QChar is not a C type or macro, so by making it appear that
> the synopsis is supposed to be interpreted strictly as C code it just
> ends up making it more confusing.  The C23 style only works if you can
> put QChar in italics, as in C23, or some other style that clearly
> distinguishes it from a type name or C code.

Yup, I'd use some style that makes it distinct from regular types.
Maybe italics, or maybe roman.  That's the least of our problems.

>  If you don't like the
> two-line synopsis it would be better to just leave the synopsis as it
> was, and add a sentence to the description that in C23 a
> const-qualified argument propagates the const qualification to the
> result type.

I prefer the overload syntax over the old syntax, because the old syntax
is confusing people.  This week someone was surprised because the
SYNOPSIS clearly shows the old syntax, but their test on Arch with the
latest glibc rejected some code that was correct according to the shown
prototype.  So we need to clearly document that the prototype is now
different, somehow.

Thanks for the feedback!


Have a lovely night!
Alex

> 
>  - Mark

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

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

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

[Rene Kita]

On Tue, Feb 24, 2026 at 03:28:44PM +0100, Alejandro Colomar wrote:
> 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);

IMHO the overload style is more appropriate for the next few years.
Everyone who has at least read K&R C will understand it.

For technical correctness the QChar/QVoid style should be mentioned, though.
That's why...

> -  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.

these man pages should be created in either case.

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

As I usually don't deal with C23 - and don't expect this to change for a
few years - I would prefer to have the old function documented. It might
be that I work on a C99 project while viewing the latest man pages on a
Arch system.

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

[Alejandro Colomar]

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

Hi Rene,

On 2026-02-24T19:52:33+0100, Rene Kita wrote:
> > -  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);
> 
> IMHO the overload style is more appropriate for the next few years.
> Everyone who has at least read K&R C will understand it.

Ok.

> For technical correctness the QChar/QVoid style should be mentioned, though.
> That's why...
> 
> > -  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.
> 
> these man pages should be created in either case.
> 
> > -  How much should we document the old function?  Should we keep that as
> >    a historic detail in the QChar(3)/QVoid(3) page?
> 
> As I usually don't deal with C23 - and don't expect this to change for a
> few years - I would prefer to have the old function documented. It might
> be that I work on a C99 project while viewing the latest man pages on a
> Arch system.

A problem, even if you write C99 on your project (let's say mutt(1), for
example), is that the compiler will default to something newer, and
you'll be exposed to those APIs.  If they're not documented, you'll be
quite surprised that your code suddenly fails.  So I think they should
be documented.  Of course, the old function would also need to be
documented, because otherwise people might be surprised the other way
around.

Hmmm, how about something like this?

	SYNOPSIS
		#include <string.h>

		char *strchr(char *s, int c);
		const char *strchr(const char *s, int c);

		#undef strchr
		char *strchr(const char *s, int c);

Plus a paragraph in HISTORY clarifying this.


Have a lovely night!
Alex

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

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

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

[Rene Kita]

On Tue, Feb 24, 2026 at 10:41:58PM +0100, Alejandro Colomar wrote:
> Hi Rene,
> 
> On 2026-02-24T19:52:33+0100, Rene Kita wrote:
> > > -  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);
> > 
> > IMHO the overload style is more appropriate for the next few years.
> > Everyone who has at least read K&R C will understand it.
> 
> Ok.
> 
> > For technical correctness the QChar/QVoid style should be mentioned, though.
> > That's why...
> > 
> > > -  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.
> > 
> > these man pages should be created in either case.
> > 
> > > -  How much should we document the old function?  Should we keep that as
> > >    a historic detail in the QChar(3)/QVoid(3) page?
> > 
> > As I usually don't deal with C23 - and don't expect this to change for a
> > few years - I would prefer to have the old function documented. It might
> > be that I work on a C99 project while viewing the latest man pages on a
> > Arch system.
> 
> A problem, even if you write C99 on your project (let's say mutt(1), for
> example), is that the compiler will default to something newer, and
> you'll be exposed to those APIs.  If they're not documented, you'll be
> quite surprised that your code suddenly fails.  So I think they should
> be documented.  Of course, the old function would also need to be
> documented, because otherwise people might be surprised the other way
> around.
> 
> Hmmm, how about something like this?
> 
> 	SYNOPSIS
> 		#include <string.h>
> 
> 		char *strchr(char *s, int c);
> 		const char *strchr(const char *s, int c);
> 
> 		#undef strchr
> 		char *strchr(const char *s, int c);
> 
> Plus a paragraph in HISTORY clarifying this.

Without the context I already have, I don't think I would understand
what's meant with this #undef. Maybe better "Before C23" or "Former
version" or something, but I'm just brainstorming here...

I'm not even sure if it has to be mentioned in the SYNOPSIS. OTOH,
C23 brings some breaking changes and it might help people save time when
those differences are clearly mentioned.