[src/trunk]: src/share/man/man9 PR/56629: Andreas Gustafsson: Update document...

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

details:   https://anonhg.NetBSD.org/src/rev/09479a4f1476
branches:  trunk
changeset: 359650:09479a4f1476
user:      christos <christos%NetBSD.org@localhost>
date:      Sat Jan 15 15:37:15 2022 +0000

description:
PR/56629: Andreas Gustafsson: Update documentation about the filter head
maintainance functions.

diffstat:

 share/man/man9/pfil.9 |  86 +++++++++++++++++++++++++++++++-------------------
 1 files changed, 53 insertions(+), 33 deletions(-)

diffs (143 lines):

diff -r dde7c829edc4 -r 09479a4f1476 share/man/man9/pfil.9
--- a/share/man/man9/pfil.9     Sat Jan 15 14:49:43 2022 +0000
+++ b/share/man/man9/pfil.9     Sat Jan 15 15:37:15 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: pfil.9,v 1.38 2018/01/17 08:34:15 uwe Exp $
+.\"    $NetBSD: pfil.9,v 1.39 2022/01/15 15:37:15 christos Exp $
 .\"
 .\" Copyright (c) 1996 Matthew R. Green
 .\" All rights reserved.
@@ -24,13 +24,13 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd January 17, 2018
+.Dd January 15, 2022
 .Dt PFIL 9
 .Os
 .Sh NAME
 .Nm pfil ,
-.Nm pfil_head_register ,
-.Nm pfil_head_unregister ,
+.Nm pfil_head_create ,
+.Nm pfil_head_destroy ,
 .Nm pfil_head_get ,
 .Nm pfil_hook_get ,
 .Nm pfil_add_hook ,
@@ -46,32 +46,32 @@
 .In sys/mbuf.h
 .In net/if.h
 .In net/pfil.h
-.Ft int
-.Fn pfil_head_register "struct pfil_head *ph"
+.Ft pfil_head_t *
+.Fn pfil_head_create "int type" "void *key"
 .Ft int
-.Fn pfil_head_unregister "struct pfil_head *ph"
-.Ft struct pfil_head *
-.Fn pfil_head_get "int af" "u_long dlt"
+.Fn pfil_head_destroy "pfil_head_t *ph"
+.Ft pfil_head_t *
+.Fn pfil_head_get "int type" "void *key"
 .Ft struct packet_filter_hook *
-.Fn pfil_hook_get "int dir" "struct pfil_head *ph"
+.Fn pfil_hook_get "int dir" "pfil_head_t *ph"
 .Ft int
-.Fn pfil_add_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *ph"
+.Fn pfil_add_hook "pfil_func_t func" "void *arg" "int flags" "pfil_head_t *ph"
 .Ft int
-.Fn pfil_remove_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *ph"
+.Fn pfil_remove_hook "pfil_func_t func" "void *arg" "int flags" "pfil_head_t *ph"
 .Ft int
 .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"
+.Fn pfil_run_hooks "pfil_head_t *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"
+.Fn pfil_add_ihook "pfil_ifunc_t ifunc" "void *arg" "int flags" "pfil_head_t *ph"
 .Ft int
-.Fn pfil_remove_ihook "void (*ifunc)()" "void *arg" "int flags" "struct pfil_head *ph"
+.Fn pfil_remove_ihook "pfil_ifunc_t ifunc" "void *arg" "int flags" "pfil_head_t *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"
+.Fn pfil_run_addrhooks "pfil_head_t *ph" "unsigned long" "struct ifaddr *ifa"
 .Ft void
-.Fn pfil_run_ifhooks "struct pfil_head *ph" "unsigned long" "struct ifnet *ifp"
+.Fn pfil_run_ifhooks "pfil_head_t *ph" "unsigned long" "struct ifnet *ifp"
 .Sh DESCRIPTION
 The
 .Nm
@@ -80,25 +80,42 @@
 These hooks may be used to implement a firewall or perform packet
 transformations.
 .Pp
-Packet filtering points are registered with
-.Fn pfil_head_register .
-Filtering points are identified by a key
-.Vt ( void * )
-and a data link type
+Packet filtering points are created with
+.Fn pfil_head_create .
+Filtering points are identified by a
+data link
 .Vt ( int )
-in the
-.Vt pfil_head
-structure.
-Packet filters use the key and data link type to look up the filtering
-point with which they register themselves.
-The key is unique to the filtering point.
-The data link type is a
+.Fa type
+and a
+.Vt ( void * )
+.Fa key .
+If a packet filtering point already exists for that data link
+.Fa type
+and
+.Fa key
+then the
+.Fn pfil_head_create
+function returns
+.Dv NULL .
+Packet filters use the
+.Fn pfil_head_get 
+function specifying the data link
+.Fa type
+and the
+.Fa key
+to look up the filtering point with which they register themselves.
+The 
+.Fa key
+is unique to the filtering point.
+The data link
+.Fa type
+is a
 .Xr bpf 4
 .Dv DLT_ Ns Ar type
 constant indicating what kind of header is present on the packet
 at the filtering point.
-Filtering points may be unregistered with the
-.Fn pfil_head_unregister
+Filtering points may be destroyed with the
+.Fn pfil_head_destroy
 function.
 .Pp
 Packet filters register/unregister themselves with a filtering point
@@ -109,8 +126,11 @@
 functions, respectively.
 The head is looked up using the
 .Fn pfil_head_get
-function, which takes the key and data link type that the packet filter
-expects.
+function, which takes the data link
+.Fa type
+and the
+.Fa key 
+that the packet filter expects.
 Filters may provide an argument to be passed to the filter when
 invoked on a packet.
 .Pp