lwres_getrrsetbyname.html revision 71c66a876ecca77923638d3f94cc0783152b2f03
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder - Copyright (C) 2000, 2001 Internet Software Consortium.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - Permission to use, copy, modify, and distribute this software for any
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - purpose with or without fee is hereby granted, provided that the above
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - copyright notice and this permission notice appear in all copies.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
d8c71aacc9f1c8cd40a8ad8dcdad9be8854b849fChristian Maeder - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - PERFORMANCE OF THIS SOFTWARE.
96646aed2ae087b942ae23f15bbe729a8f7c43d3Christian Maeder<!-- $Id: lwres_getrrsetbyname.html,v 1.20 2006/06/29 13:03:32 marka Exp $ -->
01e383014b555bbcf639c0ca60c5810b3eff83c0Christian Maeder<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
83394c6b6e6de128e71b67c9251ed7a84485d082Christian Maeder<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
ce8b15da31cd181b7e90593cbbca98f47eda29d6Till Mossakowski<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<a name="id2482688"></a><div class="titlepage"></div>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<p>lwres_getrrsetbyname, lwres_freerrset — retrieve DNS records</p>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre>
2e2094a642e3775b0d76b890556407941d3a53b6Christian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<b class="fsfunc">lwres_getrrsetbyname</b>(</code></td>
a2d6702f18737cc5fff8e8631c08f221f8375c4bChristian Maeder<var class="pdparam">res</var><code>)</code>;</td>
c55a0f77be7e88d3620b419ec8961f4379a586e3Klaus Luettich<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
8cacad2a09782249243b80985f28e9387019fe40Christian Maeder<b class="fsfunc">lwres_freerrset</b>(</code></td>
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder<var class="pdparam">rrset</var><code>)</code>;</td>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<var class="pdparam">rrset</var><code>)</code>;</td>
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder The following structures are used:
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maederstruct rdatainfo {
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder unsigned int rdi_length; /* length of data */
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder unsigned char *rdi_data; /* record data */
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maederstruct rrsetinfo {
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder unsigned int rri_flags; /* RRSET_VALIDATED... */
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder unsigned int rri_rdclass; /* class number */
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder unsigned int rri_rdtype; /* RR type number */
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder unsigned int rri_ttl; /* time to live */
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder unsigned int rri_nrdatas; /* size of rdatas array */
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder unsigned int rri_nsigs; /* size of sigs array */
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder char *rri_name; /* canonical name */
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder struct rdatainfo *rri_rdatas; /* individual records */
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder struct rdatainfo *rri_sigs; /* individual signatures */
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<a name="id2549472"></a><h2>DESCRIPTION</h2>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<p><code class="function">lwres_getrrsetbyname()</code>
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder gets a set of resource records associated with a
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <em class="parameter"><code>hostname</code></em>, <em class="parameter"><code>class</code></em>,
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder and <em class="parameter"><code>type</code></em>.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <em class="parameter"><code>hostname</code></em> is a pointer a to
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder null-terminated string. The <em class="parameter"><code>flags</code></em> field
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder is currently unused and must be zero.
a3c6d8e0670bf2aa71bc8e2a3b1f45d56dd65e4cChristian Maeder After a successful call to
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="function">lwres_getrrsetbyname()</code>,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <em class="parameter"><code>*res</code></em> is a pointer to an
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <span class="type">rrsetinfo</span> structure, containing a list of one or
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder more <span class="type">rdatainfo</span> structures containing resource
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder records and potentially another list of <span class="type">rdatainfo</span>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder structures containing SIG resource records associated with those
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder records. The members <code class="constant">rri_rdclass</code> and
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <code class="constant">rri_rdtype</code> are copied from the parameters.
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder <code class="constant">rri_ttl</code> and <code class="constant">rri_name</code>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder are properties of the obtained rrset. The resource records
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder contained in <code class="constant">rri_rdatas</code> and
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="constant">rri_sigs</code> are in uncompressed DNS wire
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder format. Properties of the rdataset are represented in the
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="constant">rri_flags</code> bitfield. If the RRSET_VALIDATED
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder bit is set, the data has been DNSSEC validated and the
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder signatures verified.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder All of the information returned by
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <code class="function">lwres_getrrsetbyname()</code> is dynamically
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder allocated: the <code class="constant">rrsetinfo</code> and
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="constant">rdatainfo</code> structures, and the canonical
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder host name strings pointed to by the
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <code class="constant">rrsetinfo</code>structure.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder Memory allocated for the dynamically allocated structures
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder created by a successful call to
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder <code class="function">lwres_getrrsetbyname()</code> is released by
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder <code class="function">lwres_freerrset()</code>.
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder <em class="parameter"><code>rrset</code></em> is a pointer to a <span class="type">struct
f4505a64a089693012a3f5c3b1f12a82cd7a2a5aKlaus Luettich rrset</span> created by a call to
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <code class="function">lwres_getrrsetbyname()</code>.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<a name="id2549652"></a><h2>RETURN VALUES</h2>
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder<p><code class="function">lwres_getrrsetbyname()</code>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder returns zero on success, and one of the following error codes if
c9acb8681bcc512245b4f0d1a9f2b189c60e10d4Christian Maeder an error occurred:
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder<dt><span class="term"><code class="constant">ERRSET_NONAME</code></span></dt>
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder the name does not exist
0cfef6179a1bfec4f07f460686dd629a27b4b778Christian Maeder<dt><span class="term"><code class="constant">ERRSET_NODATA</code></span></dt>
83394c6b6e6de128e71b67c9251ed7a84485d082Christian Maeder the name exists, but does not have data of the desired type
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<dt><span class="term"><code class="constant">ERRSET_NOMEMORY</code></span></dt>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder memory could not be allocated
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<dt><span class="term"><code class="constant">ERRSET_INVAL</code></span></dt>
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder a parameter is invalid
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers<dt><span class="term"><code class="constant">ERRSET_FAIL</code></span></dt>
fb328c4f646dd3dd78a9391c5cb58450a3dd0aa9Klaus Luettich other failure
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers<dt><span class="term"><code class="constant"></code></span></dt>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder<p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>.