1CHOWN(2) Linux Programmer's Manual CHOWN(2)
2
6 chown, fchown, lchown - change ownership of a file
7
9 #include <unistd.h>
10 int chown(const char *path, uid_t owner, gid_t group);
12 int fchown(int fd, uid_t owner, gid_t group);
13 int lchown(const char *path, uid_t owner, gid_t group);
14 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
16 fchown(), lchown(): _BSD_SOURCE || _XOPEN_SOURCE >= 500
18
20 These system calls change the owner and group of a file. The differ
21 only in how the file is specified:
22 * chown() changes the ownership of the file specified by path, which is
24 dereferenced if it is a symbolic link.
25 * fchown() changes the ownership of the file referred to by the open
27 file descriptor fd.
28 * lchown() is like chown(), but does not dereference symbolic links.
30 Only a privileged process (Linux: one with the CAP_CHOWN capability)
32 may change the owner of a file. The owner of a file may change the
33 group of the file to any group of which that owner is a member. A
34 privileged process (Linux: with CAP_CHOWN) may change the group arbi‐
35 trarily.
36 If the owner or group is specified as -1, then that ID is not changed.
38 When the owner or group of an executable file are changed by a non-
40 superuser, the S_ISUID and S_ISGID mode bits are cleared. POSIX does
41 not specify whether this also should happen when root does the chown();
42 the Linux behavior depends on the kernel version. In case of a non-
43 group-executable file (i.e., one for which the S_IXGRP bit is not set)
44 the S_ISGID bit indicates mandatory locking, and is not cleared by a
45 chown().
46
48 On success, zero is returned. On error, -1 is returned, and errno is
49 set appropriately.
50
52 Depending on the file system, other errors can be returned. The more
53 general errors for chown() are listed below.
54 EACCES Search permission is denied on a component of the path prefix.
56 (See also path_resolution(7).)
57 EFAULT path points outside your accessible address space.
59 ELOOP Too many symbolic links were encountered in resolving path.
61 ENAMETOOLONG
63 path is too long.
64 ENOENT The file does not exist.
66 ENOMEM Insufficient kernel memory was available.
68 ENOTDIR
70 A component of the path prefix is not a directory.
71 EPERM The calling process did not have the required permissions (see
73 above) to change owner and/or group.
74 EROFS The named file resides on a read-only file system.
76 The general errors for fchown() are listed below:
78 EBADF The descriptor is not valid.
80 EIO A low-level I/O error occurred while modifying the inode.
82 ENOENT See above.
84 EPERM See above.
86 EROFS See above.
88
90 4.4BSD, SVr4, POSIX.1-2001.
91 The 4.4BSD version can only be used by the superuser (that is, ordinary
93 users cannot give away files).
94
96 When a new file is created (by, for example, open(2) or mkdir(2)), its
97 owner is made the same as the file system user ID of the creating
98 process. The group of the file depends on a range of factors, includ‐
99 ing the type of file system, the options used to mount the file system,
100 and whether or not the set-group-ID permission bit is enabled on the
101 parent directory. If the file system supports the -o grpid (or, syn‐
102 onymously -o bsdgroups) and -o nogrpid (or, synonymously -o sysvgroups)
103 mount(8) options, then the rules are as follows:
104 * If the file system is mounted with -o grpid, then the group of a new
106 file is made the same as that of the parent directory.
107 * If the file system is mounted with -o nogrpid and the set-group-ID
109 bit is disabled on the parent directory, then the group of a new file
110 is made the same as the process's file system GID.
111 * If the file system is mounted with -o nogrpid and the set-group-ID
113 bit is enabled on the parent directory, then the group of a new file
114 is made the same as that of the parent directory.
115 As at Linux 2.6.25, the -o grpid and -o nogrpid mount options are sup‐
117 ported by ext2, ext3, ext4, and XFS. File systems that don't support
118 these mount options follow the -o nogrpid rules.
119 The chown() semantics are deliberately violated on NFS file systems
121 which have UID mapping enabled. Additionally, the semantics of all
122 system calls which access the file contents are violated, because
123 chown() may cause immediate access revocation on already open files.
124 Client side caching may lead to a delay between the time where owner‐
125 ship have been changed to allow access for a user and the time where
126 the file can actually be accessed by the user on other clients.
127 In versions of Linux prior to 2.1.81 (and distinct from 2.1.46),
129 chown() did not follow symbolic links. Since Linux 2.1.81, chown()
130 does follow symbolic links, and there is a new system call lchown()
131 that does not follow symbolic links. Since Linux 2.1.86, this new call
132 (that has the same semantics as the old chown()) has got the same
133 syscall number, and chown() got the newly introduced number.
134
136 The following program changes the ownership of the file named in its
137 second command-line argument to the value specified in its first com‐
138 mand-line argument. The new owner can be specified either as a numeric
139 user ID, or as a username (which is converted to a user ID by using
140 getpwnam(3) to perform a lookup in the system password file).
141 #include <pwd.h>
143 #include <stdio.h>
144 #include <stdlib.h>
145 #include <unistd.h>
146 int
148 main(int argc, char *argv[])
149 {
150 uid_t uid;
151 struct passwd *pwd;
152 char *endptr;
153 if (argc != 3 || argv[1][0] == '\0') {
155 fprintf(stderr, "%s <owner> <file>\n", argv[0]);
156 exit(EXIT_FAILURE);
157 }
158 uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */
160 if (*endptr != '\0') { /* Was not pure numeric string */
162 pwd = getpwnam(argv[1]); /* Try getting UID for username */
163 if (pwd == NULL) {
164 perror("getpwnam");
165 exit(EXIT_FAILURE);
166 }
167 uid = pwd->pw_uid;
169 }
170 if (chown(argv[2], uid, -1) == -1) {
172 perror("chown");
173 exit(EXIT_FAILURE);
174 } /* if */
175 exit(EXIT_SUCCESS);
177 } /* main */
178
180 chmod(2), fchownat(2), flock(2), path_resolution(7), symlink(7)
181
183 This page is part of release 3.22 of the Linux man-pages project. A
184 description of the project, and information about reporting bugs, can
185 be found at http://www.kernel.org/doc/man-pages/.
186Linux 2008-06-16 CHOWN(2)