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.5 2006/06/29 19:56:19 swildner Exp $
  29 .\"
  30 .Dd June 29, 2006
  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" "char *wmesg" "int timo" "int flags"
  45 .Ft int
  46 .Fn lockcount "struct lock *lkp"
  47 .Ft int
  48 .Fn lockcountnb "struct lock *lkp"
  49 .Ft int
  50 .Fn lockmgr "struct lock *lkp" "u_int flags"
  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 wmesg
  65 The lock message.
  66 This is used for both debugging output and
  67 .Xr tsleep 9 .
  68 .It Fa timo
  69 The timeout value passed to
  70 .Xr tsleep 9 .
  71 .It Fa flags
  72 The flags the lock is to be initialized with.
  73 .Bl -tag -width ".Dv LG_CANRECURSE"
  74 .It Dv LK_NOWAIT
  75 Do not sleep while acquiring the lock.
  76 .It Dv LK_SLEEPFAIL
  77 Fail after a sleep.
  78 .It Dv LK_CANRECURSE
  79 Allow recursive exclusive locks.
  80 .It Dv LK_NOPAUSE
  81 Disable the spinlock while acquiring the lock.
  82 .It Dv LK_TIMELOCK
  83 Use
  84 .Fa timo
  85 during a sleep; otherwise, 0 is used.
  86 .El
  87 .El
  88 .Pp
  89 The
  90 .Fn lockcount
  91 function returns a count of the number of exclusive locks and shared locks
  92 held against the lock
  93 .Fa lkp .
  94 .Pp
  95 The
  96 .Fn lockcountnb
  97 function is a non-blocking counter-part of
  98 .Fn lockcount .
  99 which, can be safely used in assertion statements e.g. a
 100 .Xr KASSERT 9 .
 101 .Pp
 102 The
 103 .Fn lockmgr
 104 function handles general locking functionality within the kernel, including
 105 support for shared and exclusive locks, and recursion.
 106 .Fn lockmgr
 107 is also able to upgrade and downgrade locks.
 108 .Pp
 109 Its arguments are:
 110 .Bl -tag -width ".Fa flags"
 111 .It Fa lkp
 112 A pointer to the lock to manipulate.
 113 .It Fa flags
 114 Flags indicating what action is to be taken.
 115 .Bl -tag -width ".Dv LK_EXCLUPGRADE"
 116 .It Dv LK_SHARED
 117 Acquire a shared lock.
 118 If an exclusive lock is currently held, it will be downgraded.
 119 .It Dv LK_EXCLUSIVE
 120 Acquire an exclusive lock.
 121 If an exclusive lock is already held, and
 122 .Dv LK_CANRECURSE
 123 is not set, the system will
 124 .Xr panic 9 .
 125 .It Dv LK_DOWNGRADE
 126 Downgrade exclusive lock to a shared lock.
 127 Downgrading a shared lock is not permitted.
 128 If an exclusive lock has been recursed, all references will be downgraded.
 129 .It Dv LK_EXCLUPGRADE
 130 Upgrade a shared lock to an exclusive lock.
 131 Fails with
 132 .Er EBUSY
 133 if there is someone ahead of you in line waiting for an upgrade.
 134 If this call fails, the shared lock is lost.
 135 Attempts to upgrade an exclusive lock will cause a
 136 .Xr panic 9 .
 137 .It Dv LK_UPGRADE
 138 Upgrade a shared lock to an exclusive lock.
 139 If this call fails, the shared lock is lost.
 140 Attempts to upgrade an exclusive lock will cause a
 141 .Xr panic 9 .
 142 .It Dv LK_RELEASE
 143 Release the lock.
 144 Releasing a lock that is not held can cause a
 145 .Xr panic 9 .
 146 .It Dv LK_SLEEPFAIL
 147 Fail if operation has slept.
 148 .It Dv LK_NOWAIT
 149 Do not allow the call to sleep.
 150 This can be used to test the lock.
 151 .It Dv LK_CANRECURSE
 152 Allow recursion on an exclusive lock.
 153 For every lock there must be a release.
 154 .El
 155 .El
 156 .Pp
 157 The
 158 .Fn lockstatus
 159 function returns the status of the lock in relation to the
 160 .Vt thread
 161 passed to it.
 162 Note that if
 163 .Fa td
 164 is
 165 .Dv NULL
 166 and an exclusive lock is held,
 167 .Dv LK_EXCLUSIVE
 168 will be returned.
 169 .Pp
 170 The
 171 .Fn lockmgr_printinfo
 172 function prints debugging information about the lock.
 173 It is used primarily by
 174 .Xr VOP_PRINT 9
 175 functions.
 176 .Sh RETURN VALUES
 177 The
 178 .Fn lockcount
 179 function returns an integer greater than or equal to zero.
 180 .Pp
 181 The
 182 .Fn lockmgr
 183 function returns 0 on success and non-zero on failure.
 184 .Pp
 185 The
 186 .Fn lockstatus
 187 function returns:
 188 .Bl -tag -width ".Dv LK_EXCLUSIVE"
 189 .It Dv LK_EXCLUSIVE
 190 An exclusive lock is held by the thread
 191 .Fa td .
 192 .It Dv LK_EXCLOTHER
 193 An exclusive lock is held by someone other than the thread
 194 .Fa td .
 195 .It Dv LK_SHARED
 196 A shared lock is held.
 197 .It Li 0
 198 The lock is not held by anyone.
 199 .El
 200 .Sh ERRORS
 201 .Fn lockmgr
 202 fails if:
 203 .Bl -tag -width Er
 204 .It Bq Er EBUSY
 205 .Dv LK_NOWAIT
 206 was set, and a sleep would have been required.
 207 .It Bq Er ENOLCK
 208 .Dv LK_SLEEPFAIL
 209 was set and
 210 .Fn lockmgr
 211 did sleep.
 212 .It Bq Er EINTR
 213 .Dv PCATCH
 214 was set in the lock priority, and a signal was delivered during a sleep.
 215 Note the
 216 .Er ERESTART
 217 error below.
 218 .It Bq Er ERESTART
 219 .Dv PCATCH
 220 was set in the lock priority, a signal was delivered during a sleep,
 221 and the system call is to be restarted.
 222 .It Bq Er EWOULDBLOCK
 223 a non-zero timeout was given, and the timeout expired.
 224 .El
 225 .Sh LOCKS
 226 Upgrade attempts that fail result in the loss of the lock that
 227 is currently held.
 228 Also, it is invalid to upgrade an
 229 exclusive lock, and a
 230 .Xr panic 9
 231 will be the result of trying.
 232 .Sh SEE ALSO
 233 .Xr panic 9 ,
 234 .Xr tsleep 9 ,
 235 .Xr VOP_PRINT 9
 236 .Sh AUTHORS
 237 This man page was written by
 238 .An Chad David Aq davidc@acns.ab.ca .