| blob | cecd79a1e77e4c356f762823a469a5693ca89742 |
1 '\" te
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 .TH CHMOD 2 "Sep 12, 2005"
13 .SH NAME
14 chmod, fchmod \- change access permission mode of file
15 .SH SYNOPSIS
16 .LP
17 .nf
18 #include <sys/types.h>
19 #include <sys/stat.h>
21 \fBint\fR \fBchmod\fR(\fBconst char *\fR\fIpath\fR, \fBmode_t\fR \fImode\fR);
22 .fi
24 .LP
25 .nf
26 \fBint\fR \fBfchmod\fR(\fBint\fR \fIfildes\fR, \fBmode_t\fR \fImode\fR);
27 .fi
29 .SH DESCRIPTION
30 .sp
31 .LP
32 The \fBchmod()\fR and \fBfchmod()\fR functions set the access permission
33 portion of the mode of the file whose name is given by \fIpath\fR or referenced
34 by the open file descriptor \fIfildes\fR to the bit pattern contained in
35 \fImode\fR. Access permission bits are interpreted as follows:
36 .sp
38 .sp
39 .TS
40 l l l
41 l l l .
42 \fBS_ISUID\fR 04000 Set user ID on execution.
43 \fBS_ISGID\fR 020#0 T{
44 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.
45 T}
46 \fBS_ISVTX\fR 01000 Sticky bit.
47 \fBS_IRWXU\fR 00700 Read, write, execute by owner.
48 \fBS_IRUSR\fR 00400 Read by owner.
49 \fBS_IWUSR\fR 00200 Write by owner.
50 \fBS_IXUSR\fR 00100 T{
51 Execute (search if a directory) by owner.
52 T}
53 \fBS_IRWXG\fR 00070 Read, write, execute by group.
54 \fBS_IRGRP\fR 00040 Read by group.
55 \fBS_IWGRP\fR 00020 Write by group.
56 \fBS_IXGRP\fR 00010 Execute by group.
57 \fBS_IRWXO\fR 00007 Read, write, execute (search) by others.
58 \fBS_IROTH\fR 00004 Read by others.
59 \fBS_IWOTH\fR 00002 Write by others.
60 \fBS_IXOTH\fR 00001 Execute by others.
61 .TE
63 .sp
64 .LP
65 Modes are constructed by the bitwise OR operation of the access permission
66 bits.
67 .sp
68 .LP
69 The effective user ID of the process must match the owner of the file or the
70 process must have the appropriate privilege to change the mode of a file.
71 .sp
72 .LP
73 If the process is not a privileged process and the file is not a directory,
74 mode bit 01000 (save text image on execution) is cleared.
75 .sp
76 .LP
77 If neither the process is privileged nor the file's group is a member of the
78 process's supplementary group list, and the effective group ID of the process
79 does not match the group ID of the file, mode bit 02000 (set group ID on
80 execution) is cleared.
81 .sp
82 .LP
83 If a directory is writable and has \fBS_ISVTX\fR (the sticky bit) set, files
84 within that directory can be removed or renamed only if one or more of the
85 following is true (see \fBunlink\fR(2) and \fBrename\fR(2)):
86 .RS +4
87 .TP
88 .ie t \(bu
89 .el o
90 the user owns the file
91 .RE
92 .RS +4
93 .TP
94 .ie t \(bu
95 .el o
96 the user owns the directory
97 .RE
98 .RS +4
99 .TP
100 .ie t \(bu
101 .el o
102 the file is writable by the user
103 .RE
104 .RS +4
105 .TP
106 .ie t \(bu
107 .el o
108 the user is a privileged user
109 .RE
110 .sp
111 .LP
112 If a regular file is not executable and has \fBS_ISVTX\fR set, the file is
113 assumed to be a swap file. In this case, the system's page cache will not be
114 used to hold the file's data. If the \fBS_ISVTX\fR bit is set on any other
115 file, the results are unspecified.
116 .sp
117 .LP
118 If a directory has the set group ID bit set, a given file created within that
119 directory will have the same group ID as the directory. Otherwise, the newly
120 created file's group ID will be set to the effective group ID of the creating
121 process.
122 .sp
123 .LP
124 If the mode bit 02000 (set group ID on execution) is set and the mode bit 00010
125 (execute or search by group) is not set, mandatory file/record locking will
126 exist on a regular file, possibly affecting future calls to \fBopen\fR(2),
127 \fBcreat\fR(2), \fBread\fR(2), and \fBwrite\fR(2) on this file.
128 .sp
129 .LP
130 If \fIfildes\fR references a shared memory object, \fBfchmod()\fR need only
131 affect the \fBS_IRUSR\fR, \fBS_IRGRP\fR, \fBS_IROTH\fR, \fBS_IWUSR\fR,
132 \fBS_IWGRP\fR, \fBS_IWOTH\fR, \fBS_IXUSR\fR, \fBS_IXGRP\fR, and \fBS_IXOTH\fR
133 file permission bits.
134 .sp
135 .LP
136 If \fIfildes\fR refers to a socket, \fBfchmod()\fR does not fail but no action
137 is taken.
138 .sp
139 .LP
140 If \fIfildes\fR refers to a stream that is attached to an object in the file
141 system name space with \fBfattach\fR(3C), the \fBfchmod()\fR call performs no
142 action and returns successfully.
143 .sp
144 .LP
145 Upon successful completion, \fBchmod()\fR and \fBfchmod()\fR mark for update
146 the \fBst_ctime\fR field of the file.
147 .SH RETURN VALUES
148 .sp
149 .LP
150 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
151 returned, the file mode is unchanged, and \fBerrno\fR is set to indicate the
152 error.
153 .SH ERRORS
154 .sp
155 .LP
156 The \fBchmod()\fR and \fBfchmod()\fR functions will fail if:
157 .sp
158 .ne 2
159 .na
160 \fB\fBEIO\fR\fR
161 .ad
162 .RS 9n
163 An I/O error occurred while reading from or writing to the file system.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fBEPERM\fR\fR
170 .ad
171 .RS 9n
172 The effective user ID does not match the owner of the file and the process does
173 not have appropriate privilege.
174 .sp
175 The {\fBPRIV_FILE_OWNER\fR} privilege overrides constraints on ownership when
176 changing permissions on a file.
177 .sp
178 The {\fBPRIV_FILE_SETID\fR} privilege overrides constraints on ownership when
179 adding the setuid or setgid bits to an executable file or a directory. When
180 adding the setuid bit to a root owned executable, additional restrictions
181 apply. See \fBprivileges\fR(5).
182 .RE
184 .sp
185 .LP
186 The \fBchmod()\fR function will fail if:
187 .sp
188 .ne 2
189 .na
190 \fB\fBEACCES\fR\fR
191 .ad
192 .RS 16n
193 Search permission is denied on a component of the path prefix of \fIpath\fR.
194 The privilege {\fBFILE_DAC_SEARCH\fR} overrides file permissions restrictions
195 in that case.
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fBEFAULT\fR\fR
202 .ad
203 .RS 16n
204 The \fIpath\fR argument points to an illegal address.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fBELOOP\fR\fR
211 .ad
212 .RS 16n
213 A loop exists in symbolic links encountered during the resolution of the
214 \fIpath\fR argument.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fBENAMETOOLONG\fR\fR
221 .ad
222 .RS 16n
223 The length of the \fIpath\fR argument exceeds \fBPATH_MAX\fR, or the length of
224 a \fIpath\fR component exceeds \fBNAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in
225 effect.
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fBENOENT\fR\fR
232 .ad
233 .RS 16n
234 Either a component of the path prefix or the file referred to by \fIpath\fR
235 does not exist or is a null pathname.
236 .RE
238 .sp
239 .ne 2
240 .na
241 \fB\fBENOLINK\fR\fR
242 .ad
243 .RS 16n
244 The \fIfildes\fR argument points to a remote machine and the link to that
245 machine is no longer active.
246 .RE
248 .sp
249 .ne 2
250 .na
251 \fB\fBENOTDIR\fR\fR
252 .ad
253 .RS 16n
254 A component of the prefix of \fIpath\fR is not a directory.
255 .RE
257 .sp
258 .ne 2
259 .na
260 \fB\fBEROFS\fR\fR
261 .ad
262 .RS 16n
263 The file referred to by \fIpath\fR resides on a read-only file system.
264 .RE
266 .sp
267 .LP
268 The \fBfchmod()\fR function will fail if:
269 .sp
270 .ne 2
271 .na
272 \fB\fBEBADF\fR\fR
273 .ad
274 .RS 11n
275 The \fIfildes\fR argument is not an open file descriptor
276 .RE
278 .sp
279 .ne 2
280 .na
281 \fB\fBENOLINK\fR\fR
282 .ad
283 .RS 11n
284 The \fIpath\fR argument points to a remote machine and the link to that machine
285 is no longer active.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fBEROFS\fR\fR
292 .ad
293 .RS 11n
294 The file referred to by \fIfildes\fR resides on a read-only file system.
295 .RE
297 .sp
298 .LP
299 The \fBchmod()\fR and \fBfchmod()\fR functions may fail if:
300 .sp
301 .ne 2
302 .na
303 \fB\fBEINTR\fR\fR
304 .ad
305 .RS 10n
306 A signal was caught during execution of the function.
307 .RE
309 .sp
310 .ne 2
311 .na
312 \fB\fBEINVAL\fR\fR
313 .ad
314 .RS 10n
315 The value of the \fImode\fR argument is invalid.
316 .RE
318 .sp
319 .LP
320 The \fBchmod()\fR function may fail if:
321 .sp
322 .ne 2
323 .na
324 \fB\fBELOOP\fR\fR
325 .ad
326 .RS 16n
327 More than {\fBSYMLOOP_MAX\fR} symbolic links were encountered during the
328 resolution of the \fIpath\fR argument.
329 .RE
331 .sp
332 .ne 2
333 .na
334 \fB\fBENAMETOOLONG\fR\fR
335 .ad
336 .RS 16n
337 As a result of encountering a symbolic link in resolution of the\fIpath\fR
338 argument, the length of the substituted pathname strings exceeds
339 {\fBPATH_MAX\fR}.
340 .RE
342 .sp
343 .LP
344 The \fBfchmod()\fR function may fail if:
345 .sp
346 .ne 2
347 .na
348 \fB\fBEINVAL\fR\fR
349 .ad
350 .RS 10n
351 The \fIfildes\fR argument refers to a pipe and the system disallows execution
352 of this function on a pipe.
353 .RE
355 .SH EXAMPLES
356 .LP
357 \fBExample 1 \fRSet Read Permissions for User, Group, and Others
358 .sp
359 .LP
360 The following example sets read permissions for the owner, group, and others.
362 .sp
363 .in +2
364 .nf
365 #include <sys/stat.h>
366 const char *path;
367 \&...
368 chmod(path, S_IRUSR|S_IRGRP|S_IROTH);
369 .fi
370 .in -2
372 .LP
373 \fBExample 2 \fRSet Read, Write, and Execute Permissions for the Owner Only
374 .sp
375 .LP
376 The following example sets read, write, and execute permissions for the owner,
377 and no permissions for group and others.
379 .sp
380 .in +2
381 .nf
382 #include <sys/stat.h>
383 const char *path;
384 \&...
385 chmod(path, S_IRWXU);
386 .fi
387 .in -2
389 .LP
390 \fBExample 3 \fRSet Different Permissions for Owner, Group, and Other
391 .sp
392 .LP
393 The following example sets owner permissions for CHANGEFILE to read, write, and
394 execute, group permissions to read and execute, and other permissions to read.
396 .sp
397 .in +2
398 .nf
399 #include <sys/stat.h>
400 #define CHANGEFILE "/etc/myfile"
401 \&...
402 chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH);
403 .fi
404 .in -2
406 .LP
407 \fBExample 4 \fRSet and Checking File Permissions
408 .sp
409 .LP
410 The following example sets the file permission bits for a file named
411 \fB/home/cnd/mod1\fR, then calls the \fBstat\fR(2) function to verify the
412 permissions.
414 .sp
415 .in +2
416 .nf
417 #include <sys/types.h>
418 #include <sys/stat.h>
419 int status;
420 struct stat buffer
421 \&...
422 chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH);
423 status = stat("home/cnd/mod1", &buffer;);
424 .fi
425 .in -2
427 .SH USAGE
428 .sp
429 .LP
430 If \fBchmod()\fR or \fBfchmod()\fR is used to change the file group owner
431 permissions on a file with non-trivial ACL entries, only the ACL mask is set to
432 the new permissions and the group owner permission bits in the file's mode
433 field (defined in \fBmknod\fR(2)) are unchanged. A non-trivial ACL entry is
434 one whose meaning cannot be represented in the file's mode field alone. The new
435 ACL mask permissions might change the effective permissions for additional
436 users and groups that have ACL entries on the file.
437 .SH ATTRIBUTES
438 .sp
439 .LP
440 See \fBattributes\fR(5) for descriptions of the following attributes:
441 .sp
443 .sp
444 .TS
445 box;
446 c | c
447 l | l .
448 ATTRIBUTE TYPE ATTRIBUTE VALUE
449 _
450 Interface Stability Standard
451 _
452 MT-Level Async-Signal-Safe
453 .TE
455 .SH SEE ALSO
456 .sp
457 .LP
458 \fBchmod\fR(1), \fBchown\fR(2), \fBcreat\fR(2), \fBfcntl\fR(2), \fBmknod\fR(2),
459 \fBopen\fR(2), \fBread\fR(2), \fBrename\fR(2), \fBstat\fR(2), \fBwrite\fR(2),
460 \fBfattach\fR(3C), \fBmkfifo\fR(3C), \fBstat.h\fR(3HEAD), \fBattributes\fR(5),
461 \fBprivileges\fR(5), \fBstandards\fR(5)
462 .sp
463 .LP
464 \fIProgramming Interfaces Guide\fR