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