1.\" $NetBSD: kfilter_register.9,v 1.11 2020/10/31 16:03:01 christos 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 31, 2020 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 void (*f_touch)(struct knote *kn, struct kevent *kev, long hint); 101 /* called during registration and event 102 * processing to provide custom handling 103 * of event fflags and data 104 */ 105}; 106.Ed 107.Pp 108If the filter operation is for a file descriptor, 109.Va f_isfd 110should be non-zero, otherwise it should be zero. 111This controls where the 112.Xr kqueue 2 113system stores the knotes for an object. 114.Sh RETURN VALUES 115.Fn kfilter_register 116returns 0 on success, 117.Er EINVAL 118if there's an invalid argument, or 119.Er EEXIST 120if the filter already exists, 121.Pp 122.Fn kfilter_unregister 123returns 0 on success, 124.Er EINVAL 125if there's an invalid argument, or 126.Er ENOENT 127if the filter doesn't exist. 128.Sh SEE ALSO 129.Xr kqueue 2 , 130.Xr free 9 , 131.Xr knote 9 , 132.Xr malloc 9 133.Sh HISTORY 134The 135.Fn kfilter_register 136and 137.Fn kfilter_unregister 138functions first appeared in 139.Nx 2.0 . 140.Sh AUTHORS 141The 142.Fn kfilter_register 143and 144.Fn kfilter_unregister 145functions were implemented by 146.An Luke Mewburn 147.Aq lukem@NetBSD.org . 148