IPv6-ready python 1.5.x
KAME Project
$Id: README.v6,v 1.8 2000/01/19 15:56:37 itojun Exp $


This patchkit enables python 1.5.x to perform AF_INET6 socket operations.
The only affected module is Modules/socketmodule.c.

Modules/socketmodule.c
	In most cases, IPv6 address can be placed where IPv4 address fits.

    sockaddr
	sockaddr tuple is formatted as follows:
	    IPv4: (host, port)
	    IPv6: socket class methods always generate
		    (host, port, flowinfo, scopeid).
		  socket class methods will accept 2, 3, or 4 tuple
		  (for backward compatibility).

	Compatibility warning: Some of the scripts assume that the sockaddr
	structure is 2 tuple, like:
	    host, port = sock.getpeername()
	this will fail if you are connected to IPv6 node.

    socket.getaddrinfo(host, port [, family, socktype, proto, flags])
	host: String or None
	port: String, Int or None
	family, socktype, proto, flags: Int, can be omitted

	Perform getaddrinfo(3).  Returns List of the following 5 tuple:
	    (family, socktype, proto, canonname, sockaddr)
	    family: Int
	    socktype: Int
	    proto: Int
	    canonname: String
	    sockaddr: sockaddr (see above)

	See Lib/httplib.py for typical usage on the client side.

    socket.getnameinfo(sockaddr, flags)
	sockaddr: sockaddr
	flags: Int

	Perform getnameinfo(3).  Returns the following 2 tuple:
	    host: String, numeric or hostname depending on flgags
	    port: String, numeric or portname depending on flgags

    socket.gethostbyname(host) (behavior change if IPv6 support is compiled in)
	host: String

	Performs gethostbyname(3).  Returns numeric address representation
	for "host".

	Unlike gethostbyname(3) (which returns IPv4 addresses only),
	socket.gethostbyname() can return IPv6 address in numeric form.
	This is because original Python soket.gethostbyname() can return
	addresses other than IPv4.  We just followed the existing practice
	in Python.

	However, this may cause trouble with existing scripts, if:
	- the given "host" resolves to IPv6 address
	- and the script assumes to get IPv4 address
	For example, while the following code always success with normal
	Python distribution, this can fail with IPv6-ready Python because
	'localhost' can resolve to IPv6 address ('::1').
		a = socket.gethostbyname('localhost')
		# "a" can be '::1'
		s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
		# if "a" is '::1', s.bind() fails
		s.bind(a, port)

    socket.gethostbyaddr(addr) (behavior change if IPv6 support is compiled in)
	addr: String

	Performs gethostbyaddr(3).  Returns string address representation for
	"addr".

	The function can take IPv6 numeric address as well.  This behavior
	is not problematical, because
	- if you pass numeric "addr" parameter, we can always identify address
	  family for it
	- return value is string address reprsentation, where IPv6 and IPv4
	  are not distinguishable.

     socket.bind(addr, port), socket.connect(addr, port) and others.
	(No behavior change, but be careful)

	With Python "addr" can be string hostname.  When the string hostname
	resolved to numeric address, it will obey address family of the socket
	(which was specified when socket.socket() was called).
	If you give some string that does not give matching address family,
	you will get some error.
		s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
		# this is okay, if 'localhost' resolves to both IPv4/v6
		s.connect('localhost', 80)
		# this is not okay, of course
		s.connect('::1', 80)
		# this is not okay, as v6only.kame.net will not resolve to IPv4
		s.connect('v6only.kame.net', 80)

Lib/httplib.py
	IPv6 ready.  "host" in HTTP(host) will accept the following 3 forms:
		[host]:port
		host:port	there must be only single colon
		host
	This is to allow IPv6 numeric URL (http://[host]:port/) in documents.

	IMHO "host:port" parsing should be implemented in urllib.py, not here.

Lib/ftplib.py
	IPv6 ready.  This uses EPSV/EPRT on IPv6 ftp.  See RFC2428 for
	protocol details.

Lib/SocketServer.py
	IPv6 ready.  Wildcard bind on TCPServer, i.e. TCPServer(('', port)),
	will bind to wildcard socket on TCPServer.address_family.
	TCPServer.addresss_family is set to AF_INET by default, so ('', port)
	will usually bind AF_INET.

Lib/smtplib.py, Lib/telnetlib.py, Lib/poplib.py
	IPv6 ready.  Not much to say about protocol details - they just use
	TCP over IPv6.

configure
	Configure has extra option, --enable-ipv6 and --disable-ipv6.
	The option controls IPv6 support feature.

dynamic link issues in Modules/socketmodule.c
	Modules/socketmodule.c can be dynamically loaded only in the following
	situations:
	- getaddrinfo(3) and getnameinfo(3) are supplied by OS vendor in
	  libc, and libc is dynamic link library.
	- OS vendor is NOT supplying getaddrinfo(3) nor getnameinfo(3), and
	  You are configuring this package with --disable-ipv6.  In this case,
	  you'll be using missing/get{addr,name}info.c and they will refer to
	  gethostby{name,addr}.  gethostnameby{name,addr} can usually be found
	  in dynamic-linking libc.

	In other situations, such as the following, please link
	Modules/socketmodule.c into python itself.
	- getaddrinfo(3) and getnameinfo(3) are supplied by OS vendor, but
	  they are in statically linked library like libinet6.a.
	  (KAME falls into this category)

	python usually links Modules/socketmodule.c into python itself
	(due to its popularity) so there should be no problem.

restrictions
	- The patched tree will not use gethostbyname_r and other
	  thread-ready libraries.  Instead, it will use getaddrinfo() and
	  getnameinfo() throughout the operation.

todo
	- Patch bunch of library files in Lib/*.py.

compatibility issues with existing scripts
	If you disable IPv6 support (./configure --disable-ipv6), the
	patched code is mostly compatible with original Python
	(except files in "Lib" directory modified for dual stack support).

	User script may choke if:
	- IPv4/v6 dualstack libc is supplied, python is compiled for dual
	  stack, and script assumes some of IPv4-only behavior (especially
	  sockaddr)
	- IPv4/v6 dualstack libc is supplied, python is compiled for IPv4 only,
	  and script assumes some of IPv4-only behavior.
	  In this case, Python socket class itself does not support IPv6,
	  however, name resolution functions can return IPv6 names since
	  they use IPv6-ready libc functions!  I do not recommend this
	  configuration.
	- script assumes certain IPv4-only version behavior in Lib/*.py.

compilation
	If you use IPv6 features, it is assumed that you have working
	getaddrinfo() and getnameinfo() library functions.  We have noticed
	that some of IPv6 stack is shipped with broken getaddrinfo().  In
	such cases, use missing/get{addr,name}info.c instead (but then, you
	need to have working getipnodeby{name,addr}).

	If you compile this on IPv4-only machine without get{addr,name}info,
	missing/get{addr,name}info.c will be used.  They are from KAME IPv6
	distribution and is #ifdef'ed for IPv4 only support.  They are
	fairly complete implementation and you don't need to bother with
	bind 8.2 (bind 8.2 get{addr,name}info() has bugs).

	When compiling this kit on IPv6 node, you may need to specify some
	additional library paths or cpp defs. (like -linet6 or -DINET6)
	--enable-ipv6 will give you some warning, if the IPv6 stack is unknown
	to the "configure" script.  Currently, the following IPv6 stacks
	are officially supported (i.e. we've checked that the package works
	well):
	- KAME IPv6 stack, http://www.kame.net/

References
	RFC2553, for getaddrinfo(3) and getnameinfo(3).

Author contacts
	http://www.kame.net/
	mailto:core@kame.net
