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