xref: /minix3/lib/libc/gen/lockf.3 (revision f14fb602092e015ff630df58e17c2a9cd57d29b3)
1.\" $NetBSD: lockf.3,v 1.12 2011/10/15 21:35:49 rmind Exp $
2.\"
3.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Klaus Klein and S.P. Zeidler.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd October 15, 2011
31.Dt LOCKF 3
32.Os
33.Sh NAME
34.Nm lockf
35.Nd record locking on files
36.Sh LIBRARY
37.Lb libc
38.Sh SYNOPSIS
39.In unistd.h
40.Ft int
41.Fn lockf "int filedes" "int function" "off_t size"
42.Sh DESCRIPTION
43The
44.Fn lockf
45function allows sections of a file to be locked with advisory-mode locks.
46Calls to
47.Fn lockf
48from other processes which attempt to lock the locked file section will
49either return an error value or block until the section becomes unlocked.
50All the locks for a process are removed when the process terminates.
51.Pp
52The argument
53.Fa filedes
54is an open file descriptor.
55The file descriptor must have been opened either for write-only
56.Dv ( O_WRONLY )
57or read/write
58.Dv ( O_RDWR )
59operation.
60.Pp
61The
62.Fa function
63argument is a control value which specifies the action to be taken.
64The permissible values for
65.Fa function
66are as follows:
67.Pp
68.Bl -tag -width F_ULOCKXX -compact -offset indent
69.It Sy Function
70.Sy Description
71.It Dv F_ULOCK
72unlock locked sections
73.It Dv F_LOCK
74lock a section for exclusive use
75.It Dv F_TLOCK
76test and lock a section for exclusive use
77.It Dv F_TEST
78test a section for locks by other processes
79.El
80.Pp
81.Dv F_ULOCK
82removes locks from a section of the file;
83.Dv F_LOCK
84and
85.Dv F_TLOCK
86both lock a section of a file if the section is available;
87.Dv F_TEST
88detects if a lock by another process is present on the specified section.
89.Pp
90The
91.Fa size
92argument is the number of contiguous bytes to be locked or
93unlocked.
94The section to be locked or unlocked starts at the current
95offset in the file and extends forward for a positive size or backward
96for a negative size (the preceding bytes up to but not including the
97current offset).
98However, it is not permitted to lock a section that
99starts or extends before the beginning of the file.
100If
101.Fa size
102is 0, the section from the current offset through the largest possible
103file offset is locked (that is, from the current offset through the
104present or any future end-of-file).
105.Pp
106The sections locked with
107.Dv F_LOCK
108or
109.Dv F_TLOCK
110may, in whole or in part, contain or be contained by a previously
111locked section for the same process.
112When this occurs, or if adjacent
113locked sections would occur, the sections are combined into a single
114locked section.
115If the request would cause the number of locks to
116exceed a system-imposed limit, the request will fail.
117.Pp
118.Dv F_LOCK
119and
120.Dv F_TLOCK
121requests differ only by the action taken if the section is not
122available.
123.Dv F_LOCK
124blocks the calling process until the section is available.
125.Dv F_TLOCK
126makes the function fail if the section is already locked by another
127process.
128.Pp
129File locks are released on first close by the locking process of any
130file descriptor for the file.
131.Pp
132.Dv F_ULOCK
133requests release (wholly or in part) one or more locked sections
134controlled by the process.
135Locked sections will be unlocked starting
136at the current file offset through
137.Fa size
138bytes or to the end of file if size is 0.
139When all of a locked section
140is not released (that is, when the beginning or end of the area to be
141unlocked falls within a locked section), the remaining portions of
142that section are still locked by the process.
143Releasing the center
144portion of a locked section will cause the remaining locked beginning
145and end portions to become two separate locked sections.
146If the
147request would cause the number of locks in the system to exceed a
148system-imposed limit, the request will fail.
149.Pp
150An
151.Dv F_ULOCK
152request in which size is non-zero and the offset of the last byte of
153the requested section is the maximum value for an object of type
154off_t, when the process has an existing lock in which size is 0 and
155which includes the last byte of the requested section, will be treated
156as a request to unlock from the start of the requested section with a
157size equal to 0.
158Otherwise an
159.Dv F_ULOCK
160request will attempt to unlock only the requested section.
161.Pp
162A potential for deadlock occurs if a process controlling a locked
163region is put to sleep by attempting to lock the locked region of
164another process.
165This implementation detects that sleeping until a
166locked region is unlocked would cause a deadlock and fails with an
167.Er EDEADLK
168error.
169.Pp
170.Fn lockf ,
171.Xr fcntl 2
172and
173.Xr flock 2
174locks may be safely used concurrently.
175.Pp
176Blocking on a section is interrupted by any signal.
177.Sh RETURN VALUES
178If successful, the
179.Fn lockf
180function returns 0.
181Otherwise, it returns \-1, sets
182.Va errno
183to indicate an error, and existing locks are not changed.
184.Sh ERRORS
185.Fn lockf
186will fail if:
187.Bl -tag -width Er
188.It Bq Er EAGAIN
189The argument
190.Fa function
191is
192.Dv F_TLOCK
193or
194.Dv F_TEST
195and the section is already locked by another process.
196.It Bq Er EBADF
197The argument
198.Fa filedes
199is not a valid open file descriptor.
200.Pp
201The argument
202.Fa function
203is
204.Dv F_LOCK
205or
206.Dv F_TLOCK ,
207and
208.Fa filedes
209is not a valid file descriptor open for writing.
210.It Bq Er EDEADLK
211The argument
212.Fa function
213is
214.Dv F_LOCK
215and a deadlock is detected.
216.It Bq Er EINTR
217The argument
218.Fa function
219is F_LOCK
220and
221.Fn lockf
222was interrupted by the delivery of a signal.
223.It Bq Er EINVAL
224The argument
225.Fa function
226is not one of
227.Dv F_ULOCK ,
228.Dv F_LOCK ,
229.Dv F_TLOCK
230or
231.Dv F_TEST .
232.Pp
233The argument
234.Fa filedes
235refers to a file that does not support locking.
236.It Bq Er ENOLCK
237The argument
238.Fa function
239is
240.Dv F_ULOCK ,
241.Dv F_LOCK
242or
243.Dv F_TLOCK ,
244and satisfying the lock or unlock request would result in the number
245of locked regions in the system exceeding a system-imposed limit.
246.El
247.Sh SEE ALSO
248.Xr fcntl 2 ,
249.Xr flock 2 ,
250.Xr flockfile 3
251.Sh STANDARDS
252The
253.Fn lockf
254function conforms to
255.St -xpg4.2
256and
257.St -p1003.1-2008 .
258.Sh HISTORY
259The
260.Fn lockf
261function first appeared in
262.Fx 1.4 .
263