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 - :const:`AF_QIPCRTR` is a Linux-only socket based interface for communicating
197 with services running on co-processors in Qualcomm platforms. The address
199 are non-negative integers.
203 If you use a hostname in the *host* portion of IPv4/v6 socket address, the
206 differently into an actual IPv4/v6 address, depending on the results from DNS
211 and out-of-memory conditions can be raised; starting from Python 3.3, errors
215 Non-blocking mode is supported through :meth:`~socket.setblocking`. A
221 ---------------
240 address-related errors, i.e. for functions that use *h_errno* in the POSIX
253 address-related errors by :func:`getaddrinfo` and :func:`getnameinfo`.
347 On Windows, ``TCP_FASTOPEN``, ``TCP_KEEPCNT`` appear if run-time Windows
353 On Windows, ``TCP_KEEPIDLE``, ``TCP_KEEPINTVL`` appear if run-time Windows
396 CAN_ISOTP, in the CAN protocol family, is the ISO-TP (ISO 15765-2) protocol.
397 ISO-TP constants, documented in the Linux documentation.
507 The following functions all create :ref:`socket objects <socket-objects>`.
522 auto-detected from the specified file descriptor. Auto-detection can be
530 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
532 .. audit-event:: socket.__new__ self,family,type,protocol socket.socket
542 The returned socket is now non-inheritable.
559 will still create a non-blocking socket on OSes that support
570 The newly created sockets are :ref:`non-inheritable <fd_inheritance>`.
577 The returned sockets are now non-inheritable.
585 Connect to a TCP service listening on the Internet *address* (a 2-tuple
586 ``(host, port)``), and return the socket object. This is a higher-level
587 function than :meth:`socket.connect`: if *host* is a non-numeric hostname,
591 compatible to both IPv4 and IPv6.
598 If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the
607 Convenience function which creates a TCP socket bound to *address* (a 2-tuple
616 be able to accept both IPv4 and IPv6 connections, else it will raise
620 :meth:`socket.getpeername` when an IPv4 connection occurs will be an IPv6
621 address represented as an IPv4-mapped IPv6 address.
646 handle both IPv4 and IPv6 connections.
655 above. The file descriptor should refer to a socket, but this is not checked ---
661 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
664 The returned socket is now non-inheritable.
686 The :mod:`socket` module also offers various network-related services:
699 Translate the *host*/*port* argument into a sequence of 5-tuples that contain
701 *host* is a domain name, a string representation of an IPv4/v6 address
714 The function returns a list of 5-tuples with the following structure:
723 format depends on the returned *family* (a ``(address, port)`` 2-tuple for
724 :const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for
728 .. audit-event:: socket.getaddrinfo host,port,family,type,protocol socket.getaddrinfo
759 Translate a host name to IPv4 address format. The IPv4 address is returned as a
760 string, such as ``'100.50.200.5'``. If the host name is an IPv4 address itself
763 :func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support.
765 .. audit-event:: socket.gethostbyname hostname socket.gethostbyname
770 Translate a host name to IPv4 address format, extended interface. Return a
774 a list of IPv4 addresses for the same interface on the same host (often but not
775 always a single address). :func:`gethostbyname_ex` does not support IPv6 name
776 resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual
779 .. audit-event:: socket.gethostbyname hostname socket.gethostbyname_ex
787 .. audit-event:: socket.gethostname "" socket.gethostname
798 *ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same
799 host (most likely containing only a single address). To find the fully qualified
801 both IPv4 and IPv6.
803 .. audit-event:: socket.gethostbyaddr ip_address socket.gethostbyaddr
808 Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending
809 on the settings of *flags*, the result can contain a fully-qualified domain name
818 .. audit-event:: socket.getnameinfo sockaddr socket.getnameinfo
835 .. audit-event:: socket.getservbyname servicename,protocolname socket.getservbyname
844 .. audit-event:: socket.getservbyport port,protocolname socket.getservbyport
849 Convert 32-bit positive integers from network to host byte order. On machines
850 where the host byte order is the same as network byte order, this is a no-op;
851 otherwise, it performs a 4-byte swap operation.
856 Convert 16-bit positive integers from network to host byte order. On machines
857 where the host byte order is the same as network byte order, this is a no-op;
858 otherwise, it performs a 2-byte swap operation.
861 In case *x* does not fit in 16-bit unsigned integer, but does fit in a
862 positive C int, it is silently truncated to 16-bit unsigned integer.
869 Convert 32-bit positive integers from host to network byte order. On machines
870 where the host byte order is the same as network byte order, this is a no-op;
871 otherwise, it performs a 4-byte swap operation.
876 Convert 16-bit positive integers from host to network byte order. On machines
877 where the host byte order is the same as network byte order, this is a no-op;
878 otherwise, it performs a 2-byte swap operation.
881 In case *x* does not fit in 16-bit unsigned integer, but does fit in a
882 positive C int, it is silently truncated to 16-bit unsigned integer.
889 Convert an IPv4 address from dotted-quad string format (for example,
890 '123.45.67.89') to 32-bit packed binary format, as a bytes object four characters in
893 for the 32-bit packed binary this function returns.
898 If the IPv4 address string passed to this function is invalid,
903 instead for IPv4/v6 dual stack support.
908 Convert a 32-bit packed IPv4 address (a :term:`bytes-like object` four
909 bytes in length) to its standard dotted-quad string representation (for example,
912 is the C type for the 32-bit packed binary data this function takes as an
917 support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual
921 Writable :term:`bytes-like object` is now accepted.
926 Convert an IP address from its family-specific string format to a packed,
945 Convert a packed IP address (a :term:`bytes-like object` of some number of
946 bytes) to its standard, family-specific string representation (for
963 Writable :term:`bytes-like object` is now accepted.
968 non-Unix platforms? The old (obsolete?) 4.2BSD form of the
977 receive a single item of ancillary data, but :rfc:`3542` requires
1029 .. audit-event:: socket.sethostname name socket.sethostname
1078 .. _socket-objects:
1081 --------------
1099 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
1102 The socket is now non-inheritable.
1113 of *address* depends on the address family --- see above.)
1115 .. audit-event:: socket.bind self,address socket.socket.bind
1125 Sockets are automatically closed when they are garbage-collected, but
1144 address family --- see above.)
1149 a timeout. For non-blocking sockets, the method raises an
1153 .. audit-event:: socket.connect self,address socket.socket.connect
1165 exception for errors returned by the C-level :c:func:`connect` call (other
1171 .. audit-event:: socket.connect self,address socket.socket.connect_ex
1186 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
1189 The socket is now non-inheritable.
1194 Return the socket's file descriptor (a small integer), or -1 on failure. This
1213 find out the port number of a remote IPv4/v6 socket, for instance. (The format
1214 of the address returned depends on the address family --- see above.) On some
1221 an IPv4/v6 socket, for instance. (The format of the address returned depends on
1222 the address family --- see above.)
1233 contents of the buffer (see the optional built-in module :mod:`struct` for a way
1240 non-blocking.
1260 <https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
1285 .. index:: single: I/O control; buffering
1289 interpreted the same way as by the built-in :func:`open` function, except
1302 On Windows, the file-like object created by :meth:`makefile` cannot be
1331 to zero. (The format of *address* depends on the address family --- see above.)
1355 The return value is a 4-tuple: ``(data, ancdata, msg_flags,
1357 non-ancillary data received. The *ancdata* item is a list of zero
1361 protocol-specific type respectively, and *cmsg_data* is a
1401 fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
1417 :meth:`recvmsg` would, but scatter the non-ancillary data into a
1421 filled with successive chunks of the non-ancillary data until it
1427 The return value is a 4-tuple: ``(nbytes, ancdata, msg_flags,
1429 non-ancillary data written into the buffers, and *ancdata*,
1436 >>> b1 = bytearray(b'----')
1438 >>> b3 = bytearray(b'--------------')
1444 [bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]
1458 depends on the address family --- see above.)
1477 information on this topic, consult the :ref:`socket-howto`.
1510 bytes sent. (The format of *address* depends on the address family --- see
1513 .. audit-event:: socket.sendto self,address socket.socket.sendto
1524 non-ancillary data from a series of buffers and concatenating it
1525 into a single message. The *buffers* argument specifies the
1526 non-ancillary data as an iterable of
1527 :term:`bytes-like objects <bytes-like object>`
1534 protocol-specific type respectively, and *cmsg_data* is a
1535 bytes-like object holding the associated data. Note that
1541 number of bytes of non-ancillary data sent.
1554 .. audit-event:: socket.sendmsg self,address socket.socket.sendmsg
1574 Send a file until EOF is reached by using high-performance
1584 Non-blocking sockets are not supported.
1598 Set blocking or non-blocking mode of the socket: if *flag* is false, the
1599 socket is set to non-blocking, else to blocking mode.
1616 If a non-zero value is given, subsequent socket operations will raise a
1619 non-blocking mode. If ``None`` is given, the socket is put in blocking mode.
1621 For further information, please consult the :ref:`notes on socket timeouts <socket-timeouts>`.
1637 ``None`` or a :term:`bytes-like object` representing a buffer. In the later
1639 proper bits (see the optional built-in module :mod:`struct` for a way to
1646 Writable :term:`bytes-like object` is now accepted.
1662 Duplicate a socket and prepare it for sharing with a target process. The
1663 target process must be provided with *process_id*. The resulting bytes object
1664 can then be passed to the target process using some form of interprocess
1667 the operating system has already duplicated it for the target process.
1677 Socket objects also have these (read-only) attributes that correspond to the
1697 .. _socket-timeouts:
1700 ------------------------
1702 A socket object can be in one of three modes: blocking, non-blocking, or
1709 * In *non-blocking mode*, operations fail (with an error that is unfortunately
1710 system-dependent) if they cannot be completed immediately: functions from the
1720 in non-blocking mode. Also, the blocking and timeout modes are shared between
1745 * if the listening socket is in *non-blocking mode*, whether the socket
1746 returned by :meth:`~socket.accept` is in blocking or non-blocking mode
1747 is operating system-dependent. If you want to ensure cross-platform
1751 .. _socket-example:
1754 -------
1766 The first two examples support IPv4 only. ::
1772 PORT = 50007 # Arbitrary non-privileged port
1797 The next two examples are identical to the above two, but support both IPv4 and
1799 should listen to both instead). On most of IPv6-ready systems, IPv6 will take
1800 precedence and the server may not accept IPv4 traffic. The client side will try
1809 PORT = 50007 # Arbitrary non-privileged port
1967 - *An Introductory 4.3BSD Interprocess Communication Tutorial*, by Stuart Sechrest
1969 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Leffler et
1973 PS1:7 and PS1:8). The platform-specific reference material for the various
1974 socket-related system calls are also a valuable source of information on the
1976 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may