TCP/IP 通訊協定 Socket 的介面。

此模組提供透過 TCP/IP 通訊協定 Socket 進行通訊的函式。

以下程式碼片段是一個簡單的範例，說明客戶端如何連線至埠號 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.

如需更多範例，請參閱範例章節。

注意

建立 Socket 的函式可以採用一個可選的選項：{inet_backend, Backend}，如果指定，它必須是第一個選項。這會選擇平台 Socket 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 可能會隱藏錯誤

  此呼叫不涉及接收處理序狀態，並且直接在底層 Socket 上完成。例如在 Linux 上，已知有一個錯誤行為是它會跳過某些檢查，因此在監聽 Socket 上執行關閉會傳回 ok，但邏輯結果應該是 {error, enotconn}。inet_drv.c 驅動程式會執行額外的檢查並模擬正確的錯誤，但使用 Backend = socket 會引入額外的開銷來涉及接收處理序。

• nodelay 選項是一個 TCP 特定選項，不與 domain = local 相容。

  當使用 inet_backend = socket 時，嘗試使用 domain = local 建立 Socket (透過監聽或連線) (例如使用選項 {ifaddr, {local,"/tmp/test"}})，將會失敗並傳回 {error, enotsup}。

  實際上這也不適用於 inet_backend = inet，但在這種情況下，錯誤會被直接忽略，這是一個壞主意。我們選擇對於 inet_backend = socket 不忽略此錯誤。

• 非同步關閉寫入

  對使用 inet_backend = socket 建立的 Socket 呼叫 gen_tcp:shutdown(Socket, write | read_write) 將會立即生效，這與使用 inet_backend = inet 建立的 Socket 不同。

  請參閱非同步關閉寫入以取得更多資訊。

• Windows 需要繫結 Socket (domain = inet | inet6)。

  目前，所有在 Windows 上使用 inet_backend = socket 建立的 Socket 都會被繫結。如果使用者未提供位址，則 gen_tcp 會嘗試自行「找出」位址。

範例

以下範例說明如何使用選項 {active,once} 和多重接受，方法是實作一個伺服器，其方式為使用多個工作處理序在單一監聽 Socket 上執行 accept。函式 start/2 會取得工作處理序的數量和要監聽連入連線的埠號。如果 LPort 指定為 0，則會使用臨時埠號，這就是為什麼 start 函式會傳回已配置的實際埠號的原因

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 呼叫不接受逾時選項，因為傳送逾時是透過 Socket 選項 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 會派上用場。