== Some notes on using _socket.getaddrinfo()_

Since I've been immersing myself in IPv6 I've naturally become
interested in finding out the IPv6 addresses of hosts, which means
_getaddrinfo()_. In many ways, _getaddrinfo()_ is a great API; it's
wonderfully tuned for giving you exactly the information you need in
order to make connections to places. In other ways, it's less than ideal
and how to use its API is unclear.

(For the rest of this, I'm going to assume that you've read [[its
documentation
http://docs.python.org/library/socket.html#socket.getaddrinfo]].)

The big annoyance is that in practice, the _socktype_ argument is
not optional (which means that the _family_ argument isn't either,
but you generally want to set it to 0). If you leave out _socktype_,
_getaddrinfo()_ tells you how to make both TCP *and* UDP connections
to the given host and port; this is rarely what you want. So the
standard method of using it is to tell _getaddrinfo()_ that you only
want to make TCP connections by using '((getaddrinfo(host, port, 0,
socket.SOCK_STREAM)))'.

The next annoyance (which is in the C API on some systems) is that
_getaddrinfo()_ won't necessarily give you IPv6 connection details if
it doesn't think that you can use them. This is fine if you're using
_getaddrinfo()_ because you want to make a connection; it's not so fine
if you're using _getaddrinfo()_ to look up host addresses themselves.
Thus, if you're looking up host addresses and need to get both IPv4 and
IPv6 addresses if the host has them, you need to call _getaddrinfo()_
twice, once with ((socket.AF_INET)) and once with ((socket.AF_INET6)) as
the _family_ argument.

(To use _getaddrinfo()_ to find host addresses in general, you call
it, go through the list of results, and find the host address as the
first element of the _sockaddr_ element of the result 5-tuple. If you
remembered to ask for only TCP connections, you shouldn't normally get
duplicate host addresses. This is annoyingly indirect, but that's what
utility functions are for.)

There's no guarantee that _getaddrinfo()_ always returns IPv6 addresses
before (or after) IPv4 ones if the host has both; what happens seems to
vary from system to system. If you want to be sure to try IPv6 before
IPv4, you're going to need to apply a sorting function to the list that
_getaddrinfo()_ returns.

(If you want to try IPv4 before IPv6, plain _.sort()_ will probably
order things the way you want.)

=== Sidebar: the standard way to use _getaddrinfo()_

This is taken more or less straight from ((create_connection)) in
the [[socket module http://docs.python.org/library/socket.html]],
which you can read [[here
http://svn.python.org/view/python/trunk/Lib/socket.py?view=markup]]; this
version has less error checking and features. I feel like writing
it down for my own future convenience:

 import socket 
 
 def makeconn(host, port):
     for r in socket.getaddrinfo(host, port,
                                 0, socket.SOCK_STREAM):
         af, st, pr, _, sa = r
         s = socket.socket(af, st, pr)
         try:
             s.connect(sa)
             return s
         except socket.error, msg:
             s.close()
     raise msg

A function to determine the IPv4 and IPv6 addresses of a host is left
for a later entry (or an exercise for the reader), since it involves
more annoyance.