.\" .\" Copyright 1998 by the Massachusetts Institute of Technology. .\" SPDX-License-Identifier: MIT .\" .TH ARES_GETADDRINFO 3 "4 November 2018" .SH NAME ares_getaddrinfo \- Initiate a host query by name and service .SH SYNOPSIS .nf #include typedef void (*ares_addrinfo_callback)(void *\fIarg\fP, int \fIstatus\fP, int \fItimeouts\fP, struct ares_addrinfo *\fIresult\fP) void ares_getaddrinfo(ares_channel_t *\fIchannel\fP, const char *\fIname\fP, const char* \fIservice\fP, const struct ares_addrinfo_hints *\fIhints\fP, ares_addrinfo_callback \fIcallback\fP, void *\fIarg\fP) .fi .SH DESCRIPTION The \fBares_getaddrinfo(3)\fP function initiates a host query by name on the name service channel identified by .IR channel . The .I name and .I service parameters give the hostname and service as NULL-terminated C strings. The .I hints parameter is an .BR ares_addrinfo_hints structure: .PP .RS .EX struct ares_addrinfo_hints { int ai_flags; int ai_family; int ai_socktype; int ai_protocol; }; .EE .RE .TP .I ai_family Specifies desired address family. AF_UNSPEC means return both AF_INET and AF_INET6. .TP .I ai_socktype Specifies desired socket type, for example SOCK_STREAM or SOCK_DGRAM. Setting this to 0 means any type. .TP .I ai_protocol Setting this to 0 means any protocol. .TP .I ai_flags Specifies additional options, see below. .PP .TP 19 .B ARES_AI_NUMERICSERV If this option is set .I service field will be treated as a numeric value. .TP 19 .B ARES_AI_CANONNAME The ares_addrinfo structure will return a canonical names list. .TP 19 .B ARES_AI_NOSORT Result addresses will not be sorted and no connections to resolved addresses will be attempted. .TP 19 .B ARES_AI_ENVHOSTS Read hosts file path from the environment variable .I CARES_HOSTS . .PP When the query is complete or has failed, the ares library will invoke \fIcallback\fP. Completion or failure of the query may happen immediately, or may happen during a later call to \fIares_process(3)\fP, \fIares_destroy(3)\fP or \fIares_cancel(3)\fP. .PP 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 \fIares_getaddrinfo(3)\fP. For integrators running their own event loops and not using \fBARES_OPT_EVENT_THREAD\fP, care needs to be taken to ensure any file descriptor lists are updated immediately within the eventloop when notified. .PP The callback argument .I arg is copied from the \fBares_getaddrinfo(3)\fP argument .IR arg . The callback argument .I status indicates whether the query succeeded and, if not, how it failed. It may have any of the following values: .TP 19 .B ARES_SUCCESS The host lookup completed successfully. .TP 19 .B ARES_ENOTIMP The ares library does not know how to find addresses of type .IR family . .TP 19 .B ARES_ENOTFOUND The .I name was not found. .TP 19 .B ARES_ENOMEM Memory was exhausted. .TP 19 .B ARES_ESERVICE The textual service name provided could not be dereferenced into a port. .TP 19 .B ARES_ECANCELLED The query was cancelled. .TP 19 .B ARES_EDESTRUCTION The name service channel .I channel is being destroyed; the query will not be completed. .PP On successful completion of the query, the callback argument .I result points to a .B 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). .PP .RS .EX struct ares_addrinfo { struct ares_addrinfo_cname *cnames; struct ares_addrinfo_node *nodes; char *name; }; .EE .RE .PP .I ares_addrinfo_node structure is similar to RFC3493 addrinfo, but without canonname and with extra ttl field. .RS .PP .EX 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; }; .EE .RE .PP .I ares_addrinfo_cname structure is a linked list of CNAME records where .I ttl is a time to live .I alias is a label of the resource record and .I name is a value (canonical name) of the resource record. See RFC2181 10.1.1. CNAME terminology. .RS .PP .EX struct ares_addrinfo_cname { int ttl; char *alias; char *name; struct ares_addrinfo_cname *next; }; .EE .RE .PP The reserved memory has to be deleted by \fBares_freeaddrinfo(3)\fP. 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. .SH AVAILABILITY This function was added in c-ares 1.16.0, released in March 2020. .SH SEE ALSO .BR ares_freeaddrinfo (3) .SH AUTHOR Christian Ammer .br Andrew Selivanov