[CC += gcc@]

Hi Seth,

On Wed, Jan 21, 2026 at 06:12:45AM +0000, Seth McDonald wrote:
[...]
> > We might need a qualifiers(7) manual page.  Especially, once their rules
> > are modified in ISO C2y.  Alternatively, we may need a new section
> > man3qual, with an intro(3qual) page talking about this, and then
> > const(3qual) and volatile(3qual) to document the usual qualifiers, plus
> > a restrict(3qual) documenting how irremediably broken that monster is,
> > and _Atomic(3qual) also documenting that qualifier (which I never really
> > understood well, and from what the committee is talking now, they don't
> > seem to like it either).
> 
> I'd be down for a qualifiers(7) man page.  Don't know about a whole
> man3qual section though.  Unlike library functions (man3), constants
> (man3const), or types (man3type), which are all provided by GNU/Linux,
> qualifiers are a built-in language feature of C.

We have _Countof(3), _Maxof(3), and _Minof(3) manual pages for these
operators (which are also built-in language features (operators) of C.

And we have manual pages for attributes (man3attr).

man3qual would be smaller (the number of qualifiers is rather small),
but it would be consistent, I think.

> One could argue that
> GCC 'provides' them, but I don't think that means they should be
> documented as if they're a feature of GNU/Linux.

The fact that qualifiers are so widespread and unified today that
there's not much variance among implementations doesn't mean that there
aren't outliers.  Some implementations (dialects) of C still don't have
qualifiers; an example is Plan9's C compiler, which doesn't have const.

So, const is indeed a feature of GCC (among many others).

> Documenting them in
> the miscellaneous man7 instead conveys how they're important enough to
> document and are related to GNU/Linux, without implying that they're
> part of/provided by GNU/Linux (like other man3* sections).
> 
> Btw, I'm curious as to why you say the restrict qualifier is broken.
> I'm yet to encounter much trouble with it, so I'd be interested in its
> flaws.

For a starter, it doesn't follow the usual qualifier rules; being a
qualifier on the pointer, it gets discarded immediately on lvalue
conversion.  It essentially behaves as an attribute with the syntax of
a qualifier.

Regarding the semantics, it's defined in terms of accesses, and thus it
is valid to declare two aliasing pointers as restrict as long as they
are not accessed.

	alx@devuan:~/tmp$ cat restrict.c 
	int *f(int *restrict a, int *restrict b);

	int
	main(void)
	{
		int x;

		f(&x, &x);
	}

	int *
	f(int *restrict a, int *restrict b)
	{
		*a = 42;
		return b;
	}
	alx@devuan:~/tmp$ gcc -Wall -Wextra restrict.c 
	restrict.c: In function ‘main’:
	restrict.c:8:11: warning: passing argument 1 to ‘restrict’-qualified parameter aliases with argument 2 [-Wrestrict]
	    8 |         f(&x, &x);
	      |           ^~  ~~

The program above is fine according to ISO C.  GCC diagnoses in this
case (it is a false positive), but doesn't diagnose on other cases.
Clang doesn't diagnose at all.  See below an example that is not
diagnosed by GCC either:

	alx@devuan:~/tmp$ cat restrict2.c 
	int *f(int *restrict a, int **restrict b);

	int
	main(void)
	{
		int *x = &(int){0};

		f(x, &x);
	}

	int *
	f(int *restrict a, int **restrict b)
	{
		*a = 42;
		*b = a;
		return *b;
	}
	alx@devuan:~/tmp$ gcc -Wall -Wextra restrict2.c 
	alx@devuan:~/tmp$ clang -Weverything restrict2.c 
	alx@devuan:~/tmp$ 

This program is also fine according to ISO C.  Neither GCC nor Clang
emit any diagnostics; and they can't!  If they diagnosed this, they'd
have to diagnose on valid uses of strtol(3), and that would be
unacceptable.

But if compilers can't diagnose on the call f(x,&x) where f()'s
parameters are restrict, what stops one from passing aliasing pointers
to a function that really accesses its parameters?  The compiler can't
know what the function will do with them.  Thus, restrict results in
having more UB, and the optimizations it enables can make that UB even
more dangerous.

And unsurprisingly, the rationale for restrict was optimizations, not
diagnostics.  That's a bad idea.

restrict should eventually be replaced by an attribute (a qualifier
won't work).  Such an attribute should be defined only in terms of
aliasing of pointers, and not on accesses.  That would turn it into
a tool for diagnostics instead of a tool for optimization (while it
would still allow for optimizations in most cases), and that is a good
idea.


Have a lovely day!
Alex

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