kfilter_register(9) [netbsd man page]
KFILTER_REGISTER(9) BSD Kernel Developer's Manual KFILTER_REGISTER(9) NAME
kfilter_register, kfilter_unregister -- add or remove kernel event filters SYNOPSIS
#include <sys/event.h> int kfilter_register(const char *name, struct filterops *filtops, int *retfilter); int kfilter_unregister(const char *name); DESCRIPTION
The kfilter_register() function adds a new kernel event filter (kfilter) to the system, for use by callers of kqueue(2) and kevent(2). name is the name of the new filter (which must not already exist), and filtops is a pointer to a filterops structure which describes the filter operations. Both name and filtops will be copied to an internal data structure, and a new filter number will be allocated. If retfilter is not NULL, then the new filter number will be returned in the address pointed at by retfilter. The kfilter_unregister() function removes a kfilter named name that was previously registered with kfilter_register(). If a filter with the same name is later reregistered with kfilter_register(), it will get a different filter number (i.e., filter numbers are not recycled). It is not possible to unregister the system filters (i.e., those that start with ``EVFILT_'' and are documented in kqueue(2)). The filterops structure is defined as follows: struct filterops { int f_isfd; /* true if ident == filedescriptor */ int (*f_attach)(struct knote *kn); /* called when knote is ADDed */ void (*f_detach)(struct knote *kn); /* called when knote is DELETEd */ int (*f_event)(struct knote *kn, long hint); /* called when event is triggered */ }; If the filter operation is for a file descriptor, f_isfd should be non-zero, otherwise it should be zero. This controls where the kqueue(2) system stores the knotes for an object. RETURN VALUES
kfilter_register() returns 0 on success, EINVAL if there's an invalid argument, or EEXIST if the filter already exists, kfilter_unregister() returns 0 on success, EINVAL if there's an invalid argument, or ENOENT if the filter doesn't exist. SEE ALSO
kqueue(2), free(9), knote(9), malloc(9) HISTORY
The kfilter_register() and kfilter_unregister() functions first appeared in NetBSD 2.0. AUTHORS
The kfilter_register() and kfilter_unregister() functions were implemented by Luke Mewburn <lukem@NetBSD.org>. BSD
October 23, 2002 BSD
Check Out this Related Man Page
KQUEUE(9) BSD Kernel Developer's Manual KQUEUE(9) NAME
kqueue_add_filteropts, kqueue_del_filteropts, kqfd_register, knote_fdclose, knlist_add, knlist_remove, knlist_remove_inevent, knlist_empty, knlist_init, knlist_destroy, knlist_clear, knlist_delete, KNOTE_LOCKED, KNOTE_UNLOCKED -- event delivery subsystem SYNOPSIS
#include <sys/event.h> int kqueue_add_filteropts(int filt, struct filterops *filtops); int kqueue_del_filteropts(int filt); int kqfd_register(int fd, struct kevent *kev, struct thread *td, int waitok); void knote_fdclose(struct thread *td, int fd); void knlist_add(struct knlist *knl, struct knote *kn, int islocked); void knlist_remove(struct knlist *knl, struct knote *kn, int islocked); void knlist_remove_inevent(struct knlist *knl, struct knote *kn); int knlist_empty(struct knlist *knl); void knlist_init(struct knlist *knl, void *lock, void (*kl_lock)(void *), void (*kl_unlock)(void *), int (*kl_locked)(void *)); void knlist_destroy(struct knlist *knl); void knlist_clear(struct knlist *knl, int islocked); void knlist_delete(struct knlist *knl, struct thread *td, int islocked); void KNOTE_LOCKED(struct knlist *knl, long hint); void KNOTE_UNLOCKED(struct knlist *knl, long hint); DESCRIPTION
The functions kqueue_add_filteropts() and kqueue_del_filteropts() allow for the addition and removal of a filter type. The filter is stati- cally defined by the EVFILT_* macros. The function kqueue_add_filteropts() will make filt available. The struct filterops has the following members: f_isfd If f_isfd is set, ident in struct kevent is taken to be a file descriptor. In this case, the knote passed into f_attach will have the kn_fp member initialized to the struct file * that represents the file descriptor. f_attach The f_attach function will be called when attaching a knote to the object. The method should call knlist_add() to add the knote to the list that was initialized with knlist_init(). The call to knlist_add() is only necessary if the object can have multiple knotes associated with it. If there is no knlist to call knlist_add() with, the function f_attach must clear the KN_DETACHED bit of kn_status in the knote. The function shall return 0 on success, or appropriate error for the failure. 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 pro- cessing the knote. f_detach The f_detach function will be called to detach the knote if the knote has not already been detached by a call to knlist_remove(). f_event The f_event function will be called to update the status of the 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 argument will be 0 when scanning knotes to see which are trig- gered. Otherwise, the 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, knlist_remove_inevent() must be called. The function knlist_remove_inevent() will remove the note from the list, the f_detach function will not be called and the 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 kl_lock function of the knlist that the knote was added to. The function kqfd_register() will register the kevent on the kqueue file descriptor fd. If it is safe to sleep, waitok should be set. The function knote_fdclose() is used to delete all knotes associated with fd. Once returned, there will no longer be any knotes associated with the fd. The knotes removed will never be returned from a kevent(2) call, so if userland uses the knote to track resources, they will be leaked. The FILEDESC_LOCK() lock must be held over the call to knote_fdclose() so that file descriptors cannot be added or removed. The knlist_*() family of functions are for managing knotes associated with an object. A knlist is not required, but is commonly used. If used, the knlist must be initialized with the knlist_init() function. If lock is NULL, an internal lock will be used and the remaining argu- ments will be ignored. The kl_lock, kl_unlock and kl_locked functions will be used to manipulate a lock. If the argument is NULL, default routines operating on struct mtx * will be used. The knlist structure may be embedded into the object structure. The lock will be held over calls to f_event. If NULL is passed for the mutex, a private mutex will be used. The function knlist_empty() requires that a lock be held. The function knlist_clear() is used to remove all knotes associated with the list. The islocked argument declares if lock has been acquired. All knotes will be marked as detached, and EV_ONESHOT will be set so that the knote will be deleted after the next scan. The knlist_destroy() function is used to destroy a knlist. There must be no knotes associated with the knlist (knlist_empty() returns true) and no more knotes may be attached to the object. A knlist may be emptied by calling knlist_clear(). The macros KNOTE_LOCKED() and KNOTE_UNLOCKED() are used to notify knotes about events associated with the object. It will iterate over all knotes on the list calling the f_event function associated with the knote. The macro KNOTE_LOCKED() must be used if the lock associated with the knl passed in is held. The function KNOTE_UNLOCKED() will acquire the lock before iterating over the list of knotes. RETURN VALUES
The function kqueue_add_filteropts() will return zero on success, EINVAL in the case of an invalid filt, or EEXIST if the filter has already been installed. The function kqueue_del_filteropts() will return zero on success, EINVAL in the case of an invalid filt, or EBUSY if the filter is still in use. The function kqfd_register() will return zero on success, 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 John-Mark Gurney <jmg@FreeBSD.org>. BSD
December 28, 2006 BSD