jpayne@68: .\" jpayne@68: .\" Copyright 1998 by the Massachusetts Institute of Technology. jpayne@68: .\" SPDX-License-Identifier: MIT jpayne@68: .\" jpayne@68: .TH ARES_SEND 3 "25 July 1998" jpayne@68: .SH NAME jpayne@68: ares_send \- Initiate a DNS query jpayne@68: .SH SYNOPSIS jpayne@68: .nf jpayne@68: #include jpayne@68: jpayne@68: typedef void (*ares_callback_dnsrec)(void *arg, ares_status_t status, jpayne@68: size_t timeouts, jpayne@68: const ares_dns_record_t *dnsrec); jpayne@68: jpayne@68: ares_status_t ares_send_dnsrec(ares_channel_t *channel, jpayne@68: const ares_dns_record_t *dnsrec, jpayne@68: ares_callback_dnsrec callback, jpayne@68: void *arg, unsigned short *qid); jpayne@68: jpayne@68: typedef void (*ares_callback)(void *arg, int status, jpayne@68: int timeouts, unsigned char *abuf, jpayne@68: int alen); jpayne@68: jpayne@68: void ares_send(ares_channel_t *channel, const unsigned char *qbuf, jpayne@68: int qlen, ares_callback callback, void *arg); jpayne@68: jpayne@68: .fi jpayne@68: .SH DESCRIPTION jpayne@68: The \fIares_send_dnsrec(3)\fP function initiates a DNS query formatted using the jpayne@68: \fIares_dns_record_t *\fP data structure created via jpayne@68: \fIares_dns_record_create(3)\fP in the jpayne@68: .IR dnsrec jpayne@68: parameter. The supplied callback in the jpayne@68: .IR callback jpayne@68: parameter also returns the response using a jpayne@68: \fIares_dns_record_t *\fP data structure. jpayne@68: jpayne@68: The \fIares_send(3)\fP function similarly initiates a DNS query, but instead uses jpayne@68: raw binary buffers with fully formatted DNS messages passed in the request via the jpayne@68: .IR qbuf jpayne@68: and jpayne@68: .IR qlen jpayne@68: parameters. The supplied callback in the jpayne@68: .IR callback jpayne@68: parameter also returns the raw binary DNS response in the jpayne@68: .IR abuf jpayne@68: and jpayne@68: .IR alen jpayne@68: parameters. This method should be considered deprecated in favor of jpayne@68: \fIares_send_dnsrec(3)\fP. jpayne@68: jpayne@68: Both functions take an initialized ares channel identified by jpayne@68: .IR channel . jpayne@68: jpayne@68: The \fIares_send_dnsrec(3)\fP also can be supplied an optional output parameter of jpayne@68: .IR qid jpayne@68: to populate the query id as it was placed on the wire. jpayne@68: jpayne@68: The \fIares_send_dnsrec(3)\fP function returns an \fIares_status_t\fP response jpayne@68: code. This may be useful to know that the query was enqueued properly. The jpayne@68: response code does not reflect the result of the query, just the result of the jpayne@68: enqueuing of the query. jpayne@68: jpayne@68: Completion or failure of the query may happen immediately (even before the jpayne@68: function returning), or may happen later as network events are processed. jpayne@68: jpayne@68: When the associated callback is called, it is called with a channel lock so care jpayne@68: must be taken to ensure any processing is minimal to prevent DNS channel stalls. jpayne@68: jpayne@68: The callback may be triggered from a different thread than the one which jpayne@68: called \fIares_send_dnsrec(3)\fP or \fIares_send(3)\fP. jpayne@68: jpayne@68: For integrators running their own event loops and not using \fBARES_OPT_EVENT_THREAD\fP, jpayne@68: care needs to be taken to ensure any file descriptor lists are updated immediately jpayne@68: within the eventloop when notified. jpayne@68: jpayne@68: The callback argument jpayne@68: .IR arg jpayne@68: is copied from the \fIares_send_dnsrec(3)\fP or \fIares_send(3)\fP jpayne@68: .IR arg jpayne@68: parameter. jpayne@68: jpayne@68: The callback argument jpayne@68: .I status jpayne@68: indicates whether the query succeeded and, if not, how it failed. It jpayne@68: may have any of the following values: jpayne@68: .TP 19 jpayne@68: .B ARES_SUCCESS jpayne@68: The query completed. jpayne@68: .TP 19 jpayne@68: .B ARES_EBADQUERY jpayne@68: The query buffer was poorly formed (was not long enough for a DNS jpayne@68: header or was too long for TCP transmission). jpayne@68: .TP 19 jpayne@68: .B ARES_ETIMEOUT jpayne@68: No name servers responded within the timeout period. jpayne@68: .TP 19 jpayne@68: .B ARES_ECONNREFUSED jpayne@68: No name servers could be contacted. jpayne@68: .TP 19 jpayne@68: .B ARES_ENOMEM jpayne@68: Memory was exhausted. jpayne@68: .TP 19 jpayne@68: .B ARES_ECANCELLED jpayne@68: The query was cancelled. jpayne@68: .TP 19 jpayne@68: .B ARES_EDESTRUCTION jpayne@68: The name service channel jpayne@68: .I channel jpayne@68: is being destroyed; the query will not be completed. jpayne@68: .TP 19 jpayne@68: .B ARES_ENOSERVER jpayne@68: The query will not be completed because no DNS servers were configured on the jpayne@68: channel. jpayne@68: .TP 19 jpayne@68: .B ARES_EBADQUERY jpayne@68: Misformatted DNS query. jpayne@68: .PP jpayne@68: jpayne@68: The callback argument jpayne@68: .I timeouts jpayne@68: reports how many times a query timed out during the execution of the jpayne@68: given request. jpayne@68: jpayne@68: If the query completed, the callback argument jpayne@68: .IR dnsrec jpayne@68: for \fIares_send_dnsrec(3)\fP or jpayne@68: .IR abuf jpayne@68: and jpayne@68: .IR alen jpayne@68: for \fIares_send(3)\fP will be non-NULL. jpayne@68: jpayne@68: Unless the flag jpayne@68: .B ARES_FLAG_NOCHECKRESP jpayne@68: was set at channel initialization time, \fIares_send_dnsrec(3)\fP and jpayne@68: \fIares_send(3)\fP will normally ignore responses whose questions do not match jpayne@68: the supplied questions, as well as responses with reply codes of jpayne@68: .BR SERVFAIL , jpayne@68: .BR NOTIMP , jpayne@68: and jpayne@68: .BR REFUSED . jpayne@68: Unlike other query functions in the ares library, however, jpayne@68: \fIares_send_dnsrec(3)\fP and \fIares_send(3)\fP do not inspect the header of jpayne@68: the reply packet to determine the error status, so a callback status of jpayne@68: .B ARES_SUCCESS jpayne@68: does not reflect as much about the response as for other query functions. jpayne@68: jpayne@68: .SH AVAILABILITY jpayne@68: \fBares_send_dnsrec(3)\fP was introduced in c-ares 1.28.0. jpayne@68: jpayne@68: .SH SEE ALSO jpayne@68: .BR ares_dns_record_create (3), jpayne@68: .BR ares_process (3), jpayne@68: .BR ares_search (3), jpayne@68: .BR ares_dns_record (3)