ares_send.3 (4866B)
1 .\" 2 .\" Copyright 1998 by the Massachusetts Institute of Technology. 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_SEND 3 "25 July 1998" 6 .SH NAME 7 ares_send \- Initiate a DNS query 8 .SH SYNOPSIS 9 .nf 10 #include <ares.h> 11 12 typedef void (*ares_callback_dnsrec)(void *arg, ares_status_t status, 13 size_t timeouts, 14 const ares_dns_record_t *dnsrec); 15 16 ares_status_t ares_send_dnsrec(ares_channel_t *channel, 17 const ares_dns_record_t *dnsrec, 18 ares_callback_dnsrec callback, 19 void *arg, unsigned short *qid); 20 21 typedef void (*ares_callback)(void *arg, int status, 22 int timeouts, unsigned char *abuf, 23 int alen); 24 25 void ares_send(ares_channel_t *channel, const unsigned char *qbuf, 26 int qlen, ares_callback callback, void *arg); 27 28 .fi 29 .SH DESCRIPTION 30 The \fIares_send_dnsrec(3)\fP function initiates a DNS query formatted using the 31 \fIares_dns_record_t *\fP data structure created via 32 \fIares_dns_record_create(3)\fP in the 33 .IR dnsrec 34 parameter. The supplied callback in the 35 .IR callback 36 parameter also returns the response using a 37 \fIares_dns_record_t *\fP data structure. 38 39 The \fIares_send(3)\fP function similarly initiates a DNS query, but instead uses 40 raw binary buffers with fully formatted DNS messages passed in the request via the 41 .IR qbuf 42 and 43 .IR qlen 44 parameters. The supplied callback in the 45 .IR callback 46 parameter also returns the raw binary DNS response in the 47 .IR abuf 48 and 49 .IR alen 50 parameters. This method should be considered deprecated in favor of 51 \fIares_send_dnsrec(3)\fP. 52 53 Both functions take an initialized ares channel identified by 54 .IR channel . 55 56 The \fIares_send_dnsrec(3)\fP also can be supplied an optional output parameter of 57 .IR qid 58 to populate the query id as it was placed on the wire. 59 60 The \fIares_send_dnsrec(3)\fP function returns an \fIares_status_t\fP response 61 code. This may be useful to know that the query was enqueued properly. The 62 response code does not reflect the result of the query, just the result of the 63 enqueuing of the query. 64 65 Completion or failure of the query may happen immediately (even before the 66 function returning), or may happen later as network events are processed. 67 68 When the associated callback is called, it is called with a channel lock so care 69 must be taken to ensure any processing is minimal to prevent DNS channel stalls. 70 71 The callback may be triggered from a different thread than the one which 72 called \fIares_send_dnsrec(3)\fP or \fIares_send(3)\fP. 73 74 For integrators running their own event loops and not using \fBARES_OPT_EVENT_THREAD\fP, 75 care needs to be taken to ensure any file descriptor lists are updated immediately 76 within the eventloop when notified. 77 78 The callback argument 79 .IR arg 80 is copied from the \fIares_send_dnsrec(3)\fP or \fIares_send(3)\fP 81 .IR arg 82 parameter. 83 84 The callback argument 85 .I status 86 indicates whether the query succeeded and, if not, how it failed. It 87 may have any of the following values: 88 .TP 19 89 .B ARES_SUCCESS 90 The query completed. 91 .TP 19 92 .B ARES_EBADQUERY 93 The query buffer was poorly formed (was not long enough for a DNS 94 header or was too long for TCP transmission). 95 .TP 19 96 .B ARES_ETIMEOUT 97 No name servers responded within the timeout period. 98 .TP 19 99 .B ARES_ECONNREFUSED 100 No name servers could be contacted. 101 .TP 19 102 .B ARES_ENOMEM 103 Memory was exhausted. 104 .TP 19 105 .B ARES_ECANCELLED 106 The query was cancelled. 107 .TP 19 108 .B ARES_EDESTRUCTION 109 The name service channel 110 .I channel 111 is being destroyed; the query will not be completed. 112 .TP 19 113 .B ARES_ENOSERVER 114 The query will not be completed because no DNS servers were configured on the 115 channel. 116 .TP 19 117 .B ARES_EBADQUERY 118 Misformatted DNS query. 119 .PP 120 121 The callback argument 122 .I timeouts 123 reports how many times a query timed out during the execution of the 124 given request. 125 126 If the query completed, the callback argument 127 .IR dnsrec 128 for \fIares_send_dnsrec(3)\fP or 129 .IR abuf 130 and 131 .IR alen 132 for \fIares_send(3)\fP will be non-NULL. 133 134 Unless the flag 135 .B ARES_FLAG_NOCHECKRESP 136 was set at channel initialization time, \fIares_send_dnsrec(3)\fP and 137 \fIares_send(3)\fP will normally ignore responses whose questions do not match 138 the supplied questions, as well as responses with reply codes of 139 .BR SERVFAIL , 140 .BR NOTIMP , 141 and 142 .BR REFUSED . 143 Unlike other query functions in the ares library, however, 144 \fIares_send_dnsrec(3)\fP and \fIares_send(3)\fP do not inspect the header of 145 the reply packet to determine the error status, so a callback status of 146 .B ARES_SUCCESS 147 does not reflect as much about the response as for other query functions. 148 149 .SH AVAILABILITY 150 \fBares_send_dnsrec(3)\fP was introduced in c-ares 1.28.0. 151 152 .SH SEE ALSO 153 .BR ares_dns_record_create (3), 154 .BR ares_process (3), 155 .BR ares_search (3), 156 .BR ares_dns_record (3)