Debian Codegraph @

upstream/debian-unstable/man3/lockf.3

raw
1 '\" t
2 .\" Copyright 1997, Nicolás Lichtmaier <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH lockf 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 lockf \- apply, test or remove a POSIX lock on an open file
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .BI "int lockf(int " fd ", int " op ", off_t " size );
18 .fi
19 .P
20 .RS -4
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
23 .RE
24 .P
25 .BR lockf ():
26 .nf
27 _XOPEN_SOURCE >= 500
28 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
29 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
30 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
31 .fi
32 .SH DESCRIPTION
33 Apply, test, or remove a POSIX lock on a section of an open file.
34 The file is specified by
35 .IR fd ,
36 a file descriptor open for writing, the action by
37 .IR op ,
38 and the section consists of byte positions
39 .IR pos .. pos + size \-1
40 if
41 .I size
42 is positive, and
43 .IR pos \- size .. pos \-1
44 if
45 .I size
46 is negative, where
47 .I pos
48 is the current file position, and if
49 .I size
50 is zero, the section extends from the current file position to
51 infinity, encompassing the present and future end-of-file positions.
52 In all cases, the section may extend past current end-of-file.
53 .P
54 On Linux,
55 .BR lockf ()
56 is just an interface on top of
57 .BR fcntl (2)
58 locking.
59 Many other systems implement
60 .BR lockf ()
61 in this way, but note that POSIX.1 leaves the relationship between
62 .BR lockf ()
63 and
64 .BR fcntl (2)
65 locks unspecified.
66 A portable application should probably avoid mixing calls
67 to these interfaces.
68 .P
69 Valid operations are given below:
70 .TP
71 .B F_LOCK
72 Set an exclusive lock on the specified section of the file.
73 If (part of) this section is already locked, the call
74 blocks until the previous lock is released.
75 If this section overlaps an earlier locked section,
76 both are merged.
77 File locks are released as soon as the process holding the locks
78 closes some file descriptor for the file.
79 A child process does not inherit these locks.
80 .TP
81 .B F_TLOCK
82 Same as
83 .B F_LOCK
84 but the call never blocks and returns an error instead if the file is
85 already locked.
86 .TP
87 .B F_ULOCK
88 Unlock the indicated section of the file.
89 This may cause a locked section to be split into two locked sections.
90 .TP
91 .B F_TEST
92 Test the lock: return 0 if the specified section
93 is unlocked or locked by this process;
94 return \-1, set
95 .I errno
96 to
97 .B EAGAIN
98 .RB ( EACCES
99 on some other systems),
100 if another process holds a lock.
101 .SH RETURN VALUE
102 On success, zero is returned.
103 On error, \-1 is returned, and
104 .I errno
105 is set to indicate the error.
106 .SH ERRORS
107 .TP
108 .BR EACCES " or " EAGAIN
109 The file is locked and
110 .B F_TLOCK
111 or
112 .B F_TEST
113 was specified, or the operation is prohibited because the file has
114 been memory-mapped by another process.
115 .TP
116 .B EBADF
117 .I fd
118 is not an open file descriptor;
119 or
120 .I op
121 is
122 .B F_LOCK
123 or
124 .B F_TLOCK
125 and
126 .I fd
127 is not a writable file descriptor.
128 .TP
129 .B EDEADLK
130 .I op
131 was
132 .B F_LOCK
133 and this lock operation would cause a deadlock.
134 .TP
135 .B EINTR
136 While waiting to acquire a lock, the call was interrupted by
137 delivery of a signal caught by a handler;
138 see
139 .BR signal (7).
140 .TP
141 .B EINVAL
142 An invalid operation was specified in
143 .IR op .
144 .TP
145 .B ENOLCK
146 Too many segment locks open, lock table is full.
147 .SH ATTRIBUTES
148 For an explanation of the terms used in this section, see
149 .BR attributes (7).
150 .TS
151 allbox;
152 lbx lb lb
153 l l l.
154 Interface Attribute Value
155 T{
156 .na
157 .nh
158 .BR lockf ()
159 T} Thread safety MT-Safe
160 .TE
161 .SH STANDARDS
162 POSIX.1-2008.
163 .SH HISTORY
164 POSIX.1-2001, SVr4.
165 .SH SEE ALSO
166 .BR fcntl (2),
167 .BR flock (2)
168 .P
169 .I locks.txt
170 and
171 .I mandatory\-locking.txt
172 in the Linux kernel source directory
173 .I Documentation/filesystems
174 (on older kernels, these files are directly under the
175 .I Documentation
176 directory, and
177 .I mandatory\-locking.txt
178 is called
179 .IR mandatory.txt )