cpython-lru_cache-weakref: Doc/library/socket.rst annotate

annotate Doc/library/socket.rst @ 58925:eecf1bef052d 2.6

Merged revisions 78207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78207 | ezio.melotti | 2010-02-17 01:26:09 +0200 (Wed, 17 Feb 2010) | 1 line #7930: fix stripid ........

author	Ezio Melotti <ezio.melotti@gmail.com>
date	Tue, 16 Feb 2010 23:29:44 +0000
parents	f2f59d7b4614
children	c2ffd20d6cf8

rev	line source
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	1
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	2 :mod:`socket` --- Low-level networking interface
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	3 ================================================
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	4
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	5 .. module:: socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	6 :synopsis: Low-level networking interface.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	7
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	8
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	9 This module provides access to the BSD socket interface. It is available on
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	10 all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	11 platforms.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	12
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	13 .. note::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	14
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	15 Some behavior may be platform dependent, since calls are made to the operating
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	16 system socket APIs.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	17
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	18 For an introduction to socket programming (in C), see the following papers: An
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	19 Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	20 An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	21 al, both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	22 PS1:7 and PS1:8). The platform-specific reference material for the various
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	23 socket-related system calls are also a valuable source of information on the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	24 details of socket semantics. For Unix, refer to the manual pages; for Windows,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	25 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may
45085 a281e33198c0 Update IPv6 RFC number. Georg Brandl <georg@python.org> parents: 44703 diff changeset	26 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	27
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	28 .. index:: object: socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	29
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	30 The Python interface is a straightforward transliteration of the Unix system
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	31 call and library interface for sockets to Python's object-oriented style: the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	32 :func:`socket` function returns a :dfn:`socket object` whose methods implement
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	33 the various socket system calls. Parameter types are somewhat higher-level than
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	34 in the C interface: as with :meth:`read` and :meth:`write` operations on Python
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	35 files, buffer allocation on receive operations is automatic, and buffer length
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	36 is implicit on send operations.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	37
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	38 Socket addresses are represented as follows: A single string is used for the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	39 :const:`AF_UNIX` address family. A pair ``(host, port)`` is used for the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	40 :const:`AF_INET` address family, where host is a string representing either a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	41 hostname in Internet domain notation like ``'daring.cwi.nl'`` or an IPv4 address
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	42 like ``'100.50.200.5'``, and port is an integral port number. For
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	43 :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	44 scopeid)`` is used, where flowinfo and scopeid represents ``sin6_flowinfo``
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	45 and ``sin6_scope_id`` member in :const:`struct sockaddr_in6` in C. For
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	46 :mod:`socket` module methods, flowinfo and scopeid can be omitted just for
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	47 backward compatibility. Note, however, omission of scopeid can cause problems
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	48 in manipulating scoped IPv6 addresses. Other address families are currently not
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	49 supported. The address format required by a particular socket object is
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	50 automatically selected based on the address family specified when the socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	51 object was created.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	52
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	53 For IPv4 addresses, two special forms are accepted instead of a host address:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	54 the empty string represents :const:`INADDR_ANY`, and the string
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	55 ``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. The behavior is not
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	56 available for IPv6 for backward compatibility, therefore, you may want to avoid
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	57 these if you intend to support IPv6 with your Python programs.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	58
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	59 If you use a hostname in the host portion of IPv4/v6 socket address, the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	60 program may show a nondeterministic behavior, as Python uses the first address
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	61 returned from the DNS resolution. The socket address will be resolved
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	62 differently into an actual IPv4/v6 address, depending on the results from DNS
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	63 resolution and/or the host configuration. For deterministic behavior use a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	64 numeric address in host portion.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	65
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	66 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	67 AF_NETLINK sockets are represented as pairs ``pid, groups``.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	68
44561 ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	69 .. versionadded:: 2.6
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	70 Linux-only support for TIPC is also available using the :const:`AF_TIPC`
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	71 address family. TIPC is an open, non-IP based networked protocol designed
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	72 for use in clustered computer environments. Addresses are represented by a
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	73 tuple, and the fields depend on the address type. The general tuple form is
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	74 ``(addr_type, v1, v2, v3 [, scope])``, where:
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	75
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	76 - addr_type is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	77 TIPC_ADDR_ID.
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	78 - scope is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	79 TIPC_NODE_SCOPE.
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	80 - If addr_type is TIPC_ADDR_NAME, then v1 is the server type, v2 is
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	81 the port identifier, and v3 should be 0.
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	82
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	83 If addr_type is TIPC_ADDR_NAMESEQ, then v1 is the server type, v2
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	84 is the lower port number, and v3 is the upper port number.
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	85
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	86 If addr_type is TIPC_ADDR_ID, then v1 is the node, v2 is the
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	87 reference, and v3 should be set to 0.
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	88
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	89
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	90 All errors raise exceptions. The normal exceptions for invalid argument types
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	91 and out-of-memory conditions can be raised; errors related to socket or address
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	92 semantics raise the error :exc:`socket.error`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	93
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	94 Non-blocking mode is supported through :meth:`setblocking`. A generalization of
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	95 this based on timeouts is supported through :meth:`settimeout`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	96
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	97 The module :mod:`socket` exports the following constants and functions:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	98
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	99
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	100 .. exception:: error
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	101
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	102 .. index:: module: errno
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	103
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	104 This exception is raised for socket-related errors. The accompanying value is
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	105 either a string telling what went wrong or a pair ``(errno, string)``
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	106 representing an error returned by a system call, similar to the value
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	107 accompanying :exc:`os.error`. See the module :mod:`errno`, which contains names
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	108 for the error codes defined by the underlying operating system.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	109
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	110 .. versionchanged:: 2.6
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	111 :exc:`socket.error` is now a child class of :exc:`IOError`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	112
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	113
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	114 .. exception:: herror
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	115
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	116 This exception is raised for address-related errors, i.e. for functions that use
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	117 h_errno in the C API, including :func:`gethostbyname_ex` and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	118 :func:`gethostbyaddr`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	119
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	120 The accompanying value is a pair ``(h_errno, string)`` representing an error
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	121 returned by a library call. string represents the description of h_errno, as
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	122 returned by the :cfunc:`hstrerror` C function.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	123
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	124
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	125 .. exception:: gaierror
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	126
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	127 This exception is raised for address-related errors, for :func:`getaddrinfo` and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	128 :func:`getnameinfo`. The accompanying value is a pair ``(error, string)``
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	129 representing an error returned by a library call. string represents the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	130 description of error, as returned by the :cfunc:`gai_strerror` C function. The
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	131 error value will match one of the :const:`EAI_\*` constants defined in this
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	132 module.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	133
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	134
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	135 .. exception:: timeout
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	136
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	137 This exception is raised when a timeout occurs on a socket which has had
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	138 timeouts enabled via a prior call to :meth:`settimeout`. The accompanying value
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	139 is a string whose value is currently always "timed out".
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	140
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	141 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	142
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	143
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	144 .. data:: AF_UNIX
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	145 AF_INET
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	146 AF_INET6
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	147
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	148 These constants represent the address (and protocol) families, used for the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	149 first argument to :func:`socket`. If the :const:`AF_UNIX` constant is not
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	150 defined then this protocol is unsupported.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	151
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	152
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	153 .. data:: SOCK_STREAM
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	154 SOCK_DGRAM
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	155 SOCK_RAW
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	156 SOCK_RDM
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	157 SOCK_SEQPACKET
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	158
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	159 These constants represent the socket types, used for the second argument to
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	160 :func:`socket`. (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	161 generally useful.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	162
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	163
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	164 .. data:: SO_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	165 SOMAXCONN
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	166 MSG_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	167 SOL_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	168 IPPROTO_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	169 IPPORT_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	170 INADDR_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	171 IP_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	172 IPV6_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	173 EAI_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	174 AI_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	175 NI_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	176 TCP_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	177
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	178 Many constants of these forms, documented in the Unix documentation on sockets
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	179 and/or the IP protocol, are also defined in the socket module. They are
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	180 generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt`
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	181 methods of socket objects. In most cases, only those symbols that are defined
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	182 in the Unix header files are defined; for a few symbols, default values are
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	183 provided.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	184
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	185 .. data:: SIO_*
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	186 RCVALL_*
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	187
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	188 Constants for Windows' WSAIoctl(). The constants are used as arguments to the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	189 :meth:`ioctl` method of socket objects.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	190
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	191 .. versionadded:: 2.6
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	192
44561 ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	193 .. data:: TIPC_*
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	194
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	195 TIPC related constants, matching the ones exported by the C socket API. See
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	196 the TIPC documentation for more information.
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	197
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	198 .. versionadded:: 2.6
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	199
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	200 .. data:: has_ipv6
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	201
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	202 This constant contains a boolean value which indicates if IPv6 is supported on
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	203 this platform.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	204
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	205 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	206
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	207
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	208 .. function:: create_connection(address[, timeout])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	209
47372 e2c5ae30cffe Fixed the semantic of timeout for socket.create_connection and Facundo Batista <facundobatista@gmail.com> parents: 47241 diff changeset	210 Convenience function. Connect to address (a 2-tuple ``(host, port)``),
e2c5ae30cffe Fixed the semantic of timeout for socket.create_connection and Facundo Batista <facundobatista@gmail.com> parents: 47241 diff changeset	211 and return the socket object. Passing the optional timeout parameter will
e2c5ae30cffe Fixed the semantic of timeout for socket.create_connection and Facundo Batista <facundobatista@gmail.com> parents: 47241 diff changeset	212 set the timeout on the socket instance before attempting to connect. If no
e2c5ae30cffe Fixed the semantic of timeout for socket.create_connection and Facundo Batista <facundobatista@gmail.com> parents: 47241 diff changeset	213 timeout is supplied, the global default timeout setting returned by
e2c5ae30cffe Fixed the semantic of timeout for socket.create_connection and Facundo Batista <facundobatista@gmail.com> parents: 47241 diff changeset	214 :func:`getdefaulttimeout` is used.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	215
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	216 .. versionadded:: 2.6
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	217
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	218
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	219 .. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	220
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	221 Resolves the host/port argument, into a sequence of 5-tuples that contain
49287 db999eb2bbdc Improve wording Andrew M. Kuchling <amk@amk.ca> parents: 47372 diff changeset	222 all the necessary arguments for creating the corresponding socket. host is a domain
db999eb2bbdc Improve wording Andrew M. Kuchling <amk@amk.ca> parents: 47372 diff changeset	223 name, a string representation of an IPv4/v6 address or ``None``. port is a string
db999eb2bbdc Improve wording Andrew M. Kuchling <amk@amk.ca> parents: 47372 diff changeset	224 service name such as ``'http'``, a numeric port number or ``None``.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	225 The rest of the arguments are optional and must be numeric if specified.
49287 db999eb2bbdc Improve wording Andrew M. Kuchling <amk@amk.ca> parents: 47372 diff changeset	226 By passing ``None`` as the value of host and port, , you can pass ``NULL`` to the C API.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	227
46862 f6388dc019cc #2742: ``''`` is not converted to NULL in getaddrinfo. Georg Brandl <georg@python.org> parents: 46681 diff changeset	228 The :func:`getaddrinfo` function returns a list of 5-tuples with the following
f6388dc019cc #2742: ``''`` is not converted to NULL in getaddrinfo. Georg Brandl <georg@python.org> parents: 46681 diff changeset	229 structure:
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	230
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	231 ``(family, socktype, proto, canonname, sockaddr)``
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	232
49287 db999eb2bbdc Improve wording Andrew M. Kuchling <amk@amk.ca> parents: 47372 diff changeset	233 family, socktype, proto are all integers and are meant to be passed to the
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	234 :func:`socket` function. canonname is a string representing the canonical name
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	235 of the host. It can be a numeric IPv4/v6 address when :const:`AI_CANONNAME` is
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	236 specified for a numeric host. sockaddr is a tuple describing a socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	237 address, as described above. See the source for :mod:`socket` and other
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	238 library modules for a typical usage of the function.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	239
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	240 .. versionadded:: 2.2
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	241
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	242
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	243 .. function:: getfqdn([name])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	244
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	245 Return a fully qualified domain name for name. If name is omitted or empty,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	246 it is interpreted as the local host. To find the fully qualified name, the
49287 db999eb2bbdc Improve wording Andrew M. Kuchling <amk@amk.ca> parents: 47372 diff changeset	247 hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	248 host, if available. The first name which includes a period is selected. In
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	249 case no fully qualified domain name is available, the hostname as returned by
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	250 :func:`gethostname` is returned.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	251
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	252 .. versionadded:: 2.0
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	253
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	254
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	255 .. function:: gethostbyname(hostname)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	256
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	257 Translate a host name to IPv4 address format. The IPv4 address is returned as a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	258 string, such as ``'100.50.200.5'``. If the host name is an IPv4 address itself
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	259 it is returned unchanged. See :func:`gethostbyname_ex` for a more complete
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	260 interface. :func:`gethostbyname` does not support IPv6 name resolution, and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	261 :func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	262
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	263
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	264 .. function:: gethostbyname_ex(hostname)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	265
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	266 Translate a host name to IPv4 address format, extended interface. Return a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	267 triple ``(hostname, aliaslist, ipaddrlist)`` where hostname is the primary
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	268 host name responding to the given ip_address, aliaslist is a (possibly
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	269 empty) list of alternative host names for the same address, and ipaddrlist is
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	270 a list of IPv4 addresses for the same interface on the same host (often but not
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	271 always a single address). :func:`gethostbyname_ex` does not support IPv6 name
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	272 resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	273 stack support.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	274
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	275
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	276 .. function:: gethostname()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	277
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	278 Return a string containing the hostname of the machine where the Python
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49287 diff changeset	279 interpreter is currently executing.
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49287 diff changeset	280
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49287 diff changeset	281 If you want to know the current machine's IP address, you may want to use
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49287 diff changeset	282 ``gethostbyname(gethostname())``. This operation assumes that there is a
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49287 diff changeset	283 valid address-to-host mapping for the host, and the assumption does not
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49287 diff changeset	284 always hold.
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49287 diff changeset	285
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49287 diff changeset	286 Note: :func:`gethostname` doesn't always return the fully qualified domain
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49287 diff changeset	287 name; use ``getfqdn()`` (see above).
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	288
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	289
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	290 .. function:: gethostbyaddr(ip_address)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	291
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	292 Return a triple ``(hostname, aliaslist, ipaddrlist)`` where hostname is the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	293 primary host name responding to the given ip_address, aliaslist is a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	294 (possibly empty) list of alternative host names for the same address, and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	295 ipaddrlist is a list of IPv4/v6 addresses for the same interface on the same
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	296 host (most likely containing only a single address). To find the fully qualified
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	297 domain name, use the function :func:`getfqdn`. :func:`gethostbyaddr` supports
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	298 both IPv4 and IPv6.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	299
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	300
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	301 .. function:: getnameinfo(sockaddr, flags)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	302
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	303 Translate a socket address sockaddr into a 2-tuple ``(host, port)``. Depending
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	304 on the settings of flags, the result can contain a fully-qualified domain name
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	305 or numeric address representation in host. Similarly, port can contain a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	306 string port name or a numeric port number.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	307
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	308 .. versionadded:: 2.2
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	309
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	310
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	311 .. function:: getprotobyname(protocolname)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	312
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	313 Translate an Internet protocol name (for example, ``'icmp'``) to a constant
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	314 suitable for passing as the (optional) third argument to the :func:`socket`
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	315 function. This is usually only needed for sockets opened in "raw" mode
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	316 (:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	317 automatically if the protocol is omitted or zero.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	318
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	319
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	320 .. function:: getservbyname(servicename[, protocolname])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	321
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	322 Translate an Internet service name and protocol name to a port number for that
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	323 service. The optional protocol name, if given, should be ``'tcp'`` or
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	324 ``'udp'``, otherwise any protocol will match.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	325
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	326
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	327 .. function:: getservbyport(port[, protocolname])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	328
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	329 Translate an Internet port number and protocol name to a service name for that
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	330 service. The optional protocol name, if given, should be ``'tcp'`` or
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	331 ``'udp'``, otherwise any protocol will match.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	332
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	333
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	334 .. function:: socket([family[, type[, proto]]])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	335
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	336 Create a new socket using the given address family, socket type and protocol
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	337 number. The address family should be :const:`AF_INET` (the default),
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	338 :const:`AF_INET6` or :const:`AF_UNIX`. The socket type should be
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	339 :const:`SOCK_STREAM` (the default), :const:`SOCK_DGRAM` or perhaps one of the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	340 other ``SOCK_`` constants. The protocol number is usually zero and may be
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	341 omitted in that case.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	342
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	343
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	344 .. function:: socketpair([family[, type[, proto]]])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	345
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	346 Build a pair of connected socket objects using the given address family, socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	347 type, and protocol number. Address family, socket type, and protocol number are
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	348 as for the :func:`socket` function above. The default family is :const:`AF_UNIX`
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	349 if defined on the platform; otherwise, the default is :const:`AF_INET`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	350 Availability: Unix.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	351
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	352 .. versionadded:: 2.4
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	353
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	354
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	355 .. function:: fromfd(fd, family, type[, proto])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	356
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	357 Duplicate the file descriptor fd (an integer as returned by a file object's
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	358 :meth:`fileno` method) and build a socket object from the result. Address
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	359 family, socket type and protocol number are as for the :func:`socket` function
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	360 above. The file descriptor should refer to a socket, but this is not checked ---
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	361 subsequent operations on the object may fail if the file descriptor is invalid.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	362 This function is rarely needed, but can be used to get or set socket options on
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	363 a socket passed to a program as standard input or output (such as a server
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	364 started by the Unix inet daemon). The socket is assumed to be in blocking mode.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	365 Availability: Unix.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	366
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	367
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	368 .. function:: ntohl(x)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	369
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	370 Convert 32-bit positive integers from network to host byte order. On machines
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	371 where the host byte order is the same as network byte order, this is a no-op;
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	372 otherwise, it performs a 4-byte swap operation.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	373
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	374
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	375 .. function:: ntohs(x)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	376
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	377 Convert 16-bit positive integers from network to host byte order. On machines
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	378 where the host byte order is the same as network byte order, this is a no-op;
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	379 otherwise, it performs a 2-byte swap operation.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	380
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	381
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	382 .. function:: htonl(x)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	383
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	384 Convert 32-bit positive integers from host to network byte order. On machines
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	385 where the host byte order is the same as network byte order, this is a no-op;
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	386 otherwise, it performs a 4-byte swap operation.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	387
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	388
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	389 .. function:: htons(x)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	390
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	391 Convert 16-bit positive integers from host to network byte order. On machines
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	392 where the host byte order is the same as network byte order, this is a no-op;
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	393 otherwise, it performs a 2-byte swap operation.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	394
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	395
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	396 .. function:: inet_aton(ip_string)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	397
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	398 Convert an IPv4 address from dotted-quad string format (for example,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	399 '123.45.67.89') to 32-bit packed binary format, as a string four characters in
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	400 length. This is useful when conversing with a program that uses the standard C
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	401 library and needs objects of type :ctype:`struct in_addr`, which is the C type
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	402 for the 32-bit packed binary this function returns.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	403
56812 a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 56801 diff changeset	404 :func:`inet_aton` also accepts strings with less than three dots; see the
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 56801 diff changeset	405 Unix manual page :manpage:`inet(3)` for details.
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 56801 diff changeset	406
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	407 If the IPv4 address string passed to this function is invalid,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	408 :exc:`socket.error` will be raised. Note that exactly what is valid depends on
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	409 the underlying C implementation of :cfunc:`inet_aton`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	410
54348 a27a739cef7f Merged revisions 72085,72132,72159,72288,72290,72292 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	411 :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	412 instead for IPv4/v6 dual stack support.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	413
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	414
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	415 .. function:: inet_ntoa(packed_ip)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	416
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	417 Convert a 32-bit packed IPv4 address (a string four characters in length) to its
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	418 standard dotted-quad string representation (for example, '123.45.67.89'). This
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	419 is useful when conversing with a program that uses the standard C library and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	420 needs objects of type :ctype:`struct in_addr`, which is the C type for the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	421 32-bit packed binary data this function takes as an argument.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	422
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	423 If the string passed to this function is not exactly 4 bytes in length,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	424 :exc:`socket.error` will be raised. :func:`inet_ntoa` does not support IPv6, and
54348 a27a739cef7f Merged revisions 72085,72132,72159,72288,72290,72292 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	425 :func:`inet_ntop` should be used instead for IPv4/v6 dual stack support.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	426
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	427
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	428 .. function:: inet_pton(address_family, ip_string)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	429
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	430 Convert an IP address from its family-specific string format to a packed, binary
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	431 format. :func:`inet_pton` is useful when a library or network protocol calls for
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	432 an object of type :ctype:`struct in_addr` (similar to :func:`inet_aton`) or
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	433 :ctype:`struct in6_addr`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	434
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	435 Supported values for address_family are currently :const:`AF_INET` and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	436 :const:`AF_INET6`. If the IP address string ip_string is invalid,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	437 :exc:`socket.error` will be raised. Note that exactly what is valid depends on
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	438 both the value of address_family and the underlying implementation of
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	439 :cfunc:`inet_pton`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	440
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	441 Availability: Unix (maybe not all platforms).
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	442
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	443 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	444
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	445
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	446 .. function:: inet_ntop(address_family, packed_ip)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	447
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	448 Convert a packed IP address (a string of some number of characters) to its
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	449 standard, family-specific string representation (for example, ``'7.10.0.5'`` or
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	450 ``'5aef:2b::8'``) :func:`inet_ntop` is useful when a library or network protocol
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	451 returns an object of type :ctype:`struct in_addr` (similar to :func:`inet_ntoa`)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	452 or :ctype:`struct in6_addr`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	453
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	454 Supported values for address_family are currently :const:`AF_INET` and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	455 :const:`AF_INET6`. If the string packed_ip is not the correct length for the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	456 specified address family, :exc:`ValueError` will be raised. A
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	457 :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	458
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	459 Availability: Unix (maybe not all platforms).
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	460
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	461 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	462
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	463
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	464 .. function:: getdefaulttimeout()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	465
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	466 Return the default timeout in floating seconds for new socket objects. A value
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	467 of ``None`` indicates that new socket objects have no timeout. When the socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	468 module is first imported, the default is ``None``.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	469
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	470 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	471
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	472
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	473 .. function:: setdefaulttimeout(timeout)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	474
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	475 Set the default timeout in floating seconds for new socket objects. A value of
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	476 ``None`` indicates that new socket objects have no timeout. When the socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	477 module is first imported, the default is ``None``.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	478
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	479 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	480
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	481
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	482 .. data:: SocketType
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	483
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	484 This is a Python type object that represents the socket object type. It is the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	485 same as ``type(socket(...))``.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	486
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	487
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	488 .. seealso::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	489
47241 ba1fa511b72d socketserver renaming reversal part 3: move the module into the right Georg Brandl <georg@python.org> parents: 46929 diff changeset	490 Module :mod:`SocketServer`
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	491 Classes that simplify writing network servers.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	492
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	493
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	494 .. _socket-objects:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	495
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	496 Socket Objects
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	497 --------------
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	498
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	499 Socket objects have the following methods. Except for :meth:`makefile` these
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	500 correspond to Unix system calls applicable to sockets.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	501
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	502
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	503 .. method:: socket.accept()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	504
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	505 Accept a connection. The socket must be bound to an address and listening for
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	506 connections. The return value is a pair ``(conn, address)`` where conn is a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	507 new socket object usable to send and receive data on the connection, and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	508 address is the address bound to the socket on the other end of the connection.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	509
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	510
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	511 .. method:: socket.bind(address)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	512
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	513 Bind the socket to address. The socket must not already be bound. (The format
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	514 of address depends on the address family --- see above.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	515
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	516 .. note::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	517
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	518 This method has historically accepted a pair of parameters for :const:`AF_INET`
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	519 addresses instead of only a tuple. This was never intentional and is no longer
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	520 available in Python 2.0 and later.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	521
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	522
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	523 .. method:: socket.close()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	524
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	525 Close the socket. All future operations on the socket object will fail. The
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	526 remote end will receive no more data (after queued data is flushed). Sockets are
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	527 automatically closed when they are garbage-collected.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	528
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	529
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	530 .. method:: socket.connect(address)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	531
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	532 Connect to a remote socket at address. (The format of address depends on the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	533 address family --- see above.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	534
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	535 .. note::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	536
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	537 This method has historically accepted a pair of parameters for :const:`AF_INET`
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	538 addresses instead of only a tuple. This was never intentional and is no longer
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	539 available in Python 2.0 and later.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	540
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	541
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	542 .. method:: socket.connect_ex(address)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	543
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	544 Like ``connect(address)``, but return an error indicator instead of raising an
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	545 exception for errors returned by the C-level :cfunc:`connect` call (other
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	546 problems, such as "host not found," can still raise exceptions). The error
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	547 indicator is ``0`` if the operation succeeded, otherwise the value of the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	548 :cdata:`errno` variable. This is useful to support, for example, asynchronous
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	549 connects.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	550
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	551 .. note::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	552
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	553 This method has historically accepted a pair of parameters for :const:`AF_INET`
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	554 addresses instead of only a tuple. This was never intentional and is no longer
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	555 available in Python 2.0 and later.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	556
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	557
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	558 .. method:: socket.fileno()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	559
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	560 Return the socket's file descriptor (a small integer). This is useful with
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	561 :func:`select.select`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	562
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	563 Under Windows the small integer returned by this method cannot be used where a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	564 file descriptor can be used (such as :func:`os.fdopen`). Unix does not have
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	565 this limitation.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	566
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	567
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	568 .. method:: socket.getpeername()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	569
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	570 Return the remote address to which the socket is connected. This is useful to
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	571 find out the port number of a remote IPv4/v6 socket, for instance. (The format
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	572 of the address returned depends on the address family --- see above.) On some
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	573 systems this function is not supported.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	574
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	575
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	576 .. method:: socket.getsockname()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	577
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	578 Return the socket's own address. This is useful to find out the port number of
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	579 an IPv4/v6 socket, for instance. (The format of the address returned depends on
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	580 the address family --- see above.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	581
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	582
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	583 .. method:: socket.getsockopt(level, optname[, buflen])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	584
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	585 Return the value of the given socket option (see the Unix man page
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	586 :manpage:`getsockopt(2)`). The needed symbolic constants (:const:`SO_\*` etc.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	587 are defined in this module. If buflen is absent, an integer option is assumed
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	588 and its integer value is returned by the function. If buflen is present, it
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	589 specifies the maximum length of the buffer used to receive the option in, and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	590 this buffer is returned as a string. It is up to the caller to decode the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	591 contents of the buffer (see the optional built-in module :mod:`struct` for a way
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	592 to decode C structures encoded as strings).
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	593
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	594
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	595 .. method:: socket.ioctl(control, option)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	596
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	597 :platform: Windows
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	598
44703 c4383d765ca7 Markup fix Andrew M. Kuchling <amk@amk.ca> parents: 44561 diff changeset	599 The :meth:`ioctl` method is a limited interface to the WSAIoctl system
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	600 interface. Please refer to the MSDN documentation for more information.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	601
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 56812 diff changeset	602 On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 56812 diff changeset	603 functions may be used; they accept a socket object as their first argument.
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 56812 diff changeset	604
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	605 .. versionadded:: 2.6
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	606
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	607
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	608 .. method:: socket.listen(backlog)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	609
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	610 Listen for connections made to the socket. The backlog argument specifies the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	611 maximum number of queued connections and should be at least 1; the maximum value
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	612 is system-dependent (usually 5).
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	613
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	614
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	615 .. method:: socket.makefile([mode[, bufsize]])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	616
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	617 .. index:: single: I/O control; buffering
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	618
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	619 Return a :dfn:`file object` associated with the socket. (File objects are
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	620 described in :ref:`bltin-file-objects`.) The file object
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	621 references a :cfunc:`dup`\ ped version of the socket file descriptor, so the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	622 file object and socket object may be closed or garbage-collected independently.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	623 The socket must be in blocking mode (it can not have a timeout). The optional
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	624 mode and bufsize arguments are interpreted the same way as by the built-in
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	625 :func:`file` function.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	626
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	627
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	628 .. method:: socket.recv(bufsize[, flags])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	629
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	630 Receive data from the socket. The return value is a string representing the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	631 data received. The maximum amount of data to be received at once is specified
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	632 by bufsize. See the Unix manual page :manpage:`recv(2)` for the meaning of
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	633 the optional argument flags; it defaults to zero.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	634
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	635 .. note::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	636
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	637 For best match with hardware and network realities, the value of bufsize
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	638 should be a relatively small power of 2, for example, 4096.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	639
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	640
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	641 .. method:: socket.recvfrom(bufsize[, flags])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	642
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	643 Receive data from the socket. The return value is a pair ``(string, address)``
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	644 where string is a string representing the data received and address is the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	645 address of the socket sending the data. See the Unix manual page
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	646 :manpage:`recv(2)` for the meaning of the optional argument flags; it defaults
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	647 to zero. (The format of address depends on the address family --- see above.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	648
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	649
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	650 .. method:: socket.recvfrom_into(buffer[, nbytes[, flags]])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	651
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	652 Receive data from the socket, writing it into buffer instead of creating a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	653 new string. The return value is a pair ``(nbytes, address)`` where nbytes is
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	654 the number of bytes received and address is the address of the socket sending
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	655 the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	656 optional argument flags; it defaults to zero. (The format of address
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	657 depends on the address family --- see above.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	658
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	659 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	660
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	661
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	662 .. method:: socket.recv_into(buffer[, nbytes[, flags]])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	663
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	664 Receive up to nbytes bytes from the socket, storing the data into a buffer
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	665 rather than creating a new string. If nbytes is not specified (or 0),
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	666 receive up to the size available in the given buffer. See the Unix manual page
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	667 :manpage:`recv(2)` for the meaning of the optional argument flags; it defaults
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	668 to zero.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	669
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	670 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	671
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	672
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	673 .. method:: socket.send(string[, flags])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	674
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	675 Send data to the socket. The socket must be connected to a remote socket. The
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	676 optional flags argument has the same meaning as for :meth:`recv` above.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	677 Returns the number of bytes sent. Applications are responsible for checking that
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	678 all data has been sent; if only some of the data was transmitted, the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	679 application needs to attempt delivery of the remaining data.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	680
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	681
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	682 .. method:: socket.sendall(string[, flags])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	683
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	684 Send data to the socket. The socket must be connected to a remote socket. The
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	685 optional flags argument has the same meaning as for :meth:`recv` above.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	686 Unlike :meth:`send`, this method continues to send data from string until
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	687 either all data has been sent or an error occurs. ``None`` is returned on
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	688 success. On error, an exception is raised, and there is no way to determine how
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	689 much data, if any, was successfully sent.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	690
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	691
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	692 .. method:: socket.sendto(string[, flags], address)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	693
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	694 Send data to the socket. The socket should not be connected to a remote socket,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	695 since the destination socket is specified by address. The optional flags
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	696 argument has the same meaning as for :meth:`recv` above. Return the number of
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	697 bytes sent. (The format of address depends on the address family --- see
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	698 above.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	699
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	700
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	701 .. method:: socket.setblocking(flag)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	702
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	703 Set blocking or non-blocking mode of the socket: if flag is 0, the socket is
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	704 set to non-blocking, else to blocking mode. Initially all sockets are in
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	705 blocking mode. In non-blocking mode, if a :meth:`recv` call doesn't find any
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	706 data, or if a :meth:`send` call can't immediately dispose of the data, a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	707 :exc:`error` exception is raised; in blocking mode, the calls block until they
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	708 can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0)``;
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	709 ``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	710
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	711
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	712 .. method:: socket.settimeout(value)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	713
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	714 Set a timeout on blocking socket operations. The value argument can be a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	715 nonnegative float expressing seconds, or ``None``. If a float is given,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	716 subsequent socket operations will raise an :exc:`timeout` exception if the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	717 timeout period value has elapsed before the operation has completed. Setting
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	718 a timeout of ``None`` disables timeouts on socket operations.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	719 ``s.settimeout(0.0)`` is equivalent to ``s.setblocking(0)``;
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	720 ``s.settimeout(None)`` is equivalent to ``s.setblocking(1)``.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	721
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	722 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	723
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	724
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	725 .. method:: socket.gettimeout()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	726
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	727 Return the timeout in floating seconds associated with socket operations, or
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	728 ``None`` if no timeout is set. This reflects the last call to
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	729 :meth:`setblocking` or :meth:`settimeout`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	730
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	731 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	732
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	733 Some notes on socket blocking and timeouts: A socket object can be in one of
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	734 three modes: blocking, non-blocking, or timeout. Sockets are always created in
56801 e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 54348 diff changeset	735 blocking mode. In blocking mode, operations block until complete or
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 54348 diff changeset	736 the system returns an error (such as connection timed out). In
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	737 non-blocking mode, operations fail (with an error that is unfortunately
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	738 system-dependent) if they cannot be completed immediately. In timeout mode,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	739 operations fail if they cannot be completed within the timeout specified for the
56801 e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 54348 diff changeset	740 socket or if the system returns an error. The :meth:`setblocking` method is simply
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 54348 diff changeset	741 a shorthand for certain :meth:`settimeout` calls.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	742
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	743 Timeout mode internally sets the socket in non-blocking mode. The blocking and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	744 timeout modes are shared between file descriptors and socket objects that refer
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	745 to the same network endpoint. A consequence of this is that file objects
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	746 returned by the :meth:`makefile` method must only be used when the socket is in
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	747 blocking mode; in timeout or non-blocking mode file operations that cannot be
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	748 completed immediately will fail.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	749
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	750 Note that the :meth:`connect` operation is subject to the timeout setting, and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	751 in general it is recommended to call :meth:`settimeout` before calling
56801 e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 54348 diff changeset	752 :meth:`connect` or pass a timeout parameter to :meth:`create_connection`.
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 54348 diff changeset	753 The system network stack may return a connection timeout error
57796 89996755cf39 Merged revisions 76904 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56819 diff changeset	754 of its own regardless of any Python socket timeout setting.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	755
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	756
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	757 .. method:: socket.setsockopt(level, optname, value)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	758
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	759 .. index:: module: struct
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	760
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	761 Set the value of the given socket option (see the Unix manual page
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	762 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	763 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	764 string representing a buffer. In the latter case it is up to the caller to
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	765 ensure that the string contains the proper bits (see the optional built-in
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	766 module :mod:`struct` for a way to encode C structures as strings).
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	767
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	768
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	769 .. method:: socket.shutdown(how)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	770
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	771 Shut down one or both halves of the connection. If how is :const:`SHUT_RD`,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	772 further receives are disallowed. If how is :const:`SHUT_WR`, further sends
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	773 are disallowed. If how is :const:`SHUT_RDWR`, further sends and receives are
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	774 disallowed.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	775
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	776 Note that there are no methods :meth:`read` or :meth:`write`; use :meth:`recv`
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	777 and :meth:`send` without flags argument instead.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	778
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	779 Socket objects also have these (read-only) attributes that correspond to the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	780 values given to the :class:`socket` constructor.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	781
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	782
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	783 .. attribute:: socket.family
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	784
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	785 The socket family.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	786
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	787 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	788
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	789
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	790 .. attribute:: socket.type
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	791
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	792 The socket type.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	793
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	794 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	795
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	796
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	797 .. attribute:: socket.proto
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	798
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	799 The socket protocol.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	800
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	801 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	802
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	803
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	804 .. _socket-example:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	805
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	806 Example
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	807 -------
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	808
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	809 Here are four minimal example programs using the TCP/IP protocol: a server that
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	810 echoes all data that it receives back (servicing only one client), and a client
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	811 using it. Note that a server must perform the sequence :func:`socket`,
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	812 :meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	813 :meth:`accept` to service more than one client), while a client only needs the
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	814 sequence :func:`socket`, :meth:`connect`. Also note that the server does not
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	815 :meth:`send`/:meth:`recv` on the socket it is listening on but on the new
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	816 socket returned by :meth:`accept`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	817
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	818 The first two examples support IPv4 only. ::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	819
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	820 # Echo server program
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	821 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	822
46655 a94b9db9223f #2752: wrong meaning of '' for socket host. Georg Brandl <georg@python.org> parents: 45429 diff changeset	823 HOST = '' # Symbolic name meaning all available interfaces
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	824 PORT = 50007 # Arbitrary non-privileged port
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	825 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	826 s.bind((HOST, PORT))
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	827 s.listen(1)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	828 conn, addr = s.accept()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	829 print 'Connected by', addr
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	830 while 1:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	831 data = conn.recv(1024)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	832 if not data: break
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	833 conn.send(data)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	834 conn.close()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	835
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	836 ::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	837
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	838 # Echo client program
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	839 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	840
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	841 HOST = 'daring.cwi.nl' # The remote host
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	842 PORT = 50007 # The same port as used by the server
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	843 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	844 s.connect((HOST, PORT))
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	845 s.send('Hello, world')
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	846 data = s.recv(1024)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	847 s.close()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	848 print 'Received', repr(data)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	849
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	850 The next two examples are identical to the above two, but support both IPv4 and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	851 IPv6. The server side will listen to the first address family available (it
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	852 should listen to both instead). On most of IPv6-ready systems, IPv6 will take
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	853 precedence and the server may not accept IPv4 traffic. The client side will try
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	854 to connect to the all addresses returned as a result of the name resolution, and
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	855 sends traffic to the first one connected successfully. ::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	856
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	857 # Echo server program
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	858 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	859 import sys
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	860
46862 f6388dc019cc #2742: ``''`` is not converted to NULL in getaddrinfo. Georg Brandl <georg@python.org> parents: 46681 diff changeset	861 HOST = None # Symbolic name meaning all available interfaces
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	862 PORT = 50007 # Arbitrary non-privileged port
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	863 s = None
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	864 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	865 socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	866 af, socktype, proto, canonname, sa = res
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	867 try:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	868 s = socket.socket(af, socktype, proto)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	869 except socket.error, msg:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	870 s = None
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	871 continue
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	872 try:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	873 s.bind(sa)
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	874 s.listen(1)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	875 except socket.error, msg:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	876 s.close()
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	877 s = None
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	878 continue
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	879 break
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	880 if s is None:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	881 print 'could not open socket'
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	882 sys.exit(1)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	883 conn, addr = s.accept()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	884 print 'Connected by', addr
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	885 while 1:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	886 data = conn.recv(1024)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	887 if not data: break
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	888 conn.send(data)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	889 conn.close()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	890
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	891 ::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	892
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	893 # Echo client program
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	894 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	895 import sys
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	896
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	897 HOST = 'daring.cwi.nl' # The remote host
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	898 PORT = 50007 # The same port as used by the server
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	899 s = None
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	900 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	901 af, socktype, proto, canonname, sa = res
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	902 try:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	903 s = socket.socket(af, socktype, proto)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	904 except socket.error, msg:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	905 s = None
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	906 continue
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	907 try:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	908 s.connect(sa)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	909 except socket.error, msg:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	910 s.close()
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	911 s = None
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	912 continue
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	913 break
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	914 if s is None:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	915 print 'could not open socket'
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	916 sys.exit(1)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	917 s.send('Hello, world')
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	918 data = s.recv(1024)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	919 s.close()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	920 print 'Received', repr(data)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	921
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	922
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	923 The last example shows how to write a very simple network sniffer with raw
46872 6bd666075e14 Fix typo. Georg Brandl <georg@python.org> parents: 46862 diff changeset	924 sockets on Windows. The example requires administrator privileges to modify
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	925 the interface::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	926
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	927 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	928
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	929 # the public network interface
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	930 HOST = socket.gethostbyname(socket.gethostname())
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	931
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	932 # create a raw socket and bind it to the public interface
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	933 s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	934 s.bind((HOST, 0))
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	935
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	936 # Include IP headers
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	937 s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	938
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	939 # receive all packages
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	940 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	941
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	942 # receive a package
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	943 print s.recvfrom(65565)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	944
45429 853af5bbb497 A lot more typo fixes by Ori Avtalion. Georg Brandl <georg@python.org> parents: 45085 diff changeset	945 # disabled promiscuous mode
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	946 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/socket.rst @ 58925:eecf1bef052d 2.6