packages/net/common/v2_0/doc/manpages/net/getrrsetbyname.3

   1 .\" $OpenBSD: getrrsetbyname.3,v 1.4 2001/08/08 16:28:43 jakob Exp $
   2 .\"
   3 .\" Copyright (C) 2000, 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 INTERNET SOFTWARE CONSORTIUM
  10 .\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  11 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  12 .\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
  13 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  14 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  15 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  16 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd Oct 18, 2000
  19 .Dt GETRRSETBYNAME 3
  20 .Os
  21 .Sh NAME
  22 .Nm getrrsetbyname
  23 .Nd retrieve DNS records
  24 .Sh SYNOPSIS
  25 .Fd #include <netdb.h>
  26 .Ft int
  27 .Fn getrrsetbyname "const char *hostname" "unsigned int rdclass" \
  28 "unsigned int rdtype" "unsigned int flags" "struct rrsetinfo **res"
  29 .Ft int
  30 .Fn freerrset "struct rrsetinfo **rrset"
  31 .Sh DESCRIPTION
  32 .Fn getrrsetbyname
  33 gets a set of resource records associated with a
  34 .Fa hostname ,
  35 .Fa class
  36 and
  37 .Fa type .
  38 .Fa hostname
  39 is a pointer a to null-terminated string.
  40 The
  41 .Fa flags
  42 field is currently unused and must be zero.
  43 .Pp
  44 After a successful call to
  45 .Fn getrrsetbyname ,
  46 .Fa *res
  47 is a pointer to an
  48 .Li rrsetinfo
  49 structure, containing a list of one or more
  50 .Li rdatainfo
  51 structures containing resource records and potentially another list of
  52 .Li rdatainfo
  53 structures containing SIG resource records associated with those records.
  54 The members
  55 .Li rri_rdclass
  56 and
  57 .Li rri_rdtype
  58 are copied from the parameters.
  59 .Li rri_ttl
  60 and
  61 .Li rri_name
  62 are properties of the obtained rrset.
  63 The resource records contained in
  64 .Li rri_rdatas
  65 and
  66 .Li rri_sigs
  67 are in uncompressed DNS wire format.
  68 Properties of the rdataset are represented in the
  69 .Li rri_flags
  70 bitfield. If the
  71 .Dv RRSET_VALIDATED
  72 bit is set, the data has been DNSSEC
  73 validated and the signatures verified.
  74 .Pp
  75 The following structures are used:
  76 .Bd -literal -offset
  77 struct  rdatainfo {
  78         unsigned int            rdi_length;     /* length of data */
  79         unsigned char           *rdi_data;      /* record data */
  80 };
  81
  82 struct  rrsetinfo {
  83         unsigned int            rri_flags;      /* RRSET_VALIDATED ... */
  84         unsigned int            rri_rdclass;    /* class number */
  85         unsigned int            rri_rdtype;     /* RR type number */
  86         unsigned int            rri_ttl;        /* time to live */
  87         unsigned int            rri_nrdatas;    /* size of rdatas array */
  88         unsigned int            rri_nsigs;      /* size of sigs array */
  89         char                    *rri_name;      /* canonical name */
  90         struct rdatainfo        *rri_rdatas;    /* individual records */
  91         struct rdatainfo        *rri_sigs;      /* individual signatures */
  92 };
  93 .Ed
  94 .Pp
  95 All of the information returned by
  96 .Fn getrrsetbyname
  97 is dynamically allocated: the
  98 .Li rrsetinfo
  99 and
 100 .Li rdatainfo
 101 structures,
 102 and the canonical host name strings pointed to by the
 103 .Li rrsetinfostructure.
 104 Memory allocated for the dynamically allocated structures created by
 105 a successful call to
 106 .Fn getrrsetbyname
 107 is released by
 108 .Fn freerrset .
 109 .Li rrset
 110 is a pointer to a
 111 .Li struct rrset
 112 created by a call to
 113 .Fn getrrsetbyname .
 114 .Pp
 115 If the EDNS0 option is activated in
 116 .Xr resolv.conf 3 ,
 117 .Fn getrrsetbyname
 118 will request DNSSEC authentication using the EDNS0 DNSSEC OK (DO) bit.
 119 .Sh "RETURN VALUES"
 120 .Fn getrrsetbyname
 121 returns zero on success, and one of the following error
 122 codes if an error occurred:
 123 .Pp
 124 .Bl -tag -width ERRSET_NOMEMORY -compact
 125 .It Dv ERRSET_NONAME
 126 the name does not exist
 127 .It Dv ERRSET_NODATA
 128 the name exists, but does not have data of the desired type
 129 .It Dv ERRSET_NOMEMORY
 130 memory could not be allocated
 131 .It Dv ERRSET_INVAL
 132 a parameter is invalid
 133 .It Dv ERRSET_FAIL
 134 other failure
 135 .El
 136 .Sh SEE ALSO
 137 .Xr resolver 3 ,
 138 .Xr resolv.conf 5 ,
 139 .Xr named 8
 140 .Sh AUTHORS
 141 Jakob Schlyter
 142 .Aq jakob@openbsd.org
 143 .Sh HISTORY
 144 .Fn getrrsetbyname
 145 first appeared in
 146 .Ox 3.0 .
 147 The API first appeared in ISC BIND version 9.
 148 .Sh BUGS
 149 The data in
 150 .Li *rdi_data
 151 should be returned in uncompressed wire format.
 152 Currently, the data is in compressed format and the caller can't
 153 uncompress since it doesn't have the full message.
 154 .Sh CAVEATS
 155 The
 156 .Dv RRSET_VALIDATED
 157 flag in
 158 .Li rri_flags
 159 is set if the AD (autenticated data) bit in the DNS answer is
 160 set. This flag
 161 .Em should not
 162 be trusted unless the transport between the nameserver and the resolver
 163 is secure (e.g. IPsec, trusted network, loopback communication).