5236N/A - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC") 5236N/A - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. 5236N/A - Permission to use, copy, modify, and/or distribute this software for any 5236N/A - purpose with or without fee is hereby granted, provided that the above 5236N/A - copyright notice and this permission notice appear in all copies. 6983N/A - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 6983N/A - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 5236N/A - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 5236N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 5236N/A - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 5236N/A - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 6983N/A - PERFORMANCE OF THIS SOFTWARE. 5236N/A<
meta http-
equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5236N/A<
title>lwres_getaddrinfo</
title>
5236N/A<
meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
5236N/A<
body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><
div class="refentry">
5236N/A<
a name="id-1"></
a><
div class="titlepage"></
div>
5236N/A<
p>lwres_getaddrinfo, lwres_freeaddrinfo — socket address structure to host and service name</
p>
5236N/A<
div class="refsynopsisdiv">
5236N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
5236N/A<
b class="fsfunc">lwres_getaddrinfo</
b>(</
code></
td>
5236N/A<
td>const char *<
var class="pdparam">hostname</
var>, </
td>
5236N/A<
td>const char *<
var class="pdparam">servname</
var>, </
td>
5236N/A<
td>const struct addrinfo *<
var class="pdparam">hints</
var>, </
td>
5236N/A<
td>struct addrinfo **<
var class="pdparam">res</
var><
code>)</
code>;</
td>
5236N/A<
div class="funcprototype-spacer">�</
div>
5236N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><
tr>
5236N/A<
b class="fsfunc">lwres_freeaddrinfo</
b>(</
code></
td>
5236N/A<
td>struct addrinfo *<
var class="pdparam">ai</
var><
code>)</
code>;</
td>
5236N/A<
div class="funcprototype-spacer">�</
div>
5236N/A If the operating system does not provide a
5236N/A <
span class="type">struct addrinfo</
span>,
5236N/A the following structure is used:
5236N/A<
pre class="programlisting">
5236N/A int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
5236N/A int ai_family; /* PF_xxx */
5236N/A int ai_socktype; /* SOCK_xxx */
5236N/A int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
5236N/A size_t ai_addrlen; /* length of ai_addr */
5236N/A char *ai_canonname; /* canonical name for hostname */
5236N/A struct sockaddr *ai_addr; /* binary address */
5236N/A struct addrinfo *ai_next; /* next structure in linked list */
5236N/A<
a name="id-1.7"></
a><
h2>DESCRIPTION</
h2>
5236N/A<
p><
code class="function">lwres_getaddrinfo()</
code>
5236N/A is used to get a list of IP addresses and port numbers for host
5236N/A <
em class="parameter"><
code>hostname</
code></
em> and service
5236N/A <
em class="parameter"><
code>servname</
code></
em>.
5236N/A The function is the lightweight resolver's implementation of
5236N/A <
code class="function">getaddrinfo()</
code> as defined in RFC2133.
5236N/A <
em class="parameter"><
code>hostname</
code></
em> and
5236N/A <
em class="parameter"><
code>servname</
code></
em> are pointers to null-terminated
5236N/A strings or <
span class="type">NULL</
span>.
5236N/A <
em class="parameter"><
code>hostname</
code></
em> is either a host name or a
5236N/A numeric host address string: a dotted decimal IPv4 address or an
5236N/A IPv6 address. <
em class="parameter"><
code>servname</
code></
em> is either a
5236N/A decimal port number or a service name as listed in
5236N/A<
p><
em class="parameter"><
code>hints</
code></
em>
5236N/A is an optional pointer to a
5236N/A <
span class="type">struct addrinfo</
span>.
5236N/A This structure can be used to provide hints concerning the type of
5236N/A that the caller supports or wishes to use.
5236N/A The caller can supply the following structure elements in
5236N/A <
em class="parameter"><
code>*hints</
code></
em>:
5236N/A<
div class="variablelist"><
dl class="variablelist">
5236N/A<
dt><
span class="term"><
code class="constant">ai_family</
code></
span></
dt>
5236N/A The protocol family that should be used.
5236N/A <
code class="constant">ai_family</
code>
5236N/A <
span class="type">PF_UNSPEC</
span>,
5236N/A it means the caller will accept any protocol family supported by
5236N/A<
dt><
span class="term"><
code class="constant">ai_socktype</
code></
span></
dt>
5236N/A denotes the type of socket —
5236N/A <
span class="type">SOCK_STREAM</
span>,
5236N/A <
span class="type">SOCK_DGRAM</
span>
5236N/A <
span class="type">SOCK_RAW</
span>
5236N/A <
code class="constant">ai_socktype</
code>
5236N/A is zero the caller will accept any socket type.
5236N/A<
dt><
span class="term"><
code class="constant">ai_protocol</
code></
span></
dt>
5236N/A indicates which transport protocol is wanted: IPPROTO_UDP or
5236N/A <
code class="constant">ai_protocol</
code>
5236N/A is zero the caller will accept any protocol.
5236N/A<
dt><
span class="term"><
code class="constant">ai_flags</
code></
span></
dt>
5236N/A <
span class="type">AI_CANONNAME</
span>
5236N/A bit is set, a successful call to
5236N/A <
code class="function">lwres_getaddrinfo()</
code>
5236N/A will return a null-terminated string containing the canonical
5236N/A of the specified hostname in
5236N/A <
code class="constant">ai_canonname</
code>
5236N/A <
span class="type">addrinfo</
span>
5236N/A <
span class="type">AI_PASSIVE</
span>
5236N/A bit indicates that the returned socket address structure is
5236N/A <
span class="citerefentry"><
span class="refentrytitle">bind</
span>(2)</
span>.
5236N/A In this case, if the hostname argument is a
5236N/A <
span class="type">NULL</
span>
5236N/A pointer, then the IP address portion of the socket
5236N/A address structure will be set to
5236N/A <
span class="type">INADDR_ANY</
span>
5236N/A <
span class="type">IN6ADDR_ANY_INIT</
span>
5236N/A <
code class="constant">ai_flags</
code>
5236N/A <
span class="type">AI_PASSIVE</
span>
5236N/A bit, the returned socket address structure will be ready
5236N/A <
span class="citerefentry"><
span class="refentrytitle">connect</
span>(2)</
span>
5236N/A for a connection-oriented protocol or
5236N/A <
span class="citerefentry"><
span class="refentrytitle">connect</
span>(2)</
span>,
5236N/A <
span class="citerefentry"><
span class="refentrytitle">sendto</
span>(2)</
span>,
5236N/A <
span class="citerefentry"><
span class="refentrytitle">sendmsg</
span>(2)</
span>
5236N/A if a connectionless protocol was chosen.
5236N/A The IP address portion of the socket address structure will be
5236N/A set to the loopback address if
5236N/A <
em class="parameter"><
code>hostname</
code></
em>
5236N/A <
span class="type">NULL</
span>
5236N/A <
span class="type">AI_PASSIVE</
span>
5236N/A <
code class="constant">ai_flags</
code>.
5236N/A <
code class="constant">ai_flags</
code>
5236N/A <
span class="type">AI_NUMERICHOST</
span>
5236N/A <
em class="parameter"><
code>hostname</
code></
em>
5236N/A should be treated as a numeric string defining an IPv4 or IPv6
5236N/A and no name resolution should be attempted.
5236N/A All other elements of the <
span class="type">struct addrinfo</
span> passed
5236N/A via <
em class="parameter"><
code>hints</
code></
em> must be zero.
5236N/A A <
em class="parameter"><
code>hints</
code></
em> of <
span class="type">NULL</
span> is
5236N/A the caller provided a <
span class="type">struct addrinfo</
span> initialized to zero
5236N/A with <
code class="constant">ai_family</
code>set to
5236N/A <
code class="constant">PF_UNSPEC</
code>.
5236N/A <
code class="function">lwres_getaddrinfo()</
code>,
5236N/A <
em class="parameter"><
code>*res</
code></
em>
5236N/A is a pointer to a linked list of one or more
5236N/A <
span class="type">addrinfo</
span>
5236N/A <
span class="type">struct addrinfo</
span>
5236N/A in this list cn be processed by following
5236N/A <
code class="constant">ai_next</
code>
5236N/A <
span class="type">NULL</
span>
5236N/A <
code class="constant">ai_family</
code>,
5236N/A <
code class="constant">ai_socktype</
code>,
5236N/A <
code class="constant">ai_protocol</
code>
5236N/A <
span class="type">addrinfo</
span>
5236N/A structure contain the corresponding arguments for a call to
5236N/A <
span class="citerefentry"><
span class="refentrytitle">socket</
span>(2)</
span>.
5236N/A <
span class="type">addrinfo</
span>
5236N/A <
code class="constant">ai_addr</
code>
5236N/A member points to a filled-in socket address structure of length
5236N/A <
code class="constant">ai_addrlen</
code>.
5236N/A All of the information returned by
5236N/A <
code class="function">lwres_getaddrinfo()</
code>
5236N/A is dynamically allocated: the addrinfo structures, and the socket
5236N/A address structures and canonical host name strings pointed to by the
5236N/A <
code class="constant">addrinfo</
code>structures.
5236N/A Memory allocated for the dynamically allocated structures created by
5236N/A <
code class="function">lwres_getaddrinfo()</
code>
5236N/A <
code class="function">lwres_freeaddrinfo()</
code>.
5236N/A <
em class="parameter"><
code>ai</
code></
em>
5236N/A <
span class="type">struct addrinfo</
span>
5236N/A <
code class="function">lwres_getaddrinfo()</
code>.
5236N/A<
a name="id-1.8"></
a><
h2>RETURN VALUES</
h2>
5236N/A<
p><
code class="function">lwres_getaddrinfo()</
code>
5236N/A returns zero on success or one of the error codes listed in
5236N/A <
span class="citerefentry"><
span class="refentrytitle">gai_strerror</
span>(3)</
span>
5236N/A if an error occurs. If both <
em class="parameter"><
code>hostname</
code></
em> and
5236N/A <
em class="parameter"><
code>servname</
code></
em> are <
span class="type">NULL</
span>
5236N/A <
code class="function">lwres_getaddrinfo()</
code> returns
5236N/A <
span class="errorcode">EAI_NONAME</
span>.
5236N/A<
a name="id-1.9"></
a><
h2>SEE ALSO</
h2>
5236N/A<
p><
span class="citerefentry"><
span class="refentrytitle">lwres</
span>(3)</
span>,
5236N/A <
span class="citerefentry"><
span class="refentrytitle">lwres_getaddrinfo</
span>(3)</
span>,
5236N/A <
span class="citerefentry"><
span class="refentrytitle">lwres_freeaddrinfo</
span>(3)</
span>,
5236N/A <
span class="citerefentry"><
span class="refentrytitle">lwres_gai_strerror</
span>(3)</
span>,
5236N/A <
span class="citerefentry"><
span class="refentrytitle">RFC2133</
span></
span>,
5236N/A <
span class="citerefentry"><
span class="refentrytitle">getservbyname</
span>(3)</
span>,
5236N/A <
span class="citerefentry"><
span class="refentrytitle">bind</
span>(2)</
span>,
<
span class="citerefentry"><
span class="refentrytitle">connect</
span>(2)</
span>,
<
span class="citerefentry"><
span class="refentrytitle">sendto</
span>(2)</
span>,
<
span class="citerefentry"><
span class="refentrytitle">sendmsg</
span>(2)</
span>,
<
span class="citerefentry"><
span class="refentrytitle">socket</
span>(2)</
span>.