table of contents
KQUEUE(9) | Kernel Developer's Manual | KQUEUE(9) |
NAME¶
kqueue_add_filteropts, kqueue_del_filteropts, kqfd_register, knote_fdclose, knlist_add, knlist_remove, knlist_remove_inevent, knlist_empty, knlist_init, knlist_destroy, knlist_clear, knlist_delete, KNOTE_LOCKED, KNOTE_UNLOCKED — event delivery subsystemSYNOPSIS¶
#include <sys/event.h> intkqueue_add_filteropts(int filt, struct filterops *filtops); int
kqueue_del_filteropts(int filt); int
kqfd_register(int fd, struct kevent *kev, struct thread *td, int waitok); void
knote_fdclose(struct thread *td, int fd); void
knlist_add(struct knlist *knl, struct knote *kn, int islocked); void
knlist_remove(struct knlist *knl, struct knote *kn, int islocked); void
knlist_remove_inevent(struct knlist *knl, struct knote *kn); int
knlist_empty(struct knlist *knl); void
knlist_init(struct knlist *knl, void *lock, void (*kl_lock)(void *), void (*kl_unlock)(void *), int (*kl_locked)(void *)); void
knlist_destroy(struct knlist *knl); void
knlist_clear(struct knlist *knl, int islocked); void
knlist_delete(struct knlist *knl, struct thread *td, int islocked); void
KNOTE_LOCKED(struct knlist *knl, long hint); void
KNOTE_UNLOCKED(struct knlist *knl, long hint);
DESCRIPTION¶
The functions kqueue_add_filteropts() and kqueue_del_filteropts() allow for the addition and removal of a filter type. The filter is statically defined by theEVFILT_*
macros. The function
kqueue_add_filteropts() will make filt
available. The struct filterops has the following
members:
- f_isfd
- If f_isfd is set, ident in struct kevent is taken to be a file descriptor. In this case, the knote passed into f_attach will have the kn_fp member initialized to the struct file * that represents the file descriptor.
- f_attach
- The f_attach function will be called
when attaching a knote to the object. The method
should call knlist_add() to add the
knote to the list that was initialized with
knlist_init(). The call to
knlist_add() is only necessary if the object can have
multiple knotes associated with it. If there is no
knlist to call knlist_add() with,
the function f_attach must clear the
KN_DETACHED
bit of kn_status in the knote. The function shall return 0 on success, or appropriate error for the failure. During f_attach, it is valid to change the kn_fops pointer to a different pointer. This will change the f_event and f_detach functions called when processing the knote. - f_detach
- The f_detach function will be called to detach the knote if the knote has not already been detached by a call to knlist_remove().
- f_event
- The f_event function will be called
to update the status of the knote. If the function
returns 0, it will be assumed that the object is not ready (or no longer
ready) to be woken up. The hint argument will be 0
when scanning knotes to see which are triggered.
Otherwise, the hint argument will be the value
passed to either
KNOTE_LOCKED
orKNOTE_UNLOCKED
. The kn_data value should be updated as necessary to reflect the current value, such as number of bytes available for reading, or buffer space available for writing. If the note needs to be removed, knlist_remove_inevent() must be called. The function knlist_remove_inevent() will remove the note from the list, the f_detach function will not be called and the knote will not be returned as an event. Locks must not be acquired in f_event. If a lock is required in f_event, it must be obtained in the kl_lock function of the knlist that the knote was added to.
NULL
, an internal lock will be used and the remaining
arguments will be ignored. The kl_lock,
kl_unlock and kl_locked functions
will be used to manipulate a lock. If the argument is
NULL
, default routines operating on
struct mtx * will be used. The
knlist structure may be embedded into the object
structure. The lock will be held over calls to
f_event. If NULL
is passed for
the mutex, a private mutex will be used. The function
knlist_empty() requires that a lock be
held. The function knlist_clear() is used to remove all
knotes associated with the list. The
islocked argument declares if lock
has been acquired. All knotes will be marked as
detached, and EV_ONESHOT
will be set so that the
knote will be deleted after the next scan. The
knlist_destroy() function is used to destroy a
knlist. There must be no knotes
associated with the knlist (knlist_empty returns true)
and no more knotes may be attached to the object. A
knlist may be emptied by calling
knlist_clear().
The macros KNOTE_LOCKED() and
KNOTE_UNLOCKED() are used to notify
knotes about events associated with the object. It will
iterate over all knotes on the list calling the
f_event function associated with the
knote. The macro KNOTE_LOCKED() must
be used if the lock associated with the knl passed in is
held. The function KNOTE_UNLOCKED() will acquire the lock
before iterating over the list of knotes.
RETURN VALUES¶
The function kqueue_add_filteropts() will return zero on success,EINVAL
in the case of an invalid
filt, or EEXIST
if the filter
has already been installed.
The function kqueue_del_filteropts() will return zero on
success, EINVAL
in the case of an invalid
filt, or EBUSY
if the filter is
still in use.
The function kqfd_register() will return zero on success,
EBADF
if the file descriptor is not a kqueue, or any
of the possible values returned by kevent(2).
SEE ALSO¶
kevent(2), kqueue(2)AUTHORS¶
This manual page was written by John-Mark Gurney ⟨jmg@FreeBSD.org⟩.December 28, 2006 | Debian |