--- name: "ares_dns_parse" section: "3" platform: "linux" package: "c-ares" version: "1.34.9-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/ares_dns_record" --- # ares\_dns\_parse(3) DNS Record parsing, writing, creating and destroying functions. Part of [ares\_dns\_record(3)](/ares_dns_record/3.md). ## NAME 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, ares\_dns\_write - DNS Record parsing, writing, creating and destroying functions. ## SYNOPSIS ``` #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(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 **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)](/ares_dns_parse/3.md)* 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 The *[ares\_dns\_record\_destroy(3)](/ares_dns_record_destroy/3.md)* function destroys the memory associated with the dns record created by either *[ares\_dns\_record\_create(3)](/ares_dns_record_create/3.md)* or *[ares\_dns\_parse(3)](/ares_dns_parse/3.md)* passed in via *dnsrec*. The *[ares\_dns\_parse(3)](/ares_dns_parse/3.md)* function parses the buffer provided in *buf* with length provided in *buf\_len.* The *flags* parameter can be one or more *ares\_dns\_parse\_flags\_t*, or zero if no flags are needed. The resulting dns record data structure is stored into the variable pointed to by *dnsrec* and must be destroyed using *[ares\_dns\_record\_destroy(3)](/ares_dns_record_destroy/3.md)*. The *[ares\_dns\_write(3)](/ares_dns_write/3.md)* function takes a populated DNS record structure in *dnsrec* and writes a wire-format DNS message into the variable pointed to by *buf* and writes the length of the buffer into the variable pointed to by *buf\_len.* The buffer must be destroyed using *[ares\_free\_string(3)](/ares_free_string/3.md)*. The *[ares\_dns\_record\_create(3)](/ares_dns_record_create/3.md)* function creates an empty DNS record structure in the variable pointed to by *dnsrec.* The *id* parameter is the DNS message id, however if passing to *[ares\_send(3)](/ares_send/3.md)* this identifier will be overwritten, so should typically be 0. The *flags* parameter is one or more *ares\_dns\_flags\_t*. The opcode is passed in the *opcode* parameter and should typically be *ARES\_OPCODE\_QUERY*. The response code is meant mostly for responses and is passed in the *rcode* parameter and is typically *ARES\_RCODE\_NOERROR*. The *[ares\_dns\_record\_duplicate(3)](/ares_dns_record_duplicate/3.md)* function duplicates an existing DNS record structure. This may be useful if needing to save a result as retrieved from *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)* or *[ares\_search\_dnsrec(3)](/ares_search_dnsrec/3.md)*. The structure to be duplicated is passed in the *dnsrec* parameter, and the duplicated copy is returned, or NULL on error such as out of memory. The *[ares\_dns\_record\_get\_id(3)](/ares_dns_record_get_id/3.md)* function is used to retrieve the DNS message id from the DNS record provided in the *dnsrec* parameter. The *[ares\_dns\_record\_set\_id(3)](/ares_dns_record_set_id/3.md)* function is used to set the DNS message id in the *id* parameter from the DNS record provided in the *dnsrec* parameter. This id will be overwritten when passing the record to c-ares, so mostly exists for external purposes. The *[ares\_dns\_record\_get\_flags(3)](/ares_dns_record_get_flags/3.md)* function is used to retrieve the DNS message flags from the DNS record provided in the *dnsrec* parameter. The *[ares\_dns\_record\_get\_opcode(3)](/ares_dns_record_get_opcode/3.md)* function is used to retrieve the DNS message flags from the DNS record provided in the *dnsrec* parameter. The *[ares\_dns\_record\_get\_rcode(3)](/ares_dns_record_get_rcode/3.md)* function is used to retrieve the DNS message response code from the DNS record provided in the *dnsrec* parameter. The *[ares\_dns\_record\_query\_add(3)](/ares_dns_record_query_add/3.md)* function is used to add a question to the DNS record provided in the *dnsrec* parameter. The domain name specified for the question is provided in the *name* parameter, along with the question type in the *qtype* parameter and the question class (typically *ARES\_CLASS\_IN*) in the *qclass* parameter. The *[ares\_dns\_record\_query\_set\_name(3)](/ares_dns_record_query_set_name/3.md)* function is used to modify the question name in the DNS record provided in the *dnsrec* parameter. The index of the query, which must be less than *[ares\_dns\_record\_query\_cnt(3)](/ares_dns_record_query_cnt/3.md)*, is provided in the *idx* parameter. The new domain name is provided in the *name* parameter. Care should be taken as this will cause invalidation of any *name* pointer retrieved from *ares\_dns\_Record\_query\_get(3)*. This function is useful if sending multiple similar queries without re-creating the entire DNS query. The *[ares\_dns\_record\_query\_set\_type(3)](/ares_dns_record_query_set_type/3.md)* function is used to modify the question type in the DNS record provided in the *dnsrec* parameter. The index of the query, which must be less than *[ares\_dns\_record\_query\_cnt(3)](/ares_dns_record_query_cnt/3.md)*, is provided in the *idx* parameter. The new query type is provided in the *qtype* parameter. The *[ares\_dns\_record\_query\_cnt(3)](/ares_dns_record_query_cnt/3.md)* function is used to retrieve the number of DNS questions in the DNS record provided in the *dnsrec* parameter. The *[ares\_dns\_record\_query\_get(3)](/ares_dns_record_query_get/3.md)* function is used to retrieve the details of a single DNS question in the provided *dnsrec* parameter. The index provided in the *idx* parameter must be less than the value returned from *[ares\_dns\_record\_query\_cnt(3)](/ares_dns_record_query_cnt/3.md)*. The DNS question name will be returned in the variable pointed to by the *name* parameter, this may be provided as NULL if the name is not needed. This pointer will be invalided by any call to *[ares\_dns\_record\_query\_set\_name(3)](/ares_dns_record_query_set_name/3.md)*. The DNS question type will be returned in the variable pointed to by the *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 *qclass* parameter, this may be provided as NULL if the class is not needed. ## RETURN VALUES *[ares\_dns\_parse(3)](/ares_dns_parse/3.md)*, *[ares\_dns\_write(3)](/ares_dns_write/3.md)*, *[ares\_dns\_record\_create(3)](/ares_dns_record_create/3.md)*, *[ares\_dns\_record\_query\_add(3)](/ares_dns_record_query_add/3.md)*, and *[ares\_dns\_record\_query\_get(3)](/ares_dns_record_query_get/3.md)* all return an *ares\_status\_t* error code. **ARES\_SUCCESS** is returned on success, **ARES\_ENOMEM** is returned on out of memory, **ARES\_EFORMERR** is returned on misuse. *[ares\_dns\_write(3)](/ares_dns_write/3.md)* also returns **ARES\_EBADQUERY** if the message is too large to encode. *[ares\_dns\_record\_get\_id(3)](/ares_dns_record_get_id/3.md)*, *[ares\_dns\_record\_set\_id(3)](/ares_dns_record_set_id/3.md)*, *[ares\_dns\_record\_get\_flags(3)](/ares_dns_record_get_flags/3.md)*, *[ares\_dns\_record\_get\_opcode(3)](/ares_dns_record_get_opcode/3.md)*, *[ares\_dns\_record\_get\_rcode(3)](/ares_dns_record_get_rcode/3.md)*, and *[ares\_dns\_record\_query\_cnt(3)](/ares_dns_record_query_cnt/3.md)* 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. ## AVAILABILITY These functions were first introduced in c-ares version 1.22.0. ## SEE ALSO [**ares\_dns\_mapping**(3)](/ares_dns_mapping/3.md), [**ares\_dns\_rr**(3)](/ares_dns_rr/3.md), [**ares\_free\_string**(3)](/ares_free_string/3.md)