Re: utimensat(2) and faccessat(2): man pages do not mention AT_EMPTY_PATH flag

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3379 bytes --]

Dear Renzo,

On Sat, Dec 09, 2023 at 05:38:57PM +0100, Renzo Davoli wrote:
> Dear Alex,
> 
> On Sat, Dec 09, 2023 at 01:00:08PM +0100, Alejandro Colomar wrote:
> > On Wed, Dec 06, 2023 at 12:04:07PM +0100, Renzo Davoli wrote:
> > > utimensat and faccessat support the flag AT_EMPTY_PATH since Linux 5.8 but
> > > this option is still missing in the man pages.
> > Thanks for reporting that.  Would you mind preparing a patch updating
> > the page?  If you need any help, just ask for it.
> 
> No problem. It is here attached. Let me know if it's okay.
> 
> All the Best and Happy Hacking.
> ciao
> 
>         renzo

> diff --git a/man2/access.2 b/man2/access.2
> index 95de3815d..97398ba76 100644
> --- a/man2/access.2
> +++ b/man2/access.2
> @@ -19,6 +19,8 @@
>  .\" Modified 2002-04-23 by Roger Luethi <rl@hellgate.ch>
>  .\" Modified 2004-06-23 by Michael Kerrisk
>  .\" 2007-06-10, mtk, various parts rewritten, and added BUGS section.
> +.\" Modified 2023-12-09 by Renzo Davoli <renzo@cs.unibo.it>
> +.\"   add AT_EMPTY_PATH flag

We don't use those anymore.  Simply add yourself to Copyright if
appropriate, but for knowing what was written by who, git(1) works
better.

>  .\"
>  .TH access 2 (date) "Linux man-pages (unreleased)"
>  .SH NAME
> @@ -155,6 +157,27 @@ By default,
>  uses the real IDs (like
>  .BR access ()).
>  .TP
> +.BR AT_EMPTY_PATH " (since Linux 5.8)"
> +If
> +.I pathname
> +is an empty string, operate on the file referred to by
> +.I dirfd
> +(which may have been obtained using the
> +.BR open (2)
> +.B O_PATH
> +flag).
> +In this case,
> +.I dirfd
> +can refer to any type of file, not just a directory.
> +If
> +.I dirfd
> +is
> +.BR AT_FDCWD ,
> +the call operates on the current working directory.
> +This flag is Linux-specific; define
> +.B _GNU_SOURCE
> +to obtain its definition.
> +.TP
>  .B AT_SYMLINK_NOFOLLOW
>  If
>  .I pathname
> diff --git a/man2/utimensat.2 b/man2/utimensat.2
> index 495e15cee..29980c464 100644
> --- a/man2/utimensat.2
> +++ b/man2/utimensat.2
> @@ -4,6 +4,9 @@
>  .\"
>  .\" SPDX-License-Identifier: Linux-man-pages-copyleft
>  .\"
> +.\" Modified 2023-12-09 by Renzo Davoli <renzo@cs.unibo.it>
> +.\"     add AT_EMPTY_PATH flag
> +.\"

Same here.

>  .TH utimensat 2 (date) "Linux man-pages (unreleased)"
>  .SH NAME
>  utimensat, futimens \- change file timestamps with nanosecond precision
> @@ -182,10 +185,31 @@ is ignored.
>  .P
>  The
>  .I flags
> -field is a bit mask that may be 0, or include the following constant,
> -defined in
> +argument is a bit mask created by ORing together zero or more of
> +the following values defined in
>  .IR <fcntl.h> :
>  .TP
> +.BR AT_EMPTY_PATH " (since Linux 5.8)"
> +If
> +.I pathname
> +is an empty string, operate on the file referred to by
> +.I dirfd
> +(which may have been obtained using the
> +.BR open (2)
> +.B O_PATH
> +flag).
> +In this case,
> +.I dirfd
> +can refer to any type of file, not just a directory.
> +If
> +.I dirfd
> +is
> +.BR AT_FDCWD ,
> +the call operates on the current working directory.
> +This flag is Linux-specific; define
> +.B _GNU_SOURCE
> +to obtain its definition.
> +.TP

LGTM.

Have a lovely night,
Alex

>  .B AT_SYMLINK_NOFOLLOW
>  If
>  .I pathname


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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]