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

[Alejandro Colomar <alx@kernel.org>]

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