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