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 July 26, 2010
  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 .Nd "lockmgr family of functions"
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In sys/lock.h
  42 .Ft void
  43 .Fn lockinit "struct lock *lkp" "const char *wmesg" "int timo" "int flags"
  44 .Ft void
  45 .Fn lockuninit "struct lock *lkp"
  46 .Ft int
  47 .Fn lockcount "struct lock *lkp"
  48 .Ft int
  49 .Fn lockcountnb "struct lock *lkp"
  50 .Ft int
  51 .Fn lockmgr "struct lock *lkp" "u_int flags"
  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 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 LK_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_TIMELOCK
  82 Use
  83 .Fa timo
  84 during a sleep; otherwise, 0 is used.
  85 .El
  86 .El
  87 .Pp
  88 The
  89 .Fn lockuninit
  90 function destroys a lock that was previously initialized using
  91 .Fn lockinit .
  92 .Pp
  93 The
  94 .Fn lockcount
  95 function returns a count of the number of exclusive locks and shared locks
  96 held against the lock
  97 .Fa lkp .
  98 .Pp
  99 The
 100 .Fn lockcountnb
 101 function is a non-blocking counter-part of
 102 .Fn lockcount .
 103 which, can be safely used in assertion statements e.g. a
 104 .Xr KASSERT 9 .
 105 .Pp
 106 The
 107 .Fn lockmgr
 108 function handles general locking functionality within the kernel, including
 109 support for shared and exclusive locks, and recursion.
 110 .Fn lockmgr
 111 is also able to upgrade and downgrade locks.
 112 .Pp
 113 Its arguments are:
 114 .Bl -tag -width ".Fa flags"
 115 .It Fa lkp
 116 A pointer to the lock to manipulate.
 117 .It Fa flags
 118 Flags indicating what action is to be taken.
 119 .Bl -tag -width ".Dv LK_EXCLUPGRADE"
 120 .It Dv LK_SHARED
 121 Acquire a shared lock.
 122 If an exclusive lock is currently held, it will be downgraded.
 123 .It Dv LK_EXCLUSIVE
 124 Acquire an exclusive lock.
 125 If an exclusive lock is already held, and
 126 .Dv LK_CANRECURSE
 127 is not set, the system will
 128 .Xr panic 9 .
 129 .It Dv LK_DOWNGRADE
 130 Downgrade exclusive lock to a shared lock.
 131 Downgrading a shared lock is not permitted.
 132 If an exclusive lock has been recursed, all references will be downgraded.
 133 .It Dv LK_EXCLUPGRADE
 134 Upgrade a shared lock to an exclusive lock.
 135 Fails with
 136 .Er EBUSY
 137 if there is someone ahead of you in line waiting for an upgrade.
 138 If this call fails, the shared lock is lost.
 139 Attempts to upgrade an exclusive lock will cause a
 140 .Xr panic 9 .
 141 .It Dv LK_UPGRADE
 142 Upgrade a shared lock to an exclusive lock.
 143 If this call fails, the shared lock is lost.
 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_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 .El
 159 .El
 160 .Pp
 161 The
 162 .Fn lockstatus
 163 function returns the status of the lock in relation to the
 164 .Vt thread
 165 passed to it.
 166 Note that if
 167 .Fa td
 168 is
 169 .Dv NULL
 170 and an exclusive lock is held,
 171 .Dv LK_EXCLUSIVE
 172 will be returned.
 173 .Pp
 174 The
 175 .Fn lockmgr_printinfo
 176 function prints debugging information about the lock.
 177 It is used primarily by
 178 .Xr VOP_PRINT 9
 179 functions.
 180 .Sh RETURN VALUES
 181 The
 182 .Fn lockcount
 183 function returns an integer greater than or equal to zero.
 184 .Pp
 185 The
 186 .Fn lockmgr
 187 function returns 0 on success and non-zero on failure.
 188 .Pp
 189 The
 190 .Fn lockstatus
 191 function returns:
 192 .Bl -tag -width ".Dv LK_EXCLUSIVE"
 193 .It Dv LK_EXCLUSIVE
 194 An exclusive lock is held by the thread
 195 .Fa td .
 196 .It Dv LK_EXCLOTHER
 197 An exclusive lock is held by someone other than the thread
 198 .Fa td .
 199 .It Dv LK_SHARED
 200 A shared lock is held.
 201 .It Li 0
 202 The lock is not held by anyone.
 203 .El
 204 .Sh FILES
 205 The lock manager itself is implemented within the file
 206 .Pa /sys/kern/kern_lock.c .
 207 Data structures and function prototypes for the lock manager are in
 208 .Pa /sys/sys/lock.h .
 209 .Sh ERRORS
 210 .Fn lockmgr
 211 fails if:
 212 .Bl -tag -width Er
 213 .It Bq Er EBUSY
 214 .Dv LK_NOWAIT
 215 was set, and a sleep would have been required.
 216 .It Bq Er ENOLCK
 217 .Dv LK_SLEEPFAIL
 218 was set and
 219 .Fn lockmgr
 220 did sleep.
 221 .It Bq Er EINTR
 222 .Dv PCATCH
 223 was set in the lock priority, and a signal was delivered during a sleep.
 224 Note the
 225 .Er ERESTART
 226 error below.
 227 .It Bq Er ERESTART
 228 .Dv PCATCH
 229 was set in the lock priority, a signal was delivered during a sleep,
 230 and the system call is to be restarted.
 231 .It Bq Er EWOULDBLOCK
 232 a non-zero timeout was given, and the timeout expired.
 233 .El
 234 .Sh LOCKS
 235 Upgrade attempts that fail result in the loss of the lock that
 236 is currently held.
 237 Also, it is invalid to upgrade an
 238 exclusive lock, and a
 239 .Xr panic 9
 240 will be the result of trying.
 241 .Sh SEE ALSO
 242 .Xr panic 9 ,
 243 .Xr tsleep 9 ,
 244 .Xr VOP_PRINT 9
 245 .Sh HISTORY
 246 The lock manager appeared in
 247 .Dx 1.0 .
 248 .Pp
 249 The lock manager API first appeared in
 250 .Bx 4.4 lite2 .
 251 .Sh AUTHORS
 252 This man page was written by
 253 .An Chad David Aq davidc@acns.ab.ca .