1DNET(3) BSD Library Functions Manual DNET(3)
2
4 dnet — dumb networking library
5
7 #include <dnet.h>
8 Network addressing
10 int
11 addr_cmp(const struct addr *a, const struct addr *b);
12 int
14 addr_bcast(const struct addr *a, struct addr *b);
15 int
17 addr_net(const struct addr *a, struct addr *b);
18 char *
20 addr_ntop(const struct addr *src, char *dst, size_t size);
21 int
23 addr_pton(const char *src, struct addr *dst);
24 char *
26 addr_ntoa(const struct addr *a);
27 int
29 addr_aton(const char *src, struct addr *dst);
30 int
32 addr_ntos(const struct addr *a, struct sockaddr *sa);
33 int
35 addr_ston(const struct sockaddr *sa, struct addr *a);
36 int
38 addr_btos(uint16_t bits, struct sockaddr *sa);
39 int
41 addr_stob(const struct sockaddr *sa, uint16_t *bits);
42 int
44 addr_btom(uint16_t bits, void *mask, size_t size);
45 int
47 addr_mtob(const void *mask, size_t size, uint16_t *bits);
48 Address Resolution Protocol
50 typedef int
51 (*arp_handler)(const struct arp_entry *entry, void *arg);
53 arp_t *
55 arp_open(void);
56 int
58 arp_add(arp_t *a, const struct arp_entry *entry);
59 int
61 arp_delete(arp_t *a, const struct arp_entry *entry);
62 int
64 arp_get(arp_t *a, struct arp_entry *entry);
65 int
67 arp_loop(arp_t *a, arp_handler callback, void *arg);
68 arp_t *
70 arp_close(arp_t *a);
71 Binary buffers
73 blob_t *
74 blob_new(void);
75 int
77 blob_read(blob_t *b, void *buf, int len);
78 int
80 blob_write(blob_t *b, const void *buf, int len);
81 int
83 blob_seek(blob_t *b, int off, int whence);
84 int
86 blob_index(blob_t *b, const void *buf, int len);
87 int
89 blob_rindex(blob_t *b, const void *buf, int len);
90 int
92 blob_pack(blob_t *b, const void *fmt, ...);
93 int
95 blob_unpack(blob_t *b, const void *fmt, ...);
96 int
98 blob_print(blob_t *b, char *style, int len);
99 blob_t *
101 blob_free(blob_t *b);
102 Ethernet
104 eth_t *
105 eth_open(const char *device);
106 int
108 eth_get(eth_t *e, eth_addr_t *ea);
109 int
111 eth_set(eth_t *e, const eth_addr_t *ea);
112 ssize_t
114 eth_send(eth_t *e, const void *buf, size_t len);
115 eth_t *
117 eth_close(eth_t *e);
118 Firewalling
120 typedef int
121 (*fw_handler)(const struct fw_rule *rule, void *arg);
123 fw_t *
125 fw_open(void);
126 int
128 fw_add(fw_t *f, const struct fw_rule *rule);
129 int
131 fw_delete(fw_t *f, const struct fw_rule *rule);
132 int
134 fw_loop(fw_t *f, fw_handler callback, void *arg);
135 fw_t *
137 fw_close(fw_t *f);
138 Network interfaces
140 typedef int
141 (*intf_handler)(const struct intf_entry *entry, void *arg);
143 intf_t *
145 intf_open(void);
146 int
148 intf_get(intf_t *i, struct intf_entry *entry);
149 int
151 intf_get_src(intf_t *i, struct intf_entry *entry, struct addr *src);
152 int
154 intf_get_dst(intf_t *i, struct intf_entry *entry, struct addr *dst);
155 int
157 intf_set(intf_t *i, const struct intf_entry *entry);
158 int
160 intf_loop(intf_t *i, intf_handler callback, void *arg);
161 intf_t *
163 intf_close(intf_t *i);
164 Internet Protocol
166 ip_t *
167 ip_open(void);
168 ssize_t
170 ip_add_option(void *buf, size_t len, int proto, const void *optbuf,
171 size_t optlen);
172 void
174 ip_checksum(void *buf, size_t len);
175 ssize_t
177 ip_send(ip_t *i, const void *buf, size_t len);
178 ip_t *
180 ip_close(ip_t *i);
181 Internet Protocol Version 6
183 void
184 ip6_checksum(void *buf, size_t len);
185 Random number generation
187 rand_t *
188 rand_open(void);
189 int
191 rand_get(rand_t *r, void *buf, size_t len);
192 int
194 rand_set(rand_t *r, const void *seed, size_t len);
195 int
197 rand_add(rand_t *r, const void *buf, size_t len);
198 uint8_t
200 rand_uint8(rand_t *r);
201 uint16_t
203 rand_uint16(rand_t *r);
204 uint32_t
206 rand_uint32(rand_t *r);
207 int
209 rand_shuffle(rand_t *r, void *base, size_t nmemb, size_t size);
210 rand_t *
212 rand_close(rand_t *r);
213 Routing
215 typedef int
216 (*route_handler)(const struct route_entry *entry, void *arg);
218 route_t *
220 route_open(void);
221 int
223 route_add(route_t *r, const struct route_entry *entry);
224 int
226 route_delete(route_t *r, const struct route_entry *entry);
227 int
229 route_get(route_t *r, struct route_entry *entry);
230 int
232 route_loop(route_t *r, route_handler callback, void *arg);
233 route_t *
235 route_close(route_t *r);
236 Tunnel interface
238 tun_t *
239 tun_open(struct addr *src, struct addr *dst, int mtu);
240 int
242 tun_fileno(tun_t *t);
243 const char *
245 tun_name(tun_t *t);
246 ssize_t
248 tun_send(tun_t *t, const void *buf, size_t size);
249 ssize_t
251 tun_recv(tun_t *t, void *buf, size_t size);
252 tun_t *
254 tun_close(tun_t *t);
255
257 dnet provides a simplified, portable interface to several low-level net‐
258 working routines, including network address manipulation, kernel arp(4)
259 cache and route(4) table lookup and manipulation, network firewalling,
260 network interface lookup and manipulation, and raw IP packet and Ethernet
261 frame transmission. It is intended to complement the functionality pro‐
262 vided by pcap(3).
263 In addition, dnet also provides platform-independent definitions of vari‐
265 ous network protocol formats and values for portable low-level network
266 programming, as well as a simple binary buffer handling API.
267 Network addressing
269 Network addresses are described by the following structure:
270 struct addr {
272 uint16_t addr_type;
273 uint16_t addr_bits;
274 union {
275 eth_addr_t __eth;
276 ip_addr_t __ip;
277 ip6_addr_t __ip6;
278 uint8_t __data8[16];
280 uint16_t __data16[8];
281 uint32_t __data32[4];
282 } __addr_u;
283 };
284 #define addr_eth __addr_u.__eth
285 #define addr_ip __addr_u.__ip
286 #define addr_ip6 __addr_u.__ip6
287 #define addr_data8 __addr_u.__data8
288 #define addr_data16 __addr_u.__data16
289 #define addr_data32 __addr_u.__data32
290 The following values are defined for addr_type:
292 #define ADDR_TYPE_NONE 0 /* No address set */
294 #define ADDR_TYPE_ETH 1 /* Ethernet */
295 #define ADDR_TYPE_IP 2 /* Internet Protocol v4 */
296 #define ADDR_TYPE_IP6 3 /* Internet Protocol v6 */
297 The field addr_bits denotes the length of the network mask in bits.
299 addr_cmp() compares network addresses a and b, returning an integer less
301 than, equal to, or greater than zero if a is found, respectively, to be
302 less than, equal to, or greater than b. Both addresses must be of the
303 same address type.
304 addr_bcast() computes the broadcast address for the network specified in
306 a and writes it into b.
307 addr_net() computes the network address for the network specified in a
309 and writes it into b.
310 addr_ntop() converts an address from network format to a string.
312 addr_pton() converts an address from a string to network format.
314 addr_ntoa() converts an address from network format to a string, return‐
316 ing a pointer to the result in static memory.
317 addr_aton() is a synonym for addr_pton().
319 addr_ntos() converts an address from network format to the appropriate
321 struct sockaddr.
322 addr_ston() converts an address from a struct sockaddr to network format.
324 addr_btos() converts a network mask length to a network mask specified as
326 a struct sockaddr.
327 addr_stob() converts a network mask specified in a struct sockaddr to a
329 network mask length.
330 addr_btom() converts a network mask length to a network mask in network
332 byte order.
333 addr_mtob() converts a network mask in network byte order to a network
335 mask length.
336 Address Resolution Protocol
338 ARP cache entries are described by the following structure:
339 struct arp_entry {
341 struct addr arp_pa; /* protocol address */
342 struct addr arp_ha; /* hardware address */
343 };
344 arp_open() is used to obtain a handle to access the kernel arp(4) cache.
346 arp_add() adds a new ARP entry.
348 arp_delete() deletes the ARP entry for the protocol address specified by
350 arp_pa.
351 arp_get() retrieves the ARP entry for the protocol address specified by
353 arp_pa.
354 arp_loop() iterates over the kernel arp(4) cache, invoking the specified
356 callback with each entry and the context arg passed to arp_loop().
357 arp_close() closes the specified handle.
359 Binary buffers
361 Binary buffers are described by the following structure:
362 typedef struct blob {
364 u_char *base; /* start of data */
365 int off; /* offset into data */
366 int end; /* end of data */
367 int size; /* size of allocation */
368 } blob_t;
369 blob_new() is used to allocate a new dynamic binary buffer, returning
371 NULL on failure.
372 blob_read() reads len bytes from the current offset in blob b into buf,
374 returning the total number of bytes read, or -1 on failure.
375 blob_write() writes len bytes from buf to blob b, advancing the current
377 offset. It returns the number of bytes written, or -1 on failure.
378 blob_seek() repositions the offset within blob b to off, according to the
380 directive whence (see lseek(2) for details), returning the new absolute
381 offset, or -1 on failure.
382 blob_index() returns the offset of the first occurrence in blob b of the
384 specified buf of length len, or -1 on failure.
385 blob_rindex() returns the offset of the last occurrence in blob b of the
387 specified buf of length len, or -1 on failure.
388 blob_pack() converts and writes, and blob_unpack() reads and converts
390 data in blob b according to the given format fmt as described below, re‐
391 turning 0 on success, and -1 on failure.
392 The format string is composed of zero or more directives: ordinary char‐
394 acters (not % ), which are copied to / read from the blob, and conversion
395 specifications, each of which results in reading / writing zero or more
396 subsequent arguments.
397 Each conversion specification is introduced by the character %, and may
399 be prefixed by length specifier. The arguments must correspond properly
400 (after type promotion) with the length and conversion specifiers.
401 The length specifier is either a a decimal digit string specifying the
403 length of the following argument, or the literal character * indicating
404 that the length should be read from an integer argument for the argument
405 following it.
406 The conversion specifiers and their meanings are:
408 D An unsigned 32-bit integer in network byte order.
410 H An unsigned 16-bit integer in network byte order.
412 b A binary buffer (length specifier required).
414 c An unsigned character.
416 d An unsigned 32-bit integer in host byte order.
418 h An unsigned 16-bit integer in host byte order.
420 s A C-style null-terminated string, whose maximum length must be
422 specified when unpacking.
423 Custom conversion routines and their specifiers may be registered via
425 blob_register_pack(), currently undocumented.
426 blob_print() prints len bytes of the contents of blob b from the current
428 offset in the specified style; currently only “hexl” is available.
429 blob_free() deallocates the memory associated with blob b and returns
431 NULL.
432 Ethernet
434 eth_open() is used to obtain a handle to transmit raw Ethernet frames via
435 the specified network device.
436 eth_get() retrieves the hardware MAC address for the interface specified
438 by e.
439 eth_set() configures the hardware MAC address for the interface specified
441 by e.
442 eth_send() transmits len bytes of the Ethernet frame pointed to by buf.
444 eth_close() closes the specified handle.
446 Firewalling
448 Firewall rules are described by the following structure:
449 struct fw_rule {
451 char fw_device[INTF_NAME_LEN]; /* interface name */
452 uint8_t fw_op; /* operation */
453 uint8_t fw_dir; /* direction */
454 uint8_t fw_proto; /* IP protocol */
455 struct addr fw_src; /* src address / net */
456 struct addr fw_dst; /* dst address / net */
457 uint16_t fw_sport[2]; /* range / ICMP type */
458 uint16_t fw_dport[2]; /* range / ICMP code */
459 };
460 The following values are defined for fw_op:
462 #define FW_OP_ALLOW 1
464 #define FW_OP_BLOCK 2
465 The following values are defined for fw_dir:
467 #define FW_DIR_IN 1
469 #define FW_DIR_OUT 2
470 fw_open() is used to obtain a handle to access the local network firewall
472 configuration.
473 fw_add() adds the specified firewall rule.
475 fw_delete() deletes the specified firewall rule.
477 fw_loop() iterates over the active firewall ruleset, invoking the speci‐
479 fied callback with each rule and the context arg passed to fw_loop().
480 fw_close() closes the specified handle.
482 Network interfaces
484 Network interface information is described by the following structure:
485 #define INTF_NAME_LEN 16
487 struct intf_entry {
489 u_int intf_len; /* length of entry */
490 char intf_name[INTF_NAME_LEN]; /* interface name */
491 u_short intf_type; /* interface type (r/o) */
492 u_short intf_flags; /* interface flags */
493 u_int intf_mtu; /* interface MTU */
494 struct addr intf_addr; /* interface address */
495 struct addr intf_dst_addr; /* point-to-point dst */
496 struct addr intf_link_addr; /* link-layer address */
497 u_int intf_alias_num; /* number of aliases */
498 struct addr intf_alias_addrs __flexarr; /* array of aliases */
499 };
500 The following bitmask values are defined for intf_type:
502 #define INTF_TYPE_OTHER 1 /* other */
504 #define INTF_TYPE_ETH 6 /* Ethernet */
505 #define INTF_TYPE_LOOPBACK 24 /* software loopback */
506 #define INTF_TYPE_TUN 53 /* proprietary virtual/internal */
507 The following bitmask values are defined for intf_flags:
509 #define INTF_FLAG_UP 0x01 /* enable interface */
511 #define INTF_FLAG_LOOPBACK 0x02 /* is a loopback net (r/o) */
512 #define INTF_FLAG_POINTOPOINT 0x04 /* point-to-point link (r/o) */
513 #define INTF_FLAG_NOARP 0x08 /* disable ARP */
514 #define INTF_FLAG_BROADCAST 0x10 /* supports broadcast (r/o) */
515 #define INTF_FLAG_MULTICAST 0x20 /* supports multicast (r/o) */
516 intf_open() is used to obtain a handle to access the network interface
518 configuration.
519 intf_get() retrieves an interface configuration entry, keyed on
521 intf_name. For all intf_get() functions, intf_len should be set to the
522 size of the buffer pointed to by entry (usually sizeof(struct intf_en‐
523 try), but should be larger to accommodate any interface alias addresses.
524 intf_get_src() retrieves the configuration for the interface whose pri‐
526 mary address matches the specified src.
527 intf_get_dst() retrieves the configuration for the best interface with
529 which to reach the specified dst.
530 intf_set() sets the interface configuration entry.
532 intf_loop() iterates over all network interfaces, invoking the specified
534 callback with each interface configuration entry and the context arg
535 passed to intf_loop().
536 intf_close() closes the specified handle.
538 Internet Protocol
540 ip_open() is used to obtain a handle to transmit raw IP packets, routed
541 by the kernel.
542 ip_add_option() adds the header option for the protocol proto specified
544 by optbuf of length optlen and appends it to the appropriate header of
545 the IP packet contained in buf of size len, shifting any existing payload
546 and adding NOPs to pad the option to a word boundary if necessary.
547 ip_checksum() sets the IP checksum and any appropriate transport protocol
549 checksum for the IP packet pointed to by buf of length len.
550 ip_send() transmits len bytes of the IP packet pointed to by buf.
552 ip_close() closes the specified handle.
554 Internet Protocol Version 6
556 ip6_checksum() sets the appropriate transport protocol checksum for the
557 IPv6 packet pointed to by buf of length len.
558 Random number generation
560 rand_open() is used to obtain a handle for fast, cryptographically strong
561 pseudo-random number generation. The starting seed is derived from the
562 system random data source device (if one exists), or from the current
563 time and random stack contents.
564 rand_set() re-initializes the PRNG to start from a known seed value, use‐
566 ful in generating repeatable sequences.
567 rand_get() writes len random bytes into buf.
569 rand_add() adds len bytes of entropy data from buf into the random mix.
571 rand_uint8(), rand_uint16(), and rand_uint32() return 8, 16, and 32-bit
573 unsigned random values, respectively.
574 rand_shuffle() randomly shuffles an array of nmemb elements of size
576 bytes, starting at base.
577 rand_close() closes the specified handle.
579 Routing
581 Routing table entries are described by the following structure:
582 struct route_entry {
584 struct addr route_dst; /* destination address */
585 struct addr route_gw; /* gateway address */
586 };
587 route_open() is used to obtain a handle to access the kernel route(4) ta‐
589 ble.
590 route_add() adds a new routing table entry.
592 route_delete() deletes the routing table entry for the destination prefix
594 specified by route_dst.
595 route_get() retrieves the routing table entry for the destination prefix
597 specified by route_dst.
598 route_loop() iterates over the kernel route(4) table, invoking the speci‐
600 fied callback with each entry and the context arg passed to route_loop().
601 route_close() closes the specified handle.
603 Tunnel interface
605 tun_open() is used to obtain a handle to a network tunnel interface, to
606 which IP packets destined for dst are delivered (with source addresses
607 rewritten to src ), where they may be read by a userland process and pro‐
608 cessed as desired. IP packets written back to the handle are injected
609 into the kernel networking subsystem.
610 tun_fileno() returns a file descriptor associated with the tunnel handle,
612 suitable for select(2).
613 tun_name() returns a pointer to the tunnel interface name.
615 tun_send() submits a packet to the kernel networking subsystem for deliv‐
617 ery.
618 tun_recv() reads the next packet delivered to the tunnel interface.
620 tun_close() closes the specified handle.
622
624 addr_ntop() returns a pointer to the dst argument, or NULL on failure.
625 addr_ntoa() returns a pointer to a static memory area containing the
627 printable address, or NULL on failure.
628 arp_open(), eth_open(), fw_open(), intf_open(), ip_open(), rand_open(),
630 and route_open() return a valid handle on success, or NULL on failure.
631 arp_close(), eth_close(), fw_close(), intf_close(), ip_close(),
633 rand_close(), and route_close() always return NULL.
634 eth_send() and ip_send() return the length of the datagram successfully
636 sent, or -1 on failure.
637 arp_loop(), fw_loop(), intf_loop(), and route_loop() return the status of
639 their callback routines. Any non-zero return from a callback will cause
640 the loop to exit immediately.
641 ip_add_option() returns the length of the inserted option (which may have
643 been padded with NOPs for memory alignment) or -1 on failure.
644 rand_uint8(), rand_uint16(), and rand_uint32() return 8, 16, and 32-bit
646 unsigned random values, respectively.
647 All other dnet routines return 0 on success, or -1 on failure.
649
651 pcap(3)
652
654 Dug Song ⟨dugsong@monkey.org⟩
655 Oliver Falk ⟨oliver@linux-kernel.at⟩
656BSD August 21, 2001 BSD