5253N/A - Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC") 5253N/A - This Source Code Form is subject to the terms of the Mozilla Public 5253N/A - License, v. 2.0. If a copy of the MPL was not distributed with this 5253N/A<
meta http-
equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5253N/A<
title>lwres_getaddrinfo</
title>
5253N/A<
meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
5253N/A<
body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><
div class="refentry">
5253N/A<
a name="id-1"></
a><
div class="titlepage"></
div>
6917N/A — socket address structure to host and service name
5253N/A <
div class="refsynopsisdiv">
5253N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
6917N/A<
b class="fsfunc">lwres_getaddrinfo</
b>(</
code></
td>
6917N/A<
td>const char *<
var class="pdparam">hostname</
var>, </
td>
5253N/A<
td>const char *<
var class="pdparam">servname</
var>, </
td>
5253N/A<
td>const struct addrinfo *<
var class="pdparam">hints</
var>, </
td>
5253N/A<
td>struct addrinfo **<
var class="pdparam">res</
var><
code>)</
code>;</
td>
5256N/A<
div class="funcprototype-spacer">�</
div>
5256N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><
tr>
5256N/A<
b class="fsfunc">lwres_freeaddrinfo</
b>(</
code></
td>
6917N/A<
td>struct addrinfo *<
var class="pdparam">ai</
var><
code>)</
code>;</
td>
5253N/A<
div class="funcprototype-spacer">�</
div>
5253N/A If the operating system does not provide a
6917N/A <
span class="type">struct addrinfo</
span>,
6917N/A the following structure is used:
6917N/A <
pre class="programlisting">
5253N/A int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
5253N/A int ai_family; /* PF_xxx */
5784N/A int ai_socktype; /* SOCK_xxx */
5253N/A int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
5253N/A size_t ai_addrlen; /* length of ai_addr */
6917N/A char *ai_canonname; /* canonical name for hostname */
5253N/A struct sockaddr *ai_addr; /* binary address */
5305N/A struct addrinfo *ai_next; /* next structure in linked list */
5305N/A<
a name="id-1.7"></
a><
h2>DESCRIPTION</
h2>
5305N/A <
p><
code class="function">lwres_getaddrinfo()</
code>
5305N/A is used to get a list of IP addresses and port numbers for host
5305N/A <
em class="parameter"><
code>hostname</
code></
em> and service
5305N/A <
em class="parameter"><
code>servname</
code></
em>.
5305N/A The function is the lightweight resolver's implementation of
5305N/A <
code class="function">getaddrinfo()</
code> as defined in RFC2133.
5305N/A <
em class="parameter"><
code>hostname</
code></
em> and
5305N/A <
em class="parameter"><
code>servname</
code></
em> are pointers to null-terminated
5305N/A strings or <
span class="type">NULL</
span>.
6917N/A <
em class="parameter"><
code>hostname</
code></
em> is either a host name or a
5305N/A numeric host address string: a dotted decimal IPv4 address or an
6917N/A IPv6 address. <
em class="parameter"><
code>servname</
code></
em> is either a
5305N/A decimal port number or a service name as listed in
5525N/A <
p><
em class="parameter"><
code>hints</
code></
em>
5253N/A is an optional pointer to a
5525N/A <
span class="type">struct addrinfo</
span>.
5525N/A This structure can be used to provide hints concerning the type of
5253N/A that the caller supports or wishes to use.
6917N/A The caller can supply the following structure elements in
6917N/A <
em class="parameter"><
code>*hints</
code></
em>:
6917N/A<
div class="variablelist"><
dl class="variablelist">
5253N/A<
dt><
span class="term"><
code class="constant">ai_family</
code></
span></
dt>
5525N/A The protocol family that should be used.
5525N/A <
code class="constant">ai_family</
code>
5305N/A <
span class="type">PF_UNSPEC</
span>,
5253N/A it means the caller will accept any protocol family supported by
5253N/A<
dt><
span class="term"><
code class="constant">ai_socktype</
code></
span></
dt>
5253N/A denotes the type of socket —
5253N/A <
span class="type">SOCK_STREAM</
span>,
5253N/A <
span class="type">SOCK_DGRAM</
span>
5253N/A <
span class="type">SOCK_RAW</
span>
5253N/A <
code class="constant">ai_socktype</
code>
5253N/A is zero the caller will accept any socket type.
5253N/A<
dt><
span class="term"><
code class="constant">ai_protocol</
code></
span></
dt>
5253N/A indicates which transport protocol is wanted: IPPROTO_UDP or
5253N/A <
code class="constant">ai_protocol</
code>
5253N/A is zero the caller will accept any protocol.
5253N/A<
dt><
span class="term"><
code class="constant">ai_flags</
code></
span></
dt>
6917N/A <
span class="type">AI_CANONNAME</
span>
6917N/A bit is set, a successful call to
6917N/A <
code class="function">lwres_getaddrinfo()</
code>
6917N/A will return a null-terminated string containing the canonical
6917N/A of the specified hostname in
6917N/A <
code class="constant">ai_canonname</
code>
6917N/A <
span class="type">addrinfo</
span>
6917N/A <
span class="type">AI_PASSIVE</
span>
6917N/A bit indicates that the returned socket address structure is
5253N/A <
span class="citerefentry">
5253N/A <
span class="refentrytitle">bind</
span>(2)
5253N/A In this case, if the hostname argument is a
5253N/A <
span class="type">NULL</
span>
5253N/A pointer, then the IP address portion of the socket
5253N/A address structure will be set to
5253N/A <
span class="type">INADDR_ANY</
span>
6917N/A <
span class="type">IN6ADDR_ANY_INIT</
span>
5253N/A <
code class="constant">ai_flags</
code>
6918N/A <
span class="type">AI_PASSIVE</
span>
6918N/A bit, the returned socket address structure will be ready
5253N/A <
span class="citerefentry">
5253N/A <
span class="refentrytitle">connect</
span>(2)
5253N/A for a connection-oriented protocol or
5253N/A <
span class="citerefentry">
5253N/A <
span class="refentrytitle">connect</
span>(2)
5253N/A <
span class="citerefentry">
5253N/A <
span class="refentrytitle">sendto</
span>(2)
5253N/A <
span class="citerefentry">
5253N/A <
span class="refentrytitle">sendmsg</
span>(2)
5253N/A if a connectionless protocol was chosen.
5253N/A The IP address portion of the socket address structure will be
5253N/A set to the loopback address if
5253N/A <
em class="parameter"><
code>hostname</
code></
em>
5253N/A <
span class="type">NULL</
span>
6918N/A <
span class="type">AI_PASSIVE</
span>
<
code class="constant">ai_flags</
code>.
<
code class="constant">ai_flags</
code>
<
span class="type">AI_NUMERICHOST</
span>
<
em class="parameter"><
code>hostname</
code></
em>
should be treated as a numeric string defining an IPv4 or IPv6
and no name resolution should be attempted.
All other elements of the <
span class="type">struct addrinfo</
span> passed
via <
em class="parameter"><
code>hints</
code></
em> must be zero.
A <
em class="parameter"><
code>hints</
code></
em> of <
span class="type">NULL</
span> is
the caller provided a <
span class="type">struct addrinfo</
span> initialized to zero
with <
code class="constant">ai_family</
code>set to
<
code class="constant">PF_UNSPEC</
code>.
After a successful call to
<
code class="function">lwres_getaddrinfo()</
code>,
<
em class="parameter"><
code>*res</
code></
em>
is a pointer to a linked list of one or more
<
span class="type">addrinfo</
span>
<
span class="type">struct addrinfo</
span>
in this list cn be processed by following
<
code class="constant">ai_next</
code>
<
span class="type">NULL</
span>
<
code class="constant">ai_family</
code>,
<
code class="constant">ai_socktype</
code>,
<
code class="constant">ai_protocol</
code>
<
span class="type">addrinfo</
span>
structure contain the corresponding arguments for a call to
<
span class="citerefentry">
<
span class="refentrytitle">socket</
span>(2)
<
span class="type">addrinfo</
span>
structure in the list, the
<
code class="constant">ai_addr</
code>
member points to a filled-in socket address structure of length
<
code class="constant">ai_addrlen</
code>.
All of the information returned by
<
code class="function">lwres_getaddrinfo()</
code>
is dynamically allocated: the addrinfo structures, and the socket
address structures and canonical host name strings pointed to by the
<
code class="constant">addrinfo</
code>structures.
Memory allocated for the dynamically allocated structures created by
<
code class="function">lwres_getaddrinfo()</
code>
<
code class="function">lwres_freeaddrinfo()</
code>.
<
em class="parameter"><
code>ai</
code></
em>
<
span class="type">struct addrinfo</
span>
<
code class="function">lwres_getaddrinfo()</
code>.
<
a name="id-1.8"></
a><
h2>RETURN VALUES</
h2>
<
p><
code class="function">lwres_getaddrinfo()</
code>
returns zero on success or one of the error codes listed in
<
span class="citerefentry">
<
span class="refentrytitle">gai_strerror</
span>(3)
if an error occurs. If both <
em class="parameter"><
code>hostname</
code></
em> and
<
em class="parameter"><
code>servname</
code></
em> are <
span class="type">NULL</
span>
<
code class="function">lwres_getaddrinfo()</
code> returns
<
span class="errorcode">EAI_NONAME</
span>.
<
a name="id-1.9"></
a><
h2>SEE ALSO</
h2>
<
p><
span class="citerefentry">
<
span class="refentrytitle">lwres</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_getaddrinfo</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_freeaddrinfo</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_gai_strerror</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">RFC2133</
span>
<
span class="citerefentry">
<
span class="refentrytitle">getservbyname</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">bind</
span>(2)
<
span class="citerefentry">
<
span class="refentrytitle">connect</
span>(2)
<
span class="citerefentry">
<
span class="refentrytitle">sendto</
span>(2)
<
span class="citerefentry">
<
span class="refentrytitle">sendmsg</
span>(2)
<
span class="citerefentry">
<
span class="refentrytitle">socket</
span>(2)