Left: | ||
Right: |
OLD | NEW |
---|---|
1 :mod:`socket` --- Low-level networking interface | 1 :mod:`socket` --- Low-level networking interface |
2 ================================================ | 2 ================================================ |
3 | 3 |
4 .. module:: socket | 4 .. module:: socket |
5 :synopsis: Low-level networking interface. | 5 :synopsis: Low-level networking interface. |
6 | 6 |
7 | 7 |
8 This module provides access to the BSD *socket* interface. It is available on | 8 This module provides access to the BSD *socket* interface. It is available on |
9 all modern Unix systems, Windows, MacOS, and probably additional platforms. | 9 all modern Unix systems, Windows, MacOS, and probably additional platforms. |
10 | 10 |
(...skipping 28 matching lines...) Expand all Loading... | |
39 Depending on the system and the build options, various socket families | 39 Depending on the system and the build options, various socket families |
40 are supported by this module. | 40 are supported by this module. |
41 | 41 |
42 The address format required by a particular socket object is automatically | 42 The address format required by a particular socket object is automatically |
43 selected based on the address family specified when the socket object was | 43 selected based on the address family specified when the socket object was |
44 created. Socket addresses are represented as follows: | 44 created. Socket addresses are represented as follows: |
45 | 45 |
46 - The address of an :const:`AF_UNIX` socket bound to a file system node | 46 - The address of an :const:`AF_UNIX` socket bound to a file system node |
47 is represented as a string, using the file system encoding and the | 47 is represented as a string, using the file system encoding and the |
48 ``'surrogateescape'`` error handler (see :pep:`383`). An address in | 48 ``'surrogateescape'`` error handler (see :pep:`383`). An address in |
49 Linux's abstract namespace is returned as a :class:`bytes` object with | 49 Linux's abstract namespace is returned as a :term:`bytes-like object` with |
50 an initial null byte; note that sockets in this namespace can | 50 an initial null byte; note that sockets in this namespace can |
51 communicate with normal file system sockets, so programs intended to | 51 communicate with normal file system sockets, so programs intended to |
52 run on Linux may need to deal with both types of address. A string or | 52 run on Linux may need to deal with both types of address. A string or |
53 :class:`bytes` object can be used for either type of address when | 53 bytes-like object can be used for either type of address when |
54 passing it as an argument. | 54 passing it as an argument. |
55 | 55 |
56 .. versionchanged:: 3.3 | 56 .. versionchanged:: 3.3 |
57 Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8 | 57 Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8 |
58 encoding. | 58 encoding. |
59 | 59 |
60 .. versionchanged: 3.5 | |
61 Writable :term:`bytes-like object` is now accepted. | |
62 | |
60 - A pair ``(host, port)`` is used for the :const:`AF_INET` address family, | 63 - A pair ``(host, port)`` is used for the :const:`AF_INET` address family, |
61 where *host* is a string representing either a hostname in Internet domain | 64 where *host* is a string representing either a hostname in Internet domain |
62 notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``, | 65 notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``, |
63 and *port* is an integer. | 66 and *port* is an integer. |
64 | 67 |
65 - For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo, | 68 - For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo, |
66 scopeid)`` is used, where *flowinfo* and *scopeid* represent the ``sin6_flowin fo`` | 69 scopeid)`` is used, where *flowinfo* and *scopeid* represent the ``sin6_flowin fo`` |
67 and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C. For | 70 and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C. For |
68 :mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for | 71 :mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for |
69 backward compatibility. Note, however, omission of *scopeid* can cause proble ms | 72 backward compatibility. Note, however, omission of *scopeid* can cause proble ms |
(...skipping 532 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
602 If the IPv4 address string passed to this function is invalid, | 605 If the IPv4 address string passed to this function is invalid, |
603 :exc:`OSError` will be raised. Note that exactly what is valid depends on | 606 :exc:`OSError` will be raised. Note that exactly what is valid depends on |
604 the underlying C implementation of :c:func:`inet_aton`. | 607 the underlying C implementation of :c:func:`inet_aton`. |
605 | 608 |
606 :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used | 609 :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used |
607 instead for IPv4/v6 dual stack support. | 610 instead for IPv4/v6 dual stack support. |
608 | 611 |
609 | 612 |
610 .. function:: inet_ntoa(packed_ip) | 613 .. function:: inet_ntoa(packed_ip) |
611 | 614 |
612 Convert a 32-bit packed IPv4 address (a bytes object four characters in | 615 Convert a 32-bit packed IPv4 address (a :term:`bytes-like object` four |
613 length) to its standard dotted-quad string representation (for example, | 616 characters in length) to its standard dotted-quad string representation (for example, |
Martin Panter
2015/03/20 02:41:08
four bytes in length
storchaka
2015/03/20 07:47:34
Done.
| |
614 '123.45.67.89'). This is useful when conversing with a program that uses the | 617 '123.45.67.89'). This is useful when conversing with a program that uses the |
615 standard C library and needs objects of type :c:type:`struct in_addr`, which | 618 standard C library and needs objects of type :c:type:`struct in_addr`, which |
616 is the C type for the 32-bit packed binary data this function takes as an | 619 is the C type for the 32-bit packed binary data this function takes as an |
617 argument. | 620 argument. |
618 | 621 |
619 If the byte sequence passed to this function is not exactly 4 bytes in | 622 If the byte sequence passed to this function is not exactly 4 bytes in |
620 length, :exc:`OSError` will be raised. :func:`inet_ntoa` does not | 623 length, :exc:`OSError` will be raised. :func:`inet_ntoa` does not |
621 support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual | 624 support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual |
622 stack support. | 625 stack support. |
626 | |
627 .. versionchanged: 3.5 | |
628 Writable :term:`bytes-like object` is now accepted. | |
623 | 629 |
624 | 630 |
625 .. function:: inet_pton(address_family, ip_string) | 631 .. function:: inet_pton(address_family, ip_string) |
626 | 632 |
627 Convert an IP address from its family-specific string format to a packed, | 633 Convert an IP address from its family-specific string format to a packed, |
628 binary format. :func:`inet_pton` is useful when a library or network protocol | 634 binary format. :func:`inet_pton` is useful when a library or network protocol |
629 calls for an object of type :c:type:`struct in_addr` (similar to | 635 calls for an object of type :c:type:`struct in_addr` (similar to |
630 :func:`inet_aton`) or :c:type:`struct in6_addr`. | 636 :func:`inet_aton`) or :c:type:`struct in6_addr`. |
631 | 637 |
632 Supported values for *address_family* are currently :const:`AF_INET` and | 638 Supported values for *address_family* are currently :const:`AF_INET` and |
633 :const:`AF_INET6`. If the IP address string *ip_string* is invalid, | 639 :const:`AF_INET6`. If the IP address string *ip_string* is invalid, |
634 :exc:`OSError` will be raised. Note that exactly what is valid depends on | 640 :exc:`OSError` will be raised. Note that exactly what is valid depends on |
635 both the value of *address_family* and the underlying implementation of | 641 both the value of *address_family* and the underlying implementation of |
636 :c:func:`inet_pton`. | 642 :c:func:`inet_pton`. |
637 | 643 |
638 Availability: Unix (maybe not all platforms), Windows. | 644 Availability: Unix (maybe not all platforms), Windows. |
639 | 645 |
640 .. versionchanged:: 3.4 | 646 .. versionchanged:: 3.4 |
641 Windows support added | 647 Windows support added |
642 | 648 |
643 | 649 |
644 .. function:: inet_ntop(address_family, packed_ip) | 650 .. function:: inet_ntop(address_family, packed_ip) |
645 | 651 |
646 Convert a packed IP address (a bytes object of some number of characters) to its | 652 Convert a packed IP address (a :term:`bytes-like object` of some number of |
647 standard, family-specific string representation (for example, ``'7.10.0.5'`` or | 653 characters) to its standard, family-specific string representation (for |
Martin Panter
2015/03/20 02:41:08
Probably should be “some number of bytes”, since t
storchaka
2015/03/20 07:47:34
Done.
| |
648 ``'5aef:2b::8'``). :func:`inet_ntop` is useful when a library or network prot ocol | 654 example, ``'7.10.0.5'`` or ``'5aef:2b::8'``). |
649 returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_nt oa`) | 655 :func:`inet_ntop` is useful when a library or network protocol returns an |
650 or :c:type:`struct in6_addr`. | 656 object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`) or |
657 :c:type:`struct in6_addr`. | |
651 | 658 |
652 Supported values for *address_family* are currently :const:`AF_INET` and | 659 Supported values for *address_family* are currently :const:`AF_INET` and |
653 :const:`AF_INET6`. If the string *packed_ip* is not the correct length for th e | 660 :const:`AF_INET6`. If the bytes object *packed_ip* is not the correct |
654 specified address family, :exc:`ValueError` will be raised. A | 661 length for the specified address family, :exc:`ValueError` will be raised. |
655 :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`. | 662 A :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`. |
656 | 663 |
657 Availability: Unix (maybe not all platforms), Windows. | 664 Availability: Unix (maybe not all platforms), Windows. |
658 | 665 |
659 .. versionchanged:: 3.4 | 666 .. versionchanged:: 3.4 |
660 Windows support added | 667 Windows support added |
661 | 668 |
669 .. versionchanged: 3.5 | |
670 Writable :term:`bytes-like object` is now accepted. | |
671 | |
662 | 672 |
663 .. | 673 .. |
664 XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any | 674 XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any |
665 non-Unix platforms? The old (obsolete?) 4.2BSD form of the | 675 non-Unix platforms? The old (obsolete?) 4.2BSD form of the |
666 interface, in which struct msghdr has no msg_control or | 676 interface, in which struct msghdr has no msg_control or |
667 msg_controllen members, is not currently supported. | 677 msg_controllen members, is not currently supported. |
668 | 678 |
669 .. function:: CMSG_LEN(length) | 679 .. function:: CMSG_LEN(length) |
670 | 680 |
671 Return the total length, without trailing padding, of an ancillary | 681 Return the total length, without trailing padding, of an ancillary |
(...skipping 528 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
1200 | 1210 |
1201 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`. | 1211 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`. |
1202 | 1212 |
1203 | 1213 |
1204 .. method:: socket.setsockopt(level, optname, value) | 1214 .. method:: socket.setsockopt(level, optname, value) |
1205 | 1215 |
1206 .. index:: module: struct | 1216 .. index:: module: struct |
1207 | 1217 |
1208 Set the value of the given socket option (see the Unix manual page | 1218 Set the value of the given socket option (see the Unix manual page |
1209 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the | 1219 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the |
1210 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a | 1220 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or |
1211 bytes object representing a buffer. In the latter case it is up to the calle r to | 1221 a :term:`bytes-like object` representing a buffer. In the latter case it is |
1222 up to the caller to | |
1212 ensure that the bytestring contains the proper bits (see the optional built-i n | 1223 ensure that the bytestring contains the proper bits (see the optional built-i n |
1213 module :mod:`struct` for a way to encode C structures as bytestrings). | 1224 module :mod:`struct` for a way to encode C structures as bytestrings). |
1225 | |
1226 .. versionchanged: 3.5 | |
1227 Writable :term:`bytes-like object` is now accepted. | |
1214 | 1228 |
1215 | 1229 |
1216 .. method:: socket.shutdown(how) | 1230 .. method:: socket.shutdown(how) |
1217 | 1231 |
1218 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD` , | 1232 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD` , |
1219 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends | 1233 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends |
1220 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives a re | 1234 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives a re |
1221 disallowed. | 1235 disallowed. |
1222 | 1236 |
1223 | 1237 |
(...skipping 310 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
1534 | 1548 |
1535 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et | 1549 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et |
1536 al, | 1550 al, |
1537 | 1551 |
1538 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections | 1552 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections |
1539 PS1:7 and PS1:8). The platform-specific reference material for the various | 1553 PS1:7 and PS1:8). The platform-specific reference material for the various |
1540 socket-related system calls are also a valuable source of information on the | 1554 socket-related system calls are also a valuable source of information on the |
1541 details of socket semantics. For Unix, refer to the manual pages; for Window s, | 1555 details of socket semantics. For Unix, refer to the manual pages; for Window s, |
1542 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers m ay | 1556 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers m ay |
1543 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv 6. | 1557 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv 6. |
OLD | NEW |