Manpages: Move manpages (back?) into the top-level directory.

[mLib] / lock.3

diff --git a/lock.3 b/lock.3
new file mode 100644 (file)
index 0000000..75460b4
--- /dev/null
+++ b/lock.3
@@ -0,0 +1,61 @@
+.\" -*-nroff-*-
+.TH lock 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+lock \- oversimplified file locking interface
+.\" @lock_file
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/lock.h>"
+
+.BI "int lock_file(int " fd ", unsigned " how );
+.fi
+.SH DESCRIPTION
+The
+.B lock_file
+function provides an extremely simplistic interface to POSIX
+.BR fcntl (2)
+locking.  It locks only entire files, not sections of files.  It doesn't
+have a nonblocking `is this file locked?' function.
+.PP
+On entry,
+.I fd
+should be a file descriptor on an open file, and
+.I how
+is a constant which describes how the file is to be locked.  The
+possible values of
+.I how
+are:
+.TP
+.B LOCK_EXCL
+Lock the file exclusively.  Attempts to lock the file exclusively or
+nonexclusively will fail until the file is unlocked.
+.TP
+.B LOCK_NONEXCL
+Lock the file nonexclusively.  Until the file is unlocked, attempts to
+lock it exclusively will fail, but other nonexclusive locks will
+succeed.
+.TP
+.B LOCK_UNLOCK
+Unlocks a locked file.  Any locks afterwards can succeed.
+.PP
+The
+.B lock_file
+function will block if it can't obtain a lock immediately.  It will time
+itself out after a short while (10 seconds in the current
+implementation) if the lock doesn't become available.
+.PP
+If the call succeeds,
+.B lock_file
+returns zero.  On failure, \-1 is returned, and
+.B errno
+is set to an appropriate value.  Most of the error returns are from
+.BR fcntl (2)
+(q.v.).  If the lock operation times out,
+.B errno
+is set to
+.BR EINTR .
+.SH "SEE ALSO"
+.BR fcntl (2),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>