RTREQUEST(9)

💅 RTREQUEST(9) — like, the routing table's personal assistant

okay so this one's from the Kernel Developer's Manual, and honestly? it's giving "backstage pass to the kernel" energy. rtrequest is the function that adds or removes entries from a routing table — the person doing the actual heavy lifting while everyone else gets the credit. main character energy fr.

---

✨ SYNOPSIS ✨

first you gotta pull in the header files, no cap:

#include <sys/types.h>
#include <net/route.h>

int
rtrequest(int req, struct rt_addrinfo *info, u_int8_t prio,
    struct rtentry **rtp, u_int rtableid);

struct rt_addrinfo {
        int     rti_addrs;
        struct  sockaddr *rti_info[RTAX_MAX];
        int     rti_flags;
        struct  ifaddr *rti_ifa;
        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_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 */

yeah that's a lot of defines, but they're all RTAX_* friends and they're all iconic in their own way 🎀

---

💖 DESCRIPTION 💖

rtrequest() is the function you call when you want to add or remove entries from a specific routing table. like, you point at one table and you're like "hi bestie, changes please."

it takes these args, and here's the whole rundown:

• req — one of these actions, pick your fighter:
  • RTM_ADD — add an entry to a given routing table. slay.
  • RTM_DELETE — remove an entry from a given routing table. and heads up: in the case of a cloning entry, all of its children get deleted too. the whole family. 😭 no survivors.
  • RTM_RESOLVE — add a cloned entry, based on the parent cloning entry that rtp points to, into a given routing table.
• info — describes the routing entry you're adding or removing. it's the little description card, basically.
• prio — specifies the priority of the routing entry described by info. and here's the cute part: if it's 0 and the requested action is RTM_ADD, then a default priority based on the priority of the associated interface gets chosen for you. king behavior honestly 👑
• rtp — must point to the cloning entry if the action is RTM_RESOLVE. in all cases where no error is returned and it's not NULL, a pointer to the deleted or added entry gets placed there. and bestie, listen — the caller has to take care of releasing that returned reference by calling rtfree(9). don't leave it hanging, that's rude 🫶
• rtableid — the ID of the routing table you want to modify. that's it. that's the whole thing.

---

🦋 CONTEXT 🦋

rtrequest() can be called during autoconf, from process context, or from interrupt context. three whole vibes, and it's flexible enough for all of them 💅

---

🔥 RETURN VALUES 🔥

rtrequest() may fail with any of these, so buckle up:

• [EAFNOSUPPORT] — the routing table with ID of rtableid doesn't exist, or it doesn't support the protocol specified in info.
• [ESRCH] — no routing entry corresponding to info could be found.
• [ESRCH] — multipath routing entry with no gateway provided in info. like, you forgot the gateway, bestie.
• [ESRCH] — the entry could not be found in the routing table of ID rtableid. specified. (yes there's a little dangling "specified" there at the end — the original page has it too, we don't know either 💀)
• [EINVAL] — the entry pointed to by rtp is not valid, or doesn't point to a cloning entry in the RTM_RESOLVE case.
• [EEXIST] — multipath routing entry conflicts with an existing one. drama.
• [EEXIST] — the entry 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. no room, no entry, that's the rule 😭
• [ENETUNREACH] — an interface address corresponding to the routing entry described by info could not be found.

okay so notice some of these errno values show up twice with different meanings — that's not a typo on my end, the page literally lists them that way. ESRCH three times and EEXIST twice. it's giving "same word, different context," iykyk.

---

🌈 SEE ALSO 🌈

• rtfree(9) — go free your references, bestie, that's the whole point 🧚

---

⭐ so yeah, that's the page! it's from Debian, dated July 12, 2019 — vintage but still serving looks. go add those routes, free those references, and remember: the kernel is counting on you 💜✨