root/src/udns/udns.3

Revision 5a9b91bc0a14543e0995eba973fbeacc05aaee8b, 56.3 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 6 years ago)

svn merge -r 327:330 https://labs.omniti.com/reconnoiter/branches/dev/udns .

closes #38

  • Property mode set to 100644
Line 
1 .\" $Id: udns.3,v 1.32 2007/01/15 21:19:08 mjt Exp $
2 .\" udns library manpage
3 .\"
4 .\" Copyright (C) 2005  Michael Tokarev <mjt@corpit.ru>
5 .\" This file is part of UDNS library, an async DNS stub resolver.
6 .\"
7 .\" This library is free software; you can redistribute it and/or
8 .\" modify it under the terms of the GNU Lesser General Public
9 .\" License as published by the Free Software Foundation; either
10 .\" version 2.1 of the License, or (at your option) any later version.
11 .\"
12 .\" This library is distributed in the hope that it will be useful,
13 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
14 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15 .\" Lesser General Public License for more details.
16 .\"
17 .\" You should have received a copy of the GNU Lesser General Public
18 .\" License along with this library, in file named COPYING.LGPL; if not,
19 .\" write to the Free Software Foundation, Inc., 59 Temple Place,
20 .\" Suite 330, Boston, MA  02111-1307  USA
21
22 .TH udns 3 "Jan 2007" "Library Functions"
23
24 .SH NAME
25 udns \- stub DNS resolver library
26
27 .SH SYNOPSYS
28 .nf
29 #include <udns.h>
30 struct \fBdns_ctx\fR;
31 struct \fBdns_query\fR;
32 extern struct dns_ctx \fBdns_defctx\fR;
33 struct dns_ctx *\fIctx\fR;
34 typedef void \fBdns_query_fn\fR(\fIctx\fR, void *\fIresult\fR, void *\fIdata\fR);
35 typedef int
36 \fBdns_parse_fn\fR(const unsigned char *\fIqnd\fR,
37        const unsigned char *\fIpkt\fR,
38        const unsigned char *\fIcur\fR,
39        const unsigned char *\fIend\fR,
40        void **\fIresultp\fR);
41
42 \fBcc\fR ... -l\fBudns\fR
43 .fi
44
45 .SH DESCRIPTION
46
47 .PP
48 The DNS library, \fBudns\fR, implements thread-safe stub DNS resolver
49 functionality, which may be used both traditional, syncronous way
50 and asyncronously, with application-supplied event loop.
51
52 .PP
53 While DNS works with both TCP and UDP, performing UDP query first and
54 if the result does not fit in UDP buffer (512 bytes max for original
55 DNS protocol), retrying the query over TCP, the library uses UDP only,
56 but uses EDNS0 (RFC2671) extensions which allows larger UDP buffers.
57
58 .PP
59 The library uses single UDP socket to perform all operations even when
60 asking multiple nameservers.  This way, it is very simple to use the
61 library in asyncronous event-loop applications: an application should
62 add only single socket to the set of filedescriptors it monitors for I/O.
63
64 .PP
65 The library uses two main objects, \fIresolver context\fR of type
66 \fBstruct\ dns_ctx\fR, and \fIquery structure\fR of type
67 \fBstruct\ dns_query\fR, both are opaque for an application.
68 Resolver context holds global information about the resolver,
69 such as list of nameservers to use, list of active requests and the like.
70 Query objects holds information about a single DNS query in progress and
71 are allocated/processed/freed by the library.   Pointer to query structure
72 may be treated as an identifier of an in-progress query and may be used
73 to cancel the asyncronous query or to wait for it to complete.
74
75 .PP
76 Asyncronous interface works as follows.  An application initializes
77 resolver context, submits any number of queries for it using one of
78 supplied \fBdns_submit_\fIXXX\fR() routines (each return the query
79 identifier as pointer to query structure), waits for input on the
80 UDP socket used by the library, and gives some control to the library
81 by calling \fBdns_ioevent\fR() and \fBdns_timeouts\fR() routines when
82 appropriate.  The library performs all necessary processing and executes
83 application supplied callback routine when a query completes (either
84 successefully or not), giving it the result if any, pointer to the
85 resolver context (from which completion status may be obtained), and
86 the data pointer supplied by an application when the query has been
87 submitted.  When submitting a query, an application requests how to
88 handle the reply -- to either return raw DNS reply packet for its
89 own low-level processing, or it may provide an address of \fIparsing
90 routine\fR of type \fBdns_parse_fn\fR to perform conversion of on-wire
91 format into easy to use data structure (the library provides parsing
92 routines for several commonly used resource record types, as well as
93 type-safe higher-level inteface that requests parsing automatically).
94 The I/O monitoring and timeout handling may be either traditional
95 select() or poll() based, or any callback-driven technique may be
96 used.
97
98 .PP
99 Additionally, the library provides traditional syncronous interface,
100 which may be intermixed with asyncronous calls (during syncronous
101 query processing, other asyncronous queries for the same resolver
102 context continued to be processed as usual).  An application uses
103 one of numerous \fBdns_resolve_\fIXXX\fR() routines provided by the
104 library to perform a query.  As with asyncronous interface, an
105 application may either request to return raw DNS packet or type-specific
106 data structure by providing the parsing routine to handle the reply.
107 Every routine from \fBdns_resolve_\fIXXX\fR() series return pointer
108 to result or NULL in case of any error.  Query completion status
109 (or length of the raw DNS packet) is available from the resolver
110 context using \fBdns_status\fR() routine, the same way as for the
111 asyncronous interface.
112
113 .PP
114 Internally, library uses on-wire format of domain names, referred
115 to as \fIDN format\fR in this manual page.  This is a series of domain
116 \fIlabels\fR whith preceeding length byte, terminated by zero-length
117 label wich is integral part of the DN format.  There are several routines
118 provided to convert from traditional asciiz string to DN and back.
119 Higher-level type-specific query interface hides the DN format from
120 an application.
121
122 .SH "COMMON DEFINITIONS"
123
124 .PP
125 Every DNS Resource Record (RR) has a \fItype\fR and a \fIclass\fR.
126 The library defines several integer constants, \fBDNS_C_\fIXXX\fR and
127 \fBDNS_T_\fIXXX\fR, to use as symbolic names for RR classes and types,
128 such as \fBDNS_C_IN\fR for Internet class, \fBDNS_T_A\fR for IPv4
129 address record type and so on.  See udns.h header file for complete list
130 of all such constants.
131
132 .PP
133 The following constants are defined in udns.h header file:
134 .IP "\fBDNS_MAXDN\fR (255 bytes)"
135 Maximum length of the domain name in internal (on-wire) DN format.
136 .IP "\fBDNS_MAXLABEL\fR (63 bytes)"
137 Maximum length of a single label in DN format.
138 .IP "\fBDNS_MAXNAME\fR (1024 bytes)"
139 Maximum length of asciiz format of a domain name.
140 .IP "\fBDNS_HSIZE\fR (12 bytes)"
141 Size of header in DNS packet.
142 .IP "\fBDNS_PORT\fR (53)"
143 Default port to use when contacting a DNS server.
144 .IP "\fBDNS_MAXSERV\fR (6 servers)"
145 Maximum number of DNS servers to use.
146 .IP "\fBDNS_MAXPACKET\fR (512 bytes)"
147 Maximum length of DNS UDP packet as specified by original DNS protocol
148 .IP "\fBDNS_EDNS0PACKET\fR (4096 bytes)"
149 Default length of DNS UDP packet (with EDNS0 extensions) the library uses.
150 Note that recursive nameservers usually resides near the client asking them
151 to resolve names, e.g. on the same LAN segment or even on the same host, so
152 UDP packet fragmentation isn't a problem in most cases.  Note also that
153 the size of actual packets will be as many bytes as actual reply size requires,
154 which is smaller than this value in almost all cases.
155
156 .PP
157 Additionally, several constants are defined to simplify work with raw DNS
158 packets, such as DNS response codes (\fBDNS_R_\fIXXX\fR), DNS header layout
159 (\fBDNS_H_\fIXXX\fR) and others.  Again, see udns.h for complete list.
160 Library error codes (\fBDNS_E_\fIXXX\fR) are described later in this
161 manual page.
162
163 .SH "RESOLVER CONTEXT"
164
165 .PP
166 Resolver context, of type \fBstruct\ dns_ctx\fR, is an object which is
167 opaque to an application.  Several routines provided by the library
168 to initialize, copy and free resolver contexts.  Most other high-level
169 routines in this library expects a pointer to resolver context, \fIctx\fR,
170 as the first argument.  There is a default resolver context available,
171 named \fBdns_defctx\fR.  When the context pointer \fIctx\fR passed to
172 a routine is NULL, \fBdns_defctx\fR is used.  Several resolver contexts
173 may be active at the same time, for example, when an application is
174 multi-threaded and each thread uses resolver.
175 .PP
176 In order to use the library, an application should initialize and open
177 one or more resolver context objects.  These are two separate actions,
178 performed by \fBdns_init\fR() (or \fBdns_reset\fR()), and \fBdns_open\fR().
179 Between the two calls, an application is free to pefrorm additional
180 initialisation, such as setting custom nameservers, options or domain search
181 lists.  Optionally, in case no additional custom initialisation is required,
182 \fBdns_init\fR() may open the context if \fIdo_open\fR argument (see below)
183 is non-zero.
184 .PP
185 When initializing resolver context, the library uses information from
186 system file /etc/resolv.conf (see \fBresolv.conf\fR(5)), consults
187 environment variables \fB$LOCALDOMAIN\fR, \fB$DNSCACHEIP\fR,
188 \fB$NAMESERVERS\fR and \fB$RES_OPTIONS\fR, and local host name to obtain
189 list of local nameservers, domain name search list and various resolver
190 options.
191 .PP
192 The following routines to initialize resolver context are available:
193 .PP
194 .nf
195 void \fBdns_reset\fR(\fIctx\fR)
196 int \fBdns_init\fR(\fIctx\fR, int \fIdo_open\fR)
197 .fi
198 .RS
199 \fBdns_reset\fR() resets a given resolver context to default values,
200 preparing it to be opened by \fBdns_open\fR().
201 It is ok to call this routine against opened and active context - all active
202 queries will be dropped, sockets will be closed and so on.  This routine
203 does not initialize any parameters from system configuration files, use
204 \fBdns_init\fR() for this.  There's no error return - operation always
205 succeeds.  \fBdns_init\fR() does everything \fBdns_reset\fR() does,
206 plus initializes various parameters of the context according to system
207 configuration and process environment variables.  If \fIdo_open\fR is
208 non-zero, \fBdns_init\fR() calls \fIdns_open\fR(), so that the whole
209 library initialisation is performed in a single step.
210 .RE
211 .PP
212 .nf
213 struct dns_ctx *\fBdns_new\fR(struct dns_ctx *\fIcopy\fR)
214 void \fBdns_free\fR(\fIctx\fR)
215 .fi
216 .RS
217 \fBdns_new\fR() allocates new resolver context and copies all parameters
218 for a given resolver context \fIcopy\fR, or default context if \fIcopy\fR
219 is NULL, and returns pointer to the newly allocated context.  The context
220 being copied should be initialized.
221 \fBdns_new\fR() may fail if there's no memory available to make a copy
222 of \fIcopy\fR, in which case the routine will return NULL pointer.
223 \fBdns_free\fR() is used to close assotiated socket and free resolver
224 context resources and cancelling (abandoming) all active queries
225 assotiated with it.  It's an error to free \fBdns_defctx\fR, only
226 dynamically allocated contexts returned by \fBdns_new\fR() are allowed
227 to be freed by \fBdns_free\fR().
228 .RE
229 .PP
230 .nf
231 int \fBdns_add_serv\fR(\fIctx\fR, const char *\fIservaddr\fR)
232 int \fBdns_add_serv_s\fR(\fIctx\fR, const struct sockaddr *\fIsa\fR)
233 int \fBdns_add_srch\fR(\fIctx\fR, const char *\fIsrch\fR)
234 .fi
235 .RS
236 Add an element to list of nameservers (\fBdns_add_serv\fR(), as
237 asciiz-string \fIservaddr\fR with an IP address of the nameserver,
238 and \fBdns_add_serv_s\fR(), as initialized socket address \fIsa\fR),
239 or search list (\fBdns_add_srch\fR(), as a pointer to domain name)
240 for the given context \fIctx\fR.  If the last argument is a NULL
241 pointer, the corresponding list (search or nameserver) is reset
242 instead.  Upon successeful completion, each routine returns new
243 number of elements in the list in question.  On error, negative
244 value is returned and global variable \fBerrno\fR is set appropriately.
245 It is an error to call any of this functions if the context is
246 opened (after \fBdns_open\fR() or \fBdns_init\fR() with non-zero argument).
247 .RE
248 .PP
249 .nf
250 int \fBdns_set_opts\fR(\fIctx\fR, const char *\fIopts\fR)
251 .fi
252 .RS
253 set resolver context options from \fIopts\fR string, in the same way as
254 processing \fBoptions\fR statement in resolv.conf and \fB$RES_OPTIONS\fR
255 environment variable.
256 .RE
257 .PP
258 .nf
259 void \fBdns_set_opt\fR(\fIctx\fR, int \fIopt\fR, \fIval\fR)
260 .fi
261 .RS
262 .B TODO
263 The \fIflags\fR argument is a bitmask with the following bits defined:
264 .IP \fBDNS_NOSRCH\fR
265 do not perform domain name search in search list.
266 .IP \fBDNS_NORD\fR
267 do not request recursion when performing queries
268 (i.e. don't set RD flag in querues).
269 .IP \fBDNS_AAONLY\fR
270 request authoritative answers only (i.e. set AA
271 flag in queries).
272 .RE
273
274 .PP
275 .nf
276 int \fBdns_open\fR(\fIctx\fR)
277 int \fBdns_sock\fR(const \fIctx\fR)
278 void \fBdns_close\fR(\fIctx\fR)
279 .fi
280 .RS
281 \fBdns_open\fR() opens the UDP socket used for queries if not already
282 open, and return assotiated filedescriptor (or negative value in case
283 of error).  Before any query can be submitted, the context should be
284 opened using this routine.  And before opening, the context should be
285 initialized.
286 \fBdns_sock\fR() return the UDP socket if open, or -1 if not.
287 \fBdns_close\fR() closes the UDP socket if it was open, and drops all active
288 queries if any.
289 .RE
290
291 .PP
292 .nf
293 int \fBdns_active\fR(const \fIctx\fR)
294 .fi
295 .RS
296 return number of active queries queued for the given context
297 \fIctx\fR, or zero if none.
298 .RE
299
300 .PP
301 .nf
302 int \fBdns_status\fR(const \fIctx\fR)
303 .fi
304 .RS
305 return status code from last operation.  When using syncronous
306 interface, this is the query completion status of the last query.
307 With asyncronous interface, from within the callback routine,
308 this is the query completion status of the query for which the
309 callback is being called.  When query submission fails, this
310 is the error code indicating failure reason.  All error codes
311 are negative and are represented by \fBDNS_E_\fIXXX\fR constants
312 described below.
313 .RE
314
315 .PP
316 .nf
317 void \fBdns_ioevent\fR(\fIctx\fR, time_t \fInow\fR)
318 .fi
319 .RS
320 this routine may be called by an application to process I/O
321 events on the UDP socket used by the library, as returned
322 by \fBdns_sock\fR().  The routine tries to receive incoming
323 UDP datagram from the socket and process it.  The socket is
324 set up to be non-blocking, so it is safe to call the routine
325 even if there's no data to read.  The routine will process
326 as many datagrams as are queued for the socket, so it is
327 safe to use it with either level-triggered or edge-triggered
328 I/O monitoring model.  The \fInow\fR argument is either a
329 current time as returned by \fBtime\fR(), or 0, in which
330 case the routine will obtain current time by it's own.
331 .RE
332
333 .PP
334 .nf
335 int \fBdns_timeouts\fR(\fIctx\fR, int \fImaxwait\fR, time_t \fInow\fR)
336 .fi
337 .RS
338 process any pending timeouts and return number of secounds
339 from current time (\fInow\fR if it is not 0) to the time when
340 the library wants the application to pass it control to process
341 more queued requests.  In case when there are no requests pending,
342 this time is -1.  The routine will not request a time larger than
343 \fImaxwait\fR secounds if it is greather or equal to zero.  If
344 \fInow\fR is 0, the routine will obtain current time by it's own;
345 when it is not 0, it should contain current time as returned by
346 \fBtime\fR().
347 .RE
348
349 .PP
350 .nf
351 typedef void \fBdns_utm_fn\fR(\fIctx\fR, int \fItimeout\fR, void *\fIdata\fR)
352 void \fBdns_set_cbck\fR(\fIctx\fR, dns_utm_fn *\fIutmfn\fR, void *\fIdata\fR)
353 .fi
354 .RS
355 An application may use custom callback-based I/O multiplexing mechanism.
356 Usually such a mechanism have concept of a \fItimer\fR, and an ability
357 to register a timer event in a form of a callback routine which will
358 be executed after certain amount of time.  In order to use such an
359 event mechanism, udns provides an ability to register and de-register
360 timer events necessary for internal processing using whatever event
361 mechanism an application uses.  For this to work, it is possible to
362 assotiate a pointer to a routine that will perform necessary work for
363 (de)registering timer events with a given resolver context, and
364 udns will call that routine at appropriate times.  Prototype of
365 such a routine is shown by \fBdns_utm_fn\fR typedef above.  Libudns
366 assotiates single timer with resolver context.  User-supplied \fIutmfn\fR
367 routine will be called by the library with the following arguments:
368 .IP "\fIctx\fR == NULL"
369 delete user timer, at context free time or when an application changes
370 user timer request routine using \fBdns_set_cbck\fR();
371 .IP "\fIctx\fR != NULL, \fItimeout\fR < 0"
372 don't fire timer anymore, when there are no active requests;
373 .IP "\fIctx\fR != NULL, \fItimeout\fR == 0"
374 fire timer at the next possibility, but not immediately;
375 .IP "\fIctx\fR != NULL, \fItimeout\fR > 0"
376 fire timer after \fItimeout\fR seconds after now.
377 .PP
378 The \fIdata\fR argument passed to the routine will be the same
379 as passed to \fBdns_set_cbck\fR().
380 .PP
381 When a timer expires, an application should call \fBdns_tmeouts\fR()
382 routine (see below).  Non-callback timer usage is provided too.
383 .RE
384
385 .PP
386 .B XXXX TODO: some more resolver context routines, like dns_set_dbgfn() etc.
387
388 .SH "QUERY INTERFACE"
389
390 .PP
391 There are two ways to perform DNS queries: traditional syncronous
392 way, when udns performs all the necessary processing and return
393 control to the application only when the query completes, and
394 asyncronous way, when an application submits one or more queries
395 to the library using given resolver context, and waits for completion
396 by monitoring filedescriptor used by library and calling library
397 routines to process input on that filedescriptor.  Asyncronous mode
398 works with callback routines: an application supplies an address of
399 a routine to execute when the query completes, and a data pointer,
400 which is passed to the callback routine.
401
402 .PP
403 Queries are submitted to the library in a form of \fBstruct\ dns_query\fR.
404 To perform asyncronous query, an application calls one of the
405 \fBdns_submit_\fIXXX\fR() rounines, and provides necessary information
406 for a callback, together with all the query parameters.
407 When the query completes, library will call application-supplied callback
408 routine, giving it the resolver context (wich holds query completion status),
409 dynamically allocated result (which will be either raw DNS packet or, if
410 applicatin requested parsing the result by specifying non-NULL parse routine,
411 ready-to-use type-specific structure), and a data pointer provided by an
412 application when it submitted the query.  It is the application who's
413 responsible for freeing the result memory.
414 .PP
415 Generic query callback routine looks like this:
416 .nf
417 typedef void
418 \fBdns_query_fn\fR(\fIctx\fR, void *\fIresult\fR, void *\fIdata\fR)
419 .fi
420 Type-specific query interface expects similar form of callback
421 routine with the only difference in type of \fBresult\fR argument,
422 which will be pointer to specific data structure (decoded reply)
423 instead of this void pointer to raw DNS packet data.
424
425 .PP
426 Result parsing routine looks like this:
427 .nf
428 typedef int
429 \fBdns_parse_fn\fR(const unsigned char *\fIqdn\fR,
430       const unsigned char *\fIpkt\fR,
431       const unsigned char *\fIcur\fR,
432       const unsigned char *\fIend\fR,
433       void **\fIresultp\fR);
434 .fi
435 When called by the library, the arguments are as follows:
436 \fIpkt\fR points to the start of the packet received;
437 \fIend\fR points past the end of the packet received;
438 \fIcur\fR points past the query DN in the query section of the
439 packet;
440 \fIqdn\fR points to the original query DN.
441 The routine should allocate a single buffer to hold the result,
442 parse the reply filling in the buffer, and return the buffer
443 using \fIresultp\fR argument.  It returns 0 in case of error,
444 or udns error code (\fBDNS_E_\fIXXX\fR constants) in case of
445 error.
446 Note that by the time when the parse routine is called by the
447 library, packet is already verified to be a reply to the
448 original query, by matching query DN, query class and query type.
449
450 .PP
451 Type-specific query inteface supplies necessary parsing routines
452 automatically.
453
454 .PP
455 In case of error, query completion status as returned by
456 \fBdns_status\fR(\fIctx\fR), will contain one of the following values:
457 .IP "positive value"
458 length of raw DNS packet if parsing is not requested.
459 .IP 0
460 the query was successeful and the \fIreply\fR points to type-specific
461 data structure.
462 .IP \fBDNS_E_TEMPFAIL\fR
463 temporary error, the resolver nameserver was not able to
464 process our query or timed out.
465 .IP \fBDNS_E_PROTOCOL\fR
466 protocol error, a nameserver returned malformed reply.
467 .IP \fBDNS_E_NXDOMAIN\fR
468 the domain name does not exist.
469 .IP \fBDNS_E_NODATA\fR
470 there is no data of requested type found.
471 .IP \fBDNS_E_NOMEM\fR
472 out of memory while processing request.
473 .IP \fBDNS_E_BADQUERY\fR
474 some aspect of the query (most common is the domain name in question)
475 is invalid, and the library can't even start a query.
476
477 .PP
478 Library provides two series of routines which uses similar interface --
479 one for asyncronous queries and another for syncronous queries.  There
480 are two general low-level routines in each series to submit (asyncronous
481 interface) and resolve (syncronous interface) queries, as well as several
482 type-specific routines with more easy-to-use interfaces.  To submit
483 an asyncronous query, use one of \fBdns_submit_\fIXXX\fR() routine, each
484 of which accepts query parameters, pointers to callback routine and to
485 callback data, and optional current time hint.  Note type-specific
486 \fBdns_submit_\fIXXX\fR() routines expects specific type of the callback
487 routine as well, which accepts reply as a pointer to corresponding
488 structure, not a void pointer).  Every \fBdns_submit_\fIXXX\fR() routine
489 return pointer to internal query structure of type struct\ dns_query,
490 used as an identifier for the given query.
491
492 .PP
493 To resolve a query syncronously, use one of \fBdns_resolve_\fIXXX\fR()
494 routines, which accepts the same query parameters (but not the
495 callback pointers) as corresponding \fBdns_submit_\fIXXX\fR(), and
496 return the query result, which is the same as passed to the callback
497 routine in case of asyncronous interface.
498
499 .PP
500 In either case, the result memory (if the query completed successefully)
501 is dynamically allocated and should be freed by an application.  If
502 the query failed for any reason, the result will be NULL, and error
503 status will be available from \fBdns_status\fR(\fIctx\fR) routine
504 as shown above.
505
506 .PP
507 .nf
508 struct dns_query *
509 \fBdns_submit_dn\fR(\fIctx\fR,
510      const unsigned char *\fIdn\fR, \fIqcls\fR, \fIqtyp\fR, \fIflags\fR,
511      \fIparse\fR, \fIcbck\fR, \fIdata\fR)
512 struct dns_query *
513 \fBdns_submit_p\fR(\fIctx\fR,
514      const char *\fIname\fR, \fIqcls\fR, \fIqtyp\fR, \fIflags\fR,
515      \fIparse\fR, \fIcbck\fR, \fIdata\fR)
516    enum dns_class \fIqcls\fR;
517    enum dns_type \fIqtyp\fR;
518    int \fIflags\fR;
519    dns_parse_fn *\fIparse\fR;
520    dns_query_fn *\fIcbck\fR;
521    void *\fIdata\fR;
522 .fi
523 .RS
524 submit a query for processing for the given resolver context \fIctx\fR.
525 Two routines differs only in 3rd argument, which is domain name in
526 DN format (\fIdn\fR) or asciiz string (\fIname\fR).  The query will be
527 performed for the given domain name, with type \fIqtyp\fR in class \fIqcls\fR,
528 using option bits in \fIflags\fR, using RR parsing routine pointed by
529 \fIparse\fR if not-NULL, and upon completion, \fIcbck\fR function will
530 be called with the \fIdata\fR argument.
531 In case of successeful query submission,
532 the routine return pointer to internal query structure which may be treated
533 as an identifier of the query as used by the library, and may be used as an
534 argument for \fBdns_cancel\fR() routine.  In case of error, NULL will be
535 returned, and context error status (available using \fIdns_status\fR() routine)
536 will be set to corresponding error code, which in this case may be
537 DNS_E_BADQUERY if the \fIname\fR of \fIdn\fR is invalid, DNS_E_NOMEM if
538 there's no memory available to allocate query structure, or DNS_E_TEMPFAIL
539 if an internal error occured.
540 .RE
541
542 .PP
543 .nf
544 void *\fBdns_resolve_dn\fR(\fIctx\fR,
545      const unsigned char *\fIdn\fR, \fIqcls\fR, \fIqtyp\fR, \fIflags\fR, \fIparse\fR);
546 void *\fBdns_resolve_p\fR(\fIctx\fR,
547      const char *\fIname\fR, \fIqcls\fR, \fIqtyp\fR, \fIflags\fR, \fIparse\fR)
548    enum dns_class \fIqcls\fR;
549    enum dns_type \fIqtyp\fR;
550    int \fIflags\fR;
551    dns_parse_fn *\fIparse\fR; 
552 .fi
553 .RS
554 syncronous interface.  The routines perform all the steps necessary to resolve
555 the given query and return the result.  If there's no positive result for any
556 reason, all the routines return NULL, and set context error status (available
557 using \fBdns_status\fR() routine) to indicate the error code.  If the query
558 was successeful, context status code will contain either the length of the
559 raw DNS reply packet if \fIparse\fR argument was NULL (in which case the return
560 value is pointer to the reply DNS packet), or 0 (in which case the return value
561 is the result of \fIparse\fR routine).  If the query successeful (return value
562 is not NULL), the memory returned was dynamically allocated by the library
563 and should be free()d by application after use.
564 .RE
565
566 .PP
567 .nf
568 void *\fBdns_resolve\fR(\fIctx\fR, struct dns_query *\fIq\fR)
569 .fi
570 .RS
571 wait for the given query \fIq\fR, as returned by one of
572 \fBdns_submit_\fIXXX\fR() routines, for completion, and
573 return the result.  The callback routine will not be called
574 for this query.  After completion, the query identifier \fIq\fR
575 is not valid. Both \fBdns_resolve_dn\fR() and \fBdns_resolve_p\fR()
576 are just wrappers around corresponding submit routines and this
577 \fBdns_resolve\fR() routine.
578 .RE
579
580 .PP
581 .nf
582 void \fBdns_cancel\fR(\fIctx\fR, struct dns_query *\fIq\fR)
583 .fi
584 .RS
585 cancel an active query \fIq\fR, without calling a callback routine.
586 After completion, the query identifier \fIq\fR is not valid.
587 .RE
588
589 .SH "TYPE-SPECIFIC QUERIES"
590
591 .PP
592 In addition to the generic low-level query interface, the library provides
593 a set of routines to perform specific queries in a type-safe manner, as
594 well as parsers for several well-known resource record types.  The library
595 implements high-level interface for A, AAAA, PTR, MX and TXT records
596 and DNSBL and RHSBL functionality.  These routines returns specific types
597 as result of a query, instead of raw DNS packets.  The following types
598 and routines are available.
599
600 .PP
601 .nf
602 struct \fBdns_rr_null\fR {
603   char *\fBdnsn_qname\fR;     /* original query name */
604   char *\fBdnsn_cname\fR;     /* canonical name */
605   unsigned \fBdnsn_ttl\fR;    /* Time-To-Live (TTL) value */
606   int \fBdnsn_nrr\fR;         /* number of records in the set */
607 };
608 .fi
609 .PP
610 NULL RR set, used as a base for all other RR type structures.
611 Every RR structure as used by the library have four standard
612 fields as in struct\ \fBdns_rr_null\fR.
613
614 .SS "IN A Queries"
615 .PP
616 .nf
617 struct \fBdns_rr_a4\fR {       /* IN A RRset */
618   char *\fBdnsa4_qname\fR;     /* original query name */
619   char *\fBdnsa4_cname\fR;     /* canonical name */
620   unsigned \fBdnsa4_ttl\fR;    /* Time-To-Live (TTL) value */
621   int \fBdnsa4_nrr\fR;         /* number of addresses in the set */
622   struct in_addr \fBdnsa4_addr\fR[]; /* array of addresses */
623 };
624 typedef void
625   \fBdns_query_a4_fn\fR(\fIctx\fR, struct dns_rr_a4 *\fIresult\fR, \fIdata\fR)
626 dns_parse_fn \fBdns_parse_a4\fB;
627 struct dns_query *
628 \fBdns_submit_a4\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR,
629    dns_query_a4_fn *\fIcbck\fR, \fIdata\fR);
630 struct dns_rr_a4 *
631 \fBdns_resolve_a4\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR);
632 .fi
633 .PP
634 The \fBdns_rr_a4\fR structure holds a result of an \fBIN A\fR query,
635 which is an array of IPv4 addresses.  Callback routine for IN A queries
636 expected to be of type \fBdns_query_a4_fn\fR, which expects pointer to
637 \fBdns_rr_a4\fR structure as query result instead of raw DNS packet.
638 The \fBdns_parse_a4\fR() is used to convert raw DNS reply packet into
639 \fBdns_rr_a4\fR structure (it is used internally and may be used directly too
640 with generic query interface).  Routines \fBdns_submit_a4\fR() and
641 \fBdns_resolve_a4\fR() are used to perform A IN queries in a type-safe
642 manner.  The \fIname\fR parameter is the domain name in question, and
643 \fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
644 interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
645 DNS_NOSRCH flag will be set automatically).
646
647 .SS "IN AAAA Queries"
648 .PP
649 .nf
650 struct \fBdns_rr_a6\fR {       /* IN AAAA RRset */
651   char *\fBdnsa6_qname\fR;     /* original query name */
652   char *\fBdnsa6_cname\fR;     /* canonical name */
653   unsigned \fBdnsa6_ttl\fR;    /* Time-To-Live (TTL) value */
654   int \fBdnsa6_nrr\fR;         /* number of addresses in the set */
655   struct in6_addr \fBdnsa6_addr\fR[]; /* array of addresses */
656 };
657 typedef void
658   \fBdns_query_a6_fn\fR(\fIctx\fR, struct dns_rr_a6 *\fIresult\fR, \fIdata\fR)
659 dns_parse_fn \fBdns_parse_a6\fB;
660 struct dns_query *
661 \fBdns_submit_a6\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR,
662    dns_query_a6_fn *\fIcbck\fR, \fIdata\fR);
663 struct dns_rr_a6 *
664 \fBdns_resolve_a6\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR);
665 .fi
666 .PP
667 The \fBdns_rr_a6\fR structure holds a result of an \fBIN AAAA\fR query,
668 which is an array of IPv6 addresses.  Callback routine for IN AAAA queries
669 expected to be of type \fBdns_query_a6_fn\fR, which expects pointer to
670 \fBdns_rr_a6\fR structure as query result instead of raw DNS packet.
671 The \fBdns_parse_a6\fR() is used to convert raw DNS reply packet into
672 \fBdns_rr_a6\fR structure (it is used internally and may be used directly too
673 with generic query interface).  Routines \fBdns_submit_a6\fR() and
674 \fBdns_resolve_a6\fR() are used to perform AAAA IN queries in a type-safe
675 manner.  The \fIname\fR parameter is the domain name in question, and
676 \fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
677 interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
678 DNS_NOSRCH flag will be set automatically).
679
680 .SS "IN PTR Queries"
681 .PP
682 .nf
683 struct \fBdns_rr_ptr\fR {       /* IN PTR RRset */
684   char *\fBdnsptr_qname\fR;     /* original query name */
685   char *\fBdnsptr_cname\fR;     /* canonical name */
686   unsigned \fBdnsptr_ttl\fR;    /* Time-To-Live (TTL) value */
687   int \fBdnsptr_nrr\fR;         /* number of domain name pointers */
688   char *\fBdnsptr_ptr\fR[];     /* array of domain name pointers */
689 };
690 typedef void
691   \fBdns_query_ptr_fn\fR(\fIctx\fR, struct dns_rr_ptr *\fIresult\fR, \fIdata\fR)
692 dns_parse_fn \fBdns_parse_ptr\fB;
693 struct dns_query *
694 \fBdns_submit_a4ptr\fB(\fIctx\fR, const struct in_addr *\fBaddr\fR,
695    dns_query_ptr_fn *\fIcbck\fR, \fIdata\fR);
696 struct dns_rr_ptr *
697 \fBdns_resolve_a4ptr\fB(\fIctx\fR, const struct in_addr *\fBaddr\fR);
698 struct dns_query *
699 \fBdns_submit_a6ptr\fB(\fIctx\fR, const struct in6_addr *\fBaddr\fR,
700    dns_query_ptr_fn *\fIcbck\fR, \fIdata\fR);
701 struct dns_rr_ptr *
702 \fBdns_resolve_a6ptr\fB(\fIctx\fR, const struct in6_addr *\fBaddr\fR);
703 .fi
704 .PP
705 The \fBdns_rr_ptr\fR structure holds a result of an IN PTR query, which
706 is an array of domain name pointers for a given IPv4 or IPv6 address.
707 Callback routine for IN PTR queries expected to be of type
708 \fBdns_query_ptr_fn\fR, which expects pointer to \fBdns_rr_ptr\fR
709 structure as query result instead of raw DNS packet.  The \fBdns_parse_ptr\fR()
710 is used to convert raw DNS reply packet into \fBdns_rr_ptr\fR structure
711 (it is used internally and may be used directly too with generic query
712 interface).  Routines \fBdns_submit_a4ptr\fR() and \fBdns_resolve_a4ptr\fR()
713 are used to perform IN PTR queries for IPv4 addresses in a type-safe
714 manner. Routines \fBdns_submit_a6ptr\fR() and \fBdns_resolve_a6ptr\fR()
715 are used to perform IN PTR queries for IPv6 addresses.
716
717 .SS "IN MX Queries"
718 .PP
719 .nf
720 struct \fBdns_mx\fR {          /* single MX record */
721   int \fBpriority\fR;          /* priority value of this MX */
722   char *\fBname\fR;            /* domain name of this MX */
723 };
724 struct \fBdns_rr_mx\fR {       /* IN MX RRset */
725   char *\fBdnsmx_qname\fR;     /* original query name */
726   char *\fBdnsmx_cname\fR;     /* canonical name */
727   unsigned \fBdnsmx_ttl\fR;    /* Time-To-Live (TTL) value */
728   int \fBdnsmx_nrr\fR;         /* number of mail exchangers in the set */
729   struct dns_mx \fBdnsmx_mx\fR[]; /* array of mail exchangers */
730 };
731 typedef void
732   \fBdns_query_mx_fn\fR(\fIctx\fR, struct dns_rr_mx *\fIresult\fR, \fIdata\fR)
733 dns_parse_fn \fBdns_parse_mx\fB;
734 struct dns_query *
735 \fBdns_submit_mx\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR,
736    dns_query_mx_fn *\fIcbck\fR, \fIdata\fR);
737 struct dns_rr_mx *
738 \fBdns_resolve_mx\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR);
739 .fi
740 .PP
741 The \fBdns_rr_mx\fR structure holds a result of an IN MX query, which
742 is an array of mail exchangers for a given domain.  Callback routine for IN MX
743 queries expected to be of type \fBdns_query_mx_fn\fR, which expects pointer to
744 \fBdns_rr_mx\fR structure as query result instead of raw DNS packet.
745 The \fBdns_parse_mx\fR() is used to convert raw DNS reply packet into
746 \fBdns_rr_mx\fR structure (it is used internally and may be used directly too
747 with generic query interface).  Routines \fBdns_submit_mx\fR() and
748 \fBdns_resolve_mx\fR() are used to perform IN MX queries in a type-safe
749 manner.  The \fIname\fR parameter is the domain name in question, and
750 \fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
751 interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
752 DNS_NOSRCH flag will be set automatically).
753
754 .SS "TXT Queries"
755 .PP
756 .nf
757 struct \fBdns_txt\fR {          /* single TXT record */
758   int \fBlen\fR;                /* length of the text */
759   unsigned char *\fBtxt\fR;     /* pointer to the text */
760 };
761 struct \fBdns_rr_txt\fR {       /* TXT RRset */
762   char *\fBdnstxt_qname\fR;     /* original query name */
763   char *\fBdnstxt_cname\fR;     /* canonical name */
764   unsigned \fBdnstxt_ttl\fR;    /* Time-To-Live (TTL) value */
765   int \fBdnstxt_nrr\fR;         /* number of text records in the set */
766   struct dns_txt \fBdnstxt_txt\fR[]; /* array of TXT records */
767 };
768 typedef void
769   \fBdns_query_txt_fn\fR(\fIctx\fR, struct dns_rr_txt *\fIresult\fR, \fIdata\fR)
770 dns_parse_fn \fBdns_parse_txt\fB;
771 struct dns_query *
772 \fBdns_submit_txt\fB(\fIctx\fR, const char *\fIname\fR, enum dns_class \fIqcls\fR,
773    int \fIflags\fR, dns_query_txt_fn *\fIcbck\fR, \fIdata\fR);
774 struct dns_rr_txt *
775 \fBdns_resolve_txt\fB(\fIctx\fR, const char *\fIname\fR,
776              enum dns_class \fIqcls\fR, int \fIflags\fR);
777 .fi
778 .PP
779 The \fBdns_rr_txt\fR structure holds a result of a TXT query, which is an
780 array of text records for a given domain name.  Callback routine for TXT
781 queries expected to be of type \fBdns_query_txt_fn\fR, which expects pointer
782 to \fBdns_rr_txt\fR structure as query result instead of raw DNS packet.
783 The \fBdns_parse_txt\fR() is used to convert raw DNS reply packet into
784 \fBdns_rr_txt\fR structure (it is used internally and may be used directly too
785 with generic query interface).  Routines \fBdns_submit_txt\fR() and
786 \fBdns_resolve_txt\fR() are used to perform IN MX queries in a type-safe
787 manner.  The \fIname\fR parameter is the domain name in question, and
788 \fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
789 interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
790 DNS_NOSRCH flag will be set automatically).  Note that each TXT string
791 is represented by \fBstruct\ dns_txt\fR, while zero-terminated (and the
792 len field of the structure does not include the terminator), may contain
793 embedded null characters -- content of TXT records is not interpreted
794 by the library in any way.
795
796 .SS "SRV Queries"
797 .PP
798 .nf
799 struct \fBdns_srv\fR {          /* single SRV record */
800   int \fBpriority\fR;           /* priority of the record */
801   int \fBweight\fR;             /* weight of the record */
802   int \fBport\fR;               /* the port number to connect to */
803   char *\fBname\fR;             /* target host name */
804 };
805 struct \fBdns_rr_srv\fR {       /* SRV RRset */
806   char *\fBdnssrv_qname\fR;     /* original query name */
807   char *\fBdnssrv_cname\fR;     /* canonical name */
808   unsigned \fBdnssrv_ttl\fR;    /* Time-To-Live (TTL) value */
809   int \fBdnssrv_nrr\fR;         /* number of text records in the set */
810   struct dns_srv \fBdnssrv_srv\fR[]; /* array of SRV records */
811 };
812 typedef void
813   \fBdns_query_srv_fn\fR(\fIctx\fR, struct dns_rr_srv *\fIresult\fR, \fIdata\fR)
814 dns_parse_fn \fBdns_parse_srv\fB;
815 struct dns_query *
816 \fBdns_submit_srv\fB(\fIctx\fR, const char *\fIname\fR, const char *\fIservice\fR, const char *\fIprotocol\fR,
817    int \fIflags\fR, dns_query_txt_fn *\fIcbck\fR, \fIdata\fR);
818 struct dns_rr_srv *
819 \fBdns_resolve_srv\fB(\fIctx\fR, const char *\fIname\fR, const char *\fIservice\fR, const char *\fIprotocol\fR,
820              int \fIflags\fR);
821 .fi
822 .PP
823 The \fBdns_rr_srv\fR structure holds a result of an IN SRV (rfc2782) query,
824 which is an array of servers (together with port numbers) which are performing
825 operations for a given \fIservice\fR using given \fIprotocol\fR on a target
826 domain \fIname\fR.  Callback routine for IN SRV queries expected to be of type
827 \fBdns_query_srv_fn\fR, which expects pointer to \fBdns_rr_srv\fR structure as
828 query result instead of raw DNS packet.  The \fBdns_parse_srv\fR() is used to
829 convert raw DNS reply packet into \fBdns_rr_srv\fR structure (it is used
830 internally and may be used directly too with generic query interface).
831 Routines \fBdns_submit_srv\fR() and \fBdns_resolve_srv\fR() are used to
832 perform IN SRV queries in a type-safe manner.  The \fIname\fR parameter
833 is the domain name in question, \fIservice\fR and \fRprotocl\fR specifies the
834 service and the protocol in question (the library will construct query DN
835 according to rfc2782 rules) and may be NULL (in this case the library
836 assumes \fIname\fR parameter holds the complete SRV query), and
837 \fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
838 interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
839 DNS_NOSRCH flag will be set automatically).
840
841 .SS "NAPTR Queries"
842 .PP
843 .nf
844 struct \fBdns_naptr\fR {        /* single NAPTR record */
845   int \fBorder\fR;              /* record order */
846   int \fBpreference\fR;         /* preference of this record */
847   char *\fBflags\fR;            /* application-specific flags */
848   char *\fBservices\fR;         /* service parameters */
849   char *\fBregexp\fR;           /* substitutional regular expression */
850   char *\fBreplacement\fR;      /* replacement string */
851 };
852 struct \fBdns_rr_naptr\fR {     /* NAPTR RRset */
853   char *\fBdnsnaptr_qname\fR;   /* original query name */
854   char *\fBdnsnaptr_cname\fR;   /* canonical name */
855   unsigned \fBdnsnaptr_ttl\fR;  /* Time-To-Live (TTL) value */
856   int \fBdnsnaptr_nrr\fR;       /* number of text records in the set */
857   struct dns_naptr \fBdnsnaptr_naptr\fR[]; /* array of NAPTR records */
858 };
859 typedef void
860   \fBdns_query_naptr_fn\fR(\fIctx\fR, struct dns_rr_naptr *\fIresult\fR, \fIdata\fR)
861 dns_parse_fn \fBdns_parse_naptr\fB;
862 struct dns_query *
863 \fBdns_submit_naptr\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR,
864    dns_query_txt_fn *\fIcbck\fR, \fIdata\fR);
865 struct dns_rr_naptr *
866 \fBdns_resolve_naptr\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR);
867 .fi
868 .PP
869 The \fBdns_rr_naptr\fR structure holds a result of an IN NAPTR (rfc3403) query.
870 Callback routine for IN NAPTR queries expected to be of type
871 \fBdns_query_naptr_fn\fR, expects pointer to \fBdns_rr_naptr\fR
872 structure as query result instead of raw DNS packet.
873 The \fBdns_parse_naptr\fR() is used to convert raw DNS reply packet into
874 \fBdns_rr_naptr\fR structure (it is used
875 internally and may be used directly too with generic query interface).
876 Routines \fBdns_submit_naptr\fR() and \fBdns_resolve_naptr\fR() are used to
877 perform IN NAPTR queries in a type-safe manner.  The \fIname\fR parameter
878 is the domain name in question, and \fIflags\fR is query flags bitmask,
879 with one bit, DNS_NOSRCH, of practical interest (if the \fIname\fR is
880 absolute, that is, it ends up with a dot, DNS_NOSRCH flag will be set
881 automatically).
882
883 .SS "DNSBL Interface"
884 .PP
885 A DNS-based blocklists, or a DNSBLs, are in wide use nowadays, especially
886 to protect mailservers from spammers.  The library provides DNSBL interface,
887 a set of routines to perform queries against DNSBLs.  Routines accepts an
888 IP address (IPv4 and IPv6 are both supported) and a base DNSBL zone as
889 query parameters, and returns either \fBdns_rr_a4\fR or \fBdns_rr_txt\fR
890 structure.  Note that IPv6 interface return IPv4 RRset.
891 .PP
892 .nf
893 struct dns_query *
894 \fBdns_submit_a4dnsbl\fR(\fIctx\fR,
895   const struct in_addr *\fIaddr\fR, const char *\fIdnsbl\fR,
896   dns_query_a4_fn *\fIcbck\fR, void *\fIdata\fR);
897 struct dns_query *
898 \fBdns_submit_a4dnsbl_txt\fR(\fIctx\fR,
899   const struct in_addr *\fIaddr\fR, const char *\fIdnsbl\fR,
900   dns_query_txt_fn *\fIcbck\fR, void *\fIdata\fR);
901 struct dns_query *
902 \fBdns_submit_a6dnsbl\fR(\fIctx\fR,
903   const struct in6_addr *\fIaddr\fR, const char *\fIdnsbl\fR,
904   dns_query_a4_fn *\fIcbck\fR, void *\fIdata\fR);
905 struct dns_query *
906 \fBdns_submit_a6dnsbl_txt\fR(\fIctx\fR,
907   const struct in6_addr *\fIaddr\fR, const char *\fIdnsbl\fR,
908   dns_query_txt_fn *\fIcbck\fR, void *\fIdata\fR);
909 struct dns_rr_a4 *\fBdns_resolve_a4dnsbl\fR(\fIctx\fR,
910   const struct in_addr *\fIaddr\fR, const char *\fIdnsbl\fR)
911 struct dns_rr_txt *\fBdns_resolve_a4dnsbl_txt\fR(\fIctx\fR,
912   const struct in_addr *\fIaddr\fR, const char *\fIdnsbl\fR)
913 struct dns_rr_a4 *\fBdns_resolve_a6dnsbl\fR(\fIctx\fR,
914   const struct in6_addr *\fIaddr\fR, const char *\fIdnsbl\fR)
915 struct dns_rr_txt *\fBdns_resolve_a6dnsbl_txt\fR(\fIctx\fR,
916   const struct in6_addr *\fIaddr\fR, const char *\fIdnsbl\fR)
917 .fi
918 Perform (submit or resolve) a DNSBL query for the given \fIdnsbl\fR
919 domain and an IP \fIaddr\fR in question, requesting either A or TXT
920 records.
921
922 .SS "RHSBL Interface"
923 .PP
924 RHSBL is similar to DNSBL, but instead of an IP address, the
925 parameter is a domain name.
926 .PP
927 .nf
928 struct dns_query *
929 \fBdns_submit_rhsbl\fR(\fIctx\fR, const char *\fIname\fR, const char *\fIrhsbl\fR,
930   dns_query_a4_fn *\fIcbck\fR, void *\fIdata\fR);
931 struct dns_query *
932 \fBdns_submit_rhsbl_txt\fR(\fIctx\fR, const char *\fIname\fR, const char *\fIrhsbl\fR,
933   dns_query_txt_fn *\fIcbck\fR, void *\fIdata\fR);
934 struct dns_rr_a4 *
935 \fBdns_resolve_rhsbl\fR(\fIctx\fR, const char *\fIname\fR, const char *\fIrhsbl\fR);
936 struct dns_rr_txt *
937 \fBdns_resolve_rhsbl_txt\fR(\fIctx\fR, const char *\fIname\fR, const char *\fIrhsbl\fR);
938 .fi
939 Perform (submit or resolve) a RHSBL query for the given \fIrhsbl\fR
940 domain and \fIname\fR in question, requesting either A or TXT records.
941
942
943 .SH "LOW-LEVEL INTERFACE"
944
945 .SS "Domain Names (DNs)"
946
947 .PP
948 A DN is a series of domain name labels each starts with length byte,
949 followed by empty label (label with zero length).  The following
950 routines to work with DNs are provided.
951
952 .PP
953 .nf
954 unsigned \fBdns_dnlen\fR(const unsigned char *\fIdn\fR)
955 .fi
956 .RS
957 return length of the domain name \fIdn\fR, including the terminating label.
958 .RE
959
960 .PP
961 .nf
962 unsigned \fBdns_dnlabels\fR(const unsigned char *\fIdn\fR)
963 .fi
964 .RS
965 return number of non-zero labels in domain name \fIdn\fR.
966 .RE
967
968 .PP
969 .nf
970 unsigned \fBdns_dnequal\fR(\fIdn1\fR, \fIdn2\fR)
971   const unsigned char *\fIdn1\fR, *\fIdn2\fR;
972 .fi
973 .RS
974 test whenever the two domain names, \fIdn1\fR and \fIdn2\fR, are
975 equal (case-insensitive).  Return domain name length if equal
976 or 0 if not.
977 .RE
978
979 .PP
980 .nf
981 unsigned \fBdns_dntodn\fR(\fIsdn\fR, \fIddn\fR, \fIdnsiz\fR)
982   const unsigned char *\fIsdn\fR;
983   unsigned char *\fIddn\fR;
984   unsigned \fIdnsiz\fR;
985 .fi
986 .RS
987 copies the source domain name \fIsdn\fR to destination buffer \fIddn\fR
988 of size \fIdnsiz\fR.  Return domain name length or 0 if \fIddn\fR is
989 too small.
990 .RE
991
992 .PP
993 .nf
994 int \fBdns_ptodn\fR(\fIname\fR, \fInamelen\fR, \fIdn\fR, \fIdnsiz\fR, \fIisabs\fR)
995 int \fBdns_sptodn\fR(\fIname\fR, \fIdn\fR, \fIdnsiz\fR)
996   const char *\fIname\fR; unsigned \fInamelen\fR;
997   unsigned char *\fIdn\fR; unsigned \fIdnsiz\fR;
998   int *\fIisabs\fR;
999 .fi
1000 .RS
1001 convert asciiz name \fIname\fR of length \fInamelen\fR to DN format,
1002 placing result into buffer \fIdn\fR of size \fIdnsiz\fR.  Return
1003 length of the DN if successeful, 0 if the \fIdn\fR buffer supplied is
1004 too small, or negative value if \fIname\fR is invalid.  If \fIisabs\fR
1005 is non-NULL and conversion was successeful, *\fIisabs\fR will be set to
1006 either 1 or 0 depending whenever \fIname\fR was absolute (i.e. ending with
1007 a dot) or not.  Name length, \fInamelength\fR, may be zero, in which case
1008 strlen(\fIname\fR) will be used.  Second form, \fBdns_sptodn\fR(), is a
1009 simplified form of \fBdns_ptodn\fR(), equivalent to
1010 .br
1011 .nf
1012 \fBdns_ptodn\fR(\fIname\fR, 0, \fIdn\fR, \fIdnlen\fR, 0).
1013 .fi
1014 .RE
1015
1016 .PP
1017 .nf
1018 extern const unsigned char \fBdns_inaddr_arpa_dn\fR[]
1019 int \fBdns_a4todn\fR(const struct in_addr *\fIaddr\fR, const unsigned char *\fItdn\fR,
1020       unsigned char *\fIdn\fR, unsigned \fIdnsiz\fR)
1021 int \fBdns_a4ptodn\fR(const struct in_addr *\fIaddr\fR, const char *\fItname\fR,
1022       unsigned char *\fIdn\fR, unsigned \fIdnsiz\fR)
1023 extern const unsigned char \fBdns_ip6_arpa_dn\fR[]
1024 int \fBdns_a6todn\fR(const struct in6_addr *\fIaddr\fR, const unsigned char *\fItdn\fR,
1025       unsigned char *\fIdn\fR, unsigned \fIdnsiz\fR)
1026 int \fBdns_a6ptodn\fR(const struct in6_addr *\fIaddr\fR, const char *\fItname\fR,
1027       unsigned char *\fIdn\fR, unsigned \fIdnsiz\fR)
1028 .fi
1029 .RS
1030 several variants of routines to convert IPv4 and IPv6 address \fIaddr\fR
1031 into reverseDNS-like domain name in DN format, storing result in \fIdn\fR
1032 of size \fIdnsiz\fR.  \fItdn\fR (or \fItname\fR) is the base zone name,
1033 like in-addr.arpa for IPv4 or in6.arpa for IPv6.  If \fItdn\fR (or \fItname\fR)
1034 is NULL, \fBdns_inaddr_arpa_dn\fR (or \fBdns_ip6_arpa_dn\fR) will be used.
1035 The routines may be used to construct a DN for a DNSBL lookup for example.
1036 All routines return length of the resulting DN on success, -1 if resulting
1037 DN is invalid, or 0 if the \fIdn\fR buffer (\fIdnsiz\fR) is too small.
1038 To hold standard rDNS DN, a buffer of size \fBDNS_A4RSIZE\fR (30 bytes) for
1039 IPv4 address, or \fBDNS_A6RSIZE\fR (74 bytes) for IPv6 address, is sufficient.
1040 .RE
1041
1042 .PP
1043 .nf
1044 int \fBdns_dntop\fR(\fIdn\fR, \fIname\fR, \fInamesiz\fR)
1045    const unsigned char *\fIdn\fR;
1046    const char *\fIname\fR; unsigned \fInamesiz\fR;
1047 .fi
1048 .RS
1049 convert domain name \fIdn\fR in DN format to asciiz string, placing result
1050 into \fIname\fR buffer of size \fInamesiz\fR.  Maximum length of asciiz
1051 representation of domain name is \fBDNS_MAXNAME\fR (1024) bytes.  Root
1052 domain is represented as empty string.  Return length of the resulting name
1053 (including terminating character, i.e. strlen(name)+1) on success, 0 if the
1054 \fIname\fR buffer is too small, or negative value if \fIdn\fR is invalid
1055 (last case should never happen since all routines in this library which
1056 produce domain names ensure the DNs generated are valid).
1057 .RE
1058
1059 .PP
1060 .nf
1061 const char *\fBdns_dntosp\fR(const unsigned char *\fIdn\fR)
1062 .fi
1063 .RS
1064 convert domain name \fIdn\fR in DN format to asciiz string using static
1065 buffer.  Return the resulting asciiz string on success or NULL on failure.
1066 Note since this routine uses static buffer, it is not thread-safe.
1067 .RE
1068
1069 .PP
1070 .nf
1071 unsigned \fBdns_dntop_size\fR(const unsigned char *\fIdn\fR)
1072 .fi
1073 .RS
1074 return the buffer size needed to convert the \fIdn\fR domain name
1075 in DN format to asciiz string, for \fBdns_dntop\fR().  The routine
1076 return either the size of buffer required, including the trailing
1077 zero byte, or 0 if \fIdn\fR is invalid.
1078 .RE
1079
1080 .SS "Working with DNS Packets"
1081
1082 .PP
1083 The following routines are provided to encode and decode DNS on-wire
1084 packets.  This is low-level interface.
1085
1086 .PP
1087 DNS response codes (returned by \fBdns_rcode\fR() routine) are
1088 defined as constants prefixed with \fBDNS_R_\fR.  See udns.h
1089 header file for the complete list.  In particular, constants
1090 \fBDNS_R_NOERROR\fR (0), \fBDNS_R_SERVFAIL\fR, \fBDNS_R_NXDOMAIN\fR
1091 may be of interest to an application.
1092
1093 .PP
1094 .nf
1095 unsigned \fBdns_get16\fR(const unsigned char *\fIp\fR)
1096 unsigned \fBdns_get32\fR(const unsigned char *\fIp\fR)
1097 .fi
1098 .RS
1099 helper routines, convert 16-bit or 32-bit integer in on-wire
1100 format pointed to by \fIp\fR to unsigned.
1101 .RE
1102
1103 .PP
1104 .nf
1105 unsigned char *\fBdns_put16\fR(unsigned char *\fId\fR, unsigned \fIn\fR)
1106 unsigned char *\fBdns_put32\fR(unsigned char *\fId\fR, unsigned \fIn\fR)
1107 .fi
1108 .RS
1109 helper routine, convert unsigned 16-bit or 32-bit integer \fIn\fR to
1110 on-wire format to buffer pointed to by \fId\fR, return \fId\fR+2 or
1111 \fId\fR+4.
1112 .RE
1113
1114 .PP
1115 .nf
1116 \fBDNS_HSIZE\fR (12)
1117 .fi
1118 .RS
1119 defines size of DNS header.  Data section
1120 in the DNS packet immediately follows the header.  In the header,
1121 there are query identifier (id), various flags and codes,
1122 and number of resource records in various data sections.
1123 See udns.h header file for complete list of DNS header definitions.
1124 .RE
1125
1126 .PP
1127 .nf
1128 unsigned \fBdns_qid\fR(const unsigned char *\fIpkt\fR)
1129 int \fBdns_rd\fR(const unsigned char *\fIpkt\fR)
1130 int \fBdns_tc\fR(const unsigned char *\fIpkt\fR)
1131 int \fBdns_aa\fR(const unsigned char *\fIpkt\fR)
1132 int \fBdns_qr\fR(const unsigned char *\fIpkt\fR)
1133 int \fBdns_ra\fR(const unsigned char *\fIpkt\fR)
1134 unsigned \fBdns_opcode\fR(const unsigned char *\fIpkt\fR)
1135 unsigned \fBdns_rcode\fR(const unsigned char *\fIpkt\fR)
1136 unsigned \fBdns_numqd\fR(const unsigned char *\fIpkt\fR)
1137 unsigned \fBdns_numan\fR(const unsigned char *\fIpkt\fR)
1138 unsigned \fBdns_numns\fR(const unsigned char *\fIpkt\fR)
1139 unsigned \fBdns_numar\fR(const unsigned char *\fIpkt\fR)
1140 const unsigned char *\fBdns_payload\fR(const unsigned char *\fIpkt\fR)
1141 .fi
1142 .RS
1143 return various parts from the DNS packet header \fIpkt\fR:
1144 query identifier (qid),
1145 recursion desired (rd) flag,
1146 truncation occured (tc) flag,
1147 authoritative answer (aa) flag,
1148 query response (qr) flag,
1149 recursion available (ra) flag,
1150 operation code (opcode),
1151 result code (rcode),
1152 number of entries in question section (numqd),
1153 number of answers (numan),
1154 number of authority records (numns),
1155 number of additional records (numar),
1156 and the pointer to the packet data (payload).
1157 .RE
1158
1159 .PP
1160 .nf
1161 int \fBdns_getdn\fR(\fIpkt\fR, \fIcurp\fR, \fIpkte\fR, \fIdn\fR, \fIdnsiz\fR)
1162 const unsigned char *\fBdns_skipdn\fR(\fIcur\fR, \fIpkte\fR)
1163    const unsigned char *\fIpkt\fR, *\fIpkte\fR, **\fIcurp\fR, *\fIcur\fR;
1164    unsigned char *\fIdn\fR; unsigned \fIdnsiz\fR;
1165 .fi
1166 .RS
1167 \fBdns_getdn\fR() extract DN from DNS packet \fIpkt\fR which ends before
1168 \fIpkte\fR starting at position *\fIcurp\fR into buffer pointed to by
1169 \fIdn\fR of size \fIdnsiz\fR.  Upon successeful completion, *\fIcurp\fR
1170 will point to the next byte in the packet after the extracted domain name.
1171 It return positive number (length of the DN if \fIdn\fR) upon successeful
1172 completion, negative value on error (when the packet contains invalid data),
1173 or zero if the \fIdnsiz\fR is too small (maximum length of a domain name is
1174 \fBDNS_MAXDN\fR).  \fBdns_skipdn\fR() return pointer to the next byte in
1175 DNS packet which ends up before \fIpkte\fR after a domain name which starts
1176 at the \fIcur\fP byte, or NULL if the packet is invalid.  \fBdns_skipdn\fR()
1177 is more or less equivalent to what \fBdns_getdn\fR() does, except it does not
1178 actually extract the domain name in question, and uses simpler interface.
1179 .RE
1180
1181 .PP
1182 .nf
1183 struct \fBdns_rr\fR {
1184   unsigned char \fBdnsrr_dn\fR[DNS_MAXDN]; /* the RR DN name */
1185   enum dns_class \fBdnsrr_cls\fR;          /* class of the RR */
1186   enum dns_type  \fBdnsrr_typ\fR;          /* type of the RR */
1187   unsigned \fBdnsrr_ttl\fR;                /* TTL value */
1188   unsigned \fBdnsrr_dsz\fR;                /* size of data in bytes */
1189   const unsigned char *\fBdnsrr_dptr\fR;   /* pointer to the first data byte */
1190   const unsigned char *\fBdnsrr_dend\fR;   /* next byte after RR */
1191 };
1192 .fi
1193 .RS
1194 The \fBdns_rr\fR structure is used to hold information about
1195 single DNS Resource Record (RR) in an easy to use form.
1196 .RE
1197
1198 .PP
1199 .nf
1200 struct \fBdns_parse\fR {
1201   const unsigned char *\fBdnsp_pkt\fR; /* pointer to the packet being parsed */
1202   const unsigned char *\fBdnsp_end\fR; /* end of the packet pointer */
1203   const unsigned char *\fBdnsp_cur\fR; /* current packet positionn */
1204   const unsigned char *\fBdnsp_ans\fR; /* pointer to the answer section */
1205   int \fBdnsp_rrl\fR;                  /* number of RRs left */
1206   int \fBdnsp_nrr\fR;                  /* number of relevant RRs seen so far */
1207   unsigned \fBdnsp_ttl\fR;             /* TTL value so far */
1208   const unsigned char *\fBdnsp_qdn\fR; /* the domain of interest or NULL */
1209   enum dns_class \fBdnsp_qcls\fR;      /* class of interest or 0 for any */
1210   enum dns_type  \fBdnsp_qtyp\fR;      /* type of interest or 0 for any */
1211   unsigned char \fBdnsp_dnbuf\fR[DNS_MAXDN]; /* domain name buffer */
1212 };
1213 .fi
1214 .RS
1215 The \fBdns_parse\fR structure is used to parse DNS reply packet.
1216 It holds information about the packet being parsed (dnsp_pkt, dnsp_end and
1217 dnsp_cur fields), number of RRs in the current section left to do, and
1218 the information about specific RR which we're looking for (dnsp_qdn,
1219 dnsp_qcls and dnsp_qtyp fields).
1220 .RE
1221
1222 .PP
1223 .nf
1224 int \fBdns_initparse\fR(struct dns_parse *\fIp\fR,
1225   const unsigned char *\fIqdn\fR,
1226   const unsigned char *\fIpkt\fR,
1227   const unsigned char *\fIcur\fR,
1228   const unsigned char *\fIend\fR)
1229 .fi
1230 .RS
1231 initializes the RR parsing structure \fIp\fR.  Arguments \fIpkt\fR, \fIcur\fR
1232 and \fIend\fR should describe the received packet: \fIpkt\fR is the start of
1233 the packet, \fIend\fR points to the next byte after the end of the packet,
1234 and \fIcur\fR points past the query DN in query section (to query class+type
1235 information).  And \fIqdn\fR points to the query DN.  This is the arguments
1236 passed to \fBdns_parse_fn\fR() routine. \fBdns_initparse\fR() initializes
1237 \fBdnsp_pkt\fR, \fBdnsp_end\fR and \fBdnsp_qdn\fR fields to the corresponding
1238 arguments, extracts and initializes \fBdnsp_qcls\fR and \fBdnsp_qtyp\fR
1239 fields to the values found at \fIcur\fR pointer, initializes
1240 \fBdnsp_cur\fR and \fBdnsp_ans\fR fields to be \fIcur\fR+4 (to the start of
1241 answer section), and initializes \fBdnsp_rrl\fR field to be number of entries
1242 in answer section. \fBdnsp_ttl\fR will be set to max TTL value, 0xffffffff,
1243 and \fBdnsp_nrr\fR to 0.
1244 .RE
1245
1246 .PP
1247 .nf
1248 int \fBdns_nextrr\fR(struct dns_parse *\fIp\fR, struct dns_rr *\fIrr\fR);
1249 .fi
1250 .RS
1251 searches for next RR in the packet based on the criteria provided in
1252 the \fIp\fR structure, filling in the \fIrr\fR structure and
1253 advancing \fIp\fR->\fBdnsp_cur\fR to the next RR in the packet.
1254 RR selection is based on dnsp_qdn, dnsp_qcls and dnsp_qtyp fields in
1255 the dns_parse structure.  Any (or all) of the 3 fields may be 0,
1256 which means any actual value from the packet is acceptable.  In case
1257 the field isn't 0 (or NULL for dnsp_qdn), only RRs with corresponding
1258 characteristics are acceptable.  Additionally, when dnsp_qdn is non-NULL,
1259 \fBdns_nextrr\fR() performs automatic CNAME expansion.
1260 Routine will return positive value on success, 0 in case it reached the end
1261 of current section in the packet (\fIp\fR->\fBdnsp_rrl\fR is zero), or
1262 negative value if next RR can not be decoded (packet format is invalid).
1263 The routine updates \fIp\fR->\fBdnsp_qdn\fR automatically when this
1264 field is non-NULL and it encounters appropriate CNAME RRs (saving CNAME
1265 target in \fIp\fR->\fBdnsp_dnbuf\fR), so after end of the process,
1266 \fIp\fR->\fBdnsp_qdn\fR will point to canonical name of the domain
1267 in question.  The routine updates \fIp\fR->\fBdnsp_ttl\fR value to
1268 be the minimum TTL of all RRs found.
1269 .RE
1270
1271 .PP
1272 .nf
1273 void \fBdns_rewind\fR(struct dns_parse *\fIp\fR, const unsigned char *\fIqdn\fR)
1274 .fi
1275 .RS
1276 this routine "rewinds" the packet parse state structure to be at the
1277 same state as after a call to \fBdns_initparse\fR(), i.e. reposition
1278 the parse structure \fIp\fR to the start of answer section and
1279 initialize \fIp\fR->\fBdnsp_rrl\fR to the number of entries in
1280 answer section.
1281 .RE
1282
1283 .PP
1284 .nf
1285 int \fBdns_stdrr_size\fR(const struct dns_parse *\fIp\fR);
1286 .fi
1287 .RS
1288 return size to hold standard RRset structure information, as shown
1289 in \fBdns_rr_null\fR structure (for the query and canonical
1290 names).  Used to calculate amount of memory to allocate for common
1291 part of type-specific RR structures in parsing routines.
1292 .RE
1293
1294 .PP
1295 .nf
1296 void *\fBdns_stdrr_finish\fR(struct dns_rr_null *\fIret\fR, char *\fIcp\fR,
1297   const struct dns_parse *\fIp\fR);
1298 .fi
1299 .RS
1300 initializes standard RRset fields in \fIret\fR structure using buffer
1301 pointed to by \fIcp\fR, which should have at least as many bytes
1302 as \fBdns_stdrr_size\fR(\fIp\fR) returned.  Used to finalize common
1303 part of type-specific RR structures in parsing routines.
1304 .RE
1305
1306 .PP
1307 See library source for usage examples of all the above low-level routines,
1308 especially source of the parsing routines.
1309
1310 .SS "Auxilary Routines"
1311
1312 .PP
1313 .nf
1314 int \fBdns_pton\fR(int \fIaf\fR, const char *\fIsrc\fR, void *\fIdst\fR);
1315 .fi
1316 .RS
1317 privides functionality similar to standard \fBinet_pton\fR() routine,
1318 to convert printable representation of an IP address of family \fIaf\fR
1319 (either \fBAF_INET\fR or \fBAF_INET6\fR) pointed to by \fIsrc\fR into
1320 binary form suitable for socket addresses and transmission over network,
1321 in buffer pointed to by \fIdst\fR.  The destination buffer should be
1322 of size 4 for \fBAF_INET\fR family or 16 for \fBAF_INET6\fR.
1323 The return value is positive on success, 0 if \fIsrc\fR is not a valid text
1324 representation of an address of family \fIaf\fR, or negative if the
1325 given address family is not supported.
1326 .RE
1327
1328 .PP
1329 .nf
1330 const char *\fBdns_ntop\fR(int \fIaf\fR, const void *\fIsrc\fR,
1331     char *\fIdst\fR, int \fIdstsize\fR)
1332 .fi
1333 .RS
1334 privides functionality similar to standard \fBinet_ntop\fR() routine,
1335 to convert binary representation of an IP address of family \fIaf\fR
1336 (either \fBAF_INET\fR or \fBAF_INET6\fR) pointed to by \fIsrc\fR
1337 (either 4 or 16 bytes) into printable form in buffer in buffer pointed
1338 to by \fIdst\fR of size \fIdstsize\fR.  The destination buffer should be
1339 at least of size 16 bytes for \fBAF_INET\fR family or 46 bytes for
1340 \fBAF_INET6\fR.  The return value is either \fIdst\fR, or NULL pointer
1341 if \fIdstsize\fR is too small to hold this address or if the given
1342 address family is not supported.
1343 .RE
1344
1345 .SH AUTHOR
1346 .PP
1347 The \fBudns\fR library has been written by Michael Tokarev, mjt@corpit.ru.
1348
1349 .SH VERSION
1350 .PP
1351 This manual page corresponds to udns version 0.0.9, released Jan-2007.
Note: See TracBrowser for help on using the browser.