Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 372 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/chmod.3p b/upstream/archlinux/man3p/chmod.3p
new file mode 100644
index 00000000..13ea518e
--- /dev/null
+++ b/upstream/archlinux/man3p/chmod.3p
@@ -0,0 +1,372 @@
+'\" et
+.TH CHMOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+chmod, fchmodat
+\(em change mode of a file
+.SH SYNOPSIS
+.LP
+.nf
+#include <sys/stat.h>
+.P
+int chmod(const char *\fIpath\fP, mode_t \fImode\fP);
+.P
+#include <fcntl.h>
+.P
+int fchmodat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP, int \fIflag\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIchmod\fR()
+function shall change S_ISUID, S_ISGID,
+S_ISVTX,
+and the file permission bits of the file named by the pathname pointed
+to by the
+.IR path
+argument to the corresponding bits in the
+.IR mode
+argument. The application shall ensure that the effective user ID
+of the process matches the owner of the file or the process has
+appropriate privileges in order to do this.
+.P
+S_ISUID, S_ISGID,
+S_ISVTX,
+and the file permission bits
+are described in
+.IR <sys/stat.h> .
+.P
+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 shall be cleared
+upon successful return from
+\fIchmod\fR().
+.P
+Additional implementation-defined restrictions may cause the S_ISUID
+and S_ISGID bits in
+.IR mode
+to be ignored.
+.P
+Upon successful completion,
+\fIchmod\fR()
+shall mark for update the last file status change timestamp of the file.
+.P
+The
+\fIfchmodat\fR()
+function shall be equivalent to the
+\fIchmod\fR()
+function except in the case where
+.IR path
+specifies a relative path. In this case the file to be changed is
+determined relative to the directory associated with the file
+descriptor
+.IR fd
+instead of the current working directory. If the access mode of the
+open file description associated with the file descriptor is not
+O_SEARCH, the function shall check whether directory searches
+are permitted using the current permissions of the directory
+underlying the file descriptor. If the access mode is
+O_SEARCH, the function shall not perform the check.
+.P
+Values for
+.IR flag
+are constructed by a bitwise-inclusive OR of flags from the following
+list, defined in
+.IR <fcntl.h> :
+.IP AT_SYMLINK_NOFOLLOW 6
+.br
+If
+.IR path
+names a symbolic link, then the mode of the symbolic link is changed.
+.P
+If
+\fIfchmodat\fR()
+is passed the special value AT_FDCWD in the
+.IR fd
+parameter, the current working directory shall be used. If also
+.IR flag
+is zero, the behavior shall be identical to a call to
+\fIchmod\fR().
+.SH "RETURN VALUE"
+Upon successful completion, these functions shall return 0.
+Otherwise, these functions shall return \-1 and set
+.IR errno
+to indicate the error. If \-1 is returned, no change to the
+file mode occurs.
+.SH ERRORS
+These functions shall fail if:
+.TP
+.BR EACCES
+Search permission is denied on a component of the path prefix.
+.TP
+.BR ELOOP
+A loop exists in symbolic links encountered during resolution of the
+.IR path
+argument.
+.TP
+.BR ENAMETOOLONG
+.br
+The length of a component of a pathname is longer than
+{NAME_MAX}.
+.TP
+.BR ENOENT
+A component of
+.IR path
+does not name an existing file or
+.IR path
+is an empty string.
+.TP
+.BR ENOTDIR
+A component of the path prefix names an existing file that is neither
+a directory nor a symbolic link to a directory, or the
+.IR path
+argument contains at least one non-\c
+<slash>
+character and ends with one or more trailing
+<slash>
+characters and the last pathname component names an existing file
+that is neither a directory nor a symbolic link to a directory.
+.TP
+.BR EPERM
+The effective user ID does not match the owner of the file and the
+process does not have appropriate privileges.
+.TP
+.BR EROFS
+The named file resides on a read-only file system.
+.P
+The
+\fIfchmodat\fR()
+function shall fail if:
+.TP
+.BR EACCES
+The access mode of the open file description associated with
+.IR fd
+is not O_SEARCH and the permissions of the directory underlying
+.IR fd
+do not permit directory searches.
+.TP
+.BR EBADF
+The
+.IR path
+argument does not specify an absolute path and the
+.IR fd
+argument is neither AT_FDCWD nor a valid file descriptor open
+for reading or searching.
+.TP
+.BR ENOTDIR
+The
+.IR path
+argument is not an absolute path and
+.IR fd
+is a file descriptor associated with a non-directory file.
+.P
+These functions may fail if:
+.TP
+.BR EINTR
+A signal was caught during execution of the function.
+.TP
+.BR EINVAL
+The value of the
+.IR mode
+argument is invalid.
+.TP
+.BR ELOOP
+More than
+{SYMLOOP_MAX}
+symbolic links were encountered during resolution of the
+.IR path
+argument.
+.TP
+.BR ENAMETOOLONG
+.br
+The length of a pathname exceeds
+{PATH_MAX},
+or pathname resolution of a symbolic link produced an intermediate
+result with a length that exceeds
+{PATH_MAX}.
+.P
+The
+\fIfchmodat\fR()
+function may fail if:
+.TP
+.BR EINVAL
+The value of the
+.IR flag
+argument is invalid.
+.TP
+.BR EOPNOTSUPP
+The AT_SYMLINK_NOFOLLOW bit is set in the
+.IR flag
+argument,
+.IR path
+names a symbolic link, and the system does not support changing the
+mode of a symbolic link.
+.br
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+.SS "Setting Read Permissions for User, Group, and Others"
+.P
+The following example sets read permissions for the owner, group, and
+others.
+.sp
+.RS 4
+.nf
+
+#include <sys/stat.h>
+.P
+const char *path;
+\&...
+chmod(path, S_IRUSR|S_IRGRP|S_IROTH);
+.fi
+.P
+.RE
+.SS "Setting Read, Write, and Execute Permissions for the Owner Only"
+.P
+The following example sets read, write, and execute permissions for the
+owner, and no permissions for group and others.
+.sp
+.RS 4
+.nf
+
+#include <sys/stat.h>
+.P
+const char *path;
+\&...
+chmod(path, S_IRWXU);
+.fi
+.P
+.RE
+.SS "Setting Different Permissions for Owner, Group, and Other"
+.P
+The following example sets owner permissions for CHANGEFILE to read,
+write, and execute, group permissions to read and execute, and other
+permissions to read.
+.sp
+.RS 4
+.nf
+
+#include <sys/stat.h>
+.P
+#define CHANGEFILE "/etc/myfile"
+\&...
+chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH);
+.fi
+.P
+.RE
+.SS "Setting and Checking File Permissions"
+.P
+The following example sets the file permission bits for a file named
+.BR /home/cnd/mod1 ,
+then calls the
+\fIstat\fR()
+function to verify the permissions.
+.sp
+.RS 4
+.nf
+
+#include <sys/types.h>
+#include <sys/stat.h>
+.P
+int status;
+struct stat buffer
+\&...
+chmod("/home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH);
+status = stat("/home/cnd/mod1", &buffer);
+.fi
+.P
+.RE
+.SH "APPLICATION USAGE"
+In order to ensure that the S_ISUID and S_ISGID
+bits are set, an application requiring this should use
+\fIstat\fR()
+after a successful
+\fIchmod\fR()
+to verify this.
+.P
+Any file descriptors currently open by any process on the file could
+possibly 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. This behavior will not occur in a
+conforming environment.
+.SH RATIONALE
+This volume of POSIX.1\(hy2017 specifies that the S_ISGID bit is cleared by
+\fIchmod\fR()
+on a regular file under certain conditions. This is specified on the
+assumption that regular files may be executed, and the system should
+prevent users from making executable
+\fIsetgid\fR()
+files perform with privileges that the caller does not have. On
+implementations that support execution of other file types, the S_ISGID
+bit should be cleared for those file types under the same
+circumstances.
+.P
+Implementations that use the S_ISUID bit to indicate some other
+function (for example, mandatory record locking) on non-executable
+files need not clear this bit on writing. They should clear the bit
+for executable files and any other cases where the bit grants special
+powers to processes that change the file contents. Similar comments
+apply to the S_ISGID bit.
+.P
+The purpose of the
+\fIfchmodat\fR()
+function is to enable changing the mode of files in directories other
+than the current working directory without exposure to race conditions.
+Any part of the path of a file could be changed in parallel to a call
+to
+\fIchmod\fR(),
+resulting in unspecified behavior. By opening a file descriptor for
+the target directory and using the
+\fIfchmodat\fR()
+function it can be guaranteed that the changed file is located relative
+to the desired directory. Some implementations might allow changing
+the mode of symbolic links. This is not supported by the interfaces in
+the POSIX specification. Systems with such support provide an
+interface named
+.IR lchmod (\|).
+To support such implementations
+\fIfchmodat\fR()
+has a
+.IR flag
+parameter.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIaccess\fR\^(\|)",
+.IR "\fIchown\fR\^(\|)",
+.IR "\fIexec\fR\^",
+.IR "\fIfstatat\fR\^(\|)",
+.IR "\fIfstatvfs\fR\^(\|)",
+.IR "\fImkdir\fR\^(\|)",
+.IR "\fImkfifo\fR\^(\|)",
+.IR "\fImknod\fR\^(\|)",
+.IR "\fIopen\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<fcntl.h>\fP",
+.IR "\fB<sys_stat.h>\fP",
+.IR "\fB<sys_types.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .