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

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

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