lwres_getaddrinfo.html revision d6fa26d0adaec6c910115be34fe7a5a5f402c14f
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
c7ef13f6c9ef4436bc804b150e0a93307b11fa27Tinderbox User - Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User - This Source Code Form is subject to the terms of the Mozilla Public
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User - License, v. 2.0. If a copy of the MPL was not distributed with this
c57668a2fbbe558c1bd21652813616f2f517c469Tinderbox User - file, You can obtain one at http://mozilla.org/MPL/2.0/.
bed0874e1a09e810575328c4bfc346a47514b69fMark Andrews<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
e20309353e6246485c521278131d3fced73d7957Tinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
e20309353e6246485c521278131d3fced73d7957Tinderbox User<a name="id-1"></a><div class="titlepage"></div>
3cc98b8ecedcbc8465f1cf2740b966b315662430Automatic Updater<p>lwres_getaddrinfo, lwres_freeaddrinfo — socket address structure to host and service name</p>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre>
df4ebd8217d02dafc12145b55c4d93d0255d1ec7Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater<b class="fsfunc">lwres_getaddrinfo</b>(</code></td>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater<td>const char *<var class="pdparam">hostname</var>, </td>
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User<td>const char *<var class="pdparam">servname</var>, </td>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt<td>const struct addrinfo *<var class="pdparam">hints</var>, </td>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt<td>struct addrinfo **<var class="pdparam">res</var><code>)</code>;</td>
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<b class="fsfunc">lwres_freeaddrinfo</b>(</code></td>
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater<td>struct addrinfo *<var class="pdparam">ai</var><code>)</code>;</td>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater If the operating system does not provide a
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews the following structure is used:
e20309353e6246485c521278131d3fced73d7957Tinderbox Userstruct addrinfo {
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
24934f08b9ff81c2be711e566e8002d145573031Tinderbox User int ai_family; /* PF_xxx */
e20309353e6246485c521278131d3fced73d7957Tinderbox User int ai_socktype; /* SOCK_xxx */
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
7feccf248d2a20a2ae48b290f58ded5abc853e9aTinderbox User size_t ai_addrlen; /* length of ai_addr */
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews char *ai_canonname; /* canonical name for hostname */
c59750de3ea3c7d5890000fb4606e8f5835a52aaTinderbox User struct sockaddr *ai_addr; /* binary address */
80faf1588895fd26490f82f95a7a1b771df1c324Automatic Updater struct addrinfo *ai_next; /* next structure in linked list */
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<p><code class="function">lwres_getaddrinfo()</code>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater is used to get a list of IP addresses and port numbers for host
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater <em class="parameter"><code>hostname</code></em> and service
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews <em class="parameter"><code>servname</code></em>.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson The function is the lightweight resolver's implementation of
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater <code class="function">getaddrinfo()</code> as defined in RFC2133.
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater <em class="parameter"><code>hostname</code></em> and
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <em class="parameter"><code>servname</code></em> are pointers to null-terminated
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater strings or <span class="type">NULL</span>.
b871c7156eb037d41f53828c6fcb9cc876128962Mark Andrews <em class="parameter"><code>hostname</code></em> is either a host name or a
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews numeric host address string: a dotted decimal IPv4 address or an
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User IPv6 address. <em class="parameter"><code>servname</code></em> is either a
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User decimal port number or a service name as listed in
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User<p><em class="parameter"><code>hints</code></em>
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User is an optional pointer to a
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews This structure can be used to provide hints concerning the type of
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User that the caller supports or wishes to use.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The caller can supply the following structure elements in
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews <em class="parameter"><code>*hints</code></em>:
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews<div class="variablelist"><dl class="variablelist">
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews<dt><span class="term"><code class="constant">ai_family</code></span></dt>
a308b69ac66fadf66863484f301314d6e6a3f1d2Automatic Updater The protocol family that should be used.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews it means the caller will accept any protocol family supported by
b871c7156eb037d41f53828c6fcb9cc876128962Mark Andrews operating system.
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews<dt><span class="term"><code class="constant">ai_socktype</code></span></dt>
b871c7156eb037d41f53828c6fcb9cc876128962Mark Andrews denotes the type of socket —
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater — that is wanted.
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater is zero the caller will accept any socket type.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<dt><span class="term"><code class="constant">ai_protocol</code></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews indicates which transport protocol is wanted: IPPROTO_UDP or
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater is zero the caller will accept any protocol.
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater<dt><span class="term"><code class="constant">ai_flags</code></span></dt>
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark Andrews bit is set, a successful call to
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User <code class="function">lwres_getaddrinfo()</code>
c7ef13f6c9ef4436bc804b150e0a93307b11fa27Tinderbox User will return a null-terminated string containing the canonical
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User of the specified hostname in
f132a836c4e386b1af045dd8fe7106ae61b90bffAutomatic Updater <code class="constant">ai_canonname</code>
d642d3857129678797a01adee14fbd70335b05a9Mark Andrews of the first
609b8d08176469485edce25f3c2f50365bbd3819Mark Andrews structure returned.
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark Andrews bit indicates that the returned socket address structure is
8711e5c73ca872d59810760af0332194cbdd619bAutomatic Updater for used in a call to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>.
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrews In this case, if the hostname argument is a
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark Andrews pointer, then the IP address portion of the socket
6a9d2121152c94cb9e35832126c3f2e4d18d81edTinderbox User address structure will be set to
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrews for an IPv4 address or
bc0a53583d92309bebcf93c408e2f3247ebd3d3cAutomatic Updater <span class="type">IN6ADDR_ANY_INIT</span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater for an IPv6 address.
7f79131f9a8e804b93c57f3c679065cce878b726Automatic Updater does not set the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater bit, the returned socket address structure will be ready
609b8d08176469485edce25f3c2f50365bbd3819Mark Andrews for use in a call to
609b8d08176469485edce25f3c2f50365bbd3819Mark Andrews <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater for a connection-oriented protocol or
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>
5ecad47f69b3fd945472ab2900a9ff826a7ce2f6Automatic Updater if a connectionless protocol was chosen.
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark Andrews The IP address portion of the socket address structure will be
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrews set to the loopback address if
6a9d2121152c94cb9e35832126c3f2e4d18d81edTinderbox User <em class="parameter"><code>hostname</code></em>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater it indicates that
6a9d2121152c94cb9e35832126c3f2e4d18d81edTinderbox User <em class="parameter"><code>hostname</code></em>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews should be treated as a numeric string defining an IPv4 or IPv6
27c3c21f41520e8d6336d80a8094389e321cb6d2Mark Andrews and no name resolution should be attempted.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater All other elements of the <span class="type">struct addrinfo</span> passed
a792d42c3cdd6cd4608b936c0a06437b8c2d99ccTinderbox User via <em class="parameter"><code>hints</code></em> must be zero.
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is
dc5552b4df5e3821783821c8d4e734c1608c446eTinderbox User treated as if
cf7e98f59148b559946a7f1ca728471374f1eef3Automatic Updater the caller provided a <span class="type">struct addrinfo</span> initialized to zero
930f6069e5aa157cf6987cdafd412f5757a5a558Automatic Updater with <code class="constant">ai_family</code>set to
cf7e98f59148b559946a7f1ca728471374f1eef3Automatic Updater After a successful call to
c3fd32ed29e9e419bb56583f4272a506773b1ea0Automatic Updater <code class="function">lwres_getaddrinfo()</code>,
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <em class="parameter"><code>*res</code></em>
c3fd32ed29e9e419bb56583f4272a506773b1ea0Automatic Updater is a pointer to a linked list of one or more
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User in this list cn be processed by following
d642d3857129678797a01adee14fbd70335b05a9Mark Andrews pointer, until a
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews pointer is encountered.
9174e44c14b1cb91a651fa1dc29470438c246ab9Automatic Updater The three members
e2caa7536302de34de6cc04025abcd53dc3a499aAutomatic Updater <code class="constant">ai_socktype</code>,
f751b1576ee6fef4023bf7101d10167e4fe520f3Tinderbox User structure contain the corresponding arguments for a call to
f751b1576ee6fef4023bf7101d10167e4fe520f3Tinderbox User <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
b109432c3a939bff66a463be86c371bd88efe3aaAutomatic Updater structure in the list, the
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews member points to a filled-in socket address structure of length
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews All of the information returned by
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews <code class="function">lwres_getaddrinfo()</code>
3351ccbd5c1961404044f8273d54dad405f53960Mark Andrews is dynamically allocated: the addrinfo structures, and the socket
7d12a6b412fe47e6d6582923fd6954ab8cd0baebAutomatic Updater address structures and canonical host name strings pointed to by the
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews <code class="constant">addrinfo</code>structures.
0b57424d28c9a67018107133f9fbc0a7dcf057e2Mark Andrews Memory allocated for the dynamically allocated structures created by
7d12a6b412fe47e6d6582923fd6954ab8cd0baebAutomatic Updater a successful call to
0b57424d28c9a67018107133f9fbc0a7dcf057e2Mark Andrews <code class="function">lwres_getaddrinfo()</code>
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater is released by
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater <code class="function">lwres_freeaddrinfo()</code>.
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater <em class="parameter"><code>ai</code></em>
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater is a pointer to a
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater created by a call to
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater <code class="function">lwres_getaddrinfo()</code>.
82a986aaa5d3384a541b5a7d6dae8cf0726d6513Tinderbox User<p><code class="function">lwres_getaddrinfo()</code>
82a986aaa5d3384a541b5a7d6dae8cf0726d6513Tinderbox User returns zero on success or one of the error codes listed in
c7ef13f6c9ef4436bc804b150e0a93307b11fa27Tinderbox User <span class="citerefentry"><span class="refentrytitle">gai_strerror</span>(3)</span>
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews if an error occurs. If both <em class="parameter"><code>hostname</code></em> and
82a986aaa5d3384a541b5a7d6dae8cf0726d6513Tinderbox User <em class="parameter"><code>servname</code></em> are <span class="type">NULL</span>
b30ec46fec40a1b246f7965fbcd341fc6cfd1cc1Mark Andrews <code class="function">lwres_getaddrinfo()</code> returns
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User<p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</span>(3)</span>,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="citerefentry"><span class="refentrytitle">lwres_gai_strerror</span>(3)</span>,
7f79131f9a8e804b93c57f3c679065cce878b726Automatic Updater <span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>,
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <span class="citerefentry"><span class="refentrytitle">getservbyname</span>(3)</span>,
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>,
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrews <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>,
b13d89bd89878137c81b36a36596cca3920f27a4Automatic Updater <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.