<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<refentry>

<refentryinfo>

<date>Jun 30, 2000</date>

</refentryinfo>

<refmeta>

<refentrytitle>lwres_getaddrinfo</refentrytitle>

<manvolnum>3</manvolnum>

<refmiscinfo>BIND9</refmiscinfo>

</refmeta>

<refnamediv>

<refname>lwres_getaddrinfo</refname>

<refname>lwres_freeaddrinfo</refname>

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

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

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

<funcprototype>

<funcdef>

int

<function>lwres_getaddrinfo</function></funcdef>

<paramdef>const char *hostname</paramdef>

<paramdef>const char *servname</paramdef>

<paramdef>const struct addrinfo *hints</paramdef>

<paramdef>struct addrinfo **res</paramdef>

</funcprototype>

<funcprototype>

<funcdef>

void

<function>lwres_freeaddrinfo</function></funcdef>

<paramdef>struct addrinfo *ai</paramdef>

</funcprototype>

</funcsynopsis>

<para>

If the operating system does not provide a

<type>struct addrinfo</type>,

the following structure is used:

<programlisting>

struct addrinfo {

int ai_flags; /* AI_PASSIVE, AI_CANONNAME */

int ai_family; /* PF_xxx */

int ai_socktype; /* SOCK_xxx */

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

size_t ai_addrlen; /* length of ai_addr */

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

struct sockaddr *ai_addr; /* binary address */

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

};

</programlisting>

</para>

</refsynopsisdiv>

<refsect1>

<title>DESCRIPTION</title>

<para>

<function>lwres_getaddrinfo()</function>

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

<parameter>hostname</parameter>

and service

<parameter>servname</parameter>.

The function is the lightweight resolver's implementation of

<function>getaddrinfo()</function>

as defined in RFC2133.

<parameter>hostname</parameter>

and

<parameter>servname</parameter>

are pointers to null-terminated

strings or

<type>NULL</type>.

<parameter>hostname</parameter>

is either a host name or a numeric host address string: a dotted decimal

IPv4 address or an IPv6 address.

<parameter>servname</parameter>

is either a decimal port number or a service name as listed in

<filename>/etc/services</filename>.

</para>

<para>

<parameter>hints</parameter>

is an optional pointer to a

<type>struct addrinfo</type>.

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

that the caller supports or wishes to use.

The caller can supply the following structure elements in

<parameter>*hints</parameter>:

<variablelist>

<varlistentry><term><constant>ai_family</constant></term>

<listitem>

<para>The protocol family that should be used.

When

<constant>ai_family</constant>

is set to

<type>PF_UNSPEC</type>,

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

operating system.

<varlistentry><term><constant>ai_socktype</constant></term>

<listitem>

<para>

denotes the type of socket &mdash;

<type>SOCK_STREAM</type>,

<type>SOCK_DGRAM</type>

or

<type>SOCK_RAW</type>

&mdash; that is wanted.

When

<constant>ai_socktype</constant>

is zero the caller will accept any socket type.

</para>

</listitem>

<varlistentry><term><constant>ai_protocol</constant></term>

<listitem>

<para>

indicates which transport protocol is wanted: IPPROTO_UDP or

IPPROTO_TCP.

If

<constant>ai_protocol</constant>

is zero the caller will accept any protocol.

</para>

</listitem>

<varlistentry><term><constant>ai_flags</constant></term>

<listitem>

<para>

Flag bits.

If the

<type>AI_CANONNAME</type>

bit is set, a successful call to

<function>lwres_getaddrinfo()</function>

will return a a null-terminated string containing the canonical name

of the specified hostname in

<constant>ai_canonname</constant>

of the first

<type>addrinfo</type>

structure returned.

Setting the

<type>AI_PASSIVE</type>

bit indicates that the returned socket address structure is intended

for used in a call to

<citerefentry>

<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>

</citerefentry>.

In this case, if the hostname argument is a

<type>NULL</type>

pointer, then the IP address portion of the socket

address structure will be set to

<type>INADDR_ANY</type>

for an IPv4 address or

<type>IN6ADDR_ANY_INIT</type>

for an IPv6 address.

</para>

<para>

When

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

</variablelist>

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

</refsect1>

<refsect1>

<title>RETURN VALUES</title>

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

</refsect1>

<refsect1>

<title>SEE ALSO</title>

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

</refsect1>

</refentry>