NAME

chmod – change mode of a file

SYNOPSIS

DESCRIPTION

The chmod() function shall change S_ISUID, S_ISGID, [XSI] [Option Start] S_ISVTX, [Option End] and the file permission bits of the file named by the pathname pointed to by the path argument to the corresponding bits in the mode argument. The application shall ensure that the effective user ID of the process matches the owner of the file or the process has appropriate privileges in order to do this.

S_ISUID, S_ISGID, S_ISVTX, and the file permission bits are described in <sys/stat.h>.

If the calling process does not have appropriate privileges, and if the group ID of the file does not match the effective group ID or one of the supplementary group IDs and if the file is a regular file, bit S_ISGID (set-group-ID on execution) in the file’s mode shall be cleared upon successful return from chmod().

Additional implementation-defined restrictions may cause the S_ISUID and S_ISGID bits in mode to be ignored.

The effect on file descriptors for files open at the time of a call to chmod() is implementation-defined.

Upon successful completion, chmod() shall mark for update the st_ctime field of the file.

RETURN VALUE

Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to indicate the error. If -1 is returned, no change to the file mode occurs.

ERRORS

The chmod() function shall fail if:
[EACCES]
Search permission is denied on a component of the path prefix.
[ELOOP]
A loop exists in symbolic links encountered during resolution of the path argument.
[ENAMETOOLONG]
The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.
[ENOTDIR]
A component of the path prefix is not a directory.
[ENOENT]
A component of path does not name an existing file or path is an empty string.
[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.

The chmod() function may fail if:
[EINTR]
A signal was caught during execution of the function.
[EINVAL]
The value of the mode argument is invalid.
[ELOOP]
More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the path argument.
[ENAMETOOLONG]
As a result of encountering a symbolic link in resolution of the path argument, the length of the substituted pathname strings exceeded {PATH_MAX}.