kqueue_add_filteropts (9)

Leading comments

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 ...

(The comments found at the beginning of the groff file "man9/kqueue_add_filteropts.9freebsd".)

NAME

kqueue_add_filteropts , kqueue_del_filteropts kqfd_register knote_fdclose knlist_init , knlist_init_mtx , knlist_init_rw_reader knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty knlist_clear , knlist_delete , knlist_destroy KNOTE_LOCKED , KNOTE_UNLOCKED - event delivery subsystem

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_lockrp]lp]void *rp] Fa void lp]*kl_unlockrp]lp]void *rp] Fa int lp]*kl_lockedrp]lp]void *rp] Fc Ft void Fn knlist_init_mtx struct knlist *knl struct mtx *lock Ft void Fn knlist_init_rw_reader struct knlist *knl struct rwlock *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 void Fn knlist_remove_inevent struct knlist *knl struct knote *kn 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

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 EVFILT_* macros. The function Fn kqueue_add_filteropts will make Fa filt available. The Vt struct filterops has the following members:

f_isfd

If f_isfd is set, ident in Vt struct kevent is taken to be a file descriptor. In this case, the Vt knote passed into f_attach will have the kn_fp member initialized to the Vt struct file * that represents the file descriptor.

f_attach

The 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 f_attach must clear the KN_DETACHED bit of 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 f_attach it is valid to change the kn_fops pointer to a different pointer. This will change the f_event and f_detach functions called when processing the Vt knote .

f_detach

The 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 , Fn knlist_remove_inevent or Fn knlist_delete . The list Fa lock will not be held when this function is called.

f_event

The 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 KNOTE_LOCKED or KNOTE_UNLOCKED The 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 f_detach function will not be called and the Vt knote will not be returned as an event.

Locks must not be acquired in f_event If a lock is required in f_event it must be obtained in the Fa kl_lock function of the Vt knlist that the knote was added to.

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.

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 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.

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 , Fn knlist_init_mtx or Fn knlist_init_rw_reader . The Vt knlist structure may be embedded into the object structure. The Fa lock will be held over f_event calls.

For the Fn knlist_init function, if Fa lock is NULL a shared global lock will be used and the remaining arguments must be 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 NULL a function operating on MTX_DEF style mutex(9) locks will be used instead.

The function Fn knlist_init_mtx may be used to initialize a Vt knlist when Fa lock is a MTX_DEF style mutex(9) lock.

The function Fn knlist_init_rw_reader may be used to initialize a Vt knlist when Fa lock is a rwlock(9) read lock. Lock is acquired via Fn rw_rlock function.

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.

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 EV_ONESHOT set so that the Vt knote will be returned and removed durning the next scan. The f_detach function will be called when the Vt knote is deleted durning the next scan. This function must not be used when f_isfd is set in Vt struct filterops , as the Fa td argument of Fn fdrop will be NULL

The function Fn knlist_delete removes and deletes all Vt knotes on the list. The function f_detach will not be called, and the Vt knote will not be returned on the next scan. Using this function could leak user land resources if a process uses the Vt knote to track resources.

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.

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 or Fn knlist_delete .

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 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 .

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.

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.

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 kevent(2).

SEE ALSO

kevent(2), kqueue(2)

AUTHORS

This manual page was written by An John-Mark Gurney Aq jmg@FreeBSD.org .