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>
20
21 \fBint\fR \fBchmod\fR(\fBconst char *\fR\fIpath\fR, \fBmode_t\fR \fImode\fR);
22 .fi
23
24 .LP
25 .nf
26 \fBint\fR \fBfchmod\fR(\fBint\fR \fIfildes\fR, \fBmode_t\fR \fImode\fR);
27 .fi
28
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
37
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
62
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
165
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
183
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
197
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
206
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
216
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
227
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
237
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
247
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
256
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
265
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
277
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
287
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
296
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
308
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
317
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
330
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
341
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
354
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.
361
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
371
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.
378
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
388
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.
395
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
405
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.
413
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
426
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
442
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
454
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
|
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 .
|