From cafe6b37db3c7571ae38f02ac528e44ebbdad1f9 Mon Sep 17 00:00:00 2001 From: Brad House Date: Mon, 13 Nov 2023 12:26:29 -0500 Subject: [PATCH] Add DNS record manpages (#615) The new DNS record parser and writer needs manpages. This PR implements those. Fix By: Brad House (@bradh352) --- docs/Makefile.inc | 66 +++ docs/ares_dns_class_fromstr.3 | 4 + docs/ares_dns_class_t.3 | 3 + docs/ares_dns_class_tostr.3 | 4 + docs/ares_dns_datatype_t.3 | 4 + docs/ares_dns_flags_t.3 | 3 + docs/ares_dns_mapping.3 | 296 ++++++++++++++ docs/ares_dns_opcode_t.3 | 3 + docs/ares_dns_opcode_tostr.3 | 4 + docs/ares_dns_opt_datatype_t.3 | 4 + docs/ares_dns_opt_get_datatype.3 | 4 + docs/ares_dns_opt_get_name.3 | 4 + docs/ares_dns_parse.3 | 3 + docs/ares_dns_rcode_t.3 | 3 + docs/ares_dns_rcode_tostr.3 | 4 + docs/ares_dns_rec_type_fromstr.3 | 4 + docs/ares_dns_rec_type_t.3 | 3 + docs/ares_dns_rec_type_tostr.3 | 4 + docs/ares_dns_record.3 | 375 +++++++++++++++++ docs/ares_dns_record_create.3 | 3 + docs/ares_dns_record_destroy.3 | 3 + docs/ares_dns_record_get_flags.3 | 3 + docs/ares_dns_record_get_id.3 | 3 + docs/ares_dns_record_get_opcode.3 | 3 + docs/ares_dns_record_get_rcode.3 | 3 + docs/ares_dns_record_query_add.3 | 3 + docs/ares_dns_record_query_cnt.3 | 3 + docs/ares_dns_record_query_get.3 | 3 + docs/ares_dns_record_rr_add.3 | 3 + docs/ares_dns_record_rr_cnt.3 | 3 + docs/ares_dns_record_rr_del.3 | 3 + docs/ares_dns_record_rr_get.3 | 3 + docs/ares_dns_rr.3 | 621 +++++++++++++++++++++++++++++ docs/ares_dns_rr_get_addr.3 | 3 + docs/ares_dns_rr_get_addr6.3 | 3 + docs/ares_dns_rr_get_bin.3 | 3 + docs/ares_dns_rr_get_class.3 | 3 + docs/ares_dns_rr_get_keys.3 | 3 + docs/ares_dns_rr_get_name.3 | 3 + docs/ares_dns_rr_get_opt.3 | 3 + docs/ares_dns_rr_get_opt_byid.3 | 3 + docs/ares_dns_rr_get_opt_cnt.3 | 3 + docs/ares_dns_rr_get_str.3 | 3 + docs/ares_dns_rr_get_ttl.3 | 3 + docs/ares_dns_rr_get_type.3 | 3 + docs/ares_dns_rr_get_u16.3 | 3 + docs/ares_dns_rr_get_u32.3 | 3 + docs/ares_dns_rr_get_u8.3 | 3 + docs/ares_dns_rr_key_datatype.3 | 4 + docs/ares_dns_rr_key_t.3 | 3 + docs/ares_dns_rr_key_to_rec_type.3 | 4 + docs/ares_dns_rr_key_tostr.3 | 4 + docs/ares_dns_rr_set_addr.3 | 3 + docs/ares_dns_rr_set_addr6.3 | 3 + docs/ares_dns_rr_set_bin.3 | 3 + docs/ares_dns_rr_set_opt.3 | 3 + docs/ares_dns_rr_set_str.3 | 3 + docs/ares_dns_rr_set_u16.3 | 3 + docs/ares_dns_rr_set_u32.3 | 3 + docs/ares_dns_rr_set_u8.3 | 3 + docs/ares_dns_section_t.3 | 3 + docs/ares_dns_section_tostr.3 | 4 + docs/ares_dns_write.3 | 3 + docs/ares_opt_param_t.3 | 4 + docs/ares_reinit.3 | 2 + docs/ares_svcb_param_t.3 | 4 + docs/ares_tlsa_match_t.3 | 3 + docs/ares_tlsa_selector_t.3 | 3 + docs/ares_tlsa_usage_t.3 | 3 + include/ares_dns_record.h | 51 +-- 70 files changed, 1594 insertions(+), 25 deletions(-) create mode 100644 docs/ares_dns_class_fromstr.3 create mode 100644 docs/ares_dns_class_t.3 create mode 100644 docs/ares_dns_class_tostr.3 create mode 100644 docs/ares_dns_datatype_t.3 create mode 100644 docs/ares_dns_flags_t.3 create mode 100644 docs/ares_dns_mapping.3 create mode 100644 docs/ares_dns_opcode_t.3 create mode 100644 docs/ares_dns_opcode_tostr.3 create mode 100644 docs/ares_dns_opt_datatype_t.3 create mode 100644 docs/ares_dns_opt_get_datatype.3 create mode 100644 docs/ares_dns_opt_get_name.3 create mode 100644 docs/ares_dns_parse.3 create mode 100644 docs/ares_dns_rcode_t.3 create mode 100644 docs/ares_dns_rcode_tostr.3 create mode 100644 docs/ares_dns_rec_type_fromstr.3 create mode 100644 docs/ares_dns_rec_type_t.3 create mode 100644 docs/ares_dns_rec_type_tostr.3 create mode 100644 docs/ares_dns_record.3 create mode 100644 docs/ares_dns_record_create.3 create mode 100644 docs/ares_dns_record_destroy.3 create mode 100644 docs/ares_dns_record_get_flags.3 create mode 100644 docs/ares_dns_record_get_id.3 create mode 100644 docs/ares_dns_record_get_opcode.3 create mode 100644 docs/ares_dns_record_get_rcode.3 create mode 100644 docs/ares_dns_record_query_add.3 create mode 100644 docs/ares_dns_record_query_cnt.3 create mode 100644 docs/ares_dns_record_query_get.3 create mode 100644 docs/ares_dns_record_rr_add.3 create mode 100644 docs/ares_dns_record_rr_cnt.3 create mode 100644 docs/ares_dns_record_rr_del.3 create mode 100644 docs/ares_dns_record_rr_get.3 create mode 100644 docs/ares_dns_rr.3 create mode 100644 docs/ares_dns_rr_get_addr.3 create mode 100644 docs/ares_dns_rr_get_addr6.3 create mode 100644 docs/ares_dns_rr_get_bin.3 create mode 100644 docs/ares_dns_rr_get_class.3 create mode 100644 docs/ares_dns_rr_get_keys.3 create mode 100644 docs/ares_dns_rr_get_name.3 create mode 100644 docs/ares_dns_rr_get_opt.3 create mode 100644 docs/ares_dns_rr_get_opt_byid.3 create mode 100644 docs/ares_dns_rr_get_opt_cnt.3 create mode 100644 docs/ares_dns_rr_get_str.3 create mode 100644 docs/ares_dns_rr_get_ttl.3 create mode 100644 docs/ares_dns_rr_get_type.3 create mode 100644 docs/ares_dns_rr_get_u16.3 create mode 100644 docs/ares_dns_rr_get_u32.3 create mode 100644 docs/ares_dns_rr_get_u8.3 create mode 100644 docs/ares_dns_rr_key_datatype.3 create mode 100644 docs/ares_dns_rr_key_t.3 create mode 100644 docs/ares_dns_rr_key_to_rec_type.3 create mode 100644 docs/ares_dns_rr_key_tostr.3 create mode 100644 docs/ares_dns_rr_set_addr.3 create mode 100644 docs/ares_dns_rr_set_addr6.3 create mode 100644 docs/ares_dns_rr_set_bin.3 create mode 100644 docs/ares_dns_rr_set_opt.3 create mode 100644 docs/ares_dns_rr_set_str.3 create mode 100644 docs/ares_dns_rr_set_u16.3 create mode 100644 docs/ares_dns_rr_set_u32.3 create mode 100644 docs/ares_dns_rr_set_u8.3 create mode 100644 docs/ares_dns_section_t.3 create mode 100644 docs/ares_dns_section_tostr.3 create mode 100644 docs/ares_dns_write.3 create mode 100644 docs/ares_opt_param_t.3 create mode 100644 docs/ares_svcb_param_t.3 create mode 100644 docs/ares_tlsa_match_t.3 create mode 100644 docs/ares_tlsa_selector_t.3 create mode 100644 docs/ares_tlsa_usage_t.3 diff --git a/docs/Makefile.inc b/docs/Makefile.inc index 74398549..1a68c790 100644 --- a/docs/Makefile.inc +++ b/docs/Makefile.inc @@ -4,6 +4,67 @@ MANPAGES = ares_cancel.3 \ ares_create_query.3 \ ares_destroy.3 \ ares_destroy_options.3 \ + ares_dns_class_fromstr.3 \ + ares_dns_class_t.3 \ + ares_dns_class_tostr.3 \ + ares_dns_datatype_t.3 \ + ares_dns_flags_t.3 \ + ares_dns_mapping.3 \ + ares_dns_opcode_tostr.3 \ + ares_dns_opt_datatype_t.3 \ + ares_dns_opt_get_datatype.3 \ + ares_dns_opt_get_name.3 \ + ares_dns_opcode_t.3 \ + ares_dns_parse.3 \ + ares_dns_rcode_t.3 \ + ares_dns_rcode_tostr.3 \ + ares_dns_record.3 \ + ares_dns_record_create.3 \ + ares_dns_record_get_flags.3 \ + ares_dns_record_get_id.3 \ + ares_dns_record_get_opcode.3 \ + ares_dns_record_get_rcode.3 \ + ares_dns_record_destroy.3 \ + ares_dns_record_query_add.3 \ + ares_dns_record_query_cnt.3 \ + ares_dns_record_query_get.3 \ + ares_dns_record_rr_add.3 \ + ares_dns_record_rr_cnt.3 \ + ares_dns_record_rr_del.3 \ + ares_dns_record_rr_get.3 \ + ares_dns_rec_type_fromstr.3 \ + ares_dns_rec_type_t.3 \ + ares_dns_rr.3 \ + ares_dns_rr_get_addr.3 \ + ares_dns_rr_get_addr6.3 \ + ares_dns_rr_get_bin.3 \ + ares_dns_rr_get_class.3 \ + ares_dns_rr_get_keys.3 \ + ares_dns_rr_get_name.3 \ + ares_dns_rr_get_opt.3 \ + ares_dns_rr_get_opt_byid.3 \ + ares_dns_rr_get_opt_cnt.3 \ + ares_dns_rr_get_str.3 \ + ares_dns_rr_get_type.3 \ + ares_dns_rr_get_ttl.3 \ + ares_dns_rr_get_u16.3 \ + ares_dns_rr_get_u32.3 \ + ares_dns_rr_get_u8.3 \ + ares_dns_rr_key_datatype.3 \ + ares_dns_rr_key_t.3 \ + ares_dns_rr_key_to_rec_type.3 \ + ares_dns_rr_key_tostr.3 \ + ares_dns_rr_set_addr.3 \ + ares_dns_rr_set_addr6.3 \ + ares_dns_rr_set_bin.3 \ + ares_dns_rr_set_opt.3 \ + ares_dns_rr_set_str.3 \ + ares_dns_rr_set_u16.3 \ + ares_dns_rr_set_u32.3 \ + ares_dns_rr_set_u8.3 \ + ares_dns_section_t.3 \ + ares_dns_section_tostr.3 \ + ares_dns_write.3 \ ares_dup.3 \ ares_expand_name.3 \ ares_expand_string.3 \ @@ -29,6 +90,7 @@ MANPAGES = ares_cancel.3 \ ares_library_init_android.3 \ ares_library_initialized.3 \ ares_mkquery.3 \ + ares_opt_param_t.3 \ ares_parse_a_reply.3 \ ares_parse_aaaa_reply.3 \ ares_parse_caa_reply.3 \ @@ -58,5 +120,9 @@ MANPAGES = ares_cancel.3 \ ares_set_socket_functions.3 \ ares_set_sortlist.3 \ ares_strerror.3 \ + ares_svcb_param_t.3 \ ares_timeout.3 \ + ares_tlsa_match_t.3 \ + ares_tlsa_selector_t.3 \ + ares_tlsa_usage_t.3 \ ares_version.3 diff --git a/docs/ares_dns_class_fromstr.3 b/docs/ares_dns_class_fromstr.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_class_fromstr.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_class_t.3 b/docs/ares_dns_class_t.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_class_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_class_tostr.3 b/docs/ares_dns_class_tostr.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_class_tostr.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_datatype_t.3 b/docs/ares_dns_datatype_t.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_datatype_t.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_flags_t.3 b/docs/ares_dns_flags_t.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_flags_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_mapping.3 b/docs/ares_dns_mapping.3 new file mode 100644 index 00000000..4879b1b1 --- /dev/null +++ b/docs/ares_dns_mapping.3 @@ -0,0 +1,296 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.\" +.TH ARES_DNS_MAPPINGS 3 "12 November 2023" +.SH NAME +Helper functions for converting dns record identifiers to and from their +respective types, as well identifying datatypes for various records. +.SH SYNOPSIS +.nf +#include + +const char *ares_dns_rec_type_tostr(ares_dns_rec_type_t type); + +const char *ares_dns_class_tostr(ares_dns_class_t qclass); + +const char *ares_dns_opcode_tostr(ares_dns_opcode_t opcode); + +const char *ares_dns_rr_key_tostr(ares_dns_rr_key_t key); + +const char *ares_dns_section_tostr(ares_dns_section_t section); + +const char *ares_dns_rcode_tostr(ares_dns_rcode_t rcode); + +ares_bool_t ares_dns_class_fromstr(ares_dns_class_t *qclass, const char *str); + +ares_bool_t ares_dns_rec_type_fromstr(ares_dns_rec_type_t *qtype, + const char *str); + +const ares_dns_rr_key_t *ares_dns_rr_get_keys(ares_dns_rec_type_t type, + size_t *cnt); + +ares_dns_datatype_t ares_dns_rr_key_datatype(ares_dns_rr_key_t key); + +ares_dns_rec_type_t ares_dns_rr_key_to_rec_type(ares_dns_rr_key_t key); + +ares_dns_opt_datatype_t ares_dns_opt_get_datatype(ares_dns_rr_key_t key, + unsigned short opt); + +const char *ares_dns_opt_get_name(ares_dns_rr_key_t key, unsigned short opt); + +.fi +.SH ENUMERATIONS +.B ares_dns_datatype_t - +Data types associated with \fIares_dns_rr_key_t\fP: +.RS 4 +.B ARES_DATATYPE_INADDR +- IPv4 address as \fIstruct in_addr *\fP. Use \fIares_dns_rr_set_addr(3)\fP to +set and \fIares_dns_rr_get_addr(3)\fP to get. +.br +.B ARES_DATATYPE_INADDR6 +- IPv6 address as \fIstruct ares_in6_addr *\fP. Use \fIares_dns_rr_set_addr6(3)\fP to +set and \fIares_dns_rr_get_addr6(3)\fP to get. +.br +.B ARES_DATATYPE_U8 +- 8bit unsigned integer. Use \fIares_dns_rr_set_u8(3)\fP to +set and \fIares_dns_rr_get_u8(3)\fP to get. +.br +.B ARES_DATATYPE_U16 +- 16bit unsigned integer. Use \fIares_dns_rr_set_u16(3)\fP to +set and \fIares_dns_rr_get_u16(3)\fP to get. +.br +.B ARES_DATATYPE_U32 +- 32bit unsigned integer. Use \fIares_dns_rr_set_u32(3)\fP to +set and \fIares_dns_rr_get_u32(3)\fP to get. +.br +.B ARES_DATATYPE_NAME +- Null-terminated string of a domain name (series of labels). Use \fIares_dns_rr_set_str(3)\fP to +set and \fIares_dns_rr_get_str(3)\fP to get. +.br +.B ARES_DATATYPE_STR +- Null-terminated string. Use \fIares_dns_rr_set_str(3)\fP to +set and \fIares_dns_rr_get_str(3)\fP to get. +.br +.B ARES_DATATYPE_BIN +- Binary Data. Use \fIares_dns_rr_set_bin(3)\fP to +set and \fIares_dns_rr_get_bin(3)\fP to get. +.br +.B ARES_DATATYPE_BINP +- Officially defined as binary data, but likely printable. Guaranteed to have +a NULL terminator for convenience (not included in length). Use \fIares_dns_rr_set_bin(3)\fP to +set and \fIares_dns_rr_get_bin(3)\fP to get. +.br +.B ARES_DATATYPE_OPT +- Array of options. 16bit identifier, Binary data. Use \fIares_dns_rr_set_opt(3)\fP to +set and \fIares_dns_rr_get_opt(3)\fP to get. +.br +.RE + +.B ares_dns_opt_datatype_t - +Data types associated with \fIARES_DATATYPE_OPT\fP parameters if known as returned +by \fIares_dns_opt_get_datatype(3)\fP: +.RS 4 +.B ARES_OPT_DATATYPE_NONE +- No value allowed for this parameter +.br +.B ARES_OPT_DATATYPE_STR_LIST +- List of strings, each prefixed with a single octet representing the length as +defined by RFC 1035. Can use \fIares_expand_string(3)\fP until buffer is consumed. +.br +.B ARES_OPT_DATATYPE_U8_LIST +- List of 8bit unsigned integers, concatenated +.br +.B ARES_OPT_DATATYPE_U16 +- 16bit unsigned integer in network byte order +.br +.B ARES_OPT_DATATYPE_U16_LIST +- list of 16bit unsigned integers in network byte order, concatenated. +.br +.B ARES_OPT_DATATYPE_U32 +- 32bit unsigned integer in network byte order +.br +.B ARES_OPT_DATATYPE_U32_LIST +- list of 16bit unsigned integers in network byte order, concatenated. +.br +.B ARES_OPT_DATATYPE_INADDR4_LIST +- List of ipv4 addresses in network byte order, concatenated +.br +.B ARES_OPT_DATATYPE_INADDR6_LIST +- List of ipv6 addresses in network byte order, concatenated +.br +.B ARES_OPT_DATATYPE_BIN +- Binary Data +.br +.B ARES_OPT_DATATYPE_NAME +- DNS Domain Name binary format as defined in RFC1035, can use \fIares_expand_name(3)\fP +.br +.RE + +.B ares_svcb_param_t - +SVCB (and HTTPS) RR known parameters as returned by \fIares_dns_opt_get_datatype(3)\fP +with \fIARES_RR_SVCB_PARAMS\fB or \fIARES_RR_HTTPS_PARAMS\fP: +.RS 4 +.B ARES_SVCB_PARAM_MANDATORY +- Mandatory keys in this RR (RFC 9460 Section 8). Dataype: \fIARES_OPT_DATATYPE_U16_LIST\fP +.br +.B ARES_SVCB_PARAM_ALPN +- Additional supported protocols (RFC 9460 Section 7.1). Dataype: \fIARES_OPT_DATATYPE_STR_LIST\fP +.br +.B ARES_SVCB_PARAM_NO_DEFAULT_ALPN +- No support for default protocol (RFC 9460 Section 7.1). Dataype: \fIARES_OPT_DATATYPE_NONE\fP +.br +.B ARES_SVCB_PARAM_PORT. Dataype: \fIARES_OPT_DATATYPE_U16\fP +- Port for alternative endpoint (RFC 9460 Section 7.2) +.br +.B ARES_SVCB_PARAM_IPV4HINT. Dataype: \fIARES_OPT_DATATYPE_INADDR4_LIST\fP +- IPv4 address hints (RFC 9460 Section 7.3) +.br +.B ARES_SVCB_PARAM_ECH +- RESERVED (held for Encrypted ClientHello) +.br +.B ARES_SVCB_PARAM_IPV6HINT. Dataype: \fIARES_OPT_DATATYPE_INADDR6_LIST\fP +.br IPv6 address hints (RFC 9460 Section 7.3) + +.RE + +.B ares_opt_param_t - +OPT RR known parameters as returned by \fIares_dns_opt_get_datatype(3)\fP +with \fIARES_RR_OPT_OPTIONS\fB: +.RS 4 +.B ARES_OPT_PARAM_LLQ +- RFC 8764. Apple's DNS Long-Lived Queries Protocol. Datatype: \fIARES_OPT_DATATYPE_BIN\fP +.br +.B ARES_OPT_PARAM_UL +- http://files.dns-sd.org/draft-sekar-dns-ul.txt: Update Lease. Datatype: \fIARES_OPT_DATATYPE_U32\fP +.br +.B ARES_OPT_PARAM_NSID +- RFC 5001. Name Server Identification. Datatype: \fIARES_OPT_DATATYPE_BIN\fP +.br +.B ARES_OPT_PARAM_DAU +- RFC 6975. DNSSEC Algorithm Understood. Datatype: \fIARES_OPT_DATATYPE_U8_LIST\fP +.br +.B ARES_OPT_PARAM_DHU +- RFC 6975. DS Hash Understood. Datatype: \fIARES_OPT_DATATYPE_U8_LIST\fP +.br +.B ARES_OPT_PARAM_N3U +- RFC 6975. NSEC3 Hash Understood. Datatype: \fIARES_OPT_DATATYPE_U8_LIST\fP +.br +.B ARES_OPT_PARAM_EDNS_CLIENT_SUBNET +- RFC 7871. Client Subnet. Datatype: \fIARES_OPT_DATATYPE_BIN\fP +.br +.B ARES_OPT_PARAM_EDNS_EXPIRE +- RFC 7314. Expire Timer. Datatype: \fIARES_OPT_DATATYPE_U32\fP +.br +.B ARES_OPT_PARAM_COOKIE +- RFC 7873. Client and Server Cookies. Datatype: \fIARES_OPT_DATATYPE_BIN\fP +.br +.B ARES_OPT_PARAM_EDNS_TCP_KEEPALIVE +- RFC 7828. TCP Keepalive timeout. Datatype: \fIARES_OPT_DATATYPE_U16\fP +.br +.B ARES_OPT_PARAM_PADDING +- RFC 7830. Padding. Datatype: \fIARES_OPT_DATATYPE_BIN\fP +.br +.B ARES_OPT_PARAM_CHAIN +- RFC 7901. Chain query requests. Datatype: \fIARES_OPT_DATATYPE_NAME\fP +.br +.B ARES_OPT_PARAM_EDNS_KEY_TAG +- RFC 8145. Signaling Trust Anchor Knowledge in DNSSEC. Datatype: \fIARES_OPT_DATATYPE_U16_LIST\fP +.br +.B ARES_OPT_PARAM_EXTENDED_DNS_ERROR +- RFC 8914. Extended ERROR code and message. Datatype: \fIARES_OPT_DATATYPE_BIN\fP +.br +.RE + +.SH DESCRIPTION +The \fIares_dns_rec_type_tostr(3)\fP function outputs a human readable DNS record +type from its numeric form passed in +.IR type . + +The \fIares_dns_class_tostr(3)\fP function outputs a human readable DNS class +from its numeric form passed in +.IR qclass . + +The \fIares_dns_opcode_tostr(3)\fP function outputs a human readable DNS opcode +from its numeric form in +.IR opcode . + +The \fIares_dns_rr_key_tostr(3)\fP function outputs a human readable DNS Resource +Record parameter name from its numeric form in +.IR key . + +The \fIares_dns_section_tostr(3)\fP function outputs a human readable DNS +message section from its numeric form in +.IR section . + +The \fIares_dns_rcode_tostr(3)\fP function outputs a human readable DNS +response code from its numeric form in +.IR rcode . + +The \fIares_dns_class_fromstr(3)\fP function outputs the DNS class in numeric +from from its string representation in +.IR str . +The result is stored into the variable pointed to by +.IR qclass . + +The \fIares_dns_rec_type_fromstr(3)\fP function outputs the DNS record type in +numeric from from its string representation in +.IR str . +The result is stored into the variable pointed to by +.IR qtype . + +The \fIares_dns_rr_get_keys(3)\fP function retrieves a list of parameters that +may be set or retrieved for the provided +.IR type . +The count of returned keys is stored into the variable pointed to by +.IR cnt . + +The \fIares_dns_rr_key_datatype(3)\fP function retrieves the associated datatype +for an RR parameter specified by +.IR key . + +The \fIares_dns_rr_key_to_rec_type(3)\fP function dereferences the provided RR +parameter specified by +.IR key +to the DNS Record Type it belongs. + +The \fIares_dns_opt_get_datatype(3)\fP function is used in association with +\fIares_dns_rr_set_opt(3)\fP and \fIares_dns_rr_get_opt(3)\fP to retrieve the +datatype of an option record contained within an RR as specified in +.IR key +if it is known. The raw option record identifier is provided by +.IR opt . + +The \fIares_dns_opt_get_name(3)\fP function is used in association with +\fIares_dns_rr_set_opt(3)\fP and \fIares_dns_rr_get_opt(3)\fP to retrieve human +readable parameter name of an option record contained within an RR as specified +in +.IR key +if it is known. The raw option record identifier is provided by +.IR opt . + +.SH RETURN VALUES +\fIares_dns_rec_type_tostr(3)\fP, \fIares_dns_class_tostr(3)\fP, +\fIares_dns_opcode_tostr(3)\fP, \fIares_dns_rr_key_tostr(3)\fP, +\fIares_dns_section_tostr(3)\fP, \fIares_dns_rcode_tostr(3)\fP, and +\fIares_dns_opt_get_name(3)\fP all return a human printable ASCII string, or +NULL on error. + +\fIares_dns_class_fromstr(3)\fP and \fIares_dns_rec_type_fromstr(3)\fP return +.B ARES_TRUE +on successful conversion, otherwise +.B ARES_FALSE. + +\fIares_dns_rr_get_keys(3)\fP returns an array of keys or NULL on failure. + +\fIares_dns_rr_key_datatype(3)\fP, \fIares_dns_rr_key_to_rec_type(3)\fP, and +\fIares_dns_opt_get_datatype(3)\fP return their respective integer values, or +0 on failure. + +.SH AVAILABILITY +These functions were first introduced in c-ares version 1.22.0. +.SH SEE ALSO +.BR ares_dns_record (3), +.BR ares_dns_rr (3), +.BR ares_init (3) +.SH AUTHOR +Copyright (C) 2023 The c-ares project and its members. diff --git a/docs/ares_dns_opcode_t.3 b/docs/ares_dns_opcode_t.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_opcode_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_opcode_tostr.3 b/docs/ares_dns_opcode_tostr.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_opcode_tostr.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_opt_datatype_t.3 b/docs/ares_dns_opt_datatype_t.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_opt_datatype_t.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_opt_get_datatype.3 b/docs/ares_dns_opt_get_datatype.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_opt_get_datatype.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_opt_get_name.3 b/docs/ares_dns_opt_get_name.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_opt_get_name.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_parse.3 b/docs/ares_dns_parse.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_parse.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_rcode_t.3 b/docs/ares_dns_rcode_t.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_rcode_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_rcode_tostr.3 b/docs/ares_dns_rcode_tostr.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_rcode_tostr.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_rec_type_fromstr.3 b/docs/ares_dns_rec_type_fromstr.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_rec_type_fromstr.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_rec_type_t.3 b/docs/ares_dns_rec_type_t.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_rec_type_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_rec_type_tostr.3 b/docs/ares_dns_rec_type_tostr.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_rec_type_tostr.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_record.3 b/docs/ares_dns_record.3 new file mode 100644 index 00000000..b2930505 --- /dev/null +++ b/docs/ares_dns_record.3 @@ -0,0 +1,375 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.\" +.TH ARES_DNS_RECORD 3 "12 November 2023" +.SH NAME +DNS Record parsing, writing, creating and destroying functions. +.SH SYNOPSIS +.nf +#include + +void ares_dns_record_destroy(ares_dns_record_t *dnsrec); + +ares_status_t ares_dns_parse(const unsigned char *buf, + size_t buf_len, unsigned int flags, + ares_dns_record_t **dnsrec); + +ares_status_t ares_dns_write(ares_dns_record_t *dnsrec, + unsigned char **buf, size_t *buf_len); + +ares_status_t ares_dns_record_create(ares_dns_record_t **dnsrec, + unsigned short id, + unsigned short flags, + ares_dns_opcode_t opcode, + ares_dns_rcode_t rcode); + +unsigned short ares_dns_record_get_id(const ares_dns_record_t *dnsrec); + +unsigned short ares_dns_record_get_flags(const ares_dns_record_t *dnsrec); + +ares_dns_opcode_t ares_dns_record_get_opcode(const ares_dns_record_t *dnsrec); + +ares_dns_rcode_t ares_dns_record_get_rcode(const ares_dns_record_t *dnsrec); + +ares_status_t ares_dns_record_query_add(ares_dns_record_t *dnsrec, + const char *name, + ares_dns_rec_type_t qtype, + ares_dns_class_t qclass); + +size_t ares_dns_record_query_cnt(const ares_dns_record_t *dnsrec); + +ares_status_t ares_dns_record_query_get(const ares_dns_record_t *dnsrec, + size_t idx, const char **name, + ares_dns_rec_type_t *qtype, + ares_dns_class_t *qclass); + +.fi +.SH ENUMERATIONS + +.B ares_dns_rec_type_t - +DNS Record types handled by c-ares. Some record types may only be valid +on requests, and some may only be valid on responses: +.RS 4 +.B ARES_REC_TYPE_A +- Host address +.br +.B ARES_REC_TYPE_NS +- Authoritative server +.br +.B ARES_REC_TYPE_CNAME +- Canonical name +.br +.B ARES_REC_TYPE_SOA +- Start of authority zone +.br +.B ARES_REC_TYPE_PTR +- Domain name pointer +.br +.B ARES_REC_TYPE_HINFO +- Host information +.br +.B ARES_REC_TYPE_MX +- Mail routing information +.br +.B ARES_REC_TYPE_TXT +- Text strings +.br +.B ARES_REC_TYPE_AAAA +- RFC 3596. Ip6 Address +.br +.B ARES_REC_TYPE_SRV +- RFC 2782. Server Selection +.br +.B ARES_REC_TYPE_NAPTR +- RFC 3403. Naming Authority Pointer +.br +.B ARES_REC_TYPE_OPT +- RFC 6891. EDNS0 option (meta-RR). Psuedo Record. +.br +.B ARES_REC_TYPE_TLSA +- RFC 6698. DNS-Based Authentication of Named Entities (DANE) Transport Layer Security (TLS) Protocol: TLSA +.br +.B ARES_REC_TYPE_SVCB +- RFC 9460. General Purpose Service Binding +.br +.B ARES_REC_TYPE_HTTPS - +- RFC 9460. Service Binding type for use with HTTPS +.br +.B ARES_REC_TYPE_ANY +- Wildcard match. Not response RR +.br +.B ARES_REC_TYPE_URI +- RFC 7553. Uniform Resource Identifier +.br +.B ARES_REC_TYPE_CAA +- RFC 6844. Certification Authority Authorization +.br +.B ARES_REC_TYPE_RAW_RR +- Used as an indicator that the RR record is not parsed, but provided in wire +format +.br +.RE + +.B ares_dns_class_t - +DNS Classes for requests and responses: +.RS 4 +.B ARES_CLASS_IN +- Internet +.br +.B ARES_CLASS_CHAOS +- CHAOS +.br +.B ARES_CLASS_HESOID +- Hesoid [Dyer 87] +.br +.B ARES_CLASS_NONE +- RFC 2136 +.br +.B ARES_CLASS_ANY +- Any class (requests only) +.br +.RE + +.B ares_dns_opcode_t - +DNS Header Opcodes: +.RS 4 +.B ARES_OPCODE_QUERY +- Standard query +.br +.B ARES_OPCODE_IQUERY +- Inverse query. Obsolete +.br +.B ARES_OPCODE_STATUS +- Name server status query +.br +.B ARES_OPCODE_NOTIFY +- Zone change notification (RFC 1996) +.br +.B ARES_OPCODE_UPDATE +- Zone update message (RFC2136) +.br +.RE + +.B ares_dns_flags_t - +DNS Header Flags: +.RS 4 +.B ARES_FLAG_QR +- QR. If set, is a response +.br +.B ARES_FLAG_AA +- Authoritative Answer. If set, is authoritative +.br +.B ARES_FLAG_TC +- Truncation. If set, is truncated response +.br +.B ARES_FLAG_RD +- Recursion Desired. If set, recursion is desired +.br +.B ARES_FLAG_RA +- Recursion Available. If set, server supports recursion +.br +.B ARES_FLAG_AD +- RFC 2065. Authentic Data bit indicates in a response that the data included +has been verified by the server providing it +.br +.B ARES_FLAG_CD +- RFC 2065. Checking Disabled bit indicates in a query that non-verified data +is acceptable to the resolver sending the query +.br +.RE + +.B ares_dns_rcode_t - +DNS Response codes from server: +.RS 4 +.B ARES_RCODE_NOERROR +- Success +.br +.B ARES_RCODE_FORMERR +- Format error. The name server was unable to interpret the query +.br +.B ARES_RCODE_SERVFAIL +- Server Failure. The name server was unable to process this query due to a +problem with the nameserver +.br +.B ARES_RCODE_NXDOMAIN +- Name Error. Meaningful only for responses from an authoritative name server, +this code signifies that the domain name referenced in the query does not exist. +.br +.B ARES_RCODE_NOTIMP +- Not implemented. The name server does not support the requested kind of query +.br +.B ARES_RCODE_REFUSED +- Refused. The name server refuses to perform the speciied operation for policy +reasons. +.br +.B ARES_RCODE_YXDOMAIN +- RFC 2136. Some name that ought not to exist, does exist +.br +.B ARES_RCODE_YXRRSET +- RFC 2136. Some RRset that ought to not exist, does exist +.br +.B ARES_RCODE_NXRRSET +- RFC 2136. Some RRset that ought to exist, does not exist +.br +.B ARES_RCODE_NOTAUTH +- RFC 2136. The server is not authoritative for the zone named in the Zone section. +.br +.B ARES_RCODE_NOTZONE +- RFC 2136. A name used in the Prerequisite or Update Section is not within the +zone denoted by the Zone Section. +.br +.B ARES_RCODE_DSOTYPEI +- RFC 8409. DSO-TYPE Not implemented +.br +.B ARES_RCODE_BADSIG +- RFC 8945. TSIG Signature Failure +.br +.B ARES_RCODE_BADKEY +- RFC 8945. Key not recognized +.br +.B ARES_RCODE_BADTIME +- RFC 8945. Signature out of time window +.br +.B ARES_RCODE_BADMODE +- RFC 2930. Bad TKEY Mode +.br +.B ARES_RCODE_BADNAME +- RFC 2930. Duplicate Key Name +.br +.B ARES_RCODE_BADALG +- RFC 2930. Algorithm not supported +.br +.B ARES_RCODE_BADTRUNC +- RFC 8945. Bad Truncation +.br +.B ARES_RCODE_BADCOOKIE +- RFC 7973. Bad/missing Server Cookie +.br +.RE + + +.SH DESCRIPTION + +The \fIares_dns_record_destroy(3)\fP function destroys the memory associated +with the dns record created by either \fIares_dns_record_create(3)\fP or +\fIares_dns_parse(3)\fP passed in via +.IR dnsrec . + +The \fIares_dns_parse(3)\fP function parses the buffer provided in +.IR buf +with length provided in +.IR buf_len. +The +.IR flags +parameter can be one or more \fIares_dns_parse_flags_t\fP, or zero if no +flags are needed. The resulting dns record data structure is stored into the +variable pointed to by +.IR dnsrec +and must be destroyed using \fIares_dns_record_destroy(3)\fP. + +The \fIares_dns_write(3)\fP function takes a populated DNS record structure in +.IR dnsrec +and writes a wire-format DNS message into the variable pointed to by +.IR buf +and writes the length of the buffer into the variable pointed to by +.IR buf_len. +The buffer must be destroyed using \fIares_free_string(3)\fP. + +The \fIares_dns_record_create(3)\fP function creates an empty DNS record structure +in the variable pointed to by +.IR dnsrec. +The +.IR id +parameter is the DNS message id, however if passing to \fIares_send(3)\fP this +identifier will be overwritten, so should typically be 0. The +.IR flags +parameter is one or more \fIares_dns_flags_t\fP. The opcode is passed in the +.IR opcode +parameter and should typically be \fIARES_OPCODE_QUERY\fP. The response code +is meant mostly for responses and is passed in the +.IR rcode +parameter and is typically \fPARES_RCODE_NOERROR\fP. + + +The \fIares_dns_record_get_id(3)\fP function is used to retrieve the DNS +message id from the DNS record provided in the +.IR dnsrec +parameter. + +The \fIares_dns_record_get_flags(3)\fP function is used to retrieve the DNS +message flags from the DNS record provided in the +.IR dnsrec +parameter. + +The \fIares_dns_record_get_opcode(3)\fP function is used to retrieve the DNS +message flags from the DNS record provided in the +.IR dnsrec +parameter. + +The \fIares_dns_record_get_rcode(3)\fP function is used to retrieve the DNS +message response code from the DNS record provided in the +.IR dnsrec +parameter. + + +The \fIares_dns_record_query_add(3)\fP function is used to add a question to +the DNS record provided in the +.IR dnsrec +parameter. The domain name specified for the question is provided in the +.IR name +parameter, along with the question type in the +.IR qtype +parameter and the question class (typically \fIARES_CLASS_IN\fP) in the +.IR qclass +parameter. + +The \fIares_dns_record_query_cnt(3)\fP function is used to retrieve the number +of DNS questions in the DNS record provided in the +.IR dnsrec +parameter. + +The \fIares_dns_record_query_get(3)\fP function is used to retrieve the details +of a single DNS question in the provided +.IR dnsrec +parameter. The index provided in the +.IR idx +parameter must be less than the value returned from \fIares_dns_record_query_cnt(3)\fP. +The DNS question name will be returned in the variable pointed to by the +.IR name +parameter, this may be provided as NULL if the name is not needed. +The DNS question type will be returned in the variable pointed to by the +.IR qtype +parameter, this may be provided as NULL if the type is not needed. +The DNS question class will be returned in the variable pointed to by the +.IR qclass +parameter, this may be provided as NULL if the class is not needed. + + +.SH RETURN VALUES + +\fIares_dns_parse(3)\fP, \fIares_dns_write(3)\fP, \fIares_dns_record_create(3)\fP, +\fIares_dns_record_query_add(3)\fP, and \fIares_dns_record_query_get(3)\fP all +return an \fIares_status_t\fP error code. +.B ARES_SUCCESS +is returned on success, +.B ARES_ENOMEM +is returned on out of memory, +.B ARES_EFORMERR +is returned on misuse. + +\fIares_dns_record_get_id(3)\fP, \fIares_dns_record_get_flags(3)\fP, +\fIares_dns_record_get_opcode(3)\fP, \fIares_dns_record_get_rcode(3)\fP, and +\fIares_dns_record_query_cnt(3)\fP all returned their prescribed datatype +values and in general can't fail except for misuse cases, in which a 0 may +be returned, however 0 can also be a valid return value for most of these +functions. + + +.SH AVAILABILITY +These functions were first introduced in c-ares version 1.22.0. +.SH SEE ALSO +.BR ares_dns_mapping (3), +.BR ares_dns_rr (3), +.BR ares_free_string (3) +.SH AUTHOR +Copyright (C) 2023 The c-ares project and its members. diff --git a/docs/ares_dns_record_create.3 b/docs/ares_dns_record_create.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_record_create.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_record_destroy.3 b/docs/ares_dns_record_destroy.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_record_destroy.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_record_get_flags.3 b/docs/ares_dns_record_get_flags.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_record_get_flags.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_record_get_id.3 b/docs/ares_dns_record_get_id.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_record_get_id.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_record_get_opcode.3 b/docs/ares_dns_record_get_opcode.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_record_get_opcode.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_record_get_rcode.3 b/docs/ares_dns_record_get_rcode.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_record_get_rcode.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_record_query_add.3 b/docs/ares_dns_record_query_add.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_record_query_add.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_record_query_cnt.3 b/docs/ares_dns_record_query_cnt.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_record_query_cnt.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_record_query_get.3 b/docs/ares_dns_record_query_get.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_record_query_get.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_dns_record_rr_add.3 b/docs/ares_dns_record_rr_add.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_record_rr_add.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_record_rr_cnt.3 b/docs/ares_dns_record_rr_cnt.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_record_rr_cnt.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_record_rr_del.3 b/docs/ares_dns_record_rr_del.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_record_rr_del.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_record_rr_get.3 b/docs/ares_dns_record_rr_get.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_record_rr_get.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr.3 b/docs/ares_dns_rr.3 new file mode 100644 index 00000000..15d933b4 --- /dev/null +++ b/docs/ares_dns_rr.3 @@ -0,0 +1,621 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.\" +.TH ARES_DNS_RR 3 "12 November 2023" +.SH NAME +DNS Resource record creating, reading, and writing functions. +.SH SYNOPSIS +.nf +#include + +size_t ares_dns_record_rr_cnt(const ares_dns_record_t *dnsrec, + ares_dns_section_t sect); + +ares_status_t ares_dns_record_rr_add(ares_dns_rr_t **rr_out, + ares_dns_record_t *dnsrec, + ares_dns_section_t sect, + const char *name, + ares_dns_rec_type_t type, + ares_dns_class_t rclass, + unsigned int ttl); + +ares_dns_rr_t *ares_dns_record_rr_get(ares_dns_record_t *dnsrec, + ares_dns_section_t sect, + size_t idx); + +ares_status_t ares_dns_record_rr_del(ares_dns_record_t *dnsrec, + ares_dns_section_t sect, + size_t idx); + +const char *ares_dns_rr_get_name(const ares_dns_rr_t *rr); + +ares_dns_rec_type_t ares_dns_rr_get_type(const ares_dns_rr_t *rr); + +ares_dns_class_t ares_dns_rr_get_class(const ares_dns_rr_t *rr); + +unsigned int ares_dns_rr_get_ttl(const ares_dns_rr_t *rr); + +ares_status_t ares_dns_rr_set_addr(ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + const struct in_addr *addr); + +ares_status_t ares_dns_rr_set_addr6(ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + const struct ares_in6_addr *addr); + +ares_status_t ares_dns_rr_set_str(ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + const char *val); + +ares_status_t ares_dns_rr_set_u8(ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + unsigned char val); + +ares_status_t ares_dns_rr_set_u16(ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + unsigned short val); + +ares_status_t ares_dns_rr_set_u32(ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + unsigned int val); + +ares_status_t ares_dns_rr_set_bin(ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + const unsigned char *val, + size_t len); + +ares_status_t ares_dns_rr_set_opt(ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + unsigned short opt, + const unsigned char *val, + size_t val_len); + +const struct in_addr *ares_dns_rr_get_addr(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key); + +const struct ares_in6_addr *ares_dns_rr_get_addr6(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key); + +const char *ares_dns_rr_get_str(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key); + +unsigned char ares_dns_rr_get_u8(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key); + +unsigned short ares_dns_rr_get_u16(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key); + +unsigned int ares_dns_rr_get_u32(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key); + +const unsigned char *ares_dns_rr_get_bin(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + size_t *len); + +size_t ares_dns_rr_get_opt_cnt(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key); + +unsigned short ares_dns_rr_get_opt(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + size_t idx, + const unsigned char **val, + size_t *val_len); + +ares_bool_t ares_dns_rr_get_opt_byid(const ares_dns_rr_t *dns_rr, + ares_dns_rr_key_t key, + unsigned short opt, + const unsigned char **val, + size_t *val_len); + +.fi +.SH ENUMERATIONS + +.B ares_dns_section_t - +DNS RR section types: +.RS 4 +.B ARES_SECTION_ANSWER +- Answer section +.br +.B ARES_SECTION_AUTHORITY +- Authority section +.br +.B ARES_SECTION_ADDITIONAL +- Additional Information section +.br +.RE + +.B ares_dns_rr_key_t - +Keys used for handling RR record parameters: +.RS 4 +.B ARES_RR_A_ADDR +- A Record. Address. Datatype: \fIARES_DATATYPE_INADDR\fP +.br +.B ARES_RR_NS_NSDNAME +- NS Record. Name. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_CNAME_CNAME +- CNAME Record. CName. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_SOA_MNAME +- SOA Record. MNAME, Primary Source of Data. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_SOA_RNAME +- SOA Record. RNAME, Mailbox of person responsible. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_SOA_SERIAL +- SOA Record. Serial, version. Datatype: \fIARES_DATATYPE_U32\fP +.br +.B ARES_RR_SOA_REFRESH +- SOA Record. Refresh, zone refersh interval. Datatype: \fIARES_DATATYPE_U32\fP +.br +.B ARES_RR_SOA_RETRY +- SOA Record. Retry, failed refresh retry interval. Datatype: \fIARES_DATATYPE_U32\fP +.br +.B ARES_RR_SOA_EXPIRE +- SOA Record. Expire, upper limit on authority. Datatype: \fIARES_DATATYPE_U32\fP +.br +.B ARES_RR_SOA_MINIMUM +- SOA Record. Minimum, RR TTL. Datatype: \fIARES_DATATYPE_U32\fP +.br +.B ARES_RR_PTR_DNAME +- PTR Record. DNAME, pointer domain. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_HINFO_CPU +- HINFO Record. CPU. Datatype: \fIARES_DATATYPE_STR\fP +.br +.B ARES_RR_HINFO_OS +- HINFO Record. OS. Datatype: \fIARES_DATATYPE_STR\fP +.br +.B ARES_RR_MX_PREFERENCE +- MX Record. Preference. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_MX_EXCHANGE +- MX Record. Exchange, domain. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_TXT_DATA +- TXT Record. Data. Datatype: \fIARES_DATATYPE_BINP\fP +.br +.B ARES_RR_AAAA_ADDR +- AAAA Record. Address. Datatype: \fIARES_DATATYPE_INADDR6\fP +.br +.B ARES_RR_SRV_PRIORITY +- SRV Record. Priority. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_SRV_WEIGHT +- SRV Record. Weight. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_SRV_PORT +- SRV Record. Port. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_SRV_TARGET +- SRV Record. Target domain. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_NAPTR_ORDER +- NAPTR Record. Order. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_NAPTR_PREFERENCE +- NAPTR Record. Preference. Datatype: \fIARES_DATATYPE_U16\fp +.br +.B ARES_RR_NAPTR_FLAGS +- NAPTR Record. Flags. Datatype: \fIARES_DATATYPE_STR\fP +.br +.B ARES_RR_NAPTR_SERVICES +- NAPTR Record. Services. Datatype: \fIARES_DATATYPE_STR\fP +.br +.B ARES_RR_NAPTR_REGEXP +- NAPTR Record. Regexp. Datatype: \fIARES_DATATYPE_STR\fP +.br +.B ARES_RR_NAPTR_REPLACEMENT +- NAPTR Record. Replacement. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_OPT_UDP_SIZE +- OPT Record. UDP Size. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_OPT_VERSION +- OPT Record. Version. Datatype: \fIARES_DATATYPE_U8\fP +.br +.B ARES_RR_OPT_FLAGS +- OPT Record. Flags. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_OPT_OPTIONS +- OPT Record. Options. See \fIares_opt_param_t\fP. Datatype: \fIARES_DATATYPE_OPT\fP +.br +.B ARES_RR_TLSA_CERT_USAGE +- TLSA Record. Certificate Usage. See \fIares_tlsa_usage_t\fP. Datatype: \fIARES_DATATYPE_U8\fP +.br +.B ARES_RR_TLSA_SELECTOR +- TLSA Record. Selector. See \fIares_tlsa_selector_t\fP. Datatype: \fIARES_DATATYPE_U8\fP +.br +.B ARES_RR_TLSA_MATCH +- TLSA Record. Matching Type. See \fIares_tlsa_match_t\fP. Datatype: \fIARES_DATATYPE_U8\fP +.br +.B ARES_RR_TLSA_DATA +- TLSA Record. Certificate Association Data. Datatype: \fIARES_DATATYPE_BIN\fP +.br +.B ARES_RR_SVCB_PRIORITY +- SVCB Record. SvcPriority. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_SVCB_TARGET +- SVCB Record. TargetName. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_SVCB_PARAMS +- SVCB Record. SvcParams. See \fIares_svcb_param_t\fP. Datatype: \fIARES_DATATYPE_OPT\fP +.br +.B ARES_RR_HTTPS_PRIORITY +- HTTPS Record. SvcPriority. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_HTTPS_TARGET +- HTTPS Record. TargetName. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_HTTPS_PARAMS +- HTTPS Record. SvcParams. See \fIares_svcb_param_t\fP. Datatype: \fIARES_DATATYPE_OPT\fP +.br +.B ARES_RR_URI_PRIORITY +- URI Record. Priority. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_URI_WEIGHT +- URI Record. Weight. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_URI_TARGET +- URI Record. Target domain. Datatype: \fIARES_DATATYPE_NAME\fP +.br +.B ARES_RR_CAA_CRITICAL +- CAA Record. Critical flag. Datatype: \fIARES_DATATYPE_U8\fP +.br +.B ARES_RR_CAA_TAG +- CAA Record. Tag/Property. Datatype: \fIARES_DATATYPE_STR\fP +.br +.B ARES_RR_CAA_VALUE +- CAA Record. Value. Datatype: \fIARES_DATATYPE_BINP\fP +.br +.B ARES_RR_RAW_RR_TYPE +- RAW Record. RR Type. Datatype: \fIARES_DATATYPE_U16\fP +.br +.B ARES_RR_RAW_RR_DATA +- RAW Record. RR Data. Datatype: \fIARES_DATATYPE_BIN\fP +.br +.RE + +.B ares_tlsa_usage_t - +TLSA Record \fIARES_RR_TLSA_CERT_USAGE\fP known values +.RS 4 +.B ARES_TLSA_USAGE_CA +- Certificate Usage 0. CA Constraint +.br +.B ARES_TLSA_USAGE_SERVICE +- Certificate Usage 1. Service Certificate Constraint +.br +.B ARES_TLSA_USAGE_TRUSTANCHOR +- Certificate Usage 2. Trust Anchor Assertation +.br +.B ARES_TLSA_USAGE_DOMAIN +- Certificate Usage 3. Domain-issued certificate +.br +.RE + +.B ares_tlsa_selector_t - +TLSA Record \fIARES_RR_TLSA_SELECTOR\fP known values: +.RS 4 +.B ARES_TLSA_SELECTOR_FULL +- Full Certificate +.br +.B ARES_TLSA_SELECTOR_SUBJPUBKEYINFO +- DER-encoded SubjectPublicKeyInfo +.br +.RE + +.B ares_tlsa_match_t - +TLSA Record \fIARES_RR_TLSA_MATCH\fP known values: +.RS 4 +.B ARES_TLSA_MATCH_EXACT +- Exact match +.br +.B ARES_TLSA_MATCH_SHA256 +- Sha256 match +.br +.B ARES_TLSA_MATCH_SHA512 +- Sha512 match +.br +.RE + + +.SH DESCRIPTION + +The \fIares_dns_record_rr_cnt(3)\fP function returns the number of resource +records in the DNS record provided by the +.IR dnsrec +parameter for the section provided in the +.IR sect +parameter. + +The \fIares_dns_record_rr_add(3)\fP function adds a new resource record entry +the the DNS record provided by the +.IR dnsrec +parameter. The resulting resource record is stored into the variable pointed to by +.IR rr_out. +The DNS section the resource record belongs to is specified by the +.IR sect +parameter. The domain name associated with the resource record is specified by the +.IR name +parameter, which can not be NULL but may be an empty string, or ".". The resource +record type is specified in the +.IR type +parameter, along withe the DNS record class in the +.IR rclass +parameter, and the Time To Live (TTL) in the +.IR ttl +parameter. + + +The \fIares_dns_record_rr_get(3)\fP function is used to retrieve the resource +record pointer from the DNS record provided in the +.IR dnsrec +parameter, for the resource record section provided in the +.IR sect +parameter, for the specified index in the +.IR idx +parameter. The index must be less than \fIares_dns_record_rr_cnt(3)\fP. + + +The \fIares_dns_record_rr_del(3)\fP is used to delete a resource record from +the DNS record specified in the +.IR dnsrec +parameter. Its primary use is to remove a \fIARES_REC_TYPE_OPT\fP record when +needing to retry a query without EDNS support. The DNS RR section is specified +via the +.IR sect +parameter, and the index to remove is specified in the +.IR idx +parameter. The index must be less than \fIares_dns_record_rr_cnt(3)\fP. + + +The \fIares_dns_rr_get_name(3)\fP function is used to retrieve the resource +record domain name from the Resource Record pointer provided in the +.IR rr +parameter. + +The \fIares_dns_rr_get_type(3)\fP function is used to retrieve the resource +record type from the Resource Record pointer provided in the +.IR rr +parameter. + +The \fIares_dns_rr_get_class(3)\fP function is used to retrieve the resource +record class from the Resource Record pointer provided in the +.IR rr +parameter. + +The \fIares_dns_rr_get_ttl(3)\fP function is used to retrieve the resource +record class Time to Live (TTL) from the Resource Record pointer provided in the +.IR rr +parameter. + +The \fIares_dns_rr_set_addr(3)\fP function is used to set an IPv4 address for the +associated resource record key/parameter when the datatype is \fIARES_DATATYPE_INADDR\fP. +The resource record to be modified is provided in the +.IR dns_rr +parameter, the key/parameter is provided in the +.IR key +parameter, and the value is provided in the +.IR addr +parameter. + +The \fIares_dns_rr_set_addr6(3)\fP function is used to set an IPv6 address for the +associated resource record key/parameter when the datatype is \fIARES_DATATYPE_INADDR6\fP. +The resource record to be modified is provided in the +.IR dns_rr +parameter, the key/parameter is provided in the +.IR key +parameter, and the value is provided in the +.IR addr +parameter. + +The \fIares_dns_rr_set_str(3)\fP function is used to set a string for the +associated resource record key/parameter when the datatype is \fIARES_DATATYPE_STR\fP +or \fIARES_DATATYPE_NAME\fP. Most strings are limited to 255 bytes, +however some records, such as a TXT record may allow longer as they are output +as multiple strings. The resource record to be modified is +provided in the +.IR dns_rr +parameter, the key/parameter is provided in the +.IR key +parameter, and the value is provided in the +.IR val +parameter. + +The \fIares_dns_rr_set_u8(3)\fP function is used to set an 8bit unsigned value for the +associated resource record key/parameter when the datatype is \fIARES_DATATYPE_U8\fP. +The resource record to be modified is provided in the +.IR dns_rr +parameter, the key/parameter is provided in the +.IR key +parameter, and the value is provided in the +.IR val +parameter. + +The \fIares_dns_rr_set_u16(3)\fP function is used to set an 16bit unsigned value for the +associated resource record key/parameter when the datatype is \fIARES_DATATYPE_U16\fP. +The resource record to be modified is provided in the +.IR dns_rr +parameter, the key/parameter is provided in the +.IR key +parameter, and the value is provided in the +.IR val +parameter. + +The \fIares_dns_rr_set_u32(3)\fP function is used to set an 32bit unsigned value for the +associated resource record key/parameter when the datatype is \fIARES_DATATYPE_U32\fP. +The resource record to be modified is provided in the +.IR dns_rr +parameter, the key/parameter is provided in the +.IR key +parameter, and the value is provided in the +.IR val +parameter. + +The \fIares_dns_rr_set_bin(3)\fP function is used to set an binary value for the +associated resource record key/parameter when the datatype is \fIARES_DATATYPE_BIN\fP +or \fIARES_DATATYPE_BINP\fP. +The resource record to be modified is provided in the +.IR dns_rr +parameter, the key/parameter is provided in the +.IR key +parameter, and the value is provided in the +.IR val +parameter. And the associated value length is provided in the +.IR len +parameter. + +The \fIares_dns_rr_set_opt(3)\fP function is used to set option/parameter keys and +values for the resource record when the datatype if \fIARES_DATATYPE_OPT\fP. The +resource record to be modified is provided in the +.IR dns_rr +parameter. They key/parameter is provided in the +.IR key +parameter. The option/parameter value specific to the resource record is provided +in the +.IR opt +parameter, and this is left to the user to determine the appropriate value to +use. Some known values may be provided by \fIares_svcb_param_t\fP and \fIares_opt_param_t\fP +enumerations. The value for the option is always provided in binary form in +.IR val +with length provided in +.IR val_len. + +The \fIares_dns_rr_get_addr(3)\fP function is used to retrieve the IPv4 address +from the resource record when the datatype is \fIARES_DATATYPE_INADDR\fP. The +resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key +parameter. + +The \fIares_dns_rr_get_addr6(3)\fP function is used to retrieve the IPv6 address +from the resource record when the datatype is \fIARES_DATATYPE_INADDR6\fP. The +resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key +parameter. + +The \fIares_dns_rr_get_str(3)\fP function is used to retrieve a string +from the resource record when the datatype is \fIARES_DATATYPE_STR\fP or +\fIARES_DATATYPE_NAME\fP. The resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key +parameter. + +The \fIares_dns_rr_get_u8(3)\fP function is used to retrieve an 8bit integer +from the resource record when the datatype is \fIARES_DATATYPE_U8\fP. +The resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key +parameter. + +The \fIares_dns_rr_get_u16(3)\fP function is used to retrieve a 16bit integer +from the resource record when the datatype is \fIARES_DATATYPE_U16\fP. +The resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key +parameter. + +The \fIares_dns_rr_get_u32(3)\fP function is used to retrieve a 32bit integer +from the resource record when the datatype is \fIARES_DATATYPE_U32\fP. +The resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key +parameter. + +The \fIares_dns_rr_get_bin(3)\fP function is used to retrieve binary data +from the resource record when the datatype is \fIARES_DATATYPE_BIN\fP or +\fIARES_DATATYPE_BINP\fP. +The resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key +parameter, and length is stored into the variable pointed to by +.IR len. + +The \fIares_dns_rr_get_opt_cnt(3)\fP function is used to retrieve the count +of options/parameters associated with the resource record when the datatype +is \fIARES_DATATYPE_OPT\fP. +The resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key. + +The \fIares_dns_rr_get_opt(3)\fP function is used to retrieve binary option data +from the resource record when the datatype is \fIARES_DATATYPE_OPT\fP for the +specified index. +The resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key +parameter, the index to retrieve the option data from is provided in the +.IR idx +parameter. The value is stored into the variable pointed to by +.IR val +and length is stored into the variable pointed to by +.IR val_len. + +The \fIares_dns_rr_get_opt_byid(3)\fP function is used to retrieve binary option data +from the resource record when the datatype is \fIARES_DATATYPE_OPT\fP for the +specified option identifier, if it exists. +The resource record is provided in the +.IR dns_rr +parameter and the key/parameter to retrieve is provided in the +.IR key +parameter, the identifier to retrieve the option data from is provided in the +.IR opt +parameter. The value is stored into the variable pointed to by +.IR val +and length is stored into the variable pointed to by +.IR val_len. + + +.SH RETURN VALUES + +\fIares_dns_record_rr_cnt(3)\fP and \fIares_dns_rr_get_opt_cnt(3)\fP return the +respective counts. + +\fIares_dns_record_rr_add(3)\fP, \fIares_dns_record_rr_del(3)\fP, +\fIares_dns_rr_set_addr(3)\fP, \fIares_dns_rr_set_addr6(3)\fP, +\fIares_dns_rr_set_str(3)\fP, \fIares_dns_rr_set_u8(3)\fP, +\fIares_dns_rr_set_u16(3)\fP, \fIares_dns_rr_set_u32(3)\fP, +\fIares_dns_rr_set_bin(3)\fP, and \fIares_dns_rr_set_opt(3)\fP all +return an \fIares_status_t\fP error code. +.B ARES_SUCCESS +is returned on success, +.B ARES_ENOMEM +is returned on out of memory, +.B ARES_EFORMERR +is returned on misuse. + + +\fIares_dns_rr_get_name(3)\fP, \fIares_dns_rr_get_type(3)\fP, +\fIares_dns_rr_get_class(3)\fP, \fIares_dns_rr_get_ttl(3)\fP, +\fIares_dns_rr_get_addr(3)\fP, \fIares_dns_rr_get_addr6(3)\fP, +\fIares_dns_rr_get_str(3)\fP, \fIares_dns_rr_get_u8(3)\fP, +\fIares_dns_rr_get_u16(3)\fP, \fIares_dns_rr_get_u32(3)\fP, +\fIares_dns_rr_get_bin(3)\fP, \fIares_dns_rr_get_opt(3)\fP all return their +prescribed datatype values and in general can't fail except for misuse cases, +in which a 0 (or NULL) may be returned, however 0 can also be a valid return +value for most of these functions. + +\fIares_dns_record_rr_get(3)\fP will return the requested resource record +pointer or NULL on failure (misuse). + +\fIares_dns_rr_get_opt_by_id(3)\fP will return ARES_TRUE if the option was +found, otherwise ARES_FALSE if not found (or misuse). + +.SH AVAILABILITY +These functions were first introduced in c-ares version 1.22.0. +.SH SEE ALSO +.BR ares_dns_mapping (3), +.BR ares_dns_record (3), +.BR ares_free_string (3) +.SH AUTHOR +Copyright (C) 2023 The c-ares project and its members. diff --git a/docs/ares_dns_rr_get_addr.3 b/docs/ares_dns_rr_get_addr.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_addr.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_addr6.3 b/docs/ares_dns_rr_get_addr6.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_addr6.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_bin.3 b/docs/ares_dns_rr_get_bin.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_bin.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_class.3 b/docs/ares_dns_rr_get_class.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_class.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_keys.3 b/docs/ares_dns_rr_get_keys.3 new file mode 100644 index 00000000..a7758577 --- /dev/null +++ b/docs/ares_dns_rr_get_keys.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_rr_get_name.3 b/docs/ares_dns_rr_get_name.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_name.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_opt.3 b/docs/ares_dns_rr_get_opt.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_opt.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_opt_byid.3 b/docs/ares_dns_rr_get_opt_byid.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_opt_byid.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_opt_cnt.3 b/docs/ares_dns_rr_get_opt_cnt.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_opt_cnt.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_str.3 b/docs/ares_dns_rr_get_str.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_str.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_ttl.3 b/docs/ares_dns_rr_get_ttl.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_ttl.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_type.3 b/docs/ares_dns_rr_get_type.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_type.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_u16.3 b/docs/ares_dns_rr_get_u16.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_u16.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_u32.3 b/docs/ares_dns_rr_get_u32.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_u32.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_get_u8.3 b/docs/ares_dns_rr_get_u8.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_get_u8.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_key_datatype.3 b/docs/ares_dns_rr_key_datatype.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_rr_key_datatype.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_rr_key_t.3 b/docs/ares_dns_rr_key_t.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_key_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_key_to_rec_type.3 b/docs/ares_dns_rr_key_to_rec_type.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_rr_key_to_rec_type.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_rr_key_tostr.3 b/docs/ares_dns_rr_key_tostr.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_rr_key_tostr.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_rr_set_addr.3 b/docs/ares_dns_rr_set_addr.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_set_addr.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_set_addr6.3 b/docs/ares_dns_rr_set_addr6.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_set_addr6.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_set_bin.3 b/docs/ares_dns_rr_set_bin.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_set_bin.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_set_opt.3 b/docs/ares_dns_rr_set_opt.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_set_opt.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_set_str.3 b/docs/ares_dns_rr_set_str.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_set_str.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_set_u16.3 b/docs/ares_dns_rr_set_u16.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_set_u16.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_set_u32.3 b/docs/ares_dns_rr_set_u32.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_set_u32.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_rr_set_u8.3 b/docs/ares_dns_rr_set_u8.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_rr_set_u8.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_section_t.3 b/docs/ares_dns_section_t.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_dns_section_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_dns_section_tostr.3 b/docs/ares_dns_section_tostr.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_dns_section_tostr.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_dns_write.3 b/docs/ares_dns_write.3 new file mode 100644 index 00000000..4acc581d --- /dev/null +++ b/docs/ares_dns_write.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_record.3 diff --git a/docs/ares_opt_param_t.3 b/docs/ares_opt_param_t.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_opt_param_t.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_reinit.3 b/docs/ares_reinit.3 index 9fb8127e..1b99fec7 100644 --- a/docs/ares_reinit.3 +++ b/docs/ares_reinit.3 @@ -37,6 +37,8 @@ A configuration file could not be read. .B ARES_ENOMEM The process's available memory was exhausted. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.22.0. .SH SEE ALSO .BR ares_init (3), .BR ares_init_options (3), diff --git a/docs/ares_svcb_param_t.3 b/docs/ares_svcb_param_t.3 new file mode 100644 index 00000000..4587b9a5 --- /dev/null +++ b/docs/ares_svcb_param_t.3 @@ -0,0 +1,4 @@ +.\" +.\" Copyright (C) Daniel Stenberg +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_mapping.3 diff --git a/docs/ares_tlsa_match_t.3 b/docs/ares_tlsa_match_t.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_tlsa_match_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_tlsa_selector_t.3 b/docs/ares_tlsa_selector_t.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_tlsa_selector_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/docs/ares_tlsa_usage_t.3 b/docs/ares_tlsa_usage_t.3 new file mode 100644 index 00000000..b93e4cd4 --- /dev/null +++ b/docs/ares_tlsa_usage_t.3 @@ -0,0 +1,3 @@ +.\" Copyright (C) 2023 The c-ares project and its contributors. +.\" SPDX-License-Identifier: MIT +.so man3/ares_dns_rr.3 diff --git a/include/ares_dns_record.h b/include/ares_dns_record.h index 7a74ef17..00f85761 100644 --- a/include/ares_dns_record.h +++ b/include/ares_dns_record.h @@ -490,6 +490,32 @@ CARES_EXTERN const char *ares_dns_opt_get_name(ares_dns_rr_key_t key, unsigned short opt); +/*! Retrieve a list of Resource Record keys that can be set or retrieved for + * the Resource record type. + * + * \param[in] type Record Type + * \param[out] cnt Number of keys returned + * \return array of keys associated with Resource Record + */ +CARES_EXTERN const ares_dns_rr_key_t * + ares_dns_rr_get_keys(ares_dns_rec_type_t type, size_t *cnt); + +/*! Retrieve the datatype associated with a Resource Record key. + * + * \param[in] key Resource Record Key + * \return datatype + */ +CARES_EXTERN ares_dns_datatype_t + ares_dns_rr_key_datatype(ares_dns_rr_key_t key); + +/*! Retrieve the DNS Resource Record type associated with a Resource Record key. + * + * \param[in] key Resource Record Key + * \return DNS Resource Record Type + */ +CARES_EXTERN ares_dns_rec_type_t + ares_dns_rr_key_to_rec_type(ares_dns_rr_key_t key); + /*! Opaque data type representing a DNS RR (Resource Record) */ struct ares_dns_rr; @@ -650,31 +676,6 @@ CARES_EXTERN ares_status_t ares_dns_record_rr_del(ares_dns_record_t *dnsrec, ares_dns_section_t sect, size_t idx); -/*! Retrieve a list of Resource Record keys that can be set or retrieved for - * the Resource record type. - * - * \param[in] type Record Type - * \param[out] cnt Number of keys returned - * \return array of keys associated with Resource Record - */ -CARES_EXTERN const ares_dns_rr_key_t * - ares_dns_rr_get_keys(ares_dns_rec_type_t type, size_t *cnt); - -/*! Retrieve the datatype associated with a Resource Record key. - * - * \param[in] key Resource Record Key - * \return datatype - */ -CARES_EXTERN ares_dns_datatype_t - ares_dns_rr_key_datatype(ares_dns_rr_key_t key); - -/*! Retrieve the DNS Resource Record type associated with a Resource Record key. - * - * \param[in] key Resource Record Key - * \return DNS Resource Record Type - */ -CARES_EXTERN ares_dns_rec_type_t - ares_dns_rr_key_to_rec_type(ares_dns_rr_key_t key); /*! Retrieve the resource record Name/Hostname *