c-ares/ares_getaddrinfo.3

.\"
.\" Copyright 1998 by the Massachusetts Institute of Technology.
.\"
.\" Permission to use, copy, modify, and distribute this
.\" software and its documentation for any purpose and without
.\" fee is hereby granted, provided that the above copyright
.\" notice appear in all copies and that both that copyright
.\" notice and this permission notice appear in supporting
.\" documentation, and that the name of M.I.T. not be used in
.\" advertising or publicity pertaining to distribution of the
.\" software without specific, written prior permission.
.\" M.I.T. makes no representations about the suitability of
.\" this software for any purpose.  It is provided "as is"
.\" without express or implied warranty.
.\"
.TH ARES_GETADDRINFO 3 "4 November 2018"
.SH NAME
ares_getaddrinfo \- Initiate a host query by name
.SH SYNOPSIS
.nf
.B #include <ares.h>
.PP
.B typedef void (*ares_addr_callback)(void *\fIarg\fP, int \fIstatus\fP,
.B 	int \fItimeouts\fP, struct ares_addrinfo *\fIresult\fP)
.PP
.B void ares_getaddrinfo(ares_channel \fIchannel\fP, const char *\fIname\fP,
.B 	const char* \fIservice\fP, const struct ares_addrinfo *\fIhints\fP,
.B 	ares_addr_callback \fIcallback\fP, void *\fIarg\fP)
.PP
.B struct ares_addrinfo {
.B 	int                  \fIai_flags\fP;
.B 	int                  \fIai_family\fP;
.B 	int                  \fIai_socktype\fP;
.B 	int                  \fIai_protocol\fP;
.B 	ares_socklen_t       \fIai_addrlen\fP;
.B 	char                 \fI*ai_canonname\fP;
.B 	struct sockaddr      \fI*ai_addr\fP;
.B 	struct ares_addrinfo \fI*ai_next\fP;
.B };
.fi
.SH DESCRIPTION
The
.B ares_getaddrinfo
function initiates a host query by name on the name service channel
identified by
.IR channel .
The parameter
.I name
gives the hostname as a NUL-terminated C string, and
.I hints->ai_family
gives the desired type of address for the resulting addrinfo result list.
The parameter
.I service
and the other properties from the
.I hints
parameter are ignored. 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
The callback argument
.I arg
is copied from the
.B ares_getaddrinfo
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 name
.I name
was not found.
.TP 19
.B ARES_ENOMEM
Memory was exhausted.
.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 addrinfo
which is a linked list, where each item contains family and address of
the requested name. The reserved memory has to be deleted by
.B ares_freeaddrinfo.

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 SEE ALSO
.BR ares_freeaddrinfo (3)
.SH AUTHOR
Christian Ammer
.br
Andrew Selivanov <andrew.selivanov@gmail.com>
.SH CAVEATS
This function is under development. It only supports a minimum feature set
of the function
.B getaddrinfo
defined in RFC-3493
.br