jpayne@68: .\" jpayne@68: .\" Copyright 1998 by the Massachusetts Institute of Technology. jpayne@68: .\" SPDX-License-Identifier: MIT jpayne@68: .\" jpayne@68: .TH ARES_QUERY 3 "24 July 1998" jpayne@68: .SH NAME jpayne@68: ares_query \- Initiate a single-question 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_query_dnsrec(ares_channel_t *channel, jpayne@68: const char *name, jpayne@68: ares_dns_class_t dnsclass, jpayne@68: ares_dns_rec_type_t type, jpayne@68: ares_callback_dnsrec callback, jpayne@68: void *arg, jpayne@68: 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_query(ares_channel_t *channel, const char *name, jpayne@68: int dnsclass, int type, jpayne@68: ares_callback callback, void *arg); jpayne@68: jpayne@68: .fi jpayne@68: jpayne@68: .SH DESCRIPTION jpayne@68: jpayne@68: The \fBares_query_dnsrec(3)\fP and \fBares_query(3)\fP functions initiate a jpayne@68: single-question DNS query on the name service channel identified by jpayne@68: .IR channel . jpayne@68: The parameter jpayne@68: .I name jpayne@68: gives the query name as a NUL-terminated C string of period-separated jpayne@68: labels optionally ending with a period; periods and backslashes within jpayne@68: 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. jpayne@68: jpayne@68: \fBares_query_dnsrec(3)\fP uses the ares \fBares_dns_class_t\fP and jpayne@68: \fBares_dns_rec_type_t\fP defined types. However, \fBares_query(3)\fP uses jpayne@68: the values defined in \fB\fP. jpayne@68: jpayne@68: When the query is complete or has failed, the ares library will invoke jpayne@68: .IR callback . jpayne@68: Completion or failure of the query may happen immediately (even before the jpayne@68: return of the function call), or may happen during a later call to jpayne@68: \fBares_process(3)\fP or \fBares_destroy(3)\fP. jpayne@68: 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: jpayne@68: The callback argument jpayne@68: .I arg jpayne@68: is copied from the \fBares_query_dnsrec(3)\fP or \fBares_query(3)\fP argument jpayne@68: .IR arg . 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 successfully. jpayne@68: .TP 19 jpayne@68: .B ARES_ENODATA jpayne@68: The query completed but contains no answers. jpayne@68: .TP 19 jpayne@68: .B ARES_EFORMERR jpayne@68: The query completed but the server claims that the query was jpayne@68: malformatted. jpayne@68: .TP 19 jpayne@68: .B ARES_ESERVFAIL jpayne@68: The query completed but the server claims 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 \fBares_send_dnsrec(3)\fP level.) jpayne@68: .TP 19 jpayne@68: .B ARES_ENOTFOUND jpayne@68: The query completed but the queried-for domain name was not found. jpayne@68: .TP 19 jpayne@68: .B ARES_ENOTIMP jpayne@68: The 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 \fBares_send_dnsrec(3)\fP level.) jpayne@68: .TP 19 jpayne@68: .B ARES_EREFUSED jpayne@68: The query completed but the server refused the query. (This code can jpayne@68: 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 \fBares_send_dnsrec(3)\fP level.) jpayne@68: .TP 19 jpayne@68: .B ARES_EBADNAME jpayne@68: The query name jpayne@68: .I name jpayne@68: could not be encoded as a domain name, either because it contained a jpayne@68: zero-length label or because it contained a label of more than 63 jpayne@68: characters. 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: .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 (even if there was something wrong with it, as jpayne@68: indicated by some of the above error codes), the callback argument jpayne@68: .I dnsrec jpayne@68: or jpayne@68: .I abuf jpayne@68: will be non-NULL, otherwise they will be NULL. jpayne@68: jpayne@68: .SH AVAILABILITY jpayne@68: \fBares_query_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)