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 For queries not using the search list, if the query to all nameservers
43 results in {error,nxdomain} or an empty answer, the same query is tried
44 for alt_nameservers.
45
47 The following data types concern the resolver:
48
50 res_option() =
51 {alt_nameservers, [nameserver()]} |
52 {edns, 0 | false} |
53 {inet6, boolean()} |
54 {nameservers, [nameserver()]} |
55 {recurse, boolean()} |
56 {retry, integer()} |
57 {timeout, integer()} |
58 {udp_payload_size, integer()} |
59 {usevc, boolean()}
60 nameserver() = {inet:ip_address(), Port :: 1..65535}
62 res_error() =
64 formerr | qfmterror | servfail | nxdomain | notimp | refused |
65 badvers | timeout
66
68 The following data types concern the DNS client:
69
71 dns_name() = string()
72 A string with no adjacent dots.
74 rr_type() =
76 a | aaaa | cname | gid | hinfo | ns | mb | md | mg | mf |
77 minfo | mx | naptr | null | ptr | soa | spf | srv | txt |
78 uid | uinfo | unspec | wks
79 dns_class() = in | chaos | hs | any
81 dns_msg() = term()
83 This is the start of a hiearchy of opaque data structures that
85 can be examined with access functions in inet_dns, which return
86 lists of {Field,Value} tuples. The arity 2 functions only return
87 the value for a specified field.
88 dns_msg() = DnsMsg
90 inet_dns:msg(DnsMsg) ->
91 [ {header, dns_header()}
92 | {qdlist, dns_query()}
93 | {anlist, dns_rr()}
94 | {nslist, dns_rr()}
95 | {arlist, dns_rr()} ]
96 inet_dns:msg(DnsMsg, header) -> dns_header() % for example
97 inet_dns:msg(DnsMsg, Field) -> Value
98 dns_header() = DnsHeader
100 inet_dns:header(DnsHeader) ->
101 [ {id, integer()}
102 | {qr, boolean()}
103 | {opcode, query | iquery | status | integer()}
104 | {aa, boolean()}
105 | {tc, boolean()}
106 | {rd, boolean()}
107 | {ra, boolean()}
108 | {pr, boolean()}
109 | {rcode, integer(0..16)} ]
110 inet_dns:header(DnsHeader, Field) -> Value
111 query_type() = axfr | mailb | maila | any | rr_type()
113 dns_query() = DnsQuery
115 inet_dns:dns_query(DnsQuery) ->
116 [ {domain, dns_name()}
117 | {type, query_type()}
118 | {class, dns_class()} ]
119 inet_dns:dns_query(DnsQuery, Field) -> Value
120 dns_rr() = DnsRr
122 inet_dns:rr(DnsRr) -> DnsRrFields | DnsRrOptFields
123 DnsRrFields = [ {domain, dns_name()}
124 | {type, rr_type()}
125 | {class, dns_class()}
126 | {ttl, integer()}
127 | {data, dns_data()} ]
128 DnsRrOptFields = [ {domain, dns_name()}
129 | {type, opt}
130 | {udp_payload_size, integer()}
131 | {ext_rcode, integer()}
132 | {version, integer()}
133 | {z, integer()}
134 | {data, dns_data()} ]
135 inet_dns:rr(DnsRr, Field) -> Value
136 There is an information function for the types above:
138 inet_dns:record_type(dns_msg()) -> msg;
140 inet_dns:record_type(dns_header()) -> header;
141 inet_dns:record_type(dns_query()) -> dns_query;
142 inet_dns:record_type(dns_rr()) -> rr;
143 inet_dns:record_type(_) -> undefined.
144 So, inet_dns:(inet_dns:record_type(X))(X) converts any of these
146 data structures into a {Field,Value} list.
147 dns_data() =
149 dns_name() |
150 inet:ip4_address() |
151 inet:ip6_address() |
152 {MName :: dns_name(),
153 RName :: dns_name(),
154 Serial :: integer(),
155 Refresh :: integer(),
156 Retry :: integer(),
157 Expiry :: integer(),
158 Minimum :: integer()} |
159 {inet:ip4_address(), Proto :: integer(), BitMap :: binary()} |
160 {CpuString :: string(), OsString :: string()} |
161 {RM :: dns_name(), EM :: dns_name()} |
162 {Prio :: integer(), dns_name()} |
163 {Prio :: integer(),
164 Weight :: integer(),
165 Port :: integer(),
166 dns_name()} |
167 {Order :: integer(),
168 Preference :: integer(),
169 Flags :: string(),
170 Services :: string(),
171 Regexp :: string(),
172 dns_name()} |
173 [string()] |
174 binary()
175 Regexp is a string with characters encoded in the UTF-8 coding
177 standard.
178
180 getbyname(Name, Type) -> {ok, Hostent} | {error, Reason}
181 getbyname(Name, Type, Timeout) -> {ok, Hostent} | {error, Reason}
183 Types:
185 Name = dns_name()
187 Type = rr_type()
188 Timeout = timeout()
189 Hostent = inet:hostent()
190 Reason = inet:posix() | res_error()
191 Resolves a DNS record of the specified type for the specified
193 host, of class in. Returns, on success, a hostent() record with
194 dns_data() elements in the address list field.
195 This function uses resolver option search that is a list of
197 domain names. If the name to resolve contains no dots, it is
198 prepended to each domain name in the search list, and they are
199 tried in order. If the name contains dots, it is first tried as
200 an absolute name and if that fails, the search list is used. If
201 the name has a trailing dot, it is supposed to be an absolute
202 name and the search list is not used.
203 gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}
205 gethostbyaddr(Address, Timeout) -> {ok, Hostent} | {error, Reason}
207 Types:
209 Address = inet:ip_address()
211 Timeout = timeout()
212 Hostent = inet:hostent()
213 Reason = inet:posix() | res_error()
214 Backend functions used by inet:gethostbyaddr/1.
216 gethostbyname(Name) -> {ok, Hostent} | {error, Reason}
218 gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}
220 gethostbyname(Name, Family, Timeout) ->
222 {ok, Hostent} | {error, Reason}
223 Types:
225 Name = dns_name()
227 Hostent = inet:hostent()
228 Timeout = timeout()
229 Family = inet:address_family()
230 Reason = inet:posix() | res_error()
231 Backend functions used by inet:gethostbyname/1,2.
233 This function uses resolver option search just like getby‐
235 name/2,3.
236 If resolver option inet6 is true, an IPv6 address is looked up.
238 lookup(Name, Class, Type) -> [dns_data()]
240 lookup(Name, Class, Type, Opts) -> [dns_data()]
242 lookup(Name, Class, Type, Opts, Timeout) -> [dns_data()]
244 Types:
246 Name = dns_name() | inet:ip_address()
248 Class = dns_class()
249 Type = rr_type()
250 Opts = [res_option() | verbose]
251 Timeout = timeout()
252 Resolves the DNS data for the record of the specified type and
254 class for the specified name. On success, filters out the answer
255 records with the correct Class and Type, and returns a list of
256 their data fields. So, a lookup for type any gives an empty
257 answer, as the answer records have specific types that are not
258 any. An empty answer or a failed lookup returns an empty list.
259 Calls resolve/* with the same arguments and filters the result,
261 so Opts is described for those functions.
262 resolve(Name, Class, Type) -> {ok, dns_msg()} | Error
264 resolve(Name, Class, Type, Opts) -> {ok, dns_msg()} | Error
266 resolve(Name, Class, Type, Opts, Timeout) ->
268 {ok, dns_msg()} | Error
269 Types:
271 Name = dns_name() | inet:ip_address()
273 Class = dns_class()
274 Type = rr_type()
275 Opts = [Opt]
276 Opt = res_option() | verbose | atom()
277 Timeout = timeout()
278 Error = {error, Reason} | {error, {Reason, dns_msg()}}
279 Reason = inet:posix() | res_error()
280 Resolves a DNS record of the specified type and class for the
282 specified name. The returned dns_msg() can be examined using
283 access functions in inet_db, as described in section in DNS
284 Types.
285 If Name is an ip_address(), the domain name to query for is gen‐
287 erated as the standard reverse ".IN-ADDR.ARPA." name for an IPv4
288 address, or the ".IP6.ARPA." name for an IPv6 address. In this
289 case, you most probably want to use Class = in and Type = ptr,
290 but it is not done automatically.
291 Opts overrides the corresponding resolver options. If option
293 nameservers is specified, it is assumed that it is the complete
294 list of name serves, so resolver option alt_nameserves is
295 ignored. However, if option alt_nameserves is also specified to
296 this function, it is used.
297 Option verbose (or rather {verbose,true}) causes diagnostics
299 printout through io:format/2 of queries, replies retransmis‐
300 sions, and so on, similar to from utilities, such as dig and
301 nslookup.
302 If Opt is any atom, it is interpreted as {Opt,true} unless the
304 atom string starts with "no", making the interpretation
305 {Opt,false}. For example, usevc is an alias for {usevc,true} and
306 nousevc is an alias for {usevc,false}.
307 Option inet6 has no effect on this function. You probably want
309 to use Type = a | aaaa instead.
310
312 This access functions example shows how lookup/3 can be implemented
313 using resolve/3 from outside the module:
314 example_lookup(Name, Class, Type) ->
316 case inet_res:resolve(Name, Class, Type) of
317 {ok,Msg} ->
318 [inet_dns:rr(RR, data)
319 || RR <- inet_dns:msg(Msg, anlist),
320 inet_dns:rr(RR, type) =:= Type,
321 inet_dns:rr(RR, class) =:= Class];
322 {error,_} ->
323 []
324 end.
325
327 These are deprecated because the annoying double meaning of the name
328 servers/time-out argument, and because they have no decent place for a
329 resolver options list.
330
332 nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason}
333 nslookup(Name, Class, Type, Timeout) ->
335 {ok, dns_msg()} | {error, Reason}
336 nslookup(Name, Class, Type, Nameservers) ->
338 {ok, dns_msg()} | {error, Reason}
339 Types:
341 Name = dns_name() | inet:ip_address()
343 Class = dns_class()
344 Type = rr_type()
345 Timeout = timeout()
346 Nameservers = [nameserver()]
347 Reason = inet:posix() | res_error()
348 Resolves a DNS record of the specified type and class for the
350 specified name.
351 nnslookup(Name, Class, Type, Nameservers) ->
353 {ok, dns_msg()} | {error, Reason}
354 nnslookup(Name, Class, Type, Nameservers, Timeout) ->
356 {ok, dns_msg()} | {error, Reason}
357 Types:
359 Name = dns_name() | inet:ip_address()
361 Class = dns_class()
362 Type = rr_type()
363 Timeout = timeout()
364 Nameservers = [nameserver()]
365 Reason = inet:posix()
366 Resolves a DNS record of the specified type and class for the
368 specified name.
369Ericsson AB kernel 6.5.2 inet_res(3)