Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/ares_getaddrinfo.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_GETADDRINFO 3 "4 November 2018"
6 .SH NAME
7 ares_getaddrinfo \- Initiate a host query by name and service
8 .SH SYNOPSIS
9 .nf
10 #include <ares.h>
11
12 typedef void (*ares_addrinfo_callback)(void *\fIarg\fP, int \fIstatus\fP,
13 int \fItimeouts\fP,
14 struct ares_addrinfo *\fIresult\fP)
15
16 void ares_getaddrinfo(ares_channel_t *\fIchannel\fP, const char *\fIname\fP,
17 const char* \fIservice\fP,
18 const struct ares_addrinfo_hints *\fIhints\fP,
19 ares_addrinfo_callback \fIcallback\fP, void *\fIarg\fP)
20 .fi
21 .SH DESCRIPTION
22 The \fBares_getaddrinfo(3)\fP function initiates a host query by name on the
23 name service channel identified by
24 .IR channel .
25 The
26 .I name
27 and
28 .I service
29 parameters give the hostname and service as NULL-terminated C strings.
30 The
31 .I hints
32 parameter is an
33 .BR ares_addrinfo_hints
34 structure:
35 .PP
36 .RS
37 .EX
38 struct ares_addrinfo_hints {
39 int ai_flags;
40 int ai_family;
41 int ai_socktype;
42 int ai_protocol;
43 };
44 .EE
45 .RE
46 .TP
47 .I ai_family
48 Specifies desired address family. AF_UNSPEC means return both AF_INET and AF_INET6.
49 .TP
50 .I ai_socktype
51 Specifies desired socket type, for example SOCK_STREAM or SOCK_DGRAM.
52 Setting this to 0 means any type.
53 .TP
54 .I ai_protocol
55 Setting this to 0 means any protocol.
56 .TP
57 .I ai_flags
58 Specifies additional options, see below.
59 .PP
60 .TP 19
61 .B ARES_AI_NUMERICSERV
62 If this option is set
63 .I service
64 field will be treated as a numeric value.
65 .TP 19
66 .B ARES_AI_CANONNAME
67 The ares_addrinfo structure will return a canonical names list.
68 .TP 19
69 .B ARES_AI_NOSORT
70 Result addresses will not be sorted and no connections to resolved addresses will be attempted.
71 .TP 19
72 .B ARES_AI_ENVHOSTS
73 Read hosts file path from the environment variable
74 .I CARES_HOSTS .
75 .PP
76 When the query is complete or has failed, the ares library will invoke \fIcallback\fP.
77 Completion or failure of the query may happen immediately, or may happen
78 during a later call to \fIares_process(3)\fP, \fIares_destroy(3)\fP or
79 \fIares_cancel(3)\fP.
80 .PP
81 When the associated callback is called, it is called with a channel lock so care
82 must be taken to ensure any processing is minimal to prevent DNS channel stalls.
83
84 The callback may be triggered from a different thread than the one which
85 called \fIares_getaddrinfo(3)\fP.
86
87 For integrators running their own event loops and not using \fBARES_OPT_EVENT_THREAD\fP,
88 care needs to be taken to ensure any file descriptor lists are updated immediately
89 within the eventloop when notified.
90 .PP
91 The callback argument
92 .I arg
93 is copied from the \fBares_getaddrinfo(3)\fP argument
94 .IR arg .
95 The callback argument
96 .I status
97 indicates whether the query succeeded and, if not, how it failed. It
98 may have any of the following values:
99 .TP 19
100 .B ARES_SUCCESS
101 The host lookup completed successfully.
102 .TP 19
103 .B ARES_ENOTIMP
104 The ares library does not know how to find addresses of type
105 .IR family .
106 .TP 19
107 .B ARES_ENOTFOUND
108 The
109 .I name
110 was not found.
111 .TP 19
112 .B ARES_ENOMEM
113 Memory was exhausted.
114 .TP 19
115 .B ARES_ESERVICE
116 The textual service name provided could not be dereferenced into a port.
117 .TP 19
118 .B ARES_ECANCELLED
119 The query was cancelled.
120 .TP 19
121 .B ARES_EDESTRUCTION
122 The name service channel
123 .I channel
124 is being destroyed; the query will not be completed.
125 .PP
126 On successful completion of the query, the callback argument
127 .I result
128 points to a
129 .B struct ares_addrinfo
130 which contains two linked lists, one with resolved addresses and another with canonical names.
131 Also included is the official name of the host (analogous to gethostbyname() h_name).
132 .PP
133 .RS
134 .EX
135 struct ares_addrinfo {
136 struct ares_addrinfo_cname *cnames;
137 struct ares_addrinfo_node *nodes;
138 char *name;
139 };
140 .EE
141 .RE
142 .PP
143 .I ares_addrinfo_node
144 structure is similar to RFC3493 addrinfo, but without canonname and with extra ttl field.
145 .RS
146 .PP
147 .EX
148 struct ares_addrinfo_node {
149 int ai_ttl;
150 int ai_flags;
151 int ai_family;
152 int ai_socktype;
153 int ai_protocol;
154 ares_socklen_t ai_addrlen;
155 struct sockaddr *ai_addr;
156 struct ares_addrinfo_node *ai_next;
157 };
158 .EE
159 .RE
160 .PP
161 .I ares_addrinfo_cname
162 structure is a linked list of CNAME records where
163 .I ttl
164 is a time to live
165 .I alias
166 is a label of the resource record and
167 .I name
168 is a value (canonical name) of the resource record.
169 See RFC2181 10.1.1. CNAME terminology.
170 .RS
171 .PP
172 .EX
173 struct ares_addrinfo_cname {
174 int ttl;
175 char *alias;
176 char *name;
177 struct ares_addrinfo_cname *next;
178 };
179 .EE
180 .RE
181 .PP
182 The reserved memory has to be deleted by \fBares_freeaddrinfo(3)\fP.
183
184 The result is sorted according to RFC6724 except:
185 - Rule 3 (Avoid deprecated addresses)
186 - Rule 4 (Prefer home addresses)
187 - Rule 7 (Prefer native transport)
188
189 Please note that the function will attempt a connection
190 on each of the resolved addresses as per RFC6724.
191 .SH AVAILABILITY
192 This function was added in c-ares 1.16.0, released in March 2020.
193 .SH SEE ALSO
194 .BR ares_freeaddrinfo (3)