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

annotate Doc/library/socket.rst @ 53750:310daa99d607

Merged revisions 72292 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r72292 | georg.brandl | 2009-05-04 22:49:17 +0200 (Mo, 04 Mai 2009) | 1 line #5916, 5917: small socket doc improvements. ........

author	Georg Brandl <georg@python.org>
date	Mon, 04 May 2009 20:50:30 +0000
parents	8a292543e871
children	ddb50c3b86f2

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 :mod:`socket` --- Low-level networking interface
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 .. module:: socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 :synopsis: Low-level networking interface.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 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	10 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	11 platforms.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 .. note::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 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	16 system socket APIs.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 For an introduction to socket programming (in C), see the following papers: An
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 al, both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 PS1:7 and PS1:8). The platform-specific reference material for the various
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 socket-related system calls are also a valuable source of information on the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 details of socket semantics. For Unix, refer to the manual pages; for Windows,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may
45134 bdcf40d1b38e Merged revisions 60481,60485,60489-60520,60523-60527,60530-60533,60535-60538,60540-60551 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44742 diff changeset	26 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 .. index:: object: socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 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	31 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	32 :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	33 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	34 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	35 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	36 is implicit on send operations.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 Socket addresses are represented as follows: A single string is used for the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 :const:`AF_UNIX` address family. A pair ``(host, port)`` is used for the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 :const:`AF_INET` address family, where host is a string representing either a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 hostname in Internet domain notation like ``'daring.cwi.nl'`` or an IPv4 address
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 like ``'100.50.200.5'``, and port is an integral port number. For
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 scopeid)`` is used, where flowinfo and scopeid represents ``sin6_flowinfo``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 and ``sin6_scope_id`` member in :const:`struct sockaddr_in6` in C. For
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 :mod:`socket` module methods, flowinfo and scopeid can be omitted just for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 backward compatibility. Note, however, omission of scopeid can cause problems
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 in manipulating scoped IPv6 addresses. Other address families are currently not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 supported. The address format required by a particular socket object is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 automatically selected based on the address family specified when the socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 object was created.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 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	54 the empty string represents :const:`INADDR_ANY`, and the string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 ``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. The behavior is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 available for IPv6 for backward compatibility, therefore, you may want to avoid
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 these if you intend to support IPv6 with your Python programs.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 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	60 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	61 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	62 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	63 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	64 numeric address in host portion.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65
43176 808f32a0d99c Get rid of the remaining versionadded/versionchanged directives. Georg Brandl <georg@python.org> parents: 42954 diff changeset	66 AF_NETLINK sockets are represented as pairs ``pid, groups``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	68
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	69 Linux-only support for TIPC is also available using the :const:`AF_TIPC`
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	70 address family. TIPC is an open, non-IP based networked protocol designed
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	71 for use in clustered computer environments. Addresses are represented by a
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	72 tuple, and the fields depend on the address type. The general tuple form is
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	73 ``(addr_type, v1, v2, v3 [, scope])``, where:
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	74
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	75 - addr_type is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	76 TIPC_ADDR_ID.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	77 - scope is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	78 TIPC_NODE_SCOPE.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	79 - If addr_type is TIPC_ADDR_NAME, then v1 is the server type, v2 is
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	80 the port identifier, and v3 should be 0.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	81
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	82 If addr_type is TIPC_ADDR_NAMESEQ, then v1 is the server type, v2
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	83 is the lower port number, and v3 is the upper port number.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	84
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	85 If addr_type is TIPC_ADDR_ID, then v1 is the node, v2 is the
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	86 reference, and v3 should be set to 0.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	87
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	88
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 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	90 and out-of-memory conditions can be raised; errors related to socket or address
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 semantics raise the error :exc:`socket.error`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 Non-blocking mode is supported through :meth:`setblocking`. A generalization of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 this based on timeouts is supported through :meth:`settimeout`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 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	97
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 .. exception:: error
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 .. index:: module: errno
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 This exception is raised for socket-related errors. The accompanying value is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 either a string telling what went wrong or a pair ``(errno, string)``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 representing an error returned by a system call, similar to the value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 accompanying :exc:`os.error`. See the module :mod:`errno`, which contains names
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 for the error codes defined by the underlying operating system.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 .. exception:: herror
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 This exception is raised for address-related errors, i.e. for functions that use
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 h_errno in the C API, including :func:`gethostbyname_ex` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 :func:`gethostbyaddr`.
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 The accompanying value is a pair ``(h_errno, string)`` representing an error
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 returned by a library call. string represents the description of h_errno, as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 returned by the :cfunc:`hstrerror` C function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 .. exception:: gaierror
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 This exception is raised for address-related errors, for :func:`getaddrinfo` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 :func:`getnameinfo`. The accompanying value is a pair ``(error, string)``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 representing an error returned by a library call. string represents the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 description of error, as returned by the :cfunc:`gai_strerror` C function. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 error value will match one of the :const:`EAI_\*` constants defined in this
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 module.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 .. exception:: timeout
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 This exception is raised when a timeout occurs on a socket which has had
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 timeouts enabled via a prior call to :meth:`settimeout`. The accompanying value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 is a string whose value is currently always "timed out".
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 .. data:: AF_UNIX
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 AF_INET
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 AF_INET6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 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	143 first argument to :func:`socket`. If the :const:`AF_UNIX` constant is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 defined then this protocol is unsupported.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 .. data:: SOCK_STREAM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 SOCK_DGRAM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 SOCK_RAW
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 SOCK_RDM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 SOCK_SEQPACKET
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 These constants represent the socket types, used for the second argument to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 :func:`socket`. (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 generally useful.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 .. data:: SO_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 SOMAXCONN
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 MSG_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 SOL_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 IPPROTO_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 IPPORT_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 INADDR_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 IP_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 IPV6_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 EAI_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 AI_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 NI_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 TCP_*
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 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	173 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	174 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	175 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	176 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	177 provided.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	179 .. data:: SIO_*
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	180 RCVALL_*
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	181
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	182 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	183 :meth:`ioctl` method of socket objects.
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	184
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	186 .. data:: TIPC_*
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	187
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	188 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	189 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	190
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	191
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 .. data:: has_ipv6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 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	195 this platform.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 .. function:: create_connection(address[, timeout])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199
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	200 Convenience function. Connect to address (a 2-tuple ``(host, port)``),
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	201 and return the socket object. Passing the optional timeout parameter will
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	202 set the timeout on the socket instance before attempting to connect. If no
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	203 timeout is supplied, the global default timeout setting returned by
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	204 :func:`getdefaulttimeout` is used.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 .. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 Resolves the host/port argument, into a sequence of 5-tuples that contain
49327 4844cac08652 Devil merge! Benjamin Peterson <benjamin@python.org> parents: 48690 diff changeset	210 all the necessary arguments for creating the corresponding socket. host is a domain
4844cac08652 Devil merge! Benjamin Peterson <benjamin@python.org> parents: 48690 diff changeset	211 name, a string representation of an IPv4/v6 address or ``None``. port is a string
4844cac08652 Devil merge! Benjamin Peterson <benjamin@python.org> parents: 48690 diff changeset	212 service name such as ``'http'``, a numeric port number or ``None``.
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	213 The rest of the arguments are optional and must be numeric if specified.
49327 4844cac08652 Devil merge! Benjamin Peterson <benjamin@python.org> parents: 48690 diff changeset	214 By passing ``None`` as the value of host and port, , you can pass ``NULL`` to the C API.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
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	216 The :func:`getaddrinfo` function returns a list of 5-tuples with the following
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	217 structure:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 ``(family, socktype, proto, canonname, sockaddr)``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220
49327 4844cac08652 Devil merge! Benjamin Peterson <benjamin@python.org> parents: 48690 diff changeset	221 family, socktype, proto are all integers and are meant to be passed to the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 :func:`socket` function. canonname is a string representing the canonical name
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 of the host. It can be a numeric IPv4/v6 address when :const:`AI_CANONNAME` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 specified for a numeric host. sockaddr is a tuple describing a socket
42775 d7517c306791 Merged revisions 57221-57391 via svnmerge from Guido van Rossum <guido@python.org> parents: 42645 diff changeset	225 address, as described above. See the source for :mod:`socket` and other
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 library modules for a typical usage of the function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 .. function:: getfqdn([name])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 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	232 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	233 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	234 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	235 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	236 :func:`gethostname` is returned.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 .. function:: gethostbyname(hostname)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 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	242 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	243 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	244 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	245 :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	246
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 .. function:: gethostbyname_ex(hostname)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 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	251 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	252 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	253 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	254 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	255 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	256 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	257 stack support.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 .. function:: gethostname()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 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	263 interpreter is currently executing.
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	264
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	265 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	266 ``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	267 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	268 always hold.
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	269
5b4cb8cd5051 Merged revisions 67089,67091,67101 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	270 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	271 name; use ``getfqdn()`` (see above).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 .. function:: gethostbyaddr(ip_address)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 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	277 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	278 (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	279 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	280 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	281 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	282 both IPv4 and IPv6.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 .. function:: getnameinfo(sockaddr, flags)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 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	288 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	289 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	290 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	291
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 .. function:: getprotobyname(protocolname)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 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	296 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	297 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	298 (: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	299 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	300
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 .. function:: getservbyname(servicename[, protocolname])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 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	305 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	306 ``'udp'``, otherwise any protocol will match.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 .. function:: getservbyport(port[, protocolname])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 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	312 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	313 ``'udp'``, otherwise any protocol will match.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 .. function:: socket([family[, type[, proto]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 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	319 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	320 :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	321 :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	322 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	323 omitted in that case.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324
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 .. function:: socketpair([family[, type[, proto]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 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	329 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	330 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	331 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	332 Availability: Unix.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333
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 .. function:: fromfd(fd, family, type[, proto])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 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	338 :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	339 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	340 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	341 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	342 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	343 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	344 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	345 Availability: Unix.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 .. function:: ntohl(x)
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 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	351 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	352 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	353
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 .. function:: ntohs(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 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	358 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	359 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	360
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 .. function:: htonl(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 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	365 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	366 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	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:: htons(x)
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 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	372 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	373 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	374
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 .. function:: inet_aton(ip_string)
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 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	379 '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	380 length. This is useful when conversing with a program that uses the standard C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 library and needs objects of type :ctype:`struct in_addr`, which is the C type
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 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	383
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 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	385 :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	386 the underlying C implementation of :cfunc:`inet_aton`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
53750 310daa99d607 Merged revisions 72292 via svnmerge from Georg Brandl <georg@python.org> parents: 51712 diff changeset	388 :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	389 instead for IPv4/v6 dual stack support.
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:: inet_ntoa(packed_ip)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	394 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	395 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	396 '123.45.67.89'). This is useful when conversing with a program that uses the
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	397 standard C library and needs objects of type :ctype:`struct in_addr`, which
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	398 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	399 argument.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	401 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	402 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	403 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	404 stack support.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 .. function:: inet_pton(address_family, ip_string)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	409 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	410 binary format. :func:`inet_pton` is useful when a library or network protocol
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	411 calls for an object of type :ctype:`struct in_addr` (similar to
f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	412 :func:`inet_aton`) or :ctype:`struct in6_addr`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 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	415 :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	416 :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	417 both the value of address_family and the underlying implementation of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 :cfunc:`inet_pton`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 Availability: Unix (maybe not all platforms).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421
53750 310daa99d607 Merged revisions 72292 via svnmerge from Georg Brandl <georg@python.org> parents: 51712 diff changeset	422 .. seealso::
310daa99d607 Merged revisions 72292 via svnmerge from Georg Brandl <georg@python.org> parents: 51712 diff changeset	423
310daa99d607 Merged revisions 72292 via svnmerge from Georg Brandl <georg@python.org> parents: 51712 diff changeset	424 :func:`ipaddr.BaseIP.packed`
310daa99d607 Merged revisions 72292 via svnmerge from Georg Brandl <georg@python.org> parents: 51712 diff changeset	425 Platform-independent conversion to a packed, binary format.
310daa99d607 Merged revisions 72292 via svnmerge from Georg Brandl <georg@python.org> parents: 51712 diff changeset	426
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 .. function:: inet_ntop(address_family, packed_ip)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	430 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	431 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	432 ``'5aef:2b::8'``). :func:`inet_ntop` is useful when a library or network protocol
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 returns an object of type :ctype:`struct in_addr` (similar to :func:`inet_ntoa`)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 or :ctype:`struct in6_addr`.
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 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	437 :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	438 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	439 :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	440
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 Availability: Unix (maybe not all platforms).
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 .. function:: getdefaulttimeout()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 Return the default timeout in floating seconds for new socket objects. A value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447 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	448 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	449
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 .. function:: setdefaulttimeout(timeout)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 Set the default timeout in floating seconds for new socket objects. A value of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 ``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	455 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	456
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 .. data:: SocketType
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 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	461 same as ``type(socket(...))``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465
46933 aca5c1d1c569 Renamed the SocketServer module to 'socketserver'. Alexandre Vassalotti <alexandre@peadrop.com> parents: 46690 diff changeset	466 Module :mod:`socketserver`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 Classes that simplify writing network servers.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 .. _socket-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472 Socket Objects
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 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	476 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	477
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 .. method:: socket.accept()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 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	482 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	483 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	484 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	485
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 .. method:: socket.bind(address)
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 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	490 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	491
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 .. method:: socket.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 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	496 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	497 automatically closed when they are garbage-collected.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 .. method:: socket.connect(address)
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 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	503 address family --- see above.)
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506 .. method:: socket.connect_ex(address)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 Like ``connect(address)``, but return an error indicator instead of raising an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 exception for errors returned by the C-level :cfunc:`connect` call (other
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 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	511 indicator is ``0`` if the operation succeeded, otherwise the value of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 :cdata:`errno` variable. This is useful to support, for example, asynchronous
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 connects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 .. method:: socket.fileno()
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 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	519 :func:`select.select`.
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 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	522 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	523 this limitation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526 .. method:: socket.getpeername()
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 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	529 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	530 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	531 systems this function is not supported.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534 .. method:: socket.getsockname()
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 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	537 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	538 the address family --- see above.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539
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 .. method:: socket.getsockopt(level, optname[, buflen])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 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	544 :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	545 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	546 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	547 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	548 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	549 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	550 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	551
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	552
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	553 .. method:: socket.ioctl(control, option)
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	554
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	555 :platform: Windows
93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	556
44742 14d4104976fc Merged revisions 59985-60000,60002,60005-60007,60009-60042 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44568 diff changeset	557 The :meth:`ioctl` method is a limited interface to the WSAIoctl system
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	558 interface. Please refer to the MSDN documentation for more information.
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	559
42604 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 .. method:: socket.listen(backlog)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 Listen for connections made to the socket. The backlog argument specifies the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564 maximum number of queued connections and should be at least 1; the maximum value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 is system-dependent (usually 5).
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 .. method:: socket.makefile([mode[, bufsize]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570 .. index:: single: I/O control; buffering
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 Return a :dfn:`file object` associated with the socket. (File objects are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 described in :ref:`bltin-file-objects`.) The file object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574 references a :cfunc:`dup`\ ped version of the socket file descriptor, so the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 file object and socket object may be closed or garbage-collected independently.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 The socket must be in blocking mode (it can not have a timeout). The optional
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 mode and bufsize arguments are interpreted the same way as by the built-in
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44115 diff changeset	578 :func:`file` function.
42604 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 .. method:: socket.recv(bufsize[, flags])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	583 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	584 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	585 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	586 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	587
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 .. note::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590 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	591 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	592
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594 .. method:: socket.recvfrom(bufsize[, flags])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	596 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	597 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	598 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	599 :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	600 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	601
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603 .. method:: socket.recvfrom_into(buffer[, nbytes[, flags]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	605 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	606 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	607 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	608 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	609 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	610 depends on the address family --- see above.)
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.recv_into(buffer[, nbytes[, flags]])
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 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	616 rather than creating a new bytestring. If nbytes is not specified (or 0),
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617 receive up to the size available in the given buffer. See the Unix manual page
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618 :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	619 to zero.
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
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	622 .. method:: socket.send(bytes[, flags])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624 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	625 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	626 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	627 all data has been sent; if only some of the data was transmitted, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628 application needs to attempt delivery of the remaining data.
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
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	631 .. method:: socket.sendall(bytes[, flags])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 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	634 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	635 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	636 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	637 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	638 much data, if any, was successfully sent.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	641 .. method:: socket.sendto(bytes[, flags], address)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 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	644 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	645 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	646 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	647 above.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 .. method:: socket.setblocking(flag)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 Set blocking or non-blocking mode of the socket: if flag is 0, the socket is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 set to non-blocking, else to blocking mode. Initially all sockets are in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 blocking mode. In non-blocking mode, if a :meth:`recv` call doesn't find any
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 data, or if a :meth:`send` call can't immediately dispose of the data, a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 :exc:`error` exception is raised; in blocking mode, the calls block until they
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0)``;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 ``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659
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 .. method:: socket.settimeout(value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 Set a timeout on blocking socket operations. The value argument can be a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664 nonnegative float expressing seconds, or ``None``. If a float is given,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 subsequent socket operations will raise an :exc:`timeout` exception if the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666 timeout period value has elapsed before the operation has completed. Setting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667 a timeout of ``None`` disables timeouts on socket operations.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668 ``s.settimeout(0.0)`` is equivalent to ``s.setblocking(0)``;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 ``s.settimeout(None)`` is equivalent to ``s.setblocking(1)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672 .. method:: socket.gettimeout()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 Return the timeout in floating seconds associated with socket operations, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 ``None`` if no timeout is set. This reflects the last call to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676 :meth:`setblocking` or :meth:`settimeout`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 Some notes on socket blocking and timeouts: A socket object can be in one of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 three modes: blocking, non-blocking, or timeout. Sockets are always created in
51712 8a292543e871 merge socket module documentation update from trunk r69731. Gregory P. Smith <greg@mad-scientist.com> parents: 50571 diff changeset	681 blocking mode. In blocking mode, operations block until complete or
8a292543e871 merge socket module documentation update from trunk r69731. Gregory P. Smith <greg@mad-scientist.com> parents: 50571 diff changeset	682 the system returns an error (such as connection timed out). In
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683 non-blocking mode, operations fail (with an error that is unfortunately
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 system-dependent) if they cannot be completed immediately. In timeout mode,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685 operations fail if they cannot be completed within the timeout specified for the
51712 8a292543e871 merge socket module documentation update from trunk r69731. Gregory P. Smith <greg@mad-scientist.com> parents: 50571 diff changeset	686 socket or if the system returns an error. The :meth:`setblocking` method is simply
8a292543e871 merge socket module documentation update from trunk r69731. Gregory P. Smith <greg@mad-scientist.com> parents: 50571 diff changeset	687 a shorthand for certain :meth:`settimeout` calls.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689 Timeout mode internally sets the socket in non-blocking mode. The blocking and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 timeout modes are shared between file descriptors and socket objects that refer
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691 to the same network endpoint. A consequence of this is that file objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692 returned by the :meth:`makefile` method must only be used when the socket is in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693 blocking mode; in timeout or non-blocking mode file operations that cannot be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694 completed immediately will fail.
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 Note that the :meth:`connect` operation is subject to the timeout setting, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697 in general it is recommended to call :meth:`settimeout` before calling
51712 8a292543e871 merge socket module documentation update from trunk r69731. Gregory P. Smith <greg@mad-scientist.com> parents: 50571 diff changeset	698 :meth:`connect` or pass a timeout parameter to :meth:`create_connection`.
8a292543e871 merge socket module documentation update from trunk r69731. Gregory P. Smith <greg@mad-scientist.com> parents: 50571 diff changeset	699 The system network stack may return a connection timeout error
8a292543e871 merge socket module documentation update from trunk r69731. Gregory P. Smith <greg@mad-scientist.com> parents: 50571 diff changeset	700 of its own regardless of any python socket timeout setting.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703 .. method:: socket.setsockopt(level, optname, value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 .. index:: module: struct
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707 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	708 :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	709 :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	710 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	711 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	712 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	713
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715 .. method:: socket.shutdown(how)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 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	718 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	719 are disallowed. If how is :const:`SHUT_RDWR`, further sends and receives are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720 disallowed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 Note that there are no methods :meth:`read` or :meth:`write`; use :meth:`recv`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 and :meth:`send` without flags argument instead.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 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	726 values given to the :class:`socket` constructor.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 .. attribute:: socket.family
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 The socket family.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 .. attribute:: socket.type
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736 The socket type.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739 .. attribute:: socket.proto
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 The socket protocol.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 .. _socket-example:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 Example
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 -------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 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	750 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	751 using it. Note that a server must perform the sequence :func:`socket`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 :meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 :meth:`accept` to service more than one client), while a client only needs the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 sequence :func:`socket`, :meth:`connect`. Also note that the server does not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 :meth:`send`/:meth:`recv` on the socket it is listening on but on the new
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 socket returned by :meth:`accept`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 The first two examples support IPv4 only. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 # Echo server program
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 import socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762
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	763 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	764 PORT = 50007 # Arbitrary non-privileged port
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 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	766 s.bind((HOST, PORT))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767 s.listen(1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 conn, addr = s.accept()
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	769 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	770 while True:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 data = conn.recv(1024)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 if not data: break
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 conn.send(data)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 conn.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 # Echo client program
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779 import socket
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 HOST = 'daring.cwi.nl' # The remote host
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 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	783 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	784 s.connect((HOST, PORT))
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	785 s.send(b'Hello, world')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 data = s.recv(1024)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 s.close()
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	788 print('Received', repr(data))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790 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	791 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	792 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	793 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	794 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	795 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	796
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 # Echo server program
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798 import socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799 import sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800
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	801 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	802 PORT = 50007 # Arbitrary non-privileged port
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803 s = None
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	804 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	805 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	806 af, socktype, proto, canonname, sa = res
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807 try:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	808 s = socket.socket(af, socktype, proto)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 except socket.error as msg:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	810 s = None
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	811 continue
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812 try:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	813 s.bind(sa)
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	814 s.listen(1)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815 except socket.error as msg:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	816 s.close()
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	817 s = None
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	818 continue
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819 break
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820 if s is None:
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	821 print('could not open socket')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822 sys.exit(1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823 conn, addr = s.accept()
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	824 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	825 while True:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826 data = conn.recv(1024)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827 if not data: break
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828 conn.send(data)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829 conn.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833 # Echo client program
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834 import socket
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	835 import sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	836
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	837 HOST = 'daring.cwi.nl' # The remote host
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 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	839 s = None
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840 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	841 af, socktype, proto, canonname, sa = res
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842 try:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	843 s = socket.socket(af, socktype, proto)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844 except socket.error as msg:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	845 s = None
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	846 continue
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847 try:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	848 s.connect(sa)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849 except socket.error as msg:
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	850 s.close()
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	851 s = None
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	852 continue
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 break
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854 if s is None:
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	855 print('could not open socket')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856 sys.exit(1)
48690 f1260f4311ee #3550: socket APIs use bytes, not strings. Georg Brandl <georg@python.org> parents: 47559 diff changeset	857 s.send(b'Hello, world')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 data = s.recv(1024)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859 s.close()
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	860 print('Received', repr(data))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	862
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	863 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	864 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	865 the interface::
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	866
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	867 import socket
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	868
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	869 # the public network interface
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	870 HOST = socket.gethostbyname(socket.gethostname())
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	871
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	872 # 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	873 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	874 s.bind((HOST, 0))
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	875
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	876 # Include IP headers
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	877 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	878
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	879 # receive all packages
420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	880 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	881
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	882 # 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	883 print(s.recvfrom(65565))
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49650 diff changeset	884
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	885 # disabled promiscuous mode
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	886 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/socket.rst @ 53750:310daa99d607