GETADDRINFO(3) FreeBSD Library Functions Manual GETADDRINFO(3)
NNAAMMEE
ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr -- nodename-to-address translation
in protocol-independent manner
SSYYNNOOPPSSIISS
##iinncclluuddee <<ssyyss//ssoocckkeett..hh>>
##iinncclluuddee <<nneettddbb..hh>>
_i_n_t
ggeettaaddddrriinnffoo(_c_o_n_s_t _c_h_a_r _*_n_o_d_e_n_a_m_e, _c_o_n_s_t _c_h_a_r _*_s_e_r_v_n_a_m_e,
_c_o_n_s_t _s_t_r_u_c_t _a_d_d_r_i_n_f_o _*_h_i_n_t_s, _s_t_r_u_c_t _a_d_d_r_i_n_f_o _*_*_r_e_s);
_v_o_i_d
ffrreeeeaaddddrriinnffoo(_s_t_r_u_c_t _a_d_d_r_i_n_f_o _*_a_i);
_c_h_a_r _*
ggaaii__ssttrreerrrroorr(_i_n_t _e_c_o_d_e);
DDEESSCCRRIIPPTTIIOONN
The ggeettaaddddrriinnffoo() function is defined for protocol-independent nodename-
to-address translation. It performs functionality of gethostbyname(3)
and getservbyname(3), in more sophisticated manner.
The addrinfo structure is defined as a result of including the <netdb.h>
header:
struct addrinfo { *
int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
int ai_family; /* PF_xxx */
int ai_socktype; /* SOCK_xxx */
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
size_t ai_addrlen; /* length of ai_addr */
char *ai_canonname; /* canonical name for nodename */
struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */
};
The _n_o_d_e_n_a_m_e and _s_e_r_v_n_a_m_e arguments are pointers to null-terminated
strings or NULL. One or both of these two arguments must be a non-NULL
pointer. In the normal client scenario, both the _n_o_d_e_n_a_m_e and _s_e_r_v_n_a_m_e
are specified. In the normal server scenario, only the _s_e_r_v_n_a_m_e is spec-
ified. A non-NULL _n_o_d_e_n_a_m_e string can be either a node name or a numeric
host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex
address). A non-NULL _s_e_r_v_n_a_m_e string can be either a service name or a
decimal port number.
The caller can optionally pass an addrinfo structure, pointed to by the
third argument, to provide hints concerning the type of socket that the
caller supports. In this _h_i_n_t_s structure all members other than
_a_i___f_l_a_g_s, _a_i___f_a_m_i_l_y, _a_i___s_o_c_k_t_y_p_e, and _a_i___p_r_o_t_o_c_o_l must be zero or a NULL
pointer. A value of PF_UNSPEC for _a_i___f_a_m_i_l_y means the caller will accept
any protocol family. A value of 0 for _a_i___s_o_c_k_t_y_p_e means the caller will
accept any socket type. A value of 0 for _a_i___p_r_o_t_o_c_o_l means the caller
will accept any protocol. For example, if the caller handles only TCP
and not UDP, then the _a_i___s_o_c_k_t_y_p_e member of the hints structure should be
set to SOCK_STREAM when ggeettaaddddrriinnffoo() is called. If the caller handles
only IPv4 and not IPv6, then the _a_i___f_a_m_i_l_y member of the _h_i_n_t_s structure
should be set to PF_INET when ggeettaaddddrriinnffoo() is called. If the third
argument to ggeettaaddddrriinnffoo() is a NULL pointer, this is the same as if the
caller had filled in an addrinfo structure initialized to zero with
_a_i___f_a_m_i_l_y set to PF_UNSPEC.
Upon successful return a pointer to a linked list of one or more addrinfo
structures is returned through the final argument. The caller can
process each addrinfo structure in this list by following the _a_i___n_e_x_t
pointer, until a NULL pointer is encountered. In each returned addrinfo
structure the three members _a_i___f_a_m_i_l_y, _a_i___s_o_c_k_t_y_p_e, and _a_i___p_r_o_t_o_c_o_l are
the corresponding arguments for a call to the ssoocckkeett() function. In each
addrinfo structure the _a_i___a_d_d_r member points to a filled-in socket
address structure whose length is specified by the _a_i___a_d_d_r_l_e_n member.
If the AI_PASSIVE bit is set in the _a_i___f_l_a_g_s member of the _h_i_n_t_s struc-
ture, then the caller plans to use the returned socket address structure
in a call to bbiinndd(). In this case, if the _n_o_d_e_n_a_m_e argument is a NULL
pointer, then the IP address portion of the socket address structure will
be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
address.
If the AI_PASSIVE bit is not set in the _a_i___f_l_a_g_s member of the _h_i_n_t_s
structure, then the returned socket address structure will be ready for a
call to ccoonnnneecctt() (for a connection-oriented protocol) or either
ccoonnnneecctt(), sseennddttoo(), or sseennddmmssgg() (for a connectionless protocol). In
this case, if the _n_o_d_e_n_a_m_e argument is a NULL pointer, then the IP
address portion of the socket address structure will be set to the loop-
back address.
If the AI_CANONNAME bit is set in the _a_i___f_l_a_g_s member of the _h_i_n_t_s struc-
ture, then upon successful return the _a_i___c_a_n_o_n_n_a_m_e member of the first
addrinfo structure in the linked list will point to a null-terminated
string containing the canonical name of the specified _n_o_d_e_n_a_m_e.
If the AI_NUMERICHOST bit is set in the _a_i___f_l_a_g_s member of the _h_i_n_t_s
structure, then a non-NULL _n_o_d_e_n_a_m_e string must be a numeric host address
string. Otherwise an error of EAI_NONAME is returned. This flag pre-
vents any type of name resolution service (e.g., the DNS) from being
called.
All of the information returned by ggeettaaddddrriinnffoo() is dynamically allo-
cated: the addrinfo structures, and the socket address structures and
canonical node name strings pointed to by the addrinfo structures. To
return this information to the system the function Fn freeaddrinfo is
called. The _a_d_d_r_i_n_f_o structure pointed to by the _a_i _a_r_g_u_m_e_n_t is freed,
along with any dynamic storage pointed to by the structure. This opera-
tion is repeated until a NULL _a_i___n_e_x_t pointer is encountered.
To aid applications in printing error messages based on the EAI_xxx codes
returned by ggeettaaddddrriinnffoo(), ggaaii__ssttrreerrrroorr() is defined. The argument is
one of the EAI_xxx values defined earlier and the return value points to
a string describing the error. If the argument is not one of the EAI_xxx
values, the function still returns a pointer to a string whose contents
indicate an unknown error.
FFIILLEESS
/etc/hosts
/etc/host.conf
/etc/resolv.conf
DDIIAAGGNNOOSSTTIICCSS
Error return status from ggeettaaddddrriinnffoo() is zero on success and non-zero on
errors. Non-zero error codes are defined in <netdb.h>, and as follows:
EAI_ADDRFAMILY address family for nodename not supported
EAI_AGAIN temporary failure in name resolution
EAI_BADFLAGS invalid value for ai_flags
EAI_FAIL non-recoverable failure in name resolution
EAI_FAMILY ai_family not supported
EAI_MEMORY memory allocation failure
EAI_NODATA no address associated with nodename
EAI_NONAME nodename nor servname provided, or not known
EAI_SERVICE servname not supported for ai_socktype
EAI_SOCKTYPE ai_socktype not supported
EAI_SYSTEM system error returned in errno
If called with proper argument, ggaaii__ssttrreerrrroorr() returns a pointer to a
string describing the given error code. If the argument is not one of
the EAI_xxx values, the function still returns a pointer to a string
whose contents indicate an unknown error.
SSEEEE AALLSSOO
getnameinfo(3), gethostbyname(3), getservbyname(3), hosts(5),
services(5), hostname(7)
R. Gilligan, S. Thomson, J. Bound, and W. Stevens, ``Basic Socket Inter-
face Extensions for IPv6,'' RFC2133, April 1997.
HHIISSTTOORRYY
The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
kit.
SSTTAANNDDAARRDDSS
The ggeettaaddddrriinnffoo() function is defined IEEE POSIX 1003.1g draft specifica-
tion, and documented in ``Basic Socket Interface Extensions for IPv6''
(RFC2133).
BBUUGGSS
The text was shamelessly copied from RFC2133.
KAME May 25, 1995 KAME