TCP/IP 套接字的接口。

此模块提供通过 TCP/IP 协议套接字进行通信的函数。

以下代码片段是一个简单的客户端示例，它连接到端口 5678 上的服务器，传输二进制数据并关闭连接。

client() ->
    SomeHostInNet = "localhost", % to make it runnable on one machine
    {ok, Sock} = gen_tcp:connect(SomeHostInNet, 5678,
                                 [binary, {packet, 0}]),
    ok = gen_tcp:send(Sock, "Some Data"),
    ok = gen_tcp:close(Sock).

另一端，服务器正在端口 5678 上监听，接受连接并接收二进制数据。

server() ->
    {ok, LSock} = gen_tcp:listen(5678, [binary, {packet, 0},
                                        {active, false}]),
    {ok, Sock} = gen_tcp:accept(LSock),
    {ok, Bin} = do_recv(Sock, []),
    ok = gen_tcp:close(Sock),
    ok = gen_tcp:close(LSock),
    Bin.

do_recv(Sock, Bs) ->
    case gen_tcp:recv(Sock, 0) of
        {ok, B} ->
            do_recv(Sock, [Bs, B]);
        {error, closed} ->
            {ok, list_to_binary(Bs)}
    end.

有关更多示例，请参阅 示例 部分。

注意

创建套接字的函数可以接受一个可选的选项；{inet_backend, Backend}，如果指定，则必须是第一个选项。 这会选择平台套接字 API 的实现后端。

这是一个临时选项，将在未来的版本中被忽略。

默认值为 Backend = inet，它选择传统的 inet_drv.c 驱动程序。另一个选择是 Backend = socket，它选择新的 socket 模块及其 NIF 实现。

当节点使用应用程序 kernel 的配置变量 inet_backend 启动时，可以更改系统默认值。

对于 gen_tcp 与 inet_backend = socket，我们尝试尽可能地保持“兼容”，但这有时是不可能的。以下是 inet 后端 inet（默认）和 socket 的行为不同的情况列表：

• 非阻塞发送

  如果用户调用 gen_tcp:send/2 且 inet_backend = inet，尝试发送的数据量超过了操作系统缓冲区中的空间，则“剩余数据”会由 inet 驱动程序缓冲（稍后在后台发送）。用户看到的效果是调用是非阻塞的。

  当 inet_backend = socket 时，效果不是这样，因为没有缓冲。相反，用户会一直挂起，直到所有数据都已发送或达到 send_timeout 超时为止。

• shutdown/2 可能会隐藏错误

  该调用不涉及接收进程状态，直接在底层套接字上完成。例如，在 Linux 上，众所周知的一个错误行为是它会跳过一些检查，因此在监听套接字上执行关闭操作会返回 ok，而逻辑结果应该是 {error, enotconn}。 inet_drv.c 驱动程序执行了额外的检查并模拟了正确的错误，但是使用 Backend = socket 会引入涉及接收进程的开销。

• 选项 nodelay 是一个 TCP 特定选项，它与 domain = local 不兼容。

  当使用 inet_backend = socket 时，尝试创建具有 domain = local 的套接字（通过监听或连接）（例如使用选项 {ifaddr, {local,"/tmp/test"}}）将失败，并返回 {error, enotsup}。

  这对于 inet_backend = inet 实际上也不起作用，但在那种情况下，错误会被简单地忽略，这是一个坏主意。我们选择对于 inet_backend = socket 不忽略此错误。

• 异步关闭写入

  在以 inet_backend = socket 创建的套接字上调用 gen_tcp:shutdown(Socket, write | read_write) 将会立即生效，这与以 inet_backend = inet 创建的套接字不同。

  有关更多信息，请参阅 异步关闭写入。

• Windows 要求套接字（domain = inet | inet6）进行绑定。

  目前，在 Windows 上使用 inet_backend = socket 创建的所有套接字都将被绑定。如果用户未提供地址，则 gen_tcp 将尝试自行“计算出”地址。

示例

以下示例说明了如何使用选项 {active,once} 和多个接受操作，通过将服务器实现为多个工作进程，对单个侦听套接字执行接受操作。 函数 start/2 接受工作进程的数量和要侦听传入连接的端口号。如果 LPort 指定为 0，则使用临时端口号，这就是为什么启动函数返回实际分配的端口号的原因。

start(Num,LPort) ->
    case gen_tcp:listen(LPort,[{active, false},{packet,2}]) of
        {ok, ListenSock} ->
            start_servers(Num,ListenSock),
            {ok, Port} = inet:port(ListenSock),
            Port;
        {error,Reason} ->
            {error,Reason}
    end.

start_servers(0,_) ->
    ok;
start_servers(Num,LS) ->
    spawn(?MODULE,server,[LS]),
    start_servers(Num-1,LS).

server(LS) ->
    case gen_tcp:accept(LS) of
        {ok,S} ->
            loop(S),
            server(LS);
        Other ->
            io:format("accept returned ~w - goodbye!~n",[Other]),
            ok
    end.

loop(S) ->
    inet:setopts(S,[{active,once}]),
    receive
        {tcp,S,Data} ->
            Answer = process(Data), % Not implemented in this example
            gen_tcp:send(S,Answer),
            loop(S);
        {tcp_closed,S} ->
            io:format("Socket ~w closed [~w]~n",[S,self()]),
            ok
    end.

一个简单客户端的示例

client(PortNo,Message) ->
    {ok,Sock} = gen_tcp:connect("localhost",PortNo,[{active,false},
                                                    {packet,2}]),
    gen_tcp:send(Sock,Message),
    A = gen_tcp:recv(Sock,0),
    gen_tcp:close(Sock),
    A.

send 调用不接受超时选项，因为发送超时是通过套接字选项 send_timeout 处理的。在没有接收器的情况下，发送操作的行为主要由底层 TCP 堆栈和网络基础设施定义。 要编写代码来处理挂起的接收器，该接收器最终可能导致发送方在 send 上挂起，请执行以下操作。

考虑一个进程，该进程从客户端进程接收数据，以便转发到网络上的服务器。该进程通过 TCP/IP 连接到服务器，并且不接收对其发送的每个消息的任何确认，但必须依靠发送超时选项来检测另一端无响应。连接时可以使用选项 send_timeout。

...
{ok,Sock} = gen_tcp:connect(HostAddress, Port,
                            [{active,false},
                             {send_timeout, 5000},
                             {packet,2}]),
                loop(Sock), % See below
...

在处理请求的循环中，现在可以检测到发送超时

loop(Sock) ->
    receive
        {Client, send_data, Binary} ->
            case gen_tcp:send(Sock,[Binary]) of
                {error, timeout} ->
                    io:format("Send timeout, closing!~n",
                              []),
                    handle_send_timeout(), % Not implemented here
                    Client ! {self(),{error_sending, timeout}},
                    %% Usually, it's a good idea to give up in case of a
                    %% send timeout, as you never know how much actually
                    %% reached the server, maybe only a packet header?!
                    gen_tcp:close(Sock);
                {error, OtherSendError} ->
                    io:format("Some other error on socket (~p), closing",
                              [OtherSendError]),
                    Client ! {self(),{error_sending, OtherSendError}},
                    gen_tcp:close(Sock);
                ok ->
                    Client ! {self(), data_sent},
                    loop(Sock)
            end
    end.

通常，检测接收超时就足够了，因为大多数协议都包含来自服务器的某种确认，但是如果协议是严格单向的，则选项 send_timeout 会派上用场。