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

DESCRIPTION

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
264     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
268   Network addressing
269     Network addresses are described by the following structure:
270
271     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
279                     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
291     The following values are defined for addr_type:
292
293     #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
298     The field addr_bits denotes the length of the network mask in bits.
299
300     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
305     addr_bcast() computes the broadcast address for the network specified in
306     a and writes it into b.
307
308     addr_net() computes the network address for the network specified in a
309     and writes it into b.
310
311     addr_ntop() converts an address from network format to a string.
312
313     addr_pton() converts an address (or hostname) from a string to network
314     format.
315
316     addr_ntoa() converts an address from network format to a string, return‐
317     ing a pointer to the result in static memory.
318
319     addr_aton() is a synonym for addr_pton().
320
321     addr_ntos() converts an address from network format to the appropriate
322     struct sockaddr.
323
324     addr_ston() converts an address from a struct sockaddr to network format.
325
326     addr_btos() converts a network mask length to a network mask specified as
327     a struct sockaddr.
328
329     addr_stob() converts a network mask specified in a struct sockaddr to a
330     network mask length.
331
332     addr_btom() converts a network mask length to a network mask in network
333     byte order.
334
335     addr_mtob() converts a network mask in network byte order to a network
336     mask length.
337
338   Address Resolution Protocol
339     ARP cache entries are described by the following structure:
340
341     struct arp_entry {
342             struct addr     arp_pa;         /* protocol address */
343             struct addr     arp_ha;         /* hardware address */
344     };
345
346     arp_open() is used to obtain a handle to access the kernel arp(4) cache.
347
348     arp_add() adds a new ARP entry.
349
350     arp_delete() deletes the ARP entry for the protocol address specified by
351     arp_pa.
352
353     arp_get() retrieves the ARP entry for the protocol address specified by
354     arp_pa.
355
356     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
359     arp_close() closes the specified handle.
360
361   Binary buffers
362     Binary buffers are described by the following structure:
363
364     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
371     blob_new() is used to allocate a new dynamic binary buffer, returning
372     NULL on failure.
373
374     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
377     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
380     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
384     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
387     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
390     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
394     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
399     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
403     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
408     The conversion specifiers and their meanings are:
409
410     D       An unsigned 32-bit integer in network byte order.
411
412     H       An unsigned 16-bit integer in network byte order.
413
414     b       A binary buffer (length specifier required).
415
416     c       An unsigned character.
417
418     d       An unsigned 32-bit integer in host byte order.
419
420     h       An unsigned 16-bit integer in host byte order.
421
422     s       A C-style null-terminated string, whose maximum length must be
423             specified when unpacking.
424
425     Custom conversion routines and their specifiers may be registered via
426     blob_register_pack(), currently undocumented.
427
428     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
431     blob_free() deallocates the memory associated with blob b and returns
432     NULL.
433
434   Ethernet
435     eth_open() is used to obtain a handle to transmit raw Ethernet frames via
436     the specified network device.
437
438     eth_get() retrieves the hardware MAC address for the interface specified
439     by e.
440
441     eth_set() configures the hardware MAC address for the interface specified
442     by e.
443
444     eth_send() transmits len bytes of the Ethernet frame pointed to by buf.
445
446     eth_close() closes the specified handle.
447
448   Firewalling
449     Firewall rules are described by the following structure:
450
451     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
462     The following values are defined for fw_op:
463
464     #define FW_OP_ALLOW     1
465     #define FW_OP_BLOCK     2
466
467     The following values are defined for fw_dir:
468
469     #define FW_DIR_IN       1
470     #define FW_DIR_OUT      2
471
472     fw_open() is used to obtain a handle to access the local network firewall
473     configuration.
474
475     fw_add() adds the specified firewall rule.
476
477     fw_delete() deletes the specified firewall rule.
478
479     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
482     fw_close() closes the specified handle.
483
484   Network interfaces
485     Network interface information is described by the following structure:
486
487     #define INTF_NAME_LEN   16
488
489     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
502     The following bitmask values are defined for intf_type:
503
504     #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
509     The following bitmask values are defined for intf_flags:
510
511     #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
518     intf_open() is used to obtain a handle to access the network interface
519     configuration.
520
521     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
526     intf_get_src() retrieves the configuration for the interface whose pri‐
527     mary address matches the specified src.
528
529     intf_get_dst() retrieves the configuration for the best interface with
530     which to reach the specified dst.
531
532     intf_set() sets the interface configuration entry.
533
534     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
538     intf_close() closes the specified handle.
539
540   Internet Protocol
541     ip_open() is used to obtain a handle to transmit raw IP packets, routed
542     by the kernel.
543
544     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
549     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
552     ip_send() transmits len bytes of the IP packet pointed to by buf.
553
554     ip_close() closes the specified handle.
555
556   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
560   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
566     rand_set() re-initializes the PRNG to start from a known seed value, use‐
567     ful in generating repeatable sequences.
568
569     rand_get() writes len random bytes into buf.
570
571     rand_add() adds len bytes of entropy data from buf into the random mix.
572
573     rand_uint8(), rand_uint16(), and rand_uint32() return 8, 16, and 32-bit
574     unsigned random values, respectively.
575
576     rand_shuffle() randomly shuffles an array of nmemb elements of size
577     bytes, starting at base.
578
579     rand_close() closes the specified handle.
580
581   Routing
582     Routing table entries are described by the following structure:
583
584     struct route_entry {
585             struct addr     route_dst;      /* destination address */
586             struct addr     route_gw;       /* gateway address */
587     };
588
589     route_open() is used to obtain a handle to access the kernel route(4) ta‐
590     ble.
591
592     route_add() adds a new routing table entry.
593
594     route_delete() deletes the routing table entry for the destination prefix
595     specified by route_dst.
596
597     route_get() retrieves the routing table entry for the destination prefix
598     specified by route_dst.
599
600     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
603     route_close() closes the specified handle.
604
605   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
612     tun_fileno() returns a file descriptor associated with the tunnel handle,
613     suitable for select(2).
614
615     tun_name() returns a pointer to the tunnel interface name.
616
617     tun_send() submits a packet to the kernel networking subsystem for deliv‐
618     ery.
619
620     tun_recv() reads the next packet delivered to the tunnel interface.
621
622     tun_close() closes the specified handle.
623

RETURN VALUES

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

SEE ALSO

652     pcap(3)
653

AUTHORS

655     Dug Song ⟨dugsong@monkey.org⟩
656
657BSD                             August 21, 2001                            BSD
Impressum