chmod(2)

chmod, fchmod -- change mode of file

Synopsis

   #include <sys/types.h> 
   #include <sys/stat.h> 
    
   int chmod(const char path, mode_t mode); 
   
 
   int fchmod(int fildes, mode_t mode);

Description

chmod and fchmod set the access permission portion of the mode of the file whose name is given by path or referenced by the descriptor fildes to the bit pattern contained in mode. If path or fildes are symbolic links, the access permissions of the target of the symbolic links are set. Access permission bits are interpreted as follows:

S_ISUID 04000 Set user ID on execution.

S_ISGID 020#0 Set group ID on execution if # is 7, 5, 3, or 1

Enable mandatory file/record locking if # is 6, 4, 2, or 0

S_ISVTX 01000 Save text image after execution.

S_IRWXU 00700 Read, write, execute by owner.

S_IRUSR 00400 Read by owner.

S_IWUSR 00200 Write by owner.

S_IXUSR 00100 Execute (search if a directory) by owner.

S_IRWXG 00070 Read, write, execute by group.

S_IRGRP 00040 Read by group.

S_IWGRP 00020 Write by group.

S_IXGRP 00010 Execute by group.

S_IRWXO 00007 Read, write, execute (search) by others.

S_IROTH 00004 Read by others.

S_IWOTH 00002 Write by others

S_IXOTH 00001 Execute by others.

 
 S_ISUID   04000   Set user ID on execution. 
 S_ISGID   020#0   Set group ID on execution if # is 7, 5, 3, or 1 
                   Enable mandatory file/record locking if # is 6, 4, 2, or 0 
 S_ISVTX   01000   Save text image  after execution. 
 S_IRWXU   00700   Read, write, execute by owner. 
 S_IRUSR   00400   Read by owner. 
 S_IWUSR   00200   Write by owner. 
 S_IXUSR   00100   Execute (search if a directory) by owner. 
 S_IRWXG   00070   Read, write, execute by group. 
 S_IRGRP   00040   Read by group. 
 S_IWGRP   00020   Write by group. 
 S_IXGRP   00010   Execute by group. 
 S_IRWXO   00007   Read, write, execute (search) by others. 
 S_IROTH   00004   Read by others. 
 S_IWOTH   00002   Write by others 
 S_IXOTH   00001   Execute by others.

Modes are constructed by an OR of the access permission bits.

The effective user ID of the process must match the owner of the file or the process must have the appropriate privilege to change the mode of a file.

If the process does not have appropriate privilege and the file is not a directory, mode bit 01000 (save text image on execution) is cleared.

If the effective group ID of the process does not match the group ID of the file, and the process does not have appropriate privilege mode bit 02000 (set group ID on execution) is cleared.

If a 0410 executable file has the sticky bit (mode bit 01000) set, the operating system will not delete the program text from the swap area when the last user process terminates. If a 0413 or ELF executable file has the sticky bit set, the operating system will not delete the program text from memory when the last user process terminates. In either case, if the sticky bit is set the text will already be available (either in a swap area or in memory) when the next user of the file executes it, thus making execution faster.

If a directory is writable and the sticky 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 write permission for the file.
the process has appropriate privileges

If the mode bit 02000 (set group ID on execution) is set and the mode bit 00010 (execute or search by group) is not set, mandatory file/record locking will exist on a regular file. This may affect future calls to open(2), creat(2), read(2), and write(2) on this file.

The following environment variables affect the execution of chmod

LC_MESSAGES: Determines the locale to be used for diagnostic messages. If available, these messages will be retrieved from the message data base, uxcore.abi.
LC_ALL: If a non-empty string, this overrides the values of all the other internationalization variables.
LANG: The default value for internationalization variables that are unset or null.

Return values

On success, chmod and fchmod return 0 and mark for update the st_ctime field of the file. On failure, chmod and fchmod return -1, set errno to identify the error, and the file mode is unchanged.

In the following conditions, chmod fails and sets errno to:

EACCES

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

EACCES

Write permission on the named file is denied.

EFAULT

path points outside the allocated address space of the process.

EINTR

A signal was caught during execution of the system call.

EINVAL

An attempt was made to set file/record locking on a file on an NFS mounted filesystem.

EIO

An I/O error occurred while reading from or writing to the file system.

ELOOP

Too many symbolic links were encountered in translating path.

EMULTIHOP

Components of path require hopping to multiple remote machines and file system type does not allow it.

ENAMETOOLONG

The length of the path argument exceeds {PATH_MAX}, or the length of a path component exceeds {NAME_MAX} while _POSIX_NO_TRUNC is in effect.

ENOTDIR

A component of the prefix of path is not a directory.

ENOENT

Either a component of the path prefix, or the file referred to by path does not exist or is a null pathname.

ENOLINK

fildes points to a remote machine and the link to that machine is no longer active.

EPERM

The effective user ID does not match the owner of the file and the process does not have appropriate privilege (P_OWNER).

EROFS

The file referred to by path resides on a read-only file system.

In the following conditions, fchmod fails and sets errno to:

EBADF

fildes is not an open file descriptor

EIO

An I/O error occurred while reading from or writing to the file system.

EINTR

A signal was caught during execution of the fchmod system call.

ENOLINK

path points to a remote machine and the link to that machine is no longer active.

EPERM

The effective user ID does not match the owner of the file and the process does not have appropriate privilege (P_OWNER).

EROFS

The file referred to by fildes resides on a read-only file system.

References

access(2), chmod(1) chown(2), creat(2), exec(2), fcntl(2), mkfifo(3C), mknod(2), open(2), read(2), stat(2), stat(5), write(2)

S_ISUID	04000	Set user ID on execution.
S_ISGID	020#0	Set group ID on execution if # is 7, 5, 3, or 1
		Enable mandatory file/record locking if # is 6, 4, 2, or 0
S_ISVTX	01000	Save text image after execution.
S_IRWXU	00700	Read, write, execute by owner.
S_IRUSR	00400	Read by owner.
S_IWUSR	00200	Write by owner.
S_IXUSR	00100	Execute (search if a directory) by owner.
S_IRWXG	00070	Read, write, execute by group.
S_IRGRP	00040	Read by group.
S_IWGRP	00020	Write by group.
S_IXGRP	00010	Execute by group.
S_IRWXO	00007	Read, write, execute (search) by others.
S_IROTH	00004	Read by others.
S_IWOTH	00002	Write by others
S_IXOTH	00001	Execute by others.