summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAntoine Pitrou <solipsis@pitrou.net>2010-05-31 17:06:44 (GMT)
committerAntoine Pitrou <solipsis@pitrou.net>2010-05-31 17:06:44 (GMT)
commit3f6b2d07eda6a49ab088485e309722c10756ab22 (patch)
treed4768956275d7c252b42a9dcab4d70c2f1438013
parent5ca31edd0efe9869b5af877818b57d6cd395cd8e (diff)
downloadcpython-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.rst49
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])