add man page talking about how to interface w/ the kqueue system so others

can write additional filters...

mdoc police please!

2 files changed, 353 insertions, 0 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 280dc58..c41657e 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -129,6 +129,7 @@ MAN=	accept_filter.9 \
 	kernacc.9 \
 	kernel_mount.9 \
 	kobj.9 \
+	kqueue.9 \
 	kthread.9 \
 	ktr.9 \
 	lock.9 \
@@ -665,6 +666,20 @@ MLINKS+=kobj.9 DEFINE_CLASS.9 \
 	kobj.9 kobj_create.9 \
 	kobj.9 kobj_delete.9 \
 	kobj.9 kobj_init.9
+MLINKS+=kqueue.9 kqfd_register.9 \
+	kqueue.9 knlist_add.9 \
+	kqueue.9 knlist_remove.9 \
+	kqueue.9 knlist_remove_inevent.9 \
+	kqueue.9 knlist_empty.9 \
+	kqueue.9 knlist_init.9 \
+	kqueue.9 knlist_destroy.9 \
+	kqueue.9 knlist_clear.9 \
+	kqueue.9 knlist_delete.9 \
+	kqueue.9 knote_fdclose.9 \
+	kqueue.9 KNOTE_LOCKED.9 \
+	kqueue.9 KNOTE_UNLOCKED.9 \
+	kqueue.9 kqueue_add_filteropts.9 \
+	kqueue.9 kqueue_del_filteropts.9
 MLINKS+=kthread.9 kproc_shutdown.9 \
 	kthread.9 kproc_start.9 \
 	kthread.9 kthread_create.9 \
diff --git a/share/man/man9/kqueue.9 b/share/man/man9/kqueue.9
new file mode 100644
index 0000000..a0ad6e0
--- /dev/null
+++ b/share/man/man9/kqueue.9
@@ -0,0 +1,338 @@
+.\" 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 .