ARES\_DNS\_RECORD(3) Library Functions Manual ARES\_DNS\_RECORD(3) # [NAME](#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](#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](#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)*](/man/os/c-ares/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](#DESCRIPTION) The [*ares\_dns\_record\_destroy(3)*](/man/os/c-ares/ares_dns_record_destroy.3) function destroys the memory associated with the dns record created by either [*ares\_dns\_record\_create(3)*](/man/os/c-ares/ares_dns_record_create.3) or [*ares\_dns\_parse(3)*](/man/os/c-ares/ares_dns_parse.3) passed in via *dnsrec*. The [*ares\_dns\_parse(3)*](/man/os/c-ares/ares_dns_parse.3) 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)*](/man/os/c-ares/ares_dns_record_destroy.3). The [*ares\_dns\_write(3)*](/man/os/c-ares/ares_dns_write.3) 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)*](/man/os/c-ares/ares_free_string.3). The [*ares\_dns\_record\_create(3)*](/man/os/c-ares/ares_dns_record_create.3) 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)*](/man/os/c-ares/ares_send.3) 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)*](/man/os/c-ares/ares_dns_record_duplicate.3) function duplicates an existing DNS record structure. This may be useful if needing to save a result as retrieved from [*ares\_send\_dnsrec(3)*](/man/os/c-ares/ares_send_dnsrec.3) or [*ares\_search\_dnsrec(3)*](/man/os/c-ares/ares_search_dnsrec.3). 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)*](/man/os/c-ares/ares_dns_record_get_id.3) 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)*](/man/os/c-ares/ares_dns_record_set_id.3) 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)*](/man/os/c-ares/ares_dns_record_get_flags.3) 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)*](/man/os/c-ares/ares_dns_record_get_opcode.3) 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)*](/man/os/c-ares/ares_dns_record_get_rcode.3) 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)*](/man/os/c-ares/ares_dns_record_query_add.3) 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)*](/man/os/c-ares/ares_dns_record_query_set_name.3) 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)*](/man/os/c-ares/ares_dns_record_query_cnt.3), 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)*](/man/os/c-ares/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)*](/man/os/c-ares/ares_dns_record_query_set_type.3) 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)*](/man/os/c-ares/ares_dns_record_query_cnt.3), is provided in the *idx* parameter. The new query type is provided in the *qtype* parameter. The [*ares\_dns\_record\_query\_cnt(3)*](/man/os/c-ares/ares_dns_record_query_cnt.3) 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)*](/man/os/c-ares/ares_dns_record_query_get.3) 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)*](/man/os/c-ares/ares_dns_record_query_cnt.3). 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)*](/man/os/c-ares/ares_dns_record_query_set_name.3). 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](#RETURN_VALUES) [*ares\_dns\_parse(3)*](/man/os/c-ares/ares_dns_parse.3), [*ares\_dns\_write(3)*](/man/os/c-ares/ares_dns_write.3), [*ares\_dns\_record\_create(3)*](/man/os/c-ares/ares_dns_record_create.3), [*ares\_dns\_record\_query\_add(3)*](/man/os/c-ares/ares_dns_record_query_add.3), and [*ares\_dns\_record\_query\_get(3)*](/man/os/c-ares/ares_dns_record_query_get.3) 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)*](/man/os/c-ares/ares_dns_write.3) also returns **ARES\_EBADQUERY** if the message is too large to encode. [*ares\_dns\_record\_get\_id(3)*](/man/os/c-ares/ares_dns_record_get_id.3), [*ares\_dns\_record\_set\_id(3)*](/man/os/c-ares/ares_dns_record_set_id.3), [*ares\_dns\_record\_get\_flags(3)*](/man/os/c-ares/ares_dns_record_get_flags.3), [*ares\_dns\_record\_get\_opcode(3)*](/man/os/c-ares/ares_dns_record_get_opcode.3), [*ares\_dns\_record\_get\_rcode(3)*](/man/os/c-ares/ares_dns_record_get_rcode.3), and [*ares\_dns\_record\_query\_cnt(3)*](/man/os/c-ares/ares_dns_record_query_cnt.3) 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](#AVAILABILITY) These functions were first introduced in c-ares version 1.22.0. # [SEE ALSO](#SEE_ALSO) [**ares\_dns\_mapping**(3)](/man/os/c-ares/ares_dns_mapping.3), [**ares\_dns\_rr**(3)](/man/os/c-ares/ares_dns_rr.3), [**ares\_free\_string**(3)](/man/os/c-ares/ares_free_string.3) 12 November 2023 --- Document: ares_dns_record_get_id(3) from c-ares 1.34.9-r0 (Chainguard OS) Source: https://github.com/c-ares/c-ares