#
# USAGI libinet6 - Basic Library for IPv6
#
# $USAGI: Libinet6,v 1.3.2.4 2001/12/30 20:09:50 mk Exp $
#

0. What is libinet6?

The GNU C Library, aka glibc, is the standard library for linux-based systems.
Glibc-2.1.3 and later are known to have basic functionality for IPv6.
However, some of them are also known to be buggy and/or not to be compliant
with current specifications (incl. RFC and/or Internet-drafts).

Our goal is to achieve stable / advanced ipv6 support in the standard library.
However it is not so easy to develop / test on it.  We decided to develop
such enhancements on a static library; it is called libinet6.
Libinet6 is designed not to affect existing applications unless you
link it.


1. Functions and Definitions in the Libinet6

You can use these functions and definitions with libinet6.

 - getaddrinfo(), getnameinfo() with sin6_scope_id support
 - getifaddrs()
 - SA_LEN()
 - new flags for getaddrinfo() and getnameinfo().
 - some missing functions described in latest specs, such as
   inet6_options_XXX() and inet6_rthdr_XXX().


2. Usage

1) getaddrinfo() / getnameinfo() with sin6_scope_id support.

Glibc-2.1.x does not support sin6_socpe_id.  Our libinet6 for 
glibc-2.1.x-based systems supports it.

Glibc-2.2.x support sin6_socpe_id contributed by us.
However, linux 2.2.x kernels do not have sin6_scope_id field in its struct 
sockaddr_in6.  Because of this inconsistency, you will get troubles 
if you want to use linux-2.2.x on glibc-2.2.x-based systems.
Our libinet6 has hacked getnameinfo() which accept linux-2.2.x-style 
struct sockaddr_in6 to avoid major troubles.

2) getifaddrs()

SIOCGIFADDR and its variants are used to get ipv4 address.
People want to get ipv6 addresses, but we cannot do it with this 
interface because struct sockaddr_in6{} is too bit to put it into struct
sockaddr{}.  BSDI designed new generic interface to get addresses;
IPv6 addresses, IPv4 addresses and MAC addresses.
Manpage will be installed under /usr/local/v6/man.

Basic usage is as follows:

	struct ifaddrs *ifap, *p;

	if (getifaddrs(&ifap)) {
		/* err */
		return NULL;	/* errno is set */
	}
    
	for (p=ifap ; p ; p = p->ifa_next) {
		if (!p->ifa_addr)
			continue;	/* for safety */
		if (p->ifa_addr->sa_family == AF_INET6) {
			/* What you want for IPv6 addresses */
		} else if(p->ifa_addr->sa_family == AF_INET) {
			/* What you want for IPv4 addresses */
		}
	}

	freeifaddrs(ifap);
   
3) SA_LEN

SA_LEN macro was removed from glibc-2.2.x, though it is useful for us.
You can use SA_LEN macro with defining "_USAGI" symbol;
It returns the sizeof struct sockaddr{}'s variants based on its
address-family type.

4) New Flags for getaddrinfo()

We added 3 new flags for getaddrinfo(), one flag for getnameinfo(), 
described in successor of RFC2553, aka RFC2553bis.

 For getaddrinfo():
 - AI_ADDRCONF
 - AI_V4MAPPED
 - AI_ALL

 For getnameinfo():
 - NI_NUMERICSCOPE

5) Other functions

Some functions described in latest specs such as 
inet6_option_XXX() and inet6_rthdr_XXX() were added.
See manpages, which will be installed under /usr/local/v6/man.

