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