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.6 1997/05/11 08:50:33 davidn 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_SEEK_ERR: 103The lock file was 104.Dq stale , 105but the call to 106.Xr lseek 2 107necessary to write the current process id failed. 108.Pp 109.Dv UU_LOCK_WRITE_ERR: 110The current process id could not be written to the lock file via a call to 111.Xr write 2 . 112.Pp 113If a value of 114.Dv UU_LOCK_OK 115is passed to 116.Fn uu_lockerr , 117an empty string is returned. 118Otherwise, a string specifying 119the reason for failure is returned. 120.Fn uu_lockerr 121uses the current value of 122.Va errno 123to determine the exact error. Care should be made not to allow 124.Va errno 125to be changed between calls to 126.Fn uu_lock 127and 128.Fn uu_lockerr . 129.Sh ERRORS 130If 131.Fn uu_lock 132returns one of the four error values above, the global value 133.Va errno 134can be used to determine the cause. Refer to the respective manual pages 135for further details. 136.Pp 137.Fn uu_unlock 138will set the global variable 139.Va errno 140to reflect the reason that the lock file could not be removed. 141Refer to the description of 142.Xr unlink 2 143for further details. 144.Sh SEE ALSO 145.Xr open 2 , 146.Xr read 2 , 147.Xr lseek 2 , 148.Xr write 2 149.Sh BUGS 150Locking is not atomic. Should a race condition occur, it's 151possible that the 152.Dq losing 153process fails to identify the 154.Dq winning 155process. If this happens, 156.Fn uu_lock 157returns 158.Dv UU_LOCK_READ_ERR 159and errno is set to 160.Er EINVAL . 161.Pp 162It is possible that a stale lock is not recognised as such if a new 163processes is assigned the same processes id as the program that left 164the stale lock. 165.Pp 166The calling process must have write permissions to the 167.Pa /var/spool/lock 168directory. There is no mechanism in place to ensure that the 169permissions of this directory are the same as those of the 170serial devices that might be locked. 171