ares_search.3 (6052B)
1 .\" 2 .\" Copyright 1998 by the Massachusetts Institute of Technology. 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_SEARCH 3 "24 July 1998" 6 .SH NAME 7 ares_search \- Initiate a DNS query with domain search 8 .SH SYNOPSIS 9 .nf 10 #include <ares.h> 11 12 typedef void (*ares_callback_dnsrec)(void *\fIarg\fP, 13 ares_status_t \fIstatus\fP, 14 size_t \fItimeouts\fP, 15 const ares_dns_record_t *\fIdnsrec\fP); 16 17 void ares_search_dnsrec(ares_channel_t *\fIchannel\fP, 18 const ares_dns_record_t *\fIdnsrec\fP, 19 ares_callback_dnsrec \fIcallback\fP, void *\fIarg\fP); 20 21 typedef void (*ares_callback)(void *\fIarg\fP, int \fIstatus\fP, 22 int \fItimeouts\fP, unsigned char *\fIabuf\fP, 23 int \fIalen\fP); 24 25 void ares_search(ares_channel_t *\fIchannel\fP, const char *\fIname\fP, 26 int \fIdnsclass\fP, int \fItype\fP, 27 ares_callback \fIcallback\fP, void *\fIarg\fP); 28 29 .fi 30 .SH DESCRIPTION 31 The 32 .B ares_search 33 function initiates a series of single-question DNS queries on the name 34 service channel identified by 35 .IR channel , 36 using the channel's search domains as well as a host alias file given 37 by the HOSTALIAS environment variable. The parameter 38 .I name 39 gives the alias name or the base of the query name as a NUL-terminated 40 C string of period-separated labels; if it ends with a period, the 41 channel's search domains will not be used. Periods and backslashes 42 within a label must be escaped with a backslash. The parameters 43 .I dnsclass 44 and 45 .I type 46 give the class and type of the query using the values defined in 47 .BR <arpa/nameser.h> . 48 When the query sequence is complete or has failed, the ares library 49 will invoke 50 .IR callback . 51 Completion or failure of the query sequence may happen immediately, or 52 may happen during a later call to 53 .BR ares_process (3) 54 or 55 .BR ares_destroy (3). 56 .PP 57 If this is called from a thread other than which the main program event loop is 58 running, care needs to be taken to ensure any file descriptor lists are updated 59 immediately within the eventloop. When the associated callback is called, 60 it is called with a channel lock so care must be taken to ensure any processing 61 is minimal to prevent DNS channel stalls. 62 .PP 63 The callback argument 64 .I arg 65 is copied from the 66 .B ares_search 67 argument 68 .IR arg . 69 The callback argument 70 .I status 71 indicates whether the query sequence ended with a successful query 72 and, if not, how the query sequence failed. It may have any of the 73 following values: 74 .TP 19 75 .B ARES_SUCCESS 76 A query completed successfully. 77 .TP 19 78 .B ARES_ENODATA 79 No query completed successfully; when the query was tried without a 80 search domain appended, a response was returned with no answers. 81 .TP 19 82 .B ARES_EFORMERR 83 A query completed but the server claimed that the query was 84 malformatted. 85 .TP 19 86 .B ARES_ESERVFAIL 87 No query completed successfully; when the query was tried without a 88 search domain appended, the server claimed to have experienced a 89 failure. (This code can only occur if the 90 .B ARES_FLAG_NOCHECKRESP 91 flag was specified at channel initialization time; otherwise, such 92 responses are ignored at the 93 .BR ares_send (3) 94 level.) 95 .TP 19 96 .B ARES_ENOTFOUND 97 No query completed successfully; when the query was tried without a 98 search domain appended, the server reported that the queried-for 99 domain name was not found. 100 .TP 19 101 .B ARES_ENOTIMP 102 A query completed but the server does not implement the operation 103 requested by the query. (This code can only occur if the 104 .B ARES_FLAG_NOCHECKRESP 105 flag was specified at channel initialization time; otherwise, such 106 responses are ignored at the 107 .BR ares_send (3) 108 level.) 109 .TP 19 110 .B ARES_EREFUSED 111 A query completed but the server refused the query. (This code can 112 only occur returned if the 113 .B ARES_FLAG_NOCHECKRESP 114 flag was specified at channel initialization time; otherwise, such 115 responses are ignored at the 116 .BR ares_send (3) 117 level.) 118 .TP 19 119 .B ARES_TIMEOUT 120 No name servers responded to a query within the timeout period. 121 .TP 19 122 .B ARES_ECONNREFUSED 123 No name servers could be contacted. 124 .TP 19 125 .B ARES_ENOMEM 126 Memory was exhausted. 127 .TP 19 128 .B ARES_ECANCELLED 129 The query was cancelled. 130 .TP 19 131 .B ARES_EDESTRUCTION 132 The name service channel 133 .I channel 134 is being destroyed; the query will not be completed. 135 .TP 19 136 .B ARES_ENOSERVER 137 No query completed successfully; no DNS servers were configured on the channel. 138 .PP 139 The callback argument 140 .I timeouts 141 reports how many times a query timed out during the execution of the 142 given request. 143 .PP 144 If a query completed successfully, the callback argument 145 .I abuf 146 points to a result buffer of length 147 .IR alen . 148 If the query did not complete successfully, 149 .I abuf 150 will usually be NULL and 151 .I alen 152 will usually be 0, but in some cases an unsuccessful query result may 153 be placed in 154 .IR abuf . 155 156 The \fIares_search_dnsrec(3)\fP function behaves identically to 157 \fIares_search(3)\fP, but takes an initialized and filled DNS record object to 158 use for queries as the second argument 159 .I dnsrec 160 instead of a name, class and type. This object is used as the base for the 161 queries and must itself represent a valid query for a single name. Note that 162 the search domains will only be appended to the name in the question section; 163 RRs on the DNS record object will not be affected. Moreover, the 164 .I callback 165 argument is of type \fIares_callback_dnsrec\fP. This callback behaves 166 identically to \fIares_callback\fP, but is invoked with a parsed DNS record 167 object 168 .I dnsrec 169 rather than a raw buffer with length. Note that this object is read-only. 170 171 The \fIares_search_dnsrec(3)\fP function returns an \fIares_status_t\fP response 172 code. This may be useful to know that the query was enqueued properly. The 173 response code does not reflect the result of the query, just the result of the 174 enqueuing of the query. 175 176 .SH AVAILABILITY 177 \fBares_search_dnsrec(3)\fP was introduced in c-ares 1.28.0. 178 179 .SH SEE ALSO 180 .BR ares_process (3), 181 .BR ares_dns_record (3)