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 [EMAIL PROTECTED]),
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
-->
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
