# `socket` — Low-level networking interface

Вихідний код: Lib/socket.py

Цей модуль забезпечує доступ до інтерфейсу BSD socket. Він доступний у всіх сучасних системах Unix, Windows, MacOS і, можливо, на додаткових платформах.

Примітка

Деяка поведінка може залежати від платформи, оскільки виклики здійснюються до API сокетів операційної системи.

Availability: not WASI.

This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.

The Python interface is a straightforward transliteration of the Unix system call and library interface for sockets to Python’s object-oriented style: the `socket()` function returns a socket object whose methods implement the various socket system calls. Parameter types are somewhat higher-level than in the C interface: as with `read()` and `write()` operations on Python files, buffer allocation on receive operations is automatic, and buffer length is implicit on send operations.

Дивись також

Модуль `socketserver`

  Класи, які спрощують написання мережевих серверів.

Модуль `ssl`

  Обгортка TLS/SSL для об’єктів сокета.

## Сімейства розеток

Залежно від системи та параметрів збірки, цей модуль підтримує різні сімейства сокетів.

Формат адреси, необхідний для певного об’єкта сокета, вибирається автоматично на основі сімейства адрес, указаного під час створення об’єкта сокета. Адреси сокетів представлені таким чином:

- Адреса сокета `AF_UNIX`, пов’язаного з вузлом файлової системи, представлена у вигляді рядка з використанням кодування файлової системи та обробника помилок `'surrogateescape'` (див. PEP 383). Адреса в абстрактному просторі імен Linux повертається як bytes-like object з початковим нульовим байтом; зауважте, що сокети в цьому просторі імен можуть взаємодіяти зі звичайними сокетами файлової системи, тому програми, призначені для роботи в Linux, можуть мати справу з обома типами адрес. Рядок або байт-подібний об’єкт можна використовувати для будь-якого типу адреси, передаючи його як аргумент.

  Змінено в версії 3.3: Раніше вважалося, що шляхи сокетів `AF_UNIX` використовували кодування UTF-8.

  Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

- Пара `(хост, порт)` використовується для родини адрес `AF_INET`, де хост — це рядок, який представляє або ім’я хоста в нотації домену Інтернету, як-от `'daring.cwi.nl'` або адреса IPv4, наприклад `'100.50.200.5''`, і порт є цілим числом.

  - Для адрес IPv4 приймаються дві спеціальні форми замість адреси хоста: `''` представляє `INADDR_ANY`, який використовується для прив’язки до всіх інтерфейсів, а рядок `' <broadcast> ''` представляє `INADDR_BROADCAST`. Така поведінка несумісна з IPv6, тому ви можете уникнути цього, якщо ви маєте намір підтримувати IPv6 у своїх програмах на Python.

- For `AF_INET6` address family, a four-tuple `(host, port, flowinfo, scope_id)` is used, where flowinfo and scope_id represent the `sin6_flowinfo` and `sin6_scope_id` members in `struct sockaddr_in6` in C. For `socket` module methods, flowinfo and scope_id can be omitted just for backward compatibility. Note, however, omission of scope_id can cause problems in manipulating scoped IPv6 addresses.

  Змінено в версії 3.7: Для багатоадресних адрес (зі значенням scope_id) address не може містити частину `%scope_id` (або `zone id`). Ця інформація є зайвою, і її можна сміливо опустити (рекомендовано).

- `AF_NETLINK` сокети представлені як пари `(pid, groups)`.

- Підтримка TIPC лише для Linux доступна за допомогою родини адрес `AF_TIPC`. TIPC — це відкритий мережевий протокол не на основі IP, призначений для використання в кластерних комп’ютерних середовищах. Адреси представлені кортежем, а поля залежать від типу адреси. Загальна форма кортежу `(addr_type, v1, v2, v3 [, scope])`, де:

  - addr_type є одним із `TIPC_ADDR_NAMESEQ`, `TIPC_ADDR_NAME` або `TIPC_ADDR_ID`.

  - scope є одним із `TIPC_ZONE_SCOPE`, `TIPC_CLUSTER_SCOPE` та `TIPC_NODE_SCOPE`.

  - Якщо addr_type дорівнює `TIPC_ADDR_NAME`, тоді v1 — це тип сервера, v2 — ідентифікатор порту, а v3 має бути 0.

    Якщо addr_type дорівнює `TIPC_ADDR_NAMESEQ`, то v1 — це тип сервера, v2 — нижній номер порту, а v3 — верхній номер порту.

    Якщо addr_type дорівнює `TIPC_ADDR_ID`, тоді v1 є вузлом, v2 є посиланням, а v3 має бути встановлено на 0.

- Кортеж `(інтерфейс, )` використовується для сімейства адрес `AF_CAN`, де інтерфейс — це рядок, що представляє назву мережевого інтерфейсу, наприклад `'can0'`. Ім’я мережевого інтерфейсу `''` можна використовувати для отримання пакетів від усіх мережевих інтерфейсів цього сімейства.

  - Протокол `CAN_ISOTP` вимагає кортеж `(interface, rx_addr, tx_addr)`, де обидва додаткові параметри є довгим цілим числом без знаку, що представляє ідентифікатор CAN (стандартний або розширений).

  - Протокол `CAN_J1939` вимагає кортеж `(interface, name, pgn, addr)`, де додаткові параметри є 64-розрядним цілим числом без знака, що представляє назву ECU, 32-розрядним цілим числом без знака, що представляє номер групи параметрів (PGN ) і 8-бітове ціле число, що представляє адресу.

- A string or a tuple `(id, unit)` is used for the `SYSPROTO_CONTROL` protocol of the `PF_SYSTEM` family. The string is the name of a kernel control using a dynamically assigned ID. The tuple can be used if ID and unit number of the kernel control are known or if a registered ID is used.

  Added in version 3.3.

- `AF_BLUETOOTH` підтримує наступні протоколи та формати адрес:

  - `BTPROTO_L2CAP` accepts a tuple `(bdaddr, psm[, cid[, bdaddr_type]])` where:

    - `bdaddr` is a string specifying the Bluetooth address.

    - `psm` is an integer specifying the Protocol/Service Multiplexer.

    - `cid` is an optional integer specifying the Channel Identifier. If not given, defaults to zero.

    - `bdaddr_type` is an optional integer specifying the address type; one of `BDADDR_BREDR` (default), `BDADDR_LE_PUBLIC`, `BDADDR_LE_RANDOM`.

    Змінено в версії 3.14: Added `cid` and `bdaddr_type` fields.

  - `BTPROTO_RFCOMM` приймає `(bdaddr, канал)`, де `bdaddr` — це адреса Bluetooth у вигляді рядка, а `channel` — ціле число.

  - `BTPROTO_HCI` accepts a format that depends on your OS.

    - On Linux it accepts an integer `device_id` or a tuple `(device_id, [channel])` where `device_id` specifies the number of the Bluetooth device, and `channel` is an optional integer specifying the HCI channel (`HCI_CHANNEL_RAW` by default).

    - On FreeBSD, NetBSD and DragonFly BSD it accepts `bdaddr` where `bdaddr` is the Bluetooth address as a string.

    Змінено в версії 3.2: Додано підтримку NetBSD і DragonFlyBSD.

    Змінено в версії 3.13.3: FreeBSD support added.

    Змінено в версії 3.14: Added `channel` field. `device_id` not packed in a tuple is now accepted.

  - `BTPROTO_SCO` accepts `bdaddr` where `bdaddr` is the Bluetooth address as a string or a `bytes` object. (ex. `'12:23:34:45:56:67'` or `b'12:23:34:45:56:67'`)

    Змінено в версії 3.14: FreeBSD support added.

- `AF_ALG` — це інтерфейс для криптографії ядра на основі сокетів лише для Linux. Сокет алгоритму налаштований за допомогою кортежу з двох-чотирьох елементів `(type, name [, feat [, mask]])`, де:

  - type — це тип алгоритму як рядок, напр. `aead`, `hash`, `skcipher` або `rng`.

  - ім’я — це назва алгоритму та режим роботи у вигляді рядка, напр. `sha256`, `hmac(sha256)`, `cbc(aes)` або `drbg_nopr_ctr_aes256`.

  - feat і mask — це 32-розрядні цілі числа без знаку.

  Availability: Linux >= 2.6.38.

  Some algorithm types require more recent Kernels.

  Added in version 3.6.

- `AF_VSOCK` дозволяє спілкуватися між віртуальними машинами та їх хостами. Сокети представлені як кортеж `(CID, порт)`, де ідентифікатор контексту або CID і порт є цілими числами.

  Availability: Linux >= 3.9

  See vsock(7)

  Added in version 3.7.

- `AF_PACKET` is a low-level interface directly to network devices. The addresses are represented by the tuple `(ifname, proto[, pkttype[, hatype[, addr]]])` where:

  - ifname - Рядок, що визначає назву пристрою.

  - proto - The Ethernet protocol number. May be `ETH_P_ALL` to capture all protocols, one of the ETHERTYPE_* constants or any other Ethernet protocol number.

  - pkttype - додаткове ціле число, що вказує тип пакета:

    - `PACKET_HOST` (за замовчуванням) - пакет, адресований локальному хосту.

    - `PACKET_BROADCAST` - широкомовний пакет фізичного рівня.

    - `PACKET_MULTICAST` - Packet sent to a physical-layer multicast address.

    - `PACKET_OTHERHOST` - Пакет до іншого хосту, який був перехоплений драйвером пристрою в безладному режимі.

    - `PACKET_OUTGOING` – Пакет, що надходить від локального хосту і повертається до сокета пакета.

  - hatype – додаткове ціле число, що визначає тип апаратної адреси ARP.

  - addr – необов’язковий байтовий об’єкт, що вказує апаратну фізичну адресу, інтерпретація якої залежить від пристрою.

  Availability: Linux >= 2.2.

- `AF_QIPCRTR` — це інтерфейс на основі сокетів лише для Linux для зв’язку зі службами, що працюють на співпроцесорах на платформах Qualcomm. Сімейство адрес представлено як кортеж `(вузол, порт)`, де вузол і порт є невід’ємними цілими числами.

  Availability: Linux >= 4.7.

  Added in version 3.8.

- `IPPROTO_UDPLITE` — це варіант UDP, який дозволяє вказати, яку частину пакету охоплює контрольна сума. Він додає два варіанти розеток, які ви можете змінити. `self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length)` змінить частину вихідних пакетів, охоплених контрольною сумою, а `self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length)` відфільтровує пакети, які покривають занадто мало їхні дані. В обох випадках `довжина` має бути в `діапазоні (8, 2**16, 8)`.

  Такий сокет має бути створений за допомогою `socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE)` для IPv4 або `socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE)` для IPv6.

  Availability: Linux >= 2.6.20, FreeBSD >= 10.1

  Added in version 3.9.

- `AF_HYPERV` is a Windows-only socket based interface for communicating with Hyper-V hosts and guests. The address family is represented as a `(vm_id, service_id)` tuple where the `vm_id` and `service_id` are UUID strings.

  The `vm_id` is the virtual machine identifier or a set of known VMID values if the target is not a specific virtual machine. Known VMID constants defined on `socket` are:

  - `HV_GUID_ZERO`

  - `HV_GUID_BROADCAST`

  - `HV_GUID_WILDCARD` - Used to bind on itself and accept connections from all partitions.

  - `HV_GUID_CHILDREN` - Used to bind on itself and accept connection from child partitions.

  - `HV_GUID_LOOPBACK` - Used as a target to itself.

  - `HV_GUID_PARENT` - When used as a bind accepts connection from the parent partition. When used as an address target it will connect to the parent partition.

  The `service_id` is the service identifier of the registered service.

  Added in version 3.12.

Якщо ви використовуєте ім’я хоста в частині host адреси сокета IPv4/v6, програма може продемонструвати недетерміновану поведінку, оскільки Python використовує першу адресу, повернуту з вирішення DNS. Адреса сокета буде перетворена по-іншому в фактичну адресу IPv4/v6, залежно від результатів розв’язання DNS та/або конфігурації хоста. Для детермінованої поведінки використовуйте числову адресу в частині host.

Усі помилки викликають винятки. Можна викликати звичайні винятки для недійсних типів аргументів і умов браку пам’яті. Помилки, пов’язані із семантикою сокета чи адреси, викликають `OSError` або один із його підкласів.

Неблокуючий режим підтримується через `setblocking()`. Узагальнення цього на основі тайм-аутів підтримується через `settimeout()`.

## Зміст модуля

The module `socket` exports the following elements.

### Винятки

exception socket.error

  Застарілий псевдонім `OSError`.

  Змінено в версії 3.3: Після PEP 3151 цей клас отримав псевдонім `OSError`.

exception socket.herror

  Підклас `OSError`, цей виняток виникає для помилок, пов’язаних з адресою, тобто для функцій, які використовують h_errno в POSIX C API, включаючи `gethostbyname_ex()` і `gethostbyaddr()`. Супровідним значенням є пара `(h_errno, string)`, яка представляє помилку, яку повертає виклик бібліотеки. h_errno — це числове значення, тоді як string представляє опис h_errno, який повертає функція `hstrerror()` C.

  Змінено в версії 3.3: Цей клас було створено підкласом `OSError`.

exception socket.gaierror

  A subclass of `OSError`, this exception is raised for address-related errors by `getaddrinfo()` and `getnameinfo()`. The accompanying value is a pair `(error, string)` representing an error returned by a library call. string represents the description of error, as returned by the `gai_strerror()` C function. The numeric error value will match one of the `EAI_*` constants defined in this module.

  Змінено в версії 3.3: Цей клас було створено підкласом `OSError`.

exception socket.timeout

  Застарілий псевдонім `TimeoutError`.

  Підклас `OSError`, цей виняток виникає, коли тайм-аут виникає в сокеті, для якого було ввімкнено тайм-аути через попередній виклик `settimeout()` (або неявно через `setdefaulttimeout()`). Супровідне значення - це рядок, значення якого наразі завжди «закінчено».

  Змінено в версії 3.3: Цей клас було створено підкласом `OSError`.

  Змінено в версії 3.10: Цей клас отримав псевдонім `TimeoutError`.

### Константи

Константи AF_* і SOCK_* тепер є колекціями `AddressFamily` і `SocketKind` `IntEnum`.

Added in version 3.4.

socket.AF_UNIX
socket.AF_INET
socket.AF_INET6

  These constants represent the address (and protocol) families, used for the first argument to `socket()`. If the `AF_UNIX` constant is not defined then this protocol is unsupported. More constants may be available depending on the system.

socket.AF_UNSPEC

  `AF_UNSPEC` means that `getaddrinfo()` should return socket addresses for any address family (either IPv4, IPv6, or any other) that can be used.

socket.SOCK_STREAM
socket.SOCK_DGRAM
socket.SOCK_RAW
socket.SOCK_RDM
socket.SOCK_SEQPACKET

  These constants represent the socket types, used for the second argument to `socket()`. More constants may be available depending on the system. (Only `SOCK_STREAM` and `SOCK_DGRAM` appear to be generally useful.)

socket.SOCK_CLOEXEC
socket.SOCK_NONBLOCK

  Ці дві константи, якщо їх визначено, можна комбінувати з типами сокетів і дозволити вам встановлювати деякі прапори атомарно (таким чином уникаючи можливих умов змагання та потреби в окремих викликах).

  Дивись також

  Secure File Descriptor Handling for a more thorough explanation.

  Availability: Linux >= 2.6.27.

  Added in version 3.2.

SO_*
socket.SOMAXCONN
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*

  Many constants of these forms, documented in the Unix documentation on sockets and/or the IP protocol, are also defined in the socket module. They are generally used in arguments to the `setsockopt()` and `getsockopt()` methods of socket objects. In most cases, only those symbols that are defined in the Unix header files are defined; for a few symbols, default values are provided.

  Змінено в версії 3.6: Додано `SO_DOMAIN`, `SO_PROTOCOL`, `SO_PEERSEC`, `SO_PASSSEC`, `TCP_USER_TIMEOUT`, `TCP_CONGESTION`.

  Змінено в версії 3.6.5: Added support for `TCP_FASTOPEN`, `TCP_KEEPCNT` on Windows platforms when available.

  Змінено в версії 3.7: `TCP_NOTSENT_LOWAT` було додано.

  Added support for `TCP_KEEPIDLE`, `TCP_KEEPINTVL` on Windows platforms when available.

  Змінено в версії 3.10: `IP_RECVTOS` було додано. Додано `TCP_KEEPALIVE`. У MacOS цю константу можна використовувати так само, як `TCP_KEEPIDLE` використовується в Linux.

  Змінено в версії 3.11: Added `TCP_CONNECTION_INFO`. On MacOS this constant can be used in the same way that `TCP_INFO` is used on Linux and BSD.

  Змінено в версії 3.12: Added `SO_RTABLE` and `SO_USER_COOKIE`. On OpenBSD and FreeBSD respectively those constants can be used in the same way that `SO_MARK` is used on Linux. Also added missing TCP socket options from Linux: `TCP_MD5SIG`, `TCP_THIN_LINEAR_TIMEOUTS`, `TCP_THIN_DUPACK`, `TCP_REPAIR`, `TCP_REPAIR_QUEUE`, `TCP_QUEUE_SEQ`, `TCP_REPAIR_OPTIONS`, `TCP_TIMESTAMP`, `TCP_CC_INFO`, `TCP_SAVE_SYN`, `TCP_SAVED_SYN`, `TCP_REPAIR_WINDOW`, `TCP_FASTOPEN_CONNECT`, `TCP_ULP`, `TCP_MD5SIG_EXT`, `TCP_FASTOPEN_KEY`, `TCP_FASTOPEN_NO_COOKIE`, `TCP_ZEROCOPY_RECEIVE`, `TCP_INQ`, `TCP_TX_DELAY`. Added `IP_PKTINFO`, `IP_UNBLOCK_SOURCE`, `IP_BLOCK_SOURCE`, `IP_ADD_SOURCE_MEMBERSHIP`, `IP_DROP_SOURCE_MEMBERSHIP`.

  Змінено в версії 3.13: Added `SO_BINDTOIFINDEX`. On Linux this constant can be used in the same way that `SO_BINDTODEVICE` is used, but with the index of a network interface instead of its name.

  Змінено в версії 3.14: Added missing `IP_FREEBIND`, `IP_RECVERR`, `IPV6_RECVERR`, `IP_RECVTTL`, and `IP_RECVORIGDSTADDR` on Linux.

  Змінено в версії 3.14: Added support for `TCP_QUICKACK` on Windows platforms when available.

  Змінено в версії 3.15: `IPV6_HDRINCL` was added.

socket.AF_CAN
socket.PF_CAN
SOL_CAN_*
CAN_*

  Багато констант цих форм, задокументованих у документації Linux, також визначені в модулі сокета.

  Availability: Linux >= 2.6.25, NetBSD >= 8.

  Added in version 3.3.

  Змінено в версії 3.11: NetBSD support was added.

  Змінено в версії 3.14: Restored missing `CAN_RAW_ERR_FILTER` on Linux.

socket.CAN_BCM
CAN_BCM_*

  CAN_BCM, у сімействі протоколів CAN, є протоколом менеджера трансляції (BCM). Константи менеджера трансляції, задокументовані в документації Linux, також визначені в модулі сокета.

  Availability: Linux >= 2.6.25.

  Примітка

  Прапор `CAN_BCM_CAN_FD_FRAME` доступний лише в Linux >= 4.8.

  Added in version 3.4.

socket.CAN_RAW_FD_FRAMES

  Вмикає підтримку CAN FD у гнізді CAN_RAW. За замовчуванням це вимкнено. Це дозволяє вашій програмі надсилати кадри CAN і CAN FD; однак під час читання з роз’єму ви повинні приймати як CAN, так і CAN FD кадри.

  Ця константа задокументована в документації Linux.

  Availability: Linux >= 3.6.

  Added in version 3.5.

socket.CAN_RAW_JOIN_FILTERS

  Об’єднує застосовані фільтри CAN, щоб у простір користувача передавалися лише кадри CAN, які відповідають усім наданим фільтрам CAN.

  Ця константа задокументована в документації Linux.

  Availability: Linux >= 4.1.

  Added in version 3.9.

socket.CAN_ISOTP

  CAN_ISOTP у сімействі протоколів CAN є протоколом ISO-TP (ISO 15765-2). Константи ISO-TP, задокументовані в документації Linux.

  Availability: Linux >= 2.6.25.

  Added in version 3.7.

socket.CAN_J1939

  CAN_J1939 у сімействі протоколів CAN є протоколом SAE J1939. Константи J1939, задокументовані в документації Linux.

  Availability: Linux >= 5.4.

  Added in version 3.9.

socket.AF_DIVERT
socket.PF_DIVERT

  These two constants, documented in the FreeBSD divert(4) manual page, are also defined in the socket module.

  Availability: FreeBSD >= 14.0.

  Added in version 3.12.

socket.AF_PACKET
socket.PF_PACKET
PACKET_*

  Багато констант цих форм, задокументованих у документації Linux, також визначені в модулі сокета.

  Availability: Linux >= 2.2.

socket.ETH_P_ALL

  `ETH_P_ALL` can be used in the `socket` constructor as proto for the `AF_PACKET` family in order to capture every packet, regardless of protocol.

  For more information, see the packet(7) manpage.

  Availability: Linux.

  Added in version 3.12.

socket.AF_RDS
socket.PF_RDS
socket.SOL_RDS
RDS_*

  Багато констант цих форм, задокументованих у документації Linux, також визначені в модулі сокета.

  Availability: Linux >= 2.6.30.

  Added in version 3.3.

socket.SIO_RCVALL
socket.SIO_KEEPALIVE_VALS
socket.SIO_LOOPBACK_FAST_PATH
RCVALL_*

  Константи для Windows WSAIoctl(). Константи використовуються як аргументи методу `ioctl()` об’єктів сокета.

  Змінено в версії 3.6: `SIO_LOOPBACK_FAST_PATH` було додано.

TIPC_*

  Константи, пов’язані з TIPC, що збігаються з тими, які експортує API сокета C. Додаткову інформацію див. у документації TIPC.

socket.AF_ALG
socket.SOL_ALG
ALG_*

  Константи для криптографії ядра Linux.

  Availability: Linux >= 2.6.38.

  Added in version 3.6.

socket.AF_VSOCK
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID
VMADDR*
SO_VM*

  Константи для зв’язку хост/гость Linux.

  Availability: Linux >= 4.8.

  Added in version 3.7.

socket.AF_LINK

  Availability: BSD, macOS.

  Added in version 3.4.

socket.has_ipv6

  Ця константа містить логічне значення, яке вказує, чи підтримується IPv6 на цій платформі.

socket.AF_BLUETOOTH
socket.BTPROTO_L2CAP
socket.BTPROTO_RFCOMM
socket.BTPROTO_HCI
socket.BTPROTO_SCO

  Integer constants for use with Bluetooth addresses.

socket.BDADDR_ANY
socket.BDADDR_LOCAL

  Це рядкові константи, що містять адреси Bluetooth зі спеціальними значеннями. Наприклад, `BDADDR_ANY` можна використовувати для вказівки будь-якої адреси, коли вказується сокет прив’язки за допомогою `BTPROTO_RFCOMM`.

socket.BDADDR_BREDR
socket.BDADDR_LE_PUBLIC
socket.BDADDR_LE_RANDOM

  These constants describe the Bluetooth address type when binding or connecting a `BTPROTO_L2CAP` socket.

  Availability: Linux, FreeBSD

  Added in version 3.14.

socket.SOL_RFCOMM
socket.SOL_L2CAP
socket.SOL_HCI
socket.SOL_SCO
socket.SOL_BLUETOOTH

  Used in the level argument to the `setsockopt()` and `getsockopt()` methods of Bluetooth socket objects.

  `SOL_BLUETOOTH` is only available on Linux. Other constants are available if the corresponding protocol is supported.

SO_L2CAP_*
socket.L2CAP_LM
L2CAP_LM_*
SO_RFCOMM_*
RFCOMM_LM_*
SO_SCO_*
SO_BTH_*
BT_*

  Used in the option name and value argument to the `setsockopt()` and `getsockopt()` methods of Bluetooth socket objects.

  `BT_*` and `L2CAP_LM` are only available on Linux. `SO_BTH_*` are only available on Windows. Other constants may be available on Linux and various BSD platforms.

  Added in version 3.14.

socket.HCI_FILTER
socket.HCI_TIME_STAMP
socket.HCI_DATA_DIR
socket.SO_HCI_EVT_FILTER
socket.SO_HCI_PKT_FILTER

  Option names for use with `BTPROTO_HCI`. Availability and format of the option values depend on platform.

  Змінено в версії 3.14: Added `SO_HCI_EVT_FILTER` and `SO_HCI_PKT_FILTER` on NetBSD and DragonFly BSD. Added `HCI_DATA_DIR` on FreeBSD, NetBSD and DragonFly BSD.

socket.HCI_DEV_NONE

  The `device_id` value used to create an HCI socket that isn’t specific to a single Bluetooth adapter.

  Availability: Linux

  Added in version 3.14.

socket.HCI_CHANNEL_RAW
socket.HCI_CHANNEL_USER
socket.HCI_CHANNEL_MONITOR
socket.HCI_CHANNEL_CONTROL
socket.HCI_CHANNEL_LOGGING

  Possible values for `channel` field in the `BTPROTO_HCI` address.

  Availability: Linux

  Added in version 3.14.

socket.AF_QIPCRTR

  Константа для протоколу маршрутизатора IPC Qualcomm, який використовується для зв’язку з віддаленими процесорами, що надають послуги.

  Availability: Linux >= 4.7.

socket.SCM_CREDS2
socket.LOCAL_CREDS
socket.LOCAL_CREDS_PERSISTENT

  LOCAL_CREDS and LOCAL_CREDS_PERSISTENT can be used with SOCK_DGRAM, SOCK_STREAM sockets, equivalent to Linux/DragonFlyBSD SO_PASSCRED, while LOCAL_CREDS sends the credentials at first read, LOCAL_CREDS_PERSISTENT sends for each read, SCM_CREDS2 must be then used for the latter for the message type.

  Added in version 3.11.

  Availability: FreeBSD.

socket.SO_INCOMING_CPU

  Constant to optimize CPU locality, to be used in conjunction with `SO_REUSEPORT`.

  Added in version 3.11.

  Availability: Linux >= 3.9

socket.SO_REUSEPORT_LB

  > Constant to enable duplicate address and port bindings with load balancing.

  Added in version 3.14.

  Availability: FreeBSD >= 12.0

socket.AF_HYPERV
socket.HV_PROTOCOL_RAW
socket.HVSOCKET_CONNECT_TIMEOUT
socket.HVSOCKET_CONNECT_TIMEOUT_MAX
socket.HVSOCKET_CONNECTED_SUSPEND
socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU
socket.HV_GUID_ZERO
socket.HV_GUID_WILDCARD
socket.HV_GUID_BROADCAST
socket.HV_GUID_CHILDREN
socket.HV_GUID_LOOPBACK
socket.HV_GUID_PARENT

  Constants for Windows Hyper-V sockets for host/guest communications.

  Availability: Windows.

  Added in version 3.12.

socket.ETHERTYPE_ARP
socket.ETHERTYPE_IP
socket.ETHERTYPE_IPV6
socket.ETHERTYPE_VLAN

  IEEE 802.3 protocol number. constants.

  Availability: Linux, FreeBSD, macOS.

  Added in version 3.12.

socket.SHUT_RD
socket.SHUT_WR
socket.SHUT_RDWR

  These constants are used by the `shutdown()` method of socket objects.

  Availability: not WASI.

### Функції

#### Створення сокетів

Усі наступні функції створюють об’єкти socket.

class socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)

  Створіть новий сокет, використовуючи вказане сімейство адрес, тип сокета та номер протоколу. Сімейство адрес має бути `AF_INET` (за замовчуванням), `AF_INET6`, `AF_UNIX`, `AF_CAN`, `AF_PACKET` або `AF_RDS`. Тип сокета має бути `SOCK_STREAM` (за замовчуванням), `SOCK_DGRAM`, `SOCK_RAW` або, можливо, одна з інших констант `SOCK_`. Номер протоколу зазвичай дорівнює нулю і може бути пропущений або у випадку, коли сімейство адрес `AF_CAN`, протокол має бути одним із `CAN_RAW`, `CAN_BCM`, `CAN_ISOTP` або `CAN_J1939`.

  If fileno is specified, the values for family, type, and proto are auto-detected from the specified file descriptor. Auto-detection can be overruled by calling the function with explicit family, type, or proto arguments. This only affects how Python represents e.g. the return value of `socket.getpeername()` but not the actual OS resource. Unlike `socket.fromfd()`, fileno will return the same socket and not a duplicate. This may help close a detached socket using `socket.close()`.

  Новостворений сокет не успадковується.

  Викликає подію аудиту `socket.__new__` з аргументами `self`, `family`, `type`, `protocol`.

  Змінено в версії 3.3: Додано сімейство AF_CAN. Додано сімейство AF_RDS.

  Змінено в версії 3.4: Додано протокол CAN_BCM.

  Змінено в версії 3.4: Повернений сокет тепер не успадковується.

  Змінено в версії 3.7: Додано протокол CAN_ISOTP.

  Змінено в версії 3.7: When `SOCK_NONBLOCK` or `SOCK_CLOEXEC` bit flags are applied to type they are cleared, and `socket.type` will not reflect them. They are still passed to the underlying system `socket()` call. Therefore,

      sock = socket.socket(
          socket.AF_INET,
          socket.SOCK_STREAM | socket.SOCK_NONBLOCK)

  усе одно створить неблокуючий сокет в ОС, які підтримують `SOCK_NONBLOCK`, але `sock.type` буде встановлено на `socket.SOCK_STREAM`.

  Змінено в версії 3.9: Додано протокол CAN_J1939.

  Змінено в версії 3.10: Додано протокол IPPROTO_MPTCP.

socket.socketpair([family[, type[, proto]]])

  Build a pair of connected socket objects using the given address family, socket type, and protocol number. Address family, socket type, and protocol number are as for the `socket()` function above. The default family is `AF_UNIX` if defined on the platform; otherwise, the default is `AF_INET`.

  Новостворені сокети не успадковуються.

  Змінено в версії 3.2: Повернені об’єкти сокета тепер підтримують весь API сокета, а не його підмножину.

  Змінено в версії 3.4: Повернені сокети тепер не успадковуються.

  Змінено в версії 3.5: Додано підтримку Windows.

socket.create_connection(address, timeout=GLOBAL_DEFAULT, source_address=None, *, all_errors=False)

  Підключіться до служби TCP, яка прослуховує адресу в Інтернеті (2-кортеж `(хост, порт)`) і поверніть об’єкт сокета. Це функція вищого рівня, ніж `socket.connect()`: якщо host є нечисловим ім’ям хоста, вона намагатиметься вирішити його як для `AF_INET`, так і для `AF_INET6`, а потім спробуйте підключитися до всіх можливих адрес по черзі, доки підключення не вдасться. Це полегшує написання клієнтів, сумісних як з IPv4, так і з IPv6.

  Передача додаткового параметра timeout встановить час очікування для екземпляра сокета перед спробою підключення. Якщо тайм-аут не вказано, використовується глобальне налаштування тайм-ауту за умовчанням, яке повертає `getdefaulttimeout()`.

  Якщо надано, source_address має бути 2-кортежем `(хост, порт)`, щоб сокет прив’язувався до своєї адреси джерела перед підключенням. Якщо хост або порт мають значення „“ або 0 відповідно, буде використано типову поведінку ОС.

  When a connection cannot be created, an exception is raised. By default, it is the exception from the last address in the list. If all_errors is `True`, it is an `ExceptionGroup` containing the errors of all attempts.

  Змінено в версії 3.2: вихідна_адреса була додана.

  Змінено в версії 3.11: all_errors was added.

socket.create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)

  Convenience function which creates a TCP socket bound to address (a 2-tuple `(host, port)`) and returns the socket object.

  family should be either `AF_INET` or `AF_INET6`. backlog is the queue size passed to `socket.listen()`; if not specified , a default reasonable value is chosen. reuse_port dictates whether to set the `SO_REUSEPORT` socket option.

  If dualstack_ipv6 is true, family is `AF_INET6` and the platform supports it the socket will be able to accept both IPv4 and IPv6 connections, else it will raise `ValueError`. Most POSIX platforms and Windows are supposed to support this functionality. When this functionality is enabled the address returned by `socket.getpeername()` when an IPv4 connection occurs will be an IPv6 address represented as an IPv4-mapped IPv6 address. If dualstack_ipv6 is false it will explicitly disable this functionality on platforms that enable it by default (e.g. Linux). This parameter can be used in conjunction with `has_dualstack_ipv6()`:

      import socket

      addr = ("", 8080)  # all interfaces, port 8080
      if socket.has_dualstack_ipv6():
          s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
      else:
          s = socket.create_server(addr)

  Примітка

  На платформах POSIX параметр сокета `SO_REUSEADDR` встановлено для негайного повторного використання попередніх сокетів, які були прив’язані до тієї самої адреси та залишалися в стані TIME_WAIT.

  Added in version 3.8.

socket.has_dualstack_ipv6()

  Повертає `True`, якщо платформа підтримує створення TCP-сокета, який може обробляти з’єднання IPv4 і IPv6.

  Added in version 3.8.

socket.fromfd(fd, family, type, proto=0)

  Duplicate the file descriptor fd (an integer as returned by a file object’s `fileno()` method) and build a socket object from the result. Address family, socket type and protocol number are as for the `socket()` function above. The file descriptor should refer to a socket, but this is not checked — subsequent operations on the object may fail if the file descriptor is invalid. This function is rarely needed, but can be used to get or set socket options on a socket passed to a program as standard input or output (such as a server started by the Unix inet daemon). The socket is assumed to be in blocking mode.

  Новостворений сокет не успадковується.

  Змінено в версії 3.4: Повернений сокет тепер не успадковується.

socket.fromshare(data)

  Створіть екземпляр сокета з даних, отриманих з методу `socket.share()`. Передбачається, що розетка знаходиться в режимі блокування.

  Availability: Windows.

  Added in version 3.3.

socket.SocketType

  Це об’єкт типу Python, який представляє тип об’єкта сокета. Це те саме, що `type(socket(...))`.

#### Інші функції

The `socket` module also offers various network-related services:

socket.close(fd)

  Закрийте дескриптор файлу сокета. Це як `os.close()`, але для сокетів. На деяких платформах (найбільш помітна Windows) `os.close()` не працює для дескрипторів файлів сокетів.

  Added in version 3.7.

socket.getaddrinfo(host, port, family=AF_UNSPEC, type=0, proto=0, flags=0)

  This function wraps the C function `getaddrinfo` of the underlying system.

  Переведіть аргумент host/port у послідовність із 5 кортежів, які містять усі необхідні аргументи для створення сокета, підключеного до цієї служби. host – це доменне ім’я, рядкове представлення адреси IPv4/v6 або `None`. порт — це рядкова назва служби, наприклад `'http'`, числовий номер порту або `None`. Передаючи `None` як значення host і port, ви можете передати `NULL` базовому C API.

  The family, type and proto arguments can be optionally specified in order to provide options and limit the list of addresses returned. Pass their default values (`AF_UNSPEC`, 0, and 0, respectively) to not limit the results. See the note below for details.

  The flags argument can be one or several of the `AI_*` constants, and will influence how results are computed and returned. For example, `AI_NUMERICHOST` will disable domain name resolution and will raise an error if host is a domain name.

  Функція повертає список із 5-ти кортежів із такою структурою:

  `(сімейство, тип, прото, canonname, sockaddr)`

  In these tuples, family, type, proto are all integers and are meant to be passed to the `socket()` function. canonname will be a string representing the canonical name of the host if `AI_CANONNAME` is part of the flags argument; else canonname will be empty. sockaddr is a tuple describing a socket address, whose format depends on the returned family and flags Python was compiled with, and is meant to be passed to the `socket.connect()` method.

  sockaddr can be one of the following:

  - a `(address, port)` 2-tuple for `AF_INET`

  - a `(address, port, flowinfo, scope_id)` 4-tuple for `AF_INET6` if Python was compiled with `--enable-ipv6` (the default)

  - a 2-tuple containing raw data for `AF_INET6` if Python was compiled with `--disable-ipv6`

  Примітка

  If you intend to use results from `getaddrinfo()` to create a socket (rather than, for example, retrieve canonname), consider limiting the results by type (e.g. `SOCK_STREAM` or `SOCK_DGRAM`) and/or proto (e.g. `IPPROTO_TCP` or `IPPROTO_UDP`) that your application can handle.

  The behavior with default values of family, type, proto and flags is system-specific.

  Many systems (for example, most Linux configurations) will return a sorted list of all matching addresses. These addresses should generally be tried in order until a connection succeeds (possibly tried in parallel, for example, using a Happy Eyeballs algorithm). In these cases, limiting the type and/or proto can help eliminate unsuccessful or unusable connection attempts.

  Some systems will, however, only return a single address. (For example, this was reported on Solaris and AIX configurations.) On these systems, limiting the type and/or proto helps ensure that this address is usable.

  Викликає подію аудиту `socket.getaddrinfo` з аргументами `хост`, `порт`, `сімейство`, `тип`, `протокол`.

  У наступному прикладі отримується інформація про адресу для гіпотетичного TCP-з’єднання з `example.org` на порту 80 (результати можуть відрізнятися у вашій системі, якщо IPv6 не ввімкнено):

      >>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
      [(socket.AF_INET6, socket.SOCK_STREAM,
       6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
       (socket.AF_INET, socket.SOCK_STREAM,
       6, '', ('93.184.216.34', 80))]

  Змінено в версії 3.2: параметри тепер можна передавати за допомогою аргументів ключових слів.

  Змінено в версії 3.7: для багатоадресних адрес IPv6 рядок, що представляє адресу, не міститиме частину `%scope_id`.

socket.getfqdn([name])

  Повернути повне доменне ім’я для name. Якщо ім’я опущене або порожнє, воно інтерпретується як локальний хост. Щоб знайти повне ім’я, перевіряється ім’я хоста, яке повертає `gethostbyaddr()`, а потім ідуть псевдоніми хоста, якщо вони доступні. Вибрано перше ім’я, яке містить крапку. Якщо повне доменне ім’я недоступне, а було вказано ім’я, воно повертається без змін. Якщо name було порожнім або дорівнює `'0.0.0.0'`, повертається ім’я хоста з `gethostname()`.

socket.gethostbyname(hostname)

  Перекладіть ім’я хоста у формат адреси IPv4. Адреса IPv4 повертається у вигляді рядка, наприклад `'100.50.200.5`. Якщо ім’я хоста є адресою IPv4, воно повертається без змін. Дивіться `gethostbyname_ex()` для більш повного інтерфейсу. `gethostbyname()` не підтримує розпізнавання імен IPv6, а `getaddrinfo()` слід використовувати замість цього для підтримки подвійного стеку IPv4/v6.

  Викликає подію аудиту `socket.gethostbyname` з аргументом `hostname`.

  Availability: not WASI.

socket.gethostbyname_ex(hostname)

  Translate a host name to IPv4 address format, extended interface. Return a 3-tuple `(hostname, aliaslist, ipaddrlist)` where hostname is the host’s primary host name, aliaslist is a (possibly empty) list of alternative host names for the same address, and ipaddrlist is a list of IPv4 addresses for the same interface on the same host (often but not always a single address). `gethostbyname_ex()` does not support IPv6 name resolution, and `getaddrinfo()` should be used instead for IPv4/v6 dual stack support.

  Викликає подію аудиту `socket.gethostbyname` з аргументом `hostname`.

  Availability: not WASI.

socket.gethostname()

  Повертає рядок, що містить ім’я хоста машини, на якій зараз виконується інтерпретатор Python.

  Викликає подію аудиту `socket.gethostname` без аргументів.

  Примітка: `gethostname()` не завжди повертає повне доменне ім’я; використовуйте для цього `getfqdn()`.

  Availability: not WASI.

socket.gethostbyaddr(ip_address)

  Return a 3-tuple `(hostname, aliaslist, ipaddrlist)` where hostname is the primary host name responding to the given ip_address, aliaslist is a (possibly empty) list of alternative host names for the same address, and ipaddrlist is a list of IPv4/v6 addresses for the same interface on the same host (most likely containing only a single address). To find the fully qualified domain name, use the function `getfqdn()`. `gethostbyaddr()` supports both IPv4 and IPv6.

  Викликає подію аудиту `socket.gethostbyaddr` з аргументом `ip_address`.

  Availability: not WASI.

socket.getnameinfo(sockaddr, flags)

  Translate a socket address sockaddr into a 2-tuple `(host, port)`. Depending on the settings of flags, the result can contain a fully qualified domain name or numeric address representation in host. Similarly, port can contain a string port name or a numeric port number.

  Для адрес IPv6 `%scope_id` додається до частини хоста, якщо sockaddr містить значимий scope_id. Зазвичай це відбувається для багатоадресних адрес.

  Для отримання додаткової інформації про прапори ви можете звернутися до getnameinfo(3).

  Викликає подію аудиту `socket.getnameinfo` з аргументом `sockaddr`.

  Availability: not WASI.

socket.getprotobyname(protocolname)

  Translate an internet protocol name (for example, `'icmp'`) to a constant suitable for passing as the (optional) third argument to the `socket()` function. This is usually only needed for sockets opened in «raw» mode (`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen automatically if the protocol is omitted or zero.

  Availability: not WASI.

socket.getservbyname(servicename[, protocolname])

  Перекладіть назву інтернет-сервісу та назву протоколу на номер порту для цієї служби. Додаткова назва протоколу, якщо її вказано, має бути `'tcp'` або `'udp'`, інакше будь-який протокол збігатиметься.

  Викликає подію аудиту `socket.getservbyname` з аргументами `servicename`, `protocolname`.

  Availability: not WASI.

socket.getservbyport(port[, protocolname])

  Перекладіть номер інтернет-порту та назву протоколу на назву служби для цієї служби. Додаткова назва протоколу, якщо її вказано, має бути `'tcp'` або `'udp'`, інакше будь-який протокол збігатиметься.

  Викликає подію аудиту `socket.getservbyport` з аргументами `port`, `protocolname`.

  Availability: not WASI.

socket.ntohl(x)

  Перетворення 32-розрядних додатних чисел із мережевого порядку байтів на хост. На машинах, де порядок байтів хоста збігається з порядком байтів у мережі, це заборонено; інакше він виконує 4-байтову операцію обміну.

socket.ntohs(x)

  Перетворення 16-розрядних додатних чисел із мережевого порядку байтів на хост. На машинах, де порядок байтів хоста збігається з порядком байтів у мережі, це заборонено; інакше він виконує 2-байтову операцію обміну.

  Змінено в версії 3.10: Викликає `OverflowError`, якщо x не вміщується в 16-бітне ціле число без знаку.

socket.htonl(x)

  Перетворюйте 32-розрядні додатні цілі числа з хоста на мережевий порядок байтів. На машинах, де порядок байтів хоста збігається з порядком байтів у мережі, це заборонено; інакше він виконує 4-байтову операцію обміну.

socket.htons(x)

  Перетворення 16-розрядних додатних чисел із хоста в мережевий порядок байтів. На машинах, де порядок байтів хоста збігається з порядком байтів у мережі, це заборонено; інакше він виконує 2-байтову операцію обміну.

  Змінено в версії 3.10: Викликає `OverflowError`, якщо x не вміщується в 16-бітне ціле число без знаку.

socket.inet_aton(ip_string)

  Convert an IPv4 address from dotted-quad string format (for example, „123.45.67.89“) to 32-bit packed binary format, as a bytes object four characters in length. This is useful when conversing with a program that uses the standard C library and needs objects of type `in_addr`, which is the C type for the 32-bit packed binary this function returns.

  `inet_aton()` також приймає рядки з менш ніж трьома крапками; подробиці див. на сторінці посібника Unix inet(3).

  Якщо рядок адреси IPv4, переданий цій функції, недійсний, буде викликано `OSError`. Зауважте, що саме те, що є дійсним, залежить від базової реалізації C `inet_aton()`.

  `inet_aton()` не підтримує IPv6, а `inet_pton()` слід використовувати замість цього для підтримки подвійного стеку IPv4/v6.

socket.inet_ntoa(packed_ip)

  Convert a 32-bit packed IPv4 address (a bytes-like object four bytes in length) to its standard dotted-quad string representation (for example, „123.45.67.89“). This is useful when conversing with a program that uses the standard C library and needs objects of type `in_addr`, which is the C type for the 32-bit packed binary data this function takes as an argument.

  Якщо послідовність байтів, передана цій функції, не має довжини точно 4 байти, виникне `OSError`. `inet_ntoa()` не підтримує IPv6, а `inet_ntop()` слід використовувати замість цього для підтримки подвійного стеку IPv4/v6.

  Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

socket.inet_pton(address_family, ip_string)

  Convert an IP address from its family-specific string format to a packed, binary format. `inet_pton()` is useful when a library or network protocol calls for an object of type `in_addr` (similar to `inet_aton()`) or `in6_addr`.

  Підтримувані значення для address_family наразі: `AF_INET` і `AF_INET6`. Якщо рядок IP-адреси ip_string недійсний, виникне `OSError`. Зауважте, що саме те, що є дійсним, залежить як від значення address_family, так і від базової реалізації `inet_pton()`.

  Availability: Unix, Windows.

  Змінено в версії 3.4: Додано підтримку Windows

socket.inet_ntop(address_family, packed_ip)

  Convert a packed IP address (a bytes-like object of some number of bytes) to its standard, family-specific string representation (for example, `'7.10.0.5'` or `'5aef:2b::8'`). `inet_ntop()` is useful when a library or network protocol returns an object of type `in_addr` (similar to `inet_ntoa()`) or `in6_addr`.

  Підтримувані значення для address_family наразі: `AF_INET` і `AF_INET6`. Якщо об’єкт bytes packed_ip не має правильної довжини для вказаного сімейства адрес, буде викликано `ValueError`. `OSError` викликається для помилок виклику `inet_ntop()`.

  Availability: Unix, Windows.

  Змінено в версії 3.4: Додано підтримку Windows

  Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

socket.CMSG_LEN(length)

  Повертає загальну довжину, без заповнення в кінці, елемента допоміжних даних із пов’язаними даними заданої довжини. Це значення часто можна використовувати як розмір буфера для `recvmsg()` для отримання окремого елемента допоміжних даних, але RFC 3542 вимагає, щоб портативні програми використовували `CMSG_SPACE()` і таким чином включали простір для заповнення, навіть якщо елемент буде останнім у буфері. Викликає `OverflowError`, якщо length виходить за межі допустимого діапазону значень.

  Availability: Unix, not WASI.

  Most Unix platforms.

  Added in version 3.3.

socket.CMSG_SPACE(length)

  Повертає розмір буфера, необхідний для `recvmsg()` для отримання елемента допоміжних даних із пов’язаними даними заданої довжини разом із будь-яким доповненням у кінці. Буферний простір, необхідний для отримання кількох елементів, є сумою значень `CMSG_SPACE()` для відповідної довжини даних. Викликає `OverflowError`, якщо length виходить за межі допустимого діапазону значень.

  Зауважте, що деякі системи можуть підтримувати допоміжні дані без надання цієї функції. Також зауважте, що встановлення розміру буфера за допомогою результатів цієї функції може не обмежувати точно кількість допоміжних даних, які можна отримати, оскільки додаткові дані можуть поміститися в область заповнення.

  Availability: Unix, not WASI.

  most Unix platforms.

  Added in version 3.3.

socket.getdefaulttimeout()

  Повертає стандартний час очікування в секундах (float) для нових об’єктів сокета. Значення `None` вказує на те, що нові об’єкти сокета не мають часу очікування. Коли модуль сокета імпортовано вперше, за замовчуванням буде `None`.

socket.setdefaulttimeout(timeout)

  Set the default timeout in seconds (real number) for new socket objects. When the socket module is first imported, the default is `None`. See `settimeout()` for possible values and their respective meanings.

  Змінено в версії 3.15: Accepts any real number, not only integer or float.

socket.sethostname(name)

  Встановіть ім’я хоста машини на name. Це викличе `OSError`, якщо у вас недостатньо прав.

  Викликає подію аудиту `socket.sethostname` з аргументом `name`.

  Availability: Unix, not Android.

  Added in version 3.3.

socket.if_nameindex()

  Повертає список кортежів інформації про мережевий інтерфейс (index int, name string). `OSError`, якщо системний виклик не вдається.

  Availability: Unix, Windows, not WASI.

  Added in version 3.3.

  Змінено в версії 3.8: Додано підтримку Windows.

  Примітка

  У Windows мережеві інтерфейси мають різні імена в різних контекстах (усі імена є прикладами):

  - UUID: `{FB605B73-AAC2-49A6-9A2F-25416AEA0573}`

  - назва: `ethernet_32770`

  - зрозуміла назва: `vEthernet (nat)`

  - опис: `Hyper-V Virtual Ethernet Adapter`

  Ця функція повертає імена другої форми зі списку, `ethernet_32770` у цьому прикладі.

socket.if_nametoindex(if_name)

  Повертає номер індексу мережевого інтерфейсу, який відповідає імені інтерфейсу. `OSError`, якщо не існує інтерфейсу з вказаною назвою.

  Availability: Unix, Windows, not WASI.

  Added in version 3.3.

  Змінено в версії 3.8: Додано підтримку Windows.

  Дивись також

  «Назва інтерфейсу» — це назва, задокументована в `if_nameindex()`.

socket.if_indextoname(if_index)

  Повертає назву мережевого інтерфейсу, що відповідає номеру індексу інтерфейсу. `OSError`, якщо не існує інтерфейсу з даним індексом.

  Availability: Unix, Windows, not WASI.

  Added in version 3.3.

  Змінено в версії 3.8: Додано підтримку Windows.

  Дивись також

  «Назва інтерфейсу» — це назва, задокументована в `if_nameindex()`.

socket.send_fds(sock, buffers, fds[, flags[, address]])

  Send the list of file descriptors fds over an `AF_UNIX` socket sock. The fds parameter is a sequence of file descriptors. Consult `sendmsg()` for the documentation of these parameters.

  Availability: Unix, not WASI.

  Unix platforms supporting `sendmsg()` and `SCM_RIGHTS` mechanism.

  Added in version 3.9.

socket.recv_fds(sock, bufsize, maxfds[, flags])

  Receive up to maxfds file descriptors from an `AF_UNIX` socket sock. Return `(msg, list(fds), flags, addr)`. Consult `recvmsg()` for the documentation of these parameters.

  Availability: Unix, not WASI.

  Unix platforms supporting `recvmsg()` and `SCM_RIGHTS` mechanism.

  Added in version 3.9.

  Примітка

  Будь-які скорочені цілі числа в кінці списку дескрипторів файлів.

## Об’єкти Socket

Об’єкти Socket мають такі методи. За винятком `makefile()`, вони відповідають системним викликам Unix, застосовним до сокетів.

Змінено в версії 3.2: Додано підтримку протоколу context manager. Вихід із контекстного менеджера еквівалентний виклику `close()`.

socket.accept()

  Прийняти підключення. Сокет має бути прив’язаний до адреси та прослуховувати підключення. Поверненим значенням є пара `(conn, address)`, де conn — це новий об’єкт сокета, який можна використовувати для надсилання та отримання даних під час з’єднання, а address — це адреса, прив’язана до сокета на іншому кінець з’єднання.

  Новостворений сокет не успадковується.

  Змінено в версії 3.4: Тепер сокет не успадковується.

  Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток `InterruptedError` (перегляньте PEP 475 для обґрунтування).

socket.bind(address)

  Прив’яжіть сокет до адреси. Розетка ще не повинна бути прив’язаною. (Формат адреси залежить від групи адрес — див. вище.)

  Викликає подію аудиту `socket.bind` з аргументами `self`, `address`.

  Availability: not WASI.

socket.close()

  Mark the socket closed. The underlying system resource (e.g. a file descriptor) is also closed when all file objects from `makefile()` are closed. Once that happens, all future operations on the socket object will fail. The remote end will receive no more data (after queued data is flushed).

  Сокети автоматично закриваються під час збирання сміття, але рекомендується `close()` їх явно або використовувати оператор `with` навколо них.

  Змінено в версії 3.6: `OSError` тепер викликається, якщо виникає помилка під час основного виклику `close()`.

  Примітка

  `close()` releases the resource associated with a connection but does not necessarily close the connection immediately. If you want to close the connection in a timely fashion, call `shutdown()` before `close()`.

socket.connect(address)

  Підключіться до віддаленої розетки за адресою. (Формат адреси залежить від групи адрес — див. вище.)

  Якщо з’єднання перервано сигналом, метод чекає, доки з’єднання не завершиться, або викликає `TimeoutError` після тайм-ауту, якщо обробник сигналу не викликає виключення, а сокет блокується або має тайм-аут. Для неблокуючих сокетів метод викликає виняток `InterruptedError`, якщо з’єднання переривається сигналом (або винятком, викликаним обробником сигналу).

  Викликає подію аудиту `socket.connect` з аргументами `self`, `address`.

  Змінено в версії 3.5: Тепер метод очікує, доки з’єднання завершиться, замість того, щоб викликати виняток `InterruptedError`, якщо з’єднання перервано сигналом, обробник сигналу не викликає виключення, а сокет блокується або має тайм-аут (див. PEP 475 для обґрунтування).

  Availability: not WASI.

socket.connect_ex(address)

  Подібно до `connect(address)`, але повертає індикатор помилки замість виклику винятку для помилок, які повертає виклик `connect()` рівня C (інші проблеми, такі як «хост не знайдено», можуть все ще викликають винятки). Індикатор помилки – `0`, якщо операція виконана успішно, інакше значення змінної `errno`. Це корисно для підтримки, наприклад, асинхронних підключень.

  Викликає подію аудиту `socket.connect` з аргументами `self`, `address`.

  Availability: not WASI.

socket.detach()

  Переведіть об’єкт сокета в закритий стан, фактично не закриваючи базовий файловий дескриптор. Файловий дескриптор повертається, і його можна повторно використовувати для інших цілей.

  Added in version 3.2.

socket.dup()

  Дублюйте розетку.

  Новостворений сокет не успадковується.

  Змінено в версії 3.4: Тепер сокет не успадковується.

  Availability: not WASI.

socket.fileno()

  Повертає дескриптор файлу сокета (мале ціле число) або -1 у разі помилки. Це корисно з `select.select()`.

  Під Windows мале ціле число, яке повертає цей метод, не можна використовувати там, де можна використовувати дескриптор файлу (наприклад, `os.fdopen()`). Unix не має цього обмеження.

socket.get_inheritable()

  Отримайте inheritable flag дескриптора файлу сокета або дескриптора сокета: `True`, якщо сокет можна успадкувати в дочірніх процесах, `False`, якщо це неможливо.

  Added in version 3.4.

socket.getpeername()

  Повертає віддалену адресу, до якої підключений сокет. Це корисно, наприклад, щоб дізнатися номер порту віддаленого сокета IPv4/v6. (Формат адреси, що повертається, залежить від родини адрес — див. вище.) У деяких системах ця функція не підтримується.

socket.getsockname()

  Повернути власну адресу сокета. Це корисно, наприклад, щоб дізнатися номер порту сокета IPv4/v6. (Формат адреси, що повертається, залежить від сімейства адрес — див. вище.)

socket.getsockopt(level, optname[, buflen])

  Return the value of the given socket option (see the Unix man page getsockopt(2)). The needed symbolic constants (SO_* etc.) are defined in this module. If buflen is absent, an integer option is assumed and its integer value is returned by the function. If buflen is present, it specifies the maximum length of the buffer used to receive the option in, and this buffer is returned as a bytes object. It is up to the caller to decode the contents of the buffer (see the optional built-in module `struct` for a way to decode C structures encoded as byte strings).

  Availability: not WASI.

socket.getblocking()

  Повертає `True`, якщо сокет знаходиться в режимі блокування, `False`, якщо він не блокується.

  This is equivalent to checking `socket.gettimeout() != 0`.

  Added in version 3.7.

socket.gettimeout()

  Повертає тайм-аут у секундах (float), пов’язаний з операціями сокета, або `None`, якщо тайм-аут не встановлено. Це відображає останній виклик `setblocking()` або `settimeout()`.

socket.ioctl(control, option)

  Метод `ioctl()` є обмеженим інтерфейсом системного інтерфейсу WSAIoctl. Будь ласка, зверніться до документації Win32 для отримання додаткової інформації.

  На інших платформах можна використовувати загальні функції `fcntl.fcntl()` і `fcntl.ioctl()`; вони приймають об’єкт сокета як свій перший аргумент.

  Наразі підтримуються лише такі керуючі коди: `SIO_RCVALL`, `SIO_KEEPALIVE_VALS` і `SIO_LOOPBACK_FAST_PATH`.

  Availability: Windows

  Змінено в версії 3.6: `SIO_LOOPBACK_FAST_PATH` було додано.

socket.listen([backlog])

  Увімкніть сервер для прийняття підключень. Якщо вказано backlog, воно має бути принаймні 0 (якщо менше, то встановлюється на 0); він визначає кількість неприйнятих підключень, які система дозволить перед тим, як відхилити нові підключення. Якщо не вказано, вибирається розумне значення за умовчанням.

  Availability: not WASI.

  Змінено в версії 3.5: Параметр backlog тепер необов’язковий.

socket.makefile(mode='r', buffering=None, *, encoding=None, errors=None, newline=None)

  Return a file object associated with the socket. The exact returned type depends on the arguments given to `makefile()`. These arguments are interpreted the same way as by the built-in `open()` function, except the only supported mode values are `'r'` (default), `'w'`, `'b'`, or a combination of those.

  Розетка повинна бути в режимі блокування; він може мати тайм-аут, але внутрішній буфер файлового об’єкта може опинитися в неузгодженому стані, якщо відбудеться тайм-аут.

  Закриття файлового об’єкта, який повертає `makefile()`, не закриє оригінальний сокет, якщо всі інші файлові об’єкти не закриті та `socket.close()` не викликано для об’єкта сокета.

  Примітка

  У Windows файлоподібний об’єкт, створений `makefile()`, не можна використовувати там, де очікується файловий об’єкт із дескриптором файлу, наприклад аргументи потоку `subprocess.Popen()`.

socket.recv(bufsize[, flags])

  Receive data from the socket. The return value is a bytes object representing the data received. The maximum amount of data to be received at once is specified by bufsize. A returned empty bytes object indicates that the client has disconnected. See the Unix manual page recv(2) for the meaning of the optional argument flags; it defaults to zero.

  Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток `InterruptedError` (перегляньте PEP 475 для обґрунтування).

socket.recvfrom(bufsize[, flags])

  Отримувати дані з розетки. Поверненим значенням є пара `(байти, адреса)`, де байт — об’єкт байтів, що представляє отримані дані, а адреса — адреса сокета, який надсилає дані. Перегляньте сторінку посібника Unix recv(2) для визначення значення необов’язкового аргументу flags; за замовчуванням він дорівнює нулю. (Формат адреси залежить від групи адрес — див. вище.)

  Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток `InterruptedError` (перегляньте PEP 475 для обґрунтування).

  Змінено в версії 3.7: Для багатоадресної адреси IPv6 перший елемент address більше не містить частини `%scope_id`. Щоб отримати повну адресу IPv6, використовуйте `getnameinfo()`.

socket.recvmsg(bufsize[, ancbufsize[, flags]])

  Отримувати звичайні дані (до bufsize байтів) і допоміжні дані з сокета. Аргумент ancbufsize встановлює розмір у байтах внутрішнього буфера, який використовується для отримання допоміжних даних; за замовчуванням він дорівнює 0, що означає, що допоміжні дані не будуть отримані. Відповідні розміри буферів для допоміжних даних можна обчислити за допомогою `CMSG_SPACE()` або `CMSG_LEN()`, а елементи, які не вміщаються в буфер, можуть бути скорочені або відкинуті. Аргумент flags за умовчанням дорівнює 0 і має те саме значення, що й для `recv()`.

  Повернене значення – це 4-кортеж: `(data, ancdata, msg_flags, address)`. Елемент data — це об’єкт `bytes`, що містить отримані непобічні дані. Елемент ancdata — це список із нуля або більше кортежів `(cmsg_level, cmsg_type, cmsg_data)`, що представляють отримані допоміжні дані (керуючі повідомлення): cmsg_level і cmsg_type — цілі числа, що визначають рівень протоколу та протокол- певного типу відповідно, і cmsg_data є об’єктом `bytes`, що містить пов’язані дані. Елемент msg_flags — це порозрядне АБО різних прапорів, що вказують на умови отриманого повідомлення; подробиці дивіться в системній документації. Якщо сокет-одержувач не підключений, адреса є адресою сокета-відправника, якщо він доступний; інакше його значення не вказано.

  On some systems, `sendmsg()` and `recvmsg()` can be used to pass file descriptors between processes over an `AF_UNIX` socket. When this facility is used (it is often restricted to `SOCK_STREAM` sockets), `recvmsg()` will return, in its ancillary data, items of the form `(socket.SOL_SOCKET, socket.SCM_RIGHTS, fds)`, where fds is a `bytes` object representing the new file descriptors as a binary array of the native C int type. If `recvmsg()` raises an exception after the system call returns, it will first attempt to close any file descriptors received via this mechanism.

  Деякі системи не вказують скорочену довжину елементів допоміжних даних, які були отримані лише частково. Якщо елемент виходить за кінець буфера, `recvmsg()` видає `RuntimeWarning` і повертає його частину, яка знаходиться всередині буфера, за умови, що вона не була скорочена до початку своїх пов’язаних даних.

  У системах, які підтримують механізм `SCM_RIGHTS`, наступна функція отримає до maxfds файлових дескрипторів, повертаючи дані повідомлення та список, що містить дескриптори (ігноруючи неочікувані умови, такі як отримання непов’язаних керуючих повідомлень). Дивіться також `sendmsg()`.

      import socket, array

      def recv_fds(sock, msglen, maxfds):
          fds = array.array("i")   # Array of ints
          msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
          for cmsg_level, cmsg_type, cmsg_data in ancdata:
              if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
                  # Append data, ignoring any truncated integers at the end.
                  fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
          return msg, list(fds)

  Availability: Unix.

  Most Unix platforms.

  Added in version 3.3.

  Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток `InterruptedError` (перегляньте PEP 475 для обґрунтування).

socket.recvmsg_into(buffers[, ancbufsize[, flags]])

  Отримувати звичайні дані та допоміжні дані з сокета, поводячись так, як це зробив би `recvmsg()`, але розкидати не допоміжні дані в ряд буферів замість повернення нового об’єкта bytes. Аргумент buffers має бути ітерованим об’єктами, які експортують записувані буфери (наприклад, об’єкти `bytearray`); вони будуть заповнені послідовними фрагментами непоміжних даних, доки вони не будуть записані або більше не залишиться буферів. Операційна система може встановити обмеження (`sysconf()` значення `SC_IOV_MAX`) на кількість буферів, які можна використовувати. Аргументи ancbufsize і flags мають те саме значення, що й для `recvmsg()`.

  Повернене значення — це 4-кортеж: `(nbytes, ancdata, msg_flags, address)`, де nbytes — загальна кількість байтів непоміжних даних, записаних у буфери, а ancdata, msg_flags і адреса такі самі, як і для `recvmsg()`.

  Приклад:

      >>> import socket
      >>> s1, s2 = socket.socketpair()
      >>> b1 = bytearray(b'----')
      >>> b2 = bytearray(b'0123456789')
      >>> b3 = bytearray(b'--------------')
      >>> s1.send(b'Mary had a little lamb')
      22
      >>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3])
      (22, [], 0, None)
      >>> [b1, b2, b3]
      [bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]

  Availability: Unix.

  Most Unix platforms.

  Added in version 3.3.

socket.recvfrom_into(buffer[, nbytes[, flags]])

  Отримувати дані з сокета, записуючи їх у буфер замість створення нового байтового рядка. Поверненим значенням є пара `(nbytes, address)`, де nbytes — це кількість отриманих байтів, а address — це адреса сокета, який надсилає дані. Перегляньте сторінку посібника Unix recv(2) для визначення значення необов’язкового аргументу flags; за замовчуванням він дорівнює нулю. (Формат адреси залежить від групи адрес — див. вище.)

socket.recv_into(buffer[, nbytes[, flags]])

  Отримайте до nbytes байт із сокета, зберігаючи дані в буфері, а не створюючи новий рядок байтів. Якщо nbytes не вказано (або 0), отримати до розміру, доступного в даному буфері. Повертає кількість отриманих байтів. Перегляньте сторінку посібника Unix recv(2) для визначення значення необов’язкового аргументу flags; за замовчуванням він дорівнює нулю.

socket.send(bytes[, flags])

  Надіслати дані в сокет. Розетка повинна бути підключена до віддаленої розетки. Необов’язковий аргумент flags має те саме значення, що й для `recv()` вище. Повертає кількість надісланих байтів. Додатки відповідають за перевірку того, що всі дані були надіслані; якщо було передано лише частину даних, програма повинна спробувати доставити решту даних. Для отримання додаткової інформації з цієї теми зверніться до HOWTO з програмування сокетів.

  Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток `InterruptedError` (перегляньте PEP 475 для обґрунтування).

socket.sendall(bytes[, flags])

  Надіслати дані в сокет. Розетка повинна бути підключена до віддаленої розетки. Необов’язковий аргумент flags має те саме значення, що й для `recv()` вище. На відміну від `send()`, цей метод продовжує надсилати дані з байтів, доки не буде надіслано всі дані або не станеться помилка. `None` повертається в разі успіху. У разі помилки виникає виняток, і немає способу визначити, скільки даних було успішно надіслано, якщо такі були.

  Змінено в версії 3.5: The socket timeout is no longer reset each time data is sent successfully. The socket timeout is now the maximum total duration to send all data.

  Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток `InterruptedError` (перегляньте PEP 475 для обґрунтування).

socket.sendto(bytes, address)
socket.sendto(bytes, flags, address)

  Надіслати дані в сокет. Сокет не слід підключати до віддаленого сокета, оскільки сокет призначення вказується адресою. Необов’язковий аргумент flags має те саме значення, що й для `recv()` вище. Повертає кількість надісланих байтів. (Формат адреси залежить від групи адрес — див. вище.)

  Викликає подію аудиту `socket.sendto` з аргументами `self`, `address`.

  Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток `InterruptedError` (перегляньте PEP 475 для обґрунтування).

socket.sendmsg(buffers[, ancdata[, flags[, address]]])

  Надсилайте звичайні та допоміжні дані в сокет, збираючи недопоміжні дані з ряду буферів і об’єднуючи їх в одне повідомлення. Аргумент buffers вказує на не допоміжні дані як ітерацію bytes-подібних об’єктів (наприклад, `bytes` об’єктів); операційна система може встановити обмеження (`sysconf()` значення `SC_IOV_MAX`) на кількість буферів, які можна використовувати. Аргумент ancdata визначає допоміжні дані (керуючі повідомлення) як ітерацію з нуля або більше кортежів `(cmsg_level, cmsg_type, cmsg_data)`, де cmsg_level і cmsg_type є цілими числами, що визначають рівень протоколу та протокол- певного типу відповідно, а cmsg_data — це байтиподібний об’єкт, що містить пов’язані дані. Зверніть увагу, що деякі системи (зокрема, системи без `CMSG_SPACE()`) можуть підтримувати надсилання лише одного керуючого повідомлення на виклик. Аргумент flags за умовчанням дорівнює 0 і має те саме значення, що й для `send()`. Якщо вказано address, а не `None`, це встановлює адресу призначення для повідомлення. Повернене значення — це кількість байтів надісланих непоміжних даних.

  Наступна функція надсилає список дескрипторів файлів fds через сокет `AF_UNIX` у системах, які підтримують механізм `SCM_RIGHTS`. Дивіться також `recvmsg()`.

      import socket, array

      def send_fds(sock, msg, fds):
          return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])

  Availability: Unix, not WASI.

  Most Unix platforms.

  Викликає подію аудиту `socket.sendmsg` з аргументами `self`, `address`.

  Added in version 3.3.

  Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток `InterruptedError` (перегляньте PEP 475 для обґрунтування).

socket.sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])

  Спеціалізована версія `sendmsg()` для `AF_ALG` сокета. Установіть довжину пов’язаних даних режиму, IV, AEAD і прапорці для сокета `AF_ALG`.

  Availability: Linux >= 2.6.38.

  Added in version 3.6.

socket.sendfile(file, offset=0, count=None)

  Надсилайте файл до досягнення EOF за допомогою високопродуктивного `os.sendfile` і повертайте загальну кількість надісланих байтів. file має бути звичайним файловим об’єктом, відкритим у двійковому режимі. Якщо `os.sendfile` недоступний (наприклад, Windows) або file не є звичайним файлом, замість нього буде використано `send()`. offset вказує, звідки почати читання файлу. Якщо вказано, count — це загальна кількість байтів для передачі, а не надсилання файлу до досягнення EOF. Позиція файлу оновлюється при поверненні або також у разі помилки, у цьому випадку `file.tell()` можна використовувати для визначення кількості надісланих байтів. Сокет має бути типу `SOCK_STREAM`. Неблокуючі сокети не підтримуються.

  Added in version 3.5.

socket.set_inheritable(inheritable)

  Установіть inheritable flag дескриптора файлу сокета або дескриптора сокета.

  Added in version 3.4.

socket.setblocking(flag)

  Встановіть блокуючий або неблокуючий режим сокета: якщо flag має значення false, сокет встановлено в неблокуючий режим, інакше в режим блокування.

  Цей метод є скороченням певних викликів `settimeout()`:

  - `sock.setblocking(True)` еквівалентно `sock.settimeout(None)`

  - `sock.setblocking(False)` еквівалентний `sock.settimeout(0.0)`

  Змінено в версії 3.7: Метод більше не застосовує прапор `SOCK_NONBLOCK` до `socket.type`.

socket.settimeout(value)

  Set a timeout on blocking socket operations. The value argument can be a nonnegative real number expressing seconds, or `None`. If a non-zero value is given, subsequent socket operations will raise a `timeout` exception if the timeout period value has elapsed before the operation has completed. If zero is given, the socket is put in non-blocking mode. If `None` is given, the socket is put in blocking mode.

  Щоб отримати додаткову інформацію, зверніться до приміток щодо тайм-аутів сокетів.

  Змінено в версії 3.7: Метод більше не вмикає прапор `SOCK_NONBLOCK` на `socket.type`.

  Змінено в версії 3.15: Accepts any real number, not only integer or float.

socket.setsockopt(level, optname, value: int | Buffer)
socket.setsockopt(level, optname, None, optlen: int)

  Set the value of the given socket option (see the Unix manual page setsockopt(2)). The needed symbolic constants are defined in this module (SO_* etc. <socket-unix-constants>). The value can be an integer, `None` or a bytes-like object representing a buffer. In the later case it is up to the caller to ensure that the bytestring contains the proper bits (see the optional built-in module `struct` for a way to encode C structures as bytestrings). When value is set to `None`, optlen argument is required. It’s equivalent to call `setsockopt()` C function with `optval=NULL` and `optlen=optlen`.

  Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

  Змінено в версії 3.6: Додано форму setsockopt(level, optname, None, optlen: int).

  Availability: not WASI.

socket.shutdown(how)

  Вимкніть одну або обидві половини з’єднання. Якщо how `SHUT_RD`, подальші прийоми заборонені. Якщо how `SHUT_WR`, подальші надсилання заборонені. Якщо how `SHUT_RDWR`, подальше надсилання та отримання заборонено.

  Availability: not WASI.

socket.share(process_id)

  Скопіюйте сокет і підготуйте його для спільного використання з цільовим процесом. Цільовому процесу має бути надано process_id. Отриманий об’єкт bytes потім можна передати цільовому процесу за допомогою певної форми міжпроцесного зв’язку, а сокет можна відтворити там за допомогою `fromshare()`. Після виклику цього методу можна безпечно закрити сокет, оскільки операційна система вже скопіювала його для цільового процесу.

  Availability: Windows.

  Added in version 3.3.

Зверніть увагу, що немає методів `read()` або `write()`; замість цього використовуйте `recv()` і `send()` без аргументу flags.

Об’єкти Socket також мають ці атрибути (лише для читання), які відповідають значенням, наданим конструктору `socket`.

socket.family

  Сімейство розеток.

socket.type

  Тип розетки.

socket.proto

  Протокол сокета.

## Примітки щодо тайм-аутів сокетів

Об’єкт сокета може бути в одному з трьох режимів: блокування, неблокування або час очікування. За умовчанням сокети завжди створюються в режимі блокування, але це можна змінити, викликавши `setdefaulttimeout()`.

- У режимі блокування операції блокуються до завершення або доки система не поверне повідомлення про помилку (наприклад, час очікування підключення закінчився).

- In non-blocking mode, operations fail (with an error that is unfortunately system-dependent) if they cannot be completed immediately: functions from the `select` module can be used to know when and whether a socket is available for reading or writing.

- У режимі тайм-ауту операції завершуються невдало, якщо їх не можна завершити протягом тайм-ауту, указаного для сокета (вони викликають виняток `timeout`) або якщо система повертає помилку.

Примітка

At the operating system level, sockets in timeout mode are internally set in non-blocking mode. Also, the blocking and timeout modes are shared between file descriptors and socket objects that refer to the same network endpoint. This implementation detail can have visible consequences if e.g. you decide to use the `fileno()` of a socket.

### Час очікування та метод `connect`

Операція `connect()` також залежить від параметра тайм-ауту, і загалом рекомендується викликати `settimeout()` перед викликом `connect()` або передати параметр часу очікування для `create_connection()`. Однак системний мережевий стек також може повертати власну помилку очікування підключення незалежно від будь-якого параметра часу очікування сокета Python.

### Час очікування та метод `accept`

Якщо `getdefaulttimeout()` не `None`, сокети, повернуті методом `accept()`, успадковують цей час очікування. В іншому випадку поведінка залежить від налаштувань прослуховувального сокета:

- якщо прослуховувальний сокет знаходиться в режимі блокування або в режимі очікування, сокет, який повертає `accept()`, знаходиться в режимі блокування;

- якщо сокет, що прослуховує, знаходиться в неблокуючому режимі, чи є сокет, повернутий `accept()` у блокуючому чи неблокуючому режимі, залежить від операційної системи. Якщо ви хочете забезпечити кросплатформну поведінку, радимо вручну змінити це налаштування.

## приклад

Here are four minimal example programs using the TCP/IP protocol: a server that echoes all data that it receives back (servicing only one client), and a client using it. Note that a server must perform the sequence `socket()`, `bind()`, `listen()`, `accept()` (possibly repeating the `accept()` to service more than one client), while a client only needs the sequence `socket()`, `connect()`. Also note that the server does not `sendall()`/`recv()` on the socket it is listening on but on the new socket returned by `accept()`.

Перші два приклади підтримують лише IPv4.

    # Echo server program
    import socket

    HOST = ''                 # Symbolic name meaning all available interfaces
    PORT = 50007              # Arbitrary non-privileged port
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        s.bind((HOST, PORT))
        s.listen(1)
        conn, addr = s.accept()
        with conn:
            print('Connected by', addr)
            while True:
                data = conn.recv(1024)
                if not data: break
                conn.sendall(data)

    # Echo client program
    import socket

    HOST = 'daring.cwi.nl'    # The remote host
    PORT = 50007              # The same port as used by the server
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        s.connect((HOST, PORT))
        s.sendall(b'Hello, world')
        data = s.recv(1024)
    print('Received', repr(data))

The next two examples are identical to the above two, but support both IPv4 and IPv6. The server side will listen to the first address family available (it should listen to both instead). On most of IPv6-ready systems, IPv6 will take precedence and the server may not accept IPv4 traffic. The client side will try to connect to all the addresses returned as a result of the name resolution, and sends traffic to the first one connected successfully.

    # Echo server program
    import socket
    import sys

    HOST = None               # Symbolic name meaning all available interfaces
    PORT = 50007              # Arbitrary non-privileged port
    s = None
    for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                                  socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
        af, socktype, proto, canonname, sa = res
        try:
            s = socket.socket(af, socktype, proto)
        except OSError as msg:
            s = None
            continue
        try:
            s.bind(sa)
            s.listen(1)
        except OSError as msg:
            s.close()
            s = None
            continue
        break
    if s is None:
        print('could not open socket')
        sys.exit(1)
    conn, addr = s.accept()
    with conn:
        print('Connected by', addr)
        while True:
            data = conn.recv(1024)
            if not data: break
            conn.send(data)

    # Echo client program
    import socket
    import sys

    HOST = 'daring.cwi.nl'    # The remote host
    PORT = 50007              # The same port as used by the server
    s = None
    for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
        af, socktype, proto, canonname, sa = res
        try:
            s = socket.socket(af, socktype, proto)
        except OSError as msg:
            s = None
            continue
        try:
            s.connect(sa)
        except OSError as msg:
            s.close()
            s = None
            continue
        break
    if s is None:
        print('could not open socket')
        sys.exit(1)
    with s:
        s.sendall(b'Hello, world')
        data = s.recv(1024)
    print('Received', repr(data))

У наступному прикладі показано, як написати дуже простий мережевий сніфер із необробленими сокетами у Windows. У прикладі потрібні права адміністратора, щоб змінити інтерфейс:

    import socket

    # the public network interface
    HOST = socket.gethostbyname(socket.gethostname())

    # create a raw socket and bind it to the public interface
    s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
    s.bind((HOST, 0))

    # Include IP headers
    s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

    # receive all packets
    s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

    # receive a packet
    print(s.recvfrom(65565))

    # disabled promiscuous mode
    s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

У наступному прикладі показано, як використовувати інтерфейс сокета для зв’язку з мережею CAN за допомогою необробленого протоколу сокета. Щоб замість цього використовувати CAN із протоколом диспетчера трансляції, відкрийте сокет за допомогою:

    socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)

After binding (`CAN_RAW`) or connecting (`CAN_BCM`) the socket, you can use the `socket.send()` and `socket.recv()` operations (and their counterparts) on the socket object as usual.

Цей останній приклад може вимагати спеціальних привілеїв:

    import socket
    import struct

    # CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)

    can_frame_fmt = "=IB3x8s"
    can_frame_size = struct.calcsize(can_frame_fmt)

    def build_can_frame(can_id, data):
        can_dlc = len(data)
        data = data.ljust(8, b'\x00')
        return struct.pack(can_frame_fmt, can_id, can_dlc, data)

    def dissect_can_frame(frame):
        can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame)
        return (can_id, can_dlc, data[:can_dlc])

    # create a raw socket and bind it to the 'vcan0' interface
    s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
    s.bind(('vcan0',))

    while True:
        cf, addr = s.recvfrom(can_frame_size)

        print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf))

        try:
            s.send(cf)
        except OSError:
            print('Error sending CAN frame')

        try:
            s.send(build_can_frame(0x01, b'\x01\x02\x03'))
        except OSError:
            print('Error sending CAN frame')

Запуск прикладу кілька разів із занадто малою затримкою між виконаннями може призвести до цієї помилки:

    OSError: [Errno 98] Address already in use

Це пов’язано з тим, що попереднє виконання залишило сокет у стані `TIME_WAIT` і не може бути негайно повторно використано.

There is a `socket` flag to set, in order to prevent this, `socket.SO_REUSEADDR`:

    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    s.bind((HOST, PORT))

прапорець `SO_REUSEADDR` повідомляє ядру повторно використовувати локальний сокет у стані `TIME_WAIT`, не чекаючи закінчення його природного часу очікування.

Дивись також

Для ознайомлення з програмуванням сокетів (на C) перегляньте такі документи:

- Вступний навчальний посібник із взаємодії між процесами 4.3BSD, Стюарт Сехрест

- Навчальний посібник із розширеного міжпроцесного зв’язку 4.3BSD, Семюел Дж. Леффлер та інші,

обидва в Посібнику програміста UNIX, Додаткові документи 1 (розділи PS1:7 та PS1:8). Довідковий матеріал для певної платформи для різноманітних системних викликів, пов’язаних із сокетами, також є цінним джерелом інформації про деталі семантики сокетів. Для Unix зверніться до сторінок посібника; для Windows дивіться специфікацію WinSock (або Winsock 2). Щодо API, готових до IPv6, читачі можуть звернутися до RFC 3493 під назвою Basic Socket Interface Extensions for IPv6.