Rev | Author | # | Line |
---|---|---|---|
1 | perry | 1 | RESOLVER |
2 | !!!RESOLVER | ||
3 | NAME | ||
4 | SYNOPSIS | ||
5 | DESCRIPTION | ||
6 | RETURN VALUE | ||
7 | FILES | ||
8 | CONFORMING TO | ||
9 | SEE ALSO | ||
10 | ---- | ||
11 | !!NAME | ||
12 | |||
13 | |||
14 | res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, dn_comp, dn_expand - resolver routines | ||
15 | !!SYNOPSIS | ||
16 | |||
17 | |||
18 | __#include | ||
19 | __''dname''__, int__ ''class''__, int__ ''type''__, | ||
20 | unsigned char *__''answer''__, int__ ''anslen''__); | ||
21 | int res_search(const char *__''dname''__, int__ ''class''__, int__ ''type''__, | ||
22 | unsigned char *__''answer''__, int__ ''anslen''__); | ||
23 | int res_querydomain(const char *__''name''__, const char *__''domain''__, | ||
24 | int__ ''class''__, int__ ''type''__, unsigned char *__''answer''__, | ||
25 | int__ ''anslen''__); | ||
26 | int res_mkquery(int__ ''op''__, const char *__''dname''__, int__ ''class''__, | ||
27 | int__ ''type''__, char *__''data''__, int__ ''datalen''__, struct rrec *__''newrr''__, | ||
28 | char *__''buf''__, int__ ''buflen''__); | ||
29 | int res_send(const char *__''msg''__, int__ ''msglen''__, char *__''answer''__, | ||
30 | int__ ''anslen''__); | ||
31 | int dn_comp(unsigned char *__''exp_dn''__, unsigned char *__''comp_dn''__, | ||
32 | int__ ''length''__, unsigned char **__''dnptrs''__, unsigned char *__''exp_dn''__, | ||
33 | unsigned char **__''lastdnptr''__); | ||
34 | int dn_expand(unsigned char *__''msg''__, unsigned char *__''eomorig''__, | ||
35 | unsigned char *__''comp_dn''__, unsigned char *__''exp_dn''__, | ||
36 | int__ ''length''__); | ||
37 | __ | ||
38 | !!DESCRIPTION | ||
39 | |||
40 | |||
41 | These functions make queries to and interpret the responses | ||
42 | from Internet domain name servers. | ||
43 | |||
44 | |||
45 | The __res_init()__ function reads the configuration files | ||
46 | (see resolv+(8)) to get the default domain name, search | ||
47 | order and name server address(es). If no server is given, | ||
48 | the local host is tried. If no domain is given, that | ||
49 | associated with the local host is used. It can be overridden | ||
50 | with the environment variable LOCALDOMAIN. __res_init()__ | ||
51 | is normally executed by the first call to one of the other | ||
52 | functions. | ||
53 | |||
54 | |||
55 | The __res_query()__ function queries the name server for | ||
56 | the fully-qualified domain name ''name'' of specified | ||
57 | ''type'' and ''class''. The reply is left in the | ||
58 | buffer ''answer'' of length ''anslen'' supplied by the | ||
59 | caller. | ||
60 | |||
61 | |||
62 | The __res_search()__ function makes a query and waits for | ||
63 | the response like __res_query()__, but in addition | ||
64 | implements the default and search rules controlled by | ||
65 | RES_DEFNAMES and RES_DNSRCH (see description of ''_res'' | ||
66 | options below). | ||
67 | |||
68 | |||
69 | The __res_querydomain()__ function makes a query using | ||
70 | __res_query()__ on the concatenation of ''name'' and | ||
71 | ''domain''. | ||
72 | |||
73 | |||
74 | The following functions are lower-level routines used by | ||
75 | __res_query()__. | ||
76 | |||
77 | |||
78 | The __res_mkquery()__ function constructs a query message | ||
79 | in ''buf'' of length ''buflen'' for the domain name | ||
80 | ''dname''. The query type ''op'' is usually QUERY, but | ||
81 | can be any of the types defined in | ||
82 | ''''. ''newrr'' is currently | ||
83 | unused. | ||
84 | |||
85 | |||
86 | The __res_send()__ function sends a pre-formatted query | ||
87 | given in ''msg'' of length ''msglen'' and returns the | ||
88 | answer in ''answer'' which is of length ''anslen''. It | ||
89 | will call __res_init()__, if it has not already been | ||
90 | called. | ||
91 | |||
92 | |||
93 | The __dn_comp()__ function compresses the domain name | ||
94 | ''exp_dn'' and stores it in the buffer ''comp_dn'' of | ||
95 | length ''length''. The compression uses an array of | ||
96 | pointers ''dnptrs'' to previously compressed names in the | ||
97 | current message. The first pointer points to the beginning | ||
98 | of the message and the list ends with NULL. The limit of the | ||
99 | array is specified by ''lastdnptr''. if ''dnptr'' is | ||
100 | NULL, domain names are not compressed. If ''lastdnptr'' | ||
101 | is NULL, the list of labels is not updated. | ||
102 | |||
103 | |||
104 | The dn_expand() function expands the compressed domain name | ||
105 | ''comp_dn'' to a full domain name, which is placed in the | ||
106 | buffer ''exp_dn'' of size ''length''. The compressed | ||
107 | name is contained in a query or reply message, and | ||
108 | ''msg'' points to the beginning of the | ||
109 | message. | ||
110 | |||
111 | |||
112 | The resolver routines use global configuration and state | ||
113 | information contained in the structure ''_res'', which is | ||
114 | defined in ''''. The only field that is | ||
115 | normally manipulated by the user is ''_res.options''. | ||
116 | This field can contain the bitwise ``or'' of the following | ||
117 | options: | ||
118 | |||
119 | |||
120 | __RES_INIT__ | ||
121 | |||
122 | |||
123 | True if __res_init()__ has been called. | ||
124 | |||
125 | |||
126 | __RES_DEBUG__ | ||
127 | |||
128 | |||
129 | Print debugging messages. | ||
130 | |||
131 | |||
132 | __RES_AAONLY__ | ||
133 | |||
134 | |||
135 | Accept authoritative answers only. __res_send()__ | ||
136 | continues until it fins an authoritative answer or returns | ||
137 | an error. [[Not currently implemented]. | ||
138 | |||
139 | |||
140 | __RES_USEVC__ | ||
141 | |||
142 | |||
143 | Use TCP connections for queries rather than UDP | ||
144 | datagrams. | ||
145 | |||
146 | |||
147 | __RES_PRIMARY__ | ||
148 | |||
149 | |||
150 | Query primary domain name server only. | ||
151 | |||
152 | |||
153 | __RES_IGNTC__ | ||
154 | |||
155 | |||
156 | Ignore truncation errors. Don't retry with TCP. [[Not | ||
157 | currently implemented]. | ||
158 | |||
159 | |||
160 | __RES_RECURSE__ | ||
161 | |||
162 | |||
163 | Set the recursion desired bit in queries. Recursion is | ||
164 | carried out by the domain name server, not by | ||
165 | __res_send()__. [[Enabled by default]. | ||
166 | |||
167 | |||
168 | __RES_DEFNAMES__ | ||
169 | |||
170 | |||
171 | If set, __res_search()__ will append the default domain | ||
172 | name to single component names, ie. those that do not | ||
173 | contain a dot. [[Enabled by default]. | ||
174 | |||
175 | |||
176 | __RES_STAYOPEN__ | ||
177 | |||
178 | |||
179 | Used with RES_USEVC to keep the TCP connection open between | ||
180 | queries. | ||
181 | |||
182 | |||
183 | __RES_DNSRCH__ | ||
184 | |||
185 | |||
186 | If set, __res_search()__ will search for host names in | ||
187 | the current domain and in parent domains. This option is | ||
188 | used by gethostbyname(3). [[Enabled by | ||
189 | default]. | ||
190 | !!RETURN VALUE | ||
191 | |||
192 | |||
193 | The __res_init()__ function returns 0 on success, or -1 | ||
194 | if an error occurs. | ||
195 | |||
196 | |||
197 | The __res_query()__, __res_search()__, | ||
198 | __res_querydomain()__, __res_mkquery()__ and | ||
199 | __res_send()__ functions return the length of the | ||
200 | response, or -1 if an error occurs. | ||
201 | |||
202 | |||
203 | The __dn_comp()__ and __dn_expand()__ functions return | ||
204 | the length of the compressed name, or -1 if an error | ||
205 | occurs. | ||
206 | !!FILES | ||
207 | |||
208 | |||
209 | /etc/resolv.conf resolver configuration file | ||
210 | /etc/host.conf resolver configuration file | ||
211 | !!CONFORMING TO | ||
212 | |||
213 | |||
214 | BSD 4.3 | ||
215 | !!SEE ALSO | ||
216 | |||
217 | |||
218 | gethostbyname(3), hostname(7), | ||
219 | named(8), resolv+(8) | ||
220 | ---- |