contrib/ntp/arlib/arlib.3

   1 .TH arlib 3
   2 .SH NAME
   3 ar_answer, ar_close, ar_delete, ar_gethostbyname, ar_gethostbyaddr,
   4 ar_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
  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
  46 .B "BIND 4.8"
  47 resolve
  48 libraries is required (or any library derived from it).
  49 .PP
  50    This library should be used in conjunction with
  51 .B select(2)
  52 to wait for
  53 the 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()
  57 or
  58 ar_init()
  59 must be used.
  60 .B  ar_open()
  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
  64 .B resolv(5)
  65 ).  In both cases, if the socket
  66
  67 > i
  68 .B  ar_init()
  69 is
  70 used to both open the socket (as in
  71 .B ar_open()
  72 ) and initialize the
  73 queues used by this library.  The values recognized as parameters to
  74 .B ar_init()
  75 are:
  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.
  91 ARES_CALLINIT is a flag which when set causes
  92 .B res_init()
  93 to be called.
  94 ARES_INITSOCK will close the current socket if it is open and call
  95 .B ar_open()
  96 to open a new one, returning the fd for that socket.
  97 ARES_INITDEBG sets the RES_DEBUG flag of the
  98 .B _res
  99 structure.
 100 ARES_INITCACH is as yet, unused and is for future use where the library
 101 keeps its own cache of replies.
 102
 103    To send a query about either a hostname or an IP number,
 104 .B ar_gethostbyname()
 105 and
 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.
 120
 121    To check for a query,
 122 .B ar_answer()
 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()
 126 or
 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.
 133
 134    To expire old queries,
 135 .B ar_timeout()
 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,
 144 .B ar_timeout()
 145 also
 146 triggers resends of queries and the searching of the domain tree for the
 147 host, the latter works from the
 148 .B _res
 149 structure of
 150 .B resolv(5).
 151
 152    To delete entries from the queue,
 153 .B ar_delete()
 154 can be used and by
 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.
 161
 162    To close a socket opened by
 163 .B ar_open()
 164 ,
 165 .B ar_close()
 166 should  be used so
 167 that it is closed and also marked closed within this library.
 168
 169
 170 .SH DIAGNOSIS
 171
 172 .B ar_open()
 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.
 175
 176 .B ar_init()
 177 returns -1 for any errors, the value returned by
 178 .B res_init()
 179 if
 180 .B res_init()
 181 was called, the return value for
 182 .B ar_open()
 183 if that was
 184 called or the current socket open if 0 is passed and a socket is open.
 185 If neither
 186 .B res_init()
 187 or
 188 .B ar_open()
 189 are called and the flags are non-zero, -2 is returned.
 190
 191 .B ar_gethostbyaddr()
 192 and
 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.
 196
 197 .B ar_answer()
 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.
 202
 203 .B ar_timeout()
 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.
 207
 208 .B ar_delete()
 209 returns the number of entries that were found to match
 210 and consequently deleted.
 211
 212 .SH SEE ALSO
 213
 214 gethostbyaddr(3), gethostbyname(3), resolv(5)
 215
 216 .SH FILES
 217 .nf
 218 arlib.h
 219 /usr/include/resolv.h
 220 /usr/include/arpa/nameser.h
 221 /etc/resolv.conf
 222
 223 .SH BUGS
 224
 225 The results of a successful call to ar_answer() destroy the structure
 226 for any previous calls.
 227
 228 .SH AUTHOR
 229
 230 Darren Reed.  Email address: avalon@coombs.anu.edu.au