ares_dns_rr.3 (26524B)
1 .\" Copyright (C) 2023 The c-ares project and its contributors. 2 .\" SPDX-License-Identifier: MIT 3 .\" 4 .TH ARES_DNS_RR 3 "12 November 2023" 5 .SH NAME 6 ares_dns_record_rr_add, ares_dns_record_rr_cnt, ares_dns_record_rr_del, 7 ares_dns_record_rr_get, ares_dns_record_rr_get_const, ares_dns_rr_get_addr, 8 ares_dns_rr_get_addr6, ares_dns_rr_get_bin, ares_dns_rr_get_abin_cnt, 9 ares_dns_rr_get_abin, ares_dns_rr_get_class, 10 ares_dns_rr_get_name, ares_dns_rr_get_opt, ares_dns_rr_get_opt_byid, 11 ares_dns_rr_get_opt_cnt, ares_dns_rr_get_str, ares_dns_rr_get_ttl, 12 ares_dns_rr_get_type, ares_dns_rr_get_u16, ares_dns_rr_get_u32, 13 ares_dns_rr_get_u8, ares_dns_rr_key_t, ares_dns_rr_set_addr, 14 ares_dns_rr_set_addr6, ares_dns_rr_set_bin, ares_dns_rr_add_abin, 15 ares_dns_rr_del_abin, ares_dns_rr_set_opt, 16 ares_dns_rr_set_str, ares_dns_rr_set_u16, ares_dns_rr_set_u32, 17 ares_dns_rr_set_u8, ares_dns_section_t, ares_tlsa_match_t, 18 ares_tlsa_selector_t, ares_tlsa_usage_t \- 19 DNS Resource Record creating, reading, and writing functions. 20 .SH SYNOPSIS 21 .nf 22 #include <ares.h> 23 24 size_t ares_dns_record_rr_cnt(const ares_dns_record_t *dnsrec, 25 ares_dns_section_t sect); 26 27 ares_status_t ares_dns_record_rr_add(ares_dns_rr_t **rr_out, 28 ares_dns_record_t *dnsrec, 29 ares_dns_section_t sect, 30 const char *name, 31 ares_dns_rec_type_t type, 32 ares_dns_class_t rclass, 33 unsigned int ttl); 34 35 ares_dns_rr_t *ares_dns_record_rr_get(ares_dns_record_t *dnsrec, 36 ares_dns_section_t sect, 37 size_t idx); 38 39 const ares_dns_rr_t *ares_dns_record_rr_get_const(const ares_dns_record_t *dnsrec, 40 ares_dns_section_t sect, 41 size_t idx); 42 43 ares_status_t ares_dns_record_rr_del(ares_dns_record_t *dnsrec, 44 ares_dns_section_t sect, 45 size_t idx); 46 47 const char *ares_dns_rr_get_name(const ares_dns_rr_t *rr); 48 49 ares_dns_rec_type_t ares_dns_rr_get_type(const ares_dns_rr_t *rr); 50 51 ares_dns_class_t ares_dns_rr_get_class(const ares_dns_rr_t *rr); 52 53 unsigned int ares_dns_rr_get_ttl(const ares_dns_rr_t *rr); 54 55 ares_status_t ares_dns_rr_set_addr(ares_dns_rr_t *dns_rr, 56 ares_dns_rr_key_t key, 57 const struct in_addr *addr); 58 59 ares_status_t ares_dns_rr_set_addr6(ares_dns_rr_t *dns_rr, 60 ares_dns_rr_key_t key, 61 const struct ares_in6_addr *addr); 62 63 ares_status_t ares_dns_rr_set_str(ares_dns_rr_t *dns_rr, 64 ares_dns_rr_key_t key, 65 const char *val); 66 67 ares_status_t ares_dns_rr_set_u8(ares_dns_rr_t *dns_rr, 68 ares_dns_rr_key_t key, 69 unsigned char val); 70 71 ares_status_t ares_dns_rr_set_u16(ares_dns_rr_t *dns_rr, 72 ares_dns_rr_key_t key, 73 unsigned short val); 74 75 ares_status_t ares_dns_rr_set_u32(ares_dns_rr_t *dns_rr, 76 ares_dns_rr_key_t key, 77 unsigned int val); 78 79 ares_status_t ares_dns_rr_set_bin(ares_dns_rr_t *dns_rr, 80 ares_dns_rr_key_t key, 81 const unsigned char *val, 82 size_t len); 83 84 ares_status_t ares_dns_rr_add_abin(ares_dns_rr_t *dns_rr, 85 ares_dns_rr_key_t key, 86 const unsigned char *val, 87 size_t len); 88 89 ares_status_t ares_dns_rr_del_abin(ares_dns_rr_t *dns_rr, 90 ares_dns_rr_key_t key, 91 size_t idx); 92 93 ares_status_t ares_dns_rr_set_opt(ares_dns_rr_t *dns_rr, 94 ares_dns_rr_key_t key, 95 unsigned short opt, 96 const unsigned char *val, 97 size_t val_len); 98 99 ares_status_t ares_dns_rr_del_opt_byid(ares_dns_rr_t *dns_rr, 100 ares_dns_rr_key_t key, 101 unsigned short opt); 102 103 const struct in_addr *ares_dns_rr_get_addr(const ares_dns_rr_t *dns_rr, 104 ares_dns_rr_key_t key); 105 106 const struct ares_in6_addr *ares_dns_rr_get_addr6(const ares_dns_rr_t *dns_rr, 107 ares_dns_rr_key_t key); 108 109 const char *ares_dns_rr_get_str(const ares_dns_rr_t *dns_rr, 110 ares_dns_rr_key_t key); 111 112 unsigned char ares_dns_rr_get_u8(const ares_dns_rr_t *dns_rr, 113 ares_dns_rr_key_t key); 114 115 unsigned short ares_dns_rr_get_u16(const ares_dns_rr_t *dns_rr, 116 ares_dns_rr_key_t key); 117 118 unsigned int ares_dns_rr_get_u32(const ares_dns_rr_t *dns_rr, 119 ares_dns_rr_key_t key); 120 121 const unsigned char *ares_dns_rr_get_bin(const ares_dns_rr_t *dns_rr, 122 ares_dns_rr_key_t key, 123 size_t *len); 124 125 size_t ares_dns_rr_get_abin_cnt(const ares_dns_rr_t *dns_rr, 126 ares_dns_rr_key_t key); 127 128 const unsigned char *ares_dns_rr_get_abin(const ares_dns_rr_t *dns_rr, 129 ares_dns_rr_key_t key, size_t idx, 130 size_t *len); 131 132 size_t ares_dns_rr_get_opt_cnt(const ares_dns_rr_t *dns_rr, 133 ares_dns_rr_key_t key); 134 135 unsigned short ares_dns_rr_get_opt(const ares_dns_rr_t *dns_rr, 136 ares_dns_rr_key_t key, 137 size_t idx, 138 const unsigned char **val, 139 size_t *val_len); 140 141 ares_bool_t ares_dns_rr_get_opt_byid(const ares_dns_rr_t *dns_rr, 142 ares_dns_rr_key_t key, 143 unsigned short opt, 144 const unsigned char **val, 145 size_t *val_len); 146 147 .fi 148 .SH ENUMERATIONS 149 150 .B ares_dns_section_t - 151 DNS RR section types: 152 .RS 4 153 .B ARES_SECTION_ANSWER 154 - Answer section 155 .br 156 .B ARES_SECTION_AUTHORITY 157 - Authority section 158 .br 159 .B ARES_SECTION_ADDITIONAL 160 - Additional Information section 161 .br 162 .RE 163 164 .B ares_dns_rr_key_t - 165 Keys used for handling RR record parameters: 166 .RS 4 167 .B ARES_RR_A_ADDR 168 - A Record. Address. Datatype: \fIARES_DATATYPE_INADDR\fP 169 .br 170 .B ARES_RR_NS_NSDNAME 171 - NS Record. Name. Datatype: \fIARES_DATATYPE_NAME\fP 172 .br 173 .B ARES_RR_CNAME_CNAME 174 - CNAME Record. CName. Datatype: \fIARES_DATATYPE_NAME\fP 175 .br 176 .B ARES_RR_SOA_MNAME 177 - SOA Record. MNAME, Primary Source of Data. Datatype: \fIARES_DATATYPE_NAME\fP 178 .br 179 .B ARES_RR_SOA_RNAME 180 - SOA Record. RNAME, Mailbox of person responsible. Datatype: \fIARES_DATATYPE_NAME\fP 181 .br 182 .B ARES_RR_SOA_SERIAL 183 - SOA Record. Serial, version. Datatype: \fIARES_DATATYPE_U32\fP 184 .br 185 .B ARES_RR_SOA_REFRESH 186 - SOA Record. Refresh, zone refersh interval. Datatype: \fIARES_DATATYPE_U32\fP 187 .br 188 .B ARES_RR_SOA_RETRY 189 - SOA Record. Retry, failed refresh retry interval. Datatype: \fIARES_DATATYPE_U32\fP 190 .br 191 .B ARES_RR_SOA_EXPIRE 192 - SOA Record. Expire, upper limit on authority. Datatype: \fIARES_DATATYPE_U32\fP 193 .br 194 .B ARES_RR_SOA_MINIMUM 195 - SOA Record. Minimum, RR TTL. Datatype: \fIARES_DATATYPE_U32\fP 196 .br 197 .B ARES_RR_PTR_DNAME 198 - PTR Record. DNAME, pointer domain. Datatype: \fIARES_DATATYPE_NAME\fP 199 .br 200 .B ARES_RR_HINFO_CPU 201 - HINFO Record. CPU. Datatype: \fIARES_DATATYPE_STR\fP 202 .br 203 .B ARES_RR_HINFO_OS 204 - HINFO Record. OS. Datatype: \fIARES_DATATYPE_STR\fP 205 .br 206 .B ARES_RR_MX_PREFERENCE 207 - MX Record. Preference. Datatype: \fIARES_DATATYPE_U16\fP 208 .br 209 .B ARES_RR_MX_EXCHANGE 210 - MX Record. Exchange, domain. Datatype: \fIARES_DATATYPE_NAME\fP 211 .br 212 .B ARES_RR_TXT_DATA 213 - TXT Record. Data. Datatype: \fIARES_DATATYPE_ABINP\fP 214 .br 215 .B ARES_RR_SIG_TYPE_COVERED 216 - SIG Record. Type Covered. Datatype: \fIARES_DATATYPE_U16\fP 217 .br 218 .B ARES_RR_SIG_ALGORITHM 219 - SIG Record. Algorithm. Datatype: \fIARES_DATATYPE_U8\fP 220 .br 221 .B ARES_RR_SIG_LABELS 222 - SIG Record. Labels. Datatype: \fIARES_DATATYPE_U8\fP 223 .br 224 .B ARES_RR_SIG_ORIGINAL_TTL 225 - SIG Record. Original TTL. Datatype: \fIARES_DATATYPE_U32\fP 226 .br 227 .B ARES_RR_SIG_EXPIRATION 228 - SIG Record. Signature Expiration. Datatype: \fIARES_DATATYPE_U32\fP 229 .br 230 .B ARES_RR_SIG_INCEPTION 231 - SIG Record. Signature Inception. Datatype: \fIARES_DATATYPE_U32\fP 232 .br 233 .B ARES_RR_SIG_KEY_TAG 234 - SIG Record. Key Tag. Datatype: \fIARES_DATATYPE_U16\fP 235 .br 236 .B ARES_RR_SIG_SIGNERS_NAME 237 - SIG Record. Signer's Name. Datatype: \fIARES_DATATYPE_NAME\fP 238 .br 239 .B ARES_RR_SIG_SIGNATURE 240 - SIG Record. Signature. Datatype: \fIARES_DATATYPE_BIN\fP 241 .br 242 .B ARES_RR_AAAA_ADDR 243 - AAAA Record. Address. Datatype: \fIARES_DATATYPE_INADDR6\fP 244 .br 245 .B ARES_RR_SRV_PRIORITY 246 - SRV Record. Priority. Datatype: \fIARES_DATATYPE_U16\fP 247 .br 248 .B ARES_RR_SRV_WEIGHT 249 - SRV Record. Weight. Datatype: \fIARES_DATATYPE_U16\fP 250 .br 251 .B ARES_RR_SRV_PORT 252 - SRV Record. Port. Datatype: \fIARES_DATATYPE_U16\fP 253 .br 254 .B ARES_RR_SRV_TARGET 255 - SRV Record. Target domain. Datatype: \fIARES_DATATYPE_NAME\fP 256 .br 257 .B ARES_RR_NAPTR_ORDER 258 - NAPTR Record. Order. Datatype: \fIARES_DATATYPE_U16\fP 259 .br 260 .B ARES_RR_NAPTR_PREFERENCE 261 - NAPTR Record. Preference. Datatype: \fIARES_DATATYPE_U16\fP 262 .br 263 .B ARES_RR_NAPTR_FLAGS 264 - NAPTR Record. Flags. Datatype: \fIARES_DATATYPE_STR\fP 265 .br 266 .B ARES_RR_NAPTR_SERVICES 267 - NAPTR Record. Services. Datatype: \fIARES_DATATYPE_STR\fP 268 .br 269 .B ARES_RR_NAPTR_REGEXP 270 - NAPTR Record. Regexp. Datatype: \fIARES_DATATYPE_STR\fP 271 .br 272 .B ARES_RR_NAPTR_REPLACEMENT 273 - NAPTR Record. Replacement. Datatype: \fIARES_DATATYPE_NAME\fP 274 .br 275 .B ARES_RR_OPT_UDP_SIZE 276 - OPT Record. UDP Size. Datatype: \fIARES_DATATYPE_U16\fP 277 .br 278 .B ARES_RR_OPT_VERSION 279 - OPT Record. Version. Datatype: \fIARES_DATATYPE_U8\fP 280 .br 281 .B ARES_RR_OPT_FLAGS 282 - OPT Record. Flags. Datatype: \fIARES_DATATYPE_U16\fP 283 .br 284 .B ARES_RR_OPT_OPTIONS 285 - OPT Record. Options. See \fIares_opt_param_t\fP. Datatype: \fIARES_DATATYPE_OPT\fP 286 .br 287 .B ARES_RR_TLSA_CERT_USAGE 288 - TLSA Record. Certificate Usage. See \fIares_tlsa_usage_t\fP. Datatype: \fIARES_DATATYPE_U8\fP 289 .br 290 .B ARES_RR_TLSA_SELECTOR 291 - TLSA Record. Selector. See \fIares_tlsa_selector_t\fP. Datatype: \fIARES_DATATYPE_U8\fP 292 .br 293 .B ARES_RR_TLSA_MATCH 294 - TLSA Record. Matching Type. See \fIares_tlsa_match_t\fP. Datatype: \fIARES_DATATYPE_U8\fP 295 .br 296 .B ARES_RR_TLSA_DATA 297 - TLSA Record. Certificate Association Data. Datatype: \fIARES_DATATYPE_BIN\fP 298 .br 299 .B ARES_RR_SVCB_PRIORITY 300 - SVCB Record. SvcPriority. Datatype: \fIARES_DATATYPE_U16\fP 301 .br 302 .B ARES_RR_SVCB_TARGET 303 - SVCB Record. TargetName. Datatype: \fIARES_DATATYPE_NAME\fP 304 .br 305 .B ARES_RR_SVCB_PARAMS 306 - SVCB Record. SvcParams. See \fIares_svcb_param_t\fP. Datatype: \fIARES_DATATYPE_OPT\fP 307 .br 308 .B ARES_RR_HTTPS_PRIORITY 309 - HTTPS Record. SvcPriority. Datatype: \fIARES_DATATYPE_U16\fP 310 .br 311 .B ARES_RR_HTTPS_TARGET 312 - HTTPS Record. TargetName. Datatype: \fIARES_DATATYPE_NAME\fP 313 .br 314 .B ARES_RR_HTTPS_PARAMS 315 - HTTPS Record. SvcParams. See \fIares_svcb_param_t\fP. Datatype: \fIARES_DATATYPE_OPT\fP 316 .br 317 .B ARES_RR_URI_PRIORITY 318 - URI Record. Priority. Datatype: \fIARES_DATATYPE_U16\fP 319 .br 320 .B ARES_RR_URI_WEIGHT 321 - URI Record. Weight. Datatype: \fIARES_DATATYPE_U16\fP 322 .br 323 .B ARES_RR_URI_TARGET 324 - URI Record. Target domain. Datatype: \fIARES_DATATYPE_NAME\fP 325 .br 326 .B ARES_RR_CAA_CRITICAL 327 - CAA Record. Critical flag. Datatype: \fIARES_DATATYPE_U8\fP 328 .br 329 .B ARES_RR_CAA_TAG 330 - CAA Record. Tag/Property. Datatype: \fIARES_DATATYPE_STR\fP 331 .br 332 .B ARES_RR_CAA_VALUE 333 - CAA Record. Value. Datatype: \fIARES_DATATYPE_BINP\fP 334 .br 335 .B ARES_RR_RAW_RR_TYPE 336 - RAW Record. RR Type. Datatype: \fIARES_DATATYPE_U16\fP 337 .br 338 .B ARES_RR_RAW_RR_DATA 339 - RAW Record. RR Data. Datatype: \fIARES_DATATYPE_BIN\fP 340 .br 341 .RE 342 343 .B ares_tlsa_usage_t - 344 TLSA Record \fIARES_RR_TLSA_CERT_USAGE\fP known values 345 .RS 4 346 .B ARES_TLSA_USAGE_CA 347 - Certificate Usage 0. CA Constraint 348 .br 349 .B ARES_TLSA_USAGE_SERVICE 350 - Certificate Usage 1. Service Certificate Constraint 351 .br 352 .B ARES_TLSA_USAGE_TRUSTANCHOR 353 - Certificate Usage 2. Trust Anchor Assertion 354 .br 355 .B ARES_TLSA_USAGE_DOMAIN 356 - Certificate Usage 3. Domain-issued certificate 357 .br 358 .RE 359 360 .B ares_tlsa_selector_t - 361 TLSA Record \fIARES_RR_TLSA_SELECTOR\fP known values: 362 .RS 4 363 .B ARES_TLSA_SELECTOR_FULL 364 - Full Certificate 365 .br 366 .B ARES_TLSA_SELECTOR_SUBJPUBKEYINFO 367 - DER-encoded SubjectPublicKeyInfo 368 .br 369 .RE 370 371 .B ares_tlsa_match_t - 372 TLSA Record \fIARES_RR_TLSA_MATCH\fP known values: 373 .RS 4 374 .B ARES_TLSA_MATCH_EXACT 375 - Exact match 376 .br 377 .B ARES_TLSA_MATCH_SHA256 378 - Sha256 match 379 .br 380 .B ARES_TLSA_MATCH_SHA512 381 - Sha512 match 382 .br 383 .RE 384 385 386 .SH DESCRIPTION 387 388 The \fIares_dns_record_rr_cnt(3)\fP function returns the number of resource 389 records in the DNS record provided by the 390 .IR dnsrec 391 parameter for the section provided in the 392 .IR sect 393 parameter. 394 395 The \fIares_dns_record_rr_add(3)\fP function adds a new resource record entry 396 the the DNS record provided by the 397 .IR dnsrec 398 parameter. The resulting resource record is stored into the variable pointed to by 399 .IR rr_out. 400 The DNS section the resource record belongs to is specified by the 401 .IR sect 402 parameter. The domain name associated with the resource record is specified by the 403 .IR name 404 parameter, which can not be NULL but may be an empty string, or ".". The resource 405 record type is specified in the 406 .IR type 407 parameter, along with the DNS record class in the 408 .IR rclass 409 parameter, and the Time To Live (TTL) in the 410 .IR ttl 411 parameter. 412 413 414 The \fIares_dns_record_rr_get(3)\fP and \fIares_dns_record_rr_get_const(3)\fP 415 functions are used to retrieve the resource record pointer from the DNS record 416 provided in the 417 .IR dnsrec 418 parameter, for the resource record section provided in the 419 .IR sect 420 parameter, for the specified index in the 421 .IR idx 422 parameter. The index must be less than \fIares_dns_record_rr_cnt(3)\fP. The 423 former returns a writable pointer to the resource record, while the latter 424 returns a read-only pointer to the resource record. 425 426 427 The \fIares_dns_record_rr_del(3)\fP is used to delete a resource record from 428 the DNS record specified in the 429 .IR dnsrec 430 parameter. Its primary use is to remove a \fIARES_REC_TYPE_OPT\fP record when 431 needing to retry a query without EDNS support. The DNS RR section is specified 432 via the 433 .IR sect 434 parameter, and the index to remove is specified in the 435 .IR idx 436 parameter. The index must be less than \fIares_dns_record_rr_cnt(3)\fP. 437 438 439 The \fIares_dns_rr_get_name(3)\fP function is used to retrieve the resource 440 record domain name from the Resource Record pointer provided in the 441 .IR rr 442 parameter. 443 444 The \fIares_dns_rr_get_type(3)\fP function is used to retrieve the resource 445 record type from the Resource Record pointer provided in the 446 .IR rr 447 parameter. 448 449 The \fIares_dns_rr_get_class(3)\fP function is used to retrieve the resource 450 record class from the Resource Record pointer provided in the 451 .IR rr 452 parameter. 453 454 The \fIares_dns_rr_get_ttl(3)\fP function is used to retrieve the resource 455 record class Time to Live (TTL) from the Resource Record pointer provided in the 456 .IR rr 457 parameter. 458 459 The \fIares_dns_rr_set_addr(3)\fP function is used to set an IPv4 address for the 460 associated resource record key/parameter when the datatype is \fIARES_DATATYPE_INADDR\fP. 461 The resource record to be modified is provided in the 462 .IR dns_rr 463 parameter, the key/parameter is provided in the 464 .IR key 465 parameter, and the value is provided in the 466 .IR addr 467 parameter. 468 469 The \fIares_dns_rr_set_addr6(3)\fP function is used to set an IPv6 address for the 470 associated resource record key/parameter when the datatype is \fIARES_DATATYPE_INADDR6\fP. 471 The resource record to be modified is provided in the 472 .IR dns_rr 473 parameter, the key/parameter is provided in the 474 .IR key 475 parameter, and the value is provided in the 476 .IR addr 477 parameter. 478 479 The \fIares_dns_rr_set_str(3)\fP function is used to set a string for the 480 associated resource record key/parameter when the datatype is \fIARES_DATATYPE_STR\fP 481 or \fIARES_DATATYPE_NAME\fP. Most strings are limited to 255 bytes, 482 however some records, such as a TXT record may allow longer as they are output 483 as multiple strings. The resource record to be modified is 484 provided in the 485 .IR dns_rr 486 parameter, the key/parameter is provided in the 487 .IR key 488 parameter, and the value is provided in the 489 .IR val 490 parameter. 491 492 The \fIares_dns_rr_set_u8(3)\fP function is used to set an 8bit unsigned value for the 493 associated resource record key/parameter when the datatype is \fIARES_DATATYPE_U8\fP. 494 The resource record to be modified is provided in the 495 .IR dns_rr 496 parameter, the key/parameter is provided in the 497 .IR key 498 parameter, and the value is provided in the 499 .IR val 500 parameter. 501 502 The \fIares_dns_rr_set_u16(3)\fP function is used to set an 16bit unsigned value for the 503 associated resource record key/parameter when the datatype is \fIARES_DATATYPE_U16\fP. 504 The resource record to be modified is provided in the 505 .IR dns_rr 506 parameter, the key/parameter is provided in the 507 .IR key 508 parameter, and the value is provided in the 509 .IR val 510 parameter. 511 512 The \fIares_dns_rr_set_u32(3)\fP function is used to set an 32bit unsigned value for the 513 associated resource record key/parameter when the datatype is \fIARES_DATATYPE_U32\fP. 514 The resource record to be modified is provided in the 515 .IR dns_rr 516 parameter, the key/parameter is provided in the 517 .IR key 518 parameter, and the value is provided in the 519 .IR val 520 parameter. 521 522 The \fIares_dns_rr_set_bin(3)\fP function is used to set a binary value for the 523 associated resource record key/parameter when the datatype is \fIARES_DATATYPE_BIN\fP 524 or \fIARES_DATATYPE_BINP\fP. 525 The resource record to be modified is provided in the 526 .IR dns_rr 527 parameter, the key/parameter is provided in the 528 .IR key 529 parameter, and the value is provided in the 530 .IR val 531 parameter. And the associated value length is provided in the 532 .IR len 533 parameter. 534 535 The \fIares_dns_rr_add_abin(3)\fP function is used to append a binary value in 536 the array for the associated resource record key/parameter when the datatype 537 is \fIARES_DATATYPE_ABINP\fP. 538 The resource record to be modified is provided in the 539 .IR dns_rr 540 parameter, the key/parameter is provided in the 541 .IR key 542 parameter, and the value is provided in the 543 .IR val 544 parameter. And the associated value length is provided in the 545 .IR len 546 parameter. 547 548 The \fIares_dns_rr_del_abin(3)\fP function is used to delete a binary value in 549 the array for the associated resource record key/parameter when the datatype 550 is \fIARES_DATATYPE_ABINP\fP. 551 The resource record to be modified is provided in the 552 .IR dns_rr 553 parameter, the key/parameter is provided in the 554 .IR key 555 parameter, and the index to remove is provided in the 556 .IR idx 557 parameter. 558 559 The \fIares_dns_rr_set_opt(3)\fP function is used to set option/parameter keys and 560 values for the resource record when the datatype is \fIARES_DATATYPE_OPT\fP. The 561 resource record to be modified is provided in the 562 .IR dns_rr 563 parameter. They key/parameter is provided in the 564 .IR key 565 parameter. The option/parameter value specific to the resource record is provided 566 in the 567 .IR opt 568 parameter, and this is left to the user to determine the appropriate value to 569 use. Some known values may be provided by \fIares_svcb_param_t\fP and \fIares_opt_param_t\fP 570 enumerations. The value for the option is always provided in binary form in 571 .IR val 572 with length provided in 573 .IR val_len. 574 575 The \fIares_dns_rr_del_opt_byid(3)\fP function is used to delete option/parameter 576 keys and values for the resource record when the datatype is 577 \fIARES_DATATYPE_OPT\fP. The resource record to be modified is provided in the 578 .IR dns_rr 579 parameter. They key/parameter is provided in the 580 .IR key 581 parameter. The option/parameter value specific to the resource record is provided 582 in the 583 .IR opt 584 parameter. This function returns \fIARES_SUCCESS\fP if the record is successfully 585 removed, or \fIARES_ENOTFOUND\fP if the record could not be found. 586 587 The \fIares_dns_rr_get_addr(3)\fP function is used to retrieve the IPv4 address 588 from the resource record when the datatype is \fIARES_DATATYPE_INADDR\fP. The 589 resource record is provided in the 590 .IR dns_rr 591 parameter and the key/parameter to retrieve is provided in the 592 .IR key 593 parameter. 594 595 The \fIares_dns_rr_get_addr6(3)\fP function is used to retrieve the IPv6 address 596 from the resource record when the datatype is \fIARES_DATATYPE_INADDR6\fP. The 597 resource record is provided in the 598 .IR dns_rr 599 parameter and the key/parameter to retrieve is provided in the 600 .IR key 601 parameter. 602 603 The \fIares_dns_rr_get_str(3)\fP function is used to retrieve a string 604 from the resource record when the datatype is \fIARES_DATATYPE_STR\fP or 605 \fIARES_DATATYPE_NAME\fP. The resource record is provided in the 606 .IR dns_rr 607 parameter and the key/parameter to retrieve is provided in the 608 .IR key 609 parameter. 610 611 The \fIares_dns_rr_get_u8(3)\fP function is used to retrieve an 8bit integer 612 from the resource record when the datatype is \fIARES_DATATYPE_U8\fP. 613 The resource record is provided in the 614 .IR dns_rr 615 parameter and the key/parameter to retrieve is provided in the 616 .IR key 617 parameter. 618 619 The \fIares_dns_rr_get_u16(3)\fP function is used to retrieve a 16bit integer 620 from the resource record when the datatype is \fIARES_DATATYPE_U16\fP. 621 The resource record is provided in the 622 .IR dns_rr 623 parameter and the key/parameter to retrieve is provided in the 624 .IR key 625 parameter. 626 627 The \fIares_dns_rr_get_u32(3)\fP function is used to retrieve a 32bit integer 628 from the resource record when the datatype is \fIARES_DATATYPE_U32\fP. 629 The resource record is provided in the 630 .IR dns_rr 631 parameter and the key/parameter to retrieve is provided in the 632 .IR key 633 parameter. 634 635 The \fIares_dns_rr_get_bin(3)\fP function is used to retrieve binary data 636 from the resource record when the datatype is \fIARES_DATATYPE_BIN\fP or 637 \fIARES_DATATYPE_BINP\fP. 638 The resource record is provided in the 639 .IR dns_rr 640 parameter and the key/parameter to retrieve is provided in the 641 .IR key 642 parameter, and length is stored into the variable pointed to by 643 .IR len. 644 645 The \fIares_dns_rr_get_abin_cnt(3)\fP function is used to retrieve the count 646 of the array of stored binary values from the resource record when the datatype 647 is \fIARES_DATATYPE_ABINP\fP. 648 The resource record is provided in the 649 .IR dns_rr 650 parameter and the key/parameter to retrieve is provided in the 651 .IR key 652 parameter. 653 654 The \fIares_dns_rr_get_abin(3)\fP function is used to retrieve binary data from 655 the resource record array when the datatype is \fIARES_DATATYPE_ABINP\fP. 656 The resource record is provided in the 657 .IR dns_rr 658 parameter and the key/parameter to retrieve is provided in the 659 .IR key 660 parameter, and the index to retrieve from the array is provided by the 661 .IR idx 662 parameter, and length is stored into the variable pointed to by 663 .IR len. 664 665 The \fIares_dns_rr_get_opt_cnt(3)\fP function is used to retrieve the count 666 of options/parameters associated with the resource record when the datatype 667 is \fIARES_DATATYPE_OPT\fP. 668 The resource record is provided in the 669 .IR dns_rr 670 parameter and the key/parameter to retrieve is provided in the 671 .IR key. 672 673 The \fIares_dns_rr_get_opt(3)\fP function is used to retrieve binary option data 674 from the resource record when the datatype is \fIARES_DATATYPE_OPT\fP for the 675 specified index. 676 The resource record is provided in the 677 .IR dns_rr 678 parameter and the key/parameter to retrieve is provided in the 679 .IR key 680 parameter, the index to retrieve the option data from is provided in the 681 .IR idx 682 parameter. The value is stored into the variable pointed to by 683 .IR val 684 and length is stored into the variable pointed to by 685 .IR val_len. 686 687 The \fIares_dns_rr_get_opt_byid(3)\fP function is used to retrieve binary option data 688 from the resource record when the datatype is \fIARES_DATATYPE_OPT\fP for the 689 specified option identifier, if it exists. 690 The resource record is provided in the 691 .IR dns_rr 692 parameter and the key/parameter to retrieve is provided in the 693 .IR key 694 parameter, the identifier to retrieve the option data from is provided in the 695 .IR opt 696 parameter. The value is stored into the variable pointed to by 697 .IR val 698 and length is stored into the variable pointed to by 699 .IR val_len. 700 701 702 .SH RETURN VALUES 703 704 \fIares_dns_record_rr_cnt(3)\fP and \fIares_dns_rr_get_opt_cnt(3)\fP return the 705 respective counts. 706 707 \fIares_dns_record_rr_add(3)\fP, \fIares_dns_record_rr_del(3)\fP, 708 \fIares_dns_rr_set_addr(3)\fP, \fIares_dns_rr_set_addr6(3)\fP, 709 \fIares_dns_rr_set_str(3)\fP, \fIares_dns_rr_set_u8(3)\fP, 710 \fIares_dns_rr_set_u16(3)\fP, \fIares_dns_rr_set_u32(3)\fP, 711 \fIares_dns_rr_set_bin(3)\fP, \fIares_dns_rr_add_abin(3)\fP, 712 \fIares_dns_rr_del_abin(3)\fP, 713 and \fIares_dns_rr_set_opt(3)\fP all return an \fIares_status_t\fP error code. 714 .B ARES_SUCCESS 715 is returned on success, 716 .B ARES_ENOMEM 717 is returned on out of memory, 718 .B ARES_EFORMERR 719 is returned on misuse. 720 721 722 \fIares_dns_rr_get_name(3)\fP, \fIares_dns_rr_get_type(3)\fP, 723 \fIares_dns_rr_get_class(3)\fP, \fIares_dns_rr_get_ttl(3)\fP, 724 \fIares_dns_rr_get_addr(3)\fP, \fIares_dns_rr_get_addr6(3)\fP, 725 \fIares_dns_rr_get_str(3)\fP, \fIares_dns_rr_get_u8(3)\fP, 726 \fIares_dns_rr_get_u16(3)\fP, \fIares_dns_rr_get_u32(3)\fP, 727 \fIares_dns_rr_get_bin(3)\fP, \fIares_dns_rr_get_abin_cnt(3)\fP, 728 \fIares_dns_rr_get_abin(3)\fP, \fIares_dns_rr_get_opt(3)\fP all return their 729 prescribed datatype values and in general can't fail except for misuse cases, 730 in which a 0 (or NULL) may be returned, however 0 can also be a valid return 731 value for most of these functions. 732 733 \fIares_dns_record_rr_get(3)\fP and \fIares_dns_record_rr_get_const(3)\fP will 734 return the requested resource record pointer or NULL on failure (misuse). 735 736 \fIares_dns_rr_get_opt_byid(3)\fP will return ARES_TRUE if the option was 737 found, otherwise ARES_FALSE if not found (or misuse). 738 739 .SH AVAILABILITY 740 These functions were first introduced in c-ares version 1.22.0. 741 .SH SEE ALSO 742 .BR ares_dns_mapping (3), 743 .BR ares_dns_record (3), 744 .BR ares_free_string (3)