Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 293 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/lockf.3p b/upstream/archlinux/man3p/lockf.3p
new file mode 100644
index 00000000..b64216e7
--- /dev/null
+++ b/upstream/archlinux/man3p/lockf.3p
@@ -0,0 +1,293 @@
+'\" et
+.TH LOCKF "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
+lockf
+\(em record locking on files
+.SH SYNOPSIS
+.LP
+.nf
+#include <unistd.h>
+.P
+int lockf(int \fIfildes\fP, int \fIfunction\fP, off_t \fIsize\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIlockf\fR()
+function shall lock sections of a file with advisory-mode locks. Calls
+to
+\fIlockf\fR()
+from threads in other processes which attempt to lock the locked file
+section shall either return an error value or block until the section
+becomes unlocked. All the locks for a process are removed when the
+process terminates. Record locking with
+\fIlockf\fR()
+shall be supported for regular files and may be supported for other
+files.
+.P
+The
+.IR fildes
+argument is an open file descriptor. To establish a lock with this
+function, the file descriptor shall be opened with write-only
+permission (O_WRONLY) or with read/write permission (O_RDWR).
+.P
+The
+.IR function
+argument is a control value which specifies the action to be taken. The
+permissible values for
+.IR function
+are defined in
+.IR <unistd.h> 
+as follows:
+.TS
+box tab(!) center;
+cB | cB
+l | l.
+Function!Description
+_
+F_ULOCK!Unlock locked sections.
+F_LOCK!Lock a section for exclusive use.
+F_TLOCK!Test and lock a section for exclusive use.
+F_TEST!Test a section for locks by other processes.
+.TE
+.P
+F_TEST shall detect if a lock by another process is present on the
+specified section.
+.P
+F_LOCK and F_TLOCK shall both lock a section of a file if the section
+is available.
+.P
+F_ULOCK shall remove locks from a section of the file.
+.P
+The
+.IR size
+argument is the number of contiguous bytes to be locked or unlocked.
+The section to be locked or unlocked starts at the current offset in
+the file and extends forward for a positive size or backward for a
+negative size (the preceding bytes up to but not including the current
+offset). If
+.IR size
+is 0, the section from the current offset through the largest possible
+file offset shall be locked (that is, from the current offset through
+the present or any future end-of-file). An area need not be allocated
+to the file to be locked because locks may exist past the end-of-file.
+.P
+The sections locked with F_LOCK or F_TLOCK may, in whole or in part,
+contain or be contained by a previously locked section for the same
+process. When this occurs, or if adjacent locked sections would occur,
+the sections shall be combined into a single locked section. If the
+request would cause the number of locks to exceed a system-imposed
+limit, the request shall fail.
+.P
+F_LOCK and F_TLOCK requests differ only by the action taken if the
+section is not available. F_LOCK shall block the calling thread until
+the section is available. F_TLOCK shall cause the function to fail if
+the section is already locked by another process.
+.P
+File locks shall be released on first close by the locking process of
+any file descriptor for the file.
+.P
+F_ULOCK requests may release (wholly or in part) one or more locked
+sections controlled by the process. Locked sections shall be unlocked
+starting at the current file offset through
+.IR size
+bytes or to the end-of-file if
+.IR size
+is (\fBoff_t\fR)0. When all of a locked section is not released (that
+is, when the beginning or end of the area to be unlocked falls within a
+locked section), the remaining portions of that section shall remain
+locked by the process. Releasing the center portion of a locked section
+shall cause the remaining locked beginning and end portions to become two
+separate locked sections. If the request would cause the number of
+locks in the system to exceed a system-imposed limit, the request
+shall fail.
+.P
+A potential for deadlock occurs if the threads of a process controlling
+a locked section are blocked by accessing a locked section of
+another process. If the system detects that deadlock would occur,
+\fIlockf\fR()
+shall fail with an
+.BR [EDEADLK] 
+error.
+.P
+The interaction between
+\fIfcntl\fR()
+and
+\fIlockf\fR()
+locks is unspecified.
+.P
+Blocking on a section shall be interrupted by any signal.
+.P
+An F_ULOCK request in which
+.IR size
+is non-zero and the offset of the last byte of the requested section is
+the maximum value for an object of type
+.BR off_t ,
+when the process has an existing lock in which
+.IR size
+is 0 and which includes the last byte of the requested section, shall be
+treated as a request to unlock from the start of the requested section
+with a size equal to 0. Otherwise, an F_ULOCK request shall attempt to
+unlock only the requested section.
+.P
+Attempting to lock a section of a file that is associated with a
+buffered stream produces unspecified results.
+.SH "RETURN VALUE"
+Upon successful completion,
+\fIlockf\fR()
+shall return 0. Otherwise, it shall return \-1, set
+.IR errno
+to indicate an error, and existing locks shall not be changed.
+.SH ERRORS
+The
+\fIlockf\fR()
+function shall fail if:
+.TP
+.BR EBADF
+The
+.IR fildes
+argument is not a valid open file descriptor; or
+.IR function
+is F_LOCK or F_TLOCK and
+.IR fildes
+is not a valid file descriptor open for writing.
+.TP
+.BR EACCES " or " EAGAIN
+.br
+The
+.IR function
+argument is F_TLOCK or F_TEST and the section is already locked by
+another process.
+.TP
+.BR EDEADLK
+The
+.IR function
+argument is F_LOCK and a deadlock is detected.
+.TP
+.BR EINTR
+A signal was caught during execution of the function.
+.TP
+.BR EINVAL
+The
+.IR function
+argument is not one of F_LOCK, F_TLOCK, F_TEST, or F_ULOCK; or
+.IR size
+plus the current file offset is less than 0.
+.TP
+.BR EOVERFLOW
+The offset of the first, or if
+.IR size
+is not 0 then the last, byte in the requested section cannot be
+represented correctly in an object of type
+.BR off_t .
+.P
+The
+\fIlockf\fR()
+function may fail if:
+.TP
+.BR EAGAIN
+The
+.IR function
+argument is F_LOCK or F_TLOCK and the file is mapped with
+\fImmap\fR().
+.TP
+.BR EDEADLK " or " ENOLCK
+.br
+The
+.IR function
+argument is F_LOCK, F_TLOCK, or F_ULOCK, and the request would cause
+the number of locks to exceed a system-imposed limit.
+.TP
+.BR EOPNOTSUPP " or " EINVAL
+.br
+The implementation does not support the locking of files of the type
+indicated by the
+.IR fildes
+argument.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+.SS "Locking a Portion of a File"
+.P
+In the following example, a file named
+.BR /home/cnd/mod1
+is being modified. Other processes that use locking are prevented from
+changing it during this process. Only the first 10\|000 bytes are
+locked, and the lock call fails if another process has any part of this
+area locked already.
+.sp
+.RS 4
+.nf
+
+#include <fcntl.h>
+#include <unistd.h>
+.P
+int fildes;
+int status;
+\&...
+fildes = open("/home/cnd/mod1", O_RDWR);
+status = lockf(fildes, F_TLOCK, (off_t)10000);
+.fi
+.P
+.RE
+.SH "APPLICATION USAGE"
+Record-locking should not be used in combination with the
+\fIfopen\fR(),
+\fIfread\fR(),
+\fIfwrite\fR(),
+and other
+.IR stdio
+functions. Instead, the more primitive, non-buffered functions (such as
+\fIopen\fR())
+should be used. Unexpected results may occur in processes that do
+buffering in the user address space. The process may later read/write
+data which is/was locked. The
+.IR stdio
+functions are the most common source of unexpected buffering.
+.P
+The
+\fIalarm\fR()
+function may be used to provide a timeout facility in applications
+requiring it.
+.SH RATIONALE
+None.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIalarm\fR\^(\|)",
+.IR "\fIchmod\fR\^(\|)",
+.IR "\fIclose\fR\^(\|)",
+.IR "\fIcreat\fR\^(\|)",
+.IR "\fIfcntl\fR\^(\|)",
+.IR "\fIfopen\fR\^(\|)",
+.IR "\fImmap\fR\^(\|)",
+.IR "\fIopen\fR\^(\|)",
+.IR "\fIread\fR\^(\|)",
+.IR "\fIwrite\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.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 .