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

Alejandro Colomar
2023-12-09T21:36:23Z

[-- 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/>