ares_getaddrinfo(3)

1ARES_GETADDRINFO(3)        Library Functions Manual        ARES_GETADDRINFO(3)
2
3
4

NAME

6       ares_getaddrinfo - Initiate a host query by name and service
7

SYNOPSIS

9       #include <ares.h>
10
11       typedef void (*ares_addrinfo_callback)(void *arg, int status,
12                                              int timeouts,
13                                              struct ares_addrinfo *result)
14
15       void ares_getaddrinfo(ares_channel channel, const char *name,
16                             const char* service,
17                             const struct ares_addrinfo_hints *hints,
18                             ares_addrinfo_callback callback, void *arg)
19

DESCRIPTION

21       The  ares_getaddrinfo(3) function initiates a host query by name on the
22       name service channel identified by channel.  The name and  service  pa‐
23       rameters  give  the  hostname and service as NULL-terminated C strings.
24       The hints parameter is an ares_addrinfo_hints structure:
25
26              struct ares_addrinfo_hints {
27                int ai_flags;
28                int ai_family;
29                int ai_socktype;
30                int ai_protocol;
31              };
32
33       ai_family
34              Specifies desired address family. AF_UNSPEC  means  return  both
35              AF_INET and AF_INET6.
36
37       ai_socktype
38              Specifies  desired  socket  type,  for  example  SOCK_STREAM  or
39              SOCK_DGRAM.  Setting this to 0 means any type.
40
41       ai_protocol
42              Setting this to 0 means any protocol.
43
44       ai_flags
45              Specifies additional options, see below.
46
47       ARES_AI_NUMERICSERV
48                          If this option is set service field will be  treated
49                          as a numeric value.
50
51       ARES_AI_CANONNAME  The  ares_addrinfo structure will return a canonical
52                          names list.
53
54       ARES_AI_NOSORT     Result addresses will not be sorted and  no  connec‐
55                          tions to resolved addresses will be attempted.
56
57       ARES_AI_ENVHOSTS   Read  hosts  file path from the environment variable
58                          CARES_HOSTS .
59
60       When the query is complete or has failed, the ares library will  invoke
61       callback.   Completion  or failure of the query may happen immediately,
62       or may happen during a later call to  ares_process(3),  ares_destroy(3)
63       or ares_cancel(3).
64
65       The  callback argument arg is copied from the ares_getaddrinfo(3) argu‐
66       ment arg.  The callback argument status  indicates  whether  the  query
67       succeeded and, if not, how it failed.  It may have any of the following
68       values:
69
70       ARES_SUCCESS       The host lookup completed successfully.
71
72       ARES_ENOTIMP       The ares library does not know how to find addresses
73                          of type family.
74
75       ARES_ENOTFOUND     The name was not found.
76
77       ARES_ENOMEM        Memory was exhausted.
78
79       ARES_ECANCELLED    The query was cancelled.
80
81       ARES_EDESTRUCTION  The name service channel channel is being destroyed;
82                          the query will not be completed.
83
84       On successful completion of the query,  the  callback  argument  result
85       points  to  a struct ares_addrinfo which contains two linked lists, one
86       with resolved addresses and another with  canonical  names.   Also  in‐
87       cluded  is  the official name of the host (analogous to gethostbyname()
88       h_name).
89
90              struct ares_addrinfo {
91                struct ares_addrinfo_cname *cnames;
92                struct ares_addrinfo_node  *nodes;
93                char *name;
94              };
95
96       ares_addrinfo_node structure is similar to RFC3493 addrinfo, but  with‐
97       out canonname and with extra ttl field.
98
99              struct ares_addrinfo_node {
100                int                        ai_ttl;
101                int                        ai_flags;
102                int                        ai_family;
103                int                        ai_socktype;
104                int                        ai_protocol;
105                ares_socklen_t             ai_addrlen;
106                struct sockaddr           *ai_addr;
107                struct ares_addrinfo_node *ai_next;
108              };
109
110       ares_addrinfo_cname  structure  is a linked list of CNAME records where
111       ttl is a time to live alias is a label of the resource record and  name
112       is  a  value  (canonical  name)  of  the  resource record.  See RFC2181
113       10.1.1. CNAME terminology.
114
115              struct ares_addrinfo_cname {
116                int                         ttl;
117                char                       *alias;
118                char                       *name;
119                struct ares_addrinfo_cname *next;
120              };
121
122       The reserved memory has to be deleted by ares_freeaddrinfo(3).
123
124       The result is sorted according to RFC6724 except:
125        - Rule 3 (Avoid deprecated addresses)
126        - Rule 4 (Prefer home addresses)
127        - Rule 7 (Prefer native transport)
128
129       Please note that the function will attempt a connection on each of  the
130       resolved addresses as per RFC6724.
131

AVAILABILITY

133       This function was added in c-ares 1.16.0, released in March 2020.
134

AUTHOR

139       Christian Ammer
140       Andrew Selivanov <andrew.selivanov@gmail.com>
141
142
143
144                                4 November 2018            ARES_GETADDRINFO(3)

NAME

SYNOPSIS

DESCRIPTION

AVAILABILITY

SEE ALSO

AUTHOR