@@@ much mess, mostly manpages

[mLib] / sys / lock.3.in

diff --git a/sys/lock.3.in b/sys/lock.3.in
new file mode 100644 (file)
index 0000000..04f3cc4
--- /dev/null
+++ b/sys/lock.3.in
@@ -0,0 +1,113 @@
+.\" -*-nroff-*-
+.\"
+.\" Manual for file locking
+.\"
+.\" (c) 1999, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of the mLib utilities library.
+.\"
+.\" mLib is free software: you can redistribute it and/or modify it under
+.\" the terms of the GNU Library General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or (at
+.\" your option) any later version.
+.\"
+.\" mLib is distributed in the hope that it will be useful, but WITHOUT
+.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
+.\" License for more details.
+.\"
+.\" You should have received a copy of the GNU Library General Public
+.\" License along with mLib.  If not, write to the Free Software
+.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
+.\" USA.
+.
+.\"--------------------------------------------------------------------------
+.so ../defs.man \" @@@PRE@@@
+.
+.\"--------------------------------------------------------------------------
+.TH lock 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @lock_file
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+lock \- oversimplified file locking interface
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/lock.h>"
+.PP
+.ta 2n
+.B "enum {"
+.B "   LOCK_UNLOCK = ...,"
+.B "   LOCK_EXCL = ...,"
+.B "   LOCK_NONEXCL = ..."
+.B "};"
+.PP
+.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>
+.
+.\"----- That's all, folks --------------------------------------------------