summaryrefslogtreecommitdiffstats
path: root/man2/flock.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/flock.2')
-rw-r--r--man2/flock.2267
1 files changed, 0 insertions, 267 deletions
diff --git a/man2/flock.2 b/man2/flock.2
deleted file mode 100644
index c2c93ca..0000000
--- a/man2/flock.2
+++ /dev/null
@@ -1,267 +0,0 @@
-.\" 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-03-03 "Linux man-pages 6.7"
-.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)