summaryrefslogtreecommitdiff
path: root/src/lib/libc/net/getrrsetbyname.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/net/getrrsetbyname.3')
-rw-r--r--src/lib/libc/net/getrrsetbyname.3166
1 files changed, 166 insertions, 0 deletions
diff --git a/src/lib/libc/net/getrrsetbyname.3 b/src/lib/libc/net/getrrsetbyname.3
new file mode 100644
index 0000000000..121cb67fcc
--- /dev/null
+++ b/src/lib/libc/net/getrrsetbyname.3
@@ -0,0 +1,166 @@
1.\" $OpenBSD: getrrsetbyname.3,v 1.15 2007/05/31 19:19:30 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: May 31 2007 $
19.Dt GETRRSETBYNAME 3
20.Os
21.Sh NAME
22.Nm freerrset ,
23.Nm getrrsetbyname
24.Nd retrieve DNS records
25.Sh SYNOPSIS
26.Fd #include <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.Li rrsetinfo
50structure, containing a list of one or more
51.Li rdatainfo
52structures containing resource records and potentially another list of
53.Li 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.Li rrsetinfo
101and
102.Li rdatainfo
103structures,
104and the canonical host name strings pointed to by the
105.Li 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.Li struct rrsetinfo
115created by a call to
116.Fn getrrsetbyname .
117.Pp
118If the EDNS0 option is activated in
119.Xr resolv.conf 5 ,
120.Fn getrrsetbyname
121will 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.Pp
127.Bl -tag -width ERRSET_NOMEMORY
128.It Bq Er ERRSET_NONAME
129The name does not exist.
130.It Bq Er ERRSET_NODATA
131The name exists, but does not have data of the desired type.
132.It Bq Er ERRSET_NOMEMORY
133Memory could not be allocated.
134.It Bq Er ERRSET_INVAL
135A parameter is invalid.
136.It Bq Er ERRSET_FAIL
137Other failure.
138.El
139.Sh SEE ALSO
140.Xr resolver 3 ,
141.Xr resolv.conf 5 ,
142.Xr named 8
143.Sh HISTORY
144.Fn getrrsetbyname
145first appeared in
146.Ox 3.0 .
147The API first appeared in ISC BIND version 9.
148.Sh AUTHORS
149.An Jakob Schlyter Aq jakob@openbsd.org
150.Sh CAVEATS
151The
152.Dv RRSET_VALIDATED
153flag in
154.Li rri_flags
155is set if the AD (authenticated data) bit in the DNS answer is
156set.
157This flag
158.Em should not
159be trusted unless the transport between the nameserver and the resolver
160is secure (e.g. IPsec, trusted network, loopback communication).
161.Sh BUGS
162The data in
163.Li *rdi_data
164should be returned in uncompressed wire format.
165Currently, the data is in compressed format and the caller can't
166uncompress since it doesn't have the full message.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-03 22:14:56 +0000