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 .