Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 414 insertions, 0 deletions

diff --git a/upstream/archlinux/man0p/sys_stat.h.0p b/upstream/archlinux/man0p/sys_stat.h.0p
new file mode 100644
index 00000000..83b2f159
--- /dev/null
+++ b/upstream/archlinux/man0p/sys_stat.h.0p
@@ -0,0 +1,414 @@
+'\" et
+.TH sys_stat.h "0P" 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
+sys/stat.h
+\(em data returned by the stat(\|) function
+.SH SYNOPSIS
+.LP
+.nf
+#include <sys/stat.h>
+.fi
+.SH DESCRIPTION
+The
+.IR <sys/stat.h> 
+header shall define the structure of the data returned by the
+\fIfstat\fR(),
+\fIlstat\fR(),
+and
+\fIstat\fR()
+functions.
+.P
+The
+.IR <sys/stat.h> 
+header shall define the
+.BR stat
+structure, which shall include at least the following members:
+.sp
+.RS 4
+.nf
+
+dev_t st_dev            \fRDevice ID of device containing file.\fR
+ino_t st_ino            \fRFile serial number.\fR
+mode_t st_mode          \fRMode of file (see below).\fR
+nlink_t st_nlink        \fRNumber of hard links to the file.\fR
+uid_t st_uid            \fRUser ID of file.\fR
+gid_t st_gid            \fRGroup ID of file.\fR
+dev_t st_rdev           \fRDevice ID (if file is character or block special).\fR
+off_t st_size           \fRFor regular files, the file size in bytes.\fR
+                        \fRFor symbolic links, the length in bytes of the\fR
+                        \fRpathname contained in the symbolic link.\fR
+                        \fRFor a shared memory object, the length in bytes.\fR
+                        \fRFor a typed memory object, the length in bytes.\fR
+                        \fRFor other file types, the use of this field is\fR
+                        \fRunspecified.\fR
+struct timespec st_atim \fRLast data access timestamp.\fR
+struct timespec st_mtim \fRLast data modification timestamp.\fR
+struct timespec st_ctim \fRLast file status change timestamp.\fR
+blksize_t st_blksize    \fRA file system-specific preferred I/O block size\fR
+                        \fRfor this object. In some file system types, this\fR
+                        \fRmay vary from file to file.\fR
+blkcnt_t st_blocks      \fRNumber of blocks allocated for this object.\fR
+.fi
+.P
+.RE
+.P
+The
+.IR st_ino
+and
+.IR st_dev
+fields taken together uniquely identify the file within the system.
+.P
+The
+.IR <sys/stat.h> 
+header shall define the
+.BR blkcnt_t ,
+.BR blksize_t ,
+.BR dev_t ,
+.BR ino_t ,
+.BR mode_t ,
+.BR nlink_t ,
+.BR uid_t ,
+.BR gid_t ,
+.BR off_t ,
+and
+.BR time_t
+types as described in
+.IR <sys/types.h> .
+.P
+The
+.IR <sys/stat.h> 
+header shall define the
+.BR timespec
+structure as described in
+.IR <time.h> .
+Times shall be given in seconds since the Epoch.
+.P
+Which structure members have meaningful values depends on the
+type of file. For further information, see the descriptions of
+\fIfstat\fR(),
+\fIlstat\fR(),
+and
+\fIstat\fR()
+in the System Interfaces volume of POSIX.1\(hy2017.
+.P
+For compatibility with earlier versions of this standard, the
+.IR st_atime
+macro shall be defined with the value
+.IR st_atim.tv_sec .
+Similarly,
+.IR st_ctime
+and
+.IR st_mtime
+shall be defined as macros with the values
+.IR st_ctim.tv_sec
+and
+.IR st_mtim.tv_sec ,
+respectively.
+.br
+.P
+The
+.IR <sys/stat.h> 
+header shall define the following symbolic constants for the
+file types encoded in type
+.BR mode_t .
+The values shall be suitable for use in
+.BR #if
+preprocessing directives:
+.IP S_IFMT 12
+Type of file.
+.RS 12 
+.IP S_IFBLK 12
+Block special.
+.IP S_IFCHR 12
+Character special.
+.IP S_IFIFO 12
+FIFO special.
+.IP S_IFREG 12
+Regular.
+.IP S_IFDIR 12
+Directory.
+.IP S_IFLNK 12
+Symbolic link.
+.IP S_IFSOCK 12
+Socket.
+.RE
+.P
+The
+.IR <sys/stat.h> 
+header shall define the following symbolic constants for the file mode
+bits encoded in type
+.BR mode_t ,
+with the indicated numeric values. These macros shall expand to an
+expression which has a type that allows them to be used, either singly
+or OR'ed together, as the third argument to
+\fIopen\fR()
+without the need for a
+.BR mode_t
+cast. The values shall be suitable for use in
+.BR #if
+preprocessing directives.
+.TS
+center box tab(@);
+cB | cB | cB
+l | n | l.
+Name@Numeric Value@Description
+_
+S_IRWXU@0700@Read, write, execute/search by owner.
+S_IRUSR@0400@Read permission, owner.
+S_IWUSR@0200@Write permission, owner.
+S_IXUSR@0100@Execute/search permission, owner.
+_
+S_IRWXG@070@Read, write, execute/search by group.
+S_IRGRP@040@Read permission, group.
+S_IWGRP@020@Write permission, group.
+S_IXGRP@010@Execute/search permission, group.
+_
+S_IRWXO@07@Read, write, execute/search by others.
+S_IROTH@04@Read permission, others.
+S_IWOTH@02@Write permission, others.
+S_IXOTH@01@Execute/search permission, others.
+_
+S_ISUID@04000@Set-user-ID on execution.
+S_ISGID@02000@Set-group-ID on execution.
+\*!S_ISVTX@01000@On directories, restricted deletion flag.\0\0\0\*?
+.TE
+.P
+The following macros shall be provided to test whether a file is of the
+specified type. The value
+.IR m
+supplied to the macros is the value of
+.IR st_mode
+from a
+.BR stat
+structure. The macro shall evaluate to a non-zero value if the test is
+true; 0 if the test is false.
+.IP "S_ISBLK(\fIm\fP)" 14
+Test for a block special file.
+.IP "S_ISCHR(\fIm\fP)" 14
+Test for a character special file.
+.IP "S_ISDIR(\fIm\fP)" 14
+Test for a directory.
+.IP "S_ISFIFO(\fIm\fP)" 14
+Test for a pipe or FIFO special file.
+.IP "S_ISREG(\fIm\fP)" 14
+Test for a regular file.
+.IP "S_ISLNK(\fIm\fP)" 14
+Test for a symbolic link.
+.IP "S_ISSOCK(\fIm\fP)" 14
+Test for a socket.
+.P
+The implementation may implement message queues, semaphores, or shared
+memory objects as distinct file types. The following macros shall be
+provided to test whether a file is of the specified type. The value of
+the
+.IR buf
+argument supplied to the macros is a pointer to a
+.BR stat
+structure. The macro shall evaluate to a non-zero value if the
+specified object is implemented as a distinct file type and the
+specified file type is contained in the
+.BR stat
+structure referenced by
+.IR buf .
+Otherwise, the macro shall evaluate to zero.
+.IP "S_TYPEISMQ(\fIbuf\fP)" 14
+Test for a message queue.
+.IP "S_TYPEISSEM(\fIbuf\fP)" 14
+Test for a semaphore.
+.IP "S_TYPEISSHM(\fIbuf\fP)" 14
+Test for a shared memory object.
+.P
+The implementation may implement typed memory objects as distinct
+file types, and the following macro shall test whether a file is of the
+specified type. The value of the
+.IR buf
+argument supplied to the macros is a pointer to a
+.BR stat
+structure. The macro shall evaluate to a non-zero value if the
+specified object is implemented as a distinct file type and the
+specified file type is contained in the
+.BR stat
+structure referenced by
+.IR buf .
+Otherwise, the macro shall evaluate to zero.
+.IP "S_TYPEISTMO(\fIbuf\fP)" 14
+Test macro for a typed memory object.
+.P
+The
+.IR <sys/stat.h> 
+header shall define the following symbolic constants as distinct
+integer values outside of the range [0,999\|999\|999],
+for use with the
+\fIfutimens\fR()
+and
+\fIutimensat\fR()
+functions:
+UTIME_NOW
+UTIME_OMIT
+.P
+The following shall be declared as functions and may also be defined
+as macros. Function prototypes shall be provided.
+.sp
+.RS 4
+.nf
+
+int    chmod(const char *, mode_t);
+int    fchmod(int, mode_t);
+int    fchmodat(int, const char *, mode_t, int);
+int    fstat(int, struct stat *);
+int    fstatat(int, const char *restrict, struct stat *restrict, int);
+int    futimens(int, const struct timespec [2]);
+int    lstat(const char *restrict, struct stat *restrict);
+int    mkdir(const char *, mode_t);
+int    mkdirat(int, const char *, mode_t);
+int    mkfifo(const char *, mode_t);
+int    mkfifoat(int, const char *, mode_t);
+int    mknod(const char *, mode_t, dev_t);
+int    mknodat(int, const char *, mode_t, dev_t);
+int    stat(const char *restrict, struct stat *restrict);
+mode_t umask(mode_t);
+int    utimensat(int, const char *, const struct timespec [2], int);
+.fi
+.P
+.RE
+.P
+Inclusion of the
+.IR <sys/stat.h> 
+header may make visible all symbols from the
+.IR <time.h> 
+header.
+.LP
+.IR "The following sections are informative."
+.SH "APPLICATION USAGE"
+Use of the macros is recommended for determining the type of a file.
+.SH RATIONALE
+A conforming C-language application must include
+.IR <sys/stat.h> 
+for functions that have arguments or return values of type
+.BR mode_t ,
+so that symbolic values for that type can be used. An alternative
+would be to require that these constants are also defined by including
+.IR <sys/types.h> .
+.P
+The S_ISUID and S_ISGID
+bits may be cleared on any write, not just on
+\fIopen\fR(),
+as some historical implementations do.
+.P
+System calls that update the time entry fields in the
+.BR stat
+structure must be documented by the implementors. POSIX-conforming
+systems should not update the time entry fields for functions listed in
+the System Interfaces volume of POSIX.1\(hy2017 unless the standard requires that they do, except in the case
+of documented extensions to the standard.
+.P
+Upon assignment, file timestamps are immediately converted to the
+resolution of the file system by truncation (i.e., the recorded time
+can be older than the actual time). For example, if the file system
+resolution is 1 microsecond, then a conforming
+\fIstat\fR()
+must always return an
+.IR st_mtim.tv_nsec
+that is a multiple of 1000. Some older implementations returned
+higher-resolution timestamps while the
+.IR inode
+information was cached, and then spontaneously truncated the
+.IR tv_nsec
+fields when they were stored to and retrieved from disk, but this behavior
+does not conform.
+.P
+Note that
+.IR st_dev
+must be unique within a Local Area Network (LAN) in a ``system'' made
+up of multiple computers' file systems connected by a LAN.
+.P
+Networked implementations of a POSIX-conforming system must guarantee
+that all files visible within the file tree (including parts of the
+tree that may be remotely mounted from other machines on the network)
+on each individual processor are uniquely identified by the combination
+of the
+.IR st_ino
+and
+.IR st_dev
+fields.
+.P
+The unit for the
+.IR st_blocks
+member of the
+.BR stat
+structure is not defined within POSIX.1\(hy2008. In some implementations
+it is 512 bytes. It may differ on a file system basis. There is no
+correlation between values of the
+.IR st_blocks
+and
+.IR st_blksize ,
+and the
+.IR f_bsize
+(from
+.IR <sys/statvfs.h> )
+structure members.
+.P
+Traditionally, some implementations defined the multiplier for
+.IR st_blocks
+in
+.IR <sys/param.h> 
+as the symbol DEV_BSIZE.
+.P
+Some earlier versions of this standard did not specify values for the
+file mode bit macros. The expectation was that some implementors might
+choose to use a different encoding for these bits than the traditional
+one, and that new applications would use symbolic file modes instead of
+numeric. This version of the standard specifies the traditional encoding,
+in recognition that nearly 20 years after the first publication of this
+standard numeric file modes are still in widespread use by application
+developers, and that all conforming implementations still use the
+traditional encoding.
+.SH "FUTURE DIRECTIONS"
+No new S_IFMT symbolic names for the file type values of
+.BR mode_t
+will be defined by POSIX.1\(hy2008; if new file types are required, they will
+only be testable through
+.IR S_ISxx (\|)
+or
+.IR S_TYPEISxxx (\|)
+macros instead.
+.SH "SEE ALSO"
+.IR "\fB<sys_statvfs.h>\fP",
+.IR "\fB<sys_types.h>\fP",
+.IR "\fB<time.h>\fP"
+.P
+The System Interfaces volume of POSIX.1\(hy2017,
+.IR "\fIchmod\fR\^(\|)",
+.IR "\fIfchmod\fR\^(\|)",
+.IR "\fIfstat\fR\^(\|)",
+.IR "\fIfstatat\fR\^(\|)",
+.IR "\fIfutimens\fR\^(\|)",
+.IR "\fImkdir\fR\^(\|)",
+.IR "\fImkfifo\fR\^(\|)",
+.IR "\fImknod\fR\^(\|)",
+.IR "\fIumask\fR\^(\|)"
+.\"
+.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 .