erlang setopts(Socket, Options)用法及代碼示例

為套接字設置一個或多個選項。

可以使用以下選項：

{active, true | false | once | N}

如果值為 true (默認值)，則從套接字接收到的所有內容都會作為消息發送到接收進程。

如果值為false(被動模式)，進程必須通過調用顯式接收傳入數據gen_tcp:recv/2,3,gen_udp:recv/2,3， 或者recv(Socket)(取決於插座的類型)。

如果值為 once ( {active, once} )，則來自套接字的一條數據消息將發送到進程。要再接收一條消息，必須使用選項 {active, once} 再次調用 setopts/2 。

如果該值為 -32768 到 32767(含)範圍內的整數 N，則該值將添加到套接字發送到控製進程的數據消息的計數中。套接字的默認消息計數是 0 。如果指定負值，並且其大小等於或大於套接字的當前消息計數，則套接字的消息計數將設置為 0 。一旦套接字的消息計數達到 0 ，無論是因為將收到的數據消息發送到進程還是通過顯式設置，都會通過一條特定於套接字類型的特殊消息通知進程，套接字已進入被動模式。一旦套接字進入被動模式，要接收更多消息，必須再次調用 setopts/2 將套接字設置回主動模式。

使用 {active, once} 或 {active, N} 時，套接字在收到數據時會自動更改行為。與 connection-oriented 套接字(即 gen_tcp )結合使用時，這可能會造成混淆，因為具有 {active, false} 行為的套接字報告的關閉方式與具有 {active, true} 行為的套接字不同。為了簡化編程，對等方關閉的套接字(在 {active, false} 模式下檢測到此情況)在設置為 {active, once} 、 {active, true} 或 {active, N} 模式時仍會生成消息 {tcp_closed,Socket}。因此，可以安全地假設當套接字在 {active, true} 和 {active, false} 模式之間來回更改時，最終會出現消息 {tcp_closed,Socket} ，可能隨後是套接字端口終止(取決於選項 exit_on_close )。然而，當檢測到對等關閉時，這完全取決於底層 TCP/IP 堆棧和協議。

請注意，{active, true} 模式不提供流量控製；快速的發送者可以很容易地讓接收者溢出傳入的消息。 {active, N} 模式也是如此，但消息計數大於零。

僅當您的高級協議提供自己的流量控製(例如，確認收到的消息)或交換的數據量較小時，才使用主動模式。 {active, false} 模式、使用 {active, once} 模式或 {active, N} 模式以及適合應用程序的 N 值提供流量控製。另一方的發送速度不能快於接收方的讀取速度。

{broadcast, Boolean} (UDP sockets)

啟用/禁用發送廣播的權限。

{buffer, Size}

驅動程序使用的user-level緩衝區的大小。不要與選項混淆sndbuf和recbuf，對應於內核套接字緩衝區。對於 TCP，建議val(buffer) >= val(recbuf)以避免由於不必要的複製而出現性能問題。對於 UDP，同樣的建議適用，但最大值不應大於網絡路徑的 MTU。val(buffer)時自動設置為上述最大值recbuf已設置。然而，由於尺寸設置為recbuf通常會變得更大，鼓勵您使用getopts/2分析您的操作係統的行為。

請注意，這也是可以從單個 recv 調用接收的最大數據量。如果您使用的 MTU 高於正常值，請考慮將緩衝區設置得更高。

{delay_send, Boolean}

通常，當 Erlang 進程發送到套接字時，驅動程序會嘗試立即發送數據。如果失敗，驅動程序將使用任何可用的方法將要發送的消息排隊，隻要操作係統表示它可以處理它。設置 {delay_send, true} 使所有消息排隊。發送到網絡的消息會更大但更少。該選項影響發送請求與 Erlang 進程的調度，而不是更改套接字的任何實際屬性。該選項是特定於實現的。默認為 false 。

{deliver, port | term}

當 {active, true} 時，數據以 port : {S, {data, [H1,..Hsz | Data]}} 或 term : {tcp, S, [H1..Hsz | Data]} 的形式傳遞。

{dontroute, Boolean}

啟用/禁用傳出消息的路由旁路。

{exit_on_close, Boolean}

默認情況下，此選項設置為true。

將其設置為的唯一原因false是如果您想在檢測到關閉後繼續向套接字發送數據，例如，如果對等方使用gen_tcp:shutdown/2關閉寫入端。

{exclusiveaddruse, Boolean}

在 Windows 上啟用/禁用獨占地址/端口使用。也就是說，通過啟用此選項，您可以防止其他套接字綁定到同一地址/端口。默認情況下此選項被禁用。也就是說，其他套接字可以通過設置使用相同的地址/端口{reuseaddr, true}結合{reuseport, true}除非{exclusiveaddruse, true}已設置為Socket。在非 Windows 係統上，此選項將被默默忽略。

{header, Size}

僅當創建套接字時指定了選項 binary 時，此選項才有意義。如果指定了選項 header，則從套接字接收的前 Size 數據字節是列表的元素，其餘數據是指定為同一列表尾部的二進製數據。例如，如果 Size == 2 ，則收到的數據與 [Byte1,Byte2|Binary] 匹配。

{high_msgq_watermark, Size}

當消息隊列上的數據量達到此限製時，套接字消息隊列將設置為繁忙狀態。請注意，此限製僅涉及尚未到達 ERTS 內部套接字實現的數據。默認為 8 kB。

如果套接字消息隊列繁忙或套接字本身繁忙，則向套接字發送數據的發送者將被掛起。

有關詳細信息，請參閱選項 low_msgq_watermark 、 high_watermark 和 low_watermark 。

請注意，分發套接字禁用high_msgq_watermark和low_msgq_watermark。相反，使用分配緩衝區繁忙限製，這是一個類似的特征。

{high_watermark, Size} (TCP/IP sockets)

當 ERTS 套接字實現內部排隊的數據量達到此限製時，套接字將設置為繁忙狀態。默認為 8 kB。

如果套接字消息隊列繁忙或套接字本身繁忙，則向套接字發送數據的發送者將被掛起。

有關詳細信息，請參閱選項 low_watermark 、 high_msgq_watermark 和 low_msqg_watermark 。

{ipv6_v6only, Boolean}

限製套接字僅使用 IPv6，禁止任何 IPv4 連接。這僅適用於 IPv6 套接字(選項 inet6 )。

在大多數平台上，必須先在套接字上設置此選項，然後才能將其關聯到地址。因此，隻有在創建套接字時指定它才合理，而在調用函數時不使用它(setopts/2)包含此說明。

將此選項設置為 true 的套接字的行為是唯一可移植的。 FreeBSD 不推薦 IPv6 剛出現時對所有流量使用 IPv6 的最初想法(您可以使用 {ipv6_v6only,false} 覆蓋推薦的係統默認值)，OpenBSD(支持的 GENERIC 內核)禁止，並且在 Windows 上不可能(它具有獨立的 IPv4 和 IPv6 協議棧)。大多數 Linux 發行版仍然具有係統默認值 false 。操作係統之間將 IPv6 與 IPv4 流量分開的政策轉變已經演變，因為事實證明正確且安全地實現雙棧是困難且複雜的。

在某些平台上，此選項唯一允許的值為 true ，例如 OpenBSD 和 Windows。在這種情況下，在創建套接字時嘗試將此選項設置為 false 會失敗。

在不存在此選項的平台上設置此選項將被忽略。獲取此選項getopts/2無返回值，即返回的列表不包含{ipv6_v6only,_}元組。在 Windows 上，該選項不存在，但它被模擬為具有值的隻讀選項true.

因此，在創建套接字時將此選項設置為 true 永遠不會失敗，除非在您已將內核自定義為僅允許 false 的平台上，這在例如 OpenBSD 上是可行的(但很尷尬)。

如果您使用讀回選項值getopts/2並且沒有得到任何值，則該選項在主機操作係統中不存在。 IPv6 和 IPv4 套接字在同一端口上偵聽的行為以及 IPv6 套接字獲取 IPv4 流量的行為將不再可預測。

{keepalive, Boolean}(TCP/IP sockets)

當沒有交換其他數據時，啟用/禁用已連接套接字上的定期傳輸。如果另一端沒有響應，則認為連接已斷開，並向控製進程發送錯誤消息。默認為 false 。

{linger, {true|false, Seconds}}

確定 time-out(以秒為單位)，用於刷新 close/1 套接字調用中未發送的數據。

第一個組件是是否啟用了 linger，第二個組件是刷新 time-out，以秒為單位。有3種選擇：

{false, _}

close/1 或 shutdown/2 立即返回，不等待數據刷新，關閉在後台發生。

{true, 0}

關閉時中止連接。丟棄發送緩衝區中仍保留的任何數據並將 RST 發送到對等方。

這避免了 TCP 的 TIME_WAIT 狀態，但留下了創建此連接的另一個 "incarnation" 的可能性。

{true, Time} when Time > 0

close/1 或 shutdown/2 不會返回，直到套接字的所有排隊消息均已成功發送或達到延遲超時 (Time)。

{low_msgq_watermark, Size}

如果套接字消息隊列處於繁忙狀態，則當消息隊列中排隊的數據量低於此限製時，套接字消息隊列將設置為不繁忙狀態。請注意，此限製僅涉及尚未到達 ERTS 內部套接字實現的數據。默認為 4 kB。

當套接字消息隊列和套接字不忙時，由於消息隊列繁忙或套接字繁忙而掛起的發送方將恢複。

有關詳細信息，請參閱選項 high_msgq_watermark 、 high_watermark 和 low_watermark 。

請注意，分發套接字禁用high_msgq_watermark和low_msgq_watermark。相反，他們使用分配緩衝區繁忙限製，這是一個類似的特征。

{low_watermark, Size} (TCP/IP sockets)

如果套接字處於繁忙狀態，則當 ERTS 套接字實現內部排隊的數據量低於此限製時，套接字將設置為不繁忙狀態。默認為 4 kB。

因消息隊列繁忙或套接字繁忙而掛起的發送方會在套接字消息隊列和套接字不繁忙時恢複。

有關詳細信息，請參閱選項 high_watermark 、 high_msgq_watermark 和 low_msgq_watermark 。

{mode, Mode :: binary | list}

收到的 Packet 按照 Mode 的定義進行傳遞。

{netns, Namespace :: file:filename_all()}

設置套接字的網絡命名空間。範圍Namespace是定義命名空間的文件名，例如，"/var/run/netns/example"，通常由命令創建ip netns add example。該選項必須在創建套接字的函數調用中使用，即connect(Address, Port, Opts),gen_tcp:listen/2,open(Port)或者open()， 並且getifaddrs/1.

此選項使用 Linux 特定的係統調用 setns() ，例如在 Linux 內核 3.0 或更高版本中，因此僅在為此類操作係統編譯運行時係統時才存在。

虛擬機還需要提升權限，或者以超級用戶身份運行，或者(對於 Linux)根據 setns(2) 的文檔具有 CAP_SYS_ADMIN 函數。然而，在測試過程中，CAP_SYS_PTRACE 和 CAP_DAC_READ_SEARCH 也被證明是必要的。

例子：

setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp

請注意，包含虛擬機可執行文件(示例中的 beam.smp)的文件係統必須是本地的、不帶標誌 nosetuid 掛載的、支持擴展屬性，並且內核必須支持文件函數。所有這些至少在 Ubuntu 12.04 LTS 上都可以開箱即用，隻是 SCTP 套接字似乎不支持網絡命名空間。

Namespace是一個文件名，按照模塊中的討論進行編碼和解碼文件，但以下情況除外：

• 仿真器標誌 +fnu 被忽略。

• getopts/2如果無法解碼存儲的文件名，此選項將返回文件名的二進製文件。僅當您使用無法使用模擬器的文件名編碼進行解碼的二進製文件設置該選項時，才會發生這種情況：file:native_name_encoding/0.

{bind_to_device, Ifname :: binary()}

將套接字綁定到特定的網絡接口。該選項必須在創建套接字的函數調用中使用，即connect(Address, Port, Opts),gen_tcp:listen/2,open(Port)， 或者open().

不像getifaddrs/0, Ifname 被編碼為二進製。在極少數情況下，係統在網絡設備名稱中使用非 7-bit-ASCII 字符，對此參數進行編碼時必須特別小心。

此選項使用 Linux 特定的套接字選項 SO_BINDTODEVICE ，例如在 Linux 內核 2.0.30 或更高版本中，因此僅在為此類操作係統編譯運行時係統時才存在。

在 Linux 3.8 之前，可以設置此套接字選項，但無法使用getopts/2。從Linux 3.8開始，它是可讀的。

虛擬機還需要提升的權限，或者以超級用戶身份運行，或者(對於 Linux)具有 CAP_NET_RAW 函數。

此選項的主要用例是將套接字綁定到Linux VRF 實例.

list

收到的 Packet 以列表形式傳送。

binary

收到的 Packet 以二進製形式交付。

{nodelay, Boolean}(TCP/IP sockets)

如果Boolean == true，則為套接字打開選項TCP_NODELAY，這意味著也會立即發送少量數據。

domain = local 不支持此選項，但如果是inet_backend =/= socket，此錯誤將被忽略。

{nopush, Boolean}(TCP/IP sockets)

這在 BSD 上轉換為 TCP_NOPUSH，在 Linux 上轉換為 TCP_CORK。

如果 Boolean == true ，則為套接字打開相應的選項，這意味著會累積少量數據，直到完整的 MSS-worth 數據可用或關閉此選項。

請注意，雖然 TCP_NOPUSH 套接字選項在 OSX 上可用，但其語義非常不同(例如，取消設置它不會導致立即發送累積數據)。因此，nopush 選項在 OSX 上被有意忽略。

{packet, PacketType}(TCP/IP sockets)

定義用於套接字的數據包類型。可能的值：

raw | 0

沒有進行任何包裝。

1 | 2 | 4

數據包包含一個標頭，指定數據包中的字節數，後跟該字節數。標頭長度可以是 1、2 或 4 個字節，並包含一個采用大端字節順序的無符號整數。每個發送操作都會生成標頭，並且標頭會在每次接收操作時被剝離。

4 字節標頭限製為 2Gb。

asn1 | cdr | sunrm | fcgi | tpkt | line

這些數據包類型僅對接收有影響。發送數據包時，應用程序有責任提供正確的標頭。然而，在接收時，對於收到的每個完整數據包，都會向控製進程發送一條消息，並且類似地，每次調用 gen_tcp:recv/2,3 都會返回一個完整的數據包。標頭沒有被剝離。

報文類型的含義如下：

• asn1 - ASN.1 BER
• sunrm - Sun 的 RPC 編碼
• cdr - CORBA (GIOP 1.1)
• fcgi - 快速 CGI
• tpkt - TPKT 格式 [RFC1006]
• line - 行模式，數據包是帶有換行符的line-terminated，長於接收緩衝區的行將被截斷

http | http_bin

超文本傳輸協議。返回的數據包格式如下HttpPacket說明於decode_packet(Type, Bin, Options)在 ERTS 中。被動模式下的套接字返回{ok, HttpPacket}從gen_tcp:recv當活動套接字發送消息時，例如{http, Socket, HttpPacket}.

httph | httph_bin

通常不需要這兩種類型，因為在讀取第一行後，套接字會在內部自動從http /http_bin 切換到httph /httph_bin。但是，在某些情況下它們可能很有用，例如從分塊編碼中解析預告片。

{packet_size, Integer}(TCP/IP sockets)

設置數據包正文允許的最大長度。如果報文頭指示報文的長度大於允許的最大長度，則認為該報文無效。如果數據包標頭對於套接字接收緩衝區來說太大，也會發生同樣的情況。

對於 line-oriented 協議( line 、 http* )，選項 packet_size 還保證接受指定長度的行，並且不會因為內部緩衝區限製而被視為無效。

{line_delimiter, Char}(TCP/IP sockets)

設置 line-oriented 協議 ( line ) 的行定界字符。默認為 $\n 。

{raw, Protocol, OptionNum, ValueBin}

見下文。

{read_packets, Integer}(UDP sockets)

設置數據可用時無需套接字幹預即可讀取的 UDP 數據包的最大數量。當這麽多數據包已被讀取並傳遞到目標進程時，在新的可用數據通知到達之前不會讀取新數據包。默認為 5 。如果此參數設置得太高，係統可能會因 UDP 數據包泛洪而變得無響應。

{recbuf, Size}

用於套接字的接收緩衝區的最小大小。鼓勵您使用getopts/2檢索操作係統設置的大小。

{recvtclass, Boolean}

如果設置為 true，則會激活在為套接字實現協議 IPPROTO_IPV6 選項 IPV6_RECVTCLASS 或 IPV6_2292RECVTCLASS 的平台上返回接收到的 TCLASS 值。無論平台返回 IPV6_TCLASS 還是 IPV6_RECVTCLASS CMSG 值，該值都會作為 {tclass,TCLASS} 元組返回。

對於麵向數據包的套接字，支持接收帶有有效負載數據的輔助數據(gen_udp和gen_sctp)， 這TCLASS值在包含在一個擴展返回元組中返回輔助數據列表。對於麵向流的套接字(gen_tcp)獲得的唯一方法TCLASS值是平台是否支持 pktoptions 選項。

{recvtos, Boolean}

如果設置為 true，則會激活在為套接字實現協議 IPPROTO_IP 選項 IP_RECVTOS 的平台上返回接收到的 TOS 值。無論平台返回 IP_TOS 還是 IP_RECVTOS CMSG 值，該值都會以 {tos,TOS} 元組形式返回。

對於麵向數據包的套接字，支持接收帶有有效負載數據的輔助數據(gen_udp和gen_sctp)， 這TOS值在包含在一個擴展返回元組中返回輔助數據列表。對於麵向流的套接字(gen_tcp)獲得的唯一方法TOS值是平台是否支持 pktoptions 選項。

{recvttl, Boolean}

如果設置為 true，則會激活在為套接字實現協議 IPPROTO_IP 選項 IP_RECVTTL 的平台上返回接收到的 TTL 值。無論平台返回 IP_TTL 還是 IP_RECVTTL CMSG 值，該值都會以 {ttl,TTL} 元組形式返回。

對於麵向數據包的套接字，支持接收帶有有效負載數據的輔助數據(gen_udp和gen_sctp)， 這TTL值在包含在一個擴展返回元組中返回輔助數據列表。對於麵向流的套接字(gen_tcp)獲得的唯一方法TTL值是平台是否支持 pktoptions 選項。

{reuseaddr, Boolean}

允許或禁止重複使用本地地址。默認情況下，不允許重複使用。

注意

在窗戶上{reuseaddr, true}不會有任何影響，除非也{reuseport, true}已設置。如果兩者都設置了，則SO_REUSEADDRWindows 套接字選項將被啟用。這自從設定SO_REUSEADDR在 Windows 上或多或少與設置兩者具有相同的行為SO_REUSEADDR和SO_REUSEPORT在 BSD 上。此行為是從 OTP 26.0 開始引入的。

改變

以前在 Windows 上的行為：

• 在 OTP 25.0 之前，{reuseaddr, true} 選項被默默忽略。
• 在 OTP 25.0 和 OTP 25.2 的前身之間，如果設置了 {reuseaddr, true}，則設置了底層 SO_REUSEADDR 套接字選項。
• 在 OTP 25.2 和 OTP 26.0 的前身之間，如果設置了 {reuseaddr, true}，則僅在 UDP 套接字上設置底層 SO_REUSEADDR 套接字選項，並在其他套接字上默默忽略。

另請參閱exclusiveaddruse選項。

{reuseport, Boolean}

允許或禁止重複使用本地端口可以不可以根據底層操作係統進行負載平衡。默認情況下，不允許重複使用。也可以看看reuseport_lb.

注意

在窗戶上{reuseport, true}不會有任何影響，除非也{reuseaddr, true}已設置。如果兩者都設置了，則SO_REUSEADDRWindows 套接字選項將被啟用。這自從設定SO_REUSEADDR在 Windows 上或多或少與設置兩者具有相同的行為SO_REUSEADDR和SO_REUSEPORT在 BSD 上。這reuseport從 OTP 26.0 開始引入該選項。

另請參閱exclusiveaddruse選項。

注意

reuseport 可以不可以與標的期權相同reuseport_lb取決於底層操作係統。例如，它們在 Linux 上。當它們是相同的基礎選項時，對兩者進行操作可能會導致它們以令人驚訝的方式相互作用。例如，通過啟用reuseport然後禁用reuseport_lb兩者最終都會被禁用。

{reuseport_lb, Boolean}

允許或禁止重複使用本地端口和負載均衡。默認情況下，不允許重複使用。也可以看看reuseport.

注意

reuseport_lb 可以不可以與標的期權相同reuseport取決於底層操作係統。例如，它們在 Linux 上。當它們是相同的基礎選項時，對兩者進行操作可能會導致它們以令人驚訝的方式相互作用。例如，通過啟用reuseport_lb然後禁用reuseport兩者最終都會被禁用。

{send_timeout, Integer}

僅允許用於connection-oriented 套接字。

指定等待底層 TCP 堆棧接受發送操作的最長時間。當超出限製時，發送操作返回{error,timeout}。發送的數據包有多少是未知的；因此，隻要發生time-out，套接字就會被關閉(參見下麵的send_timeout_close)。默認為 infinity 。

{send_timeout_close, Boolean}

僅允許用於connection-oriented 套接字。

與 send_timeout 一起使用，指定當發送操作返回 {error,timeout} 時是否自動關閉套接字。推薦設置為 true ，它會自動關閉套接字。由於向後兼容性，默認為false。

{show_econnreset, Boolean} (TCP/IP sockets)

當該選項設置為false默認情況下，從 TCP 對等方收到的 RST 被視為正常關閉(就像發送了 FIN)。調用者gen_tcp:recv/2得到{error, closed}。在主動模式下，控製進程接收{tcp_closed, Socket}消息，表明對端已關閉連接。

將此選項設置為true允許您區分正常關閉的連接和 TCP 對等方(有意或無意)中止的連接。調用gen_tcp:recv/2返回{error, econnreset}。在主動模式下，控製進程接收{tcp_error, Socket, econnreset}在平常之前發消息{tcp_closed, Socket}，與任何其他套接字錯誤的情況一樣。調用gen_tcp:send/2也返回{error, econnreset}當檢測到 TCP 對等方已發送 RST 時。

從返回的已連接套接字accept(ListenSocket)繼承了show_econnreset從監聽套接字設置。

{sndbuf, Size}

用於套接字的發送緩衝區的最小大小。鼓勵您使用getopts/2，檢索操作係統設置的大小。

{priority, Integer}

在實現此函數的平台上設置 SO_PRIORITY 套接字級別選項。不同係統的行為和允許範圍有所不同。在未實現該選項的平台上，該選項將被忽略。謹慎使用。

{tos, Integer}

在實現此函數的平台上設置IP_TOS IP 級別選項。不同係統的行為和允許範圍有所不同。在未實現該選項的平台上，該選項將被忽略。謹慎使用。

{tclass, Integer}

在實現此函數的平台上設置IPV6_TCLASS IP 級別選項。不同係統的行為和允許範圍有所不同。在未實現該選項的平台上，該選項將被忽略。謹慎使用。

除了這些選項之外，還可以使用原始選項規範。原始選項被指定為四元組，以標記 raw 開頭，後跟協議級別、選項號和指定為二進製的選項值。這對應於 C 套接字 API 中 setsockopt 調用的第二個、第三個和第四個參數。選項值必須以平台的本機字節序進行編碼，並且如果需要結構，則必須遵循特定平台上的結構對齊約定。

使用原始套接字選項需要詳細了解當前操作係統和 TCP 堆棧。

例子：

此示例涉及原始選項的使用。考慮一個 Linux 係統，您希望在堆棧中的協議級別 IPPROTO_TCP 上設置選項 TCP_LINGER2。您知道在這個特定的係統上它默認為 60(秒)，但您希望針對特定套接字將其降低到 30。 inet 未明確支持選項 TCP_LINGER2，但您知道協議級別轉換為數字 6，選項編號轉換為數字 8，並且該值將指定為 32 位整數。您可以使用此代碼行為名為 Sock 的套接字設置選項：

inet:setopts(Sock,[{raw,6,8,<<30:32/native>>}]),

因為如果指定的選項超出範圍，堆棧會默默地丟棄許多選項；檢查原始選項是否被接受可能是個好主意。以下代碼將值放入變量TcpLinger2:中

{ok,[{raw,6,8,<<TcpLinger2:32/native>>}]}=inet:getopts(Sock,[{raw,6,8,4}]),

諸如這些示例之類的代碼本質上是不可移植的，即使同一平台上同一操作係統的不同版本也可能對這種選項操作做出不同的響應。小心使用。

請注意，TCP/IP 套接字的默認選項可以使用本手冊頁開頭提到的內核配置參數進行更改。