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