diff options
Diffstat (limited to 'man2/chmod.2')
| -rw-r--r-- | man2/chmod.2 | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/man2/chmod.2 b/man2/chmod.2 new file mode 100644 index 0000000..b1c130e --- /dev/null +++ b/man2/chmod.2 @@ -0,0 +1,347 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt <michael@moria.de> +.\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1997-01-12 by Michael Haardt +.\" <michael@cantor.informatik.rwth-aachen.de>: NFS details +.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.TH chmod 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +chmod, fchmod, fchmodat \- change permissions of a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/stat.h> +.PP +.BI "int chmod(const char *" pathname ", mode_t " mode ); +.BI "int fchmod(int " fd ", mode_t " mode ); +.PP +.BR "#include <fcntl.h>" " /* Definition of AT_* constants */" +.B #include <sys/stat.h> +.PP +.BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \ +mode ", int " flags ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.nf +.BR fchmod (): + Since glibc 2.24: + _POSIX_C_SOURCE >= 199309L +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + glibc 2.19 to glibc 2.23 + _POSIX_C_SOURCE + glibc 2.16 to glibc 2.19: + _BSD_SOURCE || _POSIX_C_SOURCE + glibc 2.12 to glibc 2.16: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 + || _POSIX_C_SOURCE >= 200809L + glibc 2.11 and earlier: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.fi +.PP +.BR fchmodat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +The +.BR chmod () +and +.BR fchmod () +system calls change a file's mode bits. +(The file mode consists of the file permission bits plus the set-user-ID, +set-group-ID, and sticky bits.) +These system calls differ only in how the file is specified: +.IP \[bu] 3 +.BR chmod () +changes the mode of the file specified whose pathname is given in +.IR pathname , +which is dereferenced if it is a symbolic link. +.IP \[bu] +.BR fchmod () +changes the mode of the file referred to by the open file descriptor +.IR fd . +.PP +The new file mode is specified in +.IR mode , +which is a bit mask created by ORing together zero or +more of the following: +.TP 18 +.BR S_ISUID " (04000)" +set-user-ID (set process effective user ID on +.BR execve (2)) +.TP +.BR S_ISGID " (02000)" +set-group-ID (set process effective group ID on +.BR execve (2); +mandatory locking, as described in +.BR fcntl (2); +take a new file's group from parent directory, as described in +.BR chown (2) +and +.BR mkdir (2)) +.TP +.BR S_ISVTX " (01000)" +sticky bit (restricted deletion flag, as described in +.BR unlink (2)) +.TP +.BR S_IRUSR " (00400)" +read by owner +.TP +.BR S_IWUSR " (00200)" +write by owner +.TP +.BR S_IXUSR " (00100)" +execute/search by owner ("search" applies for directories, +and means that entries within the directory can be accessed) +.TP +.BR S_IRGRP " (00040)" +read by group +.TP +.BR S_IWGRP " (00020)" +write by group +.TP +.BR S_IXGRP " (00010)" +execute/search by group +.TP +.BR S_IROTH " (00004)" +read by others +.TP +.BR S_IWOTH " (00002)" +write by others +.TP +.BR S_IXOTH " (00001)" +execute/search by others +.PP +The effective UID of the calling process must match the owner of the file, +or the process must be privileged (Linux: it must have the +.B CAP_FOWNER +capability). +.PP +If the calling process is not privileged (Linux: does not have the +.B CAP_FSETID +capability), and the group of the file does not match +the effective group ID of the process or one of its +supplementary group IDs, the +.B S_ISGID +bit will be turned off, +but this will not cause an error to be returned. +.PP +As a security measure, depending on the filesystem, +the set-user-ID and set-group-ID execution bits +may be turned off if a file is written. +(On Linux, this occurs if the writing process does not have the +.B CAP_FSETID +capability.) +On some filesystems, only the superuser can set the sticky bit, +which may have a special meaning. +For the sticky bit, and for set-user-ID and set-group-ID bits on +directories, see +.BR inode (7). +.PP +On NFS filesystems, restricting the permissions will immediately influence +already open files, because the access control is done on the server, but +open files are maintained by the client. +Widening the permissions may be +delayed for other clients if attribute caching is enabled on them. +.\" +.\" +.SS fchmodat() +The +.BR fchmodat () +system call operates in exactly the same way as +.BR chmod (), +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR chmod () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR chmod ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +.I flags +can either be 0, or include the following flag: +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead operate on the link itself. +This flag is not currently implemented. +.PP +See +.BR openat (2) +for an explanation of the need for +.BR fchmodat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Depending on the filesystem, +errors other than those listed below can be returned. +.PP +The more general errors for +.BR chmod () +are listed below: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( fchmod ()) +The file descriptor +.I fd +is not valid. +.TP +.B EBADF +.RB ( fchmodat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EINVAL +.RB ( fchmodat ()) +Invalid flag specified in +.IR flags . +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B ENOTDIR +.RB ( fchmodat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B ENOTSUP +.RB ( fchmodat ()) +.I flags +specified +.BR AT_SYMLINK_NOFOLLOW , +which is not supported. +.TP +.B EPERM +The effective UID does not match the owner of the file, +and the process is not privileged (Linux: it does not have the +.B CAP_FOWNER +capability). +.TP +.B EPERM +The file is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.TP +.B EROFS +The named file resides on a read-only filesystem. +.SH VERSIONS +.SS C library/kernel differences +The GNU C library +.BR fchmodat () +wrapper function implements the POSIX-specified +interface described in this page. +This interface differs from the underlying Linux system call, which does +.I not +have a +.I flags +argument. +.SS glibc notes +On older kernels where +.BR fchmodat () +is unavailable, the glibc wrapper function falls back to the use of +.BR chmod (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I dirfd +argument. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR chmod () +.TQ +.BR fchmod () +4.4BSD, SVr4, POSIX.1-2001. +.TP +.BR fchmodat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.SH SEE ALSO +.BR chmod (1), +.BR chown (2), +.BR execve (2), +.BR open (2), +.BR stat (2), +.BR inode (7), +.BR path_resolution (7), +.BR symlink (7) |