socket --- 底层网络接口¶

套接字协议族¶

根据系统以及构建选项，此模块提供了各种套接字协议簇。

特定的套接字对象需要的地址格式将根据此套接字对象被创建时指定的地址族被自动选择。套接字地址表示如下：

• 一个绑定在文件系统节点上的 AF_UNIX 套接字的地址表示为一个字符串，使用文件系统字符编码和 'surrogateescape' 错误回调方法（see PEP 383）。一个地址在 Linux 的抽象命名空间被返回为带有初始的 null 字节的 字节类对象 ；注意在这个命名空间种的套接字可能与普通文件系统套接字通信，所以打算运行在 Linux 上的程序可能需要解决两种地址类型。当传递为参数时，一个字符串或字节类对象可以用于任一类型的地址。

  在 3.3 版更改: 之前，AF_UNIX 套接字路径被假设使用 UTF-8 编码。

  在 3.5 版更改: 现在接受可写的 字节类对象。

• 一对 (host, port) 被用作 AF_INET 地址族，其中 host 是一个表示互联网域名标记形式的主机名例如 'daring.cwi.nl' 或者 IPv4 地址例如 '100.50.200.5' 的字符串，而 port 是一个整数值。

  • 对于 IPv4 地址，有两种可接受的特殊形式被用来代替一个主机地址： '' 代表 INADDR_ANY，用来绑定到所有接口；字符串 '<broadcast>' 代表 INADDR_BROADCAST。此行为不兼容 IPv6，因此，如果你的 Python 程序打算支持 IPv6，则可能需要避开这些。

• 对于 AF_INET6 地址族，使用一个四元组 (host, port, flowinfo, scope_id)，其中 flowinfo 和 scope_id 代表了 C 库 struct sockaddr_in6 中的 sin6_flowinfo 和 sin6_scope_id 成员。对于 socket 模块中的方法， flowinfo 和 scope_id 可以被省略，只为了向后兼容。注意，省略 scope_id 可能会导致操作带有领域 (Scope) 的 IPv6 地址时出错。

  在 3.7 版更改: 对于多播地址（其 scope_id 起作用），地址 中可以不包含 %scope_id （或 zone id ）部分，这部分是多余的，可以放心省略（推荐）。

• AF_NETLINK 套接字由一对 (pid, groups) 表示。

• 指定 AF_TIPC 地址族可以使用仅 Linux 支持的 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 是节点 (node)，v2 是 ref，v3 应为 0。

• AF_CAN 地址族使用元组 (interface, )，其中 interface 是表示网络接口名称的字符串，如 'can0'。网络接口名 '' 可以用于接收本族所有网络接口的数据包。

  • CAN_ISOTP 协议接受一个元组 (interface, rx_addr, tx_addr)，其中两个额外参数都是无符号长整数，都表示 CAN 标识符（标准或扩展标识符）。

  • CAN_J1939 协议接受一个元组 (interface, name, pgn, addr)，其中额外参数有：表示 ECU 名称的 64 位无符号整数，表示参数组号 (Parameter Group Number, PGN) 的 32 位无符号整数，以及表示地址的 8 位整数。

• PF_SYSTEM 协议簇的 SYSPROTO_CONTROL 协议接受一个字符串或元组 (id, unit)。其中字符串是内核控件的名称，该控件使用动态分配的 ID。而如果 ID 和内核控件的单元 (unit) 编号都已知，或使用了已注册的 ID，可以采用元组。

  3.3 新版功能.

• AF_BLUETOOTH 支持以下协议和地址格式：

  • BTPROTO_L2CAP 接受 (bdaddr, psm)，其中 bdaddr 为字符串格式的蓝牙地址，psm 是一个整数。

  • BTPROTO_RFCOMM 接受 (bdaddr, channel)，其中 bdaddr 为字符串格式的蓝牙地址，channel 是一个整数。

  • BTPROTO_HCI 接受 (device_id,)，其中 device_id 为整数或字符串，它表示接口对应的蓝牙地址（具体取决于你的系统，NetBSD 和 DragonFlyBSD 需要蓝牙地址字符串，其他系统需要整数）。

    在 3.2 版更改: 添加了对 NetBSD 和 DragonFlyBSD 的支持。

  • BTPROTO_SCO 接受 bdaddr，其中 bdaddr 是 bytes 对象，其中含有字符串格式的蓝牙地址（如 b'12:23:34:45:56:67' ），FreeBSD 不支持此协议。

• AF_ALG 是一个仅 Linux 可用的、基于套接字的接口，用于连接内核加密算法。算法套接字可用包括 2 至 4 个元素的元组来配置 (type, name [, feat [, mask]])，其中：

  • type 是表示算法类型的字符串，如 aead、hash、skcipher 或 rng。

  • name 是表示算法类型和操作模式的字符串，如 sha256、hmac(sha256)、cbc(aes) 或 drbg_nopr_ctr_aes256。

  • feat 和 mask 是无符号 32 位整数。

  Availability: Linux 2.6.38, some algorithm types require more recent Kernels.

  3.6 新版功能.

• AF_VSOCK 用于支持虚拟机与宿主机之间的通讯。该套接字用 (CID, port) 元组表示，其中 Context ID (CID) 和 port 都是整数。

  Availability: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5.

  3.7 新版功能.

• AF_PACKET 是一个底层接口，直接连接至网卡。数据包使用元组 (ifname, proto[, pkttype[, hatype[, addr]]]) 表示，其中：

  • ifname - 指定设备名称的字符串。

  • proto - 一个用网络字节序表示的整数，指定以太网协议版本号。

  • 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 可用的、基于套接字的接口，用于与高通平台中协处理器上运行的服务进行通信。该地址簇用一个 (node, port) 元组表示，其中 node 和 port 为非负整数。

  Availability: Linux >= 4.7.

  3.8 新版功能.

• IPPROTO_UDPLITE 是一种 UDP 的变体，允许指定数据包的哪一部分计算入校验码内。它添加了两个可以修改的套接字选项。self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) 修改传出数据包的哪一部分计算入校验码内，而 self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) 将过滤掉计算入校验码的数据太少的数据包。在这两种情况下，length 都应在 range(8, 2**16, 8) 范围内。

  对于 IPv4，应使用 socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) 来构造这样的套接字；对于 IPv6，应使用 socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) 来构造这样的套接字。

  Availability: Linux >= 2.6.20, FreeBSD >= 10.1-RELEASE

  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 parition.

  The service_id is the service identifier of the registered service.

  3.12 新版功能.

如果你在 IPv4/v6 套接字地址的 host 部分中使用了一个主机名，此程序可能会表现不确定行为，因为 Python 使用 DNS 解析返回的第一个地址。套接字地址在实际的 IPv4/v6 中以不同方式解析，根据 DNS 解析和/或 host 配置。为了确定行为，在 host 部分中使用数字的地址。

All errors raise exceptions. The normal exceptions for invalid argument types and out-of-memory conditions can be raised. Errors related to socket or address semantics raise OSError or one of its subclasses.

可以用 setblocking() 设置非阻塞模式。一个基于超时的 generalization 通过 settimeout() 支持。

模块内容¶

socket 模块包含下列元素。

套接字对象¶

套接字对象具有以下方法。除了 makefile()，其他都与套接字专用的 Unix 系统调用相对应。

socket.accept()¶

接受一个连接。此 socket 必须绑定到一个地址上并且监听连接。返回值是一个 (conn, address) 对，其中 conn 是一个 新 的套接字对象，用于在此连接上收发数据，address 是连接另一端的套接字所绑定的地址。

新创建的套接字是 不可继承的。

在 3.4 版更改: 该套接字现在是不可继承的。

在 3.5 版更改: 如果系统调用被中断，但信号处理程序没有触发异常，此方法现在会重试系统调用，而不是触发 InterruptedError 异常 (原因详见 PEP 475)。

socket.bind(address)¶

将套接字绑定到 address。套接字必须尚未绑定。（ address 的格式取决于地址簇 —— 参见上文）

引发一个 审计事件 socket.bind，附带参数 self、address。

socket.close()¶

将套接字标记为关闭。当 makefile() 创建的所有文件对象都关闭时，底层系统资源（如文件描述符）也将关闭。一旦上述情况发生，将来对套接字对象的所有操作都会失败。对端将接收不到任何数据（清空队列数据后）。

垃圾回收时，套接字会自动关闭，但建议显式 close() 它们，或在它们周围使用 with 语句。

在 3.6 版更改: 现在，如果底层的 close() 调用出错，会抛出 OSError。

备注

close() 释放与连接相关联的资源，但不一定立即关闭连接。如果需要及时关闭连接，请在调用 close() 之前调用 shutdown()。

socket.connect(address)¶

连接到 address 处的远程套接字。（ address 的格式取决于地址簇 —— 参见上文）

如果连接被信号中断，则本方法将等待直至连接完成，或者如果信号处理句柄未引发异常并且套接字被阻塞或已超时则会在超时后引发 TimeoutError。 对于非阻塞型套接字，如果连接被信号中断则本方法将引发 InterruptedError 异常（或信号处理句柄所引发的异常）。

引发一个 审计事件 socket.connect，附带参数 self、address。

在 3.5 版更改: 本方法现在将等待，直到连接完成，而不是在以下情况抛出 InterruptedError 异常。该情况为，连接被信号中断，信号处理程序未抛出异常，且套接字阻塞中或已超时（具体解释请参阅 PEP 475 ）。

socket.connect_ex(address)¶

类似于 connect(address)，但是对于 C 级别的 connect() 调用返回的错误，本函数将返回错误指示器，而不是抛出异常（对于其他问题，如“找不到主机”，仍然可以抛出异常）。如果操作成功，则错误指示器为 0，否则为 errno 变量的值。这对支持如异步连接很有用。

引发一个 审计事件 socket.connect，附带参数 self、address。

socket.detach()¶

将套接字对象置于关闭状态，而底层的文件描述符实际并不关闭。返回该文件描述符，使其可以重新用于其他目的。

3.2 新版功能.

socket.dup()¶

创建套接字的副本。

新创建的套接字是 不可继承的。

在 3.4 版更改: 该套接字现在是不可继承的。

socket.fileno()¶

返回套接字的文件描述符（一个小整数），失败返回 -1。配合 select.select() 使用很有用。

在 Windows 下，此方法返回的小整数在允许使用文件描述符的地方无法使用（如 os.fdopen() ）。Unix 无此限制。

socket.get_inheritable()¶

获取套接字文件描述符或套接字句柄的 可继承标志 ：如果子进程可以继承套接字则为 True，否则为 False。

3.4 新版功能.

socket.getpeername()¶

返回套接字连接到的远程地址。举例而言，这可以用于查找远程 IPv4/v6 套接字的端口号。（返回的地址格式取决于地址簇 —— 参见上文。）部分系统不支持此函数。

socket.getsockname()¶

返回套接字本身的地址。举例而言，这可以用于查找 IPv4/v6 套接字的端口号。（返回的地址格式取决于地址簇 —— 参见上文。）

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

返回指定套接字选项的值（参阅 Unix 手册页 getsockopt(2) ）。所需的符号常量（ SO_* 等）已定义在本模块中。如果未指定 buflen，则认为该选项值为整数，由本函数返回该整数值。如果指定 buflen，则它定义了用于存放选项值的缓冲区的最大长度，且该缓冲区将作为字节对象返回。对缓冲区的解码工作由调用者自行完成（针对编码为字节串的 C 结构，其解码方法请参阅可选的内置模块 struct ）。

socket.getblocking()¶

如果套接字处于阻塞模式，返回 True，非阻塞模式返回 False。

这相当于检测 socket.gettimeout() == 0。

3.7 新版功能.

socket.gettimeout()¶

返回套接字操作相关的超时秒数（浮点数），未设置超时则返回 None。它反映最后一次调用 setblocking() 或 settimeout() 后的设置。

socket.ioctl(control, option)¶

平台

Windows

ioctl() 方法是 WSAIoctl 系统接口的有限接口。请参考 Win32 文档 以获取更多信息。

在其他平台上，可以使用通用的 fcntl.fcntl() 和 fcntl.ioctl() 函数，它们接受套接字对象作为第一个参数。

当前仅支持以下控制码： SIO_RCVALL、SIO_KEEPALIVE_VALS 和 SIO_LOOPBACK_FAST_PATH。

在 3.6 版更改: 添加了 SIO_LOOPBACK_FAST_PATH。

socket.listen([backlog])¶

启动一个服务器用于接受连接。如果指定 backlog，则它最低为 0（小于 0 会被置为 0），它指定系统允许暂未 accept 的连接数，超过后将拒绝新连接。未指定则自动设为合理的默认值。

在 3.5 版更改: backlog 参数现在是可选的。

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

返回与套接字关联的 文件对象。返回的对象的具体类型取决于 makefile() 的参数。这些参数的解释方式与内置的 open() 函数相同，其中 mode 的值仅支持 'r' （默认），'w' 和 'b'。

套接字必须处于阻塞模式，它可以有超时，但是如果发生超时，文件对象的内部缓冲区可能会以不一致的状态结尾。

关闭 makefile() 返回的文件对象不会关闭原始套接字，除非所有其他文件对象都已关闭且在套接字对象上调用了 socket.close()。

备注

在 Windows 上，由 makefile() 创建的文件类对象无法作为带文件描述符的文件对象使用，如无法作为 subprocess.Popen() 的流参数。

socket.recv(bufsize[, flags])¶

从套接字接收数据。返回值是一个字节对象，表示接收到的数据。bufsize 指定一次接收的最大数据量。可选参数 flags 的含义请参阅 Unix 手册页 recv(2)，它默认为零。

备注

为了最佳匹配硬件和网络的实际情况，bufsize 的值应为 2 的相对较小的幂，如 4096。

在 3.5 版更改: 如果系统调用被中断，但信号处理程序没有触发异常，此方法现在会重试系统调用，而不是触发 InterruptedError 异常 (原因详见 PEP 475)。

socket.recvfrom(bufsize[, flags])¶

从套接字接收数据。返回值是一对 (bytes, address)，其中 bytes 是字节对象，表示接收到的数据，address 是发送端套接字的地址。可选参数 flags 的含义请参阅 Unix 手册页 recv(2)，它默认为零。（ address 的格式取决于地址簇 —— 参见上文）

在 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() 中的相同。

返回值是一个四元组： (data, ancdata, msg_flags, address)。data 项是一个 bytes 对象，用于保存接收到的非辅助数据。ancdata 项是零个或多个元组 (cmsg_level, cmsg_type, cmsg_data) 组成的列表，表示接收到的辅助数据（控制消息）：cmsg_level 和 cmsg_type 是分别表示协议级别和协议类型的整数，而 cmsg_data 是保存相关数据的 bytes 对象。msg_flags 项由各种标志按位或组成，表示接收消息的情况，详细信息请参阅系统文档。如果接收端套接字断开连接，则 address 是发送端套接字的地址（如果有），否则该值无指定。

某些系统上可以利用 AF_UNIX 套接字通过 sendmsg() 和 recvmsg() 在进程之间传递文件描述符。使用此功能时（通常仅限于 SOCK_STREAM 套接字），recvmsg() 将在其辅助数据中返回以下格式的项 (socket.SOL_SOCKET, socket.SCM_RIGHTS, fds)，其中 fds 是一个 bytes 对象，是新文件描述符表示为原生 C int 类型的二进制数组。如果 recvmsg() 在系统调用返回后抛出异常，它将首先关闭此机制接收到的所有文件描述符。

对于仅接收到一部分的辅助数据项，一些系统没有指示其截断长度。如果某个项目可能超出了缓冲区的末尾，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)

可用性： 大多数 Unix 平台，其他平台也可能可用。

3.3 新版功能.

在 3.5 版更改: 如果系统调用被中断，但信号处理程序没有触发异常，此方法现在会重试系统调用，而不是触发 InterruptedError 异常 (原因详见 PEP 475)。

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

从套接字接收普通数据和辅助数据，其行为与 recvmsg() 相同，但将非辅助数据分散到一系列缓冲区中，而不是返回新的字节对象。buffers 参数必须是可迭代对象，它迭代出可供写入的缓冲区（如 bytearray 对象），这些缓冲区将被连续的非辅助数据块填充，直到数据全部写完或缓冲区用完为止。在允许使用的缓冲区数量上，操作系统可能会有限制（ sysconf() 的 SC_IOV_MAX 值）。ancbufsize 和 flags 参数的含义与 recvmsg() 中的相同。

返回值为四元组： (nbytes, ancdata, msg_flags, address)，其中 nbytes 是写入缓冲区的非辅助数据的字节总数，而 ancdata、msg_flags 和 address 与 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---')]

可用性： 大多数 Unix 平台，其他平台也可能可用。

3.3 新版功能.

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

从套接字接收数据，将其写入 buffer 而不是创建新的字节串。返回值是一对 (nbytes, address)，其中 nbytes 是收到的字节数，address 是发送端套接字的地址。可选参数 flags 的含义请参阅 Unix 手册页 recv(2)，它默认为零。（ address 的格式取决于地址簇 —— 参见上文）

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

从套接字接收至多 nbytes 个字节，将其写入缓冲区而不是创建新的字节串。如果 nbytes 未指定（或指定为 0），则接收至所给缓冲区的最大可用大小。返回接收到的字节数。可选参数 flags 的含义请参阅 Unix 手册页 recv(2)，它默认为零。

socket.send(bytes[, flags])¶

发送数据给套接字。本套接字必须已连接到远程套接字。可选参数 flags 的含义与上述 recv() 中的相同。本方法返回已发送的字节数。应用程序要负责检查所有数据是否已发送，如果仅传输了部分数据，程序需要自行尝试传输其余数据。有关该主题的更多信息，请参考 套接字编程指南。

在 3.5 版更改: 如果系统调用被中断，但信号处理程序没有触发异常，此方法现在会重试系统调用，而不是触发 InterruptedError 异常 (原因详见 PEP 475)。

socket.sendall(bytes[, flags])¶

发送数据给套接字。本套接字必须已连接到远程套接字。可选参数 flags 的含义与上述 recv() 中的相同。与 send() 不同，本方法持续从 bytes 发送数据，直到所有数据都已发送或发生错误为止。成功后会返回 None。出错后会抛出一个异常，此时并没有办法确定成功发送了多少数据。

在 3.5 版更改: 每次成功发送数据后，套接字超时不再重置。现在，套接字超时是发送所有数据的最大总持续时间。

在 3.5 版更改: 如果系统调用被中断，但信号处理程序没有触发异常，此方法现在会重试系统调用，而不是触发 InterruptedError 异常 (原因详见 PEP 475)。

socket.sendto(bytes, address)¶

socket.sendto(bytes, flags, address)

发送数据给套接字。本套接字不应连接到远程套接字，而应由 address 指定目标套接字。可选参数 flags 的含义与上述 recv() 中的相同。本方法返回已发送的字节数。（ address 的格式取决于地址簇 —— 参见上文。）

引发一个 审计事件 socket.sendto，附带参数 self、address。

在 3.5 版更改: 如果系统调用被中断，但信号处理程序没有触发异常，此方法现在会重试系统调用，而不是触发 InterruptedError 异常 (原因详见 PEP 475)。

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

将普通数据和辅助数据发送给套接字，将从一系列缓冲区中收集非辅助数据，并将其拼接为一条消息。buffers 参数指定的非辅助数据应为可迭代的 字节类对象 （如 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 以外的值，它将作为消息的目标地址。返回值是已发送的非辅助数据的字节数。

在支持 SCM_RIGHTS 机制的系统上，下方的函数通过一个 AF_UNIX 套接字来发送文件描述符列表 fds。另请参阅 recvmsg()。

import socket, array

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

可用性： 大多数 Unix 平台，其他平台也可能可用。

引发一个 审计事件 socket.sendmsg，附带参数 self、address。

3.3 新版功能.

在 3.5 版更改: 如果系统调用被中断，但信号处理程序没有触发异常，此方法现在会重试系统调用，而不是触发 InterruptedError 异常 (原因详见 PEP 475)。

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

为 AF_ALG 套接字定制的 sendmsg() 版本。可为 AF_ALG 套接字设置模式、IV、AEAD 关联数据的长度和标志位。

可用性： Linux >= 2.6.38。

3.6 新版功能.

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

使用高性能的 os.sendfile 发送文件，直到达到文件的 EOF 为止，返回已发送的字节总数。file 必须是一个以二进制模式打开的常规文件对象。如果 os.sendfile 不可用（如 Windows）或 file 不是常规文件，将使用 send() 代替。offset 指示从哪里开始读取文件。如果指定了 count，它确定了要发送的字节总数，而不会持续发送直到达到文件的 EOF。返回时或发生错误时，文件位置将更新，在这种情况下，file.tell() 可用于确定已发送的字节数。套接字必须为 SOCK_STREAM 类型。不支持非阻塞的套接字。

3.5 新版功能.

socket.set_inheritable(inheritable)¶

设置套接字文件描述符或套接字句柄的 可继承标志。

3.4 新版功能.

socket.setblocking(flag)¶

设置套接字为阻塞或非阻塞模式：如果 flag 为 false，则将套接字设置为非阻塞，否则设置为阻塞。

本方法是某些 settimeout() 调用的简写：

• sock.setblocking(True) 相当于 sock.settimeout(None)

• sock.setblocking(False) 相当于 sock.settimeout(0.0)

在 3.7 版更改: 本方法不再对 socket.type 属性设置 SOCK_NONBLOCK 标志。

socket.settimeout(value)¶

为阻塞套接字的操作设置超时。value 参数可以是非负浮点数，表示秒，也可以是 None。如果赋为一个非零值，那么如果在操作完成前超过了超时时间 value，后续的套接字操作将抛出 timeout 异常。如果赋为 0，则套接字将处于非阻塞模式。如果指定为 None，则套接字将处于阻塞模式。

更多信息请查阅 关于套接字超时的说明。

在 3.7 版更改: 本方法不再修改 socket.type 属性的 SOCK_NONBLOCK 标志。

socket.setsockopt(level, optname, value: int)¶

socket.setsockopt(level, optname, value: buffer)

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

设置给定套接字选项的值（参阅 Unix 手册页 setsockopt(2) ）。所需的符号常量（ SO_* 等）已定义在本 socket 模块中。该值可以是整数、None 或表示缓冲区的 字节类对象。在后一种情况下，由调用者确保字节串中包含正确的数据位（关于将 C 结构体编码为字节串的方法，请参阅可选的内置模块 struct ）。当 value 设置为 None 时，必须设置 optlen 参数。这相当于调用 setsockopt() C 函数时使用了 optval=NULL 和 optlen=optlen 参数。

在 3.5 版更改: 现在接受可写的 字节类对象。

在 3.6 版更改: 添加了 setsockopt(level, optname, None, optlen: int) 调用形式。

socket.shutdown(how)¶

关闭一半或全部的连接。如果 how 为 SHUT_RD，则后续不再允许接收。如果 how 为 SHUT_WR，则后续不再允许发送。如果 how 为 SHUT_RDWR，则后续的发送和接收都不允许。

socket.share(process_id)¶

复制套接字，并准备将其与目标进程共享。目标进程必须以 process_id 形式提供。然后可以利用某种形式的进程间通信，将返回的字节对象传递给目标进程，还可以使用 fromshare() 在新进程中重新创建套接字。一旦本方法调用完毕，就可以安全地将套接字关闭，因为操作系统已经为目标进程复制了该套接字。

可用性: Windows。

3.3 新版功能.

注意此处没有 read() 或 write() 方法，请使用不带 flags 参数的 recv() 和 send() 来替代。

套接字对象还具有以下（只读）属性，这些属性与传入 socket 构造函数的值相对应。

socket.family¶

套接字的协议簇。

socket.type¶

套接字的类型。

socket.proto¶

套接字的协议。

关于套接字超时的说明¶

一个套接字对象可以处于以下三种模式之一：阻塞、非阻塞或超时。套接字默认以阻塞模式创建，但是可以调用 setdefaulttimeout() 来更改。

• 在 blocking mode （阻塞模式）中，操作将阻塞，直到操作完成或系统返回错误（如连接超时）。

• 在 non-blocking mode （非阻塞模式）中，如果操作无法立即完成，则操作将失败（不幸的是，不同系统返回的错误不同）：位于 select 中的函数可用于了解套接字何时以及是否可以读取或写入。

• 在 timeout mode （超时模式）下，如果无法在指定的超时内完成操作（抛出 timeout 异常），或如果系统返回错误，则操作将失败。

示例¶

以下是 4 个使用 TCP/IP 协议的最小示例程序：一台服务器，它将收到的所有数据原样返回（仅服务于一个客户端），还有一个使用该服务器的客户端。注意，服务器必须按序执行 socket(), bind(), listen(), accept() （可能需要重复执行 accept() 以服务多个客户端），而客户端仅需要按序执行 socket(), connect()。还须注意，服务器不在侦听套接字上发送 sendall()/recv()，而是在 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))

下两个例子与上两个很像，但是同时支持 IPv4 和 IPv6。 服务端将监听第一个可用的地址族（它本应同时监听两个）。 在大多数支持 IPv6 的系统上，IPv6 将有优先权并且服务端可能不会接受 IPv4 流量。 客户端将尝试连接到作为名称解析结果被返回的所有地址，并将流量发送给连接成功的第一个地址。

# 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 packages
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

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

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

下面的例子演示了如何使用 socket 接口与采用原始套接字协议的 CAN 网络进行通信。 要改为通过广播管理器协议来使用 CAN，则要用以下方式打开一个 socket:

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

在绑定 (CAN_RAW) 或连接 (CAN_BCM) socket 之后，你将可以在 socket 对象上正常使用 socket.send() 以及 socket.recv() 操作（及同类操作）。

最后一个例子可能需要特别的权限:

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 状态，无法立即重用。

要防止这种情况，需要设置一个 socket 标志 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 状态的本地套接字重新使用，而不必等到固有的超时到期。