1.\" Copyright 2004 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 163014 2006-10-04 20:17:14Z jmg $
26.\"
27.Dd October 4, 2006
28.Dt KQUEUE 9
29.Os
30.Sh NAME
31.Nm kqueue_add_filteropts , kqueue_del_filteropts
32.Nd "add and remove kqueue event filters"
33.Pp
34.Nm kqfd_register
35.Nd "register a kevent with kqueue by fd"
36.Pp
37.Nm knote_fdclose
38.Nd "deactivate all knotes associated with fd"
39.Pp
40.Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty , knlist_init , knlist_destroy , knlist_clear , knlist_delete
41.Nd "initalize and manipulate lists of knotes"
42.Pp
43.Nm KNOTE_LOCKED , KNOTE_UNLOCKED
44.Nd "activate knotes on a knlist"
45.Sh SYNOPSIS
46.In sys/event.h
47.Ft int
48.Fn kqueue_add_filteropts "int filt" "struct filterops *"
49.Ft int
50.Fn kqueue_del_filteropts "int filt"
51.Ft int
52.Fn kqfd_register "int fd" "struct kevent *" "struct thread *" "int waitok"
53.Ft void
54.Fn knote_fdclose "struct thread *" "int fd"
55.Ft void
56.Fn knlist_add "struct knlist *" "struct knote *" "int islocked"
57.Ft void
58.Fn knlist_remove "struct knlist *" "struct knote *" "int islocked"
59.Ft void
60.Fn knlist_remove_inevent "struct knlist *" "struct knote *"
61.Ft int
62.Fn knlist_empty "struct knlist *"
63.Ft void
64.Fn knlist_init "struct knlist *" "void *lock" "void (*kl_lock)(void *)" "void (*kl_unlock)(void *) "int (*kl_locked)(void *)"
65.Ft void
66.Fn knlist_destroy "struct knlist *"
67.Ft void
68.Fn knlist_clear "struct knlist *" "int islocked"
69.Ft void
70.Fn knlist_delete "struct knlist *" "struct thread *" "int islocked"
71.Ft void
72.Fn KNOTE_LOCKED "struct knlist *" "long hint"
73.Ft void
74.Fn KNOTE_UNLOCKED "struct knlist *" "long hint"
75.Sh DESCRIPTION
76The functions
77.Fn kqueue_add_filteropts
78and
79.Fn kqueue_del_filteropts
80allows the addition and removal of a filter type.
81The filter is staticly defined by the
82.Dv EVFILT_*
83macros.
84The function
85.Fn kqueue_add_filteropts
86will make filt available. The
87.Vt "struct filterops"
88has the following members:
89.Bl -tag -width ".Va f_attach"
90.It Va f_isfd
91If
92.Va f_isfd
93is set,
94.Va ident
95in
96.Vt "struct kevent"
97is taken to be a file descriptor.
98In this case, the knote passed into
99.Va f_attach
100will have the
101.Va kn_fp
102member initalized to the
103.Vt "struct file *"
104that represense the file descriptor.
105.It Va f_attach
106The
107.Va f_attach
108member will be called when attaching a
109.Vt knote
110to the object.
111The method should call
112.Fn knlist_add
113to add the
114.Vt knote
115to the list that was initalized with
116.Fn knlist_init .
117The call to
118.Fn knlist_add
119is only necesary if the object can have multiple knotes associated with it.
120If there is no
121.Vt knlist
122to call
123.Fn knlist_add
124with, the function
125.Va f_attach
126must clear the
127.Dv KN_DETACHED
128bit of
129.Va kn_status
130in the
131.Va knote .
132The function shall return 0 on success, or appropriate errno for the failure.
133Durning
134.Va f_attach
135it is valid to change the
136.Va kn_fops
137pointer to a different pointer.
138This will change the
139.Va f_event
140and
141.Va f_detach
142members called when processing the knote.
143.It Va f_detach
144The
145.Va f_detach
146member will be called to detach the
147.Vt knote
148if the
149.Vt knote
150has not already been detached by a call to
151.Fn knlist_remove .
152.It Va f_event
153The
154.Va f_event
155meber will be called to update the status of the
156.Vt knote .
157If the function returns 0, it will be assumed that the object is not
158ready (or no longer ready) to be woken up.
159The hint field will be 0 when called scanning knotes to see which
160are available.
161Otherwise the hint field will be populated with the value passed to
162.Dv KNOTE_LOCKED
163or
164.Dv KNOTE_UNLOCKED .
165The
166.Va kn_data
167value should be updated as necessary to reflect the current value, such as
168number of bytes available for reading, or buffer space available for writing.
169If the note needs to be removed,
170.Fn knlist_remove_inevent
171must be called.
172The function
173.Fn knlist_remove_inevent
174will remove the note from the list, the
175.Va f_detach
176member will not be called and the
177.Va knote
178will not be returned as an event.
179.El
180.Pp
181The function
182.Fn kqfd_register
183will register the
184.Vt kevent
185on the kqueue file descriptor
186.Fa fd .
187If it is safe to sleep, waitok should be set.
188.Pp
189The function
190.Fn knote_fdclose
191is used to delete all
192.Vt knotes
193associated with
194.Fa fd .
195Once returned there will no longer be any
196.Vt knotes
197associated with the
198.Fa fd .
199The
200.Vt knotes
201removed will never be returned from a
202.Xr kevent 2
203call, so if userland uses the
204.Vt knote
205to track resources, they will be leaked.
206The
207.Fn FILEDESC_LOCK
208must be held over the call to
209.Fn knote_fdclose
210so that file descriptors cannot be added or removed.
211.Pp
212The
213.Fn knlist_*
214family of functions are for managing knotes associated with an object.
215A
216.Va knlist
217is not required, but is commonly used.
218If used, the
219.Vt knlist
220must be initalized with the
221.Fn knlist_init
222function.
223If
224.Fa lock
225is
226.Dv NULL ,
227an internal lock will be used and the remaining arguments will be ignored.
228The
229.Fa kl_lock , kl_unlock
230and
231.Fa kl_locked
232will be used to manipulate
233.Fa lock .
234If the argument is
235.Dv NULL ,
236a default routine operating on
237.Vt "struct mtx *"
238will be used.
239The
240.Vt knlist
241structure may be embeded in your object structure.
242The
243.Fa lock
244will be held over calls to
245.Fn f_event .
246If
247.Dv NULL
248is passed for the mutex, a private mutex will be used.
249The function
250.Fn knlist_empty
251requires that
252.Fa lock
253be held.
254The function
255.Fn knlist_clear
256is used to remove all knotes associated with the list.
257The
258.Fa islocked
259argument declares if you have the
260.Fa lock
261has been aquired.
262All
263.Vt knotes
264will be marked as detached, and
265.Dv EV_ONESHOT
266will be set so that the
267.Vt knote
268will be deleted after the next scan.
269The function
270.Fn knlist_destroy
271is to be used at object destruction time.
272There must be no
273.Vt knotes
274associated with the
275.Vt knlist
276.Fn ( knlist_clear
277be called before or
278.Fn knlist_empty
279returns true) and no more
280.Vt knotes
281are able to be attached to the object.
282.Pp
283.Pp
284The functions
285.Fn KNOTE_LOCKED
286and
287.Fn KNOTE_UNLOCKED
288are used to notify knotes about events associated with your object.
289It will iterated over all
290.Vt knotes
291on the list calling the
292.Va f_event
293function associated with the
294.Vt knote .
295The function
296.Fn KNOTE_LOCKED
297must be used if the lock associated with the
298.Fa knl
299passed in is held.
300The function
301.Fn KNOTE_UNLOCKED
302will aquire the lock before iterating over the list of
303.Ft knotes .
304.Sh RETURN VALUES
305The function
306.Fn kqueue_add_filteropts
307will return zero on success,
308.Er EINVAL
309in the case of an invalid
310.Fa filt
311or
312.Er EEXIST
313if the filter has already been installed.
314.Pp
315The function
316.Fn kqueue_del_filteropts
317will return zero on success,
318.Er EINVAL
319in the case of an invalid
320.Fa filt
321or
322.Er EBUSY
323if the filter is still in use.
324.Pp
325The function
326.Fn kqfd_register
327will return zero on success,
328.Er EBADF
329if the file descriptor is not a kqueue or any of the possible values returned
330by
331.Xr kevent .
332.Sh SEE ALSO
333.Xr kqueue 2 ,
334.Xr kevent 2
335.Sh AUTHORS
336This
337manual page was written by
338.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 163014 2006-10-04 20:17:14Z jmg $
26.\"
27.Dd October 4, 2006
28.Dt KQUEUE 9
29.Os
30.Sh NAME
31.Nm kqueue_add_filteropts , kqueue_del_filteropts
32.Nd "add and remove kqueue event filters"
33.Pp
34.Nm kqfd_register
35.Nd "register a kevent with kqueue by fd"
36.Pp
37.Nm knote_fdclose
38.Nd "deactivate all knotes associated with fd"
39.Pp
40.Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty , knlist_init , knlist_destroy , knlist_clear , knlist_delete
41.Nd "initalize and manipulate lists of knotes"
42.Pp
43.Nm KNOTE_LOCKED , KNOTE_UNLOCKED
44.Nd "activate knotes on a knlist"
45.Sh SYNOPSIS
46.In sys/event.h
47.Ft int
48.Fn kqueue_add_filteropts "int filt" "struct filterops *"
49.Ft int
50.Fn kqueue_del_filteropts "int filt"
51.Ft int
52.Fn kqfd_register "int fd" "struct kevent *" "struct thread *" "int waitok"
53.Ft void
54.Fn knote_fdclose "struct thread *" "int fd"
55.Ft void
56.Fn knlist_add "struct knlist *" "struct knote *" "int islocked"
57.Ft void
58.Fn knlist_remove "struct knlist *" "struct knote *" "int islocked"
59.Ft void
60.Fn knlist_remove_inevent "struct knlist *" "struct knote *"
61.Ft int
62.Fn knlist_empty "struct knlist *"
63.Ft void
64.Fn knlist_init "struct knlist *" "void *lock" "void (*kl_lock)(void *)" "void (*kl_unlock)(void *) "int (*kl_locked)(void *)"
65.Ft void
66.Fn knlist_destroy "struct knlist *"
67.Ft void
68.Fn knlist_clear "struct knlist *" "int islocked"
69.Ft void
70.Fn knlist_delete "struct knlist *" "struct thread *" "int islocked"
71.Ft void
72.Fn KNOTE_LOCKED "struct knlist *" "long hint"
73.Ft void
74.Fn KNOTE_UNLOCKED "struct knlist *" "long hint"
75.Sh DESCRIPTION
76The functions
77.Fn kqueue_add_filteropts
78and
79.Fn kqueue_del_filteropts
80allows the addition and removal of a filter type.
81The filter is staticly defined by the
82.Dv EVFILT_*
83macros.
84The function
85.Fn kqueue_add_filteropts
86will make filt available. The
87.Vt "struct filterops"
88has the following members:
89.Bl -tag -width ".Va f_attach"
90.It Va f_isfd
91If
92.Va f_isfd
93is set,
94.Va ident
95in
96.Vt "struct kevent"
97is taken to be a file descriptor.
98In this case, the knote passed into
99.Va f_attach
100will have the
101.Va kn_fp
102member initalized to the
103.Vt "struct file *"
104that represense the file descriptor.
105.It Va f_attach
106The
107.Va f_attach
108member will be called when attaching a
109.Vt knote
110to the object.
111The method should call
112.Fn knlist_add
113to add the
114.Vt knote
115to the list that was initalized with
116.Fn knlist_init .
117The call to
118.Fn knlist_add
119is only necesary if the object can have multiple knotes associated with it.
120If there is no
121.Vt knlist
122to call
123.Fn knlist_add
124with, the function
125.Va f_attach
126must clear the
127.Dv KN_DETACHED
128bit of
129.Va kn_status
130in the
131.Va knote .
132The function shall return 0 on success, or appropriate errno for the failure.
133Durning
134.Va f_attach
135it is valid to change the
136.Va kn_fops
137pointer to a different pointer.
138This will change the
139.Va f_event
140and
141.Va f_detach
142members called when processing the knote.
143.It Va f_detach
144The
145.Va f_detach
146member will be called to detach the
147.Vt knote
148if the
149.Vt knote
150has not already been detached by a call to
151.Fn knlist_remove .
152.It Va f_event
153The
154.Va f_event
155meber will be called to update the status of the
156.Vt knote .
157If the function returns 0, it will be assumed that the object is not
158ready (or no longer ready) to be woken up.
159The hint field will be 0 when called scanning knotes to see which
160are available.
161Otherwise the hint field will be populated with the value passed to
162.Dv KNOTE_LOCKED
163or
164.Dv KNOTE_UNLOCKED .
165The
166.Va kn_data
167value should be updated as necessary to reflect the current value, such as
168number of bytes available for reading, or buffer space available for writing.
169If the note needs to be removed,
170.Fn knlist_remove_inevent
171must be called.
172The function
173.Fn knlist_remove_inevent
174will remove the note from the list, the
175.Va f_detach
176member will not be called and the
177.Va knote
178will not be returned as an event.
179.El
180.Pp
181The function
182.Fn kqfd_register
183will register the
184.Vt kevent
185on the kqueue file descriptor
186.Fa fd .
187If it is safe to sleep, waitok should be set.
188.Pp
189The function
190.Fn knote_fdclose
191is used to delete all
192.Vt knotes
193associated with
194.Fa fd .
195Once returned there will no longer be any
196.Vt knotes
197associated with the
198.Fa fd .
199The
200.Vt knotes
201removed will never be returned from a
202.Xr kevent 2
203call, so if userland uses the
204.Vt knote
205to track resources, they will be leaked.
206The
207.Fn FILEDESC_LOCK
208must be held over the call to
209.Fn knote_fdclose
210so that file descriptors cannot be added or removed.
211.Pp
212The
213.Fn knlist_*
214family of functions are for managing knotes associated with an object.
215A
216.Va knlist
217is not required, but is commonly used.
218If used, the
219.Vt knlist
220must be initalized with the
221.Fn knlist_init
222function.
223If
224.Fa lock
225is
226.Dv NULL ,
227an internal lock will be used and the remaining arguments will be ignored.
228The
229.Fa kl_lock , kl_unlock
230and
231.Fa kl_locked
232will be used to manipulate
233.Fa lock .
234If the argument is
235.Dv NULL ,
236a default routine operating on
237.Vt "struct mtx *"
238will be used.
239The
240.Vt knlist
241structure may be embeded in your object structure.
242The
243.Fa lock
244will be held over calls to
245.Fn f_event .
246If
247.Dv NULL
248is passed for the mutex, a private mutex will be used.
249The function
250.Fn knlist_empty
251requires that
252.Fa lock
253be held.
254The function
255.Fn knlist_clear
256is used to remove all knotes associated with the list.
257The
258.Fa islocked
259argument declares if you have the
260.Fa lock
261has been aquired.
262All
263.Vt knotes
264will be marked as detached, and
265.Dv EV_ONESHOT
266will be set so that the
267.Vt knote
268will be deleted after the next scan.
269The function
270.Fn knlist_destroy
271is to be used at object destruction time.
272There must be no
273.Vt knotes
274associated with the
275.Vt knlist
276.Fn ( knlist_clear
277be called before or
278.Fn knlist_empty
279returns true) and no more
280.Vt knotes
281are able to be attached to the object.
282.Pp
283.Pp
284The functions
285.Fn KNOTE_LOCKED
286and
287.Fn KNOTE_UNLOCKED
288are used to notify knotes about events associated with your object.
289It will iterated over all
290.Vt knotes
291on the list calling the
292.Va f_event
293function associated with the
294.Vt knote .
295The function
296.Fn KNOTE_LOCKED
297must be used if the lock associated with the
298.Fa knl
299passed in is held.
300The function
301.Fn KNOTE_UNLOCKED
302will aquire the lock before iterating over the list of
303.Ft knotes .
304.Sh RETURN VALUES
305The function
306.Fn kqueue_add_filteropts
307will return zero on success,
308.Er EINVAL
309in the case of an invalid
310.Fa filt
311or
312.Er EEXIST
313if the filter has already been installed.
314.Pp
315The function
316.Fn kqueue_del_filteropts
317will return zero on success,
318.Er EINVAL
319in the case of an invalid
320.Fa filt
321or
322.Er EBUSY
323if the filter is still in use.
324.Pp
325The function
326.Fn kqfd_register
327will return zero on success,
328.Er EBADF
329if the file descriptor is not a kqueue or any of the possible values returned
330by
331.Xr kevent .
332.Sh SEE ALSO
333.Xr kqueue 2 ,
334.Xr kevent 2
335.Sh AUTHORS
336This
337manual page was written by
338.An John-Mark Gurney Aq jmg@FreeBSD.org .