diff options
Diffstat (limited to '')
| -rw-r--r-- | man2/flock.2 | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/man2/flock.2 b/man2/flock.2 new file mode 100644 index 0000000..5f2917f --- /dev/null +++ b/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 2023-03-30 "Linux man-pages 6.05.01" +.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> +.PP +.BI "int flock(int " fd ", int " operation ); +.fi +.SH DESCRIPTION +Apply or remove an advisory lock on the open file specified by +.IR fd . +The argument +.I operation +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 +.PP +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. +.PP +A single file may not simultaneously have both shared and exclusive locks. +.PP +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. +.PP +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. +.PP +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. +.PP +Locks created by +.BR flock () +are preserved across an +.BR execve (2). +.PP +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 operation +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. +.PP +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. +.PP +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. +.PP +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. +.PP +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. +.PP +.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. +.PP +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) +.PP +.I Documentation/filesystems/locks.txt +in the Linux kernel source tree +.RI ( Documentation/locks.txt +in older kernels) |