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 (sticky bit).
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 (sticky bit).
 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 P_OWNER privilege, to change the mode of the file.

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

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

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:

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.

Additional access permissions beyond those indicated by the mode bits may be placed on the file. [See acl(2).]

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 the P_OWNER privilege.

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 the P_OWNER privilege.

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

References

access(2), acl(2), chmod(1) chown(2), creat(2), exec(2), fcntl(2), getacl(1), mkfifo(3C), mknod(2), open(2), read(2), setacl(1), stat(2), stat(5), write(2)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004