diff options
author | Antoine Pitrou <solipsis@pitrou.net> | 2010-05-31 17:06:44 (GMT) |
---|---|---|
committer | Antoine Pitrou <solipsis@pitrou.net> | 2010-05-31 17:06:44 (GMT) |
commit | 3f6b2d07eda6a49ab088485e309722c10756ab22 (patch) | |
tree | d4768956275d7c252b42a9dcab4d70c2f1438013 | |
parent | 5ca31edd0efe9869b5af877818b57d6cd395cd8e (diff) | |
download | cpython-3f6b2d07eda6a49ab088485e309722c10756ab22.zip cpython-3f6b2d07eda6a49ab088485e309722c10756ab22.tar.gz cpython-3f6b2d07eda6a49ab088485e309722c10756ab22.tar.bz2 |
Merged revisions 81623 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
................
r81623 | antoine.pitrou | 2010-05-31 19:04:40 +0200 (lun., 31 mai 2010) | 9 lines
Merged revisions 81621 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r81621 | antoine.pitrou | 2010-05-31 19:01:01 +0200 (lun., 31 mai 2010) | 4 lines
Improve documentation for getaddrinfo() (part of #8857)
........
................
-rw-r--r-- | Doc/library/socket.rst | 49 |
1 files changed, 33 insertions, 16 deletions
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 75454cb..28397f5 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -205,27 +205,44 @@ The module :mod:`socket` exports the following constants and functions: :func:`getdefaulttimeout` is used. -.. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]]) +.. function:: getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0) - Resolves the *host*/*port* argument, into a sequence of 5-tuples that contain - all the necessary arguments for creating the corresponding socket. *host* is a domain - name, a string representation of an IPv4/v6 address or ``None``. *port* is a string - service name such as ``'http'``, a numeric port number or ``None``. - The rest of the arguments are optional and must be numeric if specified. - By passing ``None`` as the value of *host* and *port*, , you can pass ``NULL`` to the C API. + Translate the *host*/*port* argument into a sequence of 5-tuples that contain + all the necessary arguments for creating a socket connected to that service. + *host* is a domain name, a string representation of an IPv4/v6 address + or ``None``. *port* is a string service name such as ``'http'``, a numeric + port number or ``None``. By passing ``None`` as the value of *host* + and *port*, you can pass ``NULL`` to the underlying C API. - The :func:`getaddrinfo` function returns a list of 5-tuples with the following - structure: + The *family*, *socktype* and *proto* arguments can be optionally specified + in order to narrow the list of addresses returned. Passing zero as a + value for each of these arguments selects the full range of results. + The *flags* argument can be one or several of the ``AI_*`` constants, + and will influence how results are computed and returned. + For example, :const:`AI_NUMERICHOST` will disable domain name resolution + and will raise an error if *host* is a domain name. - ``(family, socktype, proto, canonname, sockaddr)`` + The function returns a list of 5-tuples with the following structure: - *family*, *socktype*, *proto* are all integers and are meant to be passed to the - :func:`socket` function. *canonname* is a string representing the canonical name - of the *host*. It can be a numeric IPv4/v6 address when :const:`AI_CANONNAME` is - specified for a numeric *host*. *sockaddr* is a tuple describing a socket - address, as described above. See the source for :mod:`socket` and other - library modules for a typical usage of the function. + ``(family, socktype, proto, canonname, sockaddr)`` + In these tuples, *family*, *socktype*, *proto* are all integers and are + meant to be passed to the :func:`socket` function. *canonname* will be + a string representing the canonical name of the *host* if + :const:`AI_CANONNAME` is part of the *flags* argument; else *canonname* + will be empty. *sockaddr* is a tuple describing a socket address, whose + format depends on the returned *family* (a ``(address, port)`` 2-tuple for + :const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for + :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect` + method. + + The following example fetches address information for a hypothetical TCP + connection to ``www.python.org`` on port 80 (results may differ on your + system if IPv6 isn't enabled):: + + >>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.SOL_TCP) + [(2, 1, 6, '', ('82.94.164.162', 80)), + (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))] .. function:: getfqdn([name]) |