Deleted Added
sdiff udiff text old ( 163014 ) new ( 163025 )
full compact
1.\" Copyright 2004 John-Mark Gurney
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 163014 2006-10-04 20:17:14Z jmg $
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.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
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
44.Nd "activate knotes on a knlist"
37.Nd "event delivery subsystem"
38.Sh SYNOPSIS
39.In sys/event.h
40.Ft int
48.Fn kqueue_add_filteropts "int filt" "struct filterops *"
41.Fn kqueue_add_filteropts "int filt" "struct filterops *filtops"
42.Ft int
43.Fn kqueue_del_filteropts "int filt"
44.Ft int
52.Fn kqfd_register "int fd" "struct kevent *" "struct thread *" "int waitok"
45.Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok"
46.Ft void
54.Fn knote_fdclose "struct thread *" "int fd"
47.Fn knote_fdclose "struct thread *td" "int fd"
48.Ft void
56.Fn knlist_add "struct knlist *" "struct knote *" "int islocked"
49.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked"
50.Ft void
58.Fn knlist_remove "struct knlist *" "struct knote *" "int islocked"
51.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked"
52.Ft void
60.Fn knlist_remove_inevent "struct knlist *" "struct knote *"
53.Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn"
54.Ft int
62.Fn knlist_empty "struct knlist *"
55.Fn knlist_empty "struct knlist *knl"
56.Ft void
64.Fn knlist_init "struct knlist *" "void *lock" "void (*kl_lock)(void *)" "void (*kl_unlock)(void *) "int (*kl_locked)(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
66.Fn knlist_destroy "struct knlist *"
65.Fn knlist_destroy "struct knlist *knl"
66.Ft void
68.Fn knlist_clear "struct knlist *" "int islocked"
67.Fn knlist_clear "struct knlist *knl" "int islocked"
68.Ft void
70.Fn knlist_delete "struct knlist *" "struct thread *" "int islocked"
69.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked"
70.Ft void
72.Fn KNOTE_LOCKED "struct knlist *" "long hint"
71.Fn KNOTE_LOCKED "struct knlist *knl" "long hint"
72.Ft void
74.Fn KNOTE_UNLOCKED "struct knlist *" "long hint"
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
80allows the addition and removal of a filter type.
81The filter is staticly defined by the
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
86will make filt available. The
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.
98In this case, the knote passed into
100In this case, the
101.Vt knote
102passed into
103.Va f_attach
104will have the
105.Va kn_fp
102member initalized to the
106member initialized to the
107.Vt "struct file *"
104that represense the file descriptor.
108that represents the file descriptor.
109.It Va f_attach
110The
111.Va f_attach
108member will be called when attaching a
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
115to the list that was initalized with
119to the list that was initialized with
120.Fn knlist_init .
121The call to
122.Fn knlist_add
119is only necesary if the object can have multiple knotes associated with it.
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
131.Va knote .
132The function shall return 0 on success, or appropriate errno for the failure.
133Durning
134.Va f_attach
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
142members called when processing the knote.
148functions called when processing the
149.Vt knote .
150.It Va f_detach
151The
152.Va f_detach
146member will be called to detach the
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
155meber will be called to update the status of the
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.
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
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
176member will not be called and the
177.Va knote
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 .
187If it is safe to sleep, waitok should be set.
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 .
195Once returned there will no longer be any
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
208must be held over the call to
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_*
214family of functions are for managing knotes associated with an object.
228family of functions are for managing
229.Vt knotes
230associated with an object.
231A
216.Va knlist
232.Vt knlist
233is not required, but is commonly used.
234If used, the
235.Vt knlist
220must be initalized with the
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
232will be used to manipulate
248functions will be used to manipulate a
249.Fa lock .
250If the argument is
251.Dv NULL ,
236a default routine operating on
252default routines operating on
253.Vt "struct mtx *"
254will be used.
255The
256.Vt knlist
241structure may be embeded in your object structure.
257structure may be embedded into the object structure.
258The
259.Fa lock
260will be held over calls to
245.Fn f_event .
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
251requires that
267requires that a
268.Fa lock
269be held.
270The function
271.Fn knlist_clear
256is used to remove all knotes associated with the list.
272is used to remove all
273.Vt knotes
274associated with the list.
275The
276.Fa islocked
259argument declares if you have the
277argument declares if
278.Fa lock
261has been aquired.
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.
269The function
287The
288.Fn knlist_destroy
271is to be used at object destruction time.
289function is used to destroy a
290.Vt knlist .
291There must be no
292.Vt knotes
293associated with the
294.Vt knlist
276.Fn ( knlist_clear
277be called before or
278.Fn knlist_empty
279returns true) and no more
295.Fn ( knlist_empty
296returns true)
297and no more
298.Vt knotes
281are able to be attached to the object.
299may be attached to the object.
300A
301.Vt knlist
302may be emptied by calling
303.Fn knlist_clear .
304.Pp
283.Pp
284The functions
305The macros
306.Fn KNOTE_LOCKED
307and
308.Fn KNOTE_UNLOCKED
288are used to notify knotes about events associated with your object.
289It will iterated over all
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 .
295The function
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
302will aquire the lock before iterating over the list of
303.Ft knotes .
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
310.Fa filt
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
320.Fa filt
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
329if the file descriptor is not a kqueue or any of the possible values returned
352if the file descriptor is not a kqueue, or any of the possible values returned
353by
331.Xr kevent .
354.Xr kevent 2 .
355.Sh SEE ALSO
333.Xr kqueue 2 ,
334.Xr kevent 2
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 .