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

<!-- $Revision$ -->

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

<!-- Reviewed: yes -->

<!-- Rev-Revision: 7be2426e49ee1c9131866f20b67a48aaea0a642a Reviewer: samesch -->

<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>Liefert die zu einem Hostnamen gehörenden DNS-Einträge</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>

Fragt die zum übergebenen <parameter>hostname</parameter> gehörenden DNS

Resource Records ab.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>hostname</parameter></term>

<listitem>

<para>

<parameter>hostname</parameter> sollte ein gültiger Hostname wie &zb;

"<literal>www.example.com</literal>" sein. Reverse Lookups sind mit der

<literal>in-addr.arpa</literal>-Notation möglich, jedoch sollte für

diesen Fall <function>gethostbyaddr</function> genutzt werden.

</para>

<note>

<para>

Gemäß dem DNS-Standard werden E-Mail-Adressen in der Form

<literal>user.host</literal> zurückgegeben (zum Beispiel:

<literal>hostmaster.example.com</literal> statt

<literal>[email protected]</literal>). Darum ist es wichtig,

diesen Wert zu überprüfen und ihn ggf. zu ändern, bevor Sie ihn in

Funktionen wie &zb; <function>mail</function> verwenden.

</para>

</note>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>type</parameter></term>

<listitem>

<para>

Standardmäßig sucht <function>dns_get_record</function> nach jedem

Resource Record für den <parameter>hostname</parameter>. Um die Anfrage

einzuschränken, kann eine der

<constant>DNS_<replaceable>*</replaceable></constant>-Konstanten

verwendet werden.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Wird per Referenz übergeben und wird, wenn es angegeben wurde, mit den

Records für die <emphasis>Autoritativen Nameserver</emphasis> gefüllt.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Wird per Referenz übergeben und wird, wenn es angegeben wurde, mit

allen <emphasis>zusätzlichen Records</emphasis> gefüllt.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Der Parameter <parameter>type</parameter> wird als unverarbeitete

DNS-Typ-ID interpretiert (die

<literal>DNS_<replaceable>*</replaceable></literal>-Konstanten können

nicht verwendet werden). Der Rückgabewert enthält einen

<literal>data</literal>-Schlüssel, der manuell geparst werden muss.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Diese Funktion gibt ein Array an assioziativen Arrays zurück.

&return.falseforfailure; Jedes assoziative Array enthält

<emphasis>mindestens</emphasis> die folgenden Keys:

<table>

<title>Grundlegende DNS-Attribute</title>

<tgroup cols="2">

<thead>

<row>

<entry>Attribut</entry>

<entry>Bedeutung</entry>

</row>

</thead>

<tbody>

<row>

<entry>host</entry>

<entry>

Der Host im DNS-Namensraum, auf den sich die restlichen Werte in dem

assoziativen Array beziehen.

</entry>

</row>

<row>

<entry>class</entry>

<entry>

<function>dns_get_record</function> gibt nur Internet Class Records

zurück, wodurch dieser Paramater immer <literal>IN</literal>

zurückgibt.

</entry>

</row>

<row>

<entry>type</entry>

<entry>

Ein String, in dem der Record-Typ hinterlegt ist. Zusätzliche

Attribute sind, abhängig vom Typ, ebenfalls in dem Array enthalten.

Siehe untere Tabelle.

</entry>

</row>

<row>

<entry>ttl</entry>

<entry>

<literal>"Time To Live"</literal>, die Zeit, die für diesen Record

noch verbleibt. Diese ist <emphasis>nicht</emphasis> identisch mit der

ursprünglichen ttl des Records, sondern entspricht der ursprünglichen

ttl abzüglich der Zeit, die seit der Abfrage des autoritativen

Namensservers vergangen ist.

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

<para>

<table>

<title>Andere Keys im assoziativen Array abhängig von <parameter>type</parameter></title>

<tgroup cols="2">

<thead>

<row>

<entry>Type</entry>

<entry>Extra Spalten</entry>

</row>

</thead>

<tbody>

<row>

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

<entry>

<literal>ip</literal>: Eine IPv4-Addresse in dezimaler Punktnotation.

</entry>

</row>

<row>

<entry><literal>MX</literal></entry>

<entry>

<literal>pri</literal>: Die Priorität des MX-Records. Niedrigere

Zahlen bedeuten eine höhere Priorität. <literal>target</literal>: FQDN

des MX-Records. Siehe auch: <function>dns_get_mx</function>.

</entry>

</row>

<row>

<entry><literal>CNAME</literal></entry>

<entry>

<literal>target</literal>: Die FQDN des Ziels, auf das dieser Alias

zeigt.

</entry>

</row>

<row>

<entry><literal>NS</literal></entry>

<entry>

<literal>target</literal>: Die FQDN des Nameservers, der der

autorative Nameserver für dieses Zone ist.

</entry>

</row>

<row>

<entry><literal>PTR</literal></entry>

<entry>

<literal>target</literal>: Die Stelle im DNS-Namensraum, auf den

dieser Record zeigt.

</entry>

</row>

<row>

<entry><literal>TXT</literal></entry>

<entry>

<literal>txt</literal>: Ein beliebiger String, der diesem Record

zugeordnet ist.

</entry>

</row>

<row>

<entry><literal>HINFO</literal></entry>

<entry>

<literal>cpu</literal>: Die IANA-Nummer für die CPU des Hosts, der

durch diesen Record referenziert wird. <literal>os</literal>: Die

IANA-Nummer für das Betriebssystem des Hosts, der durch diesen Record

referenziert wird. Siehe IANAs

<link xlink:href="&url.iana.system-names;"><literal>Operating System Names</literal></link>

für die Bedeutung dieses Records.

</entry>

</row>

<row>

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

<entry>

<literal>flags</literal>: Ein Ein-Byte-Bitfeld; zurzeit ist nur Bit 0

definiert, was "kritisch" bedeutet; andere Bits sind reserviert und

sollten ignoriert werden. <literal>tag</literal>: Der CAA-Tag-Name

(alphanumerische ASCII-Zeichenkette). <literal>value</literal>: Der

CAA-Tag-Wert (Binärstring, der Unterformate verwenden kann). Für

weitere Information siehe

<link xlink:href="&url.rfc;6844">RFC 6844</link>

</entry>

</row>

<row>

<entry><literal>SOA</literal></entry>

<entry>

<literal>mname</literal>: Der FQDN für den Host, von dem diese

Resource Records kommen. <literal>rname</literal>: Die E-Mail-Adresse

des Administrators dieser Domain. <literal>serial</literal>: Die

aufsteigende Nummer für die Revision der angefragten Domain.

<literal>refresh</literal>: Das Aktualisierungsintervall, das die

sekundären Nameserver nutzen sollten, wenn sie ihre gespiegelten

Kopien der Zone aktualisieren wollen. <literal>retry</literal>: Die

Zeit, die nach einem fehlerhaften Versuch gewartet werden soll.

<literal>expire</literal>: Die maximale Zeit, die ein sekundärer

Nameserver Kopien der Zone behalten soll. Wird nach jedem

erfolgreichen Refresh neu gezählt. <literal>minimum-ttl</literal>: Die

Anzahl der Sekunden, die eine Anfrage im Cache behalten wird. Kann von

individuellen Resource Records überschrieben werden.

</entry>

</row>

<row>

<entry><literal>AAAA</literal></entry>

<entry>

<literal>ipv6</literal>: Die IPv6-Addresse.

</entry>

</row>

<row>

<entry><literal>A6</literal></entry>

<entry>

<literal>masklen</literal>: Die Anzahl der Bits, die von dem durch

<parameter>chain</parameter> vorgegeben Ziel geerbt werden.

<literal>ipv6</literal>: Die Adresse für diesen speziellen Record, der

mit <parameter>chain</parameter> zusammengeführt werden soll.

<literal>chain</literal>: Der übergeordnete Record, der mit den

<parameter>ipv6</parameter>-Daten zusammengeführt werden soll.

</entry>

</row>

<row>

<entry><literal>SRV</literal></entry>

<entry>

<literal>pri</literal>: (Priorität) Die niedrigsten Prioritäten

sollten zuerst verwendet werden. <literal>weight</literal>: Die

Rangfolge der Gewichtung, welche der üblicherweise priorisierten

<parameter>targets</parameter> zufällig ausgewählt werden sollen.

Bsp.: Ziel A: 3, Ziel B: 2. Ziel A wird im Mittel in 60% der Fälle

gewählt. <literal>target</literal> und <literal>port</literal>:

Hostname und Port, unter dem der Service erreicht werden kann. Für

weitere Information siehe:

<link xlink:href="&url.rfc;2782">RFC 2782</link>.

</entry>

</row>

<row>

<entry><literal>NAPTR</literal></entry>

<entry>

<literal>order</literal> und <literal>pref</literal>: Gleichwertig zu

<parameter>pri</parameter> und <parameter>weight</parameter> oben.

<literal>flags</literal>, <literal>services</literal>,

<literal>regex</literal>, und <literal>replacement</literal>:

Parameter wie in <link xlink:href="&url.rfc;2915">RFC 2915</link>

definiert.

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

Die Unterstützung für den CAA-Record-Typ wurde hinzugefügt.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Benutzung von <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>Benutzung von <function>dns_get_record</function> und DNS_ANY</title>

<para>

Da man häufig auch die IP des Mailservers für einen MX-Record benötigt,

gibt <function>dns_get_record</function> auch ein Array in

<parameter>additional_records</parameter> zurück, in dem die zugehörigen

Records zu finden sind. Ebenso wird

<parameter>authoritative_name_servers</parameter> mit einer Liste der

autorativen Nameserver zurückgegeben.

</para>

<programlisting role="php">

<![CDATA[

<?php

/* Fordert alle ("ANY") Records für php.net an

und erstellt dann die Arrays $authns und $addtl,

die eine Liste von Servernamen enthalten, und alle

Aufzeichnungen, die zu ihnen gehören

*/

$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

-->