diff options
Diffstat (limited to 'src/lib/libc/net/getrrsetbyname.3')
-rw-r--r-- | src/lib/libc/net/getrrsetbyname.3 | 164 |
1 files changed, 0 insertions, 164 deletions
diff --git a/src/lib/libc/net/getrrsetbyname.3 b/src/lib/libc/net/getrrsetbyname.3 deleted file mode 100644 index 314f31665c..0000000000 --- a/src/lib/libc/net/getrrsetbyname.3 +++ /dev/null | |||
@@ -1,164 +0,0 @@ | |||
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 | ||
34 | gets a set of resource records associated with a | ||
35 | .Fa hostname , | ||
36 | .Fa rdclass , | ||
37 | and | ||
38 | .Fa rdtype . | ||
39 | .Fa hostname | ||
40 | is a pointer to a NUL-terminated string. | ||
41 | The | ||
42 | .Fa flags | ||
43 | field is currently unused and must be zero. | ||
44 | .Pp | ||
45 | After a successful call to | ||
46 | .Fn getrrsetbyname , | ||
47 | .Fa *res | ||
48 | is a pointer to an | ||
49 | .Vt rrsetinfo | ||
50 | structure, containing a list of one or more | ||
51 | .Vt rdatainfo | ||
52 | structures containing resource records and potentially another list of | ||
53 | .Vt rdatainfo | ||
54 | structures containing SIG resource records associated with those records. | ||
55 | The members | ||
56 | .Li rri_rdclass | ||
57 | and | ||
58 | .Li rri_rdtype | ||
59 | are copied from the parameters. | ||
60 | .Li rri_ttl | ||
61 | and | ||
62 | .Li rri_name | ||
63 | are properties of the obtained rrset. | ||
64 | The resource records contained in | ||
65 | .Li rri_rdatas | ||
66 | and | ||
67 | .Li rri_sigs | ||
68 | are in uncompressed DNS wire format. | ||
69 | Properties of the rdataset are represented in the | ||
70 | .Li rri_flags | ||
71 | bitfield. | ||
72 | If the | ||
73 | .Dv RRSET_VALIDATED | ||
74 | bit is set, the data has been DNSSEC | ||
75 | validated and the signatures verified. | ||
76 | .Pp | ||
77 | The following structures are used: | ||
78 | .Bd -literal -offset indent | ||
79 | struct rdatainfo { | ||
80 | unsigned int rdi_length; /* length of data */ | ||
81 | unsigned char *rdi_data; /* record data */ | ||
82 | }; | ||
83 | |||
84 | struct 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 | ||
97 | All of the information returned by | ||
98 | .Fn getrrsetbyname | ||
99 | is dynamically allocated: the | ||
100 | .Vt rrsetinfo | ||
101 | and | ||
102 | .Vt rdatainfo | ||
103 | structures, | ||
104 | and the canonical host name strings pointed to by the | ||
105 | .Vt rrsetinfo | ||
106 | structure. | ||
107 | Memory allocated for the dynamically allocated structures created by | ||
108 | a successful call to | ||
109 | .Fn getrrsetbyname | ||
110 | is released by | ||
111 | .Fn freerrset . | ||
112 | .Li rrset | ||
113 | is a pointer to a | ||
114 | .Vt struct rrsetinfo | ||
115 | created 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 | ||
124 | returns zero on success, and one of the following error | ||
125 | codes if an error occurred: | ||
126 | .Bl -tag -width ERRSET_NOMEMORY | ||
127 | .It Bq Er ERRSET_NONAME | ||
128 | The name does not exist. | ||
129 | .It Bq Er ERRSET_NODATA | ||
130 | The name exists, but does not have data of the desired type. | ||
131 | .It Bq Er ERRSET_NOMEMORY | ||
132 | Memory could not be allocated. | ||
133 | .It Bq Er ERRSET_INVAL | ||
134 | A parameter is invalid. | ||
135 | .It Bq Er ERRSET_FAIL | ||
136 | Other failure. | ||
137 | .El | ||
138 | .Sh SEE ALSO | ||
139 | .Xr res_init 3 , | ||
140 | .Xr resolv.conf 5 | ||
141 | .Sh HISTORY | ||
142 | .Fn getrrsetbyname | ||
143 | first appeared in | ||
144 | .Ox 3.0 . | ||
145 | The API first appeared in ISC BIND version 9. | ||
146 | .Sh AUTHORS | ||
147 | .An Jakob Schlyter Aq Mt jakob@openbsd.org | ||
148 | .Sh CAVEATS | ||
149 | The | ||
150 | .Dv RRSET_VALIDATED | ||
151 | flag in | ||
152 | .Li rri_flags | ||
153 | is set if the AD (authenticated data) bit in the DNS answer is | ||
154 | set. | ||
155 | This flag | ||
156 | .Em should not | ||
157 | be trusted unless the transport between the nameserver and the resolver | ||
158 | is secure (e.g. IPsec, trusted network, loopback communication). | ||
159 | .Sh BUGS | ||
160 | The data in | ||
161 | .Li *rdi_data | ||
162 | should be returned in uncompressed wire format. | ||
163 | Currently, the data is in compressed format and the caller can't | ||
164 | uncompress since it doesn't have the full message. | ||