[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