Thread (2 messages) 2 messages, 2 authors, 2024-01-01

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

From: Alejandro Colomar <alx@kernel.org>
Date: 2024-01-01 11:43:57

Possibly related (same subject, not in this thread)

[CCing again linux-man@]

Dear Renzo,

On Sat, Dec 09, 2023 at 05:37:21PM +0100, Renzo Davoli wrote:
Dear Alex,

On Sat, Dec 09, 2023 at 01:00:08PM +0100, Alejandro Colomar wrote:
quoted
On Wed, Dec 06, 2023 at 12:04:07PM +0100, Renzo Davoli wrote:
quoted
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.
Normally, you should send a patch with a commit message (as formatted by
git-format-patch(1)).  However, I've written something based on your
original mail, so you don't need to do it.  I also signed it with your
name.

Patch applied here:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=26cdb3ebb2f6bd5a0c947bcf46e35b7c07759632>

Thanks!

Have a lovely year,
Alex

All the Best and Happy Hacking.
ciao

	renzo
quoted hunk
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

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.
  


  
Attachments

  

    
  

  
    

      

        Keyboard shortcuts
      

      

        
          
hback out one level

          
jnext message in thread

          
kprevious message in thread

          
ldrill in

          
Escclose help / fold thread tree

          
?toggle this help