1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
.\"
.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
.\" DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd July 9, 2001
.Dt LOCKMGR 9
.Os
.Sh NAME
.Nm lockmgr
.Nd "acquires, releases and updates locks"
.Sh SYNOPSIS
.In sys/types.h
.In sys/lockmgr.h
.Ft int
.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "struct proc *p"
.Sh DESCRIPTION
The
.Fn lockmgr
function handles general locking functionality within the kernel, including
support for shared and exclusive locks, and recursion.
Locks can also be upgraded and downgraded.
.Pp
Its arguments are:
.Bl -tag -xwidth ".Fa interlkp"
.It Fa lkp
A pointer to lock to manipulate.
.It Fa flags
Flags indicating what action is to be taken.
.Bl -tag -xwidth ".Dv LK_EXCLUPGRADE"
.It Dv LK_SHARED
Aquire a shared lock.
If we currently hold an exclusive lock it will be downgraded.
.It Dv LK_EXCLUSIVE
Aquire an exclusive lock.
If we already hold an exclusive lock and
.Dv LK_CANRECURSE
is not set we will panic.
.It Dv LK_DOWNGRADE
Downgrade our exclusive lock to a shared lock.
Downgrading a shared lock is not valid.
If the exclusive lock has been recursed, all references will
be downgraded.
.It Dv LK_EXCLUPGRADE
Upgrade our lock to an exclusive lock.
Will fail with
.Er EBUSY
if there is someone ahead of use waiting for an upgrade.
If this call fails we loose
our shared lock.
Upgrading an exclusive lock will cause a panic.
.It Dv LK_UPGRADE
Upgrades our lock to an exclusive lock.
If this call fails we loose
our shared lock.
Upgrading an exclusive lock will cause a panic.
.It Dv LK_RELEASE
Release the lock.
Releasing a lock that you do not hold can cause
a panic.
.It Dv LK_DRAIN
Waits for all activity on the lock to end, and then marks it decommissioned.
This is used before freeing a lock that is part of a piece of memory that is about to
be freed.
(As documented in
.Pa lockmgr.h . )
.It Dv LK_SLEEPFAIL
If we had to sleep for the lock then fail.
.It Dv LK_NOWAIT
Do not allow the call to sleep.
This can be used to test the lock.
.It Dv LK_CANRECURSE
It is ok to recurse on an exclusive lock.
For every lock there
must be a release.
.It Dv LK_INTERLOCK
Unlock the interlock, which is of course locked already.
.El
.It Fa interlkp
An interlock mutex for controlling group access to the lock.
If
.Dv LK_INTERLOCK
is specified,
.Fn lockmgr
assumes
.Fa interlkp
is currently owned and not recursed, and will return it unlocked.
See
.Xr mtx_assert 9 .
.It Fa p
The process responsible for this call.
.Dv NULL
becomes
.Dv LK_KERNPROC .
.El
.Sh LOCKS
If
.Dv LK_INTERLOCK
is specified then
.Fa interlkp
must be held prior to calling
.Fn lockmgr
and will be returned unlocked.
.Pp
Upgrade attempts that fail result in the loss of the lock that
is currently held.
As well, it is not valid to upgrade an
exclusive lock, and a panic will be the result of trying.
.Sh RETURN VALUES
A value of 0 is returned on success.
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EBUSY
Either
.Dv LK_NOWAIT
was specified and
.Fn lockmgr
would have slept, or another
process was ahead of you in line for an exclusive upgrade.
.It Bq Er ENOLCK
.Dv LK_SLEEP_FAIL
was set and we slept.
.El
.Sh SEE ALSO
.Xr lockcount 9 ,
.Xr lockdestroy 9 ,
.Xr lockmgr_printinfo 9 ,
.Xr lockstatus 9 ,
.Xr mutex 9
.Sh AUTHORS
This man page was written by
.An Chad David .
|
