doc/html/ref/net-common-tcpip-manpages-getrrsetbyname.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >getrrsetbyname</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="TCP/IP Library Reference"
  23 HREF="tcpip-library-reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="getprotoent"
  26 HREF="net-common-tcpip-manpages-getprotoent.html"><LINK
  27 REL="NEXT"
  28 TITLE="getservent"
  29 HREF="net-common-tcpip-manpages-getservent.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="net-common-tcpip-manpages-getprotoent.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 38. TCP/IP Library Reference</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="net-common-tcpip-manpages-getservent.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="NET-COMMON-TCPIP-MANPAGES-GETRRSETBYNAME">getrrsetbyname</H1
  86 ><TABLE
  87 BORDER="5"
  88 BGCOLOR="#E0E0F0"
  89 WIDTH="70%"
  90 ><TR
  91 ><TD
  92 ><PRE
  93 CLASS="SCREEN"
  94 >GETRRSETBYNAME(3)       System Library Functions Manual      GETRRSETBYNAME(3)
  95
  96 NAME
  97      getrrsetbyname - retrieve DNS records
  98
  99 SYNOPSIS
 100      #include &lt;netdb.h&#62;
 101
 102      int
 103      getrrsetbyname(const char *hostname, unsigned int rdclass,
 104              unsigned int rdtype, unsigned int flags, struct rrsetinfo **res);
 105
 106      int
 107      freerrset(struct rrsetinfo **rrset);
 108
 109 DESCRIPTION
 110      getrrsetbyname() gets a set of resource records associated with a
 111      hostname, class and type.  hostname is a pointer a to null-terminated
 112      string.  The flags field is currently unused and must be zero.
 113
 114      After a successful call to getrrsetbyname(), *res is a pointer to an
 115      rrsetinfo structure, containing a list of one or more rdatainfo struc-
 116      tures containing resource records and potentially another list of
 117      rdatainfo structures containing SIG resource records associated with
 118      those records.  The members rri_rdclass and rri_rdtype are copied from
 119      the parameters.  rri_ttl and rri_name are properties of the obtained
 120      rrset.  The resource records contained in rri_rdatas and rri_sigs are in
 121      uncompressed DNS wire format.  Properties of the rdataset are represented
 122      in the rri_flags bitfield. If the RRSET_VALIDATED bit is set, the data
 123      has been DNSSEC validated and the signatures verified.
 124
 125      The following structures are used:
 126
 127      struct  rdatainfo {
 128              unsigned int            rdi_length;     /* length of data */
 129              unsigned char           *rdi_data;      /* record data */
 130      };
 131
 132      struct  rrsetinfo {
 133              unsigned int            rri_flags;      /* RRSET_VALIDATED ... */
 134              unsigned int            rri_rdclass;    /* class number */
 135              unsigned int            rri_rdtype;     /* RR type number */
 136              unsigned int            rri_ttl;        /* time to live */
 137              unsigned int            rri_nrdatas;    /* size of rdatas array */
 138              unsigned int            rri_nsigs;      /* size of sigs array */
 139              char                    *rri_name;      /* canonical name */
 140              struct rdatainfo        *rri_rdatas;    /* individual records */
 141              struct rdatainfo        *rri_sigs;      /* individual signatures */
 142      };
 143
 144      All of the information returned by getrrsetbyname() is dynamically allo-
 145      cated: the rrsetinfo and rdatainfo structures, and the canonical host
 146      name strings pointed to by the rrsetinfostructure. Memory allocated for
 147      the dynamically allocated structures created by a successful call to
 148      getrrsetbyname() is released by freerrset().  rrset is a pointer to a
 149      struct rrset created by a call to getrrsetbyname().
 150
 151      If the EDNS0 option is activated in resolv.conf(3), getrrsetbyname() will
 152      request DNSSEC authentication using the EDNS0 DNSSEC OK (DO) bit.
 153
 154 RETURN VALUES
 155      getrrsetbyname() returns zero on success, and one of the following error
 156      codes if an error occurred:
 157
 158      ERRSET_NONAME    the name does not exist
 159      ERRSET_NODATA    the name exists, but does not have data of the desired
 160                       type
 161      ERRSET_NOMEMORY  memory could not be allocated
 162      ERRSET_INVAL     a parameter is invalid
 163      ERRSET_FAIL      other failure
 164
 165 SEE ALSO
 166      resolver(3), resolv.conf(5), named(8)
 167
 168 AUTHORS
 169      Jakob Schlyter &lt;jakob@openbsd.org&#62;
 170
 171 HISTORY
 172      getrrsetbyname() first appeared in OpenBSD 3.0.  The API first appeared
 173      in ISC BIND version 9.
 174
 175 BUGS
 176      The data in *rdi_data should be returned in uncompressed wire format.
 177      Currently, the data is in compressed format and the caller can't uncom-
 178      press since it doesn't have the full message.
 179
 180 CAVEATS
 181      The RRSET_VALIDATED flag in rri_flags is set if the AD (autenticated
 182      data) bit in the DNS answer is set. This flag should not be trusted
 183      unless the transport between the nameserver and the resolver is secure
 184      (e.g. IPsec, trusted network, loopback communication).
 185
 186 BSD                              Oct 18, 2000                              BSD
 187     </PRE
 188 ></TD
 189 ></TR
 190 ></TABLE
 191 ></DIV
 192 ><DIV
 193 CLASS="NAVFOOTER"
 194 ><HR
 195 ALIGN="LEFT"
 196 WIDTH="100%"><TABLE
 197 SUMMARY="Footer navigation table"
 198 WIDTH="100%"
 199 BORDER="0"
 200 CELLPADDING="0"
 201 CELLSPACING="0"
 202 ><TR
 203 ><TD
 204 WIDTH="33%"
 205 ALIGN="left"
 206 VALIGN="top"
 207 ><A
 208 HREF="net-common-tcpip-manpages-getprotoent.html"
 209 ACCESSKEY="P"
 210 >Prev</A
 211 ></TD
 212 ><TD
 213 WIDTH="34%"
 214 ALIGN="center"
 215 VALIGN="top"
 216 ><A
 217 HREF="ecos-ref.html"
 218 ACCESSKEY="H"
 219 >Home</A
 220 ></TD
 221 ><TD
 222 WIDTH="33%"
 223 ALIGN="right"
 224 VALIGN="top"
 225 ><A
 226 HREF="net-common-tcpip-manpages-getservent.html"
 227 ACCESSKEY="N"
 228 >Next</A
 229 ></TD
 230 ></TR
 231 ><TR
 232 ><TD
 233 WIDTH="33%"
 234 ALIGN="left"
 235 VALIGN="top"
 236 >getprotoent</TD
 237 ><TD
 238 WIDTH="34%"
 239 ALIGN="center"
 240 VALIGN="top"
 241 ><A
 242 HREF="tcpip-library-reference.html"
 243 ACCESSKEY="U"
 244 >Up</A
 245 ></TD
 246 ><TD
 247 WIDTH="33%"
 248 ALIGN="right"
 249 VALIGN="top"
 250 >getservent</TD
 251 ></TR
 252 ></TABLE
 253 ></DIV
 254 ></BODY
 255 ></HTML
 256 >