cvs: phpdoc /en/reference/network/functions dns-get-record.xml
| From: | Sara Golemon | Date: | Sat, 23 Nov 2002 02:49:50 +0000 |
| Subject: | cvs: phpdoc /en/reference/network/functions dns-get-record.xml | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969349880@lists.php.net to get a copy of this message | ||
pollita Fri Nov 22 21:49:50 2002 EDT
Added files:
/phpdoc/en/reference/network/functions dns-get-record.xml
Log:
New function.
Index: phpdoc/en/reference/network/functions/dns-get-record.xml +++ phpdoc/en/reference/network/functions/dns-get-record.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <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>&authns</parameter></methodparam> <methodparam choice="opt"><type>array</type><parameter>&addtl</parameter></methodparam> </methodsynopsis> <note> This function is not implemented on Windows platforms. </note> <para> Returns an array of associative arrays. Each associative array contains <emphasis>at minimum</emphasis> the following keys: host, type, class, ttl. <note> 'class' key will always be "IN" indicating an IPv4 resource record. </note> <note> 'ttl' key will contain the TTL <emphasis>remaining</emphasis> since the last time the local nameserver queried the authoritative name server. </note> Depending on the value of type, the associate array will also contain one or more of the following keys: ip, pri, target, cpu, os, mname, rname, serial, refresh, retry, expire, minimum-ttl, txt. </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_ALL</constant> or <constant>DNS_ANY</constant>. The default is <emphasis>DNS_ANY</emphasis>. <note> Because of excentricities 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. </note> </para> <simpara> The optional third and fourth arguments to this function, <parameter>authns</parameters> 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> SOA records are the largest of the returned types. 'mname' contains the name of the machine from which the resource records originated. 'rname' is the email address of the administrative contact for this zone. 'serial', 'refresh', 'retry', 'expire', and 'minimum-ttl' give the traditional SOA zone values one would expect. <note> 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>. </note> </para> <simpara> A records will contain an 'ip' key providing their IPv4 address. </simpara> <simpara> MX records will conatin a 'pri' key indicating priority (preference). It will also have a 'target' key which lists the FQDN of the mail exchanger. See also <function>dns_get_mx</function>. </simpara> <simpara> CNAME, NS, and PTR records will each contain a 'target' key giving the particular location in the DNS namespace which they refer to. </simpara> <simpara> TXT records will have a 'txt' key containing the text data associated with the named resource record. </simpara> <simpara> HINFO records have two parameters: 'cpu' and 'os' which describe the opperating environment of the specified host. The values are given as integers, see <ulink url="&url.rfc1010;">RFC 1010</ulink> for the meaning of these values. </simpara> <example> <title>Using <function>dns_get_record</function></title> <programlisting role="php"> <![CDATA[ <?php $result = dns_get_record("php.net"); print_r($result); ?> /* Produces ouput similar to the following: ---------------------------------------- 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 ) ) */ ]]> </programlisting> </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 conatining a list of authoritative name servers. </simpara> <example> <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); print "Result = "; print_r($result); print "Auth NS = "; print_r($authns); print "Additional = "; print_r($addtl); ?> /* Produces output similar to the following: ----------------------------------------- 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 ) ) */ ]]> </programlisting> </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 -->
Index: phpdoc/en/reference/network/functions/dns-get-record.xml +++ phpdoc/en/reference/network/functions/dns-get-record.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <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>&authns</parameter></methodparam> <methodparam choice="opt"><type>array</type><parameter>&addtl</parameter></methodparam> </methodsynopsis> <note> This function is not implemented on Windows platforms. </note> <para> Returns an array of associative arrays. Each associative array contains <emphasis>at minimum</emphasis> the following keys: host, type, class, ttl. <note> 'class' key will always be "IN" indicating an IPv4 resource record. </note> <note> 'ttl' key will contain the TTL <emphasis>remaining</emphasis> since the last time the local nameserver queried the authoritative name server. </note> Depending on the value of type, the associate array will also contain one or more of the following keys: ip, pri, target, cpu, os, mname, rname, serial, refresh, retry, expire, minimum-ttl, txt. </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_ALL</constant> or <constant>DNS_ANY</constant>. The default is <emphasis>DNS_ANY</emphasis>. <note> Because of excentricities 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. </note> </para> <simpara> The optional third and fourth arguments to this function, <parameter>authns</parameters> 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> SOA records are the largest of the returned types. 'mname' contains the name of the machine from which the resource records originated. 'rname' is the email address of the administrative contact for this zone. 'serial', 'refresh', 'retry', 'expire', and 'minimum-ttl' give the traditional SOA zone values one would expect. <note> 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>. </note> </para> <simpara> A records will contain an 'ip' key providing their IPv4 address. </simpara> <simpara> MX records will conatin a 'pri' key indicating priority (preference). It will also have a 'target' key which lists the FQDN of the mail exchanger. See also <function>dns_get_mx</function>. </simpara> <simpara> CNAME, NS, and PTR records will each contain a 'target' key giving the particular location in the DNS namespace which they refer to. </simpara> <simpara> TXT records will have a 'txt' key containing the text data associated with the named resource record. </simpara> <simpara> HINFO records have two parameters: 'cpu' and 'os' which describe the opperating environment of the specified host. The values are given as integers, see <ulink url="&url.rfc1010;">RFC 1010</ulink> for the meaning of these values. </simpara> <example> <title>Using <function>dns_get_record</function></title> <programlisting role="php"> <![CDATA[ <?php $result = dns_get_record("php.net"); print_r($result); ?> /* Produces ouput similar to the following: ---------------------------------------- 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 ) ) */ ]]> </programlisting> </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 conatining a list of authoritative name servers. </simpara> <example> <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); print "Result = "; print_r($result); print "Auth NS = "; print_r($authns); print "Additional = "; print_r($addtl); ?> /* Produces output similar to the following: ----------------------------------------- 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 ) ) */ ]]> </programlisting> </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 -->