socket ——低层组网接口

源代码: Lib/socket.py


此模块提供对BSD的访问 Socket 接口。它可以在所有现代的Unix系统、Windows、MacOS以及其他平台上使用。

注解

有些行为可能依赖于平台,因为调用操作系统套接字API。

python接口是unix系统调用和库接口的直接音译,用于将套接字转换为python面向对象的样式:the socket() 函数返回 socket object 其方法实现各种套接字系统调用。参数类型比C接口中的更高级:与 read()write() 对python文件的操作,接收操作的缓冲区分配是自动的,而发送操作的缓冲区长度是隐式的。

参见

模块 socketserver

简化网络服务器编写的类。

模块 ssl

套接字对象的TLS/SSL封装。

套接字族

根据系统和构建选项,此模块支持各种Socket系列。

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

  • 地址 AF_UNIX 绑定到文件系统节点的套接字表示为字符串,使用文件系统编码和 'surrogateescape' 错误处理程序(请参见 PEP 383 )Linux抽象命名空间中的地址作为 bytes-like object 使用一个初始的空字节;请注意,这个名称空间中的套接字可以与正常的文件系统套接字通信,因此打算在Linux上运行的程序可能需要处理这两种类型的地址。当作为参数传递时,字符串或类似于对象的字节可以用于任意一种地址类型。

    在 3.3 版更改: 以前, AF_UNIX 假定套接字路径使用UTF-8编码。

    在 3.5 版更改: 可写的 bytes-like object 现在被接受。

  • 一对 (host, port) 用于 AF_INET 地址家庭,在哪里 host 是表示Internet域表示法中的主机名的字符串,如 '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) 使用,在哪里 流程信息scope_id 代表 sin6_flowinfosin6_scope_id 成员在 struct sockaddr_in6 在C. socket 模块方法, 流程信息scope_id 为了向后兼容可以省略。但是,请注意,省略了 scope_id 可能会导致操作作用域IPv6地址时出现问题。

    在 3.7 版更改: 对于多播地址(使用 scope_id 有意义的) 地址 不得包含 %scope_id (或) zone id 部分。此信息是多余的,可以安全地省略(推荐)。

  • AF_NETLINK 套接字表示为对 (pid, groups) .

  • 使用 AF_TIPC 家庭住址。TIPC是一种开放的、非基于IP的网络协议,设计用于集群计算机环境。地址由元组表示,字段取决于地址类型。一般的元组形式是 (addr_type, v1, v2, v3 [, scope]) ,其中:

    • addr_type 是其中之一 TIPC_ADDR_NAMESEQTIPC_ADDR_NAMETIPC_ADDR_ID .

    • 范围 是其中之一 TIPC_ZONE_SCOPETIPC_CLUSTER_SCOPETIPC_NODE_SCOPE .

    • 如果 addr_typeTIPC_ADDR_NAME 然后 v1 是服务器类型, v2 是端口标识符,并且 v3 应该是0。

      如果 addr_typeTIPC_ADDR_NAMESEQ 然后 v1 是服务器类型, v2 是较低的端口号,并且 v3 是上端口号。

      如果 addr_typeTIPC_ADDR_ID 然后 v1 是节点, v2 是参考文件,并且 v3 应设置为0。

  • 元组 (interface, ) 用于 AF_CAN 地址家庭,在哪里 界面 表示网络接口名称的字符串 'can0' . 网络接口名称 '' 可用于从该系列的所有网络接口接收数据包。

    • CAN_ISOTP 协议需要元组 (interface, rx_addr, tx_addr) 其中两个附加参数都是表示CAN标识符(标准或扩展)的无符号长整数。

    • CAN_J1939 协议需要元组 (interface, name, pgn, addr) 其中,附加参数是表示ECU名称的64位无符号整数、表示参数组号(PGN)的32位无符号整数和表示地址的8位整数。

  • 字符串或元组 (id, unit) 用于 SYSPROTO_CONTROL 协议 PF_SYSTEM 家庭。字符串是使用动态分配的ID的内核控件的名称。如果已知内核控件的ID和单元号,或者使用注册的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 以字符串格式包含蓝牙地址的对象。(Ex. b'12:23:34:45:56:67' )FreeBSD不支持此协议。

  • AF_ALG 是一个Linux专用的基于套接字的内核加密接口。算法套接字配置了一个由两到四个元素组成的元组。 (type, name [, feat [, mask]]) ,其中:

    • type 算法类型是否为字符串,例如 aeadhashskcipherrng .

    • name 是作为字符串的算法名称和操作模式,例如 sha256hmac(sha256)cbc(aes)drbg_nopr_ctr_aes256 .

    • featmask 是无符号32位整数。

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

    3.6 新版功能.

  • AF_VSOCK 允许虚拟机与其主机之间进行通信。套接字表示为 (CID, port) 上下文ID或cid和端口为整数的元组。

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

    3.7 新版功能.

  • AF_PACKET 是直接连接到网络设备的低级接口。数据包由元组表示。 (ifname, proto[, pkttype[, hatype[, addr]]]) 在哪里?

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

    • 原始的 -指定以太网协议号的网络内字节顺序整数。

    • PKT型 -指定数据包类型的可选整数:

      • PACKET_HOST (默认)-发往本地主机的数据包。

      • PACKET_BROADCAST -物理层广播包。

      • PACKET_MULTIHOST -发送到物理层多播地址的数据包。

      • PACKET_OTHERHOST -在混杂模式下被设备驱动程序捕获的其他主机的数据包。

      • PACKET_OUTGOING -来自本地主机的数据包,它被循环回数据包套接字。

    • 哈蒂普 -指定ARP硬件地址类型的可选整数。

    • addr -可选字节,如指定硬件物理地址的对象,其解释取决于设备。

  • AF_QIPCRTR 是一个Linux专用的基于套接字的接口,用于与运行在高通平台上的协处理器上的服务进行通信。地址族表示为 (node, port) 元组在哪里 nodeport 是非负整数。

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

    这样的插座应该用 socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) 对于IPv4或 socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) 对于IPv6。

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

    3.9 新版功能.

如果在 host 作为IPv4/V6套接字地址的一部分,程序可能会显示不确定性行为,因为Python使用从DNS解析返回的第一个地址。根据DNS解析和/或主机配置的结果,套接字地址将以不同的方式解析为实际的IPv4/V6地址。对于确定性行为,请在 host 部分。

所有错误都会引发异常。可以引发无效参数类型和内存不足条件的正常异常;从Python3.3开始,与套接字或地址语义相关的错误将引发 OSError 或者它的一个子类 socket.error

非阻塞模式支持通过 setblocking() . 基于超时的此概括可通过 settimeout() .

模块内容

模块 socket 导出以下元素。

例外情况

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

一个子类 OSError ,对地址相关错误引发此异常 getaddrinfo()getnameinfo() .伴随值是一对 (error, string) 表示库调用返回的错误。 string 表示的说明 errors ,由 gai_strerror() C函数。数字的 errors 值将与 EAI_* 此模块中定义的常量。

在 3.3 版更改: 这个类是 OSError .

exception socket.timeout

已弃用的别名 TimeoutError

一个子类 OSError ,此异常在通过先前调用启用超时的套接字上发生超时时引发。 settimeout() (或通过 setdefaulttimeout() )伴随的值是一个字符串,其值当前总是“超时”。

在 3.3 版更改: 这个类是 OSError .

在 3.10 版更改: 这个类的别名是 TimeoutError

常量

AFA * and SOCK_* 常量现在是 AddressFamilySocketKind IntEnum 收藏。

3.4 新版功能.

socket.AF_UNIX
socket.AF_INET
socket.AF_INET6

这些常量表示地址(和协议)族,用于 socket() . 如果 AF_UNIX 未定义常量,则不支持此协议。根据系统的不同,可能会有更多的常量。

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

这些常量表示套接字类型,用于 socket() . 根据系统的不同,可能会有更多的常量。(仅) SOCK_STREAMSOCK_DGRAM 似乎一般有用。)

socket.SOCK_CLOEXEC
socket.SOCK_NONBLOCK

如果定义了这两个常量,则可以将其与套接字类型组合,并允许您原子地设置一些标志(从而避免可能的争用条件和需要单独调用)。

参见

Secure File Descriptor Handling 更详细的解释。

Availability :linux>=2.6.27。

3.2 新版功能.

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

这些形式的许多常量(在有关套接字和/或IP协议的Unix文档中记录)也在套接字模块中定义。它们通常用于 setsockopt()getsockopt() 套接字对象的方法。在大多数情况下,只定义Unix头文件中定义的符号;对于少数符号,提供默认值。

在 3.6 版更改: SO_DOMAINSO_PROTOCOLSO_PEERSECSO_PASSSECTCP_USER_TIMEOUTTCP_CONGESTION 加入。

在 3.6.5 版更改: 在Windows上, TCP_FASTOPENTCP_KEEPCNT 如果运行时Windows支持,则显示。

在 3.7 版更改: TCP_NOTSENT_LOWAT 加入。

在Windows上, TCP_KEEPIDLETCP_KEEPINTVL 如果运行时Windows支持,则显示。

socket.AF_CAN
socket.PF_CAN
SOL_CAN_*
CAN_*

Linux文档中记录的这些形式的许多常量也在socket模块中定义。

Availability :linux>=2.6.25。

3.3 新版功能.

socket.CAN_BCM
CAN_BCM_*

CAN协议系列中的CAN-BCM是广播管理器(BCM)协议。Linux文档中记录的Broadcast Manager常量也在socket模块中定义。

Availability :linux>=2.6.25。

注解

这个 CAN_BCM_CAN_FD_FRAME 标记仅在Linux>=4.8上可用。

3.4 新版功能.

socket.CAN_RAW_FD_FRAMES

在can_原始套接字中启用can-fd支持。这在默认情况下是禁用的。这允许应用程序同时发送CAN和CAN FD帧;但是,从套接字读取时,必须同时接受CAN和CAN FD帧。

Linux文档中记录了这个常量。

Availability :Linux >=3.6。

3.5 新版功能.

socket.CAN_RAW_JOIN_FILTERS

连接应用的CAN过滤器,以便只有与所有给定CAN过滤器匹配的帧才能传递到用户空间。

Linux文档中记录了这个常量。

Availability :Linux>=4.1。

3.9 新版功能.

socket.CAN_ISOTP

CAN协议系列中的CAN-ISOTP是ISO-TP(ISO 15765-2)协议。ISO-TP常量,记录在Linux文档中。

Availability :linux>=2.6.25。

3.7 新版功能.

socket.CAN_J1939

在CAN协议系列中,CAN-J1939是saej1939协议。J1939常量,记录在Linux文档中。

Availability :Linux>=5.4。

3.9 新版功能.

socket.AF_PACKET
socket.PF_PACKET
PACKET_*

Linux文档中记录的这些形式的许多常量也在socket模块中定义。

Availability :Linux >=2.2。

socket.AF_RDS
socket.PF_RDS
socket.SOL_RDS
RDS_*

Linux文档中记录的这些形式的许多常量也在socket模块中定义。

Availability :linux>=2.6.30。

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相关的常量,与c socket api导出的常量匹配。有关更多信息,请参阅TIPC文档。

socket.AF_ALG
socket.SOL_ALG
ALG_*

Linux内核加密的常量。

Availability :linux>=2.6.38。

3.6 新版功能.

socket.AF_VSOCK
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID
VMADDR*
SO_VM*

Linux主机/来宾通信常量。

Availability :Linux >=4.8。

3.7 新版功能.

Availability BSD,OSX。

3.4 新版功能.

socket.has_ipv6

此常量包含一个布尔值,该值指示此平台上是否支持IPv6。

socket.BDADDR_ANY
socket.BDADDR_LOCAL

这些是包含具有特殊含义的蓝牙地址的字符串常量。例如, BDADDR_ANY 在指定绑定套接字时,可以使用 BTPROTO_RFCOMM .

socket.HCI_FILTER
socket.HCI_TIME_STAMP
socket.HCI_DATA_DIR

供使用 BTPROTO_HCI . HCI_FILTER 不适用于netbsd或dragonflybsd。 HCI_TIME_STAMPHCI_DATA_DIR 不适用于freebsd、netbsd或dragonflybsd。

socket.AF_QIPCRTR

高通公司IPC路由器协议的常量,用于与提供远程处理器的服务通信。

Availability :Linux >=4.7。

功能

创建套接字

以下所有函数都创建 socket objects .

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

使用给定的地址系列、套接字类型和协议号创建新的套接字。地址家庭应该是 AF_INET (违约), AF_INET6AF_UNIXAF_CANAF_PACKETAF_RDS . 套接字类型应为 SOCK_STREAM (违约), SOCK_DGRAMSOCK_RAW 或者可能是另一个 SOCK_ 常量。协议号通常为零,可以省略,或者在地址族为 AF_CAN 协议应该是 CAN_RAWCAN_BCMCAN_ISOTPCAN_J1939 .

如果 文件描述符 是指定的,值为 家庭type原始的 从指定的文件描述符中自动检测到。通过使用显式调用函数,可以取消自动检测 家庭type原始的 参数。这只影响python表示的方式,例如 socket.getpeername() 但不是实际的操作系统资源。不像 socket.fromfd()文件描述符 将返回相同的套接字,而不是重复的。这可能有助于使用 socket.close() .

新创建的套接字是 non-inheritable .

提出一个 auditing event socket.__new__ 带着论据 selffamilytypeprotocol .

在 3.3 版更改: 添加了af_can家族。添加了af-rds家族。

在 3.4 版更改: 添加了CAN-BCM协议。

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

在 3.7 版更改: 添加了can eu-isopp协议。

在 3.7 版更改: 什么时候? SOCK_NONBLOCKSOCK_CLOEXEC 位标志应用于 type 他们被清除了,并且 socket.type 不会反映出来。它们仍然传递给底层系统 socket() 打电话来。因此,

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

仍将在支持的操作系统上创建非阻塞套接字 SOCK_NONBLOCK ,但是 sock.type 将被设置为 socket.SOCK_STREAM .

在 3.9 版更改: 增加了CAN-J1939协议。

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

使用给定的地址系列、套接字类型和协议号构建一对连接的套接字对象。地址系列、套接字类型和协议号与 socket() 上面的函数。默认族是 AF_UNIX 如果在平台上定义,则默认为 AF_INET .

新创建的套接字是 non-inheritable .

在 3.2 版更改: 返回的socket对象现在支持整个socket API,而不是一个子集。

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

在 3.5 版更改: 已添加Windows支持。

socket.create_connection(address[, timeout[, source_address]])

连接到Internet上正在侦听的TCP服务 地址 (2元组) (host, port) ,然后返回socket对象。这是一个比 socket.connect() 如果 host 是一个非数字主机名,它将尝试同时解析这两个主机名 AF_INETAF_INET6 ,然后依次尝试连接到所有可能的地址,直到连接成功。这使得编写既兼容IPv4又兼容IPv6的客户端变得容易。

通过选项 timeout 参数将在尝试连接之前设置套接字实例的超时。如果没有 timeout 如果提供,则返回全局默认超时设置 getdefaulttimeout() 使用。

如果提供, source_address 必须是2元组 (host, port) 以便在连接前将套接字绑定到作为其源地址。如果主机或端口分别为“”或0,则将使用操作系统默认行为。

在 3.2 版更改: source_address 加入。

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

地址 (2元组) (host, port)

家庭 应该是 AF_INETAF_INET6 . 积压 socket.listen() 0 reuse_port SO_REUSEPORT

如果 dualstack_ipv6 ValueError socket.getpeername() dualstack_ipv6 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)

注解

SO_REUSEADDR 地址

3.8 新版功能.

socket.has_dualstack_ipv6()

返回 True

3.8 新版功能.

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

复制文件描述符 fd (文件对象返回的整数 fileno() 方法)并根据结果构建一个套接字对象。地址系列、套接字类型和协议号与 socket() 上面的函数。文件描述符应该引用一个套接字,但没有选中它---如果文件描述符无效,对对象的后续操作可能会失败。很少需要此函数,但可以用于获取或设置作为标准输入或输出(例如由unix inet守护进程启动的服务器)传递给程序的套接字选项。假定套接字处于阻塞模式。

新创建的套接字是 non-inheritable .

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

socket.fromshare(data)

从中获取的数据实例化套接字 socket.share() 方法。假定套接字处于阻塞模式。

Availability :Windows。

3.3 新版功能.

socket.SocketType

这是一个代表套接字对象类型的python类型对象。它和 type(socket(...)) .

其他功能

这个 socket 模块还提供各种网络相关服务:

socket.close(fd)

关闭套接字文件描述符。这就像 os.close() ,但Socket除外。在某些平台上(最明显的窗口) os.close() 不适用于套接字文件描述符。

3.7 新版功能.

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

翻译 host / port 参数转换成5个元组的序列,其中包含创建连接到该服务的套接字所需的所有参数。 host 是域名、IPv4/V6地址的字符串表示形式或 None . port 是字符串服务名称,例如 'http' ,数字端口号或 None . 旁路 None 作为价值 hostport 你可以通过 NULL 到基础C API。

这个 家庭type原始的 可以选择指定参数以缩小返回的地址列表。将零作为每个参数的值传递,将选择完整的结果范围。这个 flags 参数可以是 AI_* 常量,并将影响计算和返回结果的方式。例如, AI_NUMERICHOST 将禁用域名解析,如果 host 是域名。

函数返回具有以下结构的5个元组的列表:

(family, type, proto, canonname, sockaddr)

在这些元组中, 家庭type原始的 都是整数,并且要传递给 socket() 功能。 冠名 将是一个字符串,表示 host 如果 AI_CANONNAME旗帜 争论;其他 冠名 将为空。 索卡德尔 是描述套接字地址的元组,其格式取决于返回的 家庭 (A) (address, port) 2-元组 AF_INET ,A (address, port, flowinfo, scope_id) 4元组 AF_INET6 ,并将传递给 socket.connect() 方法。

提出一个 auditing event socket.getaddrinfo 带着论据 hostportfamilytypeprotocol .

下面的示例获取假设的TCP连接的地址信息 example.org 在端口80上(如果未启用IPv6,系统上的结果可能会有所不同)::

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

在 3.2 版更改: 现在可以使用关键字参数传递参数。

在 3.7 版更改: 对于IPv6多播地址,表示地址的字符串将不包含 %scope_id 部分。

socket.getfqdn([name])

返回的完全限定域名 name .如果 name 被省略或为空,将其解释为本地主机。要查找完全限定名,主机名由 gethostbyaddr() 已选中,然后是主机的别名(如果可用)。选择包含句点的名字。如果没有完全限定的域名可用,则返回的主机名 gethostname() 返回。

socket.gethostbyname(hostname)

将主机名转换为IPv4地址格式。IPv4地址作为字符串返回,例如 '100.50.200.5' . 如果主机名是IPv4地址本身,则返回时不变。见 gethostbyname_ex() 更完整的界面。 gethostbyname() 不支持IPv6名称解析,并且 getaddrinfo() 应该用于支持IPv4/V6双堆栈。

提出一个 auditing event socket.gethostbyname 带着论证 hostname .

socket.gethostbyname_ex(hostname)

将主机名转换为IPv4地址格式,扩展接口。返回三倍 (hostname, aliaslist, ipaddrlist) 在哪里? 主机名 主主机名是否响应给定的 ip_address别名列表 是同一地址的备用主机名列表(可能为空),以及 IPAD列表 是同一主机上同一接口的IPv4地址列表(通常但不总是一个地址)。 gethostbyname_ex() 不支持IPv6名称解析,并且 getaddrinfo() 应该用于支持IPv4/V6双堆栈。

提出一个 auditing event socket.gethostbyname 带着论证 hostname .

socket.gethostname()

返回一个字符串,该字符串包含当前执行Python解释器的计算机的主机名。

提出一个 auditing event socket.gethostname 没有参数。

注: gethostname() 不总是返回完全限定的域名;使用 getfqdn() 为此。

socket.gethostbyaddr(ip_address)

返回三倍 (hostname, aliaslist, ipaddrlist) 在哪里? 主机名 主主机名是否响应给定的 ip_address别名列表 是同一地址的备用主机名列表(可能为空),以及 IPAD列表 是同一主机上同一接口的IPv4/V6地址列表(很可能只包含一个地址)。要查找完全限定的域名,请使用函数 getfqdn() . gethostbyaddr() 同时支持IPv4和IPv6。

提出一个 auditing event socket.gethostbyaddr 带着论证 ip_address .

socket.getnameinfo(sockaddr, flags)

转换套接字地址 索卡德尔 成为一个2元组 (host, port) . 取决于的设置 flags ,结果可以包含完全限定的域名或数字地址表示形式 host .同样地, port 可以包含字符串端口名或数字端口号。

对于IPv6地址, %scope_id 附加到主机部件,如果 索卡德尔 包含有意义的 scope_id . 这种情况通常发生在多播地址上。

有关的详细信息 旗帜 getnameinfo(3) .

提出一个 auditing event socket.getnameinfo 带着论证 sockaddr .

socket.getprotobyname(protocolname)

翻译Internet协议名称(例如, 'icmp' )到适合作为(可选)第三个参数传递给 socket() 功能。这通常只需要在“原始”模式下打开的套接字 (SOCK_RAW );对于正常套接字模式,如果协议被省略或为零,则自动选择正确的协议。

socket.getservbyname(servicename[, protocolname])

将Internet服务名和协议名转换为该服务的端口号。如果给定可选的协议名,则应为 'tcp''udp' ,否则任何协议都将匹配。

提出一个 auditing event socket.getservbyname 带着论据 servicenameprotocolname .

socket.getservbyport(port[, protocolname])

将Internet端口号和协议名转换为该服务的服务名。如果给定可选的协议名,则应为 'tcp''udp' ,否则任何协议都将匹配。

提出一个 auditing event socket.getservbyport 带着论据 portprotocolname .

socket.ntohl(x)

将32位正整数从网络转换为主机字节顺序。在主机字节顺序与网络字节顺序相同的机器上,这是一个no op;否则,它执行4字节交换操作。

socket.ntohs(x)

将16位正整数从网络转换为主机字节顺序。在主机字节顺序与网络字节顺序相同的机器上,这是一个no op;否则,它执行一个2字节交换操作。

在 3.10 版更改: 加薪 OverflowError 如果 x 不适合16位无符号整数。

socket.htonl(x)

将32位正整数从主机转换为网络字节顺序。在主机字节顺序与网络字节顺序相同的机器上,这是一个no op;否则,它执行4字节交换操作。

socket.htons(x)

将16位正整数从主机转换为网络字节顺序。在主机字节顺序与网络字节顺序相同的机器上,这是一个no op;否则,它执行一个2字节交换操作。

在 3.10 版更改: 加薪 OverflowError 如果 x 不适合16位无符号整数。

socket.inet_aton(ip_string)

将IPv4地址从点分四字符串格式(例如,“123.45.67.89”)转换为32位压缩二进制格式,作为字节对象,长度为4个字符。当与使用标准C库并需要类型为 struct in_addr ,它是此函数返回的32位压缩二进制文件的C类型。

inet_aton() 还接受少于三个点的字符串;请参见Unix手册页 inet(3) 有关详细信息。

如果传递给此函数的IPv4地址字符串无效, OSError 将被引发。请注意,正确的有效性取决于 inet_aton() .

inet_aton() 不支持IPv6,并且 inet_pton() 应该用于支持IPv4/V6双堆栈。

socket.inet_ntoa(packed_ip)

转换32位压缩的IPv4地址(A bytes-like object 四个字节的长度)到其标准的点四字符串表示形式(例如,“123.45.67.89”)。当与使用标准C库并需要类型为 struct in_addr ,它是32位压缩二进制数据的C类型,此函数将其作为参数。

如果传递给此函数的字节序列的长度不是4个字节, OSError 将被引发。 inet_ntoa() 不支持IPv6,并且 inet_ntop() 应该用于支持IPv4/V6双堆栈。

在 3.5 版更改: 可写的 bytes-like object 现在被接受。

socket.inet_pton(address_family, ip_string)

将IP地址从其系列特定的字符串格式转换为压缩的二进制格式。 inet_pton() 当库或网络协议调用类型的对象时很有用 struct in_addr (类似于 inet_aton()struct in6_addr .

支持的值 address_family 目前 AF_INETAF_INET6 . 如果IP地址字符串 ip_string 无效, OSError 将被引发。请注意,正确的有效值取决于 address_family 以及 inet_pton() .

Availability :Unix(可能不是所有平台)、Windows。

在 3.4 版更改: 已添加Windows支持

socket.inet_ntop(address_family, packed_ip)

转换打包的IP地址(A bytes-like object 以其标准的、特定于系列的字符串表示形式(例如, '7.10.0.5''5aef:2b::8'inet_ntop() 当库或网络协议返回类型为的对象时很有用 struct in_addr (类似于 inet_ntoa()struct in6_addr .

支持的值 address_family 目前 AF_INETAF_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 如果 长度 超出了允许的值范围。

Availability :大多数Unix平台,可能还有其他平台。

3.3 新版功能.

socket.CMSG_SPACE(length)

返回所需的缓冲区大小 recvmsg() 接收具有给定的关联数据的辅助数据项 长度 以及任何尾随填充。接收多个项目所需的缓冲区空间是 CMSG_SPACE() 相关数据长度的值。引发 OverflowError 如果 长度 超出了允许的值范围。

请注意,有些系统可能支持不提供此功能的辅助数据。另外请注意,使用此函数的结果设置缓冲区大小可能不会精确地限制可以接收的辅助数据的数量,因为附加数据可能适合填充区域。

Availability :大多数Unix平台,可能还有其他平台。

3.3 新版功能.

socket.getdefaulttimeout()

返回新套接字对象的默认超时(以秒为单位)(浮点)。一个值 None 指示新的套接字对象没有超时。首次导入套接字模块时,默认值为 None .

socket.setdefaulttimeout(timeout)

为新的套接字对象设置默认超时(以秒为单位)(浮点)。首次导入套接字模块时,默认值为 None . 见 settimeout() 对于可能的值及其各自的含义。

socket.sethostname(name)

将计算机的主机名设置为 name . 这将提高 OSError 如果你没有足够的权利。

提出一个 auditing event socket.sethostname 带着论证 name .

Availability UNIX。

3.3 新版功能.

socket.if_nameindex()

返回网络接口信息(index int,name string)元组的列表。 OSError 如果系统调用失败。

Availability :Unix、Windows。

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。

3.3 新版功能.

在 3.8 版更改: 已添加Windows支持。

参见

“接口名称”是中记录的名称 if_nameindex()

socket.if_indextoname(if_index)

返回与接口索引号相对应的网络接口名称。 OSError 如果不存在与给定索引的接口。

Availability :Unix、Windows。

3.3 新版功能.

在 3.8 版更改: 已添加Windows支持。

参见

“接口名称”是中记录的名称 if_nameindex()

套接字对象

socket对象有以下方法。除了 makefile() ,这些对应于适用于套接字的UNIX系统调用。

在 3.2 版更改: 支持 context manager 添加了协议。退出上下文管理器等同于调用 close() .

socket.accept()

接受连接。套接字必须绑定到地址并侦听连接。返回值是一对 (conn, address) 在哪里? conn 是一个 new 可用于在连接上发送和接收数据的套接字对象,以及 地址 是绑定到连接另一端套接字的地址。

新创建的套接字是 non-inheritable .

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

在 3.5 版更改: 如果系统调用被中断并且信号处理程序没有引发异常,则该方法现在将重试系统调用,而不是引发 InterruptedError 例外(见) PEP 475 理由)。

socket.bind(address)

将套接字绑定到 地址 . 套接字必须尚未绑定。(格式) 地址 取决于地址族---见上文。)

提出一个 auditing event socket.bind 带着论据 selfaddress .

socket.close()

标记Socket已关闭。当来自的所有文件对象 makefile() 关闭。一旦发生这种情况,以后对socket对象的所有操作都将失败。远程端将不再接收数据(在刷新排队的数据之后)。

套接字在被垃圾收集时自动关闭,但建议 close() 明确地,或者使用 with 他们周围的声明。

在 3.6 版更改: OSError 如果在下面的 close() 调用来。

注解

close() 释放与连接关联的资源,但不一定立即关闭连接。如果要及时关闭连接,请致电 shutdown() 之前 close() .

socket.connect(address)

连接到远程Socket 地址 . (格式) 地址 取决于地址族---见上文。)

如果连接被信号中断,则该方法将等待,直到连接完成,或者引发 TimeoutError 在超时时,如果信号处理程序没有引发异常,并且套接字阻塞或超时。对于非阻塞套接字,该方法引发 InterruptedError 如果连接被信号(或信号处理程序引发的异常)中断,则引发异常。

提出一个 auditing event socket.connect 带着论据 selfaddress .

在 3.5 版更改: 方法现在等待连接完成,而不是引发 InterruptedError 异常如果连接被信号中断,则信号处理程序不会引发异常,并且套接字被阻塞或超时(请参见 PEP 475 理由)。

socket.connect_ex(address)

类似于 connect(address) ,但返回错误指示器,而不是对C级别返回的错误引发异常 connect() 调用(其他问题,如“主机未找到”,仍会引发异常)。错误指示器是 0 如果操作成功,则返回 errno 变量。这对于支持异步连接很有用。

提出一个 auditing event socket.connect 带着论据 selfaddress .

socket.detach()

将socket对象置于关闭状态,而不实际关闭底层文件描述符。文件描述符将被返回,并可用于其他目的。

3.2 新版功能.

socket.dup()

复制Socket。

新创建的套接字是 non-inheritable .

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

socket.fileno()

返回套接字的文件描述符(小整数),失败时返回-1。这对 select.select() .

在Windows下,如果可以使用文件描述符(例如 os.fdopen() )。Unix没有这个限制。

socket.get_inheritable()

得到 inheritable flag 套接字的文件描述符或套接字句柄: True 如果套接字可以在子进程中继承, False 如果不能。

3.4 新版功能.

socket.getpeername()

返回套接字连接到的远程地址。例如,这对于查找远程IPv4/V6套接字的端口号很有用。(返回地址的格式取决于地址族---见上文。)在某些系统上,不支持此功能。

socket.getsockname()

返回套接字自己的地址。例如,这对于查找IPv4/V6套接字的端口号很有用。(返回地址的格式取决于地址族---见上文。)

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

返回给定socket选项的值(请参见Unix手册页 getsockopt(2) )所需的符号常量 (SO_* 等)在本模块中定义。如果 缓冲区长度 如果不存在,则假定使用integer选项,函数将返回其整数值。如果 缓冲区长度 如果存在,它将指定用于接收中选项的缓冲区的最大长度,并且该缓冲区作为字节对象返回。由调用者来解码缓冲区的内容(参见可选的内置模块 struct 用于解码编码为字节字符串的C结构)。

socket.getblocking()

返回 True 如果Socket处于阻塞模式, False 如果处于非阻塞状态。

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

3.7 新版功能.

socket.gettimeout()

返回与套接字操作相关联的超时(以秒为单位)(浮点),或者 None 如果没有设置超时。这反映了 setblocking()settimeout() .

socket.ioctl(control, option)
平台

Windows

这个 ioctl() 方法是wsaioctl系统接口的有限接口。请参阅 Win32 documentation 更多信息。

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

目前仅支持以下控制代码: SIO_RCVALLSIO_KEEPALIVE_VALSSIO_LOOPBACK_FAST_PATH .

在 3.6 版更改: SIO_LOOPBACK_FAST_PATH 加入。

socket.listen([backlog])

允许服务器接受连接。如果 积压 如果指定,则必须至少为0(如果低于0,则设置为0);它指定系统在拒绝新连接之前允许的未接受连接数。如果未指定,则选择默认的合理值。

在 3.5 版更改: 这个 积压 参数现在是可选的。

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

返回A file object 与套接字关联。返回的确切类型取决于给定的参数 makefile() . 这些参数的解释方式与内置的 open() 函数,只支持 mode 价值观是 'r' (默认) 'w''b' .

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

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

注解

在Windows上,由 makefile() 不能在需要具有文件描述符的文件对象的位置使用,例如 subprocess.Popen() .

socket.recv(bufsize[, flags])

从套接字接收数据。返回值是表示接收数据的字节对象。一次接收的最大数据量由 蟾蜍尺码 . 请参见Unix手册页 recv(2) 为了可选参数的意义 flags ;默认为零。

注解

为了与硬件和网络现实最佳匹配, 蟾蜍尺码 应该是一个相对较小的2的幂,例如4096。

在 3.5 版更改: 如果系统调用被中断并且信号处理程序没有引发异常,则该方法现在将重试系统调用,而不是引发 InterruptedError 例外(见) PEP 475 理由)。

socket.recvfrom(bufsize[, flags])

从套接字接收数据。返回值是一对 (bytes, address) 在哪里? 字节 是表示接收数据的bytes对象,并且 地址 是发送数据的套接字的地址。请参见Unix手册页 recv(2) 为了可选参数的意义 flags ;默认为零。(格式) 地址 取决于地址族---见上文。)

在 3.5 版更改: 如果系统调用被中断并且信号处理程序没有引发异常,则该方法现在将重试系统调用,而不是引发 InterruptedError 例外(见) PEP 475 理由)。

在 3.7 版更改: 对于多播IPv6地址,第一项 地址 不包含 %scope_id 部分不再。为了获得完整的IPv6地址,请使用 getnameinfo() .

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

接收正常数据(最多 蟾蜍尺码 字节)和来自套接字的辅助数据。这个 联合规模 参数设置用于接收辅助数据的内部缓冲区的字节大小;它默认为0,表示不会接收任何辅助数据。可使用以下公式计算辅助数据的适当缓冲区大小: CMSG_SPACE()CMSG_LEN() 和不适合缓冲区的项可能被截断或丢弃。这个 flags 参数默认为0,其含义与 recv() .

返回值是4元组: (data, ancdata, msg_flags, address) . 这个 data 项目是 bytes 保存接收到的非辅助数据的对象。这个 ANCODATA 项是零个或多个元组的列表 (cmsg_level, cmsg_type, cmsg_data) 表示接收到的辅助数据(控制消息): cmsg_levelcmsg_type 是分别指定协议级别和协议特定类型的整数,以及 cmsg_data 是一个 bytes 保存关联数据的对象。这个 msg_flags item是指示接收消息条件的各种标志的位或;有关详细信息,请参阅系统文档。如果接收Socket未连接, 地址 是发送套接字的地址(如果可用);否则,其值未指定。

在某些系统上, sendmsg()recvmsg() 可用于在进程之间传递文件描述符 AF_UNIX Socket。当使用此设施时(通常仅限于 SOCK_STREAM 套接字) recvmsg() 将在其辅助数据中返回表单的项 (socket.SOL_SOCKET, socket.SCM_RIGHTS, fds) 在哪里 fds 是一个 bytes 对象,将新的文件描述符表示为本机C的二进制数组 int 类型。如果 recvmsg() 在系统调用返回后引发异常,它将首先尝试关闭通过此机制接收的任何文件描述符。

有些系统不指示仅部分接收的辅助数据项的截断长度。如果一个项似乎超出了缓冲区的末尾, recvmsg() 将发行 RuntimeWarning ,并返回缓冲区内的部分,前提是在相关数据开始之前未截断该部分。

在支持 SCM_RIGHTS 机构,以下功能最多可接收 最大自由度 文件描述符,返回消息数据和包含描述符的列表(同时忽略接收到的不相关控制消息等意外情况)。也见 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平台,可能还有其他平台。

3.3 新版功能.

在 3.5 版更改: 如果系统调用被中断并且信号处理程序没有引发异常,则该方法现在将重试系统调用,而不是引发 InterruptedError 例外(见) PEP 475 理由)。

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

从套接字接收正常数据和辅助数据,表现为 recvmsg() 将非辅助数据分散到一系列缓冲区中,而不是返回新的bytes对象。这个 缓冲器 参数必须是导出可写缓冲区(例如 bytearray 对象);这些将用连续的非辅助数据块填充,直到全部写入或不再有缓冲区为止。操作系统可能会设置限制 (sysconf() 价值 SC_IOV_MAX )可使用的缓冲区数量。这个 联合规模flags 参数的含义与 recvmsg() .

返回值是4元组: (nbytes, ancdata, msg_flags, address) 在哪里 字节数 是写入缓冲区的非辅助数据的总字节数,以及 ANCODATAmsg_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平台,可能还有其他平台。

3.3 新版功能.

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

从套接字接收数据,并将其写入 缓冲区 而不是创建一个新的字节串。返回值是一对 (nbytes, address) 在哪里? 字节数 是接收的字节数,并且 地址 是发送数据的套接字的地址。请参见Unix手册页 recv(2) 为了可选参数的意义 flags ;默认为零。(格式) 地址 取决于地址族---见上文。)

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

接收到 字节数 来自套接字的字节,将数据存储到缓冲区中,而不是创建新的字节串。如果 字节数 未指定(或0),接收到给定缓冲区中可用的大小。返回接收的字节数。请参见Unix手册页 recv(2) 为了可选参数的意义 flags ;默认为零。

socket.send(bytes[, flags])

将数据发送到套接字。Socket必须连接到远程Socket。可选的 flags 参数的含义与for相同 recv() 上面。返回发送的字节数。应用程序负责检查所有数据是否已发送;如果只传输了部分数据,则应用程序需要尝试传递其余数据。有关此主题的详细信息,请参阅 Socket编程方法 .

在 3.5 版更改: 如果系统调用被中断并且信号处理程序没有引发异常,则该方法现在将重试系统调用,而不是引发 InterruptedError 例外(见) PEP 475 理由)。

socket.sendall(bytes[, flags])

将数据发送到套接字。Socket必须连接到远程Socket。可选的 flags 参数的含义与for相同 recv() 上面。不像 send() ,此方法继续从 字节 直到发送完所有数据或发生错误。 None 成功时返回。出错时会引发异常,无法确定成功发送了多少数据(如果有)。

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

在 3.5 版更改: 如果系统调用被中断并且信号处理程序没有引发异常,则该方法现在将重试系统调用,而不是引发 InterruptedError 例外(见) PEP 475 理由)。

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

将数据发送到套接字。套接字不应连接到远程套接字,因为目标套接字由 地址 . 可选的 flags 参数的含义与for相同 recv() 上面。返回发送的字节数。(格式 地址 取决于地址族---见上文。)

提出一个 auditing event socket.sendto 带着论据 selfaddress .

在 3.5 版更改: 如果系统调用被中断并且信号处理程序没有引发异常,则该方法现在将重试系统调用,而不是引发 InterruptedError 例外(见) PEP 475 理由)。

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

将正常和辅助数据发送到套接字,从一系列缓冲区收集非辅助数据,并将其连接到单个消息中。这个 缓冲器 参数将非辅助数据指定为 bytes-like objects (例如) bytes 对象);操作系统可以设置限制 (sysconf() 价值 SC_IOV_MAX )可使用的缓冲区数量。这个 ANCODATA 参数将辅助数据(控制消息)指定为零个或多个元组的可Itable (cmsg_level, cmsg_type, cmsg_data) 在哪里 cmsg_levelcmsg_type 是分别指定协议级别和协议特定类型的整数,以及 cmsg_data 是一个类似于保存相关数据的对象的字节。注意一些系统(特别是没有 CMSG_SPACE() )可能支持每个调用仅发送一条控制消息。这个 flags 参数默认为0,其含义与 send() . 如果 地址 是否提供 None 设置消息的目标地址。返回值是发送的非辅助数据的字节数。

以下函数发送文件描述符列表 fds 过了 AF_UNIX Socket,位于支持 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平台,可能还有其他平台。

提出一个 auditing event socket.sendmsg 带着论据 selfaddress .

3.3 新版功能.

在 3.5 版更改: 如果系统调用被中断并且信号处理程序没有引发异常,则该方法现在将重试系统调用,而不是引发 InterruptedError 例外(见) PEP 475 理由)。

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

的专用版本 sendmsg() 对于 AF_ALG Socket。设置模式、IV、AEAD相关数据长度和标志 AF_ALG Socket。

Availability :linux>=2.6.38。

3.6 新版功能.

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

发送文件描述符列表 fds 过了 AF_UNIX 插座。这个 fds 参数是一系列文件描述符。咨询 sendmsg() 用于记录这些参数。

Availability :UNIX支持 sendmsg()SCM_RIGHTS 机械装置。

3.9 新版功能.

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

接收到 最大自由度 文件描述符。返回 (msg, list(fds), flags, addr) . 查阅 recvmsg() 用于记录这些参数。

Availability :UNIX支持 recvmsg()SCM_RIGHTS 机械装置。

3.9 新版功能.

注解

文件描述符列表末尾的任何截断整数。

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

使用高性能发送文件,直到达到EOF os.sendfile 并返回发送的字节总数。 file 必须是以二进制模式打开的常规文件对象。如果 os.sendfile 不可用(如Windows)或 file 不是常规文件 send() 将改为使用。 抵消 告诉从何处开始读取文件。如果指定, 计数 是要传输的总字节数,而不是在达到EOF之前发送文件。文件位置在返回时更新,或者在出现错误的情况下更新 file.tell() 可以用来计算发送的字节数。Socket必须为 SOCK_STREAM 类型。不支持非阻塞套接字。

3.5 新版功能.

socket.set_inheritable(inheritable)

设置 inheritable flag 套接字的文件描述符或套接字句柄。

3.4 新版功能.

socket.setblocking(flag)

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

这种方法确实是 settimeout() 调用:

  • sock.setblocking(True) is equivalent to sock.settimeout(None)

  • sock.setblocking(False) is equivalent to sock.settimeout(0.0)

在 3.7 版更改: 该方法不再适用 SOCK_NONBLOCK 旗上 socket.type .

socket.settimeout(value)

设置阻塞套接字操作的超时。这个 value 参数可以是表示秒的非负浮点数,或者 None . 如果给定一个非零值,随后的套接字操作将引发 timeout 如果超时时间为 value 在操作完成之前已过。如果给定零,则将套接字置于非阻塞模式。如果 None 如果给定,则将套接字置于阻塞模式。

有关更多信息,请咨询 notes on socket timeouts .

在 3.7 版更改: 方法不再切换 SOCK_NONBLOCK 旗上 socket.type .

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

设置给定socket选项的值(请参见Unix手册页 setsockopt(2) )所需的符号常量在 socket 模块 (SO_* 等等)。该值可以是整数, None 或A bytes-like object 表示缓冲区。在后一种情况下,由调用者来确保字节串包含正确的位(参见可选的内置模块 struct 一种将C结构编码为bytestrings的方法)。什么时候? 价值 设置为 Noneoptlen公司 参数是必需的。相当于打电话 setsockopt() C函数 optval=NULLoptlen=optlen .

在 3.5 版更改: 可写的 bytes-like object 现在被接受。

在 3.6 版更改: 添加了setsockopt(level,optname,none,optlen:int)表单。

socket.shutdown(how)

关闭连接的一个或两个部分。如果 howSHUT_RD ,不允许进一步接收。如果 howSHUT_WR ,不允许进一步发送。如果 howSHUT_RDWR ,不允许进一步发送和接收。

socket.share(process_id)

复制套接字并准备与目标进程共享。目标流程必须提供 process_id . 然后,可以使用某种形式的进程间通信将生成的bytes对象传递给目标进程,并且可以使用在那里重新创建套接字 fromshare() . 一旦调用了这个方法,就可以安全地关闭套接字,因为操作系统已经为目标进程复制了它。

Availability :Windows。

3.3 新版功能.

请注意,没有任何方法 read()write() 使用 recv()send() 没有 flags 改为参数。

socket对象还具有这些(只读)属性,这些属性对应于 socket 构造函数。

socket.family

Socket家族。

socket.type

Socket类型。

socket.proto

套接字协议。

Socket超时注意事项

套接字对象可以处于三种模式之一:阻塞、非阻塞或超时。默认情况下,套接字始终以阻塞模式创建,但可以通过调用 setdefaulttimeout() .

  • 阻塞模式 ,操作将一直阻塞到完成,或者系统返回错误(例如连接超时)。

  • non-blocking mode ,如果无法立即完成操作,则操作将失败(很遗憾,错误取决于系统):来自的函数 select 可以用来知道何时以及是否有一个套接字可以读写。

  • 超时模式 ,如果无法在为套接字指定的超时内完成操作,则操作失败(它们引发 timeout 异常)或系统返回错误。

注解

在操作系统级别,套接字 超时模式 内部设置为非阻塞模式。此外,阻塞和超时模式在引用同一网络端点的文件描述符和套接字对象之间共享。如果您决定使用 fileno() Socket的

超时和 connect 方法

这个 connect() 操作也受超时设置的限制,通常建议调用 settimeout() 调用之前 connect() 或将超时参数传递给 create_connection() . 但是,无论python socket超时设置如何,系统网络堆栈也可能返回自己的连接超时错误。

超时和 accept 方法

如果 getdefaulttimeout() 不是 None ,由返回的套接字 accept() 方法继承该超时。否则,行为取决于侦听套接字的设置:

  • 如果监听Socket在 阻塞模式 或在 超时模式 ,套接字由返回 accept() 是在 阻塞模式

  • 如果监听Socket在 non-blocking mode ,套接字是否由返回 accept() 处于阻塞或非阻塞模式取决于操作系统。如果要确保跨平台行为,建议手动覆盖此设置。

例子

下面是使用TCP/IP协议的四个最基本的示例程序:一个服务器回显它接收到的所有数据(仅为一个客户机提供服务),另一个客户机使用它。请注意,服务器必须执行该序列 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() 在它正在监听的套接字上,但在由返回的新套接字上 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)

下一个示例演示如何使用套接字接口使用原始套接字协议与CAN网络通信。要将CAN与Broadcast Manager协议一起使用,请打开一个套接字:

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

装订后 (CAN_RAW 或连接 (CAN_BCM )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 状态,而不等待其自然超时到期。

参见

有关套接字编程的介绍(在C中),请参阅以下论文:

  • 介绍性的4.3BSD进程间通信教程 ,作者:Stuart Sechret

  • 高级4.3BSD进程间通信教程 ,由Samuel J.Leffler等人,

在Unix程序员手册中,补充文档1(第PS1:7节和第PS1:8节)。各种与套接字相关的系统调用的平台特定参考资料也是有关套接字语义细节的宝贵信息源。对于UNIX,请参阅手册页;对于Windows,请参阅Winsock(或Winsock 2)规范。对于支持IPv6的API,读卡器可能希望引用 RFC 3493 标题为IPv6的基本套接字接口扩展。