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