DNET(3)

💖 DNET(3) 💖

okay bestie, sit down, hydrate, and get comfy, because we're doing dnet(3) from the Library Functions Manual — the dumb networking library. and yes "dumb" is literally the name, it's not shade, it's branding. 🫶

---

🌸 NAME 🌸

dnet — dumb networking library 💅

---

✨ SYNOPSIS ✨

#include <dnet.h>

🌐 Network addressing

int
addr_cmp(const struct addr *a, const struct addr *b);

int
addr_bcast(const struct addr *a, struct addr *b);

int
addr_net(const struct addr *a, struct addr *b);

char *
addr_ntop(const struct addr *src, char *dst, size_t size);

int
addr_pton(const char *src, struct addr *dst);

char *
addr_ntoa(const struct addr *a);

int
addr_aton(const char *src, struct addr *dst);

int
addr_ntos(const struct addr *a, struct sockaddr *sa);

int
addr_ston(const struct sockaddr *sa, struct addr *a);

int
addr_btos(uint16_t bits, struct sockaddr *sa);

int
addr_stob(const struct sockaddr *sa, uint16_t *bits);

int
addr_btom(uint16_t bits, void *mask, size_t size);

int
addr_mtob(const void *mask, size_t size, uint16_t *bits);

🎀 Address Resolution Protocol 🎀

typedef int (*arp_handler)(const struct arp_entry *entry, void *arg);

arp_t *
arp_open(void);

int
arp_add(arp_t *a, const struct arp_entry *entry);

int
arp_delete(arp_t *a, const struct arp_entry *entry);

int
arp_get(arp_t *a, struct arp_entry *entry);

int
arp_loop(arp_t *a, arp_handler callback, void *arg);

arp_t *
arp_close(arp_t *a);

🦋 Binary buffers 🦋

blob_t *
blob_new(void);

int
blob_read(blob_t *b, void *buf, int len);

int
blob_write(blob_t *b, const void *buf, int len);

int
blob_seek(blob_t *b, int off, int whence);

int
blob_index(blob_t *b, const void *buf, int len);

int
blob_rindex(blob_t *b, const void *buf, int len);

int
blob_pack(blob_t *b, const void *fmt, ...);

int
blob_unpack(blob_t *b, const void *fmt, ...);

int
blob_print(blob_t *b, char *style, int len);

blob_t *
blob_free(blob_t *b);

🌈 Ethernet 🌈

eth_t *
eth_open(const char *device);

int
eth_get(eth_t *e, eth_addr_t *ea);

int
eth_set(eth_t *e, const eth_addr_t *ea);

ssize_t
eth_send(eth_t *e, const void *buf, size_t len);

eth_t *
eth_close(eth_t *e);

🔥 Firewalling 🔥

typedef int (*fw_handler)(const struct fw_rule *rule, void *arg);

fw_t *
fw_open(void);

int
fw_add(fw_t *f, const struct fw_rule *rule);

int
fw_delete(fw_t *f, const struct fw_rule *rule);

int
fw_loop(fw_t *f, fw_handler callback, void *arg);

fw_t *
fw_close(fw_t *f);

👑 Network interfaces 👑

typedef int (*intf_handler)(const struct intf_entry *entry, void *arg);

intf_t *
intf_open(void);

int
intf_get(intf_t *i, struct intf_entry *entry);

int
intf_get_src(intf_t *i, struct intf_entry *entry, struct addr *src);

int
intf_get_dst(intf_t *i, struct intf_entry *entry, struct addr *dst);

int
intf_set(intf_t *i, const struct intf_entry *entry);

int
intf_loop(intf_t *i, intf_handler callback, void *arg);

intf_t *
intf_close(intf_t *i);

⭐ Internet Protocol ⭐

ip_t *
ip_open(void);

ssize_t
ip_add_option(void *buf, size_t len, int proto, const void *optbuf,
    size_t optlen);

void
ip_checksum(void *buf, size_t len);

ssize_t
ip_send(ip_t *i, const void *buf, size_t len);

ip_t *
ip_close(ip_t *i);

💜 Internet Protocol Version 6 💜

void
ip6_checksum(void *buf, size_t len);

🎲 Random number generation 🎲

rand_t *
rand_open(void);

int
rand_get(rand_t *r, void *buf, size_t len);

int
rand_set(rand_t *r, const void *seed, size_t len);

int
rand_add(rand_t *r, const void *buf, size_t len);

uint8_t
rand_uint8(rand_t *r);

uint16_t
rand_uint16(rand_t *r);

uint32_t
rand_uint32(rand_t *r);

int
rand_shuffle(rand_t *r, void *base, size_t nmemb, size_t size);

rand_t *
rand_close(rand_t *r);

🧚 Routing 🧚

typedef int (*route_handler)(const struct route_entry *entry, void *arg);

route_t *
route_open(void);

int
route_add(route_t *r, const struct route_entry *entry);

int
route_delete(route_t *r, const struct route_entry *entry);

int
route_get(route_t *r, struct route_entry *entry);

int
route_loop(route_t *r, route_handler callback, void *arg);

route_t *
route_close(route_t *r);

🍓 Tunnel interface 🍓

tun_t *
tun_open(struct addr *src, struct addr *dst, int mtu);

int
tun_fileno(tun_t *t);

const char *
tun_name(tun_t *t);

ssize_t
tun_send(tun_t *t, const void *buf, size_t size);

ssize_t
tun_recv(tun_t *t, void *buf, size_t size);

tun_t *
tun_close(tun_t *t);

---

💫 DESCRIPTION 💫

so like, dnet gives you a simplified, portable interface to a whole bunch of low-level networking routines. we're talking network address manipulation, kernel arp(4) cache and route(4) table lookup and manipulation, network firewalling, network interface lookup and manipulation, and raw IP packet and Ethernet frame transmission. it's meant to be the little sibling that complements what pcap(3) already does for you. 🫶

and there's more — dnet also hands you platform-independent definitions of a bunch of network protocol formats and values for portable low-level network programming, plus a simple binary buffer handling API. it's giving "everything you need, nothing you don't." periodt.

🌐 Network addressing

network addresses are described by this structure, and bestie, look at it carefully because everything else builds on it:

struct addr {
        uint16_t                addr_type;
        uint16_t                addr_bits;
        union {
                eth_addr_t      __eth;
                ip_addr_t       __ip;
                ip6_addr_t      __ip6;

                uint8_t         __data8[16];
                uint16_t        __data16[8];
                uint32_t        __data32[4];
        } __addr_u;
};
#define addr_eth        __addr_u.__eth
#define addr_ip         __addr_u.__ip
#define addr_ip6        __addr_u.__ip6
#define addr_data8      __addr_u.__data8
#define addr_data16     __addr_u.__data16
#define addr_data32     __addr_u.__data32

these are the values defined for addr_type:

#define ADDR_TYPE_NONE          0       /* No address set */
#define ADDR_TYPE_ETH           1       /* Ethernet */
#define ADDR_TYPE_IP            2       /* Internet Protocol v4 */
#define ADDR_TYPE_IP6           3       /* Internet Protocol v6 */

the field addr_bits denotes the length of the network mask in bits. (yes that's what it's for, don't overthink it 💅)

• addr_cmp() compares network addresses a and b, returning an integer less than, equal to, or greater than zero if a is found, respectively, to be less than, equal to, or greater than b. both addresses must be of the same address type — no mixing, that's the rule.
• addr_bcast() computes the broadcast address for the network specified in a and writes it into b.
• addr_net() computes the network address for the network specified in a and writes it into b.
• addr_ntop() converts an address from network format to a string.
• addr_pton() converts an address from a string to network format.
• addr_ntoa() converts an address from network format to a string, returning a pointer to the result in static memory.
• addr_aton() is a synonym for addr_pton(). same thing, different name, iconic.
• addr_ntos() converts an address from network format to the appropriate struct sockaddr.
• addr_ston() converts an address from a struct sockaddr to network format.
• addr_btos() converts a network mask length to a network mask specified as a struct sockaddr.
• addr_stob() converts a network mask specified in a struct sockaddr to a network mask length.
• addr_btom() converts a network mask length to a network mask in network byte order.
• addr_mtob() converts a network mask in network byte order to a network mask length.

🎀 Address Resolution Protocol 🎀

ARP cache entries are described by the following structure:

struct arp_entry {
        struct addr     arp_pa;         /* protocol address */
        struct addr     arp_ha;         /* hardware address */
};

• arp_open() is used to obtain a handle to access the kernel arp(4) cache.
• arp_add() adds a new ARP entry.
• arp_delete() deletes the ARP entry for the protocol address specified by arp_pa.
• arp_get() retrieves the ARP entry for the protocol address specified by arp_pa.
• arp_loop() iterates over the kernel arp(4) cache, invoking the specified callback with each entry and the context arg passed to arp_loop().
• arp_close() closes the specified handle.

🦋 Binary buffers 🦋

binary buffers are described by the following structure:

typedef struct blob {
        u_char          *base;          /* start of data */
        int              off;           /* offset into data */
        int              end;           /* end of data */
        int              size;          /* size of allocation */
} blob_t;

• blob_new() is used to allocate a new dynamic binary buffer, returning NULL on failure. 😭
• blob_read() reads len bytes from the current offset in blob b into buf, returning the total number of bytes read, or -1 on failure.
• blob_write() writes len bytes from buf to blob b, advancing the current offset. it returns the number of bytes written, or -1 on failure.
• blob_seek() repositions the offset within blob b to off, according to the directive whence (see lseek(2) for details), returning the new absolute offset, or -1 on failure.
• blob_index() returns the offset of the first occurrence in blob b of the specified buf of length len, or -1 on failure.
• blob_rindex() returns the offset of the last occurrence in blob b of the specified buf of length len, or -1 on failure.
• blob_pack() converts and writes, and blob_unpack() reads and converts data in blob b according to the given format fmt as described below, returning 0 on success, and -1 on failure.

the format string is composed of zero or more directives: ordinary characters (not % ), which are copied to / read from the blob, and conversion specifications, each of which results in reading / writing zero or more subsequent arguments.

each conversion specification is introduced by the character %, and may be prefixed by length specifier. the arguments must correspond properly (after type promotion) with the length and conversion specifiers.

the length specifier is either a decimal digit string specifying the length of the following argument, or the literal character * indicating that the length should be read from an integer argument for the argument following it.

the conversion specifiers and their meanings are:

• D — an unsigned 32-bit integer in network byte order.
• H — an unsigned 16-bit integer in network byte order.
• b — a binary buffer (length specifier required).
• c — an unsigned character.
• d — an unsigned 32-bit integer in host byte order.
• h — an unsigned 16-bit integer in host byte order. slay ✨
• s — a C-style null-terminated string, bestie. Its maximum length must be specified when unpacking. periodt 🎀

Custom conversion routines and their specifiers may be registered via blob_register_pack(), currently undocumented. iykyk 🌈

blob_print() prints len bytes of the contents of blob b from the current offset in the specified style; currently only “hexl” is available. obsessed 💅

blob_free() deallocates the memory associated with blob b and returns NULL. clean. 🧚

---

✨ Ethernet ✨

• eth_open() — used to obtain a handle to transmit raw Ethernet frames via the specified network device. main character energy 🔥
• eth_get() — retrieves the hardware MAC address for the interface specified by e. got it 🦋
• eth_set() — configures the hardware MAC address for the interface specified by e. set it off 💖
• eth_send() — transmits len bytes of the Ethernet frame pointed to by buf. send it 🚀
• eth_close() — closes the specified handle. bye bestie 👋

🔥 Firewalling 🔥

Firewall rules are described by this structure, and yes, you're gonna wanna screenshot it:

struct fw_rule {
        char            fw_device[INTF_NAME_LEN]; /* interface name */
        uint8_t         fw_op;                    /* operation */
        uint8_t         fw_dir;                   /* direction */
        uint8_t         fw_proto;                 /* IP protocol */
        struct addr     fw_src;                   /* src address / net */
        struct addr     fw_dst;                   /* dst address / net */
        uint16_t        fw_sport[2];              /* range / ICMP type */
        uint16_t        fw_dport[2];              /* range / ICMP code */
};

The following values are defined for fw_op:

#define FW_OP_ALLOW     1
#define FW_OP_BLOCK     2

The following values are defined for fw_dir:

#define FW_DIR_IN       1
#define FW_DIR_OUT      2

• fw_open() — used to obtain a handle to access the local network firewall configuration. gatekeeper vibes 🛡️
• fw_add() — adds the specified firewall rule. add it to the list 💅
• fw_delete() — deletes the specified firewall rule. not me deleting it 😭
• fw_loop() — iterates over the active firewall ruleset, invoking the specified callback with each rule and the context arg passed to fw_loop(). loop de loop 🔁
• fw_close() — closes the specified handle. closing time 🎀

🌸 Network interfaces 🌸

Network interface information is described by this structure:

#define INTF_NAME_LEN   16

struct intf_entry {
        u_int           intf_len;                   /* length of entry */
        char            intf_name[INTF_NAME_LEN];   /* interface name */
        u_short         intf_type;                  /* interface type (r/o) */
        u_short         intf_flags;                 /* interface flags */
        u_int           intf_mtu;                   /* interface MTU */
        struct addr     intf_addr;                  /* interface address */
        struct addr     intf_dst_addr;              /* point-to-point dst */
        struct addr     intf_link_addr;             /* link-layer address */
        u_int           intf_alias_num;             /* number of aliases */
        struct addr     intf_alias_addrs __flexarr; /* array of aliases */
};

The following bitmask values are defined for intf_type:

#define INTF_TYPE_OTHER         1       /* other */
#define INTF_TYPE_ETH           6       /* Ethernet */
#define INTF_TYPE_LOOPBACK      24      /* software loopback */
#define INTF_TYPE_TUN           53      /* proprietary virtual/internal */

The following bitmask values are defined for intf_flags:

#define INTF_FLAG_UP            0x01    /* enable interface */
#define INTF_FLAG_LOOPBACK      0x02    /* is a loopback net (r/o) */
#define INTF_FLAG_POINTOPOINT   0x04    /* point-to-point link (r/o) */
#define INTF_FLAG_NOARP         0x08    /* disable ARP */
#define INTF_FLAG_BROADCAST     0x10    /* supports broadcast (r/o) */
#define INTF_FLAG_MULTICAST     0x20    /* supports multicast (r/o) */

• intf_open() — used to obtain a handle to access the network interface configuration. let's get into it ✨
• intf_get() — retrieves an interface configuration entry, keyed on intf_name. For all intf_get() functions, intf_len should be set to the size of the buffer pointed to by entry (usually sizeof(struct intf_entry), but should be larger to accommodate any interface alias addresses). size matters, bestie 📏
• intf_get_src() — retrieves the configuration for the interface whose primary address matches the specified src. match made in heaven 💞
• intf_get_dst() — retrieves the configuration for the best interface with which to reach the specified dst. bestie route 🗺️
• intf_set() — sets the interface configuration entry. set it ✅
• intf_loop() — iterates over all network interfaces, invoking the specified callback with each interface configuration entry and the context arg passed to intf_loop(). loop it up 🔄
• intf_close() — closes the specified handle. that's a wrap 🎬

💜 Internet Protocol 💜

• ip_open() — used to obtain a handle to transmit raw IP packets, routed by the kernel. kernel's got it 🧠
• ip_add_option() — adds the header option for the protocol proto specified by optbuf of length optlen and appends it to the appropriate header of the IP packet contained in buf of size len, shifting any existing payload and adding NOPs to pad the option to a word boundary if necessary. padding? she's doing the most 💅
• ip_checksum() — sets the IP checksum and any appropriate transport protocol checksum for the IP packet pointed to by buf of length len. checksum slay 🧮
• ip_send() — transmits len bytes of the IP packet pointed to by buf. send it 📤
• ip_close() — closes the specified handle. close the door 🚪

🌈 Internet Protocol Version 6 🌈

• ip6_checksum() — sets the appropriate transport protocol checksum for the IPv6 packet pointed to by buf of length len. IPv6 era ✨

🎲 Random number generation 🎲

• rand_open() — used to obtain a handle for fast, cryptographically strong pseudo-random number generation. The starting seed is derived from the system random data source device (if one exists), or from the current time and random stack contents. random but make it secure 🔐
• rand_set() — re-initializes the PRNG to start from a known seed value, useful in generating repeatable sequences. repeatable? for science 🧪
• rand_get() — writes len random bytes into buf. gimme bytes 💾
• rand_add() — adds len bytes of entropy data from buf into the random mix. entropy mix 🥤
• rand_uint8(), rand_uint16(), and rand_uint32() — return 8, 16, and 32-bit unsigned random values, respectively. numbers go brrr 🔢
• rand_shuffle() — randomly shuffles an array of nmemb elements of size bytes, starting at base. shuffle queen 🃏
• rand_close() — closes the specified handle. done ✅

🛣️ Routing 🛣️

Routing table entries are described by this structure:

struct route_entry {
        struct addr     route_dst;      /* destination address */
        struct addr     route_gw;       /* gateway address */
};

• route_open() — used to obtain a handle to access the kernel route(4) table. route(4) bestie 🗺️
• route_add() — adds a new routing table entry. new path unlocked 🛤️
• route_delete() — deletes the routing table entry for the destination prefix specified by route_dst. delete it ❌
• route_get() — retrieves the routing table entry for the destination prefix specified by route_dst. got the route 📍
• route_loop() — iterates over the kernel route(4) table, invoking the specified callback with each entry and the context arg passed to route_loop(). loop the routes 🔁
• route_close() — closes the specified handle. bye 👋

🕳️ Tunnel interface 🕳️

• tun_open() — used to obtain a handle to a network tunnel interface, to which IP packets destined for dst are delivered (with source addresses rewritten to src ), where they may be read by a userland process and processed as desired. IP packets written back to the handle are injected into the kernel networking subsystem. tunnel vision, but make it networking 🌀
• tun_fileno() — returns a file descriptor associated with the tunnel handle, suitable for select(2). select(2) said yes 📁
• tun_name() — returns a pointer to the tunnel interface name. name drop 🏷️
• tun_send() — submits a packet to the kernel networking subsystem for delivery. send it to the kernel 📦
• tun_recv() — reads the next packet delivered to the tunnel interface. incoming 📥
• tun_close() — closes the specified handle. tunnel closed 🚧

---

✨ RETURN VALUES ✨

• addr_ntop() returns a pointer to the dst argument, or NULL on failure. pointer or nada 🎯
• addr_ntoa() returns a pointer to a static memory area containing the printable address, or NULL on failure. static memory realness 📜
• arp_open(), eth_open(), fw_open(), intf_open(), ip_open(), rand_open(), and route_open() return a valid handle on success, or NULL on failure. handle check ✅
• arp_close(), eth_close(), fw_close(), intf_close(), ip_close(), rand_close(), and route_close() always return NULL. always NULL, no cap 💀
• eth_send() and ip_send() return the length of the datagram successfully sent, or -1 on failure. length or L 📏
• arp_loop(), fw_loop(), intf_loop(), and route_loop() return the status of their callback routines. Any non-zero return from a callback will cause the loop to exit immediately. callback said stop, so we stop 🛑
• ip_add_option() returns the length of the inserted option (which may have been padded with NOPs for memory alignment) or -1 on failure. padded but make it work 💅
• rand_uint8(), rand_uint16(), and rand_uint32() return 8, 16, and 32-bit unsigned random values, respectively. random numbers, again 🎲
• All other dnet routines return 0 on success, or -1 on failure. zero or negative one, that's the vibe ✨

---

🌟 SEE ALSO 🌟

• pcap(3) go read that too, bestie 📖

---

👑 AUTHORS 👑

• Dug Song ⟨dugsong@monkey.org⟩ icon 💖
• Oliver Falk ⟨oliver@linux-kernel.at⟩ legend 💜

---

This page was served fresh from Debian on August 21, 2001 for DNET(3). Stay slaying, bestie. 💅✨🦋