]>
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 | .\" | |
460495ca | 28 | .TH LOCKF 3 2015-08-08 "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> | |
33 | .sp | |
ab95e95e | 34 | .BI "int lockf(int " fd ", int " cmd ", off_t " len ); |
cc4615cc MK |
35 | .sp |
36 | .in -4n | |
37 | Feature Test Macro Requirements for glibc (see | |
38 | .BR feature_test_macros (7)): | |
39 | .in | |
40 | .sp | |
41 | .BR lockf (): | |
c29dc444 MK |
42 | .ad l |
43 | .RS 4 | |
44 | _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 || | |
45 | _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
46 | .RE | |
47 | .ad | |
fea681da MK |
48 | .SH DESCRIPTION |
49 | Apply, test or remove a POSIX lock on a section of an open file. | |
50 | The file is specified by | |
51 | .IR fd , | |
52 | a file descriptor open for writing, the action by | |
53 | .IR cmd , | |
54 | and the section consists of byte positions | |
c65433e6 | 55 | .IR pos .. pos + len \-1 |
21cb07dc MK |
56 | if |
57 | .I len | |
58 | is positive, and | |
c65433e6 | 59 | .IR pos \- len .. pos \-1 |
21cb07dc MK |
60 | if |
61 | .I len | |
62 | is negative, where | |
fea681da MK |
63 | .I pos |
64 | is the current file position, and if | |
65 | .I len | |
66 | is zero, the section extends from the current file position to | |
67 | infinity, encompassing the present and future end-of-file positions. | |
68 | In all cases, the section may extend past current end-of-file. | |
69 | .LP | |
73e15b46 MK |
70 | On Linux, |
71 | .BR lockf () | |
72 | is just an interface on top of | |
73 | .BR fcntl (2) | |
74 | locking. | |
75 | Many other systems implement | |
76 | .BR lockf () | |
f287e294 | 77 | in this way, but note that POSIX.1 leaves the relationship between |
e511ffb6 | 78 | .BR lockf () |
fea681da | 79 | and |
fb186734 | 80 | .BR fcntl (2) |
73e15b46 MK |
81 | locks unspecified. |
82 | A portable application should probably avoid mixing calls | |
83 | to these interfaces. | |
fea681da MK |
84 | .LP |
85 | Valid operations are given below: | |
86 | .TP | |
87 | .B F_LOCK | |
88 | Set an exclusive lock on the specified section of the file. | |
89 | If (part of) this section is already locked, the call | |
90 | blocks until the previous lock is released. | |
91 | If this section overlaps an earlier locked section, | |
92 | both are merged. | |
93 | File locks are released as soon as the process holding the locks | |
c13182ef MK |
94 | closes some file descriptor for the file. |
95 | A child process does not inherit these locks. | |
fea681da MK |
96 | .TP |
97 | .B F_TLOCK | |
98 | Same as | |
99 | .B F_LOCK | |
100 | but the call never blocks and returns an error instead if the file is | |
101 | already locked. | |
102 | .TP | |
103 | .B F_ULOCK | |
104 | Unlock the indicated section of the file. | |
105 | This may cause a locked section to be split into two locked sections. | |
106 | .TP | |
107 | .B F_TEST | |
108 | Test the lock: return 0 if the specified section | |
109 | is unlocked or locked by this process; return \-1, set | |
110 | .I errno | |
111 | to | |
0daa9e92 | 112 | .B EAGAIN |
0febdb5c MK |
113 | .RB ( EACCES |
114 | on some other systems), | |
fea681da | 115 | if another process holds a lock. |
47297adb | 116 | .SH RETURN VALUE |
c13182ef MK |
117 | On success, zero is returned. |
118 | On error, \-1 is returned, and | |
fea681da MK |
119 | .I errno |
120 | is set appropriately. | |
121 | .SH ERRORS | |
122 | .TP | |
0febdb5c | 123 | .BR EACCES " or " EAGAIN |
fea681da MK |
124 | The file is locked and |
125 | .B F_TLOCK | |
126 | or | |
127 | .B F_TEST | |
128 | was specified, or the operation is prohibited because the file has | |
129 | been memory-mapped by another process. | |
130 | .TP | |
131 | .B EBADF | |
132 | .I fd | |
c28d4af6 MK |
133 | is not an open file descriptor; or |
134 | .I cmd | |
135 | is | |
136 | .B F_LOCK | |
137 | or | |
138 | .BR F_TLOCK | |
139 | and | |
140 | .I fd | |
141 | is not a writable file descriptor. | |
fea681da MK |
142 | .TP |
143 | .B EDEADLK | |
144 | The command was | |
02ff975d | 145 | .B F_LOCK |
fea681da MK |
146 | and this lock operation would cause a deadlock. |
147 | .TP | |
148 | .B EINVAL | |
149 | An invalid operation was specified in | |
de76dacf | 150 | .IR cmd . |
fea681da MK |
151 | .TP |
152 | .B ENOLCK | |
153 | Too many segment locks open, lock table is full. | |
3d004cf0 | 154 | .SH ATTRIBUTES |
8931aeb5 MK |
155 | For an explanation of the terms used in this section, see |
156 | .BR attributes (7). | |
157 | .TS | |
158 | allbox; | |
159 | lb lb lb | |
160 | l l l. | |
161 | Interface Attribute Value | |
162 | T{ | |
3d004cf0 | 163 | .BR lockf () |
8931aeb5 MK |
164 | T} Thread safety MT-Safe |
165 | .TE | |
47297adb | 166 | .SH CONFORMING TO |
f287e294 | 167 | POSIX.1-2001, POSIX.1-2008, SVr4. |
47297adb | 168 | .SH SEE ALSO |
fea681da MK |
169 | .BR fcntl (2), |
170 | .BR flock (2) | |
173fe7e7 | 171 | |
fea681da MK |
172 | .I locks.txt |
173 | and | |
f6beb9d7 | 174 | .I mandatory-locking.txt |
173fe7e7 | 175 | in the Linux kernel source directory |
4eaa04c5 | 176 | .IR Documentation/filesystems |
173fe7e7 DP |
177 | (on older kernels, these files are directly under the |
178 | .I Documentation | |
73e15b46 MK |
179 | directory, and |
180 | .I mandatory-locking.txt | |
181 | is called | |
173fe7e7 | 182 | .IR mandatory.txt ) |