1.\" $OpenBSD: uu_lock.3,v 1.1 2019/08/30 03:57:56 deraadt Exp $ 2.\" 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" " 26.Dd $Mdocdate: August 30 2019 $ 27.Dt UU_LOCK 3 28.Os 29.Sh NAME 30.Nm uu_lock , 31.Nm uu_unlock , 32.Nm uu_lockerr , 33.Nm uu_lock_txfr 34.Nd acquire and release control of a serial device 35.Sh SYNOPSIS 36.In sys/types.h 37.In util.h 38.Ft int 39.Fn uu_lock "const char *ttyname" 40.Ft int 41.Fn uu_lock_txfr "const char *ttyname" "pid_t pid" 42.Ft int 43.Fn uu_unlock "const char *ttyname" 44.Ft const char * 45.Fn uu_lockerr "int uu_lockresult" 46.Sh DESCRIPTION 47The 48.Fn uu_lock 49function attempts to create a lock file called 50.Pa /var/spool/lock/LCK.. 51with a suffix given by the passed 52.Fa ttyname . 53If the file already exists, it is expected to contain the process 54ID of the locking program. 55.Pp 56If the file does not already exist, or the owning process given by 57the process ID found in the lock file is no longer running, 58.Fn uu_lock 59will write its own process ID into the file and return success. 60.Pp 61.Fn uu_lock_txfr 62transfers lock ownership to another process. 63.Fn uu_lock 64must have previously been successful. 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 3 . 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. 128Care should be made not to allow 129.Va errno 130to be changed between calls to 131.Fn uu_lock 132and 133.Fn uu_lockerr . 134.Pp 135.Fn uu_lock_txfr 136may return any of the following values: 137.Pp 138.Dv UU_LOCK_OK : 139The transfer was successful. 140The specified process now holds the device lock. 141.Pp 142.Dv UU_LOCK_OWNER_ERR : 143The current process does not already own a lock on the specified device. 144.Pp 145.Dv UU_LOCK_WRITE_ERR : 146The new process ID could not be written to the lock file via a call to 147.Xr write 2 . 148.Sh ERRORS 149If 150.Fn uu_lock 151returns one of the error values above, the global value 152.Va errno 153can be used to determine the cause. 154Refer to the respective manual pages for further details. 155.Pp 156.Fn uu_unlock 157will set the global variable 158.Va errno 159to reflect the reason that the lock file could not be removed. 160Refer to the description of 161.Xr unlink 2 162for further details. 163.Sh SEE ALSO 164.Xr lseek 2 , 165.Xr open 2 , 166.Xr read 2 , 167.Xr write 2 168.Sh BUGS 169It is possible that a stale lock is not recognised as such if a new 170process is assigned the same process ID as the program that left 171the stale lock. 172.Pp 173The calling process must have write permissions to the 174.Pa /var/spool/lock 175directory. 176There is no mechanism in place to ensure that the 177permissions of this directory are the same as those of the 178serial devices that might be locked. 179