| .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and |
| .\" and Copyright 2002 Michael Kerrisk |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| flock \- apply or remove an advisory lock on an open file |
| .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 CONFORMING TO |
| 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. |
| .SH NOTES |
| Since kernel 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.) |
| .PP |
| .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 |
| .SS NFS details |
| In Linux kernels up to 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 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) |