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