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

[Alejandro Colomar <alx@kernel.org>]

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