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 too eager will actually only get what is in the servfail
46 cache). If there is too little time left of the resolver call's timeout
47 to do a retry, the resolver call may return before the call's timeout
48 has expired.
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 {nxdomain_reply, boolean()}
69 nameserver() = {inet:ip_address(), Port :: 1..65535}
71 res_error() =
73 formerr | qfmterror | servfail | nxdomain | notimp | refused |
74 badvers | timeout
75
77 The following data types concern the DNS client:
78
80 dns_name() = string()
81 A string with no adjacent dots.
83 dns_rr_type() =
85 a | aaaa | caa | cname | gid | hinfo | ns | mb | md | mg |
86 mf | minfo | mx | naptr | null | ptr | soa | spf | srv | txt |
87 uid | uinfo | unspec | uri | wks
88 dns_class() = in | chaos | hs | any
90 dns_msg() = term()
92 This is the start of a hierarchy of opaque data structures that
94 can be examined with access functions in inet_dns, which return
95 lists of {Field,Value} tuples. The arity 2 functions only return
96 the value for a specified field.
97 dns_msg() = DnsMsg
99 inet_dns:msg(DnsMsg) ->
100 [ {header, dns_header()}
101 | {qdlist, dns_query()}
102 | {anlist, dns_rr()}
103 | {nslist, dns_rr()}
104 | {arlist, dns_rr()} ]
105 inet_dns:msg(DnsMsg, header) -> dns_header() % for example
106 inet_dns:msg(DnsMsg, Field) -> Value
107 dns_header() = DnsHeader
109 inet_dns:header(DnsHeader) ->
110 [ {id, integer()}
111 | {qr, boolean()}
112 | {opcode, query | iquery | status | integer()}
113 | {aa, boolean()}
114 | {tc, boolean()}
115 | {rd, boolean()}
116 | {ra, boolean()}
117 | {pr, boolean()}
118 | {rcode, integer(0..16)} ]
119 inet_dns:header(DnsHeader, Field) -> Value
120 query_type() = axfr | mailb | maila | any | dns_rr_type()
122 dns_query() = DnsQuery
124 inet_dns:dns_query(DnsQuery) ->
125 [ {domain, dns_name()}
126 | {type, query_type()}
127 | {class, dns_class()} ]
128 inet_dns:dns_query(DnsQuery, Field) -> Value
129 dns_rr() = DnsRr
131 inet_dns:rr(DnsRr) -> DnsRrFields | DnsRrOptFields
132 DnsRrFields = [ {domain, dns_name()}
133 | {type, dns_rr_type()}
134 | {class, dns_class()}
135 | {ttl, integer()}
136 | {data, dns_data()} ]
137 DnsRrOptFields = [ {domain, dns_name()}
138 | {type, opt}
139 | {udp_payload_size, integer()}
140 | {ext_rcode, integer()}
141 | {version, integer()}
142 | {z, integer()}
143 | {data, dns_data()} ]
144 inet_dns:rr(DnsRr, Field) -> Value
145 There is an information function for the types above:
147 inet_dns:record_type(dns_msg()) -> msg;
149 inet_dns:record_type(dns_header()) -> header;
150 inet_dns:record_type(dns_query()) -> dns_query;
151 inet_dns:record_type(dns_rr()) -> rr;
152 inet_dns:record_type(_) -> undefined.
153 So, inet_dns:(inet_dns:record_type(X))(X) converts any of these
155 data structures into a {Field,Value} list.
156 dns_data() =
158 dns_name() |
159 inet:ip4_address() |
160 inet:ip6_address() |
161 {MName :: dns_name(),
162 RName :: dns_name(),
163 Serial :: integer(),
164 Refresh :: integer(),
165 Retry :: integer(),
166 Expiry :: integer(),
167 Minimum :: integer()} |
168 {inet:ip4_address(), Proto :: integer(), BitMap :: binary()} |
169 {CpuString :: string(), OsString :: string()} |
170 {RM :: dns_name(), EM :: dns_name()} |
171 {Prio :: integer(), dns_name()} |
172 {Prio :: integer(),
173 Weight :: integer(),
174 Port :: integer(),
175 dns_name()} |
176 {Order :: integer(),
177 Preference :: integer(),
178 Flags :: string(),
179 Services :: string(),
180 Regexp :: string(),
181 dns_name()} |
182 [string()] |
183 binary()
184 Regexp is a string with characters encoded in the UTF-8 coding
186 standard.
187 hostent() =
189 {hostent,
190 H_name :: inet:hostname(),
191 H_aliases :: [inet:hostname()],
192 H_addrtype :: dns_rr_type(),
193 H_length :: integer() >= 0,
194 H_addr_list :: [dns_data()]}
195
197 getbyname(Name, Type) -> {ok, Hostent} | {error, Reason}
198 getbyname(Name, Type, Timeout) -> {ok, Hostent} | {error, Reason}
200 Types:
202 Name = dns_name()
204 Type = dns_rr_type()
205 Timeout = timeout()
206 Hostent = inet:hostent() | hostent()
207 Reason = inet:posix() | res_error()
208 Resolves a DNS record of the specified Type for the specified
210 host, of class in. Returns, on success, when resolving a Type =
211 a|aaaa DNS record, a #hostent{} record with #hostent.h_addrtype
212 = inet|inet6, respectively; see inet:hostent().
213 When resolving other Type = dns_rr_type():s (of class in), also
215 returns a #hostent{} record but with dns_rr_type() in #hos‐
216 tent.h_addrtype, and the resolved dns_data() in #hos‐
217 tent.h_addr_list; see hostent().
218 This function uses resolver option search that is a list of do‐
220 main names. If the name to resolve contains no dots, it is
221 prepended to each domain name in the search list, and they are
222 tried in order. If the name contains dots, it is first tried as
223 an absolute name and if that fails, the search list is used. If
224 the name has a trailing dot, it is supposed to be an absolute
225 name and the search list is not used.
226 gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}
228 gethostbyaddr(Address, Timeout) -> {ok, Hostent} | {error, Reason}
230 Types:
232 Address = inet:ip_address()
234 Timeout = timeout()
235 Hostent = inet:hostent()
236 Reason = inet:posix() | res_error()
237 Backend functions used by inet:gethostbyaddr/1.
239 gethostbyname(Name) -> {ok, Hostent} | {error, Reason}
241 gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}
243 gethostbyname(Name, Family, Timeout) ->
245 {ok, Hostent} | {error, Reason}
246 Types:
248 Name = dns_name()
250 Hostent = inet:hostent()
251 Timeout = timeout()
252 Family = inet:address_family()
253 Reason = inet:posix() | res_error()
254 Backend functions used by inet:gethostbyname/1,2.
256 This function uses resolver option search just like getby‐
258 name/2,3.
259 If resolver option inet6 is true, an IPv6 address is looked up.
261 lookup(Name, Class, Type) -> [dns_data()]
263 lookup(Name, Class, Type, Opts) -> [dns_data()]
265 lookup(Name, Class, Type, Opts, Timeout) -> [dns_data()]
267 Types:
269 Name = dns_name() | inet:ip_address()
271 Class = dns_class()
272 Type = dns_rr_type()
273 Opts = [res_option() | verbose]
274 Timeout = timeout()
275 Resolves the DNS data for the record of the specified type and
277 class for the specified name. On success, filters out the answer
278 records with the correct Class and Type, and returns a list of
279 their data fields. So, a lookup for type any gives an empty an‐
280 swer, as the answer records have specific types that are not
281 any. An empty answer or a failed lookup returns an empty list.
282 Calls resolve/* with the same arguments and filters the result,
284 so Opts is described for those functions.
285 resolve(Name, Class, Type) -> {ok, dns_msg()} | Error
287 resolve(Name, Class, Type, Opts) -> {ok, dns_msg()} | Error
289 resolve(Name, Class, Type, Opts, Timeout) ->
291 {ok, dns_msg()} | Error
292 Types:
294 Name = dns_name() | inet:ip_address()
296 Class = dns_class()
297 Type = dns_rr_type()
298 Opts = [Opt]
299 Opt = res_option() | verbose | atom()
300 Timeout = timeout()
301 Error = {error, Reason} | {error, {Reason, dns_msg()}}
302 Reason = inet:posix() | res_error()
303 Resolves a DNS record of the specified type and class for the
305 specified name. The returned dns_msg() can be examined using ac‐
306 cess functions in inet_db, as described in section in DNS Types.
307 If Name is an ip_address(), the domain name to query for is gen‐
309 erated as the standard reverse ".IN-ADDR.ARPA." name for an IPv4
310 address, or the ".IP6.ARPA." name for an IPv6 address. In this
311 case, you most probably want to use Class = in and Type = ptr,
312 but it is not done automatically.
313 Opts overrides the corresponding resolver options. If option
315 nameservers is specified, it is assumed that it is the complete
316 list of name serves, so resolver option alt_nameserves is ig‐
317 nored. However, if option alt_nameserves is also specified to
318 this function, it is used.
319 Option verbose (or rather {verbose,true}) causes diagnostics
321 printout through io:format/2 of queries, replies retransmis‐
322 sions, and so on, similar to from utilities, such as dig and
323 nslookup.
324 Option nxdomain_reply (or rather {nxdomain_reply,true}) causes
326 nxdomain errors from DNS servers to be returned as {error, {nx‐
327 domain, dns_msg()}}. dns_msg() contains the additional sections
328 that where included by the answering server. This is mainly use‐
329 ful to inspect the SOA record to get the TTL for negative
330 caching.
331 If Opt is any atom, it is interpreted as {Opt,true} unless the
333 atom string starts with "no", making the interpretation
334 {Opt,false}. For example, usevc is an alias for {usevc,true} and
335 nousevc is an alias for {usevc,false}.
336 Option inet6 has no effect on this function. You probably want
338 to use Type = a | aaaa instead.
339
341 This access functions example shows how lookup/3 can be implemented us‐
342 ing resolve/3 from outside the module:
343 example_lookup(Name, Class, Type) ->
345 case inet_res:resolve(Name, Class, Type) of
346 {ok,Msg} ->
347 [inet_dns:rr(RR, data)
348 || RR <- inet_dns:msg(Msg, anlist),
349 inet_dns:rr(RR, type) =:= Type,
350 inet_dns:rr(RR, class) =:= Class];
351 {error,_} ->
352 []
353 end.
354
356 These are deprecated because the annoying double meaning of the name
357 servers/time-out argument, and because they have no decent place for a
358 resolver options list.
359
361 nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason}
362 nslookup(Name, Class, Type, Timeout) ->
364 {ok, dns_msg()} | {error, Reason}
365 nslookup(Name, Class, Type, Nameservers) ->
367 {ok, dns_msg()} | {error, Reason}
368 Types:
370 Name = dns_name() | inet:ip_address()
372 Class = dns_class()
373 Type = dns_rr_type()
374 Timeout = timeout()
375 Nameservers = [nameserver()]
376 Reason = inet:posix() | res_error()
377 Resolves a DNS record of the specified type and class for the
379 specified name.
380 nnslookup(Name, Class, Type, Nameservers) ->
382 {ok, dns_msg()} | {error, Reason}
383 nnslookup(Name, Class, Type, Nameservers, Timeout) ->
385 {ok, dns_msg()} | {error, Reason}
386 Types:
388 Name = dns_name() | inet:ip_address()
390 Class = dns_class()
391 Type = dns_rr_type()
392 Timeout = timeout()
393 Nameservers = [nameserver()]
394 Reason = inet:posix()
395 Resolves a DNS record of the specified type and class for the
397 specified name.
398Ericsson AB kernel 8.5.3 inet_res(3)