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