share/man/man9/domain.9

   1 .\"
   2 .\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  18 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  25 .\" DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd December 7, 2001
  30 .Dt DOMAIN 9
  31 .Os
  32 .Sh NAME
  33 .Nm net_add_domain ,
  34 .Nm pfctlinput ,
  35 .Nm pfctlinput2 ,
  36 .Nm pffindproto ,
  37 .Nm pffindtype ,
  38 .Nm DOMAIN_SET
  39 .Nd "network domain management"
  40 .Sh SYNOPSIS
  41 .In sys/param.h
  42 .In sys/kernel.h
  43 .In sys/protosw.h
  44 .In sys/domain.h
  45 .Ft void
  46 .Fn net_add_domain "void *data"
  47 .Ft void
  48 .Fn pfctlinput "int cmd" "struct sockaddr *sa"
  49 .Ft void
  50 .Fn pfctlinput2 "int cmd" "struct sockaddr *sa" "void *ctlparam"
  51 .Ft struct protosw *
  52 .Fn pffindproto "int family" "int protocol" "int type"
  53 .Ft struct protosw *
  54 .Fn pffindtype "int family" "int type"
  55 .Ft void
  56 .Fn DOMAIN_SET "name"
  57 .Sh DESCRIPTION
  58 Network protocols installed in the system are maintained within what
  59 are called domains
  60 (for example the
  61 .Va inetdomain
  62 and
  63 .Va localdomain ) .
  64 .Bd -literal
  65 struct domain {
  66         int     dom_family;             /* AF_xxx */
  67         char    *dom_name;
  68         void    (*dom_init)             /* initialize domain data structures */
  69                 (void);
  70         int     (*dom_externalize)      /* externalize access rights */
  71                 (struct mbuf *, struct mbuf **);
  72         void    (*dom_dispose)          /* dispose of internalized rights */
  73                 (struct mbuf *);
  74         struct  protosw *dom_protosw, *dom_protoswNPROTOSW;
  75         struct  domain *dom_next;
  76         int     (*dom_rtattach)         /* initialize routing table */
  77                 (void **, int);
  78         int     dom_rtoffset;           /* an arg to rtattach, in bits */
  79         int     dom_maxrtkey;           /* for routing layer */
  80 };
  81 .Ed
  82 .Pp
  83 Each domain contains an array of protocol switch structures
  84 .Pq Vt "struct protosw *" ,
  85 one for each socket type supported.
  86 .Bd -literal
  87 struct protosw {
  88         short   pr_type;                /* socket type used for */
  89         struct  domain *pr_domain;      /* domain protocol a member of */
  90         short   pr_protocol;            /* protocol number */
  91         short   pr_flags;               /* see below */
  92 /* protocol-protocol hooks */
  93         pr_input_t *pr_input;           /* input to protocol (from below) */
  94         pr_output_t *pr_output;         /* output to protocol (from above) */
  95         pr_ctlinput_t *pr_ctlinput;     /* control input (from below) */
  96         pr_ctloutput_t *pr_ctloutput;   /* control output (from above) */
  97 /* user-protocol hook */
  98         pr_usrreq_t     *pr_ousrreq;
  99 /* utility hooks */
 100         pr_init_t *pr_init;
 101         pr_fasttimo_t *pr_fasttimo;     /* fast timeout (200ms) */
 102         pr_slowtimo_t *pr_slowtimo;     /* slow timeout (500ms) */
 103         pr_drain_t *pr_drain;           /* flush any excess space possible */
 104
 105         struct  pr_usrreqs *pr_usrreqs; /* supersedes pr_usrreq() */
 106         struct  pfil_head       pr_pfh;
 107 };
 108 .Ed
 109 .Pp
 110 The following functions handle the registration of a new domain,
 111 lookups of specific protocols and protocol types within those domains,
 112 and handle control messages from the system.
 113 .Pp
 114 .Fn pfctlinput
 115 is called by the system whenever an event occurs that could affect every
 116 domain.
 117 Examples of those types of events are routing table changes, interface
 118 shutdowns or certain
 119 .Tn ICMP
 120 message types.
 121 When called,
 122 .Fn pfctlinput
 123 calls the protocol specific
 124 .Fn pr_ctlinput
 125 function for each protocol in that has defined one, in every domain.
 126 .Pp
 127 .Fn pfctlinput2
 128 provides that same functionality of
 129 .Fn pfctlinput ,
 130 but with a few additional checks and a new
 131 .Vt "void *"
 132 argument that is passed directly to the protocol's
 133 .Fn pr_ctlinput
 134 function.
 135 Unlike
 136 .Fn pfctlinput ,
 137 .Fn pfctlinput2
 138 verifies that
 139 .Fa sa
 140 is not
 141 .Dv NULL ,
 142 and that only the protocol families that are the same as
 143 .Fa sa
 144 have their
 145 .Fn pr_ctlinput
 146 function called.
 147 .Pp
 148 .Fn net_add_domain
 149 adds a new protocol domain to the system.
 150 The argument
 151 .Fa data
 152 is cast directly to
 153 .Vt "struct domain *"
 154 within the function, but is declared
 155 .Vt "void *"
 156 in order to prevent compiler warnings when new domains are registered with
 157 .Fn SYSINIT .
 158 In most cases
 159 .Fn net_add_domain
 160 is not called directly, instead
 161 .Fn DOMAIN_SET
 162 is used.
 163 .Pp
 164 If the new domain has defined an initialization routine, it is called by
 165 .Fn net_add_domain ;
 166 as well, each of the protocols within the domain that have defined an
 167 initialization routine will have theirs called.
 168 .Pp
 169 Once a domain is added it cannot be unloaded.
 170 This is because there is
 171 no reference counting system in place to determine if there are any
 172 active references from sockets within that domain.
 173 .Pp
 174 .Fn pffindtype
 175 and
 176 .Fn pffindproto
 177 look up a protocol by its number or by its type.
 178 In most cases, if the protocol or type cannot be found,
 179 .Dv NULL
 180 is returned, but
 181 .Fn pffindproto
 182 may return the default if the requested type is
 183 .Dv SOCK_RAW ,
 184 a protocol switch type of
 185 .Dv SOCK_RAW
 186 is found, and the domain has a default raw protocol.
 187 .Pp
 188 Both functions are called by
 189 .Fn socreate
 190 in order to resolve the protocol for the socket currently being created.
 191 .Pp
 192 .Fn DOMAIN_SET
 193 is a macro that simplifies the registration of a domain via
 194 .Fn SYSINIT .
 195 The code resulting from the macro expects there to be a domain structure
 196 named
 197 .Dq Fa name Ns Li domain
 198 where
 199 .Fa name
 200 is the argument to
 201 .Fn DOMAIN_SET :
 202 .Bd -literal
 203 struct domain localdomain =
 204 { AF_LOCAL, "local", unp_init, unp_externalize, unp_dispose,
 205   localsw, &localsw[sizeof(localsw)/sizeof(localsw[0])] };
 206
 207 DOMAIN_SET(local);
 208 .Ed
 209 .Sh RETURN VALUES
 210 Both
 211 .Fn pffindtype
 212 and
 213 .Fn pffindproto
 214 return a
 215 .Vt "struct protosw *"
 216 for the protocol requested.
 217 If the protocol or socket type is not found,
 218 .Dv NULL
 219 is returned.
 220 In the case of
 221 .Fn pffindproto ,
 222 the default protocol may be returned for
 223 .Dv SOCK_RAW
 224 types if the domain has a default raw protocol.
 225 .Sh SEE ALSO
 226 .Xr socket 2
 227 .Sh AUTHORS
 228 This manual page was written by
 229 .An Chad David Aq davidc@acns.ab.ca .