函数
创建套接字
下列函数都能创建 套接字对象.
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 之一。
如果指定了 fileno,那么将从这一指定的文件描述符中自动检测 family、type 和 proto 的值。如果调用本函数时显式指定了 family、type 或 proto 参数,可以覆盖自动检测的值。这只会影响 Python 表示诸如 socket.getpeername() 一类函数的返回值的方式,而不影响实际的操作系统资源。与 socket.fromfd() 不同,fileno 将返回原先的套接字,而不是复制出新的套接字。这有助于在分离的套接字上调用 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 版更改: 当将 SOCK_NONBLOCK 或 SOCK_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 协议。
在 3.10 版更改: 添加了 IPPROTO_MPTCP 协议。
socket.
socketpair
([family[, type[, proto]]])
构建一对已连接的套接字对象,使用给定的地址簇、套接字类型和协议号。地址簇、套接字类型和协议号与上述 socket()
函数相同。默认地址簇为 AF_UNIX (需要当前平台支持,不支持则默认为 AF_INET )。
新创建的套接字都是 不可继承的。
在 3.2 版更改: 现在,返回的套接字对象支持全部套接字 API,而不是全部 API 的一个子集。
在 3.4 版更改: 返回的套接字现在都是不可继承的。
在 3.5 版更改: 添加了 Windows 支持。
socket.
create_connection
(address[, timeout[, source_address]])
连接到一个在互联网 address (以 (host, port)
2 元组表示) 上侦听的 TCP 服务,并返回套接字对象。 这是一个相比 socket.connect() 层级更高的函数:如果 host 是非数字的主机名,它将尝试将其解析为 AF_INET 和 AF_INET6,然后依次尝试连接到所有可能的地址直到连接成功。 这使编写兼容 IPv4 和 IPv6 的客户端变得很容易。
传入可选参数 timeout 可以在套接字实例上设置超时(在尝试连接前)。如果未提供 timeout,则使用由 getdefaulttimeout() 返回的全局默认超时设置。
如果提供了 source_address,它必须为二元组 (host, port)
,以便套接字在连接之前绑定为其源地址。如果 host 或 port 分别为 '' 或 0,则使用操作系统默认行为。
在 3.2 版更改: 添加了*source_address* 参数
socket.
create_server
(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)
便捷函数,创建绑定到 address (二元组 (host, port)
)的 TCP 套接字,返回套接字对象。
family 应设置为 AF_INET 或 AF_INET6。backlog 是传递给 socket.listen() 的队列大小,当它为 0
则表示默认的合理值。reuse_port 表示是否设置 SO_REUSEPORT
套接字选项。
如果 dualstack_ipv6 为 true 且平台支持,则套接字能接受 IPv4 和 IPv6 连接,否则将抛出 ValueError 异常。大多数 POSIX 平台和 Windows 应该支持此功能。启用此功能后,socket.getpeername() 在进行 IPv4 连接时返回的地址将是一个(映射到 IPv4 的)IPv6 地址。在默认启用该功能的平台上(如 Linux),如果 dualstack_ipv6 为 false,即显式禁用此功能。该参数可以与 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
套接字选项是为了立即重用以前绑定在同一 address 上并保持 TIME_WAIT 状态的套接字。
3.8 新版功能.
socket.
has_dualstack_ipv6
()
如果平台支持创建 IPv4 和 IPv6 连接都可以处理的 TCP 套接字,则返回 True
。
3.8 新版功能.
socket.
fromfd
(fd, family, type, proto=0)
复制文件描述符 fd (一个由文件对象的 fileno()
方法返回的整数),然后从结果中构建一个套接字对象。地址簇、套接字类型和协议号与上述 socket()
函数相同。文件描述符应指向一个套接字,但不会专门去检查——如果文件描述符是无效的,则对该对象的后续操作可能会失败。本函数很少用到,但是在将套接字作为标准输入或输出传递给程序(如 Unix inet 守护程序启动的服务器)时,可以使用本函数获取或设置套接字选项。套接字将处于阻塞模式。
新创建的套接字是 不可继承的。
在 3.4 版更改: 返回的套接字现在是不可继承的。
socket.
fromshare
(data)
根据 socket.share() 方法获得的数据实例化套接字。套接字将处于阻塞模式。
可用性: Windows。
3.3 新版功能.
socket.
SocketType
这是一个 Python 类型对象,表示套接字对象的类型。它等同于 type(socket(...))
。
其他功能
socket 模块还提供多种网络相关服务:
socket.
close
(fd)
关闭一个套接字文件描述符。它类似于 os.close(),但专用于套接字。在某些平台上(特别是在 Windows 上),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
作为 host 和 port 的值,相当于将 NULL
传递给底层 C API。
可以指定 family、type 和 proto 参数,以缩小返回的地址列表。向这些参数分别传入 0 表示保留全部结果范围。flags 参数可以是 AI_*
常量中的一个或多个,它会影响结果的计算和返回。例如,AI_NUMERICHOST
会禁用域名解析,此时如果 host 是域名,则会抛出错误。
本函数返回一个列表,其中的 5 元组具有以下结构:
(family, type, proto, canonname, sockaddr)
在这些元组中,family, type, proto 都是整数且其作用是被传入 socket()
函数。 如果 AI_CANONNAME
是 flags 参数的一部分则 canonname 将是表示 host 规范名称的字符串;否则 canonname 将为空。 sockaddr 是一个描述套接字地址的元组,其具体格式取决于返回的 family (对于 AF_INET 为 (address, port)
2 元组,对于 AF_INET6 则为 (address, port, flowinfo, scope_id)
4 元组),其作用是被传入 socket.connect() 方法。
引发一个 审计事件 socket.getaddrinfo
附带参数 host
、port
、family
、type
、protocol
。
下面的示例获取了 TCP 连接地址信息,假设该连接通过 80 端口连接至 example.org
(如果系统未启用 IPv6,则结果可能会不同):
>>>
>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
[(<AddressFamily.AF_INET6: 10>, <AddressFamily.SOCK_STREAM: 1>,
6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
(<AddressFamily.AF_INET: 2>, <AddressFamily.SOCK_STREAM: 1>,
6, '', ('93.184.216.34', 80))]
在 3.2 版更改: 现在可以使用关键字参数的形式来传递参数。
在 3.7 版更改: 对于 IPv6 多播地址,表示地址的字符串将不包含 %scope_id
部分。
socket.
getfqdn
([name])
返回 name 的完整限定域名。 如果 name 被省略或为空,则将其解读为本地主机。 要查找完整限定名称,将先检查 gethostbyaddr() 所返回的主机名,然后是主机的别名(如果存在)。 包括句点的第一个名称将会被选择。 对于没有完整限定域名而提供了 name 的情况,则会将其原样返回。 如果 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
。
socket.
gethostbyname_ex
(hostname)
将一个主机名转换为 IPv4 地址格式的扩展接口。 返回一个三元组 (hostname, aliaslist, ipaddrlist)
其中 hostname 是主机的首选主机名,aliaslist 是同一地址的其他主机名的列表(可能为空),而 ipaddrlist 是同一主机上同一接口的 IPv4 地址列表(通常为单个地址但并不总是如此)。 gethostbyname_ex() 不支持 IPv6 名称解析,应当改用 getaddrinfo() 来提供 IPv4/v6 双栈支持。
引发一个 审计事件 socket.gethostbyname
,附带参数 hostname
。
socket.
gethostname
()
返回一个字符串,包含当前正在运行 Python 解释器的机器的主机名。
引发一个 审计事件 socket.gethostname
,没有附带参数。
注意: gethostname() 并不总是返回全限定域名,必要的话请使用 getfqdn()。
socket.
gethostbyaddr
(ip_address)
返回三元组 (hostname, aliaslist, ipaddrlist)
,其中 hostname 是响应给定 ip_address 的主要主机名,aliaslist 是相同地址的其他可用主机名的列表(可能为空),而 ipaddrlist 是 IPv4/v6 地址列表,包含相同主机名、相同接口的不同地址(很可能仅包含一个地址)。要查询全限定域名,请使用函数 getfqdn()。gethostbyaddr() 支持 IPv4 和 IPv6。
引发一个 审计事件 socket.gethostbyaddr
,附带参数 ip_address
。
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 地址,如果 sockaddr 包含有意义的 scope_id,则 %scope_id
会被附加到主机部分。 这种情况通常发生在多播地址上。
关于 flags 的更多信息可参阅 getnameinfo(3)。
引发一个 审计事件 socket.getnameinfo
,附带参数 sockaddr
。
socket.
getprotobyname
(protocolname)
将一个互联网协议名称 (如 'icmp'
) 转换为能被作为 (可选的) 第三个参数传给 socket()
函数的常量。 这通常仅对以 "raw" 模式 (SOCK_RAW) 打开的套接字来说是必要的;对于正常的套接字模式,当该协议名称被省略或为零时会自动选择正确的协议。
socket.
getservbyname
(servicename[, protocolname])
将一个互联网服务名称和协议名称转换为该服务的端口号。 如果给出了可选的协议名称,它应为 'tcp'
或 'udp'
,否则将匹配任意的协议。
引发一个 审计事件 socket.getservbyname
,附带参数 servicename
、protocolname
。
socket.
getservbyport
(port[, protocolname])
将一个互联网端口号和协议名称转换为该服务的服务名称。 如果给出了可选的协议名称,它应为 'tcp'
或 'udp'
,否则将匹配任意的协议。
引发一个 审计事件 socket.getservbyport
,附带参数 port
、protocolname
。
socket.
ntohl
(x)
将 32 位正整数从网络字节序转换为主机字节序。在主机字节序与网络字节序相同的计算机上,这是一个空操作。字节序不同将执行 4 字节交换操作。
socket.
ntohs
(x)
将 16 位正整数从网络字节序转换为主机字节序。在主机字节序与网络字节序相同的计算机上,这是一个空操作。字节序不同将执行 2 字节交换操作。
在 3.10 版更改: 如果 x 不能转为 16 位无符号整数则会引发 OverflowError。
socket.
htonl
(x)
将 32 位正整数从主机字节序转换为网络字节序。在主机字节序与网络字节序相同的计算机上,这是一个空操作。字节序不同将执行 4 字节交换操作。
socket.
htons
(x)
将 16 位正整数从主机字节序转换为网络字节序。在主机字节序与网络字节序相同的计算机上,这是一个空操作。字节序不同将执行 2 字节交换操作。
在 3.10 版更改: 如果 x 不能转为 16 位无符号整数则会引发 OverflowError。
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。注意,具体什么样的地址有效取决于 inet_aton()
的底层 C 实现。
inet_aton() 不支持 IPv6,在 IPv4/v6 双协议栈下应使用 inet_pton() 来代替。
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,在 IPv4/v6 双协议栈下应使用 inet_ntop() 来代替。
在 3.5 版更改: 现在接受可写的 字节类对象。
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()
的底层实现。
可用性: 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。如果字节对象 packed_ip 与指定的地址簇长度不符,则抛出 ValueError。针对 inet_ntop() 调用的错误则抛出 OSError。
可用性: Unix(可能非所有平台都可用)、Windows。
在 3.4 版更改: 添加了 Windows 支持
在 3.5 版更改: 现在接受可写的 字节类对象。