FreeBSD Manual Pages
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_t *channel, const char *name, const char* service, const struct ares_addrinfo_hints *hints, ares_addrinfo_callback callback, void *arg) DESCRIPTION The ares_getaddrinfo(3) function initiates a host query by name on the name service channel identified by channel. The name and service para- meters 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). When the associated callback is called, it is called with a channel lock so care must be taken to ensure any processing is minimal to pre- vent DNS channel stalls. The callback may be triggered from a different thread than the one which called ares_getaddrinfo(3). For integrators running their own event loops and not using ARES_OPT_EVENT_THREAD, care needs to be taken to ensure any file de- scriptor lists are updated immediately within the eventloop when noti- fied. The callback argument arg is copied from the ares_getaddrinfo(3) argu- ment 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 find addresses of type family. ARES_ENOTFOUND The name was not found. ARES_ENOMEM Memory was exhausted. ARES_ESERVICE The textual service name provided could not be dereferenced into a port. 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. Also in- cluded is the official name of the host (analogous to gethostbyname() h_name). struct ares_addrinfo { struct ares_addrinfo_cname *cnames; struct ares_addrinfo_node *nodes; char *name; }; 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(3). 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. AVAILABILITY This function was added in c-ares 1.16.0, released in March 2020. SEE ALSO ares_freeaddrinfo(3) 4 November 2018 ARES_GETADDRINFO(3)
NAME | SYNOPSIS | DESCRIPTION | AVAILABILITY | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ares_getaddrinfo&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>