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