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 - 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
21 The chown() function shall change the user and group ownership of a
22 file.
23 The path argument points to a pathname naming a file. The user ID and
25 group ID of the named file shall be set to the numeric values contained
26 in owner and group, respectively.
27 Only processes with an effective user ID equal to the user ID of the
29 file or with appropriate privileges may change the ownership of a file.
30 If _POSIX_CHOWN_RESTRICTED is in effect for path:
31 * Changing the user ID is restricted to processes with appropriate
33 privileges.
34 * Changing the group ID is permitted to a process with an effective
36 user ID equal to the user ID of the file, but without appropriate
37 privileges, if and only if owner is equal to the file's user ID or (
38 uid_t)-1 and group is equal either to the calling process' effective
39 group ID or to one of its supplementary group IDs.
40 If the specified file is a regular file, one or more of the S_IXUSR,
42 S_IXGRP, or S_IXOTH bits of the file mode are set, and the process does
43 not have appropriate privileges, the set-user-ID (S_ISUID) and set-
44 group-ID (S_ISGID) bits of the file mode shall be cleared upon success‐
45 ful return from chown(). If the specified file is a regular file, one
46 or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are
47 set, and the process has appropriate privileges, it is implementation-
48 defined whether the set-user-ID and set-group-ID bits are altered. If
49 the chown() function is successfully invoked on a file that is not a
50 regular file and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits
51 of the file mode are set, the set-user-ID and set-group-ID bits may be
52 cleared.
53 If owner or group is specified as ( uid_t)-1 or ( gid_t)-1, respec‐
55 tively, the corresponding ID of the file shall not be changed. If both
56 owner and group are -1, the times need not be updated.
57 Upon successful completion, chown() shall mark for update the st_ctime
59 field of the file.
60
62 Upon successful completion, 0 shall be returned; otherwise, -1 shall be
63 returned and errno set to indicate the error. If -1 is returned, no
64 changes are made in the user ID and group ID of the file.
65
67 The chown() function shall fail if:
68 EACCES Search permission is denied on a component of the path prefix.
70 ELOOP A loop exists in symbolic links encountered during resolution of
72 the path argument.
73 ENAMETOOLONG
75 The length of the path argument exceeds {PATH_MAX} or a pathname
76 component is longer than {NAME_MAX}.
77 ENOTDIR
79 A component of the path prefix is not a directory.
80 ENOENT A component of path does not name an existing file or path is an
82 empty string.
83 EPERM The effective user ID does not match the owner of the file, or
85 the calling process does not have appropriate privileges and
86 _POSIX_CHOWN_RESTRICTED indicates that such privilege is
87 required.
88 EROFS The named file resides on a read-only file system.
90 The chown() function may fail if:
93 EIO An I/O error occurred while reading or writing to the file sys‐
95 tem.
96 EINTR The chown() function was interrupted by a signal which was
98 caught.
99 EINVAL The owner or group ID supplied is not a value supported by the
101 implementation.
102 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
104 resolution of the path argument.
105 ENAMETOOLONG
107 As a result of encountering a symbolic link in resolution of the
108 path argument, the length of the substituted pathname string
109 exceeded {PATH_MAX}.
110 The following sections are informative.
113
115 None.
116
118 Although chown() can be used on some implementations by the file owner
119 to change the owner and group to any desired values, the only portable
120 use of this function is to change the group of a file to the effective
121 GID of the calling process or to a member of its group set.
122
124 System III and System V allow a user to give away files; that is, the
125 owner of a file may change its user ID to anything. This is a serious
126 problem for implementations that are intended to meet government secu‐
127 rity regulations. Version 7 and 4.3 BSD permit only the superuser to
128 change the user ID of a file. Some government agencies (usually not
129 ones concerned directly with security) find this limitation too confin‐
130 ing. This volume of IEEE Std 1003.1-2001 uses may to permit secure
131 implementations while not disallowing System V.
132 System III and System V allow the owner of a file to change the group
134 ID to anything. Version 7 permits only the superuser to change the
135 group ID of a file. 4.3 BSD permits the owner to change the group ID of
136 a file to its effective group ID or to any of the groups in the list of
137 supplementary group IDs, but to no others.
138 The POSIX.1-1990 standard requires that the chown() function invoked by
140 a non-appropriate privileged process clear the S_ISGID and the S_ISUID
141 bits for regular files, and permits them to be cleared for other types
142 of files. This is so that changes in accessibility do not accidentally
143 cause files to become security holes. Unfortunately, requiring these
144 bits to be cleared on non-executable data files also clears the manda‐
145 tory file locking bit (shared with S_ISGID), which is an extension on
146 many implementations (it first appeared in System V). These bits should
147 only be required to be cleared on regular files that have one or more
148 of their execute bits set.
149
151 None.
152
154 chmod(), pathconf(), the Base Definitions volume of
155 IEEE Std 1003.1-2001, <sys/types.h>, <unistd.h>
156
158 Portions of this text are reprinted and reproduced in electronic form
159 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
160 -- Portable Operating System Interface (POSIX), The Open Group Base
161 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
162 Electrical and Electronics Engineers, Inc and The Open Group. In the
163 event of any discrepancy between this version and the original IEEE and
164 The Open Group Standard, the original IEEE and The Open Group Standard
165 is the referee document. The original Standard can be obtained online
166 at http://www.opengroup.org/unix/online.html .
167IEEE/The Open Group 2003 CHOWN(3P)