{
  "source": "doc/api/dns.markdown",
  "modules": [
    {
      "textRaw": "DNS",
      "name": "dns",
      "stability": 3,
      "stabilityText": "Stable",
      "desc": "<p>Use <code>require(&#39;dns&#39;)</code> to access this module.\n\n</p>\n<p>This module contains functions that belong to two different categories:\n\n</p>\n<p>1) Functions that use the underlying operating system facilities to perform\nname resolution, and that do not necessarily do any network communication.\nThis category contains only one function: <code>dns.lookup</code>. <strong>Developers looking\nto perform name resolution in the same way that other applications on the same\noperating system behave should use <code>dns.lookup</code>.</strong>\n\n</p>\n<p>Here is an example that does a lookup of <code>www.google.com</code>.\n\n</p>\n<pre><code>var dns = require(&#39;dns&#39;);\n\ndns.lookup(&#39;www.google.com&#39;, function onLookup(err, addresses, family) {\n  console.log(&#39;addresses:&#39;, addresses);\n});</code></pre>\n<p>2) Functions that connect to an actual DNS server to perform name resolution,\nand that <em>always</em> use the network to perform DNS queries. This category\ncontains all functions in the <code>dns</code> module but <code>dns.lookup</code>. These functions\ndo not use the same set of configuration files than what <code>dns.lookup</code> uses.\nFor instance, <em>they do not use the configuration from <code>/etc/hosts</code></em>. These\nfunctions should be used by developers who do not want to use the underlying\noperating system&#39;s facilities for name resolution, and instead want to\n<em>always</em> perform DNS queries.\n\n</p>\n<p>Here is an example which resolves <code>&#39;www.google.com&#39;</code> then reverse\nresolves the IP addresses which are returned.\n\n</p>\n<pre><code>var dns = require(&#39;dns&#39;);\n\ndns.resolve4(&#39;www.google.com&#39;, function (err, addresses) {\n  if (err) throw err;\n\n  console.log(&#39;addresses: &#39; + JSON.stringify(addresses));\n\n  addresses.forEach(function (a) {\n    dns.reverse(a, function (err, domains) {\n      if (err) {\n        throw err;\n      }\n\n      console.log(&#39;reverse for &#39; + a + &#39;: &#39; + JSON.stringify(domains));\n    });\n  });\n});</code></pre>\n<p>There are subtle consequences in choosing one or another, please consult the\n<a href=\"#dns_implementation_considerations\">Implementation considerations section</a>\nfor more information.\n\n</p>\n",
      "methods": [
        {
          "textRaw": "dns.lookup(domain, [family], callback)",
          "type": "method",
          "name": "lookup",
          "desc": "<p>Resolves a domain (e.g. <code>&#39;google.com&#39;</code>) into the first found A (IPv4) or\nAAAA (IPv6) record.\nThe <code>family</code> can be the integer <code>4</code> or <code>6</code>. Defaults to <code>null</code> that indicates\nboth Ip v4 and v6 address family.\n\n</p>\n<p>The callback has arguments <code>(err, address, family)</code>.  The <code>address</code> argument\nis a string representation of a IP v4 or v6 address. The <code>family</code> argument\nis either the integer 4 or 6 and denotes the family of <code>address</code> (not\nnecessarily the value initially passed to <code>lookup</code>).\n\n</p>\n<p>On error, <code>err</code> is an <code>Error</code> object, where <code>err.code</code> is the error code.\nKeep in mind that <code>err.code</code> will be set to <code>&#39;ENOENT&#39;</code> not only when\nthe domain does not exist but also when the lookup fails in other ways\nsuch as no available file descriptors.\n\n</p>\n<p><code>dns.lookup</code> doesn&#39;t necessarily have anything to do with the DNS protocol.\nIt&#39;s only an operating system facility that can associate name with addresses,\nand vice versa.\n\n</p>\n<p>Its implementation can have subtle but important consequences on the behavior\nof any Node.js program. Please take some time to consult the <a href=\"#dns_implementation_considerations\">Implementation\nconsiderations section</a> before using it.\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "domain"
                },
                {
                  "name": "family",
                  "optional": true
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "dns.resolve(domain, [rrtype], callback)",
          "type": "method",
          "name": "resolve",
          "desc": "<p>Resolves a domain (e.g. <code>&#39;google.com&#39;</code>) into an array of the record types\nspecified by rrtype. Valid rrtypes are <code>&#39;A&#39;</code> (IPV4 addresses, default),\n<code>&#39;AAAA&#39;</code> (IPV6 addresses), <code>&#39;MX&#39;</code> (mail exchange records), <code>&#39;TXT&#39;</code> (text\nrecords), <code>&#39;SRV&#39;</code> (SRV records), <code>&#39;PTR&#39;</code> (used for reverse IP lookups),\n<code>&#39;NS&#39;</code> (name server records) and <code>&#39;CNAME&#39;</code> (canonical name records).\n\n</p>\n<p>The callback has arguments <code>(err, addresses)</code>.  The type of each item\nin <code>addresses</code> is determined by the record type, and described in the\ndocumentation for the corresponding lookup methods below.\n\n</p>\n<p>On error, <code>err</code> is an <code>Error</code> object, where <code>err.code</code> is\none of the error codes listed below.\n\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "domain"
                },
                {
                  "name": "rrtype",
                  "optional": true
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "dns.resolve4(domain, callback)",
          "type": "method",
          "name": "resolve4",
          "desc": "<p>The same as <code>dns.resolve()</code>, but only for IPv4 queries (<code>A</code> records).\n<code>addresses</code> is an array of IPv4 addresses (e.g.\n<code>[&#39;74.125.79.104&#39;, &#39;74.125.79.105&#39;, &#39;74.125.79.106&#39;]</code>).\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "domain"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "dns.resolve6(domain, callback)",
          "type": "method",
          "name": "resolve6",
          "desc": "<p>The same as <code>dns.resolve4()</code> except for IPv6 queries (an <code>AAAA</code> query).\n\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "domain"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "dns.resolveMx(domain, callback)",
          "type": "method",
          "name": "resolveMx",
          "desc": "<p>The same as <code>dns.resolve()</code>, but only for mail exchange queries (<code>MX</code> records).\n\n</p>\n<p><code>addresses</code> is an array of MX records, each with a priority and an exchange\nattribute (e.g. <code>[{&#39;priority&#39;: 10, &#39;exchange&#39;: &#39;mx.example.com&#39;},...]</code>).\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "domain"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "dns.resolveTxt(domain, callback)",
          "type": "method",
          "name": "resolveTxt",
          "desc": "<p>The same as <code>dns.resolve()</code>, but only for text queries (<code>TXT</code> records).\n<code>addresses</code> is an array of the text records available for <code>domain</code> (e.g.,\n<code>[&#39;v=spf1 ip4:0.0.0.0 ~all&#39;]</code>).\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "domain"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "dns.resolveSrv(domain, callback)",
          "type": "method",
          "name": "resolveSrv",
          "desc": "<p>The same as <code>dns.resolve()</code>, but only for service records (<code>SRV</code> records).\n<code>addresses</code> is an array of the SRV records available for <code>domain</code>. Properties\nof SRV records are priority, weight, port, and name (e.g.,\n<code>[{&#39;priority&#39;: 10, {&#39;weight&#39;: 5, &#39;port&#39;: 21223, &#39;name&#39;: &#39;service.example.com&#39;}, ...]</code>).\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "domain"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "dns.resolveNs(domain, callback)",
          "type": "method",
          "name": "resolveNs",
          "desc": "<p>The same as <code>dns.resolve()</code>, but only for name server records (<code>NS</code> records).\n<code>addresses</code> is an array of the name server records available for <code>domain</code>\n(e.g., <code>[&#39;ns1.example.com&#39;, &#39;ns2.example.com&#39;]</code>).\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "domain"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "dns.resolveCname(domain, callback)",
          "type": "method",
          "name": "resolveCname",
          "desc": "<p>The same as <code>dns.resolve()</code>, but only for canonical name records (<code>CNAME</code>\nrecords). <code>addresses</code> is an array of the canonical name records available for\n<code>domain</code> (e.g., <code>[&#39;bar.example.com&#39;]</code>).\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "domain"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "dns.reverse(ip, callback)",
          "type": "method",
          "name": "reverse",
          "desc": "<p>Reverse resolves an ip address to an array of domain names.\n\n</p>\n<p>The callback has arguments <code>(err, domains)</code>.\n\n</p>\n<p>On error, <code>err</code> is an <code>Error</code> object, where <code>err.code</code> is\none of the error codes listed below.\n\n</p>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "ip"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        }
      ],
      "modules": [
        {
          "textRaw": "Error codes",
          "name": "error_codes",
          "desc": "<p>Each DNS query can return one of the following error codes:\n\n</p>\n<ul>\n<li><code>dns.NODATA</code>: DNS server returned answer with no data.</li>\n<li><code>dns.FORMERR</code>: DNS server claims query was misformatted.</li>\n<li><code>dns.SERVFAIL</code>: DNS server returned general failure.</li>\n<li><code>dns.NOTFOUND</code>: Domain name not found.</li>\n<li><code>dns.NOTIMP</code>: DNS server does not implement requested operation.</li>\n<li><code>dns.REFUSED</code>: DNS server refused query.</li>\n<li><code>dns.BADQUERY</code>: Misformatted DNS query.</li>\n<li><code>dns.BADNAME</code>: Misformatted domain name.</li>\n<li><code>dns.BADFAMILY</code>: Unsupported address family.</li>\n<li><code>dns.BADRESP</code>: Misformatted DNS reply.</li>\n<li><code>dns.CONNREFUSED</code>: Could not contact DNS servers.</li>\n<li><code>dns.TIMEOUT</code>: Timeout while contacting DNS servers.</li>\n<li><code>dns.EOF</code>: End of file.</li>\n<li><code>dns.FILE</code>: Error reading file.</li>\n<li><code>dns.NOMEM</code>: Out of memory.</li>\n<li><code>dns.DESTRUCTION</code>: Channel is being destroyed.</li>\n<li><code>dns.BADSTR</code>: Misformatted string.</li>\n<li><code>dns.BADFLAGS</code>: Illegal flags specified.</li>\n<li><code>dns.NONAME</code>: Given hostname is not numeric.</li>\n<li><code>dns.BADHINTS</code>: Illegal hints flags specified.</li>\n<li><code>dns.NOTINITIALIZED</code>: c-ares library initialization not yet performed.</li>\n<li><code>dns.LOADIPHLPAPI</code>: Error loading iphlpapi.dll.</li>\n<li><code>dns.ADDRGETNETWORKPARAMS</code>: Could not find GetNetworkParams function.</li>\n<li><code>dns.CANCELLED</code>: DNS query cancelled.</li>\n</ul>\n",
          "type": "module",
          "displayName": "Error codes"
        },
        {
          "textRaw": "Implementation considerations",
          "name": "implementation_considerations",
          "desc": "<p>Although <code>dns.lookup</code> and <code>dns.resolve*/dns.reverse</code> functions have the same\ngoal of associating a network name with a network address (or vice versa),\ntheir behavior is quite different. These differences can have subtle but\nsignificant consequences on the behavior of Node.js programs.\n\n</p>\n",
          "properties": [
            {
              "textRaw": "dns.lookup",
              "name": "lookup",
              "desc": "<p>Under the hood, <code>dns.lookup</code> uses the same operating system facilities as most\nother programs. For instance, <code>dns.lookup</code> will almost always resolve a given\nname the same way as the <code>ping</code> command. On most POSIX-like operating systems,\nthe behavior of the <code>dns.lookup</code> function can be tweaked by changing settings\nin <code>nsswitch.conf(5)</code> and/or <code>resolv.conf(5)</code>, but be careful that changing\nthese files will change the behavior of all other programs running on the same\noperating system.\n\n</p>\n<p>Though the call will be asynchronous from JavaScript&#39;s perspective, it is\nimplemented as a synchronous call to <code>getaddrinfo(3)</code> that runs on libuv&#39;s\nthreadpool. Because libuv&#39;s threadpool has a fixed size, it means that if for\nwhatever reason the call to <code>getaddrinfo(3)</code> takes a long time, other\noperations that could run on libuv&#39;s threadpool (such as filesystem\noperations) will experience degraded performance. In order to mitigate this\nissue, one potential solution is to increase the size of libuv&#39;s threadpool by\nsetting the &#39;UV_THREADPOOL_SIZE&#39; environment variable to a value greater than\n4 (its current default value). For more information on libuv&#39;s threadpool, see\n<a href=\"http://docs.libuv.org/en/latest/threadpool.html\">the official libuv\ndocumentation</a>.\n\n</p>\n"
            }
          ],
          "modules": [
            {
              "textRaw": "dns.resolve, functions starting with dns.resolve and dns.reverse",
              "name": "dns.resolve,_functions_starting_with_dns.resolve_and_dns.reverse",
              "desc": "<p>These functions are implemented quite differently than <code>dns.lookup</code>. They do\nnot use <code>getaddrinfo(3)</code> and they <em>always</em> perform a DNS query on the network.\nThis network communication is always done asynchronously, and does not use\nlibuv&#39;s threadpool.\n\n</p>\n<p>As a result, these functions cannot have the same negative impact on other\nprocessing that happens on libuv&#39;s threadpool that <code>dns.lookup</code> can have.\n\n</p>\n<p>They do not use the same set of configuration files than what <code>dns.lookup</code>\nuses. For instance, <em>they do not use the configuration from <code>/etc/hosts</code></em>.\n</p>\n",
              "type": "module",
              "displayName": "dns.resolve, functions starting with dns.resolve and dns.reverse"
            }
          ],
          "type": "module",
          "displayName": "Implementation considerations"
        }
      ],
      "type": "module",
      "displayName": "DNS"
    }
  ]
}