/contrib/ntp/arlib/arlib.3

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 230 lines · 198 code · 32 blank · 0 comment · 0 complexity · 4dd7016ff728a987ad1ccbcee830e55d MD5 · raw file

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