1CHOWN(3P) POSIX Programmer's Manual CHOWN(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 chown, fchownat — change owner and group of a file
13
15 #include <unistd.h>
16 int chown(const char *path, uid_t owner, gid_t group);
18 #include <fcntl.h>
20 int fchownat(int fd, const char *path, uid_t owner, gid_t group,
22 int flag);
23
25 The chown() function shall change the user and group ownership of a
26 file.
27 The path argument points to a pathname naming a file. The user ID and
29 group ID of the named file shall be set to the numeric values contained
30 in owner and group, respectively.
31 Only processes with an effective user ID equal to the user ID of the
33 file or with appropriate privileges may change the ownership of a file.
34 If _POSIX_CHOWN_RESTRICTED is in effect for path:
35 * Changing the user ID is restricted to processes with appropriate
37 privileges.
38 * Changing the group ID is permitted to a process with an effective
40 user ID equal to the user ID of the file, but without appropriate
41 privileges, if and only if owner is equal to the file's user ID or
42 (uid_t)-1 and group is equal either to the calling process' effec‐
43 tive group ID or to one of its supplementary group IDs.
44 If the specified file is a regular file, one or more of the S_IXUSR,
46 S_IXGRP, or S_IXOTH bits of the file mode are set, and the process does
47 not have appropriate privileges, the set-user-ID (S_ISUID) and set-
48 group-ID (S_ISGID) bits of the file mode shall be cleared upon success‐
49 ful return from chown(). If the specified file is a regular file, one
50 or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are
51 set, and the process has appropriate privileges, it is implementation-
52 defined whether the set-user-ID and set-group-ID bits are altered. If
53 the chown() function is successfully invoked on a file that is not a
54 regular file and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits
55 of the file mode are set, the set-user-ID and set-group-ID bits may be
56 cleared.
57 If owner or group is specified as (uid_t)-1 or (gid_t)-1, respectively,
59 the corresponding ID of the file shall not be changed.
60 Upon successful completion, chown() shall mark for update the last file
62 status change timestamp of the file, except that if owner is (uid_t)-1
63 and group is (gid_t)-1, the file status change timestamp need not be
64 marked for update.
65 The fchownat() function shall be equivalent to the chown() and lchown()
67 functions except in the case where path specifies a relative path. In
68 this case the file to be changed is determined relative to the direc‐
69 tory associated with the file descriptor fd instead of the current
70 working directory. If the access mode of the open file description
71 associated with the file descriptor is not O_SEARCH, the function shall
72 check whether directory searches are permitted using the current per‐
73 missions of the directory underlying the file descriptor. If the access
74 mode is O_SEARCH, the function shall not perform the check.
75 Values for flag are constructed by a bitwise-inclusive OR of flags from
77 the following list, defined in <fcntl.h>:
78 AT_SYMLINK_NOFOLLOW
80 If path names a symbolic link, ownership of the symbolic link is
81 changed.
82 If fchownat() is passed the special value AT_FDCWD in the fd parameter,
84 the current working directory shall be used and the behavior shall be
85 identical to a call to chown() or lchown() respectively, depending on
86 whether or not the AT_SYMLINK_NOFOLLOW bit is set in the flag argument.
87
89 Upon successful completion, these functions shall return 0. Otherwise,
90 these functions shall return -1 and set errno to indicate the error. If
91 -1 is returned, no changes are made in the user ID and group ID of the
92 file.
93
95 These functions shall fail if:
96 EACCES Search permission is denied on a component of the path prefix.
98 ELOOP A loop exists in symbolic links encountered during resolution of
100 the path argument.
101 ENAMETOOLONG
103 The length of a component of a pathname is longer than
104 {NAME_MAX}.
105 ENOENT A component of path does not name an existing file or path is an
107 empty string.
108 ENOTDIR
110 A component of the path prefix names an existing file that is
111 neither a directory nor a symbolic link to a directory, or the
112 path argument contains at least one non-<slash> character and
113 ends with one or more trailing <slash> characters and the last
114 pathname component names an existing file that is neither a
115 directory nor a symbolic link to a directory.
116 EPERM The effective user ID does not match the owner of the file, or
118 the calling process does not have appropriate privileges and
119 _POSIX_CHOWN_RESTRICTED indicates that such privilege is
120 required.
121 EROFS The named file resides on a read-only file system.
123 The fchownat() function shall fail if:
125 EACCES The access mode of the open file description associated with fd
127 is not O_SEARCH and the permissions of the directory underlying
128 fd do not permit directory searches.
129 EBADF The path argument does not specify an absolute path and the fd
131 argument is neither AT_FDCWD nor a valid file descriptor open
132 for reading or searching.
133 ENOTDIR
135 The path argument is not an absolute path and fd is a file
136 descriptor associated with a non-directory file.
137 These functions may fail if:
139 EIO An I/O error occurred while reading or writing to the file sys‐
141 tem.
142 EINTR The chown() function was interrupted by a signal which was
144 caught.
145 EINVAL The owner or group ID supplied is not a value supported by the
147 implementation.
148 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
150 resolution of the path argument.
151 ENAMETOOLONG
153 The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
154 tion of a symbolic link produced an intermediate result with a
155 length that exceeds {PATH_MAX}.
156 The fchownat() function may fail if:
158 EINVAL The value of the flag argument is not valid.
160 The following sections are informative.
162
164 None.
165
167 Although chown() can be used on some implementations by the file owner
168 to change the owner and group to any desired values, the only portable
169 use of this function is to change the group of a file to the effective
170 GID of the calling process or to a member of its group set.
171
173 System III and System V allow a user to give away files; that is, the
174 owner of a file may change its user ID to anything. This is a serious
175 problem for implementations that are intended to meet government secu‐
176 rity regulations. Version 7 and 4.3 BSD permit only the superuser to
177 change the user ID of a file. Some government agencies (usually not
178 ones concerned directly with security) find this limitation too confin‐
179 ing. This volume of POSIX.1‐2017 uses may to permit secure implementa‐
180 tions while not disallowing System V.
181 System III and System V allow the owner of a file to change the group
183 ID to anything. Version 7 permits only the superuser to change the
184 group ID of a file. 4.3 BSD permits the owner to change the group ID
185 of a file to its effective group ID or to any of the groups in the list
186 of supplementary group IDs, but to no others.
187 The POSIX.1‐1990 standard requires that the chown() function invoked by
189 a non-appropriate privileged process clear the S_ISGID and the S_ISUID
190 bits for regular files, and permits them to be cleared for other types
191 of files. This is so that changes in accessibility do not accidentally
192 cause files to become security holes. Unfortunately, requiring these
193 bits to be cleared on non-executable data files also clears the manda‐
194 tory file locking bit (shared with S_ISGID), which is an extension on
195 many implementations (it first appeared in System V). These bits should
196 only be required to be cleared on regular files that have one or more
197 of their execute bits set.
198 The purpose of the fchownat() function is to enable changing ownership
200 of files in directories other than the current working directory with‐
201 out exposure to race conditions. Any part of the path of a file could
202 be changed in parallel to a call to chown() or lchown(), resulting in
203 unspecified behavior. By opening a file descriptor for the target
204 directory and using the fchownat() function it can be guaranteed that
205 the changed file is located relative to the desired directory.
206
208 None.
209
211 chmod(), fpathconf(), lchown()
212 The Base Definitions volume of POSIX.1‐2017, <fcntl.h>, <sys_types.h>,
214 <unistd.h>
215
217 Portions of this text are reprinted and reproduced in electronic form
218 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
219 table Operating System Interface (POSIX), The Open Group Base Specifi‐
220 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
221 Electrical and Electronics Engineers, Inc and The Open Group. In the
222 event of any discrepancy between this version and the original IEEE and
223 The Open Group Standard, the original IEEE and The Open Group Standard
224 is the referee document. The original Standard can be obtained online
225 at http://www.opengroup.org/unix/online.html .
226 Any typographical or formatting errors that appear in this page are
228 most likely to have been introduced during the conversion of the source
229 files to man page format. To report such errors, see https://www.ker‐
230 nel.org/doc/man-pages/reporting_bugs.html .
231IEEE/The Open Group 2017 CHOWN(3P)