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 .\"
  29 .Dd January 19, 2014
  30 .Dt LOCK 9
  31 .Os
  32 .Sh NAME
  33 .Nm lockinit ,
  34 .Nm lockcount ,
  35 .Nm lockmgr ,
  36 .Nm lockstatus ,
  37 .Nm lockmgr_printinfo ,
  38 .Nm lockowned
  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" "const char *wmesg" "int timo" "int flags"
  45 .Ft void
  46 .Fn lockuninit "struct lock *lkp"
  47 .Ft int
  48 .Fn lockcount "struct lock *lkp"
  49 .Ft int
  50 .Fn lockcountnb "struct lock *lkp"
  51 .Ft int
  52 .Fn lockmgr "struct lock *lkp" "u_int flags"
  53 .Ft int
  54 .Fn lockstatus "struct lock *lkp" "struct thread *td"
  55 .Ft void
  56 .Fn lockmgr_printinfo "struct lock *lkp"
  57 .Ft int
  58 .Fn lockowned "struct lock *lkp"
  59 .Sh DESCRIPTION
  60 The
  61 .Fn lockinit
  62 function is used to initialize a lock.
  63 It must be called before any operation can be performed on a lock.
  64 Its arguments are:
  65 .Bl -tag -width ".Fa wmesg"
  66 .It Fa lkp
  67 A pointer to the lock to initialize.
  68 .It Fa wmesg
  69 The lock message.
  70 This is used for both debugging output and
  71 .Xr tsleep 9 .
  72 .It Fa timo
  73 The timeout value passed to
  74 .Xr tsleep 9 .
  75 .It Fa flags
  76 The flags the lock is to be initialized with.
  77 .Bl -tag -width ".Dv LK_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_TIMELOCK
  85 Use
  86 .Fa timo
  87 during a sleep; otherwise, 0 is used.
  88 .El
  89 .El
  90 .Pp
  91 The
  92 .Fn lockuninit
  93 function destroys a lock that was previously initialized using
  94 .Fn lockinit .
  95 .Pp
  96 The
  97 .Fn lockcount
  98 function returns a count of the number of exclusive locks and shared locks
  99 held against the lock
 100 .Fa lkp .
 101 .Pp
 102 The
 103 .Fn lockcountnb
 104 function is a non-blocking counter-part of
 105 .Fn lockcount .
 106 which, can be safely used in assertion statements e.g. a
 107 .Xr KASSERT 9 .
 108 .Pp
 109 The
 110 .Fn lockmgr
 111 function handles general locking functionality within the kernel, including
 112 support for shared and exclusive locks, and recursion.
 113 .Fn lockmgr
 114 is also able to upgrade and downgrade locks.
 115 .Pp
 116 Its arguments are:
 117 .Bl -tag -width ".Fa flags"
 118 .It Fa lkp
 119 A pointer to the lock to manipulate.
 120 .It Fa flags
 121 Flags indicating what action is to be taken.
 122 .Bl -tag -width ".Dv LK_EXCLUPGRADE"
 123 .It Dv LK_SHARED
 124 Acquire a shared lock.
 125 If an exclusive lock is currently held, it will be downgraded.
 126 .It Dv LK_EXCLUSIVE
 127 Acquire an exclusive lock.
 128 If an exclusive lock is already held, and
 129 .Dv LK_CANRECURSE
 130 is not set, the system will
 131 .Xr panic 9 .
 132 .It Dv LK_DOWNGRADE
 133 Downgrade exclusive lock to a shared lock.
 134 Downgrading a shared lock is not permitted.
 135 If an exclusive lock has been recursed, all references will be downgraded.
 136 .It Dv LK_EXCLUPGRADE
 137 Upgrade a shared lock to an exclusive lock.
 138 Fails with
 139 .Er EBUSY
 140 if there is someone ahead of you in line waiting for an upgrade.
 141 If this call fails, the shared lock is lost.
 142 Attempts to upgrade an exclusive lock will cause a
 143 .Xr panic 9 .
 144 .It Dv LK_UPGRADE
 145 Upgrade a shared lock to an exclusive lock.
 146 If this call fails, the shared lock is lost.
 147 Attempts to upgrade an exclusive lock will cause a
 148 .Xr panic 9 .
 149 .It Dv LK_RELEASE
 150 Release the lock.
 151 Releasing a lock that is not held can cause a
 152 .Xr panic 9 .
 153 .It Dv LK_SLEEPFAIL
 154 Fail if operation has slept.
 155 .It Dv LK_NOWAIT
 156 Do not allow the call to sleep.
 157 This can be used to test the lock.
 158 .It Dv LK_CANRECURSE
 159 Allow recursion on an exclusive lock.
 160 For every lock there must be a release.
 161 .El
 162 .El
 163 .Pp
 164 The
 165 .Fn lockstatus
 166 function returns the status of the lock in relation to the
 167 .Vt thread
 168 passed to it.
 169 Note that if
 170 .Fa td
 171 is
 172 .Dv NULL
 173 and an exclusive lock is held,
 174 .Dv LK_EXCLUSIVE
 175 will be returned.
 176 .Pp
 177 The
 178 .Fn lockmgr_printinfo
 179 function prints debugging information about the lock.
 180 It is used primarily by
 181 .Xr VOP_PRINT 9
 182 functions.
 183 .Pp
 184 The
 185 .Fn lockowned
 186 function is used to determine whether the calling thread owns a lock.
 187 .Sh RETURN VALUES
 188 The
 189 .Fn lockcount
 190 function returns an integer greater than or equal to zero.
 191 .Pp
 192 The
 193 .Fn lockmgr
 194 function returns 0 on success and non-zero on failure.
 195 .Pp
 196 The
 197 .Fn lockstatus
 198 function returns:
 199 .Bl -tag -width ".Dv LK_EXCLUSIVE"
 200 .It Dv LK_EXCLUSIVE
 201 An exclusive lock is held by the thread
 202 .Fa td .
 203 .It Dv LK_EXCLOTHER
 204 An exclusive lock is held by someone other than the thread
 205 .Fa td .
 206 .It Dv LK_SHARED
 207 A shared lock is held.
 208 .It Li 0
 209 The lock is not held by anyone.
 210 .El
 211 .Pp
 212 The
 213 .Fn lockowned
 214 function returns a non-zero return value if the caller owns the lock shared or exclusive.
 215 .Sh FILES
 216 The lock manager itself is implemented within the file
 217 .Pa /sys/kern/kern_lock.c .
 218 Data structures and function prototypes for the lock manager are in
 219 .Pa /sys/sys/lock.h .
 220 .Sh ERRORS
 221 .Fn lockmgr
 222 fails if:
 223 .Bl -tag -width Er
 224 .It Bq Er EBUSY
 225 .Dv LK_NOWAIT
 226 was set, and a sleep would have been required.
 227 .It Bq Er ENOLCK
 228 .Dv LK_SLEEPFAIL
 229 was set and
 230 .Fn lockmgr
 231 did sleep.
 232 .It Bq Er EINTR
 233 .Dv PCATCH
 234 was set in the lock priority, and a signal was delivered during a sleep.
 235 Note the
 236 .Er ERESTART
 237 error below.
 238 .It Bq Er ERESTART
 239 .Dv PCATCH
 240 was set in the lock priority, a signal was delivered during a sleep,
 241 and the system call is to be restarted.
 242 .It Bq Er EWOULDBLOCK
 243 a non-zero timeout was given, and the timeout expired.
 244 .El
 245 .Sh LOCKS
 246 Upgrade attempts that fail result in the loss of the lock that
 247 is currently held.
 248 Also, it is invalid to upgrade an
 249 exclusive lock, and a
 250 .Xr panic 9
 251 will be the result of trying.
 252 .Sh SEE ALSO
 253 .Xr locking 9 ,
 254 .Xr panic 9 ,
 255 .Xr tsleep 9 ,
 256 .Xr VOP_PRINT 9
 257 .Sh HISTORY
 258 The lock manager appeared in
 259 .Dx 1.0 .
 260 .Pp
 261 The lock manager API first appeared in
 262 .Bx 4.4 lite2 .
 263 .Sh AUTHORS
 264 This man page was written by
 265 .An Chad David Aq Mt davidc@acns.ab.ca .