/contrib/ntp/arlib/arlib.3

  1.TH arlib 3
  2.SH NAME
  3ar_answer, ar_close, ar_delete, ar_gethostbyname, ar_gethostbyaddr,
  4ar_init, ar_open, ar_timeout - Asynchronous DNS library routines
  5.SH SYNOPSIS
  6.nf
  7.B #include "arlib.h"
  8
  9.B struct hostent *ar_answer(dataptr, size)
 10.B char *dataptr;
 11.B int size;
 12
 13.B void ar_close();
 14
 15.B int ar_delete(dataptr, size)
 16.B char *dataptr;
 17.B int size;
 18
 19.B int ar_gethostbyname(name, dataptr, size)
 20.B char *name;
 21.B char *dataptr;
 22.B int size;
 23
 24.B int ar_gethostbyaddr(name, dataptr, size)
 25.B char *name;
 26.B char *dataptr;
 27.B int size;
 28
 29.B int ar_init(flags)
 30.B int flags;
 31
 32.B int ar_open();
 33
 34.B long ar_timeout(time, dataptr, size)
 35.B long time;
 36.B char *dataptr;
 37.B int size;
 38.fi
 39.SH DESCRIPTION
 40
 41.PP
 42   This small library of DNS routines is intended to provide an
 43asynchronous interface to performing hostname and IP number lookups.
 44Only lookups of Internet domain are handled as yet.  To use this
 45set of routines properly, the presence of the
 46.B "BIND 4.8"
 47resolve
 48libraries is required (or any library derived from it).
 49.PP
 50   This library should be used in conjunction with
 51.B select(2)
 52to wait for
 53the name server's reply to arrive or the lookup to timeout.
 54.PP
 55   To open a fd for talking to the name server, either
 56.B ar_open()
 57or
 58ar_init()
 59must be used.
 60.B  ar_open()
 61 will open either a datagram socket
 62or a virtual circuit with the name server, depending on the flags
 63set in the _res structure (see
 64.B resolv(5)
 65).  In both cases, if the socket
 66
 67> i
 68.B  ar_init()
 69is
 70used to both open the socket (as in
 71.B ar_open()
 72) and initialize the
 73queues used by this library.  The values recognized as parameters to
 74.B ar_init()
 75are:
 76
 77.RS
 78#define ARES_INITLIST   1
 79.RE
 80.RS
 81#define ARES_CALLINIT   2
 82.RE
 83.RS
 84#define ARES_INITSOCK   4
 85.RE
 86.RS
 87#define ARES_INITDEBG   8
 88.RE
 89
 90   ARES_INITLIST initializes the list of queries waiting for replies.
 91ARES_CALLINIT is a flag which when set causes
 92.B res_init()
 93to be called.
 94ARES_INITSOCK will close the current socket if it is open and call
 95.B ar_open()
 96to open a new one, returning the fd for that socket.
 97ARES_INITDEBG sets the RES_DEBUG flag of the
 98.B _res
 99structure.
100ARES_INITCACH is as yet, unused and is for future use where the library
101keeps its own cache of replies.
102
103   To send a query about either a hostname or an IP number,
104.B ar_gethostbyname()
105and
106.B ar_gethostbyaddr()
107must be used.  Each takes
108either a pointer to the hostname or the IP number respectively for use
109when making the query.  In addition to this, both (optionally) can be
110passed a pointer to data, dataptr, with the size also passed which can
111be used for identifying individual queries.  A copy of the area pointed
112to is made if dataptr is non NULL and size is non zero.  These functions
113will always return NULL unless the answer to the query is found in
114internal caches.  A new flag, RES_CHECKPTR is checked during the
115processing of answers for
116.B ar_gethostbyname()
117which will automatically
118cause a reverse lookup to be queued, causing a failure if that reply
119differs from the original.
120
121   To check for a query,
122.B ar_answer()
123is called with a pointer to an  area
124of memory which is sufficient to hold what was originally passed via
125.B ar_gethostbyname()
126or
127.B ar_gethostbyaddr()
128through dataptr.  If an answer
129is found, a pointer to the host information is returned and the data
130segment copied if dataptr is non NULL and it was originally passed.  The
131size of the copied data is the smaller of the passed size and that of
132original data stored.
133
134   To expire old queries,
135.B ar_timeout()
136is called with the 'current' time
137(or the time for which you want to do timeouts for).  If a queue entry
138is too old, it will be expired when it has exhausted all available avenues
139for lookups and the data segment for the expired query copied into
140dataptr.  The size of the copied data is the smaller of the passed size
141and that of the original stored data.  Only 1 entry is thus expired with
142each call, requiring that it be called immediately after an expiration
143to check for others.  In addition to expiring lookups,
144.B ar_timeout()
145also
146triggers resends of queries and the searching of the domain tree for the
147host, the latter works from the
148.B _res
149structure of
150.B resolv(5).
151
152   To delete entries from the queue,
153.B ar_delete()
154can be used and by
155passing the pointer and size of the data segment, all queries have their
156data segments checked (if present) for an exact match, being deleted if
157and only if there is a match.  A NULL pointer passed to ar_deleted()
158matches all queries which were called with a NULL dataptr parameter.
159The amount of data compared is the smaller of the size passed and that
160of the data stored for the queue entry being compared.
161
162   To close a socket opened by
163.B ar_open()
164,
165.B ar_close()
166should  be used so
167that it is closed and also marked closed within this library.
168
169   
170.SH DIAGNOSIS
171
172.B ar_open()
173returns -1 if a socket isn't open and could not be opened;
174otherwise returns the current fd open or the fd it opened.
175
176.B ar_init()
177returns -1 for any errors, the value returned by
178.B res_init()
179if
180.B res_init()
181was called, the return value for
182.B ar_open()
183if that was
184called or the current socket open if 0 is passed and a socket is open.
185If neither
186.B res_init()
187or
188.B ar_open()
189are called and the flags are non-zero, -2 is returned.
190 
191.B ar_gethostbyaddr()
192and
193.B ar_gethostbyname()
194will always return NULL in this version but may return a pointer to a hostent
195structure if a cache is being used and the answer is found in the cache.
196
197.B ar_answer()
198returns NULL if the answer is either not found or the
199query returned an error and another attempt at a lookup is attempted.
200If an answer was found, it returned a pointer to this structure and
201the contents of the data segment copied over.
202
203.B ar_timeout()
204returns the time when it should be called next or 0 if
205there are no queries in the queue to be checked later.  If any queries
206are expired, the data segment is copied over if dataptr is non NULL.
207
208.B ar_delete()
209returns the number of entries that were found to match
210and consequently deleted.
211
212.SH SEE ALSO
213
214gethostbyaddr(3), gethostbyname(3), resolv(5)
215
216.SH FILES
217.nf
218arlib.h
219/usr/include/resolv.h
220/usr/include/arpa/nameser.h
221/etc/resolv.conf
222
223.SH BUGS
224
225The results of a successful call to ar_answer() destroy the structure
226for any previous calls.
227
228.SH AUTHOR
229
230Darren Reed.  Email address: avalon@coombs.anu.edu.au