aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc')
-rw-r--r--erts/doc/src/crash_dump.xml88
-rw-r--r--erts/doc/src/erl.xml11
-rw-r--r--erts/doc/src/erlang.xml30
-rw-r--r--erts/doc/src/match_spec.xml57
-rw-r--r--erts/doc/src/notes.xml59
-rw-r--r--erts/doc/src/zlib.xml53
6 files changed, 257 insertions, 41 deletions
diff --git a/erts/doc/src/crash_dump.xml b/erts/doc/src/crash_dump.xml
index 2b5fc877c3..8291bf38b7 100644
--- a/erts/doc/src/crash_dump.xml
+++ b/erts/doc/src/crash_dump.xml
@@ -55,10 +55,12 @@
emulator or the operating system can be reconfigured to avoid the
crash, which is why interpreting the crash dump correctly is
important.</p>
+ <p>On systems that support OS signals, it is also possible to stop
+ the runtime system and generate a crash dump by sending the SIGUSR1.</p>
<p>The erlang crash dump is a readable text file, but it might not be
very easy to read. Using the Crashdump Viewer tool in the
<c><![CDATA[observer]]></c> application will simplify the task. This is an
- HTML based tool for browsing Erlang crash dumps.</p>
+ wx-widget based tool for browsing Erlang crash dumps.</p>
<section>
<marker id="general_info"></marker>
@@ -66,8 +68,9 @@
<p>The first part of the dump shows the creation time for the dump,
a slogan indicating the reason for the dump, the system version,
of the node from which the dump originates, the compile time of
- the emulator running the originating node and the number of
- atoms in the atom table.
+ the emulator running the originating node, the number of
+ atoms in the atom table and the runtime system thread that caused
+ the crash dump to happen.
</p>
<section>
@@ -170,6 +173,60 @@
</section>
<section>
+ <marker id="scheduler"></marker>
+ <title>Scheduler information</title>
+ <p>Under the tag <em>=scheduler</em> information about the current state
+ and statistics of the schedulers in the runtime system is displayed.
+ On OSs that do allow instant suspension of other threads, the data within
+ this section will reflect what the runtime system looks like at the moment
+ when the crash happens.</p>
+ <p>The following fields can exist for a process:</p>
+ <taglist>
+ <tag><em>=scheduler:id</em></tag>
+ <item>Header, states the scheduler identifier.</item>
+ <tag><em>Scheduler Sleep Info Flags</em></tag>
+ <item>If empty the scheduler was doing some work.
+ If not empty the scheduler is either in some state of sleep,
+ or suspended. This entry is only present in a SMP enabled emulator</item>
+ <tag><em>Scheduler Sleep Info Aux Work</em></tag>
+ <item>If not empty, a scheduler internal auxiliary work is scheduled
+ to be done.</item>
+ <tag><em>Current Port</em></tag>
+ <item>The port identifier of the port that is currently being
+ executed by the scheduler.</item>
+ <tag><em>Current Process</em></tag>
+ <item>The process identifier of the process that is currently being
+ executed by the scheduler. If there is such a process this entry is
+ followed by the <em>State</em>,<em>Internal State</em>,
+ <em>Program Counter</em>, <em>CP</em> of that same process. See
+ <seealso marker="#processes">Process Information</seealso> for a
+ description what the different entries mean. Keep in mind that
+ this is a snapshot of what the entries are exactly when the crash
+ dump is starting to be generated. Therefore they will most likely
+ be different (and more telling) then the entries for the same
+ processes found in the <em>=proc</em> section. If there is no currently
+ running process, only the <em>Current Process</em> entry will be printed.
+ </item>
+ <tag><em>Current Process Limited Stack Trace</em></tag>
+ <item>This entry only shows up if there is a current process. It is very
+ similar to <seealso marker="#proc_data"><em>=proc_stack</em></seealso>,
+ except that only the function frames are printed (i.e. the stack variables
+ are omited). It is also limited to only print the top and bottom part
+ of the stack. If the stack is small (less that 512 slots) then the
+ entire stack will be printed. If not, an entry stating
+ <code>skipping ## slots</code> will be printed where ## is
+ replaced by the number of slots that has been skipped.</item>
+ <tag><em>Run Queue</em></tag>
+ <item>Displays statistics about how many processes and ports
+ of different priorities are scheduled on this scheduler.</item>
+ <tag><em>** crashed **</em></tag>
+ <item>This entry is normally not printed. It signifies that getting
+ the rest of the information about this scheduler failed for some reason.
+ </item>
+ </taglist>
+ </section>
+
+ <section>
<marker id="memory"></marker>
<title>Memory information</title>
<p>Under the tag <em>=memory</em> you will find information similar
@@ -314,6 +371,9 @@
<item>The number of live argument registers. The argument registers,
if any are live, will follow. These may contain the arguments
of the function if they are not yet moved to the stack.</item>
+ <item><em>Internal State</em></item>
+ <item>A more detailed internal represantation of the state of
+ this process.</item>
</taglist>
<p>See also the section about <seealso marker="#proc_data">process data</seealso>.</p>
</section>
@@ -339,18 +399,38 @@
<tag><em>Name</em></tag>
<item>The name of the table, regardless of whether it is a
<c><![CDATA[named_table]]></c> or not.</item>
- <tag><em>Buckets</em></tag>
+ <tag><em>Hash table, Buckets</em></tag>
<item>This occurs if the table is a hash table, i.e. if it is not an
<c><![CDATA[ordered_set]]></c>.</item>
+ <tag><em>Hash table, Chain Length</em></tag>
+ <item>Only applicable for hash tables. Contains statistics about the
+ hash table, such as the max, min and avg chain length. Having a max much
+ larger than the avg, and a std dev much larger that
+ the expected std dev is a sign that the hashing of the terms is
+ behaving badly for some reason.</item>
<tag><em>Ordered set (AVL tree), Elements</em></tag>
<item>This occurs only if the table is an <c><![CDATA[ordered_set]]></c>. (The
number of elements is the same as the number of objects in the
table.)</item>
+ <tag><em>Fixed</em></tag>
+ <item>If the table is fixed using ets:safe_fixtable or some internal
+ mechanism.</item>
<tag><em>Objects</em></tag>
<item>The number of objects in the table</item>
<tag><em>Words</em></tag>
<item>The number of words (usually 4 bytes/word) allocated to data
in the table.</item>
+ <tag><em>Type</em></tag>
+ <item>The type of the table, i.e. <c>set</c>, <c>bag</c>,
+ <c>dublicate_bag</c> or <c>ordered_set</c>.</item>
+ <tag><em>Compressed</em></tag>
+ <item>If this table was compressed.</item>
+ <tag><em>Protection</em></tag>
+ <item>The protection of this table.</item>
+ <tag><em>Write Concurrency</em></tag>
+ <item>If write_concurrency was enabled for this table.</item>
+ <tag><em>Read Concurrency</em></tag>
+ <item>If read_concurrency was enabled for this table.</item>
</taglist>
</section>
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index 19a8e1f789..ea94a4e82b 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -599,6 +599,11 @@
<p>Sets the default binary virtual heap size of processes to the size
<c><![CDATA[Size]]></c>.</p>
</item>
+ <tag><c><![CDATA[+hpds Size]]></c></tag>
+ <item>
+ <p>Sets the initial process dictionary size of processes to the size
+ <c><![CDATA[Size]]></c>.</p>
+ </item>
<tag><c><![CDATA[+K true | false]]></c></tag>
<item>
<p>Enables or disables the kernel poll functionality if
@@ -1156,9 +1161,9 @@
<tag><marker id="+secio"><c>+secio true|false</c></marker></tag>
<item>
<p>Enable or disable eager check I/O scheduling. The default
- is currently <c>false</c>, but will most likely be changed
- to <c>true</c> in OTP 18. The behaviour before this flag
- was introduced corresponds to <c>+secio false</c>.</p>
+ is currently <c>true</c>. The default was changed from <c>false</c>
+ to <c>true</c> as of erts version 7.0. The behaviour before this
+ flag was introduced corresponds to <c>+secio false</c>.</p>
<p>The flag effects when schedulers will check for I/O
operations possible to execute, and when such I/O operations
will execute. As the name of the parameter implies,
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index bd5efb712c..ba5f80a9c1 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -1339,10 +1339,11 @@ true
<fsummary>Check if a function is exported and loaded</fsummary>
<desc>
<p>Returns <c>true</c> if the module <c><anno>Module</anno></c> is loaded
- and contains an exported function <c><anno>Function</anno>/<anno>Arity</anno></c>;
- otherwise <c>false</c>.</p>
- <p>Returns <c>false</c> for any BIF (functions implemented in C
- rather than in Erlang).</p>
+ and contains an exported function <c><anno>Function</anno>/<anno>Arity</anno></c>,
+ or if there is a BIF (a built-in function implemented in C)
+ with the given name; otherwise returns <c>false</c>.</p>
+ <note><p>This function used to return false for built-in
+ functions before the 18.0 release.</p></note>
</desc>
</func>
<func>
@@ -1443,7 +1444,7 @@ true
<name name="get" arity="1"/>
<fsummary>Return a value from the process dictionary</fsummary>
<desc>
- <p>Returns the value <c><anno>Val</anno></c>associated with <c><anno>Key</anno></c> in
+ <p>Returns the value <c><anno>Val</anno></c> associated with <c><anno>Key</anno></c> in
the process dictionary, or <c>undefined</c> if <c><anno>Key</anno></c>
does not exist.</p>
<pre>
@@ -1463,6 +1464,19 @@ true
</desc>
</func>
<func>
+ <name name="get_keys" arity="0"/>
+ <fsummary>Return a list of all keys from the process dictionary</fsummary>
+ <desc>
+ <p>Returns a list of keys all keys present in the process dictionary.</p>
+ <pre>
+> <input>put(dog, {animal,1}),</input>
+<input>put(cow, {animal,2}),</input>
+<input>put(lamb, {animal,3}),</input>
+<input>get_keys().</input>
+[dog,cow,lamb]</pre>
+ </desc>
+ </func>
+ <func>
<name name="get_keys" arity="1"/>
<fsummary>Return a list of keys from the process dictionary</fsummary>
<desc>
@@ -3057,7 +3071,7 @@ os_prompt% </pre>
raised. The error reason may differ between operating
systems. Typically the error <c>enoent</c> is raised
when one tries to run a program that is not found and
- <c>eaccess</c> is raised when the given file is not
+ <c>eacces</c> is raised when the given file is not
executable.</p>
</item>
<tag><c>{fd, <anno>In</anno>, <anno>Out</anno>}</c></tag>
@@ -7365,7 +7379,9 @@ timestamp() ->
only allowed with <c>PidSpec==all</c>. If the host
machine operating system does not support high resolution
CPU time measurements, <c>trace/3</c> exits with
- <c>badarg</c>.</p>
+ <c>badarg</c>. Note that most operating systems do
+ not synchronize this value across cores, so be prepared
+ that time might seem to go backwards when using this option.</p>
</item>
<tag><c>arity</c></tag>
<item>
diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index 334b47d34c..b4cc8e9f78 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -76,22 +76,26 @@
{ GuardFunction, ConditionExpression, ... }
</item>
<item>BoolFunction ::= <c><![CDATA[is_atom]]></c> |
- <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> | <c><![CDATA[is_list]]></c> |
- <c><![CDATA[is_number]]></c> | <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> |
- <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | <c><![CDATA[is_binary]]></c> |
- <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | <c><![CDATA[is_seq_trace]]></c> |
- <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> |
- <c><![CDATA[andalso]]></c> | <c><![CDATA[orelse]]></c></item>
+ <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> |
+ <c><![CDATA[is_list]]></c> | <c><![CDATA[is_number]]></c> |
+ <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> |
+ <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> |
+ <c><![CDATA[is_map]]></c> | <c><![CDATA[is_binary]]></c> |
+ <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> |
+ <c><![CDATA[is_seq_trace]]></c> | <c><![CDATA['and']]></c> |
+ <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> |
+ <c><![CDATA['xor']]></c> | <c><![CDATA[andalso]]></c> |
+ <c><![CDATA[orelse]]></c></item>
<item>ConditionExpression ::= ExprMatchVariable | { GuardFunction } |
{ GuardFunction, ConditionExpression, ... } | TermConstruct
</item>
<item>ExprMatchVariable ::= MatchVariable (bound in the MatchHead) |
<c><![CDATA['$_']]></c> | <c><![CDATA['$$']]></c></item>
- <item>TermConstruct = {{}} | {{ ConditionExpression, ... }} |
- <c><![CDATA[[]]]></c> | [ConditionExpression, ...] | NonCompositeTerm | Constant
- </item>
- <item>NonCompositeTerm ::= term() (not list or tuple)
- </item>
+ <item>TermConstruct = {{}} | {{ ConditionExpression, ... }} |
+ <c><![CDATA[[]]]></c> | [ConditionExpression, ...] |
+ <c><![CDATA[#{}]]></c> | #{term() => ConditionExpression, ...} |
+ NonCompositeTerm | Constant</item>
+ <item>NonCompositeTerm ::= term() (not list or tuple or map)</item>
<item>Constant ::= {<c><![CDATA[const]]></c>, term()}
</item>
<item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> |
@@ -134,22 +138,26 @@
{ GuardFunction, ConditionExpression, ... }
</item>
<item>BoolFunction ::= <c><![CDATA[is_atom]]></c> |
- <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> | <c><![CDATA[is_list]]></c> |
- <c><![CDATA[is_number]]></c> | <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> |
- <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | <c><![CDATA[is_binary]]></c> |
- <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | <c><![CDATA[is_seq_trace]]></c> |
- <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> |
- <c><![CDATA[andalso]]></c> | <c><![CDATA[orelse]]></c></item>
+ <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> |
+ <c><![CDATA[is_list]]></c> | <c><![CDATA[is_number]]></c> |
+ <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> |
+ <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> |
+ <c><![CDATA[is_map]]></c> | <c><![CDATA[is_binary]]></c> |
+ <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> |
+ <c><![CDATA[is_seq_trace]]></c> | <c><![CDATA['and']]></c> |
+ <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> |
+ <c><![CDATA['xor']]></c> | <c><![CDATA[andalso]]></c> |
+ <c><![CDATA[orelse]]></c></item>
<item>ConditionExpression ::= ExprMatchVariable | { GuardFunction } |
{ GuardFunction, ConditionExpression, ... } | TermConstruct
</item>
<item>ExprMatchVariable ::= MatchVariable (bound in the MatchHead) |
<c><![CDATA['$_']]></c> | <c><![CDATA['$$']]></c></item>
<item>TermConstruct = {{}} | {{ ConditionExpression, ... }} |
- <c><![CDATA[[]]]></c> | [ConditionExpression, ...] | NonCompositeTerm | Constant
- </item>
- <item>NonCompositeTerm ::= term() (not list or tuple)
- </item>
+ <c><![CDATA[[]]]></c> | [ConditionExpression, ...] | #{} |
+ #{term() => ConditionExpression, ...} | NonCompositeTerm |
+ Constant</item>
+ <item>NonCompositeTerm ::= term() (not list or tuple or map)</item>
<item>Constant ::= {<c><![CDATA[const]]></c>, term()}
</item>
<item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> |
@@ -172,9 +180,10 @@
<title>Functions allowed in all types of match specifications</title>
<p>The different functions allowed in <c><![CDATA[match_spec]]></c> work like this:
</p>
- <p><em>is_atom, is_float, is_integer, is_list, is_number, is_pid, is_port, is_reference, is_tuple, is_binary, is_function: </em> Like the corresponding guard tests in
- Erlang, return <c><![CDATA[true]]></c> or <c><![CDATA[false]]></c>.
- </p>
+ <p><em>is_atom, is_float, is_integer, is_list, is_number, is_pid, is_port,
+ is_reference, is_tuple, is_map, is_binary, is_function:</em> Like the
+ corresponding guard tests in Erlang, return <c><![CDATA[true]]></c> or
+ <c><![CDATA[false]]></c>.</p>
<p><em>is_record: </em>Takes an additional parameter, which SHALL
be the result of <c><![CDATA[record_info(size, <record_type>)]]></c>,
like in <c><![CDATA[{is_record, '$1', rectype, record_info(size, rectype)}]]></c>.
diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml
index c896ee0cae..af0d4d7377 100644
--- a/erts/doc/src/notes.xml
+++ b/erts/doc/src/notes.xml
@@ -30,6 +30,65 @@
</header>
<p>This document describes the changes made to the ERTS application.</p>
+<section><title>Erts 6.3.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Fix getifaddrs realloc pointer error</p>
+ <p>
+ When a buffer was exhausted and subsequently reallocated,
+ we could get an unsafe pointer pointing to faulty memory.</p>
+ <p>
+ For this to occur we would need to have a large number of
+ interfaces and a reallocation of memory to a lower
+ addresses.</p>
+ <p>
+ The symptom would be garbage returned from
+ erlang:port_control(Port, 25, [])
+ (prim_inet:getifaddrs(Port) resulting in a badarg) or a
+ segmentation fault.</p>
+ <p>
+ Own Id: OTP-12445</p>
+ </item>
+ <item>
+ <p>
+ Don't close all file descriptors twice in child_setup</p>
+ <p>
+ The commit c2b4eab25c907f453a394d382c04cd04e6c06b49
+ introduced an error in which child_setup erroneously
+ tried to close all file descriptors twice.</p>
+ <p>
+ Use closefrom() if available when closing all file
+ descriptors.</p>
+ <p>
+ The function closefrom() was only used in the vfork()
+ case before but is now also used in the fork() case if
+ available.</p>
+ <p>
+ Own Id: OTP-12446</p>
+ </item>
+ <item>
+ <p>
+ During a crashdump all file descriptors are closed to
+ ensure the closing of the epmd port and to reserve a file
+ descriptor for the crashdump file.</p>
+ <p>
+ If a driver (third party library) cannot handle closing
+ of sockets this could result in a segmentation fault in
+ which case a crashdump would not be produced. This is now
+ fixed by only closing inets sockets via an emergency
+ close callback to the driver and thus closing the epmd
+ socket.</p>
+ <p>
+ Own Id: OTP-12447</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>Erts 6.3</title>
<section><title>Fixed Bugs and Malfunctions</title>
diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml
index da8ccdecdf..1f10ddef6d 100644
--- a/erts/doc/src/zlib.xml
+++ b/erts/doc/src/zlib.xml
@@ -99,7 +99,7 @@ list_to_binary([Compressed|Last])</pre>
<datatype>
<name name="zwindowbits"/>
<desc>
- <p>Normally in the range <c>-15..-9 | 9..15</c>.</p>
+ <p>Normally in the range <c>-15..-8 | 8..15</c>.</p>
</desc>
</datatype>
</datatypes>
@@ -149,7 +149,7 @@ list_to_binary([Compressed|Last])</pre>
currently the only supported method is <c>deflated</c>.</p>
<p>The <c><anno>WindowBits</anno></c> parameter is the base two logarithm
of the window size (the size of the history buffer). It
- should be in the range 9 through 15. Larger values
+ should be in the range 8 through 15. Larger values
of this parameter result in better compression at the
expense of memory usage. The default value is 15 if
<c>deflateInit/2</c>. A negative <c><anno>WindowBits</anno></c>
@@ -288,7 +288,7 @@ list_to_binary([B1,B2])</pre>
<p>Initialize decompression session on zlib stream.</p>
<p>The <c><anno>WindowBits</anno></c> parameter is the base two logarithm
of the maximum window size (the size of the history buffer).
- It should be in the range 9 through 15.
+ It should be in the range 8 through 15.
The default value is 15 if <c>inflateInit/1</c> is used.
If a compressed stream with a larger window size is
given as input, inflate() will throw the <c>data_error</c>
@@ -312,6 +312,53 @@ list_to_binary([B1,B2])</pre>
</desc>
</func>
<func>
+ <name name="inflateChunk" arity="2"/>
+ <fsummary>Decompress data with limited output size</fsummary>
+ <desc>
+ <p>Like <c>inflate/2</c>, but decompress no more data than
+ will fit in the buffer configured via <c>setBufSize/2</c>.
+ Is is useful when decompressing a stream with a high compression
+ ratio such that a small amount of compressed input may expand up to
+ 1000 times.
+ It returns <c>{more, Decompressed}</c>, when there is more output
+ available, and <c>inflateChunk/1</c> should be used to read it.
+ It may introduce some output latency (reading
+ input without producing any output).</p>
+ <p>If a preset dictionary is needed at this point (see
+ <c>inflateSetDictionary</c> below), <c>inflateChunk/2</c> throws a
+ <c>{need_dictionary,Adler}</c> exception where <c>Adler</c> is
+ the adler32 checksum of the dictionary chosen by the
+ compressor.</p>
+
+ <pre>
+walk(Compressed, Handler) ->
+ Z = zlib:open(),
+ zlib:inflateInit(Z),
+ % Limit single uncompressed chunk size to 512kb
+ zlib:setBufSize(Z, 512 * 1024),
+ loop(Z, Handler, zlib:inflateChunk(Z, Compressed)),
+ zlib:inflateEnd(Z),
+ zlib:close(Z).
+
+loop(Z, Handler, {more, Uncompressed}) ->
+ Handler(Uncompressed),
+ loop(Z, Handler, zlib:inflateChunk(Z));
+loop(Z, Handler, Uncompressed) ->
+ Handler(Uncompressed).
+ </pre>
+ </desc>
+ </func>
+ <func>
+ <name name="inflateChunk" arity="1"/>
+ <fsummary>Read next uncompressed chunk</fsummary>
+ <desc>
+ <p>Read next chunk of uncompressed data, initialized by
+ <c>inflateChunk/2</c>.</p>
+ <p>This function should be repeatedly called, while it returns
+ <c>{more, Decompressed}</c>.</p>
+ </desc>
+ </func>
+ <func>
<name name="inflateSetDictionary" arity="2"/>
<fsummary>Initialize the decompression dictionary</fsummary>
<desc>