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