dns-get-record.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 7be2426e49ee1c9131866f20b67a48aaea0a642a Maintainer: takagi Status: ready -->
<!-- Credits: mumumu -->
<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>ホスト名に関連する DNS リソースレコードを取得する</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>dns_get_record</methodname>
   <methodparam><type>string</type><parameter>hostname</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>type</parameter><initializer><constant>DNS_ANY</constant></initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">authoritative_name_servers</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">additional_records</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>raw</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <para>
   指定した <parameter>hostname</parameter>
   に関連づけられた DNS リソースレコードを取得します。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>hostname</parameter></term>
     <listitem>
      <para>
       <parameter>hostname</parameter> は、正しい DNS ホスト名、すなわち
       "<literal>www.example.com</literal>" のようなものでなければなりません。
       <literal>in-addr.arpa</literal> 形式の表記を用いた逆引き検索は可能ですが、
       たいていは <function>gethostbyaddr</function> を用いるほうが適当です。
      </para>
      <note>
       <para>
        DNS の標準規格により、メールアドレスは <literal>user.host</literal> 形式で渡されます
        （たとえば、<literal>hostmaster.example.com</literal> が <literal>hostmaster@example.com</literal>
        の代わりとなります）。
        この値をしっかり確認し、<function>mail</function> のような関数で
        利用する前には必要なら変更を加えることを忘れないようにしてください。 
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>type</parameter></term>
     <listitem>
      <para>
       デフォルトでは、<function>dns_get_record</function> は
       <parameter>hostname</parameter> に関連するすべてのリソースレコードを検索します。
       これを制限するには、オプションの
       <parameter>type</parameter> パラメータを指定してください。
       <parameter>type</parameter> は以下のうちのいずれかです。
       <constant>DNS_A</constant>, <constant>DNS_CNAME</constant>,
       <constant>DNS_HINFO</constant>, <constant>DNS_CAA</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>
       または <constant>DNS_ANY</constant>。
      </para>
      <note>
       <para>
        プラットフォーム依存の libresolv のおかしな挙動のせいで、
        <constant>DNS_ANY</constant> が常にすべてのレコードを返すとは
        限りません。速度は遅くなりますが、<constant>DNS_ALL</constant>
        のほうがより確実にすべてのレコードを取得できます。
       </para>
      </note>
      <note>
       <para>
        Windows では、<constant>DNS_CAA</constant>
        はサポートされていませんし、
        <constant>DNS_A6</constant> は実装されていません。
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>authoritative_name_servers</parameter></term>
     <listitem>
      <para>
       参照で渡し、
       <emphasis>Authoritative Name Servers</emphasis>
       のリソースレコードが格納されます。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_records</parameter></term>
     <listitem>
      <para>
       参照で渡し、
       <emphasis>Additional Records</emphasis>
       が格納されます。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>raw</parameter></term>
     <listitem>
      <para>
       <parameter>type</parameter> は生のDNSのタイプIDとして解釈されます。
       (<literal>DNS_*</literal> 定数は使えません)
       戻り値には手動でパースが必要な <literal>data</literal> キーが含まれます。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   この関数は、連想配列を要素にもつ配列を返します。
   &return.falseforfailure;。
   それぞれの連想配列には
   <emphasis>少なくとも</emphasis> 以下のキーが含まれています:
   <table>
    <title>基本 DNS 属性</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>属性</entry>
       <entry>意味</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>host</entry>
       <entry>
        これ以降の関連するデータが参照する DNS 名。
       </entry>
      </row>
      <row>
       <entry>class</entry>
       <entry>
        <function>dns_get_record</function> は
        Internet クラスのレコードのみを返すので、このパラメータは常に
        <literal>IN</literal> を返します。
       </entry>
      </row>
      <row>
       <entry>type</entry>
       <entry>
        レコード型を表す文字列。type の値に応じて、
        結果の配列には追加の属性が含まれます。以下の表を参照ください。
       </entry>
      </row>
      <row>
       <entry>ttl</entry>
       <entry>
        このレコードの<literal>"有効期限 (Time To Live)"</literal>。レコードの本来の ttl と一致するとは
        <emphasis>限りません</emphasis>。むしろ、
        ネームサーバーへのクエリにかかった時間をそこから引いたものに一致します。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para>
   <table>
    <title>'type' に応じて連想配列に追加される項目</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>レコード型</entry>
       <entry>追加項目</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>A</literal></entry>
       <entry>
        <literal>ip</literal>: ドット区切り 10 進数形式の IPv4 アドレス。
       </entry>
      </row>
      <row>
       <entry><literal>MX</literal></entry>
       <entry>
        <literal>pri</literal>: メールエクスチェンジャの優先度。
        数字が小さいほど優先度が高い。
        <literal>target</literal>: メールエクスチェンジャの FQDN 。
        <function>dns_get_mx</function> も参照ください。
       </entry>
      </row>
      <row>
       <entry><literal>CNAME</literal></entry>
       <entry>
        <literal>target</literal>: レコードのエイリアスの対象となっている場所の FQDN 。
       </entry>
      </row>
      <row>
       <entry><literal>NS</literal></entry>
       <entry>
        <literal>target</literal>: このホスト名に対する権威をもっているネームサーバーの FQDN 。
       </entry>
      </row>
      <row>
       <entry><literal>PTR</literal></entry>
       <entry>
        <literal>target</literal>: レコードが指している、DNS 名前空間内の場所
       </entry>
      </row>
       <row>
       <entry><literal>TXT</literal></entry>
       <entry>
        <literal>txt</literal>: このレコードに関連付けられている任意の文字列。
       </entry>
      </row>
      <row>
       <entry><literal>HINFO</literal></entry>
       <entry>
        <literal>cpu</literal>: このレコードが参照しているマシンの CPU を識別する IANA 番号。
        <literal>os</literal>: このレコードが参照しているマシン上の OS を識別する IANA 番号。
        これらの値の意味については、IANA の 
        <link xlink:href="&url.iana.system-names;"><literal>Operating System Names</literal></link>
        を参照ください。
       </entry>
      </row>
      <row>
       <entry><literal>CAA</literal></entry>
       <entry>
        <literal>flags</literal>: 1バイトのビットフィールド;
        現在はビット0だけが定義されており、'critical' を意味します。
        他のビットは予約されており、無視されるべきです。
        <literal>tag</literal>: CAA タグの名前 (alphanumeric な ASCII 文字列).
        <literal>value</literal>: CAA タグの値 (バイナリ文字列, サブフォーマットの使用可)
        詳細は、<link xlink:href="&url.rfc;6844">RFC 6844</link> を参照ください。
       </entry>
      </row>
      <row>
       <entry><literal>SOA</literal></entry>
       <entry>
        <literal>mname</literal>: リソースレコードの元となるマシンの FQDN 。
        <literal>rname</literal>: このドメインの管理責任者の Email アドレス。
        <literal>serial</literal>: ドメインのシリアル番号。
        <literal>refresh</literal>:
        セカンダリネームサーバーがこのドメインのコピーを更新する際に参照するリフレッシュ間隔（秒単位）。
        <literal>retry</literal>: リフレッシュが失敗した際に
        2 度目のリフレッシュを試みるまでの間隔（秒単位）
        <literal>expire</literal>: セカンダリネームサーバーが、ゾーンデータの
        リフレッシュに失敗した場合にコピーのデータを破棄せず持ち続ける期間
        （秒単位）。
        <literal>minimum-ttl</literal>: クライアントが、
        一度取得したデータを再リクエストすることなしに利用できる最小期間（秒単位）。
        個々のリソースレコードによって上書きが可能。
       </entry>
      </row>
      <row>
       <entry><literal>AAAA</literal></entry>
       <entry>
        <literal>ipv6</literal>: IPv6 アドレス。
       </entry>
      </row>
      <row>
       <entry><literal>A6</literal></entry>
       <entry>
        <literal>masklen</literal>: <parameter>chain</parameter>
        で指定された対象から引き継ぐビット長。
        <literal>ipv6</literal>: <parameter>chain</parameter>
        とマージするためのこのレコードのアドレス。
        <literal>chain</literal>: <parameter>ipv6</parameter>
        データとマージするための親レコード。
       </entry>
      </row>
      <row>
       <entry><literal>SRV</literal></entry>
       <entry>
        <literal>pri</literal>: (Priority) 値が小さいものが優先されます。
        <literal>weight</literal>: 同じ優先順位の
        <parameter>targets</parameter> からランダムに選択する際の重み。
        <literal>target</literal> および <literal>port</literal>:
        リクエストされたサービスが存在するホスト名とポート。
        詳細は <link xlink:href="&url.rfc;2782">RFC 2782</link> を参照ください。
       </entry>
      </row>
      <row>
       <entry><literal>NAPTR</literal></entry>
       <entry>
        <literal>order</literal> および <literal>pref</literal>: 上の
        <parameter>pri</parameter> および <parameter>weight</parameter> と同じ。
        <literal>flags</literal>, <literal>services</literal>, <literal>regex</literal>,
        および <literal>replacement</literal>:
        <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>7.0.16, 7.1.2</entry>
       <entry>
        CAA レコード型のサポートが追加されました。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><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><function>dns_get_record</function> と DNS_ANY の使用</title>
    <para>
     MX レコードが解決されれば、たいていはメールサーバーの IP アドレスを
     取得したくなるものです。そのため、<function>dns_get_record</function>
     は <parameter>additional_records</parameter> に関連するレコードを含めて返します。
     また、<parameter>authoritative_name_servers</parameter> には
     権威のあるネームサーバーのリストを含めて返します。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
/* php.net の "ANY" レコードを要求し、
   それに付随する情報を格納した配列を
   作成する。
   $authns にはネームサーバーの一覧が、
   また $addtl には追加レコードが
   それぞれ格納される。 */
$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="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
-->