mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-22 02:37:15 +00:00
![Mark Johnston](/assets/img/avatar_default.png)
knlist_clear() does not free knotes and so does not call fdrop(), so remove the bit of the function description which claims otherwise. (The knote will be dropped by the next queue scan, and it is at that point that the fd reference will be dropped.) MFC after: 1 week
427 lines
8.9 KiB
Groff
427 lines
8.9 KiB
Groff
.\" Copyright 2006,2011 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.
|
|
.\"
|
|
.Dd December 18, 2023
|
|
.Dt KQUEUE 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm kqueue_add_filteropts , kqueue_del_filteropts ,
|
|
.Nm kqfd_register ,
|
|
.Nm knote_fdclose ,
|
|
.Nm knlist_init , knlist_init_mtx ,
|
|
.Nm knlist_add , knlist_remove , knlist_empty ,
|
|
.Nm knlist_clear , knlist_delete , knlist_destroy ,
|
|
.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
|
|
.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_init_mtx "struct knlist *knl" "struct mtx *lock"
|
|
.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 int
|
|
.Fn knlist_empty "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 knlist_destroy "struct knlist *knl"
|
|
.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,
|
|
such as when the object is being destroyed, or does not exist.
|
|
During
|
|
.Va f_attach ,
|
|
it is valid to change the
|
|
.Va kn_fop
|
|
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
|
|
or
|
|
.Fn knlist_delete .
|
|
The list
|
|
.Fa lock
|
|
will not be held when this function is called.
|
|
.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.
|
|
.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 either
|
|
.Fn knlist_init
|
|
or
|
|
.Fn knlist_init_mtx .
|
|
The
|
|
.Vt knlist
|
|
structure may be embedded into the object structure.
|
|
The
|
|
.Fa lock
|
|
will be held over
|
|
.Va f_event
|
|
calls.
|
|
.Pp
|
|
For the
|
|
.Fn knlist_init
|
|
function, if
|
|
.Fa lock
|
|
is
|
|
.Dv NULL ,
|
|
a shared global lock will be used and the remaining arguments must be
|
|
.Dv NULL .
|
|
The function pointers
|
|
.Fa kl_lock , kl_unlock
|
|
and
|
|
.Fa kl_locked
|
|
will be used to manipulate the argument
|
|
.Fa lock .
|
|
If any of the function pointers are
|
|
.Dv NULL ,
|
|
a function operating on
|
|
.Dv MTX_DEF
|
|
style
|
|
.Xr mutex 9
|
|
locks will be used instead.
|
|
.Pp
|
|
The function
|
|
.Fn knlist_init_mtx
|
|
may be used to initialize a
|
|
.Vt knlist
|
|
when
|
|
.Fa lock
|
|
is a
|
|
.Dv MTX_DEF
|
|
style
|
|
.Xr mutex 9
|
|
lock.
|
|
.Pp
|
|
The function
|
|
.Fn knlist_empty
|
|
returns true when there are no
|
|
.Vt knotes
|
|
on the list.
|
|
The function requires that the
|
|
.Fa lock
|
|
be held when called.
|
|
.Pp
|
|
The function
|
|
.Fn knlist_clear
|
|
removes all
|
|
.Vt knotes
|
|
from the list.
|
|
The
|
|
.Fa islocked
|
|
argument declares if the
|
|
.Fa lock
|
|
has been acquired.
|
|
All
|
|
.Vt knotes
|
|
will have
|
|
.Dv EV_ONESHOT
|
|
set so that the
|
|
.Vt knote
|
|
will be returned and removed during the next scan.
|
|
The
|
|
.Va f_detach
|
|
function will be called when the
|
|
.Vt knote
|
|
is deleted during the next scan.
|
|
.Pp
|
|
The function
|
|
.Fn knlist_delete
|
|
removes and deletes all
|
|
.Vt knotes
|
|
on the list.
|
|
The function
|
|
.Va f_detach
|
|
will not be called, and the
|
|
.Vt knote
|
|
will not be returned on the next scan.
|
|
Using this function could leak userland resources if a process uses the
|
|
.Vt knote
|
|
to track resources.
|
|
.Pp
|
|
Both the
|
|
.Fn knlist_clear
|
|
and
|
|
.Fn knlist_delete
|
|
functions may sleep.
|
|
They also may release the
|
|
.Fa lock
|
|
to wait for other
|
|
.Vt knotes
|
|
to drain.
|
|
.Pp
|
|
The
|
|
.Fn knlist_destroy
|
|
function is used to destroy a
|
|
.Vt knlist .
|
|
There must be no
|
|
.Vt knotes
|
|
associated with the
|
|
.Vt knlist
|
|
.Po Fn knlist_empty
|
|
returns true
|
|
.Pc
|
|
and no more
|
|
.Vt knotes
|
|
may be attached to the object.
|
|
A
|
|
.Vt knlist
|
|
may be emptied by calling
|
|
.Fn knlist_clear
|
|
or
|
|
.Fn knlist_delete .
|
|
.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
|
|
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 Mt jmg@FreeBSD.org .
|