CHMOD(1)                   POSIX Programmer's Manual                  CHMOD(1)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NAME
       chmod -- change the file modes

SYNOPSIS
       chmod [[-R]] mode file...

DESCRIPTION
       The chmod utility shall change any or all of the file mode bits of the
       file named by each file operand in the way specified by the mode
       operand.

       It is implementation-defined whether and how the chmod utility affects
       any alternate or additional file access control mechanism (see the Base
       Definitions volume of POSIX.1-2017, Section 4.5, File Access
       Permissions) being used for the specified file.

       Only a process whose effective user ID matches the user ID of the file,
       or a process with appropriate privileges, shall be permitted to change
       the file mode bits of a file.

       Upon successfully changing the file mode bits of a file, the chmod
       utility shall mark for update the last file status change timestamp of
       the file.

OPTIONS
       The chmod utility shall conform to the Base Definitions volume of
       POSIX.1-2017, Section 12.2, Utility Syntax Guidelines.

       The following option shall be supported:

       -R        Recursively change file mode bits. For each file operand that
                 names a directory, chmod shall change the file mode bits of
                 the directory and all files in the file hierarchy below it.

OPERANDS
       The following operands shall be supported:

       mode      Represents the change to be made to the file mode bits of
                 each file named by one of the file operands; see the EXTENDED
                 DESCRIPTION section.

       file      A pathname of a file whose file mode bits shall be modified.

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of
       chmod:

       LANG      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, Section 8.2, Internationalization
                 Variables for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       LC__ALL    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       LC__CTYPE  Determine the locale for the interpretation of sequences of
                 bytes of text data as characters (for example, single-byte as
                 opposed to multi-byte characters in arguments).

       LC__MESSAGES
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       NLSPATH   Determine the location of message catalogs for the processing
                 of LC__MESSAGES.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       Not used.

STDERR
       The standard error shall be used only for diagnostic messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       The mode operand shall be either a symbolic__mode expression or a non-
       negative octal integer. The symbolic__mode form is described by the
       grammar later in this section.

       Each clause shall specify an operation to be performed on the current
       file mode bits of each file.  The operations shall be performed on each
       file in the order in which the ccllaauussees are specified.

       The who symbols uu, gg, and oo shall specify the user, group, and other
       parts of the file mode bits, respectively. A who consisting of the
       symbol aa shall be equivalent to ugo.

       The perm symbols rr, ww, and xx represent the read, write, and
       execute/search portions of file mode bits, respectively. The perm
       symbol ss shall represent the set-user-ID-on-execution (when who
       contains or implies uu) and set-group-ID-on-execution (when who contains
       or implies gg) bits.

       The perm symbol XX shall represent the execute/search portion of the
       file mode bits if the file is a directory or if the current
       (unmodified) file mode bits have at least one of the execute bits
       (S_IXUSR, S_IXGRP, or S_IXOTH) set. It shall be ignored if the file is
       not a directory and none of the execute bits are set in the current
       file mode bits.

       The permcopy symbols uu, gg, and oo shall represent the current
       permissions associated with the user, group, and other parts of the
       file mode bits, respectively. For the remainder of this section, perm
       refers to the non-terminals perm and permcopy in the grammar.

       If multiple aaccttiioonnlliisstts are grouped with a single wholist in the
       grammar, each actionlist shall be applied in the order specified with
       that wholist.  The op symbols shall represent the operation performed,
       as follows:

       +     If perm is not specified, the ''++'' operation shall not change the
             file mode bits.

             If who is not specified, the file mode bits represented by perm
             for the owner, group, and other permissions, except for those
             with corresponding bits in the file mode creation mask of the
             invoking process, shall be set.

             Otherwise, the file mode bits represented by the specified who
             and perm values shall be set.

       -     If perm is not specified, the ''--'' operation shall not change the
             file mode bits.

             If who is not specified, the file mode bits represented by perm
             for the owner, group, and other permissions, except for those
             with corresponding bits in the file mode creation mask of the
             invoking process, shall be cleared.

             Otherwise, the file mode bits represented by the specified who
             and perm values shall be cleared.

       =     Clear the file mode bits specified by the who value, or, if no
             who value is specified, all of the file mode bits specified in
             this volume of POSIX.1-2017.

             If perm is not specified, the ''=='' operation shall make no further
             modifications to the file mode bits.

             If who is not specified, the file mode bits represented by perm
             for the owner, group, and other permissions, except for those
             with corresponding bits in the file mode creation mask of the
             invoking process, shall be set.

             Otherwise, the file mode bits represented by the specified who
             and perm values shall be set.

       When using the symbolic mode form on a regular file, it is
       implementation-defined whether or not:

        *  Requests to set the set-user-ID-on-execution or set-group-ID-on-
           execution bit when all execute bits are currently clear and none
           are being set are ignored.

        *  Requests to clear all execute bits also clear the set-user-ID-on-
           execution and set-group-ID-on-execution bits.

        *  Requests to clear the set-user-ID-on-execution or set-group-ID-on-
           execution bits when all execute bits are currently clear are
           ignored. However, if the command ls -l file writes an _s in the
           position indicating that the set-user-ID-on-execution or set-group-
           ID-on-execution is set, the commands chmod u-s file or chmod g-s
           file, respectively, shall not be ignored.

       When using the symbolic mode form on other file types, it is
       implementation-defined whether or not requests to set or clear the set-
       user-ID-on-execution or set-group-ID-on-execution bits are honored.

       If the who symbol oo is used in conjunction with the perm symbol ss with
       no other who symbols being specified, the set-user-ID-on-execution and
       set-group-ID-on-execution bits shall not be modified. It shall not be
       an error to specify the who symbol oo in conjunction with the perm
       symbol ss.

       The perm symbol tt shall specify the S_ISVTX bit. When used with a file
       of type directory, it can be used with the who symbol aa, or with no who
       symbol. It shall not be an error to specify a who symbol of uu, gg, or oo
       in conjunction with the perm symbol tt, but the meaning of these
       combinations is unspecified. The effect when using the perm symbol tt
       with any file type other than directory is unspecified.

       For an octal integer mode operand, the file mode bits shall be set
       absolutely.

       For each bit set in the octal number, the corresponding file permission
       bit shown in the following table shall be set; all other file
       permission bits shall be cleared. For regular files, for each bit set
       in the octal number corresponding to the set-user-ID-on-execution or
       the set-group-ID-on-execution, bits shown in the following table shall
       be set; if these bits are not set in the octal number, they are
       cleared. For other file types, it is implementation-defined whether or
       not requests to set or clear the set-user-ID-on-execution or set-group-
       ID-on-execution bits are honored.

     +-----------------+------------------+------------------+------------------+
     |Octal   Mode Bit | Octal   Mode Bit | Octal   Mode Bit | Octal   Mode Bit |
     +-----------------+------------------+------------------+------------------+
     |44000000    S_ISUID  | 00440000    S_IRUSR  | 00004400    S_IRGRP  | 00000044    S_IROTH  |
     +-----------------+------------------+------------------+------------------+
     |22000000    S_ISGID  | 00220000    S_IWUSR  | 00002200    S_IWGRP  | 00000022    S_IWOTH  |
     +-----------------+------------------+------------------+------------------+
     |11000000    S_ISVTX  | 00110000    S_IXUSR  | 00001100    S_IXGRP  | 00000011    S_IXOTH  |
     +-----------------+------------------+------------------+------------------+
       When bits are set in the octal number other than those listed in the
       table above, the behavior is unspecified.

   Grammar for chmod
       The grammar and lexical conventions in this section describe the syntax
       for the symbolic__mode operand. The general conventions for this style
       of grammar are described in Section 1.3, Grammar Conventions.  A valid
       symbolic__mode can be represented as the non-terminal symbol
       symbolic__mode in the grammar. This formal syntax shall take precedence
       over the preceding text syntax description.

       The lexical processing is based entirely on single characters.
       Implementations need not allow <blank> characters within the single
       argument being processed.


           %start    symbolic_mode
           %%

           symbolic_mode    : clause
                            | symbolic_mode ',' clause
                            ;

           clause           : actionlist
                            | wholist actionlist
                            ;

           wholist          : who
                            | wholist who
                            ;

           who              : 'u' | 'g' | 'o' | 'a'
                            ;

           actionlist       : action
                            | actionlist action
                            ;

           action           : op
                            | op permlist
                            | op permcopy
                            ;

           permcopy         : 'u' | 'g' | 'o'
                            ;

           op               : '+' | '-' | '='
                            ;

           permlist         : perm
                            | perm permlist
                            ;

           perm             : 'r' | 'w' | 'x' | 'X' | 's' | 't'
                            ;

EXIT STATUS
       The following exit values shall be returned:

        0    The utility executed successfully and all requested changes were
             made.

       >0    An error occurred.

CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       Some implementations of the chmod utility change the mode of a
       directory before the files in the directory when performing a recursive
       (-R option) change; others change the directory mode after the files in
       the directory. If an application tries to remove read or search
       permission for a file hierarchy, the removal attempt fails if the
       directory is changed first; on the other hand, trying to re-enable
       permissions to a restricted hierarchy fails if directories are changed
       last. Users should not try to make a hierarchy inaccessible to
       themselves.

       Some implementations of chmod never used the umask of the process when
       changing modes; systems conformant with this volume of POSIX.1-2017 do
       so when who is not specified. Note the difference between:


           chmod a-w file

       which removes all write permissions, and:


           chmod -- -w file

       which removes write permissions that would be allowed if file was
       created with the same umask.

       Conforming applications should never assume that they know how the set-
       user-ID and set-group-ID bits on directories are interpreted.

EXAMPLES
                      +------+--------------------------------+
                      |Mode  |            Results             |
                      +------+--------------------------------+
                      |_a+=   | Equivalent to _a+,_a=; clears    |
                      |      | all file mode bits.            |
                      |go+-w | Equivalent to go+,go-_w; clears |
                      |      | group and other write bits.    |
                      |_g=_o-_w | Equivalent to _g=_o,_g-_w; sets    |
                      |      | group bit to match other bits  |
                      |      | and then clears group write    |
                      |      | bit.                           |
                      |_g-_r+_w | Equivalent to _g-_r,_g+_w; clears  |
                      |      | group read bit and sets group  |
                      |      | write bit.                     |
                      |uo=_g  | Sets owner bits to match group |
                      |      | bits and sets other bits to    |
                      |      | match group bits.              |
                      +------+--------------------------------+
RATIONALE
       The functionality of chmod is described substantially through
       references to concepts defined in the System Interfaces volume of
       POSIX.1-2017. In this way, there is less duplication of effort required
       for describing the interactions of permissions. However, the behavior
       of this utility is not described in terms of the chmod() function from
       the System Interfaces volume of POSIX.1-2017 because that specification
       requires certain side-effects upon alternate file access control
       mechanisms that might not be appropriate, depending on the
       implementation.

       Implementations that support mandatory file and record locking as
       specified by the 1984 /usr/group standard historically used the
       combination of set-group-ID bit set and group execute bit clear to
       indicate mandatory locking. This condition is usually set or cleared
       with the symbolic mode perm symbol ll instead of the perm symbols ss and
       xx so that the mandatory locking mode is not changed without explicit
       indication that that was what the user intended. Therefore, the details
       on how the implementation treats these conditions must be defined in
       the documentation. This volume of POSIX.1-2017 does not require
       mandatory locking (nor does the System Interfaces volume of
       POSIX.1-2017), but does allow it as an extension. However, this volume
       of POSIX.1-2017 does require that the ls and chmod utilities work
       consistently in this area. If ls -l file indicates that the set-group-
       ID bit is set, chmod g-s file must clear it (assuming appropriate
       privileges exist to change modes).

       The System V and BSD versions use different exit status codes. Some
       implementations used the exit status as a count of the number of errors
       that occurred; this practice is unworkable since it can overflow the
       range of valid exit status values. This problem is avoided here by
       specifying only 0 and >0 as exit values.

       The System Interfaces volume of POSIX.1-2017 indicates that
       implementation-defined restrictions may cause the S_ISUID and S_ISGID
       bits to be ignored. This volume of POSIX.1-2017 allows the chmod
       utility to choose to modify these bits before calling chmod() (or some
       function providing equivalent capabilities) for non-regular files.
       Among other things, this allows implementations that use the set-user-
       ID and set-group-ID bits on directories to enable extended features to
       handle these extensions in an intelligent manner.

       The XX perm symbol was adopted from BSD-based systems because it
       provides commonly desired functionality when doing recursive (-R
       option) modifications. Similar functionality is not provided by the
       find utility. Historical BSD versions of chmod, however, only supported
       XX with op+; it has been extended in this volume of POSIX.1-2017 because
       it is also useful with op=.  (It has also been added for op- even
       though it duplicates xx, in this case, because it is intuitive and
       easier to explain.)

       The grammar was extended with the permcopy non-terminal to allow
       historical-practice forms of symbolic modes like oo=uu -g (that is, set
       the ``other'' permissions to the permissions of ``owner'' minus the
       permissions of ``group'').

FUTURE DIRECTIONS
       None.

SEE ALSO
       ls, umask

       The Base Definitions volume of POSIX.1-2017, Section 4.5, File Access
       Permissions, Chapter _8, Environment Variables, Section 12.2, Utility
       Syntax Guidelines

       The System Interfaces volume of POSIX.1-2017, chmod()

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version 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 .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                             CHMOD(1)
