[PATCH v6] linux: Add openat2 (BZ 31664)

[Adhemerval Zanella Netto]

On 18/11/25 17:32, Paul Eggert wrote:
> On 2025-11-18 11:37, Adhemerval Zanella Netto wrote:
> 
>>>> +@item RESOLVE_CACHED
>>>> +Make the open operation fail unless all path components are already
>>>> +present in the kernel's lookup cache.
>>>
>>> I have no idea why an application would want to use this flag.
>>> Please add a cogent explanation for why it's useful.
>>
>> I am not sure either, so I used the documentation from man-pages.  The
>> kernel does not have any self-test using this flag either. I don't have
>> a strong opinion here, where either we just skip this from documentation
>> or use this generic explanation.
> 
> If we don't know what it's for, let's not document it. (But perhaps Aleksa or Arjun can explain.)
> 

Sounds reasonable.

> 
>>>> +For additional information, consult the manual page @manpageurl{openat2,2}.
>>>> +@xref{Linux Kernel}.
>>>
>>> Please remove this, and put any such additional information (what is it?) into the glibc manual.
>>
>> I followed what we did for sched_setattr and sched_getattr (21571ca0d70302909cf72707b2a7736cf12190a0)
> 
> That's a bad precedent. In the Glibc manual we should do what we've done for zillions of other syscalls, and document things completely. We do our readers a disservice by saying "We give up - look elsewhere for the real documentation".

I don't have a strong opinion here, but since we do include the kernel header when
available for some syscalls we don't have fully control what we end up exporting
and thus our documentation can eventually not cover everything. I think that's
why Florian has added this line to refer the Linux man-pages as the authoritative
documentation.

I will remove the reference from openat2, but I think we should also evaluate 
the wording for sched_setattr and sched_getattr .

> 
> 
>>>> +@item EAGAIN
>>>> +@code{@var{how}->resolve} contains either RESOLVE_IN_ROOT or RESOLVE_BENEATH, and
>>>> +the kernel could not ensure that @code{".."} component did not escape.  Or
>>>> +@code{RESOLVE_CACHED} was set, and the open operation cannot be performed
>>>> +using only cached information.
>>>
>>> This requires more explanation. How can the kernel not know whether ".." escapes? Please give a scenario.
>>>
>>
>> As for RESOLVE_CACHED, I am relying on man-pages explanation here.  I don't
>> think I have added a testcase for this specific, so I think would be better
>> to just remove this.
> 
> Yes, sounds good to remove the EAGAIN note (unless we can get an explanation for it).