Re: swab.3: mention UB when from and to overlap

["Sertonix" <sertonix@posteo.net>]

On Sun Oct 12, 2025 at 2:02 AM CEST, Alejandro Colomar wrote:
> Hi Sertonix, Collin,
>
> On Sat, Oct 11, 2025 at 03:40:34PM -0700, Collin Funk wrote:
>> "Sertonix" <sertonix@posteo.net> writes:
>> 
>> > The current swab.3 page doesn't seem to mention anything about what
>> > happens when from and to overlap. In POSIX any overlap is UB.
>> >
>> > glibc handles cases when from == to but it will choke when for example
>> > from == to+1. I am uncertain if from == to is meant to be a feature.
>> >
>> > If it is, would it be possible to mention that overlap is only safe when
>> > from == to and it's glibc (not eg. musl)? If it's not intended would it
>> > be possible to include the same information as in POSIX?
>> 
>> The prototype uses restrict for both pointers which is how you tell the
>> C compiler that two objects will not overlap.
>
> As Collin says, 'restrict' is there to document this.
>
> The 'restrict' keyword (theoretically, a qualifier, but it works more
> like an attribute) is difficult to explain (and the wording of the
> standard to describe it is quite difficult to follow).  However, the
> core idea is simple: nothing should overlap such a pointer.

Thanks for the explanation! Then this was just my lack of understanding
the restrict keyword.

> There are exceptions, such as the case when a function doesn't access
> such a pointer.  That's why strtol(3) is declared as
>
>      long strtol(const char *restrict s, char **restrict endp, int base);
>
> even though one can (and usually do) call it as strtol(s, &s, 0), where
> 's' is indeed aliased by another pointer (*endp).  That's because *endp
> is never accessed within strtol(3).

If endp is considered to point to a 0 size block of memory it works ;)

>> But maybe it is better to be friendly to those new to see and state it
>> explicitly? Alex will know better than I.
>
> I hope we don't.  That would require a CAVEATS section in too many
> pages.
>
> 	$ grep -rl '\<restrict\>' man | wc -l
> 	156
>
> While the detail about strtol(3) is tricky, and could be worthy of
> documentation (most likely), the general idea behind 'restrict' is
> quite easy to understand, IMO, and I think documenting it in plain
> English would be too much.  Especially, since 'restrict' is a C99
> keyword, so I expect it to be more or less common knowledge.

It seems fair to not repeat the meaning of restrict everywhere.