1inet_res(3) Erlang Module Definition inet_res(3)
2
6 inet_res - A rudimentary DNS client.
7
9 This module performs DNS name resolving to recursive name servers.
10 See also ERTS User's Guide: Inet Configuration for more information
12 about how to configure an Erlang runtime system for IP communication,
13 and how to enable this DNS client by defining 'dns' as a lookup method.
14 The DNS client then acts as a backend for the resolving functions in
15 inet.
16 This DNS client can resolve DNS records even if it is not used for nor‐
18 mal name resolving in the node.
19 This is not a full-fledged resolver, only a DNS client that relies on
21 asking trusted recursive name servers.
22
24 UDP queries are used unless resolver option usevc is true, which forces
25 TCP queries. If the query is too large for UDP, TCP is used instead.
26 For regular DNS queries, 512 bytes is the size limit.
27 When EDNS is enabled (resolver option edns is set to the EDNS version
29 (that is, 0 instead of false), resolver option udp_payload_size sets
30 the limit. If a name server replies with the TC bit set (truncation),
31 indicating that the answer is incomplete, the query is retried to that
32 name server using TCP. Resolver option udp_payload_size also sets the
33 advertised size for the maximum allowed reply size, if EDNS is enabled,
34 otherwise the name server uses the limit 512 bytes. If the reply is
35 larger, it gets truncated, forcing a TCP requery.
36 For UDP queries, resolver options timeout and retry control retransmis‐
38 sion. Each name server in the nameservers list is tried with a time-out
39 of timeout/retry. Then all name servers are tried again, doubling the
40 time-out, for a total of retry times.
41 But before all name servers are tried again, there is a (user config‐
43 urable) timeout, servfail_retry_timeout. The point of this is to pre‐
44 vent the new query to be handled by a server's servfail cache (a client
45 that is to eager will actually only get what is in the servfail cache).
46 If there is too little time left of the resolver call's timeout to do a
47 retry, the resolver call may return before the call's timeout has ex‐
48 pired.
49 For queries not using the search list, if the query to all nameservers
51 results in {error,nxdomain} or an empty answer, the same query is tried
52 for alt_nameservers.
53
55 The following data types concern the resolver:
56
58 res_option() =
59 {alt_nameservers, [nameserver()]} |
60 {edns, 0 | false} |
61 {inet6, boolean()} |
62 {nameservers, [nameserver()]} |
63 {recurse, boolean()} |
64 {retry, integer()} |
65 {timeout, integer()} |
66 {udp_payload_size, integer()} |
67 {usevc, boolean()}
68 nameserver() = {inet:ip_address(), Port :: 1..65535}
70 res_error() =
72 formerr | qfmterror | servfail | nxdomain | notimp | refused |
73 badvers | timeout
74
76 The following data types concern the DNS client:
77
79 dns_name() = string()
80 A string with no adjacent dots.
82 rr_type() =
84 a | aaaa | cname | gid | hinfo | ns | mb | md | mg | mf |
85 minfo | mx | naptr | null | ptr | soa | spf | srv | txt |
86 uid | uinfo | unspec | wks
87 dns_class() = in | chaos | hs | any
89 dns_msg() = term()
91 This is the start of a hiearchy of opaque data structures that
93 can be examined with access functions in inet_dns, which return
94 lists of {Field,Value} tuples. The arity 2 functions only return
95 the value for a specified field.
96 dns_msg() = DnsMsg
98 inet_dns:msg(DnsMsg) ->
99 [ {header, dns_header()}
100 | {qdlist, dns_query()}
101 | {anlist, dns_rr()}
102 | {nslist, dns_rr()}
103 | {arlist, dns_rr()} ]
104 inet_dns:msg(DnsMsg, header) -> dns_header() % for example
105 inet_dns:msg(DnsMsg, Field) -> Value
106 dns_header() = DnsHeader
108 inet_dns:header(DnsHeader) ->
109 [ {id, integer()}
110 | {qr, boolean()}
111 | {opcode, query | iquery | status | integer()}
112 | {aa, boolean()}
113 | {tc, boolean()}
114 | {rd, boolean()}
115 | {ra, boolean()}
116 | {pr, boolean()}
117 | {rcode, integer(0..16)} ]
118 inet_dns:header(DnsHeader, Field) -> Value
119 query_type() = axfr | mailb | maila | any | rr_type()
121 dns_query() = DnsQuery
123 inet_dns:dns_query(DnsQuery) ->
124 [ {domain, dns_name()}
125 | {type, query_type()}
126 | {class, dns_class()} ]
127 inet_dns:dns_query(DnsQuery, Field) -> Value
128 dns_rr() = DnsRr
130 inet_dns:rr(DnsRr) -> DnsRrFields | DnsRrOptFields
131 DnsRrFields = [ {domain, dns_name()}
132 | {type, rr_type()}
133 | {class, dns_class()}
134 | {ttl, integer()}
135 | {data, dns_data()} ]
136 DnsRrOptFields = [ {domain, dns_name()}
137 | {type, opt}
138 | {udp_payload_size, integer()}
139 | {ext_rcode, integer()}
140 | {version, integer()}
141 | {z, integer()}
142 | {data, dns_data()} ]
143 inet_dns:rr(DnsRr, Field) -> Value
144 There is an information function for the types above:
146 inet_dns:record_type(dns_msg()) -> msg;
148 inet_dns:record_type(dns_header()) -> header;
149 inet_dns:record_type(dns_query()) -> dns_query;
150 inet_dns:record_type(dns_rr()) -> rr;
151 inet_dns:record_type(_) -> undefined.
152 So, inet_dns:(inet_dns:record_type(X))(X) converts any of these
154 data structures into a {Field,Value} list.
155 dns_data() =
157 dns_name() |
158 inet:ip4_address() |
159 inet:ip6_address() |
160 {MName :: dns_name(),
161 RName :: dns_name(),
162 Serial :: integer(),
163 Refresh :: integer(),
164 Retry :: integer(),
165 Expiry :: integer(),
166 Minimum :: integer()} |
167 {inet:ip4_address(), Proto :: integer(), BitMap :: binary()} |
168 {CpuString :: string(), OsString :: string()} |
169 {RM :: dns_name(), EM :: dns_name()} |
170 {Prio :: integer(), dns_name()} |
171 {Prio :: integer(),
172 Weight :: integer(),
173 Port :: integer(),
174 dns_name()} |
175 {Order :: integer(),
176 Preference :: integer(),
177 Flags :: string(),
178 Services :: string(),
179 Regexp :: string(),
180 dns_name()} |
181 [string()] |
182 binary()
183 Regexp is a string with characters encoded in the UTF-8 coding
185 standard.
186
188 getbyname(Name, Type) -> {ok, Hostent} | {error, Reason}
189 getbyname(Name, Type, Timeout) -> {ok, Hostent} | {error, Reason}
191 Types:
193 Name = dns_name()
195 Type = rr_type()
196 Timeout = timeout()
197 Hostent = inet:hostent()
198 Reason = inet:posix() | res_error()
199 Resolves a DNS record of the specified type for the specified
201 host, of class in. Returns, on success, a hostent() record with
202 dns_data() elements in the address list field.
203 This function uses resolver option search that is a list of do‐
205 main names. If the name to resolve contains no dots, it is
206 prepended to each domain name in the search list, and they are
207 tried in order. If the name contains dots, it is first tried as
208 an absolute name and if that fails, the search list is used. If
209 the name has a trailing dot, it is supposed to be an absolute
210 name and the search list is not used.
211 gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}
213 gethostbyaddr(Address, Timeout) -> {ok, Hostent} | {error, Reason}
215 Types:
217 Address = inet:ip_address()
219 Timeout = timeout()
220 Hostent = inet:hostent()
221 Reason = inet:posix() | res_error()
222 Backend functions used by inet:gethostbyaddr/1.
224 gethostbyname(Name) -> {ok, Hostent} | {error, Reason}
226 gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}
228 gethostbyname(Name, Family, Timeout) ->
230 {ok, Hostent} | {error, Reason}
231 Types:
233 Name = dns_name()
235 Hostent = inet:hostent()
236 Timeout = timeout()
237 Family = inet:address_family()
238 Reason = inet:posix() | res_error()
239 Backend functions used by inet:gethostbyname/1,2.
241 This function uses resolver option search just like getby‐
243 name/2,3.
244 If resolver option inet6 is true, an IPv6 address is looked up.
246 lookup(Name, Class, Type) -> [dns_data()]
248 lookup(Name, Class, Type, Opts) -> [dns_data()]
250 lookup(Name, Class, Type, Opts, Timeout) -> [dns_data()]
252 Types:
254 Name = dns_name() | inet:ip_address()
256 Class = dns_class()
257 Type = rr_type()
258 Opts = [res_option() | verbose]
259 Timeout = timeout()
260 Resolves the DNS data for the record of the specified type and
262 class for the specified name. On success, filters out the answer
263 records with the correct Class and Type, and returns a list of
264 their data fields. So, a lookup for type any gives an empty an‐
265 swer, as the answer records have specific types that are not
266 any. An empty answer or a failed lookup returns an empty list.
267 Calls resolve/* with the same arguments and filters the result,
269 so Opts is described for those functions.
270 resolve(Name, Class, Type) -> {ok, dns_msg()} | Error
272 resolve(Name, Class, Type, Opts) -> {ok, dns_msg()} | Error
274 resolve(Name, Class, Type, Opts, Timeout) ->
276 {ok, dns_msg()} | Error
277 Types:
279 Name = dns_name() | inet:ip_address()
281 Class = dns_class()
282 Type = rr_type()
283 Opts = [Opt]
284 Opt = res_option() | verbose | atom()
285 Timeout = timeout()
286 Error = {error, Reason} | {error, {Reason, dns_msg()}}
287 Reason = inet:posix() | res_error()
288 Resolves a DNS record of the specified type and class for the
290 specified name. The returned dns_msg() can be examined using ac‐
291 cess functions in inet_db, as described in section in DNS Types.
292 If Name is an ip_address(), the domain name to query for is gen‐
294 erated as the standard reverse ".IN-ADDR.ARPA." name for an IPv4
295 address, or the ".IP6.ARPA." name for an IPv6 address. In this
296 case, you most probably want to use Class = in and Type = ptr,
297 but it is not done automatically.
298 Opts overrides the corresponding resolver options. If option
300 nameservers is specified, it is assumed that it is the complete
301 list of name serves, so resolver option alt_nameserves is ig‐
302 nored. However, if option alt_nameserves is also specified to
303 this function, it is used.
304 Option verbose (or rather {verbose,true}) causes diagnostics
306 printout through io:format/2 of queries, replies retransmis‐
307 sions, and so on, similar to from utilities, such as dig and
308 nslookup.
309 If Opt is any atom, it is interpreted as {Opt,true} unless the
311 atom string starts with "no", making the interpretation
312 {Opt,false}. For example, usevc is an alias for {usevc,true} and
313 nousevc is an alias for {usevc,false}.
314 Option inet6 has no effect on this function. You probably want
316 to use Type = a | aaaa instead.
317
319 This access functions example shows how lookup/3 can be implemented us‐
320 ing resolve/3 from outside the module:
321 example_lookup(Name, Class, Type) ->
323 case inet_res:resolve(Name, Class, Type) of
324 {ok,Msg} ->
325 [inet_dns:rr(RR, data)
326 || RR <- inet_dns:msg(Msg, anlist),
327 inet_dns:rr(RR, type) =:= Type,
328 inet_dns:rr(RR, class) =:= Class];
329 {error,_} ->
330 []
331 end.
332
334 These are deprecated because the annoying double meaning of the name
335 servers/time-out argument, and because they have no decent place for a
336 resolver options list.
337
339 nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason}
340 nslookup(Name, Class, Type, Timeout) ->
342 {ok, dns_msg()} | {error, Reason}
343 nslookup(Name, Class, Type, Nameservers) ->
345 {ok, dns_msg()} | {error, Reason}
346 Types:
348 Name = dns_name() | inet:ip_address()
350 Class = dns_class()
351 Type = rr_type()
352 Timeout = timeout()
353 Nameservers = [nameserver()]
354 Reason = inet:posix() | res_error()
355 Resolves a DNS record of the specified type and class for the
357 specified name.
358 nnslookup(Name, Class, Type, Nameservers) ->
360 {ok, dns_msg()} | {error, Reason}
361 nnslookup(Name, Class, Type, Nameservers, Timeout) ->
363 {ok, dns_msg()} | {error, Reason}
364 Types:
366 Name = dns_name() | inet:ip_address()
368 Class = dns_class()
369 Type = rr_type()
370 Timeout = timeout()
371 Nameservers = [nameserver()]
372 Reason = inet:posix()
373 Resolves a DNS record of the specified type and class for the
375 specified name.
376Ericsson AB kernel 7.3.1.1 inet_res(3)