share/man/man9/kfilter_register.9

   1 .\"     $NetBSD: kfilter_register.9,v 1.9 2003/12/09 19:52:21 augustss 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
  44 The
  45 .Fn kfilter_register
  46 function adds a new kernel event filter (kfilter) to the system,
  47 for use by callers of
  48 .Xr kqueue 2
  49 and
  50 .Xr kevent 2 .
  51 .Fa name
  52 is the name of the new filter (which must not already exist), and
  53 .Fa filtops
  54 is a pointer to a
  55 .Va filterops
  56 structure which describes the filter operations.
  57 Both
  58 .Fa name
  59 and
  60 .Fa filtops
  61 will be copied to an internal data structure, and a new filter number
  62 will be allocated.
  63 If
  64 .Fa retfilter
  65 is not
  66 .Dv NULL ,
  67 then the new filter number will be returned in the address pointed at by
  68 .Fa retfilter .
  69 .Pp
  70 The
  71 .Fn kfilter_unregister
  72 function removes a kfilter named
  73 .Fa name
  74 that was previously registered with
  75 .Fn kfilter_register .
  76 If a filter with the same
  77 .Fa name
  78 is later reregistered with
  79 .Fn kfilter_register ,
  80 it will get a different filter number
  81 (i.e., filter numbers are not recycled).
  82 It is not possible to unregister the system filters
  83 (i.e., those that start with
  84 .Dq EVFILT_
  85 and are documented in
  86 .Xr kqueue 2 ) .
  87 .Pp
  88 The
  89 .Va filterops
  90 structure is defined as follows:
  91 .Bd -literal -offset indent
  92 struct 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
 103 If the filter operation is for a file descriptor,
 104 .Va f_isfd
 105 should be non-zero, otherwise it should be zero.
 106 This controls where the
 107 .Xr kqueue 2
 108 system stores the knotes for an object.
 109 .Sh RETURN VALUES
 110 .Fn kfilter_register
 111 returns 0 on success,
 112 .Er EINVAL
 113 if there's an invalid argument, or
 114 .Er EEXIST
 115 if the filter already exists,
 116 .Pp
 117 .Fn kfilter_unregister
 118 returns 0 on success,
 119 .Er EINVAL
 120 if there's an invalid argument, or
 121 .Er ENOENT
 122 if 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
 129 The
 130 .Fn kfilter_register
 131 and
 132 .Fn kfilter_unregister
 133 functions first appeared in
 134 .Nx 2.0 .
 135 .Sh AUTHORS
 136 The
 137 .Fn kfilter_register
 138 and
 139 .Fn kfilter_unregister
 140 functions were implemented by
 141 .An Luke Mewburn
 142 .Aq lukem@NetBSD.org .