ARES_DNS_RECORD(3)

🦋 ARES_DNS_RECORD(3) — from the Library Functions Manual 🦋

okay so bestie, this is the ares_dns_record(3) page and it is literally the whole DNS-record squad: parsing, writing, creating, destroying, and all the enum lore that comes with it. We’re doing this in two parts, and this part is the NAME ✨ SYNOPSIS ✨ ENUMERATIONS serve. Buckle up. 💅

---

🌸 NAME 🌸

The whole iconic crew on this page is: ares_dns_class_t, ares_dns_flags_t, ares_dns_opcode_t, ares_dns_parse, ares_dns_rcode_t, ares_dns_record_create, ares_dns_record_destroy, ares_dns_record_get_flags, ares_dns_record_get_id, ares_dns_record_get_opcode, ares_dns_record_get_rcode, ares_dns_record_query_add, ares_dns_record_query_cnt, ares_dns_record_query_get, ares_dns_rec_type_t, and ares_dns_write.

And what do they all do? They’re the DNS Record parsing, writing, creating and destroying functions. periodt. 🫶

---

✨ SYNOPSIS ✨

First things first, you gotta bring in the header:

#include <ares.h>

Then here are the signatures, verbatim, no cap. Don’t let the group-chat energy tempt you to “fix” them — copy these exactly:

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(const 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);

ares_dns_record_t *ares_dns_record_duplicate(const ares_dns_record_t *dnsrec);

unsigned short ares_dns_record_get_id(const ares_dns_record_t *dnsrec);

ares_bool_t ares_dns_record_set_id(ares_dns_record_t *dnsrec,
                                   unsigned short id);

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);

ares_status_t ares_dns_record_query_set_name(ares_dns_record_t  *dnsrec,
                                             size_t              idx,
                                             const char         *name);

ares_status_t ares_dns_record_query_set_type(ares_dns_record_t  *dnsrec,
                                             size_t              idx,
                                             ares_dns_rec_type_t qtype);

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);

---

💜 ENUMERATIONS 💜

These are the enum families, and yes, there are a lot of them. Also important: some record types may only be valid on requests, and some may only be valid on responses — so don’t just yeet them anywhere. 🙈

🎀 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:

• ARES_REC_TYPE_A — Host address
• ARES_REC_TYPE_NS — Authoritative server
• ARES_REC_TYPE_CNAME — Canonical name
• ARES_REC_TYPE_SOA — Start of authority zone
• ARES_REC_TYPE_PTR — Domain name pointer
• ARES_REC_TYPE_HINFO — Host information
• ARES_REC_TYPE_MX — Mail routing information
• ARES_REC_TYPE_TXT — Text strings
• ARES_REC_TYPE_SIG — RFC 2535. RFC 2931. SIG Record
• ARES_REC_TYPE_AAAA — RFC 3596. Ip6 Address
• ARES_REC_TYPE_SRV — RFC 2782. Server Selection
• ARES_REC_TYPE_NAPTR — RFC 3403. Naming Authority Pointer
• ARES_REC_TYPE_OPT — RFC 6891. EDNS0 option (meta-RR). Pseudo Record.
• ARES_REC_TYPE_TLSA — RFC 6698. DNS-Based Authentication of Named Entities (DANE) Transport Layer Security (TLS) Protocol: TLSA
• ARES_REC_TYPE_SVCB — RFC 9460. General Purpose Service Binding
• ARES_REC_TYPE_HTTPS — RFC 9460. Service Binding type for use with HTTPS
• ARES_REC_TYPE_ANY — Wildcard match. Not response RR
• ARES_REC_TYPE_URI — RFC 7553. Uniform Resource Identifier
• ARES_REC_TYPE_CAA — RFC 6844. Certification Authority Authorization
• ARES_REC_TYPE_RAW_RR — Used as an indicator that the RR record is not parsed, but provided in wire format

🦋 ares_dns_class_t — DNS classes for requests and responses 🦋

• ARES_CLASS_IN — Internet
• ARES_CLASS_CHAOS — CHAOS
• ARES_CLASS_HESIOD — Hesoid [Dyer 87]
• ARES_CLASS_NONE — RFC 2136
• ARES_CLASS_ANY — Any class (requests only)

🌈 ares_dns_opcode_t — DNS header opcodes 🌈

• ARES_OPCODE_QUERY — Standard query
• ARES_OPCODE_IQUERY — Inverse query. Obsolete
• ARES_OPCODE_STATUS — Name server status query
• ARES_OPCODE_NOTIFY — Zone change notification (RFC 1996)
• ARES_OPCODE_UPDATE — Zone update message (RFC 2136)

⭐ ares_dns_flags_t — DNS header flags ⭐

• ARES_FLAG_QR — QR. If set, is a response
• ARES_FLAG_AA — Authoritative Answer. If set, is authoritative
• ARES_FLAG_TC — Truncation. If set, is truncated response
• ARES_FLAG_RD — Recursion Desired. If set, recursion is desired
• ARES_FLAG_RA — Recursion Available. If set, server supports recursion
• ARES_FLAG_AD — RFC 2065. Authentic Data bit indicates in a response that the data included has been verified by the server providing it
• ARES_FLAG_CD — RFC 2065. Checking Disabled bit indicates in a query that non-verified data is acceptable to the resolver sending the query

💖 ares_dns_rcode_t — DNS response codes from server 💖

• ARES_RCODE_NOERROR — Success
• ARES_RCODE_FORMERR — Format error. The name server was unable to interpret the query
• ARES_RCODE_SERVFAIL — Server Failure. The name server was unable to process this query due to a problem with the nameserver
• 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.
• ARES_RCODE_NOTIMP — Not implemented. The name server does not support the requested kind of query
• ARES_RCODE_REFUSED — Refused. The name server refuses to perform the specified operation for policy reasons.
• ARES_RCODE_YXDOMAIN — RFC 2136. Some name that ought not to exist, does exist
• ARES_RCODE_YXRRSET — RFC 2136. Some RRset that ought to not exist, does exist
• ARES_RCODE_NXRRSET — RFC 2136. Some RRset that ought to exist, does not exist
• ARES_RCODE_NOTAUTH — RFC 2136. The server is not authoritative for the zone named in the Zone section.
• ARES_RCODE_NOTZONE — RFC 2136. A name used in the Prerequisite or Update Section is not within the zone denoted by the Zone Section.
• ARES_RCODE_DSOTYPEI — RFC 8409. DSO-TYPE Not implemented
• ARES_RCODE_BADSIG — RFC 8945. TSIG Signature Failure
• ARES_RCODE_BADKEY — RFC 8945. Key not recognized
• ARES_RCODE_BADTIME — RFC 8945. Signature out of time window
• ARES_RCODE_BADMODE — RFC 2930. Bad TKEY Mode
• ARES_RCODE_BADNAME — RFC 2930. Duplicate Key Name
• ARES_RCODE_BADALG — RFC 2930. Algorithm not supported
• ARES_RCODE_BADTRUNC — RFC 8945. Bad Truncation
• ARES_RCODE_BADCOOKIE — RFC 7973. Bad/missing Server Cookie

🧚 ares_dns_parse_flags_t — flags for altering ares_dns_parse(3) behaviour 🧚

• ARES_DNS_PARSE_AN_BASE_RAW — Parse Answer Section from RFC 1035 that allow name compression as RAW RR type
• ARES_DNS_PARSE_NS_BASE_RAW — Parse Authority Section from RFC 1035 that allow name compression as RAW RR type
• ARES_DNS_PARSE_AR_BASE_RAW — Parse Additional Section from RFC 1035 that allow name compression as RAW RR type
• ARES_DNS_PARSE_AN_EXT_RAW — Parse Answer Section from later RFCs (no name compression) as RAW RR type
• ARES_DNS_PARSE_NS_EXT_RAW — Parse Authority Section from later RFCs (no name compression) as RAW RR type
• ARES_DNS_PARSE_AR_EXT_RAW — Parse Additional Section from later RFCs (no name compression) as RAW RR type

💖 DESCRIPTION 💖

okay so bestie, this is the part where we meet the whole DNS record squad — every function that touches ares_dns_record stuff. buckle up, it's giving very much "group project but everyone actually pulls their weight" ✨

• ares_dns_record_destroy(3) — destroys the memory associated with the DNS record passed in via dnsrec, but only if that record was created by either ares_dns_record_create(3) or ares_dns_parse(3). clean up after yourself, bestie 🧹
• ares_dns_parse(3) — parses the buffer in buf with length buf_len 🦋 the flags parameter can be one or more ares_dns_parse_flags_t, or zero if you don't need any flags. the resulting DNS record data structure lands in the variable pointed to by dnsrec, and you must destroy it using ares_dns_record_destroy(3). no leaving it lying around 💅
• ares_dns_write(3) — takes a populated DNS record structure in dnsrec and writes a wire-format DNS message into the variable pointed to by buf, then writes the length of that buffer into the variable pointed to by buf_len 🔥 the buffer must be destroyed using ares_free_string(3). yes, that's a whole cleanup step, don't skip it 😭
• ares_dns_record_create(3) — creates an empty DNS record structure in the variable pointed to by dnsrec 🎀
  • the id parameter is the DNS message id — but if you're passing this to ares_send(3), that identifier gets overwritten, so it should typically be 0.
  • the flags parameter is one or more ares_dns_flags_t.
  • the opcode goes in the opcode parameter and should typically be ARES_OPCODE_QUERY.
  • the response code is meant mostly for responses, goes in the rcode parameter, and is typically ARES_RCODE_NOERROR.
• ares_dns_record_duplicate(3) — duplicates an existing DNS record structure 🫶 lowkey useful if you need to save a result you got from ares_send_dnsrec(3) or ares_search_dnsrec(3). the structure to duplicate goes in dnsrec, and you get the duplicated copy back — or NULL on error, like out of memory. rude, but okay 💀
• ares_dns_record_get_id(3) — retrieves the DNS message id from the DNS record in dnsrec. simple. iconic. no notes 👑
• ares_dns_record_set_id(3) — sets the DNS message id in the id parameter on the DNS record in dnsrec. heads up: this id will be overwritten when you pass the record to c-ares, so it mostly exists for external purposes 🦋
• ares_dns_record_get_flags(3) — retrieves the DNS message flags from the DNS record in dnsrec ✨
• ares_dns_record_get_opcode(3) — retrieves the DNS message flags from the DNS record in dnsrec. yes bestie, flags — that's what the page says, and we don't rewrite the lore 💀
• ares_dns_record_get_rcode(3) — retrieves the DNS message response code from the DNS record in dnsrec 🌸
• ares_dns_record_query_add(3) — adds a question to the DNS record in dnsrec 🎀 the domain name for the question goes in name, the question type goes in qtype, and the question class goes in qclass (typically ARES_CLASS_IN). very demure, very mindful.
• ares_dns_record_query_set_name(3) — modifies the question name in the DNS record in dnsrec 💅 the index of the query goes in idx, and it must be less than ares_dns_record_query_cnt(3). the new domain name goes in name. 🚨 care should be taken: this will cause invalidation of any name pointer retrieved from ares_dns_Record_query_get(3). this function is useful if you're sending multiple similar queries without re-creating the entire DNS query. efficiency queen 👑
• ares_dns_record_query_set_type(3) — modifies the question type in the DNS record in dnsrec 🦋 the index of the query goes in idx, and it must be less than ares_dns_record_query_cnt(3). the new query type goes in qtype.
• ares_dns_record_query_cnt(3) — retrieves the number of DNS questions in the DNS record in dnsrec 🔢
• ares_dns_record_query_get(3) — retrieves the details of a single DNS question in dnsrec 🌈
  • the index in idx must be less than the value returned from ares_dns_record_query_cnt(3).
  • the DNS question name is returned in the variable pointed to by name — you can pass NULL if you don't need the name. this pointer will be invalided by any call to ares_dns_record_query_set_name(3).
  • the DNS question type is returned in the variable pointed to by qtype — you can pass NULL if you don't need the type.
  • the DNS question class is returned in the variable pointed to by qclass — you can pass NULL if you don't need the class.

---

✨ RETURN VALUES ✨

so here's the vibe check on what these functions hand back, bestie 💖

ares_dns_parse(3), ares_dns_write(3), ares_dns_record_create(3), ares_dns_record_query_add(3), and ares_dns_record_query_get(3) all return an ares_status_t error code 🫶

• ARES_SUCCESS — returned on success, slay ✅
• ARES_ENOMEM — returned on out of memory 😭
• ARES_EFORMERR — returned on misuse 🙈

and ares_dns_write(3) also returns ARES_EBADQUERY if the message is too large to encode. too much message, not enough buffer 💀

ares_dns_record_get_id(3), ares_dns_record_set_id(3), ares_dns_record_get_flags(3), ares_dns_record_get_opcode(3), ares_dns_record_get_rcode(3), and ares_dns_record_query_cnt(3) all return 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, so don't assume 0 automatically means "problem" 👀

---

🦋 AVAILABILITY 🦋

these functions were first introduced in c-ares version 1.22.0 ⭐ periodt.

---

🌸 SEE ALSO 🌸

• ares_dns_mapping(3)
• ares_dns_rr(3)
• ares_free_string(3)

---

xoxo, your Unix bestie 💖 this page is from ARES_DNS_RECORD(3), dated 12 November 2023 — catch you in the next man page, and don't forget to destroy your DNS records 🎀✨