1.\" $NetBSD: kfilter_register.9,v 1.10 2008/04/30 13:10:58 martin Exp $ 2.\" 3.\" Copyright (c) 2001, 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This documentation is derived from text contributed by 7.\" Luke Mewburn. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 23, 2002 31.Dt KFILTER_REGISTER 9 32.Os 33.Sh NAME 34.Nm kfilter_register , 35.Nm kfilter_unregister 36.Nd add or remove kernel event filters 37.Sh SYNOPSIS 38.In sys/event.h 39.Ft int 40.Fn kfilter_register "const char *name" "struct filterops *filtops" "int *retfilter" 41.Ft int 42.Fn kfilter_unregister "const char *name" 43.Sh DESCRIPTION 44The 45.Fn kfilter_register 46function adds a new kernel event filter (kfilter) to the system, 47for use by callers of 48.Xr kqueue 2 49and 50.Xr kevent 2 . 51.Fa name 52is the name of the new filter (which must not already exist), and 53.Fa filtops 54is a pointer to a 55.Va filterops 56structure which describes the filter operations. 57Both 58.Fa name 59and 60.Fa filtops 61will be copied to an internal data structure, and a new filter number 62will be allocated. 63If 64.Fa retfilter 65is not 66.Dv NULL , 67then the new filter number will be returned in the address pointed at by 68.Fa retfilter . 69.Pp 70The 71.Fn kfilter_unregister 72function removes a kfilter named 73.Fa name 74that was previously registered with 75.Fn kfilter_register . 76If a filter with the same 77.Fa name 78is later reregistered with 79.Fn kfilter_register , 80it will get a different filter number 81(i.e., filter numbers are not recycled). 82It is not possible to unregister the system filters 83(i.e., those that start with 84.Dq EVFILT_ 85and are documented in 86.Xr kqueue 2 ) . 87.Pp 88The 89.Va filterops 90structure is defined as follows: 91.Bd -literal -offset indent 92struct filterops { 93 int f_isfd; /* true if ident == filedescriptor */ 94 int (*f_attach)(struct knote *kn); 95 /* called when knote is ADDed */ 96 void (*f_detach)(struct knote *kn); 97 /* called when knote is DELETEd */ 98 int (*f_event)(struct knote *kn, long hint); 99 /* called when event is triggered */ 100}; 101.Ed 102.Pp 103If the filter operation is for a file descriptor, 104.Va f_isfd 105should be non-zero, otherwise it should be zero. 106This controls where the 107.Xr kqueue 2 108system stores the knotes for an object. 109.Sh RETURN VALUES 110.Fn kfilter_register 111returns 0 on success, 112.Er EINVAL 113if there's an invalid argument, or 114.Er EEXIST 115if the filter already exists, 116.Pp 117.Fn kfilter_unregister 118returns 0 on success, 119.Er EINVAL 120if there's an invalid argument, or 121.Er ENOENT 122if the filter doesn't exist. 123.Sh SEE ALSO 124.Xr kqueue 2 , 125.Xr free 9 , 126.Xr knote 9 , 127.Xr malloc 9 128.Sh HISTORY 129The 130.Fn kfilter_register 131and 132.Fn kfilter_unregister 133functions first appeared in 134.Nx 2.0 . 135.Sh AUTHORS 136The 137.Fn kfilter_register 138and 139.Fn kfilter_unregister 140functions were implemented by 141.An Luke Mewburn 142.Aq lukem@NetBSD.org . 143