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 April 13, 2021
  30 .Dt DOMAIN 9
  31 .Os
  32 .Sh NAME
  33 .Nm domain_add ,
  34 .Nm pfctlinput ,
  35 .Nm pffinddomain ,
  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 domain_add "void *data"
  47 .Ft void
  48 .Fn pfctlinput "int cmd" "struct sockaddr *sa"
  49 .Ft struct domain *
  50 .Fn pffinddomain "int family"
  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         void    (*dom_destroy)          /* cleanup structures / state */
  71                 (void);
  72         int     (*dom_externalize)      /* externalize access rights */
  73                 (struct mbuf *, struct mbuf **);
  74         void    (*dom_dispose)          /* dispose of internalized rights */
  75                 (struct mbuf *);
  76         struct  protosw *dom_protosw, *dom_protoswNPROTOSW;
  77         struct  domain *dom_next;
  78         int     (*dom_rtattach)         /* initialize routing table */
  79                 (void **, int);
  80         int     (*dom_rtdetach)         /* clean up routing table */
  81                 (void **, int);
  82         void    *(*dom_ifattach)(struct ifnet *);
  83         void    (*dom_ifdetach)(struct ifnet *, void *);
  84         int     (*dom_ifmtu)(struct ifnet *);
  85                                         /* af-dependent data on ifnet */
  86 };
  87 .Ed
  88 .Pp
  89 Each domain contains an array of protocol switch structures
  90 .Pq Vt "struct protosw *" ,
  91 one for each socket type supported.
  92 .Bd -literal
  93 struct protosw {
  94         short   pr_type;                /* socket type used for */
  95         struct  domain *pr_domain;      /* domain protocol a member of */
  96         short   pr_protocol;            /* protocol number */
  97         short   pr_flags;               /* see below */
  98 /* protocol-protocol hooks */
  99         pr_input_t *pr_input;           /* input to protocol (from below) */
 100         pr_output_t *pr_output;         /* output to protocol (from above) */
 101         pr_ctlinput_t *pr_ctlinput;     /* control input (from below) */
 102         pr_ctloutput_t *pr_ctloutput;   /* control output (from above) */
 103 /* utility hooks */
 104         pr_init_t *pr_init;
 105         pr_fasttimo_t *pr_fasttimo;     /* fast timeout (200ms) */
 106         pr_slowtimo_t *pr_slowtimo;     /* slow timeout (500ms) */
 107         pr_drain_t *pr_drain;           /* flush any excess space possible */
 108
 109         struct  pr_usrreqs *pr_usrreqs; /* user-protocol hook */
 110 };
 111 .Ed
 112 .Pp
 113 The following functions handle the registration of a new domain,
 114 lookups of specific protocols and protocol types within those domains,
 115 and handle control messages from the system.
 116 .Pp
 117 .Fn pfctlinput
 118 is called by the system whenever an event occurs that could affect every
 119 domain.
 120 Examples of those types of events are routing table changes, interface
 121 shutdowns or certain
 122 .Tn ICMP
 123 message types.
 124 When called,
 125 .Fn pfctlinput
 126 calls the protocol specific
 127 .Fn pr_ctlinput
 128 function for each protocol in that has defined one, in every domain.
 129 .Pp
 130 .Fn domain_add
 131 adds a new protocol domain to the system.
 132 The argument
 133 .Fa data
 134 is cast directly to
 135 .Vt "struct domain *"
 136 within the function, but is declared
 137 .Vt "void *"
 138 in order to prevent compiler warnings when new domains are registered with
 139 .Fn SYSINIT .
 140 In most cases
 141 .Fn domain_add
 142 is not called directly, instead
 143 .Fn DOMAIN_SET
 144 is used.
 145 .Pp
 146 If the new domain has defined an initialization routine, it is called by
 147 .Fn domain_add ;
 148 as well, each of the protocols within the domain that have defined an
 149 initialization routine will have theirs called.
 150 .Pp
 151 Once a domain is added it cannot be unloaded.
 152 This is because there is
 153 no reference counting system in place to determine if there are any
 154 active references from sockets within that domain.
 155 .Pp
 156 .Fn pffinddomain
 157 finds a domain by family.
 158 If the domain cannot be found,
 159 .Dv NULL
 160 is returned.
 161 .Pp
 162 .Fn pffindtype
 163 and
 164 .Fn pffindproto
 165 look up a protocol by its number or by its type.
 166 In most cases, if the protocol or type cannot be found,
 167 .Dv NULL
 168 is returned, but
 169 .Fn pffindproto
 170 may return the default if the requested type is
 171 .Dv SOCK_RAW ,
 172 a protocol switch type of
 173 .Dv SOCK_RAW
 174 is found, and the domain has a default raw protocol.
 175 .Pp
 176 Both functions are called by
 177 .Fn socreate
 178 in order to resolve the protocol for the socket currently being created.
 179 .Pp
 180 .Fn DOMAIN_SET
 181 is a macro that simplifies the registration of a domain via
 182 .Fn SYSINIT .
 183 The code resulting from the macro expects there to be a domain structure
 184 named
 185 .Dq Fa name Ns Li domain
 186 where
 187 .Fa name
 188 is the argument to
 189 .Fn DOMAIN_SET :
 190 .Bd -literal
 191 struct domain localdomain =
 192 { AF_LOCAL, "local", unp_init, unp_externalize, unp_dispose,
 193   localsw, &localsw[sizeof(localsw)/sizeof(localsw[0])] };
 194
 195 DOMAIN_SET(local);
 196 .Ed
 197 .Sh RETURN VALUES
 198 Both
 199 .Fn pffindtype
 200 and
 201 .Fn pffindproto
 202 return a
 203 .Vt "struct protosw *"
 204 for the protocol requested.
 205 If the protocol or socket type is not found,
 206 .Dv NULL
 207 is returned.
 208 In the case of
 209 .Fn pffindproto ,
 210 the default protocol may be returned for
 211 .Dv SOCK_RAW
 212 types if the domain has a default raw protocol.
 213 .Sh SEE ALSO
 214 .Xr socket 2
 215 .Sh HISTORY
 216 The functions
 217 .Fn domain_add ,
 218 .Fn pfctlinput ,
 219 .Fn pffinddomain ,
 220 .Fn pffindproto ,
 221 .Fn pffindtype
 222 and
 223 .Fn DOMAIN_SET
 224 first appeared in
 225 .Fx 4.4 .
 226 .Sh AUTHORS
 227 This manual page was written by
 228 .An Chad David Aq Mt davidc@acns.ab.ca .