/Doc/library/socket.rst
ReStructuredText | 1375 lines | 968 code | 407 blank | 0 comment | 0 complexity | d2d54dd0a4d81ceced8def068e22aeaa MD5 | raw file
Possible License(s): BSD-3-Clause, 0BSD
1:mod:`socket` --- Low-level networking interface 2================================================ 3 4.. module:: socket 5 :synopsis: Low-level networking interface. 6 7 8This module provides access to the BSD *socket* interface. It is available on 9all modern Unix systems, Windows, MacOS, OS/2, and probably additional 10platforms. 11 12.. note:: 13 14 Some behavior may be platform dependent, since calls are made to the operating 15 system socket APIs. 16 17.. index:: object: socket 18 19The Python interface is a straightforward transliteration of the Unix system 20call and library interface for sockets to Python's object-oriented style: the 21:func:`socket` function returns a :dfn:`socket object` whose methods implement 22the various socket system calls. Parameter types are somewhat higher-level than 23in the C interface: as with :meth:`read` and :meth:`write` operations on Python 24files, buffer allocation on receive operations is automatic, and buffer length 25is implicit on send operations. 26 27 28.. seealso:: 29 30 Module :mod:`socketserver` 31 Classes that simplify writing network servers. 32 33 Module :mod:`ssl` 34 A TLS/SSL wrapper for socket objects. 35 36 37Socket families 38--------------- 39 40Depending on the system and the build options, various socket families 41are supported by this module. 42 43The address format required by a particular socket object is automatically 44selected based on the address family specified when the socket object was 45created. Socket addresses are represented as follows: 46 47- The address of an :const:`AF_UNIX` socket bound to a file system node 48 is represented as a string, using the file system encoding and the 49 ``'surrogateescape'`` error handler (see :pep:`383`). An address in 50 Linux's abstract namespace is returned as a :class:`bytes` object with 51 an initial null byte; note that sockets in this namespace can 52 communicate with normal file system sockets, so programs intended to 53 run on Linux may need to deal with both types of address. A string or 54 :class:`bytes` object can be used for either type of address when 55 passing it as an argument. 56 57 .. versionchanged:: 3.3 58 Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8 59 encoding. 60 61- A pair ``(host, port)`` is used for the :const:`AF_INET` address family, 62 where *host* is a string representing either a hostname in Internet domain 63 notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``, 64 and *port* is an integral port number. 65 66- For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo, 67 scopeid)`` is used, where *flowinfo* and *scopeid* represent the ``sin6_flowinfo`` 68 and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C. For 69 :mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for 70 backward compatibility. Note, however, omission of *scopeid* can cause problems 71 in manipulating scoped IPv6 addresses. 72 73- :const:`AF_NETLINK` sockets are represented as pairs ``(pid, groups)``. 74 75- Linux-only support for TIPC is available using the :const:`AF_TIPC` 76 address family. TIPC is an open, non-IP based networked protocol designed 77 for use in clustered computer environments. Addresses are represented by a 78 tuple, and the fields depend on the address type. The general tuple form is 79 ``(addr_type, v1, v2, v3 [, scope])``, where: 80 81 - *addr_type* is one of :const:`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`, 82 or :const:`TIPC_ADDR_ID`. 83 - *scope* is one of :const:`TIPC_ZONE_SCOPE`, :const:`TIPC_CLUSTER_SCOPE`, and 84 :const:`TIPC_NODE_SCOPE`. 85 - If *addr_type* is :const:`TIPC_ADDR_NAME`, then *v1* is the server type, *v2* is 86 the port identifier, and *v3* should be 0. 87 88 If *addr_type* is :const:`TIPC_ADDR_NAMESEQ`, then *v1* is the server type, *v2* 89 is the lower port number, and *v3* is the upper port number. 90 91 If *addr_type* is :const:`TIPC_ADDR_ID`, then *v1* is the node, *v2* is the 92 reference, and *v3* should be set to 0. 93 94 If *addr_type* is :const:`TIPC_ADDR_ID`, then *v1* is the node, *v2* is the 95 reference, and *v3* should be set to 0. 96 97- A tuple ``(interface, )`` is used for the :const:`AF_CAN` address family, 98 where *interface* is a string representing a network interface name like 99 ``'can0'``. The network interface name ``''`` can be used to receive packets 100 from all network interfaces of this family. 101 102- Certain other address families (:const:`AF_BLUETOOTH`, :const:`AF_PACKET`) 103 support specific representations. 104 105 .. XXX document them! 106 107For IPv4 addresses, two special forms are accepted instead of a host address: 108the empty string represents :const:`INADDR_ANY`, and the string 109``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. This behavior is not 110compatible with IPv6, therefore, you may want to avoid these if you intend 111to support IPv6 with your Python programs. 112 113If you use a hostname in the *host* portion of IPv4/v6 socket address, the 114program may show a nondeterministic behavior, as Python uses the first address 115returned from the DNS resolution. The socket address will be resolved 116differently into an actual IPv4/v6 address, depending on the results from DNS 117resolution and/or the host configuration. For deterministic behavior use a 118numeric address in *host* portion. 119 120All errors raise exceptions. The normal exceptions for invalid argument types 121and out-of-memory conditions can be raised; starting from Python 3.3, errors 122related to socket or address semantics raise :exc:`OSError` or one of its 123subclasses (they used to raise :exc:`socket.error`). 124 125Non-blocking mode is supported through :meth:`~socket.setblocking`. A 126generalization of this based on timeouts is supported through 127:meth:`~socket.settimeout`. 128 129 130Module contents 131--------------- 132 133The module :mod:`socket` exports the following constants and functions: 134 135 136.. exception:: error 137 138 A deprecated alias of :exc:`OSError`. 139 140 .. versionchanged:: 3.3 141 Following :pep:`3151`, this class was made an alias of :exc:`OSError`. 142 143 144.. exception:: herror 145 146 A subclass of :exc:`OSError`, this exception is raised for 147 address-related errors, i.e. for functions that use *h_errno* in the POSIX 148 C API, including :func:`gethostbyname_ex` and :func:`gethostbyaddr`. 149 The accompanying value is a pair ``(h_errno, string)`` representing an 150 error returned by a library call. *h_errno* is a numeric value, while 151 *string* represents the description of *h_errno*, as returned by the 152 :c:func:`hstrerror` C function. 153 154 .. versionchanged:: 3.3 155 This class was made a subclass of :exc:`OSError`. 156 157.. exception:: gaierror 158 159 A subclass of :exc:`OSError`, this exception is raised for 160 address-related errors by :func:`getaddrinfo` and :func:`getnameinfo`. 161 The accompanying value is a pair ``(error, string)`` representing an error 162 returned by a library call. *string* represents the description of 163 *error*, as returned by the :c:func:`gai_strerror` C function. The 164 numeric *error* value will match one of the :const:`EAI_\*` constants 165 defined in this module. 166 167 .. versionchanged:: 3.3 168 This class was made a subclass of :exc:`OSError`. 169 170.. exception:: timeout 171 172 A subclass of :exc:`OSError`, this exception is raised when a timeout 173 occurs on a socket which has had timeouts enabled via a prior call to 174 :meth:`~socket.settimeout` (or implicitly through 175 :func:`~socket.setdefaulttimeout`). The accompanying value is a string 176 whose value is currently always "timed out". 177 178 .. versionchanged:: 3.3 179 This class was made a subclass of :exc:`OSError`. 180 181.. data:: AF_UNIX 182 AF_INET 183 AF_INET6 184 185 These constants represent the address (and protocol) families, used for the 186 first argument to :func:`socket`. If the :const:`AF_UNIX` constant is not 187 defined then this protocol is unsupported. More constants may be available 188 depending on the system. 189 190 191.. data:: SOCK_STREAM 192 SOCK_DGRAM 193 SOCK_RAW 194 SOCK_RDM 195 SOCK_SEQPACKET 196 197 These constants represent the socket types, used for the second argument to 198 :func:`socket`. More constants may be available depending on the system. 199 (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be generally 200 useful.) 201 202.. data:: SOCK_CLOEXEC 203 SOCK_NONBLOCK 204 205 These two constants, if defined, can be combined with the socket types and 206 allow you to set some flags atomically (thus avoiding possible race 207 conditions and the need for separate calls). 208 209 .. seealso:: 210 211 `Secure File Descriptor Handling <http://udrepper.livejournal.com/20407.html>`_ 212 for a more thorough explanation. 213 214 Availability: Linux >= 2.6.27. 215 216 .. versionadded:: 3.2 217 218.. data:: SO_* 219 SOMAXCONN 220 MSG_* 221 SOL_* 222 SCM_* 223 IPPROTO_* 224 IPPORT_* 225 INADDR_* 226 IP_* 227 IPV6_* 228 EAI_* 229 AI_* 230 NI_* 231 TCP_* 232 233 Many constants of these forms, documented in the Unix documentation on sockets 234 and/or the IP protocol, are also defined in the socket module. They are 235 generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt` 236 methods of socket objects. In most cases, only those symbols that are defined 237 in the Unix header files are defined; for a few symbols, default values are 238 provided. 239 240.. data:: AF_CAN 241 PF_CAN 242 SOL_CAN_* 243 CAN_* 244 245 Many constants of these forms, documented in the Linux documentation, are 246 also defined in the socket module. 247 248 Availability: Linux >= 2.6.25. 249 250 .. versionadded:: 3.3 251 252 253.. data:: AF_RDS 254 PF_RDS 255 SOL_RDS 256 RDS_* 257 258 Many constants of these forms, documented in the Linux documentation, are 259 also defined in the socket module. 260 261 Availability: Linux >= 2.6.30. 262 263 .. versionadded:: 3.3 264 265 266.. data:: SIO_* 267 RCVALL_* 268 269 Constants for Windows' WSAIoctl(). The constants are used as arguments to the 270 :meth:`ioctl` method of socket objects. 271 272 273.. data:: TIPC_* 274 275 TIPC related constants, matching the ones exported by the C socket API. See 276 the TIPC documentation for more information. 277 278 279.. data:: has_ipv6 280 281 This constant contains a boolean value which indicates if IPv6 is supported on 282 this platform. 283 284 285.. function:: create_connection(address[, timeout[, source_address]]) 286 287 Connect to a TCP service listening on the Internet *address* (a 2-tuple 288 ``(host, port)``), and return the socket object. This is a higher-level 289 function than :meth:`socket.connect`: if *host* is a non-numeric hostname, 290 it will try to resolve it for both :data:`AF_INET` and :data:`AF_INET6`, 291 and then try to connect to all possible addresses in turn until a 292 connection succeeds. This makes it easy to write clients that are 293 compatible to both IPv4 and IPv6. 294 295 Passing the optional *timeout* parameter will set the timeout on the 296 socket instance before attempting to connect. If no *timeout* is 297 supplied, the global default timeout setting returned by 298 :func:`getdefaulttimeout` is used. 299 300 If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the 301 socket to bind to as its source address before connecting. If host or port 302 are '' or 0 respectively the OS default behavior will be used. 303 304 .. versionchanged:: 3.2 305 *source_address* was added. 306 307 .. versionchanged:: 3.2 308 support for the :keyword:`with` statement was added. 309 310 311.. function:: getaddrinfo(host, port, family=0, type=0, proto=0, flags=0) 312 313 Translate the *host*/*port* argument into a sequence of 5-tuples that contain 314 all the necessary arguments for creating a socket connected to that service. 315 *host* is a domain name, a string representation of an IPv4/v6 address 316 or ``None``. *port* is a string service name such as ``'http'``, a numeric 317 port number or ``None``. By passing ``None`` as the value of *host* 318 and *port*, you can pass ``NULL`` to the underlying C API. 319 320 The *family*, *type* and *proto* arguments can be optionally specified 321 in order to narrow the list of addresses returned. Passing zero as a 322 value for each of these arguments selects the full range of results. 323 The *flags* argument can be one or several of the ``AI_*`` constants, 324 and will influence how results are computed and returned. 325 For example, :const:`AI_NUMERICHOST` will disable domain name resolution 326 and will raise an error if *host* is a domain name. 327 328 The function returns a list of 5-tuples with the following structure: 329 330 ``(family, type, proto, canonname, sockaddr)`` 331 332 In these tuples, *family*, *type*, *proto* are all integers and are 333 meant to be passed to the :func:`socket` function. *canonname* will be 334 a string representing the canonical name of the *host* if 335 :const:`AI_CANONNAME` is part of the *flags* argument; else *canonname* 336 will be empty. *sockaddr* is a tuple describing a socket address, whose 337 format depends on the returned *family* (a ``(address, port)`` 2-tuple for 338 :const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for 339 :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect` 340 method. 341 342 The following example fetches address information for a hypothetical TCP 343 connection to ``www.python.org`` on port 80 (results may differ on your 344 system if IPv6 isn't enabled):: 345 346 >>> socket.getaddrinfo("www.python.org", 80, proto=socket.SOL_TCP) 347 [(2, 1, 6, '', ('82.94.164.162', 80)), 348 (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))] 349 350 .. versionchanged:: 3.2 351 parameters can now be passed as single keyword arguments. 352 353.. function:: getfqdn([name]) 354 355 Return a fully qualified domain name for *name*. If *name* is omitted or empty, 356 it is interpreted as the local host. To find the fully qualified name, the 357 hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the 358 host, if available. The first name which includes a period is selected. In 359 case no fully qualified domain name is available, the hostname as returned by 360 :func:`gethostname` is returned. 361 362 363.. function:: gethostbyname(hostname) 364 365 Translate a host name to IPv4 address format. The IPv4 address is returned as a 366 string, such as ``'100.50.200.5'``. If the host name is an IPv4 address itself 367 it is returned unchanged. See :func:`gethostbyname_ex` for a more complete 368 interface. :func:`gethostbyname` does not support IPv6 name resolution, and 369 :func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support. 370 371 372.. function:: gethostbyname_ex(hostname) 373 374 Translate a host name to IPv4 address format, extended interface. Return a 375 triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the primary 376 host name responding to the given *ip_address*, *aliaslist* is a (possibly 377 empty) list of alternative host names for the same address, and *ipaddrlist* is 378 a list of IPv4 addresses for the same interface on the same host (often but not 379 always a single address). :func:`gethostbyname_ex` does not support IPv6 name 380 resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual 381 stack support. 382 383 384.. function:: gethostname() 385 386 Return a string containing the hostname of the machine where the Python 387 interpreter is currently executing. 388 389 If you want to know the current machine's IP address, you may want to use 390 ``gethostbyname(gethostname())``. This operation assumes that there is a 391 valid address-to-host mapping for the host, and the assumption does not 392 always hold. 393 394 Note: :func:`gethostname` doesn't always return the fully qualified domain 395 name; use ``getfqdn()`` (see above). 396 397 398.. function:: gethostbyaddr(ip_address) 399 400 Return a triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the 401 primary host name responding to the given *ip_address*, *aliaslist* is a 402 (possibly empty) list of alternative host names for the same address, and 403 *ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same 404 host (most likely containing only a single address). To find the fully qualified 405 domain name, use the function :func:`getfqdn`. :func:`gethostbyaddr` supports 406 both IPv4 and IPv6. 407 408 409.. function:: getnameinfo(sockaddr, flags) 410 411 Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending 412 on the settings of *flags*, the result can contain a fully-qualified domain name 413 or numeric address representation in *host*. Similarly, *port* can contain a 414 string port name or a numeric port number. 415 416 417.. function:: getprotobyname(protocolname) 418 419 Translate an Internet protocol name (for example, ``'icmp'``) to a constant 420 suitable for passing as the (optional) third argument to the :func:`socket` 421 function. This is usually only needed for sockets opened in "raw" mode 422 (:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen 423 automatically if the protocol is omitted or zero. 424 425 426.. function:: getservbyname(servicename[, protocolname]) 427 428 Translate an Internet service name and protocol name to a port number for that 429 service. The optional protocol name, if given, should be ``'tcp'`` or 430 ``'udp'``, otherwise any protocol will match. 431 432 433.. function:: getservbyport(port[, protocolname]) 434 435 Translate an Internet port number and protocol name to a service name for that 436 service. The optional protocol name, if given, should be ``'tcp'`` or 437 ``'udp'``, otherwise any protocol will match. 438 439 440.. function:: socket([family[, type[, proto]]]) 441 442 Create a new socket using the given address family, socket type and protocol 443 number. The address family should be :const:`AF_INET` (the default), 444 :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The 445 socket type should be :const:`SOCK_STREAM` (the default), 446 :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_`` 447 constants. The protocol number is usually zero and may be omitted in that 448 case or :const:`CAN_RAW` in case the address family is :const:`AF_CAN`. 449 450 .. versionchanged:: 3.3 451 The AF_CAN family was added. 452 The AF_RDS family was added. 453 454 455.. function:: socketpair([family[, type[, proto]]]) 456 457 Build a pair of connected socket objects using the given address family, socket 458 type, and protocol number. Address family, socket type, and protocol number are 459 as for the :func:`socket` function above. The default family is :const:`AF_UNIX` 460 if defined on the platform; otherwise, the default is :const:`AF_INET`. 461 Availability: Unix. 462 463 .. versionchanged:: 3.2 464 The returned socket objects now support the whole socket API, rather 465 than a subset. 466 467 468.. function:: fromfd(fd, family, type[, proto]) 469 470 Duplicate the file descriptor *fd* (an integer as returned by a file object's 471 :meth:`fileno` method) and build a socket object from the result. Address 472 family, socket type and protocol number are as for the :func:`socket` function 473 above. The file descriptor should refer to a socket, but this is not checked --- 474 subsequent operations on the object may fail if the file descriptor is invalid. 475 This function is rarely needed, but can be used to get or set socket options on 476 a socket passed to a program as standard input or output (such as a server 477 started by the Unix inet daemon). The socket is assumed to be in blocking mode. 478 479 480.. function:: ntohl(x) 481 482 Convert 32-bit positive integers from network to host byte order. On machines 483 where the host byte order is the same as network byte order, this is a no-op; 484 otherwise, it performs a 4-byte swap operation. 485 486 487.. function:: ntohs(x) 488 489 Convert 16-bit positive integers from network to host byte order. On machines 490 where the host byte order is the same as network byte order, this is a no-op; 491 otherwise, it performs a 2-byte swap operation. 492 493 494.. function:: htonl(x) 495 496 Convert 32-bit positive integers from host to network byte order. On machines 497 where the host byte order is the same as network byte order, this is a no-op; 498 otherwise, it performs a 4-byte swap operation. 499 500 501.. function:: htons(x) 502 503 Convert 16-bit positive integers from host to network byte order. On machines 504 where the host byte order is the same as network byte order, this is a no-op; 505 otherwise, it performs a 2-byte swap operation. 506 507 508.. function:: inet_aton(ip_string) 509 510 Convert an IPv4 address from dotted-quad string format (for example, 511 '123.45.67.89') to 32-bit packed binary format, as a bytes object four characters in 512 length. This is useful when conversing with a program that uses the standard C 513 library and needs objects of type :c:type:`struct in_addr`, which is the C type 514 for the 32-bit packed binary this function returns. 515 516 :func:`inet_aton` also accepts strings with less than three dots; see the 517 Unix manual page :manpage:`inet(3)` for details. 518 519 If the IPv4 address string passed to this function is invalid, 520 :exc:`OSError` will be raised. Note that exactly what is valid depends on 521 the underlying C implementation of :c:func:`inet_aton`. 522 523 :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used 524 instead for IPv4/v6 dual stack support. 525 526 527.. function:: inet_ntoa(packed_ip) 528 529 Convert a 32-bit packed IPv4 address (a bytes object four characters in 530 length) to its standard dotted-quad string representation (for example, 531 '123.45.67.89'). This is useful when conversing with a program that uses the 532 standard C library and needs objects of type :c:type:`struct in_addr`, which 533 is the C type for the 32-bit packed binary data this function takes as an 534 argument. 535 536 If the byte sequence passed to this function is not exactly 4 bytes in 537 length, :exc:`OSError` will be raised. :func:`inet_ntoa` does not 538 support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual 539 stack support. 540 541 542.. function:: inet_pton(address_family, ip_string) 543 544 Convert an IP address from its family-specific string format to a packed, 545 binary format. :func:`inet_pton` is useful when a library or network protocol 546 calls for an object of type :c:type:`struct in_addr` (similar to 547 :func:`inet_aton`) or :c:type:`struct in6_addr`. 548 549 Supported values for *address_family* are currently :const:`AF_INET` and 550 :const:`AF_INET6`. If the IP address string *ip_string* is invalid, 551 :exc:`OSError` will be raised. Note that exactly what is valid depends on 552 both the value of *address_family* and the underlying implementation of 553 :c:func:`inet_pton`. 554 555 Availability: Unix (maybe not all platforms). 556 557 558.. function:: inet_ntop(address_family, packed_ip) 559 560 Convert a packed IP address (a bytes object of some number of characters) to its 561 standard, family-specific string representation (for example, ``'7.10.0.5'`` or 562 ``'5aef:2b::8'``). :func:`inet_ntop` is useful when a library or network protocol 563 returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`) 564 or :c:type:`struct in6_addr`. 565 566 Supported values for *address_family* are currently :const:`AF_INET` and 567 :const:`AF_INET6`. If the string *packed_ip* is not the correct length for the 568 specified address family, :exc:`ValueError` will be raised. A 569 :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`. 570 571 Availability: Unix (maybe not all platforms). 572 573 574.. 575 XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any 576 non-Unix platforms? The old (obsolete?) 4.2BSD form of the 577 interface, in which struct msghdr has no msg_control or 578 msg_controllen members, is not currently supported. 579 580.. function:: CMSG_LEN(length) 581 582 Return the total length, without trailing padding, of an ancillary 583 data item with associated data of the given *length*. This value 584 can often be used as the buffer size for :meth:`~socket.recvmsg` to 585 receive a single item of ancillary data, but :rfc:`3542` requires 586 portable applications to use :func:`CMSG_SPACE` and thus include 587 space for padding, even when the item will be the last in the 588 buffer. Raises :exc:`OverflowError` if *length* is outside the 589 permissible range of values. 590 591 Availability: most Unix platforms, possibly others. 592 593 .. versionadded:: 3.3 594 595 596.. function:: CMSG_SPACE(length) 597 598 Return the buffer size needed for :meth:`~socket.recvmsg` to 599 receive an ancillary data item with associated data of the given 600 *length*, along with any trailing padding. The buffer space needed 601 to receive multiple items is the sum of the :func:`CMSG_SPACE` 602 values for their associated data lengths. Raises 603 :exc:`OverflowError` if *length* is outside the permissible range 604 of values. 605 606 Note that some systems might support ancillary data without 607 providing this function. Also note that setting the buffer size 608 using the results of this function may not precisely limit the 609 amount of ancillary data that can be received, since additional 610 data may be able to fit into the padding area. 611 612 Availability: most Unix platforms, possibly others. 613 614 .. versionadded:: 3.3 615 616 617.. function:: getdefaulttimeout() 618 619 Return the default timeout in seconds (float) for new socket objects. A value 620 of ``None`` indicates that new socket objects have no timeout. When the socket 621 module is first imported, the default is ``None``. 622 623 624.. function:: setdefaulttimeout(timeout) 625 626 Set the default timeout in seconds (float) for new socket objects. When 627 the socket module is first imported, the default is ``None``. See 628 :meth:`~socket.settimeout` for possible values and their respective 629 meanings. 630 631 632.. function:: sethostname(name) 633 634 Set the machine's hostname to *name*. This will raise a 635 :exc:`OSError` if you don't have enough rights. 636 637 Availability: Unix. 638 639 .. versionadded:: 3.3 640 641 642.. function:: if_nameindex() 643 644 Return a list of network interface information 645 (index int, name string) tuples. 646 :exc:`OSError` if the system call fails. 647 648 Availability: Unix. 649 650 .. versionadded:: 3.3 651 652 653.. function:: if_nametoindex(if_name) 654 655 Return a network interface index number corresponding to an 656 interface name. 657 :exc:`OSError` if no interface with the given name exists. 658 659 Availability: Unix. 660 661 .. versionadded:: 3.3 662 663 664.. function:: if_indextoname(if_index) 665 666 Return a network interface name corresponding to a 667 interface index number. 668 :exc:`OSError` if no interface with the given index exists. 669 670 Availability: Unix. 671 672 .. versionadded:: 3.3 673 674 675.. data:: SocketType 676 677 This is a Python type object that represents the socket object type. It is the 678 same as ``type(socket(...))``. 679 680 681.. _socket-objects: 682 683Socket Objects 684-------------- 685 686Socket objects have the following methods. Except for :meth:`makefile` these 687correspond to Unix system calls applicable to sockets. 688 689 690.. method:: socket.accept() 691 692 Accept a connection. The socket must be bound to an address and listening for 693 connections. The return value is a pair ``(conn, address)`` where *conn* is a 694 *new* socket object usable to send and receive data on the connection, and 695 *address* is the address bound to the socket on the other end of the connection. 696 697 698.. method:: socket.bind(address) 699 700 Bind the socket to *address*. The socket must not already be bound. (The format 701 of *address* depends on the address family --- see above.) 702 703 704.. method:: socket.close() 705 706 Close the socket. All future operations on the socket object will fail. The 707 remote end will receive no more data (after queued data is flushed). Sockets are 708 automatically closed when they are garbage-collected. 709 710 .. note:: 711 :meth:`close()` releases the resource associated with a connection but 712 does not necessarily close the connection immediately. If you want 713 to close the connection in a timely fashion, call :meth:`shutdown()` 714 before :meth:`close()`. 715 716 717.. method:: socket.connect(address) 718 719 Connect to a remote socket at *address*. (The format of *address* depends on the 720 address family --- see above.) 721 722 723.. method:: socket.connect_ex(address) 724 725 Like ``connect(address)``, but return an error indicator instead of raising an 726 exception for errors returned by the C-level :c:func:`connect` call (other 727 problems, such as "host not found," can still raise exceptions). The error 728 indicator is ``0`` if the operation succeeded, otherwise the value of the 729 :c:data:`errno` variable. This is useful to support, for example, asynchronous 730 connects. 731 732 733.. method:: socket.detach() 734 735 Put the socket object into closed state without actually closing the 736 underlying file descriptor. The file descriptor is returned, and can 737 be reused for other purposes. 738 739 .. versionadded:: 3.2 740 741 742.. method:: socket.fileno() 743 744 Return the socket's file descriptor (a small integer). This is useful with 745 :func:`select.select`. 746 747 Under Windows the small integer returned by this method cannot be used where a 748 file descriptor can be used (such as :func:`os.fdopen`). Unix does not have 749 this limitation. 750 751 752.. method:: socket.getpeername() 753 754 Return the remote address to which the socket is connected. This is useful to 755 find out the port number of a remote IPv4/v6 socket, for instance. (The format 756 of the address returned depends on the address family --- see above.) On some 757 systems this function is not supported. 758 759 760.. method:: socket.getsockname() 761 762 Return the socket's own address. This is useful to find out the port number of 763 an IPv4/v6 socket, for instance. (The format of the address returned depends on 764 the address family --- see above.) 765 766 767.. method:: socket.getsockopt(level, optname[, buflen]) 768 769 Return the value of the given socket option (see the Unix man page 770 :manpage:`getsockopt(2)`). The needed symbolic constants (:const:`SO_\*` etc.) 771 are defined in this module. If *buflen* is absent, an integer option is assumed 772 and its integer value is returned by the function. If *buflen* is present, it 773 specifies the maximum length of the buffer used to receive the option in, and 774 this buffer is returned as a bytes object. It is up to the caller to decode the 775 contents of the buffer (see the optional built-in module :mod:`struct` for a way 776 to decode C structures encoded as byte strings). 777 778 779.. method:: socket.gettimeout() 780 781 Return the timeout in seconds (float) associated with socket operations, 782 or ``None`` if no timeout is set. This reflects the last call to 783 :meth:`setblocking` or :meth:`settimeout`. 784 785 786.. method:: socket.ioctl(control, option) 787 788 :platform: Windows 789 790 The :meth:`ioctl` method is a limited interface to the WSAIoctl system 791 interface. Please refer to the `Win32 documentation 792 <http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more 793 information. 794 795 On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl` 796 functions may be used; they accept a socket object as their first argument. 797 798.. method:: socket.listen(backlog) 799 800 Listen for connections made to the socket. The *backlog* argument specifies the 801 maximum number of queued connections and should be at least 0; the maximum value 802 is system-dependent (usually 5), the minimum value is forced to 0. 803 804 805.. method:: socket.makefile(mode='r', buffering=None, *, encoding=None, \ 806 errors=None, newline=None) 807 808 .. index:: single: I/O control; buffering 809 810 Return a :term:`file object` associated with the socket. The exact returned 811 type depends on the arguments given to :meth:`makefile`. These arguments are 812 interpreted the same way as by the built-in :func:`open` function. 813 814 Closing the file object won't close the socket unless there are no remaining 815 references to the socket. The socket must be in blocking mode; it can have 816 a timeout, but the file object's internal buffer may end up in a inconsistent 817 state if a timeout occurs. 818 819 .. note:: 820 821 On Windows, the file-like object created by :meth:`makefile` cannot be 822 used where a file object with a file descriptor is expected, such as the 823 stream arguments of :meth:`subprocess.Popen`. 824 825 826.. method:: socket.recv(bufsize[, flags]) 827 828 Receive data from the socket. The return value is a bytes object representing the 829 data received. The maximum amount of data to be received at once is specified 830 by *bufsize*. See the Unix manual page :manpage:`recv(2)` for the meaning of 831 the optional argument *flags*; it defaults to zero. 832 833 .. note:: 834 835 For best match with hardware and network realities, the value of *bufsize* 836 should be a relatively small power of 2, for example, 4096. 837 838 839.. method:: socket.recvfrom(bufsize[, flags]) 840 841 Receive data from the socket. The return value is a pair ``(bytes, address)`` 842 where *bytes* is a bytes object representing the data received and *address* is the 843 address of the socket sending the data. See the Unix manual page 844 :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults 845 to zero. (The format of *address* depends on the address family --- see above.) 846 847 848.. method:: socket.recvmsg(bufsize[, ancbufsize[, flags]]) 849 850 Receive normal data (up to *bufsize* bytes) and ancillary data from 851 the socket. The *ancbufsize* argument sets the size in bytes of 852 the internal buffer used to receive the ancillary data; it defaults 853 to 0, meaning that no ancillary data will be received. Appropriate 854 buffer sizes for ancillary data can be calculated using 855 :func:`CMSG_SPACE` or :func:`CMSG_LEN`, and items which do not fit 856 into the buffer might be truncated or discarded. The *flags* 857 argument defaults to 0 and has the same meaning as for 858 :meth:`recv`. 859 860 The return value is a 4-tuple: ``(data, ancdata, msg_flags, 861 address)``. The *data* item is a :class:`bytes` object holding the 862 non-ancillary data received. The *ancdata* item is a list of zero 863 or more tuples ``(cmsg_level, cmsg_type, cmsg_data)`` representing 864 the ancillary data (control messages) received: *cmsg_level* and 865 *cmsg_type* are integers specifying the protocol level and 866 protocol-specific type respectively, and *cmsg_data* is a 867 :class:`bytes` object holding the associated data. The *msg_flags* 868 item is the bitwise OR of various flags indicating conditions on 869 the received message; see your system documentation for details. 870 If the receiving socket is unconnected, *address* is the address of 871 the sending socket, if available; otherwise, its value is 872 unspecified. 873 874 On some systems, :meth:`sendmsg` and :meth:`recvmsg` can be used to 875 pass file descriptors between processes over an :const:`AF_UNIX` 876 socket. When this facility is used (it is often restricted to 877 :const:`SOCK_STREAM` sockets), :meth:`recvmsg` will return, in its 878 ancillary data, items of the form ``(socket.SOL_SOCKET, 879 socket.SCM_RIGHTS, fds)``, where *fds* is a :class:`bytes` object 880 representing the new file descriptors as a binary array of the 881 native C :c:type:`int` type. If :meth:`recvmsg` raises an 882 exception after the system call returns, it will first attempt to 883 close any file descriptors received via this mechanism. 884 885 Some systems do not indicate the truncated length of ancillary data 886 items which have been only partially received. If an item appears 887 to extend beyond the end of the buffer, :meth:`recvmsg` will issue 888 a :exc:`RuntimeWarning`, and will return the part of it which is 889 inside the buffer provided it has not been truncated before the 890 start of its associated data. 891 892 On systems which support the :const:`SCM_RIGHTS` mechanism, the 893 following function will receive up to *maxfds* file descriptors, 894 returning the message data and a list containing the descriptors 895 (while ignoring unexpected conditions such as unrelated control 896 messages being received). See also :meth:`sendmsg`. :: 897 898 import socket, array 899 900 def recv_fds(sock, msglen, maxfds): 901 fds = array.array("i") # Array of ints 902 msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize)) 903 for cmsg_level, cmsg_type, cmsg_data in ancdata: 904 if (cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS): 905 # Append data, ignoring any truncated integers at the end. 906 fds.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)]) 907 return msg, list(fds) 908 909 Availability: most Unix platforms, possibly others. 910 911 .. versionadded:: 3.3 912 913 914.. method:: socket.recvmsg_into(buffers[, ancbufsize[, flags]]) 915 916 Receive normal data and ancillary data from the socket, behaving as 917 :meth:`recvmsg` would, but scatter the non-ancillary data into a 918 series of buffers instead of returning a new bytes object. The 919 *buffers* argument must be an iterable of objects that export 920 writable buffers (e.g. :class:`bytearray` objects); these will be 921 filled with successive chunks of the non-ancillary data until it 922 has all been written or there are no more buffers. The operating 923 system may set a limit (:func:`~os.sysconf` value ``SC_IOV_MAX``) 924 on the number of buffers that can be used. The *ancbufsize* and 925 *flags* arguments have the same meaning as for :meth:`recvmsg`. 926 927 The return value is a 4-tuple: ``(nbytes, ancdata, msg_flags, 928 address)``, where *nbytes* is the total number of bytes of 929 non-ancillary data written into the buffers, and *ancdata*, 930 *msg_flags* and *address* are the same as for :meth:`recvmsg`. 931 932 Example:: 933 934 >>> import socket 935 >>> s1, s2 = socket.socketpair() 936 >>> b1 = bytearray(b'----') 937 >>> b2 = bytearray(b'0123456789') 938 >>> b3 = bytearray(b'--------------') 939 >>> s1.send(b'Mary had a little lamb') 940 22 941 >>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3]) 942 (22, [], 0, None) 943 >>> [b1, b2, b3] 944 [bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')] 945 946 Availability: most Unix platforms, possibly others. 947 948 .. versionadded:: 3.3 949 950 951.. method:: socket.recvfrom_into(buffer[, nbytes[, flags]]) 952 953 Receive data from the socket, writing it into *buffer* instead of creating a 954 new bytestring. The return value is a pair ``(nbytes, address)`` where *nbytes* is 955 the number of bytes received and *address* is the address of the socket sending 956 the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the 957 optional argument *flags*; it defaults to zero. (The format of *address* 958 depends on the address family --- see above.) 959 960 961.. method:: socket.recv_into(buffer[, nbytes[, flags]]) 962 963 Receive up to *nbytes* bytes from the socket, storing the data into a buffer 964 rather than creating a new bytestring. If *nbytes* is not specified (or 0), 965 receive up to the size available in the given buffer. Returns the number of 966 bytes received. See the Unix manual page :manpage:`recv(2)` for the meaning 967 of the optional argument *flags*; it defaults to zero. 968 969 970.. method:: socket.send(bytes[, flags]) 971 972 Send data to the socket. The socket must be connected to a remote socket. The 973 optional *flags* argument has the same meaning as for :meth:`recv` above. 974 Returns the number of bytes sent. Applications are responsible for checking that 975 all data has been sent; if only some of the data was transmitted, the 976 application needs to attempt delivery of the remaining data. 977 978 979.. method:: socket.sendall(bytes[, flags]) 980 981 Send data to the socket. The socket must be connected to a remote socket. The 982 optional *flags* argument has the same meaning as for :meth:`recv` above. 983 Unlike :meth:`send`, this method continues to send data from *bytes* until 984 either all data has been sent or an error occurs. ``None`` is returned on 985 success. On error, an exception is raised, and there is no way to determine how 986 much data, if any, was successfully sent. 987 988 989.. method:: socket.sendto(bytes[, flags], address) 990 991 Send data to the socket. The socket should not be connected to a remote socket, 992 since the destination socket is specified by *address*. The optional *flags* 993 argument has the same meaning as for :meth:`recv` above. Return the number of 994 bytes sent. (The format of *address* depends on the address family --- see 995 above.) 996 997 998.. method:: socket.sendmsg(buffers[, ancdata[, flags[, address]]]) 999 1000 Send normal and ancillary data to the socket, gathering the 1001 non-ancillary data from a series of buffers and concatenating it 1002 into a single message. The *buffers* argument specifies the 1003 non-ancillary data as an iterable of buffer-compatible objects 1004 (e.g. :class:`bytes` objects); the operating system may set a limit 1005 (:func:`~os.sysconf` value ``SC_IOV_MAX``) on the number of buffers 1006 that can be used. The *ancdata* argument specifies the ancillary 1007 data (control messages) as an iterable of zero or more tuples 1008 ``(cmsg_level, cmsg_type, cmsg_data)``, where *cmsg_level* and 1009 *cmsg_type* are integers specifying the protocol level and 1010 protocol-specific type respectively, and *cmsg_data* is a 1011 buffer-compatible object holding the associated data. Note that 1012 some systems (in particular, systems without :func:`CMSG_SPACE`) 1013 might support sending only one control message per call. The 1014 *flags* argument defaults to 0 and has the same meaning as for 1015 :meth:`send`. If *address* is supplied and not ``None``, it sets a 1016 destination address for the message. The return value is the 1017 number of bytes of non-ancillary data sent. 1018 1019 The following function sends the list of file descriptors *fds* 1020 over an :const:`AF_UNIX` socket, on systems which support the 1021 :const:`SCM_RIGHTS` mechanism. See also :meth:`recvmsg`. :: 1022 1023 import socket, array 1024 1025 def send_fds(sock, msg, fds): 1026 return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))]) 1027 1028 Availability: most Unix platforms, possibly others. 1029 1030 .. versionadded:: 3.3 1031 1032 1033.. method:: socket.setblocking(flag) 1034 1035 Set blocking or non-blocking mode of the socket: if *flag* is false, the 1036 socket is set to non-blocking, else to blocking mode. 1037 1038 This method is a shorthand for certain :meth:`~socket.settimeout` calls: 1039 1040 * ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)`` 1041 1042 * ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0.0)`` 1043 1044 1045.. method:: socket.settimeout(value) 1046 1047 Set a timeout on blocking socket operations. The *value* argument can be a 1048 nonnegative floating point number expressing seconds, or ``None``. 1049 If a non-zero value is given, subsequent socket operations will raise a 1050 :exc:`timeout` exception if the timeout period *value* has elapsed before 1051 the operation has completed. If zero is given, the socket is put in 1052 non-blocking mode. If ``None`` is given, the socket is put in blocking mode. 1053 1054 For further information, please consult the :ref:`notes on socket timeouts <socket-timeouts>`. 1055 1056 1057.. method:: socket.setsockopt(level, optname, value) 1058 1059 .. index:: module: struct 1060 1061 Set the value of the given socket option (see the Unix manual page 1062 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the 1063 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a 1064 bytes object representing a buffer. In the latter case it is up to the caller to 1065 ensure that the bytestring contains the proper bits (see the optional built-in 1066 module :mod:`struct` for a way to encode C structures as bytestrings). 1067 1068 1069.. method:: socket.shutdown(how) 1070 1071 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD`, 1072 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends 1073 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives are 1074 disallowed. Depending on the platform, shutting down one half of the connection 1075 can also close the opposite half (e.g. on Mac OS X, ``shutdown(SHUT_WR)`` does 1076 not allow further reads on the other end of the connection). 1077 1078Note that there are no methods :meth:`read` or :meth:`write`; use 1079:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead. 1080 1081Socket objects also have these (read-only) attributes that correspond to the 1082values given to the :class:`socket` constructor. 1083 1084 1085.. attribute:: socket.family 1086 1087 The socket family. 1088 1089 1090.. attribute:: socket.type 1091 1092 The socket type. 1093 1094 1095.. attribute:: socket.proto 1096 1097 The socket protocol. 1098 1099 1100 1101.. _socket-timeouts: 1102 1103Notes on socket timeouts 1104------------------------ 1105 1106A socket object can be in one of three modes: blocking, non-blocking, or 1107timeout. Sockets are by default always created in blocking mode, but this 1108can be changed by calling :func:`setdefaulttimeout`. 1109 1110* In *blocking mode*, operations block until complete or the system returns 1111 an error (such as connection timed out). 1112 1113* In *non-blocking mode*, operations fail (with an error that is unfortunately 1114 system-dependent) if they cannot be completed immediately: functions from the 1115 :mod:`select` can be used to know when and whether a socket is available for 1116 reading or writing. 1117 1118* In *timeout mode*, operations fail if they cannot be completed within the 1119 timeout specified for the socket (they raise a :exc:`timeout` exception) 1120 or if the system returns an error. 1121 1122.. note:: 1123 At the operating system level, sockets in *timeout mode* are internally set 1124 in non-blocking mode. Also, the blocking and timeout modes are shared between 1125 file descriptors and socket objects that refer to the same network endpoint. 1126 This implementation detail can have visible consequences if e.g. you decide 1127 to use the :meth:`~socket.fileno()` of a socket. 1128 1129Timeouts and the ``connect`` method 1130^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1131 1132The :meth:`~socket.connect` operation is also subject to the timeout 1133setting, and in general it is recommended to call :meth:`~socket.settimeout` 1134before calling :meth:`~socket.connect` or pass a timeout parameter to 1135:meth:`create_connection`. However, the system network stack may also 1136return a connection timeout error of its own regardless of any Python socket 1137timeout setting. 1138 1139Timeouts and the ``accept`` method 1140^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1141 1142If :func:`getdefaulttimeout` is not :const:`None`, sockets returned by 1143the :meth:`~socket.accept` method inherit that timeout. Otherwise, the 1144behaviour depends on settings of the listening socket: 1145 1146* if the listening socket is in *blocking mode* or in *timeout mode*, 1147 the socket returned by :meth:`~socket.accept` is in *blocking mode*; 1148 1149* if the listening socket is in *non-blocking mode*, whether the socket 1150 returned by :meth:`~socket.accept` is in blocking or non-blocking mode 1151 is operating system-dependent. If you want to ensure cross-platform 1152 behaviour, it is recommended you manually override this setting. 1153 1154 1155.. _socket-example: 1156 1157Example 1158------- 1159 1160Here are four minimal example programs using the TCP/IP protocol: a server that 1161echoes all data that it receives back (servicing only one client), and a client 1162using it. Note that a server must perform the sequence :func:`socket`, 1163:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly 1164repeating the :meth:`~socket.accept` to service more than one client), while a 1165client only needs the sequence :func:`socket`, :meth:`~socket.connect`. Also 1166note that the server does not :meth:`~socket.send`/:meth:`~socket.recv` on the 1167socket it is listening on but on the new socket returned by 1168:meth:`~socket.accept`. 1169 1170The first two examples support IPv4 only. :: 1171 1172 # Echo server program 1173 import socket 1174 1175 HOST = '' # Symbolic name meaning all available interfaces 1176 PORT = 50007 # Arbitrary non-privileged port 1177 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) 1178 s.bind((HOST, PORT)) 1179 s.listen(1) 1180 conn, addr = s.accept() 1181 print('Connected by', addr) 1182 while True: 1183 data = conn.recv(1024) 1184 if not data: break 1185 conn.send(data) 1186 conn.close() 1187 1188:: 1189 1190 # Echo client program 1191 import socket 1192 1193 HOST = 'daring.cwi.nl' # The remote host 1194 PORT = 50007 # The same port as used by the server 1195 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) 1196 s.connect((HOST, PORT)) 1197 s.send(b'Hello, world') 1198 data = s.recv(1024) 1199 s.close() 1200 print('Received', repr(data)) 1201 1202The next two examples are identical to the above two, but support both IPv4 and 1203IPv6. The server side will listen to the first address family available (it 1204should listen to both instead). On most of IPv6-ready systems, IPv6 will take 1205precedence and the server may not accept IPv4 traffic. The client side will try 1206to connect to the all addresses returned as a result of the name resolution, and 1207sends traffic to the first one connected successfully. :: 1208 1209 # Echo server program 1210 import socket 1211 import sys 1212 1213 HOST = None # Symbolic name meaning all available interfaces 1214 PORT = 50007 # Arbitrary non-privileged port 1215 s = None 1216 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, 1217 socket.SOCK_STREAM, 0, socket.AI_PASSIVE): 1218 af, socktype, proto, canonname, sa = res 1219 try: 1220 s = socket.socket(af, socktype, proto) 1221 except OSError as msg: 1222 s = None 1223 continue 1224 try: 1225 s.bind(sa) 1226 s.listen(1) 1227 except OSError as msg: 1228 s.close() 1229 s = None 1230 continue 1231 break 1232 if s is None: 1233 print('could not open socket') 1234 sys.exit(1) 1235 conn, addr = s.accept() 1236 print('Connected by', addr) 1237 while True: 1238 data = conn.recv(1024) 1239 if not data: break 1240 conn.send(data) 1241 conn.close() 1242 1243:: 1244 1245 # Echo client program 1246 import socket 1247 import sys 1248 1249 HOST = 'daring.cwi.nl' # The remote host 1250 PORT = 50007 # The same port as used by the server 1251 s = None 1252 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM): 1253 af, socktype, proto, canonname, sa = res 1254 try: 1255 s = socket.socket(af, socktype, proto) 1256 except OSError as msg: 1257 s = None 1258 continue 1259 try: 1260 s.connect(sa) 1261 except OSError as msg: 1262 s.close() 1263 s = None 1264 continue 1265 break 1266 if s is None: 1267 print('could not open socket') 1268 sys.exit(1) 1269 s.send(b'Hello, world') 1270 data = s.recv(1024) 1271 s.close() 1272 print('Received', repr(data)) 1273 1274 1275The next example shows how to write a very simple network sniffer with raw 1276sockets on Windows. The example requires administrator privileges to modify 1277the interface:: 1278 1279 import socket 1280 1281 # the public network interface 1282 HOST = socket.gethostbyname(socket.gethostname()) 1283 1284 # create a raw socket and bind it to the public interface 1285 s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP) 1286 s.bind((HOST, 0)) 1287 1288 # Include IP headers 1289 s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1) 1290 1291 # receive all packages 1292 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON) 1293 1294 # receive a package 1295 print(s.recvfrom(65565)) 1296 1297 # disabled promiscuous mode 1298 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF) 1299 1300The last example shows how to use the socket interface to communicate to a CAN 1301network. This example might require special priviledge:: 1302 1303 import socket 1304 import struct 1305 1306 1307 # CAN frame packing/unpacking (see `struct can_frame` in <linux/can.h>) 1308 1309 can_frame_fmt = "=IB3x8s" 1310 can_frame_size = struct.calcsize(can_frame_fmt) 1311 1312 def build_can_frame(can_id, data): 1313 can_dlc = len(data) 1314 data = data.ljust(8, b'\x00') 1315 return struct.pack(can_frame_fmt, can_id, can_dlc, data) 1316 1317 def dissect_can_frame(frame): 1318 can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame) 1319 return (can_id, can_dlc, data[:can_dlc]) 1320 1321 1322 # create a raw socket and bind it to the `vcan0` interface 1323 s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW) 1324 s.bind(('vcan0',)) 1325 1326 while True: 1327 cf, addr = s.recvfrom(can_frame_size) 1328 1329 print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf)) 1330 1331 try: 1332 s.send(cf) 1333 except OSError: 1334 print('Error sending CAN frame') 1335 1336 try: 1337 s.send(build_can_frame(0x01, b'\x01\x02\x03')) 1338 except OSError: 1339 print('Error sending CAN frame') 1340 1341Running an example several times with too small delay between executions, could 1342lead to this error:: 1343 1344 OSError: [Errno 98] Address already in use 1345 1346This is because the previous execution has left the socket in a ``TIME_WAIT`` 1347state, and can't be immediately reused. 1348 1349There is a :mod:`socket` flag to set, in order to prevent this, 1350:data:`socket.SO_REUSEADDR`:: 1351 1352 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) 1353 s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) 1354 s.bind((HOST, PORT)) 1355 1356the :data:`SO_REUSEADDR` flag tells the kernel to reuse a local socket in 1357``TIME_WAIT`` state, without waiting for its natural timeout to expire. 1358 1359 1360.. seealso:: 1361 1362 For an introduction to socket programming (in C), see the following papers: 1363 1364 - *An Introductory 4.3BSD Interprocess Communication Tutorial*, by Stuart Sechrest 1365 1366 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Leffler et 1367 al, 1368 1369 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections 1370 PS1:7 and PS1:8). The platform-specific reference material for the various 1371 socket-related system calls are also a valuable source of information on the 1372 details of socket semantics. For Unix, refer to the manual pages; for Windows, 1373 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may 1374 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6. 1375