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/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
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.
25 .\" This notice shall appear on any product containing this material.
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.
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.
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]
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.
48 .TH CHMOD 2 "Dec 22, 2014"
50 chmod, fchmod, fchmodat \- change access permission mode of file
54 #include <sys/types.h>
57 \fBint\fR \fBchmod\fR(\fBconst char *\fR\fIpath\fR, \fBmode_t\fR \fImode\fR);
62 \fBint\fR \fBfchmod\fR(\fBint\fR \fIfildes\fR, \fBmode_t\fR \fImode\fR);
67 \fBint\fR \fBfchmodat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR, \fBmode_t\fR \fImode\fR, \fBint\fR \fIflag\fR);
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:
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.
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.
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.
105 Modes are constructed by the bitwise OR operation of the access permission
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.
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.
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.
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)):
130 the user owns the file
136 the user owns the directory
142 the file is writable by the user
148 the user is a privileged user
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.
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
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.
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.
176 If \fIfildes\fR refers to a socket, \fBfchmod()\fR does not fail but no action
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.
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.
196 Upon successful completion, \fBchmod()\fR, \fBfchmod()\fR, \fBfchmodat()\fR mark
197 for update the \fBst_ctime\fR field of the file.
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
205 The \fBchmod()\fR, \fBfchmod()\fR, and \fBfchmodat()\fR functions will fail if:
212 An I/O error occurred while reading from or writing to the file system.
221 The effective user ID does not match the owner of the file and the process does
222 not have appropriate privilege.
224 The {\fBPRIV_FILE_OWNER\fR} privilege overrides constraints on ownership when
225 changing permissions on a file.
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).
235 The \fBchmod()\fR and \fBfchmodat()\fR functions will fail if:
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 requested.
244 The privilege {\fBFILE_DAC_SEARCH\fR} overrides file permissions restrictions
254 The \fIpath\fR argument points to an illegal address.
263 A loop exists in symbolic links encountered during the resolution of the
270 \fB\fBENAMETOOLONG\fR\fR
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
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.
294 The \fIfildes\fR argument points to a remote machine and the link to that
295 machine is no longer active.
304 A component of the prefix of \fIpath\fR is not a directory.
313 The file referred to by \fIpath\fR resides on a read-only file system.
318 The \fBfchmod()\fR function will fail if:
325 The \fIfildes\fR argument is not an open file descriptor
334 The \fIpath\fR argument points to a remote machine and the link to that machine
344 The file referred to by \fIfildes\fR resides on a read-only file system.
349 The \fBchmod()\fR and \fBfchmod()\fR functions may fail if:
356 A signal was caught during execution of the function.
365 The value of the \fImode\fR argument is invalid.
370 The \fBfchmodat()\fR will fail if:
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.
387 The argument \fIflags\fR has a non-zero value other than
388 \fBAT_SYMLINK_NOFOLLOW\fR.
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.
407 The \fBAT_SYMLINK_NOFOLLOW\fR bit is set in the \fIflags\fR argument.
412 The \fBchmod()\fR and \fBfchmodat()\fR functions may fail if:
419 More than {\fBSYMLOOP_MAX\fR} symbolic links were encountered during the
420 resolution of the \fIpath\fR argument.
426 \fB\fBENAMETOOLONG\fR\fR
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
436 The \fBfchmod()\fR function may fail if:
443 The \fIfildes\fR argument refers to a pipe and the system disallows execution
444 of this function on a pipe.
449 \fBExample 1 \fRSet Read Permissions for User, Group, and Others
452 The following example sets read permissions for the owner, group, and others.
457 #include <sys/stat.h>
460 chmod(path, S_IRUSR|S_IRGRP|S_IROTH);
465 \fBExample 2 \fRSet Read, Write, and Execute Permissions for the Owner Only
468 The following example sets read, write, and execute permissions for the owner,
469 and no permissions for group and others.
474 #include <sys/stat.h>
477 chmod(path, S_IRWXU);
482 \fBExample 3 \fRSet Different Permissions for Owner, Group, and Other
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.
491 #include <sys/stat.h>
492 #define CHANGEFILE "/etc/myfile"
494 chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH);
499 \fBExample 4 \fRSet and Checking File Permissions
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
509 #include <sys/types.h>
510 #include <sys/stat.h>
514 chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH);
515 status = stat("home/cnd/mod1", &buffer;);
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.
530 See \fBattributes\fR(5) for descriptions of the following attributes:
538 ATTRIBUTE TYPE ATTRIBUTE VALUE
540 Interface Stability Standard
542 MT-Level Async-Signal-Safe
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)
553 \fIProgramming Interfaces Guide\fR