Debian Codegraph @

Doc/library/socket.rst

raw
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.