<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 35ca7f1087870c6023ef7a3dd0248501741c8194 Maintainer: tmn Status: ready -->

<!-- Reviewed: no -->

<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>

Функция выбирает DNS-записи, которые соответствуют свойствам хоста

<parameter>hostname</parameter>.

</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>[email protected]</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>. Константы семейства <constant>DNS_<replaceable>*</replaceable></constant>

помогают сузить запрос.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>authoritative_name_servers</parameter></term>

<listitem>

<para>

Аргумент передаётся по ссылке и при передаче заполняется ресурсными

записями для <emphasis>удостоверяющих серверов имён</emphasis>

(Authoritative Name Servers).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>additional_records</parameter></term>

<listitem>

<para>

Передаётся по ссылке и, если передан, будет заполняться

<emphasis>дополнительными записями</emphasis>

(Additional Records).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>raw</parameter></term>

<listitem>

<para>

Функция интерпретирует параметр <parameter>type</parameter> как необработанный идентификатор типа DNS;

в параметр нельзя передавать константы семейства <constant>DNS_<replaceable>*</replaceable></constant>.

Значение возврата будет содержать ключ <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>

Строка, которая содержит тип записи. Дополнительные атрибуты тоже будут

содержаться в результирующем массиве в зависимости от значения типа.

Смотрите таблицу ниже.

</entry>

</row>

<row>

<entry>ttl</entry>

<entry>

Атрибут <literal>"Time To Live"</literal> содержит значение времени жизни, которое осталось для записи.

Это значение <emphasis>не</emphasis> совпадёт с исходным ttl-значением записи.

Значение атрибута равно исходному времени жизни за вычетом времени,

которое прошло с момента отправки запроса на сервер.

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

<para>

<table>

<title>Другие ключи в ассоциативных массивах, которые зависят от значения параметра <parameter>type</parameter></title>

<tgroup cols="2">

<thead>

<row>

<entry>Тип записи</entry>

<entry>Дополнительные данные</entry>

</row>

</thead>

<tbody>

<row>

<entry><literal>A</literal></entry>

<entry>

<literal>ip</literal>: адреса 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-имя места расположения в пространстве имён

DNS, на которое указывает запись.

</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>: число IANA, которое обозначает модель процессора

компьютера, на который указывает запись.

<literal>os</literal>: число IANA, которое обозначает операционную систему

компьютера, на который указывает запись.

Смотрите дополнительно реестр названий операционных систем <link xlink:href="&url.iana.system-names;"><literal>Operating

System Names</literal></link> администрации адресного интернет-пространства IANA.

</entry>

</row>

<row>

<entry><literal>CAA</literal></entry>

<entry>

<literal>flags</literal>: Однобайтовое битовое поле; пока

определили только бит с номером 0, который называется 'critical'; другие биты зарезервировали

и игнорируются.

<literal>tag</literal>: Имя тега CAA (буквенно-числовая строка 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>: Адрес электронной почты администратора домена.

<literal>serial</literal>: Порядковый номер этой ревизии запрашиваемого

домена.

<literal>refresh</literal>: Интервал времени в секундах, который

должны использовать вторичные серверы при обновлении удалённых копий

этого домена.

<literal>retry</literal>: Время ожидания в секундах после неудачного

обновления до следующей попытки.

<literal>expire</literal>: Максимальное время в секундах, в течение

которого вторичный DNS-сервер должен держать в памяти данные удалённых

копий доменной зоны, прежде чем ответить отказом, когда не удаётся обновить

данные.

<literal>minimum-ttl</literal>: Минимальное время в секундах, в течение

которого клиент может работать с текущим DNS-разрешением, прежде чем ему

придётся повторно запрашивать это разрешение. Значение иногда замещается

отдельными ресурсными записями.

</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>: (Приоритет) меньшие значения должны использоваться

первыми.

<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>Пример получения записей с типом DNS_ANY функцией <function>dns_get_record</function></title>

<para>

Поскольку часто требуется определить IP-адрес почтового сервера,

после разрешения MX-записи функция <function>dns_get_record</function> возвращает массив

<parameter>additional_records</parameter> с записями, которые соответствуют серверам. Массив

<parameter>authoritative_name_servers</parameter> будет содержать список удостоверяющих

DNS-серверов.

</para>

<programlisting role="php">

<![CDATA[

<?php

/* Запросим запись с типом "ANY" для хоста php.net,

создадим массивы $authns и $addtl,

в которые функция поместит список серверов

имён и дополнительные записи,

которые соответствуют этим серверам

*/

$result = dns_get_record("php.net", DNS_ANY, $authns, $addtl);

echo "Результат = ";

print_r($result);

echo "Удостоверяющие серверы = ";

print_r($authns);

echo "Дополнительные записи = ";

print_r($addtl);

?>

]]>

</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

)

)

Удостоверяющие серверы = 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

)

)

Дополнительные записи = 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

-->