- Copyright (C) Internet Systems Consortium, Inc. ("ISC")

 -

 - This Source Code Form is subject to the terms of the Mozilla Public

 - License, v. 2.0. If a copy of the MPL was not distributed with this

 - file, You can obtain one at http://mozilla.org/MPL/2.0/.

 -

 - See the COPYRIGHT file distributed with this work for additional

 - information regarding copyright ownership.

-->

<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">

  <info>

    <date>2007-06-18</date>

  </info>

  <refentryinfo>

    <corpname>ISC</corpname>

    <corpauthor>Internet Systems Consortium, Inc.</corpauthor>

  </refentryinfo>

  <refmeta>

    <refentrytitle>lwres_getrrsetbyname</refentrytitle>

    <manvolnum>3</manvolnum>

    <refmiscinfo>BIND9</refmiscinfo>

  </refmeta>

  <docinfo>

    <copyright>

      <year>2000</year>

      <year>2001</year>

      <year>2004</year>

      <year>2005</year>

      <year>2007</year>

      <year>2014</year>

      <year>2015</year>

      <year>2016</year>

      <year>2018</year>

      <year>2019</year>

      <year>2020</year>

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

    </copyright>

  </docinfo>

  <refnamediv>

    <refname>lwres_getrrsetbyname</refname>

    <refname>lwres_freerrset</refname>

    <refpurpose>retrieve DNS records</refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <funcsynopsis>

<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>

<funcprototype>

        <funcdef>

int

<function>lwres_getrrsetbyname</function></funcdef>

        <paramdef>const char *<parameter>hostname</parameter></paramdef>

        <paramdef>unsigned int <parameter>rdclass</parameter></paramdef>

        <paramdef>unsigned int <parameter>rdtype</parameter></paramdef>

        <paramdef>unsigned int <parameter>flags</parameter></paramdef>

        <paramdef>struct rrsetinfo **<parameter>res</parameter></paramdef>

        </funcprototype>

<funcprototype>

        <funcdef>

void

<function>lwres_freerrset</function></funcdef>

        <paramdef>struct rrsetinfo *<parameter>rrset</parameter></paramdef>

      </funcprototype>

</funcsynopsis>

    <para>

      The following structures are used:

    </para>

    <para><programlisting>

struct  rdatainfo {

        unsigned int            rdi_length;     /* length of data */

        unsigned char           *rdi_data;      /* record data */

};

</programlisting>

    </para>

    <para><programlisting>

struct  rrsetinfo {

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

        unsigned int            rri_rdclass;    /* class number */

        unsigned int            rri_rdtype;     /* RR type number */

        unsigned int            rri_ttl;        /* time to live */

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

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

        char                    *rri_name;      /* canonical name */

        struct rdatainfo        *rri_rdatas;    /* individual records */

        struct rdatainfo        *rri_sigs;      /* individual signatures */

};

</programlisting>

    </para>

  </refsynopsisdiv>

  <refsection><info><title>DESCRIPTION</title></info>

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

      gets a set of resource records associated with a

      <parameter>hostname</parameter>, <parameter>class</parameter>,

      and <parameter>type</parameter>.

      <parameter>hostname</parameter> is a pointer a to

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

      is currently unused and must be zero.

    </para>

    <para>

      After a successful call to

      <function>lwres_getrrsetbyname()</function>,

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

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

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

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

      structures containing SIG resource records associated with those

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

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

      <constant>rri_ttl</constant> and <constant>rri_name</constant>

      are properties of the obtained rrset.  The resource records

      contained in <constant>rri_rdatas</constant> and

      <constant>rri_sigs</constant> are in uncompressed DNS wire

      format.  Properties of the rdataset are represented in the

      <constant>rri_flags</constant> bitfield.  If the RRSET_VALIDATED

      bit is set, the data has been DNSSEC validated and the

      signatures verified.

    </para>

    <para>

      All of the information returned by

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

      allocated: the <constant>rrsetinfo</constant> and

      <constant>rdatainfo</constant> structures, and the canonical

      host name strings pointed to by the

      <constant>rrsetinfo</constant>structure.

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

  </refsection>

  <refsection><info><title>RETURN VALUES</title></info>

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

          </listitem>

        </varlistentry>

      </variablelist>

    </para>

  </refsection>

  <refsection><info><title>SEE ALSO</title></info>

    <para><citerefentry>

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

      </citerefentry>.

    </para>

  </refsection>

</refentry>