Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 377 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/readdir.3p b/upstream/archlinux/man3p/readdir.3p
new file mode 100644
index 00000000..98f5f3d7
--- /dev/null
+++ b/upstream/archlinux/man3p/readdir.3p
@@ -0,0 +1,377 @@
+'\" et
+.TH READDIR "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
+readdir,
+readdir_r
+\(em read a directory
+.SH SYNOPSIS
+.LP
+.nf
+#include <dirent.h>
+.P
+struct dirent *readdir(DIR *\fIdirp\fP);
+int readdir_r(DIR *restrict \fIdirp\fP, struct dirent *restrict \fIentry\fP,
+    struct dirent **restrict \fIresult\fP);
+.fi
+.SH DESCRIPTION
+The type
+.BR DIR ,
+which is defined in the
+.IR <dirent.h> 
+header, represents a
+.IR "directory stream" ,
+which is an ordered sequence of all the directory entries in a
+particular directory. Directory entries represent files; files may be
+removed from a directory or added to a directory asynchronously to the
+operation of
+\fIreaddir\fR().
+.P
+The
+\fIreaddir\fR()
+function shall return a pointer to a structure representing the
+directory entry at the current position in the directory stream
+specified by the argument
+.IR dirp ,
+and position the directory stream at the next entry. It shall return a
+null pointer upon reaching the end of the directory stream. The
+structure
+.BR dirent
+defined in the
+.IR <dirent.h> 
+header describes a directory entry. The value of the structure's
+.IR d_ino
+member shall be set to the file serial number of the file named by the
+.IR d_name
+member. If the
+.IR d_name
+member names a symbolic link, the value of the
+.IR d_ino
+member shall be set to the file serial number of the symbolic link itself.
+.P
+The
+\fIreaddir\fR()
+function shall not return directory entries containing empty names. If
+entries for dot or dot-dot exist, one entry shall be returned for dot
+and one entry shall be returned for dot-dot; otherwise, they shall not
+be returned.
+.P
+The application shall not modify the structure to which the return
+value of
+\fIreaddir\fR()
+points, nor any storage areas pointed to by pointers within the
+structure. The returned pointer, and pointers within the structure,
+might be invalidated or the structure or the storage areas might be
+overwritten by a subsequent call to
+\fIreaddir\fR()
+on the same directory stream. They shall not be affected by a call to
+\fIreaddir\fR()
+on a different directory stream. The returned pointer, and pointers
+within the structure, might also be invalidated if the calling thread
+is terminated.
+.P
+If a file is removed from or added to the directory after the most
+recent call to
+\fIopendir\fR()
+or
+\fIrewinddir\fR(),
+whether a subsequent call to
+\fIreaddir\fR()
+returns an entry for that file is unspecified.
+.P
+The
+\fIreaddir\fR()
+function may buffer several directory entries per actual read
+operation;
+\fIreaddir\fR()
+shall mark for update the last data access timestamp
+of the directory each time the directory is actually read.
+.P
+After a call to
+\fIfork\fR(),
+either the parent or child (but not both) may continue processing the
+directory stream using
+\fIreaddir\fR(),
+\fIrewinddir\fR(),
+or
+\fIseekdir\fR().
+If both the parent and child processes use these functions, the result
+is undefined.
+.P
+The
+\fIreaddir\fR()
+function need not be thread-safe.
+.P
+Applications wishing to check for error situations should set
+.IR errno
+to 0 before calling
+\fIreaddir\fR().
+If
+.IR errno
+is set to non-zero on return, an error occurred.
+.P
+The
+\fIreaddir_r\fR()
+function shall initialize the
+.BR dirent
+structure referenced by
+.IR entry
+to represent the directory entry at the current position in the
+directory stream referred to by
+.IR dirp ,
+store a pointer to this structure at the location referenced by
+.IR result ,
+and position the directory stream at the next entry.
+.P
+The storage pointed to by
+.IR entry
+shall be large enough for a
+.BR dirent
+with an array of
+.BR char
+.IR d_name
+members containing at least
+{NAME_MAX}+1
+elements.
+.P
+Upon successful return, the pointer returned at *\fIresult\fP shall have
+the same value as the argument
+.IR entry .
+Upon reaching the end of the directory stream, this pointer shall
+have the value NULL.
+.P
+The
+\fIreaddir_r\fR()
+function shall not return directory entries containing empty names.
+.P
+If a file is removed from or added to the directory after the most
+recent call to
+\fIopendir\fR()
+or
+\fIrewinddir\fR(),
+whether a subsequent call to
+\fIreaddir_r\fR()
+returns an entry for that file is unspecified.
+.P
+The
+\fIreaddir_r\fR()
+function may buffer several directory entries per actual read
+operation;
+\fIreaddir_r\fR()
+shall mark for update the last data access timestamp of the directory
+each time the directory is actually read.
+.SH "RETURN VALUE"
+Upon successful completion,
+\fIreaddir\fR()
+shall return a pointer to an object of type
+.BR "struct dirent" .
+When an error is encountered, a null pointer shall be returned and
+.IR errno
+shall be set to indicate the error. When the end of the directory is
+encountered, a null pointer shall be returned and
+.IR errno
+is not changed.
+.P
+If successful, the
+\fIreaddir_r\fR()
+function shall return zero; otherwise, an error number shall be
+returned to indicate the error.
+.SH ERRORS
+These functions shall fail if:
+.TP
+.BR EOVERFLOW
+One of the values in the structure to be returned cannot be represented
+correctly.
+.P
+These functions may fail if:
+.TP
+.BR EBADF
+The
+.IR dirp
+argument does not refer to an open directory stream.
+.TP
+.BR ENOENT
+The current position of the directory stream is invalid.
+.LP
+.IR "The following sections are informative."
+.SH "EXAMPLES"
+The following sample program searches the current directory for
+each of the arguments supplied on the command line.
+.sp
+.RS 4
+.nf
+
+#include <dirent.h>
+#include <errno.h>
+#include <stdio.h>
+#include <string.h>
+.P
+static void lookup(const char *arg)
+{
+    DIR *dirp;
+    struct dirent *dp;
+.P
+    if ((dirp = opendir(".")) == NULL) {
+        perror("couldn\(aqt open \(aq.\(aq");
+        return;
+    }
+.P
+    do {
+        errno = 0;
+        if ((dp = readdir(dirp)) != NULL) {
+            if (strcmp(dp->d_name, arg) != 0)
+                continue;
+.P
+            (void) printf("found %s\en", arg);
+            (void) closedir(dirp);
+                return;
+.P
+        }
+    } while (dp != NULL);
+.P
+    if (errno != 0)
+        perror("error reading directory");
+    else
+        (void) printf("failed to find %s\en", arg);
+    (void) closedir(dirp);
+    return;
+}
+.P
+int main(int argc, char *argv[])
+{
+    int i;
+    for (i = 1; i < argc; i++)
+        lookup(argv[i]);
+    return (0);
+}
+.fi
+.P
+.RE
+.SH "APPLICATION USAGE"
+The
+\fIreaddir\fR()
+function should be used in conjunction with
+\fIopendir\fR(),
+\fIclosedir\fR(),
+and
+\fIrewinddir\fR()
+to examine the contents of the directory.
+.P
+The
+\fIreaddir_r\fR()
+function is thread-safe and shall return values in a user-supplied
+buffer instead of possibly using a static data area that may be
+overwritten by each call.
+.SH RATIONALE
+The returned value of
+\fIreaddir\fR()
+merely \fIrepresents\fP a directory entry. No equivalence should be
+inferred.
+.P
+Historical implementations of
+\fIreaddir\fR()
+obtain multiple directory entries on a single read operation, which
+permits subsequent
+\fIreaddir\fR()
+operations to operate from the buffered information. Any wording that
+required each successful
+\fIreaddir\fR()
+operation to mark the directory last data access timestamp
+for update would disallow such historical performance-oriented
+implementations.
+.P
+When returning a directory entry for the root of a mounted file system,
+some historical implementations of
+\fIreaddir\fR()
+returned the file serial number of the underlying mount point, rather
+than of the root of the mounted file system. This behavior is considered
+to be a bug, since the underlying file serial number has no significance
+to applications.
+.P
+Since
+\fIreaddir\fR()
+returns NULL
+when it detects an error and when the end of the directory is
+encountered, an application that needs to tell the difference must set
+.IR errno
+to zero before the call and check it if NULL is returned.
+Since the function must not change
+.IR errno
+in the second case and must set it to a non-zero value in the first
+case, a zero
+.IR errno
+after a call returning NULL indicates end-of-directory; otherwise, an
+error.
+.P
+Routines to deal with this problem more directly were proposed:
+.sp
+.RS 4
+.nf
+
+int derror (\fIdirp\fP)
+DIR *\fIdirp\fP;
+.P
+void clearderr (\fIdirp\fP)
+DIR *\fIdirp\fP;
+.fi
+.P
+.RE
+.P
+The first would indicate whether an error had occurred, and the second
+would clear the error indication. The simpler method involving
+.IR errno
+was adopted instead by requiring that
+\fIreaddir\fR()
+not change
+.IR errno
+when end-of-directory is encountered.
+.P
+An error or signal indicating that a directory has changed while open
+was considered but rejected.
+.P
+The thread-safe version of the directory reading function returns
+values in a user-supplied buffer instead of possibly using a static
+data area that may be overwritten by each call. Either the
+{NAME_MAX}
+compile-time constant or the corresponding
+\fIpathconf\fR()
+option can be used to determine the maximum sizes of returned
+pathnames.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIclosedir\fR\^(\|)",
+.IR "\fIdirfd\fR\^(\|)",
+.IR "\fIexec\fR\^",
+.IR "\fIfdopendir\fR\^(\|)",
+.IR "\fIfstatat\fR\^(\|)",
+.IR "\fIrewinddir\fR\^(\|)",
+.IR "\fIsymlink\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<dirent.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 .