ares_getaddrinfo.3 (5238B)
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)