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       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

RESOLVER TYPES

47       The following data types concern the resolver:
48

DATA TYPES

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
61       nameserver() = {inet:ip_address(), Port :: 1..65535}
62
63       res_error() =
64           formerr | qfmterror | servfail | nxdomain | notimp | refused |
65           badvers | timeout
66

DNS TYPES

68       The following data types concern the DNS client:
69

DATA TYPES

71       dns_name() = string()
72
73              A string with no adjacent dots.
74
75       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
80       dns_class() = in | chaos | hs | any
81
82       dns_msg() = term()
83
84              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
89              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
99              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
112              query_type() = axfr | mailb | maila | any | rr_type()
113
114              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
121              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
137              There is an information function for the types above:
138
139              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
145              So, inet_dns:(inet_dns:record_type(X))(X) converts any of  these
146              data structures into a {Field,Value} list.
147
148       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
176              Regexp  is  a string with characters encoded in the UTF-8 coding
177              standard.
178

EXPORTS

180       getbyname(Name, Type) -> {ok, Hostent} | {error, Reason}
181
182       getbyname(Name, Type, Timeout) -> {ok, Hostent} | {error, Reason}
183
184              Types:
185
186                 Name = dns_name()
187                 Type = rr_type()
188                 Timeout = timeout()
189                 Hostent = inet:hostent()
190                 Reason = inet:posix() | res_error()
191
192              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
196              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
204       gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}
205
206       gethostbyaddr(Address, Timeout) -> {ok, Hostent} | {error, Reason}
207
208              Types:
209
210                 Address = inet:ip_address()
211                 Timeout = timeout()
212                 Hostent = inet:hostent()
213                 Reason = inet:posix() | res_error()
214
215              Backend functions used by inet:gethostbyaddr/1.
216
217       gethostbyname(Name) -> {ok, Hostent} | {error, Reason}
218
219       gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}
220
221       gethostbyname(Name, Family, Timeout) ->
222                        {ok, Hostent} | {error, Reason}
223
224              Types:
225
226                 Name = dns_name()
227                 Hostent = inet:hostent()
228                 Timeout = timeout()
229                 Family = inet:address_family()
230                 Reason = inet:posix() | res_error()
231
232              Backend functions used by inet:gethostbyname/1,2.
233
234              This function uses  resolver  option  search  just  like  getby‐
235              name/2,3.
236
237              If resolver option inet6 is true, an IPv6 address is looked up.
238
239       lookup(Name, Class, Type) -> [dns_data()]
240
241       lookup(Name, Class, Type, Opts) -> [dns_data()]
242
243       lookup(Name, Class, Type, Opts, Timeout) -> [dns_data()]
244
245              Types:
246
247                 Name = dns_name() | inet:ip_address()
248                 Class = dns_class()
249                 Type = rr_type()
250                 Opts = [res_option() | verbose]
251                 Timeout = timeout()
252
253              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
260              Calls resolve/* with the same arguments and filters the  result,
261              so Opts is described for those functions.
262
263       resolve(Name, Class, Type) -> {ok, dns_msg()} | Error
264
265       resolve(Name, Class, Type, Opts) -> {ok, dns_msg()} | Error
266
267       resolve(Name, Class, Type, Opts, Timeout) ->
268                  {ok, dns_msg()} | Error
269
270              Types:
271
272                 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
281              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
286              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
292              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
298              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
303              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
308              Option inet6 has no effect on this function. You  probably  want
309              to use Type = a | aaaa instead.
310

EXAMPLE

312       This  access  functions  example  shows how lookup/3 can be implemented
313       using resolve/3 from outside the module:
314
315       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

LEGACY FUNCTIONS

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

EXPORTS

332       nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason}
333
334       nslookup(Name, Class, Type, Timeout) ->
335                   {ok, dns_msg()} | {error, Reason}
336
337       nslookup(Name, Class, Type, Nameservers) ->
338                   {ok, dns_msg()} | {error, Reason}
339
340              Types:
341
342                 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
349              Resolves a DNS record of the specified type and  class  for  the
350              specified name.
351
352       nnslookup(Name, Class, Type, Nameservers) ->
353                    {ok, dns_msg()} | {error, Reason}
354
355       nnslookup(Name, Class, Type, Nameservers, Timeout) ->
356                    {ok, dns_msg()} | {error, Reason}
357
358              Types:
359
360                 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
367              Resolves  a  DNS  record of the specified type and class for the
368              specified name.
369
370
371
372Ericsson AB                      kernel 6.5.2                      inet_res(3)
Impressum