<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Fetch DNS Resource Records associated with a hostname</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.dns-get-mx.html">dns_get_mx</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.fsockopen.html">fsockopen</a></div>
<div class="up"><a href="ref.network.html">Network Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.dns-get-record" class="refentry">
<div class="refnamediv">
<h1 class="refname">dns_get_record</h1>
<p class="verinfo">(PHP 5)</p><p class="refpurpose"><span class="refname">dns_get_record</span> — <span class="dc-title">Fetch DNS Resource Records associated with a hostname</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.dns-get-record-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">array</span> <span class="methodname"><strong>dns_get_record</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$hostname</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$type</code><span class="initializer"> = DNS_ANY</span></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter reference">&$authns</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter reference">&$addtl</code></span>
[, <span class="methodparam"><span class="type">bool</span> <code class="parameter reference">&$raw</code><span class="initializer"> = false</span></span>
]]]] )</div>
<p class="para rdfs-comment">
Fetch DNS Resource Records associated with the given
<em><code class="parameter">hostname</code></em>.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.dns-get-record-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">hostname</code></em></span>
<dd>
<p class="para">
<em><code class="parameter">hostname</code></em> should be a valid DNS hostname such
as "<em>www.example.com</em>". Reverse lookups can be generated
using <em>in-addr.arpa</em> notation, but
<span class="function"><a href="function.gethostbyaddr.html" class="function">gethostbyaddr()</a></span> is more suitable for
the majority of reverse lookups.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Per DNS standards, email addresses are given in <em>user.host</em> format (for
example: <em>hostmaster.example.com</em> as opposed to <em>hostmaster@example.com</em>),
be sure to check this value and modify if necessary before using it
with a functions such as <span class="function"><a href="function.mail.html" class="function">mail()</a></span>.
</p>
</p></blockquote>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">type</code></em></span>
<dd>
<p class="para">
By default, <span class="function"><strong>dns_get_record()</strong></span> will search for any
resource records associated with <em><code class="parameter">hostname</code></em>.
To limit the query, specify the optional <em><code class="parameter">type</code></em>
parameter. May be any one of the following:
<strong><code>DNS_A</code></strong>, <strong><code>DNS_CNAME</code></strong>,
<strong><code>DNS_HINFO</code></strong>, <strong><code>DNS_MX</code></strong>,
<strong><code>DNS_NS</code></strong>, <strong><code>DNS_PTR</code></strong>,
<strong><code>DNS_SOA</code></strong>, <strong><code>DNS_TXT</code></strong>,
<strong><code>DNS_AAAA</code></strong>, <strong><code>DNS_SRV</code></strong>,
<strong><code>DNS_NAPTR</code></strong>, <strong><code>DNS_A6</code></strong>,
<strong><code>DNS_ALL</code></strong> or <strong><code>DNS_ANY</code></strong>.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Because of eccentricities in the performance of libresolv
between platforms, <strong><code>DNS_ANY</code></strong> will not
always return every record, the slower <strong><code>DNS_ALL</code></strong>
will collect all records more reliably.
</p>
</p></blockquote>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">authns</code></em></span>
<dd>
<p class="para">
Passed by reference and, if given, will be populated with Resource
Records for the <em class="emphasis">Authoritative Name Servers</em>.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">addtl</code></em></span>
<dd>
<p class="para">
Passed by reference and, if given, will be populated with any
<em class="emphasis">Additional Records</em>.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">raw</code></em></span>
<dd>
<p class="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.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.dns-get-record-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
This function returns an array of associative arrays,
or <strong><code>FALSE</code></strong> on failure. Each associative array contains
<em class="emphasis">at minimum</em> the following keys:
<table class="doctable table">
<caption><strong>Basic DNS attributes</strong></caption>
<thead>
<tr>
<th>Attribute</th>
<th>Meaning</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>host</td>
<td>
The record in the DNS namespace to which the rest of the associated data refers.
</td>
</tr>
<tr>
<td>class</td>
<td>
<span class="function"><strong>dns_get_record()</strong></span> only returns Internet class records and as
such this parameter will always return <em>IN</em>.
</td>
</tr>
<tr>
<td>type</td>
<td>
String containing the record type. Additional attributes will also be contained
in the resulting array dependant on the value of type. See table below.
</td>
</tr>
<tr>
<td>ttl</td>
<td>
<em>"Time To Live"</em> remaining for this record. This will <em class="emphasis">not</em> 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.
</td>
</tr>
</tbody>
</table>
</p>
<p class="para">
<table class="doctable table">
<caption><strong>Other keys in associative arrays dependant on 'type'</strong></caption>
<thead>
<tr>
<th>Type</th>
<th>Extra Columns</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><em>A</em></td>
<td>
<em>ip</em>: An IPv4 addresses in dotted decimal notation.
</td>
</tr>
<tr>
<td><em>MX</em></td>
<td>
<em>pri</em>: Priority of mail exchanger.
Lower numbers indicate greater priority.
<em>target</em>: FQDN of the mail exchanger.
See also <span class="function"><a href="function.dns-get-mx.html" class="function">dns_get_mx()</a></span>.
</td>
</tr>
<tr>
<td><em>CNAME</em></td>
<td>
<em>target</em>: FQDN of location in DNS namespace to which
the record is aliased.
</td>
</tr>
<tr>
<td><em>NS</em></td>
<td>
<em>target</em>: FQDN of the name server which is authoritative
for this hostname.
</td>
</tr>
<tr>
<td><em>PTR</em></td>
<td>
<em>target</em>: Location within the DNS namespace to which
this record points.
</td>
</tr>
<tr>
<td><em>TXT</em></td>
<td>
<em>txt</em>: Arbitrary string data associated with this record.
</td>
</tr>
<tr>
<td><em>HINFO</em></td>
<td>
<em>cpu</em>: IANA number designating the CPU of the machine
referenced by this record.
<em>os</em>: IANA number designating the Operating System on
the machine referenced by this record.
See IANA's <a href="http://www.iana.org/assignments/operating-system-names" class="link external">» <em>Operating System
Names</em></a> for the meaning of these values.
</td>
</tr>
<tr>
<td><em>SOA</em></td>
<td>
<em>mname</em>: FQDN of the machine from which the resource
records originated.
<em>rname</em>: Email address of the administrative contain
for this domain.
<em>serial</em>: Serial # of this revision of the requested
domain.
<em>refresh</em>: Refresh interval (seconds) secondary name
servers should use when updating remote copies of this domain.
<em>retry</em>: Length of time (seconds) to wait after a
failed refresh before making a second attempt.
<em>expire</em>: Maximum length of time (seconds) a secondary
DNS server should retain remote copies of the zone data without a
successful refresh before discarding.
<em>minimum-ttl</em>: 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.
</td>
</tr>
<tr>
<td><em>AAAA</em></td>
<td>
<em>ipv6</em>: IPv6 address
</td>
</tr>
<tr>
<td><em>A6</em>(PHP >= 5.1.0)</td>
<td>
<em>masklen</em>: Length (in bits) to inherit from the target
specified by <em><code class="parameter">chain</code></em>.
<em>ipv6</em>: Address for this specific record to merge with
<em><code class="parameter">chain</code></em>.
<em>chain</em>: Parent record to merge with
<em><code class="parameter">ipv6</code></em> data.
</td>
</tr>
<tr>
<td><em>SRV</em></td>
<td>
<em>pri</em>: (Priority) lowest priorities should be used first.
<em>weight</em>: Ranking to weight which of commonly prioritized
<em><code class="parameter">targets</code></em> should be chosen at random.
<em>target</em> and <em>port</em>: hostname and port
where the requested service can be found.
For additional information see: <a href="http://www.faqs.org/rfcs/rfc2782" class="link external">» RFC 2782</a>
</td>
</tr>
<tr>
<td><em>NAPTR</em></td>
<td>
<em>order</em> and <em>pref</em>: Equivalent to
<em><code class="parameter">pri</code></em> and <em><code class="parameter">weight</code></em> above.
<em>flags</em>, <em>services</em>, <em>regex</em>,
and <em>replacement</em>: Parameters as defined by
<a href="http://www.faqs.org/rfcs/rfc2915" class="link external">» RFC 2915</a>.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.dns-get-record-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>5.4.0</td>
<td>
Added <em><code class="parameter">raw</code></em> parameter.
</td>
</tr>
<tr>
<td>5.3.0</td>
<td>
This function is now available on Windows platforms.
</td>
</tr>
<tr>
<td>5.3.0</td>
<td>
Prior to this release, if the <em><code class="parameter">authns</code></em> parameter
was given, the <em><code class="parameter">addtl</code></em> parameter was also
required.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.dns-get-record-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4471">
<p><strong>Example #1 Using <span class="function"><strong>dns_get_record()</strong></span></strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$result </span><span style="color: #007700">= </span><span style="color: #0000BB">dns_get_record</span><span style="color: #007700">(</span><span style="color: #DD0000">"php.net"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$result</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
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
)
)
</pre></div>
</div>
</div>
<div class="example" id="example-4472">
<p><strong>Example #2 Using <span class="function"><strong>dns_get_record()</strong></span> and DNS_ANY</strong></p>
<div class="example-contents"><p>
Since it's very common to want the IP address of a mail server
once the MX record has been resolved, <span class="function"><strong>dns_get_record()</strong></span>
also returns an array in <em><code class="parameter">addtl</code></em> which
contains associate records. <em><code class="parameter">authns</code></em>
is returned as well containing a list of authoritative name
servers.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Request "ANY" record for php.net,<br /> and create $authns and $addtl arrays<br /> containing list of name servers and<br /> any additional records which go with<br /> them */<br /></span><span style="color: #0000BB">$result </span><span style="color: #007700">= </span><span style="color: #0000BB">dns_get_record</span><span style="color: #007700">(</span><span style="color: #DD0000">"php.net"</span><span style="color: #007700">, </span><span style="color: #0000BB">DNS_ANY</span><span style="color: #007700">, </span><span style="color: #0000BB">$authns</span><span style="color: #007700">, </span><span style="color: #0000BB">$addtl</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"Result = "</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$result</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"Auth NS = "</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$authns</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"Additional = "</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$addtl</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
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
)
)
</pre></div>
</div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.dns-get-record-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
For compatibility with versions before PHP 5.3.0 on some operating systems,
try the <a href="http://pear.php.net/" class="link external">» PEAR</a> class
<a href="http://pear.php.net/package/Net_DNS" class="link external">» Net_DNS</a>.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-function.dns-get-record-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.dns-get-mx.html" class="function" rel="rdfs-seeAlso">dns_get_mx()</a> - Alias of getmxrr</span></li>
<li class="member"> <span class="function"><a href="function.dns-check-record.html" class="function" rel="rdfs-seeAlso">dns_check_record()</a> - Alias of checkdnsrr</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.dns-get-mx.html">dns_get_mx</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.fsockopen.html">fsockopen</a></div>
<div class="up"><a href="ref.network.html">Network Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
