| blob | fe244dfa6efa57aa8b5d34bbd2e2ca8abbb7cf8a |
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: src/share/man/man9/lock.9,v 1.11 2003/09/08 19:57:21 ru Exp $
28 .\"
29 .Dd November 25, 2017
30 .Dt LOCK 9
31 .Os
32 .Sh NAME
33 .Nm lockinit ,
34 .Nm lockmgr ,
35 .Nm lockstatus ,
36 .Nm lockmgr_printinfo ,
37 .Nm lockowned
38 .Nd "lockmgr family of functions"
39 .Sh SYNOPSIS
40 .In sys/types.h
41 .In sys/lock.h
42 .Ft void
43 .Fn lockinit "struct lock *lkp" "const char *wmesg" "int timo" "int flags"
44 .Ft void
45 .Fn lockuninit "struct lock *lkp"
46 .Ft int
47 .Fn lockmgr "struct lock *lkp" "u_int flags"
48 .Ft int
49 .Fn lockstatus "struct lock *lkp" "struct thread *td"
50 .Ft void
51 .Fn lockmgr_printinfo "struct lock *lkp"
52 .Ft int
53 .Fn lockowned "struct lock *lkp"
54 .Sh DESCRIPTION
55 The
56 .Fn lockinit
57 function is used to initialize a lock.
58 It must be called before any operation can be performed on a lock.
59 Its arguments are:
60 .Bl -tag -width ".Fa wmesg"
61 .It Fa lkp
62 A pointer to the lock to initialize.
63 .It Fa wmesg
64 The lock message.
65 This is used for both debugging output and
66 .Xr tsleep 9 .
67 .It Fa timo
68 The timeout value passed to
69 .Xr tsleep 9 .
70 .It Fa flags
71 The flags the lock is to be initialized with.
72 .Bl -tag -width ".Dv LK_CANRECURSE"
73 .It Dv LK_NOWAIT
74 Do not sleep while acquiring the lock.
75 .It Dv LK_SLEEPFAIL
76 Fail after a sleep.
77 .It Dv LK_CANRECURSE
78 Allow recursive exclusive locks.
79 .It Dv LK_TIMELOCK
80 Use
81 .Fa timo
82 during a sleep; otherwise, 0 is used.
83 .El
84 .El
85 .Pp
86 The
87 .Fn lockuninit
88 function destroys a lock that was previously initialized using
89 .Fn lockinit .
90 .Pp
91 The
92 .Fn lockmgr
93 function handles general locking functionality within the kernel, including
94 support for shared and exclusive locks, and recursion.
95 .Fn lockmgr
96 is also able to upgrade and downgrade locks.
97 .Pp
98 Its arguments are:
99 .Bl -tag -width ".Fa flags"
100 .It Fa lkp
101 A pointer to the lock to manipulate.
102 .It Fa flags
103 Flags indicating what action is to be taken.
104 .Bl -tag -width ".Dv LK_EXCLUPGRADE"
105 .It Dv LK_SHARED
106 Acquire a shared lock.
107 If an exclusive lock is currently held, it will be downgraded.
108 .It Dv LK_EXCLUSIVE
109 Acquire an exclusive lock.
110 If an exclusive lock is already held, and
111 .Dv LK_CANRECURSE
112 is not set, the system will
113 .Xr panic 9 .
114 .It Dv LK_DOWNGRADE
115 Downgrade exclusive lock to a shared lock.
116 Downgrading a shared lock is not permitted.
117 If an exclusive lock has been recursed, all references will be downgraded.
118 .It Dv LK_EXCLUPGRADE
119 Upgrade a shared lock to an exclusive lock.
120 Fails with
121 .Er EBUSY
122 if there is someone ahead of you in line waiting for an upgrade.
123 If this call fails for any reason, the shared lock is lost.
124 Attempts to upgrade an exclusive lock not already
125 owned by the caller will cause a
126 .Xr panic 9 ,
127 but otherwise will always succeed.
128 NOTE! When this operation succeeds, it guarantees that no other
129 exclusive lock was able to acquire the lock ahead of you, but
130 as indicated above, if it fails your current shared lock is lost.
131 .It Dv LK_UPGRADE
132 Upgrade a shared lock to an exclusive lock.
133 If this call fails for any reason, the shared lock is lost.
134 Attempts to upgrade an exclusive lock not already
135 owned by the caller will cause a
136 .Xr panic 9 ,
137 but otherwise will always succeed.
138 WARNING! This operation can block with the current lock temporarily
139 released, and other exclusive or shared lock holders can inject before
140 the lock is acquired on your behalf.
141 .It Dv LK_RELEASE
142 Release the lock.
143 Releasing a lock that is not held can cause a
144 .Xr panic 9 .
145 .It Dv LK_SLEEPFAIL
146 Fail if operation has slept.
147 .It Dv LK_NOWAIT
148 Do not allow the call to sleep.
149 This can be used to test the lock.
150 .It Dv LK_CANRECURSE
151 Allow recursion on an exclusive lock.
152 For every lock there must be a release.
153 .El
154 .El
155 .Pp
156 The
157 .Fn lockstatus
158 function returns the status of the lock in relation to the
159 .Vt thread
160 passed to it.
161 Note that if
162 .Fa td
163 is
164 .Dv NULL
165 and an exclusive lock is held,
166 .Dv LK_EXCLUSIVE
167 will be returned.
168 .Pp
169 The
170 .Fn lockmgr_printinfo
171 function prints debugging information about the lock.
172 It is used primarily by
173 .Xr VOP_PRINT 9
174 functions.
175 .Pp
176 The
177 .Fn lockowned
178 function is used to determine whether the calling thread owns a lock.
179 .Sh RETURN VALUES
180 The
181 .Fn lockmgr
182 function returns 0 on success and non-zero on failure.
183 .Pp
184 The
185 .Fn lockstatus
186 function returns:
187 .Bl -tag -width ".Dv LK_EXCLUSIVE"
188 .It Dv LK_EXCLUSIVE
189 An exclusive lock is held by the thread
190 .Fa td .
191 .It Dv LK_EXCLOTHER
192 An exclusive lock is held by someone other than the thread
193 .Fa td .
194 .It Dv LK_SHARED
195 A shared lock is held.
196 .It Li 0
197 The lock is not held by anyone.
198 .El
199 .Pp
200 The
201 .Fn lockowned
202 function returns a non-zero return value if the caller owns the lock shared or exclusive.
203 .Sh FILES
204 The lock manager itself is implemented within the file
205 .Pa /sys/kern/kern_lock.c .
206 Data structures and function prototypes for the lock manager are in
207 .Pa /sys/sys/lock.h .
208 .Sh ERRORS
209 .Fn lockmgr
210 fails if:
211 .Bl -tag -width Er
212 .It Bq Er EBUSY
213 .Dv LK_NOWAIT
214 was set, and a sleep would have been required.
215 .It Bq Er ENOLCK
216 .Dv LK_SLEEPFAIL
217 was set and
218 .Fn lockmgr
219 did sleep.
220 .It Bq Er EINTR
221 .Dv PCATCH
222 was set in the lock priority, and a signal was delivered during a sleep.
223 Note the
224 .Er ERESTART
225 error below.
226 .It Bq Er ERESTART
227 .Dv PCATCH
228 was set in the lock priority, a signal was delivered during a sleep,
229 and the system call is to be restarted.
230 .It Bq Er EWOULDBLOCK
231 a non-zero timeout was given, and the timeout expired.
232 .El
233 .Sh LOCKS
234 Upgrade attempts that fail result in the loss of the lock that
235 is currently held.
236 Also, it is invalid to upgrade an
237 exclusive lock, and a
238 .Xr panic 9
239 will be the result of trying.
240 .Sh SEE ALSO
241 .Xr locking 9 ,
242 .Xr panic 9 ,
243 .Xr tsleep 9 ,
244 .Xr VOP_PRINT 9
245 .Sh HISTORY
246 The lock manager appeared in
247 .Dx 1.0 .
248 .Pp
249 The lock manager API first appeared in
250 .Bx 4.4 lite2 .
251 .Sh AUTHORS
252 This man page was written by
253 .An Chad David Aq Mt davidc@acns.ab.ca .