lib/liblwres/man/lwres_getrrsetbyname.3

   1 .\"
   2 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
   9 .\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  10 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  11 .\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
  12 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  13 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  14 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  15 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .TH "LWRES_GETRRSETBYNAME" "3" "Oct 18, 2000" "BIND9" ""
  18 .SH NAME
  19 lwres_getrrsetbyname, lwres_freerrset \- retrieve DNS records
  20 .SH SYNOPSIS
  21 \fB#include <lwres/netdb.h>
  22 .sp
  23 .na
  24 int
  25 lwres_getrrsetbyname(const char *hostname, unsigned int rdclass, unsigned int rdtype, unsigned int flags, struct rrsetinfo **res);
  26 .ad
  27 .sp
  28 .na
  29 void
  30 lwres_freerrset(struct rrsetinfo *rrset);
  31 .ad
  32 \fR.PP
  33 The following structures are used:
  34 .sp
  35 .nf
  36 struct  rdatainfo {
  37         unsigned int            rdi_length;     /* length of data */
  38         unsigned char           *rdi_data;      /* record data */
  39 };
  40
  41 struct  rrsetinfo {
  42         unsigned int            rri_flags;      /* RRSET_VALIDATED... */
  43         unsigned int            rri_rdclass;    /* class number */
  44         unsigned int            rri_rdtype;     /* RR type number */
  45         unsigned int            rri_ttl;        /* time to live */
  46         unsigned int            rri_nrdatas;    /* size of rdatas array */
  47         unsigned int            rri_nsigs;      /* size of sigs array */
  48         char                    *rri_name;      /* canonical name */
  49         struct rdatainfo        *rri_rdatas;    /* individual records */
  50         struct rdatainfo        *rri_sigs;      /* individual signatures */
  51 };
  52 .sp
  53 .fi
  54 .SH "DESCRIPTION"
  55 .PP
  56 \fBlwres_getrrsetbyname()\fR
  57 gets a set of resource records associated with a
  58 \fIhostname\fR,
  59 \fIclass\fR,
  60 and
  61 \fItype\fR.
  62 \fIhostname\fR
  63 is
  64 a pointer a to null-terminated string. The
  65 \fIflags\fR
  66 field is currently unused and must be zero.
  67 .PP
  68 After a successful call to
  69 \fBlwres_getrrsetbyname()\fR,
  70 \fI*res\fR
  71 is a pointer to an
  72 \fBrrsetinfo\fR
  73 structure, containing a list of one or more
  74 \fBrdatainfo\fR
  75 structures containing resource records and potentially another list of
  76 \fBrdatainfo\fR
  77 structures containing SIG resource records
  78 associated with those records.
  79 The members
  80 rri_rdclass
  81 and
  82 rri_rdtype
  83 are copied from the parameters.
  84 rri_ttl
  85 and
  86 rri_name
  87 are properties of the obtained rrset.
  88 The resource records contained in
  89 rri_rdatas
  90 and
  91 rri_sigs
  92 are in uncompressed DNS wire format.
  93 Properties of the rdataset are represented in the
  94 rri_flags
  95 bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC
  96 validated and the signatures verified.
  97 .PP
  98 All of the information returned by
  99 \fBlwres_getrrsetbyname()\fR
 100 is dynamically allocated: the
 101 rrsetinfo
 102 and
 103 rdatainfo
 104 structures,
 105 and the canonical host name strings pointed to by the
 106 rrsetinfostructure.
 107 Memory allocated for the dynamically allocated structures created by
 108 a successful call to
 109 \fBlwres_getrrsetbyname()\fR
 110 is released by
 111 \fBlwres_freerrset()\fR.
 112 \fIrrset\fR
 113 is a pointer to a
 114 \fBstruct rrset\fR
 115 created by a call to
 116 \fBlwres_getrrsetbyname()\fR.
 117 .PP
 118 .SH "RETURN VALUES"
 119 .PP
 120 \fBlwres_getrrsetbyname()\fR
 121 returns zero on success, and one of the following error
 122 codes if an error occurred:
 123 .TP
 124 \fBERRSET_NONAME\fR
 125 the name does not exist
 126 .TP
 127 \fBERRSET_NODATA\fR
 128 the name exists, but does not have data of the desired type
 129 .TP
 130 \fBERRSET_NOMEMORY\fR
 131 memory could not be allocated
 132 .TP
 133 \fBERRSET_INVAL\fR
 134 a parameter is invalid
 135 .TP
 136 \fBERRSET_FAIL\fR
 137 other failure
 138 .TP
 139 \fB\fR
 140 .SH "SEE ALSO"
 141 .PP
 142 \fBlwres\fR(3).