diff options
Diffstat (limited to 'erts/doc/src')
| -rw-r--r-- | erts/doc/src/Makefile | 40 | ||||
| -rw-r--r-- | erts/doc/src/alt_dist.xml | 5 | ||||
| -rw-r--r-- | erts/doc/src/crash_dump.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/driver.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl_dist_protocol.xml | 60 | ||||
| -rw-r--r-- | erts/doc/src/erl_ext_dist.xml | 52 | ||||
| -rw-r--r-- | erts/doc/src/erl_ext_fig.gif | bin | 3834 -> 3840 bytes | |||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 17 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 22 | ||||
| -rw-r--r-- | erts/doc/src/net.xml | 129 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 772 | ||||
| -rw-r--r-- | erts/doc/src/part.xml.src (renamed from erts/doc/src/part.xml) | 4 | ||||
| -rw-r--r-- | erts/doc/src/ref_man.xml.src (renamed from erts/doc/src/ref_man.xml) | 5 | ||||
| -rw-r--r-- | erts/doc/src/socket.xml | 490 | ||||
| -rw-r--r-- | erts/doc/src/socket_usage.xml | 82 | ||||
| -rw-r--r-- | erts/doc/src/specs.xml.src (renamed from erts/doc/src/specs.xml) | 3 | ||||
| -rw-r--r-- | erts/doc/src/zlib.xml | 2 |
17 files changed, 1406 insertions, 281 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index bc01919da1..bb96293947 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2018. All Rights Reserved. +# Copyright Ericsson AB 1997-2019. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -47,6 +47,20 @@ XML_REF1_FILES = epmd.xml \ run_erl.xml \ start.xml +ifeq ($(USE_ESOCK), yes) +XML_REF3_ESOCK_EFILES = socket.xml +XML_CHAPTER_ESOCK_EFILES = socket_usage.xml +ESOCK_USE_SOCKET_XML=<xi:include href="socket.xml"\/> +ESOCK_USE_SOCKET_SPECS_XML=<xi:include href="../specs/specs_socket.xml"/> +ESOCK_USE_SOCKET_USAGE_XML=<xi:include href="socket_usage.xml"/> +else +XML_REF3_ESOCK_EFILES = +XML_CHAPTER_ESOCK_EFILES = +ESOCK_USE_SOCKET_XML = +ESOCK_USE_SOCKET_SPECS_XML = +ESOCK_USE_SOCKET_USAGE_XML = +endif + XML_REF3_EFILES = \ erl_prim_loader.xml \ erlang.xml \ @@ -56,8 +70,7 @@ XML_REF3_EFILES = \ atomics.xml \ counters.xml \ zlib.xml \ - socket.xml \ - net.xml + $(XML_REF3_ESOCK_EFILES) XML_REF3_FILES = \ $(XML_REF3_EFILES) \ @@ -94,7 +107,7 @@ XML_CHAPTER_FILES = \ driver.xml \ absform.xml \ inet_cfg.xml \ - socket_usage.xml \ + $(XML_CHAPTER_ESOCK_EFILES) \ erl_ext_dist.xml \ erl_dist_protocol.xml \ communication.xml \ @@ -159,7 +172,7 @@ $(HTMLDIR)/%.gif: %.gif $(XML_FIGURE_DIR)/%.png: ../../emulator/internal_doc/figures/%.png $(INSTALL_DATA) $< $@ -docs: figures man pdf html $(INFO_FILE) +docs: part ref_man specs figures man pdf html $(INFO_FILE) $(TOP_PDF_FILE): $(XML_FILES) @@ -169,6 +182,10 @@ html: gifs $(HTML_REF_MAN_FILE) man: $(MAN1_FILES) $(MAN3_FILES) +ref_man: ref_man.xml +part: part.xml +specs: specs.xml + gifs: $(GIF_FILES:%=$(HTMLDIR)/%) $(INFO_FILE): $(INFO_FILE_SRC) $(ERL_TOP)/make/$(TARGET)/otp.mk @@ -196,6 +213,19 @@ $(SPECDIR)/specs_%.xml: $(XMLDIR)/%.xml: ../../emulator/internal_doc/%.md $(ERL_TOP)/make/emd2exml $(ERL_TOP)/make/emd2exml $< $@ +ref_man.xml: ref_man.xml.src + ($(PERL) -p -e 's?%ESOCK_USE_SOCKET_XML%?$(ESOCK_USE_SOCKET_XML)?' \ + $<) > $@ + +part.xml: part.xml.src + ($(PERL) -p -e 's?%ESOCK_USE_SOCKET_USAGE_XML%?$(ESOCK_USE_SOCKET_USAGE_XML)?' \ + $<) > $@ + +specs.xml: specs.xml.src + ($(PERL) -p -e 's?%ESOCK_USE_SOCKET_SPECS_XML%?$(ESOCK_USE_SOCKET_SPECS_XML)?' \ + $<) > $@ + + # ---------------------------------------------------- # Release Target # ---------------------------------------------------- diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml index 7c997cae20..f72e8acd2c 100644 --- a/erts/doc/src/alt_dist.xml +++ b/erts/doc/src/alt_dist.xml @@ -680,7 +680,10 @@ of the distribution controller, <c>Received</c> is received packets, <c>Sent</c> is sent packets, and <c>PendSend</c> is - amount of packets in queue to be sent + amount of data in queue to be sent + (typically in bytes, but <c>dist_util</c> + only checks whether the value is non-zero + to know there is data in queue) or a <c>boolean()</c> indicating whether there are packets in queue to be sent. </p> diff --git a/erts/doc/src/crash_dump.xml b/erts/doc/src/crash_dump.xml index 33d0903622..876834307a 100644 --- a/erts/doc/src/crash_dump.xml +++ b/erts/doc/src/crash_dump.xml @@ -289,7 +289,7 @@ Slogan: <reason></pre> <marker id="memory"></marker> <title>Memory Information</title> <p>Under the tag <em>=memory</em> is shown information similar - to what can be obtainted on a living node with + to what can be obtained on a living node with <seealso marker="erts:erlang#memory/0"> <c>erlang:memory()</c></seealso>.</p> </section> diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml index 8f31df4cad..a873bf9931 100644 --- a/erts/doc/src/driver.xml +++ b/erts/doc/src/driver.xml @@ -391,7 +391,7 @@ void encode_result(ei_x_buff* x, PGresult* res, PGconn* conn) <p>Before a driver can be called from Erlang, it must be loaded and opened. Loading is done using the <c><![CDATA[erl_ddll]]></c> module (the <c><![CDATA[erl_ddll]]></c> driver that loads dynamic - driver is actually a driver itself). If loading is successfull, + driver is actually a driver itself). If loading is successful, the port can be opened with <c><![CDATA[open_port/2]]></c>. The port name must match the name of the shared library and the name in the driver entry structure.</p> diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index f924c8a70b..0c1100d394 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -109,7 +109,8 @@ <title>Register a Node in EPMD</title> <p>When a distributed node is started it registers itself in the EPMD. The message <c>ALIVE2_REQ</c> described below is sent from the node to - the EPMD. The response from the EPMD is <c>ALIVE2_RESP</c>.</p> + the EPMD. The response from the EPMD is <c>ALIVE2_X_RESP</c> (or + <c>ALIVE2_RESP</c>).</p> <table align="left"> <row> @@ -155,12 +156,12 @@ <tag><c>HighestVersion</c></tag> <item> <p>The highest distribution version that this node can handle. - The value in Erlang/OTP R6B and later is 5.</p> + The value in OTP 23 and later is 6.</p> </item> <tag><c>LowestVersion</c></tag> <item> <p>The lowest distribution version that this node can handle. - The value in Erlang/OTP R6B and later is 5.</p> + The value in OTP 23 and later is 5.</p> </item> <tag><c>Nlen</c></tag> <item> @@ -184,7 +185,24 @@ node is a distributed node. When the connection is closed, the node is automatically unregistered from the EPMD.</p> - <p>The response message <c>ALIVE2_RESP</c> is as follows:</p> + <p>The response message is either <c>ALIVE2_X_RESP</c> or + <c>ALIVE2_RESP</c> depending on distribution version. If both the node + and EPMD support distribution version 6 then response is + <c>ALIVE2_X_RESP</c> otherwise it is the older <c>ALIVE2_RESP</c>:</p> + + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">1</cell> + <cell align="center">4</cell> + </row> + <row> + <cell align="center"><c>118</c></cell> + <cell align="center"><c>Result</c></cell> + <cell align="center"><c>Creation</c></cell> + </row> + <tcaption>ALIVE2_X_RESP (118) with 32 bit creation</tcaption> + </table> <table align="left"> <row> @@ -197,7 +215,7 @@ <cell align="center"><c>Result</c></cell> <cell align="center"><c>Creation</c></cell> </row> - <tcaption>ALIVE2_RESP (121)</tcaption> + <tcaption>ALIVE2_RESP (121) with 16-bit creation</tcaption> </table> <p>Result = 0 -> ok, result > 0 -> error.</p> @@ -793,7 +811,8 @@ DiB == gen_digest(ChA, ICA)? </item> <tag><c>-define(DFLAG_NEW_FUN_TAGS,16#80).</c></tag> <item> - <p>The node understand new fun tags.</p> + <p>The node understands the <seealso marker="erl_ext_dist#NEW_FUN_EXT"> + <c>NEW_FUN_EXT</c></seealso> tag.</p> </item> <tag><c>-define(DFLAG_EXTENDED_PIDS_PORTS,16#100).</c></tag> <item> @@ -802,13 +821,18 @@ DiB == gen_digest(ChA, ICA)? </item> <tag><c>-define(DFLAG_EXPORT_PTR_TAG,16#200).</c></tag> <item> + <p>The node understands the <seealso marker="erl_ext_dist#EXPORT_EXT"> + <c>EXPORT_EXT</c></seealso> tag.</p> </item> <tag><c>-define(DFLAG_BIT_BINARIES,16#400).</c></tag> <item> + <p>The node understands the <seealso marker="erl_ext_dist#BIT_BINARY_EXT"> + <c>BIT_BINARY_EXT</c></seealso> tag.</p> </item> <tag><c>-define(DFLAG_NEW_FLOATS,16#800).</c></tag> <item> - <p>The node understands new float format.</p> + <p>The node understands the <seealso marker="erl_ext_dist#NEW_FLOAT_EXT"> + <c>NEW_FLOAT_EXT</c></seealso> tag.</p> </item> <tag><c>-define(DFLAG_UNICODE_IO,16#1000).</c></tag> <item> @@ -817,21 +841,34 @@ DiB == gen_digest(ChA, ICA)? <item> <p>The node implements atom cache in distribution header.</p> </item> + <marker id="DFLAG_SMALL_ATOM_TAGS"/> <tag><c>-define(DFLAG_SMALL_ATOM_TAGS, 16#4000).</c></tag> <item> - <p>The node understand the <c>SMALL_ATOM_EXT</c> tag.</p> + <p>The node understands the <seealso marker="erl_ext_dist#SMALL_ATOM_EXT"> + <c>SMALL_ATOM_EXT</c></seealso> tag.</p> </item> + <marker id="DFLAG_UTF8_ATOMS"/> <tag><c>-define(DFLAG_UTF8_ATOMS, 16#10000).</c></tag> <item> - <p>The node understand UTF-8 encoded atoms.</p> + <p>The node understands UTF-8 atoms encoded with + <seealso marker="erl_ext_dist#ATOM_UTF8_EXT"> + <c>ATOM_UTF8_EXT</c></seealso> and + <seealso marker="erl_ext_dist#SMALL_ATOM_UTF8_EXT"> + <c>SMALL ATOM_UTF8_EXT</c></seealso>.</p> </item> <tag><c>-define(DFLAG_MAP_TAG, 16#20000).</c></tag> <item> - <p>The node understand the map tag.</p> + <p>The node understands the map tag + <seealso marker="erl_ext_dist#MAP_EXT"><c>MAP_EXT</c></seealso>.</p> </item> + <marker id="DFLAG_BIG_CREATION"/> <tag><c>-define(DFLAG_BIG_CREATION, 16#40000).</c></tag> <item> - <p>The node understand big node creation.</p> + <p>The node understands big node creation tags + <seealso marker="erl_ext_dist#NEW_PID_EXT"><c>NEW_PID_EXT</c></seealso>, + <seealso marker="erl_ext_dist#NEW_PORT_EXT"><c>NEW_PORT_EXT</c></seealso> and + <seealso marker="erl_ext_dist#NEWER_REFERENCE_EXT"><c>NEWER_REFERENCE_EXT</c></seealso>. + </p> </item> <tag><c>-define(DFLAG_SEND_SENDER, 16#80000).</c></tag> <item> @@ -855,6 +892,7 @@ DiB == gen_digest(ChA, ICA)? <seealso marker="#control_message">control message</seealso>s instead of the non-PAYLOAD variants.</p> </item> + <marker id="DFLAG_FRAGMENTS"/> <tag><c>-define(DFLAG_FRAGMENTS, 16#800000).</c></tag> <item> <p>Use <seealso marker="erl_ext_dist#fragments">fragmented</seealso> diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index 3730f0e8ac..c5b2ce1a0a 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -128,7 +128,7 @@ are deprecated and are only kept for backward compatibility when decoding terms encoded by older nodes.</p> <p>Support for UTF-8 encoded atoms in the external format has been - available since ERTS 5.10 (OTP R16). This abillity allows such old nodes + available since ERTS 5.10 (OTP R16). This ability allows such old nodes to decode, store and encode any Unicode atoms received from a new OTP 20 node.</p> <p>The maximum number of allowed characters in an atom is 255. In the @@ -264,7 +264,7 @@ consists of. Length is a 2 byte big-endian integer if flag <c>LongAtoms</c> has been set, otherwise a 1 byte integer. When distribution flag - <seealso marker="erl_dist_protocol#dflags"> + <seealso marker="erl_dist_protocol#DFLAG_UTF8_ATOMS"> <c>DFLAG_UTF8_ATOMS</c></seealso> has been exchanged between both nodes in the <seealso marker="erl_dist_protocol#distribution_handshake"> @@ -316,8 +316,8 @@ </p> <p>Fragmented distribution messages are only used if the receiving node signals that it supports them via the - <seealso marker="erl_dist_protocol#dflags">DFLAG_FRAGMENTS</seealso> distribution - flag.</p> + <seealso marker="erl_dist_protocol#DFLAG_FRAGMENTS">DFLAG_FRAGMENTS</seealso> + distribution flag.</p> <p>A process must complete the sending of a fragmented message before it can start sending any other message on the same distribution channel.</p> @@ -637,11 +637,14 @@ <seealso marker="#NEW_PID_EXT"><c>NEW_PID_EXT</c></seealso>. Port operations are not allowed across node boundaries. </p> - <p>Introduced in OTP 19, but only to be decoded and echoed back. Not - encoded for local ports. Planned to supersede <seealso marker="#PORT_EXT"> - <c>PORT_EXT</c></seealso> in OTP 23 when - <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_BIG_CREATON</c></seealso> - becomes mandatory. + <p><c>NEW_PORT_EXT</c> was introduced in OTP 19, but only to be decoded + and echoed back. Not encoded for local ports. + </p> + <p>In OTP 23 distribution flag + <seealso marker="erl_dist_protocol#DFLAG_BIG_CREATION"><c>DFLAG_BIG_CREATION</c></seealso> + became mandatory. All ports are now + encoded using <c>NEW_PORT_EXT</c>, even external ports received as <seealso + marker="#PORT_EXT"><c>PORT_EXT</c></seealso> from older nodes. </p> </section> @@ -719,11 +722,14 @@ erlang:list_to_pid/1</seealso>).</p> </item> </taglist> - <p>Introduced in OTP 19, but only to be decoded and echoed back. Not - encoded for local processes. Planned to supersede <seealso marker="#PID_EXT"> - <c>PID_EXT</c></seealso> in OTP 23 when - <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_BIG_CREATON</c></seealso> - becomes mandatory. + <p><c>NEW_PID_EXT</c> was introduced in OTP 19, but only to be decoded + and echoed back. Not encoded for local processes. + </p> + <p>In OTP 23 distribution flag + <seealso marker="erl_dist_protocol#DFLAG_BIG_CREATION"><c>DFLAG_BIG_CREATION</c></seealso> + became mandatory. All pids are now encoded using <c>NEW_PID_EXT</c>, + even external pids received as + <seealso marker="#PID_EXT"><c>PID_EXT</c></seealso> from older nodes. </p> </section> @@ -913,7 +919,7 @@ <tcaption>SMALL_BIG_EXT</tcaption></table> <p> Bignums are stored in unary form with a <c>Sign</c> byte, - that is, 0 if the binum is positive and 1 if it is negative. The + that is, 0 if the bignum is positive and 1 if it is negative. The digits are stored with the least significant byte stored first. To calculate the integer, the following formula can be used: </p> @@ -1047,11 +1053,15 @@ <seealso marker="#NEW_PID_EXT"><c>NEW_PID_EXT</c></seealso>.</p> </item> </taglist> - <p>Introduced in OTP 19, but only to be decoded and echoed back. Not - encoded for local references. Planned to supersede <seealso marker="#NEW_REFERENCE_EXT"> - <c>NEW_REFERENCE_EXT</c></seealso> in OTP 23 when - <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_BIG_CREATON</c></seealso> - becomes mandatory. + <p><c>NEWER_REFERENCE_EXT</c> was introduced in OTP 19, but only to be decoded + and echoed back. Not encoded for local references. + </p> + <p>In OTP 23 distribution flag + <seealso marker="erl_dist_protocol#DFLAG_BIG_CREATION"><c>DFLAG_BIG_CREATION</c></seealso> + became mandatory. All references are now encoded using + <c>NEWER_REFERENCE_EXT</c>, even external references received as + <seealso marker="#NEW_REFERENCE_EXT"><c>NEW_REFERENCE_EXT</c></seealso> + from older nodes. </p> </section> @@ -1408,7 +1418,7 @@ <p> <c>SMALL_ATOM_EXT</c> was introduced in ERTS 5.7.2 and require an exchange of distribution flag - <seealso marker="erl_dist_protocol#dflags"> + <seealso marker="erl_dist_protocol#DFLAG_SMALL_ATOM_TAGS"> <c>DFLAG_SMALL_ATOM_TAGS</c></seealso> in the <seealso marker="erl_dist_protocol#distribution_handshake"> distribution handshake</seealso>. diff --git a/erts/doc/src/erl_ext_fig.gif b/erts/doc/src/erl_ext_fig.gif Binary files differindex 14d6bbc871..40dd17bd5e 100644 --- a/erts/doc/src/erl_ext_fig.gif +++ b/erts/doc/src/erl_ext_fig.gif diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index c0be715678..d74ae23a93 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -1090,7 +1090,7 @@ typedef struct { </func> <func> - <name since="OTP @OTP-15011@"><ret>int</ret> + <name since="OTP 22.0"><ret>int</ret> <nametext>enif_compare_pids(const ErlNifPid *pid1, const ErlNifPid *pid2) </nametext></name> <fsummary>Compare two pids.</fsummary> @@ -1495,6 +1495,9 @@ enif_free_iovec(iovec);]]></code> <c>term</c>.</p> <p>Returns <c>true</c> on success, or <c>false</c> if <c>term</c> is not a handle to a resource object of type <c>type</c>.</p> + <p><c>enif_get_resource</c> does not add a reference to the resource + object. However, the pointer received in <c>*objp</c> is guaranteed to + be valid at least as long as the resource handle <c>term</c> is valid.</p> </desc> </func> @@ -1890,7 +1893,7 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> - <name since="OTP @OTP-15011@"><ret>int</ret> + <name since="OTP 22.0"><ret>int</ret> <nametext>enif_is_pid_undefined(const ErlNifPid* pid)</nametext></name> <fsummary>Determine if pid is undefined.</fsummary> <desc> @@ -2247,7 +2250,7 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> - <name since="OTP @OTP-15362@"><ret>ERL_NIF_TERM</ret> + <name since="OTP 22.0"><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> @@ -2947,6 +2950,10 @@ enif_map_iterator_destroy(env, &iter);</code> References made by <seealso marker="#enif_make_resource"> <c>enif_make_resource</c></seealso> can only be removed by the garbage collector.</p> + <p>There are no guarantees exactly when the destructor of an + unreferenced resource is called. It could be called directly by + <c>enif_release_resource</c> but it could also be scheduled to be + called at a later time possibly by another thread.</p> </desc> </func> @@ -3306,7 +3313,7 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { </func> <func> - <name since="OTP @OTP-15011@"><ret>void</ret> + <name since="OTP 22.0"><ret>void</ret> <nametext>enif_set_pid_undefined(ErlNifPid* pid)</nametext></name> <fsummary>Set pid as undefined.</fsummary> <desc> @@ -3369,7 +3376,7 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { </func> <func> - <name since="OTP @OTP-15640@"><ret>ErlNifTermType</ret> + <name since="OTP 22.0"><ret>ErlNifTermType</ret> <nametext>enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)</nametext> </name> <fsummary>Determine the type of a term.</fsummary> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 2b444ccf01..0e82ceba7d 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -1297,7 +1297,7 @@ end</code> </func> <func> - <name name="dist_ctrl_get_opt" arity="2" clause_i="1" since="OTP @OTP-15617@"/> + <name name="dist_ctrl_get_opt" arity="2" clause_i="1" since="OTP 22.0"/> <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 @@ -1428,7 +1428,7 @@ end</code> </func> <func> - <name name="dist_ctrl_set_opt" arity="3" clause_i="1" since="OTP @OTP-15617@"/> + <name name="dist_ctrl_set_opt" arity="3" clause_i="1" since="OTP 22.0"/> <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 @@ -3105,6 +3105,7 @@ false</code> Map = #{42 => value_two,1337 => "value one","a" => 1}, map_get(Key,Map). "value one"</code> + <p>Allowed in guard tests.</p> </desc> </func> @@ -9412,6 +9413,18 @@ Metadata = #{ pid => pid(), <p>Returns the previous system monitor settings just like <seealso marker="#system_monitor/0"> <c>erlang:system_monitor/0</c></seealso>.</p> + <p>The arguments to <c>system_monitor/2</c> specifies how all + system monitoring on the node should be done, not how it should be + changed. This means only one process at a time + (<c><anno>MonitorPid</anno></c>) can be the receiver of system monitor + messages. Also, the way to clear a specific monitor option + is to not include it in the list <c><anno>Options</anno></c>. All + system monitoring will, however, be cleared if the process identified by + <c><anno>MonitorPid</anno></c> terminates.</p> + <p>There are no special option values (like zero) to clear an option. + Some of the options have a unspecified minimum value. Lower values + will be adjusted to the minimum value. For example, it is currently not + possible to monitor all garbage collections with <c>{long_gc, 0}</c>.</p> <note> <p>If a monitoring process gets so large that it itself starts to cause system monitor messages when garbage @@ -10116,6 +10129,11 @@ timestamp() -> time stamp flags are remembered, so if two are passed and the one with highest precedence later is disabled, the other one becomes active.</p> + <p>If a match specification (applicable only for <c>call</c>, <c>send</c> + and <c>'receive'</c> tracing) contains a <c>{message}</c> action + function with a non-boolean value, that value is added as an extra + element to the message tuple either in the last position or before + the timestamp (if it is present).</p> <p>Trace messages:</p> <marker id="trace_3_trace_messages"></marker> <taglist> diff --git a/erts/doc/src/net.xml b/erts/doc/src/net.xml deleted file mode 100644 index b9e2cffce9..0000000000 --- a/erts/doc/src/net.xml +++ /dev/null @@ -1,129 +0,0 @@ -<?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 f0f97a6775..5ca387ffd8 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -31,6 +31,761 @@ </header> <p>This document describes the changes made to the ERTS application.</p> +<section><title>Erts 10.4.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + An invalid value test caused the socket:setopt(Socket, + ip, add_membership, ip_mreq()) to fail with badarg. The + same for drop_membership.</p> + <p> + Own Id: OTP-15908 Aux Id: ERL-980 </p> + </item> + <item> + <p> + Fixed bug causing VM crash when doing textual dump of a + process containing an unhandled monitor down signal. + Textual process dumps can be done with + <c>erlang:system_info(procs)</c>, trace feature + <c>process_dump</c>, Erlang shell break menu and a + crashdump. Bug exist since OTP 21.0.</p> + <p> + Own Id: OTP-15909 Aux Id: ERL-979 </p> + </item> + <item> + <p><c>lists:subtract/2</c> would produce incorrect + results for some inputs on 64-bit platforms.</p> + <p> + Own Id: OTP-15938 Aux Id: ERL-986 </p> + </item> + <item> + <p>Fixed a bug in the loader that was similar to + <c>OTP-15938</c>, yielding incorrect code for some inputs + on 64-bit platforms.</p> + <p> + Own Id: OTP-15939</p> + </item> + <item> + <p> + Fixed bug causing scheduler threads in rare cases to + block spinnning indefinitely. Bug exists since OTP 21.0.</p> + <p> + Own Id: OTP-15941 Aux Id: PR-2313 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.4.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a buffer overflow when + <c>binary_to_existing_atom/2</c> and + <c>list_to_existing_atom/2</c> was used with the + <c>latin1</c> encoding.</p> + <p> + Own Id: OTP-15819 Aux Id: ERL-944 </p> + </item> + <item> + <p> + The runtime system disconnected a connection if it + received an <c>exit/2</c> signal where the recipient was + a process on an old incarnation of the current node. That + is, the receiving node had the same node name, but + another "creation" number. The signal will now just be + dropped since the receiving process no longer exists.</p> + <p> + Own Id: OTP-15867 Aux Id: ERIERL-373 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.4.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed <c>process_info(Pid,reductions)</c> to not + categorically increase reduction count of the measured + process <c>Pid</c>. Repeated reduction measure of an idle + process will most often (but not guaranteed) return the + same value, like it behaved before OTP 21.3.8.</p> + <p> + Own Id: OTP-15865 Aux Id: ERL-964 </p> + </item> + <item> + <p>Fixed an incorrect load-time optimization that could + cause a crash when extracting deeply nested tuple + elements.</p> + <p> + Own Id: OTP-15871 Aux Id: ERIERL-374 </p> + </item> + <item> + <p> + Fix bug causing VM crash when pressing P for "proc info" + in Erlang shell break menu. Bug exists since OTP 22.0.</p> + <p> + Own Id: OTP-15873 Aux Id: ERL-965 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.4.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>In nested use of <c>try</c>/<c>catch</c>, rethrowing + an exception using <c>erlang:raise/3</c> with a different + class would not always be able to change the class of the + exception.</p> + <p> + Own Id: OTP-15834 Aux Id: ERIERL-367 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Do not allocate new bitstring/binary when an empty binary + is appended.</p> + <p> + Own Id: OTP-15535 Aux Id: PR-2055 </p> + </item> + <item> + <p> + Document that <c>process_info(_, current_function)</c> + can return <c>{current_function, undefined}</c> in case + of execution of native code.</p> + <p> + Own Id: OTP-15543 Aux Id: PR-2089 </p> + </item> + <item> + <p> + Fixed bug in <c>ets:select</c>, <c>ets:match</c> and + friends which could cause the table to remain fixated (as + if <c>ets:safe_fixtable</c> had been called) after the + call returned. This could happen for <c>protected</c> + tables if another concurrent running process transferred + table ownership to the process during its + ets:select/match call. Ownership can be transferred using + either <c>ets:give_away</c> or the <c>heir</c> table + option.</p> + <p> + Own Id: OTP-15672</p> + </item> + <item> + <p>Fixed a Windows-specific bug in <c>file:list_dir/1</c> + that caused it to misbehave on network shares.</p> + <p> + Own Id: OTP-15693</p> + </item> + <item> + <p> + Fixed bug when calling <c>enif_whereis_*</c> from NIF + resource destructor. Symptoms could be emulator crash or + hanging scheduler threads.</p> + <p> + Own Id: OTP-15694 Aux Id: ERL-863 </p> + </item> + <item> + <p>Fixed a bug in the error case of <c>apply/3</c>, where + the exception would erroneously have an empty argument + list in some cases.</p> + <p> + Own Id: OTP-15698</p> + </item> + <item> + <p>A bug has been fixed in the <c>maps</c> implementation + that could cause a crash or memory usage to grow until + the machine ran out of memory. This could happen when + inserting a new key-value pair with a key <c>K1</c> + containing a binary <c>B1</c> into a map <c>M</c> having + a key <c>K2</c> with a binary <c>B2</c> if the following + conditions were met:</p> <list> <item><c>B1 =/= + B2</c></item> <item><c>size(B1) >= 4294967296</c></item> + <item><c>size(B2) >= 4294967296</c></item> + <item><c>size(M) >= 32</c></item> <item><c>(size(B1) rem + 4294967296) == (size(B2) rem 4294967296)</c></item> + <item>the first <c>(size(B1) rem 4294967296)</c> bytes + are the same both in <c>B1</c> and <c>B2</c></item> + <item>substituting <c>B1</c> in <c>K1</c> with <c>B2</c> + would create a term with the same value as + <c>K2</c></item> </list> <p>The root cause of the problem + is that the <c>maps</c> implementation only hashed the + first <c>(X rem 4294967296)</c> bytes of binaries so that + different binaries could get the same hash value + independently of the hash seed.</p> + <p> + Own Id: OTP-15707</p> + </item> + <item> + <p> + <c>term_to_binary()</c> and distributed sends will now + throw a <c>system_limit</c> exception instead of + producing erroneous results when trying to encode a + binary larger than 4 GB.</p> + <p> + Own Id: OTP-15708</p> + </item> + <item> + <p> + The vxworks configure has been updated to respect the + environment CFLAGS.</p> + <p> + Own Id: OTP-15773</p> + </item> + <item> + <p> + Fix configure to not enable PGO (profile guided + optimizations) when linking of the PGO binary fails. For + instance this happens when there is no gcov lib + installed.</p> + <p> + Own Id: OTP-15788</p> + </item> + <item> + <p> + Fix bug on OpenBSD where sockets using <c>active, + true</c> or <c>active, N</c> could cause the system to + live lock. The bug was introduced in erts-10.2 + (OTP-21.2).</p> + <p> + Own Id: OTP-15791</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add support for Erlang Distribution protocol to split the + payload of large signals into several fragments. This + allows other processes to communicate uninterrupted + during the transmission of these signals.</p> + <p> + Own Id: OTP-13397</p> + </item> + <item> + <p> + A simple socket API is provided through the socket + module. This is a low level API that does *not* replace + gen_[tcp|udp|sctp]. It is intended to *eventually* + replace the inet driver, but not the high level + gen-modules (gen_tcp, gen_udp and gen_sctp). It also + provides a basic API that facilitates the implementation + of other protocols, that is TCP, UDP and SCTP. </p> + <p> + Known issues are; No support for the Windows OS + (currently).</p> + <p> + Own Id: OTP-14831</p> + </item> + <item> + <p>Added NIF functions <seealso + marker="erl_nif#enif_set_pid_undefined"><c>enif_set_pid_undefined</c></seealso>, + <seealso + marker="erl_nif#enif_is_pid_undefined"><c>enif_is_pid_undefined</c></seealso> + and <seealso + marker="erl_nif#enif_compare_pids"><c>enif_compare_pids</c></seealso>.</p> + <p> + Own Id: OTP-15011 Aux Id: PR-2147 </p> + </item> + <item> + <p>Underutilized memory segments (carriers) can now move + between all allocator instances, rather than just between + instances of the same type, which greatly reduces memory + usage in some scenarios. </p> + <p> + Own Id: OTP-15063</p> + </item> + <item> + <p>The emulator will now mark free blocks in pooled + carriers with <c>madvise(2) + MADV_FREE</c> (or similar), + letting the OS reclaim the associated physical memory if + necessary.</p> + <p> + Own Id: OTP-15075</p> + </item> + <item> + <p> + New <c>ERL_NIF_SELECT_CANCEL</c> feature added to + <c>enif_select</c> in order to cancel (or "deselect") a + read or write event on a previously selected file + descriptor.</p> + <p> + Own Id: OTP-15095</p> + </item> + <item> + <p> + ETS option <c>write_concurrency</c> now also affects and + improves the scalability of <c>ordered_set</c> tables. + The implementation is based on a data structure called + contention adapting search tree, where the lock + granularity adapts to the actual amount of concurrency + exploited by the applications in runtime.</p> + <p> + Own Id: OTP-15128</p> + </item> + <item> + <p> + Build configuration of the <c>crypto</c> application has + been moved from the <c>erts</c> application into the + <c>crypto</c> application.</p> + <p> + Own Id: OTP-15129</p> + </item> + <item> + <p>Anonymous functions that don't capture environment are + now created at load-time instead of in run-time.</p> + <p> + Own Id: OTP-15195 Aux Id: PR-1812 </p> + </item> + <item> + <p> + Optimize updates of maps with identical keys and values. + E.g. in the example below the original Map will be reused + as the return of the update.</p> + <p> + 1> Map = #{ a => b }. #{ a => b } 2> Map#{ a := b }.</p> + <p> + Own Id: OTP-15211 Aux Id: PR-1889 </p> + </item> + <item> + <p> + Optimize <c>binary:match/2</c> and + <c>binary:matches/2</c> to use memchr internally.</p> + <p> + Own Id: OTP-15238 Aux Id: PR-1803 </p> + </item> + <item> + <p> + The runtime system used to terminate when a message + larger than 2 Gb was passed over the distribution. The + send operation will now instead throw a + <c>system_limit</c> exception.</p> + <p> + Own Id: OTP-15261</p> + </item> + <item> + <p> + Change the first module called by erts to be named + erl_init instead of otp_ring0. systools in sasl have been + updated to reflect this change.</p> + <p> + Own Id: OTP-15336 Aux Id: PR-1825 </p> + </item> + <item> + <p> + Minor adjustments made to build system for parallel + configure.</p> + <p> + Own Id: OTP-15340 Aux Id: OTP-14625 </p> + </item> + <item> + <p> + Two new NIF interface functions <c>enif_select_read</c> + and <c>enif_select_write</c>. They are similar to + existing <c>enif_select</c> but allow a custom event + message as an argument.</p> + <p> + Own Id: OTP-15349 Aux Id: PR-2084 </p> + </item> + <item> + <p>The embedded copy of <c>zlib</c> has been updated from + <c>1.2.8</c> to <c>1.2.11</c>.</p> + <p>Note that this copy is only used as a fallback when + the target platform doesn't provide any <c>zlib</c> + development libraries. If your system provides + <c>zlib</c> then it will be used even if it is older than + <c>1.2.11</c>.</p> + <p> + Own Id: OTP-15351 Aux Id: ERL-749 </p> + </item> + <item> + <p> + New NIF function <c>enif_make_monitor_term</c>.</p> + <p> + Own Id: OTP-15362 Aux Id: PR-2127 </p> + </item> + <item> + <p>Appending lists (The ++ operator) will now yield + properly on large inputs.</p> + <p> + Own Id: OTP-15427</p> + </item> + <item> + <p>The <c>length/1</c> BIF used to calculate the length + of the list in one go without yielding, even if the list + was very long. In OTP 22, <c>length/1</c> will yield when + called with long lists.</p> + <p> + Own Id: OTP-15439</p> + </item> + <item> + <p> + Processes sending messages are now punished with a + reduction cost based on message size. That is, a process + sending a large message will yield earlier than before.</p> + <p> + Own Id: OTP-15513 Aux Id: ERL-773 </p> + </item> + <item> + <p>The transitory emulator option <c>+ztma true</c> + (introduced in OTP 21.3) has been removed.</p> + <p> + Own Id: OTP-15581 Aux Id: OTP-15580 </p> + </item> + <item> + <p>In OTP 22, HiPE (the native code compiler) is not + fully functional. The reasons for this are:</p> + <p>There are new BEAM instructions for binary matching + that the HiPE native code compiler does not support.</p> + <p>The new optimizations in the Erlang compiler create + new combination of instructions that HiPE currently does + not handle correctly.</p> + <p>If erlc is invoked with the <c>+native</c> option, and + if any of the new binary matching instructions are used, + the compiler will issue a warning and produce a BEAM file + without native code.</p> + <p> + Own Id: OTP-15596</p> + </item> + <item> + <p> + The termination behaviour of processes has changed to + allow processes to yield while sending link exit/monitor + down signals.</p> + <p> + The erl crash dump has been expanded to now also include + processes that are termeinating but have not yet + terminated.</p> + <p> + Own Id: OTP-15610</p> + </item> + <item> + <p> + The dist messages EXIT, EXIT2 and MONITOR_DOWN have been + updated with new versions that send the reason term as + part of the payload of the message instead of as part of + the control message.</p> + <p> + The old versions are still present and can be used when + communicating with nodes that don't support the new + versions.</p> + <p> + Own Id: OTP-15611</p> + </item> + <item> + <p> + When sending messages, exit, exit2 and monitor down + distributed signals, the process sending will now yield + appropriately.</p> + <p> + This means that a terminating process will yield and + possibly be suspended on busy distribution entries while + they are terminating. This means that any memory held by + such processes will not be released until after all + exit/monitor down signals have been sent.</p> + <p> + Own Id: OTP-15612</p> + </item> + <item> + <p> + All external pids/ports/refs created by + erlang:list_to_pid/port/ref debug functions now compare + equal to any other pid/port/ref with the same number from + that node.</p> + <p> + Before this change they compared differently because the + node creation of the pid/port/ref did not compare equal + to any real pid/port/ref creation.</p> + <p> + This will mostly effect pids/ports/refs typed in the + shell.</p> + <p> + Own Id: OTP-15613</p> + </item> + <item> + <p> + The <c>persistent_term</c> functions <c>put/2</c> and + <c>erase/1</c> are now yielding.</p> + <p> + Own Id: OTP-15615</p> + </item> + <item> + <p> + A new <seealso + marker="erlang#dist_ctrl_set_opt/3"><c>erlang:dist_ctrl_set_opt(DHandle, + get_size, Value)</c></seealso> option has been added. + This option makes it possible to configure the + distribution channel identified by <c>DHandle</c> so that + <seealso + marker="erlang#dist_ctrl_get_data/1"><c>erlang:dist_ctrl_get_data(DHandle)</c></seealso> + also returns the size of the data to pass over the + channel.</p> + <p> + Own Id: OTP-15617</p> + </item> + <item> + <p>Previously, all ETS tables used centralized counter + variables to keep track of the number of items stored and + the amount of memory consumed. These counters can cause + scalability problems (especially on big NUMA systems). + This change adds an implementation of a decentralized + counter and modifies the implementation of ETS so that + ETS tables of type <c>ordered_set</c> with + <c>write_concurrency</c> enabled use the decentralized + counter. Experiments indicate that this change + substantially improves the scalability of ETS + <c>ordered_set</c> tables with <c>write_concurrency</c> + enabled in scenarios with frequent <c>ets:insert/2</c> + and <c>ets:delete/2</c> calls.</p> + <p> + Own Id: OTP-15623 Aux Id: PR-2190 </p> + </item> + <item> + <p>The <c>iolist_size/1</c> function is now yielding + which means that an Erlang/OTP system will be responsive + even if the applications running on the system frequently + call <c>iolist_size/1</c> with large iolists.</p> + <p> + Own Id: OTP-15631</p> + </item> + <item> + <p> + A simple test suite for the net module has been added.</p> + <p> + Own Id: OTP-15635</p> + </item> + <item> + <p>Added the NIF function <c>enif_term_type</c>, which + helps avoid long sequences of <c>enif_is_xyz</c> by + returning the type of the given term. This is especially + helpful for NIFs that serialize terms, such as JSON + encoders, where it can improve both performance and + readability.</p> + <p> + Own Id: OTP-15640</p> + </item> + <item> + <p>The last call optimization is now applied to BIFs. + When calling a BIF in the tail position of a function, + the return address and stack frame will now be discarded + before calling the BIF. As a consequence of this change, + the immediate caller of a tail-called BIF will no longer + be available in stack backtraces.</p> + <p> + Own Id: OTP-15674 Aux Id: PR-2177 </p> + </item> + <item> + <p> + Fix GC bug where distributed messages in a processes + mailbox would cause extra GCs. This can be very expensive + if there many messages in the mailbox.</p> + <p> + Own Id: OTP-15703</p> + </item> + <item> + <p>Internal documentation has now been added to the + <em>Erts</em> and <em>Compiler</em> applications.</p> + <p>The internal documents for <em>Erts</em> describe + miscellaneous interesting implementation details. Those + details can change at any time.</p> + <p>The internal documentation for <em>Compiler</em> + documents the API for the Core Erlang modules. While we + will not change those APIs without good reason, we don't + give the same guarantees about backward compatibility as + for the rest of the APIs in OTP.</p> + <p> + Own Id: OTP-15715</p> + </item> + <item> + <p>The performance of non-bignum integer arithmetic has + been improved.</p> + <p> + Own Id: OTP-15740</p> + </item> + <item> + <p> + The <c>-remsh</c> option to <c>erl</c> now automatically + adds the local systems hostname to the target node if no + nodename is given. e.g.</p> + <p> + <c> erl -name foo -remsh bar </c><br/> <c> erl -sname foo + -remsh bar </c></p> + <p> + Own Id: OTP-15794 Aux Id: PR-2219 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.3.5.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug causing VM crash when doing textual dump of a + process containing an unhandled monitor down signal. + Textual process dumps can be done with + <c>erlang:system_info(procs)</c>, trace feature + <c>process_dump</c>, Erlang shell break menu and a + crashdump. Bug exist since OTP 21.0.</p> + <p> + Own Id: OTP-15909 Aux Id: ERL-979 </p> + </item> + <item> + <p><c>lists:subtract/2</c> would produce incorrect + results for some inputs on 64-bit platforms.</p> + <p> + Own Id: OTP-15938 Aux Id: ERL-986 </p> + </item> + <item> + <p>Fixed a bug in the loader that was similar to + <c>OTP-15938</c>, yielding incorrect code for some inputs + on 64-bit platforms.</p> + <p> + Own Id: OTP-15939</p> + </item> + <item> + <p> + Fixed bug causing scheduler threads in rare cases to + block spinnning indefinitely. Bug exists since OTP 21.0.</p> + <p> + Own Id: OTP-15941 Aux Id: PR-2313 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.3.5.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + If you set <c>{linger,{true,0}}</c> on a <c>gen_tcp</c> + listen socket, accept a connection on that socket, and + then close the accepted socket, now the linger zero + setting is transferred to the accepted socket. Before + this correction that information was lost and the close + behaviour on the accepted socket incorrect.</p> + <p> + Own Id: OTP-15370 Aux Id: ERIERL-353 </p> + </item> + <item> + <p> + Fixed <c>process_info(Pid,reductions)</c> to not + categorically increase reduction count of the measured + process <c>Pid</c>. Repeated reduction measure of an idle + process will most often (but not guaranteed) return the + same value, like it behaved before OTP 21.3.8.</p> + <p> + Own Id: OTP-15865 Aux Id: ERL-964 </p> + </item> + <item> + <p> + The runtime system disconnected a connection if it + received an <c>exit/2</c> signal where the recipient was + a process on an old incarnation of the current node. That + is, the receiving node had the same node name, but + another "creation" number. The signal will now just be + dropped since the receiving process no longer exists.</p> + <p> + Own Id: OTP-15867 Aux Id: ERIERL-373 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The possibility to send ancillary data, in particular the + TOS field, has been added to <c>gen_udp:send/4,5</c>.</p> + <p> + Own Id: OTP-15747 Aux Id: ERIERL-294 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.3.5.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>In nested use of <c>try</c>/<c>catch</c>, rethrowing + an exception using <c>erlang:raise/3</c> with a different + class would not always be able to change the class of the + exception.</p> + <p> + Own Id: OTP-15834 Aux Id: ERIERL-367 </p> + </item> + <item> + <p> + Fixed bug in <c>seq_trace:set_token(label,Term)</c> which + could cause VM crash if <c>Term</c> was heap allocated + (not an atom, small integer, local pid or port). Bug + exists since OTP 21.0 when terms other than small + integers were first allowed as labels.</p> + <p> + Own Id: OTP-15849 Aux Id: ERL-700 </p> + </item> + <item> + <p> + Fix <c>seq_trace:print/2</c> not to raise <c>badarg</c> + exception if label is not a small integer. Bug exists + since OTP 21.0.</p> + <p> + Own Id: OTP-15859 Aux Id: ERL-700 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.3.5.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a buffer overflow when + <c>binary_to_existing_atom/2</c> and + <c>list_to_existing_atom/2</c> was used with the + <c>latin1</c> encoding.</p> + <p> + Own Id: OTP-15819 Aux Id: ERL-944 </p> + </item> + </list> + </section> + +</section> + <section><title>Erts 10.3.5</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -2040,6 +2795,23 @@ </section> +<section><title>Erts 9.3.3.11</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a buffer overflow when + <c>binary_to_existing_atom/2</c> and + <c>list_to_existing_atom/2</c> was used with the + <c>latin1</c> encoding.</p> + <p> + Own Id: OTP-15819 Aux Id: ERL-944 </p> + </item> + </list> + </section> + +</section> + <section><title>Erts 9.3.3.10</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml.src index f0b8a00b90..9b20beffad 100644 --- a/erts/doc/src/part.xml +++ b/erts/doc/src/part.xml.src @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2018</year> + <year>1996</year><year>2019</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -42,7 +42,7 @@ <xi:include href="tty.xml"/> <xi:include href="driver.xml"/> <xi:include href="inet_cfg.xml"/> - <xi:include href="socket_usage.xml"/> + %ESOCK_USE_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.src index 80cdcf9145..7dd003763c 100644 --- a/erts/doc/src/ref_man.xml +++ b/erts/doc/src/ref_man.xml.src @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2018</year> + <year>1996</year><year>2019</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -46,10 +46,9 @@ <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"/> + %ESOCK_USE_SOCKET_XML% <xi:include href="start.xml"/> <xi:include href="start_erl.xml"/> <xi:include href="werl.xml"/> diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml index f6195a65b2..2f7ff2fc07 100644 --- a/erts/doc/src/socket.xml +++ b/erts/doc/src/socket.xml @@ -29,7 +29,7 @@ <rev></rev> <file>socket.xml</file> </header> - <module since="OTP @OTP-14831@">socket</module> + <module since="OTP 22.0">socket</module> <modulesummary>Socket interface.</modulesummary> <description> <p>This module provides an API for the socket interface. @@ -41,6 +41,40 @@ e.g. <seealso marker="#recv/3"><c>recv/3</c></seealso>, has a timeout argument. </p> <note> + <p>Some functions allow for an <i>asynchronous</i> call. + This is achieved by setting the <c>Timeout</c> argument to + <c>nowait</c>. For instance, if calling the + <seealso marker="#recv_async"><c>recv/3</c></seealso> + function with Timeout set to <c>nowait</c> (<c>recv(Sock, 0, nowait)</c>) + when there is actually nothing to read, it will return with + <c>{select, </c> + <seealso marker="#type-select_info"><c>SelectInfo</c></seealso><c>}</c> + (<c>SelectInfo</c> contains the + <seealso marker="socket#type-select_ref">SelectRef</seealso>). + When data eventually arrives a 'select' message + will be sent to the caller: </p> + <taglist> + <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> + <tag></tag> + <item><c>{'$socket', socket(), select, SelectRef}</c></item> + </taglist> + <p>The caller can now make another + call to the recv function and now expect data.</p> + <p>Note that all other users are <em>locked out</em> until the + 'current user' has called the function (recv in this case).</p> + <p>Another message the user must be prepared for (when making asynchronous + calls) is the <c>abort</c> message:</p> + <taglist> + <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> + <tag></tag> + <item><c>{'$socket', socket(), abort, Info}</c></item> + </taglist> + <p>This message indicates + that the (asynchronous) operation has been aborted. + If, for instance, the socket has been closed (by another process), + <c>Info</c> will be <c>{SelectRef, closed}</c>. </p> + </note> + <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> @@ -65,6 +99,30 @@ </desc> </datatype> <datatype> + <name name="select_tag"/> + <desc> + <p>A tag that describes the (select) operation.</p> + </desc> + </datatype> + <datatype> + <name name="select_ref"/> + <desc> + <p>A reference that uniquely identifies the (select) operation.</p> + </desc> + </datatype> + <datatype> + <name name="select_info"/> + </datatype> + <datatype> + <name name="socket_counters"/> + </datatype> + <datatype> + <name name="socket_counter"/> + </datatype> + <datatype> + <name name="socket_info"/> + </datatype> + <datatype> <name name="ip4_address"/> </datatype> <datatype> @@ -256,8 +314,8 @@ <funcs> <func> - <name name="accept" arity="1" since="OTP @OTP-14831@"/> - <name name="accept" arity="2" since="OTP @OTP-14831@"/> + <name name="accept" arity="1" since="OTP 22.0"/> + <name name="accept" arity="2" clause_i="2" since="OTP 22.0"/> <fsummary>Accept a connection on a socket.</fsummary> <desc> <p>Accept a connection on a socket.</p> @@ -269,7 +327,29 @@ </func> <func> - <name name="bind" arity="2" since="OTP @OTP-14831@"/> + <name name="accept" arity="2" clause_i="1" anchor="accept_async" since="OTP @OTP-15731@"/> + <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> + + <p>In the case when there is no connections waiting, the function + will return with the <c>SelectInfo</c>. The caller can then await a + select message, <c>{'$socket', Socket, select, Info}</c> (where + <c>Info</c> is the + <seealso marker="socket#type-select_ref"><c>ref</c></seealso> + field from the <c>SelectInfo</c>), + when a client connects (a subsequent call to accept will then return + the socket). </p> + </desc> + </func> + + <func> + <name name="bind" arity="2" since="OTP 22.0"/> <fsummary>Bind a name to a socket.</fsummary> <desc> <p>Bind a name to a socket.</p> @@ -282,7 +362,19 @@ </func> <func> - <name name="close" arity="1" since="OTP @OTP-14831@"/> + <name name="cancel" arity="2" since="OTP @OTP-15731@"/> + <fsummary>Cancel an asynchronous request.</fsummary> + <desc> + <p>Cancel an asynchronous request.</p> + + <p>Call this function in order to cancel a previous + asynchronous call to, e.g. + <seealso marker="#recv/3"><c>recv/3</c></seealso>. </p> + </desc> + </func> + + <func> + <name name="close" arity="1" since="OTP 22.0"/> <fsummary>Close a socket.</fsummary> <desc> <p>Closes the socket.</p> @@ -301,8 +393,8 @@ </func> <func> - <name name="connect" arity="2" since="OTP @OTP-14831@"/> - <name name="connect" arity="3" since="OTP @OTP-14831@"/> + <name name="connect" arity="2" since="OTP 22.0"/> + <name name="connect" arity="3" clause_i="2" since="OTP 22.0"/> <fsummary>Initiate a connection on a socket.</fsummary> <desc> <p>This function connects the socket to the address @@ -311,13 +403,33 @@ </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@"/> + <name name="connect" arity="3" clause_i="1" anchor="connect_async" since="OTP @OTP-15731@"/> + <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> + + <p>In the case when its not possible to immediately establish a + connection, the function will return with the + <seealso marker="#type-select_info"><c>SelectInfo</c></seealso>. + The caller can then await a + select message, <c>{'$socket', Socket, select, Info}</c> (where + <c>Info</c> is the + <seealso marker="socket#type-select_ref"><c>ref</c></seealso> + field from the <c>SelectInfo</c>, + a subsequent call to connect will then + establish the connection). </p> + </desc> + </func> + + <func> + <name name="getopt" arity="3" clause_i="1" since="OTP 22.0"/> + <name name="getopt" arity="3" clause_i="2" since="OTP 22.0"/> + <name name="getopt" arity="3" clause_i="3" since="OTP 22.0"/> + <name name="getopt" arity="3" clause_i="4" since="OTP 22.0"/> + <name name="getopt" arity="3" clause_i="5" since="OTP 22.0"/> + <name name="getopt" arity="3" clause_i="6" since="OTP 22.0"/> + <name name="getopt" arity="3" clause_i="7" since="OTP 22.0"/> <fsummary>Get an option on a socket.</fsummary> <desc> <p>Get an option on a socket.</p> @@ -337,7 +449,7 @@ </func> <func> - <name name="getopt" arity="3" clause_i="8" since="OTP @OTP-14831@"/> + <name name="getopt" arity="3" clause_i="8" since="OTP 22.0"/> <fsummary>Get an option on a socket.</fsummary> <desc> <p>Get an option on a socket.</p> @@ -359,8 +471,22 @@ </func> <func> - <name name="listen" arity="1" since="OTP @OTP-14831@"/> - <name name="listen" arity="2" since="OTP @OTP-14831@"/> + <name name="info" arity="1" since="OTP @OTP-15818@"/> + <fsummary>Get miscellaneous socket info.</fsummary> + <desc> + <p>Get miscellaneous info about the socket.</p> + <p>The function returns a map with each info item as a key-value + binding. It reflects the "current" state of the socket. </p> + <note> + <p>In order to ensure data integrity, mutex'es are taken when + needed. So, do not call this function often. </p> + </note> + </desc> + </func> + + <func> + <name name="listen" arity="1" since="OTP 22.0"/> + <name name="listen" arity="2" since="OTP 22.0"/> <fsummary>Listen for connections on a socket.</fsummary> <desc> <p>Listen for connections on a socket.</p> @@ -368,29 +494,34 @@ </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@"/> + <name name="open" arity="2" since="OTP 22.0"/> + <name name="open" arity="3" since="OTP 22.0"/> + <name name="open" arity="4" since="OTP 22.0"/> <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> + <p>Creates an endpoint (socket) for communication.</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>For some <c>types</c> there is a default protocol, + indicated by <c>default</c>, which it <em>may</em> be + possible to specify. + And for <c>Domain = local</c>, if a protocol <em>is</em> pecified, + it <em>must</em> be <c>default</c>. </p> <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> + + <note> + <p>It may not be possible to specify the default protocol (except + when <c>Domain = local</c>). We need to be able to retreive + the resulting protocol, which is <em>not</em> possble on all + platforms. </p> + </note> </desc> </func> <func> - <name name="peername" arity="1" since="OTP @OTP-14831@"/> + <name name="peername" arity="1" since="OTP 22.0"/> <fsummary>Get name of connected socket peer.</fsummary> <desc> <p>Returns the address of the peer connected to the socket.</p> @@ -398,11 +529,11 @@ </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@"/> + <name name="recv" arity="1" since="OTP 22.0"/> + <name name="recv" arity="2" since="OTP 22.0"/> + <name name="recv" arity="3" clause_i="1" since="OTP 22.0"/> + <name name="recv" arity="3" clause_i="3" since="OTP 22.0"/> + <name name="recv" arity="4" clause_i="2" since="OTP 22.0"/> <fsummary>Receive a message from a socket.</fsummary> <desc> <p>Receive a message from a socket.</p> @@ -413,36 +544,128 @@ </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@"/> + <name name="recv" arity="3" clause_i="2" anchor="recv_async" since="OTP @OTP-15731@"/> + <name name="recv" arity="4" clause_i="1" since="OTP @OTP-15731@"/> + <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> + + <p>In the case when there is no data waiting, the function + will return with the <c>SelectInfo</c>. The caller can then await a + select message, <c>{'$socket', Socket, select, Info}</c> (where + <c>Info</c> is the + <seealso marker="socket#type-select_ref"><c>ref</c></seealso> + field from the <c>SelectInfo</c>), + when data has arrived (a subsequent call to recv will then return + the data). </p> + <p>Note that if a length (<c>> 0</c>) is specified, and only part + of that amount of data is available, the function will return with + that data <em>and</em> the <c>SelectInfo</c> (if the caller don't + want to wait for the remaining data, it must immediately call + the <seealso marker="#cancel/2"><c>cancel/2</c></seealso> function.)</p> + </desc> + </func> + + <func> + <name name="recvfrom" arity="1" since="OTP 22.0"/> + <name name="recvfrom" arity="2" since="OTP 22.0"/> + <name name="recvfrom" arity="3" clause_i="2" since="OTP 22.0"/> + <name name="recvfrom" arity="3" clause_i="3" since="OTP 22.0"/> + <name name="recvfrom" arity="3" clause_i="5" since="OTP 22.0"/> + <name name="recvfrom" arity="4" clause_i="2" since="OTP 22.0"/> <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> + how much we want to read, it returns when we get a message + (if the buffer size is to small, the message will be truncated).</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="recvfrom" arity="3" clause_i="1" anchor="recvfrom_async" since="OTP @OTP-15731@"/> + <name name="recvfrom" arity="3" clause_i="4" since="OTP @OTP-15731@"/> + <name name="recvfrom" arity="4" clause_i="1" since="OTP @OTP-15731@"/> + <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 + (if the buffer size is to small, the message will be truncated).</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> + 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> + + <p>In the case when there is no data waiting, the function + will return with the <c>SelectInfo</c>. The caller can then await a + select message, <c>{'$socket', Socket, select, Info}</c> (where + <c>Info</c> is the + <seealso marker="socket#type-select_ref"><c>ref</c></seealso> + field from the <c>SelectInfo</c>), + when data has arrived (a subsequent call to recvfrom will then return + the data). </p> + </desc> + </func> + + <func> + <name name="recvmsg" arity="1" since="OTP 22.0"/> + <name name="recvmsg" arity="2" clause_i="1" since="OTP 22.0"/> + <name name="recvmsg" arity="2" clause_i="3" since="OTP 22.0"/> + <name name="recvmsg" arity="3" clause_i="2" since="OTP 22.0"/> + <name name="recvmsg" arity="3" clause_i="3" since="OTP 22.0"/> + <name name="recvmsg" arity="5" clause_i="2" since="OTP 22.0"/> + <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="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@"/> + <name name="recvmsg" arity="2" clause_i="2" anchor="recvmsg_async" since="OTP @OTP-15731@"/> + <name name="recvmsg" arity="3" clause_i="1" since="OTP @OTP-15731@"/> + <name name="recvmsg" arity="5" clause_i="1" since="OTP @OTP-15731@"/> <fsummary>Receive a message from a socket.</fsummary> <desc> <p>Receive a message from a socket.</p> @@ -456,8 +679,8 @@ <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> + 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. @@ -469,25 +692,58 @@ (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> + + <p>In the case when there is no data waiting, the function + will return with the <c>SelectInfo</c>. The caller can then await a + select message, <c>{'$socket', Socket, select, Info}</c> (where + <c>Info</c> is the + <seealso marker="socket#type-select_ref"><c>ref</c></seealso> + field from the <c>SelectInfo</c>), + when data has arrived (a subsequent call to recvmsg will then return + the data). </p> + </desc> + </func> + + <func> + <name name="send" arity="2" since="OTP 22.0"/> + <name name="send" arity="3" clause_i="1" since="OTP 22.0"/> + <name name="send" arity="3" clause_i="3" since="OTP 22.0"/> + <name name="send" arity="4" clause_i="2" since="OTP 22.0"/> + <fsummary>Send a message on a socket.</fsummary> + <desc> + <p>Send a message on a connected socket.</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@"/> + <name name="send" arity="3" clause_i="2" anchor="send_async" since="OTP @OTP-15731@"/> + <name name="send" arity="4" clause_i="1" since="OTP @OTP-15731@"/> <fsummary>Send a message on a socket.</fsummary> <desc> <p>Send a message on a connected socket.</p> + + <p>In the case when there is no room in the (system-) buffers, + the function will return with the <c>SelectInfo</c>. The caller + can then await a select message, + <c>{'$socket', Socket, select, Info}</c> + (where <c>Info</c> is the + <seealso marker="socket#type-select_ref"><c>ref</c></seealso> + field from the + <c>SelectInfo</c>), when there is room for more data (a subsequent + call to send will then send the data). </p> + <p>Note that if not all the data was sent, the function will return + with the remaining data <em>and</em> the <c>SelectInfo</c> + (if the caller don't + want to wait to be able to send the rest, it should immediately call + the <seealso marker="#cancel/2"><c>cancel/2</c></seealso> function.)</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@"/> + <name name="sendmsg" arity="2" since="OTP 22.0"/> + <name name="sendmsg" arity="3" clause_i="1" since="OTP 22.0"/> + <name name="sendmsg" arity="3" clause_i="3" since="OTP 22.0"/> + <name name="sendmsg" arity="4" clause_i="2" since="OTP 22.0"/> <fsummary>Send a message on a socket.</fsummary> <desc> <p>Send a message on a socket. The destination, if needed @@ -508,10 +764,41 @@ </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@"/> + <name name="sendmsg" arity="3" clause_i="2" anchor="sendmsg_async" since="OTP @OTP-15731@"/> + <name name="sendmsg" arity="4" clause_i="1" since="OTP @OTP-15731@"/> + <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> + + <p>In the case when there is no room in the (system-) buffers, + the function will return with the <c>SelectInfo</c>. The caller + can then await a select message, + <c>{'$socket', Socket, select, Info}</c> + (where <c>Info</c> is the + <seealso marker="socket#type-select_ref"><c>ref</c></seealso> + field from the + <c>SelectInfo</c>), when there is room for more data (a subsequent + call to sendmsg will then send the data). </p> + </desc> + </func> + + <func> + <name name="sendto" arity="3" since="OTP 22.0"/> + <name name="sendto" arity="4" clause_i="1" since="OTP 22.0"/> + <name name="sendto" arity="4" clause_i="3" since="OTP 22.0"/> + <name name="sendto" arity="5" clause_i="2" since="OTP 22.0"/> <fsummary>Send a message on a socket.</fsummary> <desc> <p>Send a message on a socket, to the specified destination.</p> @@ -519,13 +806,32 @@ </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@"/> + <name name="sendto" arity="4" clause_i="2" anchor="sendto_async" since="OTP @OTP-15731@"/> + <name name="sendto" arity="5" clause_i="1" since="OTP @OTP-15731@"/> + <fsummary>Send a message on a socket.</fsummary> + <desc> + <p>Send a message on a socket, to the specified destination.</p> + + <p>In the case when there is no room in the (system-) buffers, + the function will return with the <c>SelectInfo</c>. The caller + can then await a select message, + <c>{'$socket', Socket, select, Info}</c> + (where <c>Info</c> is the + <seealso marker="socket#type-select_ref"><c>ref</c></seealso> + field from the + <c>SelectInfo</c>), when there is room for more data (a subsequent + call to sendto will then send the data). </p> + </desc> + </func> + + <func> + <name name="setopt" arity="4" clause_i="1" since="OTP 22.0"/> + <name name="setopt" arity="4" clause_i="2" since="OTP 22.0"/> + <name name="setopt" arity="4" clause_i="3" since="OTP 22.0"/> + <name name="setopt" arity="4" clause_i="4" since="OTP 22.0"/> + <name name="setopt" arity="4" clause_i="5" since="OTP 22.0"/> + <name name="setopt" arity="4" clause_i="6" since="OTP 22.0"/> + <name name="setopt" arity="4" clause_i="7" since="OTP 22.0"/> <fsummary>Set options on a socket.</fsummary> <desc> <p>Set options on a socket.</p> @@ -548,7 +854,7 @@ </func> <func> - <name name="setopt" arity="4" clause_i="8" since="OTP @OTP-14831@"/> + <name name="setopt" arity="4" clause_i="8" since="OTP 22.0"/> <fsummary>Set options on a socket.</fsummary> <desc> <p>Set options on a socket.</p> @@ -571,7 +877,7 @@ </func> <func> - <name name="shutdown" arity="2" since="OTP @OTP-14831@"/> + <name name="shutdown" arity="2" since="OTP 22.0"/> <fsummary>Shut down part of a full-duplex connection.</fsummary> <desc> <p>Shut down all or part of a full-duplex connection.</p> @@ -579,7 +885,7 @@ </func> <func> - <name name="sockname" arity="1" since="OTP @OTP-14831@"/> + <name name="sockname" arity="1" since="OTP 22.0"/> <fsummary>Get socket name.</fsummary> <desc> <p>Returns the current address to which the socket is bound.</p> @@ -587,25 +893,25 @@ </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@"/> + <name name="supports" arity="0" since="OTP 22.0"/> + <name name="supports" arity="1" clause_i="1" since="OTP 22.0"/> + <name name="supports" arity="1" clause_i="2" since="OTP 22.0"/> + <name name="supports" arity="1" clause_i="3" since="OTP 22.0"/> + <name name="supports" arity="1" clause_i="4" since="OTP 22.0"/> + <name name="supports" arity="2" clause_i="1" since="OTP 22.0"/> + <name name="supports" arity="2" clause_i="2" since="OTP 22.0"/> + <name name="supports" arity="2" clause_i="3" since="OTP 22.0"/> + <name name="supports" arity="2" clause_i="4" since="OTP 22.0"/> + <name name="supports" arity="2" clause_i="5" since="OTP 22.0"/> + <name name="supports" arity="2" clause_i="6" since="OTP 22.0"/> + <name name="supports" arity="2" clause_i="7" since="OTP 22.0"/> + <name name="supports" arity="3" clause_i="1" since="OTP 22.0"/> + <name name="supports" arity="3" clause_i="2" since="OTP 22.0"/> + <name name="supports" arity="3" clause_i="3" since="OTP 22.0"/> + <name name="supports" arity="3" clause_i="4" since="OTP 22.0"/> + <name name="supports" arity="3" clause_i="5" since="OTP 22.0"/> + <name name="supports" arity="3" clause_i="6" since="OTP 22.0"/> + <name name="supports" arity="3" clause_i="7" since="OTP 22.0"/> <fsummary>Report info about what the platform supports.</fsummary> <desc> <p>This function intends to retreive information about what the diff --git a/erts/doc/src/socket_usage.xml b/erts/doc/src/socket_usage.xml index e0f006e618..c3cda9a615 100644 --- a/erts/doc/src/socket_usage.xml +++ b/erts/doc/src/socket_usage.xml @@ -34,11 +34,81 @@ <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> + gen_[tcp|udp|sctp] should be sufficent (when they become available). </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> + <title>Asynchronous calls</title> + <p>Some functions allow for an <i>asynchronous</i> call + (<seealso marker="socket#accept_async"><c>accept/2</c></seealso>, + <seealso marker="socket#connect_async"><c>connect/3</c></seealso>, + <seealso marker="socket#recv_async"><c>recv/3,4</c></seealso>, + <seealso marker="socket#recvfrom_async"><c>recvfrom/3,4</c></seealso>, + <seealso marker="socket#recvmsg_async"><c>recvmsg/2,3,5</c></seealso>, + <seealso marker="socket#send_async"><c>send/3,4</c></seealso>, + <seealso marker="socket#sendmsg_async"><c>sendmsg/3,4</c></seealso> and + <seealso marker="socket#sendto_async"><c>sendto/4,5</c></seealso>). + This is achieved by setting the <c>Timeout</c> argument to + <c>nowait</c>. For instance, if calling the + <seealso marker="socket#recv_async"><c>recv/3</c></seealso> + function with Timeout set to <c>nowait</c> (i.e. + <c>recv(Sock, 0, nowait)</c>) + when there is actually nothing to read, it will return with + <c>{select, </c> + <seealso marker="socket#type-select_info"><c>SelectInfo</c></seealso><c>}</c> + (<c>SelectInfo</c> contains the + <seealso marker="socket#type-select_ref">SelectRef</seealso>). + When data eventually arrives a 'select message' + will be sent to the caller:</p> + <taglist> + <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> + <tag></tag> + <item><c>{'$socket', socket(), select, SelectRef}</c></item> + </taglist> + <p>The caller can then make another + call to the recv function and now expect data.</p> + <p>The user must also be prepared to receive an abort message: </p> + <taglist> + <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> + <tag></tag> + <item><c>{'$socket', socket(), abort, Info}</c></item> + </taglist> + <p>If the operation is aborted + for whatever reason (e.g. if the socket is closed "by someone else"). + The <c>Info</c> part contains the abort reason (in this case that + the socket has been closed <c>Info = {SelectRef, closed}</c>). </p> + <p>Note that all other users are <em>locked out</em> until the + 'current user' has called the function (recv in this case). So either + immediately call the function or + <seealso marker="socket#cancel/2"><c>cancel</c></seealso>. </p> + + <p>The general form of the 'socket' message is: </p> + <taglist> + <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> + <tag></tag> + <item><c>{'$socket', Sock :: socket(), Tag :: atom(), Info :: term()}</c></item> + </taglist> + <p>Where the format of <c>Info</c> is a function of <c>Tag</c>:</p> + <table> + <row> + <cell><em>Tag</em></cell> + <cell><em>Info value type</em></cell> + </row> + <row> + <cell>select</cell> + <cell>select_ref()</cell> + </row> + <row> + <cell>abort</cell> + <cell>{select_ref(), Reason :: term()}</cell> + </row> + <tcaption>socket message info value type</tcaption> + </table> + <p>The <c>select_ref()</c> is the same as was received in the + <seealso marker="socket#type-select_info"><c>SelectInfo</c></seealso>. </p> + </section> </section> <section> @@ -124,7 +194,7 @@ <cell><em>Other Requirements and comments</em></cell> </row> <row> - <cell>acceptcon</cell> + <cell>acceptconn</cell> <cell>boolean()</cell> <cell>no</cell> <cell>yes</cell> @@ -135,7 +205,9 @@ <cell>string()</cell> <cell>yes</cell> <cell>yes</cell> - <cell>none</cell> + <cell>Before Linux 3.8, this socket option could be set, but not get. + Only works for some socket types (e.g. <c>inet</c>). + If empty value is set, the binding is removed.</cell> </row> <row> <cell>broadcast</cell> @@ -149,7 +221,7 @@ <cell>integer()</cell> <cell>yes</cell> <cell>yes</cell> - <cell>requires admin capability</cell> + <cell>may require admin capability</cell> </row> <row> <cell>domain</cell> @@ -205,7 +277,7 @@ <cell>protocol()</cell> <cell>no</cell> <cell>yes</cell> - <cell>none</cell> + <cell><em>Not</em> on (some) Darwin (for instance)</cell> </row> <row> <cell>rcvbuf</cell> diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml.src index 68fab5edf1..54224c15f5 100644 --- a/erts/doc/src/specs.xml +++ b/erts/doc/src/specs.xml.src @@ -5,8 +5,7 @@ <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"/> + %ESOCK_USE_SOCKET_SPECS_XML% <xi:include href="../specs/specs_zlib.xml"/> <xi:include href="../specs/specs_atomics.xml"/> <xi:include href="../specs/specs_counters.xml"/> diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml index 38229456c9..8a580c8d7b 100644 --- a/erts/doc/src/zlib.xml +++ b/erts/doc/src/zlib.xml @@ -411,7 +411,7 @@ list_to_binary([B1,B2])</pre> <func> <name name="deflateParams" arity="3" since=""/> - <fsummary>Dynamicly update deflate parameters.</fsummary> + <fsummary>Dynamically update deflate parameters.</fsummary> <desc> <p>Dynamically updates the compression level and compression strategy. The interpretation of <c><anno>Level</anno></c> and |
