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

[Renzo Davoli <renzo@cs.unibo.it>]

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

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

[-- Attachment #2: access_utimensat_add_emptypath.patch --]
[-- Type: text/x-diff, Size: 2227 bytes --]

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
 .\"
 .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
+.\"
 .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
 .B AT_SYMLINK_NOFOLLOW
 If
 .I pathname