| blob | c6570886e91e811ac403caa48860aa2a86e22ea8 |
1 .\" Copyright 2006 John-Mark Gurney
2 .\" 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, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\"
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD$
26 .\"
27 .Dd December 28, 2006
28 .Dt KQUEUE 9
29 .Os
30 .Sh NAME
31 .Nm kqueue_add_filteropts , kqueue_del_filteropts ,
32 .Nm kqfd_register ,
33 .Nm knote_fdclose ,
34 .Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty ,
35 .Nm knlist_init , knlist_destroy , knlist_clear , knlist_delete ,
36 .Nm KNOTE_LOCKED , KNOTE_UNLOCKED
37 .Nd "event delivery subsystem"
38 .Sh SYNOPSIS
39 .In sys/event.h
40 .Ft int
41 .Fn kqueue_add_filteropts "int filt" "struct filterops *filtops"
42 .Ft int
43 .Fn kqueue_del_filteropts "int filt"
44 .Ft int
45 .Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok"
46 .Ft void
47 .Fn knote_fdclose "struct thread *td" "int fd"
48 .Ft void
49 .Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked"
50 .Ft void
51 .Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked"
52 .Ft void
53 .Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn"
54 .Ft int
55 .Fn knlist_empty "struct knlist *knl"
56 .Ft void
57 .Fo knlist_init
58 .Fa "struct knlist *knl"
59 .Fa "void *lock"
60 .Fa "void \*[lp]*kl_lock\*[rp]\*[lp]void *\*[rp]"
61 .Fa "void \*[lp]*kl_unlock\*[rp]\*[lp]void *\*[rp]"
62 .Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]"
63 .Fc
64 .Ft void
65 .Fn knlist_destroy "struct knlist *knl"
66 .Ft void
67 .Fn knlist_clear "struct knlist *knl" "int islocked"
68 .Ft void
69 .Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked"
70 .Ft void
71 .Fn KNOTE_LOCKED "struct knlist *knl" "long hint"
72 .Ft void
73 .Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint"
74 .Sh DESCRIPTION
75 The functions
76 .Fn kqueue_add_filteropts
77 and
78 .Fn kqueue_del_filteropts
79 allow for the addition and removal of a filter type.
80 The filter is statically defined by the
81 .Dv EVFILT_*
82 macros.
83 The function
84 .Fn kqueue_add_filteropts
85 will make
86 .Fa filt
87 available.
88 The
89 .Vt "struct filterops"
90 has the following members:
91 .Bl -tag -width ".Va f_attach"
92 .It Va f_isfd
93 If
94 .Va f_isfd
95 is set,
96 .Va ident
97 in
98 .Vt "struct kevent"
99 is taken to be a file descriptor.
100 In this case, the
101 .Vt knote
102 passed into
103 .Va f_attach
104 will have the
105 .Va kn_fp
106 member initialized to the
107 .Vt "struct file *"
108 that represents the file descriptor.
109 .It Va f_attach
110 The
111 .Va f_attach
112 function will be called when attaching a
113 .Vt knote
114 to the object.
115 The method should call
116 .Fn knlist_add
117 to add the
118 .Vt knote
119 to the list that was initialized with
120 .Fn knlist_init .
121 The call to
122 .Fn knlist_add
123 is only necessary if the object can have multiple
124 .Vt knotes
125 associated with it.
126 If there is no
127 .Vt knlist
128 to call
129 .Fn knlist_add
130 with, the function
131 .Va f_attach
132 must clear the
133 .Dv KN_DETACHED
134 bit of
135 .Va kn_status
136 in the
137 .Vt knote .
138 The function shall return 0 on success, or appropriate error for the failure.
139 During
140 .Va f_attach ,
141 it is valid to change the
142 .Va kn_fops
143 pointer to a different pointer.
144 This will change the
145 .Va f_event
146 and
147 .Va f_detach
148 functions called when processing the
149 .Vt knote .
150 .It Va f_detach
151 The
152 .Va f_detach
153 function will be called to detach the
154 .Vt knote
155 if the
156 .Vt knote
157 has not already been detached by a call to
158 .Fn knlist_remove .
159 .It Va f_event
160 The
161 .Va f_event
162 function will be called to update the status of the
163 .Vt knote .
164 If the function returns 0, it will be assumed that the object is not
165 ready (or no longer ready) to be woken up.
166 The
167 .Fa hint
168 argument will be 0 when scanning
169 .Vt knotes
170 to see which are triggered.
171 Otherwise, the
172 .Fa hint
173 argument will be the value passed to either
174 .Dv KNOTE_LOCKED
175 or
176 .Dv KNOTE_UNLOCKED .
177 The
178 .Va kn_data
179 value should be updated as necessary to reflect the current value, such as
180 number of bytes available for reading, or buffer space available for writing.
181 If the note needs to be removed,
182 .Fn knlist_remove_inevent
183 must be called.
184 The function
185 .Fn knlist_remove_inevent
186 will remove the note from the list, the
187 .Va f_detach
188 function will not be called and the
189 .Vt knote
190 will not be returned as an event.
191 .Pp
192 Locks
193 .Em must not
194 be acquired in
195 .Va f_event .
196 If a lock is required in
197 .Va f_event ,
198 it must be obtained in the
199 .Fa kl_lock
200 function of the
201 .Vt knlist
202 that the
203 .Va knote
204 was added to.
205 .El
206 .Pp
207 The function
208 .Fn kqfd_register
209 will register the
210 .Vt kevent
211 on the kqueue file descriptor
212 .Fa fd .
213 If it is safe to sleep,
214 .Fa waitok
215 should be set.
216 .Pp
217 The function
218 .Fn knote_fdclose
219 is used to delete all
220 .Vt knotes
221 associated with
222 .Fa fd .
223 Once returned, there will no longer be any
224 .Vt knotes
225 associated with the
226 .Fa fd .
227 The
228 .Vt knotes
229 removed will never be returned from a
230 .Xr kevent 2
231 call, so if userland uses the
232 .Vt knote
233 to track resources, they will be leaked.
234 The
235 .Fn FILEDESC_LOCK
236 lock must be held over the call to
237 .Fn knote_fdclose
238 so that file descriptors cannot be added or removed.
239 .Pp
240 The
241 .Fn knlist_*
242 family of functions are for managing
243 .Vt knotes
244 associated with an object.
245 A
246 .Vt knlist
247 is not required, but is commonly used.
248 If used, the
249 .Vt knlist
250 must be initialized with the
251 .Fn knlist_init
252 function.
253 If
254 .Fa lock
255 is
256 .Dv NULL ,
257 an internal lock will be used and the remaining arguments will be ignored.
258 The
259 .Fa kl_lock , kl_unlock
260 and
261 .Fa kl_locked
262 functions will be used to manipulate a
263 .Fa lock .
264 If the argument is
265 .Dv NULL ,
266 default routines operating on
267 .Vt "struct mtx *"
268 will be used.
269 The
270 .Vt knlist
271 structure may be embedded into the object structure.
272 The
273 .Fa lock
274 will be held over calls to
275 .Va f_event .
276 If
277 .Dv NULL
278 is passed for the mutex, a private mutex will be used.
279 The function
280 .Fn knlist_empty
281 requires that a
282 .Fa lock
283 be held.
284 The function
285 .Fn knlist_clear
286 is used to remove all
287 .Vt knotes
288 associated with the list.
289 The
290 .Fa islocked
291 argument declares if
292 .Fa lock
293 has been acquired.
294 All
295 .Vt knotes
296 will be marked as detached, and
297 .Dv EV_ONESHOT
298 will be set so that the
299 .Vt knote
300 will be deleted after the next scan.
301 The
302 .Fn knlist_destroy
303 function is used to destroy a
304 .Vt knlist .
305 There must be no
306 .Vt knotes
307 associated with the
308 .Vt knlist
309 .Fn ( knlist_empty
310 returns true)
311 and no more
312 .Vt knotes
313 may be attached to the object.
314 A
315 .Vt knlist
316 may be emptied by calling
317 .Fn knlist_clear .
318 .Pp
319 The macros
320 .Fn KNOTE_LOCKED
321 and
322 .Fn KNOTE_UNLOCKED
323 are used to notify
324 .Vt knotes
325 about events associated with the object.
326 It will iterate over all
327 .Vt knotes
328 on the list calling the
329 .Va f_event
330 function associated with the
331 .Vt knote .
332 The macro
333 .Fn KNOTE_LOCKED
334 must be used if the lock associated with the
335 .Fa knl
336 passed in is held.
337 The function
338 .Fn KNOTE_UNLOCKED
339 will acquire the lock before iterating over the list of
340 .Vt knotes .
341 .Sh RETURN VALUES
342 The function
343 .Fn kqueue_add_filteropts
344 will return zero on success,
345 .Er EINVAL
346 in the case of an invalid
347 .Fa filt ,
348 or
349 .Er EEXIST
350 if the filter has already been installed.
351 .Pp
352 The function
353 .Fn kqueue_del_filteropts
354 will return zero on success,
355 .Er EINVAL
356 in the case of an invalid
357 .Fa filt ,
358 or
359 .Er EBUSY
360 if the filter is still in use.
361 .Pp
362 The function
363 .Fn kqfd_register
364 will return zero on success,
365 .Er EBADF
366 if the file descriptor is not a kqueue, or any of the possible values returned
367 by
368 .Xr kevent 2 .
369 .Sh SEE ALSO
370 .Xr kevent 2 ,
371 .Xr kqueue 2
372 .Sh AUTHORS
373 This
374 manual page was written by
375 .An John-Mark Gurney Aq jmg@FreeBSD.org .