Merging upstream version 6.8.

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

1 files changed, 267 insertions, 0 deletions

diff --git a/man/man2/flock.2 b/man/man2/flock.2
new file mode 100644
index 0000000..e376c22
--- /dev/null
+++ b/man/man2/flock.2
@@ -0,0 +1,267 @@
+.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and
+.\" and Copyright 2002 Michael Kerrisk
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Fri Jan 31 16:26:07 1997 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified Fri Dec 11 17:57:27 1998 by Jamie Lokier <jamie@imbolc.ucc.ie>
+.\" Modified 24 Apr 2002 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"	Substantial rewrites and additions
+.\" 2005-05-10 mtk, noted that lock conversions are not atomic.
+.\"
+.\" FIXME Maybe document LOCK_MAND, LOCK_RW, LOCK_READ, LOCK_WRITE
+.\" which only have effect for SAMBA.
+.\"
+.TH flock 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+flock \- apply or remove an advisory lock on an open file
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/file.h>
+.P
+.BI "int flock(int " fd ", int " op );
+.fi
+.SH DESCRIPTION
+Apply or remove an advisory lock on the open file specified by
+.IR fd .
+The argument
+.I op
+is one of the following:
+.RS 4
+.TP 9
+.B LOCK_SH
+Place a shared lock.
+More than one process may hold a shared lock for a given file
+at a given time.
+.TP
+.B LOCK_EX
+Place an exclusive lock.
+Only one process may hold an exclusive lock for a given
+file at a given time.
+.TP
+.B LOCK_UN
+Remove an existing lock held by this process.
+.RE
+.P
+A call to
+.BR flock ()
+may block if an incompatible lock is held by another process.
+To make a nonblocking request, include
+.B LOCK_NB
+(by ORing)
+with any of the above operations.
+.P
+A single file may not simultaneously have both shared and exclusive locks.
+.P
+Locks created by
+.BR flock ()
+are associated with an open file description (see
+.BR open (2)).
+This means that duplicate file descriptors (created by, for example,
+.BR fork (2)
+or
+.BR dup (2))
+refer to the same lock, and this lock may be modified
+or released using any of these file descriptors.
+Furthermore, the lock is released either by an explicit
+.B LOCK_UN
+operation on any of these duplicate file descriptors, or when all
+such file descriptors have been closed.
+.P
+If a process uses
+.BR open (2)
+(or similar) to obtain more than one file descriptor for the same file,
+these file descriptors are treated independently by
+.BR flock ().
+An attempt to lock the file using one of these file descriptors
+may be denied by a lock that the calling process has
+already placed via another file descriptor.
+.P
+A process may hold only one type of lock (shared or exclusive)
+on a file.
+Subsequent
+.BR flock ()
+calls on an already locked file will convert an existing lock to the new
+lock mode.
+.P
+Locks created by
+.BR flock ()
+are preserved across an
+.BR execve (2).
+.P
+A shared or exclusive lock can be placed on a file regardless of the
+mode in which the file was opened.
+.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
+.B EBADF
+.I fd
+is not an open file descriptor.
+.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
+.I op
+is invalid.
+.TP
+.B ENOLCK
+The kernel ran out of memory for allocating lock records.
+.TP
+.B EWOULDBLOCK
+The file is locked and the
+.B LOCK_NB
+flag was selected.
+.SH VERSIONS
+Since Linux 2.0,
+.BR flock ()
+is implemented as a system call in its own right rather
+than being emulated in the GNU C library as a call to
+.BR fcntl (2).
+With this implementation,
+there is no interaction between the types of lock
+placed by
+.BR flock ()
+and
+.BR fcntl (2),
+and
+.BR flock ()
+does not detect deadlock.
+(Note, however, that on some systems, such as the modern BSDs,
+.\" E.g., according to the flock(2) man page, FreeBSD since at least 5.3
+.BR flock ()
+and
+.BR fcntl (2)
+locks
+.I do
+interact with one another.)
+.SS CIFS details
+Up to Linux 5.4,
+.BR flock ()
+is not propagated over SMB.
+A file with such locks will not appear locked for remote clients.
+.P
+Since Linux 5.5,
+.BR flock ()
+locks are emulated with SMB byte-range locks on the entire file.
+Similarly to NFS, this means that
+.BR fcntl (2)
+and
+.BR flock ()
+locks interact with one another.
+Another important side-effect is that the locks are not advisory anymore:
+any IO on a locked file will always fail with
+.B EACCES
+when done from a separate file descriptor.
+This difference originates from the design of locks in the SMB protocol,
+which provides mandatory locking semantics.
+.P
+Remote and mandatory locking semantics may vary with
+SMB protocol, mount options and server type.
+See
+.BR mount.cifs (8)
+for additional information.
+.SH STANDARDS
+BSD.
+.SH HISTORY
+4.4BSD (the
+.BR flock ()
+call first appeared in 4.2BSD).
+A version of
+.BR flock (),
+possibly implemented in terms of
+.BR fcntl (2),
+appears on most UNIX systems.
+.SS NFS details
+Up to Linux 2.6.11,
+.BR flock ()
+does not lock files over NFS
+(i.e., the scope of locks was limited to the local system).
+Instead, one could use
+.BR fcntl (2)
+byte-range locking, which does work over NFS,
+given a sufficiently recent version of
+Linux and a server which supports locking.
+.P
+Since Linux 2.6.12, NFS clients support
+.BR flock ()
+locks by emulating them as
+.BR fcntl (2)
+byte-range locks on the entire file.
+This means that
+.BR fcntl (2)
+and
+.BR flock ()
+locks
+.I do
+interact with one another over NFS.
+It also means that in order to place an exclusive lock,
+the file must be opened for writing.
+.P
+Since Linux 2.6.37,
+.\" commit 5eebde23223aeb0ad2d9e3be6590ff8bbfab0fc2
+the kernel supports a compatibility mode that allows
+.BR flock ()
+locks (and also
+.BR fcntl (2)
+byte region locks) to be treated as local;
+see the discussion of the
+.I "local_lock"
+option in
+.BR nfs (5).
+.SH NOTES
+.BR flock ()
+places advisory locks only; given suitable permissions on a file,
+a process is free to ignore the use of
+.BR flock ()
+and perform I/O on the file.
+.P
+.BR flock ()
+and
+.BR fcntl (2)
+locks have different semantics with respect to forked processes and
+.BR dup (2).
+On systems that implement
+.BR flock ()
+using
+.BR fcntl (2),
+the semantics of
+.BR flock ()
+will be different from those described in this manual page.
+.P
+Converting a lock
+(shared to exclusive, or vice versa) is not guaranteed to be atomic:
+the existing lock is first removed, and then a new lock is established.
+Between these two steps,
+a pending lock request by another process may be granted,
+with the result that the conversion either blocks, or fails if
+.B LOCK_NB
+was specified.
+(This is the original BSD behavior,
+and occurs on many other implementations.)
+.\" Kernel 2.5.21 changed things a little: during lock conversion
+.\" it is now the highest priority process that will get the lock -- mtk
+.SH SEE ALSO
+.BR flock (1),
+.BR close (2),
+.BR dup (2),
+.BR execve (2),
+.BR fcntl (2),
+.BR fork (2),
+.BR open (2),
+.BR lockf (3),
+.BR lslocks (8)
+.P
+.I Documentation/filesystems/locks.txt
+in the Linux kernel source tree
+.RI ( Documentation/locks.txt
+in older kernels)