lwres_getaddrinfo.docbook revision 14a656f94b1fd0ababd84a772228dfa52276ba15
6bdda696b3ea703c47e87fea61017ec655f91d92nd<!DOCTYPE book [
6bdda696b3ea703c47e87fea61017ec655f91d92nd<!ENTITY mdash "&#8212;">]>
6bdda696b3ea703c47e87fea61017ec655f91d92nd<!--
6bdda696b3ea703c47e87fea61017ec655f91d92nd - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
6bdda696b3ea703c47e87fea61017ec655f91d92nd - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
6bdda696b3ea703c47e87fea61017ec655f91d92nd -
6bdda696b3ea703c47e87fea61017ec655f91d92nd - Permission to use, copy, modify, and/or distribute this software for any
6bdda696b3ea703c47e87fea61017ec655f91d92nd - purpose with or without fee is hereby granted, provided that the above
6bdda696b3ea703c47e87fea61017ec655f91d92nd - copyright notice and this permission notice appear in all copies.
6bdda696b3ea703c47e87fea61017ec655f91d92nd -
0662ed52e814f8f08ef0e09956413a792584eddffuankg - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
6bdda696b3ea703c47e87fea61017ec655f91d92nd - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
6bdda696b3ea703c47e87fea61017ec655f91d92nd - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
6bdda696b3ea703c47e87fea61017ec655f91d92nd - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
6bdda696b3ea703c47e87fea61017ec655f91d92nd - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
6bdda696b3ea703c47e87fea61017ec655f91d92nd - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
6bdda696b3ea703c47e87fea61017ec655f91d92nd - PERFORMANCE OF THIS SOFTWARE.
6bdda696b3ea703c47e87fea61017ec655f91d92nd-->
6bdda696b3ea703c47e87fea61017ec655f91d92nd<!-- Converted by db4-upgrade version 1.0 -->
6bdda696b3ea703c47e87fea61017ec655f91d92nd<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
16b55a35cff91315d261d1baa776138af465c4e4fuankg <info>
16b55a35cff91315d261d1baa776138af465c4e4fuankg <date>2007-06-18</date>
16b55a35cff91315d261d1baa776138af465c4e4fuankg </info>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentryinfo>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <corpname>ISC</corpname>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </refentryinfo>
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refmeta>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentrytitle>lwres_getaddrinfo</refentrytitle>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <manvolnum>3</manvolnum>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refmiscinfo>BIND9</refmiscinfo>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </refmeta>
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd <docinfo>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <copyright>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <year>2004</year>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <year>2005</year>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <year>2007</year>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <year>2014</year>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </copyright>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <copyright>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <year>2000</year>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <year>2001</year>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <year>2003</year>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <holder>Internet Software Consortium.</holder>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </copyright>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </docinfo>
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refnamediv>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refname>lwres_getaddrinfo</refname>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refname>lwres_freeaddrinfo</refname>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refpurpose>socket address structure to host and service name</refpurpose>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </refnamediv>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refsynopsisdiv>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <funcsynopsis>
6bdda696b3ea703c47e87fea61017ec655f91d92nd<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg<funcprototype>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <funcdef>
6bdda696b3ea703c47e87fea61017ec655f91d92ndint
6bdda696b3ea703c47e87fea61017ec655f91d92nd<function>lwres_getaddrinfo</function></funcdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>const char *<parameter>hostname</parameter></paramdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>const char *<parameter>servname</parameter></paramdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </funcprototype>
6bdda696b3ea703c47e87fea61017ec655f91d92nd<funcprototype>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <funcdef>
6bdda696b3ea703c47e87fea61017ec655f91d92ndvoid
6bdda696b3ea703c47e87fea61017ec655f91d92nd<function>lwres_freeaddrinfo</function></funcdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg </funcprototype>
6bdda696b3ea703c47e87fea61017ec655f91d92nd</funcsynopsis>
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd <para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd If the operating system does not provide a
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>struct addrinfo</type>,
6bdda696b3ea703c47e87fea61017ec655f91d92nd the following structure is used:
6bdda696b3ea703c47e87fea61017ec655f91d92nd </para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <para><programlisting>
6bdda696b3ea703c47e87fea61017ec655f91d92ndstruct addrinfo {
6bdda696b3ea703c47e87fea61017ec655f91d92nd int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
6bdda696b3ea703c47e87fea61017ec655f91d92nd int ai_family; /* PF_xxx */
6bdda696b3ea703c47e87fea61017ec655f91d92nd int ai_socktype; /* SOCK_xxx */
6bdda696b3ea703c47e87fea61017ec655f91d92nd int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
6bdda696b3ea703c47e87fea61017ec655f91d92nd size_t ai_addrlen; /* length of ai_addr */
6bdda696b3ea703c47e87fea61017ec655f91d92nd char *ai_canonname; /* canonical name for hostname */
6bdda696b3ea703c47e87fea61017ec655f91d92nd struct sockaddr *ai_addr; /* binary address */
6bdda696b3ea703c47e87fea61017ec655f91d92nd struct addrinfo *ai_next; /* next structure in linked list */
6bdda696b3ea703c47e87fea61017ec655f91d92nd};
6bdda696b3ea703c47e87fea61017ec655f91d92nd</programlisting>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg </refsynopsisdiv>
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refsection><info><title>DESCRIPTION</title></info>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd <para><function>lwres_getaddrinfo()</function>
6bdda696b3ea703c47e87fea61017ec655f91d92nd is used to get a list of IP addresses and port numbers for host
6bdda696b3ea703c47e87fea61017ec655f91d92nd <parameter>hostname</parameter> and service
6bdda696b3ea703c47e87fea61017ec655f91d92nd <parameter>servname</parameter>.
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd The function is the lightweight resolver's implementation of
6bdda696b3ea703c47e87fea61017ec655f91d92nd <function>getaddrinfo()</function> as defined in RFC2133.
6bdda696b3ea703c47e87fea61017ec655f91d92nd <parameter>hostname</parameter> and
6bdda696b3ea703c47e87fea61017ec655f91d92nd <parameter>servname</parameter> are pointers to null-terminated
6bdda696b3ea703c47e87fea61017ec655f91d92nd strings or <type>NULL</type>.
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg
0662ed52e814f8f08ef0e09956413a792584eddffuankg <parameter>hostname</parameter> is either a host name or a
6bdda696b3ea703c47e87fea61017ec655f91d92nd numeric host address string: a dotted decimal IPv4 address or an
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg IPv6 address. <parameter>servname</parameter> is either a
6bdda696b3ea703c47e87fea61017ec655f91d92nd decimal port number or a service name as listed in
6bdda696b3ea703c47e87fea61017ec655f91d92nd <filename>/etc/services</filename>.
6bdda696b3ea703c47e87fea61017ec655f91d92nd </para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd <para><parameter>hints</parameter>
6bdda696b3ea703c47e87fea61017ec655f91d92nd is an optional pointer to a
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>struct addrinfo</type>.
6bdda696b3ea703c47e87fea61017ec655f91d92nd This structure can be used to provide hints concerning the type of
6bdda696b3ea703c47e87fea61017ec655f91d92nd socket
6bdda696b3ea703c47e87fea61017ec655f91d92nd that the caller supports or wishes to use.
0662ed52e814f8f08ef0e09956413a792584eddffuankg The caller can supply the following structure elements in
6bdda696b3ea703c47e87fea61017ec655f91d92nd <parameter>*hints</parameter>:
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd <variablelist>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <varlistentry>
0662ed52e814f8f08ef0e09956413a792584eddffuankg <term><constant>ai_family</constant></term>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd The protocol family that should be used.
6bdda696b3ea703c47e87fea61017ec655f91d92nd When
6bdda696b3ea703c47e87fea61017ec655f91d92nd <constant>ai_family</constant>
6bdda696b3ea703c47e87fea61017ec655f91d92nd is set to
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>PF_UNSPEC</type>,
6bdda696b3ea703c47e87fea61017ec655f91d92nd it means the caller will accept any protocol family supported by
6bdda696b3ea703c47e87fea61017ec655f91d92nd the
0662ed52e814f8f08ef0e09956413a792584eddffuankg operating system.
6bdda696b3ea703c47e87fea61017ec655f91d92nd </para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </listitem>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg </varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <term><constant>ai_socktype</constant></term>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <listitem>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg <para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd denotes the type of socket &mdash;
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>SOCK_STREAM</type>,
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>SOCK_DGRAM</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd or
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>SOCK_RAW</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd &mdash; that is wanted.
6bdda696b3ea703c47e87fea61017ec655f91d92nd When
6bdda696b3ea703c47e87fea61017ec655f91d92nd <constant>ai_socktype</constant>
6bdda696b3ea703c47e87fea61017ec655f91d92nd is zero the caller will accept any socket type.
6bdda696b3ea703c47e87fea61017ec655f91d92nd </para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <term><constant>ai_protocol</constant></term>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd indicates which transport protocol is wanted: IPPROTO_UDP or
6bdda696b3ea703c47e87fea61017ec655f91d92nd IPPROTO_TCP.
6bdda696b3ea703c47e87fea61017ec655f91d92nd If
6bdda696b3ea703c47e87fea61017ec655f91d92nd <constant>ai_protocol</constant>
6bdda696b3ea703c47e87fea61017ec655f91d92nd is zero the caller will accept any protocol.
6bdda696b3ea703c47e87fea61017ec655f91d92nd </para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <term><constant>ai_flags</constant></term>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <listitem>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg <para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd Flag bits.
6bdda696b3ea703c47e87fea61017ec655f91d92nd If the
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>AI_CANONNAME</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd bit is set, a successful call to
6bdda696b3ea703c47e87fea61017ec655f91d92nd <function>lwres_getaddrinfo()</function>
6bdda696b3ea703c47e87fea61017ec655f91d92nd will return a null-terminated string containing the canonical
6bdda696b3ea703c47e87fea61017ec655f91d92nd name
6bdda696b3ea703c47e87fea61017ec655f91d92nd of the specified hostname in
6bdda696b3ea703c47e87fea61017ec655f91d92nd <constant>ai_canonname</constant>
6bdda696b3ea703c47e87fea61017ec655f91d92nd of the first
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>addrinfo</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd structure returned.
6bdda696b3ea703c47e87fea61017ec655f91d92nd Setting the
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>AI_PASSIVE</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd bit indicates that the returned socket address structure is
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg intended
6bdda696b3ea703c47e87fea61017ec655f91d92nd for used in a call to
6bdda696b3ea703c47e87fea61017ec655f91d92nd <citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </citerefentry>.
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd In this case, if the hostname argument is a
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>NULL</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd pointer, then the IP address portion of the socket
6bdda696b3ea703c47e87fea61017ec655f91d92nd address structure will be set to
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>INADDR_ANY</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd for an IPv4 address or
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>IN6ADDR_ANY_INIT</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd for an IPv6 address.
6bdda696b3ea703c47e87fea61017ec655f91d92nd </para>
8ffac2c334103c0336602aaede650cb578611151fuankg <para>
8ffac2c334103c0336602aaede650cb578611151fuankg When
6bdda696b3ea703c47e87fea61017ec655f91d92nd <constant>ai_flags</constant>
6bdda696b3ea703c47e87fea61017ec655f91d92nd does not set the
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg <type>AI_PASSIVE</type>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg bit, the returned socket address structure will be ready
6bdda696b3ea703c47e87fea61017ec655f91d92nd for use in a call to
6bdda696b3ea703c47e87fea61017ec655f91d92nd <citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd for a connection-oriented protocol or
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg <citerefentry>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </citerefentry>,
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd <citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg </citerefentry>,
6bdda696b3ea703c47e87fea61017ec655f91d92nd
6bdda696b3ea703c47e87fea61017ec655f91d92nd or
6bdda696b3ea703c47e87fea61017ec655f91d92nd <citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd if a connectionless protocol was chosen.
6bdda696b3ea703c47e87fea61017ec655f91d92nd The IP address portion of the socket address structure will be
6bdda696b3ea703c47e87fea61017ec655f91d92nd set to the loopback address if
6bdda696b3ea703c47e87fea61017ec655f91d92nd <parameter>hostname</parameter>
6bdda696b3ea703c47e87fea61017ec655f91d92nd is a
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg <type>NULL</type>
0662ed52e814f8f08ef0e09956413a792584eddffuankg pointer and
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>AI_PASSIVE</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd is not set in
6bdda696b3ea703c47e87fea61017ec655f91d92nd <constant>ai_flags</constant>.
6bdda696b3ea703c47e87fea61017ec655f91d92nd </para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <para>
6bdda696b3ea703c47e87fea61017ec655f91d92nd If
6bdda696b3ea703c47e87fea61017ec655f91d92nd <constant>ai_flags</constant>
6bdda696b3ea703c47e87fea61017ec655f91d92nd is set to
6bdda696b3ea703c47e87fea61017ec655f91d92nd <type>AI_NUMERICHOST</type>
6bdda696b3ea703c47e87fea61017ec655f91d92nd it indicates that
6bdda696b3ea703c47e87fea61017ec655f91d92nd <parameter>hostname</parameter>
6bdda696b3ea703c47e87fea61017ec655f91d92nd should be treated as a numeric string defining an IPv4 or IPv6
0662ed52e814f8f08ef0e09956413a792584eddffuankg address
6bdda696b3ea703c47e87fea61017ec655f91d92nd and no name resolution should be attempted.
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg </para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
All other elements of the <type>struct addrinfo</type> passed
via <parameter>hints</parameter> must be zero.
</para>
<para>
A <parameter>hints</parameter> of <type>NULL</type> is
treated as if
the caller provided a <type>struct addrinfo</type> initialized to zero
with <constant>ai_family</constant>set to
<constant>PF_UNSPEC</constant>.
</para>
<para>
After a successful call to
<function>lwres_getaddrinfo()</function>,
<parameter>*res</parameter>
is a pointer to a linked list of one or more
<type>addrinfo</type>
structures.
Each
<type>struct addrinfo</type>
in this list cn be processed by following
the
<constant>ai_next</constant>
pointer, until a
<type>NULL</type>
pointer is encountered.
The three members
<constant>ai_family</constant>,
<constant>ai_socktype</constant>,
and
<constant>ai_protocol</constant>
in each
returned
<type>addrinfo</type>
structure contain the corresponding arguments for a call to
<citerefentry>
<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
For each
<type>addrinfo</type>
structure in the list, the
<constant>ai_addr</constant>
member points to a filled-in socket address structure of length
<constant>ai_addrlen</constant>.
</para>
<para>
All of the information returned by
<function>lwres_getaddrinfo()</function>
is dynamically allocated: the addrinfo structures, and the socket
address structures and canonical host name strings pointed to by the
<constant>addrinfo</constant>structures.
Memory allocated for the dynamically allocated structures created by
a successful call to
<function>lwres_getaddrinfo()</function>
is released by
<function>lwres_freeaddrinfo()</function>.
<parameter>ai</parameter>
is a pointer to a
<type>struct addrinfo</type>
created by a call to
<function>lwres_getaddrinfo()</function>.
</para>
</refsection>
<refsection><info><title>RETURN VALUES</title></info>
<para><function>lwres_getaddrinfo()</function>
returns zero on success or one of the error codes listed in
<citerefentry>
<refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
if an error occurs. If both <parameter>hostname</parameter> and
<parameter>servname</parameter> are <type>NULL</type>
<function>lwres_getaddrinfo()</function> returns
<errorcode>EAI_NONAME</errorcode>.
</para>
</refsection>
<refsection><info><title>SEE ALSO</title></info>
<para><citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>RFC2133</refentrytitle>
</citerefentry>,
<citerefentry>
<refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
</para>
</refsection>
</refentry>