xref: /freebsd/share/man/man9/lock.9 (revision 06e361fb0e6e3a82ffd2ba89b73f6038579e5449)
1e5e600c9SMark Murray.\"
25385e8bfSChad David.\" Copyright (C) 2002 Chad David <davidc@acns.ab.ca>. All rights reserved.
3e5e600c9SMark Murray.\"
4e5e600c9SMark Murray.\" Redistribution and use in source and binary forms, with or without
5e5e600c9SMark Murray.\" modification, are permitted provided that the following conditions
6e5e600c9SMark Murray.\" are met:
7e5e600c9SMark Murray.\" 1. Redistributions of source code must retain the above copyright
85385e8bfSChad David.\"    notice(s), this list of conditions and the following disclaimer as
95385e8bfSChad David.\"    the first lines of this file unmodified other than the possible
105385e8bfSChad David.\"    addition of one or more copyright notices.
11e5e600c9SMark Murray.\" 2. Redistributions in binary form must reproduce the above copyright
125385e8bfSChad David.\"    notice(s), this list of conditions and the following disclaimer in the
13e5e600c9SMark Murray.\"    documentation and/or other materials provided with the distribution.
14e5e600c9SMark Murray.\"
155385e8bfSChad David.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
165385e8bfSChad David.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
175385e8bfSChad David.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
185385e8bfSChad David.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
195385e8bfSChad David.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
205385e8bfSChad David.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
215385e8bfSChad David.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
225385e8bfSChad David.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
235385e8bfSChad David.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
245385e8bfSChad David.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
255385e8bfSChad David.\" DAMAGE.
26e5e600c9SMark Murray.\"
27e5e600c9SMark Murray.\" $FreeBSD$
28e5e600c9SMark Murray.\"
29008f392eSAttilio Rao.Dd March 1, 2008
30e5e600c9SMark Murray.Dt LOCK 9
313d45e180SRuslan Ermilov.Os
32e5e600c9SMark Murray.Sh NAME
33e5e600c9SMark Murray.Nm lockinit ,
345385e8bfSChad David.Nm lockdestroy ,
355385e8bfSChad David.Nm lockmgr ,
367f527abcSAttilio Rao.Nm lockmgr_args ,
37fc2d483eSAttilio Rao.Nm lockmgr_disown ,
38fa885265SAttilio Rao.Nm lockmgr_printinfo ,
39f0c5fe2dSAttilio Rao.Nm lockmgr_recursed ,
4078a25172SAttilio Rao.Nm lockstatus ,
41f0c5fe2dSAttilio Rao.Nm lockmgr_assert
425385e8bfSChad David.Nd "lockmgr family of functions"
43e5e600c9SMark Murray.Sh SYNOPSIS
4432eef9aeSRuslan Ermilov.In sys/types.h
45008f392eSAttilio Rao.In sys/lock.h
465385e8bfSChad David.In sys/lockmgr.h
47e5e600c9SMark Murray.Ft void
48c4a7ba6eSChad David.Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags"
495385e8bfSChad David.Ft void
505385e8bfSChad David.Fn lockdestroy "struct lock *lkp"
51e5e600c9SMark Murray.Ft int
52623c393dSAttilio Rao.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp"
535385e8bfSChad David.Ft int
547f527abcSAttilio Rao.Fn lockmgr_args "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "const char *wmesg" "int prio" "int timo"
555385e8bfSChad David.Ft void
56fc2d483eSAttilio Rao.Fn lockmgr_disown "struct lock *lkp"
57fc2d483eSAttilio Rao.Ft void
585385e8bfSChad David.Fn lockmgr_printinfo "struct lock *lkp"
59fa885265SAttilio Rao.Ft int
60fa885265SAttilio Rao.Fn lockmgr_recursed "struct lock *lkp"
617f527abcSAttilio Rao.Ft int
627f527abcSAttilio Rao.Fn lockstatus "struct lock *lkp"
63f0c5fe2dSAttilio Rao.Pp
64f0c5fe2dSAttilio Rao.Cd "options INVARIANTS"
65f0c5fe2dSAttilio Rao.Cd "options INVARIANT_SUPPORT"
66f0c5fe2dSAttilio Rao.Ft void
67f0c5fe2dSAttilio Rao.Fn lockmgr_assert "struct lock *lkp" "int what"
68e5e600c9SMark Murray.Sh DESCRIPTION
695385e8bfSChad DavidThe
70e5e600c9SMark Murray.Fn lockinit
715385e8bfSChad Davidfunction is used to initialize a lock.
72ffa23792SChad DavidIt must be called before any operation can be performed on a lock.
735385e8bfSChad DavidIts arguments are:
745385e8bfSChad David.Bl -tag -width ".Fa wmesg"
755385e8bfSChad David.It Fa lkp
765385e8bfSChad DavidA pointer to the lock to initialize.
775385e8bfSChad David.It Fa prio
785385e8bfSChad DavidThe priority passed to
79e7573e7aSJohn Baldwin.Xr sleep 9 .
805385e8bfSChad David.It Fa wmesg
815385e8bfSChad DavidThe lock message.
825385e8bfSChad DavidThis is used for both debugging output and
83e7573e7aSJohn Baldwin.Xr sleep 9 .
845385e8bfSChad David.It Fa timo
855385e8bfSChad DavidThe timeout value passed to
86e7573e7aSJohn Baldwin.Xr sleep 9 .
875385e8bfSChad David.It Fa flags
88008f392eSAttilio RaoThe flags the lock is to be initialized with:
89abd94b3dSAttilio Rao.Bl -tag -width ".Dv LK_CANRECURSE"
905385e8bfSChad David.It Dv LK_CANRECURSE
915385e8bfSChad DavidAllow recursive exclusive locks.
92008f392eSAttilio Rao.It Dv LK_NOPROFILE
93008f392eSAttilio RaoDisable lock profiling for this lock.
94f3a331b7SMaxim Konovalov.It Dv LK_NOSHARE
95f3a331b7SMaxim KonovalovAllow exclusive locks only.
96abd94b3dSAttilio Rao.It Dv LK_NOWITNESS
97abd94b3dSAttilio RaoInstruct
98abd94b3dSAttilio Rao.Xr witness 4
99abd94b3dSAttilio Raoto ignore this lock.
100abd94b3dSAttilio Rao.It Dv LK_NODUP
101abd94b3dSAttilio Rao.Xr witness 4
102abd94b3dSAttilio Raoshould log messages about duplicate locks being acquired.
103008f392eSAttilio Rao.It Dv LK_QUIET
104008f392eSAttilio RaoDisable
105008f392eSAttilio Rao.Xr ktr 4
106008f392eSAttilio Raologging for this lock.
1075385e8bfSChad David.It Dv LK_TIMELOCK
1085385e8bfSChad DavidUse
1095385e8bfSChad David.Fa timo
1105385e8bfSChad Davidduring a sleep; otherwise, 0 is used.
1115385e8bfSChad David.El
1125385e8bfSChad David.El
113e5e600c9SMark Murray.Pp
1145385e8bfSChad DavidThe
1155385e8bfSChad David.Fn lockdestroy
1165385e8bfSChad Davidfunction is used to destroy a lock, and while it is called in a number of
1175385e8bfSChad Davidplaces in the kernel, it currently does nothing.
1185385e8bfSChad David.Pp
1195385e8bfSChad DavidThe
1205385e8bfSChad David.Fn lockmgr
1215385e8bfSChad Davidfunction handles general locking functionality within the kernel, including
1225385e8bfSChad Davidsupport for shared and exclusive locks, and recursion.
1235385e8bfSChad David.Fn lockmgr
1245385e8bfSChad Davidis also able to upgrade and downgrade locks.
1255385e8bfSChad David.Pp
1265385e8bfSChad DavidIts arguments are:
1275385e8bfSChad David.Bl -tag -width ".Fa interlkp"
1285385e8bfSChad David.It Fa lkp
1295385e8bfSChad DavidA pointer to the lock to manipulate.
1305385e8bfSChad David.It Fa flags
1315385e8bfSChad DavidFlags indicating what action is to be taken.
132100f2415SAttilio Rao.Bl -tag -width ".Dv LK_CANRECURSE"
133e5e600c9SMark Murray.It Dv LK_SHARED
1345385e8bfSChad DavidAcquire a shared lock.
1355385e8bfSChad DavidIf an exclusive lock is currently held, it will be downgraded.
136e5e600c9SMark Murray.It Dv LK_EXCLUSIVE
1375385e8bfSChad DavidAcquire an exclusive lock.
1385385e8bfSChad DavidIf an exclusive lock is already held, and
1398271a102SRuslan Ermilov.Dv LK_CANRECURSE
1405385e8bfSChad Davidis not set, the system will
1415385e8bfSChad David.Xr panic 9 .
142e5e600c9SMark Murray.It Dv LK_DOWNGRADE
1435385e8bfSChad DavidDowngrade exclusive lock to a shared lock.
1445385e8bfSChad DavidDowngrading a shared lock is not permitted.
1455385e8bfSChad DavidIf an exclusive lock has been recursed, all references will be downgraded.
1465385e8bfSChad David.It Dv LK_UPGRADE
1475385e8bfSChad DavidUpgrade a shared lock to an exclusive lock.
1485385e8bfSChad DavidIf this call fails, the shared lock is lost.
149653ed924SKonstantin BelousovDuring the upgrade, the shared lock could
150653ed924SKonstantin Belousovbe temporarily dropped.
151ffa23792SChad DavidAttempts to upgrade an exclusive lock will cause a
1525385e8bfSChad David.Xr panic 9 .
153e5e600c9SMark Murray.It Dv LK_RELEASE
1545385e8bfSChad DavidRelease the lock.
1555385e8bfSChad DavidReleasing a lock that is not held can cause a
1565385e8bfSChad David.Xr panic 9 .
157e5e600c9SMark Murray.It Dv LK_DRAIN
1585385e8bfSChad DavidWait for all activity on the lock to end, then mark it decommissioned.
1595385e8bfSChad DavidThis is used before freeing a lock that is part of a piece of memory that is
1605385e8bfSChad Davidabout to be freed.
1615385e8bfSChad David(As documented in
162fe08efe6SRuslan Ermilov.In sys/lockmgr.h . )
1635385e8bfSChad David.It Dv LK_SLEEPFAIL
1645385e8bfSChad DavidFail if operation has slept.
1655385e8bfSChad David.It Dv LK_NOWAIT
1665385e8bfSChad DavidDo not allow the call to sleep.
1675385e8bfSChad DavidThis can be used to test the lock.
1685385e8bfSChad David.It Dv LK_CANRECURSE
1695385e8bfSChad DavidAllow recursion on an exclusive lock.
1705385e8bfSChad DavidFor every lock there must be a release.
1715385e8bfSChad David.It Dv LK_INTERLOCK
1725385e8bfSChad DavidUnlock the interlock (which should be locked already).
173e5e600c9SMark Murray.El
1745385e8bfSChad David.It Fa interlkp
1755385e8bfSChad DavidAn interlock mutex for controlling group access to the lock.
1765385e8bfSChad DavidIf
1775385e8bfSChad David.Dv LK_INTERLOCK
1785385e8bfSChad Davidis specified,
1795385e8bfSChad David.Fn lockmgr
1805385e8bfSChad Davidassumes
1815385e8bfSChad David.Fa interlkp
1825385e8bfSChad Davidis currently owned and not recursed, and will return it unlocked.
1835385e8bfSChad DavidSee
1845385e8bfSChad David.Xr mtx_assert 9 .
1855385e8bfSChad David.El
1865385e8bfSChad David.Pp
1875385e8bfSChad DavidThe
1887f527abcSAttilio Rao.Fn lockmgr_args
1897f527abcSAttilio Raofunction works like
1907f527abcSAttilio Rao.Fn lockmgr
1917f527abcSAttilio Raobut accepting a
1927f527abcSAttilio Rao.Fa wmesg ,
1937f527abcSAttilio Rao.Fa timo
1947f527abcSAttilio Raoand
1957f527abcSAttilio Rao.Fa prio
19606e361fbSChristian Bruefferon a per-instance basis.
19706e361fbSChristian BruefferThe specified values will override the default
1987f527abcSAttilio Raoones, but this can still be used passing, respectively,
1997f527abcSAttilio Rao.Dv LK_WMESG_DEFAULT ,
2007f527abcSAttilio Rao.Dv LK_PRIO_DEFAULT
2017f527abcSAttilio Raoand
2027f527abcSAttilio Rao.Dv LK_TIMO_DEFAULT .
2035385e8bfSChad David.Pp
2045385e8bfSChad DavidThe
205fc2d483eSAttilio Rao.Fn lockmgr_disown
2063220cdf4SAttilio Raofunction switches the owner from the current thread to be
207fc2d483eSAttilio Rao.Dv LK_KERNPROC,
208584b5892SChristian Bruefferif the lock is already held.
209fc2d483eSAttilio Rao.Pp
210fc2d483eSAttilio RaoThe
2115385e8bfSChad David.Fn lockmgr_printinfo
2125385e8bfSChad Davidfunction prints debugging information about the lock.
2135385e8bfSChad DavidIt is used primarily by
2145385e8bfSChad David.Xr VOP_PRINT 9
2155385e8bfSChad Davidfunctions.
216fa885265SAttilio Rao.Pp
217fa885265SAttilio RaoThe
218fa885265SAttilio Rao.Fn lockmgr_recursed
219fa885265SAttilio Raofunction returns true if the lock is recursed, 0
220fa885265SAttilio Raootherwise.
221f0c5fe2dSAttilio Rao.Pp
2227f527abcSAttilio RaoThe
2237f527abcSAttilio Rao.Fn lockstatus
2247f527abcSAttilio Raofunction returns the status of the lock in relation to the current thread.
2257f527abcSAttilio Rao.Pp
226f0c5fe2dSAttilio RaoWhen compiled with
227f0c5fe2dSAttilio Rao.Cd "options INVARIANTS"
228f0c5fe2dSAttilio Raoand
229f0c5fe2dSAttilio Rao.Cd "options INVARIANT_SUPPORT" ,
230f0c5fe2dSAttilio Raothe
231f0c5fe2dSAttilio Rao.Fn lockmgr_assert
232f0c5fe2dSAttilio Raofunction tests
233f0c5fe2dSAttilio Rao.Fa lkp
234f0c5fe2dSAttilio Raofor the assertions specified in
235f0c5fe2dSAttilio Rao.Fa what ,
236f0c5fe2dSAttilio Raoand panics if they are not met.
237f0c5fe2dSAttilio RaoOne of the following assertions must be specified:
238f0c5fe2dSAttilio Rao.Bl -tag -width ".Dv KA_UNLOCKED"
239f0c5fe2dSAttilio Rao.It Dv KA_LOCKED
240f0c5fe2dSAttilio RaoAssert that the current thread has either a shared or an exclusive lock on the
241f0c5fe2dSAttilio Rao.Vt lkp
242f0c5fe2dSAttilio Raolock pointed to by the first argument.
243f0c5fe2dSAttilio Rao.It Dv KA_SLOCKED
244f0c5fe2dSAttilio RaoAssert that the current thread has a shared lock on the
245f0c5fe2dSAttilio Rao.Vt lkp
246f0c5fe2dSAttilio Raolock pointed to by the first argument.
247f0c5fe2dSAttilio Rao.It Dv KA_XLOCKED
248f0c5fe2dSAttilio RaoAssert that the current thread has an exclusive lock on the
249f0c5fe2dSAttilio Rao.Vt lkp
250f0c5fe2dSAttilio Raolock pointed to by the first argument.
251f0c5fe2dSAttilio Rao.It Dv KA_UNLOCKED
252f0c5fe2dSAttilio RaoAssert that the current thread has no lock on the
253f0c5fe2dSAttilio Rao.Vt lkp
254f0c5fe2dSAttilio Raolock pointed to by the first argument.
255f0c5fe2dSAttilio Rao.It Dv KA_HELD
256af176d73SChristian BruefferAssert that an unspecified thread has a lock on the
257f0c5fe2dSAttilio Rao.Vt lkp
258f0c5fe2dSAttilio Raolock pointed to by the first argument.
259f0c5fe2dSAttilio Rao.It Dv KA_UNHELD
260f0c5fe2dSAttilio RaoAssert that no thread has a lock on the
261f0c5fe2dSAttilio Rao.Vt lkp
262f0c5fe2dSAttilio Raolock pointed to by the first argument.
263f0c5fe2dSAttilio Rao.El
264f0c5fe2dSAttilio Rao.Pp
265f0c5fe2dSAttilio RaoIn addition, one of the following optional assertions can be used with
266f0c5fe2dSAttilio Raoeither an
267f0c5fe2dSAttilio Rao.Dv KA_LOCKED ,
268f0c5fe2dSAttilio Rao.Dv KA_SLOCKED ,
269f0c5fe2dSAttilio Raoor
270f0c5fe2dSAttilio Rao.Dv KA_XLOCKED
271f0c5fe2dSAttilio Raoassertion:
272f0c5fe2dSAttilio Rao.Bl -tag -width ".Dv KA_NOTRECURSED"
273f0c5fe2dSAttilio Rao.It Dv KA_RECURSED
274f0c5fe2dSAttilio RaoAssert that the current thread has a recursed lock on
275f0c5fe2dSAttilio Rao.Fa lkp .
276f0c5fe2dSAttilio Rao.It Dv KA_NOTRECURSED
277af176d73SChristian BruefferAssert that the current thread does not have a recursed lock on
278f0c5fe2dSAttilio Rao.Fa lkp .
279f0c5fe2dSAttilio Rao.El
280f0c5fe2dSAttilio Rao.Pp
281af176d73SChristian BruefferNote that
282f0c5fe2dSAttilio Rao.Dv KA_HELD
283f0c5fe2dSAttilio Raoand
284f0c5fe2dSAttilio Rao.Dv KA_UNHELD
285af176d73SChristian Bruefferusage is highly discouraged.
286af176d73SChristian BruefferThey are intended to cater a bad behaviour
287af176d73SChristian Bruefferintroduced by buffer cache lock handling.
288af176d73SChristian BruefferThey will hopefully be
289f0c5fe2dSAttilio Raomade useless by revisiting such locks.
290e5e600c9SMark Murray.Sh RETURN VALUES
2915385e8bfSChad DavidThe
2925385e8bfSChad David.Fn lockmgr
2935385e8bfSChad Davidfunction returns 0 on success and non-zero on failure.
2945385e8bfSChad David.Pp
2955385e8bfSChad DavidThe
2965385e8bfSChad David.Fn lockstatus
2975385e8bfSChad Davidfunction returns:
2985385e8bfSChad David.Bl -tag -width ".Dv LK_EXCLUSIVE"
2995385e8bfSChad David.It Dv LK_EXCLUSIVE
3003220cdf4SAttilio RaoAn exclusive lock is held by the current thread.
3015385e8bfSChad David.It Dv LK_EXCLOTHER
3023220cdf4SAttilio RaoAn exclusive lock is held by someone other than the current thread.
3035385e8bfSChad David.It Dv LK_SHARED
3045385e8bfSChad DavidA shared lock is held.
3055385e8bfSChad David.It Li 0
3065385e8bfSChad DavidThe lock is not held by anyone.
3075385e8bfSChad David.El
3085385e8bfSChad David.Sh ERRORS
3095385e8bfSChad David.Fn lockmgr
3105385e8bfSChad Davidfails if:
3115385e8bfSChad David.Bl -tag -width Er
3125385e8bfSChad David.It Bq Er EBUSY
3138271a102SRuslan Ermilov.Dv LK_FORCEUPGRADE
3145385e8bfSChad Davidwas requested and another thread had already requested a lock upgrade.
3155385e8bfSChad David.It Bq Er EBUSY
3165385e8bfSChad David.Dv LK_NOWAIT
3175385e8bfSChad Davidwas set, and a sleep would have been required.
3185385e8bfSChad David.It Bq Er ENOLCK
3198271a102SRuslan Ermilov.Dv LK_SLEEPFAIL
3205385e8bfSChad Davidwas set and
3215385e8bfSChad David.Fn lockmgr
3225385e8bfSChad Daviddid sleep.
3235385e8bfSChad David.It Bq Er EINTR
3248271a102SRuslan Ermilov.Dv PCATCH
3255385e8bfSChad Davidwas set in the lock priority, and a signal was delivered during a sleep.
3265385e8bfSChad DavidNote the
327e5e600c9SMark Murray.Er ERESTART
3285385e8bfSChad Daviderror below.
3295385e8bfSChad David.It Bq Er ERESTART
3305385e8bfSChad David.Dv PCATCH
3315385e8bfSChad Davidwas set in the lock priority, a signal was delivered during a sleep,
3325385e8bfSChad Davidand the system call is to be restarted.
3335385e8bfSChad David.It Bq Er EWOULDBLOCK
3345385e8bfSChad Davida non-zero timeout was given, and the timeout expired.
3355385e8bfSChad David.El
3365385e8bfSChad David.Sh LOCKS
3375385e8bfSChad DavidIf
3385385e8bfSChad David.Dv LK_INTERLOCK
3395385e8bfSChad Davidis passed in the
3405385e8bfSChad David.Fa flags
3415385e8bfSChad Davidargument to
3425385e8bfSChad David.Fn lockmgr ,
3435385e8bfSChad Davidthe
3445385e8bfSChad David.Fa interlkp
3455385e8bfSChad Davidmust be held prior to calling
3465385e8bfSChad David.Fn lockmgr ,
3475385e8bfSChad Davidand will be returned unlocked.
3485385e8bfSChad David.Pp
3495385e8bfSChad DavidUpgrade attempts that fail result in the loss of the lock that
3505385e8bfSChad Davidis currently held.
3515385e8bfSChad DavidAlso, it is invalid to upgrade an
3525385e8bfSChad Davidexclusive lock, and a
3535385e8bfSChad David.Xr panic 9
3545385e8bfSChad Davidwill be the result of trying.
3555385e8bfSChad David.Sh SEE ALSO
356a280550aSJulian Elischer.Xr condvar 9 ,
357a280550aSJulian Elischer.Xr locking 9 ,
358a280550aSJulian Elischer.Xr mutex 9 ,
359a280550aSJulian Elischer.Xr rwlock 9 ,
360e7573e7aSJohn Baldwin.Xr sleep 9 ,
361a280550aSJulian Elischer.Xr sx 9 ,
3625385e8bfSChad David.Xr mtx_assert 9 ,
3635385e8bfSChad David.Xr panic 9 ,
3645385e8bfSChad David.Xr VOP_PRINT 9
3655385e8bfSChad David.Sh AUTHORS
366571dba6eSHiten PandyaThis manual page was written by
3675385e8bfSChad David.An Chad David Aq davidc@acns.ab.ca .
368