lwres_getrrsetbyname.html revision fd2597f75693a2279fdf588bd40dfe2407c42028
b5205d860b1672c405c57004e6823af873799b42Mark Andrews - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
b5205d860b1672c405c57004e6823af873799b42Mark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
9a1e8f1baf3e5c53d6b6bfa97d7f60cb3358e404Mark Andrews - Permission to use, copy, modify, and/or distribute this software for any
c79e85f7d77317a9b5c34b4bb94eaf1779fc0b6eMark Andrews - purpose with or without fee is hereby granted, provided that the above
c79e85f7d77317a9b5c34b4bb94eaf1779fc0b6eMark Andrews - copyright notice and this permission notice appear in all copies.
12b1bf8b14ac3b6ec4de9cae6fea10f389b5e5dbMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12b1bf8b14ac3b6ec4de9cae6fea10f389b5e5dbMark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
12b1bf8b14ac3b6ec4de9cae6fea10f389b5e5dbMark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
e22bd3c4bc0de0b96531fab5c2c944251e02e975Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
e22bd3c4bc0de0b96531fab5c2c944251e02e975Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
e22bd3c4bc0de0b96531fab5c2c944251e02e975Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
9c420baae0dce935d70df3852bc3abdfe5caf093Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
11e43ff752bab2983d9328b6624bbcef613a93e1Mark Andrews<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
444bbadb54d4a676aa4b20685d3178d7988534b3Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
cd6d8d61b076eea02826596334a105b918393627Mark Andrews<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
cd6d8d61b076eea02826596334a105b918393627Mark Andrews<a name="id-1"></a><div class="titlepage"></div>
f04809663f4ba3df0e2ef1247d67bdd6ce0157d6Mark Andrews<p>lwres_getrrsetbyname, lwres_freerrset — retrieve DNS records</p>
21b76ee598c937c6736cbc7ab69684bb3332428aMark Andrews<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre>
21b76ee598c937c6736cbc7ab69684bb3332428aMark Andrews<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
5c45d30402af6860e1f66f5aa7d78dff58373b27Mark Andrews<b class="fsfunc">lwres_getrrsetbyname</b>(</code></td>
b66ca17f2990433a3e277b50cc3c15f19cdd0771Mark Andrews<td>const char *<var class="pdparam">hostname</var>, </td>
dc1f18f211a91735faf2771acc8438f0fbc70d4bMark Andrews<td>unsigned int <var class="pdparam">rdclass</var>, </td>
82ecc9cd96239649dfeb0a16e31c3b978d0d266aMark Andrews<td>unsigned int <var class="pdparam">rdtype</var>, </td>
6412902ffc0d255657f54db768f30b6efa819143Mark Andrews<td>unsigned int <var class="pdparam">flags</var>, </td>
6412902ffc0d255657f54db768f30b6efa819143Mark Andrews<td>struct rrsetinfo **<var class="pdparam">res</var><code>)</code>;</td>
0d8971a4b8abed599ec9d9b7d1b51b8de8038ce2Shane Kerr<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
a8f950ff05e2e81d425a3411268cdf21f8f26b16Mark Andrews<b class="fsfunc">lwres_freerrset</b>(</code></td>
bc1467288a25b48446d3229fef0a19fad0cb6f2fMark Andrews<td>struct rrsetinfo *<var class="pdparam">rrset</var><code>)</code>;</td>
6ed53e5949d9fcd9715b440015b56e5a896d63dfDavid Hankins The following structures are used:
f19353d73186913a6e0f0f766c1f72e5f4c5e9e1Tatuya JINMEI 神明達哉struct rdatainfo {
84910d09ee8244027c7031e03999bc60a3d63adbMark Andrews unsigned int rdi_length; /* length of data */
84910d09ee8244027c7031e03999bc60a3d63adbMark Andrews unsigned char *rdi_data; /* record data */
d2ef84e07b67e72a4bd9c729c6b8228067d17584Mark Andrewsstruct rrsetinfo {
d2ef84e07b67e72a4bd9c729c6b8228067d17584Mark Andrews unsigned int rri_flags; /* RRSET_VALIDATED... */
cfe92110ce4eaf19f7f3255d2961710879bdc9ddMark Andrews unsigned int rri_rdclass; /* class number */
cfe92110ce4eaf19f7f3255d2961710879bdc9ddMark Andrews unsigned int rri_rdtype; /* RR type number */
cfe92110ce4eaf19f7f3255d2961710879bdc9ddMark Andrews unsigned int rri_ttl; /* time to live */
cfe92110ce4eaf19f7f3255d2961710879bdc9ddMark Andrews unsigned int rri_nrdatas; /* size of rdatas array */
fe6f384b2efde528dabbf822634eedc020be67e0Mark Andrews unsigned int rri_nsigs; /* size of sigs array */
fe6f384b2efde528dabbf822634eedc020be67e0Mark Andrews char *rri_name; /* canonical name */
fe6f384b2efde528dabbf822634eedc020be67e0Mark Andrews struct rdatainfo *rri_rdatas; /* individual records */
fe6f384b2efde528dabbf822634eedc020be67e0Mark Andrews struct rdatainfo *rri_sigs; /* individual signatures */
5929cde251d6d971fda14ac9ea927035421f6480Mark Andrews<p><code class="function">lwres_getrrsetbyname()</code>
5929cde251d6d971fda14ac9ea927035421f6480Mark Andrews gets a set of resource records associated with a
5929cde251d6d971fda14ac9ea927035421f6480Mark Andrews <em class="parameter"><code>hostname</code></em>, <em class="parameter"><code>class</code></em>,
5929cde251d6d971fda14ac9ea927035421f6480Mark Andrews and <em class="parameter"><code>type</code></em>.
1412643ba5bcc735c3731d8cebf71fd76eedec91Mark Andrews <em class="parameter"><code>hostname</code></em> is a pointer a to
1412643ba5bcc735c3731d8cebf71fd76eedec91Mark Andrews null-terminated string. The <em class="parameter"><code>flags</code></em> field
1412643ba5bcc735c3731d8cebf71fd76eedec91Mark Andrews is currently unused and must be zero.
6de9371826bd253eb29aa3965ef03670d9d0a06dMark Andrews After a successful call to
6de9371826bd253eb29aa3965ef03670d9d0a06dMark Andrews <code class="function">lwres_getrrsetbyname()</code>,
6de9371826bd253eb29aa3965ef03670d9d0a06dMark Andrews <em class="parameter"><code>*res</code></em> is a pointer to an
6de9371826bd253eb29aa3965ef03670d9d0a06dMark Andrews <span class="type">rrsetinfo</span> structure, containing a list of one or
daba3af103617ce4dd49bfdd0d9e07df7f22d08dMark Andrews more <span class="type">rdatainfo</span> structures containing resource
daba3af103617ce4dd49bfdd0d9e07df7f22d08dMark Andrews records and potentially another list of <span class="type">rdatainfo</span>
59d84d1b077678cb77f6cbcc53d8cfa60ff69cb7Mark Andrews structures containing SIG resource records associated with those
59d84d1b077678cb77f6cbcc53d8cfa60ff69cb7Mark Andrews records. The members <code class="constant">rri_rdclass</code> and
59d84d1b077678cb77f6cbcc53d8cfa60ff69cb7Mark Andrews <code class="constant">rri_rdtype</code> are copied from the parameters.
59d84d1b077678cb77f6cbcc53d8cfa60ff69cb7Mark Andrews <code class="constant">rri_ttl</code> and <code class="constant">rri_name</code>
ac124a78a097a0840992c5726cbbdaf1448b6ab3Mark Andrews are properties of the obtained rrset. The resource records
d76ed813a51465e5c47d521ab09ea20c06f1428dMark Andrews contained in <code class="constant">rri_rdatas</code> and
d76ed813a51465e5c47d521ab09ea20c06f1428dMark Andrews <code class="constant">rri_sigs</code> are in uncompressed DNS wire
b6d199bd6a505d84093874339056d9df4d21dfbcMark Andrews format. Properties of the rdataset are represented in the
b6d199bd6a505d84093874339056d9df4d21dfbcMark Andrews <code class="constant">rri_flags</code> bitfield. If the RRSET_VALIDATED
b6d199bd6a505d84093874339056d9df4d21dfbcMark Andrews bit is set, the data has been DNSSEC validated and the
b6d199bd6a505d84093874339056d9df4d21dfbcMark Andrews signatures verified.
1d7b3b6dac1a0c6c586808c2add2ca2bef80512fMark Andrews All of the information returned by
1d7b3b6dac1a0c6c586808c2add2ca2bef80512fMark Andrews <code class="function">lwres_getrrsetbyname()</code> is dynamically
f27eae9cfeb5b6c3c38ead6a7a0b1dd36bba691dMark Andrews allocated: the <code class="constant">rrsetinfo</code> and
f27eae9cfeb5b6c3c38ead6a7a0b1dd36bba691dMark Andrews <code class="constant">rdatainfo</code> structures, and the canonical
f27eae9cfeb5b6c3c38ead6a7a0b1dd36bba691dMark Andrews host name strings pointed to by the
9a8cec4995c1586d27e95f13d421e4de61a97eb5Mark Andrews <code class="constant">rrsetinfo</code>structure.
9a8cec4995c1586d27e95f13d421e4de61a97eb5Mark Andrews Memory allocated for the dynamically allocated structures
25c18fded02c5df8391a333e90ea776b52bff079Mark Andrews created by a successful call to
25c18fded02c5df8391a333e90ea776b52bff079Mark Andrews <code class="function">lwres_getrrsetbyname()</code> is released by
7042126e8a10315255144989f7723f0510558928Mark Andrews <code class="function">lwres_freerrset()</code>.
7042126e8a10315255144989f7723f0510558928Mark Andrews <em class="parameter"><code>rrset</code></em> is a pointer to a <span class="type">struct
7042126e8a10315255144989f7723f0510558928Mark Andrews rrset</span> created by a call to
5581e28ed8c05350ce6119230c223da60dafdbafMark Andrews <code class="function">lwres_getrrsetbyname()</code>.
45e1bd63587102c3bb361eaca42ee7b714fb3542Mark Andrews<p><code class="function">lwres_getrrsetbyname()</code>
c4008fdd56a8045802ed125e40a06bf1df9b7fbeMark Andrews returns zero on success, and one of the following error codes if
c4008fdd56a8045802ed125e40a06bf1df9b7fbeMark Andrews an error occurred:
c4008fdd56a8045802ed125e40a06bf1df9b7fbeMark Andrews<div class="variablelist"><dl class="variablelist">
4f54d095945d6f60f146112d37d31815ad73eb02Mark Andrews<dt><span class="term"><code class="constant">ERRSET_NONAME</code></span></dt>
4f54d095945d6f60f146112d37d31815ad73eb02Mark Andrews the name does not exist
472ce617b7c19ae38dfaa2fc9e8699e3bf9be4a8Mark Andrews<dt><span class="term"><code class="constant">ERRSET_NODATA</code></span></dt>
c5387e694299c41361660e54f23e89c7da3ede1dMark Andrews the name exists, but does not have data of the desired type
d00e58d4814b45c13434721b5771782e485dcb73Mark Andrews<dt><span class="term"><code class="constant">ERRSET_NOMEMORY</code></span></dt>
f3a8cd3835463b47a8e3dc84cd8e7a02bcd7fee8Mark Andrews memory could not be allocated
f3a8cd3835463b47a8e3dc84cd8e7a02bcd7fee8Mark Andrews<dt><span class="term"><code class="constant">ERRSET_INVAL</code></span></dt>
f3a8cd3835463b47a8e3dc84cd8e7a02bcd7fee8Mark Andrews a parameter is invalid
f3a8cd3835463b47a8e3dc84cd8e7a02bcd7fee8Mark Andrews<dt><span class="term"><code class="constant">ERRSET_FAIL</code></span></dt>
f3a8cd3835463b47a8e3dc84cd8e7a02bcd7fee8Mark Andrews other failure
f3a8cd3835463b47a8e3dc84cd8e7a02bcd7fee8Mark Andrews<dt><span class="term"><code class="constant"></code></span></dt>
3bf783a6d4627266d76b0ebdc05afdccb3d06ad0Mark Andrews<p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>.