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

[Alejandro Colomar <alx@kernel.org>]

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