NAME

chmod - change mode of a file

 SYNOPSIS

#include <sys/types.h>
#include <sys/stat.h>

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

 DESCRIPTION

The chmod() function changes S_ISUID, S_ISGID, S_ISVTX 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 effective user ID of the process must match the owner of the file or the process must have appropriate privileges in order to do this.

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

If a directory is writable and the mode bit S_ISVTX is set on the directory, a process may remove or rename files within that directory only if one or more of the following is true:

• The effective user ID of the process is the same as that of the owner ID of the file.

• The effective user ID of the process is the same as that of the owner ID of the directory.

• The process has appropriate privileges.

If the S_ISVTX bit is set on a non-directory file, the behaviour is unspecified.

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 will be cleared upon successful return from chmod().

Additional implementation-dependent 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-dependent.

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

 RETURN VALUE

Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error. If -1 is returned, no change to the file mode will occur.

 ERRORS

The chmod() function will fail if:

[EACCES]

Search permission is denied on a component of the path prefix.

[ELOOP]

Too many symbolic links were encountered in resolving path.

[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.

[ENAMETOOLONG]

Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.

 EXAMPLES

None.

 APPLICATION USAGE

In order to ensure that the S_ISUID and S_ISGID bits are set, an application requiring this should use stat() after a successful chmod() to verify this.

Any file descriptors currently open by any process on the file may become invalid if the mode of the file is changed to a value which would deny access to that process. One situation where this could occur is on a stateless file system.

 FUTURE DIRECTIONS

None.

 SEE ALSO

chown(), mkdir(), mkfifo(), open(), stat(), statvfs(), <sys/stat.h>, <sys/types.h>.

DERIVATION

Derived from Issue 1 of the SVID.