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