diff options
Diffstat (limited to 'man/man2/chown.2')
| -rw-r--r-- | man/man2/chown.2 | 471 |
1 files changed, 471 insertions, 0 deletions
diff --git a/man/man2/chown.2 b/man/man2/chown.2 new file mode 100644 index 000000000..ffba3acaf --- /dev/null +++ b/man/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 (date) "Linux man-pages (unreleased)" +.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> +.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 ); +.P +.BR "#include <fcntl.h> " "/* Definition of AT_* constants */" +.B #include <unistd.h> +.P +.BI "int fchownat(int " dirfd ", const char *" pathname , +.BI " uid_t " owner ", gid_t " group ", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.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 +.fi +.P +.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. +.P +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. +.P +If the +.I owner +or +.I group +is specified as \-1, then that ID is not changed. +.P +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 (). +.P +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. +.P +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). +.P +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 ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +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 ().) +.P +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. +.P +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. +.P +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. +.P +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) |