Debian Codegraph @

upstream/debian-trixie/man3/lockf.3

raw
1 '\" t
2 .\" Copyright 1997 Nicolás Lichtmaier <[email protected]>
3 .\" Created Thu Aug 7 00:44:00 ART 1997
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .\" Added section stuff, aeb, 2002-04-22.
8 .\" Corrected include file, drepper, 2003-06-15.
9 .\"
10 .TH lockf 3 2024-05-02 "Linux man-pages 6.9.1"
11 .SH NAME
12 lockf \- apply, test or remove a POSIX lock on an open file
13 .SH LIBRARY
14 Standard C library
15 .RI ( libc ", " \-lc )
16 .SH SYNOPSIS
17 .nf
18 .B #include <unistd.h>
19 .P
20 .BI "int lockf(int " fd ", int " op ", off_t " len );
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR lockf ():
29 .nf
30 _XOPEN_SOURCE >= 500
31 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
32 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
33 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
34 .fi
35 .SH DESCRIPTION
36 Apply, test, or remove a POSIX lock on a section of an open file.
37 The file is specified by
38 .IR fd ,
39 a file descriptor open for writing, the action by
40 .IR op ,
41 and the section consists of byte positions
42 .IR pos .. pos + len \-1
43 if
44 .I len
45 is positive, and
46 .IR pos \- len .. pos \-1
47 if
48 .I len
49 is negative, where
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.
56 .P
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 ()
64 in this way, but note that POSIX.1 leaves the relationship between
65 .BR lockf ()
66 and
67 .BR fcntl (2)
68 locks unspecified.
69 A portable application should probably avoid mixing calls
70 to these interfaces.
71 .P
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
81 closes some file descriptor for the file.
82 A child process does not inherit these locks.
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
99 .B EAGAIN
100 .RB ( EACCES
101 on some other systems),
102 if another process holds a lock.
103 .SH RETURN VALUE
104 On success, zero is returned.
105 On error, \-1 is returned, and
106 .I errno
107 is set to indicate the error.
108 .SH ERRORS
109 .TP
110 .BR EACCES " or " EAGAIN
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
120 is not an open file descriptor; or
121 .I op
122 is
123 .B F_LOCK
124 or
125 .B F_TLOCK
126 and
127 .I fd
128 is not a writable file descriptor.
129 .TP
130 .B EDEADLK
131 .I op
132 was
133 .B F_LOCK
134 and this lock operation would cause a deadlock.
135 .TP
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
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 )