1.\" 2.\" Copyright (c) 1996 Brian Somers <brian@awfulhak.demon.co.uk> 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $Id: uucplock.3,v 1.4 1997/04/02 03:38:28 ache Exp $ 27.\" " 28.Dd March 30, 1997 29.Os 30.Dt uucplock 3 31.Sh NAME 32.Nm uu_lock , 33.Nm uu_unlock , 34.Nm uu_lockerr 35.Nd acquire and release control of a serial device 36.Sh SYNOPSIS 37.Fd #include <libutil.h> 38.Ft int 39.Fn uu_lock "char *ttyname" 40.Ft int 41.Fn uu_unlock "char *ttyname" 42.Ft char * 43.Fn uu_lockerr "int uu_lockresult" 44.Pp 45Link with 46.Va -lutil 47on the 48.Xr cc 1 49command line. 50.Sh DESCRIPTION 51The 52.Fn uu_lock 53function attempts to create a lock file called 54.Pa /var/spool/lock/LCK.. 55with a suffix given by the passed 56.Fa ttyname . 57If the file already exists, it is expected to contain the process 58id of the locking program. 59.Pp 60If the file does not already exist, or the owning process given by 61the process id found in the lock file is no longer running, 62.Fn uu_lock 63will write its own process id into the file and return success. 64.Pp 65.Fn uu_unlock 66removes the lockfile created by 67.Fn uu_lock 68for the given 69.Fa ttyname . 70Care should be taken that 71.Fn uu_lock 72was successful before calling 73.Fn uu_unlock . 74.Pp 75.Fn uu_lockerr 76returns an error string representing the error 77.Fa uu_lockresult , 78as returned from 79.Fn uu_lock . 80.Sh RETURN VALUES 81.Fn uu_unlock 82returns 0 on success and -1 on failure. 83.Pp 84.Fn uu_lock 85may return any of the following values: 86.Pp 87.Dv UU_LOCK_INUSE: 88The lock is in use by another process. 89.Pp 90.Dv UU_LOCK_OK: 91The lock was successfully created. 92.Pp 93.Dv UU_LOCK_OPEN_ERR: 94The lock file could not be opened via 95.Xr open 2 . 96.Pp 97.Dv UU_LOCK_READ_ERR: 98The lock file could not be read via 99.Xr read 2 . 100.Pp 101.Dv UU_LOCK_SEEK_ERR: 102The lock file was 103.Dq stale , 104but the call to 105.Xr lseek 2 106necessary to write the current process id failed. 107.Pp 108.Dv UU_LOCK_WRITE_ERR: 109The current process id could not be written to the lock file via a call to 110.Xr write 2 . 111.Pp 112If a value of 113.Dv UU_LOCK_OK 114is passed to 115.Fn uu_lockerr , 116an empty string is returned. 117Otherwise, a string specifying 118the reason for failure is returned. 119.Fn uu_lockerr 120uses the current value of 121.Va errno 122to determine the exact error. Care should be made not to allow 123.Va errno 124to be changed between calls to 125.Fn uu_lock 126and 127.Fn uu_lockerr . 128.Sh ERRORS 129If 130.Fn uu_lock 131returns one of the four error values above, the global value 132.Va errno 133can be used to determine the cause. Refer to the respective manual pages 134for further details. 135.Pp 136.Fn uu_unlock 137will set the global variable 138.Va errno 139to reflect the reason that the lock file could not be removed. 140Refer to the description of 141.Xr unlink 2 142for further details. 143.Sh SEE ALSO 144.Xr open 2 , 145.Xr read 2 , 146.Xr lseek 2 , 147.Xr write 2 148.Sh BUGS 149Locking is not atomic. Should a race condition occur, it's 150possible that the 151.Dq losing 152process fails to identify the 153.Dq winning 154process. If this happens, 155.Fn uu_lock 156returns 157.Dv UU_LOCK_READ_ERR 158and errno is set to 159.Er EINVAL . 160.Pp 161It is possible that a stale lock is not recognised as such if a new 162processes is assigned the same processes id as the program that left 163the stale lock. 164.Pp 165The calling process must have write permissions to the 166.Pa /var/spool/lock 167directory. There is no mechanism in place to ensure that the 168permissions of this directory are the same as those of the 169serial devices that might be locked. 170