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$
  28 .\"
  29 .Dd June 20, 2006
  30 .Dt LOCK 9
  31 .Os
  32 .Sh NAME
  33 .Nm lockinit ,
  34 .Nm lockdestroy ,
  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/lockmgr.h
  43 .Ft void
  44 .Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags"
  45 .Ft void
  46 .Fn lockdestroy "struct lock *lkp"
  47 .Ft int
  48 .Fn lockcount "struct lock *lkp"
  49 .Ft int
  50 .Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "struct thread *td"
  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 prio
  65 The priority passed to
  66 .Xr sleep 9 .
  67 .It Fa wmesg
  68 The lock message.
  69 This is used for both debugging output and
  70 .Xr sleep 9 .
  71 .It Fa timo
  72 The timeout value passed to
  73 .Xr sleep 9 .
  74 .It Fa flags
  75 The flags the lock is to be initialized with.
  76 .Bl -tag -width ".Dv LG_CANRECURSE"
  77 .It Dv LK_NOWAIT
  78 Do not sleep while acquiring the lock.
  79 .It Dv LK_SLEEPFAIL
  80 Fail after a sleep.
  81 .It Dv LK_CANRECURSE
  82 Allow recursive exclusive locks.
  83 .It Dv LK_NOSHARE
  84 Allow exclusive locks only.
  85 .It Dv LK_TIMELOCK
  86 Use
  87 .Fa timo
  88 during a sleep; otherwise, 0 is used.
  89 .El
  90 .El
  91 .Pp
  92 The
  93 .Fn lockdestroy
  94 function is used to destroy a lock, and while it is called in a number of
  95 places in the kernel, it currently does nothing.
  96 .Pp
  97 The
  98 .Fn lockcount
  99 function returns a count of the number of exclusive locks and shared locks
 100 held against the lock
 101 .Fa lkp .
 102 .Pp
 103 The
 104 .Fn lockmgr
 105 function handles general locking functionality within the kernel, including
 106 support for shared and exclusive locks, and recursion.
 107 .Fn lockmgr
 108 is also able to upgrade and downgrade locks.
 109 .Pp
 110 Its arguments are:
 111 .Bl -tag -width ".Fa interlkp"
 112 .It Fa lkp
 113 A pointer to the lock to manipulate.
 114 .It Fa flags
 115 Flags indicating what action is to be taken.
 116 .Bl -tag -width ".Dv LK_EXCLUPGRADE"
 117 .It Dv LK_SHARED
 118 Acquire a shared lock.
 119 If an exclusive lock is currently held, it will be downgraded.
 120 .It Dv LK_EXCLUSIVE
 121 Acquire an exclusive lock.
 122 If an exclusive lock is already held, and
 123 .Dv LK_CANRECURSE
 124 is not set, the system will
 125 .Xr panic 9 .
 126 .It Dv LK_DOWNGRADE
 127 Downgrade exclusive lock to a shared lock.
 128 Downgrading a shared lock is not permitted.
 129 If an exclusive lock has been recursed, all references will be downgraded.
 130 .It Dv LK_EXCLUPGRADE
 131 Upgrade a shared lock to an exclusive lock.
 132 Fails with
 133 .Er EBUSY
 134 if there is someone ahead of you in line waiting for an upgrade.
 135 If this call fails, the shared lock is lost.
 136 Attempts to upgrade an exclusive lock will cause a
 137 .Xr panic 9 .
 138 .It Dv LK_UPGRADE
 139 Upgrade a shared lock to an exclusive lock.
 140 If this call fails, the shared lock is lost.
 141 During the upgrade, the shared lock could
 142 be temporarily dropped.
 143 Attempts to upgrade an exclusive lock will cause a
 144 .Xr panic 9 .
 145 .It Dv LK_RELEASE
 146 Release the lock.
 147 Releasing a lock that is not held can cause a
 148 .Xr panic 9 .
 149 .It Dv LK_DRAIN
 150 Wait for all activity on the lock to end, then mark it decommissioned.
 151 This is used before freeing a lock that is part of a piece of memory that is
 152 about to be freed.
 153 (As documented in
 154 .In sys/lockmgr.h . )
 155 .It Dv LK_SLEEPFAIL
 156 Fail if operation has slept.
 157 .It Dv LK_NOWAIT
 158 Do not allow the call to sleep.
 159 This can be used to test the lock.
 160 .It Dv LK_CANRECURSE
 161 Allow recursion on an exclusive lock.
 162 For every lock there must be a release.
 163 .It Dv LK_INTERLOCK
 164 Unlock the interlock (which should be locked already).
 165 .El
 166 .It Fa interlkp
 167 An interlock mutex for controlling group access to the lock.
 168 If
 169 .Dv LK_INTERLOCK
 170 is specified,
 171 .Fn lockmgr
 172 assumes
 173 .Fa interlkp
 174 is currently owned and not recursed, and will return it unlocked.
 175 See
 176 .Xr mtx_assert 9 .
 177 .It Fa td
 178 A thread responsible for this call.
 179 .Dv NULL
 180 becomes
 181 .Dv LK_KERNPROC .
 182 .El
 183 .Pp
 184 The
 185 .Fn lockstatus
 186 function returns the status of the lock in relation to the
 187 .Vt thread
 188 passed to it.
 189 Note that if
 190 .Fa td
 191 is
 192 .Dv NULL
 193 and an exclusive lock is held,
 194 .Dv LK_EXCLUSIVE
 195 will be returned.
 196 .Pp
 197 The
 198 .Fn lockmgr_printinfo
 199 function prints debugging information about the lock.
 200 It is used primarily by
 201 .Xr VOP_PRINT 9
 202 functions.
 203 .Sh RETURN VALUES
 204 The
 205 .Fn lockcount
 206 function returns an integer greater than or equal to zero.
 207 .Pp
 208 The
 209 .Fn lockmgr
 210 function returns 0 on success and non-zero on failure.
 211 .Pp
 212 The
 213 .Fn lockstatus
 214 function returns:
 215 .Bl -tag -width ".Dv LK_EXCLUSIVE"
 216 .It Dv LK_EXCLUSIVE
 217 An exclusive lock is held by the thread
 218 .Fa td .
 219 .It Dv LK_EXCLOTHER
 220 An exclusive lock is held by someone other than the thread
 221 .Fa td .
 222 .It Dv LK_SHARED
 223 A shared lock is held.
 224 .It Li 0
 225 The lock is not held by anyone.
 226 .El
 227 .Sh ERRORS
 228 .Fn lockmgr
 229 fails if:
 230 .Bl -tag -width Er
 231 .It Bq Er EBUSY
 232 .Dv LK_FORCEUPGRADE
 233 was requested and another thread had already requested a lock upgrade.
 234 .It Bq Er EBUSY
 235 .Dv LK_NOWAIT
 236 was set, and a sleep would have been required.
 237 .It Bq Er ENOLCK
 238 .Dv LK_SLEEPFAIL
 239 was set and
 240 .Fn lockmgr
 241 did sleep.
 242 .It Bq Er EINTR
 243 .Dv PCATCH
 244 was set in the lock priority, and a signal was delivered during a sleep.
 245 Note the
 246 .Er ERESTART
 247 error below.
 248 .It Bq Er ERESTART
 249 .Dv PCATCH
 250 was set in the lock priority, a signal was delivered during a sleep,
 251 and the system call is to be restarted.
 252 .It Bq Er EWOULDBLOCK
 253 a non-zero timeout was given, and the timeout expired.
 254 .El
 255 .Sh LOCKS
 256 If
 257 .Dv LK_INTERLOCK
 258 is passed in the
 259 .Fa flags
 260 argument to
 261 .Fn lockmgr ,
 262 the
 263 .Fa interlkp
 264 must be held prior to calling
 265 .Fn lockmgr ,
 266 and will be returned unlocked.
 267 .Pp
 268 Upgrade attempts that fail result in the loss of the lock that
 269 is currently held.
 270 Also, it is invalid to upgrade an
 271 exclusive lock, and a
 272 .Xr panic 9
 273 will be the result of trying.
 274 .Sh SEE ALSO
 275 .Xr condvar 9 ,
 276 .Xr locking 9 ,
 277 .Xr mutex 9 ,
 278 .Xr rwlock 9 ,
 279 .Xr sleep 9 ,
 280 .Xr sx 9 ,
 281 .Xr mtx_assert 9 ,
 282 .Xr panic 9 ,
 283 .Xr VOP_PRINT 9
 284 .Sh AUTHORS
 285 This manual page was written by
 286 .An Chad David Aq davidc@acns.ab.ca .