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