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