Merging upstream version 6.8.

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

1 files changed, 179 insertions, 0 deletions

diff --git a/man/man3/lockf.3 b/man/man3/lockf.3
new file mode 100644
index 0000000..c86895a
--- /dev/null
+++ b/man/man3/lockf.3
@@ -0,0 +1,179 @@
+'\" t
+.\" Copyright 1997 Nicolás Lichtmaier <nick@debian.org>
+.\" Created Thu Aug  7 00:44:00 ART 1997
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" Added section stuff, aeb, 2002-04-22.
+.\" Corrected include file, drepper, 2003-06-15.
+.\"
+.TH lockf 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+lockf \- apply, test or remove a POSIX lock on an open file
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "int lockf(int " fd ", int " op ", off_t " len );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR lockf ():
+.nf
+    _XOPEN_SOURCE >= 500
+.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+        || /* glibc >= 2.19: */ _DEFAULT_SOURCE
+        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+Apply, test, or remove a POSIX lock on a section of an open file.
+The file is specified by
+.IR fd ,
+a file descriptor open for writing, the action by
+.IR op ,
+and the section consists of byte positions
+.IR pos .. pos + len \-1
+if
+.I len
+is positive, and
+.IR pos \- len .. pos \-1
+if
+.I len
+is negative, where
+.I pos
+is the current file position, and if
+.I len
+is zero, the section extends from the current file position to
+infinity, encompassing the present and future end-of-file positions.
+In all cases, the section may extend past current end-of-file.
+.P
+On Linux,
+.BR lockf ()
+is just an interface on top of
+.BR fcntl (2)
+locking.
+Many other systems implement
+.BR lockf ()
+in this way, but note that POSIX.1 leaves the relationship between
+.BR lockf ()
+and
+.BR fcntl (2)
+locks unspecified.
+A portable application should probably avoid mixing calls
+to these interfaces.
+.P
+Valid operations are given below:
+.TP
+.B F_LOCK
+Set an exclusive lock on the specified section of the file.
+If (part of) this section is already locked, the call
+blocks until the previous lock is released.
+If this section overlaps an earlier locked section,
+both are merged.
+File locks are released as soon as the process holding the locks
+closes some file descriptor for the file.
+A child process does not inherit these locks.
+.TP
+.B F_TLOCK
+Same as
+.B F_LOCK
+but the call never blocks and returns an error instead if the file is
+already locked.
+.TP
+.B F_ULOCK
+Unlock the indicated section of the file.
+This may cause a locked section to be split into two locked sections.
+.TP
+.B F_TEST
+Test the lock: return 0 if the specified section
+is unlocked or locked by this process; return \-1, set
+.I errno
+to
+.B EAGAIN
+.RB ( EACCES
+on some other systems),
+if another process holds a lock.
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.BR EACCES " or " EAGAIN
+The file is locked and
+.B F_TLOCK
+or
+.B F_TEST
+was specified, or the operation is prohibited because the file has
+been memory-mapped by another process.
+.TP
+.B EBADF
+.I fd
+is not an open file descriptor; or
+.I op
+is
+.B F_LOCK
+or
+.B F_TLOCK
+and
+.I fd
+is not a writable file descriptor.
+.TP
+.B EDEADLK
+.I op
+was
+.B F_LOCK
+and this lock operation would cause a deadlock.
+.TP
+.B EINTR
+While waiting to acquire a lock, the call was interrupted by
+delivery of a signal caught by a handler; see
+.BR signal (7).
+.TP
+.B EINVAL
+An invalid operation was specified in
+.IR op .
+.TP
+.B ENOLCK
+Too many segment locks open, lock table is full.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR lockf ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.SH SEE ALSO
+.BR fcntl (2),
+.BR flock (2)
+.P
+.I locks.txt
+and
+.I mandatory\-locking.txt
+in the Linux kernel source directory
+.I Documentation/filesystems
+(on older kernels, these files are directly under the
+.I Documentation
+directory, and
+.I mandatory\-locking.txt
+is called
+.IR mandatory.txt )