| 1 |
:mod:`!socket` --- Low-level networking interface |
| 2 |
================================================= |
| 3 |
|
| 4 |
.. module:: socket |
| 5 |
:synopsis: Low-level networking interface. |
| 6 |
|
| 7 |
**Source code:** :source:`Lib/socket.py` |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 11 |
This module provides access to the BSD *socket* interface. It is available on |
| 12 |
all modern Unix systems, Windows, MacOS, and probably additional platforms. |
| 13 |
|
| 14 |
.. note:: |
| 15 |
|
| 16 |
Some behavior may be platform dependent, since calls are made to the operating |
| 17 |
system socket APIs. |
| 18 |
|
| 19 |
|
| 20 |
.. include:: ../includes/wasm-notavail.rst |
| 21 |
|
| 22 |
.. index:: pair: object; socket |
| 23 |
|
| 24 |
The Python interface is a straightforward transliteration of the Unix system |
| 25 |
call and library interface for sockets to Python's object-oriented style: the |
| 26 |
:func:`~socket.socket` function returns a :dfn:`socket object` whose methods implement |
| 27 |
the various socket system calls. Parameter types are somewhat higher-level than |
| 28 |
in the C interface: as with :meth:`read` and :meth:`write` operations on Python |
| 29 |
files, buffer allocation on receive operations is automatic, and buffer length |
| 30 |
is implicit on send operations. |
| 31 |
|
| 32 |
|
| 33 |
.. seealso:: |
| 34 |
|
| 35 |
Module :mod:`socketserver` |
| 36 |
Classes that simplify writing network servers. |
| 37 |
|
| 38 |
Module :mod:`ssl` |
| 39 |
A TLS/SSL wrapper for socket objects. |
| 40 |
|
| 41 |
|
| 42 |
.. _socket-addresses: |
| 43 |
|
| 44 |
Socket families |
| 45 |
--------------- |
| 46 |
|
| 47 |
Depending on the system and the build options, various socket families |
| 48 |
are supported by this module. |
| 49 |
|
| 50 |
The address format required by a particular socket object is automatically |
| 51 |
selected based on the address family specified when the socket object was |
| 52 |
created. Socket addresses are represented as follows: |
| 53 |
|
| 54 |
- The address of an :const:`AF_UNIX` socket bound to a file system node |
| 55 |
is represented as a string, using the file system encoding and the |
| 56 |
``'surrogateescape'`` error handler (see :pep:`383`). An address in |
| 57 |
Linux's abstract namespace is returned as a :term:`bytes-like object` with |
| 58 |
an initial null byte; note that sockets in this namespace can |
| 59 |
communicate with normal file system sockets, so programs intended to |
| 60 |
run on Linux may need to deal with both types of address. A string or |
| 61 |
bytes-like object can be used for either type of address when |
| 62 |
passing it as an argument. |
| 63 |
|
| 64 |
.. versionchanged:: 3.3 |
| 65 |
Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8 |
| 66 |
encoding. |
| 67 |
|
| 68 |
.. versionchanged:: 3.5 |
| 69 |
Writable :term:`bytes-like object` is now accepted. |
| 70 |
|
| 71 |
.. _host_port: |
| 72 |
|
| 73 |
- A pair ``(host, port)`` is used for the :const:`AF_INET` address family, |
| 74 |
where *host* is a string representing either a hostname in internet domain |
| 75 |
notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``, |
| 76 |
and *port* is an integer. |
| 77 |
|
| 78 |
- For IPv4 addresses, two special forms are accepted instead of a host |
| 79 |
address: ``''`` represents :const:`INADDR_ANY`, which is used to bind to all |
| 80 |
interfaces, and the string ``'<broadcast>'`` represents |
| 81 |
:const:`INADDR_BROADCAST`. This behavior is not compatible with IPv6, |
| 82 |
therefore, you may want to avoid these if you intend to support IPv6 with your |
| 83 |
Python programs. |
| 84 |
|
| 85 |
- For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo, |
| 86 |
scope_id)`` is used, where *flowinfo* and *scope_id* represent the ``sin6_flowinfo`` |
| 87 |
and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C. For |
| 88 |
:mod:`!socket` module methods, *flowinfo* and *scope_id* can be omitted just for |
| 89 |
backward compatibility. Note, however, omission of *scope_id* can cause problems |
| 90 |
in manipulating scoped IPv6 addresses. |
| 91 |
|
| 92 |
.. versionchanged:: 3.7 |
| 93 |
For multicast addresses (with *scope_id* meaningful) *address* may not contain |
| 94 |
``%scope_id`` (or ``zone id``) part. This information is superfluous and may |
| 95 |
be safely omitted (recommended). |
| 96 |
|
| 97 |
- :const:`AF_NETLINK` sockets are represented as pairs ``(pid, groups)``. |
| 98 |
|
| 99 |
- Linux-only support for TIPC is available using the :const:`AF_TIPC` |
| 100 |
address family. TIPC is an open, non-IP based networked protocol designed |
| 101 |
for use in clustered computer environments. Addresses are represented by a |
| 102 |
tuple, and the fields depend on the address type. The general tuple form is |
| 103 |
``(addr_type, v1, v2, v3 [, scope])``, where: |
| 104 |
|
| 105 |
- *addr_type* is one of :const:`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`, |
| 106 |
or :const:`TIPC_ADDR_ID`. |
| 107 |
- *scope* is one of :const:`TIPC_ZONE_SCOPE`, :const:`TIPC_CLUSTER_SCOPE`, and |
| 108 |
:const:`TIPC_NODE_SCOPE`. |
| 109 |
- If *addr_type* is :const:`TIPC_ADDR_NAME`, then *v1* is the server type, *v2* is |
| 110 |
the port identifier, and *v3* should be 0. |
| 111 |
|
| 112 |
If *addr_type* is :const:`TIPC_ADDR_NAMESEQ`, then *v1* is the server type, *v2* |
| 113 |
is the lower port number, and *v3* is the upper port number. |
| 114 |
|
| 115 |
If *addr_type* is :const:`TIPC_ADDR_ID`, then *v1* is the node, *v2* is the |
| 116 |
reference, and *v3* should be set to 0. |
| 117 |
|
| 118 |
- A tuple ``(interface, )`` is used for the :const:`AF_CAN` address family, |
| 119 |
where *interface* is a string representing a network interface name like |
| 120 |
``'can0'``. The network interface name ``''`` can be used to receive packets |
| 121 |
from all network interfaces of this family. |
| 122 |
|
| 123 |
- :const:`CAN_ISOTP` protocol requires a tuple ``(interface, rx_addr, tx_addr)`` |
| 124 |
where both additional parameters are unsigned long integer that represent a |
| 125 |
CAN identifier (standard or extended). |
| 126 |
- :const:`CAN_J1939` protocol requires a tuple ``(interface, name, pgn, addr)`` |
| 127 |
where additional parameters are 64-bit unsigned integer representing the |
| 128 |
ECU name, a 32-bit unsigned integer representing the Parameter Group Number |
| 129 |
(PGN), and an 8-bit integer representing the address. |
| 130 |
|
| 131 |
- A string or a tuple ``(id, unit)`` is used for the :const:`SYSPROTO_CONTROL` |
| 132 |
protocol of the :const:`PF_SYSTEM` family. The string is the name of a |
| 133 |
kernel control using a dynamically assigned ID. The tuple can be used if ID |
| 134 |
and unit number of the kernel control are known or if a registered ID is |
| 135 |
used. |
| 136 |
|
| 137 |
.. versionadded:: 3.3 |
| 138 |
|
| 139 |
- :const:`AF_BLUETOOTH` supports the following protocols and address |
| 140 |
formats: |
| 141 |
|
| 142 |
- :const:`BTPROTO_L2CAP` accepts a tuple |
| 143 |
``(bdaddr, psm[, cid[, bdaddr_type]])`` where: |
| 144 |
|
| 145 |
- ``bdaddr`` is a string specifying the Bluetooth address. |
| 146 |
- ``psm`` is an integer specifying the Protocol/Service Multiplexer. |
| 147 |
- ``cid`` is an optional integer specifying the Channel Identifier. |
| 148 |
If not given, defaults to zero. |
| 149 |
- ``bdaddr_type`` is an optional integer specifying the address type; |
| 150 |
one of :const:`BDADDR_BREDR` (default), :const:`BDADDR_LE_PUBLIC`, |
| 151 |
:const:`BDADDR_LE_RANDOM`. |
| 152 |
|
| 153 |
.. versionchanged:: 3.14 |
| 154 |
Added ``cid`` and ``bdaddr_type`` fields. |
| 155 |
|
| 156 |
- :const:`BTPROTO_RFCOMM` accepts ``(bdaddr, channel)`` where ``bdaddr`` |
| 157 |
is the Bluetooth address as a string and ``channel`` is an integer. |
| 158 |
|
| 159 |
- :const:`BTPROTO_HCI` accepts a format that depends on your OS. |
| 160 |
|
| 161 |
- On Linux it accepts an integer ``device_id`` or a tuple |
| 162 |
``(device_id, [channel])`` where ``device_id`` |
| 163 |
specifies the number of the Bluetooth device, |
| 164 |
and ``channel`` is an optional integer specifying the HCI channel |
| 165 |
(:const:`HCI_CHANNEL_RAW` by default). |
| 166 |
- On FreeBSD, NetBSD and DragonFly BSD it accepts ``bdaddr`` |
| 167 |
where ``bdaddr`` is the Bluetooth address as a string. |
| 168 |
|
| 169 |
.. versionchanged:: 3.2 |
| 170 |
NetBSD and DragonFlyBSD support added. |
| 171 |
|
| 172 |
.. versionchanged:: 3.13.3 |
| 173 |
FreeBSD support added. |
| 174 |
|
| 175 |
.. versionchanged:: 3.14 |
| 176 |
Added ``channel`` field. |
| 177 |
``device_id`` not packed in a tuple is now accepted. |
| 178 |
|
| 179 |
- :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is |
| 180 |
the Bluetooth address as a string or a :class:`bytes` object. |
| 181 |
(ex. ``'12:23:34:45:56:67'`` or ``b'12:23:34:45:56:67'``) |
| 182 |
|
| 183 |
.. versionchanged:: 3.14 |
| 184 |
FreeBSD support added. |
| 185 |
|
| 186 |
- :const:`AF_ALG` is a Linux-only socket based interface to Kernel |
| 187 |
cryptography. An algorithm socket is configured with a tuple of two to four |
| 188 |
elements ``(type, name [, feat [, mask]])``, where: |
| 189 |
|
| 190 |
- *type* is the algorithm type as string, e.g. ``aead``, ``hash``, |
| 191 |
``skcipher`` or ``rng``. |
| 192 |
|
| 193 |
- *name* is the algorithm name and operation mode as string, e.g. |
| 194 |
``sha256``, ``hmac(sha256)``, ``cbc(aes)`` or ``drbg_nopr_ctr_aes256``. |
| 195 |
|
| 196 |
- *feat* and *mask* are unsigned 32bit integers. |
| 197 |
|
| 198 |
.. availability:: Linux >= 2.6.38. |
| 199 |
|
| 200 |
Some algorithm types require more recent Kernels. |
| 201 |
|
| 202 |
.. versionadded:: 3.6 |
| 203 |
|
| 204 |
- :const:`AF_VSOCK` allows communication between virtual machines and |
| 205 |
their hosts. The sockets are represented as a ``(CID, port)`` tuple |
| 206 |
where the context ID or CID and port are integers. |
| 207 |
|
| 208 |
.. availability:: Linux >= 3.9 |
| 209 |
|
| 210 |
See :manpage:`vsock(7)` |
| 211 |
|
| 212 |
.. versionadded:: 3.7 |
| 213 |
|
| 214 |
- :const:`AF_PACKET` is a low-level interface directly to network devices. |
| 215 |
The addresses are represented by the tuple |
| 216 |
``(ifname, proto[, pkttype[, hatype[, addr]]])`` where: |
| 217 |
|
| 218 |
- *ifname* - String specifying the device name. |
| 219 |
- *proto* - The Ethernet protocol number. |
| 220 |
May be :data:`ETH_P_ALL` to capture all protocols, |
| 221 |
one of the :ref:`ETHERTYPE_* constants <socket-ethernet-types>` |
| 222 |
or any other Ethernet protocol number. |
| 223 |
- *pkttype* - Optional integer specifying the packet type: |
| 224 |
|
| 225 |
- ``PACKET_HOST`` (the default) - Packet addressed to the local host. |
| 226 |
- ``PACKET_BROADCAST`` - Physical-layer broadcast packet. |
| 227 |
- ``PACKET_MULTICAST`` - Packet sent to a physical-layer multicast address. |
| 228 |
- ``PACKET_OTHERHOST`` - Packet to some other host that has been caught by |
| 229 |
a device driver in promiscuous mode. |
| 230 |
- ``PACKET_OUTGOING`` - Packet originating from the local host that is |
| 231 |
looped back to a packet socket. |
| 232 |
- *hatype* - Optional integer specifying the ARP hardware address type. |
| 233 |
- *addr* - Optional bytes-like object specifying the hardware physical |
| 234 |
address, whose interpretation depends on the device. |
| 235 |
|
| 236 |
.. availability:: Linux >= 2.2. |
| 237 |
|
| 238 |
- :const:`AF_QIPCRTR` is a Linux-only socket based interface for communicating |
| 239 |
with services running on co-processors in Qualcomm platforms. The address |
| 240 |
family is represented as a ``(node, port)`` tuple where the *node* and *port* |
| 241 |
are non-negative integers. |
| 242 |
|
| 243 |
.. availability:: Linux >= 4.7. |
| 244 |
|
| 245 |
.. versionadded:: 3.8 |
| 246 |
|
| 247 |
- :const:`IPPROTO_UDPLITE` is a variant of UDP which allows you to specify |
| 248 |
what portion of a packet is covered with the checksum. It adds two socket |
| 249 |
options that you can change. |
| 250 |
``self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length)`` will |
| 251 |
change what portion of outgoing packets are covered by the checksum and |
| 252 |
``self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length)`` will |
| 253 |
filter out packets which cover too little of their data. In both cases |
| 254 |
``length`` should be in ``range(8, 2**16, 8)``. |
| 255 |
|
| 256 |
Such a socket should be constructed with |
| 257 |
``socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE)`` for IPv4 or |
| 258 |
``socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE)`` for IPv6. |
| 259 |
|
| 260 |
.. availability:: Linux >= 2.6.20, FreeBSD >= 10.1 |
| 261 |
|
| 262 |
.. versionadded:: 3.9 |
| 263 |
|
| 264 |
- :const:`AF_HYPERV` is a Windows-only socket based interface for communicating |
| 265 |
with Hyper-V hosts and guests. The address family is represented as a |
| 266 |
``(vm_id, service_id)`` tuple where the ``vm_id`` and ``service_id`` are |
| 267 |
UUID strings. |
| 268 |
|
| 269 |
The ``vm_id`` is the virtual machine identifier or a set of known VMID values |
| 270 |
if the target is not a specific virtual machine. Known VMID constants |
| 271 |
defined on ``socket`` are: |
| 272 |
|
| 273 |
- ``HV_GUID_ZERO`` |
| 274 |
- ``HV_GUID_BROADCAST`` |
| 275 |
- ``HV_GUID_WILDCARD`` - Used to bind on itself and accept connections from |
| 276 |
all partitions. |
| 277 |
- ``HV_GUID_CHILDREN`` - Used to bind on itself and accept connection from |
| 278 |
child partitions. |
| 279 |
- ``HV_GUID_LOOPBACK`` - Used as a target to itself. |
| 280 |
- ``HV_GUID_PARENT`` - When used as a bind accepts connection from the parent |
| 281 |
partition. When used as an address target it will connect to the parent partition. |
| 282 |
|
| 283 |
The ``service_id`` is the service identifier of the registered service. |
| 284 |
|
| 285 |
.. versionadded:: 3.12 |
| 286 |
|
| 287 |
If you use a hostname in the *host* portion of IPv4/v6 socket address, the |
| 288 |
program may show a nondeterministic behavior, as Python uses the first address |
| 289 |
returned from the DNS resolution. The socket address will be resolved |
| 290 |
differently into an actual IPv4/v6 address, depending on the results from DNS |
| 291 |
resolution and/or the host configuration. For deterministic behavior use a |
| 292 |
numeric address in *host* portion. |
| 293 |
|
| 294 |
All errors raise exceptions. The normal exceptions for invalid argument types |
| 295 |
and out-of-memory conditions can be raised. Errors |
| 296 |
related to socket or address semantics raise :exc:`OSError` or one of its |
| 297 |
subclasses. |
| 298 |
|
| 299 |
Non-blocking mode is supported through :meth:`~socket.setblocking`. A |
| 300 |
generalization of this based on timeouts is supported through |
| 301 |
:meth:`~socket.settimeout`. |
| 302 |
|
| 303 |
|
| 304 |
Module contents |
| 305 |
--------------- |
| 306 |
|
| 307 |
The module :mod:`!socket` exports the following elements. |
| 308 |
|
| 309 |
|
| 310 |
Exceptions |
| 311 |
^^^^^^^^^^ |
| 312 |
|
| 313 |
.. exception:: error |
| 314 |
|
| 315 |
A deprecated alias of :exc:`OSError`. |
| 316 |
|
| 317 |
.. versionchanged:: 3.3 |
| 318 |
Following :pep:`3151`, this class was made an alias of :exc:`OSError`. |
| 319 |
|
| 320 |
|
| 321 |
.. exception:: herror |
| 322 |
|
| 323 |
A subclass of :exc:`OSError`, this exception is raised for |
| 324 |
address-related errors, i.e. for functions that use *h_errno* in the POSIX |
| 325 |
C API, including :func:`gethostbyname_ex` and :func:`gethostbyaddr`. |
| 326 |
The accompanying value is a pair ``(h_errno, string)`` representing an |
| 327 |
error returned by a library call. *h_errno* is a numeric value, while |
| 328 |
*string* represents the description of *h_errno*, as returned by the |
| 329 |
:c:func:`hstrerror` C function. |
| 330 |
|
| 331 |
.. versionchanged:: 3.3 |
| 332 |
This class was made a subclass of :exc:`OSError`. |
| 333 |
|
| 334 |
.. exception:: gaierror |
| 335 |
|
| 336 |
A subclass of :exc:`OSError`, this exception is raised for |
| 337 |
address-related errors by :func:`getaddrinfo` and :func:`getnameinfo`. |
| 338 |
The accompanying value is a pair ``(error, string)`` representing an error |
| 339 |
returned by a library call. *string* represents the description of |
| 340 |
*error*, as returned by the :c:func:`gai_strerror` C function. The |
| 341 |
numeric *error* value will match one of the :const:`!EAI_\*` constants |
| 342 |
defined in this module. |
| 343 |
|
| 344 |
.. versionchanged:: 3.3 |
| 345 |
This class was made a subclass of :exc:`OSError`. |
| 346 |
|
| 347 |
.. exception:: timeout |
| 348 |
|
| 349 |
A deprecated alias of :exc:`TimeoutError`. |
| 350 |
|
| 351 |
A subclass of :exc:`OSError`, this exception is raised when a timeout |
| 352 |
occurs on a socket which has had timeouts enabled via a prior call to |
| 353 |
:meth:`~socket.settimeout` (or implicitly through |
| 354 |
:func:`~socket.setdefaulttimeout`). The accompanying value is a string |
| 355 |
whose value is currently always "timed out". |
| 356 |
|
| 357 |
.. versionchanged:: 3.3 |
| 358 |
This class was made a subclass of :exc:`OSError`. |
| 359 |
|
| 360 |
.. versionchanged:: 3.10 |
| 361 |
This class was made an alias of :exc:`TimeoutError`. |
| 362 |
|
| 363 |
|
| 364 |
Constants |
| 365 |
^^^^^^^^^ |
| 366 |
|
| 367 |
The AF_* and SOCK_* constants are now :class:`AddressFamily` and |
| 368 |
:class:`SocketKind` :class:`.IntEnum` collections. |
| 369 |
|
| 370 |
.. versionadded:: 3.4 |
| 371 |
|
| 372 |
.. data:: AF_UNIX |
| 373 |
AF_INET |
| 374 |
AF_INET6 |
| 375 |
|
| 376 |
These constants represent the address (and protocol) families, used for the |
| 377 |
first argument to :func:`~socket.socket`. If the :const:`AF_UNIX` constant is not |
| 378 |
defined then this protocol is unsupported. More constants may be available |
| 379 |
depending on the system. |
| 380 |
|
| 381 |
.. data:: AF_UNSPEC |
| 382 |
|
| 383 |
:const:`AF_UNSPEC` means that |
| 384 |
:func:`getaddrinfo` should return socket addresses for any |
| 385 |
address family (either IPv4, IPv6, or any other) that can be used. |
| 386 |
|
| 387 |
.. data:: SOCK_STREAM |
| 388 |
SOCK_DGRAM |
| 389 |
SOCK_RAW |
| 390 |
SOCK_RDM |
| 391 |
SOCK_SEQPACKET |
| 392 |
|
| 393 |
These constants represent the socket types, used for the second argument to |
| 394 |
:func:`~socket.socket`. More constants may be available depending on the system. |
| 395 |
(Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be generally |
| 396 |
useful.) |
| 397 |
|
| 398 |
.. data:: SOCK_CLOEXEC |
| 399 |
SOCK_NONBLOCK |
| 400 |
|
| 401 |
These two constants, if defined, can be combined with the socket types and |
| 402 |
allow you to set some flags atomically (thus avoiding possible race |
| 403 |
conditions and the need for separate calls). |
| 404 |
|
| 405 |
.. seealso:: |
| 406 |
|
| 407 |
`Secure File Descriptor Handling <https://udrepper.livejournal.com/20407.html>`_ |
| 408 |
for a more thorough explanation. |
| 409 |
|
| 410 |
.. availability:: Linux >= 2.6.27. |
| 411 |
|
| 412 |
.. versionadded:: 3.2 |
| 413 |
|
| 414 |
.. _socket-unix-constants: |
| 415 |
|
| 416 |
.. data:: SO_* |
| 417 |
SOMAXCONN |
| 418 |
MSG_* |
| 419 |
SOL_* |
| 420 |
SCM_* |
| 421 |
IPPROTO_* |
| 422 |
IPPORT_* |
| 423 |
INADDR_* |
| 424 |
IP_* |
| 425 |
IPV6_* |
| 426 |
EAI_* |
| 427 |
AI_* |
| 428 |
NI_* |
| 429 |
TCP_* |
| 430 |
|
| 431 |
Many constants of these forms, documented in the Unix documentation on sockets |
| 432 |
and/or the IP protocol, are also defined in the socket module. They are |
| 433 |
generally used in arguments to the :meth:`~socket.setsockopt` and :meth:`~socket.getsockopt` |
| 434 |
methods of socket objects. In most cases, only those symbols that are defined |
| 435 |
in the Unix header files are defined; for a few symbols, default values are |
| 436 |
provided. |
| 437 |
|
| 438 |
.. versionchanged:: 3.6 |
| 439 |
``SO_DOMAIN``, ``SO_PROTOCOL``, ``SO_PEERSEC``, ``SO_PASSSEC``, |
| 440 |
``TCP_USER_TIMEOUT``, ``TCP_CONGESTION`` were added. |
| 441 |
|
| 442 |
.. versionchanged:: 3.6.5 |
| 443 |
Added support for ``TCP_FASTOPEN``, ``TCP_KEEPCNT`` on Windows platforms |
| 444 |
when available. |
| 445 |
|
| 446 |
.. versionchanged:: 3.7 |
| 447 |
``TCP_NOTSENT_LOWAT`` was added. |
| 448 |
|
| 449 |
Added support for ``TCP_KEEPIDLE``, ``TCP_KEEPINTVL`` on Windows platforms |
| 450 |
when available. |
| 451 |
|
| 452 |
.. versionchanged:: 3.10 |
| 453 |
``IP_RECVTOS`` was added. |
| 454 |
Added ``TCP_KEEPALIVE``. On MacOS this constant can be used in the same |
| 455 |
way that ``TCP_KEEPIDLE`` is used on Linux. |
| 456 |
|
| 457 |
.. versionchanged:: 3.11 |
| 458 |
Added ``TCP_CONNECTION_INFO``. On MacOS this constant can be used in the |
| 459 |
same way that ``TCP_INFO`` is used on Linux and BSD. |
| 460 |
|
| 461 |
.. versionchanged:: 3.12 |
| 462 |
Added ``SO_RTABLE`` and ``SO_USER_COOKIE``. On OpenBSD |
| 463 |
and FreeBSD respectively those constants can be used in the same way that |
| 464 |
``SO_MARK`` is used on Linux. Also added missing TCP socket options from |
| 465 |
Linux: ``TCP_MD5SIG``, ``TCP_THIN_LINEAR_TIMEOUTS``, ``TCP_THIN_DUPACK``, |
| 466 |
``TCP_REPAIR``, ``TCP_REPAIR_QUEUE``, ``TCP_QUEUE_SEQ``, |
| 467 |
``TCP_REPAIR_OPTIONS``, ``TCP_TIMESTAMP``, ``TCP_CC_INFO``, |
| 468 |
``TCP_SAVE_SYN``, ``TCP_SAVED_SYN``, ``TCP_REPAIR_WINDOW``, |
| 469 |
``TCP_FASTOPEN_CONNECT``, ``TCP_ULP``, ``TCP_MD5SIG_EXT``, |
| 470 |
``TCP_FASTOPEN_KEY``, ``TCP_FASTOPEN_NO_COOKIE``, |
| 471 |
``TCP_ZEROCOPY_RECEIVE``, ``TCP_INQ``, ``TCP_TX_DELAY``. |
| 472 |
Added ``IP_PKTINFO``, ``IP_UNBLOCK_SOURCE``, ``IP_BLOCK_SOURCE``, |
| 473 |
``IP_ADD_SOURCE_MEMBERSHIP``, ``IP_DROP_SOURCE_MEMBERSHIP``. |
| 474 |
|
| 475 |
.. versionchanged:: 3.13 |
| 476 |
Added ``SO_BINDTOIFINDEX``. On Linux this constant can be used in the |
| 477 |
same way that ``SO_BINDTODEVICE`` is used, but with the index of a |
| 478 |
network interface instead of its name. |
| 479 |
|
| 480 |
.. versionchanged:: 3.14 |
| 481 |
Added missing ``IP_FREEBIND``, ``IP_RECVERR``, ``IPV6_RECVERR``, |
| 482 |
``IP_RECVTTL``, and ``IP_RECVORIGDSTADDR`` on Linux. |
| 483 |
|
| 484 |
.. versionchanged:: 3.14 |
| 485 |
Added support for ``TCP_QUICKACK`` on Windows platforms when available. |
| 486 |
|
| 487 |
|
| 488 |
.. data:: AF_CAN |
| 489 |
PF_CAN |
| 490 |
SOL_CAN_* |
| 491 |
CAN_* |
| 492 |
|
| 493 |
Many constants of these forms, documented in the Linux documentation, are |
| 494 |
also defined in the socket module. |
| 495 |
|
| 496 |
.. availability:: Linux >= 2.6.25, NetBSD >= 8. |
| 497 |
|
| 498 |
.. versionadded:: 3.3 |
| 499 |
|
| 500 |
.. versionchanged:: 3.11 |
| 501 |
NetBSD support was added. |
| 502 |
|
| 503 |
.. versionchanged:: 3.14 |
| 504 |
Restored missing ``CAN_RAW_ERR_FILTER`` on Linux. |
| 505 |
|
| 506 |
.. data:: CAN_BCM |
| 507 |
CAN_BCM_* |
| 508 |
|
| 509 |
CAN_BCM, in the CAN protocol family, is the broadcast manager (BCM) protocol. |
| 510 |
Broadcast manager constants, documented in the Linux documentation, are also |
| 511 |
defined in the socket module. |
| 512 |
|
| 513 |
.. availability:: Linux >= 2.6.25. |
| 514 |
|
| 515 |
.. note:: |
| 516 |
The :data:`CAN_BCM_CAN_FD_FRAME` flag is only available on Linux >= 4.8. |
| 517 |
|
| 518 |
.. versionadded:: 3.4 |
| 519 |
|
| 520 |
.. data:: CAN_RAW_FD_FRAMES |
| 521 |
|
| 522 |
Enables CAN FD support in a CAN_RAW socket. This is disabled by default. |
| 523 |
This allows your application to send both CAN and CAN FD frames; however, |
| 524 |
you must accept both CAN and CAN FD frames when reading from the socket. |
| 525 |
|
| 526 |
This constant is documented in the Linux documentation. |
| 527 |
|
| 528 |
.. availability:: Linux >= 3.6. |
| 529 |
|
| 530 |
.. versionadded:: 3.5 |
| 531 |
|
| 532 |
.. data:: CAN_RAW_JOIN_FILTERS |
| 533 |
|
| 534 |
Joins the applied CAN filters such that only CAN frames that match all |
| 535 |
given CAN filters are passed to user space. |
| 536 |
|
| 537 |
This constant is documented in the Linux documentation. |
| 538 |
|
| 539 |
.. availability:: Linux >= 4.1. |
| 540 |
|
| 541 |
.. versionadded:: 3.9 |
| 542 |
|
| 543 |
.. data:: CAN_ISOTP |
| 544 |
|
| 545 |
CAN_ISOTP, in the CAN protocol family, is the ISO-TP (ISO 15765-2) protocol. |
| 546 |
ISO-TP constants, documented in the Linux documentation. |
| 547 |
|
| 548 |
.. availability:: Linux >= 2.6.25. |
| 549 |
|
| 550 |
.. versionadded:: 3.7 |
| 551 |
|
| 552 |
.. data:: CAN_J1939 |
| 553 |
|
| 554 |
CAN_J1939, in the CAN protocol family, is the SAE J1939 protocol. |
| 555 |
J1939 constants, documented in the Linux documentation. |
| 556 |
|
| 557 |
.. availability:: Linux >= 5.4. |
| 558 |
|
| 559 |
.. versionadded:: 3.9 |
| 560 |
|
| 561 |
|
| 562 |
.. data:: AF_DIVERT |
| 563 |
PF_DIVERT |
| 564 |
|
| 565 |
These two constants, documented in the FreeBSD divert(4) manual page, are |
| 566 |
also defined in the socket module. |
| 567 |
|
| 568 |
.. availability:: FreeBSD >= 14.0. |
| 569 |
|
| 570 |
.. versionadded:: 3.12 |
| 571 |
|
| 572 |
|
| 573 |
.. data:: AF_PACKET |
| 574 |
PF_PACKET |
| 575 |
PACKET_* |
| 576 |
|
| 577 |
Many constants of these forms, documented in the Linux documentation, are |
| 578 |
also defined in the socket module. |
| 579 |
|
| 580 |
.. availability:: Linux >= 2.2. |
| 581 |
|
| 582 |
|
| 583 |
.. data:: ETH_P_ALL |
| 584 |
|
| 585 |
:data:`!ETH_P_ALL` can be used in the :class:`~socket.socket` |
| 586 |
constructor as *proto* for the :const:`AF_PACKET` family in order to |
| 587 |
capture every packet, regardless of protocol. |
| 588 |
|
| 589 |
For more information, see the :manpage:`packet(7)` manpage. |
| 590 |
|
| 591 |
.. availability:: Linux. |
| 592 |
|
| 593 |
.. versionadded:: 3.12 |
| 594 |
|
| 595 |
|
| 596 |
.. data:: AF_RDS |
| 597 |
PF_RDS |
| 598 |
SOL_RDS |
| 599 |
RDS_* |
| 600 |
|
| 601 |
Many constants of these forms, documented in the Linux documentation, are |
| 602 |
also defined in the socket module. |
| 603 |
|
| 604 |
.. availability:: Linux >= 2.6.30. |
| 605 |
|
| 606 |
.. versionadded:: 3.3 |
| 607 |
|
| 608 |
|
| 609 |
.. data:: SIO_RCVALL |
| 610 |
SIO_KEEPALIVE_VALS |
| 611 |
SIO_LOOPBACK_FAST_PATH |
| 612 |
RCVALL_* |
| 613 |
|
| 614 |
Constants for Windows' WSAIoctl(). The constants are used as arguments to the |
| 615 |
:meth:`~socket.socket.ioctl` method of socket objects. |
| 616 |
|
| 617 |
.. versionchanged:: 3.6 |
| 618 |
``SIO_LOOPBACK_FAST_PATH`` was added. |
| 619 |
|
| 620 |
|
| 621 |
.. data:: TIPC_* |
| 622 |
|
| 623 |
TIPC related constants, matching the ones exported by the C socket API. See |
| 624 |
the TIPC documentation for more information. |
| 625 |
|
| 626 |
.. data:: AF_ALG |
| 627 |
SOL_ALG |
| 628 |
ALG_* |
| 629 |
|
| 630 |
Constants for Linux Kernel cryptography. |
| 631 |
|
| 632 |
.. availability:: Linux >= 2.6.38. |
| 633 |
|
| 634 |
.. versionadded:: 3.6 |
| 635 |
|
| 636 |
|
| 637 |
.. data:: AF_VSOCK |
| 638 |
IOCTL_VM_SOCKETS_GET_LOCAL_CID |
| 639 |
VMADDR* |
| 640 |
SO_VM* |
| 641 |
|
| 642 |
Constants for Linux host/guest communication. |
| 643 |
|
| 644 |
.. availability:: Linux >= 4.8. |
| 645 |
|
| 646 |
.. versionadded:: 3.7 |
| 647 |
|
| 648 |
.. data:: AF_LINK |
| 649 |
|
| 650 |
.. availability:: BSD, macOS. |
| 651 |
|
| 652 |
.. versionadded:: 3.4 |
| 653 |
|
| 654 |
.. data:: has_ipv6 |
| 655 |
|
| 656 |
This constant contains a boolean value which indicates if IPv6 is supported on |
| 657 |
this platform. |
| 658 |
|
| 659 |
.. data:: AF_BLUETOOTH |
| 660 |
BTPROTO_L2CAP |
| 661 |
BTPROTO_RFCOMM |
| 662 |
BTPROTO_HCI |
| 663 |
BTPROTO_SCO |
| 664 |
|
| 665 |
Integer constants for use with Bluetooth addresses. |
| 666 |
|
| 667 |
.. data:: BDADDR_ANY |
| 668 |
BDADDR_LOCAL |
| 669 |
|
| 670 |
These are string constants containing Bluetooth addresses with special |
| 671 |
meanings. For example, :const:`BDADDR_ANY` can be used to indicate |
| 672 |
any address when specifying the binding socket with |
| 673 |
:const:`BTPROTO_RFCOMM`. |
| 674 |
|
| 675 |
.. data:: BDADDR_BREDR |
| 676 |
BDADDR_LE_PUBLIC |
| 677 |
BDADDR_LE_RANDOM |
| 678 |
|
| 679 |
These constants describe the Bluetooth address type when binding or |
| 680 |
connecting a :const:`BTPROTO_L2CAP` socket. |
| 681 |
|
| 682 |
.. availability:: Linux, FreeBSD |
| 683 |
|
| 684 |
.. versionadded:: 3.14 |
| 685 |
|
| 686 |
.. data:: SOL_RFCOMM |
| 687 |
SOL_L2CAP |
| 688 |
SOL_HCI |
| 689 |
SOL_SCO |
| 690 |
SOL_BLUETOOTH |
| 691 |
|
| 692 |
Used in the level argument to the :meth:`~socket.setsockopt` and |
| 693 |
:meth:`~socket.getsockopt` methods of Bluetooth socket objects. |
| 694 |
|
| 695 |
:const:`SOL_BLUETOOTH` is only available on Linux. Other constants |
| 696 |
are available if the corresponding protocol is supported. |
| 697 |
|
| 698 |
.. data:: SO_L2CAP_* |
| 699 |
L2CAP_LM |
| 700 |
L2CAP_LM_* |
| 701 |
SO_RFCOMM_* |
| 702 |
RFCOMM_LM_* |
| 703 |
SO_SCO_* |
| 704 |
SO_BTH_* |
| 705 |
BT_* |
| 706 |
|
| 707 |
Used in the option name and value argument to the :meth:`~socket.setsockopt` |
| 708 |
and :meth:`~socket.getsockopt` methods of Bluetooth socket objects. |
| 709 |
|
| 710 |
:const:`!BT_*` and :const:`L2CAP_LM` are only available on Linux. |
| 711 |
:const:`!SO_BTH_*` are only available on Windows. |
| 712 |
Other constants may be available on Linux and various BSD platforms. |
| 713 |
|
| 714 |
.. versionadded:: 3.14 |
| 715 |
|
| 716 |
.. data:: HCI_FILTER |
| 717 |
HCI_TIME_STAMP |
| 718 |
HCI_DATA_DIR |
| 719 |
SO_HCI_EVT_FILTER |
| 720 |
SO_HCI_PKT_FILTER |
| 721 |
|
| 722 |
Option names for use with :const:`BTPROTO_HCI`. |
| 723 |
Availability and format of the option values depend on platform. |
| 724 |
|
| 725 |
.. versionchanged:: 3.14 |
| 726 |
Added :const:`!SO_HCI_EVT_FILTER` and :const:`!SO_HCI_PKT_FILTER` |
| 727 |
on NetBSD and DragonFly BSD. |
| 728 |
Added :const:`!HCI_DATA_DIR` on FreeBSD, NetBSD and DragonFly BSD. |
| 729 |
|
| 730 |
.. data:: HCI_DEV_NONE |
| 731 |
|
| 732 |
The ``device_id`` value used to create an HCI socket that isn't specific |
| 733 |
to a single Bluetooth adapter. |
| 734 |
|
| 735 |
.. availability:: Linux |
| 736 |
|
| 737 |
.. versionadded:: 3.14 |
| 738 |
|
| 739 |
.. data:: HCI_CHANNEL_RAW |
| 740 |
HCI_CHANNEL_USER |
| 741 |
HCI_CHANNEL_MONITOR |
| 742 |
HCI_CHANNEL_CONTROL |
| 743 |
HCI_CHANNEL_LOGGING |
| 744 |
|
| 745 |
Possible values for ``channel`` field in the :const:`BTPROTO_HCI` address. |
| 746 |
|
| 747 |
.. availability:: Linux |
| 748 |
|
| 749 |
.. versionadded:: 3.14 |
| 750 |
|
| 751 |
.. data:: AF_QIPCRTR |
| 752 |
|
| 753 |
Constant for Qualcomm's IPC router protocol, used to communicate with |
| 754 |
service providing remote processors. |
| 755 |
|
| 756 |
.. availability:: Linux >= 4.7. |
| 757 |
|
| 758 |
.. data:: SCM_CREDS2 |
| 759 |
LOCAL_CREDS |
| 760 |
LOCAL_CREDS_PERSISTENT |
| 761 |
|
| 762 |
LOCAL_CREDS and LOCAL_CREDS_PERSISTENT can be used |
| 763 |
with SOCK_DGRAM, SOCK_STREAM sockets, equivalent to |
| 764 |
Linux/DragonFlyBSD SO_PASSCRED, while LOCAL_CREDS |
| 765 |
sends the credentials at first read, LOCAL_CREDS_PERSISTENT |
| 766 |
sends for each read, SCM_CREDS2 must be then used for |
| 767 |
the latter for the message type. |
| 768 |
|
| 769 |
.. versionadded:: 3.11 |
| 770 |
|
| 771 |
.. availability:: FreeBSD. |
| 772 |
|
| 773 |
.. data:: SO_INCOMING_CPU |
| 774 |
|
| 775 |
Constant to optimize CPU locality, to be used in conjunction with |
| 776 |
:data:`SO_REUSEPORT`. |
| 777 |
|
| 778 |
.. versionadded:: 3.11 |
| 779 |
|
| 780 |
.. availability:: Linux >= 3.9 |
| 781 |
|
| 782 |
.. data:: SO_REUSEPORT_LB |
| 783 |
|
| 784 |
Constant to enable duplicate address and port bindings with load balancing. |
| 785 |
|
| 786 |
.. versionadded:: 3.14 |
| 787 |
|
| 788 |
.. availability:: FreeBSD >= 12.0 |
| 789 |
|
| 790 |
.. data:: AF_HYPERV |
| 791 |
HV_PROTOCOL_RAW |
| 792 |
HVSOCKET_CONNECT_TIMEOUT |
| 793 |
HVSOCKET_CONNECT_TIMEOUT_MAX |
| 794 |
HVSOCKET_CONNECTED_SUSPEND |
| 795 |
HVSOCKET_ADDRESS_FLAG_PASSTHRU |
| 796 |
HV_GUID_ZERO |
| 797 |
HV_GUID_WILDCARD |
| 798 |
HV_GUID_BROADCAST |
| 799 |
HV_GUID_CHILDREN |
| 800 |
HV_GUID_LOOPBACK |
| 801 |
HV_GUID_PARENT |
| 802 |
|
| 803 |
Constants for Windows Hyper-V sockets for host/guest communications. |
| 804 |
|
| 805 |
.. availability:: Windows. |
| 806 |
|
| 807 |
.. versionadded:: 3.12 |
| 808 |
|
| 809 |
.. _socket-ethernet-types: |
| 810 |
|
| 811 |
.. data:: ETHERTYPE_ARP |
| 812 |
ETHERTYPE_IP |
| 813 |
ETHERTYPE_IPV6 |
| 814 |
ETHERTYPE_VLAN |
| 815 |
|
| 816 |
`IEEE 802.3 protocol number |
| 817 |
<https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.txt>`_. |
| 818 |
constants. |
| 819 |
|
| 820 |
.. availability:: Linux, FreeBSD, macOS. |
| 821 |
|
| 822 |
.. versionadded:: 3.12 |
| 823 |
|
| 824 |
.. data:: SHUT_RD |
| 825 |
SHUT_WR |
| 826 |
SHUT_RDWR |
| 827 |
|
| 828 |
These constants are used by the :meth:`~socket.socket.shutdown` method of socket objects. |
| 829 |
|
| 830 |
.. availability:: not WASI. |
| 831 |
|
| 832 |
Functions |
| 833 |
^^^^^^^^^ |
| 834 |
|
| 835 |
Creating sockets |
| 836 |
'''''''''''''''' |
| 837 |
|
| 838 |
The following functions all create :ref:`socket objects <socket-objects>`. |
| 839 |
|
| 840 |
|
| 841 |
.. class:: socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None) |
| 842 |
|
| 843 |
Create a new socket using the given address family, socket type and protocol |
| 844 |
number. The address family should be :const:`AF_INET` (the default), |
| 845 |
:const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN`, :const:`AF_PACKET`, |
| 846 |
or :const:`AF_RDS`. The socket type should be :const:`SOCK_STREAM` (the |
| 847 |
default), :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other |
| 848 |
``SOCK_`` constants. The protocol number is usually zero and may be omitted |
| 849 |
or in the case where the address family is :const:`AF_CAN` the protocol |
| 850 |
should be one of :const:`CAN_RAW`, :const:`CAN_BCM`, :const:`CAN_ISOTP` or |
| 851 |
:const:`CAN_J1939`. |
| 852 |
|
| 853 |
If *fileno* is specified, the values for *family*, *type*, and *proto* are |
| 854 |
auto-detected from the specified file descriptor. Auto-detection can be |
| 855 |
overruled by calling the function with explicit *family*, *type*, or *proto* |
| 856 |
arguments. This only affects how Python represents e.g. the return value |
| 857 |
of :meth:`socket.getpeername` but not the actual OS resource. Unlike |
| 858 |
:func:`socket.fromfd`, *fileno* will return the same socket and not a |
| 859 |
duplicate. This may help close a detached socket using |
| 860 |
:meth:`socket.close`. |
| 861 |
|
| 862 |
The newly created socket is :ref:`non-inheritable <fd_inheritance>`. |
| 863 |
|
| 864 |
.. audit-event:: socket.__new__ self,family,type,protocol socket.socket |
| 865 |
|
| 866 |
.. versionchanged:: 3.3 |
| 867 |
The AF_CAN family was added. |
| 868 |
The AF_RDS family was added. |
| 869 |
|
| 870 |
.. versionchanged:: 3.4 |
| 871 |
The CAN_BCM protocol was added. |
| 872 |
|
| 873 |
.. versionchanged:: 3.4 |
| 874 |
The returned socket is now non-inheritable. |
| 875 |
|
| 876 |
.. versionchanged:: 3.7 |
| 877 |
The CAN_ISOTP protocol was added. |
| 878 |
|
| 879 |
.. versionchanged:: 3.7 |
| 880 |
When :const:`SOCK_NONBLOCK` or :const:`SOCK_CLOEXEC` |
| 881 |
bit flags are applied to *type* they are cleared, and |
| 882 |
:attr:`socket.type` will not reflect them. They are still passed |
| 883 |
to the underlying system ``socket()`` call. Therefore, |
| 884 |
|
| 885 |
:: |
| 886 |
|
| 887 |
sock = socket.socket( |
| 888 |
socket.AF_INET, |
| 889 |
socket.SOCK_STREAM | socket.SOCK_NONBLOCK) |
| 890 |
|
| 891 |
will still create a non-blocking socket on OSes that support |
| 892 |
``SOCK_NONBLOCK``, but ``sock.type`` will be set to |
| 893 |
``socket.SOCK_STREAM``. |
| 894 |
|
| 895 |
.. versionchanged:: 3.9 |
| 896 |
The CAN_J1939 protocol was added. |
| 897 |
|
| 898 |
.. versionchanged:: 3.10 |
| 899 |
The IPPROTO_MPTCP protocol was added. |
| 900 |
|
| 901 |
.. function:: socketpair([family[, type[, proto]]]) |
| 902 |
|
| 903 |
Build a pair of connected socket objects using the given address family, socket |
| 904 |
type, and protocol number. Address family, socket type, and protocol number are |
| 905 |
as for the :func:`~socket.socket` function. The default family is :const:`AF_UNIX` |
| 906 |
if defined on the platform; otherwise, the default is :const:`AF_INET`. |
| 907 |
|
| 908 |
The newly created sockets are :ref:`non-inheritable <fd_inheritance>`. |
| 909 |
|
| 910 |
.. versionchanged:: 3.2 |
| 911 |
The returned socket objects now support the whole socket API, rather |
| 912 |
than a subset. |
| 913 |
|
| 914 |
.. versionchanged:: 3.4 |
| 915 |
The returned sockets are now non-inheritable. |
| 916 |
|
| 917 |
.. versionchanged:: 3.5 |
| 918 |
Windows support added. |
| 919 |
|
| 920 |
|
| 921 |
.. function:: create_connection(address, timeout=GLOBAL_DEFAULT, source_address=None, *, all_errors=False) |
| 922 |
|
| 923 |
Connect to a TCP service listening on the internet *address* (a 2-tuple |
| 924 |
``(host, port)``), and return the socket object. This is a higher-level |
| 925 |
function than :meth:`socket.connect`: if *host* is a non-numeric hostname, |
| 926 |
it will try to resolve it for both :data:`AF_INET` and :data:`AF_INET6`, |
| 927 |
and then try to connect to all possible addresses in turn until a |
| 928 |
connection succeeds. This makes it easy to write clients that are |
| 929 |
compatible to both IPv4 and IPv6. |
| 930 |
|
| 931 |
Passing the optional *timeout* parameter will set the timeout on the |
| 932 |
socket instance before attempting to connect. If no *timeout* is |
| 933 |
supplied, the global default timeout setting returned by |
| 934 |
:func:`getdefaulttimeout` is used. |
| 935 |
|
| 936 |
If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the |
| 937 |
socket to bind to as its source address before connecting. If host or port |
| 938 |
are '' or 0 respectively the OS default behavior will be used. |
| 939 |
|
| 940 |
When a connection cannot be created, an exception is raised. By default, |
| 941 |
it is the exception from the last address in the list. If *all_errors* |
| 942 |
is ``True``, it is an :exc:`ExceptionGroup` containing the errors of all |
| 943 |
attempts. |
| 944 |
|
| 945 |
.. versionchanged:: 3.2 |
| 946 |
*source_address* was added. |
| 947 |
|
| 948 |
.. versionchanged:: 3.11 |
| 949 |
*all_errors* was added. |
| 950 |
|
| 951 |
|
| 952 |
.. function:: create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False) |
| 953 |
|
| 954 |
Convenience function which creates a TCP socket bound to *address* (a 2-tuple |
| 955 |
``(host, port)``) and returns the socket object. |
| 956 |
|
| 957 |
*family* should be either :data:`AF_INET` or :data:`AF_INET6`. |
| 958 |
*backlog* is the queue size passed to :meth:`socket.listen`; if not specified |
| 959 |
, a default reasonable value is chosen. |
| 960 |
*reuse_port* dictates whether to set the :data:`SO_REUSEPORT` socket option. |
| 961 |
|
| 962 |
If *dualstack_ipv6* is true, *family* is :data:`AF_INET6` and the platform |
| 963 |
supports it the socket will be able to accept both IPv4 and IPv6 connections, |
| 964 |
else it will raise :exc:`ValueError`. Most POSIX platforms and Windows are |
| 965 |
supposed to support this functionality. |
| 966 |
When this functionality is enabled the address returned by |
| 967 |
:meth:`socket.getpeername` when an IPv4 connection occurs will be an IPv6 |
| 968 |
address represented as an IPv4-mapped IPv6 address. |
| 969 |
If *dualstack_ipv6* is false it will explicitly disable this functionality |
| 970 |
on platforms that enable it by default (e.g. Linux). |
| 971 |
This parameter can be used in conjunction with :func:`has_dualstack_ipv6`: |
| 972 |
|
| 973 |
:: |
| 974 |
|
| 975 |
import socket |
| 976 |
|
| 977 |
addr = ("", 8080) # all interfaces, port 8080 |
| 978 |
if socket.has_dualstack_ipv6(): |
| 979 |
s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True) |
| 980 |
else: |
| 981 |
s = socket.create_server(addr) |
| 982 |
|
| 983 |
.. note:: |
| 984 |
On POSIX platforms the :data:`SO_REUSEADDR` socket option is set in order to |
| 985 |
immediately reuse previous sockets which were bound on the same *address* |
| 986 |
and remained in TIME_WAIT state. |
| 987 |
|
| 988 |
.. versionadded:: 3.8 |
| 989 |
|
| 990 |
.. function:: has_dualstack_ipv6() |
| 991 |
|
| 992 |
Return ``True`` if the platform supports creating a TCP socket which can |
| 993 |
handle both IPv4 and IPv6 connections. |
| 994 |
|
| 995 |
.. versionadded:: 3.8 |
| 996 |
|
| 997 |
.. function:: fromfd(fd, family, type, proto=0) |
| 998 |
|
| 999 |
Duplicate the file descriptor *fd* (an integer as returned by a file object's |
| 1000 |
:meth:`~io.IOBase.fileno` method) and build a socket object from the result. Address |
| 1001 |
family, socket type and protocol number are as for the :func:`~socket.socket` function. |
| 1002 |
The file descriptor should refer to a socket, but this is not checked --- |
| 1003 |
subsequent operations on the object may fail if the file descriptor is invalid. |
| 1004 |
This function is rarely needed, but can be used to get or set socket options on |
| 1005 |
a socket passed to a program as standard input or output (such as a server |
| 1006 |
started by the Unix inet daemon). The socket is assumed to be in blocking mode. |
| 1007 |
|
| 1008 |
The newly created socket is :ref:`non-inheritable <fd_inheritance>`. |
| 1009 |
|
| 1010 |
.. versionchanged:: 3.4 |
| 1011 |
The returned socket is now non-inheritable. |
| 1012 |
|
| 1013 |
|
| 1014 |
.. function:: fromshare(data) |
| 1015 |
|
| 1016 |
Instantiate a socket from data obtained from the :meth:`socket.share` |
| 1017 |
method. The socket is assumed to be in blocking mode. |
| 1018 |
|
| 1019 |
.. availability:: Windows. |
| 1020 |
|
| 1021 |
.. versionadded:: 3.3 |
| 1022 |
|
| 1023 |
|
| 1024 |
.. data:: SocketType |
| 1025 |
|
| 1026 |
This is a Python type object that represents the socket object type. It is the |
| 1027 |
same as ``type(socket(...))``. |
| 1028 |
|
| 1029 |
|
| 1030 |
Other functions |
| 1031 |
''''''''''''''' |
| 1032 |
|
| 1033 |
The :mod:`!socket` module also offers various network-related services: |
| 1034 |
|
| 1035 |
|
| 1036 |
.. function:: close(fd) |
| 1037 |
|
| 1038 |
Close a socket file descriptor. This is like :func:`os.close`, but for |
| 1039 |
sockets. On some platforms (most notably Windows) :func:`os.close` |
| 1040 |
does not work for socket file descriptors. |
| 1041 |
|
| 1042 |
.. versionadded:: 3.7 |
| 1043 |
|
| 1044 |
.. function:: getaddrinfo(host, port, family=AF_UNSPEC, type=0, proto=0, flags=0) |
| 1045 |
|
| 1046 |
This function wraps the C function ``getaddrinfo`` of the underlying system. |
| 1047 |
|
| 1048 |
Translate the *host*/*port* argument into a sequence of 5-tuples that contain |
| 1049 |
all the necessary arguments for creating a socket connected to that service. |
| 1050 |
*host* is a domain name, a string representation of an IPv4/v6 address |
| 1051 |
or ``None``. *port* is a string service name such as ``'http'``, a numeric |
| 1052 |
port number or ``None``. By passing ``None`` as the value of *host* |
| 1053 |
and *port*, you can pass ``NULL`` to the underlying C API. |
| 1054 |
|
| 1055 |
The *family*, *type* and *proto* arguments can be optionally specified |
| 1056 |
in order to provide options and limit the list of addresses returned. |
| 1057 |
Pass their default values (:data:`AF_UNSPEC`, 0, and 0, respectively) |
| 1058 |
to not limit the results. See the note below for details. |
| 1059 |
|
| 1060 |
The *flags* argument can be one or several of the ``AI_*`` constants, |
| 1061 |
and will influence how results are computed and returned. |
| 1062 |
For example, :const:`AI_NUMERICHOST` will disable domain name resolution |
| 1063 |
and will raise an error if *host* is a domain name. |
| 1064 |
|
| 1065 |
The function returns a list of 5-tuples with the following structure: |
| 1066 |
|
| 1067 |
``(family, type, proto, canonname, sockaddr)`` |
| 1068 |
|
| 1069 |
In these tuples, *family*, *type*, *proto* are all integers and are |
| 1070 |
meant to be passed to the :func:`~socket.socket` function. *canonname* will be |
| 1071 |
a string representing the canonical name of the *host* if |
| 1072 |
:const:`AI_CANONNAME` is part of the *flags* argument; else *canonname* |
| 1073 |
will be empty. *sockaddr* is a tuple describing a socket address, whose |
| 1074 |
format depends on the returned *family* (a ``(address, port)`` 2-tuple for |
| 1075 |
:const:`AF_INET`, a ``(address, port, flowinfo, scope_id)`` 4-tuple for |
| 1076 |
:const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect` |
| 1077 |
method. |
| 1078 |
|
| 1079 |
.. note:: |
| 1080 |
|
| 1081 |
If you intend to use results from :func:`!getaddrinfo` to create a socket |
| 1082 |
(rather than, for example, retrieve *canonname*), |
| 1083 |
consider limiting the results by *type* (e.g. :data:`SOCK_STREAM` or |
| 1084 |
:data:`SOCK_DGRAM`) and/or *proto* (e.g. :data:`IPPROTO_TCP` or |
| 1085 |
:data:`IPPROTO_UDP`) that your application can handle. |
| 1086 |
|
| 1087 |
The behavior with default values of *family*, *type*, *proto* |
| 1088 |
and *flags* is system-specific. |
| 1089 |
|
| 1090 |
Many systems (for example, most Linux configurations) will return a sorted |
| 1091 |
list of all matching addresses. |
| 1092 |
These addresses should generally be tried in order until a connection succeeds |
| 1093 |
(possibly tried in parallel, for example, using a `Happy Eyeballs`_ algorithm). |
| 1094 |
In these cases, limiting the *type* and/or *proto* can help eliminate |
| 1095 |
unsuccessful or unusable connection attempts. |
| 1096 |
|
| 1097 |
Some systems will, however, only return a single address. |
| 1098 |
(For example, this was reported on Solaris and AIX configurations.) |
| 1099 |
On these systems, limiting the *type* and/or *proto* helps ensure that |
| 1100 |
this address is usable. |
| 1101 |
|
| 1102 |
.. audit-event:: socket.getaddrinfo host,port,family,type,protocol socket.getaddrinfo |
| 1103 |
|
| 1104 |
The following example fetches address information for a hypothetical TCP |
| 1105 |
connection to ``example.org`` on port 80 (results may differ on your |
| 1106 |
system if IPv6 isn't enabled):: |
| 1107 |
|
| 1108 |
>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP) |
| 1109 |
[(socket.AF_INET6, socket.SOCK_STREAM, |
| 1110 |
6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)), |
| 1111 |
(socket.AF_INET, socket.SOCK_STREAM, |
| 1112 |
6, '', ('93.184.216.34', 80))] |
| 1113 |
|
| 1114 |
.. versionchanged:: 3.2 |
| 1115 |
parameters can now be passed using keyword arguments. |
| 1116 |
|
| 1117 |
.. versionchanged:: 3.7 |
| 1118 |
for IPv6 multicast addresses, string representing an address will not |
| 1119 |
contain ``%scope_id`` part. |
| 1120 |
|
| 1121 |
.. _Happy Eyeballs: https://en.wikipedia.org/wiki/Happy_Eyeballs |
| 1122 |
|
| 1123 |
.. function:: getfqdn([name]) |
| 1124 |
|
| 1125 |
Return a fully qualified domain name for *name*. If *name* is omitted or empty, |
| 1126 |
it is interpreted as the local host. To find the fully qualified name, the |
| 1127 |
hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the |
| 1128 |
host, if available. The first name which includes a period is selected. In |
| 1129 |
case no fully qualified domain name is available and *name* was provided, |
| 1130 |
it is returned unchanged. If *name* was empty or equal to ``'0.0.0.0'``, |
| 1131 |
the hostname from :func:`gethostname` is returned. |
| 1132 |
|
| 1133 |
|
| 1134 |
.. function:: gethostbyname(hostname) |
| 1135 |
|
| 1136 |
Translate a host name to IPv4 address format. The IPv4 address is returned as a |
| 1137 |
string, such as ``'100.50.200.5'``. If the host name is an IPv4 address itself |
| 1138 |
it is returned unchanged. See :func:`gethostbyname_ex` for a more complete |
| 1139 |
interface. :func:`gethostbyname` does not support IPv6 name resolution, and |
| 1140 |
:func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support. |
| 1141 |
|
| 1142 |
.. audit-event:: socket.gethostbyname hostname socket.gethostbyname |
| 1143 |
|
| 1144 |
.. availability:: not WASI. |
| 1145 |
|
| 1146 |
|
| 1147 |
.. function:: gethostbyname_ex(hostname) |
| 1148 |
|
| 1149 |
Translate a host name to IPv4 address format, extended interface. Return a |
| 1150 |
3-tuple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the host's |
| 1151 |
primary host name, *aliaslist* is a (possibly |
| 1152 |
empty) list of alternative host names for the same address, and *ipaddrlist* is |
| 1153 |
a list of IPv4 addresses for the same interface on the same host (often but not |
| 1154 |
always a single address). :func:`gethostbyname_ex` does not support IPv6 name |
| 1155 |
resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual |
| 1156 |
stack support. |
| 1157 |
|
| 1158 |
.. audit-event:: socket.gethostbyname hostname socket.gethostbyname_ex |
| 1159 |
|
| 1160 |
.. availability:: not WASI. |
| 1161 |
|
| 1162 |
|
| 1163 |
.. function:: gethostname() |
| 1164 |
|
| 1165 |
Return a string containing the hostname of the machine where the Python |
| 1166 |
interpreter is currently executing. |
| 1167 |
|
| 1168 |
.. audit-event:: socket.gethostname "" socket.gethostname |
| 1169 |
|
| 1170 |
Note: :func:`gethostname` doesn't always return the fully qualified domain |
| 1171 |
name; use :func:`getfqdn` for that. |
| 1172 |
|
| 1173 |
.. availability:: not WASI. |
| 1174 |
|
| 1175 |
|
| 1176 |
.. function:: gethostbyaddr(ip_address) |
| 1177 |
|
| 1178 |
Return a 3-tuple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the |
| 1179 |
primary host name responding to the given *ip_address*, *aliaslist* is a |
| 1180 |
(possibly empty) list of alternative host names for the same address, and |
| 1181 |
*ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same |
| 1182 |
host (most likely containing only a single address). To find the fully qualified |
| 1183 |
domain name, use the function :func:`getfqdn`. :func:`gethostbyaddr` supports |
| 1184 |
both IPv4 and IPv6. |
| 1185 |
|
| 1186 |
.. audit-event:: socket.gethostbyaddr ip_address socket.gethostbyaddr |
| 1187 |
|
| 1188 |
.. availability:: not WASI. |
| 1189 |
|
| 1190 |
|
| 1191 |
.. function:: getnameinfo(sockaddr, flags) |
| 1192 |
|
| 1193 |
Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending |
| 1194 |
on the settings of *flags*, the result can contain a fully qualified domain name |
| 1195 |
or numeric address representation in *host*. Similarly, *port* can contain a |
| 1196 |
string port name or a numeric port number. |
| 1197 |
|
| 1198 |
For IPv6 addresses, ``%scope_id`` is appended to the host part if *sockaddr* |
| 1199 |
contains meaningful *scope_id*. Usually this happens for multicast addresses. |
| 1200 |
|
| 1201 |
For more information about *flags* you can consult :manpage:`getnameinfo(3)`. |
| 1202 |
|
| 1203 |
.. audit-event:: socket.getnameinfo sockaddr socket.getnameinfo |
| 1204 |
|
| 1205 |
.. availability:: not WASI. |
| 1206 |
|
| 1207 |
|
| 1208 |
.. function:: getprotobyname(protocolname) |
| 1209 |
|
| 1210 |
Translate an internet protocol name (for example, ``'icmp'``) to a constant |
| 1211 |
suitable for passing as the (optional) third argument to the :func:`~socket.socket` |
| 1212 |
function. This is usually only needed for sockets opened in "raw" mode |
| 1213 |
(:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen |
| 1214 |
automatically if the protocol is omitted or zero. |
| 1215 |
|
| 1216 |
.. availability:: not WASI. |
| 1217 |
|
| 1218 |
|
| 1219 |
.. function:: getservbyname(servicename[, protocolname]) |
| 1220 |
|
| 1221 |
Translate an internet service name and protocol name to a port number for that |
| 1222 |
service. The optional protocol name, if given, should be ``'tcp'`` or |
| 1223 |
``'udp'``, otherwise any protocol will match. |
| 1224 |
|
| 1225 |
.. audit-event:: socket.getservbyname servicename,protocolname socket.getservbyname |
| 1226 |
|
| 1227 |
.. availability:: not WASI. |
| 1228 |
|
| 1229 |
|
| 1230 |
.. function:: getservbyport(port[, protocolname]) |
| 1231 |
|
| 1232 |
Translate an internet port number and protocol name to a service name for that |
| 1233 |
service. The optional protocol name, if given, should be ``'tcp'`` or |
| 1234 |
``'udp'``, otherwise any protocol will match. |
| 1235 |
|
| 1236 |
.. audit-event:: socket.getservbyport port,protocolname socket.getservbyport |
| 1237 |
|
| 1238 |
.. availability:: not WASI. |
| 1239 |
|
| 1240 |
|
| 1241 |
.. function:: ntohl(x) |
| 1242 |
|
| 1243 |
Convert 32-bit positive integers from network to host byte order. On machines |
| 1244 |
where the host byte order is the same as network byte order, this is a no-op; |
| 1245 |
otherwise, it performs a 4-byte swap operation. |
| 1246 |
|
| 1247 |
|
| 1248 |
.. function:: ntohs(x) |
| 1249 |
|
| 1250 |
Convert 16-bit positive integers from network to host byte order. On machines |
| 1251 |
where the host byte order is the same as network byte order, this is a no-op; |
| 1252 |
otherwise, it performs a 2-byte swap operation. |
| 1253 |
|
| 1254 |
.. versionchanged:: 3.10 |
| 1255 |
Raises :exc:`OverflowError` if *x* does not fit in a 16-bit unsigned |
| 1256 |
integer. |
| 1257 |
|
| 1258 |
|
| 1259 |
.. function:: htonl(x) |
| 1260 |
|
| 1261 |
Convert 32-bit positive integers from host to network byte order. On machines |
| 1262 |
where the host byte order is the same as network byte order, this is a no-op; |
| 1263 |
otherwise, it performs a 4-byte swap operation. |
| 1264 |
|
| 1265 |
|
| 1266 |
.. function:: htons(x) |
| 1267 |
|
| 1268 |
Convert 16-bit positive integers from host to network byte order. On machines |
| 1269 |
where the host byte order is the same as network byte order, this is a no-op; |
| 1270 |
otherwise, it performs a 2-byte swap operation. |
| 1271 |
|
| 1272 |
.. versionchanged:: 3.10 |
| 1273 |
Raises :exc:`OverflowError` if *x* does not fit in a 16-bit unsigned |
| 1274 |
integer. |
| 1275 |
|
| 1276 |
|
| 1277 |
.. function:: inet_aton(ip_string) |
| 1278 |
|
| 1279 |
Convert an IPv4 address from dotted-quad string format (for example, |
| 1280 |
'123.45.67.89') to 32-bit packed binary format, as a bytes object four characters in |
| 1281 |
length. This is useful when conversing with a program that uses the standard C |
| 1282 |
library and needs objects of type :c:struct:`in_addr`, which is the C type |
| 1283 |
for the 32-bit packed binary this function returns. |
| 1284 |
|
| 1285 |
:func:`inet_aton` also accepts strings with less than three dots; see the |
| 1286 |
Unix manual page :manpage:`inet(3)` for details. |
| 1287 |
|
| 1288 |
If the IPv4 address string passed to this function is invalid, |
| 1289 |
:exc:`OSError` will be raised. Note that exactly what is valid depends on |
| 1290 |
the underlying C implementation of :c:func:`inet_aton`. |
| 1291 |
|
| 1292 |
:func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used |
| 1293 |
instead for IPv4/v6 dual stack support. |
| 1294 |
|
| 1295 |
|
| 1296 |
.. function:: inet_ntoa(packed_ip) |
| 1297 |
|
| 1298 |
Convert a 32-bit packed IPv4 address (a :term:`bytes-like object` four |
| 1299 |
bytes in length) to its standard dotted-quad string representation (for example, |
| 1300 |
'123.45.67.89'). This is useful when conversing with a program that uses the |
| 1301 |
standard C library and needs objects of type :c:struct:`in_addr`, which |
| 1302 |
is the C type for the 32-bit packed binary data this function takes as an |
| 1303 |
argument. |
| 1304 |
|
| 1305 |
If the byte sequence passed to this function is not exactly 4 bytes in |
| 1306 |
length, :exc:`OSError` will be raised. :func:`inet_ntoa` does not |
| 1307 |
support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual |
| 1308 |
stack support. |
| 1309 |
|
| 1310 |
.. versionchanged:: 3.5 |
| 1311 |
Writable :term:`bytes-like object` is now accepted. |
| 1312 |
|
| 1313 |
|
| 1314 |
.. function:: inet_pton(address_family, ip_string) |
| 1315 |
|
| 1316 |
Convert an IP address from its family-specific string format to a packed, |
| 1317 |
binary format. :func:`inet_pton` is useful when a library or network protocol |
| 1318 |
calls for an object of type :c:struct:`in_addr` (similar to |
| 1319 |
:func:`inet_aton`) or :c:struct:`in6_addr`. |
| 1320 |
|
| 1321 |
Supported values for *address_family* are currently :const:`AF_INET` and |
| 1322 |
:const:`AF_INET6`. If the IP address string *ip_string* is invalid, |
| 1323 |
:exc:`OSError` will be raised. Note that exactly what is valid depends on |
| 1324 |
both the value of *address_family* and the underlying implementation of |
| 1325 |
:c:func:`inet_pton`. |
| 1326 |
|
| 1327 |
.. availability:: Unix, Windows. |
| 1328 |
|
| 1329 |
.. versionchanged:: 3.4 |
| 1330 |
Windows support added |
| 1331 |
|
| 1332 |
|
| 1333 |
.. function:: inet_ntop(address_family, packed_ip) |
| 1334 |
|
| 1335 |
Convert a packed IP address (a :term:`bytes-like object` of some number of |
| 1336 |
bytes) to its standard, family-specific string representation (for |
| 1337 |
example, ``'7.10.0.5'`` or ``'5aef:2b::8'``). |
| 1338 |
:func:`inet_ntop` is useful when a library or network protocol returns an |
| 1339 |
object of type :c:struct:`in_addr` (similar to :func:`inet_ntoa`) or |
| 1340 |
:c:struct:`in6_addr`. |
| 1341 |
|
| 1342 |
Supported values for *address_family* are currently :const:`AF_INET` and |
| 1343 |
:const:`AF_INET6`. If the bytes object *packed_ip* is not the correct |
| 1344 |
length for the specified address family, :exc:`ValueError` will be raised. |
| 1345 |
:exc:`OSError` is raised for errors from the call to :func:`inet_ntop`. |
| 1346 |
|
| 1347 |
.. availability:: Unix, Windows. |
| 1348 |
|
| 1349 |
.. versionchanged:: 3.4 |
| 1350 |
Windows support added |
| 1351 |
|
| 1352 |
.. versionchanged:: 3.5 |
| 1353 |
Writable :term:`bytes-like object` is now accepted. |
| 1354 |
|
| 1355 |
|
| 1356 |
.. |
| 1357 |
XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any |
| 1358 |
non-Unix platforms? The old (obsolete?) 4.2BSD form of the |
| 1359 |
interface, in which struct msghdr has no msg_control or |
| 1360 |
msg_controllen members, is not currently supported. |
| 1361 |
|
| 1362 |
.. function:: CMSG_LEN(length) |
| 1363 |
|
| 1364 |
Return the total length, without trailing padding, of an ancillary |
| 1365 |
data item with associated data of the given *length*. This value |
| 1366 |
can often be used as the buffer size for :meth:`~socket.recvmsg` to |
| 1367 |
receive a single item of ancillary data, but :rfc:`3542` requires |
| 1368 |
portable applications to use :func:`CMSG_SPACE` and thus include |
| 1369 |
space for padding, even when the item will be the last in the |
| 1370 |
buffer. Raises :exc:`OverflowError` if *length* is outside the |
| 1371 |
permissible range of values. |
| 1372 |
|
| 1373 |
.. availability:: Unix, not WASI. |
| 1374 |
|
| 1375 |
Most Unix platforms. |
| 1376 |
|
| 1377 |
.. versionadded:: 3.3 |
| 1378 |
|
| 1379 |
|
| 1380 |
.. function:: CMSG_SPACE(length) |
| 1381 |
|
| 1382 |
Return the buffer size needed for :meth:`~socket.recvmsg` to |
| 1383 |
receive an ancillary data item with associated data of the given |
| 1384 |
*length*, along with any trailing padding. The buffer space needed |
| 1385 |
to receive multiple items is the sum of the :func:`CMSG_SPACE` |
| 1386 |
values for their associated data lengths. Raises |
| 1387 |
:exc:`OverflowError` if *length* is outside the permissible range |
| 1388 |
of values. |
| 1389 |
|
| 1390 |
Note that some systems might support ancillary data without |
| 1391 |
providing this function. Also note that setting the buffer size |
| 1392 |
using the results of this function may not precisely limit the |
| 1393 |
amount of ancillary data that can be received, since additional |
| 1394 |
data may be able to fit into the padding area. |
| 1395 |
|
| 1396 |
.. availability:: Unix, not WASI. |
| 1397 |
|
| 1398 |
most Unix platforms. |
| 1399 |
|
| 1400 |
.. versionadded:: 3.3 |
| 1401 |
|
| 1402 |
|
| 1403 |
.. function:: getdefaulttimeout() |
| 1404 |
|
| 1405 |
Return the default timeout in seconds (float) for new socket objects. A value |
| 1406 |
of ``None`` indicates that new socket objects have no timeout. When the socket |
| 1407 |
module is first imported, the default is ``None``. |
| 1408 |
|
| 1409 |
|
| 1410 |
.. function:: setdefaulttimeout(timeout) |
| 1411 |
|
| 1412 |
Set the default timeout in seconds (float) for new socket objects. When |
| 1413 |
the socket module is first imported, the default is ``None``. See |
| 1414 |
:meth:`~socket.settimeout` for possible values and their respective |
| 1415 |
meanings. |
| 1416 |
|
| 1417 |
|
| 1418 |
.. function:: sethostname(name) |
| 1419 |
|
| 1420 |
Set the machine's hostname to *name*. This will raise an |
| 1421 |
:exc:`OSError` if you don't have enough rights. |
| 1422 |
|
| 1423 |
.. audit-event:: socket.sethostname name socket.sethostname |
| 1424 |
|
| 1425 |
.. availability:: Unix, not Android. |
| 1426 |
|
| 1427 |
.. versionadded:: 3.3 |
| 1428 |
|
| 1429 |
|
| 1430 |
.. function:: if_nameindex() |
| 1431 |
|
| 1432 |
Return a list of network interface information |
| 1433 |
(index int, name string) tuples. |
| 1434 |
:exc:`OSError` if the system call fails. |
| 1435 |
|
| 1436 |
.. availability:: Unix, Windows, not WASI. |
| 1437 |
|
| 1438 |
.. versionadded:: 3.3 |
| 1439 |
|
| 1440 |
.. versionchanged:: 3.8 |
| 1441 |
Windows support was added. |
| 1442 |
|
| 1443 |
.. note:: |
| 1444 |
|
| 1445 |
On Windows network interfaces have different names in different contexts |
| 1446 |
(all names are examples): |
| 1447 |
|
| 1448 |
* UUID: ``{FB605B73-AAC2-49A6-9A2F-25416AEA0573}`` |
| 1449 |
* name: ``ethernet_32770`` |
| 1450 |
* friendly name: ``vEthernet (nat)`` |
| 1451 |
* description: ``Hyper-V Virtual Ethernet Adapter`` |
| 1452 |
|
| 1453 |
This function returns names of the second form from the list, ``ethernet_32770`` |
| 1454 |
in this example case. |
| 1455 |
|
| 1456 |
|
| 1457 |
.. function:: if_nametoindex(if_name) |
| 1458 |
|
| 1459 |
Return a network interface index number corresponding to an |
| 1460 |
interface name. |
| 1461 |
:exc:`OSError` if no interface with the given name exists. |
| 1462 |
|
| 1463 |
.. availability:: Unix, Windows, not WASI. |
| 1464 |
|
| 1465 |
.. versionadded:: 3.3 |
| 1466 |
|
| 1467 |
.. versionchanged:: 3.8 |
| 1468 |
Windows support was added. |
| 1469 |
|
| 1470 |
.. seealso:: |
| 1471 |
"Interface name" is a name as documented in :func:`if_nameindex`. |
| 1472 |
|
| 1473 |
|
| 1474 |
.. function:: if_indextoname(if_index) |
| 1475 |
|
| 1476 |
Return a network interface name corresponding to an |
| 1477 |
interface index number. |
| 1478 |
:exc:`OSError` if no interface with the given index exists. |
| 1479 |
|
| 1480 |
.. availability:: Unix, Windows, not WASI. |
| 1481 |
|
| 1482 |
.. versionadded:: 3.3 |
| 1483 |
|
| 1484 |
.. versionchanged:: 3.8 |
| 1485 |
Windows support was added. |
| 1486 |
|
| 1487 |
.. seealso:: |
| 1488 |
"Interface name" is a name as documented in :func:`if_nameindex`. |
| 1489 |
|
| 1490 |
|
| 1491 |
.. function:: send_fds(sock, buffers, fds[, flags[, address]]) |
| 1492 |
|
| 1493 |
Send the list of file descriptors *fds* over an :const:`AF_UNIX` socket *sock*. |
| 1494 |
The *fds* parameter is a sequence of file descriptors. |
| 1495 |
Consult :meth:`~socket.sendmsg` for the documentation of these parameters. |
| 1496 |
|
| 1497 |
.. availability:: Unix, not WASI. |
| 1498 |
|
| 1499 |
Unix platforms supporting :meth:`~socket.sendmsg` |
| 1500 |
and :const:`SCM_RIGHTS` mechanism. |
| 1501 |
|
| 1502 |
.. versionadded:: 3.9 |
| 1503 |
|
| 1504 |
|
| 1505 |
.. function:: recv_fds(sock, bufsize, maxfds[, flags]) |
| 1506 |
|
| 1507 |
Receive up to *maxfds* file descriptors from an :const:`AF_UNIX` socket *sock*. |
| 1508 |
Return ``(msg, list(fds), flags, addr)``. |
| 1509 |
Consult :meth:`~socket.recvmsg` for the documentation of these parameters. |
| 1510 |
|
| 1511 |
.. availability:: Unix, not WASI. |
| 1512 |
|
| 1513 |
Unix platforms supporting :meth:`~socket.recvmsg` |
| 1514 |
and :const:`SCM_RIGHTS` mechanism. |
| 1515 |
|
| 1516 |
.. versionadded:: 3.9 |
| 1517 |
|
| 1518 |
.. note:: |
| 1519 |
|
| 1520 |
Any truncated integers at the end of the list of file descriptors. |
| 1521 |
|
| 1522 |
|
| 1523 |
.. _socket-objects: |
| 1524 |
|
| 1525 |
Socket Objects |
| 1526 |
-------------- |
| 1527 |
|
| 1528 |
Socket objects have the following methods. Except for |
| 1529 |
:meth:`~socket.makefile`, these correspond to Unix system calls applicable |
| 1530 |
to sockets. |
| 1531 |
|
| 1532 |
.. versionchanged:: 3.2 |
| 1533 |
Support for the :term:`context manager` protocol was added. Exiting the |
| 1534 |
context manager is equivalent to calling :meth:`~socket.close`. |
| 1535 |
|
| 1536 |
|
| 1537 |
.. method:: socket.accept() |
| 1538 |
|
| 1539 |
Accept a connection. The socket must be bound to an address and listening for |
| 1540 |
connections. The return value is a pair ``(conn, address)`` where *conn* is a |
| 1541 |
*new* socket object usable to send and receive data on the connection, and |
| 1542 |
*address* is the address bound to the socket on the other end of the connection. |
| 1543 |
|
| 1544 |
The newly created socket is :ref:`non-inheritable <fd_inheritance>`. |
| 1545 |
|
| 1546 |
.. versionchanged:: 3.4 |
| 1547 |
The socket is now non-inheritable. |
| 1548 |
|
| 1549 |
.. versionchanged:: 3.5 |
| 1550 |
If the system call is interrupted and the signal handler does not raise |
| 1551 |
an exception, the method now retries the system call instead of raising |
| 1552 |
an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). |
| 1553 |
|
| 1554 |
|
| 1555 |
.. method:: socket.bind(address) |
| 1556 |
|
| 1557 |
Bind the socket to *address*. The socket must not already be bound. The format |
| 1558 |
of *address* depends on the address family --- see :ref:`socket-addresses`. |
| 1559 |
|
| 1560 |
.. audit-event:: socket.bind self,address socket.socket.bind |
| 1561 |
|
| 1562 |
.. availability:: not WASI. |
| 1563 |
|
| 1564 |
|
| 1565 |
.. method:: socket.close() |
| 1566 |
|
| 1567 |
Mark the socket closed. The underlying system resource (e.g. a file |
| 1568 |
descriptor) is also closed when all file objects from :meth:`makefile` |
| 1569 |
are closed. Once that happens, all future operations on the socket |
| 1570 |
object will fail. The remote end will receive no more data (after |
| 1571 |
queued data is flushed). |
| 1572 |
|
| 1573 |
Sockets are automatically closed when they are garbage-collected, but |
| 1574 |
it is recommended to :meth:`close` them explicitly, or to use a |
| 1575 |
:keyword:`with` statement around them. |
| 1576 |
|
| 1577 |
.. versionchanged:: 3.6 |
| 1578 |
:exc:`OSError` is now raised if an error occurs when the underlying |
| 1579 |
:c:func:`close` call is made. |
| 1580 |
|
| 1581 |
.. note:: |
| 1582 |
|
| 1583 |
:meth:`close` releases the resource associated with a connection but |
| 1584 |
does not necessarily close the connection immediately. If you want |
| 1585 |
to close the connection in a timely fashion, call :meth:`shutdown` |
| 1586 |
before :meth:`close`. |
| 1587 |
|
| 1588 |
|
| 1589 |
.. method:: socket.connect(address) |
| 1590 |
|
| 1591 |
Connect to a remote socket at *address*. The format of *address* depends on the |
| 1592 |
address family --- see :ref:`socket-addresses`. |
| 1593 |
|
| 1594 |
If the connection is interrupted by a signal, the method waits until the |
| 1595 |
connection completes, or raises a :exc:`TimeoutError` on timeout, if the |
| 1596 |
signal handler doesn't raise an exception and the socket is blocking or has |
| 1597 |
a timeout. For non-blocking sockets, the method raises an |
| 1598 |
:exc:`InterruptedError` exception if the connection is interrupted by a |
| 1599 |
signal (or the exception raised by the signal handler). |
| 1600 |
|
| 1601 |
.. audit-event:: socket.connect self,address socket.socket.connect |
| 1602 |
|
| 1603 |
.. versionchanged:: 3.5 |
| 1604 |
The method now waits until the connection completes instead of raising an |
| 1605 |
:exc:`InterruptedError` exception if the connection is interrupted by a |
| 1606 |
signal, the signal handler doesn't raise an exception and the socket is |
| 1607 |
blocking or has a timeout (see the :pep:`475` for the rationale). |
| 1608 |
|
| 1609 |
.. availability:: not WASI. |
| 1610 |
|
| 1611 |
|
| 1612 |
.. method:: socket.connect_ex(address) |
| 1613 |
|
| 1614 |
Like ``connect(address)``, but return an error indicator instead of raising an |
| 1615 |
exception for errors returned by the C-level :c:func:`connect` call (other |
| 1616 |
problems, such as "host not found," can still raise exceptions). The error |
| 1617 |
indicator is ``0`` if the operation succeeded, otherwise the value of the |
| 1618 |
:c:data:`errno` variable. This is useful to support, for example, asynchronous |
| 1619 |
connects. |
| 1620 |
|
| 1621 |
.. audit-event:: socket.connect self,address socket.socket.connect_ex |
| 1622 |
|
| 1623 |
.. availability:: not WASI. |
| 1624 |
|
| 1625 |
.. method:: socket.detach() |
| 1626 |
|
| 1627 |
Put the socket object into closed state without actually closing the |
| 1628 |
underlying file descriptor. The file descriptor is returned, and can |
| 1629 |
be reused for other purposes. |
| 1630 |
|
| 1631 |
.. versionadded:: 3.2 |
| 1632 |
|
| 1633 |
|
| 1634 |
.. method:: socket.dup() |
| 1635 |
|
| 1636 |
Duplicate the socket. |
| 1637 |
|
| 1638 |
The newly created socket is :ref:`non-inheritable <fd_inheritance>`. |
| 1639 |
|
| 1640 |
.. versionchanged:: 3.4 |
| 1641 |
The socket is now non-inheritable. |
| 1642 |
|
| 1643 |
.. availability:: not WASI. |
| 1644 |
|
| 1645 |
|
| 1646 |
.. method:: socket.fileno() |
| 1647 |
|
| 1648 |
Return the socket's file descriptor (a small integer), or -1 on failure. This |
| 1649 |
is useful with :func:`select.select`. |
| 1650 |
|
| 1651 |
Under Windows the small integer returned by this method cannot be used where a |
| 1652 |
file descriptor can be used (such as :func:`os.fdopen`). Unix does not have |
| 1653 |
this limitation. |
| 1654 |
|
| 1655 |
.. method:: socket.get_inheritable() |
| 1656 |
|
| 1657 |
Get the :ref:`inheritable flag <fd_inheritance>` of the socket's file |
| 1658 |
descriptor or socket's handle: ``True`` if the socket can be inherited in |
| 1659 |
child processes, ``False`` if it cannot. |
| 1660 |
|
| 1661 |
.. versionadded:: 3.4 |
| 1662 |
|
| 1663 |
|
| 1664 |
.. method:: socket.getpeername() |
| 1665 |
|
| 1666 |
Return the remote address to which the socket is connected. This is useful to |
| 1667 |
find out the port number of a remote IPv4/v6 socket, for instance. The format |
| 1668 |
of the address returned depends on the address family --- see :ref:`socket-addresses`. |
| 1669 |
On some systems this function is not supported. |
| 1670 |
|
| 1671 |
|
| 1672 |
.. method:: socket.getsockname() |
| 1673 |
|
| 1674 |
Return the socket's own address. This is useful to find out the port number of |
| 1675 |
an IPv4/v6 socket, for instance. The format of the address returned depends on |
| 1676 |
the address family --- see :ref:`socket-addresses`. |
| 1677 |
|
| 1678 |
|
| 1679 |
.. method:: socket.getsockopt(level, optname[, buflen]) |
| 1680 |
|
| 1681 |
Return the value of the given socket option (see the Unix man page |
| 1682 |
:manpage:`getsockopt(2)`). The needed symbolic constants (:ref:`SO_\* etc. <socket-unix-constants>`) |
| 1683 |
are defined in this module. If *buflen* is absent, an integer option is assumed |
| 1684 |
and its integer value is returned by the function. If *buflen* is present, it |
| 1685 |
specifies the maximum length of the buffer used to receive the option in, and |
| 1686 |
this buffer is returned as a bytes object. It is up to the caller to decode the |
| 1687 |
contents of the buffer (see the optional built-in module :mod:`struct` for a way |
| 1688 |
to decode C structures encoded as byte strings). |
| 1689 |
|
| 1690 |
.. availability:: not WASI. |
| 1691 |
|
| 1692 |
|
| 1693 |
.. method:: socket.getblocking() |
| 1694 |
|
| 1695 |
Return ``True`` if socket is in blocking mode, ``False`` if in |
| 1696 |
non-blocking. |
| 1697 |
|
| 1698 |
This is equivalent to checking ``socket.gettimeout() != 0``. |
| 1699 |
|
| 1700 |
.. versionadded:: 3.7 |
| 1701 |
|
| 1702 |
|
| 1703 |
.. method:: socket.gettimeout() |
| 1704 |
|
| 1705 |
Return the timeout in seconds (float) associated with socket operations, |
| 1706 |
or ``None`` if no timeout is set. This reflects the last call to |
| 1707 |
:meth:`setblocking` or :meth:`settimeout`. |
| 1708 |
|
| 1709 |
|
| 1710 |
.. method:: socket.ioctl(control, option) |
| 1711 |
|
| 1712 |
The :meth:`ioctl` method is a limited interface to the WSAIoctl system |
| 1713 |
interface. Please refer to the `Win32 documentation |
| 1714 |
<https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more |
| 1715 |
information. |
| 1716 |
|
| 1717 |
On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl` |
| 1718 |
functions may be used; they accept a socket object as their first argument. |
| 1719 |
|
| 1720 |
Currently only the following control codes are supported: |
| 1721 |
``SIO_RCVALL``, ``SIO_KEEPALIVE_VALS``, and ``SIO_LOOPBACK_FAST_PATH``. |
| 1722 |
|
| 1723 |
.. availability:: Windows |
| 1724 |
|
| 1725 |
.. versionchanged:: 3.6 |
| 1726 |
``SIO_LOOPBACK_FAST_PATH`` was added. |
| 1727 |
|
| 1728 |
|
| 1729 |
.. method:: socket.listen([backlog]) |
| 1730 |
|
| 1731 |
Enable a server to accept connections. If *backlog* is specified, it must |
| 1732 |
be at least 0 (if it is lower, it is set to 0); it specifies the number of |
| 1733 |
unaccepted connections that the system will allow before refusing new |
| 1734 |
connections. If not specified, a default reasonable value is chosen. |
| 1735 |
|
| 1736 |
.. availability:: not WASI. |
| 1737 |
|
| 1738 |
.. versionchanged:: 3.5 |
| 1739 |
The *backlog* parameter is now optional. |
| 1740 |
|
| 1741 |
|
| 1742 |
.. method:: socket.makefile(mode='r', buffering=None, *, encoding=None, \ |
| 1743 |
errors=None, newline=None) |
| 1744 |
|
| 1745 |
.. index:: single: I/O control; buffering |
| 1746 |
|
| 1747 |
Return a :term:`file object` associated with the socket. The exact returned |
| 1748 |
type depends on the arguments given to :meth:`makefile`. These arguments are |
| 1749 |
interpreted the same way as by the built-in :func:`open` function, except |
| 1750 |
the only supported *mode* values are ``'r'`` (default), ``'w'``, ``'b'``, or |
| 1751 |
a combination of those. |
| 1752 |
|
| 1753 |
The socket must be in blocking mode; it can have a timeout, but the file |
| 1754 |
object's internal buffer may end up in an inconsistent state if a timeout |
| 1755 |
occurs. |
| 1756 |
|
| 1757 |
Closing the file object returned by :meth:`makefile` won't close the |
| 1758 |
original socket unless all other file objects have been closed and |
| 1759 |
:meth:`socket.close` has been called on the socket object. |
| 1760 |
|
| 1761 |
.. note:: |
| 1762 |
|
| 1763 |
On Windows, the file-like object created by :meth:`makefile` cannot be |
| 1764 |
used where a file object with a file descriptor is expected, such as the |
| 1765 |
stream arguments of :meth:`subprocess.Popen`. |
| 1766 |
|
| 1767 |
|
| 1768 |
.. method:: socket.recv(bufsize[, flags]) |
| 1769 |
|
| 1770 |
Receive data from the socket. The return value is a bytes object representing the |
| 1771 |
data received. The maximum amount of data to be received at once is specified |
| 1772 |
by *bufsize*. A returned empty bytes object indicates that the client has disconnected. |
| 1773 |
See the Unix manual page :manpage:`recv(2)` for the meaning of the optional argument |
| 1774 |
*flags*; it defaults to zero. |
| 1775 |
|
| 1776 |
.. versionchanged:: 3.5 |
| 1777 |
If the system call is interrupted and the signal handler does not raise |
| 1778 |
an exception, the method now retries the system call instead of raising |
| 1779 |
an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). |
| 1780 |
|
| 1781 |
|
| 1782 |
.. method:: socket.recvfrom(bufsize[, flags]) |
| 1783 |
|
| 1784 |
Receive data from the socket. The return value is a pair ``(bytes, address)`` |
| 1785 |
where *bytes* is a bytes object representing the data received and *address* is the |
| 1786 |
address of the socket sending the data. See the Unix manual page |
| 1787 |
:manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults |
| 1788 |
to zero. The format of *address* depends on the address family --- see |
| 1789 |
:ref:`socket-addresses`. |
| 1790 |
|
| 1791 |
.. versionchanged:: 3.5 |
| 1792 |
If the system call is interrupted and the signal handler does not raise |
| 1793 |
an exception, the method now retries the system call instead of raising |
| 1794 |
an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). |
| 1795 |
|
| 1796 |
.. versionchanged:: 3.7 |
| 1797 |
For multicast IPv6 address, first item of *address* does not contain |
| 1798 |
``%scope_id`` part anymore. In order to get full IPv6 address use |
| 1799 |
:func:`getnameinfo`. |
| 1800 |
|
| 1801 |
.. method:: socket.recvmsg(bufsize[, ancbufsize[, flags]]) |
| 1802 |
|
| 1803 |
Receive normal data (up to *bufsize* bytes) and ancillary data from |
| 1804 |
the socket. The *ancbufsize* argument sets the size in bytes of |
| 1805 |
the internal buffer used to receive the ancillary data; it defaults |
| 1806 |
to 0, meaning that no ancillary data will be received. Appropriate |
| 1807 |
buffer sizes for ancillary data can be calculated using |
| 1808 |
:func:`CMSG_SPACE` or :func:`CMSG_LEN`, and items which do not fit |
| 1809 |
into the buffer might be truncated or discarded. The *flags* |
| 1810 |
argument defaults to 0 and has the same meaning as for |
| 1811 |
:meth:`recv`. |
| 1812 |
|
| 1813 |
The return value is a 4-tuple: ``(data, ancdata, msg_flags, |
| 1814 |
address)``. The *data* item is a :class:`bytes` object holding the |
| 1815 |
non-ancillary data received. The *ancdata* item is a list of zero |
| 1816 |
or more tuples ``(cmsg_level, cmsg_type, cmsg_data)`` representing |
| 1817 |
the ancillary data (control messages) received: *cmsg_level* and |
| 1818 |
*cmsg_type* are integers specifying the protocol level and |
| 1819 |
protocol-specific type respectively, and *cmsg_data* is a |
| 1820 |
:class:`bytes` object holding the associated data. The *msg_flags* |
| 1821 |
item is the bitwise OR of various flags indicating conditions on |
| 1822 |
the received message; see your system documentation for details. |
| 1823 |
If the receiving socket is unconnected, *address* is the address of |
| 1824 |
the sending socket, if available; otherwise, its value is |
| 1825 |
unspecified. |
| 1826 |
|
| 1827 |
On some systems, :meth:`sendmsg` and :meth:`recvmsg` can be used to |
| 1828 |
pass file descriptors between processes over an :const:`AF_UNIX` |
| 1829 |
socket. When this facility is used (it is often restricted to |
| 1830 |
:const:`SOCK_STREAM` sockets), :meth:`recvmsg` will return, in its |
| 1831 |
ancillary data, items of the form ``(socket.SOL_SOCKET, |
| 1832 |
socket.SCM_RIGHTS, fds)``, where *fds* is a :class:`bytes` object |
| 1833 |
representing the new file descriptors as a binary array of the |
| 1834 |
native C :c:expr:`int` type. If :meth:`recvmsg` raises an |
| 1835 |
exception after the system call returns, it will first attempt to |
| 1836 |
close any file descriptors received via this mechanism. |
| 1837 |
|
| 1838 |
Some systems do not indicate the truncated length of ancillary data |
| 1839 |
items which have been only partially received. If an item appears |
| 1840 |
to extend beyond the end of the buffer, :meth:`recvmsg` will issue |
| 1841 |
a :exc:`RuntimeWarning`, and will return the part of it which is |
| 1842 |
inside the buffer provided it has not been truncated before the |
| 1843 |
start of its associated data. |
| 1844 |
|
| 1845 |
On systems which support the :const:`SCM_RIGHTS` mechanism, the |
| 1846 |
following function will receive up to *maxfds* file descriptors, |
| 1847 |
returning the message data and a list containing the descriptors |
| 1848 |
(while ignoring unexpected conditions such as unrelated control |
| 1849 |
messages being received). See also :meth:`sendmsg`. :: |
| 1850 |
|
| 1851 |
import socket, array |
| 1852 |
|
| 1853 |
def recv_fds(sock, msglen, maxfds): |
| 1854 |
fds = array.array("i") # Array of ints |
| 1855 |
msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize)) |
| 1856 |
for cmsg_level, cmsg_type, cmsg_data in ancdata: |
| 1857 |
if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS: |
| 1858 |
# Append data, ignoring any truncated integers at the end. |
| 1859 |
fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)]) |
| 1860 |
return msg, list(fds) |
| 1861 |
|
| 1862 |
.. availability:: Unix. |
| 1863 |
|
| 1864 |
Most Unix platforms. |
| 1865 |
|
| 1866 |
.. versionadded:: 3.3 |
| 1867 |
|
| 1868 |
.. versionchanged:: 3.5 |
| 1869 |
If the system call is interrupted and the signal handler does not raise |
| 1870 |
an exception, the method now retries the system call instead of raising |
| 1871 |
an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). |
| 1872 |
|
| 1873 |
|
| 1874 |
.. method:: socket.recvmsg_into(buffers[, ancbufsize[, flags]]) |
| 1875 |
|
| 1876 |
Receive normal data and ancillary data from the socket, behaving as |
| 1877 |
:meth:`recvmsg` would, but scatter the non-ancillary data into a |
| 1878 |
series of buffers instead of returning a new bytes object. The |
| 1879 |
*buffers* argument must be an iterable of objects that export |
| 1880 |
writable buffers (e.g. :class:`bytearray` objects); these will be |
| 1881 |
filled with successive chunks of the non-ancillary data until it |
| 1882 |
has all been written or there are no more buffers. The operating |
| 1883 |
system may set a limit (:func:`~os.sysconf` value ``SC_IOV_MAX``) |
| 1884 |
on the number of buffers that can be used. The *ancbufsize* and |
| 1885 |
*flags* arguments have the same meaning as for :meth:`recvmsg`. |
| 1886 |
|
| 1887 |
The return value is a 4-tuple: ``(nbytes, ancdata, msg_flags, |
| 1888 |
address)``, where *nbytes* is the total number of bytes of |
| 1889 |
non-ancillary data written into the buffers, and *ancdata*, |
| 1890 |
*msg_flags* and *address* are the same as for :meth:`recvmsg`. |
| 1891 |
|
| 1892 |
Example:: |
| 1893 |
|
| 1894 |
>>> import socket |
| 1895 |
>>> s1, s2 = socket.socketpair() |
| 1896 |
>>> b1 = bytearray(b'----') |
| 1897 |
>>> b2 = bytearray(b'0123456789') |
| 1898 |
>>> b3 = bytearray(b'--------------') |
| 1899 |
>>> s1.send(b'Mary had a little lamb') |
| 1900 |
22 |
| 1901 |
>>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3]) |
| 1902 |
(22, [], 0, None) |
| 1903 |
>>> [b1, b2, b3] |
| 1904 |
[bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')] |
| 1905 |
|
| 1906 |
.. availability:: Unix. |
| 1907 |
|
| 1908 |
Most Unix platforms. |
| 1909 |
|
| 1910 |
.. versionadded:: 3.3 |
| 1911 |
|
| 1912 |
|
| 1913 |
.. method:: socket.recvfrom_into(buffer[, nbytes[, flags]]) |
| 1914 |
|
| 1915 |
Receive data from the socket, writing it into *buffer* instead of creating a |
| 1916 |
new bytestring. The return value is a pair ``(nbytes, address)`` where *nbytes* is |
| 1917 |
the number of bytes received and *address* is the address of the socket sending |
| 1918 |
the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the |
| 1919 |
optional argument *flags*; it defaults to zero. The format of *address* |
| 1920 |
depends on the address family --- see :ref:`socket-addresses`. |
| 1921 |
|
| 1922 |
|
| 1923 |
.. method:: socket.recv_into(buffer[, nbytes[, flags]]) |
| 1924 |
|
| 1925 |
Receive up to *nbytes* bytes from the socket, storing the data into a buffer |
| 1926 |
rather than creating a new bytestring. If *nbytes* is not specified (or 0), |
| 1927 |
receive up to the size available in the given buffer. Returns the number of |
| 1928 |
bytes received. See the Unix manual page :manpage:`recv(2)` for the meaning |
| 1929 |
of the optional argument *flags*; it defaults to zero. |
| 1930 |
|
| 1931 |
|
| 1932 |
.. method:: socket.send(bytes[, flags]) |
| 1933 |
|
| 1934 |
Send data to the socket. The socket must be connected to a remote socket. The |
| 1935 |
optional *flags* argument has the same meaning as for :meth:`recv`. |
| 1936 |
Returns the number of bytes sent. Applications are responsible for checking that |
| 1937 |
all data has been sent; if only some of the data was transmitted, the |
| 1938 |
application needs to attempt delivery of the remaining data. For further |
| 1939 |
information on this topic, consult the :ref:`socket-howto`. |
| 1940 |
|
| 1941 |
.. versionchanged:: 3.5 |
| 1942 |
If the system call is interrupted and the signal handler does not raise |
| 1943 |
an exception, the method now retries the system call instead of raising |
| 1944 |
an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). |
| 1945 |
|
| 1946 |
|
| 1947 |
.. method:: socket.sendall(bytes[, flags]) |
| 1948 |
|
| 1949 |
Send data to the socket. The socket must be connected to a remote socket. The |
| 1950 |
optional *flags* argument has the same meaning as for :meth:`recv`. |
| 1951 |
Unlike :meth:`send`, this method continues to send data from *bytes* until |
| 1952 |
either all data has been sent or an error occurs. ``None`` is returned on |
| 1953 |
success. On error, an exception is raised, and there is no way to determine how |
| 1954 |
much data, if any, was successfully sent. |
| 1955 |
|
| 1956 |
.. versionchanged:: 3.5 |
| 1957 |
The socket timeout is no longer reset each time data is sent successfully. |
| 1958 |
The socket timeout is now the maximum total duration to send all data. |
| 1959 |
|
| 1960 |
.. versionchanged:: 3.5 |
| 1961 |
If the system call is interrupted and the signal handler does not raise |
| 1962 |
an exception, the method now retries the system call instead of raising |
| 1963 |
an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). |
| 1964 |
|
| 1965 |
|
| 1966 |
.. method:: socket.sendto(bytes, address) |
| 1967 |
socket.sendto(bytes, flags, address) |
| 1968 |
|
| 1969 |
Send data to the socket. The socket should not be connected to a remote socket, |
| 1970 |
since the destination socket is specified by *address*. The optional *flags* |
| 1971 |
argument has the same meaning as for :meth:`recv`. Return the number of |
| 1972 |
bytes sent. The format of *address* depends on the address family --- see |
| 1973 |
:ref:`socket-addresses`. |
| 1974 |
|
| 1975 |
.. audit-event:: socket.sendto self,address socket.socket.sendto |
| 1976 |
|
| 1977 |
.. versionchanged:: 3.5 |
| 1978 |
If the system call is interrupted and the signal handler does not raise |
| 1979 |
an exception, the method now retries the system call instead of raising |
| 1980 |
an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). |
| 1981 |
|
| 1982 |
|
| 1983 |
.. method:: socket.sendmsg(buffers[, ancdata[, flags[, address]]]) |
| 1984 |
|
| 1985 |
Send normal and ancillary data to the socket, gathering the |
| 1986 |
non-ancillary data from a series of buffers and concatenating it |
| 1987 |
into a single message. The *buffers* argument specifies the |
| 1988 |
non-ancillary data as an iterable of |
| 1989 |
:term:`bytes-like objects <bytes-like object>` |
| 1990 |
(e.g. :class:`bytes` objects); the operating system may set a limit |
| 1991 |
(:func:`~os.sysconf` value ``SC_IOV_MAX``) on the number of buffers |
| 1992 |
that can be used. The *ancdata* argument specifies the ancillary |
| 1993 |
data (control messages) as an iterable of zero or more tuples |
| 1994 |
``(cmsg_level, cmsg_type, cmsg_data)``, where *cmsg_level* and |
| 1995 |
*cmsg_type* are integers specifying the protocol level and |
| 1996 |
protocol-specific type respectively, and *cmsg_data* is a |
| 1997 |
bytes-like object holding the associated data. Note that |
| 1998 |
some systems (in particular, systems without :func:`CMSG_SPACE`) |
| 1999 |
might support sending only one control message per call. The |
| 2000 |
*flags* argument defaults to 0 and has the same meaning as for |
| 2001 |
:meth:`send`. If *address* is supplied and not ``None``, it sets a |
| 2002 |
destination address for the message. The return value is the |
| 2003 |
number of bytes of non-ancillary data sent. |
| 2004 |
|
| 2005 |
The following function sends the list of file descriptors *fds* |
| 2006 |
over an :const:`AF_UNIX` socket, on systems which support the |
| 2007 |
:const:`SCM_RIGHTS` mechanism. See also :meth:`recvmsg`. :: |
| 2008 |
|
| 2009 |
import socket, array |
| 2010 |
|
| 2011 |
def send_fds(sock, msg, fds): |
| 2012 |
return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))]) |
| 2013 |
|
| 2014 |
.. availability:: Unix, not WASI. |
| 2015 |
|
| 2016 |
Most Unix platforms. |
| 2017 |
|
| 2018 |
.. audit-event:: socket.sendmsg self,address socket.socket.sendmsg |
| 2019 |
|
| 2020 |
.. versionadded:: 3.3 |
| 2021 |
|
| 2022 |
.. versionchanged:: 3.5 |
| 2023 |
If the system call is interrupted and the signal handler does not raise |
| 2024 |
an exception, the method now retries the system call instead of raising |
| 2025 |
an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). |
| 2026 |
|
| 2027 |
.. method:: socket.sendmsg_afalg([msg], *, op[, iv[, assoclen[, flags]]]) |
| 2028 |
|
| 2029 |
Specialized version of :meth:`~socket.sendmsg` for :const:`AF_ALG` socket. |
| 2030 |
Set mode, IV, AEAD associated data length and flags for :const:`AF_ALG` socket. |
| 2031 |
|
| 2032 |
.. availability:: Linux >= 2.6.38. |
| 2033 |
|
| 2034 |
.. versionadded:: 3.6 |
| 2035 |
|
| 2036 |
.. method:: socket.sendfile(file, offset=0, count=None) |
| 2037 |
|
| 2038 |
Send a file until EOF is reached by using high-performance |
| 2039 |
:mod:`os.sendfile` and return the total number of bytes which were sent. |
| 2040 |
*file* must be a regular file object opened in binary mode. If |
| 2041 |
:mod:`os.sendfile` is not available (e.g. Windows) or *file* is not a |
| 2042 |
regular file :meth:`send` will be used instead. *offset* tells from where to |
| 2043 |
start reading the file. If specified, *count* is the total number of bytes |
| 2044 |
to transmit as opposed to sending the file until EOF is reached. File |
| 2045 |
position is updated on return or also in case of error in which case |
| 2046 |
:meth:`file.tell() <io.IOBase.tell>` can be used to figure out the number of |
| 2047 |
bytes which were sent. The socket must be of :const:`SOCK_STREAM` type. |
| 2048 |
Non-blocking sockets are not supported. |
| 2049 |
|
| 2050 |
.. versionadded:: 3.5 |
| 2051 |
|
| 2052 |
.. method:: socket.set_inheritable(inheritable) |
| 2053 |
|
| 2054 |
Set the :ref:`inheritable flag <fd_inheritance>` of the socket's file |
| 2055 |
descriptor or socket's handle. |
| 2056 |
|
| 2057 |
.. versionadded:: 3.4 |
| 2058 |
|
| 2059 |
|
| 2060 |
.. method:: socket.setblocking(flag) |
| 2061 |
|
| 2062 |
Set blocking or non-blocking mode of the socket: if *flag* is false, the |
| 2063 |
socket is set to non-blocking, else to blocking mode. |
| 2064 |
|
| 2065 |
This method is a shorthand for certain :meth:`~socket.settimeout` calls: |
| 2066 |
|
| 2067 |
* ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)`` |
| 2068 |
|
| 2069 |
* ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0.0)`` |
| 2070 |
|
| 2071 |
.. versionchanged:: 3.7 |
| 2072 |
The method no longer applies :const:`SOCK_NONBLOCK` flag on |
| 2073 |
:attr:`socket.type`. |
| 2074 |
|
| 2075 |
|
| 2076 |
.. method:: socket.settimeout(value) |
| 2077 |
|
| 2078 |
Set a timeout on blocking socket operations. The *value* argument can be a |
| 2079 |
nonnegative floating-point number expressing seconds, or ``None``. |
| 2080 |
If a non-zero value is given, subsequent socket operations will raise a |
| 2081 |
:exc:`timeout` exception if the timeout period *value* has elapsed before |
| 2082 |
the operation has completed. If zero is given, the socket is put in |
| 2083 |
non-blocking mode. If ``None`` is given, the socket is put in blocking mode. |
| 2084 |
|
| 2085 |
For further information, please consult the :ref:`notes on socket timeouts <socket-timeouts>`. |
| 2086 |
|
| 2087 |
.. versionchanged:: 3.7 |
| 2088 |
The method no longer toggles :const:`SOCK_NONBLOCK` flag on |
| 2089 |
:attr:`socket.type`. |
| 2090 |
|
| 2091 |
|
| 2092 |
.. method:: socket.setsockopt(level, optname, value: int | Buffer) |
| 2093 |
socket.setsockopt(level, optname, None, optlen: int) |
| 2094 |
|
| 2095 |
.. index:: pair: module; struct |
| 2096 |
|
| 2097 |
Set the value of the given socket option (see the Unix manual page |
| 2098 |
:manpage:`setsockopt(2)`). The needed symbolic constants are defined in this |
| 2099 |
module (:ref:`!SO_\* etc. <socket-unix-constants>`). The value can be an integer, |
| 2100 |
``None`` or a :term:`bytes-like object` representing a buffer. In the latter |
| 2101 |
case it is up to the caller to ensure that the bytestring contains the |
| 2102 |
proper bits (see the optional built-in module :mod:`struct` for a way to |
| 2103 |
encode C structures as bytestrings). When *value* is set to ``None``, |
| 2104 |
*optlen* argument is required. It's equivalent to calling :c:func:`setsockopt` C |
| 2105 |
function with ``optval=NULL`` and ``optlen=optlen``. |
| 2106 |
|
| 2107 |
.. versionchanged:: 3.5 |
| 2108 |
Writable :term:`bytes-like object` is now accepted. |
| 2109 |
|
| 2110 |
.. versionchanged:: 3.6 |
| 2111 |
setsockopt(level, optname, None, optlen: int) form added. |
| 2112 |
|
| 2113 |
.. availability:: not WASI. |
| 2114 |
|
| 2115 |
|
| 2116 |
.. method:: socket.shutdown(how) |
| 2117 |
|
| 2118 |
Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD`, |
| 2119 |
further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends |
| 2120 |
are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives are |
| 2121 |
disallowed. |
| 2122 |
|
| 2123 |
.. availability:: not WASI. |
| 2124 |
|
| 2125 |
|
| 2126 |
.. method:: socket.share(process_id) |
| 2127 |
|
| 2128 |
Duplicate a socket and prepare it for sharing with a target process. The |
| 2129 |
target process must be provided with *process_id*. The resulting bytes object |
| 2130 |
can then be passed to the target process using some form of interprocess |
| 2131 |
communication and the socket can be recreated there using :func:`fromshare`. |
| 2132 |
Once this method has been called, it is safe to close the socket since |
| 2133 |
the operating system has already duplicated it for the target process. |
| 2134 |
|
| 2135 |
.. availability:: Windows. |
| 2136 |
|
| 2137 |
.. versionadded:: 3.3 |
| 2138 |
|
| 2139 |
|
| 2140 |
Note that there are no methods :meth:`read` or :meth:`write`; use |
| 2141 |
:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead. |
| 2142 |
|
| 2143 |
Socket objects also have these (read-only) attributes that correspond to the |
| 2144 |
values given to the :class:`~socket.socket` constructor. |
| 2145 |
|
| 2146 |
|
| 2147 |
.. attribute:: socket.family |
| 2148 |
|
| 2149 |
The socket family. |
| 2150 |
|
| 2151 |
|
| 2152 |
.. attribute:: socket.type |
| 2153 |
|
| 2154 |
The socket type. |
| 2155 |
|
| 2156 |
|
| 2157 |
.. attribute:: socket.proto |
| 2158 |
|
| 2159 |
The socket protocol. |
| 2160 |
|
| 2161 |
|
| 2162 |
|
| 2163 |
.. _socket-timeouts: |
| 2164 |
|
| 2165 |
Notes on socket timeouts |
| 2166 |
------------------------ |
| 2167 |
|
| 2168 |
A socket object can be in one of three modes: blocking, non-blocking, or |
| 2169 |
timeout. Sockets are by default always created in blocking mode, but this |
| 2170 |
can be changed by calling :func:`setdefaulttimeout`. |
| 2171 |
|
| 2172 |
* In *blocking mode*, operations block until complete or the system returns |
| 2173 |
an error (such as connection timed out). |
| 2174 |
|
| 2175 |
* In *non-blocking mode*, operations fail (with an error that is unfortunately |
| 2176 |
system-dependent) if they cannot be completed immediately: functions from the |
| 2177 |
:mod:`select` module can be used to know when and whether a socket is available |
| 2178 |
for reading or writing. |
| 2179 |
|
| 2180 |
* In *timeout mode*, operations fail if they cannot be completed within the |
| 2181 |
timeout specified for the socket (they raise a :exc:`timeout` exception) |
| 2182 |
or if the system returns an error. |
| 2183 |
|
| 2184 |
.. note:: |
| 2185 |
At the operating system level, sockets in *timeout mode* are internally set |
| 2186 |
in non-blocking mode. Also, the blocking and timeout modes are shared between |
| 2187 |
file descriptors and socket objects that refer to the same network endpoint. |
| 2188 |
This implementation detail can have visible consequences if e.g. you decide |
| 2189 |
to use the :meth:`~socket.fileno` of a socket. |
| 2190 |
|
| 2191 |
Timeouts and the ``connect`` method |
| 2192 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 2193 |
|
| 2194 |
The :meth:`~socket.connect` operation is also subject to the timeout |
| 2195 |
setting, and in general it is recommended to call :meth:`~socket.settimeout` |
| 2196 |
before calling :meth:`~socket.connect` or pass a timeout parameter to |
| 2197 |
:meth:`create_connection`. However, the system network stack may also |
| 2198 |
return a connection timeout error of its own regardless of any Python socket |
| 2199 |
timeout setting. |
| 2200 |
|
| 2201 |
Timeouts and the ``accept`` method |
| 2202 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 2203 |
|
| 2204 |
If :func:`getdefaulttimeout` is not :const:`None`, sockets returned by |
| 2205 |
the :meth:`~socket.accept` method inherit that timeout. Otherwise, the |
| 2206 |
behaviour depends on settings of the listening socket: |
| 2207 |
|
| 2208 |
* if the listening socket is in *blocking mode* or in *timeout mode*, |
| 2209 |
the socket returned by :meth:`~socket.accept` is in *blocking mode*; |
| 2210 |
|
| 2211 |
* if the listening socket is in *non-blocking mode*, whether the socket |
| 2212 |
returned by :meth:`~socket.accept` is in blocking or non-blocking mode |
| 2213 |
is operating system-dependent. If you want to ensure cross-platform |
| 2214 |
behaviour, it is recommended you manually override this setting. |
| 2215 |
|
| 2216 |
|
| 2217 |
.. _socket-example: |
| 2218 |
|
| 2219 |
Example |
| 2220 |
------- |
| 2221 |
|
| 2222 |
Here are four minimal example programs using the TCP/IP protocol: a server that |
| 2223 |
echoes all data that it receives back (servicing only one client), and a client |
| 2224 |
using it. Note that a server must perform the sequence :func:`~socket.socket`, |
| 2225 |
:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly |
| 2226 |
repeating the :meth:`~socket.accept` to service more than one client), while a |
| 2227 |
client only needs the sequence :func:`~socket.socket`, :meth:`~socket.connect`. Also |
| 2228 |
note that the server does not :meth:`~socket.sendall`/:meth:`~socket.recv` on |
| 2229 |
the socket it is listening on but on the new socket returned by |
| 2230 |
:meth:`~socket.accept`. |
| 2231 |
|
| 2232 |
The first two examples support IPv4 only. :: |
| 2233 |
|
| 2234 |
# Echo server program |
| 2235 |
import socket |
| 2236 |
|
| 2237 |
HOST = '' # Symbolic name meaning all available interfaces |
| 2238 |
PORT = 50007 # Arbitrary non-privileged port |
| 2239 |
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: |
| 2240 |
s.bind((HOST, PORT)) |
| 2241 |
s.listen(1) |
| 2242 |
conn, addr = s.accept() |
| 2243 |
with conn: |
| 2244 |
print('Connected by', addr) |
| 2245 |
while True: |
| 2246 |
data = conn.recv(1024) |
| 2247 |
if not data: break |
| 2248 |
conn.sendall(data) |
| 2249 |
|
| 2250 |
:: |
| 2251 |
|
| 2252 |
# Echo client program |
| 2253 |
import socket |
| 2254 |
|
| 2255 |
HOST = 'daring.cwi.nl' # The remote host |
| 2256 |
PORT = 50007 # The same port as used by the server |
| 2257 |
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: |
| 2258 |
s.connect((HOST, PORT)) |
| 2259 |
s.sendall(b'Hello, world') |
| 2260 |
data = s.recv(1024) |
| 2261 |
print('Received', repr(data)) |
| 2262 |
|
| 2263 |
The next two examples are identical to the above two, but support both IPv4 and |
| 2264 |
IPv6. The server side will listen to the first address family available (it |
| 2265 |
should listen to both instead). On most of IPv6-ready systems, IPv6 will take |
| 2266 |
precedence and the server may not accept IPv4 traffic. The client side will try |
| 2267 |
to connect to all the addresses returned as a result of the name resolution, and |
| 2268 |
sends traffic to the first one connected successfully. :: |
| 2269 |
|
| 2270 |
# Echo server program |
| 2271 |
import socket |
| 2272 |
import sys |
| 2273 |
|
| 2274 |
HOST = None # Symbolic name meaning all available interfaces |
| 2275 |
PORT = 50007 # Arbitrary non-privileged port |
| 2276 |
s = None |
| 2277 |
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, |
| 2278 |
socket.SOCK_STREAM, 0, socket.AI_PASSIVE): |
| 2279 |
af, socktype, proto, canonname, sa = res |
| 2280 |
try: |
| 2281 |
s = socket.socket(af, socktype, proto) |
| 2282 |
except OSError as msg: |
| 2283 |
s = None |
| 2284 |
continue |
| 2285 |
try: |
| 2286 |
s.bind(sa) |
| 2287 |
s.listen(1) |
| 2288 |
except OSError as msg: |
| 2289 |
s.close() |
| 2290 |
s = None |
| 2291 |
continue |
| 2292 |
break |
| 2293 |
if s is None: |
| 2294 |
print('could not open socket') |
| 2295 |
sys.exit(1) |
| 2296 |
conn, addr = s.accept() |
| 2297 |
with conn: |
| 2298 |
print('Connected by', addr) |
| 2299 |
while True: |
| 2300 |
data = conn.recv(1024) |
| 2301 |
if not data: break |
| 2302 |
conn.send(data) |
| 2303 |
|
| 2304 |
:: |
| 2305 |
|
| 2306 |
# Echo client program |
| 2307 |
import socket |
| 2308 |
import sys |
| 2309 |
|
| 2310 |
HOST = 'daring.cwi.nl' # The remote host |
| 2311 |
PORT = 50007 # The same port as used by the server |
| 2312 |
s = None |
| 2313 |
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM): |
| 2314 |
af, socktype, proto, canonname, sa = res |
| 2315 |
try: |
| 2316 |
s = socket.socket(af, socktype, proto) |
| 2317 |
except OSError as msg: |
| 2318 |
s = None |
| 2319 |
continue |
| 2320 |
try: |
| 2321 |
s.connect(sa) |
| 2322 |
except OSError as msg: |
| 2323 |
s.close() |
| 2324 |
s = None |
| 2325 |
continue |
| 2326 |
break |
| 2327 |
if s is None: |
| 2328 |
print('could not open socket') |
| 2329 |
sys.exit(1) |
| 2330 |
with s: |
| 2331 |
s.sendall(b'Hello, world') |
| 2332 |
data = s.recv(1024) |
| 2333 |
print('Received', repr(data)) |
| 2334 |
|
| 2335 |
The next example shows how to write a very simple network sniffer with raw |
| 2336 |
sockets on Windows. The example requires administrator privileges to modify |
| 2337 |
the interface:: |
| 2338 |
|
| 2339 |
import socket |
| 2340 |
|
| 2341 |
# the public network interface |
| 2342 |
HOST = socket.gethostbyname(socket.gethostname()) |
| 2343 |
|
| 2344 |
# create a raw socket and bind it to the public interface |
| 2345 |
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP) |
| 2346 |
s.bind((HOST, 0)) |
| 2347 |
|
| 2348 |
# Include IP headers |
| 2349 |
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1) |
| 2350 |
|
| 2351 |
# receive all packets |
| 2352 |
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON) |
| 2353 |
|
| 2354 |
# receive a packet |
| 2355 |
print(s.recvfrom(65565)) |
| 2356 |
|
| 2357 |
# disabled promiscuous mode |
| 2358 |
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF) |
| 2359 |
|
| 2360 |
The next example shows how to use the socket interface to communicate to a CAN |
| 2361 |
network using the raw socket protocol. To use CAN with the broadcast |
| 2362 |
manager protocol instead, open a socket with:: |
| 2363 |
|
| 2364 |
socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM) |
| 2365 |
|
| 2366 |
After binding (:const:`CAN_RAW`) or connecting (:const:`CAN_BCM`) the socket, you |
| 2367 |
can use the :meth:`socket.send` and :meth:`socket.recv` operations (and |
| 2368 |
their counterparts) on the socket object as usual. |
| 2369 |
|
| 2370 |
This last example might require special privileges:: |
| 2371 |
|
| 2372 |
import socket |
| 2373 |
import struct |
| 2374 |
|
| 2375 |
|
| 2376 |
# CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>) |
| 2377 |
|
| 2378 |
can_frame_fmt = "=IB3x8s" |
| 2379 |
can_frame_size = struct.calcsize(can_frame_fmt) |
| 2380 |
|
| 2381 |
def build_can_frame(can_id, data): |
| 2382 |
can_dlc = len(data) |
| 2383 |
data = data.ljust(8, b'\x00') |
| 2384 |
return struct.pack(can_frame_fmt, can_id, can_dlc, data) |
| 2385 |
|
| 2386 |
def dissect_can_frame(frame): |
| 2387 |
can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame) |
| 2388 |
return (can_id, can_dlc, data[:can_dlc]) |
| 2389 |
|
| 2390 |
|
| 2391 |
# create a raw socket and bind it to the 'vcan0' interface |
| 2392 |
s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW) |
| 2393 |
s.bind(('vcan0',)) |
| 2394 |
|
| 2395 |
while True: |
| 2396 |
cf, addr = s.recvfrom(can_frame_size) |
| 2397 |
|
| 2398 |
print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf)) |
| 2399 |
|
| 2400 |
try: |
| 2401 |
s.send(cf) |
| 2402 |
except OSError: |
| 2403 |
print('Error sending CAN frame') |
| 2404 |
|
| 2405 |
try: |
| 2406 |
s.send(build_can_frame(0x01, b'\x01\x02\x03')) |
| 2407 |
except OSError: |
| 2408 |
print('Error sending CAN frame') |
| 2409 |
|
| 2410 |
Running an example several times with too small delay between executions, could |
| 2411 |
lead to this error:: |
| 2412 |
|
| 2413 |
OSError: [Errno 98] Address already in use |
| 2414 |
|
| 2415 |
This is because the previous execution has left the socket in a ``TIME_WAIT`` |
| 2416 |
state, and can't be immediately reused. |
| 2417 |
|
| 2418 |
There is a :mod:`!socket` flag to set, in order to prevent this, |
| 2419 |
:const:`socket.SO_REUSEADDR`:: |
| 2420 |
|
| 2421 |
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
| 2422 |
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) |
| 2423 |
s.bind((HOST, PORT)) |
| 2424 |
|
| 2425 |
the :data:`SO_REUSEADDR` flag tells the kernel to reuse a local socket in |
| 2426 |
``TIME_WAIT`` state, without waiting for its natural timeout to expire. |
| 2427 |
|
| 2428 |
|
| 2429 |
.. seealso:: |
| 2430 |
|
| 2431 |
For an introduction to socket programming (in C), see the following papers: |
| 2432 |
|
| 2433 |
- *An Introductory 4.3BSD Interprocess Communication Tutorial*, by Stuart Sechrest |
| 2434 |
|
| 2435 |
- *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Leffler et |
| 2436 |
al, |
| 2437 |
|
| 2438 |
both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections |
| 2439 |
PS1:7 and PS1:8). The platform-specific reference material for the various |
| 2440 |
socket-related system calls are also a valuable source of information on the |
| 2441 |
details of socket semantics. For Unix, refer to the manual pages; for Windows, |
| 2442 |
see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may |
| 2443 |
want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6. |