Debian Codegraph @

upstream/debian-unstable/man2/flock.2

raw
1 .\" Copyright 1993, Rickard E. Faith <[email protected]>
2 .\" Copyright 2002, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" FIXME Maybe document LOCK_MAND, LOCK_RW, LOCK_READ, LOCK_WRITE
8 .\" which only have effect for SAMBA.
9 .\"
10 .TH flock 2 2026-02-08 "Linux man-pages 6.18"
11 .SH NAME
12 flock \- apply or remove an advisory lock on an open file
13 .SH LIBRARY
14 Standard C library
15 .RI ( libc ,\~ \-lc )
16 .SH SYNOPSIS
17 .nf
18 .B #include <sys/file.h>
19 .P
20 .BI "int flock(int " fd ", int " op );
21 .fi
22 .SH DESCRIPTION
23 Apply or remove an advisory lock on the open file specified by
24 .IR fd .
25 The argument
26 .I op
27 is one of the following:
28 .RS 4
29 .TP 9
30 .B LOCK_SH
31 Place a shared lock.
32 More than one process may hold a shared lock for a given file
33 at a given time.
34 .TP
35 .B LOCK_EX
36 Place an exclusive lock.
37 Only one process may hold an exclusive lock for a given
38 file at a given time.
39 .TP
40 .B LOCK_UN
41 Remove an existing lock held by this process.
42 .RE
43 .P
44 A call to
45 .BR flock ()
46 may block if an incompatible lock is held by another process.
47 To make a nonblocking request, include
48 .B LOCK_NB
49 (by ORing)
50 with any of the above operations.
51 .P
52 A single file may not simultaneously have both shared and exclusive locks.
53 .P
54 Locks created by
55 .BR flock ()
56 are associated with an open file description (see
57 .BR open (2)).
58 This means that duplicate file descriptors (created by, for example,
59 .BR fork (2)
60 or
61 .BR dup (2))
62 refer to the same lock, and this lock may be modified
63 or released using any of these file descriptors.
64 Furthermore, the lock is released either by an explicit
65 .B LOCK_UN
66 operation on any of these duplicate file descriptors, or when all
67 such file descriptors have been closed.
68 .P
69 If a process uses
70 .BR open (2)
71 (or similar) to obtain more than one file descriptor for the same file,
72 these file descriptors are treated independently by
73 .BR flock ().
74 An attempt to lock the file using one of these file descriptors
75 may be denied by a lock that the calling process has
76 already placed via another file descriptor.
77 .P
78 A process may hold only one type of lock (shared or exclusive)
79 on a file.
80 Subsequent
81 .BR flock ()
82 calls on an already locked file will convert an existing lock to the new
83 lock mode.
84 .P
85 Locks created by
86 .BR flock ()
87 are preserved across an
88 .BR execve (2).
89 .P
90 A shared or exclusive lock can be placed on a file regardless of the
91 mode in which the file was opened.
92 .SH RETURN VALUE
93 On success, zero is returned.
94 On error, \-1 is returned, and
95 .I errno
96 is set to indicate the error.
97 .SH ERRORS
98 .TP
99 .B EBADF
100 .I fd
101 is not an open file descriptor.
102 .TP
103 .B EINTR
104 While waiting to acquire a lock, the call was interrupted by
105 delivery of a signal caught by a handler;
106 see
107 .BR signal (7).
108 .TP
109 .B EINVAL
110 .I op
111 is invalid.
112 .TP
113 .B ENOLCK
114 The kernel ran out of memory for allocating lock records.
115 .TP
116 .B EWOULDBLOCK
117 The file is locked and the
118 .B LOCK_NB
119 flag was selected.
120 .SH VERSIONS
121 Since Linux 2.0,
122 .BR flock ()
123 is implemented as a system call in its own right rather
124 than being emulated in the GNU C library as a call to
125 .BR fcntl (2).
126 With this implementation,
127 there is no interaction between the types of lock
128 placed by
129 .BR flock ()
130 and
131 .BR fcntl (2),
132 and
133 .BR flock ()
134 does not detect deadlock.
135 (Note, however, that on some systems, such as the modern BSDs,
136 .\" E.g., according to the flock(2) man page, FreeBSD since at least 5.3
137 .BR flock ()
138 and
139 .BR fcntl (2)
140 locks
141 .I do
142 interact with one another.)
143 .SS CIFS details
144 Up to Linux 5.4,
145 .BR flock ()
146 is not propagated over SMB.
147 A file with such locks will not appear locked for remote clients.
148 .P
149 Since Linux 5.5,
150 .BR flock ()
151 locks are emulated with SMB byte-range locks on the entire file.
152 Similarly to NFS, this means that
153 .BR fcntl (2)
154 and
155 .BR flock ()
156 locks interact with one another.
157 Another important side-effect is that the locks are not advisory anymore:
158 any IO on a locked file will always fail with
159 .B EACCES
160 when done from a separate file descriptor.
161 This difference originates from the design of locks in the SMB protocol,
162 which provides mandatory locking semantics.
163 .P
164 Remote and mandatory locking semantics may vary with
165 SMB protocol, mount options and server type.
166 See
167 .BR mount.cifs (8)
168 for additional information.
169 .SH STANDARDS
170 BSD.
171 .SH HISTORY
172 4.4BSD (the
173 .BR flock ()
174 call first appeared in 4.2BSD).
175 A version of
176 .BR flock (),
177 possibly implemented in terms of
178 .BR fcntl (2),
179 appears on most UNIX systems.
180 .SS NFS details
181 Up to Linux 2.6.11,
182 .BR flock ()
183 does not lock files over NFS
184 (i.e., the scope of locks was limited to the local system).
185 Instead, one could use
186 .BR fcntl (2)
187 byte-range locking, which does work over NFS,
188 given a sufficiently recent version of
189 Linux and a server which supports locking.
190 .P
191 Since Linux 2.6.12, NFS clients support
192 .BR flock ()
193 locks by emulating them as
194 .BR fcntl (2)
195 byte-range locks on the entire file.
196 This means that
197 .BR fcntl (2)
198 and
199 .BR flock ()
200 locks
201 .I do
202 interact with one another over NFS.
203 It also means that in order to place an exclusive lock,
204 the file must be opened for writing.
205 .P
206 Since Linux 2.6.37,
207 .\" commit 5eebde23223aeb0ad2d9e3be6590ff8bbfab0fc2
208 the kernel supports a compatibility mode that allows
209 .BR flock ()
210 locks (and also
211 .BR fcntl (2)
212 byte region locks) to be treated as local;
213 see the discussion of the
214 .I "local_lock"
215 option in
216 .BR nfs (5).
217 .SH NOTES
218 .BR flock ()
219 places advisory locks only;
220 given suitable permissions on a file,
221 a process is free to ignore the use of
222 .BR flock ()
223 and perform I/O on the file.
224 .P
225 .BR flock ()
226 and
227 .BR fcntl (2)
228 locks have different semantics with respect to forked processes and
229 .BR dup (2).
230 On systems that implement
231 .BR flock ()
232 using
233 .BR fcntl (2),
234 the semantics of
235 .BR flock ()
236 will be different from those described in this manual page.
237 .P
238 Converting a lock
239 (shared to exclusive, or vice versa) is not guaranteed to be atomic:
240 the existing lock is first removed, and then a new lock is established.
241 Between these two steps,
242 a pending lock request by another process may be granted,
243 with the result that the conversion either blocks, or fails if
244 .B LOCK_NB
245 was specified.
246 (This is the original BSD behavior,
247 and occurs on many other implementations.)
248 .\" Kernel 2.5.21 changed things a little: during lock conversion
249 .\" it is now the highest priority process that will get the lock -- mtk
250 .P
251 Release of a lock when a file descriptor is closed
252 is not sequenced after all observable effects of
253 .BR close (2).
254 For example,
255 if one process writes a file while holding an exclusive lock,
256 then closes that file,
257 and another process blocks placing a shared lock on that file
258 to wait until it is closed,
259 it may observe that a subsequent
260 .BR execve (2)
261 of that file fails with
262 .BR ETXTBSY ,
263 and
264 .BR umount (2)
265 of its underlying filesystem fails with
266 .BR EBUSY ,
267 as if the file were still open in the first process.
268 .SH SEE ALSO
269 .BR flock (1),
270 .BR close (2),
271 .BR dup (2),
272 .BR execve (2),
273 .BR fcntl (2),
274 .BR fork (2),
275 .BR open (2),
276 .BR lockf (3),
277 .BR lslocks (8)
278 .P
279 .I Documentation/filesystems/locks.rst
280 in the Linux kernel source tree