Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/ares_query.3 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 .\"
jpayne@68 2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
jpayne@68 3 .\" SPDX-License-Identifier: MIT
jpayne@68 4 .\"
jpayne@68 5 .TH ARES_QUERY 3 "24 July 1998"
jpayne@68 6 .SH NAME
jpayne@68 7 ares_query \- Initiate a single-question DNS query
jpayne@68 8 .SH SYNOPSIS
jpayne@68 9 .nf
jpayne@68 10 #include <ares.h>
jpayne@68 11
jpayne@68 12 typedef void (*ares_callback_dnsrec)(void *arg, ares_status_t status,
jpayne@68 13 size_t timeouts,
jpayne@68 14 const ares_dns_record_t *dnsrec);
jpayne@68 15
jpayne@68 16 ares_status_t ares_query_dnsrec(ares_channel_t *channel,
jpayne@68 17 const char *name,
jpayne@68 18 ares_dns_class_t dnsclass,
jpayne@68 19 ares_dns_rec_type_t type,
jpayne@68 20 ares_callback_dnsrec callback,
jpayne@68 21 void *arg,
jpayne@68 22 unsigned short *qid);
jpayne@68 23
jpayne@68 24 typedef void (*ares_callback)(void *arg, int status,
jpayne@68 25 int timeouts, unsigned char *abuf,
jpayne@68 26 int alen);
jpayne@68 27
jpayne@68 28 void ares_query(ares_channel_t *channel, const char *name,
jpayne@68 29 int dnsclass, int type,
jpayne@68 30 ares_callback callback, void *arg);
jpayne@68 31
jpayne@68 32 .fi
jpayne@68 33
jpayne@68 34 .SH DESCRIPTION
jpayne@68 35
jpayne@68 36 The \fBares_query_dnsrec(3)\fP and \fBares_query(3)\fP functions initiate a
jpayne@68 37 single-question DNS query on the name service channel identified by
jpayne@68 38 .IR channel .
jpayne@68 39 The parameter
jpayne@68 40 .I name
jpayne@68 41 gives the query name as a NUL-terminated C string of period-separated
jpayne@68 42 labels optionally ending with a period; periods and backslashes within
jpayne@68 43 a label must be escaped with a backslash. The parameters
jpayne@68 44 .I dnsclass
jpayne@68 45 and
jpayne@68 46 .I type
jpayne@68 47 give the class and type of the query.
jpayne@68 48
jpayne@68 49 \fBares_query_dnsrec(3)\fP uses the ares \fBares_dns_class_t\fP and
jpayne@68 50 \fBares_dns_rec_type_t\fP defined types. However, \fBares_query(3)\fP uses
jpayne@68 51 the values defined in \fB<arpa/nameser.h>\fP.
jpayne@68 52
jpayne@68 53 When the query is complete or has failed, the ares library will invoke
jpayne@68 54 .IR callback .
jpayne@68 55 Completion or failure of the query may happen immediately (even before the
jpayne@68 56 return of the function call), or may happen during a later call to
jpayne@68 57 \fBares_process(3)\fP or \fBares_destroy(3)\fP.
jpayne@68 58
jpayne@68 59 If this is called from a thread other than which the main program event loop is
jpayne@68 60 running, care needs to be taken to ensure any file descriptor lists are updated
jpayne@68 61 immediately within the eventloop. When the associated callback is called,
jpayne@68 62 it is called with a channel lock so care must be taken to ensure any processing
jpayne@68 63 is minimal to prevent DNS channel stalls.
jpayne@68 64
jpayne@68 65 The callback argument
jpayne@68 66 .I arg
jpayne@68 67 is copied from the \fBares_query_dnsrec(3)\fP or \fBares_query(3)\fP argument
jpayne@68 68 .IR arg .
jpayne@68 69 The callback argument
jpayne@68 70 .I status
jpayne@68 71 indicates whether the query succeeded and, if not, how it failed. It
jpayne@68 72 may have any of the following values:
jpayne@68 73 .TP 19
jpayne@68 74 .B ARES_SUCCESS
jpayne@68 75 The query completed successfully.
jpayne@68 76 .TP 19
jpayne@68 77 .B ARES_ENODATA
jpayne@68 78 The query completed but contains no answers.
jpayne@68 79 .TP 19
jpayne@68 80 .B ARES_EFORMERR
jpayne@68 81 The query completed but the server claims that the query was
jpayne@68 82 malformatted.
jpayne@68 83 .TP 19
jpayne@68 84 .B ARES_ESERVFAIL
jpayne@68 85 The query completed but the server claims to have experienced a
jpayne@68 86 failure. (This code can only occur if the
jpayne@68 87 .B ARES_FLAG_NOCHECKRESP
jpayne@68 88 flag was specified at channel initialization time; otherwise, such
jpayne@68 89 responses are ignored at the \fBares_send_dnsrec(3)\fP level.)
jpayne@68 90 .TP 19
jpayne@68 91 .B ARES_ENOTFOUND
jpayne@68 92 The query completed but the queried-for domain name was not found.
jpayne@68 93 .TP 19
jpayne@68 94 .B ARES_ENOTIMP
jpayne@68 95 The query completed but the server does not implement the operation
jpayne@68 96 requested by the query. (This code can only occur if the
jpayne@68 97 .B ARES_FLAG_NOCHECKRESP
jpayne@68 98 flag was specified at channel initialization time; otherwise, such
jpayne@68 99 responses are ignored at the \fBares_send_dnsrec(3)\fP level.)
jpayne@68 100 .TP 19
jpayne@68 101 .B ARES_EREFUSED
jpayne@68 102 The query completed but the server refused the query. (This code can
jpayne@68 103 only occur if the
jpayne@68 104 .B ARES_FLAG_NOCHECKRESP
jpayne@68 105 flag was specified at channel initialization time; otherwise, such
jpayne@68 106 responses are ignored at the \fBares_send_dnsrec(3)\fP level.)
jpayne@68 107 .TP 19
jpayne@68 108 .B ARES_EBADNAME
jpayne@68 109 The query name
jpayne@68 110 .I name
jpayne@68 111 could not be encoded as a domain name, either because it contained a
jpayne@68 112 zero-length label or because it contained a label of more than 63
jpayne@68 113 characters.
jpayne@68 114 .TP 19
jpayne@68 115 .B ARES_ETIMEOUT
jpayne@68 116 No name servers responded within the timeout period.
jpayne@68 117 .TP 19
jpayne@68 118 .B ARES_ECONNREFUSED
jpayne@68 119 No name servers could be contacted.
jpayne@68 120 .TP 19
jpayne@68 121 .B ARES_ENOMEM
jpayne@68 122 Memory was exhausted.
jpayne@68 123 .TP 19
jpayne@68 124 .B ARES_ECANCELLED
jpayne@68 125 The query was cancelled.
jpayne@68 126 .TP 19
jpayne@68 127 .B ARES_EDESTRUCTION
jpayne@68 128 The name service channel
jpayne@68 129 .I channel
jpayne@68 130 is being destroyed; the query will not be completed.
jpayne@68 131 .TP 19
jpayne@68 132 .B ARES_ENOSERVER
jpayne@68 133 The query will not be completed because no DNS servers were configured on the
jpayne@68 134 channel.
jpayne@68 135 .PP
jpayne@68 136
jpayne@68 137 The callback argument
jpayne@68 138 .I timeouts
jpayne@68 139 reports how many times a query timed out during the execution of the
jpayne@68 140 given request.
jpayne@68 141
jpayne@68 142 If the query completed (even if there was something wrong with it, as
jpayne@68 143 indicated by some of the above error codes), the callback argument
jpayne@68 144 .I dnsrec
jpayne@68 145 or
jpayne@68 146 .I abuf
jpayne@68 147 will be non-NULL, otherwise they will be NULL.
jpayne@68 148
jpayne@68 149 .SH AVAILABILITY
jpayne@68 150 \fBares_query_dnsrec(3)\fP was introduced in c-ares 1.28.0.
jpayne@68 151
jpayne@68 152 .SH SEE ALSO
jpayne@68 153 .BR ares_process (3),
jpayne@68 154 .BR ares_dns_record (3)