1inet_res(3)                Erlang Module Definition                inet_res(3)
2
3
4

NAME

6       inet_res - A rudimentary DNS client.
7

DESCRIPTION

9       This module performs DNS name resolving to recursive name servers.
10
11       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
17       This DNS client can resolve DNS records even if it is not used for nor‐
18       mal name resolving in the node.
19
20       This is not a full-fledged resolver, only a DNS client that  relies  on
21       asking trusted recursive name servers.
22

NAME RESOLVING

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
28       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
37       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
42       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
50       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

RESOLVER TYPES

55       The following data types concern the resolver:
56

DATA TYPES

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
69       nameserver() = {inet:ip_address(), Port :: 1..65535}
70
71       res_error() =
72           formerr | qfmterror | servfail | nxdomain | notimp | refused |
73           badvers | timeout
74

DNS TYPES

76       The following data types concern the DNS client:
77

DATA TYPES

79       dns_name() = string()
80
81              A string with no adjacent dots.
82
83       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
88       dns_class() = in | chaos | hs | any
89
90       dns_msg() = term()
91
92              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
97              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
107              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
120              query_type() = axfr | mailb | maila | any | rr_type()
121
122              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
129              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
145              There is an information function for the types above:
146
147              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
153              So, inet_dns:(inet_dns:record_type(X))(X) converts any of  these
154              data structures into a {Field,Value} list.
155
156       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
184              Regexp  is  a string with characters encoded in the UTF-8 coding
185              standard.
186

EXPORTS

188       getbyname(Name, Type) -> {ok, Hostent} | {error, Reason}
189
190       getbyname(Name, Type, Timeout) -> {ok, Hostent} | {error, Reason}
191
192              Types:
193
194                 Name = dns_name()
195                 Type = rr_type()
196                 Timeout = timeout()
197                 Hostent = inet:hostent()
198                 Reason = inet:posix() | res_error()
199
200              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
204              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
212       gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}
213
214       gethostbyaddr(Address, Timeout) -> {ok, Hostent} | {error, Reason}
215
216              Types:
217
218                 Address = inet:ip_address()
219                 Timeout = timeout()
220                 Hostent = inet:hostent()
221                 Reason = inet:posix() | res_error()
222
223              Backend functions used by inet:gethostbyaddr/1.
224
225       gethostbyname(Name) -> {ok, Hostent} | {error, Reason}
226
227       gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}
228
229       gethostbyname(Name, Family, Timeout) ->
230                        {ok, Hostent} | {error, Reason}
231
232              Types:
233
234                 Name = dns_name()
235                 Hostent = inet:hostent()
236                 Timeout = timeout()
237                 Family = inet:address_family()
238                 Reason = inet:posix() | res_error()
239
240              Backend functions used by inet:gethostbyname/1,2.
241
242              This function uses  resolver  option  search  just  like  getby‐
243              name/2,3.
244
245              If resolver option inet6 is true, an IPv6 address is looked up.
246
247       lookup(Name, Class, Type) -> [dns_data()]
248
249       lookup(Name, Class, Type, Opts) -> [dns_data()]
250
251       lookup(Name, Class, Type, Opts, Timeout) -> [dns_data()]
252
253              Types:
254
255                 Name = dns_name() | inet:ip_address()
256                 Class = dns_class()
257                 Type = rr_type()
258                 Opts = [res_option() | verbose]
259                 Timeout = timeout()
260
261              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
268              Calls resolve/* with the same arguments and filters the  result,
269              so Opts is described for those functions.
270
271       resolve(Name, Class, Type) -> {ok, dns_msg()} | Error
272
273       resolve(Name, Class, Type, Opts) -> {ok, dns_msg()} | Error
274
275       resolve(Name, Class, Type, Opts, Timeout) ->
276                  {ok, dns_msg()} | Error
277
278              Types:
279
280                 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
289              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
293              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
299              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
305              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
310              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
315              Option  inet6  has no effect on this function. You probably want
316              to use Type = a | aaaa instead.
317

EXAMPLE

319       This access functions example shows how lookup/3 can be implemented us‐
320       ing resolve/3 from outside the module:
321
322       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

LEGACY FUNCTIONS

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

EXPORTS

339       nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason}
340
341       nslookup(Name, Class, Type, Timeout) ->
342                   {ok, dns_msg()} | {error, Reason}
343
344       nslookup(Name, Class, Type, Nameservers) ->
345                   {ok, dns_msg()} | {error, Reason}
346
347              Types:
348
349                 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
356              Resolves  a  DNS  record of the specified type and class for the
357              specified name.
358
359       nnslookup(Name, Class, Type, Nameservers) ->
360                    {ok, dns_msg()} | {error, Reason}
361
362       nnslookup(Name, Class, Type, Nameservers, Timeout) ->
363                    {ok, dns_msg()} | {error, Reason}
364
365              Types:
366
367                 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
374              Resolves a DNS record of the specified type and  class  for  the
375              specified name.
376
377
378
379Ericsson AB                     kernel 7.3.1.1                     inet_res(3)
Impressum