feat: Added FreeBSD man pages

1 files changed, 438 insertions, 0 deletions

diff --git a/static/freebsd/man9/kqueue.9 b/static/freebsd/man9/kqueue.9
new file mode 100644
index 00000000..bc735302
--- /dev/null
+++ b/static/freebsd/man9/kqueue.9
@@ -0,0 +1,438 @@
+.\" 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 2, 2025
+.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.
+.It Va f_copy
+The
+.Va f_copy
+function is called to copy notes when the process forks.
+When
+.Dv NULL ,
+the current node is not duplicated to the child process.
+Filter might set
+.Dv f_copy
+to
+.Fn knote_triv_copy
+if there is no additional handling required, besides shallow copying of the knote itself.
+.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 .