Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/ares_send.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
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
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)