
		   getaddrinfo() and getnameinfo()
		    for traditional IPv4 systems

			  Motoyuki Kasahara


This program provides getaddrinfo() and getnameinfo() described in
RFC2133, 2553 and 3493.  These functions are mainly used for IPv6
application to resolve hostname or address.

This program is designed to be working on traditional IPv4 systems
which don't have those functions.  Therefore, this implementation
supports IPv4 only.

This program is useful for application which should support both IPv6
and traditional IPv4 systems.  Use genuine getaddrinfo() and getnameinfo()
provided by system if the system supports IPv6.  Otherwise, use this
program.

This program also provides freeaddrinfo() and gai_strerror().


1. How to use getaddrinfo() and getnameinfo()

This is intended to be used in combination with GNU Autoconf.
Add the following code to `configure.ac' or `configure.in' of your
application, if missing.

    AC_PROG_CC
    AC_C_CONST
    AC_HEADER_STDC
    AC_CHECK_HEADERS(string.h, memory.h, stdlib.h)
    AC_CHECK_FUNCS(memcpy)
    AC_REPLACE_FUNCS(memset)
    AC_TYPE_SOCKLEN_T
    AC_TYPE_IN_PORT_T
    AC_DECL_H_ERRNO

    AC_CHECK_FUNCS(getaddrinfo getnameinfo)
    if test "$ac_cv_func_getaddrinfo$ac_cv_func_getnameinfo" != yesyes ; then
        AC_LIBOBJ(getaddrinfo)
    fi

The M4 macro AC_TYPE_SOCKLEN_T and AC_TYPE_IN_PORT_T are defined
`m4/sockinttypes.m4'.  AC_DECL_H_ERRNO is defined by `m4/herrno.m4'.

To use this program in your application, insert the following lines to
C source files after including `sys/types.h', `sys/socket.h' and
`netdb.h'.  `getaddrinfo.h' defines `struct addrinfo' and AI_, NI_,
EAI_ macros.

    #if !defined(HAVE_GETADDRINFO) || !defined(HAVE_GETNAMEINFO)
    #include "getaddrinfo.h"
    #endif

You also have to compile `getaddrinfo.c' and link its object file to
your application.  Note that getaddrinfo() and getnameinfo() of this
program are NOT thread safe, unless the cpp macro ENABLE_PTHREAD is
defined.


2. IPv6 programming supplement

You may want more macros related to IPv6 such as PF_INET6.  For
example, your source might contain a code like this:

    if (getaddrinfo(NULL, port_string, &hints, &res) == 0) {
        for (r = res; r != NULL; r = r->ai_next) {
            if (r->ai_family != PF_INET && r->ai_family != PF_INET6)
                continue;
	    /* ... */
        }
    }

`dummyin6.h' provides macros including PF_INET6, types and external
variables used for basic IPv6 programming.  See `dummyin6.h' to know
what it defines.

To use `dummyin6.h', add the following code to `configure.ac' or
`configure.in' of your application.

    AC_STRUCT_IN6_ADDR
    AC_STRUCT_SOCKADDR_IN6
    AC_STRUCT_SOCKADDR_STORAGE
    AC_DECL_IN6ADDR_ANY
    AC_DECL_IN6ADDR_LOOPBACK
    AC_TYPE_SA_FAMILY_T

AC_STRUCT_IN6_ADDR, AC_DECL_IN6ADDR_ANY and AC_DECL_IN6ADDR_LOOPBACK
are defined by `m4/in6addr.m4'.  AC_STRUCT_SOCKADDR_IN6 and
AC_STRUCT_SOCKADDR_STORAGE are defined by `m4/sockaddrin6.m4'.
AC_TYPE_SA_FAMILY_T is defined by `m4/sockinttypes.m4'.

Then, add the code to C source files.  `dummyin6.h' must be included
just before `getaddrinfo.h'.

    #include "dummyin6.h"

    #if !defined(HAVE_GETADDRINFO) || !defined(HAVE_GETNAMEINFO)
    #include "getaddrinfo.h"
    #endif

You also have to compile `dimmyin6.c' and link its object file to
your application.


3. Test

Type the following commands to execute test programs:

    ./configure
    make
    make check


4. Restriction

* Since `struct sockaddr_storage' defined by `dummyin6.h' is merely
  alias of `sturct sockaddr_in', it has no ss_ or __ss_ member (e.g.
  ss_family).
* `hints->ai_protocol' given to getaddrinfo() is ignored.


5. License

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Neither the name of the project nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
