Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 347 insertions, 0 deletions

diff --git a/man/man2/chmod.2 b/man/man2/chmod.2
new file mode 100644
index 0000000..9ebbf23
--- /dev/null
+++ b/man/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 2024-05-02 "Linux man-pages (unreleased)"
+.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>
+.P
+.BI "int chmod(const char *" pathname ", mode_t " mode );
+.BI "int fchmod(int " fd ", mode_t " mode );
+.P
+.BR "#include <fcntl.h>" "           /* Definition of AT_* constants */"
+.B #include <sys/stat.h>
+.P
+.BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \
+mode ", int " flags );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.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
+.P
+.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 .
+.P
+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
+.P
+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).
+.P
+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.
+.P
+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).
+.P
+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.
+.P
+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).
+.P
+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 ()).
+.P
+If
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+.P
+.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.
+.P
+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.
+.P
+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)