Provided by: erlang-manpages_22.0.7+dfsg-1build1_all bug

NAME

       inet_res - A rudimentary DNS client.

DESCRIPTION

       This module performs DNS name resolving to recursive name servers.

       See also ERTS User's Guide: Inet Configuration for more information about how to configure
       an Erlang runtime system for IP communication, and  how  to  enable  this  DNS  client  by
       defining 'dns' as a lookup method. The DNS client then acts as a backend for the resolving
       functions in inet.

       This DNS client can resolve DNS records even if it is not used for normal  name  resolving
       in the node.

       This  is  not  a  full-fledged  resolver,  only a DNS client that relies on asking trusted
       recursive name servers.

NAME RESOLVING

       UDP queries are used unless resolver option usevc is true, which forces  TCP  queries.  If
       the query is too large for UDP, TCP is used instead. For regular DNS queries, 512 bytes is
       the size limit.

       When EDNS is enabled (resolver option edns is set to the EDNS version (that is, 0  instead
       of  false), resolver option udp_payload_size sets the limit. If a name server replies with
       the TC bit set (truncation), indicating that  the  answer  is  incomplete,  the  query  is
       retried  to  that  name  server  using TCP. Resolver option udp_payload_size also sets the
       advertised size for the maximum allowed reply size, if EDNS is enabled, otherwise the name
       server  uses the limit 512 bytes. If the reply is larger, it gets truncated, forcing a TCP
       requery.

       For UDP queries, resolver options timeout and  retry  control  retransmission.  Each  name
       server  in  the  nameservers list is tried with a time-out of timeout/retry. Then all name
       servers are tried again, doubling the time-out, for a total of retry times.

       For queries not using the search  list,  if  the  query  to  all  nameservers  results  in
       {error,nxdomain} or an empty answer, the same query is tried for alt_nameservers.

RESOLVER TYPES

       The following data types concern the resolver:

DATA TYPES

       res_option() =
           {alt_nameservers, [nameserver()]} |
           {edns, 0 | false} |
           {inet6, boolean()} |
           {nameservers, [nameserver()]} |
           {recurse, boolean()} |
           {retry, integer()} |
           {timeout, integer()} |
           {udp_payload_size, integer()} |
           {usevc, boolean()}

       nameserver() = {inet:ip_address(), Port :: 1..65535}

       res_error() =
           formerr | qfmterror | servfail | nxdomain | notimp | refused |
           badvers | timeout

DNS TYPES

       The following data types concern the DNS client:

DATA TYPES

       dns_name() = string()

              A string with no adjacent dots.

       rr_type() =
           a | aaaa | cname | gid | hinfo | ns | mb | md | mg | mf |
           minfo | mx | naptr | null | ptr | soa | spf | srv | txt |
           uid | uinfo | unspec | wks

       dns_class() = in | chaos | hs | any

       dns_msg() = term()

              This is the start of a hiearchy of opaque data structures that can be examined with
              access functions in inet_dns, which return lists of {Field,Value} tuples. The arity
              2 functions only return the value for a specified field.

              dns_msg() = DnsMsg
                  inet_dns:msg(DnsMsg) ->
                      [ {header, dns_header()}
                      | {qdlist, dns_query()}
                      | {anlist, dns_rr()}
                      | {nslist, dns_rr()}
                      | {arlist, dns_rr()} ]
                  inet_dns:msg(DnsMsg, header) -> dns_header() % for example
                  inet_dns:msg(DnsMsg, Field) -> Value

              dns_header() = DnsHeader
                  inet_dns:header(DnsHeader) ->
                      [ {id, integer()}
                      | {qr, boolean()}
                      | {opcode, query | iquery | status | integer()}
                      | {aa, boolean()}
                      | {tc, boolean()}
                      | {rd, boolean()}
                      | {ra, boolean()}
                      | {pr, boolean()}
                      | {rcode, integer(0..16)} ]
                  inet_dns:header(DnsHeader, Field) -> Value

              query_type() = axfr | mailb | maila | any | rr_type()

              dns_query() = DnsQuery
                  inet_dns:dns_query(DnsQuery) ->
                      [ {domain, dns_name()}
                      | {type, query_type()}
                      | {class, dns_class()} ]
                  inet_dns:dns_query(DnsQuery, Field) -> Value

              dns_rr() = DnsRr
                  inet_dns:rr(DnsRr) -> DnsRrFields | DnsRrOptFields
                  DnsRrFields = [ {domain, dns_name()}
                                | {type, rr_type()}
                                | {class, dns_class()}
                                | {ttl, integer()}
                                | {data, dns_data()} ]
                  DnsRrOptFields = [ {domain, dns_name()}
                                   | {type, opt}
                                   | {udp_payload_size, integer()}
                                   | {ext_rcode, integer()}
                                   | {version, integer()}
                                   | {z, integer()}
                                   | {data, dns_data()} ]
                  inet_dns:rr(DnsRr, Field) -> Value

              There is an information function for the types above:

              inet_dns:record_type(dns_msg()) -> msg;
              inet_dns:record_type(dns_header()) -> header;
              inet_dns:record_type(dns_query()) -> dns_query;
              inet_dns:record_type(dns_rr()) -> rr;
              inet_dns:record_type(_) -> undefined.

              So,  inet_dns:(inet_dns:record_type(X))(X)  converts  any  of these data structures
              into a {Field,Value} list.

       dns_data() =
           dns_name() |
           inet:ip4_address() |
           inet:ip6_address() |
           {MName :: dns_name(),
            RName :: dns_name(),
            Serial :: integer(),
            Refresh :: integer(),
            Retry :: integer(),
            Expiry :: integer(),
            Minimum :: integer()} |
           {inet:ip4_address(), Proto :: integer(), BitMap :: binary()} |
           {CpuString :: string(), OsString :: string()} |
           {RM :: dns_name(), EM :: dns_name()} |
           {Prio :: integer(), dns_name()} |
           {Prio :: integer(),
            Weight :: integer(),
            Port :: integer(),
            dns_name()} |
           {Order :: integer(),
            Preference :: integer(),
            Flags :: string(),
            Services :: string(),
            Regexp :: string(),
            dns_name()} |
           [string()] |
           binary()

              Regexp is a string with characters encoded in the UTF-8 coding standard.

EXPORTS

       getbyname(Name, Type) -> {ok, Hostent} | {error, Reason}

       getbyname(Name, Type, Timeout) -> {ok, Hostent} | {error, Reason}

              Types:

                 Name = dns_name()
                 Type = rr_type()
                 Timeout = timeout()
                 Hostent = inet:hostent()
                 Reason = inet:posix() | res_error()

              Resolves a DNS record of the specified type for the specified host,  of  class  in.
              Returns,  on  success,  a  hostent() record with dns_data() elements in the address
              list field.

              This function uses resolver option search that is a list of domain  names.  If  the
              name to resolve contains no dots, it is prepended to each domain name in the search
              list, and they are tried in order. If the name contains dots, it is first tried  as
              an  absolute  name  and  if  that fails, the search list is used. If the name has a
              trailing dot, it is supposed to be an absolute name and  the  search  list  is  not
              used.

       gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}

       gethostbyaddr(Address, Timeout) -> {ok, Hostent} | {error, Reason}

              Types:

                 Address = inet:ip_address()
                 Timeout = timeout()
                 Hostent = inet:hostent()
                 Reason = inet:posix() | res_error()

              Backend functions used by inet:gethostbyaddr/1.

       gethostbyname(Name) -> {ok, Hostent} | {error, Reason}

       gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}

       gethostbyname(Name, Family, Timeout) ->
                        {ok, Hostent} | {error, Reason}

              Types:

                 Name = dns_name()
                 Hostent = inet:hostent()
                 Timeout = timeout()
                 Family = inet:address_family()
                 Reason = inet:posix() | res_error()

              Backend functions used by inet:gethostbyname/1,2.

              This function uses resolver option search just like getbyname/2,3.

              If resolver option inet6 is true, an IPv6 address is looked up.

       lookup(Name, Class, Type) -> [dns_data()]

       lookup(Name, Class, Type, Opts) -> [dns_data()]

       lookup(Name, Class, Type, Opts, Timeout) -> [dns_data()]

              Types:

                 Name = dns_name() | inet:ip_address()
                 Class = dns_class()
                 Type = rr_type()
                 Opts = [res_option() | verbose]
                 Timeout = timeout()

              Resolves  the  DNS  data  for  the  record  of the specified type and class for the
              specified name. On success, filters out the answer records with the  correct  Class
              and  Type, and returns a list of their data fields. So, a lookup for type any gives
              an empty answer, as the answer records have specific types that  are  not  any.  An
              empty answer or a failed lookup returns an empty list.

              Calls  resolve/*  with  the  same  arguments  and  filters  the  result, so Opts is
              described for those functions.

       resolve(Name, Class, Type) -> {ok, dns_msg()} | Error

       resolve(Name, Class, Type, Opts) -> {ok, dns_msg()} | Error

       resolve(Name, Class, Type, Opts, Timeout) ->
                  {ok, dns_msg()} | Error

              Types:

                 Name = dns_name() | inet:ip_address()
                 Class = dns_class()
                 Type = rr_type()
                 Opts = [Opt]
                 Opt = res_option() | verbose | atom()
                 Timeout = timeout()
                 Error = {error, Reason} | {error, {Reason, dns_msg()}}
                 Reason = inet:posix() | res_error()

              Resolves a DNS record of the specified type and class for the specified  name.  The
              returned  dns_msg() can be examined using access functions in inet_db, as described
              in section in DNS Types.

              If Name is an ip_address(), the domain name  to  query  for  is  generated  as  the
              standard  reverse  ".IN-ADDR.ARPA."  name  for an IPv4 address, or the ".IP6.ARPA."
              name for an IPv6 address. In this case, you most probably want to use  Class  =  in
              and Type = ptr, but it is not done automatically.

              Opts  overrides  the  corresponding  resolver  options.  If  option  nameservers is
              specified, it is assumed that it is the complete list of name serves,  so  resolver
              option  alt_nameserves  is  ignored.  However,  if  option  alt_nameserves  is also
              specified to this function, it is used.

              Option verbose (or  rather  {verbose,true})  causes  diagnostics  printout  through
              io:format/2  of  queries,  replies  retransmissions,  and  so  on,  similar to from
              utilities, such as dig and nslookup.

              If Opt is any atom, it is interpreted as {Opt,true} unless the atom  string  starts
              with  "no",  making  the interpretation {Opt,false}. For example, usevc is an alias
              for {usevc,true} and nousevc is an alias for {usevc,false}.

              Option inet6 has no effect on this function. You probably want to use Type  =  a  |
              aaaa instead.

EXAMPLE

       This  access  functions example shows how lookup/3 can be implemented using resolve/3 from
       outside the module:

       example_lookup(Name, Class, Type) ->
           case inet_res:resolve(Name, Class, Type) of
               {ok,Msg} ->
                   [inet_dns:rr(RR, data)
                    || RR <- inet_dns:msg(Msg, anlist),
                        inet_dns:rr(RR, type) =:= Type,
                        inet_dns:rr(RR, class) =:= Class];
               {error,_} ->
                   []
            end.

LEGACY FUNCTIONS

       These are deprecated because the annoying double  meaning  of  the  name  servers/time-out
       argument, and because they have no decent place for a resolver options list.

EXPORTS

       nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason}

       nslookup(Name, Class, Type, Timeout) ->
                   {ok, dns_msg()} | {error, Reason}

       nslookup(Name, Class, Type, Nameservers) ->
                   {ok, dns_msg()} | {error, Reason}

              Types:

                 Name = dns_name() | inet:ip_address()
                 Class = dns_class()
                 Type = rr_type()
                 Timeout = timeout()
                 Nameservers = [nameserver()]
                 Reason = inet:posix() | res_error()

              Resolves a DNS record of the specified type and class for the specified name.

       nnslookup(Name, Class, Type, Nameservers) ->
                    {ok, dns_msg()} | {error, Reason}

       nnslookup(Name, Class, Type, Nameservers, Timeout) ->
                    {ok, dns_msg()} | {error, Reason}

              Types:

                 Name = dns_name() | inet:ip_address()
                 Class = dns_class()
                 Type = rr_type()
                 Timeout = timeout()
                 Nameservers = [nameserver()]
                 Reason = inet:posix()

              Resolves a DNS record of the specified type and class for the specified name.