mirror of https://github.com/axmolengine/axmol.git
200 lines
5.1 KiB
Groff
200 lines
5.1 KiB
Groff
.\"
|
|
.\" 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
|
|
.B #include <ares.h>
|
|
.PP
|
|
.B typedef void (*ares_addrinfo_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_hints *\fIhints\fP,
|
|
.B 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>
|