1 CHMOD(2) System Calls CHMOD(2)
2
3
4
5 NAME
6 chmod, fchmod, fchmodat - change access permission mode of file
7
8 SYNOPSIS
9 #include <sys/types.h>
10 #include <sys/stat.h>
11
12 int chmod(const char *path, mode_t mode);
13
14
15 int fchmod(int fildes, mode_t mode);
16
17
18 int fchmodat(int fildes, const char *path, mode_t mode, int flag);
19
20
21 DESCRIPTION
22 The chmod(), fchmod(), and fchmodat() functions set the access
23 permission portion of the mode of the file whose name is given by path
24 or referenced by the open file descriptor fildes to the bit pattern
25 contained in mode. Access permission bits are interpreted as follows:
26
27
28
29
30 S_ISUID 04000 Set user ID on execution.
31 S_ISGID 020#0 Set group ID on execution if # is 7, 5, 3, or 1. Enable mandatory file/record locking if # is 6, 4, 2, or 0.
32 S_ISVTX 01000 Sticky bit.
33 S_IRWXU 00700 Read, write, execute by owner.
34 S_IRUSR 00400 Read by owner.
35 S_IWUSR 00200 Write by owner.
36 S_IXUSR 00100 Execute (search if a directory) by owner.
37 S_IRWXG 00070 Read, write, execute by group.
38 S_IRGRP 00040 Read by group.
39 S_IWGRP 00020 Write by group.
40 S_IXGRP 00010 Execute by group.
41 S_IRWXO 00007 Read, write, execute (search) by others.
42 S_IROTH 00004 Read by others.
43 S_IWOTH 00002 Write by others.
44 S_IXOTH 00001 Execute by others.
45
46
47
48 Modes are constructed by the bitwise OR operation of the access
49 permission bits.
50
51
52 The effective user ID of the process must match the owner of the file
53 or the process must have the appropriate privilege to change the mode
54 of a file.
55
56
57 If the process is not a privileged process and the file is not a
58 directory, mode bit 01000 (save text image on execution) is cleared.
59
60
61 If neither the process is privileged nor the file's group is a member
62 of the process's supplementary group list, and the effective group ID
63 of the process does not match the group ID of the file, mode bit 02000
64 (set group ID on execution) is cleared.
65
66
67 If a directory is writable and has S_ISVTX (the sticky bit) set, files
68 within that directory can be removed or renamed only if one or more of
69 the following is true (see unlink(2) and rename(2)):
70
71 o the user owns the file
72
73 o the user owns the directory
74
75 o the file is writable by the user
76
77 o the user is a privileged user
78
79
80 If a regular file is not executable and has S_ISVTX set, the file is
81 assumed to be a swap file. In this case, the system's page cache will
82 not be used to hold the file's data. If the S_ISVTX bit is set on any
83 other file, the results are unspecified.
84
85
86 If a directory has the set group ID bit set, a given file created
87 within that directory will have the same group ID as the directory.
88 Otherwise, the newly created file's group ID will be set to the
89 effective group ID of the creating process.
90
91
92 If the mode bit 02000 (set group ID on execution) is set and the mode
93 bit 00010 (execute or search by group) is not set, mandatory
94 file/record locking will exist on a regular file, possibly affecting
95 future calls to open(2), creat(2), read(2), and write(2) on this file.
96
97
98 If fildes references a shared memory object, fchmod() need only affect
99 the S_IRUSR, S_IRGRP, S_IROTH, S_IWUSR, S_IWGRP, S_IWOTH, S_IXUSR,
100 S_IXGRP, and S_IXOTH file permission bits.
101
102
103 If fildes refers to a socket, fchmod() does not fail but no action is
104 taken.
105
106
107 If fildes refers to a stream that is attached to an object in the file
108 system name space with fattach(3C), the fchmod() call performs no
109 action and returns successfully.
110
111
112 The fchmodat() function behaves similarly to chmod(), except when path
113 is a relative path, it is resolved relative to the directory specified
114 by filedes. If filedes has the value AT_FDCWD, then path will be
115 resolved relative to the current working directory. The argument flag
116 should be zero, but may include the value AT_SYMLINK_NOFOLLOW, which
117 indicates that if path refers to a symbolic link, then permissions
118 should be changed on the symbolic link itself. However, changing
119 permissions of symbolic links is not supported on illumos, and will
120 result in an error.
121
122
123 Upon successful completion, chmod(), fchmod(), fchmodat() mark for
124 update the st_ctime field of the file.
125
126 RETURN VALUES
127 Upon successful completion, 0 is returned. Otherwise, -1 is returned,
128 the file mode is unchanged, and errno is set to indicate the error.
129
130 ERRORS
131 The chmod(), fchmod(), and fchmodat() functions will fail if:
132
133 EIO
134 An I/O error occurred while reading from or writing to the
135 file system.
136
137
138 EPERM
139 The effective user ID does not match the owner of the file and
140 the process does not have appropriate privilege.
141
142 The {PRIV_FILE_OWNER} privilege overrides constraints on
143 ownership when changing permissions on a file.
144
145 The {PRIV_FILE_SETID} privilege overrides constraints on
146 ownership when adding the setuid or setgid bits to an
147 executable file or a directory. When adding the setuid bit to
148 a root owned executable, additional restrictions apply. See
149 privileges(5).
150
151
152
153 The chmod() and fchmodat() functions will fail if:
154
155 EACCES
156 Search permission is denied on a component of the path
157 prefix of path and for fchmodat(), filedes was not
158 opened with O_SEARCH requested. The privilege
159 {FILE_DAC_SEARCH} overrides file permissions
160 restrictions in that case.
161
162
163 EFAULT
164 The path argument points to an illegal address.
165
166
167 ELOOP
168 A loop exists in symbolic links encountered during the
169 resolution of the path argument.
170
171
172 ENAMETOOLONG
173 The length of the path argument exceeds PATH_MAX, or
174 the length of a path component exceeds NAME_MAX while
175 _POSIX_NO_TRUNC is in effect.
176
177
178 ENOENT
179 Either a component of the path prefix or the file
180 referred to by path does not exist or is a null
181 pathname.
182
183
184 ENOLINK
185 The fildes argument points to a remote machine and the
186 link to that machine is no longer active.
187
188
189 ENOTDIR
190 A component of the prefix of path is not a directory.
191
192
193 EROFS
194 The file referred to by path resides on a read-only
195 file system.
196
197
198
199 The fchmod() function will fail if:
200
201 EBADF
202 The fildes argument is not an open file descriptor
203
204
205 ENOLINK
206 The path argument points to a remote machine and the link to
207 that machine is no longer active.
208
209
210 EROFS
211 The file referred to by fildes resides on a read-only file
212 system.
213
214
215
216 The chmod() and fchmod() functions may fail if:
217
218 EINTR
219 A signal was caught during execution of the function.
220
221
222 EINVAL
223 The value of the mode argument is invalid.
224
225
226
227 The fchmodat() will fail if:
228
229 EBADF
230 The argument path is a relative path and filedes is not
231 an open file descriptor or the value AT_FDCWD.
232
233
234 EINVAL
235 The argument flags has a non-zero value other than
236 AT_SYMLINK_NOFOLLOW.
237
238
239 ENOTDIR
240 The argument path is a relative path and filedes is a
241 valid file descriptor which does not refer to a file.
242
243
244 EOPNOTSUPP
245 The AT_SYMLINK_NOFOLLOW bit is set in the flags
246 argument.
247
248
249
250 The chmod() and fchmodat() functions may fail if:
251
252 ELOOP
253 More than {SYMLOOP_MAX} symbolic links were encountered
254 during the resolution of the path argument.
255
256
257 ENAMETOOLONG
258 As a result of encountering a symbolic link in
259 resolution of the path argument, the length of the
260 substituted pathname strings exceeds {PATH_MAX}.
261
262
263
264 The fchmod() function may fail if:
265
266 EINVAL
267 The fildes argument refers to a pipe and the system disallows
268 execution of this function on a pipe.
269
270
271 EXAMPLES
272 Example 1 Set Read Permissions for User, Group, and Others
273
274
275 The following example sets read permissions for the owner, group, and
276 others.
277
278
279 #include <sys/stat.h>
280 const char *path;
281 ...
282 chmod(path, S_IRUSR|S_IRGRP|S_IROTH);
283
284
285 Example 2 Set Read, Write, and Execute Permissions for the Owner Only
286
287
288 The following example sets read, write, and execute permissions for the
289 owner, and no permissions for group and others.
290
291
292 #include <sys/stat.h>
293 const char *path;
294 ...
295 chmod(path, S_IRWXU);
296
297
298 Example 3 Set Different Permissions for Owner, Group, and Other
299
300
301 The following example sets owner permissions for CHANGEFILE to read,
302 write, and execute, group permissions to read and execute, and other
303 permissions to read.
304
305
306 #include <sys/stat.h>
307 #define CHANGEFILE "/etc/myfile"
308 ...
309 chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH);
310
311
312 Example 4 Set and Checking File Permissions
313
314
315 The following example sets the file permission bits for a file named
316 /home/cnd/mod1, then calls the stat(2) function to verify the
317 permissions.
318
319
320 #include <sys/types.h>
321 #include <sys/stat.h>
322 int status;
323 struct stat buffer
324 ...
325 chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH);
326 status = stat("home/cnd/mod1", &buffer;);
327
328
329 USAGE
330 If chmod() or fchmod() is used to change the file group owner
331 permissions on a file with non-trivial ACL entries, only the ACL mask
332 is set to the new permissions and the group owner permission bits in
333 the file's mode field (defined in mknod(2)) are unchanged. A non-
334 trivial ACL entry is one whose meaning cannot be represented in the
335 file's mode field alone. The new ACL mask permissions might change the
336 effective permissions for additional users and groups that have ACL
337 entries on the file.
338
339 ATTRIBUTES
340 See attributes(5) for descriptions of the following attributes:
341
342
343
344
345 +--------------------+-------------------+
346 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
347 +--------------------+-------------------+
348 |Interface Stability | Standard |
349 +--------------------+-------------------+
350 |MT-Level | Async-Signal-Safe |
351 +--------------------+-------------------+
352
353 SEE ALSO
354 chmod(1), chown(2), creat(2), fcntl(2), mknod(2), open(2), read(2),
355 rename(2), stat(2), write(2), fattach(3C), mkfifo(3C), stat.h(3HEAD),
356 attributes(5), privileges(5), standards(5)
357
358
359 Programming Interfaces Guide
360
361
362
363 December 22, 2014 CHMOD(2)