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
--- 7 unchanged lines hidden (view full) ---
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: head/share/man/man9/kqueue.9 163025 2006-10-05 08:42:07Z ru $
26.\"
27.Dd October 4, 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
75The functions
76.Fn kqueue_add_filteropts
77and
78.Fn kqueue_del_filteropts
79allow for the addition and removal of a filter type.
80The filter is statically defined by the
81.Dv EVFILT_*
82macros.
83The function
84.Fn kqueue_add_filteropts
85will make
86.Fa filt
87available.
88The
89.Vt "struct filterops"
90has the following members:
91.Bl -tag -width ".Va f_attach"
92.It Va f_isfd
93If
94.Va f_isfd
95is set,
96.Va ident
97in
98.Vt "struct kevent"
99is taken to be a file descriptor.
100In this case, the
101.Vt knote
102passed into
103.Va f_attach
104will have the
105.Va kn_fp
106member initialized to the
107.Vt "struct file *"
108that represents the file descriptor.
109.It Va f_attach
110The
111.Va f_attach
112function will be called when attaching a
113.Vt knote
114to the object.
115The method should call
116.Fn knlist_add
117to add the
118.Vt knote
119to the list that was initialized with
120.Fn knlist_init .
121The call to
122.Fn knlist_add
123is only necessary if the object can have multiple
124.Vt knotes
125associated with it.
126If there is no
127.Vt knlist
128to call
129.Fn knlist_add
130with, the function
131.Va f_attach
132must clear the
133.Dv KN_DETACHED
134bit of
135.Va kn_status
136in the
137.Vt knote .
138The function shall return 0 on success, or appropriate error for the failure.
139During
140.Va f_attach ,
141it is valid to change the
142.Va kn_fops
143pointer to a different pointer.
144This will change the
145.Va f_event
146and
147.Va f_detach
148functions called when processing the
149.Vt knote .
150.It Va f_detach
151The
152.Va f_detach
153function will be called to detach the
154.Vt knote
155if the
156.Vt knote
157has not already been detached by a call to
158.Fn knlist_remove .
159.It Va f_event
160The
161.Va f_event
162function will be called to update the status of the
163.Vt knote .
164If the function returns 0, it will be assumed that the object is not
165ready (or no longer ready) to be woken up.
166The
167.Fa hint
168argument will be 0 when scanning
169.Vt knotes
170to see which are triggered.
171Otherwise, the
172.Fa hint
173argument will be the value passed to either
174.Dv KNOTE_LOCKED
175or
176.Dv KNOTE_UNLOCKED .
177The
178.Va kn_data
179value should be updated as necessary to reflect the current value, such as
180number of bytes available for reading, or buffer space available for writing.
181If the note needs to be removed,
182.Fn knlist_remove_inevent
183must be called.
184The function
185.Fn knlist_remove_inevent
186will remove the note from the list, the
187.Va f_detach
188function will not be called and the
189.Vt knote
190will not be returned as an event.
191.El
192.Pp
193The function
194.Fn kqfd_register
195will register the
196.Vt kevent
197on the kqueue file descriptor
198.Fa fd .
199If it is safe to sleep,
200.Fa waitok
201should be set.
202.Pp
203The function
204.Fn knote_fdclose
205is used to delete all
206.Vt knotes
207associated with
208.Fa fd .
209Once returned, there will no longer be any
210.Vt knotes
211associated with the
212.Fa fd .
213The
214.Vt knotes
215removed will never be returned from a
216.Xr kevent 2
217call, so if userland uses the
218.Vt knote
219to track resources, they will be leaked.
220The
221.Fn FILEDESC_LOCK
222lock must be held over the call to
223.Fn knote_fdclose
224so that file descriptors cannot be added or removed.
225.Pp
226The
227.Fn knlist_*
228family of functions are for managing
229.Vt knotes
230associated with an object.
231A
232.Vt knlist
233is not required, but is commonly used.
234If used, the
235.Vt knlist
236must be initialized with the
237.Fn knlist_init
238function.
239If
240.Fa lock
241is
242.Dv NULL ,
243an internal lock will be used and the remaining arguments will be ignored.
244The
245.Fa kl_lock , kl_unlock
246and
247.Fa kl_locked
248functions will be used to manipulate a
249.Fa lock .
250If the argument is
251.Dv NULL ,
252default routines operating on
253.Vt "struct mtx *"
254will be used.
255The
256.Vt knlist
257structure may be embedded into the object structure.
258The
259.Fa lock
260will be held over calls to
261.Va f_event .
262If
263.Dv NULL
264is passed for the mutex, a private mutex will be used.
265The function
266.Fn knlist_empty
267requires that a
268.Fa lock
269be held.
270The function
271.Fn knlist_clear
272is used to remove all
273.Vt knotes
274associated with the list.
275The
276.Fa islocked
277argument declares if
278.Fa lock
279has been acquired.
280All
281.Vt knotes
282will be marked as detached, and
283.Dv EV_ONESHOT
284will be set so that the
285.Vt knote
286will be deleted after the next scan.
287The
288.Fn knlist_destroy
289function is used to destroy a
290.Vt knlist .
291There must be no
292.Vt knotes
293associated with the
294.Vt knlist
295.Fn ( knlist_empty
296returns true)
297and no more
298.Vt knotes
299may be attached to the object.
300A
301.Vt knlist
302may be emptied by calling
303.Fn knlist_clear .
304.Pp
305The macros
306.Fn KNOTE_LOCKED
307and
308.Fn KNOTE_UNLOCKED
309are used to notify
310.Vt knotes
311about events associated with the object.
312It will iterate over all
313.Vt knotes
314on the list calling the
315.Va f_event
316function associated with the
317.Vt knote .
318The macro
319.Fn KNOTE_LOCKED
320must be used if the lock associated with the
321.Fa knl
322passed in is held.
323The function
324.Fn KNOTE_UNLOCKED
325will acquire the lock before iterating over the list of
326.Vt knotes .
327.Sh RETURN VALUES
328The function
329.Fn kqueue_add_filteropts
330will return zero on success,
331.Er EINVAL
332in the case of an invalid
333.Fa filt ,
334or
335.Er EEXIST
336if the filter has already been installed.
337.Pp
338The function
339.Fn kqueue_del_filteropts
340will return zero on success,
341.Er EINVAL
342in the case of an invalid
343.Fa filt ,
344or
345.Er EBUSY
346if the filter is still in use.
347.Pp
348The function
349.Fn kqfd_register
350will return zero on success,
351.Er EBADF
352if the file descriptor is not a kqueue, or any of the possible values returned
353by
354.Xr kevent 2 .
355.Sh SEE ALSO
356.Xr kevent 2 ,
357.Xr kqueue 2
358.Sh AUTHORS
359This
360manual page was written by
361.An John-Mark Gurney Aq jmg@FreeBSD.org .
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
--- 7 unchanged lines hidden (view full) ---
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: head/share/man/man9/kqueue.9 163025 2006-10-05 08:42:07Z ru $
26.\"
27.Dd October 4, 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
75The functions
76.Fn kqueue_add_filteropts
77and
78.Fn kqueue_del_filteropts
79allow for the addition and removal of a filter type.
80The filter is statically defined by the
81.Dv EVFILT_*
82macros.
83The function
84.Fn kqueue_add_filteropts
85will make
86.Fa filt
87available.
88The
89.Vt "struct filterops"
90has the following members:
91.Bl -tag -width ".Va f_attach"
92.It Va f_isfd
93If
94.Va f_isfd
95is set,
96.Va ident
97in
98.Vt "struct kevent"
99is taken to be a file descriptor.
100In this case, the
101.Vt knote
102passed into
103.Va f_attach
104will have the
105.Va kn_fp
106member initialized to the
107.Vt "struct file *"
108that represents the file descriptor.
109.It Va f_attach
110The
111.Va f_attach
112function will be called when attaching a
113.Vt knote
114to the object.
115The method should call
116.Fn knlist_add
117to add the
118.Vt knote
119to the list that was initialized with
120.Fn knlist_init .
121The call to
122.Fn knlist_add
123is only necessary if the object can have multiple
124.Vt knotes
125associated with it.
126If there is no
127.Vt knlist
128to call
129.Fn knlist_add
130with, the function
131.Va f_attach
132must clear the
133.Dv KN_DETACHED
134bit of
135.Va kn_status
136in the
137.Vt knote .
138The function shall return 0 on success, or appropriate error for the failure.
139During
140.Va f_attach ,
141it is valid to change the
142.Va kn_fops
143pointer to a different pointer.
144This will change the
145.Va f_event
146and
147.Va f_detach
148functions called when processing the
149.Vt knote .
150.It Va f_detach
151The
152.Va f_detach
153function will be called to detach the
154.Vt knote
155if the
156.Vt knote
157has not already been detached by a call to
158.Fn knlist_remove .
159.It Va f_event
160The
161.Va f_event
162function will be called to update the status of the
163.Vt knote .
164If the function returns 0, it will be assumed that the object is not
165ready (or no longer ready) to be woken up.
166The
167.Fa hint
168argument will be 0 when scanning
169.Vt knotes
170to see which are triggered.
171Otherwise, the
172.Fa hint
173argument will be the value passed to either
174.Dv KNOTE_LOCKED
175or
176.Dv KNOTE_UNLOCKED .
177The
178.Va kn_data
179value should be updated as necessary to reflect the current value, such as
180number of bytes available for reading, or buffer space available for writing.
181If the note needs to be removed,
182.Fn knlist_remove_inevent
183must be called.
184The function
185.Fn knlist_remove_inevent
186will remove the note from the list, the
187.Va f_detach
188function will not be called and the
189.Vt knote
190will not be returned as an event.
191.El
192.Pp
193The function
194.Fn kqfd_register
195will register the
196.Vt kevent
197on the kqueue file descriptor
198.Fa fd .
199If it is safe to sleep,
200.Fa waitok
201should be set.
202.Pp
203The function
204.Fn knote_fdclose
205is used to delete all
206.Vt knotes
207associated with
208.Fa fd .
209Once returned, there will no longer be any
210.Vt knotes
211associated with the
212.Fa fd .
213The
214.Vt knotes
215removed will never be returned from a
216.Xr kevent 2
217call, so if userland uses the
218.Vt knote
219to track resources, they will be leaked.
220The
221.Fn FILEDESC_LOCK
222lock must be held over the call to
223.Fn knote_fdclose
224so that file descriptors cannot be added or removed.
225.Pp
226The
227.Fn knlist_*
228family of functions are for managing
229.Vt knotes
230associated with an object.
231A
232.Vt knlist
233is not required, but is commonly used.
234If used, the
235.Vt knlist
236must be initialized with the
237.Fn knlist_init
238function.
239If
240.Fa lock
241is
242.Dv NULL ,
243an internal lock will be used and the remaining arguments will be ignored.
244The
245.Fa kl_lock , kl_unlock
246and
247.Fa kl_locked
248functions will be used to manipulate a
249.Fa lock .
250If the argument is
251.Dv NULL ,
252default routines operating on
253.Vt "struct mtx *"
254will be used.
255The
256.Vt knlist
257structure may be embedded into the object structure.
258The
259.Fa lock
260will be held over calls to
261.Va f_event .
262If
263.Dv NULL
264is passed for the mutex, a private mutex will be used.
265The function
266.Fn knlist_empty
267requires that a
268.Fa lock
269be held.
270The function
271.Fn knlist_clear
272is used to remove all
273.Vt knotes
274associated with the list.
275The
276.Fa islocked
277argument declares if
278.Fa lock
279has been acquired.
280All
281.Vt knotes
282will be marked as detached, and
283.Dv EV_ONESHOT
284will be set so that the
285.Vt knote
286will be deleted after the next scan.
287The
288.Fn knlist_destroy
289function is used to destroy a
290.Vt knlist .
291There must be no
292.Vt knotes
293associated with the
294.Vt knlist
295.Fn ( knlist_empty
296returns true)
297and no more
298.Vt knotes
299may be attached to the object.
300A
301.Vt knlist
302may be emptied by calling
303.Fn knlist_clear .
304.Pp
305The macros
306.Fn KNOTE_LOCKED
307and
308.Fn KNOTE_UNLOCKED
309are used to notify
310.Vt knotes
311about events associated with the object.
312It will iterate over all
313.Vt knotes
314on the list calling the
315.Va f_event
316function associated with the
317.Vt knote .
318The macro
319.Fn KNOTE_LOCKED
320must be used if the lock associated with the
321.Fa knl
322passed in is held.
323The function
324.Fn KNOTE_UNLOCKED
325will acquire the lock before iterating over the list of
326.Vt knotes .
327.Sh RETURN VALUES
328The function
329.Fn kqueue_add_filteropts
330will return zero on success,
331.Er EINVAL
332in the case of an invalid
333.Fa filt ,
334or
335.Er EEXIST
336if the filter has already been installed.
337.Pp
338The function
339.Fn kqueue_del_filteropts
340will return zero on success,
341.Er EINVAL
342in the case of an invalid
343.Fa filt ,
344or
345.Er EBUSY
346if the filter is still in use.
347.Pp
348The function
349.Fn kqfd_register
350will return zero on success,
351.Er EBADF
352if the file descriptor is not a kqueue, or any of the possible values returned
353by
354.Xr kevent 2 .
355.Sh SEE ALSO
356.Xr kevent 2 ,
357.Xr kqueue 2
358.Sh AUTHORS
359This
360manual page was written by
361.An John-Mark Gurney Aq jmg@FreeBSD.org .