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

[Adhemerval Zanella Netto]

On 21/08/25 14:28, Paul Eggert wrote:
> On 8/21/25 06:38, Adhemerval Zanella wrote:
>> +extern int openat2 (int __dfd, const char *__filename, struct open_how *__how,
>> +            size_t __usize)
>> +     __nonnull ((2, 3));
> 
> The pointer arguments should be marked with __restrict, for the same reason similar syscalls mark them that way.
> 
> The __how argument should be pointer to const. The Linux man page project documents it that way in openat(2); openat2(2) seems to be incorrect here.
> 
> Similar changes need to be made to the documentation.

Ack, it is an overlook from my side.

> 
>> +The @code{size} define the expected size of @code{how} data structure.
>> +It is recommended to initialize unused fields to zero, either using
>> +@code{memset}, or using a structure initializer.
> 
> I don't know what "expected size" means. Instead, I suggest something like this:
> 
> The @var{size} argument must equal @code{sizeof *@var{how}}. For portability to future API versions that extend @code{struct open_how}, @code{*@var{how}} should be initialized either by a struct initializer or by @code{memset} to zero.
> 

Ack.

>> +@strong{Portability note:} In the future, additional fields can be added
> 
> Change "field" to "member", here and elsewhere in the new documentation.
> 
Ack.

>> +impact the application binary interface (ABI).
> 
> impact -> affect  (as there is no collision here :-)
> 

Ack.

>> +due new fields added by the kernel.
> 
> due -> due to
> 

Ack.

>> +Different than @code{openat}
> 
> Different than -> Unlike  (here and elsewhere)
> 

Ack.

>> +@strong{NB:} Different than other open-like functions, the kernel only
>> +provides the LFS variant.  When the sources are translated with
>> +@code{_FILE_OFFSET_BITS == 64} this function is not routed to a different
>> +symbol.
> 
> No need for "NB:". Too much low-level terminology like "LFS" here. In short, please reword to:
> 
> Unlike other @code{open}-like functions, this function ignores @code{_FILE_OFFSET_BITS} and always operates in large file mode.
> 

Ack.

> 
>> +returns an error for invalid value (like value larger than @code{0777}).
> 
> Reword to:
> 
> returns an error for invalid values (i.e., values greater than @code{0777}).
> 
Ack.

>> +This is a bitmask of flags that modify the way in @strong{all} components
>> +of @code{pathname}.  It allows trusted programs to restrict how untrusted
>> +paths are resolved.  The following generic flags are available.
> 
> The first sentence is not valid English. Not sure we should be talking about "trusted programs" here. This stuff is not meant only for setuid programs, for example. It's useful for any programs. And I don't know what "generic" means here. I suggest rewording to:
> 
> This is a bitmask of flags that affect the resolution of file name components.  Unlike @code{O_NOFOLLOW}, it affects all file name components, not just the last one. The following flags are available.

Ack.

> 
>> +On failure, @code{openat2} returns @math{-1} and sets @code{errno}.  The
>> +following errors are also returned:
> ...
>> +
>> +It can also return all the errors @code{openat} returns, or other errors
>> +due new fields added by the kernel.
> 
> Errors are not "returned". Also, I don't see why we should mention that openat2 can fail for new fields added by the kernel; of course the kernel can add new errno values in future versions for any reasons it likes, but that's true for any syscall. So please change to something like this:
> 
> On failure, @code{openat2} returns @math{-1} and sets @code{errno}. It can fail for any of the reasons @code{openat} fails, plus the following reasons:

Ack.