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.\"
| 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: head/lib/libc/gen/lockf.3 129369 2004-05-17 23:09:10Z yar $
| 37.\" $FreeBSD: head/lib/libc/gen/lockf.3 131504 2004-07-02 23:52:20Z ru $
|
38.\"
39.Dd December 19, 1997
40.Dt LOCKF 3
41.Os
42.Sh NAME
43.Nm lockf
44.Nd record locking on files
45.Sh LIBRARY
46.Lb libc
47.Sh SYNOPSIS
48.In unistd.h
49.Ft int
50.Fn lockf "int filedes" "int function" "off_t size"
51.Sh DESCRIPTION
52The
53.Fn lockf
54function allows sections of a file to be locked with advisory-mode locks.
55Calls to
56.Fn lockf
57from other processes which attempt to lock the locked file section will
58either return an error value or block until the section becomes unlocked.
59All the locks for a process are removed when the process terminates.
60.Pp
61The argument
62.Fa filedes
63is an open file descriptor.
64The file descriptor must have been opened either for write-only
65.Dv ( O_WRONLY )
66or read/write
67.Dv ( O_RDWR )
68operation.
69.Pp
70The
71.Fa function
72argument is a control value which specifies the action to be taken.
73The permissible values for
74.Fa function
75are as follows:
76.Bl -tag -width F_ULOCKXX -compact -offset indent
77.It Sy Function
78.Sy Description
79.It Dv F_ULOCK
80unlock locked sections
81.It Dv F_LOCK
82lock a section for exclusive use
83.It Dv F_TLOCK
84test and lock a section for exclusive use
85.It Dv F_TEST
86test a section for locks by other processes
87.El
88.Pp
89.Dv F_ULOCK
90removes locks from a section of the file;
91.Dv F_LOCK
92and
93.Dv F_TLOCK
94both lock a section of a file if the section is available;
95.Dv F_TEST
96detects if a lock by another process is present on the specified section.
97.Pp
98The
99.Fa size
100argument is the number of contiguous bytes to be locked or
101unlocked.
102The section to be locked or unlocked starts at the current
103offset in the file and extends forward for a positive size or backward
104for a negative size (the preceding bytes up to but not including the
| 38.\"
39.Dd December 19, 1997
40.Dt LOCKF 3
41.Os
42.Sh NAME
43.Nm lockf
44.Nd record locking on files
45.Sh LIBRARY
46.Lb libc
47.Sh SYNOPSIS
48.In unistd.h
49.Ft int
50.Fn lockf "int filedes" "int function" "off_t size"
51.Sh DESCRIPTION
52The
53.Fn lockf
54function allows sections of a file to be locked with advisory-mode locks.
55Calls to
56.Fn lockf
57from other processes which attempt to lock the locked file section will
58either return an error value or block until the section becomes unlocked.
59All the locks for a process are removed when the process terminates.
60.Pp
61The argument
62.Fa filedes
63is an open file descriptor.
64The file descriptor must have been opened either for write-only
65.Dv ( O_WRONLY )
66or read/write
67.Dv ( O_RDWR )
68operation.
69.Pp
70The
71.Fa function
72argument is a control value which specifies the action to be taken.
73The permissible values for
74.Fa function
75are as follows:
76.Bl -tag -width F_ULOCKXX -compact -offset indent
77.It Sy Function
78.Sy Description
79.It Dv F_ULOCK
80unlock locked sections
81.It Dv F_LOCK
82lock a section for exclusive use
83.It Dv F_TLOCK
84test and lock a section for exclusive use
85.It Dv F_TEST
86test a section for locks by other processes
87.El
88.Pp
89.Dv F_ULOCK
90removes locks from a section of the file;
91.Dv F_LOCK
92and
93.Dv F_TLOCK
94both lock a section of a file if the section is available;
95.Dv F_TEST
96detects if a lock by another process is present on the specified section.
97.Pp
98The
99.Fa size
100argument is the number of contiguous bytes to be locked or
101unlocked.
102The section to be locked or unlocked starts at the current
103offset in the file and extends forward for a positive size or backward
104for a negative size (the preceding bytes up to but not including the
|
105current offset). However, it is not permitted to lock a section that
| 105current offset).
106However, it is not permitted to lock a section that
|
106starts or extends before the beginning of the file.
107If
108.Fa size
109is 0, the section from the current offset through the largest possible
110file offset is locked (that is, from the current offset through the
111present or any future end-of-file).
112.Pp
113The sections locked with
114.Dv F_LOCK
115or
116.Dv F_TLOCK
117may, in whole or in part, contain or be contained by a previously
118locked section for the same process.
119When this occurs, or if adjacent
120locked sections would occur, the sections are combined into a single
121locked section.
122If the request would cause the number of locks to
123exceed a system-imposed limit, the request will fail.
124.Pp
125.Dv F_LOCK
126and
127.Dv F_TLOCK
128requests differ only by the action taken if the section is not
129available.
130.Dv F_LOCK
131blocks the calling process until the section is available.
132.Dv F_TLOCK
133makes the function fail if the section is already locked by another
134process.
135.Pp
136File locks are released on first close by the locking process of any
137file descriptor for the file.
138.Pp
139.Dv F_ULOCK
140requests release (wholly or in part) one or more locked sections
141controlled by the process.
142Locked sections will be unlocked starting
143at the current file offset through
144.Fa size
| 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
|
145bytes or to the end of file if size is 0. When all of a locked section
| 146bytes or to the end of file if size is 0.
147When all of a locked section
|
146is not released (that is, when the beginning or end of the area to be
147unlocked falls within a locked section), the remaining portions of
148that section are still locked by the process.
149Releasing the center
150portion of a locked section will cause the remaining locked beginning
151and end portions to become two separate locked sections.
152If the
153request would cause the number of locks in the system to exceed a
154system-imposed limit, the request will fail.
155.Pp
156An
157.Dv F_ULOCK
158request in which size is non-zero and the offset of the last byte of
159the requested section is the maximum value for an object of type
160off_t, when the process has an existing lock in which size is 0 and
161which includes the last byte of the requested section, will be treated
162as a request to unlock from the start of the requested section with a
| 148is not released (that is, when the beginning or end of the area to be
149unlocked falls within a locked section), the remaining portions of
150that section are still locked by the process.
151Releasing the center
152portion of a locked section will cause the remaining locked beginning
153and end portions to become two separate locked sections.
154If the
155request would cause the number of locks in the system to exceed a
156system-imposed limit, the request will fail.
157.Pp
158An
159.Dv F_ULOCK
160request in which size is non-zero and the offset of the last byte of
161the requested section is the maximum value for an object of type
162off_t, when the process has an existing lock in which size is 0 and
163which includes the last byte of the requested section, will be treated
164as a request to unlock from the start of the requested section with a
|
163size equal to 0. Otherwise an
| 165size equal to 0.
166Otherwise an
|
164.Dv F_ULOCK
165request will attempt to unlock only the requested section.
166.Pp
167A potential for deadlock occurs if a process controlling a locked
168region is put to sleep by attempting to lock the locked region of
| 167.Dv F_ULOCK
168request will attempt to unlock only the requested section.
169.Pp
170A potential for deadlock occurs if a process controlling a locked
171region is put to sleep by attempting to lock the locked region of
|
169another process. This implementation detects that sleeping until a
| 172another process.
173This implementation detects that sleeping until a
|
170locked region is unlocked would cause a deadlock and fails with an
171.Er EDEADLK
172error.
173.Pp
174The
175.Fn lockf ,
176.Xr fcntl 2 ,
177and
178.Xr flock 2
179locks are compatible.
180Processes using different locking interfaces can cooperate
181over the same file safely.
182However, only one of such interfaces should be used within
183the same process.
184If a file is locked by a process through
185.Xr flock 2 ,
186any record within the file will be seen as locked
187from the viewpoint of another process using
188.Xr fcntl 2
189or
190.Fn lockf ,
191and vice versa.
192.Pp
193Blocking on a section is interrupted by any signal.
194.Sh RETURN VALUES
195.Rv -std lockf
196In the case of a failure, existing locks are not changed.
197.Sh ERRORS
198The
199.Fn lockf
200function
201will fail if:
202.Bl -tag -width Er
203.It Bq Er EAGAIN
204The argument
205.Fa function
206is
207.Dv F_TLOCK
208or
209.Dv F_TEST
210and the section is already locked by another process.
211.It Bq Er EBADF
212The argument
213.Fa filedes
214is not a valid open file descriptor.
215.Pp
216The argument
217.Fa function
218is
219.Dv F_LOCK
220or
221.Dv F_TLOCK ,
222and
223.Fa filedes
224is not a valid file descriptor open for writing.
225.It Bq Er EDEADLK
226The argument
227.Fa function
228is
229.Dv F_LOCK
230and a deadlock is detected.
231.It Bq Er EINTR
232The argument
233.Fa function
234is F_LOCK
235and
236.Fn lockf
237was interrupted by the delivery of a signal.
238.It Bq Er EINVAL
239The argument
240.Fa function
241is not one of
242.Dv F_ULOCK ,
243.Dv F_LOCK ,
244.Dv F_TLOCK
245or
246.Dv F_TEST .
247.Pp
248The argument
249.Fa filedes
250refers to a file that does not support locking.
251.It Bq Er ENOLCK
252The argument
253.Fa function
254is
255.Dv F_ULOCK ,
256.Dv F_LOCK
257or
258.Dv F_TLOCK ,
259and satisfying the lock or unlock request would result in the number
260of locked regions in the system exceeding a system-imposed limit.
261.El
262.Sh SEE ALSO
263.Xr fcntl 2 ,
264.Xr flock 2
265.Sh STANDARDS
266The
267.Fn lockf
268function conforms to
269.St -xpg4.2 .
| 174locked region is unlocked would cause a deadlock and fails with an
175.Er EDEADLK
176error.
177.Pp
178The
179.Fn lockf ,
180.Xr fcntl 2 ,
181and
182.Xr flock 2
183locks are compatible.
184Processes using different locking interfaces can cooperate
185over the same file safely.
186However, only one of such interfaces should be used within
187the same process.
188If a file is locked by a process through
189.Xr flock 2 ,
190any record within the file will be seen as locked
191from the viewpoint of another process using
192.Xr fcntl 2
193or
194.Fn lockf ,
195and vice versa.
196.Pp
197Blocking on a section is interrupted by any signal.
198.Sh RETURN VALUES
199.Rv -std lockf
200In the case of a failure, existing locks are not changed.
201.Sh ERRORS
202The
203.Fn lockf
204function
205will fail if:
206.Bl -tag -width Er
207.It Bq Er EAGAIN
208The argument
209.Fa function
210is
211.Dv F_TLOCK
212or
213.Dv F_TEST
214and the section is already locked by another process.
215.It Bq Er EBADF
216The argument
217.Fa filedes
218is not a valid open file descriptor.
219.Pp
220The argument
221.Fa function
222is
223.Dv F_LOCK
224or
225.Dv F_TLOCK ,
226and
227.Fa filedes
228is not a valid file descriptor open for writing.
229.It Bq Er EDEADLK
230The argument
231.Fa function
232is
233.Dv F_LOCK
234and a deadlock is detected.
235.It Bq Er EINTR
236The argument
237.Fa function
238is F_LOCK
239and
240.Fn lockf
241was interrupted by the delivery of a signal.
242.It Bq Er EINVAL
243The argument
244.Fa function
245is not one of
246.Dv F_ULOCK ,
247.Dv F_LOCK ,
248.Dv F_TLOCK
249or
250.Dv F_TEST .
251.Pp
252The argument
253.Fa filedes
254refers to a file that does not support locking.
255.It Bq Er ENOLCK
256The argument
257.Fa function
258is
259.Dv F_ULOCK ,
260.Dv F_LOCK
261or
262.Dv F_TLOCK ,
263and satisfying the lock or unlock request would result in the number
264of locked regions in the system exceeding a system-imposed limit.
265.El
266.Sh SEE ALSO
267.Xr fcntl 2 ,
268.Xr flock 2
269.Sh STANDARDS
270The
271.Fn lockf
272function conforms to
273.St -xpg4.2 .
|