contrib/bind-9.2.4rc7/lib/lwres/man/lwres_getrrsetbyname.html

   1 <!--
   2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and 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
  18 <!-- $Id: lwres_getrrsetbyname.html,v 1.5.2.2 2004/03/15 04:45:03 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >lwres_getrrsetbyname</TITLE
  24 ><META
  25 NAME="GENERATOR"
  26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
  27 "></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 BGCOLOR="#FFFFFF"
  31 TEXT="#000000"
  32 LINK="#0000FF"
  33 VLINK="#840084"
  34 ALINK="#0000FF"
  35 ><H1
  36 ><A
  37 NAME="AEN1"
  38 >lwres_getrrsetbyname</A
  39 ></H1
  40 ><DIV
  41 CLASS="REFNAMEDIV"
  42 ><A
  43 NAME="AEN8"
  44 ></A
  45 ><H2
  46 >Name</H2
  47 >lwres_getrrsetbyname, lwres_freerrset&nbsp;--&nbsp;retrieve DNS records</DIV
  48 ><DIV
  49 CLASS="REFSYNOPSISDIV"
  50 ><A
  51 NAME="AEN12"
  52 ></A
  53 ><H2
  54 >Synopsis</H2
  55 ><DIV
  56 CLASS="FUNCSYNOPSIS"
  57 ><A
  58 NAME="AEN13"
  59 ></A
  60 ><P
  61 ></P
  62 ><PRE
  63 CLASS="FUNCSYNOPSISINFO"
  64 >#include &lt;lwres/netdb.h&gt;</PRE
  65 ><P
  66 ><CODE
  67 ><CODE
  68 CLASS="FUNCDEF"
  69 >int
  70 lwres_getrrsetbyname</CODE
  71 >(const char *hostname, unsigned int rdclass, unsigned int rdtype, unsigned int flags, struct rrsetinfo **res);</CODE
  72 ></P
  73 ><P
  74 ><CODE
  75 ><CODE
  76 CLASS="FUNCDEF"
  77 >void
  78 lwres_freerrset</CODE
  79 >(struct rrsetinfo *rrset);</CODE
  80 ></P
  81 ><P
  82 ></P
  83 ></DIV
  84 ><P
  85 >The following structures are used:
  86 <PRE
  87 CLASS="PROGRAMLISTING"
  88 >struct  rdatainfo {
  89         unsigned int            rdi_length;     /* length of data */
  90         unsigned char           *rdi_data;      /* record data */
  91 };
  92
  93 struct  rrsetinfo {
  94         unsigned int            rri_flags;      /* RRSET_VALIDATED... */
  95         unsigned int            rri_rdclass;    /* class number */
  96         unsigned int            rri_rdtype;     /* RR type number */
  97         unsigned int            rri_ttl;        /* time to live */
  98         unsigned int            rri_nrdatas;    /* size of rdatas array */
  99         unsigned int            rri_nsigs;      /* size of sigs array */
 100         char                    *rri_name;      /* canonical name */
 101         struct rdatainfo        *rri_rdatas;    /* individual records */
 102         struct rdatainfo        *rri_sigs;      /* individual signatures */
 103 };</PRE
 104 ></P
 105 ></DIV
 106 ><DIV
 107 CLASS="REFSECT1"
 108 ><A
 109 NAME="AEN29"
 110 ></A
 111 ><H2
 112 >DESCRIPTION</H2
 113 ><P
 114 ><TT
 115 CLASS="FUNCTION"
 116 >lwres_getrrsetbyname()</TT
 117 >
 118 gets a set of resource records associated with a
 119 <TT
 120 CLASS="PARAMETER"
 121 ><I
 122 >hostname</I
 123 ></TT
 124 >,
 125
 126 <TT
 127 CLASS="PARAMETER"
 128 ><I
 129 >class</I
 130 ></TT
 131 >,
 132
 133 and
 134 <TT
 135 CLASS="PARAMETER"
 136 ><I
 137 >type</I
 138 ></TT
 139 >.
 140
 141 <TT
 142 CLASS="PARAMETER"
 143 ><I
 144 >hostname</I
 145 ></TT
 146 >
 147 is
 148 a pointer a to null-terminated string.  The
 149 <TT
 150 CLASS="PARAMETER"
 151 ><I
 152 >flags</I
 153 ></TT
 154 >
 155 field is currently unused and must be zero.</P
 156 ><P
 157 >After a successful call to
 158 <TT
 159 CLASS="FUNCTION"
 160 >lwres_getrrsetbyname()</TT
 161 >,
 162
 163 <TT
 164 CLASS="PARAMETER"
 165 ><I
 166 >*res</I
 167 ></TT
 168 >
 169 is a pointer to an
 170 <SPAN
 171 CLASS="TYPE"
 172 >rrsetinfo</SPAN
 173 >
 174 structure, containing a list of one or more
 175 <SPAN
 176 CLASS="TYPE"
 177 >rdatainfo</SPAN
 178 >
 179 structures containing resource records and potentially another list of
 180 <SPAN
 181 CLASS="TYPE"
 182 >rdatainfo</SPAN
 183 >
 184 structures containing SIG resource records
 185 associated with those records.
 186 The members
 187 <TT
 188 CLASS="CONSTANT"
 189 >rri_rdclass</TT
 190 >
 191 and
 192 <TT
 193 CLASS="CONSTANT"
 194 >rri_rdtype</TT
 195 >
 196 are copied from the parameters.
 197 <TT
 198 CLASS="CONSTANT"
 199 >rri_ttl</TT
 200 >
 201 and
 202 <TT
 203 CLASS="CONSTANT"
 204 >rri_name</TT
 205 >
 206 are properties of the obtained rrset.
 207 The resource records contained in
 208 <TT
 209 CLASS="CONSTANT"
 210 >rri_rdatas</TT
 211 >
 212 and
 213 <TT
 214 CLASS="CONSTANT"
 215 >rri_sigs</TT
 216 >
 217 are in uncompressed DNS wire format.
 218 Properties of the rdataset are represented in the
 219 <TT
 220 CLASS="CONSTANT"
 221 >rri_flags</TT
 222 >
 223 bitfield.  If the RRSET_VALIDATED bit is set, the data has been DNSSEC
 224 validated and the signatures verified.  </P
 225 ><P
 226 >All of the information returned by
 227 <TT
 228 CLASS="FUNCTION"
 229 >lwres_getrrsetbyname()</TT
 230 >
 231 is dynamically allocated: the
 232 <TT
 233 CLASS="CONSTANT"
 234 >rrsetinfo</TT
 235 >
 236 and
 237 <TT
 238 CLASS="CONSTANT"
 239 >rdatainfo</TT
 240 >
 241 structures,
 242 and the canonical host name strings pointed to by the
 243 <TT
 244 CLASS="CONSTANT"
 245 >rrsetinfo</TT
 246 >structure.
 247
 248 Memory allocated for the dynamically allocated structures created by
 249 a successful call to
 250 <TT
 251 CLASS="FUNCTION"
 252 >lwres_getrrsetbyname()</TT
 253 >
 254 is released by
 255 <TT
 256 CLASS="FUNCTION"
 257 >lwres_freerrset()</TT
 258 >.
 259
 260 <TT
 261 CLASS="PARAMETER"
 262 ><I
 263 >rrset</I
 264 ></TT
 265 >
 266 is a pointer to a
 267 <SPAN
 268 CLASS="TYPE"
 269 >struct rrset</SPAN
 270 >
 271 created by a call to
 272 <TT
 273 CLASS="FUNCTION"
 274 >lwres_getrrsetbyname()</TT
 275 >.&#13;</P
 276 ><P
 277 ></P
 278 ></DIV
 279 ><DIV
 280 CLASS="REFSECT1"
 281 ><A
 282 NAME="AEN62"
 283 ></A
 284 ><H2
 285 >RETURN VALUES</H2
 286 ><P
 287 ><TT
 288 CLASS="FUNCTION"
 289 >lwres_getrrsetbyname()</TT
 290 >
 291 returns zero on success, and one of the following error
 292 codes if an error occurred:
 293 <P
 294 ></P
 295 ><DIV
 296 CLASS="VARIABLELIST"
 297 ><DL
 298 ><DT
 299 ><TT
 300 CLASS="CONSTANT"
 301 >ERRSET_NONAME</TT
 302 ></DT
 303 ><DD
 304 ><P
 305 >the name does not exist</P
 306 ></DD
 307 ><DT
 308 ><TT
 309 CLASS="CONSTANT"
 310 >ERRSET_NODATA</TT
 311 ></DT
 312 ><DD
 313 ><P
 314 >the name exists, but does not have data of the desired type</P
 315 ></DD
 316 ><DT
 317 ><TT
 318 CLASS="CONSTANT"
 319 >ERRSET_NOMEMORY</TT
 320 ></DT
 321 ><DD
 322 ><P
 323 >memory could not be allocated</P
 324 ></DD
 325 ><DT
 326 ><TT
 327 CLASS="CONSTANT"
 328 >ERRSET_INVAL</TT
 329 ></DT
 330 ><DD
 331 ><P
 332 >a parameter is invalid</P
 333 ></DD
 334 ><DT
 335 ><TT
 336 CLASS="CONSTANT"
 337 >ERRSET_FAIL</TT
 338 ></DT
 339 ><DD
 340 ><P
 341 >other failure</P
 342 ></DD
 343 ><DT
 344 ><TT
 345 CLASS="CONSTANT"
 346 ></TT
 347 ></DT
 348 ><DD
 349 ><P
 350 ></P
 351 ></DD
 352 ></DL
 353 ></DIV
 354 >&#13;</P
 355 ></DIV
 356 ><DIV
 357 CLASS="REFSECT1"
 358 ><A
 359 NAME="AEN97"
 360 ></A
 361 ><H2
 362 >SEE ALSO</H2
 363 ><P
 364 ><SPAN
 365 CLASS="CITEREFENTRY"
 366 ><SPAN
 367 CLASS="REFENTRYTITLE"
 368 >lwres</SPAN
 369 >(3)</SPAN
 370 >.</P
 371 ></DIV
 372 ></BODY
 373 ></HTML
 374 >