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.8 1997/08/10 18:42:38 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 <sys/types.h> 38.Fd #include <libutil.h> 39.Ft int 40.Fn uu_lock "const char *ttyname" 41.Ft int 42.Fn uu_unlock "const char *ttyname" 43.Ft const char * 44.Fn uu_lockerr "int uu_lockresult" 45.Pp 46Link with 47.Va -lutil 48on the 49.Xr cc 1 50command line. 51.Sh DESCRIPTION 52The 53.Fn uu_lock 54function attempts to create a lock file called 55.Pa /var/spool/lock/LCK.. 56with a suffix given by the passed 57.Fa ttyname . 58If the file already exists, it is expected to contain the process 59id of the locking program. 60.Pp 61If the file does not already exist, or the owning process given by 62the process id found in the lock file is no longer running, 63.Fn uu_lock 64will write its own process id into the file and return success. 65.Pp 66.Fn uu_unlock 67removes the lockfile created by 68.Fn uu_lock 69for the given 70.Fa ttyname . 71Care should be taken that 72.Fn uu_lock 73was successful before calling 74.Fn uu_unlock . 75.Pp 76.Fn uu_lockerr 77returns an error string representing the error 78.Fa uu_lockresult , 79as returned from 80.Fn uu_lock . 81.Sh RETURN VALUES 82.Fn uu_unlock 83returns 0 on success and -1 on failure. 84.Pp 85.Fn uu_lock 86may return any of the following values: 87.Pp 88.Dv UU_LOCK_INUSE: 89The lock is in use by another process. 90.Pp 91.Dv UU_LOCK_OK: 92The lock was successfully created. 93.Pp 94.Dv UU_LOCK_OPEN_ERR: 95The lock file could not be opened via 96.Xr open 2 . 97.Pp 98.Dv UU_LOCK_READ_ERR: 99The lock file could not be read via 100.Xr read 2 . 101.Pp 102.Dv UU_LOCK_CREAT_ERR: 103Can't create temporary lock file via 104.Xr creat 2 . 105.Pp 106.Dv UU_LOCK_WRITE_ERR: 107The current process id could not be written to the lock file via a call to 108.Xr write 2 . 109.Pp 110.Dv UU_LOCK_LINK_ERR: 111Can't link temporary lock file via 112.Xr link 2 . 113.Pp 114.Dv UU_LOCK_TRY_ERR: 115Locking attempts are failed after 5 tries. 116.Pp 117If a value of 118.Dv UU_LOCK_OK 119is passed to 120.Fn uu_lockerr , 121an empty string is returned. 122Otherwise, a string specifying 123the reason for failure is returned. 124.Fn uu_lockerr 125uses the current value of 126.Va errno 127to determine the exact error. Care should be made not to allow 128.Va errno 129to be changed between calls to 130.Fn uu_lock 131and 132.Fn uu_lockerr . 133.Sh ERRORS 134If 135.Fn uu_lock 136returns one of the four error values above, the global value 137.Va errno 138can be used to determine the cause. Refer to the respective manual pages 139for further details. 140.Pp 141.Fn uu_unlock 142will set the global variable 143.Va errno 144to reflect the reason that the lock file could not be removed. 145Refer to the description of 146.Xr unlink 2 147for further details. 148.Sh SEE ALSO 149.Xr lseek 2 , 150.Xr open 2 , 151.Xr read 2 , 152.Xr write 2 153.Sh BUGS 154Locking is not atomic. Should a race condition occur, it's 155possible that the 156.Dq losing 157process fails to identify the 158.Dq winning 159process. If this happens, 160.Fn uu_lock 161returns 162.Dv UU_LOCK_READ_ERR 163and errno is set to 164.Er EINVAL . 165.Pp 166It is possible that a stale lock is not recognised as such if a new 167processes is assigned the same processes id as the program that left 168the stale lock. 169.Pp 170The calling process must have write permissions to the 171.Pa /var/spool/lock 172directory. There is no mechanism in place to ensure that the 173permissions of this directory are the same as those of the 174serial devices that might be locked. 175