[RFC v2 0/8] Add at(2) manual page, and refer to it

[RFC v2 0/8] Add at(2) manual page, and refer to it

[Alejandro Colomar]

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

Hi!

Here's a draft of a patch set for adding a centralized at(2) manual page
and using it elsewhere to:

-  De-duplicate documentation about *at() system calls.
-  Make the slight differences more obvious.
-  Have a central specification of how new *at() system calls should
   look like, so that differences don't grow unnecessarily.
-  Try to remove the unnecessary differences, if we can.


Have a lovely day!
Alex

Alejandro Colomar (8):
  man/man3const/_ATFILE_SOURCE.3const: Add page
  man/man2/at.2: Add link page
  man/man2/chown.2: Refer to at(2)
  man/man2/mount_setattr.2: Refer to at(2)
  man/man2/open_tree.2: Refer to at(2)
  man/man2/rename.2: Refer to at(2)
  man/man3const/_ATFILE_SOURCE.3const: Some functions report ESRCH
    instead of EACCES
  man/man2/utimensat.2: Refer to at(2)

 man/man2/at.2                       |   1 +
 man/man2/chown.2                    | 114 ++-----------------
 man/man2/mount_setattr.2            |  66 +++--------
 man/man2/open_tree.2                | 168 ++-------------------------
 man/man2/rename.2                   |  84 +-------------
 man/man2/utimensat.2                | 141 ++---------------------
 man/man3const/_ATFILE_SOURCE.3const | 170 ++++++++++++++++++++++++++++
 7 files changed, 214 insertions(+), 530 deletions(-)
 create mode 100644 man/man2/at.2
 create mode 100644 man/man3const/_ATFILE_SOURCE.3const

Range-diff against v1:
-:  ------------ > 1:  39bf4d24176a man/man3const/_ATFILE_SOURCE.3const: Add page
-:  ------------ > 2:  56086d43dbe4 man/man2/at.2: Add link page
-:  ------------ > 3:  7fdc286a682a man/man2/chown.2: Refer to at(2)
-:  ------------ > 4:  c206656df161 man/man2/mount_setattr.2: Refer to at(2)
-:  ------------ > 5:  4e8ce7b9cf9d man/man2/open_tree.2: Refer to at(2)
-:  ------------ > 6:  8a5ac3f93ba5 man/man2/rename.2: Refer to at(2)
-:  ------------ > 7:  8ae17f3f6863 man/man3const/_ATFILE_SOURCE.3const: Some functions report ESRCH instead of EACCES
-:  ------------ > 8:  3de33c76083e man/man2/utimensat.2: Refer to at(2)
-- 
2.55.0


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

[RFC v2 1/8] man/man3const/_ATFILE_SOURCE.3const: Add page

[Alejandro Colomar]

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

This page documents conventions common to several system calls
(most of them conventionally named ...at()).

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3const/_ATFILE_SOURCE.3const | 168 ++++++++++++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 man/man3const/_ATFILE_SOURCE.3const

diff --git a/man/man3const/_ATFILE_SOURCE.3const b/man/man3const/_ATFILE_SOURCE.3const
new file mode 100644
index 000000000000..d88adf5892c9
--- /dev/null
+++ b/man/man3const/_ATFILE_SOURCE.3const
@@ -0,0 +1,168 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH _ATFILE_SOURCE 3const (date) "Linux man-pages (unreleased)"
+.SH NAME
+_ATFILE_SOURCE \- act on a file at a directory
+.SH SYNOPSIS
+.nf
+.B #define _ATFILE_SOURCE
+.BR "#include <fcntl.h>" "  /* Definition of " AT_* " constants */"
+.fi
+.P
+.nf
+.BI long\~...at(int\~ dirfd ", const\~char\~*" path ", ..., int\~" flags ", ...);"
+.fi
+.SH DESCRIPTION
+The
+.BR \f[I]*\f[]at ()
+system calls perform an action on a file
+specified by the combination of
+.IR dirfd ,
+.IR path ,
+and
+.IR flags .
+.P
+If
+.I path
+is absolute,
+then
+.I dirfd
+is ignored.
+.P
+If
+.I path
+is relative,
+then it is interpreted relative to the directory
+referred to by the file descriptor
+.IR dirfd .
+.P
+If
+.I path
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I path
+is interpreted relative to the current working directory
+of the calling process.
+.P
+The
+.I flags
+argument is a bit mask created by ORing together
+0 or more of the following values
+(some system calls may support more values).
+.TP
+.BR AT_EMPTY_PATH " (since Linux 2.6.39)"
+.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
+If
+.I path
+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
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+.TP
+.B AT_SYMLINK_NOFOLLOW
+If
+.I path
+is a symbolic link,
+do not dereference it:
+instead operate on the link itself.
+.SH ERRORS
+Some common errors for these system calls:
+.TP
+.B EACCES
+Search permission is denied on a component of the path prefix.
+(See also
+.BR path_resolution (7).)
+.TP
+.B EBADF
+.I path
+is relative but
+.I dirfd
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
+.TP
+.B EFAULT
+.I path
+points outside your accessible address space.
+.TP
+.B EINVAL
+Invalid flags specified in
+.IR flags .
+.TP
+.B ELOOP
+Too many symbolic links were encountered in resolving
+.IR path .
+.TP
+.B ENAMETOOLONG
+.I path
+is longer than
+.BR PATH_MAX .
+.TP
+.B ENOENT
+The file does not exist.
+.TP
+.B ENOENT
+.I path
+is an empty string,
+but
+.B AT_EMPTY_PATH
+is not specified in
+.IR flags .
+.TP
+.B ENOENT
+A component of the path prefix is a dangling symbolic link.
+.TP
+.B ENOTDIR
+A component of the path prefix is not a directory.
+.TP
+.B ENOTDIR
+.I path
+is relative and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.SH VERSIONS
+On older kernels where
+these system calls are unavailable,
+the glibc wrapper functions emulate them.
+When
+.I path
+is relative,
+glibc constructs a pathname based on the symbolic link in
+.I /proc/self/fd
+that corresponds to the
+.I dirfd
+argument.
+.SH STANDARDS
+TODO.
+.SH HISTORY
+TODO.
+.SH CAVEATS
+Most of these system calls are named with an 'at' suffix,
+although some new system calls don't have this suffix.
+.SH SEE ALSO
+.BR openat (2),
+.BR feature_test_macros (7),
+.BR path_resolution (7),
+.BR symlink (7)
-- 
2.55.0


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

[RFC v2 2/8] man/man2/at.2: Add link page

[Alejandro Colomar]

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

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/at.2 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man/man2/at.2

diff --git a/man/man2/at.2 b/man/man2/at.2
new file mode 100644
index 000000000000..e8ec02f7324c
--- /dev/null
+++ b/man/man2/at.2
@@ -0,0 +1 @@
+.so man3const/_ATFILE_SOURCE.3const
-- 
2.55.0


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

[RFC v2 3/8] man/man2/chown.2: Refer to at(2)

[Alejandro Colomar]

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

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/chown.2 | 114 ++++-------------------------------------------
 1 file changed, 8 insertions(+), 106 deletions(-)

diff --git a/man/man2/chown.2 b/man/man2/chown.2
index b346e0adb029..ce62312538b4 100644
--- a/man/man2/chown.2
+++ b/man/man2/chown.2
@@ -18,10 +18,6 @@ .SH SYNOPSIS
 .BI "int chown(const char *" path ", uid_t " owner ", gid_t " group );
 .BI "int fchown(int " fd ", uid_t " owner ", gid_t " group );
 .BI "int lchown(const char *" path ", uid_t " owner ", gid_t " group );
-.P
-.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
-.B #include <unistd.h>
-.P
 .BI "int fchownat(int " dirfd ", const char *" path ,
 .BI "             uid_t " owner ", gid_t " group ", int " flags );
 .fi
@@ -116,73 +112,12 @@ .SS fchownat()
 .BR chown (),
 except for the differences described here.
 .P
-If
-.I path
-is relative, then it is interpreted relative to the directory
-referred to by the file descriptor
-.I dirfd
-(rather than relative to the current working directory of
-the calling process, as is done by
-.BR chown ()
-for a relative pathname).
-.P
-If
-.I path
-is relative and
-.I dirfd
-is the special value
-.BR AT_FDCWD ,
-then
-.I path
-is interpreted relative to the current working
-directory of the calling process (like
-.BR chown ()).
-.P
-If
-.I path
-is absolute, then
-.I dirfd
-is ignored.
-.P
-The
+.IR path ,
+.IR dirfd ,
+and
 .I flags
-argument is a bit mask created by ORing together
-0 or more of the following values;
-.TP
-.BR AT_EMPTY_PATH " (since Linux 2.6.39)"
-.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
-If
-.I path
-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
-.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
-to obtain its definition.
-.TP
-.B AT_SYMLINK_NOFOLLOW
-If
-.I path
-is a symbolic link, do not dereference it:
-instead operate on the link itself, like
-.BR lchown ().
-(By default,
-.BR fchownat ()
-dereferences symbolic links, like
-.BR chown ().)
+are interpreted as specified in
+.BR at (2).
 .P
 See
 .BR openat (2)
@@ -194,6 +129,9 @@ .SH RETURN VALUE
 .I errno
 is set to indicate the error.
 .SH ERRORS
+See
+.BR at (2).
+.P
 Depending on the filesystem,
 errors other than those listed below can be returned.
 .P
@@ -211,24 +149,10 @@ .SH ERRORS
 .I fd
 is not a valid open file descriptor.
 .TP
-.B EBADF
-.RB ( fchownat ())
-.I path
-is relative but
-.I dirfd
-is neither
-.B AT_FDCWD
-nor a valid file descriptor.
-.TP
 .B EFAULT
 .I path
 points outside your accessible address space.
 .TP
-.B EINVAL
-.RB ( fchownat ())
-Invalid flag specified in
-.IR flags .
-.TP
 .B EIO
 .RB ( fchown ())
 A low-level I/O error occurred while modifying the inode.
@@ -250,13 +174,6 @@ .SH ERRORS
 .B ENOTDIR
 A component of the path prefix is not a directory.
 .TP
-.B ENOTDIR
-.RB ( fchownat ())
-.I path
-is relative and
-.I dirfd
-is a file descriptor referring to a file other than a directory.
-.TP
 .B EPERM
 The calling process did not have the required permissions
 (see above) to change owner and/or group.
@@ -353,21 +270,6 @@ .SS Ownership of new files
 Filesystems that don't support these mount options follow the
 .B \-o\ nogrpid
 rules.
-.SS glibc notes
-On older kernels where
-.BR fchownat ()
-is unavailable, the glibc wrapper function falls back to the use of
-.BR chown ()
-and
-.BR lchown ().
-When
-.I path
-is relative,
-glibc constructs a pathname based on the symbolic link in
-.I /proc/self/fd
-that corresponds to the
-.I dirfd
-argument.
 .SS NFS
 The
 .BR chown ()
-- 
2.55.0


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

[RFC v2 4/8] man/man2/mount_setattr.2: Refer to at(2)

[Alejandro Colomar]

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

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/mount_setattr.2 | 66 +++++++++-------------------------------
 1 file changed, 15 insertions(+), 51 deletions(-)

diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
index 0f4b619d8f38..809fa582e1ad 100644
--- a/man/man2/mount_setattr.2
+++ b/man/man2/mount_setattr.2
@@ -25,34 +25,16 @@ .SH DESCRIPTION
 .P
 .BR mount_setattr ()
 changes the mount properties of a mount or an entire mount tree.
-If
-.I path
-is relative,
-then it is interpreted relative to
-the directory referred to by the file descriptor
-.IR dirfd .
-If
-.I dirfd
-is the special value
-.BR AT_FDCWD ,
-then
-.I path
-is interpreted relative to
-the current working directory of the calling process.
-If
-.I path
-is the empty string and
-.B AT_EMPTY_PATH
-is specified in
-.IR flags ,
-then the mount properties of the mount identified by
-.I dirfd
-are changed.
-(See
-.BR openat (2)
-for an explanation of why the
-.I dirfd
-argument is useful.)
+.P
+.IR dirfd ,
+.IR path ,
+and
+.I flags
+are interpreted as specified in
+.BR at (2),
+but
+.I flags
+accepts some more values (see below).
 .P
 The
 .BR mount_setattr ()
@@ -96,22 +78,14 @@ .SH DESCRIPTION
 The
 .I flags
 argument can be used to alter the pathname resolution behavior.
+Apart from the values specified in
+.BR at (2),
+the following values are supported:
 The supported values are:
 .TP
-.B AT_EMPTY_PATH
-If
-.I path
-is the empty string,
-change the mount properties on
-.I dirfd
-itself.
-.TP
 .B AT_RECURSIVE
 Change the mount properties of the entire mount tree.
 .TP
-.B AT_SYMLINK_NOFOLLOW
-Don't follow trailing symbolic links.
-.TP
 .B AT_NO_AUTOMOUNT
 Don't trigger automounts.
 .P
@@ -383,14 +357,8 @@ .SH RETURN VALUE
 .I errno
 is set to indicate the error.
 .SH ERRORS
-.TP
-.B EBADF
-.I path
-is relative but
-.I dirfd
-is neither
-.B AT_FDCWD
-nor a valid file descriptor.
+See
+.BR at (2).
 .TP
 .B EBADF
 .I userns_fd
@@ -418,10 +386,6 @@ .SH ERRORS
 isn't a mount point.
 .TP
 .B EINVAL
-An unsupported value was set in
-.IR flags .
-.TP
-.B EINVAL
 An unsupported value was specified in the
 .I attr_set
 field of
-- 
2.55.0


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

Re: [RFC v2 4/8] man/man2/mount_setattr.2: Refer to at(2)

[Andrey Albershteyn]

On 2026-11-07 13:48:02, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>  man/man2/mount_setattr.2 | 66 +++++++++-------------------------------
>  1 file changed, 15 insertions(+), 51 deletions(-)
> 
> diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
> index 0f4b619d8f38..809fa582e1ad 100644
> --- a/man/man2/mount_setattr.2
> +++ b/man/man2/mount_setattr.2
> @@ -25,34 +25,16 @@ .SH DESCRIPTION
>  .P
>  .BR mount_setattr ()
>  changes the mount properties of a mount or an entire mount tree.
> -If
> -.I path
> -is relative,
> -then it is interpreted relative to
> -the directory referred to by the file descriptor
> -.IR dirfd .
> -If
> -.I dirfd
> -is the special value
> -.BR AT_FDCWD ,
> -then
> -.I path
> -is interpreted relative to
> -the current working directory of the calling process.
> -If
> -.I path
> -is the empty string and
> -.B AT_EMPTY_PATH
> -is specified in
> -.IR flags ,
> -then the mount properties of the mount identified by
> -.I dirfd
> -are changed.
> -(See
> -.BR openat (2)
> -for an explanation of why the
> -.I dirfd
> -argument is useful.)
> +.P
> +.IR dirfd ,
> +.IR path ,
> +and
> +.I flags
> +are interpreted as specified in
> +.BR at (2),
> +but
> +.I flags
> +accepts some more values (see below).
>  .P
>  The
>  .BR mount_setattr ()
> @@ -96,22 +78,14 @@ .SH DESCRIPTION
>  The
>  .I flags
>  argument can be used to alter the pathname resolution behavior.
> +Apart from the values specified in
> +.BR at (2),
> +the following values are supported:
>  The supported values are:
   ^^^^^^^^^^^^^^^^^^^^^^^^^

this needs to be removed too

-- 
- Andrey

[RFC v2 5/8] man/man2/open_tree.2: Refer to at(2)

[Alejandro Colomar]

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

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/open_tree.2 | 168 +++----------------------------------------
 1 file changed, 8 insertions(+), 160 deletions(-)

diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2
index 3e587f7be14b..9afca6ef91a2 100644
--- a/man/man2/open_tree.2
+++ b/man/man2/open_tree.2
@@ -115,110 +115,17 @@ .SH DESCRIPTION
 is included in
 .IR flags .
 .P
-As with "*at()" system calls,
-.BR open_tree ()
-uses the
-.I dirfd
-argument in conjunction with the
-.I path
-argument to determine the path to operate on, as follows:
-.IP \[bu] 3
-If the pathname given in
-.I path
-is absolute, then
-.I dirfd
-is ignored.
-.IP \[bu]
-If the pathname given in
-.I path
-is relative and
-.I dirfd
-is the special value
-.BR \%AT_FDCWD ,
-then
-.I path
-is interpreted relative to
-the current working directory
-of the calling process (like
-.BR open (2)).
-.IP \[bu]
-If the pathname given in
-.I path
-is relative,
-then it is interpreted relative to
-the directory referred to by the file descriptor
-.I dirfd
-(rather than relative to
-the current working directory
-of the calling process,
-as is done by
-.BR open (2)
-for a relative pathname).
-In this case,
-.I dirfd
-must be a directory
-that was opened for reading
-.RB ( \%O_RDONLY )
-or using the
-.B O_PATH
-flag.
-.IP \[bu]
-If
-.I path
-is an empty string,
+.IR dirfd ,
+.IR path ,
 and
 .I flags
-contains
-.BR \%AT_EMPTY_PATH ,
-then the file descriptor
-.I dirfd
-is operated on directly.
-In this case,
-.I dirfd
-may refer to any type of file,
-not just a directory.
-.P
-See
-.BR openat (2)
-for an explanation of why the
-.I dirfd
-argument is useful.
-.P
+are interpreted as specified in
+.BR at (2),
+but
 .I flags
-can be used to control aspects of the path lookup
-and properties of the returned file descriptor.
-A value for
-.I flags
-is constructed by bitwise ORing
-zero or more of the following constants:
+accepts some more values:
 .RS
 .TP
-.B \%AT_EMPTY_PATH
-If
-.I path
-is an empty string, operate on the file referred to by
-.I dirfd
-(which may have been obtained from
-.BR open (2),
-.BR fsmount (2),
-or from another
-.BR open_tree ()
-call).
-In this case,
-.I dirfd
-may refer to any type of file, not just a directory.
-If
-.I dirfd
-is
-.BR \%AT_FDCWD ,
-.BR open_tree ()
-will operate on the current working directory
-of the calling process.
-This flag is Linux-specific;
-define
-.B \%_GNU_SOURCE
-to obtain its definition.
-.TP
 .B \%AT_NO_AUTOMOUNT
 Do not automount the terminal ("basename") component of
 .I path
@@ -231,18 +138,6 @@ .SH DESCRIPTION
 .B \%_GNU_SOURCE
 to obtain its definition.
 .TP
-.B \%AT_SYMLINK_NOFOLLOW
-If
-.I path
-is a symbolic link, do not dereference it;
-instead,
-create either a handle to the link itself
-or a bind-mount of it.
-The resultant file descriptor is indistinguishable from one produced by
-.BR openat (2)
-with
-.BR \%O_PATH | O_NOFOLLLOW .
-.TP
 .B \%OPEN_TREE_CLOEXEC
 Set the close-on-exec
 .RB ( FD_CLOEXEC )
@@ -404,21 +299,8 @@ .SH RETURN VALUE
 .I errno
 is set to indicate the error.
 .SH ERRORS
-.TP
-.B EACCES
-Search permission is denied for one of the directories
-in the path prefix of
-.IR path .
-(See also
-.BR path_resolution (7).)
-.TP
-.B EBADF
-.I path
-is relative but
-.I dirfd
-is neither
-.B \%AT_FDCWD
-nor a valid file descriptor.
+See
+.BR at (2).
 .TP
 .B EFAULT
 .I path
@@ -426,46 +308,12 @@ .SH ERRORS
 or a pointer to a location
 outside the calling process's accessible address space.
 .TP
-.B EINVAL
-Invalid flag specified in
-.IR flags .
-.TP
-.B ELOOP
-Too many symbolic links encountered when resolving
-.IR path .
-.TP
 .B EMFILE
 The calling process has too many open files to create more.
 .TP
-.B ENAMETOOLONG
-.I path
-is longer than
-.BR PATH_MAX .
-.TP
 .B ENFILE
 The system has too many open files to create more.
 .TP
-.B ENOENT
-A component of
-.I path
-does not exist, or is a dangling symbolic link.
-.TP
-.B ENOENT
-.I path
-is an empty string, but
-.B AT_EMPTY_PATH
-is not specified in
-.IR flags .
-.TP
-.B ENOTDIR
-A component of the path prefix of
-.I path
-is not a directory, or
-.I path
-is relative and
-.I dirfd
-is a file descriptor referring to a file other than a directory.
-.TP
 .B ENOSPC
 The "anonymous" mount namespace
 necessary to contain the
-- 
2.55.0


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

Re: [RFC v2 5/8] man/man2/open_tree.2: Refer to at(2)

[Andrey Albershteyn]

On 2026-11-07 13:48:06, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>  man/man2/open_tree.2 | 168 +++----------------------------------------
>  1 file changed, 8 insertions(+), 160 deletions(-)
> 
> diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2
> index 3e587f7be14b..9afca6ef91a2 100644
> --- a/man/man2/open_tree.2
> +++ b/man/man2/open_tree.2
> @@ -115,110 +115,17 @@ .SH DESCRIPTION
>  is included in
>  .IR flags .
>  .P
> -As with "*at()" system calls,
> -.BR open_tree ()

Won't it better to restructure it a bit then, the man page seems to
start with description of custom flags cases, then describes dirfd,
path, flags from *at() and then jumps back to list of custom flags.

Maybe start with dirfd, path, flags then list of custom flags and
then the custom flag cases.

-- 
- Andrey

[RFC v2 6/8] man/man2/rename.2: Refer to at(2)

[Alejandro Colomar]

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

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/rename.2 | 84 +++--------------------------------------------
 1 file changed, 5 insertions(+), 79 deletions(-)

diff --git a/man/man2/rename.2 b/man/man2/rename.2
index 7e5c02797230..87f49ba851d7 100644
--- a/man/man2/rename.2
+++ b/man/man2/rename.2
@@ -16,10 +16,6 @@ .SH SYNOPSIS
 .B #include <stdio.h>
 .P
 .BI "int rename(const char *" oldpath ", const char *" newpath );
-.P
-.BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
-.B #include <stdio.h>
-.P
 .BI "int renameat(int " olddirfd ", const char *" oldpath ,
 .BI "             int " newdirfd ", const char *" newpath );
 .BI "int renameat2(int " olddirfd ", const char *" oldpath ,
@@ -96,52 +92,10 @@ .SH DESCRIPTION
 .I newpath
 refers to a symbolic link, the link will be overwritten.
 .SS renameat()
-The
+The file descriptor and path arguments of
 .BR renameat ()
-system call operates in exactly the same way as
-.BR rename (),
-except for the differences described here.
-.P
-If the pathname given in
-.I oldpath
-is relative, then it is interpreted relative to the directory
-referred to by the file descriptor
-.I olddirfd
-(rather than relative to the current working directory of
-the calling process, as is done by
-.BR rename ()
-for a relative pathname).
-.P
-If
-.I oldpath
-is relative and
-.I olddirfd
-is the special value
-.BR AT_FDCWD ,
-then
-.I oldpath
-is interpreted relative to the current working
-directory of the calling process (like
-.BR rename ()).
-.P
-If
-.I oldpath
-is absolute, then
-.I olddirfd
-is ignored.
-.P
-The interpretation of
-.I newpath
-is as for
-.IR oldpath ,
-except that a relative pathname is interpreted relative
-to the directory referred to by the file descriptor
-.IR newdirfd .
-.P
-See
-.BR openat (2)
-for an explanation of the need for
-.BR renameat ().
+are interpreted as specified in
+.BR at (2).
 .SS renameat2()
 .BR renameat2 ()
 has an additional
@@ -274,25 +228,20 @@ .SH RETURN VALUE
 .I errno
 is set to indicate the error.
 .SH ERRORS
+See
+.BR at (2).
 .TP
 .B EACCES
 Write permission is denied for the directory containing
 .I oldpath
 or
 .IR newpath ,
-or, search permission is denied for one of the directories
-in the path prefix of
-.I oldpath
-or
-.IR newpath ,
 or
 .I oldpath
 is a directory and does not allow write permission (needed to update
 the
 .I ..
 entry).
-(See also
-.BR path_resolution (7).)
 .TP
 .B EBUSY
 The rename fails because
@@ -411,29 +360,6 @@ .SH ERRORS
 even if the same filesystem is mounted on both.)
 .P
 The following additional errors can occur for
-.BR renameat ()
-and
-.BR renameat2 ():
-.TP
-.B EBADF
-.I oldpath
-.RI ( newpath )
-is relative but
-.I olddirfd
-.RI ( newdirfd )
-is not a valid file descriptor.
-.TP
-.B ENOTDIR
-.I oldpath
-is relative and
-.I olddirfd
-is a file descriptor referring to a file other than a directory;
-or similar for
-.I newpath
-and
-.I newdirfd
-.P
-The following additional errors can occur for
 .BR renameat2 ():
 .TP
 .B EEXIST
-- 
2.55.0


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

[RFC v2 7/8] man/man3const/_ATFILE_SOURCE.3const: Some functions report ESRCH instead of EACCES

[Alejandro Colomar]

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

For example, utimensat(2).

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3const/_ATFILE_SOURCE.3const | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/man/man3const/_ATFILE_SOURCE.3const b/man/man3const/_ATFILE_SOURCE.3const
index d88adf5892c9..183ca7cc7447 100644
--- a/man/man3const/_ATFILE_SOURCE.3const
+++ b/man/man3const/_ATFILE_SOURCE.3const
@@ -91,6 +91,8 @@ .SH ERRORS
 Some common errors for these system calls:
 .TP
 .B EACCES
+.TQ
+.B ESCRH
 Search permission is denied on a component of the path prefix.
 (See also
 .BR path_resolution (7).)
-- 
2.55.0


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

[RFC v2 8/8] man/man2/utimensat.2: Refer to at(2)

[Alejandro Colomar]

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

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/utimensat.2 | 141 +++----------------------------------------
 1 file changed, 7 insertions(+), 134 deletions(-)

diff --git a/man/man2/utimensat.2 b/man/man2/utimensat.2
index bd512d48d938..fb6fe5d54872 100644
--- a/man/man2/utimensat.2
+++ b/man/man2/utimensat.2
@@ -11,7 +11,6 @@ .SH LIBRARY
 .RI ( libc ,\~ \-lc )
 .SH SYNOPSIS
 .nf
-.BR "#include <fcntl.h>" "            /* Definition of " AT_* " constants */"
 .B #include <sys/stat.h>
 .P
 .BI "int utimensat(int " dirfd ", const char *" path ,
@@ -150,71 +149,13 @@ .SS Permissions requirements
 but other error conditions may still be detected.
 .\"
 .\"
-.SS utimensat() specifics
-If
-.I path
-is relative, then by default it is interpreted relative to the
-directory referred to by the open file descriptor,
-.I dirfd
-(rather than relative to the current working directory of
-the calling process, as is done by
-.BR utimes (2)
-for a relative pathname).
-See
-.BR openat (2)
-for an explanation of why this can be useful.
-.P
-If
-.I path
-is relative and
-.I dirfd
-is the special value
-.BR AT_FDCWD ,
-then
-.I path
-is interpreted relative to the current working
-directory of the calling process (like
-.BR utimes (2)).
-.P
-If
-.I path
-is absolute, then
-.I dirfd
-is ignored.
-.P
-The
+.SS utimensat()
+.IR dirfd ,
+.IR path ,
+and
 .I flags
-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 path
-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 path
-specifies a symbolic link, then update the timestamps of the link,
-rather than the file to which it refers.
+are interpreted as specified in
+.BR at (2).
 .SH RETURN VALUE
 On success,
 .BR utimensat ()
@@ -270,29 +211,9 @@ .SH ERRORS
 .I fd
 is not a valid file descriptor.
 .TP
-.B EBADF
-.RB ( utimensat ())
-.I path
-is relative but
-.I dirfd
-is neither
-.B AT_FDCWD
-nor a valid file descriptor.
-.TP
 .B EFAULT
 .I times
-pointed to an invalid address;
-or,
-.I dirfd
-was
-.BR AT_FDCWD ,
-and
-.I path
-is NULL or an invalid address.
-.TP
-.B EINVAL
-Invalid value in
-.IR flags .
+pointed to an invalid address.
 .TP
 .B EINVAL
 Invalid value in one of the
@@ -305,49 +226,6 @@ .SH ERRORS
 .I tv_sec
 fields.
 .TP
-.B EINVAL
-.\" SUSv4 does not specify this error.
-.I path
-is NULL,
-.I dirfd
-is not
-.BR AT_FDCWD ,
-and
-.I flags
-contains
-.BR AT_SYMLINK_NOFOLLOW .
-.TP
-.B ELOOP
-.RB ( utimensat ())
-Too many symbolic links were encountered in resolving
-.IR path .
-.TP
-.B ENAMETOOLONG
-.RB ( utimensat ())
-.I path
-is too long.
-.TP
-.B ENOENT
-.RB ( utimensat ())
-A component of
-.I path
-does not refer to an existing directory or file,
-or
-.I path
-is an empty string.
-.TP
-.B ENOTDIR
-.RB ( utimensat ())
-.I path
-is relative, but
-.I dirfd
-is neither
-.B AT_FDCWD
-nor a file descriptor referring to a directory;
-or, one of the prefix components of
-.I path
-is not a directory.
-.TP
 .B EPERM
 The caller attempted to change one or both timestamps to a value
 other than the current time,
@@ -389,11 +267,6 @@ .SH ERRORS
 .TP
 .B EROFS
 The file is on a read-only filesystem.
-.TP
-.B ESRCH
-.RB ( utimensat ())
-Search permission is denied for one of the prefix components of
-.IR path .
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).
-- 
2.55.0


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