6031e9c7eb72435516a6828deb2e97533ed0382dludovicp<!DOCTYPE book [

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp<!ENTITY mdash "&#8212;">]>

3437829f938dbb44527d91fbbc5f430a1243c5a5JnRouvignac

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <info>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <date>2007-06-18</date>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </info>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refentryinfo>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <corpname>ISC</corpname>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <corpauthor>Internet Systems Consortium, Inc.</corpauthor>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </refentryinfo>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refmeta>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refentrytitle>lwres_getaddrinfo</refentrytitle>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <manvolnum>3</manvolnum>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refmiscinfo>BIND9</refmiscinfo>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </refmeta>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <docinfo>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <copyright>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <year>2004</year>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <year>2005</year>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <year>2007</year>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <year>2014</year>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <year>2015</year>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </copyright>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <copyright>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <year>2000</year>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <year>2001</year>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <year>2003</year>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <holder>Internet Software Consortium.</holder>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </copyright>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </docinfo>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refnamediv>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refname>lwres_getaddrinfo</refname>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refname>lwres_freeaddrinfo</refname>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refpurpose>socket address structure to host and service name</refpurpose>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </refnamediv>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refsynopsisdiv>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <funcsynopsis>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp<funcprototype>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <funcdef>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicpint

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp<function>lwres_getaddrinfo</function></funcdef>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <paramdef>const char *<parameter>hostname</parameter></paramdef>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <paramdef>const char *<parameter>servname</parameter></paramdef>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </funcprototype>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp<funcprototype>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <funcdef>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicpvoid

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp<function>lwres_freeaddrinfo</function></funcdef>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </funcprototype>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp</funcsynopsis>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp If the operating system does not provide a

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>struct addrinfo</type>,

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp the following structure is used:

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <para><programlisting>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicpstruct addrinfo {

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp int ai_flags; /* AI_PASSIVE, AI_CANONNAME */

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp int ai_family; /* PF_xxx */

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp int ai_socktype; /* SOCK_xxx */

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp size_t ai_addrlen; /* length of ai_addr */

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp char *ai_canonname; /* canonical name for hostname */

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp struct sockaddr *ai_addr; /* binary address */

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp struct addrinfo *ai_next; /* next structure in linked list */

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp};

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp</programlisting>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </refsynopsisdiv>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refsection><info><title>DESCRIPTION</title></info>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <para><function>lwres_getaddrinfo()</function>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp is used to get a list of IP addresses and port numbers for host

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <parameter>hostname</parameter> and service

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <parameter>servname</parameter>.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp The function is the lightweight resolver's implementation of

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <function>getaddrinfo()</function> as defined in RFC2133.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <parameter>hostname</parameter> and

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <parameter>servname</parameter> are pointers to null-terminated

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp strings or <type>NULL</type>.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <parameter>hostname</parameter> is either a host name or a

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp numeric host address string: a dotted decimal IPv4 address or an

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp IPv6 address. <parameter>servname</parameter> is either a

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp decimal port number or a service name as listed in

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <filename>/etc/services</filename>.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <para><parameter>hints</parameter>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp is an optional pointer to a

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>struct addrinfo</type>.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp This structure can be used to provide hints concerning the type of

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp socket

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp that the caller supports or wishes to use.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp The caller can supply the following structure elements in

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <parameter>*hints</parameter>:

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <variablelist>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <varlistentry>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <term><constant>ai_family</constant></term>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <listitem>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp The protocol family that should be used.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp When

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <constant>ai_family</constant>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp is set to

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>PF_UNSPEC</type>,

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp it means the caller will accept any protocol family supported by

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp the

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp operating system.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </listitem>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </varlistentry>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <varlistentry>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <term><constant>ai_socktype</constant></term>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <listitem>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp denotes the type of socket &mdash;

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>SOCK_STREAM</type>,

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>SOCK_DGRAM</type>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp or

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>SOCK_RAW</type>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp &mdash; that is wanted.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp When

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <constant>ai_socktype</constant>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp is zero the caller will accept any socket type.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </listitem>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </varlistentry>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <varlistentry>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <term><constant>ai_protocol</constant></term>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <listitem>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp indicates which transport protocol is wanted: IPPROTO_UDP or

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp IPPROTO_TCP.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp If

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <constant>ai_protocol</constant>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp is zero the caller will accept any protocol.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </listitem>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </varlistentry>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <varlistentry>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <term><constant>ai_flags</constant></term>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <listitem>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp Flag bits.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp If the

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>AI_CANONNAME</type>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp bit is set, a successful call to

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <function>lwres_getaddrinfo()</function>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp will return a null-terminated string containing the canonical

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp name

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp of the specified hostname in

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <constant>ai_canonname</constant>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp of the first

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>addrinfo</type>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp structure returned.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp Setting the

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>AI_PASSIVE</type>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp bit indicates that the returned socket address structure is

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp intended

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp for used in a call to

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <citerefentry>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </citerefentry>.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp In this case, if the hostname argument is a

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>NULL</type>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp pointer, then the IP address portion of the socket

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp address structure will be set to

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>INADDR_ANY</type>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp for an IPv4 address or

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <type>IN6ADDR_ANY_INIT</type>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp for an IPv6 address.

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp </para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <para>

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp When

6031e9c7eb72435516a6828deb2e97533ed0382dludovicp <constant>ai_flags</constant>

does not set the

<type>AI_PASSIVE</type>

bit, the returned socket address structure will be ready

for use in a call to

<citerefentry>

<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>

</citerefentry>

for a connection-oriented protocol or

<citerefentry>

<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>

</citerefentry>,

or

<citerefentry>

<refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>

</citerefentry>

if a connectionless protocol was chosen.

The IP address portion of the socket address structure will be

set to the loopback address if

<parameter>hostname</parameter>

is a

<type>NULL</type>

pointer and

<type>AI_PASSIVE</type>

is not set in

<constant>ai_flags</constant>.

</para>

<para>

If

<constant>ai_flags</constant>

is set to

<type>AI_NUMERICHOST</type>

it indicates that

<parameter>hostname</parameter>

should be treated as a numeric string defining an IPv4 or IPv6

address

and no name resolution should be attempted.

</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>