1ARES_GETADDRINFO(3) Library Functions Manual ARES_GETADDRINFO(3)
2
6 ares_getaddrinfo - Initiate a host query by name and service
7
9 #include <ares.h>
10 typedef void (*ares_addrinfo_callback)(void *arg, int status,
12 int timeouts, struct ares_addrinfo *result)
13 void ares_getaddrinfo(ares_channel channel, const char *name,
15 const char* service, const struct ares_addrinfo_hints *hints,
16 ares_addrinfo_callback callback, void *arg)
17
19 The ares_getaddrinfo function initiates a host query by name on the
20 name service channel identified by channel. The name and service
21 parameters give the hostname and service as NULL-terminated C strings.
22 The hints parameter is an ares_addrinfo_hints structure:
23 struct ares_addrinfo_hints {
25 int ai_flags;
26 int ai_family;
27 int ai_socktype;
28 int ai_protocol;
29 };
30 ai_family
32 Specifies desired address family. AF_UNSPEC means return both
33 AF_INET and AF_INET6.
34 ai_socktype
36 Specifies desired socket type, for example SOCK_STREAM or
37 SOCK_DGRAM. Setting this to 0 means any type.
38 ai_protocol
40 Setting this to 0 means any protocol.
41 ai_flags
43 Specifies additional options, see below.
44 ARES_AI_NUMERICSERV
46 If this option is set service field will be treated
47 as a numeric value.
48 ARES_AI_CANONNAME The ares_addrinfo structure will return a canonical
50 names list.
51 ARES_AI_NOSORT Result addresses will not be sorted and no connec‐
53 tions to resolved addresses will be attempted.
54 ARES_AI_ENVHOSTS Read hosts file path from the environment variable
56 CARES_HOSTS .
57 When the query is complete or has failed, the ares library will invoke
59 callback. Completion or failure of the query may happen immediately,
60 or may happen during a later call to ares_process(3), ares_destroy(3)
61 or ares_cancel(3).
62 The callback argument arg is copied from the ares_getaddrinfo argument
64 arg. The callback argument status indicates whether the query suc‐
65 ceeded and, if not, how it failed. It may have any of the following
66 values:
67 ARES_SUCCESS The host lookup completed successfully.
69 ARES_ENOTIMP The ares library does not know how to find addresses
71 of type family.
72 ARES_ENOTFOUND The name was not found.
74 ARES_ENOMEM Memory was exhausted.
76 ARES_ECANCELLED The query was cancelled.
78 ARES_EDESTRUCTION The name service channel channel is being destroyed;
80 the query will not be completed.
81 On successful completion of the query, the callback argument result
83 points to a struct ares_addrinfo which contains two linked lists, one
84 with resolved addresses and another with canonical names.
85 struct ares_addrinfo {
87 struct ares_addrinfo_cname *cnames;
88 struct ares_addrinfo_node *nodes;
89 };
90 ares_addrinfo_node structure is similar to RFC3493 addrinfo, but with‐
92 out canonname and with extra ttl field.
93 struct ares_addrinfo_node {
95 int ai_ttl;
96 int ai_flags;
97 int ai_family;
98 int ai_socktype;
99 int ai_protocol;
100 ares_socklen_t ai_addrlen;
101 struct sockaddr *ai_addr;
102 struct ares_addrinfo_node *ai_next;
103 };
104 ares_addrinfo_cname structure is a linked list of CNAME records where
106 ttl is a time to live alias is a label of the resource record and name
107 is a value (canonical name) of the resource record. See RFC2181
108 10.1.1. CNAME terminology.
109 struct ares_addrinfo_cname {
111 int ttl;
112 char *alias;
113 char *name;
114 struct ares_addrinfo_cname *next;
115 };
116 The reserved memory has to be deleted by ares_freeaddrinfo.
118 The result is sorted according to RFC6724 except:
120 - Rule 3 (Avoid deprecated addresses)
121 - Rule 4 (Prefer home addresses)
122 - Rule 7 (Prefer native transport)
123 Please note that the function will attempt a connection on each of the
125 resolved addresses as per RFC6724.
126
128 ares_freeaddrinfo(3)
129
131 Christian Ammer
132 Andrew Selivanov <andrew.selivanov@gmail.com>
133 4 November 2018 ARES_GETADDRINFO(3)