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

annotate Doc/library/socket.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	5ccec4b36646
children	74246129bd22

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

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/socket.rst @ 54294:dba767bc3155 legacy-trunk