ARES\_GETADDRINFO(3) Library Functions Manual ARES\_GETADDRINFO(3) # [NAME](#NAME) ares\_getaddrinfo - Initiate a host query by name and service # [SYNOPSIS](#SYNOPSIS) ``` #include 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](#DESCRIPTION) The [**ares\_getaddrinfo(3)**](/man/os/c-ares/ares_getaddrinfo.3) 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. Either *name* or *service* may be NULL, but not both. If *name* is NULL, the returned addresses are synthesized from *service*: the wildcard address (0.0.0.0 or ::) is returned when **ARES\_AI\_PASSIVE** is set in *ai\_flags*, otherwise the loopback address (127.0.0.1 or ::1) is returned. 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*](#ai_family) Specifies desired address family. AF\_UNSPEC means return both AF\_INET and AF\_INET6. [*ai\_socktype*](#ai_socktype) Specifies desired socket type, for example SOCK\_STREAM or SOCK\_DGRAM. Setting this to 0 means any type. [*ai\_protocol*](#ai_protocol) Setting this to 0 means any protocol. [*ai\_flags*](#ai_flags) Specifies additional options, see below. [**ARES\_AI\_NUMERICSERV**](#ARES_AI_NUMERICSERV) If this option is set *service* field will be treated as a numeric value. [**ARES\_AI\_PASSIVE**](#ARES_AI_PASSIVE) If this option is set and *name* is NULL, the returned addresses will use the wildcard address (0.0.0.0 or ::), suitable for [**bind**(2)](/man/os/c-ares/bind.2)ing a socket that will accept connections. If not set and *name* is NULL, the loopback address (127.0.0.1 or ::1) is returned instead. [**ARES\_AI\_CANONNAME**](#ARES_AI_CANONNAME) The ares\_addrinfo structure will return a canonical names list. [**ARES\_AI\_NOSORT**](#ARES_AI_NOSORT) Result addresses will not be sorted and no connections to resolved addresses will be attempted. [**ARES\_AI\_ENVHOSTS**](#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)*](/man/os/c-ares/ares_process.3), [*ares\_destroy(3)*](/man/os/c-ares/ares_destroy.3) or [*ares\_cancel(3)*](/man/os/c-ares/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 prevent DNS channel stalls. The callback may be triggered from a different thread than the one which called [*ares\_getaddrinfo(3)*](/man/os/c-ares/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 descriptor lists are updated immediately within the eventloop when notified. The callback argument *arg* is copied from the [**ares\_getaddrinfo(3)**](/man/os/c-ares/ares_getaddrinfo.3) 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**](#ARES_SUCCESS) The host lookup completed successfully. [**ARES\_ENOTIMP**](#ARES_ENOTIMP) The ares library does not know how to find addresses of type *family*. [**ARES\_ENOTFOUND**](#ARES_ENOTFOUND) The *name* was not found. [**ARES\_ENOMEM**](#ARES_ENOMEM) Memory was exhausted. [**ARES\_ESERVICE**](#ARES_ESERVICE) The textual service name provided could not be dereferenced into a port. [**ARES\_ECANCELLED**](#ARES_ECANCELLED) The query was cancelled. [**ARES\_EDESTRUCTION**](#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 included 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 without 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)**](/man/os/c-ares/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](#AVAILABILITY) This function was added in c-ares 1.16.0, released in March 2020. # [SEE ALSO](#SEE_ALSO) [**ares\_freeaddrinfo**(3)](/man/os/c-ares/ares_freeaddrinfo.3) 4 November 2018 --- Document: ares_getaddrinfo(3) from c-ares 1.34.8-r2 (Chainguard OS) Source: https://github.com/c-ares/c-ares