1 files changed, 108 insertions, 0 deletions
diff --git a/lib/libutil/uucplock.3 b/lib/libutil/uucplock.3
new file mode 100644
index 0000000..a8b5df8
--- /dev/null
+++ b/lib/libutil/uucplock.3
@@ -0,0 +1,108 @@
+.\" 
+.\" Copyright (c) 1996 Brian Somers <brian@awfulhak.demon.co.uk>
+.\" 
+.\" All rights reserved.
+.\" 
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\" 
+.\" $Id$
+.\" "
+.Dd March 30, 1997
+.Os
+.Dt uucplock 3
+.Sh NAME
+.Nm uu_lock , 
+.Nm uu_unlock
+.Nd acquire and release control of a serial device
+.Sh SYNOPSIS
+.Fd #include <libutil.h>
+.Ft int
+.Fn uu_lock "char *ttyname"
+.Ft int
+.Fn uu_unlock "char *ttyname"
+.Pp
+Link with
+.Va -lutil
+on the
+.Xr cc 1
+command line.
+.Sh DESCRIPTION
+The
+.Fn uu_lock
+function attempts to create a lock file called
+.Dq /var/spool/lock/LCK..
+with a suffix given by the passed
+.Fa ttyname .
+If the file already exists, it is expected to contain the process
+id of the locking program.
+.Pp
+If the file does not already exist, or the owning process given by
+the process id found in the lock file is no longer running,
+.Fn uu_lock
+will write its own process id into the file and return success.
+.Pp
+.Fn uu_unlock
+removes the lockfile created by
+.Fn uu_lock
+for the given
+.Fa ttyname .
+Care should be taken that
+.Fn uu_lock
+was successful before calling
+.Fn uu_unlock .
+.Sh RETURN VALUES
+Both
+.Fn uu_lock
+and
+.Fn uu_unlock
+return 0 on success and -1 on failure.
+.Sh ERRORS
+On failure,
+.Fn uu_lock
+will log any unexpected errors using
+.Xr syslog 2 .
+If the lock already exists and contains the process id of a running
+process,
+.Fn uu_lock
+will silently fail.  The value of
+.Dv errno
+can not be used to determine the cause of failure.
+.Pp
+.Fn uu_unlock
+will set the global variable
+.Dv errno
+to reflect the reason that the lock file could not be removed.
+Refer to the description of
+.Xr unlink 2
+for further details.
+.Sh BUGS
+Locking is not atomic.  Should a race condition occur, it's entirely
+possible that both processes obtain the lock.
+.Pp
+It is possible that a stale lock is not recognised as such if a new
+processes is assigned the same processes id as the program that left
+the stale lock.
+.Pp
+The calling process must have write permissions to the
+.Dq /var/spool/lock
+directory.  There is no mechanism in place to ensure that the
+permissions of this directory are the same as those of the
+serial devices that might be locked.