Module Name: src
Committed By: christos
Date: Sat Jan 15 15:37:15 UTC 2022
Modified Files:
src/share/man/man9: pfil.9
Log Message:
PR/56629: Andreas Gustafsson: Update documentation about the filter head
maintainance functions.
To generate a diff of this commit:
cvs rdiff -u -r1.38 -r1.39 src/share/man/man9/pfil.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/pfil.9
diff -u src/share/man/man9/pfil.9:1.38 src/share/man/man9/pfil.9:1.39
--- src/share/man/man9/pfil.9:1.38 Wed Jan 17 03:34:15 2018
+++ src/share/man/man9/pfil.9 Sat Jan 15 10:37:15 2022
@@ -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 pfil_head_t *
+.Fn pfil_head_create "int type" "void *key"
.Ft int
-.Fn pfil_head_register "struct pfil_head *ph"
-.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 @@ incoming or outgoing packet for a partic
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 @@ and
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
