[src/trunk]: src document pfil_{add, remove}_ihook, pfil_run_{addr, if}hooks

[maya <maya%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e21382296ca5
branches:  trunk
changeset: 829106:e21382296ca5
user:      maya <maya%NetBSD.org@localhost>
date:      Wed Jan 17 02:45:38 2018 +0000

description:
document pfil_{add,remove}_ihook, pfil_run_{addr,if}hooks

from ryo shimizu in PR bin/51941

changes by myself: fix mdoc -Tlint, add missing set lists, adjust date
to today, reword history addition.

diffstat:

 distrib/sets/lists/comp/mi |  14 ++++++++++-
 share/man/man9/Makefile    |   8 ++++-
 share/man/man9/pfil.9      |  57 +++++++++++++++++++++++++++++++++++++++------
 3 files changed, 68 insertions(+), 11 deletions(-)

diffs (197 lines):

diff -r 22cc39482864 -r e21382296ca5 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Wed Jan 17 02:39:16 2018 +0000
+++ b/distrib/sets/lists/comp/mi        Wed Jan 17 02:45:38 2018 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.2169 2018/01/10 11:02:41 knakahara Exp $
+#      $NetBSD: mi,v 1.2170 2018/01/17 02:45:38 maya Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 ./etc/mtree/set.comp                           comp-sys-root
@@ -11011,13 +11011,17 @@
 ./usr/share/man/cat9/percpu_putref.0           comp-sys-catman         .cat
 ./usr/share/man/cat9/pfil.0                    comp-sys-catman         .cat
 ./usr/share/man/cat9/pfil_add_hook.0           comp-sys-catman         .cat
+./usr/share/man/cat9/pfil_add_ihook.0          comp-sys-catman         .cat
 ./usr/share/man/cat9/pfil_get_head.0           comp-obsolete           obsolete
 ./usr/share/man/cat9/pfil_head_get.0           comp-sys-catman         .cat
 ./usr/share/man/cat9/pfil_head_register.0      comp-sys-catman         .cat
 ./usr/share/man/cat9/pfil_head_unregister.0    comp-sys-catman         .cat
 ./usr/share/man/cat9/pfil_hook_get.0           comp-sys-catman         .cat
 ./usr/share/man/cat9/pfil_remove_hook.0                comp-sys-catman         .cat
+./usr/share/man/cat9/pfil_remove_ihook.0       comp-sys-catman         .cat
+./usr/share/man/cat9/pfil_run_addrhooks.0      comp-sys-catman         .cat
 ./usr/share/man/cat9/pfil_run_hooks.0          comp-sys-catman         .cat
+./usr/share/man/cat9/pfil_run_ifhooks.0                comp-sys-catman         .cat
 ./usr/share/man/cat9/pfind.0                   comp-obsolete           obsolete
 ./usr/share/man/cat9/pg_find.0                 comp-obsolete           obsolete
 ./usr/share/man/cat9/pgfind.0                  comp-obsolete           obsolete
@@ -18477,12 +18481,16 @@
 ./usr/share/man/html9/percpu_putref.html       comp-sys-htmlman        html
 ./usr/share/man/html9/pfil.html                        comp-sys-htmlman        html
 ./usr/share/man/html9/pfil_add_hook.html       comp-sys-htmlman        html
+./usr/share/man/html9/pfil_add_ihook.html      comp-sys-htmlman        html
 ./usr/share/man/html9/pfil_head_get.html       comp-sys-htmlman        html
 ./usr/share/man/html9/pfil_head_register.html  comp-sys-htmlman        html
 ./usr/share/man/html9/pfil_head_unregister.html comp-sys-htmlman       html
 ./usr/share/man/html9/pfil_hook_get.html       comp-sys-htmlman        html
 ./usr/share/man/html9/pfil_remove_hook.html    comp-sys-htmlman        html
+./usr/share/man/html9/pfil_remove_ihook.html   comp-sys-htmlman        html
+./usr/share/man/html9/pfil_run_addrhooks.html  comp-sys-htmlman        html
 ./usr/share/man/html9/pfil_run_hooks.html      comp-sys-htmlman        html
+./usr/share/man/html9/pfil_run_ifhooks.html    comp-sys-htmlman        html
 ./usr/share/man/html9/pfind.html               comp-obsolete           obsolete
 ./usr/share/man/html9/pg_find.html             comp-obsolete           obsolete
 ./usr/share/man/html9/pgfind.html              comp-obsolete           obsolete
@@ -26103,13 +26111,17 @@
 ./usr/share/man/man9/percpu_putref.9           comp-sys-man            .man
 ./usr/share/man/man9/pfil.9                    comp-sys-man            .man
 ./usr/share/man/man9/pfil_add_hook.9           comp-sys-man            .man
+./usr/share/man/man9/pfil_add_ihook.9          comp-sys-man            .man
 ./usr/share/man/man9/pfil_get_head.9           comp-obsolete           obsolete
 ./usr/share/man/man9/pfil_head_get.9           comp-sys-man            .man
 ./usr/share/man/man9/pfil_head_register.9      comp-sys-man            .man
 ./usr/share/man/man9/pfil_head_unregister.9    comp-sys-man            .man
 ./usr/share/man/man9/pfil_hook_get.9           comp-sys-man            .man
 ./usr/share/man/man9/pfil_remove_hook.9                comp-sys-man            .man
+./usr/share/man/man9/pfil_remove_ihook.9       comp-sys-man            .man
+./usr/share/man/man9/pfil_run_addrhooks.9      comp-sys-man            .man
 ./usr/share/man/man9/pfil_run_hooks.9          comp-sys-man            .man
+./usr/share/man/man9/pfil_run_ifhooks.9                comp-sys-man            .man
 ./usr/share/man/man9/pfind.9                   comp-obsolete           obsolete
 ./usr/share/man/man9/pg_find.9                 comp-obsolete           obsolete
 ./usr/share/man/man9/pgfind.9                  comp-obsolete           obsolete
diff -r 22cc39482864 -r e21382296ca5 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Wed Jan 17 02:39:16 2018 +0000
+++ b/share/man/man9/Makefile   Wed Jan 17 02:45:38 2018 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.417 2017/11/07 18:36:27 christos Exp $
+#       $NetBSD: Makefile,v 1.418 2018/01/17 02:45:38 maya Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -663,10 +663,14 @@
 MLINKS+=pfil.9 pfil_hook_get.9 \
        pfil.9 pfil_add_hook.9 \
        pfil.9 pfil_remove_hook.9 \
+       pfil.9 pfil_add_ihook.9 \
+       pfil.9 pfil_remove_ihook.9 \
        pfil.9 pfil_head_register.9 \
        pfil.9 pfil_head_unregister.9 \
        pfil.9 pfil_head_get.9 \
-       pfil.9 pfil_run_hooks.9
+       pfil.9 pfil_run_hooks.9 \
+       pfil.9 pfil_run_addrhooks.9 \
+       pfil.9 pfil_run_ifhooks.9
 MLINKS+=pmap.9 pmap_init.9 \
        pmap.9 pmap_virtual_space.9 \
        pmap.9 pmap_steal_memory.9 \
diff -r 22cc39482864 -r e21382296ca5 share/man/man9/pfil.9
--- a/share/man/man9/pfil.9     Wed Jan 17 02:39:16 2018 +0000
+++ b/share/man/man9/pfil.9     Wed Jan 17 02:45:38 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: pfil.9,v 1.35 2016/06/01 08:17:47 wiz Exp $
+.\"    $NetBSD: pfil.9,v 1.36 2018/01/17 02:45:38 maya Exp $
 .\"
 .\" Copyright (c) 1996 Matthew R. Green
 .\" All rights reserved.
@@ -24,7 +24,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd June 1, 2016
+.Dd January 17, 2018
 .Dt PFIL 9
 .Os
 .Sh NAME
@@ -35,7 +35,11 @@
 .Nm pfil_hook_get ,
 .Nm pfil_add_hook ,
 .Nm pfil_remove_hook ,
-.Nm pfil_run_hooks
+.Nm pfil_run_hooks ,
+.Nm pfil_add_ihook ,
+.Nm pfil_remove_ihook ,
+.Nm pfil_run_addrhooks ,
+.Nm pfil_run_ifhooks
 .Nd packet filter interface
 .Sh SYNOPSIS
 .In sys/param.h
@@ -58,6 +62,16 @@
 .Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir"
 .Ft int
 .Fn pfil_run_hooks "struct pfil_head *ph" "struct mbuf **mp" "struct ifnet *ifp" "int dir"
+.Ft int
+.Fn pfil_add_ihook "void (*ifunc)()" "void *arg" "int flags" "struct pfil_head *ph"
+.Ft int
+.Fn pfil_remove_ihook "void (*ifunc)()" "void *arg" "int flags" "struct pfil_head *ph"
+.Ft void
+.Fn (*ifunc) "void *arg" "unsigned long cmd" "void *ptr"
+.Ft void
+.Fn pfil_run_addrhooks "struct pfil_head *ph" "unsigned long" "struct ifaddr *ifa"
+.Ft void
+.Fn pfil_run_ifhooks "struct pfil_head *ph" "unsigned long" "struct ifnet *ifp"
 .Sh DESCRIPTION
 The
 .Nm
@@ -120,22 +134,44 @@
 .Fn pfil_remove_hook
 functions, indicates when the filter should be called.
 The flags are:
-.Bl -tag -offset indent -width PFIL_WAITOK -compact
+.Bl -tag -offset indent -width PFIL_ALL -compact
 .It PFIL_IN
 call me on incoming packets
 .It PFIL_OUT
 call me on outgoing packets
 .It PFIL_ALL
 call me on all of the above
+.El
+.Pp
+By the same token, event handlers register/unregister themselves
+with the
+.Fn pfil_add_ihook
+and
+.Fn pfil_remove_ihook
+functions, respectively.
+The event handler is called with its specified argument, the event id
+.Dv ( PFIL_IFNET_ATTACH
+or
+.Dv PFIL_IFNET_DETACH ,
+see also below) or ioctl number, and the pointer
+to the network interface or the pointer to the ifaddr.
+.Pp
+The
+.Em flags
+parameter, used in the
+.Fn pfil_add_ihook
+and
+.Fn pfil_remove_ihook
+functions, indicates when the filter should be called.
+The flags are:
+.Bl -tag -offset indent -width PFIL_IFADDR -compact
 .It PFIL_IFADDR
-call me on interface reconfig (mbuf ** is ioctl #)
+call me on interface reconfig (cmd is ioctl #)
 .It PFIL_IFNET
-call me on interface attach/detach (mbuf ** is either
+call me on interface attach/detach (cmd is either
 .Dv PFIL_IFNET_ATTACH
 or
 .Dv PFIL_IFNET_DETACH )
-.It PFIL_WAITOK
-OK to call malloc with M_WAITOK.
 .El
 .Sh SEE ALSO
 .Xr bpf 4
@@ -171,6 +207,11 @@
 .Nm
 framework was changed to work with an arbitrary number of filtering points,
 as well as be less IP-centric.
+.Pp
+.Fn pfil_add_ihook
+and
+.Fn pfil_remove_ihook
+were added in 8.0.
 .Sh AUTHORS
 .An -nosplit
 The