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 *res)

void ares_getaddrinfo(ares_channel channel,
const char *name, const char *service,
const struct ares_addrinfo *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 structure. Every field except ai_family, ai_socktype, ai_protocol, and ai_flags must be set to zero.

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.

If ARES_AI_NUMERICSERV option is set service field will be treated as a numeric value. If ARES_AI_CANONNAME is set the first ares_addrinfo structure will contain a canonical name of the host in ai_canonname field.

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 succeeded 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 look up addresses of type family.

ARES_ENOTFOUND
    The requested host name is not found.

ARES_ESERVICE
    The requested service is 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.

The callback argument timeouts reports how many times a query timed out during the execution of the given request.

On successful completion of the query, the callback argument res points to a struct ares_addrinfo containing the addresses of the host returned by the query. The result is not sorted in any way and ignores sortlist. The ares will not attempt to free the memory pointed to by res it is the caller's responsibility to free the resulting ares_addrinfo structure using ares_freeaddrinfo(3) when it is no longer needed. If the query did not complete successfully, res will be NULL.

SEE ALSO
ares_freeaddrinfo(3), ares_gethostbyname(3) ares_process(3),

AUTHOR
Andrew Selivanov <andrew.selivanov@gmail.com>, on behalf of Crazy Panda http://www.crazypandagames.com Christian Ammer