Debian Codegraph @

upstream/debian-unstable/man2/fcntl_locking.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH fcntl_locking 2 2026-01-23 "Linux man-pages 6.18"
6 .SH NAME
7 F_GETLK,
8 F_SETLK,
9 F_SETLKW,
10 F_OFD_GETLK,
11 F_OFD_SETLK,
12 F_OFD_SETLKW
13 \-
14 locking
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ,\~ \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <fcntl.h>
21 .P
22 .BI "int fcntl(int " fd ", F_GETLK, struct flock *" lock );
23 .BI "int fcntl(int " fd ", F_SETLK, const struct flock *" lock );
24 .BI "int fcntl(int " fd ", F_SETLKW, const struct flock *" lock );
25 .P
26 .BI "int fcntl(int " fd ", F_OFD_GETLK, struct flock *" lock );
27 .BI "int fcntl(int " fd ", F_OFD_SETLK, const struct flock *" lock );
28 .BI "int fcntl(int " fd ", F_OFD_SETLKW, const struct flock *" lock );
29 .fi
30 .SH DESCRIPTION
31 .SS Advisory record locking
32 Linux implements traditional ("process-associated") UNIX record locks,
33 as standardized by POSIX.
34 For a Linux-specific alternative with better semantics,
35 see the discussion of open file description locks below.
36 .P
37 .BR F_SETLK ,
38 .BR F_SETLKW ,
39 and
40 .B F_GETLK
41 are used to acquire, release, and test for the existence of record
42 locks (also known as byte-range, file-segment, or file-region locks).
43 The third argument,
44 .IR lock ,
45 is a pointer to a structure that has at least the following fields
46 (in unspecified order).
47 .P
48 .in +4n
49 .EX
50 struct flock {
51 ...
52 short l_type; /* Type of lock: F_RDLCK,
53 F_WRLCK, F_UNLCK */
54 short l_whence; /* How to interpret l_start:
55 SEEK_SET, SEEK_CUR, SEEK_END */
56 off_t l_start; /* Starting offset for lock */
57 off_t l_len; /* Number of bytes to lock */
58 pid_t l_pid; /* PID of process blocking our lock
59 (set by F_GETLK and F_OFD_GETLK) */
60 ...
61 };
62 .EE
63 .in
64 .P
65 The
66 .IR l_whence ", " l_start ", and " l_len
67 fields of this structure specify the range of bytes we wish to lock.
68 Bytes past the end of the file may be locked,
69 but not bytes before the start of the file.
70 .P
71 .I l_start
72 is the starting offset for the lock, and is interpreted
73 relative to either:
74 the start of the file (if
75 .I l_whence
76 is
77 .BR SEEK_SET );
78 the current file offset (if
79 .I l_whence
80 is
81 .BR SEEK_CUR );
82 or the end of the file (if
83 .I l_whence
84 is
85 .BR SEEK_END ).
86 In the final two cases,
87 .I l_start
88 can be a negative number provided the
89 offset does not lie before the start of the file.
90 .P
91 .I l_len
92 specifies the number of bytes to be locked.
93 If
94 .I l_len
95 is positive, then the range to be locked covers bytes
96 .I l_start
97 up to and including
98 .IR l_start + l_len \-1.
99 Specifying 0 for
100 .I l_len
101 has the special meaning: lock all bytes starting at the
102 location specified by
103 .IR l_whence " and " l_start
104 through to the end of file, no matter how large the file grows.
105 .P
106 POSIX.1-2001 allows (but does not require)
107 an implementation to support a negative
108 .I l_len
109 value;
110 if
111 .I l_len
112 is negative, the interval described by
113 .I lock
114 covers bytes
115 .IR l_start + l_len
116 up to and including
117 .IR l_start \-1.
118 This is supported since Linux 2.4.21 and Linux 2.5.49.
119 .P
120 The
121 .I l_type
122 field can be used to place a read
123 .RB ( F_RDLCK )
124 or a write
125 .RB ( F_WRLCK )
126 lock on a file.
127 Any number of processes may hold a read lock (shared lock)
128 on a file region, but only one process may hold a write lock
129 (exclusive lock).
130 An exclusive lock excludes all other locks,
131 both shared and exclusive.
132 A single process can hold only one type of lock on a file region;
133 if a new lock is applied to an already-locked region,
134 then the existing lock is converted to the new lock type.
135 (Such conversions may involve splitting, shrinking, or coalescing with
136 an existing lock if the byte range specified by the new lock does not
137 precisely coincide with the range of the existing lock.)
138 .TP
139 .B F_SETLK
140 Acquire a lock (when
141 .I l_type
142 is
143 .B F_RDLCK
144 or
145 .BR F_WRLCK )
146 or release a lock (when
147 .I l_type
148 is
149 .BR F_UNLCK )
150 on the bytes specified by the
151 .IR l_whence ", " l_start ", and " l_len
152 fields of
153 .IR lock .
154 If a conflicting lock is held by another process,
155 this call returns \-1 and sets
156 .I errno
157 to
158 .B EACCES
159 or
160 .BR EAGAIN .
161 (The error returned in this case differs across implementations,
162 so POSIX requires a portable application to check for both errors.)
163 .TP
164 .B F_SETLKW
165 As for
166 .BR F_SETLK ,
167 but if a conflicting lock is held on the file, then wait for that
168 lock to be released.
169 If a signal is caught while waiting, then the call is interrupted
170 and (after the signal handler has returned)
171 returns immediately (with return value \-1 and
172 .I errno
173 set to
174 .BR EINTR ;
175 see
176 .BR signal (7)).
177 .TP
178 .B F_GETLK
179 On input to this call,
180 .I lock
181 describes a lock we would like to place on the file.
182 If the lock could be placed,
183 .BR fcntl ()
184 does not actually place it, but returns
185 .B F_UNLCK
186 in the
187 .I l_type
188 field of
189 .I lock
190 and leaves the other fields of the structure unchanged.
191 .IP
192 If one or more incompatible locks would prevent
193 this lock being placed, then
194 .BR fcntl ()
195 returns details about one of those locks in the
196 .IR l_type ", " l_whence ", " l_start ", and " l_len
197 fields of
198 .IR lock .
199 If the conflicting lock is a traditional (process-associated) record lock,
200 then the
201 .I l_pid
202 field is set to the PID of the process holding that lock.
203 If the conflicting lock is an open file description lock, then
204 .I l_pid
205 is set to \-1.
206 Note that the returned information
207 may already be out of date by the time the caller inspects it.
208 .P
209 In order to place a read lock,
210 .I fd
211 must be open for reading.
212 In order to place a write lock,
213 .I fd
214 must be open for writing.
215 To place both types of lock, open a file read-write.
216 .P
217 When placing locks with
218 .BR F_SETLKW ,
219 the kernel detects
220 .IR deadlocks ,
221 whereby two or more processes have their
222 lock requests mutually blocked by locks held by the other processes.
223 For example, suppose process A holds a write lock on byte 100 of a file,
224 and process B holds a write lock on byte 200.
225 If each process then attempts to lock the byte already
226 locked by the other process using
227 .BR F_SETLKW ,
228 then, without deadlock detection,
229 both processes would remain blocked indefinitely.
230 When the kernel detects such deadlocks,
231 it causes one of the blocking lock requests to immediately fail with the error
232 .BR EDEADLK ;
233 an application that encounters such an error should release
234 some of its locks to allow other applications to proceed before
235 attempting regain the locks that it requires.
236 Circular deadlocks involving more than two processes are also detected.
237 Note, however, that there are limitations to the kernel's
238 deadlock-detection algorithm;
239 see BUGS.
240 .P
241 As well as being removed by an explicit
242 .BR F_UNLCK ,
243 record locks are automatically released when the process terminates.
244 .P
245 Record locks are not inherited by a child created via
246 .BR fork (2),
247 but are preserved across an
248 .BR execve (2).
249 .P
250 Because of the buffering performed by the
251 .BR stdio (3)
252 library, the use of record locking with routines in that package
253 should be avoided;
254 use
255 .BR read (2)
256 and
257 .BR write (2)
258 instead.
259 .P
260 The record locks described above are associated with the process
261 (unlike the open file description locks described below).
262 This has some unfortunate consequences:
263 .IP \[bu] 3
264 If a process closes
265 .I any
266 file descriptor referring to a file,
267 then all of the process's locks on that file are released,
268 regardless of the file descriptor(s) on which the locks were obtained.
269 .\" (Additional file descriptors referring to the same file
270 .\" may have been obtained by calls to
271 .\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl ().)
272 This is bad: it means that a process can lose its locks on
273 a file such as
274 .I /etc/passwd
275 or
276 .I /etc/mtab
277 when for some reason a library function decides to open, read,
278 and close the same file.
279 .IP \[bu]
280 The threads in a process share locks.
281 In other words,
282 a multithreaded program can't use record locking to ensure
283 that threads don't simultaneously access the same region of a file.
284 .P
285 Open file description locks solve both of these problems.
286 .SS Open file description locks (non-POSIX)
287 Open file description locks are advisory byte-range locks whose operation is
288 in most respects identical to the traditional record locks described above.
289 This lock type is Linux-specific,
290 and available since Linux 3.15.
291 (There is a proposal with the Austin Group
292 .\" FIXME . Review progress into POSIX
293 .\" http://austingroupbugs.net/view.php?id=768
294 to include this lock type in the next revision of POSIX.1.)
295 For an explanation of open file descriptions, see
296 .BR open (2).
297 .P
298 The principal difference between the two lock types
299 is that whereas traditional record locks
300 are associated with a process,
301 open file description locks are associated with the
302 open file description on which they are acquired,
303 much like locks acquired with
304 .BR flock (2).
305 Consequently (and unlike traditional advisory record locks),
306 open file description locks are inherited across
307 .BR fork (2)
308 (and
309 .BR clone (2)
310 with
311 .BR CLONE_FILES ),
312 and are only automatically released on the last close
313 of the open file description,
314 instead of being released on any close of the file.
315 .P
316 Conflicting lock combinations
317 (i.e., a read lock and a write lock or two write locks)
318 where one lock is an open file description lock and the other
319 is a traditional record lock conflict
320 even when they are acquired by the same process on the same file descriptor.
321 .P
322 Open file description locks placed via the same open file description
323 (i.e., via the same file descriptor,
324 or via a duplicate of the file descriptor created by
325 .BR fork (2),
326 .BR dup (2),
327 .BR F_DUPFD (2const),
328 and so on) are always compatible:
329 if a new lock is placed on an already locked region,
330 then the existing lock is converted to the new lock type.
331 (Such conversions may result in splitting, shrinking, or coalescing with
332 an existing lock as discussed above.)
333 .P
334 On the other hand, open file description locks may conflict with
335 each other when they are acquired via different open file descriptions.
336 Thus, the threads in a multithreaded program can use
337 open file description locks to synchronize access to a file region
338 by having each thread perform its own
339 .BR open (2)
340 on the file and applying locks via the resulting file descriptor.
341 .P
342 As with traditional advisory locks, the third argument to
343 .BR fcntl (),
344 .IR lock ,
345 is a pointer to an
346 .I flock
347 structure.
348 By contrast with traditional record locks, the
349 .I l_pid
350 field of that structure must be set to zero
351 when using the operations described below.
352 .P
353 The operations for working with open file description locks are analogous
354 to those used with traditional locks:
355 .TP
356 .B F_OFD_SETLK
357 Acquire an open file description lock (when
358 .I l_type
359 is
360 .B F_RDLCK
361 or
362 .BR F_WRLCK )
363 or release an open file description lock (when
364 .I l_type
365 is
366 .BR F_UNLCK )
367 on the bytes specified by the
368 .IR l_whence ", " l_start ", and " l_len
369 fields of
370 .IR lock .
371 If a conflicting lock is held by another process,
372 this call returns \-1 and sets
373 .I errno
374 to
375 .BR EAGAIN .
376 .TP
377 .B F_OFD_SETLKW
378 As for
379 .BR F_OFD_SETLK ,
380 but if a conflicting lock is held on the file, then wait for that lock to be
381 released.
382 If a signal is caught while waiting, then the call is interrupted
383 and (after the signal handler has returned) returns immediately
384 (with return value \-1 and
385 .I errno
386 set to
387 .BR EINTR ;
388 see
389 .BR signal (7)).
390 .TP
391 .B F_OFD_GETLK
392 On input to this call,
393 .I lock
394 describes an open file description lock we would like to place on the file.
395 If the lock could be placed,
396 .BR fcntl ()
397 does not actually place it, but returns
398 .B F_UNLCK
399 in the
400 .I l_type
401 field of
402 .I lock
403 and leaves the other fields of the structure unchanged.
404 If one or more incompatible locks would prevent this lock being placed,
405 then details about one of these locks are returned via
406 .IR lock ,
407 as described above for
408 .BR F_GETLK .
409 .P
410 In the current implementation,
411 .\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7
412 no deadlock detection is performed for open file description locks.
413 (This contrasts with process-associated record locks,
414 for which the kernel does perform deadlock detection.)
415 .\"
416 .SS Mandatory locking
417 .IR Warning :
418 the Linux implementation of mandatory locking is unreliable.
419 See BUGS below.
420 Because of these bugs,
421 and the fact that the feature is believed to be little used,
422 since Linux 4.5, mandatory locking has been made an optional feature,
423 governed by a configuration option
424 .RB ( CONFIG_MANDATORY_FILE_LOCKING ).
425 This feature is no longer supported at all in Linux 5.15 and above.
426 .P
427 By default, both traditional (process-associated) and open file description
428 record locks are advisory.
429 Advisory locks are not enforced and are useful only between
430 cooperating processes.
431 .P
432 Both lock types can also be mandatory.
433 Mandatory locks are enforced for all processes.
434 If a process tries to perform an incompatible access (e.g.,
435 .BR read (2)
436 or
437 .BR write (2))
438 on a file region that has an incompatible mandatory lock,
439 then the result depends upon whether the
440 .B O_NONBLOCK
441 flag is enabled for its open file description.
442 If the
443 .B O_NONBLOCK
444 flag is not enabled, then
445 the system call is blocked until the lock is removed
446 or converted to a mode that is compatible with the access.
447 If the
448 .B O_NONBLOCK
449 flag is enabled, then the system call fails with the error
450 .BR EAGAIN .
451 .P
452 To make use of mandatory locks, mandatory locking must be enabled
453 both on the filesystem that contains the file to be locked,
454 and on the file itself.
455 Mandatory locking is enabled on a filesystem
456 using the "\-o mand" option to
457 .BR mount (8),
458 or the
459 .B MS_MANDLOCK
460 flag for
461 .BR mount (2).
462 Mandatory locking is enabled on a file by disabling
463 group execute permission on the file and enabling the set-group-ID
464 permission bit (see
465 .BR chmod (1)
466 and
467 .BR chmod (2)).
468 .P
469 Mandatory locking is not specified by POSIX.
470 Some other systems also support mandatory locking,
471 although the details of how to enable it vary across systems.
472 .\"
473 .SS Lost locks
474 When an advisory lock is obtained on a networked filesystem such as
475 NFS it is possible that the lock might get lost.
476 This may happen due to administrative action on the server, or due to a
477 network partition (i.e., loss of network connectivity with the server)
478 which lasts long enough for the server to assume
479 that the client is no longer functioning.
480 .P
481 When the filesystem determines that a lock has been lost, future
482 .BR read (2)
483 or
484 .BR write (2)
485 requests may fail with the error
486 .BR EIO .
487 This error will persist until the lock is removed or the file
488 descriptor is closed.
489 Since Linux 3.12,
490 .\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d
491 this happens at least for NFSv4 (including all minor versions).
492 .P
493 Some versions of UNIX send a signal
494 .RB ( SIGLOST )
495 in this circumstance.
496 Linux does not define this signal, and does not provide any
497 asynchronous notification of lost locks.
498 .SH RETURN VALUE
499 Zero.
500 .P
501 On error, \-1 is returned, and
502 .I errno
503 is set to indicate the error.
504 .SH ERRORS
505 See
506 .BR fcntl (2).
507 .TP
508 .B EBADF
509 .I op
510 is
511 .B F_SETLK
512 or
513 .B F_SETLKW
514 and the file descriptor open mode doesn't match with the
515 type of lock requested.
516 .TP
517 .B EDEADLK
518 It was detected that the specified
519 .B F_SETLKW
520 operation would cause a deadlock.
521 .TP
522 .B EFAULT
523 .I lock
524 is outside your accessible address space.
525 .TP
526 .B EINTR
527 .I op
528 is
529 .B F_SETLKW
530 or
531 .B F_OFD_SETLKW
532 and the operation was interrupted by a signal;
533 see
534 .BR signal (7).
535 .TP
536 .B EINTR
537 .I op
538 is
539 .BR F_GETLK ,
540 .BR F_SETLK ,
541 .BR F_OFD_GETLK ,
542 or
543 .BR F_OFD_SETLK ,
544 and the operation was interrupted by a signal before the lock was checked or
545 acquired.
546 Most likely when locking a remote file (e.g., locking over
547 NFS), but can sometimes happen locally.
548 .TP
549 .B EINVAL
550 .I op
551 is
552 .BR F_OFD_SETLK ,
553 .BR F_OFD_SETLKW ,
554 or
555 .BR F_OFD_GETLK ,
556 and
557 .I l_pid
558 was not specified as zero.
559 .TP
560 .B ENOLCK
561 Too many segment locks open, lock table is full, or a remote locking
562 protocol failed (e.g., locking over NFS).
563 .SH STANDARDS
564 POSIX.1-2024.
565 .\" .P
566 .\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.
567 .SH HISTORY
568 .TP
569 .B F_GETLK
570 .TQ
571 .B F_SETLK
572 .TQ
573 .B F_SETLKW
574 4.3BSD,
575 SVr4,
576 POSIX.1-1988.
577 .TP
578 .B F_OFD_SETLK
579 .TQ
580 .B F_OFD_SETLKW
581 .TQ
582 .B F_OFD_GETLK
583 POSIX.1-2024.
584 .SH NOTES
585 .SS File locking
586 The original Linux
587 .BR fcntl ()
588 system call was not designed to handle large file offsets
589 (in the
590 .I flock
591 structure).
592 Consequently, an
593 .BR fcntl64 ()
594 system call was added in Linux 2.4.
595 The newer system call employs a different structure for file locking,
596 .IR flock64 ,
597 and corresponding operations,
598 .BR F_GETLK64 ,
599 .BR F_SETLK64 ,
600 and
601 .BR F_SETLKW64 .
602 However, these details can be ignored by applications using glibc, whose
603 .BR fcntl ()
604 wrapper function transparently employs the more recent system call
605 where it is available.
606 .\"
607 .SS Record locks
608 Since Linux 2.0, there is no interaction between the types of lock
609 placed by
610 .BR flock (2)
611 and
612 .BR fcntl ().
613 .P
614 Several systems have more fields in
615 .I "struct flock"
616 such as, for example,
617 .I l_sysid
618 (to identify the machine where the lock is held).
619 .\" e.g., Solaris 8 documents this field in fcntl(2), and Irix 6.5
620 .\" documents it in fcntl(5). mtk, May 2007
621 .\" Also, FreeBSD documents it (Apr 2014).
622 Clearly,
623 .I l_pid
624 alone is not going to be very useful if the process holding the lock
625 may live on a different machine;
626 on Linux, while present on some architectures (such as MIPS32),
627 this field is not used.
628 .P
629 The original Linux
630 .BR fcntl ()
631 system call was not designed to handle large file offsets
632 (in the
633 .I flock
634 structure).
635 Consequently, an
636 .BR fcntl64 ()
637 system call was added in Linux 2.4.
638 The newer system call employs a different structure for file locking,
639 .IR flock64 ,
640 and corresponding operations,
641 .BR F_GETLK64 ,
642 .BR F_SETLK64 ,
643 and
644 .BR F_SETLKW64 .
645 However, these details can be ignored by applications using glibc, whose
646 .BR fcntl ()
647 wrapper function transparently employs the more recent system call
648 where it is available.
649 .SS Record locking and NFS
650 Before Linux 3.12, if an NFSv4 client
651 loses contact with the server for a period of time
652 (defined as more than 90 seconds with no communication),
653 .\"
654 .\" Neil Brown: With NFSv3 the failure mode is the reverse. If
655 .\" the server loses contact with a client then any lock stays in place
656 .\" indefinitely ("why can't I read my mail"... I remember it well).
657 .\"
658 it might lose and regain a lock without ever being aware of the fact.
659 (The period of time after which contact is assumed lost is known as
660 the NFSv4 leasetime.
661 On a Linux NFS server, this can be determined by looking at
662 .IR /proc/fs/nfsd/nfsv4leasetime ,
663 which expresses the period in seconds.
664 The default value for this file is 90.)
665 .\"
666 .\" Jeff Layton:
667 .\" Note that this is not a firm timeout. The server runs a job
668 .\" periodically to clean out expired stateful objects, and it's likely
669 .\" that there is some time (maybe even up to another whole lease period)
670 .\" between when the timeout expires and the job actually runs. If the
671 .\" client gets a RENEW in there within that window, its lease will be
672 .\" renewed and its state preserved.
673 .\"
674 This scenario potentially risks data corruption,
675 since another process might acquire a lock in the intervening period
676 and perform file I/O.
677 .P
678 Since Linux 3.12,
679 .\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d
680 if an NFSv4 client loses contact with the server,
681 any I/O to the file by a process which "thinks" it holds
682 a lock will fail until that process closes and reopens the file.
683 A kernel parameter,
684 .IR nfs.recover_lost_locks ,
685 can be set to 1 to obtain the pre-3.12 behavior,
686 whereby the client will attempt to recover lost locks
687 when contact is reestablished with the server.
688 Because of the attendant risk of data corruption,
689 .\" commit f6de7a39c181dfb8a2c534661a53c73afb3081cd
690 this parameter defaults to 0 (disabled).
691 .SH BUGS
692 .SS Deadlock detection
693 The deadlock-detection algorithm employed by the kernel when dealing with
694 .B F_SETLKW
695 requests can yield both
696 false negatives (failures to detect deadlocks,
697 leaving a set of deadlocked processes blocked indefinitely)
698 and false positives
699 .RB ( EDEADLK
700 errors when there is no deadlock).
701 For example,
702 the kernel limits the lock depth of its dependency search to 10 steps,
703 meaning that circular deadlock chains that exceed
704 that size will not be detected.
705 In addition, the kernel may falsely indicate a deadlock
706 when two or more processes created using the
707 .BR clone (2)
708 .B CLONE_FILES
709 flag place locks that appear (to the kernel) to conflict.
710 .\"
711 .SS Mandatory locking
712 The Linux implementation of mandatory locking
713 is subject to race conditions which render it unreliable:
714 .\" http://marc.info/?l=linux-kernel&m=119013491707153&w=2
715 .\"
716 .\" Reconfirmed by Jeff Layton
717 .\" From: Jeff Layton <jlayton <at> redhat.com>
718 .\" Subject: Re: Status of fcntl() mandatory locking
719 .\" Newsgroups: gmane.linux.file-systems
720 .\" Date: 2014-04-28 10:07:57 GMT
721 .\" http://thread.gmane.org/gmane.linux.file-systems/84481/focus=84518
722 a
723 .BR write (2)
724 call that overlaps with a lock may modify data after the mandatory lock is
725 acquired;
726 a
727 .BR read (2)
728 call that overlaps with a lock may detect changes to data that were made
729 only after a write lock was acquired.
730 Similar races exist between mandatory locks and
731 .BR mmap (2).
732 It is therefore inadvisable to rely on mandatory locking.
733 .SH SEE ALSO
734 .BR fcntl (2),
735 .BR flock (2),
736 .BR lockf (3),
737 .BR lslocks (8)
738 .P
739 .IR locks.txt ,
740 .IR mandatory\-locking.txt ,
741 and
742 .I dnotify.txt
743 in the Linux kernel source directory
744 .I Documentation/filesystems/
745 (on older kernels, these files are directly under the
746 .I Documentation/
747 directory, and
748 .I mandatory\-locking.txt
749 is called
750 .IR mandatory.txt )