[RFC v1] man/man2/at.2: Add page

[RFC v1] man/man2/at.2: Add page

[Alejandro Colomar]

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

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

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi!

We have a lot of repeated documentation about these system calls, and
each one has sligght differences, and some syscalls even have actual
behavior differences (such as some accepting NULL, other not, and others
documenting that not while they most likely accept NULL).

This documentation aims to unify the behavior of as many at() syscalls
as possible, and document the odd ones explicitly so that differences
are known and justified.

If you maintain or know of system calls that don't behave as specified
in this page, I'm very interested in having a disussion about them.

If you know some mistake in this page (for example, I have not yet
documented anything about NULL, because I want to have a discussion
about it), please also let me know.

I'll reply to this email with a copy of the manual page as it looks when
formatted, so you don't need to apply the patch to be able to read it.


Have a lovely night!
Alex

 man/man2/at.2 | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 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..3d50e92420cd
--- /dev/null
+++ b/man/man2/at.2
@@ -0,0 +1,166 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH at 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+at \- identify a file at directory specified by file descriptor
+.SH SYNOPSIS
+.nf
+.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 path_resolution (7),
+.BR symlink (7)
-- 
2.55.0


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

Re: [RFC v1] man/man2/at.2: Add page

[Alejandro Colomar]

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

at(2)                 System Calls Manual                 at(2)

NAME
     at  -  identify  a file at directory specified by file de‐
     scriptor

SYNOPSIS
     #include <fcntl.h>  /* Definition of AT_* constants */

     long ...at(int dirfd, const char *path, ..., int flags, ...);

DESCRIPTION
     The *at() system calls perform an action on a file  speci‐
     fied by the combination of dirfd, path, and flags.

     If path is absolute, then dirfd is ignored.

     If  path  is  relative, then it is interpreted relative to
     the directory referred to by the file descriptor dirfd.

     If path is relative and dirfd is the special value  AT_FD‐
     CWD,  then  path  is  interpreted  relative to the current
     working directory of the calling process.

     The flags argument is a bit mask created by ORing together
     0 or more of the following values (some system  calls  may
     support more values).

     AT_EMPTY_PATH (since Linux 2.6.39)
            If path is an empty string, operate on the file re‐
            ferred  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 di‐
            rectory.   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.

     AT_SYMLINK_NOFOLLOW
            If path is a symbolic link, do not dereference  it:
            instead operate on the link itself.

ERRORS
     Some common errors for these system calls:

     EACCES
            Search  permission  is denied on a component of the
            path prefix.  (See also path_resolution(7).)

     EBADF  path is relative but dirfd is neither AT_FDCWD  nor
            a valid file descriptor.

     EFAULT
            path points outside your accessible address space.

     EINVAL
            Invalid flags specified in flags.

     ELOOP  Too many symbolic links were encountered in resolv‐
            ing path.

     ENAMETOOLONG
            path is longer than PATH_MAX.

     ENOENT
            The file does not exist.

     ENOENT
            path  is  an empty string, but AT_EMPTY_PATH is not
            specified in flags.

     ENOENT
            A component of the path prefix is a  dangling  sym‐
            bolic link.

     ENOTDIR
            A component of the path prefix is not a directory.

     ENOTDIR
            path is relative and dirfd is a file descriptor re‐
            ferring to a file other than a directory.

VERSIONS
     On older kernels where these system calls are unavailable,
     the  glibc  wrapper  functions emulate them.  When path is
     relative, glibc constructs a pathname based  on  the  sym‐
     bolic  link in /proc/self/fd that corresponds to the dirfd
     argument.

STANDARDS
     TODO.

HISTORY
     TODO.

CAVEATS
     Most of these system calls are named with an 'at'  suffix,
     although some new system calls don't have this suffix.

SEE ALSO
     openat(2), path_resolution(7), symlink(7)

Linux man-pages (unreleased) (date)                       at(2)

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

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

Re: [RFC v1] man/man2/at.2: Add page

[Alejandro Colomar]

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

Hi,

> Date: 2026-10-23 19:42:09+0200
> From: Alejandro Colomar <alx+linux-man@kernel.org>
>
> at(2)                 System Calls Manual                 at(2)
> 
> NAME
>      at  -  identify  a file at directory specified by file de‐
>      scriptor
> 

Since there's the _ATFILE_SOURCE macro in glibc, I was wondering whether
the page should be _ATFILE_SOURCE(2const).


Cheers,
Alex

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

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

Re: [RFC v1] man/man2/at.2: Add page

[Andrey Albershteyn]

On 2026-10-23 19:40:37, Alejandro Colomar wrote:
> This page documents conventions common to several system calls
> (most of them conventionally named ...at()).
> 
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
> 
> Hi!
> 
> We have a lot of repeated documentation about these system calls, and
> each one has sligght differences, and some syscalls even have actual
> behavior differences (such as some accepting NULL, other not, and others
> documenting that not while they most likely accept NULL).
> 
> This documentation aims to unify the behavior of as many at() syscalls
> as possible, and document the odd ones explicitly so that differences
> are known and justified.
> 
> If you maintain or know of system calls that don't behave as specified
> in this page, I'm very interested in having a disussion about them.
> 
> If you know some mistake in this page (for example, I have not yet
> documented anything about NULL, because I want to have a discussion
> about it), please also let me know.
> 
> I'll reply to this email with a copy of the manual page as it looks when
> formatted, so you don't need to apply the patch to be able to read it.
> 
> 
> Have a lovely night!
> Alex
> 

Looks good to me, this should probably be a series including patches
which update other man pages to reference this. Wouldn't it be
better to describe differences on the pages itself, for examples,
for file_attr:

	The dirfd, path and flags arguments are described in *at()*,
	with following discrepancy - NULL value could be used for
	path argument meaning empty string.

-- 
- Andrey

Re: [RFC v1] man/man2/at.2: Add page

[Alejandro Colomar]

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

Hi Andrey,

> Date: 2026-10-26 13:27:16+0100
> From: Andrey Albershteyn <aalbersh@kernel.org>
>
> On 2026-10-23 19:40:37, Alejandro Colomar wrote:
> > This page documents conventions common to several system calls
> > (most of them conventionally named ...at()).
> > 
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > ---
> > 
> > Hi!
> > 
> > We have a lot of repeated documentation about these system calls, and
> > each one has sligght differences, and some syscalls even have actual
> > behavior differences (such as some accepting NULL, other not, and others
> > documenting that not while they most likely accept NULL).
> > 
> > This documentation aims to unify the behavior of as many at() syscalls
> > as possible, and document the odd ones explicitly so that differences
> > are known and justified.
> > 
> > If you maintain or know of system calls that don't behave as specified
> > in this page, I'm very interested in having a disussion about them.
> > 
> > If you know some mistake in this page (for example, I have not yet
> > documented anything about NULL, because I want to have a discussion
> > about it), please also let me know.
> > 
> > I'll reply to this email with a copy of the manual page as it looks when
> > formatted, so you don't need to apply the patch to be able to read it.
> > 
> > 
> > Have a lovely night!
> > Alex
> > 
> 
> Looks good to me, this should probably be a series including patches
> which update other man pages to reference this. Wouldn't it be
> better to describe differences on the pages itself, for examples,
> for file_attr:
> 
> 	The dirfd, path and flags arguments are described in *at()*,
> 	with following discrepancy - NULL value could be used for
> 	path argument meaning empty string.

Agree; I'm working on patching pages to refer to this one.

And also agree: the differences should be stated in each page, and
avoided in the main at(2) page.

However, we should minimize differences.  And also, there are
differences that are currently undocumented, and we should discover
them (by asking someone who knows, I guess).  Who is the right person to
be CCed on this?  Do you know anyone who's been working in at()
functions heavily?

I'll send a v2, with some pages being updated (still incomplete).


Have a lovely day!
Alex

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

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

Re: [RFC v1] man/man2/at.2: Add page

[Andrey Albershteyn]

On 2026-10-26 16:42:46, Alejandro Colomar wrote:
> ...
> 
> Agree; I'm working on patching pages to refer to this one.
> 
> And also agree: the differences should be stated in each page, and
> avoided in the main at(2) page.
> 
> However, we should minimize differences.  And also, there are
> differences that are currently undocumented, and we should discover
> them (by asking someone who knows, I guess).  Who is the right person to
> be CCed on this?  Do you know anyone who's been working in at()
> functions heavily?

no

-- 
- Andrey

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

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

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

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

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