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 (or hostname) from a string to network
314 format.
315 addr_ntoa() converts an address from network format to a string, return‐
317 ing a pointer to the result in static memory.
318 addr_aton() is a synonym for addr_pton().
320 addr_ntos() converts an address from network format to the appropriate
322 struct sockaddr.
323 addr_ston() converts an address from a struct sockaddr to network format.
325 addr_btos() converts a network mask length to a network mask specified as
327 a struct sockaddr.
328 addr_stob() converts a network mask specified in a struct sockaddr to a
330 network mask length.
331 addr_btom() converts a network mask length to a network mask in network
333 byte order.
334 addr_mtob() converts a network mask in network byte order to a network
336 mask length.
337 Address Resolution Protocol
339 ARP cache entries are described by the following structure:
340 struct arp_entry {
342 struct addr arp_pa; /* protocol address */
343 struct addr arp_ha; /* hardware address */
344 };
345 arp_open() is used to obtain a handle to access the kernel arp(4) cache.
347 arp_add() adds a new ARP entry.
349 arp_delete() deletes the ARP entry for the protocol address specified by
351 arp_pa.
352 arp_get() retrieves the ARP entry for the protocol address specified by
354 arp_pa.
355 arp_loop() iterates over the kernel arp(4) cache, invoking the specified
357 callback with each entry and the context arg passed to arp_loop().
358 arp_close() closes the specified handle.
360 Binary buffers
362 Binary buffers are described by the following structure:
363 typedef struct blob {
365 u_char *base; /* start of data */
366 int off; /* offset into data */
367 int end; /* end of data */
368 int size; /* size of allocation */
369 } blob_t;
370 blob_new() is used to allocate a new dynamic binary buffer, returning
372 NULL on failure.
373 blob_read() reads len bytes from the current offset in blob b into buf,
375 returning the total number of bytes read, or -1 on failure.
376 blob_write() writes len bytes from buf to blob b, advancing the current
378 offset. It returns the number of bytes written, or -1 on failure.
379 blob_seek() repositions the offset within blob b to off, according to the
381 directive whence (see lseek(2) for details), returning the new absolute
382 offset, or -1 on failure.
383 blob_index() returns the offset of the first occurence in blob b of the
385 specified buf of length len, or -1 on failure.
386 blob_rindex() returns the offset of the last occurence in blob b of the
388 specified buf of length len, or -1 on failure.
389 blob_pack() converts and writes, and blob_unpack() reads and converts
391 data in blob b according to the given format fmt as described below, re‐
392 turning 0 on success, and -1 on failure.
393 The format string is composed of zero or more directives: ordinary char‐
395 acters (not % ), which are copied to / read from the blob, and conversion
396 specifications, each of which results in reading / writing zero or more
397 subsequent arguments.
398 Each conversion specification is introduced by the character %, and may
400 be prefixed by length specifier. The arguments must correspond properly
401 (after type promotion) with the length and conversion specifiers.
402 The length specifier is either a a decimal digit string specifying the
404 length of the following argument, or the literal character * indicating
405 that the length should be read from an integer argument for the argument
406 following it.
407 The conversion specifiers and their meanings are:
409 D An unsigned 32-bit integer in network byte order.
411 H An unsigned 16-bit integer in network byte order.
413 b A binary buffer (length specifier required).
415 c An unsigned character.
417 d An unsigned 32-bit integer in host byte order.
419 h An unsigned 16-bit integer in host byte order.
421 s A C-style null-terminated string, whose maximum length must be
423 specified when unpacking.
424 Custom conversion routines and their specifiers may be registered via
426 blob_register_pack(), currently undocumented.
427 blob_print() prints len bytes of the contents of blob b from the current
429 offset in the specified style; currently only “hexl” is available.
430 blob_free() deallocates the memory associated with blob b and returns
432 NULL.
433 Ethernet
435 eth_open() is used to obtain a handle to transmit raw Ethernet frames via
436 the specified network device.
437 eth_get() retrieves the hardware MAC address for the interface specified
439 by e.
440 eth_set() configures the hardware MAC address for the interface specified
442 by e.
443 eth_send() transmits len bytes of the Ethernet frame pointed to by buf.
445 eth_close() closes the specified handle.
447 Firewalling
449 Firewall rules are described by the following structure:
450 struct fw_rule {
452 char fw_device[INTF_NAME_LEN]; /* interface name */
453 uint8_t fw_op; /* operation */
454 uint8_t fw_dir; /* direction */
455 uint8_t fw_proto; /* IP protocol */
456 struct addr fw_src; /* src address / net */
457 struct addr fw_dst; /* dst address / net */
458 uint16_t fw_sport[2]; /* range / ICMP type */
459 uint16_t fw_dport[2]; /* range / ICMP code */
460 };
461 The following values are defined for fw_op:
463 #define FW_OP_ALLOW 1
465 #define FW_OP_BLOCK 2
466 The following values are defined for fw_dir:
468 #define FW_DIR_IN 1
470 #define FW_DIR_OUT 2
471 fw_open() is used to obtain a handle to access the local network firewall
473 configuration.
474 fw_add() adds the specified firewall rule.
476 fw_delete() deletes the specified firewall rule.
478 fw_loop() iterates over the active firewall ruleset, invoking the speci‐
480 fied callback with each rule and the context arg passed to fw_loop().
481 fw_close() closes the specified handle.
483 Network interfaces
485 Network interface information is described by the following structure:
486 #define INTF_NAME_LEN 16
488 struct intf_entry {
490 u_int intf_len; /* length of entry */
491 char intf_name[INTF_NAME_LEN]; /* interface name */
492 u_short intf_type; /* interface type (r/o) */
493 u_short intf_flags; /* interface flags */
494 u_int intf_mtu; /* interface MTU */
495 struct addr intf_addr; /* interface address */
496 struct addr intf_dst_addr; /* point-to-point dst */
497 struct addr intf_link_addr; /* link-layer address */
498 u_int intf_alias_num; /* number of aliases */
499 struct addr intf_alias_addrs __flexarr; /* array of aliases */
500 };
501 The following bitmask values are defined for intf_type:
503 #define INTF_TYPE_OTHER 1 /* other */
505 #define INTF_TYPE_ETH 6 /* Ethernet */
506 #define INTF_TYPE_LOOPBACK 24 /* software loopback */
507 #define INTF_TYPE_TUN 53 /* proprietary virtual/internal */
508 The following bitmask values are defined for intf_flags:
510 #define INTF_FLAG_UP 0x01 /* enable interface */
512 #define INTF_FLAG_LOOPBACK 0x02 /* is a loopback net (r/o) */
513 #define INTF_FLAG_POINTOPOINT 0x04 /* point-to-point link (r/o) */
514 #define INTF_FLAG_NOARP 0x08 /* disable ARP */
515 #define INTF_FLAG_BROADCAST 0x10 /* supports broadcast (r/o) */
516 #define INTF_FLAG_MULTICAST 0x20 /* supports multicast (r/o) */
517 intf_open() is used to obtain a handle to access the network interface
519 configuration.
520 intf_get() retrieves an interface configuration entry, keyed on
522 intf_name. For all intf_get() functions, intf_len should be set to the
523 size of the buffer pointed to by entry (usually sizeof(struct intf_en‐
524 try), but should be larger to accomodate any interface alias addresses.
525 intf_get_src() retrieves the configuration for the interface whose pri‐
527 mary address matches the specified src.
528 intf_get_dst() retrieves the configuration for the best interface with
530 which to reach the specified dst.
531 intf_set() sets the interface configuration entry.
533 intf_loop() iterates over all network interfaces, invoking the specified
535 callback with each interface configuration entry and the context arg
536 passed to intf_loop().
537 intf_close() closes the specified handle.
539 Internet Protocol
541 ip_open() is used to obtain a handle to transmit raw IP packets, routed
542 by the kernel.
543 ip_add_option() adds the header option for the protocol proto specified
545 by optbuf of length optlen and appends it to the appropriate header of
546 the IP packet contained in buf of size len, shifting any existing payload
547 and adding NOPs to pad the option to a word boundary if necessary.
548 ip_checksum() sets the IP checksum and any appropriate transport protocol
550 checksum for the IP packet pointed to by buf of length len.
551 ip_send() transmits len bytes of the IP packet pointed to by buf.
553 ip_close() closes the specified handle.
555 Internet Protocol Version 6
557 ip6_checksum() sets the appropriate transport protocol checksum for the
558 IPv6 packet pointed to by buf of length len.
559 Random number generation
561 rand_open() is used to obtain a handle for fast, cryptographically strong
562 pseudo-random number generation. The starting seed is derived from the
563 system random data source device (if one exists), or from the current
564 time and random stack contents.
565 rand_set() re-initializes the PRNG to start from a known seed value, use‐
567 ful in generating repeatable sequences.
568 rand_get() writes len random bytes into buf.
570 rand_add() adds len bytes of entropy data from buf into the random mix.
572 rand_uint8(), rand_uint16(), and rand_uint32() return 8, 16, and 32-bit
574 unsigned random values, respectively.
575 rand_shuffle() randomly shuffles an array of nmemb elements of size
577 bytes, starting at base.
578 rand_close() closes the specified handle.
580 Routing
582 Routing table entries are described by the following structure:
583 struct route_entry {
585 struct addr route_dst; /* destination address */
586 struct addr route_gw; /* gateway address */
587 };
588 route_open() is used to obtain a handle to access the kernel route(4) ta‐
590 ble.
591 route_add() adds a new routing table entry.
593 route_delete() deletes the routing table entry for the destination prefix
595 specified by route_dst.
596 route_get() retrieves the routing table entry for the destination prefix
598 specified by route_dst.
599 route_loop() iterates over the kernel route(4) table, invoking the speci‐
601 fied callback with each entry and the context arg passed to route_loop().
602 route_close() closes the specified handle.
604 Tunnel interface
606 tun_open() is used to obtain a handle to a network tunnel interface, to
607 which IP packets destined for dst are delivered (with source addresses
608 rewritten to src ), where they may be read by a userland process and pro‐
609 cessed as desired. IP packets written back to the handle are injected
610 into the kernel networking subsystem.
611 tun_fileno() returns a file descriptor associated with the tunnel handle,
613 suitable for select(2).
614 tun_name() returns a pointer to the tunnel interface name.
616 tun_send() submits a packet to the kernel networking subsystem for deliv‐
618 ery.
619 tun_recv() reads the next packet delivered to the tunnel interface.
621 tun_close() closes the specified handle.
623
625 addr_ntop() returns a pointer to the dst argument, or NULL on failure.
626 addr_ntoa() returns a pointer to a static memory area containing the
628 printable address, or NULL on failure.
629 arp_open(), eth_open(), fw_open(), intf_open(), ip_open(), rand_open(),
631 and route_open() return a valid handle on success, or NULL on failure.
632 arp_close(), eth_close(), fw_close(), intf_close(), ip_close(),
634 rand_close(), and route_close() always return NULL.
635 eth_send() and ip_send() return the length of the datagram successfully
637 sent, or -1 on failure.
638 arp_loop(), fw_loop(), intf_loop(), and route_loop() return the status of
640 their callback routines. Any non-zero return from a callback will cause
641 the loop to exit immediately.
642 ip_add_option() returns the length of the inserted option (which may have
644 been padded with NOPs for memory alignment) or -1 on failure.
645 rand_uint8(), rand_uint16(), and rand_uint32() return 8, 16, and 32-bit
647 unsigned random values, respectively.
648 All other dnet routines return 0 on success, or -1 on failure.
650
652 pcap(3)
653
655 Dug Song ⟨dugsong@monkey.org⟩
656BSD August 21, 2001 BSD