This document is for an old version of Python that is no longer supported. You should upgrade and read the Python 当前稳定版本的文档.

# 17.2. `socket` — 底层网络接口

This module provides access to the BSD socket interface. It is available on all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional platforms.

注解

一些行为可能因平台不同而异，因为调用的是操作系统的套接字API。

For an introduction to socket programming (in C), see the following papers: An Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et al, both in the UNIX Programmer’s Manual, Supplementary Documents 1 (sections PS1:7 and PS1:8). The platform-specific reference material for the various socket-related system calls are also a valuable source of information on the details of socket semantics. For Unix, refer to the manual pages; for Windows, see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may want to refer to RFC 3493 titled Basic Socket Interface Extensions for IPv6.

这个Python接口是用Python的面向对象风格对Unix系统调用和套接字库接口的直译：函数 `socket()` 返回一个 套接字对象 ，其方法是对各种套接字系统调用的实现。形参类型一般与C接口相比更高级：例如在Python文件 `read()` 和 `write()` 操作中，接收操作的缓冲区分配是自动的，发送操作的缓冲区长度是隐式的。

Socket addresses are represented as follows: A single string is used for the `AF_UNIX` address family. A pair `(host, port)` is used for the `AF_INET` address family, where host is a string representing either a hostname in Internet domain notation like `'daring.cwi.nl'` or an IPv4 address like `'100.50.200.5'`, and port is an integer. For `AF_INET6` address family, a four-tuple `(host, port, flowinfo, scopeid)` is used, where flowinfo and scopeid represents `sin6_flowinfo` and `sin6_scope_id` member in `struct sockaddr_in6` in C. For `socket` module methods, flowinfo and scopeid can be omitted just for backward compatibility. Note, however, omission of scopeid can cause problems in manipulating scoped IPv6 addresses. Other address families are currently not supported. The address format required by a particular socket object is automatically selected based on the address family specified when the socket object was created.

For IPv4 addresses, two special forms are accepted instead of a host address: the empty string represents `INADDR_ANY`, and the string `'<broadcast>'` represents `INADDR_BROADCAST`. The behavior is not available for IPv6 for backward compatibility, therefore, you may want to avoid these if you intend to support IPv6 with your Python programs.

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

2.5 新版功能: AF_NETLINK sockets are represented as pairs `pid, groups`.

2.6 新版功能: Linux-only support for TIPC is also available using the `AF_TIPC` address family. TIPC is an open, non-IP based networked protocol designed for use in clustered computer environments. Addresses are represented by a tuple, and the fields depend on the address type. The general tuple form is `(addr_type, v1, v2, v3 [, scope])`, where:

- 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。

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 the error `socket.error`.

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

The module `socket` exports the following constants and functions:

exception `socket.``error`

  This exception is raised for socket-related errors. The accompanying value is either a string telling what went wrong or a pair `(errno, string)` representing an error returned by a system call, similar to the value accompanying `os.error`. See the module `errno`, which contains names for the error codes defined by the underlying operating system.

  在 2.6 版更改: `socket.error` is now a child class of `IOError`.

exception `socket.``herror`

  This exception is raised for address-related errors, i.e. for functions that use h_errno in the C API, including `gethostbyname_ex()` and `gethostbyaddr()`.

  The accompanying value is a pair `(h_errno, string)` representing an error returned by a library call. string represents the description of h_errno, as returned by the `hstrerror()` C function.

exception `socket.``gaierror`

  This exception is raised for address-related errors, for `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 error value will match one of the `EAI_*` constants defined in this module.

exception `socket.``timeout`

  This exception is raised when a timeout occurs on a socket which has had timeouts enabled via a prior call to `settimeout()`. The accompanying value is a string whose value is currently always “timed out”.

  2.3 新版功能.

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

`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()`. (Only `SOCK_STREAM` and `SOCK_DGRAM` appear to be generally useful.)

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

  此列表内的许多常量，记载在 Unix 文档中的套接字和/或 IP 协议部分，同时也定义在本 socket 模块中。它们通常用于套接字对象的 `setsockopt()` 和 `getsockopt()` 方法的参数中。在大多数情况下，仅那些在 Unix 头文件中有定义的符号会在本模块中定义，部分符号提供了默认值。

`SIO_*`
`RCVALL_*`

  Windows 的 WSAIoctl() 的常量。这些常量用于套接字对象的 `ioctl()` 方法的参数。

  2.6 新版功能.

`TIPC_*`

  TIPC 相关常量，与 C socket API 导出的常量一致。更多信息请参阅 TIPC 文档。

  2.6 新版功能.

`socket.``has_ipv6`

  本常量为一个布尔值，该值指示当前平台是否支持 IPv6。

  2.3 新版功能.

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

  连接到一个 TCP 服务，该服务正在侦听 Internet address （用二元组 `(host, port)` 表示）。连接后返回套接字对象。这是比 `socket.connect()` 更高级的函数：如果 host 是非数字主机名，它将尝试从 `AF_INET` 和 `AF_INET6` 解析它，然后依次尝试连接到所有可能的地址，直到连接成功。这使得编写兼容 IPv4 和 IPv6 的客户端变得容易。

  传入可选参数 timeout 可以在套接字实例上设置超时（在尝试连接前）。如果未提供 timeout，则使用由 `getdefaulttimeout()` 返回的全局默认超时设置。

  如果提供了 source_address，它必须为二元组 `(host, port)`，以便套接字在连接之前绑定为其源地址。如果 host 或 port 分别为 ‘’ 或 0，则使用操作系统默认行为。

  2.6 新版功能.

  在 2.7 版更改: 添加了*source_address* 参数

`socket.``getaddrinfo`(host, port[, family[, socktype[, proto[, flags]]]])

  将 host/port 参数转换为 5 元组的序列，其中包含创建（连接到某服务的）套接字所需的所有参数。host 是域名，是字符串格式的 IPv4/v6 地址或 `None`。port 是字符串格式的服务名称，如 `'http'` 、端口号（数字）或 `None`。传入 `None` 作为 host 和 port 的值，相当于将 `NULL` 传递给底层 C API。

  The family, socktype and proto arguments can be optionally specified in order to narrow the list of addresses returned. By default, their value is `0`, meaning that the full range of results is selected. The flags argument can be one or several of the `AI_*` constants, and will influence how results are computed and returned. Its default value is `0`. For example, `AI_NUMERICHOST` will disable domain name resolution and will raise an error if host is a domain name.

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

  `(family, socktype, proto, canonname, sockaddr)`

  In these tuples, family, socktype, 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 (a `(address, port)` 2-tuple for `AF_INET`, a `(address, port, flow info, scope id)` 4-tuple for `AF_INET6`), and is meant to be passed to the `socket.connect()` method.

  下面的示例获取了 TCP 连接地址信息，假设该连接通过 80 端口连接至 `example.org` （如果系统未启用 IPv6，则结果可能会不同）：

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

  2.2 新版功能.

`socket.``getfqdn`([name])

  返回 name 的全限定域名 (Fully Qualified Domain Name – FQDN)。如果 name 省略或为空，则将其解释为本地主机。为了查找全限定名称，首先将检查由 `gethostbyaddr()` 返回的主机名，然后是主机的别名（如果存在）。选中第一个包含句点的名字。如果无法获取全限定域名，则返回由 `gethostname()` 返回的主机名。

  2.0 新版功能.

`socket.``gethostbyname`(hostname)

  将主机名转换为 IPv4 地址格式。IPv4 地址以字符串格式返回，如 `'100.50.200.5'`。如果主机名本身是 IPv4 地址，则原样返回。更完整的接口请参考 `gethostbyname_ex()`。`gethostbyname()` 不支持 IPv6 域名解析，应使用 `getaddrinfo()` 来支持 IPv4/v6 双协议栈。

`socket.``gethostbyname_ex`(hostname)

  将主机名转换为 IPv4 地址格式的扩展接口。返回三元组 `(hostname, aliaslist, ipaddrlist)`，其中 hostname 是响应给定 ip_address 的主要主机名，aliaslist 是相同地址的其他可用主机名的列表（可能为空），而 ipaddrlist 是 IPv4 地址列表，包含相同主机名、相同接口的不同地址（通常是一个地址，但不总是如此）。`gethostbyname_ex()` 不支持 IPv6 名称解析，应使用 `getaddrinfo()` 来支持 IPv4/v6 双协议栈。

`socket.``gethostname`()

  返回一个字符串，包含当前正在运行 Python 解释器的机器的主机名。

  If you want to know the current machine’s IP address, you may want to use `gethostbyname(gethostname())`. This operation assumes that there is a valid address-to-host mapping for the host, and the assumption does not always hold.

  Note: `gethostname()` doesn’t always return the fully qualified domain name; use `getfqdn()` (see above).

`socket.``gethostbyaddr`(ip_address)

  返回三元组 `(hostname, aliaslist, ipaddrlist)`，其中 hostname 是响应给定 ip_address 的主要主机名，aliaslist 是相同地址的其他可用主机名的列表（可能为空），而 ipaddrlist 是 IPv4/v6 地址列表，包含相同主机名、相同接口的不同地址（很可能仅包含一个地址）。要查询全限定域名，请使用函数 `getfqdn()`。`gethostbyaddr()` 支持 IPv4 和 IPv6。

`socket.``getnameinfo`(sockaddr, flags)

  将套接字地址 sockaddr 转换为二元组 `(host, port)`。host 的形式可能是全限定域名，或是由数字表示的地址，具体取决于 flags 的设置。同样，port 可以包含字符串格式的端口名称或数字格式的端口号。

  2.2 新版功能.

`socket.``getprotobyname`(protocolname)

  将 Internet 协议名称（如 `'icmp'` ）转换为常量，该常量适用于 `socket()` 函数的第三个（可选）参数。通常只有在 “raw” 模式 (`SOCK_RAW`) 中打开的套接字才需要使用该常量。对于正常的套接字模式，协议省略或为零时，会自动选择正确的协议。

`socket.``getservbyname`(servicename[, protocolname])

  将 Internet 服务名称和协议名称转换为该服务的端口号。协议名称是可选的，如果提供的话应为 `'tcp'` 或 `'udp'`，否则将匹配出所有协议。

`socket.``getservbyport`(port[, protocolname])

  将 Internet 端口号和协议名称转换为该服务的服务名称。协议名称是可选的，如果提供的话应为 `'tcp'` 或 `'udp'`，否则将匹配出所有协议。

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

  Create a new socket using the given address family, socket type and protocol number. The address family should be `AF_INET` (the default), `AF_INET6` or `AF_UNIX`. The socket type should be `SOCK_STREAM` (the default), `SOCK_DGRAM` or perhaps one of the other `SOCK_` constants. The protocol number is usually zero and may be omitted in that case.

`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`. Availability: Unix.

  2.4 新版功能.

`socket.``fromfd`(fd, family, type[, proto])

  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. Availability: Unix.

`socket.``ntohl`(x)

  将 32 位正整数从网络字节序转换为主机字节序。在主机字节序与网络字节序相同的计算机上，这是一个空操作。字节序不同将执行 4 字节交换操作。

`socket.``ntohs`(x)

  将 16 位正整数从网络字节序转换为主机字节序。在主机字节序与网络字节序相同的计算机上，这是一个空操作。字节序不同将执行 2 字节交换操作。

`socket.``htonl`(x)

  将 32 位正整数从主机字节序转换为网络字节序。在主机字节序与网络字节序相同的计算机上，这是一个空操作。字节序不同将执行 4 字节交换操作。

`socket.``htons`(x)

  将 16 位正整数从主机字节序转换为网络字节序。在主机字节序与网络字节序相同的计算机上，这是一个空操作。字节序不同将执行 2 字节交换操作。

`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 string four characters in length. This is useful when conversing with a program that uses the standard C library and needs objects of type `struct in_addr`, which is the C type for the 32-bit packed binary this function returns.

  `inet_aton()` 也接受句点数少于三的字符串，详情请参阅 Unix 手册 inet(3)。

  If the IPv4 address string passed to this function is invalid, `socket.error` will be raised. Note that exactly what is valid depends on the underlying C implementation of `inet_aton()`.

  `inet_aton()` 不支持 IPv6，在 IPv4/v6 双协议栈下应使用 `inet_pton()` 来代替。

`socket.``inet_ntoa`(packed_ip)

  Convert a 32-bit packed IPv4 address (a string four characters 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 `struct in_addr`, which is the C type for the 32-bit packed binary data this function takes as an argument.

  If the string passed to this function is not exactly 4 bytes in length, `socket.error` will be raised. `inet_ntoa()` does not support IPv6, and `inet_ntop()` should be used instead for IPv4/v6 dual stack support.

`socket.``inet_pton`(address_family, ip_string)

  将特定地址簇的 IP 地址（字符串）转换为压缩二进制格式。当库或网络协议需要接受 `struct in_addr` 类型的对象（类似 `inet_aton()` ）或 `struct in6_addr` 类型的对象时，`inet_pton()` 很有用。

  Supported values for address_family are currently `AF_INET` and `AF_INET6`. If the IP address string ip_string is invalid, `socket.error` will be raised. Note that exactly what is valid depends on both the value of address_family and the underlying implementation of `inet_pton()`.

  Availability: Unix (maybe not all platforms).

  2.3 新版功能.

`socket.``inet_ntop`(address_family, packed_ip)

  Convert a packed IP address (a string of some number of characters) 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 `struct in_addr` (similar to `inet_ntoa()`) or `struct in6_addr`.

  Supported values for address_family are currently `AF_INET` and `AF_INET6`. If the string packed_ip is not the correct length for the specified address family, `ValueError` will be raised. A `socket.error` is raised for errors from the call to `inet_ntop()`.

  Availability: Unix (maybe not all platforms).

  2.3 新版功能.

`socket.``getdefaulttimeout`()

  返回用于新套接字对象的默认超时（以秒为单位的浮点数）。值 `None` 表示新套接字对象没有超时。首次导入 socket 模块时，默认值为 `None`。

  2.3 新版功能.

`socket.``setdefaulttimeout`(timeout)

  Set the default timeout in seconds (float) for new socket objects. A value of `None` indicates that new socket objects have no timeout. When the socket module is first imported, the default is `None`.

  2.3 新版功能.

`socket.``SocketType`

  这是一个 Python 类型对象，表示套接字对象的类型。它等同于 `type(socket(...))`。

参见

Module `SocketServer`

  用于简化网络服务端编写的类。

模块 `ssl`

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

## 17.2.1. 套接字对象

Socket objects have the following methods. Except for `makefile()` these correspond to Unix system calls applicable to sockets.

`socket.``accept`()

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

`socket.``bind`(address)

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

  注解

  This method has historically accepted a pair of parameters for `AF_INET` addresses instead of only a tuple. This was never intentional and is no longer available in Python 2.0 and later.

`socket.``close`()

  Close the socket. All future operations on the socket object will fail. The remote end will receive no more data (after queued data is flushed). Sockets are automatically closed when they are garbage-collected.

  注解

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

`socket.``connect`(address)

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

  注解

  This method has historically accepted a pair of parameters for `AF_INET` addresses instead of only a tuple. This was never intentional and is no longer available in Python 2.0 and later.

`socket.``connect_ex`(address)

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

  注解

  This method has historically accepted a pair of parameters for `AF_INET` addresses instead of only a tuple. This was never intentional and is no longer available in Python 2.0 and later.

`socket.``fileno`()

  Return the socket’s file descriptor (a small integer). This is useful with `select.select()`.

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

`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 string. 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 strings).

`socket.``ioctl`(control, option)
  Platform

    Windows

  The `ioctl()` method is a limited interface to the WSAIoctl system interface. Please refer to the Win32 documentation for more information.

  On other platforms, the generic `fcntl.fcntl()` and `fcntl.ioctl()` functions may be used; they accept a socket object as their first argument.

  2.6 新版功能.

`socket.``listen`(backlog)

  Listen for connections made to the socket. The backlog argument specifies the maximum number of queued connections and should be at least 0; the maximum value is system-dependent (usually 5), the minimum value is forced to 0.

`socket.``makefile`([mode[, bufsize]])

  Return a file object associated with the socket. (File objects are described in File Objects.) The file object does not close the socket explicitly when its `close()` method is called, but only removes its reference to the socket object, so that the socket will be closed if it is not referenced from anywhere else.

  The socket must be in blocking mode (it can not have a timeout). The optional mode and bufsize arguments are interpreted the same way as by the built-in `file()` function.

  注解

  On Windows, the file-like object created by `makefile()` cannot be used where a file object with a file descriptor is expected, such as the stream arguments of `subprocess.Popen()`.

`socket.``recv`(bufsize[, flags])

  Receive data from the socket. The return value is a string representing the data received. The maximum amount of data to be received at once is specified by bufsize. See the Unix manual page recv(2) for the meaning of the optional argument flags; it defaults to zero.

  注解

  For best match with hardware and network realities, the value of bufsize should be a relatively small power of 2, for example, 4096.

`socket.``recvfrom`(bufsize[, flags])

  Receive data from the socket. The return value is a pair `(string, address)` where string is a string representing the data received and address is the address of the socket sending the data. See the Unix manual page recv(2) for the meaning of the optional argument flags; it defaults to zero. (The format of address depends on the address family — see above.)

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

  Receive data from the socket, writing it into buffer instead of creating a new string. The return value is a pair `(nbytes, address)` where nbytes is the number of bytes received and address is the address of the socket sending the data. See the Unix manual page recv(2) for the meaning of the optional argument flags; it defaults to zero. (The format of address depends on the address family — see above.)

  2.5 新版功能.

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

  Receive up to nbytes bytes from the socket, storing the data into a buffer rather than creating a new string. If nbytes is not specified (or 0), receive up to the size available in the given buffer. Returns the number of bytes received. See the Unix manual page recv(2) for the meaning of the optional argument flags; it defaults to zero.

  2.5 新版功能.

`socket.``send`(string[, flags])

  Send data to the socket. The socket must be connected to a remote socket. The optional flags argument has the same meaning as for `recv()` above. Returns the number of bytes sent. Applications are responsible for checking that all data has been sent; if only some of the data was transmitted, the application needs to attempt delivery of the remaining data. For further information on this concept, consult the 套接字编程指南.

`socket.``sendall`(string[, flags])

  Send data to the socket. The socket must be connected to a remote socket. The optional flags argument has the same meaning as for `recv()` above. Unlike `send()`, this method continues to send data from string until either all data has been sent or an error occurs. `None` is returned on success. On error, an exception is raised, and there is no way to determine how much data, if any, was successfully sent.

`socket.``sendto`(string, address)
`socket.``sendto`(string, flags, address)

  Send data to the socket. The socket should not be connected to a remote socket, since the destination socket is specified by address. The optional flags argument has the same meaning as for `recv()` above. Return the number of bytes sent. (The format of address depends on the address family — see above.)

`socket.``setblocking`(flag)

  Set blocking or non-blocking mode of the socket: if flag is 0, the socket is set to non-blocking, else to blocking mode. Initially all sockets are in blocking mode. In non-blocking mode, if a `recv()` call doesn’t find any data, or if a `send()` call can’t immediately dispose of the data, an `error` exception is raised; in blocking mode, the calls block until they can proceed. `s.setblocking(0)` is equivalent to `s.settimeout(0.0)`; `s.setblocking(1)` is equivalent to `s.settimeout(None)`.

`socket.``settimeout`(value)

  Set a timeout on blocking socket operations. The value argument can be a nonnegative float expressing seconds, or `None`. If a float is given, subsequent socket operations will raise a `timeout` exception if the timeout period value has elapsed before the operation has completed. Setting a timeout of `None` disables timeouts on socket operations. `s.settimeout(0.0)` is equivalent to `s.setblocking(0)`; `s.settimeout(None)` is equivalent to `s.setblocking(1)`.

  2.3 新版功能.

`socket.``gettimeout`()

  Return the timeout in seconds (float) associated with socket operations, or `None` if no timeout is set. This reflects the last call to `setblocking()` or `settimeout()`.

  2.3 新版功能.

Some notes on socket blocking and timeouts: A socket object can be in one of three modes: blocking, non-blocking, or timeout. Sockets are always created in blocking mode. In blocking mode, operations block until complete or the system returns an error (such as connection timed out). In non-blocking mode, operations fail (with an error that is unfortunately system-dependent) if they cannot be completed immediately. In timeout mode, operations fail if they cannot be completed within the timeout specified for the socket or if the system returns an error. The `setblocking()` method is simply a shorthand for certain `settimeout()` calls.

Timeout mode internally sets the socket in non-blocking mode. The blocking and timeout modes are shared between file descriptors and socket objects that refer to the same network endpoint. A consequence of this is that file objects returned by the `makefile()` method must only be used when the socket is in blocking mode; in timeout or non-blocking mode file operations that cannot be completed immediately will fail.

Note that the `connect()` operation is subject to the timeout setting, and in general it is recommended to call `settimeout()` before calling `connect()` or pass a timeout parameter to `create_connection()`. The system network stack may return a connection timeout error of its own regardless of any Python socket timeout setting.

`socket.``setsockopt`(level, optname, value)

  Set the value of the given socket option (see the Unix manual page setsockopt(2)). The needed symbolic constants are defined in the `socket` module (`SO_*` etc.). The value can be an integer or a string representing a buffer. In the latter case it is up to the caller to ensure that the string contains the proper bits (see the optional built-in module `struct` for a way to encode C structures as strings).

`socket.``shutdown`(how)

  Shut down one or both halves of the connection. If how is `SHUT_RD`, further receives are disallowed. If how is `SHUT_WR`, further sends are disallowed. If how is `SHUT_RDWR`, further sends and receives are disallowed. Depending on the platform, shutting down one half of the connection can also close the opposite half (e.g. on Mac OS X, `shutdown(SHUT_WR)` does not allow further reads on the other end of the connection).

Note that there are no methods `read()` or `write()`; use `recv()` and `send()` without flags argument instead.

Socket objects also have these (read-only) attributes that correspond to the values given to the `socket` constructor.

`socket.``family`

  The socket family.

  2.5 新版功能.

`socket.``type`

  The socket type.

  2.5 新版功能.

`socket.``proto`

  The socket protocol.

  2.5 新版功能.

## 17.2.2. 示例

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

The first two examples support IPv4 only.

    # Echo server program
    import socket

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

    # Echo client program
    import socket

    HOST = 'daring.cwi.nl'    # The remote host
    PORT = 50007              # The same port as used by the server
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    s.connect((HOST, PORT))
    s.sendall('Hello, world')
    data = s.recv(1024)
    s.close()
    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 the all 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 socket.error as msg:
            s = None
            continue
        try:
            s.bind(sa)
            s.listen(1)
        except socket.error as msg:
            s.close()
            s = None
            continue
        break
    if s is None:
        print 'could not open socket'
        sys.exit(1)
    conn, addr = s.accept()
    print 'Connected by', addr
    while 1:
        data = conn.recv(1024)
        if not data: break
        conn.send(data)
    conn.close()

    # 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 socket.error as msg:
            s = None
            continue
        try:
            s.connect(sa)
        except socket.error as msg:
            s.close()
            s = None
            continue
        break
    if s is None:
        print 'could not open socket'
        sys.exit(1)
    s.sendall('Hello, world')
    data = s.recv(1024)
    s.close()
    print 'Received', repr(data)

The last example shows how to write a very simple network sniffer with raw sockets on Windows. The example requires administrator privileges to modify the interface:

    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)

Running an example several times with too small delay between executions, could lead to this error:

    socket.error: [Errno 98] Address already in use

This is because the previous execution has left the socket in a `TIME_WAIT` state, and can’t be immediately reused.

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

the `SO_REUSEADDR` flag tells the kernel to reuse a local socket in `TIME_WAIT` state, without waiting for its natural timeout to expire.