ares_getnameinfo - Address-to-nodename translation in protocol-independent manner
typedef void (*ares_nameinfo_callback)(void *arg, int status,
int timeouts, char *node, char *service)
void ares_getnameinfo(ares_channel channel, const struct sockaddr *sa,
ares_socklen_t salen, int flags, ares_nameinfo_callback callback,
The ares_getnameinfo function is defined for protocol-independent address translation. The
function is a combination of ares_gethostbyaddr(3) and getservbyport(3). The function will
translate the address either by executing a host query on the name service channel identi-
fied by channel or it will attempt to resolve it locally if possible. The parameters sa
and len give the address as a sockaddr structure, and flags gives the options that the
function will use. Valid flags are listed below:
ARES_NI_NOFQDN Only the nodename portion of the FQDN is returned for local hosts.
The numeric form of the hostname is returned rather than the name.
ARES_NI_NAMEREQD An error is returned if the hostname cannot be found in the DNS.
The numeric form of the service is returned rather than the name.
ARES_NI_TCP The service name is to be looked up for the TCP protocol.
ARES_NI_UDP The service name is to be looked up for the UDP protocol.
ARES_NI_SCTP The service name is to be looked up for the SCTP protocol.
ARES_NI_DCCP The service name is to be looked up for the DCCP protocol.
The numeric form of the scope ID is returned rather than the name.
ARES_NI_LOOKUPHOST A hostname lookup is being requested.
A service name lookup is being requested.
When the query is complete or has failed, the ares library will invoke callback. Comple-
tion 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_getnameinfo 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 address addr 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
ARES_EBADFLAGS The flags parameter contains an illegal value.
The callback argument timeouts reports how many times a query timed out during the execu-
tion of the given request.
On successful completion of the query, the callback argument node contains a string repre-
senting the hostname (assuming ARES_NI_LOOKUPHOST was specified). Additionally, service
contains a string representing the service name (assuming ARES_NI_LOOKUPSERVICE was speci-
fied). If the query did not complete successfully, or one of the values was not
requested, node or service will be NULL.
Copyright 2005 by Dominick Meglio.
1 May 2009 ARES_GETNAMEINFO(3)