--- name: "ares_send" 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_send" --- # ares\_send(3) Initiate a DNS query ## NAME ares\_send - Initiate a DNS query ## SYNOPSIS ``` #include typedef void (*ares_callback_dnsrec)(void *arg, ares_status_t status, size_t timeouts, const ares_dns_record_t *dnsrec); ares_status_t ares_send_dnsrec(ares_channel_t *channel, const ares_dns_record_t *dnsrec, ares_callback_dnsrec callback, void *arg, unsigned short *qid); typedef void (*ares_callback)(void *arg, int status, int timeouts, unsigned char *abuf, int alen); void ares_send(ares_channel_t *channel, const unsigned char *qbuf, int qlen, ares_callback callback, void *arg); ``` ## DESCRIPTION The *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)* function initiates a DNS query formatted using the *ares\_dns\_record\_t \** data structure created via *[ares\_dns\_record\_create(3)](/ares_dns_record_create/3.md)* in the *dnsrec* parameter. The supplied callback in the *callback* parameter also returns the response using a *ares\_dns\_record\_t \** data structure. The *[ares\_send(3)](/ares_send/3.md)* function similarly initiates a DNS query, but instead uses raw binary buffers with fully formatted DNS messages passed in the request via the *qbuf* and *qlen* parameters. The supplied callback in the *callback* parameter also returns the raw binary DNS response in the *abuf* and *alen* parameters. This method should be considered deprecated in favor of *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)*. Both functions take an initialized ares channel identified by *channel*. The *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)* also can be supplied an optional output parameter of *qid* to populate the query id as it was placed on the wire. The *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)* function returns an *ares\_status\_t* response code. This may be useful to know that the query was enqueued properly. The response code does not reflect the result of the query, just the result of the enqueuing of the query. Completion or failure of the query may happen immediately (even before the function returning), or may happen later as network events are processed. When the associated callback is called, it is called with a channel lock so care must be taken to ensure any processing is minimal to prevent DNS channel stalls. The callback may be triggered from a different thread than the one which called *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)* or *[ares\_send(3)](/ares_send/3.md)*. For integrators running their own event loops and not using **ARES\_OPT\_EVENT\_THREAD**, care needs to be taken to ensure any file descriptor lists are updated immediately within the eventloop when notified. The callback argument *arg* is copied from the *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)* or *[ares\_send(3)](/ares_send/3.md)* *arg* parameter. The callback argument *status* indicates whether the query succeeded and, if not, how it failed. It may have any of the following values: - **ARES\_SUCCESS** The query completed. - **ARES\_EBADQUERY** The query buffer was poorly formed (was not long enough for a DNS header or was too long for TCP transmission). - **ARES\_ETIMEOUT** No name servers responded within the timeout period. - **ARES\_ECONNREFUSED** No name servers could be contacted. - **ARES\_ENOMEM** Memory was exhausted. - **ARES\_ECANCELLED** The query was cancelled. - **ARES\_EDESTRUCTION** The name service channel *channel* is being destroyed; the query will not be completed. - **ARES\_ENOSERVER** The query will not be completed because no DNS servers were configured on the channel. - **ARES\_EBADQUERY** Misformatted DNS query. The callback argument *timeouts* reports how many times a query timed out during the execution of the given request. If the query completed, the callback argument *dnsrec* for *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)* or *abuf* and *alen* for *[ares\_send(3)](/ares_send/3.md)* will be non-NULL. The *abuf* buffer is owned by the c-ares library and is only valid for the duration of the callback. The callback **must not** modify or free it, and must not retain a reference to it after returning; treat it as read-only. The parameter is intentionally not declared **const** solely to preserve API/ABI compatibility with existing applications. Unless the flag **ARES\_FLAG\_NOCHECKRESP** was set at channel initialization time, *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)* and *[ares\_send(3)](/ares_send/3.md)* will normally ignore responses whose questions do not match the supplied questions, as well as responses with reply codes of **SERVFAIL**, **NOTIMP**, and **REFUSED**. Unlike other query functions in the ares library, however, *[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)* and *[ares\_send(3)](/ares_send/3.md)* do not inspect the header of the reply packet to determine the error status, so a callback status of **ARES\_SUCCESS** does not reflect as much about the response as for other query functions. ## AVAILABILITY **[ares\_send\_dnsrec(3)](/ares_send_dnsrec/3.md)** was introduced in c-ares 1.28.0. ## SEE ALSO [**ares\_dns\_record\_create**(3)](/ares_dns_record_create/3.md), [**ares\_process**(3)](/ares_process/3.md), [**ares\_search**(3)](/ares_search/3.md), [**ares\_dns\_record**(3)](/ares_dns_record/3.md)