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