1DNET(3)                  BSD Library Functions Manual                  DNET(3)
2

NAME

4     dnet — dumb networking library
5

SYNOPSIS

7     #include <dnet.h>
8
9   Network addressing
10     int
11     addr_cmp(const struct addr *a, const struct addr *b);
12
13     int
14     intf_addr_cmp(const struct addr *a, const struct addr *b);
15
16     int
17     addr_bcast(const struct addr *a, struct addr *b);
18
19     int
20     addr_net(const struct addr *a, struct addr *b);
21
22     char *
23     addr_ntop(const struct addr *src, char *dst, size_t size);
24
25     int
26     addr_pton(const char *src, struct addr *dst);
27
28     char *
29     addr_ntoa(const struct addr *a);
30
31     int
32     addr_aton(const char *src, struct addr *dst);
33
34     int
35     addr_ntos(const struct addr *a, struct sockaddr *sa);
36
37     int
38     addr_ston(const struct sockaddr *sa, struct addr *a);
39
40     int
41     addr_btos(uint16_t bits, struct sockaddr *sa);
42
43     int
44     addr_stob(const struct sockaddr *sa, uint16_t *bits);
45
46     int
47     addr_btom(uint16_t bits, void *mask, size_t size);
48
49     int
50     addr_mtob(const void *mask, size_t size, uint16_t *bits);
51
52   Address Resolution Protocol
53     typedef int
54
55     (*arp_handler)(const struct arp_entry *entry, void *arg);
56
57     arp_t *
58     arp_open(void);
59
60     int
61     arp_add(arp_t *a, const struct arp_entry *entry);
62
63     int
64     arp_delete(arp_t *a, const struct arp_entry *entry);
65
66     int
67     arp_get(arp_t *a, struct arp_entry *entry);
68
69     int
70     arp_loop(arp_t *a, arp_handler callback, void *arg);
71
72     arp_t *
73     arp_close(arp_t *a);
74
75   Binary buffers
76     blob_t *
77     blob_new(void);
78
79     int
80     blob_read(blob_t *b, void *buf, int len);
81
82     int
83     blob_write(blob_t *b, const void *buf, int len);
84
85     int
86     blob_seek(blob_t *b, int off, int whence);
87
88     int
89     blob_index(blob_t *b, const void *buf, int len);
90
91     int
92     blob_rindex(blob_t *b, const void *buf, int len);
93
94     int
95     blob_pack(blob_t *b, const void *fmt, ...);
96
97     int
98     blob_unpack(blob_t *b, const void *fmt, ...);
99
100     int
101     blob_print(blob_t *b, char *style, int len);
102
103     blob_t *
104     blob_free(blob_t *b);
105
106   Ethernet
107     eth_t *
108     eth_open(const char *device);
109
110     int
111     eth_get(eth_t *e, eth_addr_t *ea);
112
113     int
114     eth_set(eth_t *e, const eth_addr_t *ea);
115
116     ssize_t
117     eth_send(eth_t *e, const void *buf, size_t len);
118
119     eth_t *
120     eth_close(eth_t *e);
121
122   Firewalling
123     typedef int
124
125     (*fw_handler)(const struct fw_rule *rule, void *arg);
126
127     fw_t *
128     fw_open(void);
129
130     int
131     fw_add(fw_t *f, const struct fw_rule *rule);
132
133     int
134     fw_delete(fw_t *f, const struct fw_rule *rule);
135
136     int
137     fw_loop(fw_t *f, fw_handler callback, void *arg);
138
139     fw_t *
140     fw_close(fw_t *f);
141
142   Network interfaces
143     typedef int
144
145     (*intf_handler)(const struct intf_entry *entry, void *arg);
146
147     intf_t *
148     intf_open(void);
149
150     int
151     intf_get(intf_t *i, struct intf_entry *entry);
152
153     int
154     intf_get_src(intf_t *i, struct intf_entry *entry, struct addr *src);
155
156     int
157     intf_get_dst(intf_t *i, struct intf_entry *entry, struct addr *dst);
158
159     int
160     intf_set(intf_t *i, const struct intf_entry *entry);
161
162     int
163     intf_loop(intf_t *i, intf_handler callback, void *arg);
164
165     intf_t *
166     intf_close(intf_t *i);
167
168   Internet Protocol
169     ip_t *
170     ip_open(void);
171
172     ssize_t
173     ip_add_option(void *buf, size_t len, int proto, const void *optbuf,
174         size_t optlen);
175
176     void
177     ip_checksum(void *buf, size_t len);
178
179     ssize_t
180     ip_send(ip_t *i, const void *buf, size_t len);
181
182     ip_t *
183     ip_close(ip_t *i);
184
185   Internet Protocol Version 6
186     void
187     ip6_checksum(void *buf, size_t len);
188
189   Random number generation
190     rand_t *
191     rand_open(void);
192
193     int
194     rand_get(rand_t *r, void *buf, size_t len);
195
196     int
197     rand_set(rand_t *r, const void *seed, size_t len);
198
199     int
200     rand_add(rand_t *r, const void *buf, size_t len);
201
202     uint8_t
203     rand_uint8(rand_t *r);
204
205     uint16_t
206     rand_uint16(rand_t *r);
207
208     uint32_t
209     rand_uint32(rand_t *r);
210
211     int
212     rand_shuffle(rand_t *r, void *base, size_t nmemb, size_t size);
213
214     rand_t *
215     rand_close(rand_t *r);
216
217   Routing
218     typedef int
219
220     (*route_handler)(const struct route_entry *entry, void *arg);
221
222     route_t *
223     route_open(void);
224
225     int
226     route_add(route_t *r, const struct route_entry *entry);
227
228     int
229     route_delete(route_t *r, const struct route_entry *entry);
230
231     int
232     route_get(route_t *r, struct route_entry *entry);
233
234     int
235     route_loop(route_t *r, route_handler callback, void *arg);
236
237     route_t *
238     route_close(route_t *r);
239
240   Tunnel interface
241     tun_t *
242     tun_open(struct addr *src, struct addr *dst, int mtu);
243
244     int
245     tun_fileno(tun_t *t);
246
247     const char *
248     tun_name(tun_t *t);
249
250     ssize_t
251     tun_send(tun_t *t, const void *buf, size_t size);
252
253     ssize_t
254     tun_recv(tun_t *t, void *buf, size_t size);
255
256     tun_t *
257     tun_close(tun_t *t);
258

DESCRIPTION

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
267     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
271   Network addressing
272     Network addresses are described by the following structure:
273
274     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
282                     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
294     The following values are defined for addr_type:
295
296     #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
301     The field addr_bits denotes the length of the network mask in bits.
302
303     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
308     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
313     addr_bcast() computes the broadcast address for the network specified in
314     a and writes it into b.
315
316     addr_net() computes the network address for the network specified in a
317     and writes it into b.
318
319     addr_ntop() converts an address from network format to a string.
320
321     addr_pton() converts an address (or hostname) from a string to network
322     format.
323
324     addr_ntoa() converts an address from network format to a string, return‐
325     ing a pointer to the result in static memory.
326
327     addr_aton() is a synonym for addr_pton().
328
329     addr_ntos() converts an address from network format to the appropriate
330     struct sockaddr.
331
332     addr_ston() converts an address from a struct sockaddr to network format.
333
334     addr_btos() converts a network mask length to a network mask specified as
335     a struct sockaddr.
336
337     addr_stob() converts a network mask specified in a struct sockaddr to a
338     network mask length.
339
340     addr_btom() converts a network mask length to a network mask in network
341     byte order.
342
343     addr_mtob() converts a network mask in network byte order to a network
344     mask length.
345
346   Address Resolution Protocol
347     ARP cache entries are described by the following structure:
348
349     struct arp_entry {
350             struct addr     arp_pa;         /* protocol address */
351             struct addr     arp_ha;         /* hardware address */
352     };
353
354     arp_open() is used to obtain a handle to access the kernel arp(4) cache.
355
356     arp_add() adds a new ARP entry.
357
358     arp_delete() deletes the ARP entry for the protocol address specified by
359     arp_pa.
360
361     arp_get() retrieves the ARP entry for the protocol address specified by
362     arp_pa.
363
364     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
367     arp_close() closes the specified handle.
368
369   Binary buffers
370     Binary buffers are described by the following structure:
371
372     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
379     blob_new() is used to allocate a new dynamic binary buffer, returning
380     NULL on failure.
381
382     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
385     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
388     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
392     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
395     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
398     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
402     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
407     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
411     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
416     The conversion specifiers and their meanings are:
417
418     D       An unsigned 32-bit integer in network byte order.
419
420     H       An unsigned 16-bit integer in network byte order.
421
422     b       A binary buffer (length specifier required).
423
424     c       An unsigned character.
425
426     d       An unsigned 32-bit integer in host byte order.
427
428     h       An unsigned 16-bit integer in host byte order.
429
430     s       A C-style null-terminated string, whose maximum length must be
431             specified when unpacking.
432
433     Custom conversion routines and their specifiers may be registered via
434     blob_register_pack(), currently undocumented.
435
436     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
439     blob_free() deallocates the memory associated with blob b and returns
440     NULL.
441
442   Ethernet
443     eth_open() is used to obtain a handle to transmit raw Ethernet frames via
444     the specified network device.
445
446     eth_get() retrieves the hardware MAC address for the interface specified
447     by e.
448
449     eth_set() configures the hardware MAC address for the interface specified
450     by e.
451
452     eth_send() transmits len bytes of the Ethernet frame pointed to by buf.
453
454     eth_close() closes the specified handle.
455
456   Firewalling
457     Firewall rules are described by the following structure:
458
459     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
470     The following values are defined for fw_op:
471
472     #define FW_OP_ALLOW     1
473     #define FW_OP_BLOCK     2
474
475     The following values are defined for fw_dir:
476
477     #define FW_DIR_IN       1
478     #define FW_DIR_OUT      2
479
480     fw_open() is used to obtain a handle to access the local network firewall
481     configuration.
482
483     fw_add() adds the specified firewall rule.
484
485     fw_delete() deletes the specified firewall rule.
486
487     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
490     fw_close() closes the specified handle.
491
492   Network interfaces
493     Network interface information is described by the following structure:
494
495     #define INTF_NAME_LEN   16
496
497     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
510     The following bitmask values are defined for intf_type:
511
512     #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
517     The following bitmask values are defined for intf_flags:
518
519     #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
526     intf_open() is used to obtain a handle to access the network interface
527     configuration.
528
529     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
535     intf_get_src() retrieves the configuration for the interface whose pri‐
536     mary address matches the specified src.
537
538     intf_get_dst() retrieves the configuration for the best interface with
539     which to reach the specified dst.
540
541     intf_set() sets the interface configuration entry.
542
543     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
547     intf_close() closes the specified handle.
548
549   Internet Protocol
550     ip_open() is used to obtain a handle to transmit raw IP packets, routed
551     by the kernel.
552
553     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
558     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
561     ip_send() transmits len bytes of the IP packet pointed to by buf.
562
563     ip_close() closes the specified handle.
564
565   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
569   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
575     rand_set() re-initializes the PRNG to start from a known seed value, use‐
576     ful in generating repeatable sequences.
577
578     rand_get() writes len random bytes into buf.
579
580     rand_add() adds len bytes of entropy data from buf into the random mix.
581
582     rand_uint8(), rand_uint16(), and rand_uint32() return 8, 16, and 32-bit
583     unsigned random values, respectively.
584
585     rand_shuffle() randomly shuffles an array of nmemb elements of size
586     bytes, starting at base.
587
588     rand_close() closes the specified handle.
589
590   Routing
591     Routing table entries are described by the following structure:
592
593     struct route_entry {
594             struct addr     route_dst;      /* destination address */
595             struct addr     route_gw;       /* gateway address */
596     };
597
598     route_open() is used to obtain a handle to access the kernel route(4) ta‐
599     ble.
600
601     route_add() adds a new routing table entry.
602
603     route_delete() deletes the routing table entry for the destination prefix
604     specified by route_dst.
605
606     route_get() retrieves the routing table entry for the destination prefix
607     specified by route_dst.
608
609     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
612     route_close() closes the specified handle.
613
614   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
621     tun_fileno() returns a file descriptor associated with the tunnel handle,
622     suitable for select(2).
623
624     tun_name() returns a pointer to the tunnel interface name.
625
626     tun_send() submits a packet to the kernel networking subsystem for deliv‐
627     ery.
628
629     tun_recv() reads the next packet delivered to the tunnel interface.
630
631     tun_close() closes the specified handle.
632

RETURN VALUES

634     addr_ntop() returns a pointer to the dst argument, or NULL on failure.
635
636     addr_ntoa() returns a pointer to a static memory area containing the
637     printable address, or NULL on failure.
638
639     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
642     arp_close(), eth_close(), fw_close(), intf_close(), ip_close(),
643     rand_close(), and route_close() always return NULL.
644
645     eth_send() and ip_send() return the length of the datagram successfully
646     sent, or -1 on failure.
647
648     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
652     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
655     rand_uint8(), rand_uint16(), and rand_uint32() return 8, 16, and 32-bit
656     unsigned random values, respectively.
657
658     All other dnet routines return 0 on success, or -1 on failure.
659

SEE ALSO

661     pcap(3)
662

AUTHORS

664     Dug Song ⟨dugsong@monkey.org⟩
665
666BSD                             August 21, 2001                            BSD
Impressum