diff options
Diffstat (limited to 'erts/doc')
-rw-r--r-- | erts/doc/src/Makefile | 40 | ||||
-rw-r--r-- | erts/doc/src/erl_dist_protocol.xml | 60 | ||||
-rw-r--r-- | erts/doc/src/erl_ext_dist.xml | 48 | ||||
-rw-r--r-- | erts/doc/src/erl_ext_fig.gif | bin | 3834 -> 3840 bytes | |||
-rw-r--r-- | erts/doc/src/erlang.xml | 1 | ||||
-rw-r--r-- | erts/doc/src/net.xml | 129 | ||||
-rw-r--r-- | erts/doc/src/notes.xml | 88 | ||||
-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 | 65 | ||||
-rw-r--r-- | erts/doc/src/socket_usage.xml | 23 | ||||
-rw-r--r-- | erts/doc/src/specs.xml.src (renamed from erts/doc/src/specs.xml) | 3 |
12 files changed, 271 insertions, 195 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/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 2ba5994557..c5b2ce1a0a 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -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> @@ -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/erlang.xml b/erts/doc/src/erlang.xml index 0e82ceba7d..2183f75487 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -2553,6 +2553,7 @@ os_prompt%</pre> true > is_map_key(value,Map). false</code> + <p>Allowed in guard tests.</p> </desc> </func> diff --git a/erts/doc/src/net.xml b/erts/doc/src/net.xml deleted file mode 100644 index 6fbc37076c..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 22.0">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 22.0"/> - <name name="getnameinfo" arity="2" since="OTP 22.0"/> - <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 22.0"/> - <name name="getaddrinfo" arity="2" clause_i="1" since="OTP 22.0"/> - <name name="getaddrinfo" arity="2" clause_i="2" since="OTP 22.0"/> - <name name="getaddrinfo" arity="2" clause_i="3" since="OTP 22.0"/> - <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 22.0"/> - <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 22.0"/> - <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 22.0"/> - <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 cfa952f01c..5ca387ffd8 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -31,6 +31,54 @@ </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> @@ -592,6 +640,46 @@ </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> 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 b4e22e86a8..2f7ff2fc07 100644 --- a/erts/doc/src/socket.xml +++ b/erts/doc/src/socket.xml @@ -47,14 +47,16 @@ <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>{ok, </c> - <seealso marker="#type-select_info"><c>SelectInfo</c></seealso><c>}</c>. + <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, select_ref()}</c></item> + <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> @@ -70,7 +72,7 @@ <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>{select_ref(), closed}</c>. </p> + <c>Info</c> will be <c>{SelectRef, closed}</c>. </p> </note> <note> <p>There is currently <em>no</em> support for Windows. </p> @@ -112,6 +114,15 @@ <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> @@ -329,7 +340,9 @@ <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 <c>select_ref()</c> from the <c>SelectInfo</c>), + <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> @@ -401,7 +414,9 @@ <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 <c>select_ref()</c> from the <c>SelectInfo</c>, + <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> @@ -456,6 +471,20 @@ </func> <func> + <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> @@ -528,7 +557,9 @@ <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 <c>select_ref()</c> from the <c>SelectInfo</c>), + <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 @@ -587,7 +618,9 @@ <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 <c>select_ref()</c> from the <c>SelectInfo</c>), + <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> @@ -663,7 +696,9 @@ <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 <c>select_ref()</c> from the <c>SelectInfo</c>), + <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> @@ -691,7 +726,9 @@ 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 <c>select_ref()</c> from the + (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 @@ -749,7 +786,9 @@ 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 <c>select_ref()</c> from the + (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> @@ -777,7 +816,9 @@ 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 <c>select_ref()</c> from the + (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> diff --git a/erts/doc/src/socket_usage.xml b/erts/doc/src/socket_usage.xml index 7e65bcbf70..c3cda9a615 100644 --- a/erts/doc/src/socket_usage.xml +++ b/erts/doc/src/socket_usage.xml @@ -56,23 +56,20 @@ 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>{ok, </c> - <seealso marker="socket#type-select_info"><c>SelectInfo</c></seealso><c>}</c>. + <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, select_ref()}</c></item> + <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> - <!-- - <list type="ordered"> - <item><c>{'$socket', Sock, abort, Info}</c></item> - </list> - --> <taglist> <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> <tag></tag> @@ -81,7 +78,7 @@ <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 = {select_ref(), closed}</c>). </p> + 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 @@ -197,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> @@ -208,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> @@ -222,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> 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"/> |