Add a man page describing the fuctions directly related to network domains.

Reviewed by: alfred

1 files changed, 225 insertions, 0 deletions

diff --git a/share/man/man9/domain.9 b/share/man/man9/domain.9
new file mode 100644
index 0000000..28b5ab7
--- /dev/null
+++ b/share/man/man9/domain.9
@@ -0,0 +1,225 @@
+.\"
+.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer as
+.\"    the first lines of this file unmodified other than the possible
+.\"    addition of one or more copyright notices.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd December 7, 2001
+.Dt DOMAIN 9
+.Os
+.Sh NAME
+.Nm net_add_domain ,
+.Nm pfctlinput ,
+.Nm pfctlinput2 ,
+.Nm pffindproto ,
+.Nm pffindtype ,
+.Nm DOMAIN_SET
+.Nd "network domain management"
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/protosw.h
+.In sys/domain.h
+.Ft void
+.Fn net_add_domain "void *data"
+.Ft void
+.Fn pfctlinput "int cmd" "struct sockaddr *sa"
+.Ft void
+.Fn pfctlinput2 "int cmd" "struct sockaddr *sa" "void *ctlparam"
+.Ft struct protosw *
+.Fn pffindproto "int family" "int protocol" "int type"
+.Ft struct protosw *
+.Fn pffindtype "int family" "int type"
+.Ft void
+.Fn DOMAIN_SET "name"
+.Sh DESCRIPTION
+Network protocols installed in the system are maintained within what
+are called domains
+.Pq for example the inetdomain and localdomain .
+.Bd -literal
+
+struct domain {
+        int     dom_family;             /* AF_xxx */
+        char    *dom_name;
+        void    (*dom_init)             /* initialize domain data structures */
+                __P((void));
+        int     (*dom_externalize)      /* externalize access rights */
+                __P((struct mbuf *, struct mbuf **));
+        void    (*dom_dispose)          /* dispose of internalized rights */
+                __P((struct mbuf *));
+        struct  protosw *dom_protosw, *dom_protoswNPROTOSW;
+        struct  domain *dom_next;
+        int     (*dom_rtattach)         /* initialize routing table */
+                __P((void **, int));
+        int     dom_rtoffset;           /* an arg to rtattach, in bits */
+        int     dom_maxrtkey;           /* for routing layer */
+};
+.Ed
+.Pp
+Each domain contains an array of protocol switch structures
+.Pq Vt struct protosw * ,
+one for each socket type supported.
+.Bd -literal
+
+struct protosw {
+        short   pr_type;                /* socket type used for */
+        struct  domain *pr_domain;      /* domain protocol a member of */
+        short   pr_protocol;            /* protocol number */
+        short   pr_flags;               /* see below */
+/* protocol-protocol hooks */
+        pr_input_t *pr_input;           /* input to protocol (from below) */
+        pr_output_t *pr_output;         /* output to protocol (from above) */
+        pr_ctlinput_t *pr_ctlinput;     /* control input (from below) */
+        pr_ctloutput_t *pr_ctloutput;   /* control output (from above) */
+/* user-protocol hook */
+        pr_usrreq_t     *pr_ousrreq;
+/* utility hooks */
+        pr_init_t *pr_init;
+        pr_fasttimo_t *pr_fasttimo;     /* fast timeout (200ms) */
+        pr_slowtimo_t *pr_slowtimo;     /* slow timeout (500ms) */
+        pr_drain_t *pr_drain;           /* flush any excess space possible */
+
+        struct  pr_usrreqs *pr_usrreqs; /* supersedes pr_usrreq() */
+        struct  pfil_head       pr_pfh;
+};
+.Ed
+.Pp
+The following functions handle the registration of a new domain,
+lookups of specific protocols and protocol types within those domains,
+and handle control messages from the system.
+.Pp
+.Fn pfctlinput
+is called by the system whenever an event occurs that could affect every
+domain.
+Examples of those types of events are routing table changes, interface
+shutdowns or certain
+.Dv ICMP
+message types.
+When called,
+.Fn pfctlinput
+calls the protocol specific
+.Fn pr_ctlinput
+function for each protocol in that has defined one, in every domain.
+.Pp
+.Fn pfctlinput2
+provides that same functionality of
+.Fn pfctlinput ,
+but with a few additional checks and a new
+.Vt void *
+argument that is passed directly to the protocols
+.Fn pr_ctlinput
+function.
+Unlike
+.Fn pfctlinput ,
+.Fn pfctlinput2
+verifies that
+.Fa sa
+is not
+.Dv NULL ,
+and that only the protocol families that are the same as
+.Fa sa
+have their
+.Fn pr_ctlinput
+function called.
+.Pp
+.Fn net_add_domain
+adds a new protocol domain to the system.
+The argument
+.Fa data
+is cast directly to
+.Vt struct domain *
+within the function, but is declared
+.Vt void *
+in order to prevent compiler warnings when new domains are registered with
+.Fn SYSINIT .
+In most cases
+.Fn net_add_domain
+is not called directly, instead
+.Fn DOMAIN_SET
+is used.
+.Pp
+If the new domain has defined an initialization routine it is called by
+.Fn net_add_domain ;
+as well, each of the protocols within the domain that have defined an
+initialization routine will have theirs called.
+.Pp
+Once a domain is added it cannot be unloaded.  This is because there is
+no reference counting system in place to determine if there are any
+active references from sockets within that domain.
+.Pp
+.Fn pffindtype
+and
+.Fn pffindproto
+lookup a protocol by its number or by its type.
+In most cases if the protocol or type cannot be found
+.Dv NULL
+is returned, but
+.Fn pffindproto
+may return the default if the requested type is
+.Dv SOCK_RAW ,
+a protocol switch type of
+.Dv SOCK_RAW
+is found, and the domain has a default raw protocol.
+.Pp
+Both functions are called by
+.Fn socreate
+in order to resolve the protocol for the socket currently being created.
+.Pp
+.Fn DOMAIN_SET
+is a macro that simplifies the registration of a domain via SYSINIT.
+The code resulting from the macro expects there to be a domain structure
+named
+.Vt namedomain 
+where name is the argument
+.Fa name .
+.Bd -literal
+
+	struct domain localdomain =
+	{ AF_LOCAL, "local", unp_init, unp_externalize, unp_dispose,
+	  localsw, &localsw[sizeof(localsw)/sizeof(localsw[0])] };
+
+	DOMAIN_SET(local);
+
+.Ed
+.Sh RETURN VALUES
+Both
+.Fn pffindtype
+and
+.Fn pffindproto
+return a
+.Vt struct protosw *
+for the protocol requested.
+If the protocol or socket type is not found
+.Dv NULL
+is returned.
+In the case of
+.Fn pffindproto
+the default protocol may be returned for
+.Dv SOCK_RAW
+types if the domain has a default raw protocol.
+.Sh SEE ALSO
+.Xr socket 2
+.Sh AUTHORS
+This man page was written by
+.An Chad David Aq davidc@acns.ab.ca .