Libc-498.1.1.tar.gz

[apple/libc.git] / gen / lockf.3

diff --git a/gen/lockf.3 b/gen/lockf.3
index 83f78180b2b135c2b27f04e4ddbafb848c5ce0f1..f4cecd116dc4fe150b4e356487b977fa21f5253c 100644 (file)
--- a/gen/lockf.3
+++ b/gen/lockf.3
@@ -34,7 +34,7 @@
 .\" 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.13 2004/07/02 23:52:10 ru Exp $
 .\"
 .Dd December 19, 1997
 .Dt LOCKF 3
@@ -47,7 +47,7 @@
 .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
@@ -56,10 +56,10 @@ Calls to
 .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 )
@@ -102,7 +102,8 @@ unlocked.
 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
@@ -142,7 +143,8 @@ controlled by the process.
 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.
@@ -160,29 +162,46 @@ the requested section is the maximum value for an object of type
 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
@@ -195,7 +214,7 @@ or
 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
@@ -205,7 +224,7 @@ is
 or
 .Dv F_TLOCK ,
 and
-.Fa filedes
+.Fa fildes
 is not a valid file descriptor open for writing.
 .It Bq Er EDEADLK
 The argument
@@ -224,25 +243,29 @@ was interrupted by the delivery of a signal.
 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 ,