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

From
Alejandro Colomar <alx@kernel.org>
Date
2026-11-07 12:48:21
Also in
linux-fsdevel, linux-man
Reply to
Alejandro Colomar, 2026-11-07
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

Attachments

Thread (17 messages) 17 messages, 3 authors, last reply 8d ago
Keyboard shortcuts
hback out one level
jnext message in thread / next series-diff position
kprevious message in thread / previous series-diff position
ldrill in
Escclose help / fold thread tree
?toggle this help