ares_dns_record.3 (13958B)
1 .\" Copyright (C) 2023 The c-ares project and its contributors. 2 .\" SPDX-License-Identifier: MIT 3 .\" 4 .TH ARES_DNS_RECORD 3 "12 November 2023" 5 .SH NAME 6 ares_dns_class_t, ares_dns_flags_t, ares_dns_opcode_t, ares_dns_parse, 7 ares_dns_rcode_t, ares_dns_record_create, ares_dns_record_destroy, 8 ares_dns_record_get_flags, ares_dns_record_get_id, ares_dns_record_get_opcode, 9 ares_dns_record_get_rcode, ares_dns_record_query_add, ares_dns_record_query_cnt, 10 ares_dns_record_query_get, ares_dns_rec_type_t, ares_dns_write \- 11 DNS Record parsing, writing, creating and destroying functions. 12 .SH SYNOPSIS 13 .nf 14 #include <ares.h> 15 16 void ares_dns_record_destroy(ares_dns_record_t *dnsrec); 17 18 ares_status_t ares_dns_parse(const unsigned char *buf, 19 size_t buf_len, unsigned int flags, 20 ares_dns_record_t **dnsrec); 21 22 ares_status_t ares_dns_write(const ares_dns_record_t *dnsrec, 23 unsigned char **buf, size_t *buf_len); 24 25 ares_status_t ares_dns_record_create(ares_dns_record_t **dnsrec, 26 unsigned short id, 27 unsigned short flags, 28 ares_dns_opcode_t opcode, 29 ares_dns_rcode_t rcode); 30 31 ares_dns_record_t *ares_dns_record_duplicate(const ares_dns_record_t *dnsrec); 32 33 unsigned short ares_dns_record_get_id(const ares_dns_record_t *dnsrec); 34 35 ares_bool_t ares_dns_record_set_id(ares_dns_record_t *dnsrec, 36 unsigned short id); 37 38 unsigned short ares_dns_record_get_flags(const ares_dns_record_t *dnsrec); 39 40 ares_dns_opcode_t ares_dns_record_get_opcode(const ares_dns_record_t *dnsrec); 41 42 ares_dns_rcode_t ares_dns_record_get_rcode(const ares_dns_record_t *dnsrec); 43 44 ares_status_t ares_dns_record_query_add(ares_dns_record_t *dnsrec, 45 const char *name, 46 ares_dns_rec_type_t qtype, 47 ares_dns_class_t qclass); 48 49 ares_status_t ares_dns_record_query_set_name(ares_dns_record_t *dnsrec, 50 size_t idx, 51 const char *name); 52 53 ares_status_t ares_dns_record_query_set_type(ares_dns_record_t *dnsrec, 54 size_t idx, 55 ares_dns_rec_type_t qtype); 56 57 size_t ares_dns_record_query_cnt(const ares_dns_record_t *dnsrec); 58 59 ares_status_t ares_dns_record_query_get(const ares_dns_record_t *dnsrec, 60 size_t idx, const char **name, 61 ares_dns_rec_type_t *qtype, 62 ares_dns_class_t *qclass); 63 64 .fi 65 .SH ENUMERATIONS 66 67 .B ares_dns_rec_type_t - 68 DNS Record types handled by c-ares. Some record types may only be valid 69 on requests, and some may only be valid on responses: 70 .RS 4 71 .B ARES_REC_TYPE_A 72 - Host address 73 .br 74 .B ARES_REC_TYPE_NS 75 - Authoritative server 76 .br 77 .B ARES_REC_TYPE_CNAME 78 - Canonical name 79 .br 80 .B ARES_REC_TYPE_SOA 81 - Start of authority zone 82 .br 83 .B ARES_REC_TYPE_PTR 84 - Domain name pointer 85 .br 86 .B ARES_REC_TYPE_HINFO 87 - Host information 88 .br 89 .B ARES_REC_TYPE_MX 90 - Mail routing information 91 .br 92 .B ARES_REC_TYPE_TXT 93 - Text strings 94 .br 95 .B ARES_REC_TYPE_SIG 96 - RFC 2535. RFC 2931. SIG Record 97 .br 98 .B ARES_REC_TYPE_AAAA 99 - RFC 3596. Ip6 Address 100 .br 101 .B ARES_REC_TYPE_SRV 102 - RFC 2782. Server Selection 103 .br 104 .B ARES_REC_TYPE_NAPTR 105 - RFC 3403. Naming Authority Pointer 106 .br 107 .B ARES_REC_TYPE_OPT 108 - RFC 6891. EDNS0 option (meta-RR). Pseudo Record. 109 .br 110 .B ARES_REC_TYPE_TLSA 111 - RFC 6698. DNS-Based Authentication of Named Entities (DANE) Transport Layer Security (TLS) Protocol: TLSA 112 .br 113 .B ARES_REC_TYPE_SVCB 114 - RFC 9460. General Purpose Service Binding 115 .br 116 .B ARES_REC_TYPE_HTTPS - 117 - RFC 9460. Service Binding type for use with HTTPS 118 .br 119 .B ARES_REC_TYPE_ANY 120 - Wildcard match. Not response RR 121 .br 122 .B ARES_REC_TYPE_URI 123 - RFC 7553. Uniform Resource Identifier 124 .br 125 .B ARES_REC_TYPE_CAA 126 - RFC 6844. Certification Authority Authorization 127 .br 128 .B ARES_REC_TYPE_RAW_RR 129 - Used as an indicator that the RR record is not parsed, but provided in wire 130 format 131 .br 132 .RE 133 134 .B ares_dns_class_t - 135 DNS Classes for requests and responses: 136 .RS 4 137 .B ARES_CLASS_IN 138 - Internet 139 .br 140 .B ARES_CLASS_CHAOS 141 - CHAOS 142 .br 143 .B ARES_CLASS_HESOID 144 - Hesoid [Dyer 87] 145 .br 146 .B ARES_CLASS_NONE 147 - RFC 2136 148 .br 149 .B ARES_CLASS_ANY 150 - Any class (requests only) 151 .br 152 .RE 153 154 .B ares_dns_opcode_t - 155 DNS Header Opcodes: 156 .RS 4 157 .B ARES_OPCODE_QUERY 158 - Standard query 159 .br 160 .B ARES_OPCODE_IQUERY 161 - Inverse query. Obsolete 162 .br 163 .B ARES_OPCODE_STATUS 164 - Name server status query 165 .br 166 .B ARES_OPCODE_NOTIFY 167 - Zone change notification (RFC 1996) 168 .br 169 .B ARES_OPCODE_UPDATE 170 - Zone update message (RFC 2136) 171 .br 172 .RE 173 174 .B ares_dns_flags_t - 175 DNS Header Flags: 176 .RS 4 177 .B ARES_FLAG_QR 178 - QR. If set, is a response 179 .br 180 .B ARES_FLAG_AA 181 - Authoritative Answer. If set, is authoritative 182 .br 183 .B ARES_FLAG_TC 184 - Truncation. If set, is truncated response 185 .br 186 .B ARES_FLAG_RD 187 - Recursion Desired. If set, recursion is desired 188 .br 189 .B ARES_FLAG_RA 190 - Recursion Available. If set, server supports recursion 191 .br 192 .B ARES_FLAG_AD 193 - RFC 2065. Authentic Data bit indicates in a response that the data included 194 has been verified by the server providing it 195 .br 196 .B ARES_FLAG_CD 197 - RFC 2065. Checking Disabled bit indicates in a query that non-verified data 198 is acceptable to the resolver sending the query 199 .br 200 .RE 201 202 .B ares_dns_rcode_t - 203 DNS Response codes from server: 204 .RS 4 205 .B ARES_RCODE_NOERROR 206 - Success 207 .br 208 .B ARES_RCODE_FORMERR 209 - Format error. The name server was unable to interpret the query 210 .br 211 .B ARES_RCODE_SERVFAIL 212 - Server Failure. The name server was unable to process this query due to a 213 problem with the nameserver 214 .br 215 .B ARES_RCODE_NXDOMAIN 216 - Name Error. Meaningful only for responses from an authoritative name server, 217 this code signifies that the domain name referenced in the query does not exist. 218 .br 219 .B ARES_RCODE_NOTIMP 220 - Not implemented. The name server does not support the requested kind of query 221 .br 222 .B ARES_RCODE_REFUSED 223 - Refused. The name server refuses to perform the specified operation for policy 224 reasons. 225 .br 226 .B ARES_RCODE_YXDOMAIN 227 - RFC 2136. Some name that ought not to exist, does exist 228 .br 229 .B ARES_RCODE_YXRRSET 230 - RFC 2136. Some RRset that ought to not exist, does exist 231 .br 232 .B ARES_RCODE_NXRRSET 233 - RFC 2136. Some RRset that ought to exist, does not exist 234 .br 235 .B ARES_RCODE_NOTAUTH 236 - RFC 2136. The server is not authoritative for the zone named in the Zone section. 237 .br 238 .B ARES_RCODE_NOTZONE 239 - RFC 2136. A name used in the Prerequisite or Update Section is not within the 240 zone denoted by the Zone Section. 241 .br 242 .B ARES_RCODE_DSOTYPEI 243 - RFC 8409. DSO-TYPE Not implemented 244 .br 245 .B ARES_RCODE_BADSIG 246 - RFC 8945. TSIG Signature Failure 247 .br 248 .B ARES_RCODE_BADKEY 249 - RFC 8945. Key not recognized 250 .br 251 .B ARES_RCODE_BADTIME 252 - RFC 8945. Signature out of time window 253 .br 254 .B ARES_RCODE_BADMODE 255 - RFC 2930. Bad TKEY Mode 256 .br 257 .B ARES_RCODE_BADNAME 258 - RFC 2930. Duplicate Key Name 259 .br 260 .B ARES_RCODE_BADALG 261 - RFC 2930. Algorithm not supported 262 .br 263 .B ARES_RCODE_BADTRUNC 264 - RFC 8945. Bad Truncation 265 .br 266 .B ARES_RCODE_BADCOOKIE 267 - RFC 7973. Bad/missing Server Cookie 268 .br 269 .RE 270 271 .B ares_dns_parse_flags_t - 272 Flags for altering \fIares_dns_parse(3)\fP behaviour: 273 .RS 4 274 .B ARES_DNS_PARSE_AN_BASE_RAW 275 - Parse Answer Section from RFC 1035 that allow name compression as RAW RR type 276 .br 277 .B ARES_DNS_PARSE_NS_BASE_RAW 278 - Parse Authority Section from RFC 1035 that allow name compression as RAW RR type 279 .br 280 .B ARES_DNS_PARSE_AR_BASE_RAW 281 - Parse Additional Section from RFC 1035 that allow name compression as RAW RR type 282 .br 283 .B ARES_DNS_PARSE_AN_EXT_RAW 284 - Parse Answer Section from later RFCs (no name compression) as RAW RR type 285 .br 286 .B ARES_DNS_PARSE_NS_EXT_RAW 287 - Parse Authority Section from later RFCs (no name compression) as RAW RR type 288 .br 289 .B ARES_DNS_PARSE_AR_EXT_RAW 290 - Parse Additional Section from later RFCs (no name compression) as RAW RR type 291 .br 292 .RE 293 294 .SH DESCRIPTION 295 296 The \fIares_dns_record_destroy(3)\fP function destroys the memory associated 297 with the dns record created by either \fIares_dns_record_create(3)\fP or 298 \fIares_dns_parse(3)\fP passed in via 299 .IR dnsrec . 300 301 The \fIares_dns_parse(3)\fP function parses the buffer provided in 302 .IR buf 303 with length provided in 304 .IR buf_len. 305 The 306 .IR flags 307 parameter can be one or more \fIares_dns_parse_flags_t\fP, or zero if no 308 flags are needed. The resulting dns record data structure is stored into the 309 variable pointed to by 310 .IR dnsrec 311 and must be destroyed using \fIares_dns_record_destroy(3)\fP. 312 313 The \fIares_dns_write(3)\fP function takes a populated DNS record structure in 314 .IR dnsrec 315 and writes a wire-format DNS message into the variable pointed to by 316 .IR buf 317 and writes the length of the buffer into the variable pointed to by 318 .IR buf_len. 319 The buffer must be destroyed using \fIares_free_string(3)\fP. 320 321 The \fIares_dns_record_create(3)\fP function creates an empty DNS record structure 322 in the variable pointed to by 323 .IR dnsrec. 324 The 325 .IR id 326 parameter is the DNS message id, however if passing to \fIares_send(3)\fP this 327 identifier will be overwritten, so should typically be 0. The 328 .IR flags 329 parameter is one or more \fIares_dns_flags_t\fP. The opcode is passed in the 330 .IR opcode 331 parameter and should typically be \fIARES_OPCODE_QUERY\fP. The response code 332 is meant mostly for responses and is passed in the 333 .IR rcode 334 parameter and is typically \fPARES_RCODE_NOERROR\fP. 335 336 The \fIares_dns_record_duplicate(3)\fP function duplicates an existing DNS 337 record structure. This may be useful if needing to save a result as retrieved 338 from \fIares_send_dnsrec(3)\fP or \fIares_search_dnsrec(3)\fP. The structure 339 to be duplicated is passed in the 340 .IR dnsrec 341 parameter, and the duplicated copy is returned, or NULL on error such as 342 out of memory. 343 344 The \fIares_dns_record_get_id(3)\fP function is used to retrieve the DNS 345 message id from the DNS record provided in the 346 .IR dnsrec 347 parameter. 348 349 The \fIares_dns_record_set_id(3)\fP function is used to set the DNS 350 message id in the 351 .IR id 352 parameter from the DNS record provided in the 353 .IR dnsrec 354 parameter. This id will be overwritten when passing the record to c-ares, 355 so mostly exists for external purposes. 356 357 The \fIares_dns_record_get_flags(3)\fP function is used to retrieve the DNS 358 message flags from the DNS record provided in the 359 .IR dnsrec 360 parameter. 361 362 The \fIares_dns_record_get_opcode(3)\fP function is used to retrieve the DNS 363 message flags from the DNS record provided in the 364 .IR dnsrec 365 parameter. 366 367 The \fIares_dns_record_get_rcode(3)\fP function is used to retrieve the DNS 368 message response code from the DNS record provided in the 369 .IR dnsrec 370 parameter. 371 372 373 The \fIares_dns_record_query_add(3)\fP function is used to add a question to 374 the DNS record provided in the 375 .IR dnsrec 376 parameter. The domain name specified for the question is provided in the 377 .IR name 378 parameter, along with the question type in the 379 .IR qtype 380 parameter and the question class (typically \fIARES_CLASS_IN\fP) in the 381 .IR qclass 382 parameter. 383 384 The \fIares_dns_record_query_set_name(3)\fP function is used to modify the 385 question name in the DNS record provided in the 386 .IR dnsrec 387 parameter. The index of the query, which must be less than 388 \fIares_dns_record_query_cnt(3)\fP, is provided in the 389 .IR idx 390 parameter. The new domain name is provided in the 391 .IR name 392 parameter. Care should be taken as this will cause invalidation of any 393 \fIname\fP pointer retrieved from \fIares_dns_Record_query_get(3)\fP. This 394 function is useful if sending multiple similar queries without re-creating 395 the entire DNS query. 396 397 The \fIares_dns_record_query_set_type(3)\fP function is used to modify the 398 question type in the DNS record provided in the 399 .IR dnsrec 400 parameter. The index of the query, which must be less than 401 \fIares_dns_record_query_cnt(3)\fP, is provided in the 402 .IR idx 403 parameter. The new query type is provided in the 404 .IR qtype 405 parameter. 406 407 The \fIares_dns_record_query_cnt(3)\fP function is used to retrieve the number 408 of DNS questions in the DNS record provided in the 409 .IR dnsrec 410 parameter. 411 412 The \fIares_dns_record_query_get(3)\fP function is used to retrieve the details 413 of a single DNS question in the provided 414 .IR dnsrec 415 parameter. The index provided in the 416 .IR idx 417 parameter must be less than the value returned from \fIares_dns_record_query_cnt(3)\fP. 418 The DNS question name will be returned in the variable pointed to by the 419 .IR name 420 parameter, this may be provided as NULL if the name is not needed. This pointer 421 will be invalided by any call to \fIares_dns_record_query_set_name(3)\fP. 422 The DNS question type will be returned in the variable pointed to by the 423 .IR qtype 424 parameter, this may be provided as NULL if the type is not needed. 425 The DNS question class will be returned in the variable pointed to by the 426 .IR qclass 427 parameter, this may be provided as NULL if the class is not needed. 428 429 430 .SH RETURN VALUES 431 432 \fIares_dns_parse(3)\fP, \fIares_dns_write(3)\fP, \fIares_dns_record_create(3)\fP, 433 \fIares_dns_record_query_add(3)\fP, and \fIares_dns_record_query_get(3)\fP all 434 return an \fIares_status_t\fP error code. 435 .B ARES_SUCCESS 436 is returned on success, 437 .B ARES_ENOMEM 438 is returned on out of memory, 439 .B ARES_EFORMERR 440 is returned on misuse. 441 442 \fIares_dns_record_get_id(3)\fP, \fIares_dns_record_set_id(3)\fP, 443 \fIares_dns_record_get_flags(3)\fP, \fIares_dns_record_get_opcode(3)\fP, 444 \fIares_dns_record_get_rcode(3)\fP, and \fIares_dns_record_query_cnt(3)\fP 445 all returned their prescribed datatype values and in general can't fail except 446 for misuse cases, in which a 0 may be returned, however 0 can also be a valid 447 return value for most of these functions. 448 449 450 .SH AVAILABILITY 451 These functions were first introduced in c-ares version 1.22.0. 452 .SH SEE ALSO 453 .BR ares_dns_mapping (3), 454 .BR ares_dns_rr (3), 455 .BR ares_free_string (3)