Spaces:
Running
Running
File size: 5,329 Bytes
1d777c4 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 |
.\"
.\" Copyright 1998 by the Massachusetts Institute of Technology.
.\"
.\" Permission to use, copy, modify, and distribute this
.\" software and its documentation for any purpose and without
.\" fee is hereby granted, provided that the above copyright
.\" notice appear in all copies and that both that copyright
.\" notice and this permission notice appear in supporting
.\" documentation, and that the name of M.I.T. not be used in
.\" advertising or publicity pertaining to distribution of the
.\" software without specific, written prior permission.
.\" M.I.T. makes no representations about the suitability of
.\" this software for any purpose. It is provided "as is"
.\" without express or implied warranty.
.\"
.TH ARES_GETADDRINFO 3 "4 November 2018"
.SH NAME
ares_getaddrinfo \- Initiate a host query by name and service
.SH SYNOPSIS
.nf
#include <ares.h>
typedef void (*ares_addrinfo_callback)(void *\fIarg\fP, int \fIstatus\fP,
int \fItimeouts\fP,
struct ares_addrinfo *\fIresult\fP)
void ares_getaddrinfo(ares_channel \fIchannel\fP, const char *\fIname\fP,
const char* \fIservice\fP,
const struct ares_addrinfo_hints *\fIhints\fP,
ares_addrinfo_callback \fIcallback\fP, void *\fIarg\fP)
.fi
.SH DESCRIPTION
The
.B ares_getaddrinfo
function initiates a host query by name on the name service channel
identified by
.IR channel .
The
.I name
and
.I service
parameters give the hostname and service as NULL-terminated C strings.
The
.I hints
parameter is an
.BR ares_addrinfo_hints
structure:
.PP
.RS
.EX
struct ares_addrinfo_hints {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
};
.EE
.RE
.TP
.I ai_family
Specifies desired address family. AF_UNSPEC means return both AF_INET and AF_INET6.
.TP
.I ai_socktype
Specifies desired socket type, for example SOCK_STREAM or SOCK_DGRAM.
Setting this to 0 means any type.
.TP
.I ai_protocol
Setting this to 0 means any protocol.
.TP
.I ai_flags
Specifies additional options, see below.
.PP
.TP 19
.B ARES_AI_NUMERICSERV
If this option is set
.I service
field will be treated as a numeric value.
.TP 19
.B ARES_AI_CANONNAME
The ares_addrinfo structure will return a canonical names list.
.TP 19
.B ARES_AI_NOSORT
Result addresses will not be sorted and no connections to resolved addresses will be attempted.
.TP 19
.B ARES_AI_ENVHOSTS
Read hosts file path from the environment variable
.I CARES_HOSTS .
.PP
When the query is complete or has failed, the ares library will invoke \fIcallback\fP.
Completion or failure of the query may happen immediately, or may happen
during a later call to \fIares_process(3)\fP, \fIares_destroy(3)\fP or
\fIares_cancel(3)\fP.
.PP
The callback argument
.I arg
is copied from the
.B ares_getaddrinfo
argument
.IR arg .
The callback argument
.I status
indicates whether the query succeeded and, if not, how it failed. It
may have any of the following values:
.TP 19
.B ARES_SUCCESS
The host lookup completed successfully.
.TP 19
.B ARES_ENOTIMP
The ares library does not know how to find addresses of type
.IR family .
.TP 19
.B ARES_ENOTFOUND
The
.I name
was not found.
.TP 19
.B ARES_ENOMEM
Memory was exhausted.
.TP 19
.B ARES_ECANCELLED
The query was cancelled.
.TP 19
.B ARES_EDESTRUCTION
The name service channel
.I channel
is being destroyed; the query will not be completed.
.PP
On successful completion of the query, the callback argument
.I result
points to a
.B struct ares_addrinfo
which contains two linked lists, one with resolved addresses and another with canonical names.
Also included is the official name of the host (analogous to gethostbyname() h_name).
.PP
.RS
.EX
struct ares_addrinfo {
struct ares_addrinfo_cname *cnames;
struct ares_addrinfo_node *nodes;
char *name;
};
.EE
.RE
.PP
.I ares_addrinfo_node
structure is similar to RFC3493 addrinfo, but without canonname and with extra ttl field.
.RS
.PP
.EX
struct ares_addrinfo_node {
int ai_ttl;
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
ares_socklen_t ai_addrlen;
struct sockaddr *ai_addr;
struct ares_addrinfo_node *ai_next;
};
.EE
.RE
.PP
.I ares_addrinfo_cname
structure is a linked list of CNAME records where
.I ttl
is a time to live
.I alias
is a label of the resource record and
.I name
is a value (canonical name) of the resource record.
See RFC2181 10.1.1. CNAME terminology.
.RS
.PP
.EX
struct ares_addrinfo_cname {
int ttl;
char *alias;
char *name;
struct ares_addrinfo_cname *next;
};
.EE
.RE
.PP
The reserved memory has to be deleted by
.B ares_freeaddrinfo.
The result is sorted according to RFC6724 except:
- Rule 3 (Avoid deprecated addresses)
- Rule 4 (Prefer home addresses)
- Rule 7 (Prefer native transport)
Please note that the function will attempt a connection
on each of the resolved addresses as per RFC6724.
.SH AVAILABILITY
This function was added in c-ares 1.16.0, released in March 2020.
.SH SEE ALSO
.BR ares_freeaddrinfo (3)
.SH AUTHOR
Christian Ammer
.br
Andrew Selivanov <[email protected]>
|