CHMOD(2,L) AIX Technical Reference CHMOD(2,L)
-------------------------------------------------------------------------------
chmod, fchmod
PURPOSE
Changes file access permissions.
LIBRARY
Standard C Library (libc.a)
SYNTAX
#include <sys/stat.h>
int chmod (path, mode) int fchmod (fd, mode)
char *path; int fd, mode;
int mode;
DESCRIPTION
The chmod system call sets the access permissions of the file specified by the
path parameter.
The fchmod system call sets the access permissions on the open file specified
by the file descriptor parameter fd. If path names a symbolic link, chmod sets
the access permissions on the file to which the symbolic link points. If path
names a hidden directory, chmod sets the access permission on a selected file
within the hidden directory. 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 ORing 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.
Processed November 7, 1990 CHMOD(2,L) 1
CHMOD(2,L) AIX Technical Reference CHMOD(2,L)
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 or fchmod. A complete list of the possible file mode values and
other useful macros appears in "stat.h."
Setting S_ISVTX on 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. The calling process must have superuser
authority to set the S_ISVTX mode bit on a regular file.
Setting S_ISVTX on a directory marks that directory such that only the
following users may remove files from the directory:
1. the owner of the directory, or
2. the owner of the files, or
3. a process with superuser authority.
Setting S_ISVTX on a character special file marks that file as a multiplex
special file. Multiplex special files are special files which appear to the
system to be a directory full of special files and are used to implement
virtual devices such as /dev/hft. See "hft."
Setting S_ENFMT (which has the same value as S_ISGID) on a regular file, while
setting no execute permission bits, marks the file such that all file locks
placed on the file with fcntl, lockf or flock are treated as enforced record
locks (see "fcntl.h"). It is undefined what the behavior is if the S_ENFMT
mode bit is changed on a file which has existing record locks. Attempts to do
this in subsequent releases of AIX may result in an error being returned.
Setting S_ISGID on a directory marks the directory in BSD compatibility mode,
causing files and directories subsequently created within the directory to
inherit their group IDs from this directory. Otherwise, newly created files
and directories inherit their group IDs from the effective group ID of the
process which created them.
Setting S_ISGID on a regular file along with one of the three execute
permission bits enables the set-group-ID behavior of exec. This is permitted
only if the calling process has superuser authority or if one of the IDs in the
calling process's group access list matches the group ID file. Otherwise, the
S_ISGID bit is cleared (see "getgroups" or "setgroups" for more information
about group access lists).
Processed November 7, 1990 CHMOD(2,L) 2
CHMOD(2,L) AIX Technical Reference CHMOD(2,L)
RETURN VALUE
Upon successful completion, the chmod and fchmod system calls return a value of
0. If the chmod or fchmod system call fails, a value of -1 is returned, and
errno is set to indicate the error.
ERROR CONDITIONS
The chmod system call fails and the file permissions remain unchanged if one or
more of the following is 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.
EFAULT The path parameter points to a location outside of the process's
allocated address space.
ENAMETOOLONG
A component of the path parameter exceeds NAME_MAX characters or the
entire path parameter exceeds PATH_MAX characters.
ENOENT A hidden directory is named, but no component inside it matches the
process's current site path list.
ENOENT A symbolic link is named, but the file to which it refers does not
exist.
ELOOP A loop of symbolic links is detected.
ENOSTORE The path is a name relative to the working directory, but no site
which stores this directory is currently up.
EINTR A signal is caught during the chmod system call.
The fchmod system call fails and file permissions remain unchanged if one or
more of the following are true:
EBADF The descriptor is not valid.
EINVAL fd refers to a socket, not to a file.
The chmod and fchmod system calls fail and file permissions remain unchanged if
one or more of the following are true:
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.
Processed November 7, 1990 CHMOD(2,L) 3
CHMOD(2,L) AIX Technical Reference CHMOD(2,L)
ESTALE The process's root or current directory is located in an NFS virtual
file system that has been unmounted.
If the Transparent Computing Facility is installed on your system, chmod can
also fail if one or more of the following are true:
ESITEDN1 The specified file cannot be accessed because a site failed.
ESITEDN2 The operation was terminated because a site failed.
ENOSTORE The file specified by fd or a component of the path is replicated but
is not stored on any site which is currently up.
EROFS Write access is requested for a file on a replicated file system in
which the primary copy is unavailable.
EIO An I/O error occurs while reading from or writing to a file system.
RELATED INFORMATION
In this book: "chown, fchown," "getgroups," "mknod, mknodx, mkfifo," and
"setgroups."
The chmod command in AIX Operating System Commands Reference.
Processed November 7, 1990 CHMOD(2,L) 4