3
ar_answer, ar_close, ar_delete, ar_gethostbyname, ar_gethostbyaddr,
4
ar_init, ar_open, ar_timeout - Asynchronous DNS library routines
9
.B struct hostent *ar_answer(dataptr, size)
15
.B int ar_delete(dataptr, size)
19
.B int ar_gethostbyname(name, dataptr, size)
24
.B int ar_gethostbyaddr(name, dataptr, size)
34
.B long ar_timeout(time, dataptr, size)
42
This small library of DNS routines is intended to provide an
43
asynchronous interface to performing hostname and IP number lookups.
44
Only lookups of Internet domain are handled as yet. To use this
45
set of routines properly, the presence of the
48
libraries is required (or any library derived from it).
50
This library should be used in conjunction with
53
the name server's reply to arrive or the lookup to timeout.
55
To open a fd for talking to the name server, either
61
will open either a datagram socket
62
or a virtual circuit with the name server, depending on the flags
63
set in the _res structure (see
65
). In both cases, if the socket
70
used to both open the socket (as in
73
queues used by this library. The values recognized as parameters to
78
#define ARES_INITLIST 1
81
#define ARES_CALLINIT 2
84
#define ARES_INITSOCK 4
87
#define ARES_INITDEBG 8
90
ARES_INITLIST initializes the list of queries waiting for replies.
91
ARES_CALLINIT is a flag which when set causes
94
ARES_INITSOCK will close the current socket if it is open and call
96
to open a new one, returning the fd for that socket.
97
ARES_INITDEBG sets the RES_DEBUG flag of the
100
ARES_INITCACH is as yet, unused and is for future use where the library
101
keeps its own cache of replies.
103
To send a query about either a hostname or an IP number,
104
.B ar_gethostbyname()
106
.B ar_gethostbyaddr()
107
must be used. Each takes
108
either a pointer to the hostname or the IP number respectively for use
109
when making the query. In addition to this, both (optionally) can be
110
passed a pointer to data, dataptr, with the size also passed which can
111
be used for identifying individual queries. A copy of the area pointed
112
to is made if dataptr is non NULL and size is non zero. These functions
113
will always return NULL unless the answer to the query is found in
114
internal caches. A new flag, RES_CHECKPTR is checked during the
115
processing of answers for
116
.B ar_gethostbyname()
117
which will automatically
118
cause a reverse lookup to be queued, causing a failure if that reply
119
differs from the original.
121
To check for a query,
123
is called with a pointer to an area
124
of memory which is sufficient to hold what was originally passed via
125
.B ar_gethostbyname()
127
.B ar_gethostbyaddr()
128
through dataptr. If an answer
129
is found, a pointer to the host information is returned and the data
130
segment copied if dataptr is non NULL and it was originally passed. The
131
size of the copied data is the smaller of the passed size and that of
132
original data stored.
134
To expire old queries,
136
is called with the 'current' time
137
(or the time for which you want to do timeouts for). If a queue entry
138
is too old, it will be expired when it has exhausted all available avenues
139
for lookups and the data segment for the expired query copied into
140
dataptr. The size of the copied data is the smaller of the passed size
141
and that of the original stored data. Only 1 entry is thus expired with
142
each call, requiring that it be called immediately after an expiration
143
to check for others. In addition to expiring lookups,
146
triggers resends of queries and the searching of the domain tree for the
147
host, the latter works from the
152
To delete entries from the queue,
155
passing the pointer and size of the data segment, all queries have their
156
data segments checked (if present) for an exact match, being deleted if
157
and only if there is a match. A NULL pointer passed to ar_deleted()
158
matches all queries which were called with a NULL dataptr parameter.
159
The amount of data compared is the smaller of the size passed and that
160
of the data stored for the queue entry being compared.
162
To close a socket opened by
167
that it is closed and also marked closed within this library.
173
returns -1 if a socket isn't open and could not be opened;
174
otherwise returns the current fd open or the fd it opened.
177
returns -1 for any errors, the value returned by
181
was called, the return value for
184
called or the current socket open if 0 is passed and a socket is open.
189
are called and the flags are non-zero, -2 is returned.
191
.B ar_gethostbyaddr()
193
.B ar_gethostbyname()
194
will always return NULL in this version but may return a pointer to a hostent
195
structure if a cache is being used and the answer is found in the cache.
198
returns NULL if the answer is either not found or the
199
query returned an error and another attempt at a lookup is attempted.
200
If an answer was found, it returned a pointer to this structure and
201
the contents of the data segment copied over.
204
returns the time when it should be called next or 0 if
205
there are no queries in the queue to be checked later. If any queries
206
are expired, the data segment is copied over if dataptr is non NULL.
209
returns the number of entries that were found to match
210
and consequently deleted.
214
gethostbyaddr(3), gethostbyname(3), resolv(5)
219
/usr/include/resolv.h
220
/usr/include/arpa/nameser.h
225
The results of a successful call to ar_answer() destroy the structure
226
for any previous calls.
230
Darren Reed. Email address: avalon@coombs.anu.edu.au
added
removed
arlib/arlib.3
