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