chmod(P)                                               chmod(P)





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
       IEEE Std 1003.1-2001, Section 4.4, File  Access  Permis-
       sions) being used for the specified file.

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

OPTIONS
       The chmod utility shall conform to the Base  Definitions
       volume  of  IEEE Std 1003.1-2001,  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  oper-
              ands; 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 internationaliza-
              tion variables that are unset or null.  (See  the
              Base  Definitions volume of IEEE Std 1003.1-2001,
              Section 8.2, Internationalization  Variables  for
              the  precedence of internationalization variables
              used to determine  the  values  of  locale  cate-
              gories.)

       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 mes-
              sages 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 expres-
       sion  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  opera-
       tions  shall  be  performed on each file in the order in
       which the clauses are specified.

       The who symbols u, g, and  o  shall  specify  the  user,
       group,  and  other  parts of the file mode bits, respec-
       tively. A who consisting of the symbol a shall be equiv-
       alent to ugo.

       The  perm symbols r, w, and x represent the read, write,
       and execute/ search portions of file mode bits,  respec-
       tively.  The perm symbol s shall represent the set-user-
       ID-on-execution (when who contains  or  implies  u)  and
       set-group-ID-on-execution  (when who contains or implies
       g) bits.

       The perm symbol X  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 u, g, and  o  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-termi-
       nals perm and permcopy in the grammar.

       If  multiple  actionlists  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  speci-
       fied 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  speci-
       fied 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
              IEEE Std 1003.1-2001.

       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 speci-
       fied 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-exe-
              cution 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 posi-
              tion 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 o is used in conjunction with the perm
       symbol  s 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 o in conjunction  with  the  perm
       symbol s.

       The  perm  symbol  t shall specify the S_ISVTX bit. When
       used with a file of type directory, it can be used  with
       the who symbol a, or with no who symbol. It shall not be
       an error to specify a who symbol of u, g, or o  in  con-
       junction  with  the  perm  symbol  t, but the meaning of
       these combinations  is  unspecified.   The  effect  when
       using  the  perm  symbol t 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
4000      S_ISUID      0400      S_IRUSR      0040      S_IRGRP      0004      S_IROTH
2000      S_ISGID      0200      S_IWUSR      0020      S_IWGRP      0002      S_IWOTH
1000      S_ISVTX      0100      S_IXUSR      0010      S_IXGRP      0001      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 Grammar Conventions . A valid symbolic_mode
       can  be  represented  as  the  non-terminal  symbol sym-
       bolic_mode in the grammar. This formal syntax shall take
       precedence over the preceding text syntax description.

       The lexical processing is based entirely on single char-
       acters. Implementations need not allow  <blank>s  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 direc-
       tory. 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 them-
       selves.

       Some implementations of chmod never  used  the  process'
       umask  when changing modes; systems conformant with this
       volume of IEEE Std 1003.1-2001 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 direc-
       tories 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 IEEE Std 1003.1-2001. 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   IEEE Std 1003.1-2001   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 l instead of the perm sym-
       bols s and x 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
       IEEE Std 1003.1-2001  does not require mandatory locking
       (nor   does   the   System    Interfaces    volume    of
       IEEE Std 1003.1-2001),  but  does  allow it as an exten-
       sion. However, this volume of IEEE Std 1003.1-2001  does
       require  that  the  ls  and chmod utilities work consis-
       tently 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 prac-
       tice 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  IEEE Std 1003.1-2001
       indicates  that  implementation-defined restrictions may
       cause the S_ISUID and S_ISGID bits to be  ignored.  This
       volume  of IEEE Std 1003.1-2001 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  X  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.  His-
       torical BSD versions of chmod, however, only supported X
       with op+;  it  has  been  extended  in  this  volume  of
       IEEE Std 1003.1-2001 because it is also useful with op=.
       (It has also been added for op- even  though  it  dupli-
       cates  x, in this case, because it is intuitive and eas-
       ier to explain.)

       The grammar was extended with the permcopy  non-terminal
       to  allow  historical-practice  forms  of symbolic modes
       like o= u -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   System   Interfaces   volume   of
       IEEE Std 1003.1-2001, chmod()

COPYRIGHT
       Portions  of  this  text are reprinted and reproduced in
       electronic form from  IEEE  Std  1003.1,  2003  Edition,
       Standard  for Information Technology -- Portable Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute 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.open-
       group.org/unix/online.html .



POSIX                         2003                     chmod(P)
