docs/ares_getaddrinfo.3

   1 .\"
   2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this
   5 .\" software and its documentation for any purpose and without
   6 .\" fee is hereby granted, provided that the above copyright
   7 .\" notice appear in all copies and that both that copyright
   8 .\" notice and this permission notice appear in supporting
   9 .\" documentation, and that the name of M.I.T. not be used in
  10 .\" advertising or publicity pertaining to distribution of the
  11 .\" software without specific, written prior permission.
  12 .\" M.I.T. makes no representations about the suitability of
  13 .\" this software for any purpose.  It is provided "as is"
  14 .\" without express or implied warranty.
  15 .\"
  16 .TH ARES_GETADDRINFO 3 "4 November 2018"
  17 .SH NAME
  18 ares_getaddrinfo \- Initiate a host query by name and service
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <ares.h>
  22 .PP
  23 .B typedef void (*ares_addrinfo_callback)(void *\fIarg\fP, int \fIstatus\fP,
  24 .B      int \fItimeouts\fP, struct ares_addrinfo *\fIresult\fP)
  25 .PP
  26 .B void ares_getaddrinfo(ares_channel \fIchannel\fP, const char *\fIname\fP,
  27 .B      const char* \fIservice\fP, const struct ares_addrinfo_hints *\fIhints\fP,
  28 .B      ares_addrinfo_callback \fIcallback\fP, void *\fIarg\fP)
  29 .fi
  30 .SH DESCRIPTION
  31 The
  32 .B ares_getaddrinfo
  33 function initiates a host query by name on the name service channel
  34 identified by
  35 .IR channel .
  36 The
  37 .I name
  38 and
  39 .I service
  40 parameters give the hostname and service as NULL-terminated C strings.
  41 The
  42 .I hints
  43 parameter is an
  44 .BR ares_addrinfo_hints
  45 structure:
  46 .PP
  47 .RS
  48 .EX
  49 struct ares_addrinfo_hints {
  50   int ai_flags;
  51   int ai_family;
  52   int ai_socktype;
  53   int ai_protocol;
  54 };
  55 .EE
  56 .RE
  57 .TP
  58 .I ai_family
  59 Specifies desired address family. AF_UNSPEC means return both AF_INET and AF_INET6.
  60 .TP
  61 .I ai_socktype
  62 Specifies desired socket type, for example SOCK_STREAM or SOCK_DGRAM.
  63 Setting this to 0 means any type.
  64 .TP
  65 .I ai_protocol
  66 Setting this to 0 means any protocol.
  67 .TP
  68 .I ai_flags
  69 Specifies additional options, see below.
  70 .PP
  71 .TP 19
  72 .B ARES_AI_NUMERICSERV
  73 If this option is set
  74 .I service
  75 field will be treated as a numeric value.
  76 .TP 19
  77 .B ARES_AI_CANONNAME
  78 The ares_addrinfo structure will return a canonical names list.
  79 .TP 19
  80 .B ARES_AI_NOSORT
  81 Result addresses will not be sorted and no connections to resolved addresses will be attempted.
  82 .TP 19
  83 .B ARES_AI_ENVHOSTS
  84 Read hosts file path from the environment variable
  85 .I CARES_HOSTS .
  86 .PP
  87 When the query is complete or has failed, the ares library will invoke \fIcallback\fP.
  88 Completion or failure of the query may happen immediately, or may happen
  89 during a later call to \fIares_process(3)\fP, \fIares_destroy(3)\fP or
  90 \fIares_cancel(3)\fP.
  91 .PP
  92 The callback argument
  93 .I arg
  94 is copied from the
  95 .B ares_getaddrinfo
  96 argument
  97 .IR arg .
  98 The callback argument
  99 .I status
 100 indicates whether the query succeeded and, if not, how it failed.  It
 101 may have any of the following values:
 102 .TP 19
 103 .B ARES_SUCCESS
 104 The host lookup completed successfully.
 105 .TP 19
 106 .B ARES_ENOTIMP
 107 The ares library does not know how to find addresses of type
 108 .IR family .
 109 .TP 19
 110 .B ARES_ENOTFOUND
 111 The
 112 .I name
 113 was not found.
 114 .TP 19
 115 .B ARES_ENOMEM
 116 Memory was exhausted.
 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
 183 .B ares_freeaddrinfo.
 184
 185 The result is sorted according to RFC6724 except:
 186  - Rule 3 (Avoid deprecated addresses)
 187  - Rule 4 (Prefer home addresses)
 188  - Rule 7 (Prefer native transport)
 189
 190 Please note that the function will attempt a connection
 191 on each of the resolved addresses as per RFC6724.
 192 .SH AVAILABILITY
 193 This function was added in c-ares 1.16.0, released in March 2020.
 194 .SH SEE ALSO
 195 .BR ares_freeaddrinfo (3)
 196 .SH AUTHOR
 197 Christian Ammer
 198 .br
 199 Andrew Selivanov <andrew.selivanov@gmail.com>