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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
<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_hosts library interface</title>
<meta name="Description" content="s6-dns: the s6dns_hosts library interface" />
<meta name="Keywords" content="s6-dns dns s6dns_hosts library libs6dns /etc/hosts" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">libs6dns</a><br />
<a href="../">s6-dns</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>s6dns_hosts</tt> library interface </h1>
<p>
The following functions are declared in the <tt>s6-dns/hosts.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_hosts</tt> provides functions and macros - mostly macros -
to perform name-to-IP or IP-to-name resolution according to the
local <tt>/etc/hosts</tt> file.
</p>
<p>
Most of the functions declared here are variations of another, more
generic function. Typically, a <em>foobar_r</em> function is the
generic one, and will take additional arguments such as: a pointer to
a local hosts database (compiled to an efficient format), and/or a
list and number of rules for qualification. The corresponding <em>foobar</em>
function is the same, except that it uses global variables to fill
these additional arguments: for instance, the hosts database made from
<tt>/etc/hosts</tt>, or the qualification rules computed from
<tt>/etc/resolv.conf</tt>. We document the simpler functions — even
though they're macros, we pretend they're functions; please refer to
the <a href="https://git.skarnet.org/cgi-bin/cgit.cgi/s6-dns/tree/src/include/s6-dns/hosts.h">s6-dns/hosts.h</a>
file for the exact prototypes or if you want to use the generic functions.
</p>
<ul>
<li> <tt>s6dns_engine_here</tt>: a global
<a href="s6dns-engine.html">s6dns_engine_t</a> storing the current
query, for sequential queries. </li>
<li> <tt>s6dns_debughook_zero</tt>: a global <tt>s6dns_debughook_t</tt>
meaning no debugging is needed. </li>
<li> <tt>s6dns_rci_here</tt>: a global
<a href="s6dns-rci.html">s6dns_rci_t</a> containing the current
resolv.conf information. </li>
</ul>
<h2> Global variables </h2>
<p>
<code> cdb s6dns_hosts_here </code> <br />
<tt>s6dns_hosts_here</tt> is the global <tt>cdb</tt> database containing
the compiled data from <tt>/etc/hosts</tt>. You normally do not need to
use it manually because it is implicitly supplied to functions when you
use the macros without a <tt>_r</tt> suffix.
</p>
<h2> Functions </h2>
<h3> Compilation </h3>
<p>
<code> int s6dns_hosts_compile (int fdr, int fdw) </code> <br />
Compiles the text file data from file descriptor <tt>fdr</tt>,
which should be in <tt>/etc/hosts</tt> format, into a cdb file
written to file descriptor <tt>fdw</tt>. <tt>fdr</tt> must be
open for reading, and <tt>fdw</tt> must be open for writing and
seekable. The function returns 1 on success and 0 (and sets errno)
on failure. A syntax error in the text file results in failure,
but link-local addresses are silently ignored.
</p>
<p>
You normally don't need to use this function yourself. To
compile the hosts database prior to use, you can call the
<a href="../s6-dns-hosts-compile.html">s6-dns-hosts-compile</a>
program (which uses this function). Alternatively,
at initialization time, the hosts database will be compiled
automatically if there isn't a more recent compiled version.
</p>
<h3> Initialization </h3>
<p>
<code> int s6dns_hosts_init (cdb *c, char const *txtfile, char const *cdbfile, char const *prefix) </code> <br />
Initializes the compiled hosts database in <em>*c</em>.
If there's a pre-compiled <em>cdbfile</em> file that
is more recent than <tt>/etc/hosts</tt>, then it is used;
else, the <em>txtfile</em> file is compiled into a
temporary file starting with <em>prefix</em>, which is used and
immediately unlinked. The function returns -1 (and sets errno)
on failure, 1 on success, and 0 if it can find neither a
suitable <em>cdbfile</em> nor a suitable <em>txtfile</em>.
</p>
<p>
<code> void s6dns_hosts_free (cdb *c) </code> <br />
Frees the compiled hosts database in <em>c</em>.
</p>
<p>
You probably don't need to use these functions yourself:
instead, the higher-level <tt>s6dns_init()</tt> and
<tt>s6dns_finish()</tt> functions perform all the necessary
initialization and cleanup, including the hosts database one.
</p>
<h3> IP to name resolution </h3>
<p>
<code> int s6dns_hosts_name (char const *ip, stralloc *storage, genalloc *indices, int is6) </code> <br />
Gets the list of names for IP address <em>ip</em> from the hosts database.
The names are stored in the stralloc <em>*storage</em>; for each name,
its index in <em>storage→s</em> is appended, as a <tt>size_t</tt>,
to the genalloc <em>*indices</em>. If <em>is6</em> is nonzero, <em>ip</em>
is interpreted as an IPv6 address, i.e. a network byte order sequence of
16 bytes; otherwise it is interpreted as an IPv4 address, i.e. a network
byte order sequence of 4 bytes. The function returns -1 (and sets errno)
in case of failure, 0 if no match could be found (which includes no
existing hosts database), or the number of names it found. Names listed
as the first name on a line in <tt>/etc/hosts</tt> are always given as
fully qualified, i.e. with a terminating dot; other names are given as
they were input in <tt>/etc/hosts</tt>.
</p>
<p>
<code> int s6dns_hosts_name4 (char const *ip, stralloc *storage, genalloc *indices) </code> <br />
Same, but <em>ip</em> is assumed to be an IPv4.
</p>
<p>
<code> int s6dns_hosts_name6 (char const *ip, stralloc *storage, genalloc *indices) </code> <br />
Same, but <em>ip</em> is assumed to be an IPv6.
</p>
<h3> Name to IP resolution </h3>
<h4> Fully qualified names </h4>
<p>
<code> extern int s6dns_hosts_a_noq (char const *name, stralloc *ip4s) </code> <br />
Gets the list of IPv4 addresses for name <em>name</em> from the hosts database.
The addresses are stored in the stralloc <em>*ip4s</em>, in network byte order,
4 bytes per item. <em>name</em> is assumed to be fully qualified: <tt>skarnet.org</tt>
will yield the same results as <tt>skarnet.org.</tt>, and <tt>blah</tt> will yield
the same results as <tt>blah.</tt> with the ending dot. The function returns -1
(and sets errno) in case of failure, 0 if no match (including no valid hosts
database), or the number of IP addresses appended to <em>*ip4s</em> (i.e. the
length increase divided by 4).
</p>
<p>
<code> extern int s6dns_hosts_aaaa_noq (char const *name, stralloc *ip6s) </code> <br />
Same as above, but gets the list of IPv6 addresses for <em>name</em>; there are
16 bytes per address instead of 4.
</p>
<p>
<code> extern int s6dns_hosts_aaaaa_noq (char const *name, genalloc *ips) </code> <br />
Same as above, but gets the list of all IP addresses for <em>name</em>, v4 or v6
indiscriminately. Every address is stored in the genalloc <em>*ips</em> as an
<a href="https://git.skarnet.org/cgi-bin/cgit.cgi/skalibs/tree/src/headers/ip46-header#n21"><tt>ip46full</tt> structure</a>.
</p>
<h4> Aliases </h4>
<p>
<code> extern int s6dns_hosts_a_unq (char const *name, stralloc *ip4s) </code> <br />
Gets the list of IPv4 addresses for name <em>name</em> from the hosts database.
The addresses are stored in the stralloc <em>*ip4s</em>, in network byte order,
4 bytes per item. <em>name</em> is assumed to be unqualified: <tt>blah</tt>
is interpreted as a local alias that will only match a <tt>blah</tt>
entry in <tt>/etc/hosts</tt> that does <strong>not</strong> appear as a first
entry. The function returns -1
(and sets errno) in case of failure, 0 if no match (including no valid hosts
database), or the number of IP addresses appended to <em>*ip4s</em> (i.e. the
length increase divided by 4).
</p>
<p>
<code> extern int s6dns_hosts_aaaa_unq (char const *name, stralloc *ip6s) </code> <br />
Same as above, but gets the list of IPv6 addresses for <em>name</em>; there are
16 bytes per address instead of 4.
</p>
<p>
<code> extern int s6dns_hosts_aaaaa_unq (char const *name, genalloc *ips) </code> <br />
Same as above, but gets the list of all IP addresses for <em>name</em>, v4 or v6
indiscriminately. Every address is stored in the genalloc <em>*ips</em> as an
<a href="https://git.skarnet.org/cgi-bin/cgit.cgi/skalibs/tree/src/headers/ip46-header#n21"><tt>ip46full</tt> structure</a>.
</p>
<h4> With qualification </h4>
<p>
<code> extern int s6dns_hosts_a_q (char const *name, stralloc *ip4s) </code> <br />
Gets the list of IPv4 addresses, from the hosts database, for all possible
qualifications for name <em>name</em>.
The addresses are stored in the stralloc <em>*ip4s</em>, in network byte order,
4 bytes per item. The function returns -1
(and sets errno) in case of failure, 0 if no match (including no valid hosts
database), or the number of IP addresses appended to <em>*ip4s</em> (i.e. the
length increase divided by 4).
</p>
<p>
First, <em>name</em> is looked up in the hosts database as a simple
unqualified names. Then, <em>name</em> is qualified with all the suffixes
read from <tt>/etc/resolv.conf</tt>, and all of the resulting FQDNs are
looked up in the hosts database. All the results are concatenated and
appended to the <em>*ip4s</em> stralloc.
</p>
<p>
<code> extern int s6dns_hosts_aaaa_q (char const *name, stralloc *ip6s) </code> <br />
Same as above, but gets the list of IPv6 addresses for <em>name</em>; there are
16 bytes per address instead of 4.
</p>
<p>
<code> extern int s6dns_hosts_aaaaa_q (char const *name, genalloc *ips) </code> <br />
Same as above, but gets the list of all IP addresses for <em>name</em>, v4 or v6
indiscriminately. Every address is stored in the genalloc <em>*ips</em> as an
<a href="https://git.skarnet.org/cgi-bin/cgit.cgi/skalibs/tree/src/headers/ip46-header#n21"><tt>ip46full</tt> structure</a>.
</p>
</body>
</html>
|
