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

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

[Renzo Davoli]

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

Dear Alejandro,

utimensat and faccessat support the flag AT_EMPTY_PATH since Linux 5.8 but
this option is still missing in the man pages.

(actually Linux 5.8 added faccessat2: glibc wrapper for faccessat
 uses faccessat2, and faccessat2 does support AT_EMPTY_PATH).

I think the standard text used in many other -at man page could fit
for these system calls, too.

AT_EMPTY_PATH (since Linux 5.8)
	If  pathname is an empty string, operate on the file referred to
	by dirfd (which may have been obtained using the open(2)  O_PATH
	flag).   In  this case, dirfd can refer to any type of file, not
	just a directory.  If dirfd is AT_FDCWD, the  call  operates  on
	the current working directory.  This flag is Linux-specific;
	define _GNU_SOURCE to obtain its definition.

All the best,

	renzo

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

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

[Alejandro Colomar]

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

Dear Renzo,

On Wed, Dec 06, 2023 at 12:04:07PM +0100, Renzo Davoli wrote:
> Dear Alejandro,
> 
> utimensat and faccessat support the flag AT_EMPTY_PATH since Linux 5.8 but
> this option is still missing in the man pages.
> 
> (actually Linux 5.8 added faccessat2: glibc wrapper for faccessat
>  uses faccessat2, and faccessat2 does support AT_EMPTY_PATH).
> 
> I think the standard text used in many other -at man page could fit
> for these system calls, too.
> 
> AT_EMPTY_PATH (since Linux 5.8)
> 	If  pathname is an empty string, operate on the file referred to
> 	by dirfd (which may have been obtained using the open(2)  O_PATH
> 	flag).   In  this case, dirfd can refer to any type of file, not
> 	just a directory.  If dirfd is AT_FDCWD, the  call  operates  on
> 	the current working directory.  This flag is Linux-specific;
> 	define _GNU_SOURCE to obtain its definition.

Thanks for reporting that.  Would you mind preparing a patch updating
the page?  If you need any help, just ask for it.

Cheers,
Alex

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

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

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

[Renzo Davoli]

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

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

[Alejandro Colomar]

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

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

[Renzo Davoli]

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

On Sat, Dec 09, 2023 at 10:36:19PM +0100, Alejandro Colomar wrote:
> Dear Renzo,
> > +.\" Modified 2023-12-09 by Renzo Davoli <renzo@cs.unibo.it>
> 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.

Okay. You'll find here attached the new patch.

ciao
	renzo

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

diff --git a/man2/access.2 b/man2/access.2
index 95de3815d..2b3e70e34 100644
--- a/man2/access.2
+++ b/man2/access.2
@@ -155,6 +155,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..d58b4d82e 100644
--- a/man2/utimensat.2
+++ b/man2/utimensat.2
@@ -182,10 +182,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

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

[Alejandro Colomar]

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

[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:
> > 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.

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

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

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

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

[Renzo Davoli]

Hi Alex,
	great. thank you.
I wish you have a happy new year to you, too.

	renzo

On Mon, Jan 01, 2024 at 12:43:53PM +0100, Alejandro Colomar wrote:
> [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:
> > > 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.
> 
> 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