Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 185 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/lseek.3p b/upstream/archlinux/man3p/lseek.3p
new file mode 100644
index 00000000..68e69e0c
--- /dev/null
+++ b/upstream/archlinux/man3p/lseek.3p
@@ -0,0 +1,185 @@
+'\" et
+.TH LSEEK "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
+lseek
+\(em move the read/write file offset
+.SH SYNOPSIS
+.LP
+.nf
+#include <unistd.h>
+.P
+off_t lseek(int \fIfildes\fP, off_t \fIoffset\fP, int \fIwhence\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIlseek\fR()
+function shall set the file offset for the open file description
+associated with the file descriptor
+.IR fildes,
+as follows:
+.IP " *" 4
+If
+.IR whence
+is SEEK_SET, the file offset shall be set to
+.IR offset
+bytes.
+.IP " *" 4
+If
+.IR whence
+is SEEK_CUR, the file offset shall be set to its current location plus
+.IR offset .
+.IP " *" 4
+If
+.IR whence
+is SEEK_END, the file offset shall be set to the size of the file plus
+.IR offset .
+.P
+The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END
+are defined in
+.IR <unistd.h> .
+.P
+The behavior of
+\fIlseek\fR()
+on devices which are incapable of seeking is implementation-defined.
+The value of the file offset associated with such a device is
+undefined.
+.P
+The
+\fIlseek\fR()
+function shall allow the file offset to be set beyond the end of the
+existing data in the file. If data is later written at this point,
+subsequent reads of data in the gap shall return bytes with the value 0
+until data is actually written into the gap.
+.P
+The
+\fIlseek\fR()
+function shall not, by itself, extend the size of a file.
+.P
+If
+.IR fildes
+refers to a shared memory object, the result of the
+\fIlseek\fR()
+function is unspecified.
+.P
+If
+.IR fildes
+refers to a typed memory object, the result of the
+\fIlseek\fR()
+function is unspecified.
+.SH "RETURN VALUE"
+Upon successful completion, the resulting offset, as measured in bytes
+from the beginning of the file, shall be returned. Otherwise, \-1
+shall be returned,
+.IR errno
+shall be set to indicate the error, and the file offset shall remain
+unchanged.
+.SH ERRORS
+The
+\fIlseek\fR()
+function shall fail if:
+.TP
+.BR EBADF
+The
+.IR fildes
+argument is not an open file descriptor.
+.TP
+.BR EINVAL
+The
+.IR whence
+argument is not a proper value, or the resulting file offset would be
+negative for a regular file, block special file, or directory.
+.TP
+.BR EOVERFLOW
+The resulting file offset would be a value which cannot be represented
+correctly in an object of type
+.BR off_t .
+.TP
+.BR ESPIPE
+The
+.IR fildes
+argument is associated with a pipe, FIFO, or socket.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+None.
+.SH RATIONALE
+The ISO\ C standard includes the functions
+\fIfgetpos\fR()
+and
+\fIfsetpos\fR(),
+which work on very large files by use of a special positioning type.
+.P
+Although
+\fIlseek\fR()
+may position the file offset beyond the end of the file, this function
+does not itself extend the size of the file. While the only function
+in POSIX.1\(hy2008 that may directly extend the size of the file is
+\fIwrite\fR(),
+\fItruncate\fR(),
+and
+\fIftruncate\fR(),
+several functions originally derived from the ISO\ C standard, such as
+\fIfwrite\fR(),
+\fIfprintf\fR(),
+and so on, may do so (by causing calls on
+\fIwrite\fR()).
+.P
+An invalid file offset that would cause
+.BR [EINVAL] 
+to be returned may be both implementation-defined and
+device-dependent (for example, memory may have few invalid values). A
+negative file offset may be valid for some devices in some
+implementations.
+.P
+The POSIX.1\(hy1990 standard did not specifically prohibit
+\fIlseek\fR()
+from returning a negative offset. Therefore, an application was
+required to clear
+.IR errno
+prior to the call and check
+.IR errno
+upon return to determine whether a return value of (\c
+.BR off_t )\-1
+is a negative offset or an indication of an error condition. The
+standard developers did not wish to require this action on the part of
+a conforming application, and chose to require that
+.IR errno
+be set to
+.BR [EINVAL] 
+when the resulting file offset would be negative for a regular file,
+block special file, or directory.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIopen\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<sys_types.h>\fP",
+.IR "\fB<unistd.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 .