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