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: head/share/man/man9/lock.9 177962 2008-04-06 21:22:12Z attilio $
28.\"
29.Dd April 6, 2008
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 "struct lock *lkp"
64.Ft int
65.Fn lockmgr_recursed "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 "struct lock *lkp"
70.Ft int
71.Fn lockstatus "struct lock *lkp"
72.Pp
73.Cd "options INVARIANTS"
74.Cd "options INVARIANT_SUPPORT"
75.Ft void
76.Fn lockmgr_assert "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_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_CANRECURSE"
146.It Dv LK_SHARED
147Acquire a shared lock.
148If an exclusive lock is currently held, it will be downgraded.
149.It Dv LK_EXCLUSIVE
150Acquire an exclusive lock.
151If an exclusive lock is already held, and
152.Dv LK_CANRECURSE
153is not set, the system will
154.Xr panic 9 .
155.It Dv LK_DOWNGRADE
156Downgrade exclusive lock to a shared lock.
157Downgrading a shared lock is not permitted.
158If an exclusive lock has been recursed, all references will be downgraded.
159.It Dv LK_UPGRADE
160Upgrade a shared lock to an exclusive lock.
161If this call fails, the shared lock is lost.
162During the upgrade, the shared lock could
163be temporarily dropped.
164Attempts to upgrade an exclusive lock will cause a
165.Xr panic 9 .
166.It Dv LK_RELEASE
167Release the lock.
168Releasing a lock that is not held can cause a
169.Xr panic 9 .
170.It Dv LK_DRAIN
171Wait for all activity on the lock to end, then mark it decommissioned.
172This is used before freeing a lock that is part of a piece of memory that is
173about to be freed.
174(As documented in
175.In sys/lockmgr.h . )
176.It Dv LK_SLEEPFAIL
177Fail if operation has slept.
178.It Dv LK_NOWAIT
179Do not allow the call to sleep.
180This can be used to test the lock.
181.It Dv LK_CANRECURSE
182Allow recursion on an exclusive lock.
183For every lock there must be a release.
184.It Dv LK_INTERLOCK
185Unlock the interlock (which should be locked already).
186.El
187.It Fa ilk
188An interlock mutex for controlling group access to the lock.
189If
190.Dv LK_INTERLOCK
191is specified,
192.Fn lockmgr
193and
194.Fn lockmgr_rw
195assume
196.Fa ilk
197is currently owned and not recursed, and will return it unlocked.
198See
199.Xr mtx_assert 9 .
200.El
201.Pp
202The
203.Fn lockmgr_args
204and
205.Fn lockmgr_args_rw
206function work like
207.Fn lockmgr
208and
209.Fn lockmgr_rw
210but accepting a
211.Fa wmesg ,
212.Fa timo
213and
214.Fa prio
215on a per-instance basis.
216The specified values will override the default
217ones, but this can still be used passing, respectively,
218.Dv LK_WMESG_DEFAULT ,
219.Dv LK_PRIO_DEFAULT
220and
221.Dv LK_TIMO_DEFAULT .
222.Pp
223The
224.Fn lockmgr_disown
225function switches the owner from the current thread to be
226.Dv LK_KERNPROC,
227if the lock is already held.
228.Pp
229The
230.Fn lockmgr_printinfo
231function prints debugging information about the lock.
232It is used primarily by
233.Xr VOP_PRINT 9
234functions.
235.Pp
236The
237.Fn lockmgr_recursed
238function returns true if the lock is recursed, 0
239otherwise.
240.Pp
241The
242.Fn lockmgr_waiters
243function returns true if the lock has waiters, 0 otherwise.
244.Pp
245The
246.Fn lockstatus
247function returns the status of the lock in relation to the current thread.
248.Pp
249When compiled with
250.Cd "options INVARIANTS"
251and
252.Cd "options INVARIANT_SUPPORT" ,
253the
254.Fn lockmgr_assert
255function tests
256.Fa lkp
257for the assertions specified in
258.Fa what ,
259and panics if they are not met.
260One of the following assertions must be specified:
261.Bl -tag -width ".Dv KA_UNLOCKED"
262.It Dv KA_LOCKED
263Assert that the current thread has either a shared or an exclusive lock on the
264.Vt lkp
265lock pointed to by the first argument.
266.It Dv KA_SLOCKED
267Assert that the current thread has a shared lock on the
268.Vt lkp
269lock pointed to by the first argument.
270.It Dv KA_XLOCKED
271Assert that the current thread has an exclusive lock on the
272.Vt lkp
273lock pointed to by the first argument.
274.It Dv KA_UNLOCKED
275Assert that the current thread has no lock on the
276.Vt lkp
277lock pointed to by the first argument.
278.It Dv KA_HELD
279Assert that an unspecified thread has a lock on the
280.Vt lkp
281lock pointed to by the first argument.
282.It Dv KA_UNHELD
283Assert that no thread has a lock on the
284.Vt lkp
285lock pointed to by the first argument.
286.El
287.Pp
288In addition, one of the following optional assertions can be used with
289either an
290.Dv KA_LOCKED ,
291.Dv KA_SLOCKED ,
292or
293.Dv KA_XLOCKED
294assertion:
295.Bl -tag -width ".Dv KA_NOTRECURSED"
296.It Dv KA_RECURSED
297Assert that the current thread has a recursed lock on
298.Fa lkp .
299.It Dv KA_NOTRECURSED
300Assert that the current thread does not have a recursed lock on
301.Fa lkp .
302.El
303.Pp
304Note that
305.Dv KA_HELD
306and
307.Dv KA_UNHELD
308usage is highly discouraged.
309They are intended to cater a bad behaviour
310introduced by buffer cache lock handling.
311They will hopefully be
312made useless by revisiting such locks.
313.Sh RETURN VALUES
314The
315.Fn lockmgr
316and
317.Fn lockmgr_rw
318functions return 0 on success and non-zero on failure.
319.Pp
320The
321.Fn lockstatus
322function returns:
323.Bl -tag -width ".Dv LK_EXCLUSIVE"
324.It Dv LK_EXCLUSIVE
325An exclusive lock is held by the current thread.
326.It Dv LK_EXCLOTHER
327An exclusive lock is held by someone other than the current thread.
328.It Dv LK_SHARED
329A shared lock is held.
330.It Li 0
331The lock is not held by anyone.
332.El
333.Sh ERRORS
334.Fn lockmgr
335and
336.Fn lockmgr_rw
337fail if:
338.Bl -tag -width Er
339.It Bq Er EBUSY
340.Dv LK_FORCEUPGRADE
341was requested and another thread had already requested a lock upgrade.
342.It Bq Er EBUSY
343.Dv LK_NOWAIT
344was set, and a sleep would have been required.
345.It Bq Er ENOLCK
346.Dv LK_SLEEPFAIL
347was set and
348.Fn lockmgr
349or
350.Fn lockmgr_rw
351did sleep.
352.It Bq Er EINTR
353.Dv PCATCH
354was set in the lock priority, and a signal was delivered during a sleep.
355Note the
356.Er ERESTART
357error below.
358.It Bq Er ERESTART
359.Dv PCATCH
360was set in the lock priority, a signal was delivered during a sleep,
361and the system call is to be restarted.
362.It Bq Er EWOULDBLOCK
363a non-zero timeout was given, and the timeout expired.
364.El
365.Sh LOCKS
366If
367.Dv LK_INTERLOCK
368is passed in the
369.Fa flags
370argument to
371.Fn lockmgr
372or
373.Fn lockmgr_rw ,
374the
375.Fa ilk
376must be held prior to calling
377.Fn lockmgr
378or
379.Fn lockmgr_rw ,
380and will be returned unlocked.
381.Pp
382Upgrade attempts that fail result in the loss of the lock that
383is currently held.
384Also, it is invalid to upgrade an
385exclusive lock, and a
386.Xr panic 9
387will be the result of trying.
388.Sh SEE ALSO
389.Xr condvar 9 ,
390.Xr locking 9 ,
391.Xr mutex 9 ,
392.Xr rwlock 9 ,
393.Xr sleep 9 ,
394.Xr sx 9 ,
395.Xr mtx_assert 9 ,
396.Xr panic 9 ,
397.Xr VOP_PRINT 9
398.Sh AUTHORS
399This manual page was written by
400.An Chad David Aq davidc@acns.ab.ca .
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: head/share/man/man9/lock.9 177962 2008-04-06 21:22:12Z attilio $
28.\"
29.Dd April 6, 2008
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 "struct lock *lkp"
64.Ft int
65.Fn lockmgr_recursed "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 "struct lock *lkp"
70.Ft int
71.Fn lockstatus "struct lock *lkp"
72.Pp
73.Cd "options INVARIANTS"
74.Cd "options INVARIANT_SUPPORT"
75.Ft void
76.Fn lockmgr_assert "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_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_CANRECURSE"
146.It Dv LK_SHARED
147Acquire a shared lock.
148If an exclusive lock is currently held, it will be downgraded.
149.It Dv LK_EXCLUSIVE
150Acquire an exclusive lock.
151If an exclusive lock is already held, and
152.Dv LK_CANRECURSE
153is not set, the system will
154.Xr panic 9 .
155.It Dv LK_DOWNGRADE
156Downgrade exclusive lock to a shared lock.
157Downgrading a shared lock is not permitted.
158If an exclusive lock has been recursed, all references will be downgraded.
159.It Dv LK_UPGRADE
160Upgrade a shared lock to an exclusive lock.
161If this call fails, the shared lock is lost.
162During the upgrade, the shared lock could
163be temporarily dropped.
164Attempts to upgrade an exclusive lock will cause a
165.Xr panic 9 .
166.It Dv LK_RELEASE
167Release the lock.
168Releasing a lock that is not held can cause a
169.Xr panic 9 .
170.It Dv LK_DRAIN
171Wait for all activity on the lock to end, then mark it decommissioned.
172This is used before freeing a lock that is part of a piece of memory that is
173about to be freed.
174(As documented in
175.In sys/lockmgr.h . )
176.It Dv LK_SLEEPFAIL
177Fail if operation has slept.
178.It Dv LK_NOWAIT
179Do not allow the call to sleep.
180This can be used to test the lock.
181.It Dv LK_CANRECURSE
182Allow recursion on an exclusive lock.
183For every lock there must be a release.
184.It Dv LK_INTERLOCK
185Unlock the interlock (which should be locked already).
186.El
187.It Fa ilk
188An interlock mutex for controlling group access to the lock.
189If
190.Dv LK_INTERLOCK
191is specified,
192.Fn lockmgr
193and
194.Fn lockmgr_rw
195assume
196.Fa ilk
197is currently owned and not recursed, and will return it unlocked.
198See
199.Xr mtx_assert 9 .
200.El
201.Pp
202The
203.Fn lockmgr_args
204and
205.Fn lockmgr_args_rw
206function work like
207.Fn lockmgr
208and
209.Fn lockmgr_rw
210but accepting a
211.Fa wmesg ,
212.Fa timo
213and
214.Fa prio
215on a per-instance basis.
216The specified values will override the default
217ones, but this can still be used passing, respectively,
218.Dv LK_WMESG_DEFAULT ,
219.Dv LK_PRIO_DEFAULT
220and
221.Dv LK_TIMO_DEFAULT .
222.Pp
223The
224.Fn lockmgr_disown
225function switches the owner from the current thread to be
226.Dv LK_KERNPROC,
227if the lock is already held.
228.Pp
229The
230.Fn lockmgr_printinfo
231function prints debugging information about the lock.
232It is used primarily by
233.Xr VOP_PRINT 9
234functions.
235.Pp
236The
237.Fn lockmgr_recursed
238function returns true if the lock is recursed, 0
239otherwise.
240.Pp
241The
242.Fn lockmgr_waiters
243function returns true if the lock has waiters, 0 otherwise.
244.Pp
245The
246.Fn lockstatus
247function returns the status of the lock in relation to the current thread.
248.Pp
249When compiled with
250.Cd "options INVARIANTS"
251and
252.Cd "options INVARIANT_SUPPORT" ,
253the
254.Fn lockmgr_assert
255function tests
256.Fa lkp
257for the assertions specified in
258.Fa what ,
259and panics if they are not met.
260One of the following assertions must be specified:
261.Bl -tag -width ".Dv KA_UNLOCKED"
262.It Dv KA_LOCKED
263Assert that the current thread has either a shared or an exclusive lock on the
264.Vt lkp
265lock pointed to by the first argument.
266.It Dv KA_SLOCKED
267Assert that the current thread has a shared lock on the
268.Vt lkp
269lock pointed to by the first argument.
270.It Dv KA_XLOCKED
271Assert that the current thread has an exclusive lock on the
272.Vt lkp
273lock pointed to by the first argument.
274.It Dv KA_UNLOCKED
275Assert that the current thread has no lock on the
276.Vt lkp
277lock pointed to by the first argument.
278.It Dv KA_HELD
279Assert that an unspecified thread has a lock on the
280.Vt lkp
281lock pointed to by the first argument.
282.It Dv KA_UNHELD
283Assert that no thread has a lock on the
284.Vt lkp
285lock pointed to by the first argument.
286.El
287.Pp
288In addition, one of the following optional assertions can be used with
289either an
290.Dv KA_LOCKED ,
291.Dv KA_SLOCKED ,
292or
293.Dv KA_XLOCKED
294assertion:
295.Bl -tag -width ".Dv KA_NOTRECURSED"
296.It Dv KA_RECURSED
297Assert that the current thread has a recursed lock on
298.Fa lkp .
299.It Dv KA_NOTRECURSED
300Assert that the current thread does not have a recursed lock on
301.Fa lkp .
302.El
303.Pp
304Note that
305.Dv KA_HELD
306and
307.Dv KA_UNHELD
308usage is highly discouraged.
309They are intended to cater a bad behaviour
310introduced by buffer cache lock handling.
311They will hopefully be
312made useless by revisiting such locks.
313.Sh RETURN VALUES
314The
315.Fn lockmgr
316and
317.Fn lockmgr_rw
318functions return 0 on success and non-zero on failure.
319.Pp
320The
321.Fn lockstatus
322function returns:
323.Bl -tag -width ".Dv LK_EXCLUSIVE"
324.It Dv LK_EXCLUSIVE
325An exclusive lock is held by the current thread.
326.It Dv LK_EXCLOTHER
327An exclusive lock is held by someone other than the current thread.
328.It Dv LK_SHARED
329A shared lock is held.
330.It Li 0
331The lock is not held by anyone.
332.El
333.Sh ERRORS
334.Fn lockmgr
335and
336.Fn lockmgr_rw
337fail if:
338.Bl -tag -width Er
339.It Bq Er EBUSY
340.Dv LK_FORCEUPGRADE
341was requested and another thread had already requested a lock upgrade.
342.It Bq Er EBUSY
343.Dv LK_NOWAIT
344was set, and a sleep would have been required.
345.It Bq Er ENOLCK
346.Dv LK_SLEEPFAIL
347was set and
348.Fn lockmgr
349or
350.Fn lockmgr_rw
351did sleep.
352.It Bq Er EINTR
353.Dv PCATCH
354was set in the lock priority, and a signal was delivered during a sleep.
355Note the
356.Er ERESTART
357error below.
358.It Bq Er ERESTART
359.Dv PCATCH
360was set in the lock priority, a signal was delivered during a sleep,
361and the system call is to be restarted.
362.It Bq Er EWOULDBLOCK
363a non-zero timeout was given, and the timeout expired.
364.El
365.Sh LOCKS
366If
367.Dv LK_INTERLOCK
368is passed in the
369.Fa flags
370argument to
371.Fn lockmgr
372or
373.Fn lockmgr_rw ,
374the
375.Fa ilk
376must be held prior to calling
377.Fn lockmgr
378or
379.Fn lockmgr_rw ,
380and will be returned unlocked.
381.Pp
382Upgrade attempts that fail result in the loss of the lock that
383is currently held.
384Also, it is invalid to upgrade an
385exclusive lock, and a
386.Xr panic 9
387will be the result of trying.
388.Sh SEE ALSO
389.Xr condvar 9 ,
390.Xr locking 9 ,
391.Xr mutex 9 ,
392.Xr rwlock 9 ,
393.Xr sleep 9 ,
394.Xr sx 9 ,
395.Xr mtx_assert 9 ,
396.Xr panic 9 ,
397.Xr VOP_PRINT 9
398.Sh AUTHORS
399This manual page was written by
400.An Chad David Aq davidc@acns.ab.ca .