chmod, fchmod, or fchmodat Subroutine
Purpose
Changes file system object base file mode bits.
Library
Standard C Library (libc.a)
Syntax
#include <sys/stat.h>
int chmod (Path, Mode)
const char *Path;
mode_t Mode;
int fchmod (FileDescriptor, Mode)
int FileDescriptor;
mode_t Mode;
int fchmodat (DirFileDescriptor, Path, Mode, Flag)
int DirFileDescriptor;
const char *Path;
mode_t Mode;
int Flag;
Description
The chmod subroutine sets the access permissions of the file specified by the Path parameter. If Network File System (NFS) is installed on your system, this path can cross into another node.
Use the fchmod subroutine to set the access permissions of an open file pointed to by the FileDescriptor parameter.
If FileDescriptor references a shared memory object, the fchmod subroutine affects the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits.
The access control information is set according to the Mode parameter. Note that these routines will replace any existing ACL associated with the file system object.
The fchmodat subroutine is equivalent to the chmod subroutine if the Path parameter specifies an absolute path or if the DirFileDescriptor parameter is set to AT_FDCWD. The file to be changed is determined by the relative path to the directory that is associated with the DirFileDescriptor parameter instead of the current working directory. If the directory is opened without the O_SEARCH open flag, the subroutine checks to determine whether directory searches are permitted by using the current permissions of the directory. If the directory is opened with the O_SEARCH open flag, the subroutine does not perform the check.
Parameters
Item | Description |
---|---|
FileDescriptor | Specifies the file descriptor of an open file or shared memory object. |
Mode | Specifies the bit pattern that determines the access permissions. The Mode parameter
is constructed by logically ORing one or more of the following values, which are defined in the
sys/mode.h file:
The following attributes apply only to files that are directly executable. They have no meaning when applied to executable text files such as shell scripts and awk scripts.
Other mode values exist that can be set with the mknod subroutine but not with the chmod subroutine. |
Path | Specifies the path name of the file. For fchmodat, if the DirFileDescriptor is specified and Path is relative, then the DirFileDescriptor specifies the effective current working directory for the Path. |
DirFileDescriptor | Specifies the file descriptor of an open directory, which is used as the effective current working directory for the Path parameter. If DirFileDescriptor equals AT_FDCWD, the DirFileDescriptor parameter is ignored and the Path argument specifies the complete file. |
Flag | Specifies a bit field argument. If the Flag parameter contains the AT_SYMLINK_NOFOLLOW bit and the Path parameter specifies a symbolic link, the mode of the symbolic link is changed. |
Return Values
Upon successful completion, the chmod, fchmod, and fchmodat subroutines return a value of 0. If the chmod, fchmod, or fchmodat subroutine is unsuccessful, a value of -1 is returned, and the errno global variable is set to identify the error.
Error Codes
The chmod or fchmodat subroutine is unsuccessful and the file permissions remain unchanged if one of the following is true:
Item | Description |
---|---|
ENOTDIR | A component of the Path prefix is not a directory. |
EACCES | Search permission is denied on a component of the Path prefix. |
EFAULT | The Path parameter points to a location outside of the allocated address space of the process. |
ELOOP | Too many symbolic links were encountered in translating the Path parameter. |
ENOENT | The named file does not exist. |
ENAMETOOLONG | A component of the Path parameter exceeded 255 characters, or the entire Path parameter exceeded 1023 characters. |
Item | Description |
---|---|
EBADF | The value of the FileDescriptor parameter is not valid. |
Item | Description |
---|---|
EPERM | The effective user ID does not match the owner of the file, and the process does not have appropriate privileges. |
EROFS | The named file resides on a read-only file system. |
EIO | An I/O error occurred during the operation. |
If NFS is installed on your system, the chmod and fchmod subroutines can also be unsuccessful if the following is true:
Item | Description |
---|---|
ESTALE | The root or current directory of the process is located in a virtual file system that has been unmounted. |
ETIMEDOUT | The connection timed out. |
The fchmodat subroutine is unsuccessful and the file permissions remain unchanged if one of the following is true:
Item | Description |
---|---|
EBADF | The Path parameter does not specify an absolute path and the DirFileDescriptor argument is neither AT_FDCWD nor a valid file descriptor. |
EINVAL | The value of the Flag argument is not valid. |
ENOTDIR | The Path parameter is not an absolute path and DirFileDescriptor is a file descriptor but is not associated with a directory. |
Security
Access Control: The invoker must have search permission for all components of the Path prefix.
If you receive the EBUSY error, toggle the enforced locking attribute in the Mode parameter and retry your operation. The enforced locking attribute should never be used on a file that is part of the Trusted Computing Base.