.\" -*-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 --------------------------------------------------