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 requested.
 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