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



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

NNAAMMEE
       chmod -- change the file modes

SSYYNNOOPPSSIISS
       chmod [[-R]] _m_o_d_e _f_i_l_e...

DDEESSCCRRIIPPTTIIOONN
       The _c_h_m_o_d utility shall change any or all of the file mode bits of the
       file named by each _f_i_l_e operand in the way specified by the _m_o_d_e
       operand.

       It is implementation-defined whether and how the _c_h_m_o_d utility affects
       any alternate or additional file access control mechanism (see the Base
       Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _4_._5, _F_i_l_e _A_c_c_e_s_s
       _P_e_r_m_i_s_s_i_o_n_s) 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 _c_h_m_o_d
       utility shall mark for update the last file status change timestamp of
       the file.

OOPPTTIIOONNSS
       The _c_h_m_o_d utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following option shall be supported:

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

OOPPEERRAANNDDSS
       The following operands shall be supported:

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

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

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of
       _c_h_m_o_d:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

       _L_C___C_T_Y_P_E  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).

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

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       Not used.

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

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       The _m_o_d_e operand shall be either a _s_y_m_b_o_l_i_c___m_o_d_e expression or a non-
       negative octal integer. The _s_y_m_b_o_l_i_c___m_o_d_e form is described by the
       grammar later in this section.

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

       The wwhhoo symbols uu, gg, and oo shall specify the _u_s_e_r, _g_r_o_u_p, and _o_t_h_e_r
       parts of the file mode bits, respectively. A wwhhoo consisting of the
       symbol aa shall be equivalent to uuggoo.

       The ppeerrmm symbols rr, ww, and xx represent the _r_e_a_d, _w_r_i_t_e, and
       _e_x_e_c_u_t_e/_s_e_a_r_c_h portions of file mode bits, respectively. The ppeerrmm
       symbol ss shall represent the _s_e_t_-_u_s_e_r_-_I_D_-_o_n_-_e_x_e_c_u_t_i_o_n (when wwhhoo
       contains or implies uu) and _s_e_t_-_g_r_o_u_p_-_I_D_-_o_n_-_e_x_e_c_u_t_i_o_n (when wwhhoo contains
       or implies gg) bits.

       The ppeerrmm 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 ppeerrmmccooppyy 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, ppeerrmm
       refers to the non-terminals ppeerrmm and ppeerrmmccooppyy in the grammar.

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

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

             If wwhhoo is not specified, the file mode bits represented by ppeerrmm
             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 wwhhoo
             and ppeerrmm values shall be set.

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

             If wwhhoo is not specified, the file mode bits represented by ppeerrmm
             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 wwhhoo
             and ppeerrmm values shall be cleared.

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

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

             If wwhhoo is not specified, the file mode bits represented by ppeerrmm
             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 wwhhoo
             and ppeerrmm 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 _l_s --ll _f_i_l_e writes an _s in the
           position indicating that the set-user-ID-on-execution or set-group-
           ID-on-execution is set, the commands _c_h_m_o_d uu--ss _f_i_l_e or _c_h_m_o_d gg--ss
           _f_i_l_e, 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 wwhhoo symbol oo is used in conjunction with the ppeerrmm symbol ss with
       no other wwhhoo 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 wwhhoo symbol oo in conjunction with the ppeerrmm
       symbol ss.

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

       For an octal integer _m_o_d_e 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.

     +-----------------+------------------+------------------+------------------+
     |OOccttaall   MMooddee BBiitt | OOccttaall   MMooddee BBiitt | OOccttaall   MMooddee BBiitt | OOccttaall   MMooddee BBiitt |
     +-----------------+------------------+------------------+------------------+
     |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.

   GGrraammmmaarr ffoorr cchhmmoodd
       The grammar and lexical conventions in this section describe the syntax
       for the _s_y_m_b_o_l_i_c___m_o_d_e operand. The general conventions for this style
       of grammar are described in _S_e_c_t_i_o_n _1_._3, _G_r_a_m_m_a_r _C_o_n_v_e_n_t_i_o_n_s.  A valid
       _s_y_m_b_o_l_i_c___m_o_d_e can be represented as the non-terminal symbol
       _s_y_m_b_o_l_i_c___m_o_d_e 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'
                            ;

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

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

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Some implementations of the _c_h_m_o_d utility change the mode of a
       directory before the files in the directory when performing a recursive
       (--RR 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 _c_h_m_o_d never used the _u_m_a_s_k of the process when
       changing modes; systems conformant with this volume of POSIX.1-2017 do
       so when wwhhoo 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 ffiillee was
       created with the same _u_m_a_s_k.

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

EEXXAAMMPPLLEESS
                      +------+--------------------------------+
                      |MMooddee  |            RReessuullttss             |
                      +------+--------------------------------+
                      |_a+=   | Equivalent to _a+,_a=; clears    |
                      |      | all file mode bits.            |
                      |_g_o+-w | Equivalent to _g_o+,_g_o-_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.                     |
                      |_u_o=_g  | Sets owner bits to match group |
                      |      | bits and sets other bits to    |
                      |      | match group bits.              |
                      +------+--------------------------------+
RRAATTIIOONNAALLEE
       The functionality of _c_h_m_o_d 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 _c_h_m_o_d() 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 ppeerrmm symbol ll instead of the ppeerrmm 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 _l_s and _c_h_m_o_d utilities work
       consistently in this area. If _l_s --ll _f_i_l_e indicates that the set-group-
       ID bit is set, _c_h_m_o_d gg--ss _f_i_l_e 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 _c_h_m_o_d
       utility to choose to modify these bits before calling _c_h_m_o_d() (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 ppeerrmm symbol was adopted from BSD-based systems because it
       provides commonly desired functionality when doing recursive (--RR
       option) modifications. Similar functionality is not provided by the
       _f_i_n_d utility. Historical BSD versions of _c_h_m_o_d, however, only supported
       XX with _o_p+; it has been extended in this volume of POSIX.1-2017 because
       it is also useful with _o_p=.  (It has also been added for _o_p- even
       though it duplicates xx, in this case, because it is intuitive and
       easier to explain.)

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

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _l_s, _u_m_a_s_k

       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _4_._5, _F_i_l_e _A_c_c_e_s_s
       _P_e_r_m_i_s_s_i_o_n_s, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y
       _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

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

CCOOPPYYRRIIGGHHTT
       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)
