aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc')
-rw-r--r--erts/doc/src/erl.xml41
-rw-r--r--erts/doc/src/erl_driver.xml25
-rw-r--r--erts/doc/src/erlang.xml60
-rw-r--r--erts/doc/src/notes.xml244
-rw-r--r--erts/doc/src/run_erl.xml11
5 files changed, 351 insertions, 30 deletions
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index f62d3fb170..8da832ac37 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -250,6 +250,11 @@
environment variable <c><![CDATA[DISPLAY]]></c> set to
<c><![CDATA[gin:0]]></c>.</p>
</item>
+ <tag><c><![CDATA[-epmd_module Module]]></c> (init flag)</tag>
+ <item>
+ <p>Configures the module responsible to communicate to
+ <seealso marker="epmd">epmd</seealso>. Defaults to <c>erl_epmd</c>.</p>
+ </item>
<tag><c><![CDATA[-eval Expr]]></c> (init flag)</tag>
<item>
<p>Makes <c><![CDATA[init]]></c> evaluate the expression
@@ -393,9 +398,11 @@
<tag><c><![CDATA[-pa Dir1 Dir2 ...]]></c></tag>
<item>
<p>Adds the specified directories to the beginning of the code
- path, similar to <c><![CDATA[code:add_pathsa/1]]></c>; see
- <seealso marker="kernel:code"><c>code(3)</c></seealso>.
- As an alternative to <c>-pa</c>, if several directories are
+ path, similar to <seealso marker="kernel:code#add_pathsa/1">
+ <c><![CDATA[code:add_pathsa/1]]></c></seealso>. Note that the
+ order of the given directories will be reversed in the
+ resulting path.</p>
+ <p>As an alternative to <c>-pa</c>, if several directories are
to be prepended to the code path and the directories have a
common parent directory, that parent directory can be
specified in environment variable <c>ERL_LIBS</c>; see
@@ -1533,6 +1540,15 @@
</item>
</taglist>
</item>
+ <tag><c><![CDATA[ERL_CRASH_DUMP_BYTES]]></c></tag>
+ <item>
+ <p>This variable sets the maximum size of a crash dump file in bytes.
+ The crash dump will be truncated if this limit is exceeded. If the
+ variable is not set, no size limit is enforced by default. If the
+ variable is set to <c>0</c>, the runtime system does not even attempt
+ to write a crash dump file.</p>
+ <p>Introduced in ERTS 8.1.2 (Erlang/OTP 19.2).</p>
+ </item>
<tag><marker id="ERL_AFLAGS"/><c><![CDATA[ERL_AFLAGS]]></c></tag>
<item>
<p>The content of this variable is added to the beginning of the
@@ -1579,6 +1595,25 @@
</section>
<section>
+ <marker id="signals"></marker>
+ <title>Signals</title>
+ <p>On Unix systems, the Erlang runtime will interpret two types of signals.</p>
+ <taglist>
+ <tag><c>SIGUSR1</c></tag>
+ <item>
+ <p>A <c>SIGUSR1</c> signal forces a crash dump.</p>
+ </item>
+ <tag><c>SIGTERM</c></tag>
+ <item>
+ <p>A <c>SIGTERM</c> will produce a <c>stop</c> message to the <c>init</c> process.
+ This is equivalent to a <c>init:stop/0</c> call.</p>
+ <p>Introduced in ERTS 8.3 (Erlang/OTP 19.3)</p>
+ </item>
+ </taglist>
+ <p>The signal <c>SIGUSR2</c> is reserved for internal usage. No other signals are handled.</p>
+ </section>
+
+ <section>
<marker id="configuration"></marker>
<title>Configuration</title>
<p>The standard Erlang/OTP system can be reconfigured to change the default
diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index 836a58a676..7fbe97bc0b 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -1103,8 +1103,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code>
<marker id="driver_binary_dec_refc"></marker>
<p>Decrements the reference count on <c>bin</c> and returns
the reference count reached after the decrement.</p>
- <p>This function is only thread-safe when the emulator with SMP
- support is used.</p>
+ <p>This function is thread-safe.</p>
<note>
<p>The reference count of driver binary is normally to be decremented
by calling <seealso marker="#driver_free_binary">
@@ -1124,8 +1123,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code>
<desc>
<marker id="driver_binary_get_refc"></marker>
<p>Returns the current reference count on <c>bin</c>.</p>
- <p>This function is only thread-safe when the emulator with SMP
- support is used.</p>
+ <p>This function is thread-safe.</p>
</desc>
</func>
@@ -1137,8 +1135,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code>
<marker id="driver_binary_inc_refc"></marker>
<p>Increments the reference count on <c>bin</c> and returns
the reference count reached after the increment.</p>
- <p>This function is only thread-safe when the emulator with SMP
- support is used.</p>
+ <p>This function is thread-safe.</p>
</desc>
</func>
@@ -1434,8 +1431,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code>
<seealso marker="#driver_alloc_binary">
<c>driver_alloc_binary</c></seealso>. As binaries
in Erlang are reference counted, the binary can still be around.</p>
- <p>This function is only thread-safe when the emulator with SMP
- support is used.</p>
+ <p>This function is thread-safe.</p>
</desc>
</func>
@@ -1872,8 +1868,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code>
<p>Resizes a driver binary, while keeping the data.</p>
<p>Returns the resized driver binary on success. Returns <c>NULL</c>
on failure (out of memory).</p>
- <p>This function is only thread-safe when the emulator with SMP
- support is used.</p>
+ <p>This function is thread-safe.</p>
</desc>
</func>
@@ -1916,9 +1911,9 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code>
returned. Another thread can still be using the event object
internally. To safely close an event object, call
<c>driver_select</c> with <c>ERL_DRV_USE</c> and <c>on==0</c>, which
- clears all events. Then call
- <seealso marker="driver_entry#stop_select">
- <c>stop_select</c></seealso> when it is safe to close the event
+ clears all events and then either calls
+ <seealso marker="driver_entry#stop_select"><c>stop_select</c></seealso>
+ or schedules it to be called when it is safe to close the event
object. <c>ERL_DRV_USE</c> is to be set together with the first event
for an event object. It is harmless to set <c>ERL_DRV_USE</c>
even if it already has been done. Clearing all events but keeping
@@ -2039,7 +2034,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code>
<fsummary>Set and get limits for busy port message queue.</fsummary>
<desc>
<marker id="erl_drv_busy_msgq_limits"></marker>
- <p>Sets and gets limits that will be used for controling the
+ <p>Sets and gets limits that will be used for controlling the
busy state of the port message queue.</p>
<p>The port message queue is set into a busy
state when the amount of command data queued on the
@@ -2112,7 +2107,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code>
It is used to identify the condition variable in planned
future debug functionality.</p>
<p>Returns <c>NULL</c> on failure. The driver
- creating the condition variable is responsibile for
+ creating the condition variable is responsible for
destroying it before the driver is unloaded.</p>
<p>This function is thread-safe.</p>
</desc>
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 950a5fe189..cf5f3fc99b 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -516,7 +516,14 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code>
<desc>
<p>Returns an Erlang term that is the result of decoding
binary object <c><anno>Binary</anno></c>, which must be encoded
- according to the Erlang external term format.</p>
+ according to the <seealso marker="erts:erl_ext_dist">
+ Erlang external term format</seealso>.</p>
+ <pre>
+> <input>Bin = term_to_binary(hello).</input>
+&lt;&lt;131,100,0,5,104,101,108,108,111>>
+> <input>hello = binary_to_term(Bin).</input>
+hello
+</pre>
<warning>
<p>When decoding binaries from untrusted sources,
consider using <c>binary_to_term/2</c> to prevent Denial
@@ -555,6 +562,14 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code>
</taglist>
<p>Failure: <c>badarg</c> if <c>safe</c> is specified and unsafe
data is decoded.</p>
+ <pre>
+> <input>binary_to_term(&lt;&lt;131,100,0,5,104,101,108,108,111>>, [safe]).</input>
+** exception error: bad argument
+> <input>hello.</input>
+hello
+> <input>binary_to_term(&lt;&lt;131,100,0,5,104,101,108,108,111>>, [safe]).</input>
+hello
+</pre>
<p>See also
<seealso marker="#term_to_binary/1"><c>term_to_binary/1</c></seealso>,
<seealso marker="#binary_to_term/1">
@@ -4854,7 +4869,9 @@ RealSystem = system + MissedSystem</code>
<p><c><anno>BinInfo</anno></c> is a list containing miscellaneous
information about binaries currently referred to by this
process. This <c><anno>InfoTuple</anno></c> can be changed or
- removed without prior notice.</p>
+ removed without prior notice. In the current implementation
+ <c><anno>BinInfo</anno></c> is a list of tuples. The tuples
+ contain; <c>BinaryId</c>, <c>BinarySize</c>, <c>BinaryRefcCount</c>.</p>
</item>
<tag><c>{catchlevel, <anno>CatchLevel</anno>}</c></tag>
<item>
@@ -4884,7 +4901,9 @@ RealSystem = system + MissedSystem</code>
<p>Returns the current call stack back-trace (<em>stacktrace</em>)
of the process. The stack has the same format as returned by
<seealso marker="#get_stacktrace/0">
- <c>erlang:get_stacktrace/0</c></seealso>.</p>
+ <c>erlang:get_stacktrace/0</c></seealso>. The depth of the
+ stacktrace is truncated according to the <c>backtrace_depth</c>
+ system flag setting.</p>
</item>
<tag><c>{dictionary, <anno>Dictionary</anno>}</c></tag>
<item>
@@ -6596,7 +6615,9 @@ ok
<fsummary>Set system flag <c>backtrace_depth</c>.</fsummary>
<desc>
<p>Sets the maximum depth of call stack back-traces in the
- exit reason element of <c>'EXIT'</c> tuples.</p>
+ exit reason element of <c>'EXIT'</c> tuples. The flag
+ also limits the stacktrace depth returned by <c>process_info</c>
+ item <c>current_stacktrace.</c></p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
@@ -8599,12 +8620,19 @@ ok
</fsummary>
<desc>
<p>Returns a binary data object that is the result of encoding
- <c><anno>Term</anno></c> according to the Erlang external
- term format.</p>
+ <c><anno>Term</anno></c> according to the
+ <seealso marker="erts:erl_ext_dist">Erlang external
+ term format.</seealso></p>
<p>This can be used for various purposes, for example,
writing a term to a file in an efficient way, or sending an
Erlang term to some type of communications channel not
supported by distributed Erlang.</p>
+ <pre>
+> <input>Bin = term_to_binary(hello).</input>
+&lt;&lt;131,100,0,5,104,101,108,108,111>>
+> <input>hello = binary_to_term(Bin).</input>
+hello
+</pre>
<p>See also <seealso marker="#binary_to_term/1">
<c>binary_to_term/1</c></seealso>.</p>
</desc>
@@ -9507,6 +9535,10 @@ timestamp() ->
<type name="trace_info_item_result"/>
<type name="trace_info_flag"/>
<type name="trace_match_spec"/>
+ <type name="match_variable"/>
+ <type_desc name="match_variable">
+ Approximation of '$1' | '$2' | '$3' | ...
+ </type_desc>
<desc>
<p>Returns trace information about a port, process, function, or
event.</p>
@@ -9638,6 +9670,10 @@ timestamp() ->
</fsummary>
<type name="trace_pattern_mfa"/>
<type name="trace_match_spec"/>
+ <type_desc name="match_variable">
+ Approximation of '$1' | '$2' | '$3' | ...
+ </type_desc>
+ <type name="match_variable"/>
<desc>
<p>The same as
<seealso marker="#trace_pattern/3">
@@ -9650,6 +9686,10 @@ timestamp() ->
<name name="trace_pattern" arity="3" clause_i="1"/>
<fsummary>Set trace pattern for message sending.</fsummary>
<type name="trace_match_spec"/>
+ <type name="match_variable"/>
+ <type_desc name="match_variable">
+ Approximation of '$1' | '$2' | '$3' | ...
+ </type_desc>
<desc>
<p>Sets trace pattern for <em>message sending</em>.
Must be combined with
@@ -9717,6 +9757,10 @@ timestamp() ->
<name name="trace_pattern" arity="3" clause_i="2"/>
<fsummary>Set trace pattern for tracing of message receiving.</fsummary>
<type name="trace_match_spec"/>
+ <type name="match_variable"/>
+ <type_desc name="match_variable">
+ Approximation of '$1' | '$2' | '$3' | ...
+ </type_desc>
<desc>
<p>Sets trace pattern for <em>message receiving</em>.
Must be combined with
@@ -9787,6 +9831,10 @@ timestamp() ->
<type name="trace_pattern_mfa"/>
<type name="trace_match_spec"/>
<type name="trace_pattern_flag"/>
+ <type name="match_variable"/>
+ <type_desc name="match_variable">
+ Approximation of '$1' | '$2' | '$3' | ...
+ </type_desc>
<desc>
<p>Enables or disables <em>call tracing</em> for one or more functions.
Must be combined with
diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml
index 412675fd2b..ae1d2b1d93 100644
--- a/erts/doc/src/notes.xml
+++ b/erts/doc/src/notes.xml
@@ -32,6 +32,250 @@
<p>This document describes the changes made to the ERTS application.</p>
+<section><title>Erts 8.2.2</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Fix bug in <c>binary_to_term</c> for binaries created by
+ <c>term_to_binary </c> with option <c>compressed</c>. The
+ bug can cause <c>badarg</c> exception for a valid binary
+ when Erlang VM is linked against a <c>zlib</c> library of
+ version 1.2.9 or newer. Bug exists since OTP 17.0.</p>
+ <p>
+ Own Id: OTP-14159 Aux Id: ERL-340 </p>
+ </item>
+ <item>
+ <p>
+ The driver efile_drv when opening a file now use fstat()
+ on the open file instead of stat() before opening, if
+ fstat() exists. This avoids a race when the file happens
+ to change between stat() and open().</p>
+ <p>
+ Own Id: OTP-14184 Aux Id: seq-13266 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 8.2.1</title>
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Fix a quite rare bug causing VM crash during code loading
+ and the use of export funs (fun M:F/A) of not yet loaded
+ modules. Requires a very specfic timing of concurrent
+ scheduler threads. Has been seen on ARM but can probably
+ also occure on other architectures. Bug has existed since
+ OTP R16.</p>
+ <p>
+ Own Id: OTP-14144 Aux Id: seq13242 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 8.2</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Fixed <c>configure</c> failures on MacOSX. Most important
+ <c>clock_gettime()</c> was detected when building for
+ MacOSX - El Capitan using XCode 8 despite it is not
+ available until MacOSX - Sierra.</p>
+ <p>
+ Own Id: OTP-13904 Aux Id: ERL-256 </p>
+ </item>
+ <item>
+ <p>
+ <c>code:add_pathsa/1</c> and command line option
+ <c>-pa</c> both revert the given list of directories when
+ adding it at the beginning of the code path. This is now
+ documented.</p>
+ <p>
+ Own Id: OTP-13920 Aux Id: ERL-267 </p>
+ </item>
+ <item>
+ <p>
+ Fix a compilation error of erts in OpenBSD related to the
+ usage of the __errno variable.</p>
+ <p>
+ Own Id: OTP-13927</p>
+ </item>
+ <item>
+ <p>
+ Fixed so that when enabling tracing on a process that had
+ an invalid tracer associated with it, the new tracer
+ overwrites the old tracer. Before this fix, calling
+ erlang:trace/3 would behave as if the tracer was still
+ alive and not apply the new trace.</p>
+ <p>
+ This fault was introduced in ERTS 8.0.</p>
+ <p>
+ Own Id: OTP-13928</p>
+ </item>
+ <item>
+ <p>
+ Fix parsing of <c>-profile_boot 'true' | 'false'</c></p>
+ <p>
+ Own Id: OTP-13955 Aux Id: ERL-280 </p>
+ </item>
+ <item>
+ <p>
+ A slight improvement of <c>erlang:get_stacktrace/0</c>
+ for exceptions raised in hipe compiled code. Beam
+ compiled functions in such stack trace was earlier
+ replaced by some unrelated function. They are now instead
+ omitted. This is an attempt to reduce the confusion in
+ the absence of a complete and correct stack trace for
+ mixed beam and hipe functions.</p>
+ <p>
+ Own Id: OTP-13992</p>
+ </item>
+ <item>
+ <p> Correct type declaration of match specification head.
+ </p>
+ <p>
+ Own Id: OTP-13996</p>
+ </item>
+ <item>
+ <p>
+ HiPE code loading failed for x86_64 if gcc was configured
+ with <c>--enable-default-pie</c>. Fixed by disabling PIE,
+ if needed for HiPE, when building the VM.</p>
+ <p>
+ Own Id: OTP-14031 Aux Id: ERL-294, PR-1239 </p>
+ </item>
+ <item>
+ <p>
+ Faulty arguments could be presented on exception from a
+ NIF that had rescheduled itself using
+ <c>enif_schedule_nif()</c>.</p>
+ <p>
+ Own Id: OTP-14048</p>
+ </item>
+ <item>
+ <p>
+ The runtime system could crash if a garbage collection on
+ a process was performed immediately after a NIF had been
+ rescheduled using <c>enif_schedule_nif()</c>.</p>
+ <p>
+ Own Id: OTP-14049</p>
+ </item>
+ <item>
+ <p>
+ A reference to purged code could be left undetected by
+ the purge operation if a process just had rescheduled a
+ NIF call using <c>enif_schedule_nif()</c> when the
+ process was checked. This could cause a runtime system
+ crash.</p>
+ <p>
+ Own Id: OTP-14050</p>
+ </item>
+ <item>
+ <p>Fixed a number of dirty scheduler related bugs:</p>
+ <list> <item><p>Process priority was not handled correct
+ when scheduling on a dirty scheduler.</p></item>
+ <item><p>The runtime system could crash when an exit
+ signal with a compound exit reason was sent to a process
+ executing on a dirty scheduler.</p></item> <item><p>The
+ runtime system crashed when call tracing a process
+ executing on a dirty scheduler.</p></item> <item><p>A
+ code purge operation could end up hanging forever when a
+ process executed on a dirty scheduler</p></item> </list>
+ <p>
+ Own Id: OTP-14051</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Fix minor soft purge race bug that could incorrectly
+ trigger code_server to load new code for the module if
+ the soft purge failed and no current version of the
+ module existed.</p>
+ <p>
+ Own Id: OTP-13925</p>
+ </item>
+ <item>
+ <p>
+ To ease troubleshooting, <c>erlang:load_nif/2</c> now
+ includes the return value from a failed call to
+ load/reload/upgrade in the text part of the error tuple.
+ The <c>crypto</c> NIF makes use of this feature by
+ returning the source line where/if the initialization
+ fails.</p>
+ <p>
+ Own Id: OTP-13951</p>
+ </item>
+ <item>
+ <p>
+ New environment variable <c>ERL_CRASH_DUMP_BYTES</c> can
+ be used to limit the size of crash dumps. If the limit is
+ reached, crash dump generation is aborted and the
+ generated file will be truncated.</p>
+ <p>
+ Own Id: OTP-14046</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 8.1.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ The emulator got a dynamic library dependency towards
+ libsctp, which on Linux was not intended since the
+ emulator there loads and resolves the needed sctp
+ functions in runtime. This has been fixed and a configure
+ switch --enable-sctp=lib has been added for those who
+ want such a library dependency.</p>
+ <p>
+ Own Id: OTP-13956 Aux Id: ERL-262, ERL-133 </p>
+ </item>
+ <item>
+ <p>
+ Fix SIGUSR1 crashdump generation</p>
+ <p>
+ Do not generate a core when a crashdump is asked for.</p>
+ <p>
+ Own Id: OTP-13997</p>
+ </item>
+ <item>
+ <p>The new functions in <c>code</c> that allows loading
+ of many modules at once had a performance problem. While
+ executing a helper function in the <c>erl_prim_loader</c>
+ process, garbage messages were produced. The garbages
+ messages were ignored and ultimately discarded, but there
+ would be a negative impact on performance and memory
+ usage. The number of garbage message depended on both the
+ number of modules to be loaded and the length of the code
+ path.</p>
+ <p>The functions affected of this problem were:
+ <c>atomic_load/1</c>, <c>ensure_modules_loaded/1</c>, and
+ <c>prepare_loading/1</c>.</p>
+ <p>
+ Own Id: OTP-14009</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>Erts 8.1</title>
<section><title>Fixed Bugs and Malfunctions</title>
diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl.xml
index ad7b2c5b85..a9b6a7e2c6 100644
--- a/erts/doc/src/run_erl.xml
+++ b/erts/doc/src/run_erl.xml
@@ -49,7 +49,7 @@
<funcs>
<func>
<name>run_erl [-daemon] pipe_dir/ log_dir "exec command
- [command_arguments]"</name>
+ arg1 arg2 ..."</name>
<fsummary>Start the Erlang emulator without attached terminal.</fsummary>
<desc>
<p>Arguments:</p>
@@ -92,11 +92,10 @@
</item>
</list>
</item>
- <tag><c>"exec command [command_arguments]"</c></tag>
+ <tag><c>"exec command arg1 arg2 ..."</c></tag>
<item>
- <p>In the third argument, <c><![CDATA[command]]></c> is the
- executable to execute where everything written to <c>stdin</c>
- and <c>stdout</c> is logged to <c><![CDATA[log_dir]]></c>.</p>
+ <p>A space-separated string specifying the program to be executed.
+ The second field is typically a command name such as <c>erl</c>.</p>
</item>
</taglist>
</desc>
@@ -105,7 +104,7 @@
<section>
<title>Notes concerning the Log Files</title>
- <p>While running, <c>run_erl</c> (as stated earlier) sends all output,
+ <p>While running, <c>run_erl</c> sends all output,
uninterpreted, to a log file. The file is named
<c><![CDATA[erlang.log.N]]></c>, where <c>N</c> is an integer. When the
log is "full" (default log size is 100 KB), <c>run_erl</c> starts to log