Lines Matching +full:getsockopt +full:- +full:timeouts
1 :mod:`socket` --- Low-level networking interface
5 :synopsis: Low-level networking interface.
9 --------------
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
248 generalization of this based on timeouts is supported through
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`.
300 occurs on a socket which has had timeouts enabled via a prior call to
374 generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt`
384 On Windows, ``TCP_FASTOPEN``, ``TCP_KEEPCNT`` appear if run-time Windows
390 On Windows, ``TCP_KEEPIDLE``, ``TCP_KEEPINTVL`` appear if run-time Windows
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.
600 The following functions all create :ref:`socket objects <socket-objects>`.
616 auto-detected from the specified file descriptor. Auto-detection can be
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.
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
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.
795 The :mod:`socket` module also offers various network-related services:
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
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
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,
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
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
1181 * UUID: ``{FB605B73-AAC2-49A6-9A2F-25416AEA0573}``
1184 * description: ``Hyper-V Virtual Ethernet Adapter``
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
1306 Sockets are automatically closed when they are garbage-collected, but
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
1401 of the address returned depends on the address family --- see above.) On some
1409 the address family --- see above.)
1412 .. method:: socket.getsockopt(level, optname[, buflen])
1415 :manpage:`getsockopt(2)`). The needed symbolic constants (:const:`SO_\*` etc.)
1420 contents of the buffer (see the optional built-in module :mod:`struct` for a way
1429 non-blocking.
1449 <https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
1481 interpreted the same way as by the built-in :func:`open` function, except
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
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.)
1673 information on this topic, consult the :ref:`socket-howto`.
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
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
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.
1880 Socket objects also have these (read-only) attributes that correspond to the
1900 .. _socket-timeouts:
1902 Notes on 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
1928 Timeouts and the ``connect`` method
1938 Timeouts and the ``accept`` method
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 -------
1975 PORT = 50007 # Arbitrary non-privileged port
2002 should listen to both instead). On most of IPv6-ready systems, IPv6 will take
2012 PORT = 50007 # Arbitrary non-privileged port
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
2179 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may