--- name: "rtalloc1" section: "9freebsd" platform: "linux" package: "freebsd-manpages" version: "12.2-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/RTFREE/9freebsd" --- # rtalloc1(9freebsd) look up a route in the kernel routing table Part of [RTFREE(9freebsd)](/RTFREE/9freebsd.md). ## NAME **rtalloc1\_fib**, **rtalloc\_ign\_fib**, **rtalloc\_fib** – look up a route in the kernel routing table ## SYNOPSIS **#include \** **#include \** **#include \** *struct rtentry \**\ **rtalloc1\_fib**(*struct sockaddr \*dst*, *int report*, *u\_long flags*, *u\_int fibnum*); *void*\ **rtalloc\_fib**(*struct route \*ro*, *u\_int fibnum*); *void*\ **rtalloc\_ign\_fib**(*struct route \*ro*, *u\_long flags*, *u\_int fibnum*); **RTFREE\_LOCKED**(*struct rt\_entry \*rt*); **RTFREE**(*struct rt\_entry \*rt*); **RT\_LOCK**(*struct rt\_entry \*rt*); **RT\_UNLOCK**(*struct rt\_entry \*rt*); **RT\_ADDREF**(*struct rt\_entry \*rt*); **RT\_REMREF**(*struct rt\_entry \*rt*); **RO\_RTFREE**(*struct route \*ro*); *void*\ **rtfree**(*struct rt\_entry \*rt*); *struct rtentry \**\ **rtalloc1**(*struct sockaddr \*dst*, *int report*, *u\_long flags*); *void*\ **rtalloc**(*struct route \*ro*); *void*\ **rtalloc\_ign**(*struct route \*ro*, *u\_long flags*); **options** **RADIX\_MPATH** ## DESCRIPTION The kernel uses a radix tree structure to manage routes for the networking subsystem. If compiled with **options** **RADIX\_MPATH** kernel may maintain several independent forwarding information databases (FIBs). The **rtalloc**() family of routines is used by protocols to query these structures for a route corresponding to a particular end-node address, and to cause certain protocol- and interface-specific actions to take place. The **rtalloc1\_fib**() function is the most general form of **rtalloc**(), and all of the other forms are implemented as calls to it. It takes a *struct sockaddr \** directly as the *dst* argument. The second argument, *report*, controls whether the routing sockets are notified when a lookup fails. The third argument, *flags*, is a combination of the following values: - RTF\_RNH\_LOCKED indicates that the radix tree lock is already held The last argument *fibnum* specifies number of forwarding information database (FIB) on which the lookup should be performed. In case of success the **rtalloc1\_fib**() function returns a pointer to a locked *struct rtentry* with an additional reference. The **rtalloc\_fib**() is the most simple variant. Its main argument is *ro*, a pointer to a *struct route*, which is defined as follows: ``` struct route { struct rtentry *ro_rt; struct llentry *ro_lle; struct sockaddr ro_dst; }; ``` Thus, this function can only be used for address families which are smaller than the default *struct sockaddr*. Before calling **rtalloc\_fib**() for the first time, callers should ensure that unused bits of the structure are set to zero. The second argument *fibnum* is FIB number. In case of success of the **rtalloc\_fib**() the *ro\_rt* points to a valid and unlocked [rtentry(9)](/rtentry/9.md), which has an additional reference put on it, freeing which is responsibility of the caller. On subsequent calls, **rtalloc\_fib**() returns without performing a lookup if *ro-\>ro\_rt* is non-null and the RTF\_UP flag is set in the rtentry's *rt\_flags* field. The **rtalloc\_ign\_fib**() function is the same as the **rtalloc\_fib**(), but there is additional *flags* argument, which is same as in **rtalloc1\_fib**(). The **RTFREE\_LOCKED**() macro is used to unref and possibly free a locked routing entry with one our reference, for example previously allocated by **rtalloc1\_fib**(). The **RTFREE**() macro is used to unref and possibly free an unlocked route entries with one our reference, for example previously allocated by **rtalloc\_fib**() or **rtalloc\_ign\_fib**(). Both **RTFREE\_LOCKED**() and **RTFREE**() macros decrement the reference count on the routing table entry, and proceed with actual freeing if the reference count has reached zero. The **RT\_LOCK**() macro is used to lock a routing table entry. The **RT\_UNLOCK**() macro is used to unlock a routing table entry. The **RT\_ADDREF**() macro increments the reference count on a previously locked route entry. It should be used whenever a reference to an [rtentry(9)](/rtentry/9.md) is going to be stored outside the routing table. The **RT\_REMREF**() macro decrements the reference count on a previously locked route entry. Its usage is contrary to **RT\_ADDREF**(). The **RO\_RTFREE**() macro is used to free route entry that is referenced by struct route. At certain circumstances the latter may not hold a reference on rtentry, and **RO\_RTFREE**() treats such routes correctly. The **rtfree**() function does the actual free of the routing table entry, and shouldn't be called directly by facilities, that just perform routing table lookups. ## LEGACY INTERFACE Prior to introduction of multiple routing tables functions did not require the *u\_int fibnum* argument. Legacy **rtalloc1**(), **rtalloc**() and **rtalloc\_ign**() functions are kept for compatibility, and are equivalent to calling new interface with *fibnum* argument equal to *0*, which implies default forwarding table. ## RETURN VALUES The **rtalloc1\_fib**() function returns a pointer to a locked routing-table entry if it succeeds, otherwise a null pointer. The **rtalloc\_fib**() and **rtalloc\_ign\_fib**() functions do not return a value, but they fill in the *\*ro\_rt* member of the *\*ro* argument with a pointer to an unlocked routing-table entry if they succeed, otherwise a null pointer. In a case of success all functions put a reference on the routing-table entry, freeing of which is responsibility of the caller. Lack of a route should in most cases be translated to the [errno(2)](/errno/2.md) value EHOSTUNREACH. ## SEE ALSO [route(4)](/route/4.md), [rtentry(9)](/rtentry/9.md) ## HISTORY The **rtalloc** facility first appeared in 4.2BSD, although with much different internals. The **rtalloc\_ign**() function and the *flags* argument to **rtalloc1**() first appeared in FreeBSD 2.0. Routing table locking was introduced in FreeBSD 5.2. Multiple routing tables were introduced in FreeBSD 8.0. ## AUTHORS The original version of this manual page was written by Garrett Wollman. It was significantly updated by Gleb Smirnoff.