lib/libutil/uucplock.3

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