225 lines
6.3 KiB
Plaintext
225 lines
6.3 KiB
Plaintext
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
|
|
[<!ENTITY mdash "—">]>
|
|
<!--
|
|
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
|
|
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
|
-
|
|
- Permission to use, copy, modify, and distribute this software for any
|
|
- purpose with or without fee is hereby granted, provided that the above
|
|
- copyright notice and this permission notice appear in all copies.
|
|
-
|
|
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
|
|
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
|
|
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
- PERFORMANCE OF THIS SOFTWARE.
|
|
-->
|
|
|
|
<!-- $Id: lwres_getrrsetbyname.docbook,v 1.3.206.3 2005/05/12 21:36:15 sra Exp $ -->
|
|
|
|
<refentry>
|
|
<refentryinfo>
|
|
|
|
|
|
<date>Oct 18, 2000</date>
|
|
</refentryinfo>
|
|
<refmeta>
|
|
<refentrytitle>lwres_getrrsetbyname</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo>BIND9</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<docinfo>
|
|
<copyright>
|
|
<year>2004</year>
|
|
<year>2005</year>
|
|
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
|
|
</copyright>
|
|
<copyright>
|
|
<year>2000</year>
|
|
<year>2001</year>
|
|
<holder>Internet Software Consortium.</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 *hostname</paramdef>
|
|
<paramdef>unsigned int rdclass</paramdef>
|
|
<paramdef>unsigned int rdtype</paramdef>
|
|
<paramdef>unsigned int flags</paramdef>
|
|
<paramdef>struct rrsetinfo **res</paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>
|
|
void
|
|
<function>lwres_freerrset</function></funcdef>
|
|
<paramdef>struct rrsetinfo *rrset</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
The following structures are used:
|
|
<programlisting>
|
|
struct rdatainfo {
|
|
unsigned int rdi_length; /* length of data */
|
|
unsigned char *rdi_data; /* record data */
|
|
};
|
|
|
|
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>
|
|
|
|
<refsect1>
|
|
<title>DESCRIPTION</title>
|
|
<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>
|
|
</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></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>
|