ares_getaddrinfo - Initiate a host query by name and service
#include <ares.h> typedef void (*ares_addrinfo_callback)(void *arg, int status, int timeouts, struct ares_addrinfo *result) void ares_getaddrinfo(ares_channel channel, const char *name, const char* service, const struct ares_addrinfo_hints *hints, ares_addrinfo_callback callback, void *arg)
ARES_GETADDRINFO(3) Library Functions Manual ARES_GETADDRINFO(3)
NAME
ares_getaddrinfo - Initiate a host query by name and service
SYNOPSIS
#include <ares.h>
typedef void (*ares_addrinfo_callback)(void *arg, int status,
int timeouts, struct ares_addrinfo *result)
void ares_getaddrinfo(ares_channel channel, const char *name,
const char* service, const struct ares_addrinfo_hints *hints,
ares_addrinfo_callback callback, void *arg)
DESCRIPTION
The ares_getaddrinfo function initiates a host query by name on the
name service channel identified by channel. The name and service
parameters give the hostname and service as NULL-terminated C strings.
The hints parameter is an ares_addrinfo_hints structure:
struct ares_addrinfo_hints {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
};
ai_family
Specifies desired address family. AF_UNSPEC means return both
AF_INET and AF_INET6.
ai_socktype
Specifies desired socket type, for example SOCK_STREAM or
SOCK_DGRAM. Setting this to 0 means any type.
ai_protocol
Setting this to 0 means any protocol.
ai_flags
Specifies additional options, see below.
ARES_AI_NUMERICSERV
If this option is set service field will be treated
as a numeric value.
ARES_AI_CANONNAME The ares_addrinfo structure will return a canonical
names list.
ARES_AI_NOSORT Result addresses will not be sorted and no connec-
tions to resolved addresses will be attempted.
ARES_AI_ENVHOSTS Read hosts file path from the environment variable
CARES_HOSTS .
When the query is complete or has failed, the ares library will invoke
callback. Completion or failure of the query may happen immediately,
or may happen during a later call to ares_process(3), ares_destroy(3)
or ares_cancel(3).
The callback argument arg is copied from the ares_getaddrinfo argument
arg. The callback argument status indicates whether the query suc-
ceeded and, if not, how it failed. It may have any of the following
values:
ARES_SUCCESS The host lookup completed successfully.
ARES_ENOTIMP The ares library does not know how to find addresses
of type family.
ARES_ENOTFOUND The name was not found.
ARES_ENOMEM Memory was exhausted.
ARES_ECANCELLED The query was cancelled.
ARES_EDESTRUCTION The name service channel channel is being destroyed;
the query will not be completed.
On successful completion of the query, the callback argument result
points to a struct ares_addrinfo which contains two linked lists, one
with resolved addresses and another with canonical names.
struct ares_addrinfo {
struct ares_addrinfo_cname *cnames;
struct ares_addrinfo_node *nodes;
};
ares_addrinfo_node structure is similar to RFC3493 addrinfo, but with-
out canonname and with extra ttl field.
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;
};
ares_addrinfo_cname structure is a linked list of CNAME records where
ttl is a time to live alias is a label of the resource record and name
is a value (canonical name) of the resource record. See RFC2181
10.1.1. CNAME terminology.
struct ares_addrinfo_cname {
int ttl;
char *alias;
char *name;
struct ares_addrinfo_cname *next;
};
The reserved memory has to be deleted by 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.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | library/libcares |
+---------------+------------------+
|Stability | Volatile |
+---------------+------------------+
SEE ALSO
ares_freeaddrinfo(3)
AUTHOR
Christian Ammer
Andrew Selivanov <andrew.selivanov@gmail.com>
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from https://c-ares.haxx.se/download/c-
ares-1.17.2.tar.gz.
Further information about this software can be found on the open source
community website at https://c-ares.haxx.se/.
4 November 2018 ARES_GETADDRINFO(3)