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