share/man/man9/rtalloc.9

   1 .\"
   2 .\" Copyright 1996 Massachusetts Institute of Technology
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software and
   5 .\" its documentation for any purpose and without fee is hereby
   6 .\" granted, provided that both the above copyright notice and this
   7 .\" permission notice appear in all copies, that both the above
   8 .\" copyright notice and this permission notice appear in all
   9 .\" supporting documentation, and that the name of M.I.T. not be used
  10 .\" in advertising or publicity pertaining to distribution of the
  11 .\" software without specific, written prior permission.  M.I.T. makes
  12 .\" no representations about the suitability of this software for any
  13 .\" purpose.  It is provided "as is" without express or implied
  14 .\" warranty.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
  17 .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  20 .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  23 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  24 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  25 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  26 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD: src/share/man/man9/rtalloc.9,v 1.8.2.4 2001/12/17 11:30:18 ru Exp $
  30 .\" $DragonFly: src/share/man/man9/rtalloc.9,v 1.3 2003/07/27 05:36:06 hmp Exp $
  31 .Dd October 8, 1996
  32 .Os
  33 .Dt RTALLOC 9
  34 .Sh NAME
  35 .Nm rtalloc ,
  36 .Nm rtalloc_ign ,
  37 .Nm rtalloc1
  38 .Nd look up a route in the kernel routing table
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In sys/socket.h
  42 .In net/route.h
  43 .Ft void
  44 .Fn rtalloc "struct route *ro"
  45 .Ft void
  46 .Fn rtalloc_ign "struct route *ro" "u_long flags"
  47 .Ft "struct rtentry *"
  48 .Fn rtalloc1 "struct sockaddr *sa" "int report" "u_long flags"
  49 .Sh DESCRIPTION
  50 The kernel uses a radix tree structure to manage routes for the
  51 networking subsystem.  The
  52 .Fn rtalloc
  53 family of routines is used by protocols to query this structure for a
  54 route corresponding to a particular end-node address, and to cause
  55 certain protocol\- and interface-specific actions to take place.
  56 .\" XXX - -mdoc should contain a standard request for getting em and
  57 .\" en dashes.
  58 .Pp
  59 When a route with the flag
  60 .Dv RTF_CLONING
  61 or
  62 .Dv RTF_PRCLONING
  63 is retrieved, and the action of those flags is not masked, the
  64 .Nm
  65 facility automatically generates a new route using information in the
  66 old route as a template, and in the case of
  67 .Dv RTF_CLONING ,
  68 sends an
  69 .Dv RTM_RESOLVE
  70 message to the appropriate interface-address route-management routine
  71 .Pq Fn ifa->ifa_rtrequest .
  72 .Dv RTF_PRCLONING
  73 routes are assumed to be managed by the protocol family and no
  74 resolution requests are made, but all routes generated by the cloning
  75 process retain a reference to the route from which they were
  76 generated.
  77 If the
  78 .Dv RTF_XRESOLVE
  79 flag is set, then the
  80 .Dv RTM_RESOLVE
  81 message is sent instead on the
  82 .Xr route 4
  83 socket interface, requesting that an external program resolve the
  84 address in question and modify the route appropriately.
  85 .Pp
  86 The default interface is
  87 .Fn rtalloc .
  88 Its only argument is
  89 .Fa ro ,
  90 a pointer to a
  91 .Dq Li "struct route" ,
  92 which is defined as follows:
  93 .Bd -literal -offset indent
  94 struct route {
  95         struct sockaddr ro_dst;
  96         struct rtentry *ro_rt;
  97 };
  98 .Ed
  99 Thus, this function can only be used for address families which are
 100 smaller than the default
 101 .Dq Li "struct sockaddr" .
 102 Before calling
 103 .Fn rtalloc
 104 for the first time, callers should ensure that unused bits of the
 105 structure are set to zero.  On subsequent calls,
 106 .Fn rtalloc
 107 returns without performing a lookup if
 108 .Va ro->ro_rt
 109 is non-null and the
 110 .Dv RTF_UP
 111 flag is set in the route's
 112 .Li rt_flags
 113 field.
 114 .Pp
 115 The
 116 .Fn rtalloc_ign
 117 interface can be used when the default actions of
 118 .Fn rtalloc
 119 in the presence of the
 120 .Dv RTF_CLONING
 121 and
 122 .Dv RTF_PRCLONING
 123 flags are undesired.  The
 124 .Fa ro
 125 argument is the same as
 126 .Fn rtalloc ,
 127 but there is additionally a
 128 .Fa flags
 129 argument, which lists the flags in the route which are to be
 130 .Em ignored
 131 (ordinarily, one or both of
 132 .Dv RTF_CLONING
 133 or
 134 .Dv RTF_PRCLONING ) .
 135 .Pp
 136 The
 137 .Fn rtalloc1
 138 function is the most general form of
 139 .Fn rtalloc
 140 (and both of the other forms are implemented as calls to rtalloc1).
 141 It does not use the
 142 .Dq Li "struct route" ,
 143 and is therefore suitable for address families which require more
 144 space than is in a traditional
 145 .Dq Li "struct sockaddr" .
 146 Instead, it takes a
 147 .Dq Li "struct sockaddr *"
 148 directly as the
 149 .Fa sa
 150 argument.  The second argument,
 151 .Fa report ,
 152 controls whether
 153 .Dv RTM_RESOLVE
 154 requests are sent to the lower layers when an
 155 .Dv RTF_CLONING
 156 or
 157 .Dv RTF_PRCLONING
 158 route is cloned.  Ordinarily a value of one should be passed, except
 159 in the processing of those lower layers which use the cloning
 160 facility.
 161 The third argument,
 162 .Fa flags ,
 163 is a set of flags to ignore, as in
 164 .Fn rtalloc_ign .
 165 .Sh RETURN VALUES
 166 The
 167 .Fn rtalloc
 168 and
 169 .Fn rtalloc_ign
 170 functions do not return a value.  The
 171 .Fn rtalloc1
 172 function returns a pointer to a routing-table entry if it succeeds,
 173 otherwise a null pointer.  Lack of a route should in most cases be
 174 translated to the
 175 .Xr errno 2
 176 value
 177 .Er EHOSTUNREACH .
 178 .Sh SEE ALSO
 179 .Xr route 4 ,
 180 .Xr rtentry 9
 181 .Sh HISTORY
 182 The
 183 .Nm
 184 facility first appeared in
 185 .Bx 4.2 ,
 186 although with much different internals.  The
 187 .Fn rtalloc_ign
 188 function and the
 189 .Fa flags
 190 argument to
 191 .Fn rtalloc1
 192 first appeared in
 193 .Fx 2.0 .
 194 .Sh AUTHORS
 195 This manual page was written by
 196 .An Garrett Wollman ,
 197 as were the changes to implement
 198 .Dv RTF_PRCLONING
 199 and the
 200 .Fn rtalloc_ign
 201 function and the
 202 .Fa flags
 203 argument to
 204 .Fn rtalloc1 .