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: src/lib/libutil/uucplock.3,v 1.13.2.4 2001/12/17 10:08:32 ru Exp $ 27.\" $DragonFly: src/lib/libutil/uucplock.3,v 1.2 2003/06/17 04:26:52 dillon Exp $ 28.\" " 29.Dd March 30, 1997 30.Os 31.Dt UUCPLOCK 3 32.Sh NAME 33.Nm uu_lock , 34.Nm uu_unlock , 35.Nm uu_lockerr 36.Nd acquire and release control of a serial device 37.Sh LIBRARY 38.Lb libutil 39.Sh SYNOPSIS 40.In sys/types.h 41.In libutil.h 42.Ft int 43.Fn uu_lock "const char *ttyname" 44.Ft int 45.Fn uu_lock_txfr "const char *ttyname" "pid_t pid" 46.Ft int 47.Fn uu_unlock "const char *ttyname" 48.Ft const char * 49.Fn uu_lockerr "int uu_lockresult" 50.Sh DESCRIPTION 51The 52.Fn uu_lock 53function attempts to create a lock file called 54.Pa /var/spool/lock/LCK.. 55with a suffix given by the passed 56.Fa ttyname . 57If the file already exists, it is expected to contain the process 58id of the locking program. 59.Pp 60If the file does not already exist, or the owning process given by 61the process id found in the lock file is no longer running, 62.Fn uu_lock 63will write its own process id into the file and return success. 64.Pp 65.Fn uu_lock_txfr 66transfers lock ownership to another process. 67.Fn uu_lock 68must have previously been successful. 69.Pp 70.Fn uu_unlock 71removes the lockfile created by 72.Fn uu_lock 73for the given 74.Fa ttyname . 75Care should be taken that 76.Fn uu_lock 77was successful before calling 78.Fn uu_unlock . 79.Pp 80.Fn uu_lockerr 81returns an error string representing the error 82.Fa uu_lockresult , 83as returned from 84.Fn uu_lock . 85.Sh RETURN VALUES 86.Fn uu_unlock 87returns 0 on success and -1 on failure. 88.Pp 89.Fn uu_lock 90may return any of the following values: 91.Pp 92.Dv UU_LOCK_INUSE : 93The lock is in use by another process. 94.Pp 95.Dv UU_LOCK_OK : 96The lock was successfully created. 97.Pp 98.Dv UU_LOCK_OPEN_ERR : 99The lock file could not be opened via 100.Xr open 2 . 101.Pp 102.Dv UU_LOCK_READ_ERR : 103The lock file could not be read via 104.Xr read 2 . 105.Pp 106.Dv UU_LOCK_CREAT_ERR : 107Can't create temporary lock file via 108.Xr creat 2 . 109.Pp 110.Dv UU_LOCK_WRITE_ERR : 111The current process id could not be written to the lock file via a call to 112.Xr write 2 . 113.Pp 114.Dv UU_LOCK_LINK_ERR : 115Can't link temporary lock file via 116.Xr link 2 . 117.Pp 118.Dv UU_LOCK_TRY_ERR : 119Locking attempts are failed after 5 tries. 120.Pp 121If a value of 122.Dv UU_LOCK_OK 123is passed to 124.Fn uu_lockerr , 125an empty string is returned. 126Otherwise, a string specifying 127the reason for failure is returned. 128.Fn uu_lockerr 129uses the current value of 130.Va errno 131to determine the exact error. Care 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. The 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. Refer 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 BUGS 172It is possible that a stale lock is not recognised as such if a new 173processes is assigned the same processes id as the program that left 174the stale lock. 175.Pp 176The calling process must have write permissions to the 177.Pa /var/spool/lock 178directory. There is no mechanism in place to ensure that the 179permissions of this directory are the same as those of the 180serial devices that might be locked. 181