xref: /freebsd/share/man/man9/kqueue.9 (revision cf771f223b1a69e11fd1b70b0a274a73fe844335)
1.\" Copyright 2006,2011 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 March 26, 2012
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_init , knlist_init_mtx , knlist_init_rw_reader ,
35.Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty ,
36.Nm knlist_clear , knlist_delete , knlist_destroy ,
37.Nm KNOTE_LOCKED , KNOTE_UNLOCKED
38.Nd "event delivery subsystem"
39.Sh SYNOPSIS
40.In sys/event.h
41.Ft int
42.Fn kqueue_add_filteropts "int filt" "struct filterops *filtops"
43.Ft int
44.Fn kqueue_del_filteropts "int filt"
45.Ft int
46.Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok"
47.Ft void
48.Fn knote_fdclose "struct thread *td" "int fd"
49.Ft void
50.Fo knlist_init
51.Fa "struct knlist *knl"
52.Fa "void *lock"
53.Fa "void \*[lp]*kl_lock\*[rp]\*[lp]void *\*[rp]"
54.Fa "void \*[lp]*kl_unlock\*[rp]\*[lp]void *\*[rp]"
55.Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]"
56.Fc
57.Ft void
58.Fn knlist_init_mtx "struct knlist *knl" "struct mtx *lock"
59.Ft void
60.Fn knlist_init_rw_reader "struct knlist *knl" "struct rwlock *lock"
61.Ft void
62.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked"
63.Ft void
64.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked"
65.Ft void
66.Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn"
67.Ft int
68.Fn knlist_empty "struct knlist *knl"
69.Ft void
70.Fn knlist_clear "struct knlist *knl" "int islocked"
71.Ft void
72.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked"
73.Ft void
74.Fn knlist_destroy "struct knlist *knl"
75.Ft void
76.Fn KNOTE_LOCKED "struct knlist *knl" "long hint"
77.Ft void
78.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint"
79.Sh DESCRIPTION
80The functions
81.Fn kqueue_add_filteropts
82and
83.Fn kqueue_del_filteropts
84allow for the addition and removal of a filter type.
85The filter is statically defined by the
86.Dv EVFILT_*
87macros.
88The function
89.Fn kqueue_add_filteropts
90will make
91.Fa filt
92available.
93The
94.Vt "struct filterops"
95has the following members:
96.Bl -tag -width ".Va f_attach"
97.It Va f_isfd
98If
99.Va f_isfd
100is set,
101.Va ident
102in
103.Vt "struct kevent"
104is taken to be a file descriptor.
105In this case, the
106.Vt knote
107passed into
108.Va f_attach
109will have the
110.Va kn_fp
111member initialized to the
112.Vt "struct file *"
113that represents the file descriptor.
114.It Va f_attach
115The
116.Va f_attach
117function will be called when attaching a
118.Vt knote
119to the object.
120The method should call
121.Fn knlist_add
122to add the
123.Vt knote
124to the list that was initialized with
125.Fn knlist_init .
126The call to
127.Fn knlist_add
128is only necessary if the object can have multiple
129.Vt knotes
130associated with it.
131If there is no
132.Vt knlist
133to call
134.Fn knlist_add
135with, the function
136.Va f_attach
137must clear the
138.Dv KN_DETACHED
139bit of
140.Va kn_status
141in the
142.Vt knote .
143The function shall return 0 on success, or appropriate error for the failure,
144such as when the object is being destroyed, or does not exist.
145During
146.Va f_attach ,
147it is valid to change the
148.Va kn_fops
149pointer to a different pointer.
150This will change the
151.Va f_event
152and
153.Va f_detach
154functions called when processing the
155.Vt knote .
156.It Va f_detach
157The
158.Va f_detach
159function will be called to detach the
160.Vt knote
161if the
162.Vt knote
163has not already been detached by a call to
164.Fn knlist_remove ,
165.Fn knlist_remove_inevent
166or
167.Fn knlist_delete .
168The list
169.Fa lock
170will not be held when this function is called.
171.It Va f_event
172The
173.Va f_event
174function will be called to update the status of the
175.Vt knote .
176If the function returns 0, it will be assumed that the object is not
177ready (or no longer ready) to be woken up.
178The
179.Fa hint
180argument will be 0 when scanning
181.Vt knotes
182to see which are triggered.
183Otherwise, the
184.Fa hint
185argument will be the value passed to either
186.Dv KNOTE_LOCKED
187or
188.Dv KNOTE_UNLOCKED .
189The
190.Va kn_data
191value should be updated as necessary to reflect the current value, such as
192number of bytes available for reading, or buffer space available for writing.
193If the note needs to be removed,
194.Fn knlist_remove_inevent
195must be called.
196The function
197.Fn knlist_remove_inevent
198will remove the note from the list, the
199.Va f_detach
200function will not be called and the
201.Vt knote
202will not be returned as an event.
203.Pp
204Locks
205.Em must not
206be acquired in
207.Va f_event .
208If a lock is required in
209.Va f_event ,
210it must be obtained in the
211.Fa kl_lock
212function of the
213.Vt knlist
214that the
215.Va knote
216was added to.
217.El
218.Pp
219The function
220.Fn kqfd_register
221will register the
222.Vt kevent
223on the kqueue file descriptor
224.Fa fd .
225If it is safe to sleep,
226.Fa waitok
227should be set.
228.Pp
229The function
230.Fn knote_fdclose
231is used to delete all
232.Vt knotes
233associated with
234.Fa fd .
235Once returned, there will no longer be any
236.Vt knotes
237associated with the
238.Fa fd .
239The
240.Vt knotes
241removed will never be returned from a
242.Xr kevent 2
243call, so if userland uses the
244.Vt knote
245to track resources, they will be leaked.
246The
247.Fn FILEDESC_LOCK
248lock must be held over the call to
249.Fn knote_fdclose
250so that file descriptors cannot be added or removed.
251.Pp
252The
253.Fn knlist_*
254family of functions are for managing
255.Vt knotes
256associated with an object.
257A
258.Vt knlist
259is not required, but is commonly used.
260If used, the
261.Vt knlist
262must be initialized with either
263.Fn knlist_init
264,
265.Fn knlist_init_mtx
266or
267.Fn knlist_init_rw_reader .
268The
269.Vt knlist
270structure may be embedded into the object structure.
271The
272.Fa lock
273will be held over
274.Va f_event
275calls.
276.Pp
277For the
278.Fn knlist_init
279function, if
280.Fa lock
281is
282.Dv NULL ,
283a shared global lock will be used and the remaining arguments must be
284.Dv NULL .
285The function pointers
286.Fa kl_lock , kl_unlock
287and
288.Fa kl_locked
289will be used to manipulate the argument
290.Fa lock .
291If any of the function pointers are
292.Dv NULL ,
293a function operating on
294.Dv MTX_DEF
295style
296.Xr mutex 9
297locks will be used instead.
298.Pp
299The function
300.Fn knlist_init_mtx
301may be used to initialize a
302.Vt knlist
303when
304.Fa lock
305is a
306.Dv MTX_DEF
307style
308.Xr mutex 9
309lock.
310.Pp
311The function
312.Fn knlist_init_rw_reader
313may be used to initialize a
314.Vt knlist
315when
316.Fa lock
317is a
318.Xr rwlock 9
319read lock.
320Lock is acquired via
321.Fn rw_rlock
322function.
323.Pp
324The function
325.Fn knlist_empty
326returns true when there are no
327.Vt knotes
328on the list.
329The function requires that the
330.Fa lock
331be held when called.
332.Pp
333The function
334.Fn knlist_clear
335removes all
336.Vt knotes
337from the list.
338The
339.Fa islocked
340argument declares if the
341.Fa lock
342has been acquired.
343All
344.Vt knotes
345will have
346.Dv EV_ONESHOT
347set so that the
348.Vt knote
349will be returned and removed durning the next scan.
350The
351.Va f_detach
352function will be called when the
353.Vt knote
354is deleted durning the next scan.
355This function must not be used when
356.Va f_isfd
357is set in
358.Vt "struct filterops" ,
359as the
360.Fa td
361argument of
362.Fn fdrop
363will be
364.Dv NULL .
365.Pp
366The function
367.Fn knlist_delete
368removes and deletes all
369.Vt knotes
370on the list.
371The function
372.Va f_detach
373will not be called, and the
374.Vt knote
375will not be returned on the next scan.
376Using this function could leak user land resources if a process uses the
377.Vt knote
378to track resources.
379.Pp
380Both the
381.Fn knlist_clear
382and
383.Fn knlist_delete
384functions may sleep.
385They also may release the
386.Fa lock
387to wait for other
388.Vt knotes
389to drain.
390.Pp
391The
392.Fn knlist_destroy
393function is used to destroy a
394.Vt knlist .
395There must be no
396.Vt knotes
397associated with the
398.Vt knlist
399.Fn ( knlist_empty
400returns true)
401and no more
402.Vt knotes
403may be attached to the object.
404A
405.Vt knlist
406may be emptied by calling
407.Fn knlist_clear
408or
409.Fn knlist_delete .
410.Pp
411The macros
412.Fn KNOTE_LOCKED
413and
414.Fn KNOTE_UNLOCKED
415are used to notify
416.Vt knotes
417about events associated with the object.
418It will iterate over all
419.Vt knotes
420on the list calling the
421.Va f_event
422function associated with the
423.Vt knote .
424The macro
425.Fn KNOTE_LOCKED
426must be used if the lock associated with the
427.Fa knl
428is held.
429The function
430.Fn KNOTE_UNLOCKED
431will acquire the lock before iterating over the list of
432.Vt knotes .
433.Sh RETURN VALUES
434The function
435.Fn kqueue_add_filteropts
436will return zero on success,
437.Er EINVAL
438in the case of an invalid
439.Fa filt ,
440or
441.Er EEXIST
442if the filter has already been installed.
443.Pp
444The function
445.Fn kqueue_del_filteropts
446will return zero on success,
447.Er EINVAL
448in the case of an invalid
449.Fa filt ,
450or
451.Er EBUSY
452if the filter is still in use.
453.Pp
454The function
455.Fn kqfd_register
456will return zero on success,
457.Er EBADF
458if the file descriptor is not a kqueue, or any of the possible values returned
459by
460.Xr kevent 2 .
461.Sh SEE ALSO
462.Xr kevent 2 ,
463.Xr kqueue 2
464.Sh AUTHORS
465This
466manual page was written by
467.An John-Mark Gurney Aq jmg@FreeBSD.org .
468