QChar and QVoid for strchr(3), memchr(3), et al.
Alejandro Colomar
maintainerHi!
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Quoted 46 lines · Alejandro Colomar
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.gitcd748a63ab1a(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:
Quoted 6 lines
- 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.
Quoted 4 lines
- 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.
Quoted 3 lines
- 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
Quoted 9 lines
Any other comments?
Have a lovely day!
Alex
Quoted 6 lines · Alejandro Colomar
- 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.
Quoted 45 lines · Alejandro Colomar
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.gitcd748a63ab1a(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:
Quoted 6 lines
- 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...
Quoted 3 lines
- 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.
Quoted 2 lines
- 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.
Alejandro Colomar
maintainerHi Paul,
Quoted 8 lines · Paul Eggert
Quoted 6 lines · Alejandro Colomar
- 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.
Quoted 3 lines
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerHi Rene,
Quoted 9 lines · Rene Kita
Quoted 6 lines
- 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.
Quoted 9 lines
For technical correctness the QChar/QVoid style should be mentioned, though. That's why...
Quoted 3 lines
- 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.
Quoted 7 lines
Quoted 2 lines
- 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
Signature · 1 line
<https://www.alejandro-colomar.es>
Quoted 1 line · Alejandro Colomar
How would you document strchr(3)?
I'd do what the standard does rather than reinvent this particular wheel.
Alejandro Colomar
maintainerHi Paul,
Quoted 4 lines · Paul Eggert
Quoted 1 line · Alejandro Colomar
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Quoted 3 lines · Alejandro Colomar
Quoted 2 lines
Quoted 1 line
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.
Alejandro Colomar
maintainerHi Paul,
Quoted 7 lines · Paul Eggert
Quoted 3 lines · Alejandro Colomar
Quoted 2 lines
Quoted 1 line
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?
Quoted 2 lines
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Quoted 19 lines · Alejandro Colomar
Hi Paul,
Quoted 7 lines · Paul Eggert
Quoted 3 lines · Alejandro Colomar
Quoted 2 lines
Quoted 1 line
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:
Quoted 8 lines
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
Quoted 27 lines
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?
Quoted 2 lines
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
Alejandro Colomar
maintainerHi Mark,
Quoted 6 lines · Mark Harris
Quoted 6 lines
strchr(3) SYNOPSIS #include <string.h> QChar *strchr(QChar *s, int c);
Quoted 8 lines
Quoted 2 lines
#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.
Quoted 5 lines
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.
Quoted 5 lines
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
Quoted 2 lines
- Mark
Signature · 1 line
<https://www.alejandro-colomar.es>
Quoted 51 lines · Alejandro Colomar
Hi Rene,
Quoted 9 lines · Rene Kita
Quoted 6 lines
- 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.
Quoted 9 lines
For technical correctness the QChar/QVoid style should be mentioned, though. That's why...
Quoted 3 lines
- 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.
Quoted 7 lines
Quoted 2 lines
- 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);
Quoted 1 line
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.