1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T.
4 .\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 .\" This notice shall appear on any product containing this material.
9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 .Dd "Sep 12, 2005"
13 .Dt CHMOD 2
14 .Os
15 .
16 .Sh NAME
17 .
18 .Nm chmod ,
19 .Nm fchmod ,
20 .Nm fchmodat
21 .Nd change access permission mode of file
22 .Sh SYNOPSIS
23 .In sys/stat.h
24 .
25 .Ft int
26 .Fo chmod
27 .Fa "const char *path"
28 .Fa "mode_t mode"
29 .Fc
30 .
31 .Ft int
32 .Fo fchmod
33 .Fa "int fildes"
34 .Fa "mode_t mode"
35 .Fc
36 .Ft int
37 .Fo fchmodat
38 .Fa "int dirfd"
39 .Fa "const char *path"
40 .Fa "mode_t mode"
41 .Fa "int flag"
42 .Fc
43 .
44 .Sh DESCRIPTION
45 .
46 The
47 .Fn chmod ,
48 .Fn fchmod ,
49 and
50 .Fn fchmodat
51 functions set the access permission
52 portion of the mode of the file whose name is given by
53 .Fa path
54 or referenced by the open file descriptor
55 .Fa fildes
56 to the bit pattern contained in
57 .Fa mode .
58 .Lp
59 Access permission bits are interpreted as follows:
60 .Bl -column -offset indent "S_IXOTH" "XXXXX" infinity
61 .It Dv S_ISUID Ta 04000 Ta Set user ID on execution.
62 .It Dv S_ISGID Ta 020#0 Ta Set group ID on execution if # is
63 7, 5, 3, or 1. Enable mandatory file/record locking if # is
64 6, 4, 2, or 0.
65 .It Dv S_ISVTX Ta 01000 Ta Sticky bit.
66 .It Dv S_IRWXU Ta 00700 Ta Read, write, execute by owner.
67 .It Dv S_IRUSR Ta 00400 Ta Read by owner.
68 .It Dv S_IWUSR Ta 00200 Ta Write by owner.
69 .It Dv S_IXUSR Ta 00100 Ta Execute (search if a directory) by owner.
70 .It Dv S_IRWXG Ta 00070 Ta Read, write, execute by group.
71 .It Dv S_IRGRP Ta 00040 Ta Read by group.
72 .It Dv S_IWGRP Ta 00020 Ta Write by group.
73 .It Dv S_IXGRP Ta 00010 Ta Execute by group.
74 .It Dv S_IRWXO Ta 00007 Ta Read, write, execute (search) by others.
75 .It Dv S_IROTH Ta 00004 Ta Read by others.
76 .It Dv S_IWOTH Ta 00002 Ta Write by others.
77 .It Dv S_IXOTH Ta 00001 Ta Execute by others.
78 .El
79 .Lp
80 Modes are constructed by the bitwise OR operation of the access permission
81 bits.
82 .Lp
83 The effective user ID of the process must match the owner of the file or the
84 process must have the appropriate privilege to change the mode of a file.
85 .Lp
86 If the process is not a privileged process and the file is not a directory,
87 mode bit 01000 (save text image on execution) is cleared.
88 .Lp
89 If neither the process is privileged nor the file's group is a member of the
90 process's supplementary group list, and the effective group ID of the process
91 does not match the group ID of the file, mode bit 02000 (set group ID on
92 execution) is cleared.
93 .Lp
94 If a directory is writable and has
95 .Dv S_ISVTX
96 (the sticky bit) set, files
97 within that directory can be removed or renamed only if one or more of the
98 following is true (see
99 .Xr unlink 2
100 and
101 .Xr rename 2 :
102 .Bl -bullet -offset indent
103 .It
104 the user owns the file
105 .It
106 the user owns the directory
107 .It
108 the file is writable by the user
109 .It
110 the user is a privileged user
111 .El
112 .Lp
113 If a regular file is not executable and has
114 .Dv S_ISVTX
115 set, the file is
116 assumed to be a swap file. In this case, the system's page cache will not be
117 used to hold the file's data. If the
118 .Dv S_ISVTX
119 bit is set on any other file, the results are unspecified.
120 .Lp
121 If a directory has the set group ID bit set, a given file created within that
122 directory will have the same group ID as the directory. Otherwise, the newly
123 created file's group ID will be set to the effective group ID of the creating
124 process.
125 .Lp
126 If the mode bit 02000 (set group ID on execution) is set and the mode bit 00010
127 (execute or search by group) is not set, mandatory file/record locking will
128 exist on a regular file, possibly affecting future calls to
129 .Xr open 2 ,
130 .Xr create 2 ,
131 .Xr read 2 ,
132 and
133 .Xr write 2
134 on this file.
135 .Lp
136 If
137 .Fa fildes
138 references a shared memory object,
139 .Fn fchmod
140 need only
141 affect the
142 .Dv S_IRUSR , S_IRGRP , S_IROTH , S_IWUSR, S_IWGRP , S_IWOTH , S_IXUSR ,
143 .Dv S_IXGRP ,
144 and
145 .Dv S_IXOTH
146 file permission bits.
147 .Lp
148 If
149 .Fa fildes
150 refers to a socket, or to a stream that is attached to an object in
151 the filesystem name space with
152 .Xr fattach 3C ,
153 .Fn fchmod
154 takes no action and returns successfully.
155 .Lp
156 Upon successful completion,
157 .Fn chmod
158 .Fn fchmod
159 and
160 .Fn fchmodat
161 mark for update the
162 .Vt st_ctime
163 field of the file.
164 .Lp
165 The
166 .Fn fchmodat
167 function operates like
168 .Fn chmod
169 except that if
170 .Fa path
171 is relative, then the file to be changed is determined relative to
172 the open directory presented by
173 .Fa dirfd ,
174 instead of the current working directory. The special value
175 .Dv AT_FDCWD can be supplied for
176 .Fa dirfd
177 to indicate the current working directory.
178 .Lp
179 If
180 .Fa dirfd
181 was opened without
182 .Dv O_SEARCH ,
183 the
184 .Fn fchmodat
185 function checks whether directory searches are permitted using the current
186 permissions of the underlying directory.
187 .Lp
188 The
189 .Fa flag
190 argument is bitwise
191 .Sy OR
192 of the following flags:
193 .Bl -tag -width Dv -offset indent
194 .It Dv AT_SYMLINK_NOFOLLOW
195 If
196 .Fa path
197 is a symbolic link, then the mode of the link is changed instead of the
198 target.
199 .El
200 .
201 .Sh RETURN VALUES
202 .
203 Upon successful completion, 0 is returned. Otherwise, \(mi1 is
204 returned, the file mode is unchanged, and
205 .Va errno
206 is set to indicate the error.
207 .
208 .Sh EXAMPLES
209 .
210 .Ss Example 1 No Set Read Permissions for User, Group, and Others
211 The following example sets read permissions for the owner, group, and others.
212 .Bd -literal -offset indent
213 #include <sys/stat.h>
214 const char *path;
215 \&...
216 chmod(path, S_IRUSR|S_IRGRP|S_IROTH);
217 .Ed
218 .
219 .Ss Example 2 No Set Read, Write, and Execute Permissions for the Owner Only
220 The following example sets read, write, and execute permissions for the owner,
221 and no permissions for group and others.
222 .Bd -literal -offset indent
223 #include <sys/stat.h>
224 const char *path;
225 \&...
226 chmod(path, S_IRWXU);
227 .Ed
228 .
229 .Ss Example 3 No Set Different Permissions for Owner, Group, and Other
230 The following example sets owner permissions for CHANGEFILE to read, write, and
231 execute, group permissions to read and execute, and other permissions to read.
232 .Bd -literal -offset indent
233 #include <sys/stat.h>
234 #define CHANGEFILE "/etc/myfile"
235 \&...
236 chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH);
237 .Ed
238 .Ss Example 4 No Set and Checking File Permissions
239 The following example sets the file permission bits for a file named
240 .Pa /home/cnd/mod1 ,
241 then calls the
242 .Xr stat 2
243 function to verify the permissions.
244 .Bd -literal -offset indent
245 #include <sys/types.h>
246 #include <sys/stat.h>
247 int status;
248 struct stat buffer
249 \&...
250 chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH);
251 status = stat("home/cnd/mod1", &buffer;);
252 .Ed
253 .
254 .Sh ERRORS
255 .
256 The
257 .Fn chmod ,
258 .Fn fchmod
259 and
260 .Fn fchmodat
261 functions will fail if:
262 .Bl -tag -width Er
263 .It Er EIO
264 An I/O error occurred while reading from or writing to the file system.
265 .It Er EPERM
266 The effective user ID does not match the owner of the file and the process does
267 not have appropriate privilege.
268 .Lp
269 The
270 .Brq Dv PRIV_FILE_OWNER
271 privilege overrides constraints on ownership when
272 changing permissions on a file.
273 .Lp
274 The
275 .Brq Dv PRIV_FILE_SETID
276 privilege overrides constraints on ownership when
277 adding the setuid or setgid bits to an executable file or a directory. When
278 adding the setuid bit to a root owned executable, additional restrictions
279 apply. See
280 .Xr privileges 5 .
281 .El
282 .Lp
283 The
284 .Fn chmod
285 and
286 .Fn fchmodat
287 functions will fail if:
288 .Bl -tag -width Er
289 .
290 .It Er EACCES
291 Search permission is denied on a component of the path prefix of
292 .Fa path .
293 The privilege
294 .Brq Dv FILE_DAC_SEARCH
295 overrides file permissions restrictions in that case.
296 .
297 .It Er EFAULT
298 The
299 .Fa path
300 argument points to an illegal address.
301 .
302 .It Er ELOOP
303 A loop exists in symbolic links encountered during the resolution of the
304 .Fa path
305 argument.
306 .
307 .It Er ENAMETOOLONG
308 The length of the
309 .Fa path
310 argument exceeds
311 .Brq Dv PATH_MAX .
312 .
313 .It Er NOENT
314 Either a component of the path prefix or the file referred to by
315 .Fa path
316 does not exist or is a null pathname.
317 .
318 .It Er ENOLINK
319 The
320 .Fa path
321 argument points to a remote machine and the link to that
322 machine is no longer active.
323 .
324 .It Er ENOTDIR
325 A component of the prefix of
326 .Fa path
327 is not a directory.
328 .
329 .It Er EROFS
330 The file referred to by
331 .Fa path
332 resides on a read-only file system.
333 .El
334 .Lp
335 The
336 .Fn fchmod
337 function will fail if:
338 .Bl -tag -width Er
339 .
340 .It Er EBADF
341 The
342 .Fa filedes
343 argument is not an open file descriptor
344 .
345 .It Er ENOLINK
346 The file referred to by
347 .Fa filedes
348 argument points to a remote machine and the link to that machine
349 is no longer active.
350 .
351 .It Er EROFS
352 The file referred to by
353 .Fa fildes
354 resides on a read-only file system.
355 .El
356 .Lp
357 The
358 .Fn fchmodat
359 function will fail if:
360 .Bl -tag -width Er
361 .
362 .It Er EBADF
363 The
364 .Fa path
365 argument does not specify an absolute path, and
366 .Fa dirfd
367 is neither
368 .Dv AT_FDCWD
369 nor a file descriptor open for reading or searching.
370 .
371 .It Er EACCES
372 The
373 .Fa dirfd
374 descriptor was opened without
375 .Dv O_SEARCH
376 and the underlying directory permissions do not allow directory
377 searches.
378 .El
379 .
380 .Lp
381 The
382 .Fn chmod ,
383 .Fn fchmod ,
384 and
385 .Fn fchmodat
386 functions may fail if:
387 .Bl -tag -width Er
388 .
389 .It Er EINTR
390 A signal was caught during execution of the function.
391 .
392 .It Er EINVAL
393 The value of the
394 .Fa mode
395 argument is invalid.
396 .El
397 .Lp
398 The
399 .Fn chmod
400 and
401 .Fn fchmodat
402 functions may fail if:
403 .Bl -tag -width Er
404 .
405 .It Er ELOOP
406 More than
407 .Brq Dv SYMLOOP_MAX
408 symbolic links were encountered during the
409 resolution of the
410 .Fa path
411 argument.
412 .
413 .It Er ENAMETOOLONG
414 As a result of encountering a symbolic link in resolution of the
415 .Fa path
416 argument, the length of the substituted pathname exceed
417 .Brq Dv PATH_MAX .
418 .El
419 .Lp
420 The
421 .Fn fchmod
422 function may fail if:
423 .Bl -tag -width Er
424 .It EINVAL
425 The
426 .Fa fildes
427 argument refers to a pipe and the system disallows execution
428 of this function on a pipe.
429 .El
430 .
431 .Lp
432 The
433 .Fn fchmodat
434 function may fail if:
435 .Bl -tag -width Er
436 .It Er EINVAL
437 The value of
438 .Fa flag
439 is invalid.
440 .It Er ENOTDIR
441 The
442 .Fa dirfd
443 argument is not a file descriptor opened on a directory or
444 the special value
445 .Dv AT_CWDFD ,
446 and
447 .Fa path
448 is not an absolute directory name.
449 .It Er EOPNOTSUPP
450 The
451 .Fa flag
452 argument contains the bit
453 .Dv AT_SYMLINK_NOFOLLOW ,
454 the
455 .Fa path
456 is a symbolic link, and the underlying filesystem does not support
457 changing the mode of symbolic links.
458 .El
459 .
460 .Sh USAGE
461 If
462 .Fn chmod ,
463 .Fn fchmod ,
464 or
465 .Fn fchmodat
466 are used to change the file group owner
467 permissions on a file with non-trivial ACL entries, only the ACL mask is set to
468 the new permissions and the group owner permission bits in the file's mode
469 field (defined in
470 .Xr mknod 2 )
471 are unchanged. A non-trivial ACL entry is
472 one whose meaning cannot be represented in the file's mode field alone. The new
473 ACL mask permissions might change the effective permissions for additional
474 users and groups that have ACL entries on the file.
475 .Lp
476 The
477 .Fn fchmodat
478 function is intended to enable changing permissions in directories other than
479 the current working directory without race conditions.
480 .
481 .Sh INTERFACE STABILITY
482 .
483 .Sy Standard .
484 .
485 .Sh MT-LEVEL
486 .
487 .Sy Async-Signal-Safe .
488 .
489 .Sh SEE ALSO
490 .
491 .Xr chmod 1 ,
492 .Xr chown 2 ,
493 .Xr creat 2 ,
494 .Xr fcntl 2 ,
495 .Xr mknod 2 ,
496 .Xr open 2 ,
497 .Xr read 2 ,
498 .Xr rename 2 ,
499 .Xr stat 2 ,
500 .Xr write 2 ,
501 .Xr fattach 3C ,
502 .Xr mkfifo 3C ,
503 .Xr stat.h 3HEAD ,
504 .Xr privileges 5 ,
505 .Xr standards 5
506 .Rs
507 .%T Programming Interfaces Guide
508 .Re
509 .
510 .Sh STANDARDS
511 .
512 The
513 .Fn chmod
514 function was introduced in
515 .At
516 and is specified in
517 .St -p1003.1 .
518 The
519 .Fn fchmod
520 function was introduced in
521 .St -xpg4.2 .
522 The
523 .Fn fchmodat
524 function was introduced in
525 .St -p1003.1-2008 .