Lines Matching +full:ipv4 +full:- +full:single +full:- +full:target
1 :mod:`socket` --- Low-level networking interface
5 :synopsis: Low-level networking interface.
9 --------------
22 call and library interface for sockets to Python's object-oriented style: the
24 the various socket system calls. Parameter types are somewhat higher-level than
40 ---------------
49 - The address of an :const:`AF_UNIX` socket bound to a file system node
52 Linux's abstract namespace is returned as a :term:`bytes-like object` with
56 bytes-like object can be used for either type of address when
60 Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8
64 Writable :term:`bytes-like object` is now accepted.
68 - A pair ``(host, port)`` is used for the :const:`AF_INET` address family,
70 notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``,
73 - For IPv4 addresses, two special forms are accepted instead of a host
80 - For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
92 - :const:`AF_NETLINK` sockets are represented as pairs ``(pid, groups)``.
94 - Linux-only support for TIPC is available using the :const:`AF_TIPC`
95 address family. TIPC is an open, non-IP based networked protocol designed
100 - *addr_type* is one of :const:`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`,
102 - *scope* is one of :const:`TIPC_ZONE_SCOPE`, :const:`TIPC_CLUSTER_SCOPE`, and
104 - If *addr_type* is :const:`TIPC_ADDR_NAME`, then *v1* is the server type, *v2* is
113 - A tuple ``(interface, )`` is used for the :const:`AF_CAN` address family,
118 - :const:`CAN_ISOTP` protocol require a tuple ``(interface, rx_addr, tx_addr)``
122 - A string or a tuple ``(id, unit)`` is used for the :const:`SYSPROTO_CONTROL`
124 kernel control using a dynamically-assigned ID. The tuple can be used if ID
130 - :const:`AF_BLUETOOTH` supports the following protocols and address
133 - :const:`BTPROTO_L2CAP` accepts ``(bdaddr, psm)`` where ``bdaddr`` is
136 - :const:`BTPROTO_RFCOMM` accepts ``(bdaddr, channel)`` where ``bdaddr``
139 - :const:`BTPROTO_HCI` accepts ``(device_id,)`` where ``device_id`` is
147 - :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is a
152 - :const:`AF_ALG` is a Linux-only socket based interface to Kernel
156 - *type* is the algorithm type as string, e.g. ``aead``, ``hash``,
159 - *name* is the algorithm name and operation mode as string, e.g.
162 - *feat* and *mask* are unsigned 32bit integers.
168 - :const:`AF_VSOCK` allows communication between virtual machines and
176 - :const:`AF_PACKET` is a low-level interface directly to network devices.
180 - *ifname* - String specifying the device name.
181 - *proto* - An in network-byte-order integer specifying the Ethernet
183 - *pkttype* - Optional integer specifying the packet type:
185 - ``PACKET_HOST`` (the default) - Packet addressed to the local host.
186 - ``PACKET_BROADCAST`` - Physical-layer broadcast packet.
187 - ``PACKET_MULTIHOST`` - Packet sent to a physical-layer multicast address.
188 - ``PACKET_OTHERHOST`` - Packet to some other host that has been caught by
190 - ``PACKET_OUTGOING`` - Packet originating from the local host that is
192 - *hatype* - Optional integer specifying the ARP hardware address type.
193 - *addr* - Optional bytes-like object specifying the hardware physical
196 If you use a hostname in the *host* portion of IPv4/v6 socket address, the
199 differently into an actual IPv4/v6 address, depending on the results from DNS
204 and out-of-memory conditions can be raised; starting from Python 3.3, errors
208 Non-blocking mode is supported through :meth:`~socket.setblocking`. A
214 ---------------
233 address-related errors, i.e. for functions that use *h_errno* in the POSIX
246 address-related errors by :func:`getaddrinfo` and :func:`getnameinfo`.
340 On Windows, ``TCP_FASTOPEN``, ``TCP_KEEPCNT`` appear if run-time Windows
346 On Windows, ``TCP_KEEPIDLE``, ``TCP_KEEPINTVL`` appear if run-time Windows
386 CAN_ISOTP, in the CAN protocol family, is the ISO-TP (ISO 15765-2) protocol.
387 ISO-TP constants, documented in the Linux documentation.
490 The following functions all create :ref:`socket objects <socket-objects>`.
505 auto-detected from the specified file descriptor. Auto-detection can be
513 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
523 The returned socket is now non-inheritable.
538 will still create a non-blocking socket on OSes that support
549 The newly created sockets are :ref:`non-inheritable <fd_inheritance>`.
556 The returned sockets are now non-inheritable.
564 Connect to a TCP service listening on the Internet *address* (a 2-tuple
565 ``(host, port)``), and return the socket object. This is a higher-level
566 function than :meth:`socket.connect`: if *host* is a non-numeric hostname,
570 compatible to both IPv4 and IPv6.
577 If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the
590 above. The file descriptor should refer to a socket, but this is not checked ---
596 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
599 The returned socket is now non-inheritable.
621 The :mod:`socket` module also offers various network-related services:
634 Translate the *host*/*port* argument into a sequence of 5-tuples that contain
636 *host* is a domain name, a string representation of an IPv4/v6 address
649 The function returns a list of 5-tuples with the following structure:
658 format depends on the returned *family* (a ``(address, port)`` 2-tuple for
659 :const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for
692 Translate a host name to IPv4 address format. The IPv4 address is returned as a
693 string, such as ``'100.50.200.5'``. If the host name is an IPv4 address itself
696 :func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support.
701 Translate a host name to IPv4 address format, extended interface. Return a
705 a list of IPv4 addresses for the same interface on the same host (often but not
706 always a single address). :func:`gethostbyname_ex` does not support IPv6 name
707 resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual
725 *ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same
726 host (most likely containing only a single address). To find the fully qualified
728 both IPv4 and IPv6.
733 Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending
734 on the settings of *flags*, the result can contain a fully-qualified domain name
766 Convert 32-bit positive integers from network to host byte order. On machines
767 where the host byte order is the same as network byte order, this is a no-op;
768 otherwise, it performs a 4-byte swap operation.
773 Convert 16-bit positive integers from network to host byte order. On machines
774 where the host byte order is the same as network byte order, this is a no-op;
775 otherwise, it performs a 2-byte swap operation.
778 In case *x* does not fit in 16-bit unsigned integer, but does fit in a
779 positive C int, it is silently truncated to 16-bit unsigned integer.
786 Convert 32-bit positive integers from host to network byte order. On machines
787 where the host byte order is the same as network byte order, this is a no-op;
788 otherwise, it performs a 4-byte swap operation.
793 Convert 16-bit positive integers from host to network byte order. On machines
794 where the host byte order is the same as network byte order, this is a no-op;
795 otherwise, it performs a 2-byte swap operation.
798 In case *x* does not fit in 16-bit unsigned integer, but does fit in a
799 positive C int, it is silently truncated to 16-bit unsigned integer.
806 Convert an IPv4 address from dotted-quad string format (for example,
807 '123.45.67.89') to 32-bit packed binary format, as a bytes object four characters in
810 for the 32-bit packed binary this function returns.
815 If the IPv4 address string passed to this function is invalid,
820 instead for IPv4/v6 dual stack support.
825 Convert a 32-bit packed IPv4 address (a :term:`bytes-like object` four
826 bytes in length) to its standard dotted-quad string representation (for example,
829 is the C type for the 32-bit packed binary data this function takes as an
834 support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual
838 Writable :term:`bytes-like object` is now accepted.
843 Convert an IP address from its family-specific string format to a packed,
862 Convert a packed IP address (a :term:`bytes-like object` of some number of
863 bytes) to its standard, family-specific string representation (for
880 Writable :term:`bytes-like object` is now accepted.
885 non-Unix platforms? The old (obsolete?) 4.2BSD form of the
894 receive a single item of ancillary data, but :rfc:`3542` requires
984 .. _socket-objects:
987 --------------
1005 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
1008 The socket is now non-inheritable.
1019 of *address* depends on the address family --- see above.)
1030 Sockets are automatically closed when they are garbage-collected, but
1049 address family --- see above.)
1054 a timeout. For non-blocking sockets, the method raises an
1068 exception for errors returned by the C-level :c:func:`connect` call (other
1088 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
1091 The socket is now non-inheritable.
1096 Return the socket's file descriptor (a small integer), or -1 on failure. This
1115 find out the port number of a remote IPv4/v6 socket, for instance. (The format
1116 of the address returned depends on the address family --- see above.) On some
1123 an IPv4/v6 socket, for instance. (The format of the address returned depends on
1124 the address family --- see above.)
1135 contents of the buffer (see the optional built-in module :mod:`struct` for a way
1142 non-blocking.
1162 <https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
1187 .. index:: single: I/O control; buffering
1191 interpreted the same way as by the built-in :func:`open` function, except
1204 On Windows, the file-like object created by :meth:`makefile` cannot be
1233 to zero. (The format of *address* depends on the address family --- see above.)
1257 The return value is a 4-tuple: ``(data, ancdata, msg_flags,
1259 non-ancillary data received. The *ancdata* item is a list of zero
1263 protocol-specific type respectively, and *cmsg_data* is a
1303 fds.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
1319 :meth:`recvmsg` would, but scatter the non-ancillary data into a
1323 filled with successive chunks of the non-ancillary data until it
1329 The return value is a 4-tuple: ``(nbytes, ancdata, msg_flags,
1331 non-ancillary data written into the buffers, and *ancdata*,
1338 >>> b1 = bytearray(b'----')
1340 >>> b3 = bytearray(b'--------------')
1346 [bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]
1360 depends on the address family --- see above.)
1379 information on this topic, consult the :ref:`socket-howto`.
1412 bytes sent. (The format of *address* depends on the address family --- see
1424 non-ancillary data from a series of buffers and concatenating it
1425 into a single message. The *buffers* argument specifies the
1426 non-ancillary data as an iterable of
1427 :term:`bytes-like objects <bytes-like object>`
1434 protocol-specific type respectively, and *cmsg_data* is a
1435 bytes-like object holding the associated data. Note that
1441 number of bytes of non-ancillary data sent.
1472 Send a file until EOF is reached by using high-performance
1482 Non-blocking sockets are not supported.
1496 Set blocking or non-blocking mode of the socket: if *flag* is false, the
1497 socket is set to non-blocking, else to blocking mode.
1514 If a non-zero value is given, subsequent socket operations will raise a
1517 non-blocking mode. If ``None`` is given, the socket is put in blocking mode.
1519 For further information, please consult the :ref:`notes on socket timeouts <socket-timeouts>`.
1535 ``None`` or a :term:`bytes-like object` representing a buffer. In the later
1537 proper bits (see the optional built-in module :mod:`struct` for a way to
1544 Writable :term:`bytes-like object` is now accepted.
1560 Duplicate a socket and prepare it for sharing with a target process. The
1561 target process must be provided with *process_id*. The resulting bytes object
1562 can then be passed to the target process using some form of interprocess
1565 the operating system has already duplicated it for the target process.
1575 Socket objects also have these (read-only) attributes that correspond to the
1595 .. _socket-timeouts:
1598 ------------------------
1600 A socket object can be in one of three modes: blocking, non-blocking, or
1607 * In *non-blocking mode*, operations fail (with an error that is unfortunately
1608 system-dependent) if they cannot be completed immediately: functions from the
1618 in non-blocking mode. Also, the blocking and timeout modes are shared between
1643 * if the listening socket is in *non-blocking mode*, whether the socket
1644 returned by :meth:`~socket.accept` is in blocking or non-blocking mode
1645 is operating system-dependent. If you want to ensure cross-platform
1649 .. _socket-example:
1652 -------
1664 The first two examples support IPv4 only. ::
1670 PORT = 50007 # Arbitrary non-privileged port
1695 The next two examples are identical to the above two, but support both IPv4 and
1697 should listen to both instead). On most of IPv6-ready systems, IPv6 will take
1698 precedence and the server may not accept IPv4 traffic. The client side will try
1707 PORT = 50007 # Arbitrary non-privileged port
1866 - *An Introductory 4.3BSD Interprocess Communication Tutorial*, by Stuart Sechrest
1868 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Leffler et
1872 PS1:7 and PS1:8). The platform-specific reference material for the various
1873 socket-related system calls are also a valuable source of information on the
1875 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may