d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - This Source Code Form is subject to the terms of the Mozilla Public
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - License, v. 2.0. If a copy of the MPL was not distributed with this
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - file, You can obtain one at http://mozilla.org/MPL/2.0/.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1"></a><div class="titlepage"></div>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_getaddrinfo,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_freeaddrinfo
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User — socket address structure to host and service name
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_getaddrinfo</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>const char *<var class="pdparam">hostname</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>const char *<var class="pdparam">servname</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>const struct addrinfo *<var class="pdparam">hints</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>struct addrinfo **<var class="pdparam">res</var><code>)</code>;</td>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_freeaddrinfo</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>struct addrinfo *<var class="pdparam">ai</var><code>)</code>;</td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If the operating system does not provide a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the following structure is used:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinstruct addrinfo {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int ai_family; /* PF_xxx */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int ai_socktype; /* SOCK_xxx */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson size_t ai_addrlen; /* length of ai_addr */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *ai_canonname; /* canonical name for hostname */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson struct sockaddr *ai_addr; /* binary address */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson struct addrinfo *ai_next; /* next structure in linked list */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p><code class="function">lwres_getaddrinfo()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is used to get a list of IP addresses and port numbers for host
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>hostname</code></em> and service
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>servname</code></em>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The function is the lightweight resolver's implementation of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">getaddrinfo()</code> as defined in RFC2133.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>hostname</code></em> and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>servname</code></em> are pointers to null-terminated
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>hostname</code></em> is either a host name or a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein numeric host address string: a dotted decimal IPv4 address or an
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein IPv6 address. <em class="parameter"><code>servname</code></em> is either a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein decimal port number or a service name as listed in
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p><em class="parameter"><code>hints</code></em>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is an optional pointer to a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This structure can be used to provide hints concerning the type of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein that the caller supports or wishes to use.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The caller can supply the following structure elements in
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="variablelist"><dl class="variablelist">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">ai_family</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The protocol family that should be used.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein it means the caller will accept any protocol family supported by
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein operating system.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">ai_socktype</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein denotes the type of socket —
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein — that is wanted.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is zero the caller will accept any socket type.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">ai_protocol</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein indicates which transport protocol is wanted: IPPROTO_UDP or
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein IPPROTO_TCP.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is zero the caller will accept any protocol.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">ai_flags</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein bit is set, a successful call to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_getaddrinfo()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein will return a null-terminated string containing the canonical
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein of the specified hostname in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein of the first
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein structure returned.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein bit indicates that the returned socket address structure is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein for used in a call to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein In this case, if the hostname argument is a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein pointer, then the IP address portion of the socket
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein address structure will be set to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein for an IPv4 address or
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein for an IPv6 address.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein does not set the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein bit, the returned socket address structure will be ready
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein for use in a call to
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">connect</span>(2)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein for a connection-oriented protocol or
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">connect</span>(2)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">sendmsg</span>(2)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein if a connectionless protocol was chosen.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The IP address portion of the socket address structure will be
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein set to the loopback address if
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>hostname</code></em>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is not set in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein it indicates that
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>hostname</code></em>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein should be treated as a numeric string defining an IPv4 or IPv6
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and no name resolution should be attempted.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein All other elements of the <span class="type">struct addrinfo</span> passed
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein via <em class="parameter"><code>hints</code></em> must be zero.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein treated as if
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the caller provided a <span class="type">struct addrinfo</span> initialized to zero
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein with <code class="constant">ai_family</code>set to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein After a successful call to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_getaddrinfo()</code>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is a pointer to a linked list of one or more
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein in this list cn be processed by following
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein pointer, until a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein pointer is encountered.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The three members
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein structure contain the corresponding arguments for a call to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein structure in the list, the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein member points to a filled-in socket address structure of length
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein All of the information returned by
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_getaddrinfo()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is dynamically allocated: the addrinfo structures, and the socket
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein address structures and canonical host name strings pointed to by the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="constant">addrinfo</code>structures.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Memory allocated for the dynamically allocated structures created by
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein a successful call to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_getaddrinfo()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is released by
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_freeaddrinfo()</code>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is a pointer to a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein created by a call to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_getaddrinfo()</code>.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p><code class="function">lwres_getaddrinfo()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein returns zero on success or one of the error codes listed in
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">gai_strerror</span>(3)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein if an error occurs. If both <em class="parameter"><code>hostname</code></em> and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>servname</code></em> are <span class="type">NULL</span>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_getaddrinfo()</code> returns
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_getaddrinfo</span>(3)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_freeaddrinfo</span>(3)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_gai_strerror</span>(3)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">getservbyname</span>(3)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">connect</span>(2)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">sendmsg</span>(2)