jpayne@68: .\" jpayne@68: .\" Copyright 1998 by the Massachusetts Institute of Technology. jpayne@68: .\" SPDX-License-Identifier: MIT jpayne@68: .\" jpayne@68: .TH ARES_SEARCH 3 "24 July 1998" jpayne@68: .SH NAME jpayne@68: ares_search \- Initiate a DNS query with domain search jpayne@68: .SH SYNOPSIS jpayne@68: .nf jpayne@68: #include jpayne@68: jpayne@68: typedef void (*ares_callback_dnsrec)(void *\fIarg\fP, jpayne@68: ares_status_t \fIstatus\fP, jpayne@68: size_t \fItimeouts\fP, jpayne@68: const ares_dns_record_t *\fIdnsrec\fP); jpayne@68: jpayne@68: void ares_search_dnsrec(ares_channel_t *\fIchannel\fP, jpayne@68: const ares_dns_record_t *\fIdnsrec\fP, jpayne@68: ares_callback_dnsrec \fIcallback\fP, void *\fIarg\fP); jpayne@68: jpayne@68: typedef void (*ares_callback)(void *\fIarg\fP, int \fIstatus\fP, jpayne@68: int \fItimeouts\fP, unsigned char *\fIabuf\fP, jpayne@68: int \fIalen\fP); jpayne@68: jpayne@68: void ares_search(ares_channel_t *\fIchannel\fP, const char *\fIname\fP, jpayne@68: int \fIdnsclass\fP, int \fItype\fP, jpayne@68: ares_callback \fIcallback\fP, void *\fIarg\fP); jpayne@68: jpayne@68: .fi jpayne@68: .SH DESCRIPTION jpayne@68: The jpayne@68: .B ares_search jpayne@68: function initiates a series of single-question DNS queries on the name jpayne@68: service channel identified by jpayne@68: .IR channel , jpayne@68: using the channel's search domains as well as a host alias file given jpayne@68: by the HOSTALIAS environment variable. The parameter jpayne@68: .I name jpayne@68: gives the alias name or the base of the query name as a NUL-terminated jpayne@68: C string of period-separated labels; if it ends with a period, the jpayne@68: channel's search domains will not be used. Periods and backslashes jpayne@68: within a label must be escaped with a backslash. The parameters jpayne@68: .I dnsclass jpayne@68: and jpayne@68: .I type jpayne@68: give the class and type of the query using the values defined in jpayne@68: .BR . jpayne@68: When the query sequence is complete or has failed, the ares library jpayne@68: will invoke jpayne@68: .IR callback . jpayne@68: Completion or failure of the query sequence may happen immediately, or jpayne@68: may happen during a later call to jpayne@68: .BR ares_process (3) jpayne@68: or jpayne@68: .BR ares_destroy (3). jpayne@68: .PP jpayne@68: If this is called from a thread other than which the main program event loop is jpayne@68: running, care needs to be taken to ensure any file descriptor lists are updated jpayne@68: immediately within the eventloop. When the associated callback is called, jpayne@68: it is called with a channel lock so care must be taken to ensure any processing jpayne@68: is minimal to prevent DNS channel stalls. jpayne@68: .PP jpayne@68: The callback argument jpayne@68: .I arg jpayne@68: is copied from the jpayne@68: .B ares_search jpayne@68: argument jpayne@68: .IR arg . jpayne@68: The callback argument jpayne@68: .I status jpayne@68: indicates whether the query sequence ended with a successful query jpayne@68: and, if not, how the query sequence failed. It may have any of the jpayne@68: following values: jpayne@68: .TP 19 jpayne@68: .B ARES_SUCCESS jpayne@68: A query completed successfully. jpayne@68: .TP 19 jpayne@68: .B ARES_ENODATA jpayne@68: No query completed successfully; when the query was tried without a jpayne@68: search domain appended, a response was returned with no answers. jpayne@68: .TP 19 jpayne@68: .B ARES_EFORMERR jpayne@68: A query completed but the server claimed that the query was jpayne@68: malformatted. jpayne@68: .TP 19 jpayne@68: .B ARES_ESERVFAIL jpayne@68: No query completed successfully; when the query was tried without a jpayne@68: search domain appended, the server claimed to have experienced a jpayne@68: failure. (This code can only occur if the jpayne@68: .B ARES_FLAG_NOCHECKRESP jpayne@68: flag was specified at channel initialization time; otherwise, such jpayne@68: responses are ignored at the jpayne@68: .BR ares_send (3) jpayne@68: level.) jpayne@68: .TP 19 jpayne@68: .B ARES_ENOTFOUND jpayne@68: No query completed successfully; when the query was tried without a jpayne@68: search domain appended, the server reported that the queried-for jpayne@68: domain name was not found. jpayne@68: .TP 19 jpayne@68: .B ARES_ENOTIMP jpayne@68: A query completed but the server does not implement the operation jpayne@68: requested by the query. (This code can only occur if the jpayne@68: .B ARES_FLAG_NOCHECKRESP jpayne@68: flag was specified at channel initialization time; otherwise, such jpayne@68: responses are ignored at the jpayne@68: .BR ares_send (3) jpayne@68: level.) jpayne@68: .TP 19 jpayne@68: .B ARES_EREFUSED jpayne@68: A query completed but the server refused the query. (This code can jpayne@68: only occur returned if the jpayne@68: .B ARES_FLAG_NOCHECKRESP jpayne@68: flag was specified at channel initialization time; otherwise, such jpayne@68: responses are ignored at the jpayne@68: .BR ares_send (3) jpayne@68: level.) jpayne@68: .TP 19 jpayne@68: .B ARES_TIMEOUT jpayne@68: No name servers responded to a query 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: No query completed successfully; no DNS servers were configured on the channel. jpayne@68: .PP 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: .PP jpayne@68: If a query completed successfully, the callback argument jpayne@68: .I abuf jpayne@68: points to a result buffer of length jpayne@68: .IR alen . jpayne@68: If the query did not complete successfully, jpayne@68: .I abuf jpayne@68: will usually be NULL and jpayne@68: .I alen jpayne@68: will usually be 0, but in some cases an unsuccessful query result may jpayne@68: be placed in jpayne@68: .IR abuf . jpayne@68: jpayne@68: The \fIares_search_dnsrec(3)\fP function behaves identically to jpayne@68: \fIares_search(3)\fP, but takes an initialized and filled DNS record object to jpayne@68: use for queries as the second argument jpayne@68: .I dnsrec jpayne@68: instead of a name, class and type. This object is used as the base for the jpayne@68: queries and must itself represent a valid query for a single name. Note that jpayne@68: the search domains will only be appended to the name in the question section; jpayne@68: RRs on the DNS record object will not be affected. Moreover, the jpayne@68: .I callback jpayne@68: argument is of type \fIares_callback_dnsrec\fP. This callback behaves jpayne@68: identically to \fIares_callback\fP, but is invoked with a parsed DNS record jpayne@68: object jpayne@68: .I dnsrec jpayne@68: rather than a raw buffer with length. Note that this object is read-only. jpayne@68: jpayne@68: The \fIares_search_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: .SH AVAILABILITY jpayne@68: \fBares_search_dnsrec(3)\fP was introduced in c-ares 1.28.0. jpayne@68: jpayne@68: .SH SEE ALSO jpayne@68: .BR ares_process (3), jpayne@68: .BR ares_dns_record (3)