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