-.\" $NetBSD: lockf.3,v 1.2 1998/02/05 18:47:28 perry Exp $
+.\" $NetBSD: lockf.3,v 1.10 2008/04/30 13:10:50 martin Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the NetBSD
-.\" Foundation, Inc. and its contributors.
-.\" 4. Neither the name of The NetBSD Foundation nor the names of its
-.\" contributors may be used to endorse or promote products derived
-.\" from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/lib/libc/gen/lockf.3,v 1.10 2001/10/01 16:08:51 ru Exp $
+.\" $FreeBSD: src/lib/libc/gen/lockf.3,v 1.14 2009/03/04 01:01:26 delphij Exp $
.\"
.Dd December 19, 1997
.Dt LOCKF 3
.Sh SYNOPSIS
.In unistd.h
.Ft int
-.Fn lockf "int filedes" "int function" "off_t size"
+.Fn lockf "int fildes" "int function" "off_t size"
.Sh DESCRIPTION
The
.Fn lockf
.Fn lockf
from other processes which attempt to lock the locked file section will
either return an error value or block until the section becomes unlocked.
-All the locks for a process are removed when the process terminates.
+All of the locks for a process are removed when the process terminates.
.Pp
The argument
-.Fa filedes
+.Fa fildes
is an open file descriptor.
The file descriptor must have been opened either for write-only
.Dv ( O_WRONLY )
The section to be locked or unlocked starts at the current
offset in the file and extends forward for a positive size or backward
for a negative size (the preceding bytes up to but not including the
-current offset). However, it is not permitted to lock a section that
+current offset).
+However, it is not permitted to lock a section that
starts or extends before the beginning of the file.
If
.Fa size
Locked sections will be unlocked starting
at the current file offset through
.Fa size
-bytes or to the end of file if size is 0. When all of a locked section
+bytes or to the end of file if size is 0.
+When all of a locked section
is not released (that is, when the beginning or end of the area to be
unlocked falls within a locked section), the remaining portions of
that section are still locked by the process.
off_t, when the process has an existing lock in which size is 0 and
which includes the last byte of the requested section, will be treated
as a request to unlock from the start of the requested section with a
-size equal to 0. Otherwise an
+size equal to 0.
+Otherwise an
.Dv F_ULOCK
request will attempt to unlock only the requested section.
.Pp
A potential for deadlock occurs if a process controlling a locked
region is put to sleep by attempting to lock the locked region of
-another process. This implementation detects that sleeping until a
+another process.
+This implementation detects that sleeping until a
locked region is unlocked would cause a deadlock and fails with an
.Er EDEADLK
error.
.Pp
+The
.Fn lockf ,
-.Xr fcntl 2
+.Xr fcntl 2 ,
and
.Xr flock 2
-locks may be safely used concurrently.
+locks are compatible.
+Processes using different locking interfaces can cooperate
+over the same file safely.
+However, only one of such interfaces should be used within
+the same process.
+If a file is locked by a process through
+.Xr flock 2 ,
+any record within the file will be seen as locked
+from the viewpoint of another process using
+.Xr fcntl 2
+or
+.Fn lockf ,
+and vice versa.
.Pp
Blocking on a section is interrupted by any signal.
.Sh RETURN VALUES
.Rv -std lockf
In the case of a failure, existing locks are not changed.
.Sh ERRORS
+The
.Fn lockf
+function
will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
and the section is already locked by another process.
.It Bq Er EBADF
The argument
-.Fa filedes
+.Fa fildes
is not a valid open file descriptor.
.Pp
The argument
or
.Dv F_TLOCK ,
and
-.Fa filedes
+.Fa fildes
is not a valid file descriptor open for writing.
.It Bq Er EDEADLK
The argument
The argument
.Fa function
is not one of
-.Dv F_ULOCK ,
.Dv F_LOCK ,
-.Dv F_TLOCK
+.Dv F_TEST ,
+.Dv F_TLOCK ,
or
-.Dv F_TEST .
+.Dv F_ULOCK .
.Pp
The argument
-.Fa filedes
-refers to a file that does not support locking.
+.Fa fildes
+refers to a file that does not support advisory locking.
.It Bq Er ENOLCK
The argument
.Fa function
is
-.Dv F_ULOCK ,
-.Dv F_LOCK
-or
+.Dv F_LOCK ,
.Dv F_TLOCK ,
+or
+.Dv F_ULOCK
and satisfying the lock or unlock request would result in the number
of locked regions in the system exceeding a system-imposed limit.
+.It Bq Er EOPNOTSUPP
+The argument
+.Fa fildes
+refers to a socket; these do not support advisory locking.
.El
.Sh SEE ALSO
.Xr fcntl 2 ,
projects / apple / libc.git / blobdiff