xref: /freebsd/share/man/man9/kqueue.9 (revision 90db62aca6ec7d5f9806bf59b1e1f2413850f9b2)

.\" Copyright 2004 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$
.\"
.Dd September 1, 2004
.Dt KQUEUE 9
.Os
.Sh NAME
.Nm kqueue_add_filteropts , kqueue_del_filteropts
.Nd "add and remove kqueue event filters"
.Pp
.Nm kqfd_register
.Nd "register a kevent with kqueue by fd"
.Pp
.Nm knote_fdclose
.Nd "deactivate all knotes associated with fd"
.Pp
.Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty , knlist_init , knlist_destroy , knlist_clear , knlist_delete
.Nd "initalize and manipulate lists of knotes"
.Pp
.Nm KNOTE_LOCKED , KNOTE_UNLOCKED
.Nd "activate knotes on a knlist"
.Sh SYNOPSIS
.In sys/event.h
.Ft int
.Fn kqueue_add_filteropts "int filt" "struct filterops *"
.Ft int
.Fn kqueue_del_filteropts "int filt"
.Ft int
.Fn kqfd_register "int fd" "struct kevent *" "struct thread *" "int waitok"
.Ft void
.Fn knote_fdclose "struct thread *" "int fd"
.Ft void
.Fn knlist_add "struct knlist *" "struct knote *" "int islocked"
.Ft void
.Fn knlist_remove "struct knlist *" "struct knote *" "int islocked"
.Ft void
.Fn knlist_remove_inevent "struct knlist *" "struct knote *"
.Ft int
.Fn knlist_empty "struct knlist *"
.Ft void
.Fn knlist_init "struct knlist *" "void *lock" "void (*kl_lock)(void *)" "void (*kl_unlock)(void *) "int (*kl_locked)(void *)"
.Ft void
.Fn knlist_destroy "struct knlist *"
.Ft void
.Fn knlist_clear "struct knlist *" "int islocked"
.Ft void
.Fn knlist_delete "struct knlist *" "struct thread *" "int islocked"
.Ft void
.Fn KNOTE_LOCKED "struct knlist *" "long hint"
.Ft void
.Fn KNOTE_UNLOCKED "struct knlist *" "long hint"
.Sh DESCRIPTION
The functions
.Fn kqueue_add_filteropts
and
.Fn kqueue_del_filteropts
allows the addition and removal of a filter type.
The filter is staticly defined by the
.Dv EVFILT_*
macros.
The function
.Fn kqueue_add_filteropts
will make 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 knote passed into
.Va f_attach
will have the
.Va kn_fp
member initalized to the
.Vt "struct file *"
that represense the file descriptor.
.It Va f_attach
The
.Va f_attach
member 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 initalized with
.Fn knlist_init .
The call to
.Fn knlist_add
is only necesary if the object can have multiple 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
.Va knote .
The function shall return 0 on success, or appropriate errno for the failure.
Durning
.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
members called when processing the knote.
.It Va f_detach
The
.Va f_detach
member 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
meber 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 hint field will be 0 when called scanning knotes to see which
are available.
Otherwise the hint field will be populated with the value passed to
.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
member will not be called and the
.Va knote
will not be returned as an event.
.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, 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
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 knotes associated with an object.
A
.Va knlist
is not required, but is commonly used.
If used, the
.Vt knlist
must be initalized 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
will be used to manipulate
.Fa lock .
If the argument is
.Dv NULL ,
a default routine operating on
.Vt "struct mtx *"
will be used.
The
.Vt knlist
structure may be embeded in your object structure.
The
.Fa lock
will be held over calls to
.Fn f_event .
If
.Dv NULL
is passed for the mutex, a private mutex will be used.
The function
.Fn knlist_empty
requires that
.Fa lock
be held.
The function
.Fn knlist_clear
is used to remove all knotes associated with the list.
The
.Fa islocked
argument declares if you have the
.Fa lock
has been aquired.
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 function
.Fn knlist_destroy
is to be used at object destruction time.
There must be no
.Vt knotes
associated with the
.Vt knlist
.Fn ( knlist_clear
be called before or
.Fn knlist_empty
returns true) and no more
.Vt knotes
are able to be attached to the object.
.Pp
.Pp
The functions
.Fn KNOTE_LOCKED
and
.Fn KNOTE_UNLOCKED
are used to notify knotes about events associated with your object.
It will iterated over all
.Vt knotes
on the list calling the
.Va f_event
function associated with the
.Vt knote .
The function
.Fn KNOTE_LOCKED
must be used if the lock associated with the
.Fa knl
passed in is held.
The function
.Fn KNOTE_UNLOCKED
will aquire the lock before iterating over the list of
.Ft 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 .
.Sh SEE ALSO
.Xr kqueue 2 ,
.Xr kevent 2
.Sh AUTHORS
This
manual page was written by
.An John-Mark Gurney Aq jmg@FreeBSD.org .