mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-27 22:38:55 +00:00
c148211fa2
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@172416 c90b9560-bf6c-de11-be94-00142212c4b1
459 lines
14 KiB
XML
459 lines
14 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.20 $ -->
|
|
<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. 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 >= 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
|
|
-->
|