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