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

annotate Doc/library/socket.rst @ 78069:a8aa77458e12 3.2

Add c_size_t and c_ssize_t to the ctypes summary table.

author	Antoine Pitrou <solipsis@pitrou.net>
date	Thu, 12 Jul 2012 20:31:50 +0200
parents	e616985284cd
children	b01eb870f84f d16065304bbd

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 :mod:`socket` --- Low-level networking interface
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 ================================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. module:: socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 :synopsis: Low-level networking interface.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 This module provides access to the BSD socket interface. It is available on
42645 a5e984eda45a Remove support for BeOS Skip Montanaro <skip@pobox.com> parents: 42604 diff changeset	9 all modern Unix systems, Windows, MacOS, OS/2, and probably additional
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 platforms.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 .. note::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 Some behavior may be platform dependent, since calls are made to the operating
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 system socket APIs.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 .. index:: object: socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 The Python interface is a straightforward transliteration of the Unix system
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 call and library interface for sockets to Python's object-oriented style: the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 :func:`socket` function returns a :dfn:`socket object` whose methods implement
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 the various socket system calls. Parameter types are somewhat higher-level than
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 in the C interface: as with :meth:`read` and :meth:`write` operations on Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 files, buffer allocation on receive operations is automatic, and buffer length
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 is implicit on send operations.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	27
67276 4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	28 .. seealso::
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	29
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	30 Module :mod:`socketserver`
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	31 Classes that simplify writing network servers.
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	32
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	33 Module :mod:`ssl`
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	34 A TLS/SSL wrapper for socket objects.
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	35
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	36
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	37 Socket families
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	38 ---------------
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	39
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	40 Depending on the system and the build options, various socket families
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	41 are supported by this module.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	42
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	43 Socket addresses are represented as follows:
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	44
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	45 - A single string is used for the :const:`AF_UNIX` address family.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	46
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	47 - A pair ``(host, port)`` is used for the :const:`AF_INET` address family,
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	48 where host is a string representing either a hostname in Internet domain
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	49 notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``,
77421 e616985284cd Issue #15060: better fix, thanks to review on #python-dev Sandro Tosi <sandro.tosi@gmail.com> parents: 77418 diff changeset	50 and port is an integer.
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	51
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	52 - For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	53 scopeid)`` is used, where flowinfo and scopeid represent the ``sin6_flowinfo``
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	54 and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C. For
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	55 :mod:`socket` module methods, flowinfo and scopeid can be omitted just for
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	56 backward compatibility. Note, however, omission of scopeid can cause problems
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	57 in manipulating scoped IPv6 addresses.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	58
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	59 - :const:`AF_NETLINK` sockets are represented as pairs ``(pid, groups)``.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	60
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	61 - Linux-only support for TIPC is available using the :const:`AF_TIPC`
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	62 address family. TIPC is an open, non-IP based networked protocol designed
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	63 for use in clustered computer environments. Addresses are represented by a
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	64 tuple, and the fields depend on the address type. The general tuple form is
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	65 ``(addr_type, v1, v2, v3 [, scope])``, where:
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	66
73788 5641a7c44f2b Mark up constants in sockets docs as such Éric Araujo <merwok@netwok.org> parents: 72204 diff changeset	67 - addr_type is one of :const:`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`,
5641a7c44f2b Mark up constants in sockets docs as such Éric Araujo <merwok@netwok.org> parents: 72204 diff changeset	68 or :const:`TIPC_ADDR_ID`.
5641a7c44f2b Mark up constants in sockets docs as such Éric Araujo <merwok@netwok.org> parents: 72204 diff changeset	69 - scope is one of :const:`TIPC_ZONE_SCOPE`, :const:`TIPC_CLUSTER_SCOPE`, and
5641a7c44f2b Mark up constants in sockets docs as such Éric Araujo <merwok@netwok.org> parents: 72204 diff changeset	70 :const:`TIPC_NODE_SCOPE`.
5641a7c44f2b Mark up constants in sockets docs as such Éric Araujo <merwok@netwok.org> parents: 72204 diff changeset	71 - If addr_type is :const:`TIPC_ADDR_NAME`, then v1 is the server type, v2 is
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	72 the port identifier, and v3 should be 0.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	73
73788 5641a7c44f2b Mark up constants in sockets docs as such Éric Araujo <merwok@netwok.org> parents: 72204 diff changeset	74 If addr_type is :const:`TIPC_ADDR_NAMESEQ`, then v1 is the server type, v2
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	75 is the lower port number, and v3 is the upper port number.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	76
73788 5641a7c44f2b Mark up constants in sockets docs as such Éric Araujo <merwok@netwok.org> parents: 72204 diff changeset	77 If addr_type is :const:`TIPC_ADDR_ID`, then v1 is the node, v2 is the
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	78 reference, and v3 should be set to 0.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	79
73788 5641a7c44f2b Mark up constants in sockets docs as such Éric Araujo <merwok@netwok.org> parents: 72204 diff changeset	80 If addr_type is :const:`TIPC_ADDR_ID`, then v1 is the node, v2 is the
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	81 reference, and v3 should be set to 0.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	82
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	83 - Certain other address families (:const:`AF_BLUETOOTH`, :const:`AF_PACKET`)
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	84 support specific representations.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	85
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	86 .. XXX document them!
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 For IPv4 addresses, two special forms are accepted instead of a host address:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 the empty string represents :const:`INADDR_ANY`, and the string
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	90 ``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. This behavior is not
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	91 compatible with IPv6, therefore, you may want to avoid these if you intend
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	92 to support IPv6 with your Python programs.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 If you use a hostname in the host portion of IPv4/v6 socket address, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 program may show a nondeterministic behavior, as Python uses the first address
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 returned from the DNS resolution. The socket address will be resolved
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 differently into an actual IPv4/v6 address, depending on the results from DNS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 resolution and/or the host configuration. For deterministic behavior use a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 numeric address in host portion.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 All errors raise exceptions. The normal exceptions for invalid argument types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 and out-of-memory conditions can be raised; errors related to socket or address
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	103 semantics raise :exc:`socket.error` or one of its subclasses.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104
61762 1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	105 Non-blocking mode is supported through :meth:`~socket.setblocking`. A
1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	106 generalization of this based on timeouts is supported through
1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	107 :meth:`~socket.settimeout`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	109
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	110 Module contents
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	111 ---------------
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	112
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 The module :mod:`socket` exports the following constants and functions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 .. exception:: error
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 .. index:: module: errno
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
68053 fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	120 A subclass of :exc:`IOError`, this exception is raised for socket-related
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	121 errors. It is recommended that you inspect its ``errno`` attribute to
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	122 discriminate between different kinds of errors.
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	123
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	124 .. seealso::
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	125 The :mod:`errno` module contains symbolic names for the error codes
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	126 defined by the underlying operating system.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 .. exception:: herror
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130
68053 fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	131 A subclass of :exc:`socket.error`, this exception is raised for
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	132 address-related errors, i.e. for functions that use h_errno in the POSIX
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	133 C API, including :func:`gethostbyname_ex` and :func:`gethostbyaddr`.
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	134 The accompanying value is a pair ``(h_errno, string)`` representing an
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	135 error returned by a library call. h_errno is a numeric value, while
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	136 string represents the description of h_errno, as returned by the
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	137 :c:func:`hstrerror` C function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 .. exception:: gaierror
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141
68053 fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	142 A subclass of :exc:`socket.error`, this exception is raised for
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	143 address-related errors by :func:`getaddrinfo` and :func:`getnameinfo`.
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	144 The accompanying value is a pair ``(error, string)`` representing an error
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	145 returned by a library call. string represents the description of
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	146 error, as returned by the :c:func:`gai_strerror` C function. The
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	147 numeric error value will match one of the :const:`EAI_\*` constants
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	148 defined in this module.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 .. exception:: timeout
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152
68053 fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	153 A subclass of :exc:`socket.error`, this exception is raised when a timeout
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	154 occurs on a socket which has had timeouts enabled via a prior call to
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	155 :meth:`~socket.settimeout` (or implicitly through
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	156 :func:`~socket.setdefaulttimeout`). The accompanying value is a string
fdf32fa0f440 Merged revisions 88686 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67383 diff changeset	157 whose value is currently always "timed out".
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 .. data:: AF_UNIX
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 AF_INET
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 AF_INET6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 These constants represent the address (and protocol) families, used for the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 first argument to :func:`socket`. If the :const:`AF_UNIX` constant is not
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	166 defined then this protocol is unsupported. More constants may be available
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	167 depending on the system.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 .. data:: SOCK_STREAM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 SOCK_DGRAM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 SOCK_RAW
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 SOCK_RDM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 SOCK_SEQPACKET
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 These constants represent the socket types, used for the second argument to
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	177 :func:`socket`. More constants may be available depending on the system.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	178 (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be generally
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	179 useful.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180
65314 12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	181 .. data:: SOCK_CLOEXEC
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	182 SOCK_NONBLOCK
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	183
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	184 These two constants, if defined, can be combined with the socket types and
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	185 allow you to set some flags atomically (thus avoiding possible race
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	186 conditions and the need for separate calls).
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	187
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	188 .. seealso::
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	189
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	190 `Secure File Descriptor Handling <http://udrepper.livejournal.com/20407.html>`_
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	191 for a more thorough explanation.
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	192
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	193 Availability: Linux >= 2.6.27.
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	194
12442ac3f7dd Issue #7523: Add SOCK_CLOEXEC and SOCK_NONBLOCK to the socket module, Antoine Pitrou <solipsis@pitrou.net> parents: 65258 diff changeset	195 .. versionadded:: 3.2
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 .. data:: SO_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 SOMAXCONN
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 MSG_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 SOL_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 IPPROTO_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 IPPORT_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 INADDR_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 IP_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 IPV6_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 EAI_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 AI_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 NI_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 TCP_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 Many constants of these forms, documented in the Unix documentation on sockets
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 and/or the IP protocol, are also defined in the socket module. They are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 methods of socket objects. In most cases, only those symbols that are defined
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 in the Unix header files are defined; for a few symbols, default values are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 provided.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	218 .. data:: SIO_*
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	219 RCVALL_*
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	220
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	221 Constants for Windows' WSAIoctl(). The constants are used as arguments to the
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	222 :meth:`ioctl` method of socket objects.
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	223
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	225 .. data:: TIPC_*
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	226
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	227 TIPC related constants, matching the ones exported by the C socket API. See
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	228 the TIPC documentation for more information.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	229
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	230
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 .. data:: has_ipv6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 This constant contains a boolean value which indicates if IPv6 is supported on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 this platform.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236
58114 b0386fe650c7 Merged revisions 77263-77264 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 57797 diff changeset	237 .. function:: create_connection(address[, timeout[, source_address]])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
74343 5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	239 Connect to a TCP service listening on the Internet address (a 2-tuple
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	240 ``(host, port)``), and return the socket object. This is a higher-level
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	241 function than :meth:`socket.connect`: if host is a non-numeric hostname,
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	242 it will try to resolve it for both :data:`AF_INET` and :data:`AF_INET6`,
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	243 and then try to connect to all possible addresses in turn until a
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	244 connection succeeds. This makes it easy to write clients that are
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	245 compatible to both IPv4 and IPv6.
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	246
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	247 Passing the optional timeout parameter will set the timeout on the
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	248 socket instance before attempting to connect. If no timeout is
5594cd88bfed Issue #13724: improve documentation for socket.create_connection. Antoine Pitrou <solipsis@pitrou.net> parents: 73788 diff changeset	249 supplied, the global default timeout setting returned by
47559 2925b568aacc Merged revisions 63562,63570,63728,63734,63784,63788,63802,63817,63827,63839,63887,63975,63998 via svnmerge from Georg Brandl <georg@python.org> parents: 47067 diff changeset	250 :func:`getdefaulttimeout` is used.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251
58114 b0386fe650c7 Merged revisions 77263-77264 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 57797 diff changeset	252 If supplied, source_address must be a 2-tuple ``(host, port)`` for the
b0386fe650c7 Merged revisions 77263-77264 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 57797 diff changeset	253 socket to bind to as its source address before connecting. If host or port
b0386fe650c7 Merged revisions 77263-77264 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 57797 diff changeset	254 are '' or 0 respectively the OS default behavior will be used.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255
58114 b0386fe650c7 Merged revisions 77263-77264 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 57797 diff changeset	256 .. versionchanged:: 3.2
b0386fe650c7 Merged revisions 77263-77264 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 57797 diff changeset	257 source_address was added.
b0386fe650c7 Merged revisions 77263-77264 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 57797 diff changeset	258
64574 caf0b4b0569e Fix issue 9794: adds context manager protocol to socket.socket so that socket.create_connection() can be used with the 'with' statement. Giampaolo Rodolà <g.rodola@gmail.com> parents: 64113 diff changeset	259 .. versionchanged:: 3.2
caf0b4b0569e Fix issue 9794: adds context manager protocol to socket.socket so that socket.create_connection() can be used with the 'with' statement. Giampaolo Rodolà <g.rodola@gmail.com> parents: 64113 diff changeset	260 support for the :keyword:`with` statement was added.
caf0b4b0569e Fix issue 9794: adds context manager protocol to socket.socket so that socket.create_connection() can be used with the 'with' statement. Giampaolo Rodolà <g.rodola@gmail.com> parents: 64113 diff changeset	261
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262
64113 ca2a859e9bf6 fix issue #8866: parameters passed to socket.getaddrinfo can now be specified as single keyword arguments. Giampaolo Rodolà <g.rodola@gmail.com> parents: 63890 diff changeset	263 .. function:: getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)
62001 8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	264
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	265 Translate the host/port argument into a sequence of 5-tuples that contain
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	266 all the necessary arguments for creating a socket connected to that service.
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	267 host is a domain name, a string representation of an IPv4/v6 address
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	268 or ``None``. port is a string service name such as ``'http'``, a numeric
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	269 port number or ``None``. By passing ``None`` as the value of host
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	270 and port, you can pass ``NULL`` to the underlying C API.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
64113 ca2a859e9bf6 fix issue #8866: parameters passed to socket.getaddrinfo can now be specified as single keyword arguments. Giampaolo Rodolà <g.rodola@gmail.com> parents: 63890 diff changeset	272 The family, type and proto arguments can be optionally specified
62001 8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	273 in order to narrow the list of addresses returned. Passing zero as a
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	274 value for each of these arguments selects the full range of results.
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	275 The flags argument can be one or several of the ``AI_*`` constants,
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	276 and will influence how results are computed and returned.
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	277 For example, :const:`AI_NUMERICHOST` will disable domain name resolution
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	278 and will raise an error if host is a domain name.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279
62001 8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	280 The function returns a list of 5-tuples with the following structure:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281
64113 ca2a859e9bf6 fix issue #8866: parameters passed to socket.getaddrinfo can now be specified as single keyword arguments. Giampaolo Rodolà <g.rodola@gmail.com> parents: 63890 diff changeset	282 ``(family, type, proto, canonname, sockaddr)``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283
64113 ca2a859e9bf6 fix issue #8866: parameters passed to socket.getaddrinfo can now be specified as single keyword arguments. Giampaolo Rodolà <g.rodola@gmail.com> parents: 63890 diff changeset	284 In these tuples, family, type, proto are all integers and are
62001 8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	285 meant to be passed to the :func:`socket` function. canonname will be
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	286 a string representing the canonical name of the host if
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	287 :const:`AI_CANONNAME` is part of the flags argument; else canonname
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	288 will be empty. sockaddr is a tuple describing a socket address, whose
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	289 format depends on the returned family (a ``(address, port)`` 2-tuple for
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	290 :const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	291 :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	292 method.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293
62001 8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	294 The following example fetches address information for a hypothetical TCP
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	295 connection to ``www.python.org`` on port 80 (results may differ on your
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	296 system if IPv6 isn't enabled)::
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	297
64113 ca2a859e9bf6 fix issue #8866: parameters passed to socket.getaddrinfo can now be specified as single keyword arguments. Giampaolo Rodolà <g.rodola@gmail.com> parents: 63890 diff changeset	298 >>> socket.getaddrinfo("www.python.org", 80, proto=socket.SOL_TCP)
62001 8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	299 [(2, 1, 6, '', ('82.94.164.162', 80)),
8a13f773a976 Merged revisions 81623 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61762 diff changeset	300 (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301
64113 ca2a859e9bf6 fix issue #8866: parameters passed to socket.getaddrinfo can now be specified as single keyword arguments. Giampaolo Rodolà <g.rodola@gmail.com> parents: 63890 diff changeset	302 .. versionchanged:: 3.2
ca2a859e9bf6 fix issue #8866: parameters passed to socket.getaddrinfo can now be specified as single keyword arguments. Giampaolo Rodolà <g.rodola@gmail.com> parents: 63890 diff changeset	303 parameters can now be passed as single keyword arguments.
ca2a859e9bf6 fix issue #8866: parameters passed to socket.getaddrinfo can now be specified as single keyword arguments. Giampaolo Rodolà <g.rodola@gmail.com> parents: 63890 diff changeset	304
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 .. function:: getfqdn([name])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 Return a fully qualified domain name for name. If name is omitted or empty,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 it is interpreted as the local host. To find the fully qualified name, the
49327 4844cac08652 Devil merge! Benjamin Peterson <benjamin@python.org> parents: 48690 diff changeset	309 hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 host, if available. The first name which includes a period is selected. In
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 case no fully qualified domain name is available, the hostname as returned by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 :func:`gethostname` is returned.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 .. function:: gethostbyname(hostname)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 Translate a host name to IPv4 address format. The IPv4 address is returned as a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 string, such as ``'100.50.200.5'``. If the host name is an IPv4 address itself
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 it is returned unchanged. See :func:`gethostbyname_ex` for a more complete
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 interface. :func:`gethostbyname` does not support IPv6 name resolution, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 :func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 .. function:: gethostbyname_ex(hostname)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 Translate a host name to IPv4 address format, extended interface. Return a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 triple ``(hostname, aliaslist, ipaddrlist)`` where hostname is the primary
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 host name responding to the given ip_address, aliaslist is a (possibly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 empty) list of alternative host names for the same address, and ipaddrlist is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 a list of IPv4 addresses for the same interface on the same host (often but not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 always a single address). :func:`gethostbyname_ex` does not support IPv6 name
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 stack support.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 .. function:: gethostname()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 Return a string containing the hostname of the machine where the Python
49650 5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	339 interpreter is currently executing.
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	340
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	341 If you want to know the current machine's IP address, you may want to use
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	342 ``gethostbyname(gethostname())``. This operation assumes that there is a
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	343 valid address-to-host mapping for the host, and the assumption does not
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	344 always hold.
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	345
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	346 Note: :func:`gethostname` doesn't always return the fully qualified domain
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	347 name; use ``getfqdn()`` (see above).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 .. function:: gethostbyaddr(ip_address)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 Return a triple ``(hostname, aliaslist, ipaddrlist)`` where hostname is the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 primary host name responding to the given ip_address, aliaslist is a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 (possibly empty) list of alternative host names for the same address, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 ipaddrlist is a list of IPv4/v6 addresses for the same interface on the same
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 host (most likely containing only a single address). To find the fully qualified
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 domain name, use the function :func:`getfqdn`. :func:`gethostbyaddr` supports
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 both IPv4 and IPv6.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 .. function:: getnameinfo(sockaddr, flags)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 Translate a socket address sockaddr into a 2-tuple ``(host, port)``. Depending
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 on the settings of flags, the result can contain a fully-qualified domain name
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 or numeric address representation in host. Similarly, port can contain a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 string port name or a numeric port number.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369 .. function:: getprotobyname(protocolname)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 Translate an Internet protocol name (for example, ``'icmp'``) to a constant
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 suitable for passing as the (optional) third argument to the :func:`socket`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 function. This is usually only needed for sockets opened in "raw" mode
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 (:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 automatically if the protocol is omitted or zero.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 .. function:: getservbyname(servicename[, protocolname])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 Translate an Internet service name and protocol name to a port number for that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 service. The optional protocol name, if given, should be ``'tcp'`` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 ``'udp'``, otherwise any protocol will match.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 .. function:: getservbyport(port[, protocolname])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387 Translate an Internet port number and protocol name to a service name for that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 service. The optional protocol name, if given, should be ``'tcp'`` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 ``'udp'``, otherwise any protocol will match.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 .. function:: socket([family[, type[, proto]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 Create a new socket using the given address family, socket type and protocol
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 number. The address family should be :const:`AF_INET` (the default),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 :const:`AF_INET6` or :const:`AF_UNIX`. The socket type should be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 :const:`SOCK_STREAM` (the default), :const:`SOCK_DGRAM` or perhaps one of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 other ``SOCK_`` constants. The protocol number is usually zero and may be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 omitted in that case.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 .. function:: socketpair([family[, type[, proto]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 Build a pair of connected socket objects using the given address family, socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 type, and protocol number. Address family, socket type, and protocol number are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 as for the :func:`socket` function above. The default family is :const:`AF_UNIX`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 if defined on the platform; otherwise, the default is :const:`AF_INET`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 Availability: Unix.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
64747 534853ba8cd3 Issue #1552: socket.socketpair() now returns regular socket.socket Antoine Pitrou <solipsis@pitrou.net> parents: 64574 diff changeset	410 .. versionchanged:: 3.2
534853ba8cd3 Issue #1552: socket.socketpair() now returns regular socket.socket Antoine Pitrou <solipsis@pitrou.net> parents: 64574 diff changeset	411 The returned socket objects now support the whole socket API, rather
534853ba8cd3 Issue #1552: socket.socketpair() now returns regular socket.socket Antoine Pitrou <solipsis@pitrou.net> parents: 64574 diff changeset	412 than a subset.
534853ba8cd3 Issue #1552: socket.socketpair() now returns regular socket.socket Antoine Pitrou <solipsis@pitrou.net> parents: 64574 diff changeset	413
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 .. function:: fromfd(fd, family, type[, proto])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 Duplicate the file descriptor fd (an integer as returned by a file object's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 :meth:`fileno` method) and build a socket object from the result. Address
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 family, socket type and protocol number are as for the :func:`socket` function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 above. The file descriptor should refer to a socket, but this is not checked ---
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 subsequent operations on the object may fail if the file descriptor is invalid.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 This function is rarely needed, but can be used to get or set socket options on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 a socket passed to a program as standard input or output (such as a server
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424 started by the Unix inet daemon). The socket is assumed to be in blocking mode.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 .. function:: ntohl(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 Convert 32-bit positive integers from network to host byte order. On machines
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 where the host byte order is the same as network byte order, this is a no-op;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 otherwise, it performs a 4-byte swap operation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 .. function:: ntohs(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436 Convert 16-bit positive integers from network to host byte order. On machines
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 where the host byte order is the same as network byte order, this is a no-op;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 otherwise, it performs a 2-byte swap operation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 .. function:: htonl(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443 Convert 32-bit positive integers from host to network byte order. On machines
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 where the host byte order is the same as network byte order, this is a no-op;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 otherwise, it performs a 4-byte swap operation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 .. function:: htons(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 Convert 16-bit positive integers from host to network byte order. On machines
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 where the host byte order is the same as network byte order, this is a no-op;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 otherwise, it performs a 2-byte swap operation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 .. function:: inet_aton(ip_string)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 Convert an IPv4 address from dotted-quad string format (for example,
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	458 '123.45.67.89') to 32-bit packed binary format, as a bytes object four characters in
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 length. This is useful when conversing with a program that uses the standard C
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	460 library and needs objects of type :c:type:`struct in_addr`, which is the C type
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 for the 32-bit packed binary this function returns.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462
54575 ddb50c3b86f2 Merged revisions 73217 via svnmerge from Georg Brandl <georg@python.org> parents: 53750 diff changeset	463 :func:`inet_aton` also accepts strings with less than three dots; see the
ddb50c3b86f2 Merged revisions 73217 via svnmerge from Georg Brandl <georg@python.org> parents: 53750 diff changeset	464 Unix manual page :manpage:`inet(3)` for details.
ddb50c3b86f2 Merged revisions 73217 via svnmerge from Georg Brandl <georg@python.org> parents: 53750 diff changeset	465
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 If the IPv4 address string passed to this function is invalid,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 :exc:`socket.error` will be raised. Note that exactly what is valid depends on
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	468 the underlying C implementation of :c:func:`inet_aton`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469
53750 310daa99d607 Merged revisions 72292 via svnmerge from Georg Brandl <georg@python.org> parents: 51712 diff changeset	470 :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 instead for IPv4/v6 dual stack support.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 .. function:: inet_ntoa(packed_ip)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	476 Convert a 32-bit packed IPv4 address (a bytes object four characters in
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	477 length) to its standard dotted-quad string representation (for example,
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	478 '123.45.67.89'). This is useful when conversing with a program that uses the
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	479 standard C library and needs objects of type :c:type:`struct in_addr`, which
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	480 is the C type for the 32-bit packed binary data this function takes as an
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	481 argument.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	483 If the byte sequence passed to this function is not exactly 4 bytes in
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	484 length, :exc:`socket.error` will be raised. :func:`inet_ntoa` does not
53750 310daa99d607 Merged revisions 72292 via svnmerge from Georg Brandl <georg@python.org> parents: 51712 diff changeset	485 support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	486 stack support.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 .. function:: inet_pton(address_family, ip_string)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	491 Convert an IP address from its family-specific string format to a packed,
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	492 binary format. :func:`inet_pton` is useful when a library or network protocol
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	493 calls for an object of type :c:type:`struct in_addr` (similar to
521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	494 :func:`inet_aton`) or :c:type:`struct in6_addr`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 Supported values for address_family are currently :const:`AF_INET` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497 :const:`AF_INET6`. If the IP address string ip_string is invalid,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 :exc:`socket.error` will be raised. Note that exactly what is valid depends on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 both the value of address_family and the underlying implementation of
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	500 :c:func:`inet_pton`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 Availability: Unix (maybe not all platforms).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 .. function:: inet_ntop(address_family, packed_ip)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	507 Convert a packed IP address (a bytes object of some number of characters) to its
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 standard, family-specific string representation (for example, ``'7.10.0.5'`` or
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	509 ``'5aef:2b::8'``). :func:`inet_ntop` is useful when a library or network protocol
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	510 returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`)
521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	511 or :c:type:`struct in6_addr`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 Supported values for address_family are currently :const:`AF_INET` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 :const:`AF_INET6`. If the string packed_ip is not the correct length for the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 specified address family, :exc:`ValueError` will be raised. A
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 Availability: Unix (maybe not all platforms).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521 .. function:: getdefaulttimeout()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522
71864 ab3432a81c26 #12725: fix working. Patch by Ben Hayden. Ezio Melotti <ezio.melotti@gmail.com> parents: 70012 diff changeset	523 Return the default timeout in seconds (float) for new socket objects. A value
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524 of ``None`` indicates that new socket objects have no timeout. When the socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 module is first imported, the default is ``None``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 .. function:: setdefaulttimeout(timeout)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529
71864 ab3432a81c26 #12725: fix working. Patch by Ben Hayden. Ezio Melotti <ezio.melotti@gmail.com> parents: 70012 diff changeset	530 Set the default timeout in seconds (float) for new socket objects. When
67384 4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	531 the socket module is first imported, the default is ``None``. See
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	532 :meth:`~socket.settimeout` for possible values and their respective
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	533 meanings.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 .. data:: SocketType
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 This is a Python type object that represents the socket object type. It is the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 same as ``type(socket(...))``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 .. _socket-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 Socket Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 --------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 Socket objects have the following methods. Except for :meth:`makefile` these
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 correspond to Unix system calls applicable to sockets.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 .. method:: socket.accept()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 Accept a connection. The socket must be bound to an address and listening for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554 connections. The return value is a pair ``(conn, address)`` where conn is a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 new socket object usable to send and receive data on the connection, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556 address is the address bound to the socket on the other end of the connection.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 .. method:: socket.bind(address)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 Bind the socket to address. The socket must not already be bound. (The format
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562 of address depends on the address family --- see above.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 .. method:: socket.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567 Close the socket. All future operations on the socket object will fail. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 remote end will receive no more data (after queued data is flushed). Sockets are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 automatically closed when they are garbage-collected.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570
67276 4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	571 .. note::
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	572 :meth:`close()` releases the resource associated with a connection but
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	573 does not necessarily close the connection immediately. If you want
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	574 to close the connection in a timely fashion, call :meth:`shutdown()`
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	575 before :meth:`close()`.
4260e30252eb Merged revisions 87653-87655 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66861 diff changeset	576
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 .. method:: socket.connect(address)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 Connect to a remote socket at address. (The format of address depends on the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 address family --- see above.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584 .. method:: socket.connect_ex(address)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 Like ``connect(address)``, but return an error indicator instead of raising an
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	587 exception for errors returned by the C-level :c:func:`connect` call (other
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 problems, such as "host not found," can still raise exceptions). The error
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589 indicator is ``0`` if the operation succeeded, otherwise the value of the
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64761 diff changeset	590 :c:data:`errno` variable. This is useful to support, for example, asynchronous
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 connects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593
63890 60076f28c023 Followup to r83869 and issue #8524: rename socket.forget() to socket.detach() Antoine Pitrou <solipsis@pitrou.net> parents: 63856 diff changeset	594 .. method:: socket.detach()
60076f28c023 Followup to r83869 and issue #8524: rename socket.forget() to socket.detach() Antoine Pitrou <solipsis@pitrou.net> parents: 63856 diff changeset	595
60076f28c023 Followup to r83869 and issue #8524: rename socket.forget() to socket.detach() Antoine Pitrou <solipsis@pitrou.net> parents: 63856 diff changeset	596 Put the socket object into closed state without actually closing the
60076f28c023 Followup to r83869 and issue #8524: rename socket.forget() to socket.detach() Antoine Pitrou <solipsis@pitrou.net> parents: 63856 diff changeset	597 underlying file descriptor. The file descriptor is returned, and can
60076f28c023 Followup to r83869 and issue #8524: rename socket.forget() to socket.detach() Antoine Pitrou <solipsis@pitrou.net> parents: 63856 diff changeset	598 be reused for other purposes.
60076f28c023 Followup to r83869 and issue #8524: rename socket.forget() to socket.detach() Antoine Pitrou <solipsis@pitrou.net> parents: 63856 diff changeset	599
60076f28c023 Followup to r83869 and issue #8524: rename socket.forget() to socket.detach() Antoine Pitrou <solipsis@pitrou.net> parents: 63856 diff changeset	600 .. versionadded:: 3.2
60076f28c023 Followup to r83869 and issue #8524: rename socket.forget() to socket.detach() Antoine Pitrou <solipsis@pitrou.net> parents: 63856 diff changeset	601
60076f28c023 Followup to r83869 and issue #8524: rename socket.forget() to socket.detach() Antoine Pitrou <solipsis@pitrou.net> parents: 63856 diff changeset	602
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603 .. method:: socket.fileno()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	605 Return the socket's file descriptor (a small integer). This is useful with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	606 :func:`select.select`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608 Under Windows the small integer returned by this method cannot be used where a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 file descriptor can be used (such as :func:`os.fdopen`). Unix does not have
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610 this limitation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613 .. method:: socket.getpeername()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 Return the remote address to which the socket is connected. This is useful to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616 find out the port number of a remote IPv4/v6 socket, for instance. (The format
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617 of the address returned depends on the address family --- see above.) On some
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618 systems this function is not supported.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621 .. method:: socket.getsockname()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623 Return the socket's own address. This is useful to find out the port number of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624 an IPv4/v6 socket, for instance. (The format of the address returned depends on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625 the address family --- see above.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628 .. method:: socket.getsockopt(level, optname[, buflen])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630 Return the value of the given socket option (see the Unix man page
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631 :manpage:`getsockopt(2)`). The needed symbolic constants (:const:`SO_\*` etc.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632 are defined in this module. If buflen is absent, an integer option is assumed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 and its integer value is returned by the function. If buflen is present, it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634 specifies the maximum length of the buffer used to receive the option in, and
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	635 this buffer is returned as a bytes object. It is up to the caller to decode the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 contents of the buffer (see the optional built-in module :mod:`struct` for a way
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	637 to decode C structures encoded as byte strings).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	639
67384 4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	640 .. method:: socket.gettimeout()
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	641
71864 ab3432a81c26 #12725: fix working. Patch by Ben Hayden. Ezio Melotti <ezio.melotti@gmail.com> parents: 70012 diff changeset	642 Return the timeout in seconds (float) associated with socket operations,
67384 4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	643 or ``None`` if no timeout is set. This reflects the last call to
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	644 :meth:`setblocking` or :meth:`settimeout`.
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	645
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	646
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	647 .. method:: socket.ioctl(control, option)
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	648
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	649 :platform: Windows
93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	650
44742 14d4104976fc Merged revisions 59985-60000,60002,60005-60007,60009-60042 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44568 diff changeset	651 The :meth:`ioctl` method is a limited interface to the WSAIoctl system
61762 1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	652 interface. Please refer to the `Win32 documentation
1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	653 <http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	654 information.
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	655
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54836 diff changeset	656 On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54836 diff changeset	657 functions may be used; they accept a socket object as their first argument.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659 .. method:: socket.listen(backlog)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661 Listen for connections made to the socket. The backlog argument specifies the
70012 713006ecee0c Issue #8498: In socket.accept(), allow to specify 0 as a backlog value in Antoine Pitrou <solipsis@pitrou.net> parents: 68257 diff changeset	662 maximum number of queued connections and should be at least 0; the maximum value
713006ecee0c Issue #8498: In socket.accept(), allow to specify 0 as a backlog value in Antoine Pitrou <solipsis@pitrou.net> parents: 68257 diff changeset	663 is system-dependent (usually 5), the minimum value is forced to 0.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665
67179 14fd0dfb16ff #10739: document that on Windows, socket.makefile() does not make a file that has a true file descriptor usable where such a thing is expected. Georg Brandl <georg@python.org> parents: 66859 diff changeset	666 .. method:: socket.makefile(mode='r', buffering=None, *, encoding=None, \
14fd0dfb16ff #10739: document that on Windows, socket.makefile() does not make a file that has a true file descriptor usable where such a thing is expected. Georg Brandl <georg@python.org> parents: 66859 diff changeset	667 errors=None, newline=None)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 .. index:: single: I/O control; buffering
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670
68008 c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67384 diff changeset	671 Return a :term:`file object` associated with the socket. The exact returned
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67384 diff changeset	672 type depends on the arguments given to :meth:`makefile`. These arguments are
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67384 diff changeset	673 interpreted the same way as by the built-in :func:`open` function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674
67384 4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	675 Closing the file object won't close the socket unless there are no remaining
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	676 references to the socket. The socket must be in blocking mode; it can have
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	677 a timeout, but the file object's internal buffer may end up in a inconsistent
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	678 state if a timeout occurs.
58150 d57291f5e668 Merged revisions 77300 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 57798 diff changeset	679
68008 c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67384 diff changeset	680 .. note::
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67384 diff changeset	681
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67384 diff changeset	682 On Windows, the file-like object created by :meth:`makefile` cannot be
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67384 diff changeset	683 used where a file object with a file descriptor is expected, such as the
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67384 diff changeset	684 stream arguments of :meth:`subprocess.Popen`.
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67384 diff changeset	685
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	687 .. method:: socket.recv(bufsize[, flags])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	689 Receive data from the socket. The return value is a bytes object representing the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 data received. The maximum amount of data to be received at once is specified
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691 by bufsize. See the Unix manual page :manpage:`recv(2)` for the meaning of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692 the optional argument flags; it defaults to zero.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694 .. note::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 For best match with hardware and network realities, the value of bufsize
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697 should be a relatively small power of 2, for example, 4096.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700 .. method:: socket.recvfrom(bufsize[, flags])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	702 Receive data from the socket. The return value is a pair ``(bytes, address)``
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	703 where bytes is a bytes object representing the data received and address is the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 address of the socket sending the data. See the Unix manual page
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 :manpage:`recv(2)` for the meaning of the optional argument flags; it defaults
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706 to zero. (The format of address depends on the address family --- see above.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709 .. method:: socket.recvfrom_into(buffer[, nbytes[, flags]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	711 Receive data from the socket, writing it into buffer instead of creating a
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	712 new bytestring. The return value is a pair ``(nbytes, address)`` where nbytes is
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713 the number of bytes received and address is the address of the socket sending
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714 the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715 optional argument flags; it defaults to zero. (The format of address
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716 depends on the address family --- see above.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 .. method:: socket.recv_into(buffer[, nbytes[, flags]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721 Receive up to nbytes bytes from the socket, storing the data into a buffer
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	722 rather than creating a new bytestring. If nbytes is not specified (or 0),
60504 a65f91bbc2fb Merged revisions 79307,79408,79430,79533,79542,79579-79580,79585-79587,79607-79608,79622,79717,79820,79822,79828,79862,79875,79923-79924,79941-79943,79945,79947,79951-79952 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58149 diff changeset	723 receive up to the size available in the given buffer. Returns the number of
a65f91bbc2fb Merged revisions 79307,79408,79430,79533,79542,79579-79580,79585-79587,79607-79608,79622,79717,79820,79822,79828,79862,79875,79923-79924,79941-79943,79945,79947,79951-79952 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58149 diff changeset	724 bytes received. See the Unix manual page :manpage:`recv(2)` for the meaning
a65f91bbc2fb Merged revisions 79307,79408,79430,79533,79542,79579-79580,79585-79587,79607-79608,79622,79717,79820,79822,79828,79862,79875,79923-79924,79941-79943,79945,79947,79951-79952 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58149 diff changeset	725 of the optional argument flags; it defaults to zero.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	728 .. method:: socket.send(bytes[, flags])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 Send data to the socket. The socket must be connected to a remote socket. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 optional flags argument has the same meaning as for :meth:`recv` above.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 Returns the number of bytes sent. Applications are responsible for checking that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 all data has been sent; if only some of the data was transmitted, the
74845 2aae44aa041a Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74343 diff changeset	734 application needs to attempt delivery of the remaining data. For further
2aae44aa041a Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74343 diff changeset	735 information on this topic, consult the :ref:`socket-howto`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	738 .. method:: socket.sendall(bytes[, flags])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740 Send data to the socket. The socket must be connected to a remote socket. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 optional flags argument has the same meaning as for :meth:`recv` above.
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	742 Unlike :meth:`send`, this method continues to send data from bytes until
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 either all data has been sent or an error occurs. ``None`` is returned on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 success. On error, an exception is raised, and there is no way to determine how
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 much data, if any, was successfully sent.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	748 .. method:: socket.sendto(bytes[, flags], address)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 Send data to the socket. The socket should not be connected to a remote socket,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 since the destination socket is specified by address. The optional flags
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 argument has the same meaning as for :meth:`recv` above. Return the number of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 bytes sent. (The format of address depends on the address family --- see
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 above.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757 .. method:: socket.setblocking(flag)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758
67384 4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	759 Set blocking or non-blocking mode of the socket: if flag is false, the
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	760 socket is set to non-blocking, else to blocking mode.
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	761
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	762 This method is a shorthand for certain :meth:`~socket.settimeout` calls:
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	763
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	764 * ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)``
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	765
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	766 * ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0.0)``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 .. method:: socket.settimeout(value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 Set a timeout on blocking socket operations. The value argument can be a
67384 4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	772 nonnegative floating point number expressing seconds, or ``None``.
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	773 If a non-zero value is given, subsequent socket operations will raise a
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	774 :exc:`timeout` exception if the timeout period value has elapsed before
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	775 the operation has completed. If zero is given, the socket is put in
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	776 non-blocking mode. If ``None`` is given, the socket is put in blocking mode.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777
67384 4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	778 For further information, please consult the :ref:`notes on socket timeouts <socket-timeouts>`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 .. method:: socket.setsockopt(level, optname, value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 .. index:: module: struct
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 Set the value of the given socket option (see the Unix manual page
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	788 bytes object representing a buffer. In the latter case it is up to the caller to
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	789 ensure that the bytestring contains the proper bits (see the optional built-in
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	790 module :mod:`struct` for a way to encode C structures as bytestrings).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793 .. method:: socket.shutdown(how)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795 Shut down one or both halves of the connection. If how is :const:`SHUT_RD`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 further receives are disallowed. If how is :const:`SHUT_WR`, further sends
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 are disallowed. If how is :const:`SHUT_RDWR`, further sends and receives are
65114 eb8e13784de7 Merged revisions 82629,82632,82724,82757-82758,82760-82763,82798-82799,82801 via svnmerge from Georg Brandl <georg@python.org> parents: 64767 diff changeset	798 disallowed. Depending on the platform, shutting down one half of the connection
eb8e13784de7 Merged revisions 82629,82632,82724,82757-82758,82760-82763,82798-82799,82801 via svnmerge from Georg Brandl <georg@python.org> parents: 64767 diff changeset	799 can also close the opposite half (e.g. on Mac OS X, ``shutdown(SHUT_WR)`` does
eb8e13784de7 Merged revisions 82629,82632,82724,82757-82758,82760-82763,82798-82799,82801 via svnmerge from Georg Brandl <georg@python.org> parents: 64767 diff changeset	800 not allow further reads on the other end of the connection).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801
61762 1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	802 Note that there are no methods :meth:`read` or :meth:`write`; use
1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	803 :meth:`~socket.recv` and :meth:`~socket.send` without flags argument instead.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	804
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805 Socket objects also have these (read-only) attributes that correspond to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806 values given to the :class:`socket` constructor.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 .. attribute:: socket.family
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811 The socket family.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814 .. attribute:: socket.type
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 The socket type.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819 .. attribute:: socket.proto
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821 The socket protocol.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823
67384 4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	824
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	825 .. _socket-timeouts:
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	826
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	827 Notes on socket timeouts
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	828 ------------------------
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	829
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	830 A socket object can be in one of three modes: blocking, non-blocking, or
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	831 timeout. Sockets are by default always created in blocking mode, but this
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	832 can be changed by calling :func:`setdefaulttimeout`.
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	833
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	834 * In blocking mode, operations block until complete or the system returns
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	835 an error (such as connection timed out).
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	836
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	837 * In non-blocking mode, operations fail (with an error that is unfortunately
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	838 system-dependent) if they cannot be completed immediately: functions from the
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	839 :mod:`select` can be used to know when and whether a socket is available for
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	840 reading or writing.
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	841
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	842 * In timeout mode, operations fail if they cannot be completed within the
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	843 timeout specified for the socket (they raise a :exc:`timeout` exception)
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	844 or if the system returns an error.
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	845
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	846 .. note::
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	847 At the operating system level, sockets in timeout mode are internally set
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	848 in non-blocking mode. Also, the blocking and timeout modes are shared between
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	849 file descriptors and socket objects that refer to the same network endpoint.
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	850 This implementation detail can have visible consequences if e.g. you decide
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	851 to use the :meth:`~socket.fileno()` of a socket.
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	852
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	853 Timeouts and the ``connect`` method
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	854 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	855
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	856 The :meth:`~socket.connect` operation is also subject to the timeout
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	857 setting, and in general it is recommended to call :meth:`~socket.settimeout`
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	858 before calling :meth:`~socket.connect` or pass a timeout parameter to
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	859 :meth:`create_connection`. However, the system network stack may also
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	860 return a connection timeout error of its own regardless of any Python socket
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	861 timeout setting.
4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	862
67383 bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	863 Timeouts and the ``accept`` method
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	864 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	865
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	866 If :func:`getdefaulttimeout` is not :const:`None`, sockets returned by
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	867 the :meth:`~socket.accept` method inherit that timeout. Otherwise, the
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	868 behaviour depends on settings of the listening socket:
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	869
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	870 * if the listening socket is in blocking mode or in timeout mode,
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	871 the socket returned by :meth:`~socket.accept` is in blocking mode;
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	872
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	873 * if the listening socket is in non-blocking mode, whether the socket
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	874 returned by :meth:`~socket.accept` is in blocking or non-blocking mode
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	875 is operating system-dependent. If you want to ensure cross-platform
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	876 behaviour, it is recommended you manually override this setting.
bdb57f463c85 Overhaul the documentation about socket timeouts. Antoine Pitrou <solipsis@pitrou.net> parents: 67273 diff changeset	877
67384 4bf3a5a04120 Merged revisions 87769 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 67276 diff changeset	878
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879 .. _socket-example:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	880
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881 Example
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882 -------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	883
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	884 Here are four minimal example programs using the TCP/IP protocol: a server that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	885 echoes all data that it receives back (servicing only one client), and a client
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886 using it. Note that a server must perform the sequence :func:`socket`,
61762 1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	887 :meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	888 repeating the :meth:`~socket.accept` to service more than one client), while a
1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	889 client only needs the sequence :func:`socket`, :meth:`~socket.connect`. Also
74845 2aae44aa041a Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74343 diff changeset	890 note that the server does not :meth:`~socket.sendall`/:meth:`~socket.recv` on
2aae44aa041a Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74343 diff changeset	891 the socket it is listening on but on the new socket returned by
61762 1f3e7812612b Merged revisions 81365,81367 via svnmerge from Georg Brandl <georg@python.org> parents: 58150 diff changeset	892 :meth:`~socket.accept`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	893
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	894 The first two examples support IPv4 only. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	895
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	896 # Echo server program
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	897 import socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	898
46664 031dfe455585 Merged revisions 62425-62429,62434-62436,62441,62444,62446-62448,62450-62455,62463,62465-62466,62469,62474,62476-62478,62480,62485,62492,62497-62498,62500,62507,62513-62514,62516,62521,62531,62535,62545-62546,62548-62551,62553-62559,62569,62574,62577,62593,62595,62604-62606,62608,62616,62626-62627,62636,62638,62644-62645,62647-62648,62651-62653,62656,62661,62663,62680,62686-62687,62696,62699-62703,62711 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45435 diff changeset	899 HOST = '' # Symbolic name meaning all available interfaces
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	900 PORT = 50007 # Arbitrary non-privileged port
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	901 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	902 s.bind((HOST, PORT))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	903 s.listen(1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	904 conn, addr = s.accept()
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	905 print('Connected by', addr)
43311 099ab823b84c Change instances of 'while 1:' in the docs into 'while True:'. Collin Winter <collinw@gmail.com> parents: 43300 diff changeset	906 while True:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	907 data = conn.recv(1024)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	908 if not data: break
74845 2aae44aa041a Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74343 diff changeset	909 conn.sendall(data)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	910 conn.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	911
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	912 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	913
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	914 # Echo client program
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	915 import socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	916
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	917 HOST = 'daring.cwi.nl' # The remote host
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	918 PORT = 50007 # The same port as used by the server
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	919 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	920 s.connect((HOST, PORT))
74845 2aae44aa041a Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74343 diff changeset	921 s.sendall(b'Hello, world')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	922 data = s.recv(1024)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	923 s.close()
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	924 print('Received', repr(data))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	925
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	926 The next two examples are identical to the above two, but support both IPv4 and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	927 IPv6. The server side will listen to the first address family available (it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	928 should listen to both instead). On most of IPv6-ready systems, IPv6 will take
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929 precedence and the server may not accept IPv4 traffic. The client side will try
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930 to connect to the all addresses returned as a result of the name resolution, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	931 sends traffic to the first one connected successfully. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	932
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	933 # Echo server program
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	934 import socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	935 import sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	936
47067 960ade856078 Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46978 diff changeset	937 HOST = None # Symbolic name meaning all available interfaces
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	938 PORT = 50007 # Arbitrary non-privileged port
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	939 s = None
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	940 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	941 socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	942 af, socktype, proto, canonname, sa = res
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	943 try:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	944 s = socket.socket(af, socktype, proto)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945 except socket.error as msg:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	946 s = None
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	947 continue
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	948 try:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	949 s.bind(sa)
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	950 s.listen(1)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	951 except socket.error as msg:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	952 s.close()
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	953 s = None
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	954 continue
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955 break
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	956 if s is None:
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	957 print('could not open socket')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958 sys.exit(1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959 conn, addr = s.accept()
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	960 print('Connected by', addr)
43311 099ab823b84c Change instances of 'while 1:' in the docs into 'while True:'. Collin Winter <collinw@gmail.com> parents: 43300 diff changeset	961 while True:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	962 data = conn.recv(1024)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963 if not data: break
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964 conn.send(data)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	965 conn.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	966
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	967 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	968
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	969 # Echo client program
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	970 import socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	971 import sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	972
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	973 HOST = 'daring.cwi.nl' # The remote host
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	974 PORT = 50007 # The same port as used by the server
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	975 s = None
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	976 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	977 af, socktype, proto, canonname, sa = res
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978 try:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	979 s = socket.socket(af, socktype, proto)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	980 except socket.error as msg:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	981 s = None
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	982 continue
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	983 try:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	984 s.connect(sa)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	985 except socket.error as msg:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	986 s.close()
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	987 s = None
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	988 continue
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	989 break
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	990 if s is None:
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	991 print('could not open socket')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	992 sys.exit(1)
74845 2aae44aa041a Fix Issue #6005: Examples in the socket library documentation use sendall, Senthil Kumaran <senthil@uthcode.com> parents: 74343 diff changeset	993 s.sendall(b'Hello, world')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	994 data = s.recv(1024)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	995 s.close()
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	996 print('Received', repr(data))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	997
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	998
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	999 The last example shows how to write a very simple network sniffer with raw
47067 960ade856078 Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46978 diff changeset	1000 sockets on Windows. The example requires administrator privileges to modify
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1001 the interface::
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1002
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1003 import socket
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1004
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1005 # the public network interface
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1006 HOST = socket.gethostbyname(socket.gethostname())
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	1007
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1008 # create a raw socket and bind it to the public interface
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1009 s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1010 s.bind((HOST, 0))
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	1011
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1012 # Include IP headers
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1013 s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	1014
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1015 # receive all packages
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1016 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	1017
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1018 # receive a package
46978 55d8c35322a7 Convert a lot of print statements to print functions in docstrings, Neal Norwitz <nnorwitz@gmail.com> parents: 46963 diff changeset	1019 print(s.recvfrom(65565))
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	1020
45435 42b3b117391d Merged revisions 60481,60485,60489-60492,60494-60496,60498-60499,60501-60503,60505-60506,60508-60509,60523-60524,60532,60543,60545,60547-60548,60552,60554,60556-60559,60561-60562,60569,60571-60572,60574,60576-60583,60585-60586,60589,60591,60594-60595,60597-60598,60600-60601,60606-60612,60615,60617,60619-60621,60623-60625,60627-60629,60631,60633,60635,60647,60650,60652,60654,60656,60658-60659,60664-60666,60668-60670,60672,60676,60678,60680-60683,60685-60686,60688,60690,60692-60694,60697-60700,60705-60706,60708,60711,60714,60720,60724-60730,60732,60736,60742,60744,60746,60748,60750-60751,60753,60756-60757,60759-60761,60763-60764,60766,60769-60770,60774-60784,60787-60789,60793,60796,60799-60809,60812-60813,60815-60821,60823-60826,60828-60829,60831-60834,60836,60838-60839,60846-60849,60852-60854,60856-60859,60861-60870,60874-60875,60880-60881,60886,60888-60890,60892,60894-60898,60900-60931,60933-60958 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45134 diff changeset	1021 # disabled promiscuous mode
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	1022 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1023
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1024
72204 c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1025 Running an example several times with too small delay between executions, could
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1026 lead to this error::
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1027
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1028 socket.error: [Errno 98] Address already in use
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1029
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1030 This is because the previous execution has left the socket in a ``TIME_WAIT``
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1031 state, and can't be immediately reused.
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1032
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1033 There is a :mod:`socket` flag to set, in order to prevent this,
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1034 :data:`socket.SO_REUSEADDR`::
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1035
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1036 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1037 s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1038 s.bind((HOST, PORT))
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1039
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1040 the :data:`SO_REUSEADDR` flag tells the kernel to reuse a local socket in
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1041 ``TIME_WAIT`` state, without waiting for its natural timeout to expire.
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1042
c4588cd2d59a #12781: Mention SO_REUSEADDR flag near socket examples Sandro Tosi <sandro.tosi@gmail.com> parents: 71864 diff changeset	1043
66861 8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1044 .. seealso::
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1045
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1046 For an introduction to socket programming (in C), see the following papers:
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1047
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1048 - An Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1049
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1050 - An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1051 al,
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1052
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1053 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1054 PS1:7 and PS1:8). The platform-specific reference material for the various
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1055 socket-related system calls are also a valuable source of information on the
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1056 details of socket semantics. For Unix, refer to the manual pages; for Windows,
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1057 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1058 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.
8081762eb6d1 Merged revisions 87197-87198 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65259 diff changeset	1059

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/socket.rst @ 78069:a8aa77458e12 3.2