1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T.
44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
46 .\" Copyright (c) 2014, Joyent, Inc.
47 .\"
48 .TH CHMOD 2 "Dec 22, 2014"
49 .SH NAME
50 chmod, fchmod, fchmodat \- change access permission mode of file
51 .SH SYNOPSIS
52 .LP
53 .nf
54 #include <sys/types.h>
55 #include <sys/stat.h>
56
57 \fBint\fR \fBchmod\fR(\fBconst char *\fR\fIpath\fR, \fBmode_t\fR \fImode\fR);
58 .fi
59
60 .LP
61 .nf
62 \fBint\fR \fBfchmod\fR(\fBint\fR \fIfildes\fR, \fBmode_t\fR \fImode\fR);
63 .fi
64
65 .LP
66 .nf
67 \fBint\fR \fBfchmodat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR, \fBmode_t\fR \fImode\fR, \fBint\fR \fIflag\fR);
68 .fi
69
70 .SH DESCRIPTION
71 .LP
72 The \fBchmod()\fR, \fBfchmod()\fR, and \fBfchmodat()\fR functions set the access
73 permission portion of the mode of the file whose name is given by \fIpath\fR or
74 referenced by the open file descriptor \fIfildes\fR to the bit pattern contained
75 in \fImode\fR. Access permission bits are interpreted as follows:
76 .sp
77
78 .sp
79 .TS
80 l l l
81 l l l .
82 \fBS_ISUID\fR 04000 Set user ID on execution.
83 \fBS_ISGID\fR 020#0 T{
84 Set group ID on execution if # is \fB7\fR, \fB5\fR, \fB3\fR, or \fB1\fR. Enable mandatory file/record locking if # is \fB6\fR, \fB4\fR, \fB2\fR, or \fB0\fR.
85 T}
86 \fBS_ISVTX\fR 01000 Sticky bit.
87 \fBS_IRWXU\fR 00700 Read, write, execute by owner.
88 \fBS_IRUSR\fR 00400 Read by owner.
89 \fBS_IWUSR\fR 00200 Write by owner.
90 \fBS_IXUSR\fR 00100 T{
91 Execute (search if a directory) by owner.
92 T}
93 \fBS_IRWXG\fR 00070 Read, write, execute by group.
94 \fBS_IRGRP\fR 00040 Read by group.
95 \fBS_IWGRP\fR 00020 Write by group.
96 \fBS_IXGRP\fR 00010 Execute by group.
97 \fBS_IRWXO\fR 00007 Read, write, execute (search) by others.
98 \fBS_IROTH\fR 00004 Read by others.
99 \fBS_IWOTH\fR 00002 Write by others.
100 \fBS_IXOTH\fR 00001 Execute by others.
101 .TE
102
103 .sp
104 .LP
105 Modes are constructed by the bitwise OR operation of the access permission
106 bits.
107 .sp
108 .LP
109 The effective user ID of the process must match the owner of the file or the
110 process must have the appropriate privilege to change the mode of a file.
111 .sp
112 .LP
113 If the process is not a privileged process and the file is not a directory,
114 mode bit 01000 (save text image on execution) is cleared.
115 .sp
116 .LP
117 If neither the process is privileged nor the file's group is a member of the
118 process's supplementary group list, and the effective group ID of the process
119 does not match the group ID of the file, mode bit 02000 (set group ID on
120 execution) is cleared.
121 .sp
122 .LP
123 If a directory is writable and has \fBS_ISVTX\fR (the sticky bit) set, files
124 within that directory can be removed or renamed only if one or more of the
125 following is true (see \fBunlink\fR(2) and \fBrename\fR(2)):
126 .RS +4
127 .TP
128 .ie t \(bu
129 .el o
130 the user owns the file
131 .RE
132 .RS +4
133 .TP
134 .ie t \(bu
135 .el o
136 the user owns the directory
137 .RE
138 .RS +4
139 .TP
140 .ie t \(bu
141 .el o
142 the file is writable by the user
143 .RE
144 .RS +4
145 .TP
146 .ie t \(bu
147 .el o
148 the user is a privileged user
149 .RE
150 .sp
151 .LP
152 If a regular file is not executable and has \fBS_ISVTX\fR set, the file is
153 assumed to be a swap file. In this case, the system's page cache will not be
154 used to hold the file's data. If the \fBS_ISVTX\fR bit is set on any other
155 file, the results are unspecified.
156 .sp
157 .LP
158 If a directory has the set group ID bit set, a given file created within that
159 directory will have the same group ID as the directory. Otherwise, the newly
160 created file's group ID will be set to the effective group ID of the creating
161 process.
162 .sp
163 .LP
164 If the mode bit 02000 (set group ID on execution) is set and the mode bit 00010
165 (execute or search by group) is not set, mandatory file/record locking will
166 exist on a regular file, possibly affecting future calls to \fBopen\fR(2),
167 \fBcreat\fR(2), \fBread\fR(2), and \fBwrite\fR(2) on this file.
168 .sp
169 .LP
170 If \fIfildes\fR references a shared memory object, \fBfchmod()\fR need only
171 affect the \fBS_IRUSR\fR, \fBS_IRGRP\fR, \fBS_IROTH\fR, \fBS_IWUSR\fR,
172 \fBS_IWGRP\fR, \fBS_IWOTH\fR, \fBS_IXUSR\fR, \fBS_IXGRP\fR, and \fBS_IXOTH\fR
173 file permission bits.
174 .sp
175 .LP
176 If \fIfildes\fR refers to a socket, \fBfchmod()\fR does not fail but no action
177 is taken.
178 .sp
179 .LP
180 If \fIfildes\fR refers to a stream that is attached to an object in the file
181 system name space with \fBfattach\fR(3C), the \fBfchmod()\fR call performs no
182 action and returns successfully.
183 .sp
184 .LP
185 The \fBfchmodat()\fR function behaves similarly to \fBchmod()\fR, except when
186 \fIpath\fR is a relative path, it is resolved relative to the directory
187 specified by \fIfiledes\fR. If \fBfiledes\fR has the value \fBAT_FDCWD\fR, then
188 \fBpath\fR will be resolved relative to the current working directory. The
189 argument \fIflag\fR should be zero, but may include the value
190 \fBAT_SYMLINK_NOFOLLOW\fR, which indicates that if \fIpath\fR refers to a
191 symbolic link, then permissions should be changed on the symbolic link itself.
192 However, changing permissions of symbolic links is not supported on illumos, and
193 will result in an error.
194 .sp
195 .LP
196 Upon successful completion, \fBchmod()\fR, \fBfchmod()\fR, \fBfchmodat()\fR mark
197 for update the \fBst_ctime\fR field of the file.
198 .SH RETURN VALUES
199 .LP
200 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
201 returned, the file mode is unchanged, and \fBerrno\fR is set to indicate the
202 error.
203 .SH ERRORS
204 .LP
205 The \fBchmod()\fR, \fBfchmod()\fR, and \fBfchmodat()\fR functions will fail if:
206 .sp
207 .ne 2
208 .na
209 \fB\fBEIO\fR\fR
210 .ad
211 .RS 9n
212 An I/O error occurred while reading from or writing to the file system.
213 .RE
214
215 .sp
216 .ne 2
217 .na
218 \fB\fBEPERM\fR\fR
219 .ad
220 .RS 9n
221 The effective user ID does not match the owner of the file and the process does
222 not have appropriate privilege.
223 .sp
224 The {\fBPRIV_FILE_OWNER\fR} privilege overrides constraints on ownership when
225 changing permissions on a file.
226 .sp
227 The {\fBPRIV_FILE_SETID\fR} privilege overrides constraints on ownership when
228 adding the setuid or setgid bits to an executable file or a directory. When
229 adding the setuid bit to a root owned executable, additional restrictions
230 apply. See \fBprivileges\fR(5).
231 .RE
232
233 .sp
234 .LP
235 The \fBchmod()\fR and \fBfchmodat()\fR functions will fail if:
236 .sp
237 .ne 2
238 .na
239 \fB\fBEACCES\fR\fR
240 .ad
241 .RS 16n
242 Search permission is denied on a component of the path prefix of \fIpath\fR and
243 for \fBfchmodat()\fR, \fBfiledes\fR was not opened with \fBO_SEARCH\fR requsted.
244 The privilege {\fBFILE_DAC_SEARCH\fR} overrides file permissions restrictions
245 in that case.
246 .RE
247
248 .sp
249 .ne 2
250 .na
251 \fB\fBEFAULT\fR\fR
252 .ad
253 .RS 16n
254 The \fIpath\fR argument points to an illegal address.
255 .RE
256
257 .sp
258 .ne 2
259 .na
260 \fB\fBELOOP\fR\fR
261 .ad
262 .RS 16n
263 A loop exists in symbolic links encountered during the resolution of the
264 \fIpath\fR argument.
265 .RE
266
267 .sp
268 .ne 2
269 .na
270 \fB\fBENAMETOOLONG\fR\fR
271 .ad
272 .RS 16n
273 The length of the \fIpath\fR argument exceeds \fBPATH_MAX\fR, or the length of
274 a \fIpath\fR component exceeds \fBNAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in
275 effect.
276 .RE
277
278 .sp
279 .ne 2
280 .na
281 \fB\fBENOENT\fR\fR
282 .ad
283 .RS 16n
284 Either a component of the path prefix or the file referred to by \fIpath\fR
285 does not exist or is a null pathname.
286 .RE
287
288 .sp
289 .ne 2
290 .na
291 \fB\fBENOLINK\fR\fR
292 .ad
293 .RS 16n
294 The \fIfildes\fR argument points to a remote machine and the link to that
295 machine is no longer active.
296 .RE
297
298 .sp
299 .ne 2
300 .na
301 \fB\fBENOTDIR\fR\fR
302 .ad
303 .RS 16n
304 A component of the prefix of \fIpath\fR is not a directory.
305 .RE
306
307 .sp
308 .ne 2
309 .na
310 \fB\fBEROFS\fR\fR
311 .ad
312 .RS 16n
313 The file referred to by \fIpath\fR resides on a read-only file system.
314 .RE
315
316 .sp
317 .LP
318 The \fBfchmod()\fR function will fail if:
319 .sp
320 .ne 2
321 .na
322 \fB\fBEBADF\fR\fR
323 .ad
324 .RS 11n
325 The \fIfildes\fR argument is not an open file descriptor
326 .RE
327
328 .sp
329 .ne 2
330 .na
331 \fB\fBENOLINK\fR\fR
332 .ad
333 .RS 11n
334 The \fIpath\fR argument points to a remote machine and the link to that machine
335 is no longer active.
336 .RE
337
338 .sp
339 .ne 2
340 .na
341 \fB\fBEROFS\fR\fR
342 .ad
343 .RS 11n
344 The file referred to by \fIfildes\fR resides on a read-only file system.
345 .RE
346
347 .sp
348 .LP
349 The \fBchmod()\fR and \fBfchmod()\fR functions may fail if:
350 .sp
351 .ne 2
352 .na
353 \fB\fBEINTR\fR\fR
354 .ad
355 .RS 10n
356 A signal was caught during execution of the function.
357 .RE
358
359 .sp
360 .ne 2
361 .na
362 \fB\fBEINVAL\fR\fR
363 .ad
364 .RS 10n
365 The value of the \fImode\fR argument is invalid.
366 .RE
367
368 .sp
369 .LP
370 The \fBfchmodat()\fR will fail if:
371 .sp
372 .ne 2
373 .na
374 .B EBADF
375 .ad
376 .RS 16n
377 The argument \fIpath\fR is a relative path and \fIfiledes\fR is not an open file
378 descriptor or the value \fBAT_FDCWD\fR.
379 .RE
380
381 .sp
382 .ne 2
383 .na
384 .B EINVAL
385 .ad
386 .RS 16n
387 The argument \fIflags\fR has a non-zero value other than
388 \fBAT_SYMLINK_NOFOLLOW\fR.
389 .RE
390
391 .sp
392 .ne 2
393 .na
394 .B ENOTDIR
395 .ad
396 .RS 16n
397 The argument \fIpath\fR is a relative path and \fIfiledes\fR is a valid file
398 descriptor which does not refer to a file.
399 .RE
400
401 .sp
402 .ne 2
403 .na
404 .B EOPNOTSUPP
405 .ad
406 .RS 16n
407 The \fBAT_SYMLINK_NOFOLLOW\fR bit is set in the \fIflags\fR argument.
408 .RE
409
410 .sp
411 .LP
412 The \fBchmod()\fR and \fBfchmodat()\fR functions may fail if:
413 .sp
414 .ne 2
415 .na
416 \fB\fBELOOP\fR\fR
417 .ad
418 .RS 16n
419 More than {\fBSYMLOOP_MAX\fR} symbolic links were encountered during the
420 resolution of the \fIpath\fR argument.
421 .RE
422
423 .sp
424 .ne 2
425 .na
426 \fB\fBENAMETOOLONG\fR\fR
427 .ad
428 .RS 16n
429 As a result of encountering a symbolic link in resolution of the \fIpath\fR
430 argument, the length of the substituted pathname strings exceeds
431 {\fBPATH_MAX\fR}.
432 .RE
433
434 .sp
435 .LP
436 The \fBfchmod()\fR function may fail if:
437 .sp
438 .ne 2
439 .na
440 \fB\fBEINVAL\fR\fR
441 .ad
442 .RS 10n
443 The \fIfildes\fR argument refers to a pipe and the system disallows execution
444 of this function on a pipe.
445 .RE
446
447 .SH EXAMPLES
448 .LP
449 \fBExample 1 \fRSet Read Permissions for User, Group, and Others
450 .sp
451 .LP
452 The following example sets read permissions for the owner, group, and others.
453
454 .sp
455 .in +2
456 .nf
457 #include <sys/stat.h>
458 const char *path;
459 \&...
460 chmod(path, S_IRUSR|S_IRGRP|S_IROTH);
461 .fi
462 .in -2
463
464 .LP
465 \fBExample 2 \fRSet Read, Write, and Execute Permissions for the Owner Only
466 .sp
467 .LP
468 The following example sets read, write, and execute permissions for the owner,
469 and no permissions for group and others.
470
471 .sp
472 .in +2
473 .nf
474 #include <sys/stat.h>
475 const char *path;
476 \&...
477 chmod(path, S_IRWXU);
478 .fi
479 .in -2
480
481 .LP
482 \fBExample 3 \fRSet Different Permissions for Owner, Group, and Other
483 .sp
484 .LP
485 The following example sets owner permissions for CHANGEFILE to read, write, and
486 execute, group permissions to read and execute, and other permissions to read.
487
488 .sp
489 .in +2
490 .nf
491 #include <sys/stat.h>
492 #define CHANGEFILE "/etc/myfile"
493 \&...
494 chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH);
495 .fi
496 .in -2
497
498 .LP
499 \fBExample 4 \fRSet and Checking File Permissions
500 .sp
501 .LP
502 The following example sets the file permission bits for a file named
503 \fB/home/cnd/mod1\fR, then calls the \fBstat\fR(2) function to verify the
504 permissions.
505
506 .sp
507 .in +2
508 .nf
509 #include <sys/types.h>
510 #include <sys/stat.h>
511 int status;
512 struct stat buffer
513 \&...
514 chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH);
515 status = stat("home/cnd/mod1", &buffer;);
516 .fi
517 .in -2
518
519 .SH USAGE
520 .LP
521 If \fBchmod()\fR or \fBfchmod()\fR is used to change the file group owner
522 permissions on a file with non-trivial ACL entries, only the ACL mask is set to
523 the new permissions and the group owner permission bits in the file's mode
524 field (defined in \fBmknod\fR(2)) are unchanged. A non-trivial ACL entry is
525 one whose meaning cannot be represented in the file's mode field alone. The new
526 ACL mask permissions might change the effective permissions for additional
527 users and groups that have ACL entries on the file.
528 .SH ATTRIBUTES
529 .LP
530 See \fBattributes\fR(5) for descriptions of the following attributes:
531 .sp
532
533 .sp
534 .TS
535 box;
536 c | c
537 l | l .
538 ATTRIBUTE TYPE ATTRIBUTE VALUE
539 _
540 Interface Stability Standard
541 _
542 MT-Level Async-Signal-Safe
543 .TE
544
545 .SH SEE ALSO
546 .LP
547 \fBchmod\fR(1), \fBchown\fR(2), \fBcreat\fR(2), \fBfcntl\fR(2), \fBmknod\fR(2),
548 \fBopen\fR(2), \fBread\fR(2), \fBrename\fR(2), \fBstat\fR(2), \fBwrite\fR(2),
549 \fBfattach\fR(3C), \fBmkfifo\fR(3C), \fBstat.h\fR(3HEAD), \fBattributes\fR(5),
550 \fBprivileges\fR(5), \fBstandards\fR(5)
551 .sp
552 .LP
553 \fIProgramming Interfaces Guide\fR