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 .Dd October 8, 1996
  31 .Os
  32 .Dt RTALLOC 9
  33 .Sh NAME
  34 .Nm rtalloc ,
  35 .Nm rtalloc_ign ,
  36 .Nm rtalloc1
  37 .Nd look up a route in the kernel routing table
  38 .Sh SYNOPSIS
  39 .In sys/types.h
  40 .In sys/socket.h
  41 .In net/route.h
  42 .Ft void
  43 .Fn rtalloc "struct route *ro"
  44 .Ft void
  45 .Fn rtalloc_ign "struct route *ro" "u_long flags"
  46 .Ft "struct rtentry *"
  47 .Fn rtalloc1 "struct sockaddr *sa" "int report" "u_long flags"
  48 .Sh DESCRIPTION
  49 The kernel uses a radix tree structure to manage routes for the
  50 networking subsystem.  The
  51 .Fn rtalloc
  52 family of routines is used by protocols to query this structure for a
  53 route corresponding to a particular end-node address, and to cause
  54 certain protocol\- and interface-specific actions to take place.
  55 .\" XXX - -mdoc should contain a standard request for getting em and
  56 .\" en dashes.
  57 .Pp
  58 When a route with the flag
  59 .Dv RTF_CLONING
  60 or
  61 .Dv RTF_PRCLONING
  62 is retrieved, and the action of those flags is not masked, the
  63 .Nm
  64 facility automatically generates a new route using information in the
  65 old route as a template, and in the case of
  66 .Dv RTF_CLONING ,
  67 sends an
  68 .Dv RTM_RESOLVE
  69 message to the appropriate interface-address route-management routine
  70 .Pq Fn ifa->ifa_rtrequest .
  71 .Dv RTF_PRCLONING
  72 routes are assumed to be managed by the protocol family and no
  73 resolution requests are made, but all routes generated by the cloning
  74 process retain a reference to the route from which they were
  75 generated.
  76 If the
  77 .Dv RTF_XRESOLVE
  78 flag is set, then the
  79 .Dv RTM_RESOLVE
  80 message is sent instead on the
  81 .Xr route 4
  82 socket interface, requesting that an external program resolve the
  83 address in question and modify the route appropriately.
  84 .Pp
  85 The default interface is
  86 .Fn rtalloc .
  87 Its only argument is
  88 .Ar ro ,
  89 a pointer to a
  90 .Dq Li "struct route" ,
  91 which is defined as follows:
  92 .Bd -literal -offset indent
  93 struct route {
  94         struct sockaddr ro_dst;
  95         struct rtentry *ro_rt;
  96 };
  97 .Ed
  98 Thus, this function can only be used for address families which are
  99 smaller than the default
 100 .Dq Li "struct sockaddr" .
 101 Before calling
 102 .Fn rtalloc
 103 for the first time, callers should ensure that unused bits of the
 104 structure are set to zero.  On subsequent calls,
 105 .Fn rtalloc
 106 returns without performing a lookup if
 107 .Ar ro->ro_rt
 108 is non-null and the
 109 .Dv RTF_UP
 110 flag is set in the route's
 111 .Li rt_flags
 112 field.
 113 .Pp
 114 The
 115 .Fn rtalloc_ign
 116 interface can be used when the default actions of
 117 .Fn rtalloc
 118 in the presence of the
 119 .Dv RTF_CLONING
 120 and
 121 .Dv RTF_PRCLONING
 122 flags are undesired.  The
 123 .Ar ro
 124 argument is the same as
 125 .Fn rtalloc ,
 126 but there is additionally a
 127 .Ar flags
 128 argument, which lists the flags in the route which are to be
 129 .Em ignored
 130 (ordinarily, one or both of
 131 .Dv RTF_CLONING
 132 or
 133 .Dv RTF_PRCLONING ) .
 134 .Pp
 135 The
 136 .Fn rtalloc1
 137 function is the most general form of
 138 .Fn rtalloc
 139 (and both of the other forms are implemented as calls to rtalloc1).
 140 It does not use the
 141 .Dq Li "struct route" ,
 142 and is therefore suitable for address families which require more
 143 space than is in a traditional
 144 .Dq Li "struct sockaddr" .
 145 Instead, it takes a
 146 .Dq Li "struct sockaddr *"
 147 directly as the
 148 .Ar sa
 149 argument.  The second argument,
 150 .Ar report ,
 151 controls whether
 152 .Dv RTM_RESOLVE
 153 requests are sent to the lower layers when an
 154 .Dv RTF_CLONING
 155 or
 156 .Dv RTF_PRCLONING
 157 route is cloned.  Ordinarily a value of one should be passed, except
 158 in the processing of those lower layers which use the cloning
 159 facility.
 160 The third argument,
 161 .Ar flags ,
 162 is a set of flags to ignore, as in
 163 .Fn rtalloc_ign .
 164 .Sh RETURN VALUES
 165 The
 166 .Fn rtalloc
 167 and
 168 .Fn rtalloc_ign
 169 functions do not return a value.  The
 170 .Fn rtalloc1
 171 function returns a pointer to a routing-table entry if it succeeds,
 172 otherwise a null pointer.  Lack of a route should in most cases be
 173 translated to the
 174 .Xr errno 2
 175 value
 176 .Er EHOSTUNREACH .
 177 .Sh SEE ALSO
 178 .Xr route 4 ,
 179 .Xr rtentry 9
 180 .Sh HISTORY
 181 The
 182 .Nm
 183 facility first appeared in
 184 .Bx 4.2 ,
 185 although with much different internals.  The
 186 .Fn rtalloc_ign
 187 function and the
 188 .Ar flags
 189 argument to
 190 .Fn rtalloc1
 191 first appeared in
 192 .Fx 2.0 .
 193 .Sh AUTHORS
 194 This manual page was written by
 195 .An Garrett Wollman ,
 196 as were the changes to implement
 197 .Dv RTF_PRCLONING
 198 and the
 199 .Fn rtalloc_ign
 200 function and the
 201 .Ar flags
 202 argument to
 203 .Fn rtalloc1 .