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

0N/A

1472N/A

1472N/A<refentry>

0N/A

0N/A<refentryinfo>

0N/A<date>Jun 30, 2000</date>

0N/A</refentryinfo>

0N/A

0N/A<refmeta>

0N/A<refentrytitle>lwres_getaddrinfo</refentrytitle>

91N/A<manvolnum>3</manvolnum>

0N/A<refmiscinfo>BIND9</refmiscinfo>

0N/A</refmeta>

0N/A

0N/A<refnamediv>

0N/A<refname>lwres_getaddrinfo</refname>

0N/A<refname>lwres_freeaddrinfo</refname>

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

0N/A</refnamediv>

0N/A<refsynopsisdiv>

0N/A<funcsynopsis>

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

0N/A<funcprototype>

3041N/A<funcdef>

3041N/Aint

2080N/A<function>lwres_getaddrinfo</function></funcdef>

2080N/A<paramdef>const char *hostname</paramdef>

3041N/A<paramdef>const char *servname</paramdef>

3041N/A<paramdef>const struct addrinfo *hints</paramdef>

3041N/A<paramdef>struct addrinfo **res</paramdef>

3041N/A</funcprototype>

3041N/A<funcprototype>

3041N/A<funcdef>

0N/Avoid

0N/A<function>lwres_freeaddrinfo</function></funcdef>

0N/A<paramdef>struct addrinfo *ai</paramdef>

0N/A</funcprototype>

1879N/A</funcsynopsis>

1879N/A

0N/A<para>

0N/AIf the operating system does not provide a

1879N/A<type>struct addrinfo</type>,

0N/Athe following structure is used:

0N/A

475N/A<programlisting>

3178N/Astruct addrinfo {

475N/A int ai_flags; /* AI_PASSIVE, AI_CANONNAME */

0N/A int ai_family; /* PF_xxx */

3178N/A int ai_socktype; /* SOCK_xxx */

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

0N/A size_t ai_addrlen; /* length of ai_addr */

603N/A char *ai_canonname; /* canonical name for hostname */

603N/A struct sockaddr *ai_addr; /* binary address */

0N/A struct addrinfo *ai_next; /* next structure in linked list */

0N/A};

0N/A</programlisting>

0N/A</para>

0N/A

0N/A</refsynopsisdiv>

0N/A

0N/A<refsect1>

0N/A<title>DESCRIPTION</title>

0N/A<para>

0N/A<function>lwres_getaddrinfo()</function>

0N/Ais used to get a list of IP addresses and port numbers for host

0N/A<parameter>hostname</parameter>

0N/Aand service

0N/A<parameter>servname</parameter>.

0N/A

0N/AThe function is the lightweight resolver's implementation of

0N/A<function>getaddrinfo()</function>

0N/Aas defined in RFC2133.

0N/A<parameter>hostname</parameter>

0N/Aand

0N/A<parameter>servname</parameter>

0N/Aare pointers to null-terminated

0N/Astrings or

0N/A<type>NULL</type>.

0N/A

0N/A<parameter>hostname</parameter>

0N/Ais either a host name or a numeric host address string: a dotted decimal

0N/AIPv4 address or an IPv6 address.

0N/A<parameter>servname</parameter>

0N/Ais either a decimal port number or a service name as listed in

0N/A<filename>/etc/services</filename>.

0N/A</para>

0N/A

0N/A<para>

0N/A<parameter>hints</parameter>

0N/Ais an optional pointer to a

0N/A<type>struct addrinfo</type>.

0N/AThis structure can be used to provide hints concerning the type of socket

0N/Athat the caller supports or wishes to use.

3178N/AThe caller can supply the following structure elements in

0N/A<parameter>*hints</parameter>:

0N/A

0N/A<variablelist>

0N/A<varlistentry><term><constant>ai_family</constant></term>

0N/A<listitem>

0N/A<para>The protocol family that should be used.

0N/AWhen

0N/A<constant>ai_family</constant>

0N/Ais set to

0N/A<type>PF_UNSPEC</type>,

0N/Ait means the caller will accept any protocol family supported by the

0N/Aoperating system.

0N/A</para></listitem></varlistentry>

0N/A<varlistentry><term><constant>ai_socktype</constant></term>

0N/A<listitem>

0N/A<para>

0N/Adenotes the type of socket &mdash;

0N/A<type>SOCK_STREAM</type>,

0N/A<type>SOCK_DGRAM</type>

0N/Aor

0N/A<type>SOCK_RAW</type>

0N/A&mdash; that is wanted.

0N/AWhen

3487N/A<constant>ai_socktype</constant>

3487N/Ais zero the caller will accept any socket type.

3487N/A</para>

3487N/A</listitem>

1396N/A</varlistentry>

475N/A<varlistentry><term><constant>ai_protocol</constant></term>

475N/A<listitem>

475N/A<para>

475N/Aindicates which transport protocol is wanted: IPPROTO_UDP or

475N/AIPPROTO_TCP.

475N/AIf

475N/A<constant>ai_protocol</constant>

475N/Ais zero the caller will accept any protocol.

1526N/A</para>

1526N/A</listitem>

1526N/A</varlistentry>

1396N/A<varlistentry><term><constant>ai_flags</constant></term>

1526N/A<listitem>

0N/A<para>

0N/AFlag bits.

0N/AIf the

0N/A<type>AI_CANONNAME</type>

0N/Abit is set, a successful call to

0N/A<function>lwres_getaddrinfo()</function>

0N/Awill return a null-terminated string containing the canonical name

0N/Aof the specified hostname in

0N/A<constant>ai_canonname</constant>

0N/Aof the first

0N/A<type>addrinfo</type>

0N/Astructure returned.

91N/ASetting the

0N/A<type>AI_PASSIVE</type>

475N/Abit indicates that the returned socket address structure is intended

475N/Afor used in a call to

0N/A<citerefentry>

0N/A<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>

0N/A</citerefentry>.

0N/A

0N/AIn this case, if the hostname argument is a

0N/A<type>NULL</type>

0N/Apointer, then the IP address portion of the socket

0N/Aaddress structure will be set to

0N/A<type>INADDR_ANY</type>

475N/Afor an IPv4 address or

0N/A<type>IN6ADDR_ANY_INIT</type>

0N/Afor an IPv6 address.

0N/A</para>

0N/A<para>

0N/AWhen

0N/A<constant>ai_flags</constant>

0N/Adoes not set the

0N/A<type>AI_PASSIVE</type>

0N/Abit, the returned socket address structure will be ready

0N/Afor use in a call to

0N/A<citerefentry>

0N/A<refentrytitle>connect</refentrytitle><manvolnum>2

0N/A</manvolnum>

0N/A</citerefentry>

0N/Afor a connection-oriented protocol or

0N/A<citerefentry>

0N/A<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>

0N/A</citerefentry>,

0N/A

0N/A<citerefentry>

0N/A<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>

0N/A</citerefentry>,

0N/A

475N/Aor

475N/A<citerefentry>

475N/A<refentrytitle>sendmsg</refentrytitle><manvolnum>2

475N/A</manvolnum>

475N/A</citerefentry>

475N/Aif a connectionless protocol was chosen.

475N/AThe IP address portion of the socket address structure will be

475N/Aset to the loopback address if

475N/A<parameter>hostname</parameter>

0N/Ais a

0N/A<type>NULL</type>

0N/Apointer and

0N/A<type>AI_PASSIVE</type>

3178N/Ais not set in

0N/A<constant>ai_flags</constant>.

0N/A</para>

0N/A<para>

0N/AIf

0N/A<constant>ai_flags</constant>

0N/Ais set to

3178N/A<type>AI_NUMERICHOST</type>

0N/Ait indicates that

0N/A<parameter>hostname</parameter>

0N/Ashould be treated as a numeric string defining an IPv4 or IPv6 address

0N/Aand no name resolution should be attempted.

0N/A</para>

0N/A</listitem>

0N/A</varlistentry>

0N/A</variablelist>

0N/A</para>

0N/A

0N/A<para>

0N/AAll 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>