chmod

Purpose

     Changes file access permissions.

Syntax

     #include <sys/stat.h>

     int chmod (path, mode)
     char *path;
     int mode;

Description

     The chmod system call sets  the access permissions of the
     file  specified by  the path  parameter.  If  Distributed
     Services is installed on your system, this path can cross
     into another  node.  The  access permissions of  the file
     are set  according to  the bit  pattern specified  by the
     mode parameter.

     To change file access  permissions, the effective user ID
     of the calling process must  either be superuser or match
     the ID of the file's owner.

     The mode parameter is constructed by logically OR-ing one
     or more of the following values, which are defined in the
     sys/stat.h header file:

     S_ISUID    Sets the  process's effective  user ID  to the
                file's owner on execution.
     S_ISGID    Sets the  process's effective group ID  to the
                file's group on execution.
     S_ISVTX    Saves text image after execution.
     S_ENFMT    Enables enforcement-mode record locking.
     S_IRUSR    Permits the file's owner to read it.
     S_IWUSR    Permits the file's owner to write to it.
     S_IXUSR    Permits the file's owner  to execute it (or to
                search the directory).
     S_IRGRP    Permits the file's group to read it.
     S_IWGRP    Permits the file's group to write to it.
     S_IXGRP    Permits the file's group  to execute it (or to
                search the directory).
     S_IROTH    Permits others to read the file.
     S_IWOTH    Permits others to write to the file.
     S_IXOTH    Permits  others to  execute  the  file (or  to
                search the directory).

     Other mode  values exist that  can be set with  the mknod
     system call, but not with  chmod.  A complete list of the
     possible file mode values and other useful macros appears
     in "stat.h."

     Setting S_ISVTX for a shared executable file prevents the
     system  from unmapping  the program  text segment  of the
     file when its last user  terminates.  Thus, when the next
     process executes it,  the text need not be  read from the
     file system.  It is simply paged in, saving time.

     If S_ENFMT  is set  and no  execute permissions  are set,
     then file locks placed on  the file with the lockf system
     call are  enforced locks.  See "lockf"  for details about
     locking regions of a file.

     If the  effective user ID  of the calling process  is not
     superuser and the  file is not a  character special file,
     then the chmod system call clears the S_ISVTX bit.

     If the  effective user ID of  the process is not  that of
     superuser, and  if the effective  group ID or one  of the
     IDs  in the  group access  list of  the process  does not
     match the file's existing group ID, then the chmod system
     call  clears  the  S_ISGID  bit.   (See  "getgroups"  and
     "setgroups" for  more information about the  group access
     list.)

Return Value

     Upon successful completion, the chmod system call returns
     a value of 0.  If the chmod system call fails, a value of
     -1 is returned, and errno is set to indicate the error.

Diagnostics

     The  chmod system  call  fails and  the file  permissions
     remain  unchanged if  one or  more of  the following  are
     true:

     ENOTDIR    A  component of  the path  parameter is  not a
                directory.

     ENOENT     The named file does not exist.

     EACCES     A component  of the path parameter  has search
                permission denied.

     EPERM      The effective user ID does not match the ID of
                the owner of the file or the ID of superuser.

     EROFS      The  named file  resides on  a read-only  file
                system.

     EFAULT     The path parameter &pointsout..

     ESTALE     The  process's root  or  current directory  is
                located in a virtual file system that has been
                unmounted.

     If  Distributed Services  is  installed  on your  system,
     chmod can also  fail if one or more of  the following are
     true:

     EDIST         The   server   has  blocked   new   inbound
                   requests.

     EDIST         Outbound requests are currently blocked.

     EDIST         The server has a  release level of Distrib-
                   uted Services that  cannot communicate with
                   this node.

     EAGAIN        The  server  is  too  busy  to  accept  the
                   request.

     ESTALE        The file  descriptor for a remote  file has
                   become obsolete.

     EPERM         The translate tables of  the server did not
                   contain any entry  for either the effective
                   user  ID  or  effective  group  ID  of  the
                   calling process.

     ENODEV        The named file is  a remote file located on
                   a  device that  has been  unmounted at  the
                   server.

     ENOMEM        Either  this node  or the  server does  not
                   have enough memory available to service the
                   request.

     ENOCONNECT    An attempt to establish  a new network con-
                   nection with a remote node failed.

     EBADCONNECT   An attempt to use  an existing network con-
                   nection with a remote node failed.

Related Information

     In  this book:   "chown, chownx,"   "getgroups," "mknod,"
     and  "setgroups."

     The chmod command in AIX Operating System Commands Refer-
     ence.