diff options
Diffstat (limited to 'contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook')
| -rw-r--r-- | contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook b/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook new file mode 100644 index 000000000000..5ec7884b360c --- /dev/null +++ b/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook @@ -0,0 +1,208 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<!-- + - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 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.1 2004/03/06 08:15:40 marka Exp $ --> + +<refentry> +<refentryinfo> + + +<date>Oct 18, 2000</date> +</refentryinfo> +<refmeta> +<refentrytitle>lwres_getrrsetbyname</refentrytitle> +<manvolnum>3</manvolnum> +<refmiscinfo>BIND9</refmiscinfo> +</refmeta> +<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> |