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 <ares.h>
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);
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_dns_class_t - DNS Classes for requests and responses:

ares_dns_opcode_t - DNS Header Opcodes:

ares_dns_flags_t - DNS Header Flags:

ares_dns_rcode_t - DNS Response codes from server:

ares_dns_parse_flags_t - Flags for altering ares_dns_parse(3) behaviour:

DESCRIPTION¶

The ares_dns_record_destroy(3) function destroys the memory associated with the dns record created by either ares_dns_record_create(3) or ares_dns_parse(3) passed in via dnsrec.

The 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).

The 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).

The 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) 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) function duplicates an existing DNS record structure. This may be useful if needing to save a result as retrieved from ares_send_dnsrec(3) or 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) function is used to retrieve the DNS message id from the DNS record provided in the dnsrec parameter.

The 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) 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) 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) 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) 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), 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) 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), is provided in the idx parameter. The new query type is provided in the qtype parameter.

The 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) 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). 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). 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_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 is returned on success, ARES_ENOMEM is returned on out of memory, ARES_EFORMERR is returned on misuse.

ares_dns_record_get_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 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_rr(3), ares_free_string(3)

AUTHOR¶

Copyright (C) 2023 The c-ares project and its members.