lwres_getaddrinfo.html revision 4abdfc917e6635a7c81d1f931a0c79227e72d025
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<!--
794b79e6bbc3f5db1ea6ae154d739b9f1ef1a375Tinderbox User - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
9210d8796eaf4125ac58c034f9b5ca167857a55aAutomatic Updater - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721Automatic Updater -
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt - Permission to use, copy, modify, and distribute this software for any
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt - purpose with or without fee is hereby granted, provided that the above
9210d8796eaf4125ac58c034f9b5ca167857a55aAutomatic Updater - copyright notice and this permission notice appear in all copies.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt -
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9210d8796eaf4125ac58c034f9b5ca167857a55aAutomatic Updater - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt - PERFORMANCE OF THIS SOFTWARE.
ea94d370123a5892f6c47a97f21d1b28d44bb168Tinderbox User-->
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<!-- $Id: lwres_getaddrinfo.html,v 1.26 2007/01/26 23:29:04 marka Exp $ -->
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<html>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<head>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
852ccdd42a71550c974111b49415204ffeca6573Automatic Updater<title>lwres_getaddrinfo</title>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt</head>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<a name="id2476275"></a><div class="titlepage"></div>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<div class="refnamediv">
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<h2>Name</h2>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<p>lwres_getaddrinfo, lwres_freeaddrinfo &#8212; socket address structure to host and service name</p>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt</div>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<div class="refsynopsisdiv">
ec899c963c91c16c393e067996400ae244921110Tinderbox User<h2>Synopsis</h2>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<div class="funcsynopsis">
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<pre class="funcsynopsisinfo">#include &lt;lwres/netdb.h&gt;</pre>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
ec899c963c91c16c393e067996400ae244921110Tinderbox User<tr>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td><code class="funcdef">
ec899c963c91c16c393e067996400ae244921110Tinderbox Userint
f5ae3cca1d2832239cc821bdef77e90c1739e66dTinderbox User<b class="fsfunc">lwres_getaddrinfo</b>(</code></td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>const char *�</td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<var class="pdparam">hostname</var>, </td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User</tr>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<tr>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>�</td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>const char *�</td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<var class="pdparam">servname</var>, </td>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt</tr>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<tr>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>�</td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>const struct addrinfo *�</td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<var class="pdparam">hints</var>, </td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User</tr>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<tr>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>�</td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>struct addrinfo **�</td>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<td>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<var class="pdparam">res</var><code>)</code>;</td>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt</tr>
ec899c963c91c16c393e067996400ae244921110Tinderbox User</table>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td><code class="funcdef">
351b62535d4c4f89883bfdba025999dd32490266Evan Huntvoid
ec899c963c91c16c393e067996400ae244921110Tinderbox User<b class="fsfunc">lwres_freeaddrinfo</b>(</code></td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>struct addrinfo *�</td>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<td>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<var class="pdparam">ai</var><code>)</code>;</td>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt</tr></table>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt</div>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<p>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt If the operating system does not provide a
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt <span class="type">struct addrinfo</span>,
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt the following structure is used:
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt </p>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<pre class="programlisting">
351b62535d4c4f89883bfdba025999dd32490266Evan Huntstruct addrinfo {
ec899c963c91c16c393e067996400ae244921110Tinderbox User int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
ec899c963c91c16c393e067996400ae244921110Tinderbox User int ai_family; /* PF_xxx */
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt int ai_socktype; /* SOCK_xxx */
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt size_t ai_addrlen; /* length of ai_addr */
ec899c963c91c16c393e067996400ae244921110Tinderbox User char *ai_canonname; /* canonical name for hostname */
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt struct sockaddr *ai_addr; /* binary address */
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt struct addrinfo *ai_next; /* next structure in linked list */
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt};
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt</pre>
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater<p>
2cbb4ab75757fbb656997a82c14ca07db37d481aAutomatic Updater </p>
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater</div>
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater<div class="refsect1" lang="en">
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater<a name="id2543409"></a><h2>DESCRIPTION</h2>
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater<p><code class="function">lwres_getaddrinfo()</code>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt is used to get a list of IP addresses and port numbers for host
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt <em class="parameter"><code>hostname</code></em> and service
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt <em class="parameter"><code>servname</code></em>.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt The function is the lightweight resolver's implementation of
ec899c963c91c16c393e067996400ae244921110Tinderbox User <code class="function">getaddrinfo()</code> as defined in RFC2133.
ec899c963c91c16c393e067996400ae244921110Tinderbox User <em class="parameter"><code>hostname</code></em> and
ec899c963c91c16c393e067996400ae244921110Tinderbox User <em class="parameter"><code>servname</code></em> are pointers to null-terminated
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt strings or <span class="type">NULL</span>.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt <em class="parameter"><code>hostname</code></em> is either a host name or a
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt numeric host address string: a dotted decimal IPv4 address or an
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt IPv6 address. <em class="parameter"><code>servname</code></em> is either a
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt decimal port number or a service name as listed in
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt <code class="filename">/etc/services</code>.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt </p>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<p><em class="parameter"><code>hints</code></em>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt is an optional pointer to a
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt <span class="type">struct addrinfo</span>.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt This structure can be used to provide hints concerning the type of
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt socket
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater that the caller supports or wishes to use.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt The caller can supply the following structure elements in
ec899c963c91c16c393e067996400ae244921110Tinderbox User <em class="parameter"><code>*hints</code></em>:
ec899c963c91c16c393e067996400ae244921110Tinderbox User
ec899c963c91c16c393e067996400ae244921110Tinderbox User </p>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<div class="variablelist"><dl>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<dt><span class="term"><code class="constant">ai_family</code></span></dt>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<dd><p>
2cbb4ab75757fbb656997a82c14ca07db37d481aAutomatic Updater The protocol family that should be used.
2cbb4ab75757fbb656997a82c14ca07db37d481aAutomatic Updater When
2cbb4ab75757fbb656997a82c14ca07db37d481aAutomatic Updater <code class="constant">ai_family</code>
2cbb4ab75757fbb656997a82c14ca07db37d481aAutomatic Updater is set to
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater <span class="type">PF_UNSPEC</span>,
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater it means the caller will accept any protocol family supported by
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater the
ec899c963c91c16c393e067996400ae244921110Tinderbox User operating system.
ec899c963c91c16c393e067996400ae244921110Tinderbox User </p></dd>
ec899c963c91c16c393e067996400ae244921110Tinderbox User<dt><span class="term"><code class="constant">ai_socktype</code></span></dt>
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater<dd><p>
7ae7246a6339bb3a79ffc9f2f9c486de9a2bf65eAutomatic Updater denotes the type of socket &#8212;
ec899c963c91c16c393e067996400ae244921110Tinderbox User <span class="type">SOCK_STREAM</span>,
ec899c963c91c16c393e067996400ae244921110Tinderbox User <span class="type">SOCK_DGRAM</span>
ec899c963c91c16c393e067996400ae244921110Tinderbox User or
2cbb4ab75757fbb656997a82c14ca07db37d481aAutomatic Updater <span class="type">SOCK_RAW</span>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt &#8212; that is wanted.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt When
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt <code class="constant">ai_socktype</code>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt is zero the caller will accept any socket type.
ec899c963c91c16c393e067996400ae244921110Tinderbox User </p></dd>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<dt><span class="term"><code class="constant">ai_protocol</code></span></dt>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<dd><p>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt indicates which transport protocol is wanted: IPPROTO_UDP or
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt IPPROTO_TCP.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt If
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt <code class="constant">ai_protocol</code>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt is zero the caller will accept any protocol.
ec899c963c91c16c393e067996400ae244921110Tinderbox User </p></dd>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<dt><span class="term"><code class="constant">ai_flags</code></span></dt>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<dd>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<p>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt Flag bits.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt If the
<span class="type">AI_CANONNAME</span>
bit is set, a successful call to
<code class="function">lwres_getaddrinfo()</code>
will return a null-terminated string containing the canonical
name
of the specified hostname in
<code class="constant">ai_canonname</code>
of the first
<span class="type">addrinfo</span>
structure returned.
Setting the
<span class="type">AI_PASSIVE</span>
bit indicates that the returned socket address structure is
intended
for used in a call to
<span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>.
In this case, if the hostname argument is a
<span class="type">NULL</span>
pointer, then the IP address portion of the socket
address structure will be set to
<span class="type">INADDR_ANY</span>
for an IPv4 address or
<span class="type">IN6ADDR_ANY_INIT</span>
for an IPv6 address.
</p>
<p>
When
<code class="constant">ai_flags</code>
does not set the
<span class="type">AI_PASSIVE</span>
bit, the returned socket address structure will be ready
for use in a call to
<span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>
for a connection-oriented protocol or
<span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
<span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
or
<span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>
if a connectionless protocol was chosen.
The IP address portion of the socket address structure will be
set to the loopback address if
<em class="parameter"><code>hostname</code></em>
is a
<span class="type">NULL</span>
pointer and
<span class="type">AI_PASSIVE</span>
is not set in
<code class="constant">ai_flags</code>.
</p>
<p>
If
<code class="constant">ai_flags</code>
is set to
<span class="type">AI_NUMERICHOST</span>
it indicates that
<em class="parameter"><code>hostname</code></em>
should be treated as a numeric string defining an IPv4 or IPv6
address
and no name resolution should be attempted.
</p>
</dd>
</dl></div>
<p>
</p>
<p>
All other elements of the <span class="type">struct addrinfo</span> passed
via <em class="parameter"><code>hints</code></em> must be zero.
</p>
<p>
A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is
treated as if
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>.
</p>
<p>
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>
structures.
Each
<span class="type">struct addrinfo</span>
in this list cn be processed by following
the
<code class="constant">ai_next</code>
pointer, until a
<span class="type">NULL</span>
pointer is encountered.
The three members
<code class="constant">ai_family</code>,
<code class="constant">ai_socktype</code>,
and
<code class="constant">ai_protocol</code>
in each
returned
<span class="type">addrinfo</span>
structure contain the corresponding arguments for a call to
<span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
For each
<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>.
</p>
<p>
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
a successful call to
<code class="function">lwres_getaddrinfo()</code>
is released by
<code class="function">lwres_freeaddrinfo()</code>.
<em class="parameter"><code>ai</code></em>
is a pointer to a
<span class="type">struct addrinfo</span>
created by a call to
<code class="function">lwres_getaddrinfo()</code>.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2543786"></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)</span>
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>.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2542117"></a><h2>SEE ALSO</h2>
<p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
<span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>,
<span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</span>(3)</span>,
<span class="citerefentry"><span class="refentrytitle">lwres_gai_strerror</span>(3)</span>,
<span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>,
<span class="citerefentry"><span class="refentrytitle">getservbyname</span>(3)</span>,
<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>.
</p>
</div>
</div></body>
</html>