ares_dns_mapping.3 (10832B)
1 .\" Copyright (C) 2023 The c-ares project and its contributors. 2 .\" SPDX-License-Identifier: MIT 3 .\" 4 .TH ARES_DNS_MAPPINGS 3 "12 November 2023" 5 .SH NAME 6 ares_dns_class_fromstr, ares_dns_class_tostr, ares_dns_datatype_t, ares_dns_opcode_tostr, 7 ares_dns_opt_datatype_t, ares_dns_opt_get_datatype, ares_dns_opt_get_name, 8 ares_dns_rcode_tostr, ares_dns_rec_type_fromstr, ares_dns_rr_get_keys, 9 ares_dns_rr_key_datatype, ares_dns_rr_key_to_rec_type, ares_dns_rr_key_tostr, 10 ares_dns_section_tostr, ares_opt_param_t, ares_svcb_param_t \- 11 Helper functions for converting dns record identifiers to and from their 12 respective types, as well identifying datatypes for various records. 13 .SH SYNOPSIS 14 .nf 15 #include <ares.h> 16 17 const char *ares_dns_rec_type_tostr(ares_dns_rec_type_t type); 18 19 const char *ares_dns_class_tostr(ares_dns_class_t qclass); 20 21 const char *ares_dns_opcode_tostr(ares_dns_opcode_t opcode); 22 23 const char *ares_dns_rr_key_tostr(ares_dns_rr_key_t key); 24 25 const char *ares_dns_section_tostr(ares_dns_section_t section); 26 27 const char *ares_dns_rcode_tostr(ares_dns_rcode_t rcode); 28 29 ares_bool_t ares_dns_class_fromstr(ares_dns_class_t *qclass, const char *str); 30 31 ares_bool_t ares_dns_rec_type_fromstr(ares_dns_rec_type_t *qtype, 32 const char *str); 33 34 const ares_dns_rr_key_t *ares_dns_rr_get_keys(ares_dns_rec_type_t type, 35 size_t *cnt); 36 37 ares_dns_datatype_t ares_dns_rr_key_datatype(ares_dns_rr_key_t key); 38 39 ares_dns_rec_type_t ares_dns_rr_key_to_rec_type(ares_dns_rr_key_t key); 40 41 ares_dns_opt_datatype_t ares_dns_opt_get_datatype(ares_dns_rr_key_t key, 42 unsigned short opt); 43 44 const char *ares_dns_opt_get_name(ares_dns_rr_key_t key, unsigned short opt); 45 46 .fi 47 .SH ENUMERATIONS 48 .B ares_dns_datatype_t - 49 Data types associated with \fIares_dns_rr_key_t\fP: 50 .RS 4 51 .B ARES_DATATYPE_INADDR 52 - IPv4 address as \fIstruct in_addr *\fP. Use \fIares_dns_rr_set_addr(3)\fP to 53 set and \fIares_dns_rr_get_addr(3)\fP to get. 54 .br 55 .B ARES_DATATYPE_INADDR6 56 - IPv6 address as \fIstruct ares_in6_addr *\fP. Use \fIares_dns_rr_set_addr6(3)\fP to 57 set and \fIares_dns_rr_get_addr6(3)\fP to get. 58 .br 59 .B ARES_DATATYPE_U8 60 - 8bit unsigned integer. Use \fIares_dns_rr_set_u8(3)\fP to 61 set and \fIares_dns_rr_get_u8(3)\fP to get. 62 .br 63 .B ARES_DATATYPE_U16 64 - 16bit unsigned integer. Use \fIares_dns_rr_set_u16(3)\fP to 65 set and \fIares_dns_rr_get_u16(3)\fP to get. 66 .br 67 .B ARES_DATATYPE_U32 68 - 32bit unsigned integer. Use \fIares_dns_rr_set_u32(3)\fP to 69 set and \fIares_dns_rr_get_u32(3)\fP to get. 70 .br 71 .B ARES_DATATYPE_NAME 72 - Null-terminated string of a domain name (series of labels). Use \fIares_dns_rr_set_str(3)\fP to 73 set and \fIares_dns_rr_get_str(3)\fP to get. 74 .br 75 .B ARES_DATATYPE_STR 76 - Null-terminated string. Use \fIares_dns_rr_set_str(3)\fP to 77 set and \fIares_dns_rr_get_str(3)\fP to get. 78 .br 79 .B ARES_DATATYPE_BIN 80 - Binary Data. Use \fIares_dns_rr_set_bin(3)\fP to 81 set and \fIares_dns_rr_get_bin(3)\fP to get. 82 .br 83 .B ARES_DATATYPE_BINP 84 - Officially defined as binary data, but likely printable. Guaranteed to have 85 a NULL terminator for convenience (not included in length). Use \fIares_dns_rr_set_bin(3)\fP to 86 set and \fIares_dns_rr_get_bin(3)\fP to get. 87 .br 88 .B ARES_DATATYPE_OPT 89 - Array of options. 16bit identifier, Binary data. Use \fIares_dns_rr_set_opt(3)\fP to 90 set and \fIares_dns_rr_get_opt(3)\fP to get. 91 .br 92 .B ARES_DATATYPE_ABINP 93 - Array of binary data, but likely printable. Guaranteed to have a NULL terminator 94 for convenience (not included in length). Use \fIares_dns_rr_add_abin(3)\fP to 95 set and \fIares_dns_rr_get_abin(3)\fP to get. Can also use 96 \fIares_dns_rr_set_bin(3)\fP and \fIares_dns_rr_get_bin(3)\fP if only concatenated 97 strings are desired. 98 .br 99 .RE 100 101 .B ares_dns_opt_datatype_t - 102 Data types associated with \fIARES_DATATYPE_OPT\fP parameters if known as returned 103 by \fIares_dns_opt_get_datatype(3)\fP: 104 .RS 4 105 .B ARES_OPT_DATATYPE_NONE 106 - No value allowed for this parameter 107 .br 108 .B ARES_OPT_DATATYPE_STR_LIST 109 - List of strings, each prefixed with a single octet representing the length as 110 defined by RFC 1035. Can use \fIares_expand_string(3)\fP until buffer is consumed. 111 .br 112 .B ARES_OPT_DATATYPE_U8_LIST 113 - List of 8bit unsigned integers, concatenated 114 .br 115 .B ARES_OPT_DATATYPE_U16 116 - 16bit unsigned integer in network byte order 117 .br 118 .B ARES_OPT_DATATYPE_U16_LIST 119 - list of 16bit unsigned integers in network byte order, concatenated. 120 .br 121 .B ARES_OPT_DATATYPE_U32 122 - 32bit unsigned integer in network byte order 123 .br 124 .B ARES_OPT_DATATYPE_U32_LIST 125 - list of 16bit unsigned integers in network byte order, concatenated. 126 .br 127 .B ARES_OPT_DATATYPE_INADDR4_LIST 128 - List of ipv4 addresses in network byte order, concatenated 129 .br 130 .B ARES_OPT_DATATYPE_INADDR6_LIST 131 - List of ipv6 addresses in network byte order, concatenated 132 .br 133 .B ARES_OPT_DATATYPE_BIN 134 - Binary Data 135 .br 136 .B ARES_OPT_DATATYPE_NAME 137 - DNS Domain Name binary format as defined in RFC1035, can use \fIares_expand_name(3)\fP 138 .br 139 .RE 140 141 .B ares_svcb_param_t - 142 SVCB (and HTTPS) RR known parameters as returned by \fIares_dns_opt_get_datatype(3)\fP 143 with \fIARES_RR_SVCB_PARAMS\fP or \fIARES_RR_HTTPS_PARAMS\fP: 144 .RS 4 145 .B ARES_SVCB_PARAM_MANDATORY 146 - Mandatory keys in this RR (RFC 9460 Section 8). Datatype: \fIARES_OPT_DATATYPE_U16_LIST\fP 147 .br 148 .B ARES_SVCB_PARAM_ALPN 149 - Additional supported protocols (RFC 9460 Section 7.1). Datatype: \fIARES_OPT_DATATYPE_STR_LIST\fP 150 .br 151 .B ARES_SVCB_PARAM_NO_DEFAULT_ALPN 152 - No support for default protocol (RFC 9460 Section 7.1). Datatype: \fIARES_OPT_DATATYPE_NONE\fP 153 .br 154 .B ARES_SVCB_PARAM_PORT 155 - Port for alternative endpoint (RFC 9460 Section 7.2). Datatype: \fIARES_OPT_DATATYPE_U16\fP 156 .br 157 .B ARES_SVCB_PARAM_IPV4HINT 158 - IPv4 address hints (RFC 9460 Section 7.3). Datatype: \fIARES_OPT_DATATYPE_INADDR4_LIST\fP 159 .br 160 .B ARES_SVCB_PARAM_ECH 161 - RESERVED (held for Encrypted ClientHello) 162 .br 163 .B ARES_SVCB_PARAM_IPV6HINT 164 - IPv6 address hints (RFC 9460 Section 7.3). Datatype: \fIARES_OPT_DATATYPE_INADDR6_LIST\fP 165 .br 166 167 .RE 168 169 .B ares_opt_param_t - 170 OPT RR known parameters as returned by \fIares_dns_opt_get_datatype(3)\fP 171 with \fIARES_RR_OPT_OPTIONS\fB: 172 .RS 4 173 .B ARES_OPT_PARAM_LLQ 174 - RFC 8764. Apple's DNS Long-Lived Queries Protocol. Datatype: \fIARES_OPT_DATATYPE_BIN\fP 175 .br 176 .B ARES_OPT_PARAM_UL 177 - http://files.dns-sd.org/draft-sekar-dns-ul.txt: Update Lease. Datatype: \fIARES_OPT_DATATYPE_U32\fP 178 .br 179 .B ARES_OPT_PARAM_NSID 180 - RFC 5001. Name Server Identification. Datatype: \fIARES_OPT_DATATYPE_BIN\fP 181 .br 182 .B ARES_OPT_PARAM_DAU 183 - RFC 6975. DNSSEC Algorithm Understood. Datatype: \fIARES_OPT_DATATYPE_U8_LIST\fP 184 .br 185 .B ARES_OPT_PARAM_DHU 186 - RFC 6975. DS Hash Understood. Datatype: \fIARES_OPT_DATATYPE_U8_LIST\fP 187 .br 188 .B ARES_OPT_PARAM_N3U 189 - RFC 6975. NSEC3 Hash Understood. Datatype: \fIARES_OPT_DATATYPE_U8_LIST\fP 190 .br 191 .B ARES_OPT_PARAM_EDNS_CLIENT_SUBNET 192 - RFC 7871. Client Subnet. Datatype: \fIARES_OPT_DATATYPE_BIN\fP 193 .br 194 .B ARES_OPT_PARAM_EDNS_EXPIRE 195 - RFC 7314. Expire Timer. Datatype: \fIARES_OPT_DATATYPE_U32\fP 196 .br 197 .B ARES_OPT_PARAM_COOKIE 198 - RFC 7873. Client and Server Cookies. Datatype: \fIARES_OPT_DATATYPE_BIN\fP 199 .br 200 .B ARES_OPT_PARAM_EDNS_TCP_KEEPALIVE 201 - RFC 7828. TCP Keepalive timeout. Datatype: \fIARES_OPT_DATATYPE_U16\fP 202 .br 203 .B ARES_OPT_PARAM_PADDING 204 - RFC 7830. Padding. Datatype: \fIARES_OPT_DATATYPE_BIN\fP 205 .br 206 .B ARES_OPT_PARAM_CHAIN 207 - RFC 7901. Chain query requests. Datatype: \fIARES_OPT_DATATYPE_NAME\fP 208 .br 209 .B ARES_OPT_PARAM_EDNS_KEY_TAG 210 - RFC 8145. Signaling Trust Anchor Knowledge in DNSSEC. Datatype: \fIARES_OPT_DATATYPE_U16_LIST\fP 211 .br 212 .B ARES_OPT_PARAM_EXTENDED_DNS_ERROR 213 - RFC 8914. Extended ERROR code and message. Datatype: \fIARES_OPT_DATATYPE_BIN\fP 214 .br 215 .RE 216 217 .SH DESCRIPTION 218 The \fIares_dns_rec_type_tostr(3)\fP function outputs a human readable DNS record 219 type from its numeric form passed in 220 .IR type . 221 222 The \fIares_dns_class_tostr(3)\fP function outputs a human readable DNS class 223 from its numeric form passed in 224 .IR qclass . 225 226 The \fIares_dns_opcode_tostr(3)\fP function outputs a human readable DNS opcode 227 from its numeric form in 228 .IR opcode . 229 230 The \fIares_dns_rr_key_tostr(3)\fP function outputs a human readable DNS Resource 231 Record parameter name from its numeric form in 232 .IR key . 233 234 The \fIares_dns_section_tostr(3)\fP function outputs a human readable DNS 235 message section from its numeric form in 236 .IR section . 237 238 The \fIares_dns_rcode_tostr(3)\fP function outputs a human readable DNS 239 response code from its numeric form in 240 .IR rcode . 241 242 The \fIares_dns_class_fromstr(3)\fP function outputs the DNS class in numeric 243 from from its string representation in 244 .IR str . 245 The result is stored into the variable pointed to by 246 .IR qclass . 247 248 The \fIares_dns_rec_type_fromstr(3)\fP function outputs the DNS record type in 249 numeric from from its string representation in 250 .IR str . 251 The result is stored into the variable pointed to by 252 .IR qtype . 253 254 The \fIares_dns_rr_get_keys(3)\fP function retrieves a list of parameters that 255 may be set or retrieved for the provided 256 .IR type . 257 The count of returned keys is stored into the variable pointed to by 258 .IR cnt . 259 260 The \fIares_dns_rr_key_datatype(3)\fP function retrieves the associated datatype 261 for an RR parameter specified by 262 .IR key . 263 264 The \fIares_dns_rr_key_to_rec_type(3)\fP function dereferences the provided RR 265 parameter specified by 266 .IR key 267 to the DNS Record Type it belongs. 268 269 The \fIares_dns_opt_get_datatype(3)\fP function is used in association with 270 \fIares_dns_rr_set_opt(3)\fP and \fIares_dns_rr_get_opt(3)\fP to retrieve the 271 datatype of an option record contained within an RR as specified in 272 .IR key 273 if it is known. The raw option record identifier is provided by 274 .IR opt . 275 276 The \fIares_dns_opt_get_name(3)\fP function is used in association with 277 \fIares_dns_rr_set_opt(3)\fP and \fIares_dns_rr_get_opt(3)\fP to retrieve human 278 readable parameter name of an option record contained within an RR as specified 279 in 280 .IR key 281 if it is known. The raw option record identifier is provided by 282 .IR opt . 283 284 .SH RETURN VALUES 285 \fIares_dns_rec_type_tostr(3)\fP, \fIares_dns_class_tostr(3)\fP, 286 \fIares_dns_opcode_tostr(3)\fP, \fIares_dns_rr_key_tostr(3)\fP, 287 \fIares_dns_section_tostr(3)\fP, \fIares_dns_rcode_tostr(3)\fP, and 288 \fIares_dns_opt_get_name(3)\fP all return a human printable ASCII string, or 289 NULL on error. 290 291 \fIares_dns_class_fromstr(3)\fP and \fIares_dns_rec_type_fromstr(3)\fP return 292 .B ARES_TRUE 293 on successful conversion, otherwise 294 .B ARES_FALSE. 295 296 \fIares_dns_rr_get_keys(3)\fP returns an array of keys or NULL on failure. 297 298 \fIares_dns_rr_key_datatype(3)\fP, \fIares_dns_rr_key_to_rec_type(3)\fP, and 299 \fIares_dns_opt_get_datatype(3)\fP return their respective integer values, or 300 0 on failure. 301 302 .SH AVAILABILITY 303 These functions were first introduced in c-ares version 1.22.0. 304 .SH SEE ALSO 305 .BR ares_dns_record (3), 306 .BR ares_dns_rr (3), 307 .BR ares_init (3)