diff options
Diffstat (limited to 'man2/chown.2')
| -rw-r--r-- | man2/chown.2 | 471 |
1 files changed, 0 insertions, 471 deletions
diff --git a/man2/chown.2 b/man2/chown.2 deleted file mode 100644 index f71030d..0000000 --- a/man2/chown.2 +++ /dev/null @@ -1,471 +0,0 @@ -.\" 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-10-31 "Linux man-pages 6.7" -.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) |