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