Lines Matching +full:windows +full:- +full:remote +full:- +full:only
1 :mod:`socket` --- Low-level networking interface
5 :synopsis: Low-level networking interface.
9 --------------
12 all modern Unix systems, Windows, MacOS, and probably additional platforms.
20 .. include:: ../includes/wasm-notavail.rst
25 call and library interface for sockets to Python's object-oriented style: the
27 the various socket system calls. Parameter types are somewhat higher-level than
43 ---------------
52 - The address of an :const:`AF_UNIX` socket bound to a file system node
55 Linux's abstract namespace is returned as a :term:`bytes-like object` with
59 bytes-like object can be used for either type of address when
63 Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8
67 Writable :term:`bytes-like object` is now accepted.
71 - A pair ``(host, port)`` is used for the :const:`AF_INET` address family,
76 - For IPv4 addresses, two special forms are accepted instead of a host
83 - For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
95 - :const:`AF_NETLINK` sockets are represented as pairs ``(pid, groups)``.
97 - Linux-only support for TIPC is available using the :const:`AF_TIPC`
98 address family. TIPC is an open, non-IP based networked protocol designed
103 - *addr_type* is one of :const:`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`,
105 - *scope* is one of :const:`TIPC_ZONE_SCOPE`, :const:`TIPC_CLUSTER_SCOPE`, and
107 - If *addr_type* is :const:`TIPC_ADDR_NAME`, then *v1* is the server type, *v2* is
116 - A tuple ``(interface, )`` is used for the :const:`AF_CAN` address family,
121 - :const:`CAN_ISOTP` protocol require a tuple ``(interface, rx_addr, tx_addr)``
124 - :const:`CAN_J1939` protocol require a tuple ``(interface, name, pgn, addr)``
125 where additional parameters are 64-bit unsigned integer representing the
126 ECU name, a 32-bit unsigned integer representing the Parameter Group Number
127 (PGN), and an 8-bit integer representing the address.
129 - A string or a tuple ``(id, unit)`` is used for the :const:`SYSPROTO_CONTROL`
137 - :const:`AF_BLUETOOTH` supports the following protocols and address
140 - :const:`BTPROTO_L2CAP` accepts ``(bdaddr, psm)`` where ``bdaddr`` is
143 - :const:`BTPROTO_RFCOMM` accepts ``(bdaddr, channel)`` where ``bdaddr``
146 - :const:`BTPROTO_HCI` accepts ``(device_id,)`` where ``device_id`` is
154 - :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is a
159 - :const:`AF_ALG` is a Linux-only socket based interface to Kernel
163 - *type* is the algorithm type as string, e.g. ``aead``, ``hash``,
166 - *name* is the algorithm name and operation mode as string, e.g.
169 - *feat* and *mask* are unsigned 32bit integers.
177 - :const:`AF_VSOCK` allows communication between virtual machines and
187 - :const:`AF_PACKET` is a low-level interface directly to network devices.
191 - *ifname* - String specifying the device name.
192 - *proto* - An in network-byte-order integer specifying the Ethernet
194 - *pkttype* - Optional integer specifying the packet type:
196 - ``PACKET_HOST`` (the default) - Packet addressed to the local host.
197 - ``PACKET_BROADCAST`` - Physical-layer broadcast packet.
198 - ``PACKET_MULTICAST`` - Packet sent to a physical-layer multicast address.
199 - ``PACKET_OTHERHOST`` - Packet to some other host that has been caught by
201 - ``PACKET_OUTGOING`` - Packet originating from the local host that is
203 - *hatype* - Optional integer specifying the ARP hardware address type.
204 - *addr* - Optional bytes-like object specifying the hardware physical
209 - :const:`AF_QIPCRTR` is a Linux-only socket based interface for communicating
210 with services running on co-processors in Qualcomm platforms. The address
212 are non-negative integers.
218 - :const:`IPPROTO_UDPLITE` is a variant of UDP which allows you to specify
243 and out-of-memory conditions can be raised. Errors
247 Non-blocking mode is supported through :meth:`~socket.setblocking`. A
253 ---------------
272 address-related errors, i.e. for functions that use *h_errno* in the POSIX
285 address-related errors by :func:`getaddrinfo` and :func:`getnameinfo`.
338 (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be generally
375 methods of socket objects. In most cases, only those symbols that are defined
384 On Windows, ``TCP_FASTOPEN``, ``TCP_KEEPCNT`` appear if run-time Windows
390 On Windows, ``TCP_KEEPIDLE``, ``TCP_KEEPINTVL`` appear if run-time Windows
427 The :data:`CAN_BCM_CAN_FD_FRAME` flag is only available on Linux >= 4.8.
445 Joins the applied CAN filters such that only CAN frames that match all
456 CAN_ISOTP, in the CAN protocol family, is the ISO-TP (ISO 15765-2) protocol.
457 ISO-TP constants, documented in the Linux documentation.
501 Constants for Windows' WSAIoctl(). The constants are used as arguments to the
566 service providing remote processors.
600 The following functions all create :ref:`socket objects <socket-objects>`.
616 auto-detected from the specified file descriptor. Auto-detection can be
618 arguments. This only affects how Python represents e.g. the return value
624 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
626 .. audit-event:: socket.__new__ self,family,type,protocol socket.socket
636 The returned socket is now non-inheritable.
653 will still create a non-blocking socket on OSes that support
670 The newly created sockets are :ref:`non-inheritable <fd_inheritance>`.
677 The returned sockets are now non-inheritable.
680 Windows support added.
685 Connect to a TCP service listening on the internet *address* (a 2-tuple
686 ``(host, port)``), and return the socket object. This is a higher-level
687 function than :meth:`socket.connect`: if *host* is a non-numeric hostname,
698 If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the
716 Convenience function which creates a TCP socket bound to *address* (a 2-tuple
726 :exc:`ValueError`. Most POSIX platforms and Windows are supposed to support
730 address represented as an IPv4-mapped IPv6 address.
764 above. The file descriptor should refer to a socket, but this is not checked ---
770 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
773 The returned socket is now non-inheritable.
781 .. availability:: Windows.
795 The :mod:`socket` module also offers various network-related services:
801 sockets. On some platforms (most noticeable Windows) :func:`os.close`
808 Translate the *host*/*port* argument into a sequence of 5-tuples that contain
823 The function returns a list of 5-tuples with the following structure:
832 format depends on the returned *family* (a ``(address, port)`` 2-tuple for
833 :const:`AF_INET`, a ``(address, port, flowinfo, scope_id)`` 4-tuple for
837 .. audit-event:: socket.getaddrinfo host,port,family,type,protocol socket.getaddrinfo
875 .. audit-event:: socket.gethostbyname hostname socket.gethostbyname
891 .. audit-event:: socket.gethostbyname hostname socket.gethostbyname_ex
901 .. audit-event:: socket.gethostname "" socket.gethostname
915 host (most likely containing only a single address). To find the fully qualified
919 .. audit-event:: socket.gethostbyaddr ip_address socket.gethostbyaddr
926 Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending
936 .. audit-event:: socket.getnameinfo sockaddr socket.getnameinfo
945 function. This is usually only needed for sockets opened in "raw" mode
958 .. audit-event:: socket.getservbyname servicename,protocolname socket.getservbyname
969 .. audit-event:: socket.getservbyport port,protocolname socket.getservbyport
976 Convert 32-bit positive integers from network to host byte order. On machines
977 where the host byte order is the same as network byte order, this is a no-op;
978 otherwise, it performs a 4-byte swap operation.
983 Convert 16-bit positive integers from network to host byte order. On machines
984 where the host byte order is the same as network byte order, this is a no-op;
985 otherwise, it performs a 2-byte swap operation.
988 Raises :exc:`OverflowError` if *x* does not fit in a 16-bit unsigned
994 Convert 32-bit positive integers from host to network byte order. On machines
995 where the host byte order is the same as network byte order, this is a no-op;
996 otherwise, it performs a 4-byte swap operation.
1001 Convert 16-bit positive integers from host to network byte order. On machines
1002 where the host byte order is the same as network byte order, this is a no-op;
1003 otherwise, it performs a 2-byte swap operation.
1006 Raises :exc:`OverflowError` if *x* does not fit in a 16-bit unsigned
1012 Convert an IPv4 address from dotted-quad string format (for example,
1013 '123.45.67.89') to 32-bit packed binary format, as a bytes object four characters in
1016 for the 32-bit packed binary this function returns.
1031 Convert a 32-bit packed IPv4 address (a :term:`bytes-like object` four
1032 bytes in length) to its standard dotted-quad string representation (for example,
1035 is the C type for the 32-bit packed binary data this function takes as an
1044 Writable :term:`bytes-like object` is now accepted.
1049 Convert an IP address from its family-specific string format to a packed,
1060 .. availability:: Unix, Windows.
1063 Windows support added
1068 Convert a packed IP address (a :term:`bytes-like object` of some number of
1069 bytes) to its standard, family-specific string representation (for
1080 .. availability:: Unix, Windows.
1083 Windows support added
1086 Writable :term:`bytes-like object` is now accepted.
1091 non-Unix platforms? The old (obsolete?) 4.2BSD form of the
1156 .. audit-event:: socket.sethostname name socket.sethostname
1169 .. availability:: Unix, Windows, not Emscripten, not WASI.
1174 Windows support was added.
1178 On Windows network interfaces have different names in different contexts
1181 * UUID: ``{FB605B73-AAC2-49A6-9A2F-25416AEA0573}``
1184 * description: ``Hyper-V Virtual Ethernet Adapter``
1196 .. availability:: Unix, Windows, not Emscripten, not WASI.
1201 Windows support was added.
1213 .. availability:: Unix, Windows, not Emscripten, not WASI.
1218 Windows support was added.
1230 .. availability:: Unix, Windows, not Emscripten, not WASI.
1244 .. availability:: Unix, Windows, not Emscripten, not WASI.
1256 .. _socket-objects:
1259 --------------
1277 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
1280 The socket is now non-inheritable.
1291 of *address* depends on the address family --- see above.)
1293 .. audit-event:: socket.bind self,address socket.socket.bind
1303 object will fail. The remote end will receive no more data (after
1306 Sockets are automatically closed when they are garbage-collected, but
1324 Connect to a remote socket at *address*. (The format of *address* depends on the
1325 address family --- see above.)
1330 a timeout. For non-blocking sockets, the method raises an
1334 .. audit-event:: socket.connect self,address socket.socket.connect
1348 exception for errors returned by the C-level :c:func:`connect` call (other
1354 .. audit-event:: socket.connect self,address socket.socket.connect_ex
1371 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
1374 The socket is now non-inheritable.
1381 Return the socket's file descriptor (a small integer), or -1 on failure. This
1384 Under Windows the small integer returned by this method cannot be used where a
1399 Return the remote address to which the socket is connected. This is useful to
1400 find out the port number of a remote IPv4/v6 socket, for instance. (The format
1401 of the address returned depends on the address family --- see above.) On some
1409 the address family --- see above.)
1420 contents of the buffer (see the optional built-in module :mod:`struct` for a way
1429 non-blocking.
1445 :platform: Windows
1449 <https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
1455 Currently only the following control codes are supported:
1481 interpreted the same way as by the built-in :func:`open` function, except
1482 the only supported *mode* values are ``'r'`` (default), ``'w'`` and ``'b'``.
1494 On Windows, the file-like object created by :meth:`makefile` cannot be
1523 to zero. (The format of *address* depends on the address family --- see above.)
1547 The return value is a 4-tuple: ``(data, ancdata, msg_flags,
1549 non-ancillary data received. The *ancdata* item is a list of zero
1553 protocol-specific type respectively, and *cmsg_data* is a
1573 items which have been only partially received. If an item appears
1593 fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
1611 :meth:`recvmsg` would, but scatter the non-ancillary data into a
1615 filled with successive chunks of the non-ancillary data until it
1621 The return value is a 4-tuple: ``(nbytes, ancdata, msg_flags,
1623 non-ancillary data written into the buffers, and *ancdata*,
1630 >>> b1 = bytearray(b'----')
1632 >>> b3 = bytearray(b'--------------')
1638 [bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]
1654 depends on the address family --- see above.)
1668 Send data to the socket. The socket must be connected to a remote socket. The
1671 all data has been sent; if only some of the data was transmitted, the
1673 information on this topic, consult the :ref:`socket-howto`.
1683 Send data to the socket. The socket must be connected to a remote socket. The
1703 Send data to the socket. The socket should not be connected to a remote socket,
1706 bytes sent. (The format of *address* depends on the address family --- see
1709 .. audit-event:: socket.sendto self,address socket.socket.sendto
1720 non-ancillary data from a series of buffers and concatenating it
1722 non-ancillary data as an iterable of
1723 :term:`bytes-like objects <bytes-like object>`
1730 protocol-specific type respectively, and *cmsg_data* is a
1731 bytes-like object holding the associated data. Note that
1733 might support sending only one control message per call. The
1737 number of bytes of non-ancillary data sent.
1752 .. audit-event:: socket.sendmsg self,address socket.socket.sendmsg
1772 Send a file until EOF is reached by using high-performance
1775 :mod:`os.sendfile` is not available (e.g. Windows) or *file* is not a
1782 Non-blocking sockets are not supported.
1796 Set blocking or non-blocking mode of the socket: if *flag* is false, the
1797 socket is set to non-blocking, else to blocking mode.
1814 If a non-zero value is given, subsequent socket operations will raise a
1817 non-blocking mode. If ``None`` is given, the socket is put in blocking mode.
1819 For further information, please consult the :ref:`notes on socket timeouts <socket-timeouts>`.
1837 ``None`` or a :term:`bytes-like object` representing a buffer. In the later
1839 proper bits (see the optional built-in module :mod:`struct` for a way to
1845 Writable :term:`bytes-like object` is now accepted.
1872 .. availability:: Windows.
1880 Socket objects also have these (read-only) attributes that correspond to the
1900 .. _socket-timeouts:
1903 ------------------------
1905 A socket object can be in one of three modes: blocking, non-blocking, or
1912 * In *non-blocking mode*, operations fail (with an error that is unfortunately
1913 system-dependent) if they cannot be completed immediately: functions from the
1923 in non-blocking mode. Also, the blocking and timeout modes are shared between
1948 * if the listening socket is in *non-blocking mode*, whether the socket
1949 returned by :meth:`~socket.accept` is in blocking or non-blocking mode
1950 is operating system-dependent. If you want to ensure cross-platform
1954 .. _socket-example:
1957 -------
1960 echoes all data that it receives back (servicing only one client), and a client
1964 client only needs the sequence :func:`.socket`, :meth:`~socket.connect`. Also
1969 The first two examples support IPv4 only. ::
1975 PORT = 50007 # Arbitrary non-privileged port
1992 HOST = 'daring.cwi.nl' # The remote host
2002 should listen to both instead). On most of IPv6-ready systems, IPv6 will take
2012 PORT = 50007 # Arbitrary non-privileged port
2047 HOST = 'daring.cwi.nl' # The remote host
2073 sockets on Windows. The example requires administrator privileges to modify
2170 - *An Introductory 4.3BSD Interprocess Communication Tutorial*, by Stuart Sechrest
2172 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Leffler et
2176 PS1:7 and PS1:8). The platform-specific reference material for the various
2177 socket-related system calls are also a valuable source of information on the
2178 details of socket semantics. For Unix, refer to the manual pages; for Windows,
2179 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may