lib/libutil/pidlock.3

   1 .\"     $NetBSD: pidlock.3,v 1.11 2006/03/23 19:30:27 wiz Exp $
   2 .\"
   3 .\" Copyright 1996, 1997 by Curt Sampson <cjs@NetBSD.org>
   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 .\"
  11 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  12 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  13 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  14 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  15 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  16 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  17 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  18 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  19 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  20 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  21 .\" POSSIBILITY OF SUCH DAMAGE.
  22 .\"
  23 .Dd March 19, 2006
  24 .Dt PIDLOCK 3
  25 .Os
  26 .Sh NAME
  27 .Nm pidlock ,
  28 .Nm ttylock ,
  29 .Nm ttyunlock
  30 .Nd locks based on files containing PIDs
  31 .Sh LIBRARY
  32 .Lb libutil
  33 .Sh SYNOPSIS
  34 .In util.h
  35 .Ft int
  36 .Fn pidlock "const char *lockfile" "int flags" "pid_t *locker" "const char *info"
  37 .Ft int
  38 .Fn ttylock "const char *tty" "int flags" "pid_t *locker"
  39 .Ft int
  40 .Fn ttyunlock "const char *tty"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn pidlock
  44 .Fn ttylock ,
  45 and
  46 .Fn ttyunlock
  47 functions attempt to create a lockfile for an arbitrary resource that
  48 only one program may hold at a time.
  49 (In the case of
  50 .Fn ttylock ,
  51 this is access to a tty device.)
  52 If the
  53 function succeeds in creating the lockfile, it will succeed for
  54 no other program calling it with the same lockfile until the original
  55 calling program has removed the lockfile or exited.
  56 The
  57 .Fn ttyunlock
  58 function will remove the lockfile created by
  59 .Fn ttylock .
  60 .Pp
  61 These functions use the method of creating a lockfile traditionally
  62 used by UUCP software.
  63 This is described as follows in the documentation for Taylor UUCP:
  64 .Bd -filled -offset indent
  65 The lock file normally contains the process ID of the locking process.
  66 This makes it easy to determine whether a lock is still valid.
  67 The algorithm is to create a temporary file and then link
  68 it to the name that must be locked.
  69 If the link fails because a file with that name already exists,
  70 the existing file is read to get the process ID.
  71 If the process still exists, the lock attempt fails.
  72 Otherwise the lock file is deleted and the locking algorithm
  73 is retried.
  74 .Ed
  75 .Pp
  76 The PID is stored in ASCII format, with leading spaces to pad it
  77 out to ten characters, and a terminating newline.
  78 This implementation has been extended to put the hostname
  79 on the second line of the file, terminated with a newline, and
  80 optionally an arbitrary comment on the third line of the file, also
  81 terminated with a newline.
  82 If a comment is given, but
  83 .Dv PIDLOCK_NONBLOCK
  84 is not, a blank line will be written as the second line of the file.
  85 .Pp
  86 The
  87 .Fn pidlock
  88 function will attempt to create the file
  89 .Fa lockfile
  90 and put the current process's pid in it.
  91 The
  92 .Fn ttylock
  93 function will do the same, but should be passed only the base name
  94 (with no leading directory prefix) of the
  95 .Fa tty
  96 to be locked; it will test that the tty exists in
  97 .Pa /dev
  98 and is a character device, and then create
  99 the file in the
 100 .Pa /var/spool/lock
 101 directory and prefix the filename with
 102 .Pa LCK.. .
 103 Use the
 104 .Fn ttyunlock
 105 function to remove this lock.
 106 .Pp
 107 The following flags may be passed in
 108 .Pa flags :
 109 .Bl -tag -width Dv -offset indent
 110 .It Dv PIDLOCK_NONBLOCK
 111 The function should return immediately when a lock is held by another
 112 active process.
 113 Otherwise the function will wait (forever, if necessary)
 114 for the lock to be freed.
 115 .It Dv PIDLOCK_USEHOSTNAME
 116 The hostname should be compared against the hostname in the second
 117 line of the file (if present), and if they differ, no attempt at
 118 checking for a living process holding the lock will be made, and
 119 the lockfile will never be deleted.
 120 (The process is assumed to be alive.)
 121 This is used for locking on NFS or other remote filesystems.
 122 (The function will never create a lock if
 123 .Dv PIDLOCK_USEHOSTNAME
 124 is specified and no hostname is present.)
 125 .El
 126 .Pp
 127 If
 128 .Pa locker
 129 is non-null, it will contain the PID of the locking process, if there
 130 is one, on return.
 131 .Pp
 132 If
 133 .Pa info
 134 is non-null and the lock succeeds, the string it points to will be
 135 written as the third line of the lock file.
 136 .Sh RETURN VALUES
 137 Zero is returned if the operation was successful; on an error a -1
 138 is returned and a standard error code is left in the global location
 139 .Va errno .
 140 .Sh ERRORS
 141 In addition to the errors that are returned from
 142 .Xr stat 2 ,
 143 .Xr open 2 ,
 144 .Xr read 2 ,
 145 .Xr write 2 ,
 146 and
 147 .Xr link 2 ,
 148 .Fn pidlock
 149 or
 150 .Fn ttylock
 151 can set
 152 .Va errno
 153 to the following values on failure:
 154 .Bl -tag -width Er
 155 .It Bq Er EWOULDBLOCK
 156 Another running process has a lock and the
 157 .Dv PIDLOCK_NONBLOCK
 158 flag was specified.
 159 .It Bq Er EFTYPE
 160 The
 161 .Fa tty
 162 specified in
 163 .Fn ttylock
 164 is not a character special device.
 165 .El
 166 .\" .Sh SEE ALSO
 167 .Sh HISTORY
 168 The
 169 .Fn pidlock
 170 and
 171 .Fn ttylock
 172 functions appeared in
 173 .Nx 1.3 .
 174 .Sh AUTHORS
 175 .An Curt Sampson
 176 .Aq cjs@NetBSD.org .
 177 .Sh BUGS
 178 The lockfile format breaks if a pid is longer than ten digits when
 179 printed in decimal form.
 180 .Pp
 181 The PID returned will be the pid of the locker on the remote machine if
 182 .Dv PIDLOCK_USEHOSTNAME
 183 is specified, but there is no indication that this is not on the local
 184 machine.