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