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