chmod(2)

NAME

chmod(), fchmod() — change file mode access permissions

SYNOPSIS

#include <sys/stat.h>

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

int fchmod(int fildes, mode_t mode);

DESCRIPTION

The chmod() and fchmod() system calls set the access permission portion of the file's mode according to the bit pattern contained in mode. path points to a path name naming a file. fildes is a file descriptor.

The following symbolic constants representing the access permission bits are defined with the indicated values in <sys/stat.h> and are used to construct the mode argument. The value of mode is the bit-wise inclusive OR of the values for the desired permissions.

S_ISUID 04000 Set user ID on execution.
S_ISGID 02000 Set group ID on execution.
S_ENFMT 02000 Record locking enforced.
S_ISVTX 01000 Sticky bit (see below).
S_IRUSR 00400 Read by owner.
S_IWUSR 00200 Write by owner.
S_IXUSR 00100 Execute (search) by owner.
S_IRGRP 00040 Read by group.
S_IWGRP 00020 Write by group.
S_IXGRP 00010 Execute (search) by group.
S_IROTH 00004 Read by others (that is, anybody else).
S_IWOTH 00002 Write by others.
S_IXOTH 00001 Execute (search) by others.

The mode bit S_ENFMT (same as S_ISGID) is used to enforce file-locking mode (see lockf(2), fcntl(2), and flock(2)) on files that are not group executable. This might affect future calls to open(), creat(), read(), write(), truncate(), and ftruncate() on such files (see open(2), creat(2), read(2), write(2), and truncate(2)).

The mode bit S_ISVTX (sticky bit) has no significance when set on a regular file.

If the path given to chmod() contains a symbolic link as the last element, this link is traversed and path name resolution continues. chmod() changes the access mode of the symbolic link's target, rather than the access mode of the link.

Access Control Lists - HFS File Systems Only

All optional entries in a file's access control list are deleted when chmod() is executed. (This behavior conforms to the IEEE Standard POSIX 1003.1-1988.) To preserve optional entries in a file's access control list, it is necessary to save and restore them using getacl() and setacl() (see getacl(2) and setacl(2)).

To set the permission bits of access control list entries, use setacl() instead of chmod().

Access Control Lists - JFS File Systems Only

The effective permissions granted by optional entries in a file's access control list may be changed when chmod() is executed. In particular, using chmod() to remove read, write and execute permissions from a file's owner, owning group, and all others works as expected, because chmod() affects the class entry in the ACL, limiting any access that can be granted to additional users or groups via optional ACL entries. The effect can be verified by doing a getacl on the file after the chmod(), and noting that all optional (non-default) ACL entries with nonzero permissions also have the comment # effective:---.

To set the permission bits of access control list entries, use setacl() instead of chmod().

For more information on access control list entries, see acl(5) and aclv(5).

Security Restrictions

To change the mode of a file, the effective user ID of the process must match that of the owner of the file or the process must have the OWNER privilege.

If the process does not have the OBJSUID privilege, mode bit S_ISVTX is cleared.

If the process does not have OBJSUID privilege, and the effective group ID of the process does not match the group ID of the file, and none of the group IDs in the supplementary groups list match the group ID of the file, mode bit S_ISGID is cleared.

If the mode bit S_ISVTX (sticky bit) is set on a directory, files inside the directory can be renamed or removed only by the owner of the file, the owner of the directory, or a process with the OWNER privilege (even if the modes of the directory would otherwise allow such an operation).

See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUE

chmod() returns the following values:

0: Successful completion.
-1: Failure. errno is set to indicate the error.

ERRORS

If chmod() fails, the file mode is unchanged. errno is set to one of the following values:

EACCES: Search permission is denied on a component of the path prefix.
EFAULT: path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent.
EINVAL: path or fildes descriptor does not refer to an appropriate file.
ELOOP: Too many symbolic links were encountered in translating path.
ENAMETOOLONG: A component of path exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect or path exceeds PATH_MAX bytes.
ENOENT: A component of path or the file named by path does not exist.
ENOTDIR: A component of the path prefix is not a directory.
EPERM: The effective user ID does not match that of the owner of the file or the process does not have OWNER privilege.
EROFS: The named file resides on a read-only file system.

If fchmod() fails, the file mode is unchanged. errno is set to one of the following values:

EBADF: fildes is not a valid file descriptor.
EINVAL: path or fildes descriptor does not refer to an appropriate file.
EPERM: The effective user ID does not match that of the owner of the file, and the effective user ID is not that of a user with appropriate privileges.
EPROFS: The named file resides on a read-only file system.

AUTHOR

chmod() was developed by AT&T, the University of California, Berkeley, and HP.

fchmod() was developed by the University of California, Berkeley.

STANDARDS CONFORMANCE

chmod(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

fchmod(): AES, SVID3