copyediting for Usenix manuals

[unix-history] / usr / src / lib / libc / sys / flock.2

diff --git a/usr/src/lib/libc/sys/flock.2 b/usr/src/lib/libc/sys/flock.2
index b6e5011..133abed 100644 (file)
--- a/usr/src/lib/libc/sys/flock.2
+++ b/usr/src/lib/libc/sys/flock.2
@@ -1,97 +1,119 @@
-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1983, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\"    @(#)flock.2     6.2 (Berkeley) %G%
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.TH FLOCK 2 ""
-.UC 5
-.SH NAME
-flock \- apply or remove an advisory lock on an open file
-.SH SYNOPSIS
-.nf
-.ft B
-#include <sys/file.h>
-.PP
-.ft B
-.DT
-#define        LOCK_SH 1       /* shared lock */
-#define        LOCK_EX 2       /* exclusive lock */
-#define        LOCK_NB 4       /* don't block when locking */
-#define        LOCK_UN 8       /* unlock */
-.PP
-.ft B
-flock(fd, operation)
-int fd, operation;
-.fi
-.SH DESCRIPTION
-.I Flock
+.\"     @(#)flock.2    8.2 (Berkeley) %G%
+.\"
+.Dd 
+.Dt FLOCK 2
+.Os BSD 4.2
+.Sh NAME
+.Nm flock
+.Nd "apply or remove an advisory lock on an open file"
+.Sh SYNOPSIS
+.Fd #include <sys/file.h>
+.Fd #define    LOCK_SH 1       /* shared lock */
+.Fd #define    LOCK_EX 2       /* exclusive lock */
+.Fd #define    LOCK_NB 4       /* don't block when locking */
+.Fd #define    LOCK_UN 8       /* unlock */
+.Ft int
+.Fn flock "int fd" "int operation"
+.Sh DESCRIPTION
+.Fn Flock

 applies or removes an
 applies or removes an

-.I advisory
+.Em advisory

 lock on the file associated with the file descriptor
 lock on the file associated with the file descriptor

-.IR fd .
+.Fa fd .

 A lock is applied by specifying an
 A lock is applied by specifying an

-.I operation
-parameter that is the inclusive or of
-LOCK_SH or LOCK_EX and, possibly, LOCK_NB.  To unlock
+.Fa operation
+parameter that is one of
+.Dv LOCK_SH
+or
+.Dv LOCK_EX
+with the optional addition of
+.Dv LOCK_NB .
+To unlock

 an existing lock
 an existing lock

-.I operation
-should be LOCK_UN.
-.PP
+.Dv operation
+should be
+.Dv LOCK_UN .
+.Pp

 Advisory locks allow cooperating processes to perform
 consistent operations on files, but do not guarantee
 Advisory locks allow cooperating processes to perform
 consistent operations on files, but do not guarantee

-consistency (i.e. processes may still access files
+consistency (i.e., processes may still access files

 without using advisory locks possibly resulting in
 inconsistencies).
 without using advisory locks possibly resulting in
 inconsistencies).

-.PP
+.Pp

 The locking mechanism allows two types of locks:
 The locking mechanism allows two types of locks:

-.I shared
+.Em shared

 locks and
 locks and

-.I exclusive
+.Em exclusive

 locks.
 At any time multiple shared locks may be applied to a file,
 but at no time are multiple exclusive, or both shared and exclusive,
 locks allowed simultaneously on a file.  
 locks.
 At any time multiple shared locks may be applied to a file,
 but at no time are multiple exclusive, or both shared and exclusive,
 locks allowed simultaneously on a file.  

-.PP
+.Pp

 A shared lock may be
 A shared lock may be

-.I upgraded
+.Em upgraded

 to an exclusive lock, and vice versa, simply by specifying
 the appropriate lock type; this results in the previous
 lock being released and the new lock applied (possibly
 after other processes have gained and released the lock).
 to an exclusive lock, and vice versa, simply by specifying
 the appropriate lock type; this results in the previous
 lock being released and the new lock applied (possibly
 after other processes have gained and released the lock).

-.PP
+.Pp

 Requesting a lock on an object that is already locked
 Requesting a lock on an object that is already locked

-normally causes the caller to blocked until the lock may be
-acquired.  If LOCK_NB is included in
-.IR operation ,
+normally causes the caller to be blocked until the lock may be
+acquired.  If
+.Dv LOCK_NB
+is included in
+.Fa operation ,

 then this will not happen; instead the call will fail and
 then this will not happen; instead the call will fail and

-the error EWOULDBLOCK will be returned.
-.SH NOTES
+the error
+.Er EWOULDBLOCK
+will be returned.
+.Sh NOTES

 Locks are on files, not file descriptors.  That is, file descriptors
 duplicated through
 Locks are on files, not file descriptors.  That is, file descriptors
 duplicated through

-.IR dup (2)
+.Xr dup 2

 or
 or

-.IR fork (2)
+.Xr fork 2

 do not result in multiple instances of a lock, but rather multiple
 references to a single lock.  If a process holding a lock on a file
 forks and the child explicitly unlocks the file, the parent will
 lose its lock.
 do not result in multiple instances of a lock, but rather multiple
 references to a single lock.  If a process holding a lock on a file
 forks and the child explicitly unlocks the file, the parent will
 lose its lock.

-.PP
+.Pp

 Processes blocked awaiting a lock may be awakened by signals.
 Processes blocked awaiting a lock may be awakened by signals.

-.SH "RETURN VALUE
+.Sh RETURN VALUES

 Zero is returned if the operation was successful;
 Zero is returned if the operation was successful;

-on an error a \-1 is returned and an error code is left in
-the global location \fIerrno\fP.
-.SH "ERRORS
-The \fIflock\fP call fails if:
-.TP 20
-[EWOULDBLOCK]
-The file is locked and the LOCK_NB option was specified.
-.TP 20
-[EBADF]
-The argument \fIfd\fP is an invalid descriptor.
-.TP 20
-[EINVAL]
-The argument \fIfd\fP refers to an object other than a file.
-.SH "SEE ALSO"
-open(2), close(2), dup(2), execve(2), fork(2)
+on an error a -1 is returned and an error code is left in
+the global location
+.Va errno .
+.Sh ERRORS
+The
+.Fn flock
+call fails if:
+.Bl -tag -width EWOULDBLOCKAA
+.It Bq Er EWOULDBLOCK
+The file is locked and the
+.Dv LOCK_NB
+option was specified.
+.It Bq Er EBADF
+The argument
+.Fa fd
+is an invalid descriptor.
+.It Bq Er EINVAL
+The argument
+.Fa fd
+refers to an object other than a file.
+.El
+.Sh SEE ALSO
+.Xr open 2 ,
+.Xr close 2 ,
+.Xr dup 2 ,
+.Xr execve 2 ,
+.Xr fork 2
+.Sh HISTORY
+The
+.Nm
+function call appeared in
+.Bx 4.2 .