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

[Paul Eggert]

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.

> +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.

> +@strong{Portability note:} In the future, additional fields can be added

Change "field" to "member", here and elsewhere in the new documentation.

> +impact the application binary interface (ABI).

impact -> affect  (as there is no collision here :-)

> +due new fields added by the kernel.

due -> due to

> +Different than @code{openat}

Different than -> Unlike  (here and elsewhere)

> +@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.


> +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}).

> +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.

> +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: