1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 3 [<!ENTITY mdash "—">]> 4<!-- 5 - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC") 6 - Copyright (C) 2000, 2001 Internet Software Consortium. 7 - 8 - Permission to use, copy, modify, and/or distribute this software for any 9 - purpose with or without fee is hereby granted, provided that the above 10 - copyright notice and this permission notice appear in all copies. 11 - 12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18 - PERFORMANCE OF THIS SOFTWARE. 19--> 20 21<refentry> 22 23 <refentryinfo> 24 <date>June 18, 2007</date> 25 </refentryinfo> 26 27 <refmeta> 28 <refentrytitle>lwres_getrrsetbyname</refentrytitle> 29 <manvolnum>3</manvolnum> 30 <refmiscinfo>BIND9</refmiscinfo> 31 </refmeta> 32 33 <docinfo> 34 <copyright> 35 <year>2004</year> 36 <year>2005</year> 37 <year>2007</year> 38 <year>2014</year> 39 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 40 </copyright> 41 <copyright> 42 <year>2000</year> 43 <year>2001</year> 44 <holder>Internet Software Consortium.</holder> 45 </copyright> 46 </docinfo> 47 48 <refnamediv> 49 <refname>lwres_getrrsetbyname</refname> 50 <refname>lwres_freerrset</refname> 51 <refpurpose>retrieve DNS records</refpurpose> 52 </refnamediv> 53 <refsynopsisdiv> 54 <funcsynopsis> 55<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> 56<funcprototype> 57 <funcdef> 58int 59<function>lwres_getrrsetbyname</function></funcdef> 60 <paramdef>const char *<parameter>hostname</parameter></paramdef> 61 <paramdef>unsigned int <parameter>rdclass</parameter></paramdef> 62 <paramdef>unsigned int <parameter>rdtype</parameter></paramdef> 63 <paramdef>unsigned int <parameter>flags</parameter></paramdef> 64 <paramdef>struct rrsetinfo **<parameter>res</parameter></paramdef> 65 </funcprototype> 66<funcprototype> 67 <funcdef> 68void 69<function>lwres_freerrset</function></funcdef> 70 <paramdef>struct rrsetinfo *<parameter>rrset</parameter></paramdef> 71 </funcprototype> 72</funcsynopsis> 73 74 <para> 75 The following structures are used: 76 </para> 77 <para><programlisting> 78struct rdatainfo { 79 unsigned int rdi_length; /* length of data */ 80 unsigned char *rdi_data; /* record data */ 81}; 82</programlisting> 83 </para> 84 <para><programlisting> 85struct rrsetinfo { 86 unsigned int rri_flags; /* RRSET_VALIDATED... */ 87 unsigned int rri_rdclass; /* class number */ 88 unsigned int rri_rdtype; /* RR type number */ 89 unsigned int rri_ttl; /* time to live */ 90 unsigned int rri_nrdatas; /* size of rdatas array */ 91 unsigned int rri_nsigs; /* size of sigs array */ 92 char *rri_name; /* canonical name */ 93 struct rdatainfo *rri_rdatas; /* individual records */ 94 struct rdatainfo *rri_sigs; /* individual signatures */ 95}; 96</programlisting> 97 </para> 98 </refsynopsisdiv> 99 100 <refsect1> 101 <title>DESCRIPTION</title> 102 <para><function>lwres_getrrsetbyname()</function> 103 gets a set of resource records associated with a 104 <parameter>hostname</parameter>, <parameter>class</parameter>, 105 and <parameter>type</parameter>. 106 <parameter>hostname</parameter> is a pointer a to 107 null-terminated string. The <parameter>flags</parameter> field 108 is currently unused and must be zero. 109 </para> 110 <para> 111 After a successful call to 112 <function>lwres_getrrsetbyname()</function>, 113 <parameter>*res</parameter> is a pointer to an 114 <type>rrsetinfo</type> structure, containing a list of one or 115 more <type>rdatainfo</type> structures containing resource 116 records and potentially another list of <type>rdatainfo</type> 117 structures containing SIG resource records associated with those 118 records. The members <constant>rri_rdclass</constant> and 119 <constant>rri_rdtype</constant> are copied from the parameters. 120 <constant>rri_ttl</constant> and <constant>rri_name</constant> 121 are properties of the obtained rrset. The resource records 122 contained in <constant>rri_rdatas</constant> and 123 <constant>rri_sigs</constant> are in uncompressed DNS wire 124 format. Properties of the rdataset are represented in the 125 <constant>rri_flags</constant> bitfield. If the RRSET_VALIDATED 126 bit is set, the data has been DNSSEC validated and the 127 signatures verified. 128 </para> 129 <para> 130 All of the information returned by 131 <function>lwres_getrrsetbyname()</function> is dynamically 132 allocated: the <constant>rrsetinfo</constant> and 133 <constant>rdatainfo</constant> structures, and the canonical 134 host name strings pointed to by the 135 <constant>rrsetinfo</constant>structure. 136 137 Memory allocated for the dynamically allocated structures 138 created by a successful call to 139 <function>lwres_getrrsetbyname()</function> is released by 140 <function>lwres_freerrset()</function>. 141 142 <parameter>rrset</parameter> is a pointer to a <type>struct 143 rrset</type> created by a call to 144 <function>lwres_getrrsetbyname()</function>. 145 </para> 146 <para></para> 147 </refsect1> 148 <refsect1> 149 <title>RETURN VALUES</title> 150 <para><function>lwres_getrrsetbyname()</function> 151 returns zero on success, and one of the following error codes if 152 an error occurred: 153 <variablelist> 154 155 <varlistentry> 156 <term><constant>ERRSET_NONAME</constant></term> 157 <listitem> 158 <para> 159 the name does not exist 160 </para> 161 </listitem> 162 </varlistentry> 163 164 <varlistentry> 165 <term><constant>ERRSET_NODATA</constant></term> 166 <listitem> 167 <para> 168 the name exists, but does not have data of the desired type 169 </para> 170 </listitem> 171 </varlistentry> 172 173 <varlistentry> 174 <term><constant>ERRSET_NOMEMORY</constant></term> 175 <listitem> 176 <para> 177 memory could not be allocated 178 </para> 179 </listitem> 180 </varlistentry> 181 182 <varlistentry> 183 <term><constant>ERRSET_INVAL</constant></term> 184 <listitem> 185 <para> 186 a parameter is invalid 187 </para> 188 </listitem> 189 </varlistentry> 190 191 <varlistentry> 192 <term><constant>ERRSET_FAIL</constant></term> 193 <listitem> 194 <para> 195 other failure 196 </para> 197 </listitem> 198 </varlistentry> 199 200 <varlistentry> 201 <term><constant/></term> 202 <listitem> 203 <para></para> 204 </listitem> 205 </varlistentry> 206 207 </variablelist> 208 209 </para> 210 </refsect1> 211 <refsect1> 212 <title>SEE ALSO</title> 213 <para><citerefentry> 214 <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> 215 </citerefentry>. 216 </para> 217 218 </refsect1> 219</refentry><!-- 220 - Local variables: 221 - mode: sgml 222 - End: 223--> 224