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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
.\" $OpenBSD: lock.9,v 1.22 2014/07/09 14:16:10 guenther Exp $
.\" $NetBSD: lock.9,v 1.12 2001/11/01 01:13:43 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" 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, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, 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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``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 FOUNDATION OR CONTRIBUTORS
.\" 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.
.\"
.Dd $Mdocdate: July 9 2014 $
.Dt LOCK 9
.Os
.Sh NAME
.Nm lock ,
.Nm lockinit ,
.Nm lockmgr ,
.Nm lockstatus
.Nd kernel lock functions
.Sh SYNOPSIS
.In sys/lock.h
.Ft void
.Fn lockinit "struct lock *lock" "int prio" "const char *wmesg" \
"int timo" "int flags"
.Ft int
.Fn lockmgr "struct lock *lock" "u_int flags" "struct simplelock *slock"
.Ft int
.Fn lockstatus "struct lock *lock"
.Sh DESCRIPTION
The
.Nm
functions provide synchronisation in the kernel by preventing multiple
processes from simultaneously executing critical sections of code
accessing shared data.
.Pp
struct lock supports sleeping until the lock can be acquired.
The lock manager supplies both exclusive-access and
shared-access locks, with recursive exclusive-access locks within a
single process.
It also allows upgrading a shared-access lock to an
exclusive-access lock, as well as downgrading an exclusive-access lock
to a shared-access lock.
.Pp
If the kernel option LOCKDEBUG is enabled, additional facilities
are provided to record additional lock information.
These facilities are provided to assist in determining deadlock occurrences.
.Sh FUNCTIONS
The functions which operate on locks are:
.Bl -tag -width Ds
.It Fn lockinit "lock" "prio" "wmesg" "timo" "flags"
The lock
.Fa lock
is initialised according to the parameters provided.
Arguments are as follows:
.Pp
.Bl -tag -width Ds -compact
.It Fa lock
The lock.
.It Fa prio
The process priority when it is woken up after sleeping on the lock.
.It Fa wmesg
A sleep message used when a process goes to sleep waiting for the lock, so
that the exact reason it is sleeping can easily be identified.
.It Fa timo
The maximum sleep time.
Used by
.Xr tsleep 9 .
.It Fa flags
Flags to specify the lock behaviour permanently over the lifetime of
the lock.
Valid lock flags are:
.Pp
.Bl -tag -width "LK_CANRECURSEXX" -compact
.It LK_NOWAIT
Processes should not sleep when attempting to acquire the lock.
.It LK_CANRECURSE
Processes can acquire the lock recursively.
.El
.El
.It Fn lockmgr "lock" "flags" "slock"
Set, change or release a lock according to the parameters provided.
Arguments are as follows:
.Pp
.Bl -tag -width Ds -compact
.It Fa lock
The lock.
.It Fa flags
Flags to specify the lock request type.
In addition to the flags specified above, the following flags are valid:
.Bl -tag -width Ds
.It LK_SHARED
Get one of many possible shared-access locks.
If a process holding an exclusive-access lock requests a shared-access lock,
the exclusive-access lock is downgraded to a shared-access lock.
.It LK_EXCLUSIVE
Stop further shared-access locks, when they are cleared, grant a
pending upgrade if it exists, then grant an exclusive-access lock.
Only one exclusive-access lock may exist at a time, except that a
process holding an exclusive-access lock may get additional
exclusive-access locks if it explicitly sets the LK_CANRECURSE flag in
the lock request, or if the LK_CANRECURSE flag was set when the lock
was initialised.
.It LK_RELEASE
Release one instance of a lock.
.It LK_DRAIN
Wait for all activity on the lock to end, then mark it decommissioned.
This feature is used before freeing a lock that is part of a piece of
memory that is about to be freed.
.It LK_RECURSEFAIL
Attempt at recursive lock fails.
.El
.Pp
.It Fa slock
This argument exists for legacy reasons, it is now ignored.
.El
.It Fn lockstatus "lock"
Returns the current state of lock
.Fa lock .
.Pp
.Bl -tag -width "LK_EXCLUSIVE" -offset indent -compact
.It Dv LK_EXCLUSIVE
Lock is locked for exclusive-access by the calling thread.
.It Dv LK_EXCLOTHER
Lock is locked for exclusive-access by a different thread.
.It Dv LK_SHARED
Lock is locked for shared-access.
The current thread may be one of the threads that has it locked.
.It 0
Lock is not locked.
.El
.El
.Sh RETURN VALUES
Successfully acquired locks return 0.
A failed lock attempt always returns a non-zero error value.
No lock is held after an error return.
Locks will always succeed unless one of the following is true:
.Bl -tag -width Er
.It Bq Er EBUSY
LK_NOWAIT is set and a sleep would be required.
.It Bq Er EINTR
PCATCH is set in lock priority and a signal arrives to interrupt
a system call.
.It Bq Er ERESTART
PCATCH is set in lock priority and a signal arrives so that
the system call is restarted.
.It Bq Er EWOULDBLOCK
Non-null lock timeout and timeout expires.
.El
.Sh SEE ALSO
.Xr mutex 9 ,
.Xr pmap 9 ,
.Xr rwlock 9 ,
.Xr spl 9 ,
.Xr tsleep 9 ,
.Xr uvm 9
.Sh HISTORY
The kernel locking API first appeared in
.Bx 4.4 lite2 .
It was progressively deprecated in favor of
.Xr rwlock 9 .
|
