Repository navigation
Expand file tree
/
Copy pathar.3
More file actions
344 lines (312 loc) · 8.64 KB
/
Copy pathar.3
File metadata and controls
344 lines (312 loc) · 8.64 KB
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
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
.TH libar 3
.SH NAME
.B ar_init(), ar_addquery(), ar_waitreply(), ar_cancelquery(), ar_resend(),
.B ar_recycle(), ar_shutdown()
-- asynchronous DNS resolver facility
.SH SYNOPSIS
#include
.I <ar.h>
typedef void *
.B ar_malloc_t
(void *, size_t);
typedef void
.B ar_free_t
(void *, void *);
AR_LIB
.B ar_init
(ar_malloc_t
.B mallocf,
ar_free_t
.B freef,
void *
.B memclosure,
int
.B flags
);
int
.B ar_shutdown
(AR_LIB
.B lib
);
void
.B ar_setretry
(AR_LIB
.B lib,
struct timeval *
.B new,
struct timeval *
.B old
);
void
.B ar_setmaxretry
(AR_LIB
.B lib,
int
.B new,
int *
.B old);
AR_QUERY
.B ar_addquery
(AR_LIB
.B lib,
const char *
.B query,
int
.B class,
int
.B type,
int
.B depth,
unsigned char *
.B buf,
size_t
.B buflen,
int *
.B err,
struct timeval *
.B timeout
);
int
.B ar_waitreply
(AR_LIB
.B lib,
AR_QUERY
.B query,
int *
.B len,
struct timeval *
.B timeout
);
int
.B ar_cancelquery
(AR_LIB
.B lib,
AR_QUERY
.B query
);
void
.B ar_recycle
(AR_LIB
.B lib,
AR_QUERY
.B query
);
int
.B ar_resend
(AR_LIB
.B lib,
AR_QUERY
.B query
);
char *
.B ar_strerror
(int
.B err
);
.SH DESCRIPTION
These functions are an interface to an asynchronous resolver facility.
The functions provided by
.B resolver(3)
and the
.B gethostbyxxx(3)
functions are not thread-safe since they use static storage, don't multiplex
efficiently, and don't have timeouts associated with them. This library
of functions was drafted to provide those facilities.
An application first initializes the package by calling
.B ar_init().
The optional
.I mallocf
parameter is a caller-provided memory allocation function taking a pointer
to a caller-provided opaque data structure (the
.I memclosure
parameter) and a number of bytes to allocate. If
.I mallocf
is not provided, the default system memory allocator function
.B malloc(3)
is used. The optional
.I freef
parameter specifies a matching caller-provided memory deallocator function,
taking a pointer to a caller-provided opaque data structure (the
.I memclosure
parameter) and a pointer to the memory to be released. If
.I freef
is not provided, the default system memory release function
.B free(3)
is used. The
.I flags
parameter is a bitwise OR of a set of available flags to tailor the operation
of the package. Currently the only flag is AR_FLAG_USETCP, which instructs
the package to submit its queries via a TCP connection rather than the
default, UDP. The handle returned by
.B ar_init()
is passed to later functions in order to share resources among transactions.
By default the package will not retransmit queries for which no reply
has arrived until requested to do so with
.B ar_resend().
Moreover, that function re-uses the same nameserver as the previous
attempt. Instead, the caller can use
.B ar_setretry()
to define (or retrieve) a time interval after which, if no reply has been
received, the query will be re-sent to the next nameserver in the list
of nameservers. In the TCP case, this will disconnect from the nameserver,
reconnect, and re-send all pending queries. A time of {0, 0} disables this
feature. The default is the same as whatever the local resolver uses.
To leave the current value unchanged, specify a value of NULL for
.I new.
If the current value is not of interest, specify a value of NULL for
.I old.
The
.B ar_setmaxretry()
function gets and/or sets the maximum number of times a query can be
attempted before the package will give up trying. The default is
the same as whatever the local resolver uses. To retrieve the current
value but leave it unchanged, specify a value of -1 for
.I new.
If the current value is not of interest, specify a value of NULL for
.I old.
To submit a new query to the nameserver, the application calls
.B ar_addquery().
The
.I lib
parameter is the handle returned from
.B ar_init().
The
.I query,
.I class
and
.I type
parameters specify the query that is to be performed.
.I buf
specifies where the result should be written when a reply is received, and
.I buflen
indicates how many bytes are available there.
.I err
is an optional pointer to an integer which will receive the value of
.I errno
if there is a transmission error between this package and the nameserver.
.I depth
indicates how many CNAME references will be re-queried before the package
gives up and returns whatever result is current.
Finally,
.I timeout
is an optional pointer to a timeval structure that indicates the total time
allowed for this query to resolve. If NULL, this query never times out.
To wait for a query result, the application calls
.B ar_waitreply().
.I lib
is again the library handle as returned by
.B ar_init().
.I query
is the query handle returned by
.B ar_addquery().
.I len
is a pointer to an integer which will receive the number of bytes that were
contained in the reply. It can be NULL if that information is not of
interest to the caller. This number may be larger than the value of
.I buflen
in the call to
.B ar_addquery(),
in which case there was not enough space in the provided buffer to receive
the reply and the application should resubmit with a bigger buffer.
.I timeout
specifies how long this particular call should wait for a reply before
returning. If the reply has already arrived (even if it's an NXDOMAIN
reply), this function will return immediately, otherwise it will wait until
either the requested timeout expires, or the timeout set on the
.B ar_addquery()
call expires.
When a reply has been retrieved, the query handle needs to be recycled
via a call to
.B ar_recycle().
To abort a query, use
.B ar_cancelquery().
This implicitly recycles the
.I query
handle passed to it.
To arrange to re-send a query for which a reply has not yet arrived, use
.B ar_resend().
When all queries are done and the facility is no longer desired,
a call to
.B ar_shutdown()
will close down the service and release related resources.
The function
.B ar_strerror()
is provided to handle error codes returned by the library. Positive error
codes are standard POSIX error codes and will be passed to
.I strerror(3)
while negative error codes are internal to the library and will be translated
to a human-readable form by this function.
.SH RETURN VALUES
.B ar_lib()
returns a handle to a newly-initialized instantiation of the library.
If operating in TCP mode, a TCP connection now exists to a nameserver.
NULL is returned if any of this initialization fails, with
.I errno
set to indicate the error.
.B ar_shutdown()
returns 0 on success, or an
.I errno
value on failure.
.B ar_addquery()
returns a newly-initialized
.I AR_QUERY
handle on success, or NULL on failure with
.I errno
set to indicate the error. EINVAL will be used if the query submitted
was malformed (i.e. contained invalid characters or character sequences).
.B ar_cancelquery()
returns 0 on success or 1 on error (i.e. invalid query handle specified).
.B ar_waitreply()
returns AR_STAT_SUCCESS (0) on success, indicating a reply is available for
processing; AR_STAT_NOREPLY (1) if a timeout is specified on the call but
expired, indicating no reply is available yet but there might be one later;
AR_STAT_EXPIRED (2) if the timeout specified on the call to
.B ar_addquery()
has expired; or AR_STAT_ERROR (-1) on error with
.I errno
set to indicate the error.
.B ar_resend()
returns 0 on success or -1 on error with
.I errno
set to indicate the error.
.SH NOTES
This system uses
.B pthreads
for synchronization and signalling. Applications that use another threading
mechanism may not work with this library.
If operating in TCP mode and the remote nameserver disconnects, the library
will attempt to connect to each of the nameservers published in
.I resolv.conf(4)
before giving up. Once it gives up, all pending and future calls to
.B ar_waitreply()
or
.B ar_addquery()
will fail. The only option after that is to shut down the library
and start again.
CNAME recursion is done at most
.I depth
times while evaluating the result of a query. The time specified in the
call to
.B ar_addquery()
should allow for recursion time, since that defines the total amount of
time the entire query, including recursion, is allowed to take.
The buffer provided in the call to
.B ar_addquery()
is sometimes used for temporary storage, specifically when chasing CNAME
references. If a particular CNAME recursion is too large for the buffer,
the search will be interrupted and returned as-is, and the
.I len
value returned will indicate that a lack of buffer space caused the
recursion to terminate (see above).
.B ar_strerror()
returns a pointer to a character string representing the supplied error
code.
.SH COPYRIGHT
Copyright (c) 2004, 2005, Sendmail, Inc. and its suppliers.
All rights reserved.
Copyright (c) 2009, The OpenDKIM Project. All rights reserved.
.SH SEE ALSO
gethostbyaddr(3),
gethostbyname(3),
resolv.conf(4),
resolver(3)