<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.21 $ -->
  <refentry id="function.dns-get-record">
    <refnamediv>
     <refname>dns_get_record</refname>
     <refpurpose>
      Fetch DNS Resource Records associated with a hostname
     </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
      <methodsynopsis>
       <type>array</type><methodname>dns_get_record</methodname>
       <methodparam><type>string</type><parameter>hostname</parameter></methodparam>
       <methodparam choice="opt"><type>int</type><parameter>type</parameter></methodparam>
       <methodparam choice="opt"><type>array</type><parameter role="reference">authns</parameter></methodparam>
       <methodparam><type>array</type><parameter role="reference">addtl</parameter></methodparam>
      </methodsynopsis>
     <para>
      <note>
       <simpara>
        This function is not implemented on Windows platforms, nor does it
        (currently) work on *BSD systems. Try the 
        <ulink url="&url.php.pear;">PEAR</ulink> class 
        <ulink url="&url.pear.package;Net_DNS">Net_DNS</ulink>.
       </simpara>
      </note>
     </para>
     <para>
      This function returns an array of associative arrays.  Each associative array contains 
      <emphasis>at minimum</emphasis> the following keys:
      <table>
       <title>Basic DNS attributes</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Attribute</entry>
          <entry>Meaning</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>host</entry>
          <entry>
           The record in the DNS namespace to which the rest of the associated data refers.
          </entry>
         </row>
         <row>
          <entry>class</entry>
          <entry>
           <function>dns_get_record</function> only returns Internet class records and as
           such this parameter will always return <literal>IN</literal>.
          </entry>
         </row>
         <row>
          <entry>type</entry>
          <entry>
           String containing the record type.  Additional attributes will also be contained 
           in the resulting array dependant on the value of type. See table below.
          </entry>
         </row>
         <row>
          <entry>ttl</entry>
          <entry>
           Time To Live remaining for this record.  This will <emphasis>not</emphasis> equal
           the record's original ttl, but will rather equal the original ttl minus whatever
           length of time has passed since the authoritative name server was queried.
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
     <simpara>
      <parameter>hostname</parameter> should be a valid DNS hostname such 
      as "www.example.com".  Reverse lookups can be generated using in-addr.arpa
      notation, but <function>gethostbyaddr</function> is more suitable for
      the majority of reverse lookups.
     </simpara>
     <para>
      By default, <function>dns_get_record</function> will search for any resource
      records associated with <parameter>hostname</parameter>.  To limit the
      query, specify the optional <parameter>type</parameter> parameter.
      <parameter>type</parameter> may be any one of the following: 
      <constant>DNS_A</constant>, <constant>DNS_CNAME</constant>, 
      <constant>DNS_HINFO</constant>, <constant>DNS_MX</constant>, 
      <constant>DNS_NS</constant>, <constant>DNS_PTR</constant>, 
      <constant>DNS_SOA</constant>, <constant>DNS_TXT</constant>, 
      <constant>DNS_AAAA</constant>, <constant>DNS_SRV</constant>,
      <constant>DNS_NAPTR</constant>, <constant>DNS_A6</constant>,
      <constant>DNS_ALL</constant> or <constant>DNS_ANY</constant>.
      The default is <emphasis>DNS_ANY</emphasis>.  
      <note>
       <para>
        Because of eccentricities in the performance of libresolv 
        between platforms, <constant>DNS_ANY</constant> will not
        always return every record, the slower <constant>DNS_ALL</constant>
        will collect all records more reliably.
       </para>
      </note>
     </para>
     <simpara>
       The optional third and fourth arguments to this function,
       <parameter>authns</parameter> and <parameter>addtl</parameter>
       are passed by reference and, if given, will be populated with
       Resource Records for the <emphasis>Authoritative Name Servers</emphasis>,
       and any <emphasis>Additional Records</emphasis> respectively.
       See the example below.
     </simpara>
     <para>
      <table>
       <title>Other keys in associative arrays dependant on 'type'</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Type</entry>
          <entry>Extra Columns</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><literal>A</literal></entry>
          <entry>
           <literal>ip</literal>: An IPv4 addresses in dotted decimal notation.
          </entry>
         </row>
         <row>
          <entry><literal>MX</literal></entry>
          <entry>
           <literal>pri</literal>: Priority of mail exchanger.  
           Lower numbers indicate greater priority.
           <literal>target</literal>: FQDN of the mail exchanger.  
           See also <function>dns_get_mx</function>.
          </entry>
         </row>
         <row>
          <entry><literal>CNAME</literal></entry>
          <entry>
           <literal>target</literal>: FQDN of location in DNS namespace to which 
           the record is aliased.
          </entry>
         </row>
         <row>
          <entry><literal>NS</literal></entry>
          <entry>
           <literal>target</literal>: FQDN of the name server which is authoritative 
           for this hostname.
          </entry>
         </row>
         <row>
          <entry><literal>PTR</literal></entry>
          <entry>
           <literal>target</literal>: Location within the DNS namespace to which 
           this record points.
          </entry>
         </row>
          <row>
          <entry><literal>TXT</literal></entry>
          <entry>
           <literal>txt</literal>: Arbitrary string data associated with this record.
          </entry>
         </row>
         <row>
          <entry><literal>HINFO</literal></entry>
          <entry>
           <literal>cpu</literal>: IANA number designating the CPU of the machine 
           referenced by this record.
           <literal>os</literal>: IANA number designating the Operating System on 
           the machine referenced by this record.
           See IANA's <ulink url="&url.iana.system-names;">Operating System
           Names</ulink> for the meaning of these values.
          </entry>
         </row>
         <row> 
          <entry><literal>SOA</literal></entry>
          <entry>
           <literal>mname</literal>: FQDN of the machine from which the resource 
           records originated.
           <literal>rname</literal>: Email address of the administrative contain 
           for this domain.
           <literal>serial</literal>: Serial # of this revision of the requested 
           domain.
           <literal>refresh</literal>: Refresh interval (seconds) secondary name 
           servers should use when updating remote copies of this domain.
           <literal>retry</literal>: Length of time (seconds) to wait after a 
           failed refresh before making a second attempt.
           <literal>expire</literal>: Maximum length of time (seconds) a secondary 
           DNS server should retain remote copies of the zone data without a 
           successful refresh before discarding.
           <literal>minimum-ttl</literal>: Minimum length of time (seconds) a 
           client can continue to use a DNS resolution before it should request 
           a new resolution from the server.  Can be overridden by individual 
           resource records.          
          </entry>
         </row>
         <row>
          <entry><literal>AAAA</literal></entry>
          <entry>
           <literal>ipv6</literal>: IPv6 address
          </entry>
         </row>
         <row>
          <entry><literal>A6</literal>(PHP &gt;= 5.1.0)</entry>
          <entry>
           <literal>masklen</literal>: Length (in bits) to inherit from the target
           specified by <parameter>chain</parameter>.
           <literal>ipv6</literal>: Address for this specific record to merge with
           <parameter>chain</parameter>.
           <literal>chain</literal>: Parent record to merge with 
           <parameter>ipv6</parameter> data.
          </entry>
         </row>
         <row>
          <entry><literal>SRV</literal></entry>
          <entry>
           <literal>pri</literal>: (Priority) lowest priorities should be used first.
           <literal>weight</literal>: Ranking to weight which of commonly prioritized
           <parameter>targets</parameter> should be chosen at random.
           <literal>target</literal> and <literal>port</literal>: hostname and port 
           where the requested service can be found.
           For additional information see: <ulink url="&url.rfc;2782">RFC 2782</ulink>
          </entry>
         </row>
         <row>
          <entry><literal>NAPTR</literal></entry>
          <entry>
           <literal>order</literal> and <literal>pref</literal>: Equivalent to
           <parameter>pri</parameter> and <parameter>weight</parameter> above.
           <literal>flags</literal>, <literal>services</literal>, <literal>regex</literal>,
           and <literal>replacement</literal>: Parameters as defined by 
           <ulink url="&url.rfc;2915">RFC 2915</ulink>.
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
     <para>
      <note>
       <para>
        Per DNS standards, email addresses are given in user.host format (for
        example: hostmaster.example.com as opposed to hostmaster@example.com),
        be sure to check this value and modify if necessary before using it
        with a functions such as <function>mail</function>.
       </para>
      </note>
     </para>
     <example>
      <title>Using <function>dns_get_record</function></title>
      <programlisting role="php">
<![CDATA[
<?php
$result = dns_get_record("php.net");
print_r($result);
?>
]]>
      </programlisting>
      <para>
       Produces output similar to the following:
      </para>
      <screen>
<![CDATA[
Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => MX
            [pri] => 5
            [target] => pair2.php.net
            [class] => IN
            [ttl] => 6765
        )

    [1] => Array
        (
            [host] => php.net
            [type] => A
            [ip] => 64.246.30.37
            [class] => IN
            [ttl] => 8125
        )

)
]]>
      </screen>
     </example>
     <simpara>
      Since it's very common to want the IP address of a mail server
      once the MX record has been resolved, <function>dns_get_record</function>
      also returns an array in <parameter>addtl</parameter> which
      contains associate records.  <parameter>authns</parameter>
      is returned as well containing a list of authoritative name
      servers.
     </simpara>
     <example>
      <title>Using <function>dns_get_record</function> and DNS_ANY</title>
      <programlisting role="php">
<![CDATA[
<?php
/* Request "ANY" record for php.net, 
   and create $authns and $addtl arrays
   containing list of name servers and
   any additional records which go with
   them */
$result = dns_get_record("php.net", DNS_ANY, $authns, $addtl);
echo "Result = ";
print_r($result);
echo "Auth NS = ";
print_r($authns);
echo "Additional = ";
print_r($addtl);
?>
]]>
      </programlisting>
      <para>
       Produces output similar to the following:
      </para>
      <screen>
<![CDATA[
Result = Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => MX
            [pri] => 5
            [target] => pair2.php.net
            [class] => IN
            [ttl] => 6765
        )

    [1] => Array
        (
            [host] => php.net
            [type] => A
            [ip] => 64.246.30.37
            [class] => IN
            [ttl] => 8125
        )

)
Auth NS = Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => remote1.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [1] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => remote2.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [2] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => ns1.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [3] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => ns2.easydns.com
            [class] => IN
            [ttl] => 10722
        )

)
Additional = Array
(
    [0] => Array
        (
            [host] => pair2.php.net
            [type] => A
            [ip] => 216.92.131.5
            [class] => IN
            [ttl] => 6766
        )

    [1] => Array
        (
            [host] => remote1.easydns.com
            [type] => A
            [ip] => 64.39.29.212
            [class] => IN
            [ttl] => 100384
        )

    [2] => Array
        (
            [host] => remote2.easydns.com
            [type] => A
            [ip] => 212.100.224.80
            [class] => IN
            [ttl] => 81241
        )

    [3] => Array
        (
            [host] => ns1.easydns.com
            [type] => A
            [ip] => 216.220.40.243
            [class] => IN
            [ttl] => 81241
        )

    [4] => Array
        (
            [host] => ns2.easydns.com
            [type] => A
            [ip] => 216.220.40.244
            [class] => IN
            [ttl] => 81241
        )

)
]]>
      </screen>
     </example>
     <simpara>
      See also
       <function>dns_get_mx</function>, and
       <function>dns_check_record</function>
     </simpara>
    </refsect1>
  </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->