xref: /freebsd/share/man/man9/lock.9 (revision 63d1fd5970ec814904aa0f4580b10a0d302d08b2)
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$
28.\"
29.Dd November 2, 2014
30.Dt LOCK 9
31.Os
32.Sh NAME
33.Nm lockinit ,
34.Nm lockdestroy ,
35.Nm lockmgr ,
36.Nm lockmgr_args ,
37.Nm lockmgr_args_rw ,
38.Nm lockmgr_disown ,
39.Nm lockmgr_printinfo ,
40.Nm lockmgr_recursed ,
41.Nm lockmgr_rw ,
42.Nm lockstatus ,
43.Nm lockmgr_assert
44.Nd "lockmgr family of functions"
45.Sh SYNOPSIS
46.In sys/types.h
47.In sys/lock.h
48.In sys/lockmgr.h
49.Ft void
50.Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags"
51.Ft void
52.Fn lockdestroy "struct lock *lkp"
53.Ft int
54.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *ilk"
55.Ft int
56.Fn lockmgr_args "struct lock *lkp" "u_int flags" "struct mtx *ilk" "const char *wmesg" "int prio" "int timo"
57.Ft int
58.Fn lockmgr_args_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" "const char *wmesg" "int prio" "int timo"
59.Ft void
60.Fn lockmgr_disown "struct lock *lkp"
61.Ft void
62.Fn lockmgr_printinfo "const struct lock *lkp"
63.Ft int
64.Fn lockmgr_recursed "const struct lock *lkp"
65.Ft int
66.Fn lockmgr_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk"
67.Ft int
68.Fn lockstatus "const struct lock *lkp"
69.Pp
70.Cd "options INVARIANTS"
71.Cd "options INVARIANT_SUPPORT"
72.Ft void
73.Fn lockmgr_assert "const struct lock *lkp" "int what"
74.Sh DESCRIPTION
75The
76.Fn lockinit
77function is used to initialize a lock.
78It must be called before any operation can be performed on a lock.
79Its arguments are:
80.Bl -tag -width ".Fa wmesg"
81.It Fa lkp
82A pointer to the lock to initialize.
83.It Fa prio
84The priority passed to
85.Xr sleep 9 .
86.It Fa wmesg
87The lock message.
88This is used for both debugging output and
89.Xr sleep 9 .
90.It Fa timo
91The timeout value passed to
92.Xr sleep 9 .
93.It Fa flags
94The flags the lock is to be initialized with:
95.Bl -tag -width ".Dv LK_CANRECURSE"
96.It Dv LK_ADAPTIVE
97Enable adaptive spinning for this lock if the kernel is compiled with the
98ADAPTIVE_LOCKMGRS option.
99.It Dv LK_CANRECURSE
100Allow recursive exclusive locks.
101.It Dv LK_NOPROFILE
102Disable lock profiling for this lock.
103.It Dv LK_NOSHARE
104Allow exclusive locks only.
105.It Dv LK_NOWITNESS
106Instruct
107.Xr witness 4
108to ignore this lock.
109.It Dv LK_NODUP
110.Xr witness 4
111should log messages about duplicate locks being acquired.
112.It Dv LK_QUIET
113Disable
114.Xr ktr 4
115logging for this lock.
116.It Dv LK_TIMELOCK
117Use
118.Fa timo
119during a sleep; otherwise, 0 is used.
120.El
121.El
122.Pp
123The
124.Fn lockdestroy
125function is used to destroy a lock, and while it is called in a number of
126places in the kernel, it currently does nothing.
127.Pp
128The
129.Fn lockmgr
130and
131.Fn lockmgr_rw
132functions handle general locking functionality within the kernel, including
133support for shared and exclusive locks, and recursion.
134.Fn lockmgr
135and
136.Fn lockmgr_rw
137are also able to upgrade and downgrade locks.
138.Pp
139Their arguments are:
140.Bl -tag -width ".Fa flags"
141.It Fa lkp
142A pointer to the lock to manipulate.
143.It Fa flags
144Flags indicating what action is to be taken.
145.Bl -tag -width ".Dv LK_NODDLKTREAT"
146.It Dv LK_SHARED
147Acquire a shared lock.
148If an exclusive lock is currently held,
149.Dv EDEADLK
150will be returned.
151.It Dv LK_EXCLUSIVE
152Acquire an exclusive lock.
153If an exclusive lock is already held, and
154.Dv LK_CANRECURSE
155is not set, the system will
156.Xr panic 9 .
157.It Dv LK_DOWNGRADE
158Downgrade exclusive lock to a shared lock.
159Downgrading a shared lock is not permitted.
160If an exclusive lock has been recursed, the system will
161.Xr panic 9 .
162.It Dv LK_UPGRADE
163Upgrade a shared lock to an exclusive lock.
164If this call fails, the shared lock is lost, even if the
165.Dv LK_NOWAIT
166flag is specified.
167During the upgrade, the shared lock could
168be temporarily dropped.
169Attempts to upgrade an exclusive lock will cause a
170.Xr panic 9 .
171.It Dv LK_TRYUPGRADE
172Try to upgrade a shared lock to an exclusive lock.
173The failure to upgrade does not result in the dropping
174of the shared lock ownership.
175.It Dv LK_RELEASE
176Release the lock.
177Releasing a lock that is not held can cause a
178.Xr panic 9 .
179.It Dv LK_DRAIN
180Wait for all activity on the lock to end, then mark it decommissioned.
181This is used before freeing a lock that is part of a piece of memory that is
182about to be freed.
183(As documented in
184.In sys/lockmgr.h . )
185.It Dv LK_SLEEPFAIL
186Fail if operation has slept.
187.It Dv LK_NOWAIT
188Do not allow the call to sleep.
189This can be used to test the lock.
190.It Dv LK_NOWITNESS
191Skip the
192.Xr witness 4
193checks for this instance.
194.It Dv LK_CANRECURSE
195Allow recursion on an exclusive lock.
196For every lock there must be a release.
197.It Dv LK_INTERLOCK
198Unlock the interlock (which should be locked already).
199.It Dv LK_NODDLKTREAT
200Normally,
201.Fn lockmgr
202postpones serving further shared requests for shared-locked lock if there is
203exclusive waiter, to avoid exclusive lock starvation.
204But, if the thread requesting the shared lock already owns a shared lockmgr
205lock, the request is granted even in presence of the parallel exclusive lock
206request, which is done to avoid deadlocks with recursive shared acquisition.
207.Pp
208The
209.Dv LK_NODDLKTREAT
210flag can only be used by code which requests shared non-recursive lock.
211The flag allows exclusive requests to preempt the current shared request
212even if the current thread owns shared locks.
213This is safe since shared lock is guaranteed to not recurse, and is used
214when thread is known to held unrelated shared locks, to not cause
215unnecessary starvation.
216An example is
217.Dv vp
218locking in VFS
219.Xr lookup 9 ,
220when
221.Dv dvp
222is already locked.
223.El
224.It Fa ilk
225An interlock mutex for controlling group access to the lock.
226If
227.Dv LK_INTERLOCK
228is specified,
229.Fn lockmgr
230and
231.Fn lockmgr_rw
232assume
233.Fa ilk
234is currently owned and not recursed, and will return it unlocked.
235See
236.Xr mtx_assert 9 .
237.El
238.Pp
239The
240.Fn lockmgr_args
241and
242.Fn lockmgr_args_rw
243function work like
244.Fn lockmgr
245and
246.Fn lockmgr_rw
247but accepting a
248.Fa wmesg ,
249.Fa timo
250and
251.Fa prio
252on a per-instance basis.
253The specified values will override the default
254ones, but this can still be used passing, respectively,
255.Dv LK_WMESG_DEFAULT ,
256.Dv LK_PRIO_DEFAULT
257and
258.Dv LK_TIMO_DEFAULT .
259.Pp
260The
261.Fn lockmgr_disown
262function switches the owner from the current thread to be
263.Dv LK_KERNPROC ,
264if the lock is already held.
265.Pp
266The
267.Fn lockmgr_printinfo
268function prints debugging information about the lock.
269It is used primarily by
270.Xr VOP_PRINT 9
271functions.
272.Pp
273The
274.Fn lockmgr_recursed
275function returns true if the lock is recursed, 0
276otherwise.
277.Pp
278The
279.Fn lockstatus
280function returns the status of the lock in relation to the current thread.
281.Pp
282When compiled with
283.Cd "options INVARIANTS"
284and
285.Cd "options INVARIANT_SUPPORT" ,
286the
287.Fn lockmgr_assert
288function tests
289.Fa lkp
290for the assertions specified in
291.Fa what ,
292and panics if they are not met.
293One of the following assertions must be specified:
294.Bl -tag -width ".Dv KA_UNLOCKED"
295.It Dv KA_LOCKED
296Assert that the current thread has either a shared or an exclusive lock on the
297.Vt lkp
298lock pointed to by the first argument.
299.It Dv KA_SLOCKED
300Assert that the current thread has a shared lock on the
301.Vt lkp
302lock pointed to by the first argument.
303.It Dv KA_XLOCKED
304Assert that the current thread has an exclusive lock on the
305.Vt lkp
306lock pointed to by the first argument.
307.It Dv KA_UNLOCKED
308Assert that the current thread has no lock on the
309.Vt lkp
310lock pointed to by the first argument.
311.El
312.Pp
313In addition, one of the following optional assertions can be used with
314either an
315.Dv KA_LOCKED ,
316.Dv KA_SLOCKED ,
317or
318.Dv KA_XLOCKED
319assertion:
320.Bl -tag -width ".Dv KA_NOTRECURSED"
321.It Dv KA_RECURSED
322Assert that the current thread has a recursed lock on
323.Fa lkp .
324.It Dv KA_NOTRECURSED
325Assert that the current thread does not have a recursed lock on
326.Fa lkp .
327.El
328.Sh RETURN VALUES
329The
330.Fn lockmgr
331and
332.Fn lockmgr_rw
333functions return 0 on success and non-zero on failure.
334.Pp
335The
336.Fn lockstatus
337function returns:
338.Bl -tag -width ".Dv LK_EXCLUSIVE"
339.It Dv LK_EXCLUSIVE
340An exclusive lock is held by the current thread.
341.It Dv LK_EXCLOTHER
342An exclusive lock is held by someone other than the current thread.
343.It Dv LK_SHARED
344A shared lock is held.
345.It Li 0
346The lock is not held by anyone.
347.El
348.Sh ERRORS
349.Fn lockmgr
350and
351.Fn lockmgr_rw
352fail if:
353.Bl -tag -width Er
354.It Bq Er EBUSY
355.Dv LK_FORCEUPGRADE
356was requested and another thread had already requested a lock upgrade.
357.It Bq Er EBUSY
358.Dv LK_NOWAIT
359was set, and a sleep would have been required, or
360.Dv LK_TRYUPGRADE
361operation was not able to upgrade the lock.
362.It Bq Er ENOLCK
363.Dv LK_SLEEPFAIL
364was set and
365.Fn lockmgr
366or
367.Fn lockmgr_rw
368did sleep.
369.It Bq Er EINTR
370.Dv PCATCH
371was set in the lock priority, and a signal was delivered during a sleep.
372Note the
373.Er ERESTART
374error below.
375.It Bq Er ERESTART
376.Dv PCATCH
377was set in the lock priority, a signal was delivered during a sleep,
378and the system call is to be restarted.
379.It Bq Er EWOULDBLOCK
380a non-zero timeout was given, and the timeout expired.
381.El
382.Sh LOCKS
383If
384.Dv LK_INTERLOCK
385is passed in the
386.Fa flags
387argument to
388.Fn lockmgr
389or
390.Fn lockmgr_rw ,
391the
392.Fa ilk
393must be held prior to calling
394.Fn lockmgr
395or
396.Fn lockmgr_rw ,
397and will be returned unlocked.
398.Pp
399Upgrade attempts that fail result in the loss of the lock that
400is currently held.
401Also, it is invalid to upgrade an
402exclusive lock, and a
403.Xr panic 9
404will be the result of trying.
405.Sh SEE ALSO
406.Xr condvar 9 ,
407.Xr locking 9 ,
408.Xr mtx_assert 9 ,
409.Xr mutex 9 ,
410.Xr panic 9 ,
411.Xr rwlock 9 ,
412.Xr sleep 9 ,
413.Xr sx 9 ,
414.Xr VOP_PRINT 9
415.Sh AUTHORS
416This manual page was written by
417.An Chad David Aq Mt davidc@acns.ab.ca .
418