1 CHMOD(2)                         System Calls                         CHMOD(2)
   2 
   3 
   4 
   5 NAME
   6        chmod, fchmod, fchmodat - change access permission mode of file
   7 
   8 SYNOPSIS
   9        #include <sys/types.h>
  10        #include <sys/stat.h>
  11 
  12        int chmod(const char *path, mode_t mode);
  13 
  14 
  15        int fchmod(int fildes, mode_t mode);
  16 
  17 
  18        int fchmodat(int fildes, const char *path, mode_t mode, int flag);
  19 
  20 
  21 DESCRIPTION
  22        The chmod(), fchmod(), and fchmodat() functions set the access
  23        permission portion of the mode of the file whose name is given by path
  24        or referenced by the open file descriptor fildes to the bit pattern
  25        contained in mode. Access permission bits are interpreted as follows:
  26 
  27 
  28 
  29 
  30        S_ISUID   04000   Set user ID on execution.
  31        S_ISGID   020#0   Set group ID on execution if # is 7, 5, 3, or 1. Enable mandatory file/record locking if # is 6, 4, 2, or 0.
  32        S_ISVTX   01000   Sticky bit.
  33        S_IRWXU   00700   Read, write, execute by owner.
  34        S_IRUSR   00400   Read by owner.
  35        S_IWUSR   00200   Write by owner.
  36        S_IXUSR   00100   Execute (search if a directory) by owner.
  37        S_IRWXG   00070   Read, write, execute by group.
  38        S_IRGRP   00040   Read by group.
  39        S_IWGRP   00020   Write by group.
  40        S_IXGRP   00010   Execute by group.
  41        S_IRWXO   00007   Read, write, execute (search) by others.
  42        S_IROTH   00004   Read by others.
  43        S_IWOTH   00002   Write by others.
  44        S_IXOTH   00001   Execute by others.
  45 
  46 
  47 
  48        Modes are constructed by the bitwise OR operation of the access
  49        permission bits.
  50 
  51 
  52        The effective user ID of the process must match the owner of the file
  53        or the process must have the appropriate privilege to change the mode
  54        of a file.
  55 
  56 
  57        If the process is not a privileged process and the file is not a
  58        directory, mode bit 01000 (save text image on execution) is cleared.
  59 
  60 
  61        If neither the process is privileged nor the file's group is a member
  62        of the process's  supplementary group list, and the effective group ID
  63        of the process does not match the group ID of the file, mode bit 02000
  64        (set group ID on execution) is cleared.
  65 
  66 
  67        If a directory is writable and has S_ISVTX (the sticky bit) set, files
  68        within that directory can be removed or renamed only if one or more of
  69        the following is true (see unlink(2) and rename(2)):
  70 
  71            o      the user owns the file
  72 
  73            o      the user owns the directory
  74 
  75            o      the file is writable by the user
  76 
  77            o      the user is a privileged user
  78 
  79 
  80        If a regular file is not executable and has S_ISVTX set, the file is
  81        assumed to be a swap file. In this case, the system's page cache will
  82        not be used to hold the file's data. If the S_ISVTX bit is set on any
  83        other file, the results are unspecified.
  84 
  85 
  86        If a directory has the set group ID bit set, a given file created
  87        within that directory will have  the same group ID as the directory.
  88        Otherwise, the newly created file's group ID will be set to the
  89        effective group ID of the creating process.
  90 
  91 
  92        If the mode bit 02000 (set group ID on execution) is set and the mode
  93        bit 00010 (execute or search by group) is not set, mandatory
  94        file/record locking will exist on a regular file, possibly affecting
  95        future calls to open(2), creat(2), read(2), and write(2) on this file.
  96 
  97 
  98        If fildes references a shared memory object, fchmod() need only affect
  99        the S_IRUSR, S_IRGRP, S_IROTH, S_IWUSR, S_IWGRP, S_IWOTH, S_IXUSR,
 100        S_IXGRP, and S_IXOTH file permission bits.
 101 
 102 
 103        If fildes refers to a socket, fchmod() does not fail but no action is
 104        taken.
 105 
 106 
 107        If fildes refers to a stream that is attached to an object in the file
 108        system name space with fattach(3C), the fchmod() call performs no
 109        action and returns successfully.
 110 
 111 
 112        The fchmodat() function behaves similarly to chmod(), except when path
 113        is a relative path, it is resolved relative to the directory specified
 114        by filedes. If filedes has the value AT_FDCWD, then path will be
 115        resolved relative to the current working directory. The argument flag
 116        should be zero, but may include the value AT_SYMLINK_NOFOLLOW, which
 117        indicates that if path refers to a symbolic link, then permissions
 118        should be changed on the symbolic link itself.  However, changing
 119        permissions of symbolic links is not supported on illumos, and will
 120        result in an error.
 121 
 122 
 123        Upon successful completion, chmod(), fchmod(), fchmodat() mark for
 124        update the st_ctime field of the file.
 125 
 126 RETURN VALUES
 127        Upon successful completion, 0 is returned. Otherwise, -1 is returned,
 128        the file mode is unchanged, and errno is set to indicate the error.
 129 
 130 ERRORS
 131        The chmod(), fchmod(), and fchmodat() functions will fail if:
 132 
 133        EIO
 134                 An I/O error occurred while reading from or writing to the
 135                 file system.
 136 
 137 
 138        EPERM
 139                 The effective user ID does not match the owner of the file and
 140                 the process does not have appropriate privilege.
 141 
 142                 The {PRIV_FILE_OWNER} privilege overrides constraints on
 143                 ownership when changing permissions on a file.
 144 
 145                 The {PRIV_FILE_SETID} privilege overrides constraints on
 146                 ownership when adding the setuid or setgid bits to an
 147                 executable file or a directory.  When adding the setuid bit to
 148                 a root owned executable, additional restrictions apply. See
 149                 privileges(5).
 150 
 151 
 152 
 153        The chmod() and fchmodat() functions will fail if:
 154 
 155        EACCES
 156                        Search permission is denied on a component of the path
 157                        prefix of path and for fchmodat(), filedes was not
 158                        opened with O_SEARCH requested.  The privilege
 159                        {FILE_DAC_SEARCH} overrides file permissions
 160                        restrictions in that case.
 161 
 162 
 163        EFAULT
 164                        The path argument points to an illegal address.
 165 
 166 
 167        ELOOP
 168                        A loop exists in symbolic links encountered during the
 169                        resolution of the path argument.
 170 
 171 
 172        ENAMETOOLONG
 173                        The length of the path argument exceeds PATH_MAX, or
 174                        the length of a path component exceeds NAME_MAX while
 175                        _POSIX_NO_TRUNC is in effect.
 176 
 177 
 178        ENOENT
 179                        Either a component of the path prefix or the file
 180                        referred to by path does not exist or is a null
 181                        pathname.
 182 
 183 
 184        ENOLINK
 185                        The fildes argument points to a remote machine and the
 186                        link to that machine is no longer active.
 187 
 188 
 189        ENOTDIR
 190                        A component of the prefix of path is not a directory.
 191 
 192 
 193        EROFS
 194                        The file referred to by path resides on a read-only
 195                        file system.
 196 
 197 
 198 
 199        The fchmod() function will fail if:
 200 
 201        EBADF
 202                   The fildes argument is not an open file descriptor
 203 
 204 
 205        ENOLINK
 206                   The path argument points to a remote machine and the link to
 207                   that machine is no longer active.
 208 
 209 
 210        EROFS
 211                   The file referred to by fildes resides on a read-only file
 212                   system.
 213 
 214 
 215 
 216        The chmod() and fchmod() functions may fail if:
 217 
 218        EINTR
 219                  A signal was caught during execution of the function.
 220 
 221 
 222        EINVAL
 223                  The value of the mode argument is invalid.
 224 
 225 
 226 
 227        The fchmodat() will fail if:
 228 
 229        EBADF
 230                        The argument path is a relative path and filedes is not
 231                        an open file descriptor or the value AT_FDCWD.
 232 
 233 
 234        EINVAL
 235                        The argument flags has a non-zero value other than
 236                        AT_SYMLINK_NOFOLLOW.
 237 
 238 
 239        ENOTDIR
 240                        The argument path is a relative path and filedes is a
 241                        valid file descriptor which does not refer to a file.
 242 
 243 
 244        EOPNOTSUPP
 245                        The AT_SYMLINK_NOFOLLOW bit is set in the flags
 246                        argument.
 247 
 248 
 249 
 250        The chmod() and fchmodat() functions may fail if:
 251 
 252        ELOOP
 253                        More than {SYMLOOP_MAX} symbolic links were encountered
 254                        during the resolution of the path argument.
 255 
 256 
 257        ENAMETOOLONG
 258                        As a result of encountering a symbolic link in
 259                        resolution of the path argument, the length of the
 260                        substituted pathname strings exceeds {PATH_MAX}.
 261 
 262 
 263 
 264        The fchmod() function may fail if:
 265 
 266        EINVAL
 267                  The fildes argument refers to a pipe and the system disallows
 268                  execution of this function on a pipe.
 269 
 270 
 271 EXAMPLES
 272        Example 1 Set Read Permissions for User, Group, and Others
 273 
 274 
 275        The following example sets read permissions for the owner, group, and
 276        others.
 277 
 278 
 279          #include <sys/stat.h>
 280          const char *path;
 281          ...
 282          chmod(path, S_IRUSR|S_IRGRP|S_IROTH);
 283 
 284 
 285        Example 2 Set Read, Write, and Execute Permissions for the Owner Only
 286 
 287 
 288        The following example sets read, write, and execute permissions for the
 289        owner, and no permissions for group and others.
 290 
 291 
 292          #include <sys/stat.h>
 293          const char *path;
 294          ...
 295          chmod(path, S_IRWXU);
 296 
 297 
 298        Example 3 Set Different Permissions for Owner, Group, and Other
 299 
 300 
 301        The following example sets owner permissions for CHANGEFILE to read,
 302        write, and execute, group permissions to read and execute, and other
 303        permissions to read.
 304 
 305 
 306          #include <sys/stat.h>
 307          #define CHANGEFILE "/etc/myfile"
 308          ...
 309          chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH);
 310 
 311 
 312        Example 4 Set and Checking File Permissions
 313 
 314 
 315        The following example sets the file permission bits for a file named
 316        /home/cnd/mod1, then calls the stat(2) function to verify the
 317        permissions.
 318 
 319 
 320          #include <sys/types.h>
 321          #include <sys/stat.h>
 322          int status;
 323          struct stat buffer
 324          ...
 325          chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH);
 326          status = stat("home/cnd/mod1", &buffer;);
 327 
 328 
 329 USAGE
 330        If chmod() or fchmod() is used to change the file group owner
 331        permissions on a file with non-trivial ACL entries, only the ACL mask
 332        is set to the new permissions and the group owner permission bits in
 333        the file's mode field (defined in mknod(2)) are unchanged.  A non-
 334        trivial ACL entry is one whose meaning cannot be represented in the
 335        file's mode field alone. The new ACL mask permissions  might change the
 336        effective permissions for additional users and groups that have ACL
 337        entries on the file.
 338 
 339 ATTRIBUTES
 340        See attributes(5) for descriptions of the following attributes:
 341 
 342 
 343 
 344 
 345        +--------------------+-------------------+
 346        |  ATTRIBUTE TYPE    |  ATTRIBUTE VALUE  |
 347        +--------------------+-------------------+
 348        |Interface Stability | Standard          |
 349        +--------------------+-------------------+
 350        |MT-Level            | Async-Signal-Safe |
 351        +--------------------+-------------------+
 352 
 353 SEE ALSO
 354        chmod(1), chown(2), creat(2), fcntl(2), mknod(2), open(2), read(2),
 355        rename(2), stat(2), write(2), fattach(3C), mkfifo(3C), stat.h(3HEAD),
 356        attributes(5), privileges(5), standards(5)
 357 
 358 
 359        Programming Interfaces Guide
 360 
 361 
 362 
 363                                December 22, 2014                      CHMOD(2)