1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>s6-dns: the s6dns_domain library interface</title>
<meta name="Description" content="s6-dns: the s6dns_domain library interface" />
<meta name="Keywords" content="s6-dns dns s6dns_domain library libs6dns" />
<!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">libs6dns</a><br />
<a href="../">s6-dns</a><br />
<a href="http://skarnet.org/software/">Software</a><br />
<a href="http://skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>s6dns_domain</tt> library interface </h1>
<p>
The following functions and structures are declared in the <tt>s6-dns/s6dns-domain.h</tt> header,
and implemented in the <tt>libs6dns.a</tt> or <tt>libs6dns.so</tt> library.
</p>
<h2> General information </h2>
<p>
<tt>s6dns_domain</tt> provides primitives to perform basic operations
on domain names.
</p>
<h2> Data structures </h2>
<p>
A <tt>s6dns_domain_t</tt> is a structure that s6dns uses internally to
represent a domain name. It can be in <em>string form</em> (or
<em>decoded form</em>), which is close to the printable form seen
by users, or in <em>packet form</em> (or <em>encoded form</em>), which
is the format used in the DNS protocol.
</p>
<p>
A <tt>s6dns_domain_t</tt> is a flat structure and can be declared
on the stack.
</p>
<h2> Functions </h2>
<p>
<code> int s6dns_domain_fromstring (s6dns_domain_t *d, char const *s, unsigned int len) </code> <br />
Makes a (string form) domain from string <em>s</em> of length <em>len</em>,
and stores it into *<em>d</em>. Returns 1 if it succeeds, otherwise it
returns 0 and sets errno appropriately - most likely ENAMETOOLONG, i.e.
the name in <em>s</em> is not a well-formed domain name.
</p>
<p>
<code> unsigned int s6dns_domain_tostring (char *s, unsigned int max, s6dns_domain_t const *d) </code> <br />
Writes into string <em>s</em> the domain contained in *<em>d</em> (in string
form). Returns the number of bytes written, or 0 in case of failure. If
the output would be more than <em>max</em> bytes, 0 ENAMETOOLONG is returned.
</p>
<p>
<code> int s6dns_domain_noqualify (s6dns_domain_t *d) </code> <br />
Makes sure that *<em>d</em> is fully qualified. This is done without using
qualification: a trailing dot is simply appended if the domain
doesn't already have one. Returns 1 if it succeeds, or 0 if it fails.
</p>
<p>
<code> unsigned int s6dns_domain_qualify (s6dns_domain_t *list, s6dns_domain_t const *d, char const *rules, unsigned int rulesnum) </code> <br />
Performs qualification on domain *<em>d</em> according to the first
<em>rulesnum</em> rules stored in string <em>rules</em>. Stores the output
(at most <em>rulesnum</em> domains) into the array pointed to by <em>list</em>.
Returns 0 on failure, or the number of written domains if it succeeds. This
number can be lesser than <em>rulesnum</em>, for instance if *<em>d</em> is
already fully qualified. <br />
Valid <em>rules</em> and <em>rulesnum</em> can be obtained via functions
declared in <a href="s6dns-rci.html">s6dns-rci.h</a>.
</p>
<p>
<code> int s6dns_domain_encode (s6dns_domain_t *d) </code> <br />
Encodes domain *<em>d</em> from string form to packet form. Returns 1
if it succeeds or 0 if it fails - for instance, *<em>d</em> is not a
valid string form (EINVAL).
</p>
<p>
<code> unsigned int s6dns_domain_encodelist (s6dns_domain_t *list, unsigned int n) </code> <br />
Encodes <em>n</em> domains pointed to by <em>list</em> from string form to packet form,
stopping at the first failure.
Returns the number of successfully encoded domains, normally <em>n</em>.
</p>
<p>
<code> int s6dns_domain_decode (s6dns_domain_t *d) </code> <br />
Decodes domain *<em>d</em> from packet form to string form. Returns 1
if it succeeds or 0 if it fails - for instance, *<em>d</em> is not a
valid packet form (EPROTO).
</p>
<p>
<code> int s6dns_domain_fromstring_noqualify_encode (s6dns_domain_t *d, char const *s, unsigned int len) </code> <br />
Higher-level function wrapping some of the above. Makes an encoded, fully qualified
(without resorting to qualification) domain from string <em>s</em> of
length <em>len</em>. Returns 1 if it succeeds and 0 if it fails.
</p>
<p>
<code> unsigned int s6dns_domain_fromstring_qualify_encode (s6dns_domain_t *list, char const *s, unsigned int len, char const *rules, unsigned int rulesnum) </code> <br />
Another wrapping function. It makes a list of encoded, fully qualified domains,
from string <em>s</em> of length <em>len</em> using <em>rulesnum</em> qualification
rules in <em>rules</em>. It writes at most <em>rulesnum</em> domains into the array
pointed to by <em>list</em> and returns the number of written domains, or 0 on an
error.
</p>
<p>
<code> void s6dns_domain_arpafromip4 (s6dns_domain_t *d, char const *ip) </code> <br />
Writes into <em>d</em> the <tt>in-addr.arpa.</tt> domain corresponding to IPv4 address
<em>ip</em> (4 bytes, in network byte order), in string form.
</p>
<p>
<code> void s6dns_domain_arpafromip6 (s6dns_domain_t *d, char const *ip, unsigned int mask) </code> <br />
Writes into <em>d</em> the <tt>ip6.arpa.</tt> domain corresponding to the first
<em>mask</em> bits of IPv6 address <em>ip</em> (16 bytes, in network byte order),
in string form.
Only multiples of 4 count for <em>mask</em>, i.e. the output will be the same
if mask is (for instance) 125, 126, 127 or 128.
</p>
</body>
</html>
|
