]>
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 | .\" | |
1dd72f9c | 4 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
5 | .\" This is free documentation; you can redistribute it and/or |
6 | .\" modify it under the terms of the GNU General Public License as | |
7 | .\" published by the Free Software Foundation; either version 2 of | |
8 | .\" the License, or (at your option) any later version. | |
9 | .\" | |
10 | .\" The GNU General Public License's references to "object code" | |
11 | .\" and "executables" are to be interpreted as the output of any | |
12 | .\" document formatting or typesetting system, including | |
13 | .\" intermediate and printed output. | |
14 | .\" | |
15 | .\" This manual is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
faede11f MK |
20 | .\" You should have received a copy of the GNU General Public |
21 | .\" License along with this manual; if not, see | |
22 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 23 | .\" %%%LICENSE_END |
faede11f | 24 | .\" |
fea681da MK |
25 | .\" Added section stuff, aeb, 2002-04-22. |
26 | .\" Corrected include file, drepper, 2003-06-15. | |
27 | .\" | |
4b8c67d9 | 28 | .TH LOCKF 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da MK |
29 | .SH NAME |
30 | lockf \- apply, test or remove a POSIX lock on an open file | |
31 | .SH SYNOPSIS | |
32 | .B #include <unistd.h> | |
68e4db0a | 33 | .PP |
ab95e95e | 34 | .BI "int lockf(int " fd ", int " cmd ", off_t " len ); |
68e4db0a | 35 | .PP |
cc4615cc MK |
36 | .in -4n |
37 | Feature Test Macro Requirements for glibc (see | |
38 | .BR feature_test_macros (7)): | |
39 | .in | |
68e4db0a | 40 | .PP |
cc4615cc | 41 | .BR lockf (): |
c29dc444 MK |
42 | .ad l |
43 | .RS 4 | |
6e0869f7 | 44 | _XOPEN_SOURCE\ >=\ 500 |
cf7fa0a1 | 45 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED |
6e0869f7 MK |
46 | || /* Glibc since 2.19: */ _DEFAULT_SOURCE |
47 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE | |
c29dc444 MK |
48 | .RE |
49 | .ad | |
fea681da MK |
50 | .SH DESCRIPTION |
51 | Apply, test or remove a POSIX lock on a section of an open file. | |
52 | The file is specified by | |
53 | .IR fd , | |
54 | a file descriptor open for writing, the action by | |
55 | .IR cmd , | |
56 | and the section consists of byte positions | |
c65433e6 | 57 | .IR pos .. pos + len \-1 |
21cb07dc MK |
58 | if |
59 | .I len | |
60 | is positive, and | |
c65433e6 | 61 | .IR pos \- len .. pos \-1 |
21cb07dc MK |
62 | if |
63 | .I len | |
64 | is negative, where | |
fea681da MK |
65 | .I pos |
66 | is the current file position, and if | |
67 | .I len | |
68 | is zero, the section extends from the current file position to | |
69 | infinity, encompassing the present and future end-of-file positions. | |
70 | In all cases, the section may extend past current end-of-file. | |
dd3568a1 | 71 | .PP |
73e15b46 MK |
72 | On Linux, |
73 | .BR lockf () | |
74 | is just an interface on top of | |
75 | .BR fcntl (2) | |
76 | locking. | |
77 | Many other systems implement | |
78 | .BR lockf () | |
f287e294 | 79 | in this way, but note that POSIX.1 leaves the relationship between |
e511ffb6 | 80 | .BR lockf () |
fea681da | 81 | and |
fb186734 | 82 | .BR fcntl (2) |
73e15b46 MK |
83 | locks unspecified. |
84 | A portable application should probably avoid mixing calls | |
85 | to these interfaces. | |
dd3568a1 | 86 | .PP |
fea681da MK |
87 | Valid operations are given below: |
88 | .TP | |
89 | .B F_LOCK | |
90 | Set an exclusive lock on the specified section of the file. | |
91 | If (part of) this section is already locked, the call | |
92 | blocks until the previous lock is released. | |
93 | If this section overlaps an earlier locked section, | |
94 | both are merged. | |
95 | File locks are released as soon as the process holding the locks | |
c13182ef MK |
96 | closes some file descriptor for the file. |
97 | A child process does not inherit these locks. | |
fea681da MK |
98 | .TP |
99 | .B F_TLOCK | |
100 | Same as | |
101 | .B F_LOCK | |
102 | but the call never blocks and returns an error instead if the file is | |
103 | already locked. | |
104 | .TP | |
105 | .B F_ULOCK | |
106 | Unlock the indicated section of the file. | |
107 | This may cause a locked section to be split into two locked sections. | |
108 | .TP | |
109 | .B F_TEST | |
110 | Test the lock: return 0 if the specified section | |
111 | is unlocked or locked by this process; return \-1, set | |
112 | .I errno | |
113 | to | |
0daa9e92 | 114 | .B EAGAIN |
0febdb5c MK |
115 | .RB ( EACCES |
116 | on some other systems), | |
fea681da | 117 | if another process holds a lock. |
47297adb | 118 | .SH RETURN VALUE |
c13182ef MK |
119 | On success, zero is returned. |
120 | On error, \-1 is returned, and | |
fea681da MK |
121 | .I errno |
122 | is set appropriately. | |
123 | .SH ERRORS | |
124 | .TP | |
0febdb5c | 125 | .BR EACCES " or " EAGAIN |
fea681da MK |
126 | The file is locked and |
127 | .B F_TLOCK | |
128 | or | |
129 | .B F_TEST | |
130 | was specified, or the operation is prohibited because the file has | |
131 | been memory-mapped by another process. | |
132 | .TP | |
133 | .B EBADF | |
134 | .I fd | |
c28d4af6 MK |
135 | is not an open file descriptor; or |
136 | .I cmd | |
137 | is | |
138 | .B F_LOCK | |
139 | or | |
140 | .BR F_TLOCK | |
141 | and | |
142 | .I fd | |
143 | is not a writable file descriptor. | |
fea681da MK |
144 | .TP |
145 | .B EDEADLK | |
146 | The command was | |
02ff975d | 147 | .B F_LOCK |
fea681da MK |
148 | and this lock operation would cause a deadlock. |
149 | .TP | |
150 | .B EINVAL | |
151 | An invalid operation was specified in | |
de76dacf | 152 | .IR cmd . |
fea681da MK |
153 | .TP |
154 | .B ENOLCK | |
155 | Too many segment locks open, lock table is full. | |
3d004cf0 | 156 | .SH ATTRIBUTES |
8931aeb5 MK |
157 | For an explanation of the terms used in this section, see |
158 | .BR attributes (7). | |
159 | .TS | |
160 | allbox; | |
161 | lb lb lb | |
162 | l l l. | |
163 | Interface Attribute Value | |
164 | T{ | |
3d004cf0 | 165 | .BR lockf () |
8931aeb5 MK |
166 | T} Thread safety MT-Safe |
167 | .TE | |
47297adb | 168 | .SH CONFORMING TO |
f287e294 | 169 | POSIX.1-2001, POSIX.1-2008, SVr4. |
47297adb | 170 | .SH SEE ALSO |
fea681da MK |
171 | .BR fcntl (2), |
172 | .BR flock (2) | |
847e0d88 | 173 | .PP |
fea681da MK |
174 | .I locks.txt |
175 | and | |
f6beb9d7 | 176 | .I mandatory-locking.txt |
173fe7e7 | 177 | in the Linux kernel source directory |
4eaa04c5 | 178 | .IR Documentation/filesystems |
173fe7e7 DP |
179 | (on older kernels, these files are directly under the |
180 | .I Documentation | |
73e15b46 MK |
181 | directory, and |
182 | .I mandatory-locking.txt | |
183 | is called | |
173fe7e7 | 184 | .IR mandatory.txt ) |