c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"

e676a596869d8a80a644c99a848afb53d1c5975eMark Andrews "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"

499b34cea04a46823d003d4c0520c8b03e8513cbBrian Wellington [<!ENTITY mdash "&#8212;">]>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer<refentry>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer

67adc03ef81fb610f8df093b17f55275ee816754Evan Hunt <refentryinfo>

67adc03ef81fb610f8df093b17f55275ee816754Evan Hunt <date>Oct 18, 2000</date>

67adc03ef81fb610f8df093b17f55275ee816754Evan Hunt </refentryinfo>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <refmeta>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <refentrytitle>lwres_getrrsetbyname</refentrytitle>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <manvolnum>3</manvolnum>

5a77e9620a0b2f7417469c98be374de49d0eccc6Andreas Gustafsson <refmiscinfo>BIND9</refmiscinfo>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer </refmeta>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <docinfo>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <copyright>

e2f470bebb3a0c107bc4ac86c6920c21e50e83e0Brian Wellington <year>2004</year>

e2f470bebb3a0c107bc4ac86c6920c21e50e83e0Brian Wellington <year>2005</year>

4eb998928b9aef0ceda42d7529980d658138698aEvan Hunt <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

e2f470bebb3a0c107bc4ac86c6920c21e50e83e0Brian Wellington </copyright>

e2f470bebb3a0c107bc4ac86c6920c21e50e83e0Brian Wellington <copyright>

e2f470bebb3a0c107bc4ac86c6920c21e50e83e0Brian Wellington <year>2000</year>

e2f470bebb3a0c107bc4ac86c6920c21e50e83e0Brian Wellington <year>2001</year>

e2f470bebb3a0c107bc4ac86c6920c21e50e83e0Brian Wellington <holder>Internet Software Consortium</holder>

e2f470bebb3a0c107bc4ac86c6920c21e50e83e0Brian Wellington </copyright>

ac21f918f23ce95fd5be807428ee9e2c42319878Evan Hunt </docinfo>

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews <refnamediv>

ac21f918f23ce95fd5be807428ee9e2c42319878Evan Hunt <refname>lwres_getrrsetbyname</refname>

ac21f918f23ce95fd5be807428ee9e2c42319878Evan Hunt <refname>lwres_freerrset</refname>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <refpurpose>retrieve DNS records</refpurpose>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt </refnamediv>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <refsynopsisdiv>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <funcsynopsis>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>

2c15fcdeac4c2402258867fbac24d7475ef98259Mark Andrews<funcprototype>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <funcdef>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Huntint

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt<function>lwres_getrrsetbyname</function></funcdef>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <paramdef>const char *<parameter>hostname</parameter></paramdef>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <paramdef>unsigned int <parameter>rdclass</parameter></paramdef>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <paramdef>unsigned int <parameter>rdtype</parameter></paramdef>

35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt <paramdef>unsigned int <parameter>flags</parameter></paramdef>

35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt <paramdef>struct rrsetinfo **<parameter>res</parameter></paramdef>

35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt </funcprototype>

35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt<funcprototype>

35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt <funcdef>

35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Huntvoid

35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt<function>lwres_freerrset</function></funcdef>

35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt <paramdef>struct rrsetinfo *<parameter>rrset</parameter></paramdef>

35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt </funcprototype>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt</funcsynopsis>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <para>

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt The following structures are used:

9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt </para>

222d38735f97f771054e223b03f84c5858252332Evan Hunt <para><programlisting>

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyerstruct rdatainfo {

c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer unsigned int rdi_length; /* length of data */

c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer unsigned char *rdi_data; /* record data */

ac21f918f23ce95fd5be807428ee9e2c42319878Evan Hunt};

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews</programlisting>

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews </para>

ac21f918f23ce95fd5be807428ee9e2c42319878Evan Hunt <para><programlisting>

ac21f918f23ce95fd5be807428ee9e2c42319878Evan Huntstruct rrsetinfo {

c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer unsigned int rri_flags; /* RRSET_VALIDATED... */

c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer unsigned int rri_rdclass; /* class number */

c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer unsigned int rri_rdtype; /* RR type number */

2c15fcdeac4c2402258867fbac24d7475ef98259Mark Andrews unsigned int rri_ttl; /* time to live */

c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer unsigned int rri_nrdatas; /* size of rdatas array */

c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer unsigned int rri_nsigs; /* size of sigs array */

ac21f918f23ce95fd5be807428ee9e2c42319878Evan Hunt char *rri_name; /* canonical name */

c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer struct rdatainfo *rri_rdatas; /* individual records */

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews struct rdatainfo *rri_sigs; /* individual signatures */

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews};

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews</programlisting>

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews </para>

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews </refsynopsisdiv>

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews <refsect1>

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews <title>DESCRIPTION</title>

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews <para><function>lwres_getrrsetbyname()</function>

a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews gets a set of resource records associated with a

7318bbc26262a66a0d740ceefed769961ef7e476Evan Hunt <parameter>hostname</parameter>, <parameter>class</parameter>,

7318bbc26262a66a0d740ceefed769961ef7e476Evan Hunt and <parameter>type</parameter>.

7318bbc26262a66a0d740ceefed769961ef7e476Evan Hunt <parameter>hostname</parameter> is a pointer a to

7318bbc26262a66a0d740ceefed769961ef7e476Evan Hunt null-terminated string. The <parameter>flags</parameter> field

7318bbc26262a66a0d740ceefed769961ef7e476Evan Hunt is currently unused and must be zero.

7318bbc26262a66a0d740ceefed769961ef7e476Evan Hunt </para>

7318bbc26262a66a0d740ceefed769961ef7e476Evan Hunt <para>

7318bbc26262a66a0d740ceefed769961ef7e476Evan Hunt After a successful call to

7318bbc26262a66a0d740ceefed769961ef7e476Evan Hunt <function>lwres_getrrsetbyname()</function>,

de5890da9b87cb4b91aca033db0e25b1fdb68c77Evan Hunt <parameter>*res</parameter> is a pointer to an

de5890da9b87cb4b91aca033db0e25b1fdb68c77Evan Hunt <type>rrsetinfo</type> structure, containing a list of one or

de5890da9b87cb4b91aca033db0e25b1fdb68c77Evan Hunt more <type>rdatainfo</type> structures containing resource

de5890da9b87cb4b91aca033db0e25b1fdb68c77Evan Hunt records and potentially another list of <type>rdatainfo</type>

de5890da9b87cb4b91aca033db0e25b1fdb68c77Evan Hunt structures containing SIG resource records associated with those

de5890da9b87cb4b91aca033db0e25b1fdb68c77Evan Hunt records. The members <constant>rri_rdclass</constant> and

de5890da9b87cb4b91aca033db0e25b1fdb68c77Evan Hunt <constant>rri_rdtype</constant> are copied from the parameters.

de5890da9b87cb4b91aca033db0e25b1fdb68c77Evan Hunt <constant>rri_ttl</constant> and <constant>rri_name</constant>

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews are properties of the obtained rrset. The resource records

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews contained in <constant>rri_rdatas</constant> and

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews <constant>rri_sigs</constant> are in uncompressed DNS wire

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews format. Properties of the rdataset are represented in the

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews <constant>rri_flags</constant> bitfield. If the RRSET_VALIDATED

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews bit is set, the data has been DNSSEC validated and the

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews signatures verified.

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews </para>

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews <para>

2c089bf6d24936de631a57b4958ba6b8b5e3b23dMark Andrews All of the information returned by

de5890da9b87cb4b91aca033db0e25b1fdb68c77Evan Hunt <function>lwres_getrrsetbyname()</function> is dynamically

74717eef53ba5d6aefc80eb262bbb090ff4bb3b5Mark Andrews allocated: the <constant>rrsetinfo</constant> and

74717eef53ba5d6aefc80eb262bbb090ff4bb3b5Mark Andrews <constant>rdatainfo</constant> structures, and the canonical

74717eef53ba5d6aefc80eb262bbb090ff4bb3b5Mark Andrews host name strings pointed to by the

74717eef53ba5d6aefc80eb262bbb090ff4bb3b5Mark Andrews <constant>rrsetinfo</constant>structure.

74717eef53ba5d6aefc80eb262bbb090ff4bb3b5Mark Andrews

74717eef53ba5d6aefc80eb262bbb090ff4bb3b5Mark Andrews Memory allocated for the dynamically allocated structures

created by a successful call to

<function>lwres_getrrsetbyname()</function> is released by

<function>lwres_freerrset()</function>.

<parameter>rrset</parameter> is a pointer to a <type>struct

rrset</type> created by a call to

<function>lwres_getrrsetbyname()</function>.

</para>

<para></para>

</refsect1>

<refsect1>

<title>RETURN VALUES</title>

<para><function>lwres_getrrsetbyname()</function>

returns zero on success, and one of the following error codes if

an error occurred:

<variablelist>

<varlistentry>

<term><constant>ERRSET_NONAME</constant></term>

<listitem>

<para>

the name does not exist

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>ERRSET_NODATA</constant></term>

<listitem>

<para>

the name exists, but does not have data of the desired type

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>ERRSET_NOMEMORY</constant></term>

<listitem>

<para>

memory could not be allocated

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>ERRSET_INVAL</constant></term>

<listitem>

<para>

a parameter is invalid

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>ERRSET_FAIL</constant></term>

<listitem>

<para>

other failure

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><constant/></term>

<listitem>

<para></para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1>

<title>SEE ALSO</title>

<para><citerefentry>

<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>.

</para>

</refsect1>

</refentry><!--