home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / NETWORK / ISP / bind.4.8.3.lzh / BIND483 / MAN / resolver.3 < prev    next >
Text File  |  1993-08-24  |  7KB  |  281 lines
  1. .\" Copyright (c) 1985 The Regents of the University of California.
  2. .\" All rights reserved.
  3. .\"
  4. .\" Redistribution and use in source and binary forms are permitted provided
  5. .\" that: (1) source distributions retain this entire copyright notice and
  6. .\" comment, and (2) distributions including binaries display the following
  7. .\" acknowledgement:  ``This product includes software developed by the
  8. .\" University of California, Berkeley and its contributors'' in the
  9. .\" documentation or other materials provided with the distribution and in
  10. .\" all advertising materials mentioning features or use of this software.
  11. .\" Neither the name of the University nor the names of its contributors may
  12. .\" be used to endorse or promote products derived from this software without
  13. .\" specific prior written permission.
  14. .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  15. .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  16. .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  17. .\"
  18. .\"    @(#)resolver.3    6.5 (Berkeley) 6/23/90
  19. .\"
  20. .TH RESOLVER 3 "June 23, 1990"
  21. .UC 4
  22. .SH NAME
  23. res_query, res_search, res_mkquery, res_send, res_init, dn_comp, dn_expand \- resolver routines
  24. .SH SYNOPSIS
  25. .B #include <sys/types.h>
  26. .br
  27. .B #include <netinet/in.h>
  28. .br
  29. .B #include <arpa/nameser.h>
  30. .br
  31. .B #include <resolv.h>
  32. .PP
  33. .B "res_query(dname, class, type, answer, anslen)"
  34. .br
  35. .B char *dname;
  36. .br
  37. .B int class, type;
  38. .br
  39. .B u_char *answer;
  40. .br
  41. .B int anslen;
  42. .PP
  43. .B "res_search(dname, class, type, answer, anslen)"
  44. .br
  45. .B char *dname;
  46. .br
  47. .B int class, type;
  48. .br
  49. .B u_char *answer;
  50. .br
  51. .B int anslen;
  52. .PP
  53. .B "res_mkquery(op, dname, class, type, data, datalen, newrr, buf, buflen)"
  54. .br
  55. .B int op;
  56. .br
  57. .B char *dname;
  58. .br
  59. .B int class, type;
  60. .br
  61. .B char *data;
  62. .br
  63. .B int datalen;
  64. .br
  65. .B struct rrec *newrr;
  66. .br
  67. .B char *buf;
  68. .br
  69. .B int buflen;
  70. .PP
  71. .B res_send(msg, msglen, answer, anslen)
  72. .br
  73. .B char *msg;
  74. .br
  75. .B int msglen;
  76. .br
  77. .B char *answer;
  78. .br
  79. .B int anslen;
  80. .PP
  81. .B res_init()
  82. .PP
  83. .B dn_comp(exp_dn, comp_dn, length, dnptrs, lastdnptr)
  84. .br
  85. .B char *exp_dn, *comp_dn;
  86. .br
  87. .B int length;
  88. .br
  89. .B char **dnptrs, **lastdnptr;
  90. .PP
  91. .B dn_expand(msg, eomorig, comp_dn, exp_dn, length)
  92. .br
  93. .B char *msg, *eomorig, *comp_dn, exp_dn;
  94. .br
  95. .B int  length;
  96. .SH DESCRIPTION
  97. These routines are used for making, sending and interpreting
  98. query and reply messages with Internet domain name servers.
  99. .PP
  100. Global configuration and state information that is used by the
  101. resolver routines is kept in the structure
  102. .IR _res .
  103. Most of the values have reasonable defaults and can be ignored.
  104. Options
  105. stored in
  106. .I _res.options
  107. are defined in
  108. .I resolv.h
  109. and are as follows.
  110. Options are stored as a simple bit mask containing the bitwise ``or''
  111. of the options enabled.
  112. .IP RES_INIT
  113. True if the initial name server address and default domain name are
  114. initialized (i.e.,
  115. .I res_init
  116. has been called).
  117. .IP RES_DEBUG
  118. Print debugging messages.
  119. .IP RES_AAONLY
  120. Accept authoritative answers only.
  121. With this option,
  122. .I res_send
  123. should continue until it finds an authoritative answer or finds an error.
  124. Currently this is not implemented.
  125. .IP RES_USEVC
  126. Use TCP connections for queries instead of UDP datagrams.
  127. .IP RES_STAYOPEN
  128. Used with RES_USEVC to keep the TCP connection open between
  129. queries.
  130. This is useful only in programs that regularly do many queries.
  131. UDP should be the normal mode used.
  132. .IP RES_IGNTC
  133. Unused currently (ignore truncation errors, i.e., don't retry with TCP).
  134. .IP RES_RECURSE
  135. Set the recursion-desired bit in queries.
  136. This is the default.
  137. (\c
  138. .I res_send
  139. does not do iterative queries and expects the name server
  140. to handle recursion.)
  141. .IP RES_DEFNAMES
  142. If set,
  143. .I res_search
  144. will append the default domain name to single-component names
  145. (those that do not contain a dot).
  146. This option is enabled by default.
  147. .IP RES_DNSRCH
  148. If this option is set,
  149. .I res_search
  150. will search for host names in the current domain and in parent domains; see
  151. .IR hostname (7).
  152. This is used by the standard host lookup routine
  153. .IR gethostbyname (3).
  154. This option is enabled by default.
  155. .PP
  156. The
  157. .I res_init
  158. routine
  159. reads the configuration file (if any; see
  160. .IR resolver (5))
  161. to get the default domain name,
  162. search list and
  163. the Internet address of the local name server(s).
  164. If no server is configured, the host running
  165. the resolver is tried.
  166. The current domain name is defined by the hostname
  167. if not specified in the configuration file;
  168. it can be overridden by the environment variable LOCALDOMAIN.
  169. Initialization normally occurs on the first call
  170. to one of the following routines.
  171. .PP
  172. The
  173. .I res_query
  174. function provides an interface to the server query mechanism.
  175. It constructs a query, sends it to the local server,
  176. awaits a response, and makes preliminary checks on the reply.
  177. The query requests information of the specified
  178. .I type
  179. and
  180. .I class
  181. for the specified fully-qualified domain name
  182. .I dname .
  183. The reply message is left in the
  184. .I answer
  185. buffer with length
  186. .I anslen
  187. supplied by the caller.
  188. .PP
  189. The
  190. .I res_search
  191. routine makes a query and awaits a response like
  192. .IR res_query ,
  193. but in addition, it implements the default and search rules
  194. controlled by the RES_DEFNAMES and RES_DNSRCH options.
  195. It returns the first successful reply.
  196. .PP
  197. The remaining routines are lower-level routines used by
  198. .IR res_query .
  199. The
  200. .I res_mkquery
  201. function
  202. constructs a standard query message and places it in
  203. .IR buf .
  204. It returns the size of the query, or \-1 if the query is
  205. larger than
  206. .IR buflen .
  207. The query type
  208. .I op
  209. is usually QUERY, but can be any of the query types defined in
  210. .IR <arpa/nameser.h> .
  211. The domain name for the query is given by
  212. .IR dname .
  213. .I Newrr
  214. is currently unused but is intended for making update messages.
  215. .PP
  216. The
  217. .I res_send
  218. routine
  219. sends a pre-formatted query and returns an answer.
  220. It will call
  221. .I res_init
  222. if RES_INIT is not set, send the query to the local name server, and
  223. handle timeouts and retries.
  224. The length of the reply message is returned, or
  225. \-1 if there were errors.
  226. .PP
  227. The
  228. .I dn_comp
  229. function
  230. compresses the domain name
  231. .I exp_dn
  232. and stores it in
  233. .IR comp_dn .
  234. The size of the compressed name is returned or \-1 if there were errors.
  235. The size of the array pointed to by
  236. .I comp_dn
  237. is given by
  238. .IR length .
  239. The compression uses
  240. an array of pointers
  241. .I dnptrs
  242. to previously-compressed names in the current message.
  243. The first pointer points to
  244. to the beginning of the message and the list ends with NULL.
  245. The limit to the array is specified by
  246. .IR lastdnptr .
  247. A side effect of
  248. .I dn_comp
  249. is to update the list of pointers for
  250. labels inserted into the message
  251. as the name is compressed.
  252. If
  253. .I dnptr
  254. is NULL, names are not compressed.
  255. If
  256. .I lastdnptr
  257. is NULL, the list of labels is not updated.
  258. .PP
  259. The
  260. .I dn_expand
  261. entry
  262. expands the compressed domain name
  263. .I comp_dn
  264. to a full domain name
  265. The compressed name is contained in a query or reply message;
  266. .I msg
  267. is a pointer to the beginning of the message.
  268. The uncompressed name is placed in the buffer indicated by
  269. .I exp_dn
  270. which is of size
  271. .IR length .
  272. The size of compressed name is returned or \-1 if there was an error.
  273. .SH FILES
  274. /etc/resolv.conf    see resolver(5)
  275. .SH "SEE ALSO"
  276. gethostbyname(3), named(8), resolver(5), hostname(7),
  277. .br
  278. RFC1032, RFC1033, RFC1034, RFC1035, RFC974, 
  279. .br
  280. SMM:11 Name Server Operations Guide for BIND
  281.