mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-27 14:28:56 +00:00
f0d05b38c3
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330268 c90b9560-bf6c-de11-be94-00142212c4b1
551 lines
16 KiB
XML
551 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xml:id="function.dns-get-record" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refnamediv>
|
|
<refname>dns_get_record</refname>
|
|
<refpurpose>Fetch DNS Resource Records associated with a hostname</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<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><initializer>DNS_ANY</initializer></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter role="reference">authns</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter role="reference">addtl</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter role="reference">raw</parameter><initializer>false</initializer></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Fetch DNS Resource Records associated with the given
|
|
<parameter>hostname</parameter>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>hostname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>hostname</parameter> should be a valid DNS hostname such
|
|
as "<literal>www.example.com</literal>". Reverse lookups can be generated
|
|
using <literal>in-addr.arpa</literal> notation, but
|
|
<function>gethostbyaddr</function> is more suitable for
|
|
the majority of reverse lookups.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Per DNS standards, email addresses are given in <literal>user.host</literal> format (for
|
|
example: <literal>hostmaster.example.com</literal> as opposed to <literal>hostmaster@example.com</literal>),
|
|
be sure to check this value and modify if necessary before using it
|
|
with a functions such as <function>mail</function>.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>type</parameter></term>
|
|
<listitem>
|
|
<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. 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>.
|
|
</para>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>authns</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Passed by reference and, if given, will be populated with Resource
|
|
Records for the <emphasis>Authoritative Name Servers</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>addtl</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Passed by reference and, if given, will be populated with any
|
|
<emphasis>Additional Records</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>raw</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
In case of raw mode, we query only the requestd type instead of looping
|
|
type by type before going with the additional info stuff.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
This function returns an array of associative arrays,
|
|
&return.falseforfailure;. 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>
|
|
<literal>"Time To Live"</literal> 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>
|
|
<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 <link xlink:href="&url.iana.system-names;"><literal>Operating System
|
|
Names</literal></link> 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: <link xlink:href="&url.rfc;2782">RFC 2782</link>
|
|
</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
|
|
<link xlink:href="&url.rfc;2915">RFC 2915</link>.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>5.4.0</entry>
|
|
<entry>
|
|
Added <parameter>raw</parameter> parameter.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.3.0</entry>
|
|
<entry>
|
|
This function is now available on Windows platforms.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.3.0</entry>
|
|
<entry>
|
|
Prior to this release, if the <parameter>authns</parameter> parameter
|
|
was given, the <parameter>addtl</parameter> parameter was also
|
|
required.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<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>
|
|
&example.outputs.similar;
|
|
<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>
|
|
<example>
|
|
<title>Using <function>dns_get_record</function> and DNS_ANY</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<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>
|
|
&example.outputs.similar;
|
|
<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>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<note>
|
|
<para>
|
|
For compatibility with versions before PHP 5.3.0 on some operating systems,
|
|
try the <link xlink:href="&url.php.pear;">PEAR</link> class
|
|
<link xlink:href="&url.pear.package;Net_DNS">Net_DNS</link>.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>dns_get_mx</function></member>
|
|
<member><function>dns_check_record</function></member>
|
|
</simplelist>
|
|
</para>
|
|
</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:"~/.phpdoc/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
|
|
-->
|