summaryrefslogtreecommitdiffstats
path: root/man2/chown.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/chown.2')
-rw-r--r--man2/chown.2471
1 files changed, 471 insertions, 0 deletions
diff --git a/man2/chown.2 b/man2/chown.2
new file mode 100644
index 0000000..ff7c6dd
--- /dev/null
+++ b/man2/chown.2
@@ -0,0 +1,471 @@
+.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
+.\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl)
+.\" and Copyright (c) 2006, 2007, 2008, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified by Michael Haardt <michael@moria.de>
+.\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
+.\" Modified 1996-07-09 by Andries Brouwer <aeb@cwi.nl>
+.\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 1997-05-18 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
+.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\" 2007-07-08, mtk, added an example program; updated SYNOPSIS
+.\" 2008-05-08, mtk, Describe rules governing ownership of new files
+.\" (bsdgroups versus sysvgroups, and the effect of the parent
+.\" directory's set-group-ID mode bit).
+.\"
+.TH chown 2 2023-05-03 "Linux man-pages 6.05.01"
+.SH NAME
+chown, fchown, lchown, fchownat \- change ownership of a file
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.PP
+.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
+.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
+.B #include <unistd.h>
+.PP
+.BI "int fchownat(int " dirfd ", const char *" pathname ,
+.BI " uid_t " owner ", gid_t " group ", int " flags );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.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
+.fi
+.PP
+.BR fchownat ():
+.nf
+ Since glibc 2.10:
+ _POSIX_C_SOURCE >= 200809L
+ Before glibc 2.10:
+ _ATFILE_SOURCE
+.fi
+.SH DESCRIPTION
+These system calls change the owner and group of a file.
+The
+.BR chown (),
+.BR fchown (),
+and
+.BR lchown ()
+system calls differ only in how the file is specified:
+.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]
+.BR fchown ()
+changes the ownership of the file referred to by the open file descriptor
+.IR fd .
+.IP \[bu]
+.BR lchown ()
+is like
+.BR chown (),
+but does not dereference symbolic links.
+.PP
+Only a privileged process (Linux: one with the
+.B CAP_CHOWN
+capability) may change the owner of a file.
+The owner of a file may change the group of the file
+to any group of which that owner is a member.
+A privileged process (Linux: with
+.BR CAP_CHOWN )
+may change the group arbitrarily.
+.PP
+If the
+.I owner
+or
+.I group
+is specified as \-1, then that ID is not changed.
+.PP
+When the owner or group of an executable file is
+changed by an unprivileged user, the
+.B S_ISUID
+and
+.B S_ISGID
+mode bits are cleared.
+POSIX does not specify whether
+this also should happen when root does the
+.BR chown ();
+the Linux behavior depends on the kernel version,
+and since Linux 2.2.13, root is treated like other users.
+.\" In Linux 2.0 kernels, superuser was like everyone else
+.\" In Linux 2.2, up to Linux 2.2.12, these bits were not cleared for superuser.
+.\" Since Linux 2.2.13, superuser is once more like everyone else.
+In case of a non-group-executable file (i.e., one for which the
+.B S_IXGRP
+bit is not set) the
+.B S_ISGID
+bit indicates mandatory locking, and is not cleared by a
+.BR chown ().
+.PP
+When the owner or group of an executable file is changed (by any user),
+all capability sets for the file are cleared.
+.\"
+.SS fchownat()
+The
+.BR fchownat ()
+system call operates in exactly the same way as
+.BR chown (),
+except for the differences described here.
+.PP
+If the pathname given in
+.I pathname
+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).
+.PP
+If
+.I pathname
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR chown ()).
+.PP
+If
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+.PP
+The
+.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 pathname
+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 pathname
+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 ().)
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR fchownat ().
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+Depending on the filesystem,
+errors other than those listed below can be returned.
+.PP
+The more general errors for
+.BR chown ()
+are listed below.
+.TP
+.B EACCES
+Search permission is denied on a component of the path prefix.
+(See also
+.BR path_resolution (7).)
+.TP
+.B EBADF
+.RB ( fchown ())
+.I fd
+is not a valid open file descriptor.
+.TP
+.B EBADF
+.RB ( fchownat ())
+.I pathname
+is relative but
+.I dirfd
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
+.TP
+.B EFAULT
+.I pathname
+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.
+.TP
+.B ELOOP
+Too many symbolic links were encountered in resolving
+.IR pathname .
+.TP
+.B ENAMETOOLONG
+.I pathname
+is too long.
+.TP
+.B ENOENT
+The file does not exist.
+.TP
+.B ENOMEM
+Insufficient kernel memory was available.
+.TP
+.B ENOTDIR
+A component of the path prefix is not a directory.
+.TP
+.B ENOTDIR
+.RB ( fchownat ())
+.I pathname
+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.
+.TP
+.B EPERM
+The file is marked immutable or append-only.
+(See
+.BR ioctl_iflags (2).)
+.TP
+.B EROFS
+The named file resides on a read-only filesystem.
+.SH VERSIONS
+The 4.4BSD version can be
+used only by the superuser (that is, ordinary users cannot give away files).
+.\" chown():
+.\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no
+.\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions.
+.\" fchown():
+.\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
+.\" error conditions.
+.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 open (2)
+or
+.BR mkdir (2)),
+its owner is made the same as the filesystem user ID of the
+creating process.
+The group of the file depends on a range of factors,
+including the type of filesystem,
+the options used to mount the filesystem,
+and whether or not the set-group-ID mode bit is enabled
+on the parent directory.
+If the filesystem supports the
+.B "\-o\ grpid"
+(or, synonymously
+.BR "\-o\ bsdgroups" )
+and
+.B "\-o\ nogrpid"
+(or, synonymously
+.BR "\-o\ sysvgroups" )
+.BR mount (8)
+options, then the rules are as follows:
+.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]
+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]
+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
+As at Linux 4.12,
+the
+.B \-o\ grpid
+and
+.B \-o\ nogrpid
+mount options are supported by ext2, ext3, ext4, and XFS.
+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 pathname
+is a relative pathname,
+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 ()
+semantics are deliberately violated on NFS filesystems
+which have UID mapping enabled.
+Additionally, the semantics of all system
+calls which access the file contents are violated, because
+.BR chown ()
+may cause immediate access revocation on already open files.
+Client side
+caching may lead to a delay between the time where ownership have
+been changed to allow access for a user and the time where the file can
+actually be accessed by the user on other clients.
+.SS Historical details
+The original Linux
+.BR chown (),
+.BR fchown (),
+and
+.BR lchown ()
+system calls supported only 16-bit user and group IDs.
+Subsequently, Linux 2.4 added
+.BR chown32 (),
+.BR fchown32 (),
+and
+.BR lchown32 (),
+supporting 32-bit IDs.
+The glibc
+.BR chown (),
+.BR fchown (),
+and
+.BR lchown ()
+wrapper functions transparently deal with the variations across kernel versions.
+.PP
+Before Linux 2.1.81 (except 2.1.46),
+.BR chown ()
+did not follow symbolic links.
+Since Linux 2.1.81,
+.BR chown ()
+does follow symbolic links, and there is a new system call
+.BR lchown ()
+that does not follow symbolic links.
+Since Linux 2.1.86, this new call (that has the same semantics
+as the old
+.BR chown ())
+has got the same syscall number, and
+.BR chown ()
+got the newly introduced number.
+.SH EXAMPLES
+The following program changes the ownership of the file named in
+its second command-line argument to the value specified in its
+first command-line argument.
+The new owner can be specified either as a numeric user ID,
+or as a username (which is converted to a user ID by using
+.BR getpwnam (3)
+to perform a lookup in the system password file).
+.SS Program source
+.\" SRC BEGIN (chown.c)
+.EX
+#include <pwd.h>
+#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]) {
+ 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 */
+ 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
+.\" SRC END
+.SH SEE ALSO
+.BR chgrp (1),
+.BR chown (1),
+.BR chmod (2),
+.BR flock (2),
+.BR path_resolution (7),
+.BR symlink (7)