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