diff options
Diffstat (limited to 'erts/doc/src')
| -rw-r--r-- | erts/doc/src/Makefile | 7 | ||||
| -rw-r--r-- | erts/doc/src/alt_dist.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl.xml | 11 | ||||
| -rw-r--r-- | erts/doc/src/erl_dist_protocol.xml | 116 | ||||
| -rw-r--r-- | erts/doc/src/erl_ext_dist.xml | 18 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 188 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 95 | ||||
| -rw-r--r-- | erts/doc/src/erts_alloc.xml | 11 | ||||
| -rw-r--r-- | erts/doc/src/net.xml | 129 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/part.xml | 1 | ||||
| -rw-r--r-- | erts/doc/src/ref_man.xml | 34 | ||||
| -rw-r--r-- | erts/doc/src/socket.xml | 650 | ||||
| -rw-r--r-- | erts/doc/src/socket_usage.xml | 773 | ||||
| -rw-r--r-- | erts/doc/src/specs.xml | 2 |
15 files changed, 1964 insertions, 75 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index 40f74b78ff..06a8691c0e 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -55,7 +55,9 @@ XML_REF3_EFILES = \ persistent_term.xml \ atomics.xml \ counters.xml \ - zlib.xml + zlib.xml \ + socket.xml \ + net.xml XML_REF3_FILES = \ $(XML_REF3_EFILES) \ @@ -77,6 +79,7 @@ XML_CHAPTER_FILES = \ driver.xml \ absform.xml \ inet_cfg.xml \ + socket_usage.xml \ erl_ext_dist.xml \ erl_dist_protocol.xml \ communication.xml \ @@ -146,6 +149,8 @@ $(INFO_FILE): $(INFO_FILE_SRC) $(ERL_TOP)/make/$(TARGET)/otp.mk debug opt: +ldocs: xmllint local_docs + clean: rm -rf $(HTMLDIR)/* rm -rf $(XMLDIR) diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml index e6245130fc..7c997cae20 100644 --- a/erts/doc/src/alt_dist.xml +++ b/erts/doc/src/alt_dist.xml @@ -60,7 +60,7 @@ parts of the logic in Erlang code, and you perhaps do not even need a new driver for the protocol. One example could be Erlang distribution over UDP using <c>gen_udp</c> (your - Erlang code will of course have to take care of retranspissions, + Erlang code will of course have to take care of retransmissions, etc in this example). That is, depending on what you want to do you perhaps do not need to implement a driver at all and can then skip the driver related sections below. diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 133f160dc9..88ddb03e97 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -464,7 +464,7 @@ </item> <tag><c><![CDATA[-rsh Program]]></c></tag> <item> - <p>Specifies an alternative to <c><![CDATA[rsh]]></c> for starting a + <p>Specifies an alternative to <c><![CDATA[ssh]]></c> for starting a slave node on a remote host; see <seealso marker="stdlib:slave"><c>slave(3)</c></seealso>.</p> </item> @@ -1552,15 +1552,6 @@ parameter determines. The lingering prevents repeated deletions and insertions in the tables from occurring.</p> </item> - <tag><marker id="+ztma"/><c>+ztma true | false</c></tag> - <item> - <p>Enables or disables support for tuple module apply in - the emulator. This is a transitional flag for running code - that uses parameterized modules and was compiled under OTP 20 - or earlier. For future compatibility, the modules will need - to be recompiled with the +tuple_calls compiler option. - Defaults to false.</p> - </item> </taglist> </item> </taglist> diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index c90c8f9521..185c75fe84 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -532,11 +532,7 @@ io:format("old/unused name ~ts at port ~p, fd = ~p ~n", <marker id="distribution_handshake"/> <title>Distribution Handshake</title> <p>This section describes the distribution handshake protocol introduced - in Erlang/OTP R6. This description was previously located in - <c>$ERL_TOP/lib/kernel/internal_doc/distribution_handshake.txt</c> and - has more or less been copied and "formatted" here. It has been almost - unchanged since 1999, but the handshake has not changed much since then - either.</p> + in Erlang/OTP R6. The handshake has remained almost the same since then.</p> <section> <title>General</title> @@ -847,6 +843,18 @@ DiB == gen_digest(ChA, ICA)? of the <c>SEND_TT</c> control message. </p> </item> + <tag><c>-define(DFLAG_BIG_SEQTRACE_LABELS, 16#100000).</c></tag> + <item> + <p>The node understands any term as the seqtrace label.</p> + </item> + <tag><c>-define(DFLAG_EXIT_PAYLOAD, 16#400000).</c></tag> + <item> + <p>Use the <c>PAYLOAD_EXIT</c>, <c>PAYLOAD_EXIT_TT</c>, + <c>PAYLOAD_EXIT2</c>, <c>PAYLOAD_EXIT2_TT</c> + and <c>PAYLOAD_MONITOR_P_EXIT</c> + <seealso marker="#control_message">control message</seealso>s + instead of the non-PAYLOAD variants.</p> + </item> </taglist> <p> There is also function <c>dist_util:strict_order_flags/0</c> @@ -859,7 +867,7 @@ DiB == gen_digest(ChA, ICA)? <section> <marker id="connected_nodes"/> <title>Protocol between Connected Nodes</title> - <p>As from ERTS 5.7.2 the runtime system passes a distribution flag + <p>Since ERTS 5.7.2 (OTP R13B) the runtime system passes a distribution flag in the handshake stage that enables the use of a <seealso marker="erl_ext_dist#distribution_header">distribution header </seealso> on all messages passed. Messages passed between nodes have in @@ -878,7 +886,7 @@ DiB == gen_digest(ChA, ICA)? <cell align="center"><c>ControlMessage</c></cell> <cell align="center"><c>Message</c></cell> </row> - <tcaption>Format of Messages Passed between Nodes (as from ERTS 5.7.2) + <tcaption>Format of Messages Passed between Nodes (as from ERTS 5.7.2 (OTP R13B)) </tcaption> </table> @@ -887,15 +895,23 @@ DiB == gen_digest(ChA, ICA)? <item> <p>Equal to d + n + m.</p> </item> + <tag><c>DistributionHeader</c></tag> + <item> + <p> + <seealso marker="erl_ext_dist#distribution_header">Distribution header + describing the atom cache and fragmented distribution messages. + </seealso> + </p> + </item> <tag><c>ControlMessage</c></tag> <item> <p>A tuple passed using the external format of Erlang.</p> </item> <tag><c>Message</c></tag> <item> - <p>The message sent to another node using the '!' (in external format). - Notice that <c>Message</c> is only passed in combination with a - <c>ControlMessage</c> encoding a send ('!').</p> + <p>The message sent to another node using the '!' + or the reason for a EXIT, EXIT2 or DOWN signal using + the external term format.</p> </item> </taglist> @@ -903,7 +919,7 @@ DiB == gen_digest(ChA, ICA)? number is omitted from the terms that follow a distribution header </seealso>.</p> - <p>Nodes with an ERTS version earlier than 5.7.2 does not pass the + <p>Nodes with an ERTS version earlier than 5.7.2 (OTP R13B) does not pass the distribution flag that enables the distribution header. Messages passed between nodes have in this case the following format:</p> @@ -920,7 +936,7 @@ DiB == gen_digest(ChA, ICA)? <cell align="center"><c>ControlMessage</c></cell> <cell align="center"><c>Message</c></cell> </row> - <tcaption>Format of Messages Passed between Nodes (before ERTS 5.7.2) + <tcaption>Format of Messages Passed between Nodes (before ERTS 5.7.2 (OTP R13B)) </tcaption> </table> @@ -963,6 +979,7 @@ DiB == gen_digest(ChA, ICA)? <tag><c>EXIT</c></tag> <item> <p><c>{3, FromPid, ToPid, Reason}</c></p> + <p>This signal is sent when a link has been broken</p> </item> <tag><c>UNLINK</c></tag> <item> @@ -985,6 +1002,7 @@ DiB == gen_digest(ChA, ICA)? <tag><c>EXIT2</c></tag> <item> <p><c>{8, FromPid, ToPid, Reason}</c></p> + <p>This signal is sent by a call to the erlang:exit/2 bif</p> </item> </taglist> </section> @@ -1007,7 +1025,7 @@ DiB == gen_digest(ChA, ICA)? <p><c>{16, FromPid, Unused, ToName, TraceToken}</c></p> <p>Followed by <c>Message</c>.</p> <p><c>Unused</c> is kept for backward compatibility.</p> - </item> + </item> <tag><c>EXIT2_TT</c></tag> <item> <p><c>{18, FromPid, ToPid, TraceToken, Reason}</c></p> @@ -1061,7 +1079,7 @@ DiB == gen_digest(ChA, ICA)? <p><c>{22, FromPid, ToPid}</c></p> <p>Followed by <c>Message</c>.</p> <p> - This control messages replace the <c>SEND</c> control + This control message replaces the <c>SEND</c> control message and will be sent when the distribution flag <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_SEND_SENDER</c></seealso> has been negotiated in the connection setup handshake. @@ -1080,7 +1098,7 @@ DiB == gen_digest(ChA, ICA)? <p><c>{23, FromPid, ToPid, TraceToken}</c></p> <p>Followed by <c>Message</c>.</p> <p> - This control messages replace the <c>SEND_TT</c> control + This control message replaces the <c>SEND_TT</c> control message and will be sent when the distribution flag <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_SEND_SENDER</c></seealso> has been negotiated in the connection setup handshake. @@ -1097,4 +1115,72 @@ DiB == gen_digest(ChA, ICA)? </taglist> </section> + <section> + <title>New Ctrlmessages for Erlang/OTP 22</title> + <note><p> + Messages encoded before the connection has + been set up may still use the non-PAYLOAD variant. + However, once a PAYLOAD control message has been sent, + no more non-PAYLOAD control messages will be sent in + the same direction on the connection. + </p></note> + <taglist> + <tag><c>PAYLOAD_EXIT</c></tag> + <item> + <p><c>{24, FromPid, ToPid}</c></p> + <p>Followed by <c>Reason</c>.</p> + <p> + This control message replaces the <c>EXIT</c> control + message and will be sent when the distribution flag + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_EXIT_PAYLOAD</c></seealso> + has been negotiated in the connection setup handshake. + </p> + </item> + <tag><c>PAYLOAD_EXIT_TT</c></tag> + <item> + <p><c>{25, FromPid, ToPid}</c></p> + <p>Followed by <c>Reason</c>.</p> + <p> + This control message replaces the <c>EXIT_TT</c> control + message and will be sent when the distribution flag + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_EXIT_PAYLOAD</c></seealso> + has been negotiated in the connection setup handshake. + </p> + </item> + <tag><c>PAYLOAD_EXIT2</c></tag> + <item> + <p><c>{26, FromPid, ToPid}</c></p> + <p>Followed by <c>Reason</c>.</p> + <p> + This control message replaces the <c>EXIT2</c> control + message and will be sent when the distribution flag + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_EXIT_PAYLOAD</c></seealso> + has been negotiated in the connection setup handshake. + </p> + </item> + <tag><c>PAYLOAD_EXIT2_TT</c></tag> + <item> + <p><c>{27, FromPid, ToPid}</c></p> + <p>Followed by <c>Reason</c>.</p> + <p> + This control message replaces the <c>EXIT2_TT</c> control + message and will be sent when the distribution flag + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_EXIT_PAYLOAD</c></seealso> + has been negotiated in the connection setup handshake. + </p> + </item> + <tag><c>PAYLOAD_MONITOR_P_EXIT</c></tag> + <item> + <p><c>{28, FromPid, ToPid, Ref}</c></p> + <p>Followed by <c>Reason</c>.</p> + <p> + This control message replaces the <c>MONITOR_P_EXIT</c> control + message and will be sent when the distribution flag + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_EXIT_PAYLOAD</c></seealso> + has been negotiated in the connection setup handshake. + </p> + </item> + </taglist> + </section> + </chapter> diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index b7090d0472..4721747097 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -136,16 +136,10 @@ </note> </section> - <section> + <section> + <marker id="distribution_header"/> <title>Distribution Header</title> <p> - <marker id="distribution_header"/> - As from ERTS 5.7.2 the old atom cache protocol was - dropped and a new one was introduced. This protocol - introduced the distribution header. Nodes with an ERTS version - earlier than 5.7.2 can still communicate with new nodes, - but no distribution header and no atom cache are used.</p> - <p> The distribution header only contains an atom cache reference section, but can in the future contain more information. The distribution header precedes one or more Erlang @@ -373,8 +367,9 @@ </row> <tcaption>FLOAT_EXT</tcaption></table> <p> - A float is stored in string format. The format used in sprintf to - format the float is "%.20e" + A finite float (i.e. not inf, -inf or NaN) is stored in + string format. The format used in sprintf to format the + float is "%.20e" (there are more bytes allocated than necessary). To unpack the float, use sscanf with format "%lf". </p> @@ -989,7 +984,8 @@ </row> <tcaption>NEW_FLOAT_EXT</tcaption></table> <p> - A float is stored as 8 bytes in big-endian IEEE format. + A finite float (i.e. not inf, -inf or NaN) is stored as 8 bytes + in big-endian IEEE format. </p> <p> This term is used in minor version 1 of the external format. diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 5cbeddabd9..cf1994887a 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -783,14 +783,16 @@ typedef struct { <p>A process identifier (pid). In contrast to pid terms (instances of <c>ERL_NIF_TERM</c>), <c>ErlNifPid</c>s are self-contained and not bound to any <seealso marker="#ErlNifEnv">environment</seealso>. - <c>ErlNifPid</c> is an opaque type.</p> + <c>ErlNifPid</c> is an opaque type. It can be copied, moved + in memory, forgotten, and so on.</p> </item> <tag><marker id="ErlNifPort"/><c>ErlNifPort</c></tag> <item> <p>A port identifier. In contrast to port ID terms (instances of <c>ERL_NIF_TERM</c>), <c>ErlNifPort</c>s are self-contained and not bound to any <seealso marker="#ErlNifEnv">environment</seealso>. - <c>ErlNifPort</c> is an opaque type.</p> + <c>ErlNifPort</c> is an opaque type. It can be copied, moved + in memory, forgotten, and so on.</p> </item> <tag><marker id="ErlNifResourceType"/><c>ErlNifResourceType</c></tag> <item> @@ -1088,6 +1090,20 @@ typedef struct { </func> <func> + <name since="OTP @OTP-15011@"><ret>int</ret> + <nametext>enif_compare_pids(const ErlNifPid *pid1, const ErlNifPid *pid2) + </nametext></name> + <fsummary>Compare two pids.</fsummary> + <desc> + <p>Compares two <seealso marker="#ErlNifPid"><c>ErlNifPid</c> + </seealso>s according to term order.</p> + <p>Returns <c>0</c> if <c>pid1</c> and <c>pid2</c> are equal, + < <c>0</c> if <c>pid1</c> < <c>pid2</c>, and + > <c>0</c> if <c>pid1</c> > <c>pid2</c>.</p> + </desc> + </func> + + <func> <name since="OTP R13B04"><ret>void</ret> <nametext>enif_cond_broadcast(ErlNifCond *cnd)</nametext></name> <fsummary></fsummary> @@ -1392,6 +1408,9 @@ enif_free_iovec(iovec);]]></code> initializes the pid variable <c>*pid</c> from it and returns <c>true</c>. Otherwise returns <c>false</c>. No check is done to see if the process is alive.</p> + <note><p><c>enif_get_local_pid</c> will return false if argument + <c>term</c> is the atom <seealso marker="#enif_make_pid"> + <c>undefined</c></seealso>.</p></note> </desc> </func> @@ -1871,6 +1890,17 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> + <name since="OTP @OTP-15011@"><ret>int</ret> + <nametext>enif_is_pid_undefined(const ErlNifPid* pid)</nametext></name> + <fsummary>Determine if pid is undefined.</fsummary> + <desc> + <p>Returns <c>true</c> if <c>pid</c> has been set as undefined by + <seealso marker="#enif_set_pid_undefined"><c>enif_set_pid_undefined</c> + </seealso>.</p> + </desc> + </func> + + <func> <name since="OTP R13B04"><ret>int</ret> <nametext>enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)</nametext> </name> @@ -2217,6 +2247,18 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> + <name since="OTP @OTP-15362@"><ret>ERL_NIF_TERM</ret> + <nametext>enif_make_monitor_term(ErlNifEnv* env, const ErlNifMonitor* mon)</nametext></name> + <fsummary>Make monitor term from the given monitor identifier.</fsummary> + <desc> + <p>Creates a term identifying the given monitor received from + <seealso marker="#enif_monitor_process"><c>enif_monitor_process</c> + </seealso>.</p> + <p>This function is primarily intended for debugging purpose.</p> + </desc> + </func> + + <func> <name since="OTP R14B"><ret>unsigned char *</ret><nametext>enif_make_new_binary(ErlNifEnv* env, size_t size, ERL_NIF_TERM* termp)</nametext></name> <fsummary>Allocate and create a new binary term.</fsummary> @@ -2247,7 +2289,8 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </name> <fsummary>Make a pid term.</fsummary> <desc> - <p>Makes a pid term from <c>*pid</c>.</p> + <p>Makes a pid term or the atom <seealso marker="#enif_set_pid_undefined"> + <c>undefined</c></seealso> from <c>*pid</c>.</p> </desc> </func> @@ -2613,7 +2656,9 @@ enif_map_iterator_destroy(env, &iter);</code> <p>Argument <c>caller_env</c> is the environment of the calling process or callback. Must only be NULL if calling from a custom thread.</p> <p>Returns <c>0</c> on success, < 0 if no <c>down</c> callback is - provided, and > 0 if the process is no longer alive.</p> + provided, and > 0 if the process is no longer alive or if + <c>target_pid</c> is <seealso marker="#enif_set_pid_undefined"> + undefined</seealso>.</p> <p>This function is only thread-safe when the emulator with SMP support is used. It can only be used in a non-SMP emulator from a NIF-calling thread.</p> @@ -3056,13 +3101,21 @@ enif_map_iterator_destroy(env, &iter);</code> <p>Argument <c>mode</c> describes the type of events to wait for. It can be <c>ERL_NIF_SELECT_READ</c>, <c>ERL_NIF_SELECT_WRITE</c> or a bitwise OR combination to wait for both. It can also be <c>ERL_NIF_SELECT_STOP</c> - which is described further below. When a read or write event is triggered, + or <c>ERL_NIF_SELECT_CANCEL</c> which are described further + below. When a read or write event is triggered, a notification message like this is sent to the process identified by <c>pid</c>:</p> <code type="none">{select, Obj, Ref, ready_input | ready_output}</code> <p><c>ready_input</c> or <c>ready_output</c> indicates if the event object is ready for reading or writing.</p> - <p>Argument <c>pid</c> may be <c>NULL</c> to indicate the calling process.</p> + <note><p>For complete control over the message format use the newer functions + <seealso marker="#enif_select_read"><c>enif_select_read</c></seealso> or + <seealso marker="#enif_select_write"><c>enif_select_write</c></seealso> + introduced in erts-11.0 (OTP-22.0).</p> + </note> + <p>Argument <c>pid</c> may be <c>NULL</c> to indicate the calling + process. It must not be set as <seealso marker="#enif_set_pid_undefined"> + undefined</seealso>.</p> <p>Argument <c>obj</c> is a resource object obtained from <seealso marker="#enif_alloc_resource"><c>enif_alloc_resource</c></seealso>. The purpose of the resource objects is as a container of the event object @@ -3073,17 +3126,29 @@ enif_map_iterator_destroy(env, &iter);</code> or the atom <c>undefined</c>. It will be passed as <c>Ref</c> in the notifications. If a selective <c>receive</c> statement is used to wait for the notification then a reference created just before the <c>receive</c> will exploit a runtime - optimization that bypasses all earlier received messages in the queue.</p> + optimization that bypasses all earlier received messages in the + queue.</p> <p>The notifications are one-shot only. To receive further notifications of the same type (read or write), repeated calls to <c>enif_select</c> must be made after receiving each notification.</p> + <p><c>ERL_NIF_SELECT_CANCEL</c> can be used to cancel previously + selected events. It must be used in a bitwise OR combination with + <c>ERL_NIF_SELECT_READ</c> and/or <c>ERL_NIF_SELECT_WRITE</c> to + indicate which type of event to cancel. Arguments <c>pid</c> and + <c>ref</c> are ignored when <c>ERL_NIF_SELECT_CANCEL</c> is specified. + The return value will tell if the event was actualy cancelled or if a + notification may already have been sent.</p> <p>Use <c>ERL_NIF_SELECT_STOP</c> as <c>mode</c> in order to safely close an event object that has been passed to <c>enif_select</c>. The <seealso marker="#ErlNifResourceStop"><c>stop</c></seealso> callback of the resource <c>obj</c> will be called when it is safe to close the event object. This safe way of closing event objects must be used - even if all notifications have been received and no further calls to - <c>enif_select</c> have been made.</p> + even if all notifications have been received (or cancelled) and no + further calls to <c>enif_select</c> have been made. + <c>ERL_NIF_SELECT_STOP</c> will first cancel any selected events + before it calls or schedules the <c>stop</c> callback. Arguments + <c>pid</c> and <c>ref</c> are ignored when <c>ERL_NIF_SELECT_STOP</c> + is specified.</p> <p>The first call to <c>enif_select</c> for a specific OS <c>event</c> will establish a relation between the event object and the containing resource. All subsequent calls for an <c>event</c> must pass its containing resource as argument @@ -3105,7 +3170,15 @@ enif_map_iterator_destroy(env, &iter);</code> <item>The stop callback was called directly by <c>enif_select</c>.</item> <tag><c>ERL_NIF_SELECT_STOP_SCHEDULED</c></tag> <item>The stop callback was scheduled to run on some other thread - or later by this thread.</item> + or later by this thread.</item> + <tag><c>ERL_NIF_SELECT_READ_CANCELLED</c></tag> + <item>A read event was cancelled by <c>ERL_NIF_SELECT_CANCEL</c> or + <c>ERL_NIF_SELECT_STOP</c> and is guaranteed not to generate a + <c>ready_input</c> notification message.</item> + <tag><c>ERL_NIF_SELECT_WRITE_CANCELLED</c></tag> + <item>A write event was cancelled by <c>ERL_NIF_SELECT_CANCEL</c> or + <c>ERL_NIF_SELECT_STOP</c> and is guaranteed not to generate a + <c>ready_output</c> notification message.</item> </taglist> <p>Returns a negative value if the call failed where the following bits can be set:</p> <taglist> @@ -3131,6 +3204,43 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { } </code> </note> + <note><p>The mode flag <c>ERL_NIF_SELECT_CANCEL</c> and the return flags + <c>ERL_NIF_SELECT_READ_CANCELLED</c> and + <c>ERL_NIF_SELECT_WRITE_CANCELLED</c> were introduced in erts-11.0 + (OTP-22.0).</p> + </note> + </desc> + </func> + + <func> + <name since="OTP 22.0"><ret>int</ret> + <nametext>enif_select_read(ErlNifEnv* env, ErlNifEvent event, void* obj, + const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)</nametext> + </name> + <name since="OTP 22.0"><ret>int</ret> + <nametext>enif_select_write(ErlNifEnv* env, ErlNifEvent event, void* obj, + const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)</nametext> + </name> + <fsummary>Manage subscription on IO event.</fsummary> + <desc> + <p>These are variants of <seealso marker="#enif_select">enif_select</seealso> + where you can supply your own message term <c>msg</c> that will be sent to + the process instead of the predefined tuple <c>{select,_,_,_}.</c></p> + <p>Argument <c>msg_env</c> must either be <c>NULL</c> or the environment of + <c>msg</c> allocated with <seealso marker="#enif_alloc_env"> + <c>enif_alloc_env</c></seealso>. If argument <c>msg_env</c> is + <c>NULL</c> the term <c>msg</c> will be copied, otherwise both + <c>msg</c> and <c>msg_env</c> will be invalidated by a successful call + to <c>enif_select_read</c> or <c>enif_select_write</c>. The environment + is then to either be freed with <seealso marker="#enif_free_env"> + <c>enif_free_env</c></seealso> or cleared for reuse with + <seealso marker="#enif_clear_env"><c>enif_clear_env</c></seealso>. An + unsuccessful call will leave <c>msg</c> and <c>msg_env</c> still valid.</p> + <p>Apart from the message format <c>enif_select_read</c> and + <c>enif_select_write</c> behaves exactly the same as <seealso + marker="#enif_select">enif_select</seealso> with argument <c>mode</c> as + either <c>ERL_NIF_SELECT_READ</c> or <c>ERL_NIF_SELECT_WRITE</c>. To + cancel or close events use <seealso marker="#enif_select">enif_select</seealso>.</p> </desc> </func> @@ -3179,8 +3289,9 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { <c>msg</c>) is invalidated by a successful call to <c>enif_send</c>. The environment is to either be freed with <seealso marker="#enif_free_env"> - <c>enif_free_env</c></seealso> of cleared for reuse with - <seealso marker="#enif_clear_env"><c>enif_clear_env</c></seealso>.</p> + <c>enif_free_env</c></seealso> or cleared for reuse with + <seealso marker="#enif_clear_env"><c>enif_clear_env</c></seealso>. An + unsuccessful call will leave <c>msg</c> and <c>msg_env</c> still valid.</p> <p>If <c>msg_env</c> is set to <c>NULL</c>, the <c>msg</c> term is copied and the original term and its environment is still valid after the call.</p> @@ -3195,6 +3306,17 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { </func> <func> + <name since="OTP @OTP-15011@"><ret>void</ret> + <nametext>enif_set_pid_undefined(ErlNifPid* pid)</nametext></name> + <fsummary>Set pid as undefined.</fsummary> + <desc> + <p>Sets an <seealso marker="#ErlNifPid"><c>ErlNifPid</c></seealso> + variable as undefined. See <seealso marker="#enif_is_pid_undefined"> + <c>enif_is_pid_undefined</c></seealso>.</p> + </desc> + </func> + + <func> <name since="OTP R13B04"><ret>unsigned</ret> <nametext>enif_sizeof_resource(void* obj)</nametext></name> <fsummary>Get the byte size of a resource object.</fsummary> @@ -3247,6 +3369,48 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { </func> <func> + <name since="OTP @OTP-15640@"><ret>ErlNifTermType</ret> + <nametext>enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)</nametext> + </name> + <fsummary>Determine the type of a term.</fsummary> + <desc> + <p>Determines the type of the given term. The term must be an ordinary + Erlang term and not one of the special terms returned by + <seealso marker="#enif_raise_exception"> + <c>enif_raise_exception</c></seealso>, + <seealso marker="#enif_schedule_nif"> + <c>enif_schedule_nif</c></seealso>, or similar.</p> + <p>The following types are defined at the moment:</p> + <taglist> + <tag><c>ERL_NIF_TERM_TYPE_ATOM</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_BITSTRING</c></tag> + <item><p>A bitstring or binary</p></item> + <tag><c>ERL_NIF_TERM_TYPE_FLOAT</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_FUN</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_INTEGER</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_LIST</c></tag> + <item><p>A list, empty or not</p></item> + <tag><c>ERL_NIF_TERM_TYPE_MAP</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_PID</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_PORT</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_REFERENCE</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_TUPLE</c></tag> + <item/> + </taglist> + <p>Note that new types may be added in the future, so the caller must + be prepared to handle unknown types.</p> + </desc> + </func> + + <func> <name since="OTP R13B04"><ret>int</ret> <nametext>enif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 6932b18571..0d94f83493 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -1269,6 +1269,42 @@ end</code> data is available by calling <seealso marker="erlang#dist_ctrl_get_data_notification/1"><c>erlang:dist_ctrl_get_data_notification(DHandle)</c></seealso>. </p> + <p>The returned value when there are data available depends + on the value of the <c>get_size</c> option configured on the + distribution channel identified by <c><anno>DHandle</anno></c>. + For more information see the documentation of the <c>get_size</c> + option for the + <seealso marker="#dist_ctrl_set_opt/3"><c>erlang:dist_ctrl_set_opt/3</c></seealso> + function.</p> + <note><p> + Only the process registered as distribution + controller for the distribution channel identified by + <c><anno>DHandle</anno></c> is allowed to call this + function. + </p></note> + <p> + This function is used when implementing an alternative + distribution carrier using processes as distribution + controllers. <c><anno>DHandle</anno></c> is retrived + via the callback + <seealso marker="erts:alt_dist#hs_data_f_handshake_complete"><c>f_handshake_complete</c></seealso>. + More information can be found in the documentation of + <seealso marker="erts:alt_dist#distribution_module">ERTS + User's Guide ➜ How to implement an Alternative Carrier + for the Erlang Distribution ➜ Distribution Module</seealso>. + </p> + </desc> + </func> + + <func> + <name name="dist_ctrl_get_opt" arity="2" clause_i="1" since="OTP @OTP-15617@"/> + <fsummary>Get value of the get_size option on a distribution channel</fsummary> + <desc> + <p>Returns the value of the <c>get_size</c> option on the distribution channel + identified by <c><anno>DHandle</anno></c>. For more information see the + documentation of the <c>get_size</c> option for the + <seealso marker="#dist_ctrl_set_opt/3"><c>erlang:dist_ctrl_set_opt/3</c></seealso> + function.</p> <note><p> Only the process registered as distribution controller for the distribution channel identified by @@ -1392,6 +1428,55 @@ end</code> </func> <func> + <name name="dist_ctrl_set_opt" arity="3" clause_i="1" since="OTP @OTP-15617@"/> + <fsummary>Set value of the get_size option on a distribution channel</fsummary> + <desc> + <p>Sets the value of the <c>get_size</c> option on the distribution channel + identified by <c><anno>DHandle</anno></c>. This option controls the return + value of calls to + <seealso marker="#dist_ctrl_get_data/1">erlang:dist_ctrl_get_data(<anno>DHandle</anno>)</seealso> + where <c><anno>DHandle</anno></c> equals <c><anno>DHandle</anno></c> used + when setting this option. + When the <c>get_size</c> option is:</p> + <taglist> + <tag><c>false</c></tag> + <item> + and there are distribution data available, a call to + <c>erlang:dist_ctrl_get_data(<anno>DHandle</anno>)</c> + will just return <c>Data</c> to pass over the channel. + This is the default value of the <c>get_size</c> option. + </item> + <tag><c>true</c></tag> + <item> + and there are distribution data available, a call to + <c>erlang:dist_ctrl_get_data(<anno>DHandle</anno>)</c> + will return <c>Data</c> to pass over the channel as well as + the <c>Size</c> of <c>Data</c> in bytes. This is returned as + a tuple on the form <c>{Size, Data}</c>. + </item> + </taglist> + <p>All options are set to default when a channel is closed.</p> + <note><p> + Only the process registered as distribution + controller for the distribution channel identified by + <c><anno>DHandle</anno></c> is allowed to call this + function. + </p></note> + <p> + This function is used when implementing an alternative + distribution carrier using processes as distribution + controllers. <c><anno>DHandle</anno></c> is retrived + via the callback + <seealso marker="erts:alt_dist#hs_data_f_handshake_complete"><c>f_handshake_complete</c></seealso>. + More information can be found in the documentation of + <seealso marker="erts:alt_dist#distribution_module">ERTS + User's Guide ➜ How to implement an Alternative Carrier + for the Erlang Distribution ➜ Distribution Module</seealso>. + </p> + </desc> + </func> + + <func> <name name="element" arity="2" since=""/> <fsummary>Return the Nth element of a tuple.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> @@ -1751,6 +1836,10 @@ true</pre> <item> <p><c>Pid</c> is the process identifier of the process that originally created the fun.</p> + <p>It might point to the <c>init</c> process if the + <c>Fun</c> was statically allocated when module was + loaded (this optimisation is performed for local + functions that do not capture the enviornment).</p> </item> <tag><c>{index, Index}</c></tag> <item> @@ -5206,11 +5295,13 @@ RealSystem = system + MissedSystem</code> changed or removed without prior notice.</p> </item> <tag><c>{current_function, {<anno>Module</anno>, - <anno>Function</anno>, Arity}}</c></tag> + <anno>Function</anno>, Arity} | undefined}</c></tag> <item> <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>, <c><anno>Arity</anno></c> is - the current function call of the process.</p> + the current function call of the process. The value + <c>undefined</c> can be returned if the process is + currently executing native compiled code.</p> </item> <tag><c>{current_location, {<anno>Module</anno>, <anno>Function</anno>, <anno>Arity</anno>, diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml index a094217959..962bc9a244 100644 --- a/erts/doc/src/erts_alloc.xml +++ b/erts/doc/src/erts_alloc.xml @@ -487,11 +487,10 @@ utilization value used. Once a carrier is abandoned, no new allocations are made in it. When an allocator instance gets an increased multiblock carrier need, it first tries to fetch an - abandoned carrier from an allocator instance of the same - allocator type. If no abandoned carrier can be fetched, it - creates a new empty carrier. When an abandoned carrier has been - fetched, it will function as an ordinary carrier. This feature has - special requirements on the + abandoned carrier from another allocator instance. If no abandoned + carrier can be fetched, it creates a new empty carrier. When an + abandoned carrier has been fetched, it will function as an ordinary + carrier. This feature has special requirements on the <seealso marker="#M_as">allocation strategy</seealso> used. Only the strategies <c>aoff</c>, <c>aoffcbf</c>, <c>aoffcaobf</c>, <c>ageffcaoff</c>m, <c>ageffcbf</c> and <c>ageffcaobf</c> @@ -584,7 +583,7 @@ carriers are decided in section <seealso marker="#mseg_mbc_sizes"> The alloc_util Framework</seealso>. On - 32-bit Unix style OS this limit cannot be set > 128 MB.</p> + 32-bit Unix style OS this limit cannot be set > 64 MB.</p> </item> <tag><marker id="M_mbcgs"/><c><![CDATA[+M<S>mbcgs <ratio>]]></c></tag> <item> diff --git a/erts/doc/src/net.xml b/erts/doc/src/net.xml new file mode 100644 index 0000000000..b9e2cffce9 --- /dev/null +++ b/erts/doc/src/net.xml @@ -0,0 +1,129 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2018</year><year>2018</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>net</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>net.xml</file> + </header> + <module since="OTP @OTP-14831@">net</module> + <modulesummary>Network interface.</modulesummary> + <description> + <p>This module provides an API for the network interface.</p> + <note> + <p>There is currently <em>no</em> support for Windows. </p> + </note> + </description> + + <datatypes> + <datatype> + <name name="address_info"/> + </datatype> + <datatype> + <name name="name_info"/> + </datatype> + <datatype> + <name name="name_info_flags"/> + </datatype> + <datatype> + <name name="name_info_flag"/> + </datatype> + <datatype> + <name name="name_info_flag_ext"/> + </datatype> + <datatype> + <name name="network_interface_name"/> + </datatype> + <datatype> + <name name="network_interface_index"/> + </datatype> + </datatypes> + + <funcs> + <func> + <name name="gethostname" arity="0"/> + <fsummary>Get hostname.</fsummary> + <desc> + <p>Returns the name of the current host.</p> + </desc> + </func> + + <func> + <name name="getnameinfo" arity="1" since="OTP @OTP-14831@"/> + <name name="getnameinfo" arity="2" since="OTP @OTP-14831@"/> + <fsummary>Address-to-name transaltion.</fsummary> + <desc> + <p>Address-to-name translation in a protocol-independant manner.</p> + <p>This function is the inverse of + <seealso marker="#getaddrinfo/1"><c>getaddrinfo</c></seealso>. + It converts a socket address to a corresponding host and service.</p> + </desc> + </func> + + <func> + <name name="getaddrinfo" arity="1" since="OTP @OTP-14831@"/> + <name name="getaddrinfo" arity="2" clause_i="1" since="OTP @OTP-14831@"/> + <name name="getaddrinfo" arity="2" clause_i="2" since="OTP @OTP-14831@"/> + <name name="getaddrinfo" arity="2" clause_i="3" since="OTP @OTP-14831@"/> + <fsummary>Network address and service transation.</fsummary> + <desc> + <p>Network address and service translation.</p> + <p>This function is the inverse of + <seealso marker="#getnameinfo/1"><c>getnameinfo</c></seealso>. + It converts host and service to a corresponding socket address.</p> + <p>One of the <c>Host</c> and <c>Service</c> may be <c>undefined</c> + but <em>not</em> both.</p> + </desc> + </func> + + <func> + <name name="if_name2index" arity="1" since="OTP @OTP-14831@"/> + <fsummary>Mappings between network interface names and indexes.</fsummary> + <desc> + <p>Mappings between network interface names and indexes.</p> + </desc> + </func> + + <func> + <name name="if_index2name" arity="1" since="OTP @OTP-14831@"/> + <fsummary>Mappings between network interface index and names.</fsummary> + <desc> + <p>Mappings between network interface index and names.</p> + </desc> + </func> + + <func> + <name name="if_names" arity="0" since="OTP @OTP-14831@"/> + <fsummary>Get network interface names and indexes.</fsummary> + <desc> + <p>Get network interface names and indexes.</p> + </desc> + </func> + + </funcs> + +</erlref> + diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index 9e5afd57a2..248b871ca0 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -11239,7 +11239,7 @@ you use erlang:halt/2 with an integer first argument and an option list containing {flush,false} as the second argument. Note that now is flushing not dependant of the - exit code, and you can not only flush async threads + exit code, and you cannot only flush async threads operations which we deemed as a strange behaviour anyway. </p> <p>Also, erlang:halt/1,2 has gotten a new feature: If the diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml index 05e9a24af8..f0b8a00b90 100644 --- a/erts/doc/src/part.xml +++ b/erts/doc/src/part.xml @@ -42,6 +42,7 @@ <xi:include href="tty.xml"/> <xi:include href="driver.xml"/> <xi:include href="inet_cfg.xml"/> + <xi:include href="socket_usage.xml"/> <xi:include href="erl_ext_dist.xml"/> <xi:include href="erl_dist_protocol.xml"/> </part> diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml index a78aaa449e..80cdcf9145 100644 --- a/erts/doc/src/ref_man.xml +++ b/erts/doc/src/ref_man.xml @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,26 +31,28 @@ </header> <description> </description> - <xi:include href="erl_prim_loader.xml"/> - <xi:include href="erlang.xml"/> - <xi:include href="init.xml"/> - <xi:include href="persistent_term.xml"/> - <xi:include href="zlib.xml"/> + <xi:include href="atomics.xml"/> + <xi:include href="counters.xml"/> + <xi:include href="driver_entry.xml"/> <xi:include href="epmd.xml"/> <xi:include href="erl.xml"/> + <xi:include href="erlang.xml"/> <xi:include href="erlc.xml"/> - <xi:include href="werl.xml"/> - <xi:include href="escript.xml"/> - <xi:include href="erlsrv.xml"/> - <xi:include href="start_erl.xml"/> - <xi:include href="run_erl.xml"/> - <xi:include href="start.xml"/> <xi:include href="erl_driver.xml"/> - <xi:include href="driver_entry.xml"/> - <xi:include href="erts_alloc.xml"/> <xi:include href="erl_nif.xml"/> + <xi:include href="erl_prim_loader.xml"/> + <xi:include href="erlsrv.xml"/> <xi:include href="erl_tracer.xml"/> - <xi:include href="atomics.xml"/> - <xi:include href="counters.xml"/> + <xi:include href="erts_alloc.xml"/> + <xi:include href="escript.xml"/> + <xi:include href="init.xml"/> + <xi:include href="net.xml"/> + <xi:include href="persistent_term.xml"/> + <xi:include href="run_erl.xml"/> + <xi:include href="socket.xml"/> + <xi:include href="start.xml"/> + <xi:include href="start_erl.xml"/> + <xi:include href="werl.xml"/> + <xi:include href="zlib.xml"/> </application> diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml new file mode 100644 index 0000000000..f6195a65b2 --- /dev/null +++ b/erts/doc/src/socket.xml @@ -0,0 +1,650 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2018</year><year>2019</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>socket</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>socket.xml</file> + </header> + <module since="OTP @OTP-14831@">socket</module> + <modulesummary>Socket interface.</modulesummary> + <description> + <p>This module provides an API for the socket interface. + It is used to create, delete and manipulate sockets, + send and receive data.</p> + <p>The idea is that it shall be as "close as possible" to the OS + level socket interface. The only significant addition is that some of + the functions, + e.g. <seealso marker="#recv/3"><c>recv/3</c></seealso>, + has a timeout argument. </p> + <note> + <p>There is currently <em>no</em> support for Windows. </p> + <p>Support for IPv6 has been implemented but <em>not</em> tested. </p> + <p>SCTP has only been partly implemented (and not tested). </p> + </note> + </description> + + <datatypes> + <datatype> + <name name="domain"/> + </datatype> + <datatype> + <name name="type"/> + </datatype> + <datatype> + <name name="protocol"/> + </datatype> + <datatype> + <name>socket()</name> + <desc><p>As returned by + <seealso marker="#open/2"><c>open/2,3,4</c></seealso> and + <seealso marker="#accept/1"><c>accept/1,2</c></seealso>.</p> + </desc> + </datatype> + <datatype> + <name name="ip4_address"/> + </datatype> + <datatype> + <name name="ip6_address"/> + </datatype> + <datatype> + <name name="ip_address"/> + </datatype> + <datatype> + <name name="sockaddr"/> + </datatype> + <datatype> + <name name="sockaddr_in4"/> + </datatype> + <datatype> + <name name="sockaddr_in6"/> + </datatype> + <datatype> + <name name="sockaddr_un"/> + </datatype> + <datatype> + <name name="port_number"/> + </datatype> + <datatype> + <name name="in6_flow_info"/> + </datatype> + <datatype> + <name name="in6_scope_id"/> + </datatype> + <datatype> + <name name="accept_flags"/> + </datatype> + <datatype> + <name name="accept_flag"/> + </datatype> + <datatype> + <name name="send_flags"/> + </datatype> + <datatype> + <name name="send_flag"/> + </datatype> + <datatype> + <name name="recv_flags"/> + </datatype> + <datatype> + <name name="recv_flag"/> + </datatype> + <datatype> + <name name="shutdown_how"/> + </datatype> + <datatype> + <name name="sockopt_level"/> + </datatype> + <datatype> + <name name="otp_socket_option"/> + </datatype> + <datatype> + <name name="socket_option"/> + </datatype> + <datatype> + <name name="ip_socket_option"/> + </datatype> + <datatype> + <name name="ipv6_socket_option"/> + </datatype> + <datatype> + <name name="tcp_socket_option"/> + </datatype> + <datatype> + <name name="udp_socket_option"/> + </datatype> + <datatype> + <name name="sctp_socket_option"/> + </datatype> + <datatype> + <name name="timeval"/> + </datatype> + <datatype> + <name name="ip_tos"/> + </datatype> + <datatype> + <name name="ip_mreq"/> + </datatype> + <datatype> + <name name="ip_mreq_source"/> + </datatype> + <datatype> + <name name="ip_pmtudisc"/> + </datatype> + <datatype> + <name name="ip_msfilter_mode"/> + </datatype> + <datatype> + <name name="ip_msfilter"/> + </datatype> + <datatype> + <name name="ip_pktinfo"/> + </datatype> + <datatype> + <name name="ipv6_mreq"/> + </datatype> + <datatype> + <name name="ipv6_pmtudisc"/> + </datatype> + <datatype> + <name name="ipv6_pktinfo"/> + </datatype> + <datatype> + <name name="sctp_assoc_id"/> + </datatype> + <datatype> + <name name="sctp_sndrcvinfo"/> + </datatype> + <datatype> + <name name="sctp_event_subscribe"/> + </datatype> + <datatype> + <name name="sctp_assocparams"/> + </datatype> + <datatype> + <name name="sctp_initmsg"/> + </datatype> + <datatype> + <name name="sctp_rtoinfo"/> + </datatype> + <datatype> + <name name="msghdr_flag"/> + </datatype> + <datatype> + <name name="msghdr_flags"/> + </datatype> + <datatype> + <name name="msghdr"/> + </datatype> + <datatype> + <name name="cmsghdr_level"/> + </datatype> + <datatype> + <name name="cmsghdr_type"/> + </datatype> + <!-- + <datatype> + <name name="cmsghdr_data"/> + </datatype> + --> + <datatype> + <name name="cmsghdr_recv"/> + </datatype> + <datatype> + <name name="cmsghdr_send"/> + </datatype> + <datatype> + <name name="uint8"/> + </datatype> + <datatype> + <name name="uint16"/> + </datatype> + <datatype> + <name name="uint20"/> + </datatype> + <datatype> + <name name="uint32"/> + </datatype> + <datatype> + <name name="int32"/> + </datatype> + <datatype> + <name name="supports_options_socket"/> + </datatype> + <datatype> + <name name="supports_options_ip"/> + </datatype> + <datatype> + <name name="supports_options_ipv6"/> + </datatype> + <datatype> + <name name="supports_options_tcp"/> + </datatype> + <datatype> + <name name="supports_options_udp"/> + </datatype> + <datatype> + <name name="supports_options_sctp"/> + </datatype> + <datatype> + <name name="supports_options"/> + </datatype> + </datatypes> + + <funcs> + <func> + <name name="accept" arity="1" since="OTP @OTP-14831@"/> + <name name="accept" arity="2" since="OTP @OTP-14831@"/> + <fsummary>Accept a connection on a socket.</fsummary> + <desc> + <p>Accept a connection on a socket.</p> + <p>This call is used with connection-based socket types + (<c>stream</c> or <c>seqpacket</c>). It extracs the first pending + connection request for the listen socket and returns the (newly) + connected socket.</p> + </desc> + </func> + + <func> + <name name="bind" arity="2" since="OTP @OTP-14831@"/> + <fsummary>Bind a name to a socket.</fsummary> + <desc> + <p>Bind a name to a socket.</p> + <p>When a socket is created + (with <seealso marker="#open/2"><c>open</c></seealso>), + it has no address assigned to it. <c>bind</c> assigns the + address specified by the <c>Addr</c> argument.</p> + <p>The rules used for name binding vary between domains.</p> + </desc> + </func> + + <func> + <name name="close" arity="1" since="OTP @OTP-14831@"/> + <fsummary>Close a socket.</fsummary> + <desc> + <p>Closes the socket.</p> + + <note> + <p>Note that for e.g. <c>protocol</c> = <c>tcp</c>, most implementations + doing a close does not guarantee that any data sent is delivered to + the recipient before the close is detected at the remote side. </p> + <p>One way to handle this is to use the + <seealso marker="#shutdown/2"><c>shutdown</c></seealso> + function + (<c>socket:shutdown(Socket, write)</c>) to signal that no more data is + to be sent and then wait for the read side of the socket to be closed.</p> + </note> + </desc> + </func> + + <func> + <name name="connect" arity="2" since="OTP @OTP-14831@"/> + <name name="connect" arity="3" since="OTP @OTP-14831@"/> + <fsummary>Initiate a connection on a socket.</fsummary> + <desc> + <p>This function connects the socket to the address + specied by the <c>SockAddr</c> argument.</p> + </desc> + </func> + + <func> + <name name="getopt" arity="3" clause_i="1" since="OTP @OTP-14831@"/> + <name name="getopt" arity="3" clause_i="2" since="OTP @OTP-14831@"/> + <name name="getopt" arity="3" clause_i="3" since="OTP @OTP-14831@"/> + <name name="getopt" arity="3" clause_i="4" since="OTP @OTP-14831@"/> + <name name="getopt" arity="3" clause_i="5" since="OTP @OTP-14831@"/> + <name name="getopt" arity="3" clause_i="6" since="OTP @OTP-14831@"/> + <name name="getopt" arity="3" clause_i="7" since="OTP @OTP-14831@"/> + <fsummary>Get an option on a socket.</fsummary> + <desc> + <p>Get an option on a socket.</p> + <p>What properties are valid depend both on <c>Level</c> and + on what kind of socket it is (<c>domain</c>, <c>type</c> and + <c>protocol</c>).</p> + + <p>See the + <seealso marker="socket_usage#socket_options">socket options</seealso> + chapter of the users guide for more info. </p> + + <note><p>Not all options are valid on all platforms. That is, + even if "we" support an option, that does not mean that the + underlying OS does.</p></note> + + </desc> + </func> + + <func> + <name name="getopt" arity="3" clause_i="8" since="OTP @OTP-14831@"/> + <fsummary>Get an option on a socket.</fsummary> + <desc> + <p>Get an option on a socket.</p> + <p>What properties are valid depend both on <c>Level</c> and + on what kind of socket it is (<c>domain</c>, <c>type</c> and + <c>protocol</c>).</p> + <p>When specifying <c>Level</c> as an integer, and therefor + using "native mode", it is *currently* up to the caller to + know how to interpret the result.</p> + + <p>See the + <seealso marker="socket_usage#socket_options">socket options</seealso> + chapter of the users guide for more info. </p> + + <note><p>Not all options are valid on all platforms. That is, + even if "we" support an option, that does not mean that the + underlying OS does.</p></note> + </desc> + </func> + + <func> + <name name="listen" arity="1" since="OTP @OTP-14831@"/> + <name name="listen" arity="2" since="OTP @OTP-14831@"/> + <fsummary>Listen for connections on a socket.</fsummary> + <desc> + <p>Listen for connections on a socket.</p> + </desc> + </func> + + <func> + <name name="open" arity="2" since="OTP @OTP-14831@"/> + <name name="open" arity="3" since="OTP @OTP-14831@"/> + <name name="open" arity="4" since="OTP @OTP-14831@"/> + <fsummary>Create an endpoint for communication.</fsummary> + <desc> + <p>Creates an endpoint (socket) for communication.</p> + <p>For some <c>types</c> there is a default protocol, which will + be used if no protocol is specified: </p> + + <list> + <item><p><c>stream</c>: <c>tcp</c></p></item> + <item><p><c>dgram</c>: <c>udp</c></p></item> + <item><p><c>seqpacket</c>: <c>sctp</c></p></item> + </list> + + <p>The <c>Extra</c> argument is intended for "obscure" options. + Currently the only supported option is <c>netns</c>, which + is only supported on the linux platform.</p> + </desc> + </func> + + <func> + <name name="peername" arity="1" since="OTP @OTP-14831@"/> + <fsummary>Get name of connected socket peer.</fsummary> + <desc> + <p>Returns the address of the peer connected to the socket.</p> + </desc> + </func> + + <func> + <name name="recv" arity="1" since="OTP @OTP-14831@"/> + <name name="recv" arity="2" since="OTP @OTP-14831@"/> + <name name="recv" arity="3" clause_i="1" since="OTP @OTP-14831@"/> + <name name="recv" arity="3" clause_i="2" since="OTP @OTP-14831@"/> + <name name="recv" arity="4" since="OTP @OTP-14831@"/> + <fsummary>Receive a message from a socket.</fsummary> + <desc> + <p>Receive a message from a socket.</p> + <p>There is a special case for the argument <c>Length</c>. + If it is set to zero (0), it means "give me everything you + currently have".</p> + </desc> + </func> + + <func> + <name name="recvfrom" arity="1" since="OTP @OTP-14831@"/> + <name name="recvfrom" arity="2" since="OTP @OTP-14831@"/> + <name name="recvfrom" arity="3" clause_i="1" since="OTP @OTP-14831@"/> + <name name="recvfrom" arity="3" clause_i="2" since="OTP @OTP-14831@"/> + <name name="recvfrom" arity="3" clause_i="3" since="OTP @OTP-14831@"/> + <name name="recvfrom" arity="4" since="OTP @OTP-14831@"/> + <fsummary>Receive a message from a socket.</fsummary> + <desc> + <p>Receive a message from a socket.</p> + <p>This function reads "messages", which means that regardless of + how much we want to read, it returns when we get a message.</p> + <p>The <c>BufSz</c> argument basically defines the size of the + receive buffer. By setting the value to zero (0), the configured + size (setopt with <c>Level</c> = <c>otp</c> and <c>Key</c> = <c>rcvbuf</c>) + is used.</p> + <p>It may be impossible to know what (buffer) size is appropriate + "in advance", and in those cases it may be convenient to use the + (recv) 'peek' flag. When this flag is provided, the message is *not* + "consumed" from the underlying buffers, so another recvfrom call + is needed, possibly with a then adjusted buffer size.</p> + </desc> + </func> + + <func> + <name name="recvmsg" arity="1" since="OTP @OTP-14831@"/> + <name name="recvmsg" arity="2" clause_i="1" since="OTP @OTP-14831@"/> + <name name="recvmsg" arity="2" clause_i="2" since="OTP @OTP-14831@"/> + <name name="recvmsg" arity="3" clause_i="1" since="OTP @OTP-14831@"/> + <name name="recvmsg" arity="3" clause_i="2" since="OTP @OTP-14831@"/> + <name name="recvmsg" arity="5" since="OTP @OTP-14831@"/> + <fsummary>Receive a message from a socket.</fsummary> + <desc> + <p>Receive a message from a socket.</p> + <p>This function reads "messages", which means that regardless of + how much we want to read, it returns when we get a message.</p> + <p>The message will be delivered in the form of a <c>msghdr()</c>, + which may contain the source address (if socket not connected), + a list of <c>cmsghdr_recv()</c> (depends on what socket options have + been set and what the protocol and platform supports) and + also a set of flags, providing further info about the read. </p> + + <p>The <c>BufSz</c> argument basically defines the size of the + receive buffer. By setting the value to zero (0), the configured + size (setopt with <c>Level</c> = <c>otp</c> and <c>Key</c> = <c>rcvbuf</c>) + is used.</p> + + <p>The <c>CtrlSz</c> argument basically defines the size of the + receive buffer for the control messages. + By setting the value to zero (0), the configured size (setopt + with <c>Level</c> = <c>otp</c>) is used.</p> + + <p>It may be impossible to know what (buffer) size is appropriate + "in advance", and in those cases it may be convenient to use the + (recv) 'peek' flag. When this flag is provided, the message is *not* + "consumed" from the underlying buffers, so another recvmsg call + is needed, possibly with a then adjusted buffer size.</p> + </desc> + </func> + + <func> + <name name="send" arity="2" since="OTP @OTP-14831@"/> + <name name="send" arity="3" clause_i="1" since="OTP @OTP-14831@"/> + <name name="send" arity="3" clause_i="2" since="OTP @OTP-14831@"/> + <name name="send" arity="4" since="OTP @OTP-14831@"/> + <fsummary>Send a message on a socket.</fsummary> + <desc> + <p>Send a message on a connected socket.</p> + </desc> + </func> + + <func> + <name name="sendmsg" arity="2" since="OTP @OTP-14831@"/> + <name name="sendmsg" arity="3" clause_i="1" since="OTP @OTP-14831@"/> + <name name="sendmsg" arity="3" clause_i="2" since="OTP @OTP-14831@"/> + <name name="sendmsg" arity="4" since="OTP @OTP-14831@"/> + <fsummary>Send a message on a socket.</fsummary> + <desc> + <p>Send a message on a socket. The destination, if needed + (socket <em>not</em> connected) is provided in the <c>MsgHdr</c>, + which also contains the message to send, + The <c>MsgHdr</c> may also contain an list of optional <c>cmsghdr_send()</c> + (depends on what the protocol and platform supports).</p> + + <p>Unlike the <seealso marker="#send/2"><c>send</c></seealso> function, + this one sends <em>one message</em>. + This means that if, for whatever reason, its not possible to send the + message in one go, the function will instead return with the + <em>remaining</em> data (<c>{ok, Remaining}</c>). Thereby leaving it + up to the caller to decide what to do (retry with the remaining data + of give up). </p> + + </desc> + </func> + + <func> + <name name="sendto" arity="3" since="OTP @OTP-14831@"/> + <name name="sendto" arity="4" clause_i="1" since="OTP @OTP-14831@"/> + <name name="sendto" arity="4" clause_i="2" since="OTP @OTP-14831@"/> + <name name="sendto" arity="5" since="OTP @OTP-14831@"/> + <fsummary>Send a message on a socket.</fsummary> + <desc> + <p>Send a message on a socket, to the specified destination.</p> + </desc> + </func> + + <func> + <name name="setopt" arity="4" clause_i="1" since="OTP @OTP-14831@"/> + <name name="setopt" arity="4" clause_i="2" since="OTP @OTP-14831@"/> + <name name="setopt" arity="4" clause_i="3" since="OTP @OTP-14831@"/> + <name name="setopt" arity="4" clause_i="4" since="OTP @OTP-14831@"/> + <name name="setopt" arity="4" clause_i="5" since="OTP @OTP-14831@"/> + <name name="setopt" arity="4" clause_i="6" since="OTP @OTP-14831@"/> + <name name="setopt" arity="4" clause_i="7" since="OTP @OTP-14831@"/> + <fsummary>Set options on a socket.</fsummary> + <desc> + <p>Set options on a socket.</p> + <p>What properties are valid depend both on <c>Level</c> and on + what kind of socket it is (<c>domain</c>, <c>type</c> and + <c>protocol</c>).</p> + + <p>See the + <seealso marker="socket_usage#socket_options">socket options</seealso> + chapter of the users guide for more info. </p> + + <note><p>Not all options are valid on all platforms. That is, + even if "we" support an option, that does not mean that the + underlying OS does.</p></note> + + <note><p>Sockets are set 'non-blocking' when created, so this option + is *not* available (as it would adversely effect the Erlang VM + to set a socket 'blocking').</p></note> + </desc> + </func> + + <func> + <name name="setopt" arity="4" clause_i="8" since="OTP @OTP-14831@"/> + <fsummary>Set options on a socket.</fsummary> + <desc> + <p>Set options on a socket.</p> + <p>What properties are valid depend both on <c>Level</c> and on + what kind of socket it is (<c>domain</c>, <c>type</c> and + <c>protocol</c>).</p> + + <p>See the + <seealso marker="socket_usage#socket_options">socket options</seealso> + chapter of the users guide for more info. </p> + + <note><p>Not all options are valid on all platforms. That is, + even if "we" support an option, that does not mean that the + underlying OS does.</p></note> + + <note><p>Sockets are set 'non-blocking' when created, so this option + is *not* available (as it would adversely effect the Erlang VM + to set a socket 'blocking').</p></note> + </desc> + </func> + + <func> + <name name="shutdown" arity="2" since="OTP @OTP-14831@"/> + <fsummary>Shut down part of a full-duplex connection.</fsummary> + <desc> + <p>Shut down all or part of a full-duplex connection.</p> + </desc> + </func> + + <func> + <name name="sockname" arity="1" since="OTP @OTP-14831@"/> + <fsummary>Get socket name.</fsummary> + <desc> + <p>Returns the current address to which the socket is bound.</p> + </desc> + </func> + + <func> + <name name="supports" arity="0" since="OTP @OTP-14831@"/> + <name name="supports" arity="1" clause_i="1" since="OTP @OTP-14831@"/> + <name name="supports" arity="1" clause_i="2" since="OTP @OTP-14831@"/> + <name name="supports" arity="1" clause_i="3" since="OTP @OTP-14831@"/> + <name name="supports" arity="1" clause_i="4" since="OTP @OTP-14831@"/> + <name name="supports" arity="2" clause_i="1" since="OTP @OTP-14831@"/> + <name name="supports" arity="2" clause_i="2" since="OTP @OTP-14831@"/> + <name name="supports" arity="2" clause_i="3" since="OTP @OTP-14831@"/> + <name name="supports" arity="2" clause_i="4" since="OTP @OTP-14831@"/> + <name name="supports" arity="2" clause_i="5" since="OTP @OTP-14831@"/> + <name name="supports" arity="2" clause_i="6" since="OTP @OTP-14831@"/> + <name name="supports" arity="2" clause_i="7" since="OTP @OTP-14831@"/> + <name name="supports" arity="3" clause_i="1" since="OTP @OTP-14831@"/> + <name name="supports" arity="3" clause_i="2" since="OTP @OTP-14831@"/> + <name name="supports" arity="3" clause_i="3" since="OTP @OTP-14831@"/> + <name name="supports" arity="3" clause_i="4" since="OTP @OTP-14831@"/> + <name name="supports" arity="3" clause_i="5" since="OTP @OTP-14831@"/> + <name name="supports" arity="3" clause_i="6" since="OTP @OTP-14831@"/> + <name name="supports" arity="3" clause_i="7" since="OTP @OTP-14831@"/> + <fsummary>Report info about what the platform supports.</fsummary> + <desc> + <p>This function intends to retreive information about what the + platform supports. Such as if SCTP is supported. Or which socket + options are supported. </p> + </desc> + </func> + + </funcs> + <section> + <title>Examples</title> + <marker id="examples"></marker> + <code type="none"> +client(Addr, SAddr, SPort) -> + {ok, Sock} = socket:open(inet, stream, tcp), + {ok, _} = socket:bind(Sock, #{family => inet, + addr => Addr}), + ok = socket:connect(Sock, #{family => inet, + addr => SAddr, + port => SPort}), + Msg = list_to_binary("hello"), + ok = socket:send(Sock, Msg), + ok = socket:shutdown(Sock, write), + {ok, Msg} = socket:recv(Sock), + ok = socket:close(Sock). + +server(Addr, Port) -> + {ok, LSock} = socket:open(inet, stream, tcp), + {ok, _} = socket:bind(LSock, #{family => inet, + port => Port, + addr => Addr}), + ok = socket:listen(LSock), + {ok, Sock} = socket:accept(LSock), + {ok, Msg} = socket:recv(Sock), + ok = socket:send(Sock, Msg), + ok = socket:shutdown(Sock, write), + ok = socket:close(Sock), + ok = socket:close(LSock). + </code> + </section> +</erlref> + diff --git a/erts/doc/src/socket_usage.xml b/erts/doc/src/socket_usage.xml new file mode 100644 index 0000000000..e0f006e618 --- /dev/null +++ b/erts/doc/src/socket_usage.xml @@ -0,0 +1,773 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2018</year><year>2019</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>Socket Usage</title> + <prepared>Micael Karlberg</prepared> + <docno></docno> + <date>2018-07-17</date> + <rev>PA1</rev> + <file>socket_usage.xml</file> + </header> + + <section> + <title>Introduction</title> + <p>The socket interface (module) is basically an "thin" layer on top of + the OS socket interface. It is assumed that, unless you have special needs, + gen_[tcp|udp|sctp] should be sufficent. </p> + <p>Note that just because we have a documented and described option, + it does <em>not</em> mean that the OS supports it. So its recommended + that the user reads the platform specific documentation for the + option used. </p> + </section> + + <section> + <marker id="socket_options"></marker> + <title>Socket Options</title> + + <p>Options for level <c>otp</c>: </p> + <table> + <row> + <cell><em>Option Name</em></cell> + <cell><em>Value Type</em></cell> + <cell><em>Set</em></cell> + <cell><em>Get</em></cell> + <cell><em>Other Requirements and comments</em></cell> + </row> + <row> + <cell>assoc_id</cell> + <cell>integer()</cell> + <cell>no</cell> + <cell>yes</cell> + <cell>type = seqpacket, protocol = sctp, is an association</cell> + </row> + <row> + <cell>debug</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>iow</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>controlling_process</cell> + <cell>pid()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>rcvbuf</cell> + <cell>default | pos_integer() | {pos_integer(), pos_ineteger()}</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>'default' only valid for set. + The tuple form is only valid for type 'stream' and protocol 'tcp'.</cell> + </row> + <row> + <cell>rcvctrlbuf</cell> + <cell>default | pos_integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>default only valid for set</cell> + </row> + <row> + <cell>sndctrlbuf</cell> + <cell>default | pos_integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>default only valid for set</cell> + </row> + <row> + <cell>fd</cell> + <cell>integer()</cell> + <cell>no</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <tcaption>option levels</tcaption> + </table> + + <p>Options for level <c>socket</c>: </p> + <table> + <row> + <cell><em>Option Name</em></cell> + <cell><em>Value Type</em></cell> + <cell><em>Set</em></cell> + <cell><em>Get</em></cell> + <cell><em>Other Requirements and comments</em></cell> + </row> + <row> + <cell>acceptcon</cell> + <cell>boolean()</cell> + <cell>no</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>bindtodevice</cell> + <cell>string()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>broadcast</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram</cell> + </row> + <row> + <cell>debug</cell> + <cell>integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>requires admin capability</cell> + </row> + <row> + <cell>domain</cell> + <cell>domain()</cell> + <cell>no</cell> + <cell>yes</cell> + <cell><em>Not</em> on FreeBSD (for instance)</cell> + </row> + <row> + <cell>dontroute</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>keepalive</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>linger</cell> + <cell>abort | linger()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>oobinline</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>peek_off</cell> + <cell>integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>domain = local (unix)</cell> + </row> + <row> + <cell>priority</cell> + <cell>integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>protocol</cell> + <cell>protocol()</cell> + <cell>no</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>rcvbuf</cell> + <cell>non_neg_integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>rcvlowat</cell> + <cell>non_neg_integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>rcvtimeo</cell> + <cell>timeval()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>reuseaddr</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>reuseport</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>domain = inet | inet6</cell> + </row> + <row> + <cell>sndbuf</cell> + <cell>non_neg_integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>sndlowat</cell> + <cell>non_neg_integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>not changeable on Linux</cell> + </row> + <row> + <cell>sndtimeo</cell> + <cell>timeval()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>timestamp</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>type</cell> + <cell>type()</cell> + <cell>no</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <tcaption>socket options</tcaption> + </table> + + <p>Options for level <c>ip</c>: </p> + <table> + <row> + <cell><em>Option Name</em></cell> + <cell><em>Value Type</em></cell> + <cell><em>Set</em></cell> + <cell><em>Get</em></cell> + <cell><em>Other Requirements and comments</em></cell> + </row> + <row> + <cell>add_membership</cell> + <cell>ip_mreq()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <row> + <cell>add_source_membership</cell> + <cell>ip_mreq_source()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <row> + <cell>block_source</cell> + <cell>ip_mreq_source()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <row> + <cell>drop_membership</cell> + <cell>ip_mreq()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <row> + <cell>drop_source_membership</cell> + <cell>ip_mreq_source()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <row> + <cell>freebind</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>hdrincl</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = raw</cell> + </row> + <row> + <cell>minttl</cell> + <cell>integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = raw</cell> + </row> + <row> + <cell>msfilter</cell> + <cell>null | ip_msfilter()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <row> + <cell>mtu</cell> + <cell>integer()</cell> + <cell>no</cell> + <cell>yes</cell> + <cell>type = raw</cell> + </row> + <row> + <cell>mtu_discover</cell> + <cell>ip_pmtudisc()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>multicast_all</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>multicast_if</cell> + <cell>any | ip4_address()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>multicast_loop</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>multicast_ttl</cell> + <cell>uint8()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>nodefrag</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = raw</cell> + </row> + <row> + <cell>pktinfo</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram</cell> + </row> + <row> + <cell>recvdstaddr</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram</cell> + </row> + <row> + <cell>recverr</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>recvif</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram | raw</cell> + </row> + <row> + <cell>recvopts</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type =/= stream</cell> + </row> + <row> + <cell>recvorigdstaddr</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>recvttl</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type =/= stream</cell> + </row> + <row> + <cell>retopts</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type =/= stream</cell> + </row> + <row> + <cell>router_alert</cell> + <cell>integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = raw</cell> + </row> + <row> + <cell>sendsrcaddr</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>tos</cell> + <cell>ip_tos()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>some high-priority levels may require superuser capability</cell> + </row> + <row> + <cell>transparent</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>requires admin capability</cell> + </row> + <row> + <cell>ttl</cell> + <cell>integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>unblock_source</cell> + <cell>ip_mreq_source()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <tcaption>ip options</tcaption> + </table> + + <p>Options for level <c>ipv6</c>: </p> + <table> + <row> + <cell><em>Option Name</em></cell> + <cell><em>Value Type</em></cell> + <cell><em>Set</em></cell> + <cell><em>Get</em></cell> + <cell><em>Other Requirements and comments</em></cell> + </row> + <row> + <cell>addrform</cell> + <cell>inet</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>allowed only for IPv6 sockets that are connected and bound to a + v4-mapped-on-v6 address</cell> + </row> + <row> + <cell>add_membership</cell> + <cell>ipv6_mreq()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <row> + <cell>authhdr</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram | raw, obsolete?</cell> + </row> + <row> + <cell>drop_membership</cell> + <cell>ipv6_mreq()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <row> + <cell>dstopts</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram | raw, requires superuser privileges to update</cell> + </row> + <row> + <cell>flowinfo</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram | raw, requires superuser privileges to update</cell> + </row> + <row> + <cell>hoplimit</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram | raw, requires superuser privileges to update</cell> + </row> + <row> + <cell>hopopts</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram | raw, requires superuser privileges to update</cell> + </row> + <row> + <cell>mtu</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>Get: Only after the socket has been connected</cell> + </row> + <row> + <cell>mtu_discover</cell> + <cell>ipv6_pmtudisc()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>multicast_hops</cell> + <cell>default | uint8()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>multicast_if</cell> + <cell>integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram | raw</cell> + </row> + <row> + <cell>multicast_loop</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>recverr</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>recvpktinfo | pktinfo</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram | raw</cell> + </row> + <row> + <cell>router_alert</cell> + <cell>integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = raw</cell> + </row> + <row> + <cell>rthdr</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>type = dgram | raw, requires superuser privileges to update</cell> + </row> + <row> + <cell>unicast_hops</cell> + <cell>default | uint8()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>v6only</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <tcaption>ipv6 options</tcaption> + </table> + + <p>Options for level <c>tcp</c>: </p> + <table> + <row> + <cell><em>Option Name</em></cell> + <cell><em>Value Type</em></cell> + <cell><em>Set</em></cell> + <cell><em>Get</em></cell> + <cell><em>Other Requirements and comments</em></cell> + </row> + <row> + <cell>congestion</cell> + <cell>string()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>maxseg</cell> + <cell>integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>nodelay</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <tcaption>tcp options</tcaption> + </table> + + <p>Options for level <c>udp</c>: </p> + <table> + <row> + <cell><em>Option Name</em></cell> + <cell><em>Value Type</em></cell> + <cell><em>Set</em></cell> + <cell><em>Get</em></cell> + <cell><em>Other Requirements and comments</em></cell> + </row> + <row> + <cell>cork</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <tcaption>udp options</tcaption> + </table> + + <p>Options for level <c>sctp</c>: </p> + <table> + <row> + <cell><em>Option Name</em></cell> + <cell><em>Value Type</em></cell> + <cell><em>Set</em></cell> + <cell><em>Get</em></cell> + <cell><em>Other Requirements and comments</em></cell> + </row> + <row> + <cell>associnfo</cell> + <cell>sctp_assocparams()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>autoclose</cell> + <cell>non_neg_integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>disable_fragments</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>events</cell> + <cell>sctp_event_subscribe()</cell> + <cell>yes</cell> + <cell>no</cell> + <cell>none</cell> + </row> + <row> + <cell>initmsg</cell> + <cell>sctp_initmsg()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>maxseg</cell> + <cell>non_neg_integer()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>nodelay</cell> + <cell>boolean()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <row> + <cell>rtoinfo</cell> + <cell>sctp_rtoinfo()</cell> + <cell>yes</cell> + <cell>yes</cell> + <cell>none</cell> + </row> + <tcaption>sctp options</tcaption> + </table> + + </section> +</chapter> + diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml index 0b943e6295..68fab5edf1 100644 --- a/erts/doc/src/specs.xml +++ b/erts/doc/src/specs.xml @@ -5,6 +5,8 @@ <xi:include href="../specs/specs_erl_tracer.xml"/> <xi:include href="../specs/specs_init.xml"/> <xi:include href="../specs/specs_persistent_term.xml"/> + <xi:include href="../specs/specs_socket.xml"/> + <xi:include href="../specs/specs_net.xml"/> <xi:include href="../specs/specs_zlib.xml"/> <xi:include href="../specs/specs_atomics.xml"/> <xi:include href="../specs/specs_counters.xml"/> |