ROUTE(9)

NAME
route - kernel routing interface

SYNOPSIS
#include <net/route.h>
struct rtentry *
rt_lookup(struct sockaddr *dst, struct sockaddr *mask, u_int tableid);
void
rtalloc(struct route *ro);
void
rtalloc_noclone(struct route *ro);
struct rtentry *
rtalloc1(struct sockaddr *dst, int flags, u_int tableid);
void
rtfree(struct rtentry *rt);
RTFREE(struct rtentry *rt);
int
rtrequest1(int req, struct rt_addrinfo *info, u_int8_t prio, struct rtentry **ret_nrt, u_int tableid);
int
rt_setgate(struct rtentry *rt0, struct sockaddr *dst, struct sockaddr *gate, u_int tableid);
void
rtredirect(struct sockaddr *dst, struct sockaddr *gateway, struct sockaddr *netmask, int flags, struct sockaddr *src, struct rtentry **rtp, u_int rdomain);
int
rtdeletemsg(struct rtentry *rt, u_int tableid);
int
rtable_exists(u_int id);
int
rtable_add(u_int id);
u_int
rtable_l2(u_int id);
void
rtable_l2set(u_int id, u_int parent);
struct radix_node_head *
rt_gettable(sa_family_t af, u_int id);
struct rttimer_queue *
rt_timer_queue_create(u_int timeout);
int
rt_timer_add(struct rtentry *rt, void (*func)(struct rtentry *, struct rttimer *), struct rttimer_queue *queue, u_int rtableid);
void
rt_timer_queue_change(struct rttimer_queue *rtq, long timeout);
void
rt_timer_queue_destroy(struct rttimer_queue *rtq, int destroy);
unsigned long
rt_timer_count(struct rttimer_queue *rtq);
void
rt_timer_remove_all(struct rtentry *rt);
u_int16_t
rtlabel_name2id(char *name);
const char *
rtlabel_id2name(u_int16_t id);
struct sockaddr *
rtlabel_id2sa(u_int16_t labelid, struct sockaddr_rtlabel *sa_rl);
void
rtlabel_unref(u_int16_t id);

    struct rt_addrinfo {
    	int	rti_addrs;
    	struct	sockaddr *rti_info[RTAX_MAX];
    	int	rti_flags;
    	struct	ifaddr *rti_ifa;
    	struct	ifnet *rti_ifp;
    	struct	rt_msghdr *rti_rtm;
    	u_char	rti_mpls;
    };
    #define RTAX_DST	0	/* destination sockaddr present */
    #define RTAX_GATEWAY	1	/* gateway sockaddr present */
    #define RTAX_NETMASK	2	/* netmask sockaddr present */
    #define RTAX_GENMASK	3	/* cloning mask sockaddr present */
    #define RTAX_IFP	4	/* interface name sockaddr present */
    #define RTAX_IFA	5	/* interface addr sockaddr present */
    #define RTAX_AUTHOR	6	/* sockaddr for author of redirect */
    #define RTAX_BRD	7	/* for NEWADDR, broadcast or p-p dest */
    #define RTAX_SRC	8	/* source sockaddr present */
    #define RTAX_SRCMASK	9	/* source netmask present */
    #define RTAX_LABEL	10	/* route label present */
    #define RTAX_MAX	11	/* size of array to allocate */

DESCRIPTION

  Route Entries
Routing entries describe the routes to be taken by packets in a router.

rt_lookup(struct sockaddr *dst, struct sockaddr *mask, u_int tableid)
    Return pointer to routing entry corresponding to address dst with a mask of mask from table tableid.

rtrequest1(int req, struct rt_addrinfo *info, u_int8_t prio, struct rtentry **ret_nrt, u_int tableid)
    Perform the action specified in req on table tableid. req can be any of the following:

    RTM_ADD

    RTM_RESOLVE

    RTM_DELETE

    If ret_nrt is non-NULL, a pointer to the routing entry which satisfied the request is placed there. If prio is 0, a default priority based on the egress interface is used.

rt_setgate(struct rtentry *rt0, struct sockaddr *dst, struct sockaddr *gate, u_int tableid)
    Set the address of the gateway for routes described by rt0 to gateway. If memory must be allocated to hold the gateway address, the address for which rt0 describes routes will be copied from dst.

rtredirect(struct sockaddr *dst, struct sockaddr *gateway, struct sockaddr *netmask, int flags, struct sockaddr *src, struct rtentry **rtp, u_int rdomain)
    Redirect routes to dst through gateway, such as in response to an ICMP redirect message. src should be the address from which the redirect message was received. If rtp is not NULL, it will be populated by the routing entry corresponding to dst.

rtdeletemsg(struct rtentry *rt, u_int tableid)
    Delete routing table entry rt from table tableid and forward a notification message to all AF_ROUTE sockets.

rtfree(struct rtentry *rt)
    Release a reference to rt, freeing it if the reference count drops to 0.

RTFREE()
    A macro which calls rtfree().

  Routing Tables and Domains
Routing tables contain layer 2 and 3 forwarding information. Each address family in use will have its own routing table. Routing domains are a way of logically segmenting a router among multiple networks and may contain more than one routing table.

rtable_exists(u_int id)
    Return 1 if table with ID id exists, 0 otherwise.

rtable_add(u_int id)
    Add table with ID of id to routing domain 0.

rtable_l2(u_int id)
    Get the routing domain of table with ID of id.

rtable_l2set(u_int id, u_int parent)
    Place table with ID of id under the routing domain with ID of parent.

  Route Timer Queues
Route timer queues provide a method of queueing routing-related actions to be triggered once per second.

rt_timer_queue_create(u_int timeout)
    Create a timer queue with a timeout of timeout seconds.

rt_timer_add(struct rtentry *rt, void (*func)(struct rtentry *, struct rttimer *), struct rttimer_queue *queue, u_int rtableid)
    Schedule func to be called on rt using the timeout of queue. If rt already has a call to func scheduled on any timer queue, it will be replaced with the new invocation.

rt_timer_queue_change(struct rttimer_queue *rtq, long timeout)
    Set timeout for rtq to timeout seconds.

rt_timer_remove_all(struct rtentry *rt)
    Remove all timeouts associated with rt from all routing timer queues.

  Route Labels
Route labels are arbitrary data appended to routes and can be acted upon by pf.

rtlabel_name2id(char *name)
    Return numerical ID of the route label named name, creating the label if it does not already exist.

rtlabel_id2name(u_int16_t id)
    Return the string name of the route label with ID id.

rtlabel_id2sa(u_int16_t labelid, struct sockaddr_rtlabel *sa_rl)
    Populate sa_rl with the data from the route label specified by labelid.

rtlabel_unref(u_int16_t id)
    Remove a reference to the route label with ID id, freeing the label if the reference count drops to 0.

RETURN VALUES
rtrequest1() may fail with:

[EAFNOSUPPORT]
    The protocol used by info is not supported in table with ID of tableid.
[ESEARCH]
    No routing entry corresponding to info could be found.
[ESEARCH]
    Multipath route with no gateway provided in info.
[ESEARCH]
    The routing entry could not be found in the routing table.
[EINVAL]
    req specified RTM_RESOLVE with a ret_nrt argument which does not point to a cloneable routing entry.
[EEXIST]
    Multipath route conflicts with existing multipath route.
[EEXIST]
    The route could not be entered into the routing table.
[ENOMEM]
    Space for MPLS protocol data could not be allocated.
[ENOBUFS]
    Space for a new routing entry could not be allocated.
[ENETUNREACH]
    An interface address corresponding to the route described by info could not be found.

rt_setgate() returns non-0 if it cannot allocate memory.

rtdeletemsg() may fail with:

[EAFNOSUPPORT]
    The protocol used by rt is not supported by table with ID tableid.
[ESRCH]
    No routing entry for rt could be found.
[ESRCH]
    rt is a multipath route that conflicts with existing multipath route.

rtable_add() may fail with:

[EEXIST]
    A table with ID of id already exists.
[ENOMEM]
    Memory could not be allocated to extend the list of routing domains.

rt_timer_add() may fail with ENOBUFS if memory could not be allocated for the timeout.

rtlabel_name2id() returns 0 if it was unable to create a route label.

SEE ALSO
route(4), route(8)

BUGS
The current route entry reference counting code, while not incorrect, is also likely not correct either.