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