]>

 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")

 -

 - This Source Code Form is subject to the terms of the Mozilla Public

 - License, v. 2.0. If a copy of the MPL was not distributed with this

 - file, You can obtain one at http://mozilla.org/MPL/2.0/.

 -

 - See the COPYRIGHT file distributed with this work for additional

 - information regarding copyright ownership.

-->

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

  <info>

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

  </info>

  <refentryinfo>

    <corpname>ISC</corpname>

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

  </refentryinfo>

  <refmeta>

    <refentrytitle>lwres_getaddrinfo</refentrytitle>

    <manvolnum>3</manvolnum>

    <refmiscinfo>BIND9</refmiscinfo>

  </refmeta>

  <docinfo>

    <copyright>

      <year>2000</year>

      <year>2001</year>

      <year>2003</year>

      <year>2004</year>

      <year>2005</year>

      <year>2007</year>

      <year>2014</year>

      <year>2015</year>

      <year>2016</year>

      <year>2018</year>

      <year>2019</year>

      <year>2020</year>

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

    </copyright>

  </docinfo>

  <refnamediv>

    <refname>lwres_getaddrinfo</refname>

    <refname>lwres_freeaddrinfo</refname>

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

  </refnamediv>

  <refsynopsisdiv>

    <funcsynopsis>

<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>

<funcprototype>

        <funcdef>

int

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

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

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

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

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

        </funcprototype>

<funcprototype>

        <funcdef>

void

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

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

      </funcprototype>

</funcsynopsis>

    <para>

      If the operating system does not provide a

      <type>struct addrinfo</type>,

      the following structure is used:

    </para>

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

  <refsection><info><title>DESCRIPTION</title></info>

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

            </para>

          </listitem>

        </varlistentry>

        <varlistentry>

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

          <listitem>

            <para>

              denotes the type of socket —

              <type>SOCK_STREAM</type>,

              <type>SOCK_DGRAM</type>

              or

              <type>SOCK_RAW</type>

              — that is wanted.

              When

              <constant>ai_socktype</constant>

              is zero the caller will accept any socket type.

            </para>

          </listitem>

        </varlistentry>

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

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

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