Sat Oct 31 16:03:01 2020 UTC ()
document f_touch


(christos)
diff -r1.10 -r1.11 src/share/man/man9/kfilter_register.9
cvs diff -r1.10 -r1.11 src/share/man/man9/kfilter_register.9 (switch to unified diff)

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