/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.html
HTML | 192 lines | 172 code | 3 blank | 17 comment | 0 complexity | a9b4fffe46e4f265fd6d7f669d7e62cd MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
1<!-- 2 - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC") 3 - Copyright (C) 2000, 2001 Internet Software Consortium. 4 - 5 - Permission to use, copy, modify, and/or distribute this software for any 6 - purpose with or without fee is hereby granted, provided that the above 7 - copyright notice and this permission notice appear in all copies. 8 - 9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 - PERFORMANCE OF THIS SOFTWARE. 16--> 17<!-- $Id$ --> 18<html> 19<head> 20<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 21<title>lwres_getrrsetbyname</title> 22<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> 23</head> 24<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> 25<a name="id2476275"></a><div class="titlepage"></div> 26<div class="refnamediv"> 27<h2>Name</h2> 28<p>lwres_getrrsetbyname, lwres_freerrset — retrieve DNS records</p> 29</div> 30<div class="refsynopsisdiv"> 31<h2>Synopsis</h2> 32<div class="funcsynopsis"> 33<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre> 34<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 35<tr> 36<td><code class="funcdef"> 37int 38<b class="fsfunc">lwres_getrrsetbyname</b>(</code></td> 39<td>const char * </td> 40<td> 41<var class="pdparam">hostname</var>, </td> 42</tr> 43<tr> 44<td> </td> 45<td>unsigned int </td> 46<td> 47<var class="pdparam">rdclass</var>, </td> 48</tr> 49<tr> 50<td> </td> 51<td>unsigned int </td> 52<td> 53<var class="pdparam">rdtype</var>, </td> 54</tr> 55<tr> 56<td> </td> 57<td>unsigned int </td> 58<td> 59<var class="pdparam">flags</var>, </td> 60</tr> 61<tr> 62<td> </td> 63<td>struct rrsetinfo ** </td> 64<td> 65<var class="pdparam">res</var><code>)</code>;</td> 66</tr> 67</table> 68<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> 69<td><code class="funcdef"> 70void 71<b class="fsfunc">lwres_freerrset</b>(</code></td> 72<td>struct rrsetinfo * </td> 73<td> 74<var class="pdparam">rrset</var><code>)</code>;</td> 75</tr></table> 76</div> 77<p> 78 The following structures are used: 79 </p> 80<pre class="programlisting"> 81struct rdatainfo { 82 unsigned int rdi_length; /* length of data */ 83 unsigned char *rdi_data; /* record data */ 84}; 85</pre> 86<p> 87 </p> 88<pre class="programlisting"> 89struct rrsetinfo { 90 unsigned int rri_flags; /* RRSET_VALIDATED... */ 91 unsigned int rri_rdclass; /* class number */ 92 unsigned int rri_rdtype; /* RR type number */ 93 unsigned int rri_ttl; /* time to live */ 94 unsigned int rri_nrdatas; /* size of rdatas array */ 95 unsigned int rri_nsigs; /* size of sigs array */ 96 char *rri_name; /* canonical name */ 97 struct rdatainfo *rri_rdatas; /* individual records */ 98 struct rdatainfo *rri_sigs; /* individual signatures */ 99}; 100</pre> 101<p> 102 </p> 103</div> 104<div class="refsect1" lang="en"> 105<a name="id2543418"></a><h2>DESCRIPTION</h2> 106<p><code class="function">lwres_getrrsetbyname()</code> 107 gets a set of resource records associated with a 108 <em class="parameter"><code>hostname</code></em>, <em class="parameter"><code>class</code></em>, 109 and <em class="parameter"><code>type</code></em>. 110 <em class="parameter"><code>hostname</code></em> is a pointer a to 111 null-terminated string. The <em class="parameter"><code>flags</code></em> field 112 is currently unused and must be zero. 113 </p> 114<p> 115 After a successful call to 116 <code class="function">lwres_getrrsetbyname()</code>, 117 <em class="parameter"><code>*res</code></em> is a pointer to an 118 <span class="type">rrsetinfo</span> structure, containing a list of one or 119 more <span class="type">rdatainfo</span> structures containing resource 120 records and potentially another list of <span class="type">rdatainfo</span> 121 structures containing SIG resource records associated with those 122 records. The members <code class="constant">rri_rdclass</code> and 123 <code class="constant">rri_rdtype</code> are copied from the parameters. 124 <code class="constant">rri_ttl</code> and <code class="constant">rri_name</code> 125 are properties of the obtained rrset. The resource records 126 contained in <code class="constant">rri_rdatas</code> and 127 <code class="constant">rri_sigs</code> are in uncompressed DNS wire 128 format. Properties of the rdataset are represented in the 129 <code class="constant">rri_flags</code> bitfield. If the RRSET_VALIDATED 130 bit is set, the data has been DNSSEC validated and the 131 signatures verified. 132 </p> 133<p> 134 All of the information returned by 135 <code class="function">lwres_getrrsetbyname()</code> is dynamically 136 allocated: the <code class="constant">rrsetinfo</code> and 137 <code class="constant">rdatainfo</code> structures, and the canonical 138 host name strings pointed to by the 139 <code class="constant">rrsetinfo</code>structure. 140 141 Memory allocated for the dynamically allocated structures 142 created by a successful call to 143 <code class="function">lwres_getrrsetbyname()</code> is released by 144 <code class="function">lwres_freerrset()</code>. 145 146 <em class="parameter"><code>rrset</code></em> is a pointer to a <span class="type">struct 147 rrset</span> created by a call to 148 <code class="function">lwres_getrrsetbyname()</code>. 149 </p> 150<p></p> 151</div> 152<div class="refsect1" lang="en"> 153<a name="id2543530"></a><h2>RETURN VALUES</h2> 154<p><code class="function">lwres_getrrsetbyname()</code> 155 returns zero on success, and one of the following error codes if 156 an error occurred: 157 </p> 158<div class="variablelist"><dl> 159<dt><span class="term"><code class="constant">ERRSET_NONAME</code></span></dt> 160<dd><p> 161 the name does not exist 162 </p></dd> 163<dt><span class="term"><code class="constant">ERRSET_NODATA</code></span></dt> 164<dd><p> 165 the name exists, but does not have data of the desired type 166 </p></dd> 167<dt><span class="term"><code class="constant">ERRSET_NOMEMORY</code></span></dt> 168<dd><p> 169 memory could not be allocated 170 </p></dd> 171<dt><span class="term"><code class="constant">ERRSET_INVAL</code></span></dt> 172<dd><p> 173 a parameter is invalid 174 </p></dd> 175<dt><span class="term"><code class="constant">ERRSET_FAIL</code></span></dt> 176<dd><p> 177 other failure 178 </p></dd> 179<dt><span class="term"><code class="constant"></code></span></dt> 180<dd><p></p></dd> 181</dl></div> 182<p> 183 184 </p> 185</div> 186<div class="refsect1" lang="en"> 187<a name="id2543630"></a><h2>SEE ALSO</h2> 188<p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>. 189 </p> 190</div> 191</div></body> 192</html>