1 | .\" Copyright (c) 1985, 1991, 1993 |
---|
2 | .\" The Regents of the University of California. All rights reserved. |
---|
3 | .\" |
---|
4 | .\" Redistribution and use in source and binary forms, with or without |
---|
5 | .\" modification, are permitted provided that the following conditions |
---|
6 | .\" are met: |
---|
7 | .\" 1. Redistributions of source code must retain the above copyright |
---|
8 | .\" notice, this list of conditions and the following disclaimer. |
---|
9 | .\" 2. Redistributions in binary form must reproduce the above copyright |
---|
10 | .\" notice, this list of conditions and the following disclaimer in the |
---|
11 | .\" documentation and/or other materials provided with the distribution. |
---|
12 | .\" 3. All advertising materials mentioning features or use of this software |
---|
13 | .\" must display the following acknowledgement: |
---|
14 | .\" This product includes software developed by the University of |
---|
15 | .\" California, Berkeley and its contributors. |
---|
16 | .\" 4. Neither the name of the University nor the names of its contributors |
---|
17 | .\" may be used to endorse or promote products derived from this software |
---|
18 | .\" without specific prior written permission. |
---|
19 | .\" |
---|
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
---|
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
---|
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
---|
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
---|
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
---|
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
---|
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
---|
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
---|
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
---|
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
---|
30 | .\" SUCH DAMAGE. |
---|
31 | .\" |
---|
32 | .\" @(#)resolver.3 8.1 (Berkeley) 6/4/93 |
---|
33 | .\" |
---|
34 | .Dd June 4, 1993 |
---|
35 | .Dt RESOLVER 3 |
---|
36 | .Os BSD 4.3 |
---|
37 | .Sh NAME |
---|
38 | .Nm res_query , |
---|
39 | .Nm res_search , |
---|
40 | .Nm res_mkquery , |
---|
41 | .Nm res_send , |
---|
42 | .Nm res_init , |
---|
43 | .Nm dn_comp , |
---|
44 | .Nm dn_expand |
---|
45 | .Nd resolver routines |
---|
46 | .Sh SYNOPSIS |
---|
47 | .Fd #include <sys/types.h> |
---|
48 | .Fd #include <netinet/in.h> |
---|
49 | .Fd #include <arpa/nameser.h> |
---|
50 | .Fd #include <resolv.h> |
---|
51 | .Ft int |
---|
52 | .Fo res_query |
---|
53 | .Fa "const char *dname" |
---|
54 | .Fa "int class" |
---|
55 | .Fa "int type" |
---|
56 | .Fa "u_char *answer" |
---|
57 | .Fa "int anslen" |
---|
58 | .Fc |
---|
59 | .Ft int |
---|
60 | .Fo res_search |
---|
61 | .Fa "const char *dname" |
---|
62 | .Fa "int class" |
---|
63 | .Fa "int type" |
---|
64 | .Fa "u_char *answer" |
---|
65 | .Fa "int anslen" |
---|
66 | .Fc |
---|
67 | .Ft int |
---|
68 | .Fo res_mkquery |
---|
69 | .Fa "int op" |
---|
70 | .Fa "const char *dname" |
---|
71 | .Fa "int class" |
---|
72 | .Fa "int type" |
---|
73 | .Fa "const u_char *data" |
---|
74 | .Fa "int datalen" |
---|
75 | .Fa "const u_char *newrr_in" |
---|
76 | .Fa "u_char *buf" |
---|
77 | .Fa "int buflen" |
---|
78 | .Fc |
---|
79 | .Ft int |
---|
80 | .Fo res_send |
---|
81 | .Fa "const u_char *msg" |
---|
82 | .Fa "int msglen" |
---|
83 | .Fa "u_char *answer" |
---|
84 | .Fa "int anslen" |
---|
85 | .Fc |
---|
86 | .Ft int |
---|
87 | .Fn res_init |
---|
88 | .Fo dn_comp |
---|
89 | .Fa "const char *exp_dn" |
---|
90 | .Fa "u_char *comp_dn" |
---|
91 | .Fa "int length" |
---|
92 | .Fa "u_char **dnptrs" |
---|
93 | .Fa "u_char **lastdnptr" |
---|
94 | .Fc |
---|
95 | .Ft int |
---|
96 | .Fo dn_expand |
---|
97 | .Fa "const u_char *msg" |
---|
98 | .Fa "const u_char *eomorig" |
---|
99 | .Fa "const u_char *comp_dn" |
---|
100 | .Fa "char *exp_dn" |
---|
101 | .Fa "int length" |
---|
102 | .Fc |
---|
103 | .Sh DESCRIPTION |
---|
104 | These routines are used for making, sending and interpreting |
---|
105 | query and reply messages with Internet domain name servers. |
---|
106 | .Pp |
---|
107 | Global configuration and state information that is used by the |
---|
108 | resolver routines is kept in the structure |
---|
109 | .Em _res . |
---|
110 | Most of the values have reasonable defaults and can be ignored. |
---|
111 | Options |
---|
112 | stored in |
---|
113 | .Em _res.options |
---|
114 | are defined in |
---|
115 | .Pa resolv.h |
---|
116 | and are as follows. |
---|
117 | Options are stored as a simple bit mask containing the bitwise ``or'' |
---|
118 | of the options enabled. |
---|
119 | .Bl -tag -width RES_DEFNAMES |
---|
120 | .It Dv RES_INIT |
---|
121 | True if the initial name server address and default domain name are |
---|
122 | initialized (i.e., |
---|
123 | .Fn res_init |
---|
124 | has been called). |
---|
125 | .It Dv RES_DEBUG |
---|
126 | Print debugging messages. |
---|
127 | .It Dv RES_AAONLY |
---|
128 | Accept authoritative answers only. |
---|
129 | With this option, |
---|
130 | .Fn res_send |
---|
131 | should continue until it finds an authoritative answer or finds an error. |
---|
132 | Currently this is not implemented. |
---|
133 | .It Dv RES_USEVC |
---|
134 | Use |
---|
135 | .Tn TCP |
---|
136 | connections for queries instead of |
---|
137 | .Tn UDP |
---|
138 | datagrams. |
---|
139 | .It Dv RES_STAYOPEN |
---|
140 | Used with |
---|
141 | .Dv RES_USEVC |
---|
142 | to keep the |
---|
143 | .Tn TCP |
---|
144 | connection open between |
---|
145 | queries. |
---|
146 | This is useful only in programs that regularly do many queries. |
---|
147 | .Tn UDP |
---|
148 | should be the normal mode used. |
---|
149 | .It Dv RES_IGNTC |
---|
150 | Unused currently (ignore truncation errors, i.e., don't retry with |
---|
151 | .Tn TCP ) . |
---|
152 | .It Dv RES_RECURSE |
---|
153 | Set the recursion-desired bit in queries. |
---|
154 | This is the default. |
---|
155 | .Pf ( Fn res_send |
---|
156 | does not do iterative queries and expects the name server |
---|
157 | to handle recursion.) |
---|
158 | .It Dv RES_DEFNAMES |
---|
159 | If set, |
---|
160 | .Fn res_search |
---|
161 | will append the default domain name to single-component names |
---|
162 | (those that do not contain a dot). |
---|
163 | This option is enabled by default. |
---|
164 | .It Dv RES_DNSRCH |
---|
165 | If this option is set, |
---|
166 | .Fn res_search |
---|
167 | will search for host names in the current domain and in parent domains; see |
---|
168 | .Xr hostname 7 . |
---|
169 | This is used by the standard host lookup routine |
---|
170 | .Xr gethostbyname 3 . |
---|
171 | This option is enabled by default. |
---|
172 | .It Dv RES_NOALIASES |
---|
173 | This option turns off the user level aliasing feature controlled by the |
---|
174 | .Dq Ev HOSTALIASES |
---|
175 | environment variable. Network daemons should set this option. |
---|
176 | .El |
---|
177 | .Pp |
---|
178 | The |
---|
179 | .Fn res_init |
---|
180 | routine |
---|
181 | reads the configuration file (if any; see |
---|
182 | .Xr resolver 5 ) |
---|
183 | to get the default domain name, |
---|
184 | search list and |
---|
185 | the Internet address of the local name server(s). |
---|
186 | If no server is configured, the host running |
---|
187 | the resolver is tried. |
---|
188 | The current domain name is defined by the hostname |
---|
189 | if not specified in the configuration file; |
---|
190 | it can be overridden by the environment variable |
---|
191 | .Ev LOCALDOMAIN . |
---|
192 | This environment variable may contain several blank-separated |
---|
193 | tokens if you wish to override the |
---|
194 | .Em "search list" |
---|
195 | on a per-process basis. This is similar to the |
---|
196 | .Em search |
---|
197 | command in the configuration file. |
---|
198 | Another environment variable ( |
---|
199 | .Dq Ev RES_OPTIONS |
---|
200 | can be set to |
---|
201 | override certain internal resolver options which are otherwise |
---|
202 | set by changing fields in the |
---|
203 | .Em _res |
---|
204 | structure or are inherited from the configuration file's |
---|
205 | .Em options |
---|
206 | command. The syntax of the |
---|
207 | .Dq Ev RES_OPTIONS |
---|
208 | environment variable is explained in |
---|
209 | .Xr resolver 5 . |
---|
210 | Initialization normally occurs on the first call |
---|
211 | to one of the following routines. |
---|
212 | .Pp |
---|
213 | The |
---|
214 | .Fn res_query |
---|
215 | function provides an interface to the server query mechanism. |
---|
216 | It constructs a query, sends it to the local server, |
---|
217 | awaits a response, and makes preliminary checks on the reply. |
---|
218 | The query requests information of the specified |
---|
219 | .Fa type |
---|
220 | and |
---|
221 | .Fa class |
---|
222 | for the specified fully-qualified domain name |
---|
223 | .Fa dname . |
---|
224 | The reply message is left in the |
---|
225 | .Fa answer |
---|
226 | buffer with length |
---|
227 | .Fa anslen |
---|
228 | supplied by the caller. |
---|
229 | .Pp |
---|
230 | The |
---|
231 | .Fn res_search |
---|
232 | routine makes a query and awaits a response like |
---|
233 | .Fn res_query , |
---|
234 | but in addition, it implements the default and search rules |
---|
235 | controlled by the |
---|
236 | .Dv RES_DEFNAMES |
---|
237 | and |
---|
238 | .Dv RES_DNSRCH |
---|
239 | options. |
---|
240 | It returns the first successful reply. |
---|
241 | .Pp |
---|
242 | The remaining routines are lower-level routines used by |
---|
243 | .Fn res_query . |
---|
244 | The |
---|
245 | .Fn res_mkquery |
---|
246 | function |
---|
247 | constructs a standard query message and places it in |
---|
248 | .Fa buf . |
---|
249 | It returns the size of the query, or \-1 if the query is |
---|
250 | larger than |
---|
251 | .Fa buflen . |
---|
252 | The query type |
---|
253 | .Fa op |
---|
254 | is usually |
---|
255 | .Dv QUERY , |
---|
256 | but can be any of the query types defined in |
---|
257 | .Aq Pa arpa/nameser.h . |
---|
258 | The domain name for the query is given by |
---|
259 | .Fa dname . |
---|
260 | .Fa Newrr |
---|
261 | is currently unused but is intended for making update messages. |
---|
262 | .Pp |
---|
263 | The |
---|
264 | .Fn res_send |
---|
265 | routine |
---|
266 | sends a pre-formatted query and returns an answer. |
---|
267 | It will call |
---|
268 | .Fn res_init |
---|
269 | if |
---|
270 | .Dv RES_INIT |
---|
271 | is not set, send the query to the local name server, and |
---|
272 | handle timeouts and retries. |
---|
273 | The length of the reply message is returned, or |
---|
274 | \-1 if there were errors. |
---|
275 | .Pp |
---|
276 | The |
---|
277 | .Fn dn_comp |
---|
278 | function |
---|
279 | compresses the domain name |
---|
280 | .Fa exp_dn |
---|
281 | and stores it in |
---|
282 | .Fa comp_dn . |
---|
283 | The size of the compressed name is returned or \-1 if there were errors. |
---|
284 | The size of the array pointed to by |
---|
285 | .Fa comp_dn |
---|
286 | is given by |
---|
287 | .Fa length . |
---|
288 | The compression uses |
---|
289 | an array of pointers |
---|
290 | .Fa dnptrs |
---|
291 | to previously-compressed names in the current message. |
---|
292 | The first pointer points to |
---|
293 | to the beginning of the message and the list ends with |
---|
294 | .Dv NULL . |
---|
295 | The limit to the array is specified by |
---|
296 | .Fa lastdnptr . |
---|
297 | A side effect of |
---|
298 | .Fn dn_comp |
---|
299 | is to update the list of pointers for |
---|
300 | labels inserted into the message |
---|
301 | as the name is compressed. |
---|
302 | If |
---|
303 | .Em dnptr |
---|
304 | is |
---|
305 | .Dv NULL, names are not compressed. |
---|
306 | If |
---|
307 | .Fa lastdnptr |
---|
308 | is |
---|
309 | .Dv NULL , |
---|
310 | the list of labels is not updated. |
---|
311 | .Pp |
---|
312 | The |
---|
313 | .Fn dn_expand |
---|
314 | entry |
---|
315 | expands the compressed domain name |
---|
316 | .Fa comp_dn |
---|
317 | to a full domain name |
---|
318 | The compressed name is contained in a query or reply message; |
---|
319 | .Fa msg |
---|
320 | is a pointer to the beginning of the message. |
---|
321 | The uncompressed name is placed in the buffer indicated by |
---|
322 | .Fa exp_dn |
---|
323 | which is of size |
---|
324 | .Fa length . |
---|
325 | The size of compressed name is returned or \-1 if there was an error. |
---|
326 | .Sh FILES |
---|
327 | .Bl -tag -width Pa |
---|
328 | /etc/resolv.conf |
---|
329 | The configuration file |
---|
330 | see |
---|
331 | .Xr resolver 5 . |
---|
332 | .El |
---|
333 | .Sh SEE ALSO |
---|
334 | .Xr gethostbyname 3 , |
---|
335 | .Xr resolver 5 , |
---|
336 | .Xr hostname 7 , |
---|
337 | .Xr named 8 |
---|
338 | .Pp |
---|
339 | .%T RFC1032 , |
---|
340 | .%T RFC1033 , |
---|
341 | .%T RFC1034 , |
---|
342 | .%T RFC1035 , |
---|
343 | .%T RFC974 |
---|
344 | .Rs |
---|
345 | .%T "Name Server Operations Guide for BIND" |
---|
346 | .Re |
---|
347 | .Sh HISTORY |
---|
348 | The |
---|
349 | .Nm |
---|
350 | function appeared in |
---|
351 | .Bx 4.3 . |
---|