share/man/man9/lock.9

   1 .\"
   2 .\" Copyright (C) 2002 Chad David <davidc@acns.ab.ca>. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), 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 COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  18 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  25 .\" DAMAGE.
  26 .\"
  27 .\" $FreeBSD: src/share/man/man9/lock.9,v 1.11 2003/09/08 19:57:21 ru Exp $
  28 .\" $DragonFly: src/share/man/man9/lock.9,v 1.6 2007/04/05 20:01:19 swildner Exp $
  29 .\"
  30 .Dd June 29, 2006
  31 .Dt LOCK 9
  32 .Os
  33 .Sh NAME
  34 .Nm lockinit ,
  35 .Nm lockcount ,
  36 .Nm lockmgr ,
  37 .Nm lockstatus ,
  38 .Nm lockmgr_printinfo
  39 .Nd "lockmgr family of functions"
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In sys/lock.h
  43 .Ft void
  44 .Fn lockinit "struct lock *lkp" "char *wmesg" "int timo" "int flags"
  45 .Ft int
  46 .Fn lockcount "struct lock *lkp"
  47 .Ft int
  48 .Fn lockcountnb "struct lock *lkp"
  49 .Ft int
  50 .Fn lockmgr "struct lock *lkp" "u_int flags"
  51 .Ft int
  52 .Fn lockstatus "struct lock *lkp" "struct thread *td"
  53 .Ft void
  54 .Fn lockmgr_printinfo "struct lock *lkp"
  55 .Sh DESCRIPTION
  56 The
  57 .Fn lockinit
  58 function is used to initialize a lock.
  59 It must be called before any operation can be performed on a lock.
  60 Its arguments are:
  61 .Bl -tag -width ".Fa wmesg"
  62 .It Fa lkp
  63 A pointer to the lock to initialize.
  64 .It Fa wmesg
  65 The lock message.
  66 This is used for both debugging output and
  67 .Xr tsleep 9 .
  68 .It Fa timo
  69 The timeout value passed to
  70 .Xr tsleep 9 .
  71 .It Fa flags
  72 The flags the lock is to be initialized with.
  73 .Bl -tag -width ".Dv LG_CANRECURSE"
  74 .It Dv LK_NOWAIT
  75 Do not sleep while acquiring the lock.
  76 .It Dv LK_SLEEPFAIL
  77 Fail after a sleep.
  78 .It Dv LK_CANRECURSE
  79 Allow recursive exclusive locks.
  80 .It Dv LK_TIMELOCK
  81 Use
  82 .Fa timo
  83 during a sleep; otherwise, 0 is used.
  84 .El
  85 .El
  86 .Pp
  87 The
  88 .Fn lockcount
  89 function returns a count of the number of exclusive locks and shared locks
  90 held against the lock
  91 .Fa lkp .
  92 .Pp
  93 The
  94 .Fn lockcountnb
  95 function is a non-blocking counter-part of
  96 .Fn lockcount .
  97 which, can be safely used in assertion statements e.g. a
  98 .Xr KASSERT 9 .
  99 .Pp
 100 The
 101 .Fn lockmgr
 102 function handles general locking functionality within the kernel, including
 103 support for shared and exclusive locks, and recursion.
 104 .Fn lockmgr
 105 is also able to upgrade and downgrade locks.
 106 .Pp
 107 Its arguments are:
 108 .Bl -tag -width ".Fa flags"
 109 .It Fa lkp
 110 A pointer to the lock to manipulate.
 111 .It Fa flags
 112 Flags indicating what action is to be taken.
 113 .Bl -tag -width ".Dv LK_EXCLUPGRADE"
 114 .It Dv LK_SHARED
 115 Acquire a shared lock.
 116 If an exclusive lock is currently held, it will be downgraded.
 117 .It Dv LK_EXCLUSIVE
 118 Acquire an exclusive lock.
 119 If an exclusive lock is already held, and
 120 .Dv LK_CANRECURSE
 121 is not set, the system will
 122 .Xr panic 9 .
 123 .It Dv LK_DOWNGRADE
 124 Downgrade exclusive lock to a shared lock.
 125 Downgrading a shared lock is not permitted.
 126 If an exclusive lock has been recursed, all references will be downgraded.
 127 .It Dv LK_EXCLUPGRADE
 128 Upgrade a shared lock to an exclusive lock.
 129 Fails with
 130 .Er EBUSY
 131 if there is someone ahead of you in line waiting for an upgrade.
 132 If this call fails, the shared lock is lost.
 133 Attempts to upgrade an exclusive lock will cause a
 134 .Xr panic 9 .
 135 .It Dv LK_UPGRADE
 136 Upgrade a shared lock to an exclusive lock.
 137 If this call fails, the shared lock is lost.
 138 Attempts to upgrade an exclusive lock will cause a
 139 .Xr panic 9 .
 140 .It Dv LK_RELEASE
 141 Release the lock.
 142 Releasing a lock that is not held can cause a
 143 .Xr panic 9 .
 144 .It Dv LK_SLEEPFAIL
 145 Fail if operation has slept.
 146 .It Dv LK_NOWAIT
 147 Do not allow the call to sleep.
 148 This can be used to test the lock.
 149 .It Dv LK_CANRECURSE
 150 Allow recursion on an exclusive lock.
 151 For every lock there must be a release.
 152 .El
 153 .El
 154 .Pp
 155 The
 156 .Fn lockstatus
 157 function returns the status of the lock in relation to the
 158 .Vt thread
 159 passed to it.
 160 Note that if
 161 .Fa td
 162 is
 163 .Dv NULL
 164 and an exclusive lock is held,
 165 .Dv LK_EXCLUSIVE
 166 will be returned.
 167 .Pp
 168 The
 169 .Fn lockmgr_printinfo
 170 function prints debugging information about the lock.
 171 It is used primarily by
 172 .Xr VOP_PRINT 9
 173 functions.
 174 .Sh RETURN VALUES
 175 The
 176 .Fn lockcount
 177 function returns an integer greater than or equal to zero.
 178 .Pp
 179 The
 180 .Fn lockmgr
 181 function returns 0 on success and non-zero on failure.
 182 .Pp
 183 The
 184 .Fn lockstatus
 185 function returns:
 186 .Bl -tag -width ".Dv LK_EXCLUSIVE"
 187 .It Dv LK_EXCLUSIVE
 188 An exclusive lock is held by the thread
 189 .Fa td .
 190 .It Dv LK_EXCLOTHER
 191 An exclusive lock is held by someone other than the thread
 192 .Fa td .
 193 .It Dv LK_SHARED
 194 A shared lock is held.
 195 .It Li 0
 196 The lock is not held by anyone.
 197 .El
 198 .Sh ERRORS
 199 .Fn lockmgr
 200 fails if:
 201 .Bl -tag -width Er
 202 .It Bq Er EBUSY
 203 .Dv LK_NOWAIT
 204 was set, and a sleep would have been required.
 205 .It Bq Er ENOLCK
 206 .Dv LK_SLEEPFAIL
 207 was set and
 208 .Fn lockmgr
 209 did sleep.
 210 .It Bq Er EINTR
 211 .Dv PCATCH
 212 was set in the lock priority, and a signal was delivered during a sleep.
 213 Note the
 214 .Er ERESTART
 215 error below.
 216 .It Bq Er ERESTART
 217 .Dv PCATCH
 218 was set in the lock priority, a signal was delivered during a sleep,
 219 and the system call is to be restarted.
 220 .It Bq Er EWOULDBLOCK
 221 a non-zero timeout was given, and the timeout expired.
 222 .El
 223 .Sh LOCKS
 224 Upgrade attempts that fail result in the loss of the lock that
 225 is currently held.
 226 Also, it is invalid to upgrade an
 227 exclusive lock, and a
 228 .Xr panic 9
 229 will be the result of trying.
 230 .Sh SEE ALSO
 231 .Xr panic 9 ,
 232 .Xr tsleep 9 ,
 233 .Xr VOP_PRINT 9
 234 .Sh AUTHORS
 235 This man page was written by
 236 .An Chad David Aq davidc@acns.ab.ca .