123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201 |
- .\"
- .\" 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 and service
- .SH SYNOPSIS
- .nf
- #include <ares.h>
- typedef void (*ares_addrinfo_callback)(void *\fIarg\fP, int \fIstatus\fP,
- int \fItimeouts\fP,
- struct ares_addrinfo *\fIresult\fP)
- void ares_getaddrinfo(ares_channel \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
- .B ares_getaddrinfo
- 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
- 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
- .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 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
- .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 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 <andrew.selivanov@gmail.com>
|