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

annotate Doc/library/socket.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	2291aff20a05
children	4e9617d3c514

rev	line source
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	1 :mod:`socket` --- Low-level networking interface
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	2 ================================================
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 .. module:: socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	5 :synopsis: Low-level networking interface.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	6
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 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	9 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	10 platforms.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	11
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	12 .. note::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	13
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	14 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	15 system socket APIs.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	16
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	17 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	18 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	19 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	20 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	21 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	22 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	23 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	24 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	25 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	26
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	27 .. index:: object: socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	28
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	29 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	30 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	31 :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	32 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	33 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	34 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	35 is implicit on send operations.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	36
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	37 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	38 :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	39 :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	40 hostname in Internet domain notation like ``'daring.cwi.nl'`` or an IPv4 address
77420 412c7daed0db Issue #15060: better fix, thanks to review on #python-dev Sandro Tosi <sandro.tosi@gmail.com> parents: 77417 diff changeset	41 like ``'100.50.200.5'``, and port is an integer. For
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	42 :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	43 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	44 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	45 :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	46 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	47 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	48 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	49 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	50 object was created.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	51
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	52 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	53 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	54 ``'<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	55 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	56 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	57
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	58 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	59 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	60 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	61 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	62 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	63 numeric address in host portion.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	64
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	65 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	66 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	67
44561 ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	68 .. 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	69 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	70 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	71 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	72 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	73 ``(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	74
75267 bb3c228302d0 Mark up constants in socket doc as such Éric Araujo <merwok@netwok.org> parents: 74844 diff changeset	75 - addr_type is one of :const;`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`,
bb3c228302d0 Mark up constants in socket doc as such Éric Araujo <merwok@netwok.org> parents: 74844 diff changeset	76 or :const:`TIPC_ADDR_ID`.
bb3c228302d0 Mark up constants in socket doc as such Éric Araujo <merwok@netwok.org> parents: 74844 diff changeset	77 - scope is one of :const:`TIPC_ZONE_SCOPE`, :const:`TIPC_CLUSTER_SCOPE`,
bb3c228302d0 Mark up constants in socket doc as such Éric Araujo <merwok@netwok.org> parents: 74844 diff changeset	78 and :const:`TIPC_NODE_SCOPE`.
bb3c228302d0 Mark up constants in socket doc as such Éric Araujo <merwok@netwok.org> parents: 74844 diff changeset	79 - If addr_type is :const:`TIPC_ADDR_NAME`, then v1 is the server type, v2 is
62292 8f27b61a40fa Merged revisions 81940-81942 via svnmerge from Georg Brandl <georg@python.org> parents: 61999 diff changeset	80 the port identifier, and v3 should be 0.
44561 ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	81
75267 bb3c228302d0 Mark up constants in socket doc as such Éric Araujo <merwok@netwok.org> parents: 74844 diff changeset	82 If addr_type is :const:`TIPC_ADDR_NAMESEQ`, then v1 is the server type, v2
62292 8f27b61a40fa Merged revisions 81940-81942 via svnmerge from Georg Brandl <georg@python.org> parents: 61999 diff changeset	83 is the lower port number, and v3 is the upper port number.
44561 ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	84
75267 bb3c228302d0 Mark up constants in socket doc as such Éric Araujo <merwok@netwok.org> parents: 74844 diff changeset	85 If addr_type is :const:`TIPC_ADDR_ID`, then v1 is the node, v2 is the
62292 8f27b61a40fa Merged revisions 81940-81942 via svnmerge from Georg Brandl <georg@python.org> parents: 61999 diff changeset	86 reference, and v3 should be set to 0.
44561 ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	87
ac51cfe5c5c6 Issue #1646: Make socket support TIPC. The socket module now has support Christian Heimes <christian@cheimes.de> parents: 44501 diff changeset	88
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	89 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	90 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	91 semantics raise the error :exc:`socket.error`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	92
60952 c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	93 Non-blocking mode is supported through :meth:`~socket.setblocking`. A
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	94 generalization of this based on timeouts is supported through
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	95 :meth:`~socket.settimeout`.
44501 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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	122 returned by the :c:func:`hstrerror` C function.
44501 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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	130 description of error, as returned by the :c:func:`gai_strerror` C function. The
44501 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
58112 72e3e85bac8b Adds an optional source_address parameter to socket.create_connection(). Gregory P. Smith <greg@mad-scientist.com> parents: 57795 diff changeset	208 .. function:: create_connection(address[, timeout[, source_address]])
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	209
74345 60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	210 Connect to a TCP service listening on the Internet address (a 2-tuple
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	211 ``(host, port)``), and return the socket object. This is a higher-level
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	212 function than :meth:`socket.connect`: if host is a non-numeric hostname,
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	213 it will try to resolve it for both :data:`AF_INET` and :data:`AF_INET6`,
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	214 and then try to connect to all possible addresses in turn until a
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	215 connection succeeds. This makes it easy to write clients that are
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	216 compatible to both IPv4 and IPv6.
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	217
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	218 Passing the optional timeout parameter will set the timeout on the
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	219 socket instance before attempting to connect. If no timeout is
60e77810a47e Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 72203 diff changeset	220 supplied, the global default timeout setting returned by
47372 e2c5ae30cffe Fixed the semantic of timeout for socket.create_connection and Facundo Batista <facundobatista@gmail.com> parents: 47241 diff changeset	221 :func:`getdefaulttimeout` is used.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	222
58112 72e3e85bac8b Adds an optional source_address parameter to socket.create_connection(). Gregory P. Smith <greg@mad-scientist.com> parents: 57795 diff changeset	223 If supplied, source_address must be a 2-tuple ``(host, port)`` for the
72e3e85bac8b Adds an optional source_address parameter to socket.create_connection(). Gregory P. Smith <greg@mad-scientist.com> parents: 57795 diff changeset	224 socket to bind to as its source address before connecting. If host or port
72e3e85bac8b Adds an optional source_address parameter to socket.create_connection(). Gregory P. Smith <greg@mad-scientist.com> parents: 57795 diff changeset	225 are '' or 0 respectively the OS default behavior will be used.
72e3e85bac8b Adds an optional source_address parameter to socket.create_connection(). Gregory P. Smith <greg@mad-scientist.com> parents: 57795 diff changeset	226
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	227 .. versionadded:: 2.6
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	228
58113 a19ad299095f issue3972: HTTPConnection and HTTPSConnection now support a Gregory P. Smith <greg@mad-scientist.com> parents: 58112 diff changeset	229 .. versionchanged:: 2.7
a19ad299095f issue3972: HTTPConnection and HTTPSConnection now support a Gregory P. Smith <greg@mad-scientist.com> parents: 58112 diff changeset	230 source_address was added.
58112 72e3e85bac8b Adds an optional source_address parameter to socket.create_connection(). Gregory P. Smith <greg@mad-scientist.com> parents: 57795 diff changeset	231
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	232
61999 c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	233 .. function:: getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0)
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	234
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	235 Translate the host/port argument into a sequence of 5-tuples that contain
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	236 all the necessary arguments for creating a socket connected to that service.
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	237 host is a domain name, a string representation of an IPv4/v6 address
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	238 or ``None``. port is a string service name such as ``'http'``, a numeric
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	239 port number or ``None``. By passing ``None`` as the value of host
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	240 and port, you can pass ``NULL`` to the underlying C API.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	241
61999 c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	242 The family, socktype and proto arguments can be optionally specified
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	243 in order to narrow the list of addresses returned. Passing zero as a
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	244 value for each of these arguments selects the full range of results.
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	245 The flags argument can be one or several of the ``AI_*`` constants,
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	246 and will influence how results are computed and returned.
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	247 For example, :const:`AI_NUMERICHOST` will disable domain name resolution
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	248 and will raise an error if host is a domain name.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	249
61999 c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	250 The function returns a list of 5-tuples with the following structure:
44501 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 ``(family, socktype, proto, canonname, sockaddr)``
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	253
61999 c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	254 In these tuples, family, socktype, proto are all integers and are
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	255 meant to be passed to the :func:`socket` function. canonname will be
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	256 a string representing the canonical name of the host if
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	257 :const:`AI_CANONNAME` is part of the flags argument; else canonname
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	258 will be empty. sockaddr is a tuple describing a socket address, whose
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	259 format depends on the returned family (a ``(address, port)`` 2-tuple for
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	260 :const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	261 :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	262 method.
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	263
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	264 The following example fetches address information for a hypothetical TCP
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	265 connection to ``www.python.org`` on port 80 (results may differ on your
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	266 system if IPv6 isn't enabled)::
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	267
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	268 >>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.SOL_TCP)
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	269 [(2, 1, 6, '', ('82.94.164.162', 80)),
c963478b9092 Merged revisions 81621 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61700 diff changeset	270 (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	271
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	272 .. versionadded:: 2.2
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	273
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 .. function:: getfqdn([name])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	276
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	277 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	278 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	279 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	280 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	281 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	282 :func:`gethostname` is returned.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	283
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	284 .. versionadded:: 2.0
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	285
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	286
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	287 .. function:: gethostbyname(hostname)
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 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	290 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	291 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	292 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	293 :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	294
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	295
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	296 .. function:: gethostbyname_ex(hostname)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	297
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	298 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	299 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	300 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	301 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	302 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	303 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	304 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	305 stack support.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	306
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 .. function:: gethostname()
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 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	311 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	312
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	313 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	314 ``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	315 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	316 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	317
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	318 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	319 name; use ``getfqdn()`` (see above).
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	320
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 .. function:: gethostbyaddr(ip_address)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	323
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	324 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	325 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	326 (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	327 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	328 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	329 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	330 both IPv4 and IPv6.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	331
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 .. function:: getnameinfo(sockaddr, flags)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	334
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	335 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	336 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	337 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	338 string port name or a numeric port number.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	339
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	340 .. versionadded:: 2.2
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	341
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 .. function:: getprotobyname(protocolname)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	344
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	345 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	346 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	347 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	348 (: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	349 automatically if the protocol is omitted or zero.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	350
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 .. function:: getservbyname(servicename[, protocolname])
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 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	355 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	356 ``'udp'``, otherwise any protocol will match.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	357
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	358
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	359 .. function:: getservbyport(port[, protocolname])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	360
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	361 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	362 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	363 ``'udp'``, otherwise any protocol will match.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	364
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	365
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	366 .. function:: socket([family[, type[, proto]]])
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 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	369 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	370 :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	371 :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	372 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	373 omitted in that case.
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
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	376 .. function:: socketpair([family[, type[, proto]]])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	377
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	378 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	379 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	380 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	381 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	382 Availability: Unix.
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 .. versionadded:: 2.4
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	385
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	386
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	387 .. function:: fromfd(fd, family, type[, proto])
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 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	390 :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	391 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	392 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	393 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	394 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	395 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	396 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	397 Availability: Unix.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	398
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	399
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	400 .. function:: ntohl(x)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	401
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	402 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	403 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	404 otherwise, it performs a 4-byte swap operation.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	405
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	406
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	407 .. function:: ntohs(x)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	408
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	409 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	410 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	411 otherwise, it performs a 2-byte swap operation.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	412
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 .. function:: htonl(x)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	415
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	416 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	417 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	418 otherwise, it performs a 4-byte swap operation.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	419
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	420
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	421 .. function:: htons(x)
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 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	424 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	425 otherwise, it performs a 2-byte swap operation.
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_aton(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 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	431 '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	432 length. This is useful when conversing with a program that uses the standard C
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	433 library and needs objects of type :c:type:`struct in_addr`, which is the C type
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	434 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	435
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	436 :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	437 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	438
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	439 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	440 :exc:`socket.error` will be raised. Note that exactly what is valid depends on
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	441 the underlying C implementation of :c:func:`inet_aton`.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	442
54348 a27a739cef7f Merged revisions 72085,72132,72159,72288,72290,72292 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	443 :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	444 instead for IPv4/v6 dual stack support.
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
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	447 .. function:: inet_ntoa(packed_ip)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	448
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	449 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	450 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	451 is useful when conversing with a program that uses the standard C library and
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	452 needs objects of type :c:type:`struct in_addr`, which is the C type for the
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	453 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	454
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	455 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	456 :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	457 :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	458
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	459
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	460 .. function:: inet_pton(address_family, ip_string)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	461
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	462 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	463 format. :func:`inet_pton` is useful when a library or network protocol calls for
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	464 an object of type :c:type:`struct in_addr` (similar to :func:`inet_aton`) or
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	465 :c:type:`struct in6_addr`.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	466
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	467 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	468 :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	469 :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	470 both the value of address_family and the underlying implementation of
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	471 :c:func:`inet_pton`.
44501 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 Availability: Unix (maybe not all platforms).
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 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	476
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	477
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	478 .. function:: inet_ntop(address_family, packed_ip)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	479
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	480 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	481 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	482 ``'5aef:2b::8'``) :func:`inet_ntop` is useful when a library or network protocol
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	483 returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`)
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	484 or :c:type:`struct in6_addr`.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	485
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	486 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	487 :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	488 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	489 :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	490
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	491 Availability: Unix (maybe not all platforms).
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 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	494
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 .. function:: getdefaulttimeout()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	497
71863 dfe6f0a603d2 #12725: fix working. Patch by Ben Hayden. Ezio Melotti <ezio.melotti@gmail.com> parents: 70011 diff changeset	498 Return the default timeout in seconds (float) for new socket objects. A value
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	499 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	500 module is first imported, the default is ``None``.
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 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	503
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 .. function:: setdefaulttimeout(timeout)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	506
71863 dfe6f0a603d2 #12725: fix working. Patch by Ben Hayden. Ezio Melotti <ezio.melotti@gmail.com> parents: 70011 diff changeset	507 Set the default timeout in seconds (float) for new socket objects. A value of
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	508 ``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	509 module is first imported, the default is ``None``.
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 .. versionadded:: 2.3
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
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	514 .. data:: SocketType
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 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	517 same as ``type(socket(...))``.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	518
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	519
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	520 .. seealso::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	521
47241 ba1fa511b72d socketserver renaming reversal part 3: move the module into the right Georg Brandl <georg@python.org> parents: 46929 diff changeset	522 Module :mod:`SocketServer`
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	523 Classes that simplify writing network servers.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	524
67277 730b1af09238 Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65127 diff changeset	525 Module :mod:`ssl`
730b1af09238 Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65127 diff changeset	526 A TLS/SSL wrapper for socket objects.
730b1af09238 Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65127 diff changeset	527
44501 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 .. _socket-objects:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	530
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	531 Socket Objects
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	532 --------------
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	533
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	534 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	535 correspond to Unix system calls applicable to sockets.
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
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	538 .. method:: socket.accept()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	539
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	540 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	541 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	542 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	543 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	544
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	545
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	546 .. method:: socket.bind(address)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	547
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	548 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	549 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	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.close()
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 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	561 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	562 automatically closed when they are garbage-collected.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	563
67277 730b1af09238 Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65127 diff changeset	564 .. note::
730b1af09238 Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65127 diff changeset	565 :meth:`close()` releases the resource associated with a connection but
730b1af09238 Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65127 diff changeset	566 does not necessarily close the connection immediately. If you want
730b1af09238 Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65127 diff changeset	567 to close the connection in a timely fashion, call :meth:`shutdown()`
730b1af09238 Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65127 diff changeset	568 before :meth:`close()`.
730b1af09238 Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65127 diff changeset	569
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	570
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	571 .. method:: socket.connect(address)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	572
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	573 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	574 address family --- see above.)
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 .. note::
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 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	579 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	580 available in Python 2.0 and later.
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.connect_ex(address)
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 Like ``connect(address)``, but return an error indicator instead of raising an
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	586 exception for errors returned by the C-level :c:func:`connect` call (other
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	587 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	588 indicator is ``0`` if the operation succeeded, otherwise the value of the
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	589 :c:data:`errno` variable. This is useful to support, for example, asynchronous
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	590 connects.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	591
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	592 .. note::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	593
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	594 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	595 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	596 available in Python 2.0 and later.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	597
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	598
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	599 .. method:: socket.fileno()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	600
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	601 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	602 :func:`select.select`.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	603
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	604 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	605 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	606 this limitation.
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
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	609 .. method:: socket.getpeername()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	610
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	611 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	612 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	613 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	614 systems this function is not supported.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	615
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 .. method:: socket.getsockname()
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 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	620 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	621 the address family --- see above.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	622
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	623
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	624 .. method:: socket.getsockopt(level, optname[, buflen])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	625
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	626 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	627 :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	628 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	629 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	630 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	631 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	632 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	633 to decode C structures encoded as strings).
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	634
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	635
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	636 .. method:: socket.ioctl(control, option)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	637
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	638 :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	639
44703 c4383d765ca7 Markup fix Andrew M. Kuchling <amk@amk.ca> parents: 44561 diff changeset	640 The :meth:`ioctl` method is a limited interface to the WSAIoctl system
60952 c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	641 interface. Please refer to the `Win32 documentation
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	642 <http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	643 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	644
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	645 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	646 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	647
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	648 .. versionadded:: 2.6
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
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	651 .. method:: socket.listen(backlog)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	652
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	653 Listen for connections made to the socket. The backlog argument specifies the
70011 48743ad2d2ef Issue #8498: In socket.accept(), allow to specify 0 as a backlog value in Antoine Pitrou <solipsis@pitrou.net> parents: 68256 diff changeset	654 maximum number of queued connections and should be at least 0; the maximum value
48743ad2d2ef Issue #8498: In socket.accept(), allow to specify 0 as a backlog value in Antoine Pitrou <solipsis@pitrou.net> parents: 68256 diff changeset	655 is system-dependent (usually 5), the minimum value is forced to 0.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	656
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	657
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	658 .. method:: socket.makefile([mode[, bufsize]])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	659
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	660 .. index:: single: I/O control; buffering
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 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	663 described in :ref:`bltin-file-objects`.) The file object
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74345 diff changeset	664 references a :c:func:`dup`\ ped version of the socket file descriptor, so the
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	665 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	666 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	667 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	668 :func:`file` function.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	669
68015 8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from Georg Brandl <georg@python.org> parents: 67277 diff changeset	670 .. note::
8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from Georg Brandl <georg@python.org> parents: 67277 diff changeset	671
8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from Georg Brandl <georg@python.org> parents: 67277 diff changeset	672 On Windows, the file-like object created by :meth:`makefile` cannot be
8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from Georg Brandl <georg@python.org> parents: 67277 diff changeset	673 used where a file object with a file descriptor is expected, such as the
8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from Georg Brandl <georg@python.org> parents: 67277 diff changeset	674 stream arguments of :meth:`subprocess.Popen`.
8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from Georg Brandl <georg@python.org> parents: 67277 diff changeset	675
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	676
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	677 .. method:: socket.recv(bufsize[, flags])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	678
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	679 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	680 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	681 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	682 the optional argument flags; it defaults to zero.
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 .. note::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	685
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	686 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	687 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	688
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	689
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	690 .. method:: socket.recvfrom(bufsize[, flags])
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 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	693 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	694 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	695 :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	696 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	697
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	698
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	699 .. method:: socket.recvfrom_into(buffer[, nbytes[, flags]])
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 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	702 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	703 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	704 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	705 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	706 depends on the address family --- see above.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	707
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	708 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	709
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 .. method:: socket.recv_into(buffer[, nbytes[, flags]])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	712
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	713 Receive up to nbytes bytes from the socket, storing the data into a buffer
61700 1065d1c53309 Merged revisions 79822,79828,79862,80067,80069,80080-80081,80084,80432-80433 via svnmerge from Georg Brandl <georg@python.org> parents: 60952 diff changeset	714 rather than creating a new string. If nbytes is not specified (or 0),
1065d1c53309 Merged revisions 79822,79828,79862,80067,80069,80080-80081,80084,80432-80433 via svnmerge from Georg Brandl <georg@python.org> parents: 60952 diff changeset	715 receive up to the size available in the given buffer. Returns the number of
1065d1c53309 Merged revisions 79822,79828,79862,80067,80069,80080-80081,80084,80432-80433 via svnmerge from Georg Brandl <georg@python.org> parents: 60952 diff changeset	716 bytes received. See the Unix manual page :manpage:`recv(2)` for the meaning
1065d1c53309 Merged revisions 79822,79828,79862,80067,80069,80080-80081,80084,80432-80433 via svnmerge from Georg Brandl <georg@python.org> parents: 60952 diff changeset	717 of the optional argument flags; it defaults to zero.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	718
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	719 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	720
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 .. method:: socket.send(string[, flags])
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 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	725 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	726 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	727 all data has been sent; if only some of the data was transmitted, the
74844 aa6415d1e160 Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74395 diff changeset	728 application needs to attempt delivery of the remaining data. For further
aa6415d1e160 Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74395 diff changeset	729 information on this concept, consult the :ref:`socket-howto`.
44501 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
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	732 .. method:: socket.sendall(string[, flags])
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	733
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	734 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	735 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	736 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	737 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	738 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	739 much data, if any, was successfully sent.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	740
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	741
79025 2291aff20a05 #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. Ezio Melotti <ezio.melotti@gmail.com> parents: 77420 diff changeset	742 .. method:: socket.sendto(string, address)
2291aff20a05 #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. Ezio Melotti <ezio.melotti@gmail.com> parents: 77420 diff changeset	743 socket.sendto(string, flags, address)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	744
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	745 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	746 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	747 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	748 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	749 above.)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	750
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	751
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	752 .. method:: socket.setblocking(flag)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	753
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	754 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	755 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	756 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	757 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	758 :exc:`error` exception is raised; in blocking mode, the calls block until they
60952 c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	759 can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0.0)``;
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	760 ``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	761
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	762
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	763 .. method:: socket.settimeout(value)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	764
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	765 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	766 nonnegative float expressing seconds, or ``None``. If a float is given,
61496 b66ebb777568 Fix typo Andrew M. Kuchling <amk@amk.ca> parents: 60951 diff changeset	767 subsequent socket operations will raise a :exc:`timeout` exception if the
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	768 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	769 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	770 ``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	771 ``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	772
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	773 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	774
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 .. method:: socket.gettimeout()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	777
71863 dfe6f0a603d2 #12725: fix working. Patch by Ben Hayden. Ezio Melotti <ezio.melotti@gmail.com> parents: 70011 diff changeset	778 Return the timeout in seconds (float) associated with socket operations, or
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	779 ``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	780 :meth:`setblocking` or :meth:`settimeout`.
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 .. versionadded:: 2.3
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	783
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	784 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	785 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	786 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	787 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	788 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	789 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	790 operations fail if they cannot be completed within the timeout specified for the
60952 c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	791 socket or if the system returns an error. The :meth:`~socket.setblocking`
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	792 method is simply a shorthand for certain :meth:`~socket.settimeout` calls.
44501 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 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	795 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	796 to the same network endpoint. A consequence of this is that file objects
60952 c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	797 returned by the :meth:`~socket.makefile` method must only be used when the
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	798 socket is in blocking mode; in timeout or non-blocking mode file operations
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	799 that cannot be completed immediately will fail.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	800
60952 c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	801 Note that the :meth:`~socket.connect` operation is subject to the timeout
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	802 setting, and in general it is recommended to call :meth:`~socket.settimeout`
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	803 before calling :meth:`~socket.connect` or pass a timeout parameter to
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	804 :meth:`create_connection`. The system network stack may return a connection
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	805 timeout error 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	806
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 .. method:: socket.setsockopt(level, optname, value)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	809
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	810 .. index:: module: struct
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	811
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	812 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	813 :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	814 :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	815 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	816 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	817 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	818
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 .. method:: socket.shutdown(how)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	821
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	822 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	823 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	824 are disallowed. If how is :const:`SHUT_RDWR`, further sends and receives are
65127 ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 62290 diff changeset	825 disallowed. Depending on the platform, shutting down one half of the connection
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 62290 diff changeset	826 can also close the opposite half (e.g. on Mac OS X, ``shutdown(SHUT_WR)`` does
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 62290 diff changeset	827 not allow further reads on the other end of the connection).
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	828
60952 c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	829 Note that there are no methods :meth:`read` or :meth:`write`; use
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	830 :meth:`~socket.recv` and :meth:`~socket.send` without flags argument instead.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	831
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	832 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	833 values given to the :class:`socket` constructor.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	834
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 .. attribute:: socket.family
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 The socket family.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	839
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	840 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	841
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	842
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	843 .. attribute:: socket.type
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	844
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	845 The socket type.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	846
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	847 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	848
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 .. attribute:: socket.proto
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	851
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	852 The socket protocol.
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	853
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	854 .. versionadded:: 2.5
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	855
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 .. _socket-example:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	858
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	859 Example
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	860 -------
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	861
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	862 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	863 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	864 using it. Note that a server must perform the sequence :func:`socket`,
60952 c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	865 :meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	866 repeating the :meth:`~socket.accept` to service more than one client), while a
c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	867 client only needs the sequence :func:`socket`, :meth:`~socket.connect`. Also
74844 aa6415d1e160 Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74395 diff changeset	868 note that the server does not :meth:`~socket.sendall`/:meth:`~socket.recv` on
aa6415d1e160 Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74395 diff changeset	869 the socket it is listening on but on the new socket returned by
60952 c2ffd20d6cf8 Merged revisions 80465-80470 via svnmerge from Georg Brandl <georg@python.org> parents: 58556 diff changeset	870 :meth:`~socket.accept`.
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	871
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	872 The first two examples support IPv4 only. ::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	873
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	874 # Echo server program
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	875 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	876
46655 a94b9db9223f #2752: wrong meaning of '' for socket host. Georg Brandl <georg@python.org> parents: 45429 diff changeset	877 HOST = '' # Symbolic name meaning all available interfaces
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	878 PORT = 50007 # Arbitrary non-privileged port
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	879 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	880 s.bind((HOST, PORT))
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	881 s.listen(1)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	882 conn, addr = s.accept()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	883 print 'Connected by', addr
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	884 while 1:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	885 data = conn.recv(1024)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	886 if not data: break
74844 aa6415d1e160 Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74395 diff changeset	887 conn.sendall(data)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	888 conn.close()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	889
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 # Echo client program
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	893 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	894
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	895 HOST = 'daring.cwi.nl' # The remote host
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	896 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	897 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	898 s.connect((HOST, PORT))
74844 aa6415d1e160 Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74395 diff changeset	899 s.sendall('Hello, world')
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	900 data = s.recv(1024)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	901 s.close()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	902 print 'Received', repr(data)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	903
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	904 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	905 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	906 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	907 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	908 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	909 sends traffic to the first one connected successfully. ::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	910
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	911 # Echo server program
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	912 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	913 import sys
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	914
46862 f6388dc019cc #2742: ``''`` is not converted to NULL in getaddrinfo. Georg Brandl <georg@python.org> parents: 46681 diff changeset	915 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	916 PORT = 50007 # Arbitrary non-privileged port
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	917 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	918 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	919 socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	920 af, socktype, proto, canonname, sa = res
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	921 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	922 s = socket.socket(af, socktype, proto)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	923 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	924 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	925 continue
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	926 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	927 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	928 s.listen(1)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	929 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	930 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	931 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	932 continue
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	933 break
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	934 if s is None:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	935 print 'could not open socket'
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	936 sys.exit(1)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	937 conn, addr = s.accept()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	938 print 'Connected by', addr
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	939 while 1:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	940 data = conn.recv(1024)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	941 if not data: break
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	942 conn.send(data)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	943 conn.close()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	944
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	945 ::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	946
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	947 # Echo client program
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	948 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	949 import sys
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	950
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	951 HOST = 'daring.cwi.nl' # The remote host
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	952 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	953 s = None
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	954 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	955 af, socktype, proto, canonname, sa = res
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	956 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	957 s = socket.socket(af, socktype, proto)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	958 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	959 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	960 continue
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	961 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	962 s.connect(sa)
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	963 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	964 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	965 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	966 continue
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	967 break
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	968 if s is None:
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	969 print 'could not open socket'
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	970 sys.exit(1)
74844 aa6415d1e160 Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74395 diff changeset	971 s.sendall('Hello, world')
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	972 data = s.recv(1024)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	973 s.close()
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	974 print 'Received', repr(data)
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	975
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	976
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	977 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	978 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	979 the interface::
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	980
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	981 import socket
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	982
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	983 # the public network interface
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	984 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	985
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	986 # 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	987 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	988 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	989
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	990 # Include IP headers
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	991 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	992
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	993 # receive all packages
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	994 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	995
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	996 # receive a package
d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	997 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	998
45429 853af5bbb497 A lot more typo fixes by Ori Avtalion. Georg Brandl <georg@python.org> parents: 45085 diff changeset	999 # disabled promiscuous mode
44501 d00de0cf04e2 Revert socket.rst to unix-eol. Georg Brandl <georg@python.org> parents: 44474 diff changeset	1000 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)
72203 fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1001
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1002
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1003 Running an example several times with too small delay between executions, could
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1004 lead to this error::
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1005
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1006 socket.error: [Errno 98] Address already in use
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1007
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1008 This is because the previous execution has left the socket in a ``TIME_WAIT``
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1009 state, and can't be immediately reused.
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1010
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1011 There is a :mod:`socket` flag to set, in order to prevent this,
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1012 :data:`socket.SO_REUSEADDR`::
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1013
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1014 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1015 s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1016 s.bind((HOST, PORT))
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1017
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1018 the :data:`SO_REUSEADDR` flag tells the kernel to reuse a local socket in
fe60689d6a2e #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71863 diff changeset	1019 ``TIME_WAIT`` state, without waiting for its natural timeout to expire.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/socket.rst @ 79675:c0a2294de787 2.7