.\" Copyright 2006 John-Mark Gurney
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/man/man9/kqueue.9,v 1.6.10.1.6.1 2010/12/21 17:09:25 kensmith Exp $
.\"
.Dd December 28, 2006
.Dt KQUEUE 9
.Os
.Sh NAME
.Nm kqueue_add_filteropts , kqueue_del_filteropts ,
.Nm kqfd_register ,
.Nm knote_fdclose ,
.Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty ,
.Nm knlist_init , knlist_destroy , knlist_clear , knlist_delete ,
.Nm KNOTE_LOCKED , KNOTE_UNLOCKED
.Nd "event delivery subsystem"
.Sh SYNOPSIS
.In sys/event.h
.Ft int
.Fn kqueue_add_filteropts "int filt" "struct filterops *filtops"
.Ft int
.Fn kqueue_del_filteropts "int filt"
.Ft int
.Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok"
.Ft void
.Fn knote_fdclose "struct thread *td" "int fd"
.Ft void
.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked"
.Ft void
.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked"
.Ft void
.Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn"
.Ft int
.Fn knlist_empty "struct knlist *knl"
.Ft void
.Fo knlist_init
.Fa "struct knlist *knl"
.Fa "void *lock"
.Fa "void \*[lp]*kl_lock\*[rp]\*[lp]void *\*[rp]"
.Fa "void \*[lp]*kl_unlock\*[rp]\*[lp]void *\*[rp]"
.Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]"
.Fc
.Ft void
.Fn knlist_destroy "struct knlist *knl"
.Ft void
.Fn knlist_clear "struct knlist *knl" "int islocked"
.Ft void
.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked"
.Ft void
.Fn KNOTE_LOCKED "struct knlist *knl" "long hint"
.Ft void
.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint"
.Sh DESCRIPTION
The functions
.Fn kqueue_add_filteropts
and
.Fn kqueue_del_filteropts
allow for the addition and removal of a filter type.
The filter is statically defined by the
.Dv EVFILT_*
macros.
The function
.Fn kqueue_add_filteropts
will make
.Fa filt
available.
The
.Vt "struct filterops"
has the following members:
.Bl -tag -width ".Va f_attach"
.It Va f_isfd
If
.Va f_isfd
is set,
.Va ident
in
.Vt "struct kevent"
is taken to be a file descriptor.
In this case, the
.Vt knote
passed into
.Va f_attach
will have the
.Va kn_fp
member initialized to the
.Vt "struct file *"
that represents the file descriptor.
.It Va f_attach
The
.Va f_attach
function will be called when attaching a
.Vt knote
to the object.
The method should call
.Fn knlist_add
to add the
.Vt knote
to the list that was initialized with
.Fn knlist_init .
The call to
.Fn knlist_add
is only necessary if the object can have multiple
.Vt knotes
associated with it.
If there is no
.Vt knlist
to call
.Fn knlist_add
with, the function
.Va f_attach
must clear the
.Dv KN_DETACHED
bit of
.Va kn_status
in the
.Vt knote .
The function shall return 0 on success, or appropriate error for the failure.
During
.Va f_attach ,
it is valid to change the
.Va kn_fops
pointer to a different pointer.
This will change the
.Va f_event
and
.Va f_detach
functions called when processing the
.Vt knote .
.It Va f_detach
The
.Va f_detach
function will be called to detach the
.Vt knote
if the
.Vt knote
has not already been detached by a call to
.Fn knlist_remove .
.It Va f_event
The
.Va f_event
function will be called to update the status of the
.Vt 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
.Fa hint
argument will be 0 when scanning
.Vt knotes
to see which are triggered.
Otherwise, the
.Fa hint
argument will be the value passed to either
.Dv KNOTE_LOCKED
or
.Dv KNOTE_UNLOCKED .
The
.Va 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,
.Fn knlist_remove_inevent
must be called.
The function
.Fn knlist_remove_inevent
will remove the note from the list, the
.Va f_detach
function will not be called and the
.Vt knote
will not be returned as an event.
.Pp
Locks
.Em must not
be acquired in
.Va f_event .
If a lock is required in
.Va f_event ,
it must be obtained in the
.Fa kl_lock
function of the
.Vt knlist
that the
.Va knote
was added to.
.El
.Pp
The function
.Fn kqfd_register
will register the
.Vt kevent
on the kqueue file descriptor
.Fa fd .
If it is safe to sleep,
.Fa waitok
should be set.
.Pp
The function
.Fn knote_fdclose
is used to delete all
.Vt knotes
associated with
.Fa fd .
Once returned, there will no longer be any
.Vt knotes
associated with the
.Fa fd .
The
.Vt knotes
removed will never be returned from a
.Xr kevent 2
call, so if userland uses the
.Vt knote
to track resources, they will be leaked.
The
.Fn FILEDESC_LOCK
lock must be held over the call to
.Fn knote_fdclose
so that file descriptors cannot be added or removed.
.Pp
The
.Fn knlist_*
family of functions are for managing
.Vt knotes
associated with an object.
A
.Vt knlist
is not required, but is commonly used.
If used, the
.Vt knlist
must be initialized with the
.Fn knlist_init
function.
If
.Fa lock
is
.Dv NULL ,
an internal lock will be used and the remaining arguments will be ignored.
The
.Fa kl_lock , kl_unlock
and
.Fa kl_locked
functions will be used to manipulate a
.Fa lock .
If the argument is
.Dv NULL ,
default routines operating on
.Vt "struct mtx *"
will be used.
The
.Vt knlist
structure may be embedded into the object structure.
The
.Fa lock
will be held over calls to
.Va f_event .
If
.Dv NULL
is passed for the mutex, a private mutex will be used.
The function
.Fn knlist_empty
requires that a
.Fa lock
be held.
The function
.Fn knlist_clear
is used to remove all
.Vt knotes
associated with the list.
The
.Fa islocked
argument declares if
.Fa lock
has been acquired.
All
.Vt knotes
will be marked as detached, and
.Dv EV_ONESHOT
will be set so that the
.Vt knote
will be deleted after the next scan.
The
.Fn knlist_destroy
function is used to destroy a
.Vt knlist .
There must be no
.Vt knotes
associated with the
.Vt knlist
.Fn ( knlist_empty
returns true)
and no more
.Vt knotes
may be attached to the object.
A
.Vt knlist
may be emptied by calling
.Fn knlist_clear .
.Pp
The macros
.Fn KNOTE_LOCKED
and
.Fn KNOTE_UNLOCKED
are used to notify
.Vt knotes
about events associated with the object.
It will iterate over all
.Vt knotes
on the list calling the
.Va f_event
function associated with the
.Vt knote .
The macro
.Fn KNOTE_LOCKED
must be used if the lock associated with the
.Fa knl
passed in is held.
The function
.Fn KNOTE_UNLOCKED
will acquire the lock before iterating over the list of
.Vt knotes .
.Sh RETURN VALUES
The function
.Fn kqueue_add_filteropts
will return zero on success,
.Er EINVAL
in the case of an invalid
.Fa filt ,
or
.Er EEXIST
if the filter has already been installed.
.Pp
The function
.Fn kqueue_del_filteropts
will return zero on success,
.Er EINVAL
in the case of an invalid
.Fa filt ,
or
.Er EBUSY
if the filter is still in use.
.Pp
The function
.Fn kqfd_register
will return zero on success,
.Er EBADF
if the file descriptor is not a kqueue, or any of the possible values returned
by
.Xr kevent 2 .
.Sh SEE ALSO
.Xr kevent 2 ,
.Xr kqueue 2
.Sh AUTHORS
This
manual page was written by
.An John-Mark Gurney Aq jmg@FreeBSD.org .