.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group );
.BI "int fchown(int " fd ", uid_t " owner ", gid_t " group );
.BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int fchownat(int " dirfd ", const char *" pathname ,
.BI " uid_t " owner ", gid_t " group ", int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fchown (),
.BR lchown ():
.nf
/* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
|| _XOPEN_SOURCE >= 500
.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
- || /* Glibc <= 2.19: */ _BSD_SOURCE
+ || /* glibc <= 2.19: */ _BSD_SOURCE
.fi
-.PP
+.P
.BR fchownat ():
.nf
Since glibc 2.10:
and
.BR lchown ()
system calls differ only in how the file is specified:
-.IP \(bu 3
+.IP \[bu] 3
.BR chown ()
changes the ownership of the file specified by
.IR pathname ,
which is dereferenced if it is a symbolic link.
-.IP \(bu
+.IP \[bu]
.BR fchown ()
changes the ownership of the file referred to by the open file descriptor
.IR fd .
-.IP \(bu
+.IP \[bu]
.BR lchown ()
is like
.BR chown (),
but does not dereference symbolic links.
-.PP
+.P
Only a privileged process (Linux: one with the
.B CAP_CHOWN
capability) may change the owner of a file.
A privileged process (Linux: with
.BR CAP_CHOWN )
may change the group arbitrarily.
-.PP
+.P
If the
.I owner
or
.I group
is specified as \-1, then that ID is not changed.
-.PP
+.P
When the owner or group of an executable file is
changed by an unprivileged user, the
.B S_ISUID
.B S_ISGID
bit indicates mandatory locking, and is not cleared by a
.BR chown ().
-.PP
+.P
When the owner or group of an executable file is changed (by any user),
all capability sets for the file are cleared.
.\"
system call operates in exactly the same way as
.BR chown (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR chown ()
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR chown ()).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
The
.I flags
argument is a bit mask created by ORing together
.BR fchownat ()
dereferences symbolic links, like
.BR chown ().)
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
.SH ERRORS
Depending on the filesystem,
errors other than those listed below can be returned.
-.PP
+.P
The more general errors for
.BR chown ()
are listed below.
.B EROFS
The named file resides on a read-only filesystem.
.SH VERSIONS
-.BR fchownat ()
-was added in Linux 2.6.16;
-library support was added in glibc 2.4.
-.SH STANDARDS
-.BR chown (),
-.BR fchown (),
-.BR lchown ():
-4.4BSD, SVr4, POSIX.1-2001, POSIX.1-2008.
-.PP
The 4.4BSD version can be
used only by the superuser (that is, ordinary users cannot give away files).
.\" chown():
.\" fchown():
.\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
.\" error conditions.
-.PP
-.BR fchownat ():
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR chown ()
+.TQ
+.BR fchown ()
+.TQ
+.BR lchown ()
+4.4BSD, SVr4, POSIX.1-2001.
+.TP
+.BR fchownat ()
POSIX.1-2008.
+Linux 2.6.16,
+glibc 2.4.
.SH NOTES
.SS Ownership of new files
When a new file is created (by, for example,
.BR "\-o\ sysvgroups" )
.BR mount (8)
options, then the rules are as follows:
-.IP \(bu 3
+.IP \[bu] 3
If the filesystem is mounted with
.BR "\-o\ grpid" ,
then the group of a new file is made
the same as that of the parent directory.
-.IP \(bu
+.IP \[bu]
If the filesystem is mounted with
.B \-o\ nogrpid
and the set-group-ID bit is disabled on the parent directory,
then the group of a new file is made the same as the
process's filesystem GID.
-.IP \(bu
+.IP \[bu]
If the filesystem is mounted with
.B \-o\ nogrpid
and the set-group-ID bit is enabled on the parent directory,
then the group of a new file is made
the same as that of the parent directory.
-.PP
+.P
As at Linux 4.12,
the
.B \-o\ grpid
Filesystems that don't support these mount options follow the
.B \-o\ nogrpid
rules.
-.SS Glibc notes
+.SS glibc notes
On older kernels where
.BR fchownat ()
is unavailable, the glibc wrapper function falls back to the use of
and
.BR lchown ()
wrapper functions transparently deal with the variations across kernel versions.
-.PP
+.P
Before Linux 2.1.81 (except 2.1.46),
.BR chown ()
did not follow symbolic links.
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
-
+\&
int
main(int argc, char *argv[])
{
char *endptr;
uid_t uid;
struct passwd *pwd;
-
- if (argc != 3 || argv[1][0] == \(aq\e0\(aq) {
+\&
+ if (argc != 3 || argv[1][0] == \[aq]\e0\[aq]) {
fprintf(stderr, "%s <owner> <file>\en", argv[0]);
exit(EXIT_FAILURE);
}
-
+\&
uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */
-
- if (*endptr != \(aq\e0\(aq) { /* Was not pure numeric string */
+\&
+ if (*endptr != \[aq]\e0\[aq]) { /* Was not pure numeric string */
pwd = getpwnam(argv[1]); /* Try getting UID for username */
if (pwd == NULL) {
perror("getpwnam");
exit(EXIT_FAILURE);
}
-
+\&
uid = pwd\->pw_uid;
}
-
+\&
if (chown(argv[2], uid, \-1) == \-1) {
perror("chown");
exit(EXIT_FAILURE);
}
-
+\&
exit(EXIT_SUCCESS);
}
.EE
projects / thirdparty / man-pages.git / blobdiff