aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erl.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erl.xml')
-rw-r--r--erts/doc/src/erl.xml265
1 files changed, 162 insertions, 103 deletions
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index 8da832ac37..05a9895687 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>1996</year><year>2016</year>
+ <year>1996</year><year>2018</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -239,6 +239,13 @@
<item>
<p>Useful for debugging. Prints the arguments sent to the emulator.</p>
</item>
+ <tag><c><![CDATA[-emu_type Type]]></c></tag>
+ <item>
+ <p>Start an emulator of a different type. For example, to start
+ the lock-counter emualator, use <c>-emu_type lcnt</c>. (The emulator
+ must already be built. Use the <c>configure</c> option
+ <c>--enable-lock-counter</c> to build the lock-counter emulator.)</p>
+ </item>
<tag><c><![CDATA[-env Variable Value]]></c></tag>
<item>
<p>Sets the host OS environment variable <c><![CDATA[Variable]]></c> to
@@ -353,11 +360,12 @@
</item>
<tag><c><![CDATA[-mode interactive | embedded]]></c></tag>
<item>
- <p>Indicates if the system is to load code dynamically
- (<c><![CDATA[interactive]]></c>), or if all code is to be loaded
- during system initialization (<c><![CDATA[embedded]]></c>); see
- <seealso marker="kernel:code"><c>code(3)</c></seealso>.
- Defaults to <c><![CDATA[interactive]]></c>.</p>
+ <p>Modules are auto loaded when they are first referenced if the
+ runtime system runs in <c><![CDATA[interactive]]></c> mode, which is
+ the default. In <c><![CDATA[embedded]]></c> mode modules are not auto
+ loaded. The latter is recommended when the boot script preloads all
+ modules, as conventionally happens in OTP releases. See
+ <seealso marker="kernel:code"><c>code(3)</c></seealso></p>.
</item>
<tag><c><![CDATA[-name Name]]></c></tag>
<item>
@@ -372,6 +380,16 @@
<c><![CDATA[Host]]></c> is the fully qualified host name of the
current host. For short names, use flag <c><![CDATA[-sname]]></c>
instead.</p>
+ <warning>
+ <p>
+ Starting a distributed node without also specifying
+ <seealso marker="#proto_dist"><c>-proto_dist inet_tls</c></seealso>
+ will expose the node to attacks that may give the attacker
+ complete access to the node and in extension the cluster.
+ When using un-secure distributed nodes, make sure that the
+ network is configured to keep potential attackers out.
+ </p>
+ </warning>
</item>
<tag><c><![CDATA[-noinput]]></c></tag>
<item>
@@ -421,12 +439,17 @@
</item>
<tag><c><![CDATA[-proto_dist Proto]]></c></tag>
<item>
+ <marker id="proto_dist"/>
<p>Specifies a protocol for Erlang distribution:</p>
<taglist>
<tag><c>inet_tcp</c></tag>
<item>TCP over IPv4 (the default)</item>
<tag><c>inet_tls</c></tag>
- <item>Distribution over TLS/SSL</item>
+ <item>Distribution over TLS/SSL, See the
+ <seealso marker="ssl:ssl_distribution">
+ Using SSL for Erlang Distribution</seealso> User's Guide
+ for details on how to setup a secure distributed node.
+ </item>
<tag><c>inet6_tcp</c></tag>
<item>TCP over IPv6</item>
</taglist>
@@ -490,6 +513,16 @@
exist between nodes running with flag <c><![CDATA[-sname]]></c>
and those running with flag <c><![CDATA[-name]]></c>, as node
names must be unique in distributed Erlang systems.</p>
+ <warning>
+ <p>
+ Starting a distributed node without also specifying
+ <seealso marker="#proto_dist"><c>-proto_dist inet_tls</c></seealso>
+ will expose the node to attacks that may give the attacker
+ complete access to the node and in extension the cluster.
+ When using un-secure distributed nodes, make sure that the
+ network is configured to keep potential attackers out.
+ </p>
+ </warning>
</item>
<tag><marker id="start_epmd"/><c>-start_epmd true | false</c></tag>
<item>
@@ -506,20 +539,6 @@
<p>Note that a distributed node will fail to start if epmd is
not running.</p>
</item>
- <tag><marker id="smp"/><c><![CDATA[-smp [enable|auto|disable]]]></c></tag>
- <item>
- <p><c>-smp enable</c> and <c>-smp</c> start the Erlang runtime
- system with SMP support enabled. This can fail if no runtime
- system with SMP support is available. <c>-smp auto</c> starts
- the Erlang runtime system with SMP support enabled if it is
- available and more than one logical processor is detected.
- <c>-smp disable</c> starts a runtime system without SMP support.</p>
- <note>
- <p>The runtime system with SMP support is not available on all
- supported platforms. See also flag
- <seealso marker="#+S"><c>+S</c></seealso>.</p>
- </note>
- </item>
<tag><c><![CDATA[-version]]></c> (emulator flag)</tag>
<item>
<p>Makes the emulator print its version number. The same
@@ -553,7 +572,7 @@
<tag><marker id="async_thread_pool_size"/><c><![CDATA[+A size]]></c></tag>
<item>
<p>Sets the number of threads in async thread pool. Valid range
- is 0-1024. Defaults to 10 if thread support is available.</p>
+ is 0-1024. Defaults to 1.</p>
</item>
<tag><c><![CDATA[+B [c | d | i]]]></c></tag>
<item>
@@ -612,14 +631,16 @@
of process heaps is destroyed by the crash dump generation.</p>
<p>Option <c>+d</c> instructs the emulator to produce only a
core dump and no crash dump if an internal error is detected.</p>
- <p>Calling <seealso marker="erlang:halt/1">
+ <p>Calling <seealso marker="erlang#halt/1">
<c>erlang:halt/1</c></seealso> with a string argument still
produces a crash dump. On Unix systems, sending an emulator process
a <c>SIGUSR1</c> signal also forces a crash dump.</p>
</item>
<tag><marker id="+e"/><c><![CDATA[+e Number]]></c></tag>
<item>
- <p>Sets the maximum number of ETS tables.</p>
+ <p>Sets the maximum number of ETS tables. This limit is
+ <seealso marker="stdlib:ets#max_ets_tables">partially obsolete</seealso>.
+ </p>
</item>
<tag><c><![CDATA[+ec]]></c></tag>
<item>
@@ -638,7 +659,7 @@
this value also applies to command-line parameters and environment
variables (see section <seealso
marker="stdlib:unicode_usage#unicode_in_environment_and_parameters">
- Unicode in Enviroment and Parameters</seealso> in the STDLIB
+ Unicode in Environment and Parameters</seealso> in the STDLIB
User's Guide).</p>
</item>
<tag><c><![CDATA[+fnu[{w|i|e}]]]></c></tag>
@@ -674,7 +695,7 @@
this value also applies to command-line parameters and environment
variables (see section <seealso
marker="stdlib:unicode_usage#unicode_in_environment_and_parameters">
- Unicode in Enviroment and Parameters</seealso> in the STDLIB
+ Unicode in Environment and Parameters</seealso> in the STDLIB
User's Guide).</p>
</item>
<tag><c><![CDATA[+fna[{w|i|e}]]]></c></tag>
@@ -695,7 +716,7 @@
this value also applies to command-line parameters and environment
variables (see section <seealso
marker="stdlib:unicode_usage#unicode_in_environment_and_parameters">
- Unicode in Enviroment and Parameters</seealso> in the STDLIB
+ Unicode in Environment and Parameters</seealso> in the STDLIB
User's Guide).</p>
</item>
<tag><c><![CDATA[+hms Size]]></c></tag>
@@ -744,13 +765,40 @@
<seealso marker="erlang#process_flag_message_queue_data">
<c>process_flag(message_queue_data, MQD)</c></seealso>.</p>
</item>
- <tag><c><![CDATA[+K true | false]]></c></tag>
+ <tag><marker id="+IOp"/><c>+IOp PollSets</c></tag>
+ <item>
+ <p>Sets the number of IO pollsets to use when polling for I/O.
+ This option is only used on platforms that support concurrent
+ updates of a pollset, otherwise the same number of pollsets
+ are used as IO poll threads.
+ The default is 1.
+ </p>
+ </item>
+ <tag><marker id="+IOt"/><c>+IOt PollThreads</c></tag>
+ <item>
+ <p>Sets the number of IO poll threads to use when polling for I/O.
+ The maximum number of poll threads allowed is 1024. The default is 1.
+ </p>
+ <p>A good way to check if more IO poll threads are needed is to use
+ <seealso marker="runtime_tools:msacc">microstate accounting</seealso>
+ and see what the load of the IO poll thread is. If it is high it could
+ be a good idea to add more threads.</p>
+ </item>
+ <tag><marker id="+IOPp"/><c>+IOPp PollSetsPercentage</c></tag>
+ <item>
+ <p>Similar to <seealso marker="#+IOp"><c>+IOp</c></seealso> but uses
+ percentages to set the number of IO pollsets to create, based on the
+ number of poll threads configured. If both <c>+IOPp</c> and <c>+IOp</c>
+ are used, <c>+IOPp</c> is ignored.
+ </p>
+ </item>
+ <tag><marker id="+IOPt"/><c>+IOPt PollThreadsPercentage</c></tag>
<item>
- <p>Enables or disables the kernel poll functionality if supported by
- the emulator. Defaults to <c><![CDATA[false]]></c> (disabled).
- If the emulator does not support kernel poll, and flag
- <c><![CDATA[+K]]></c> is passed to the emulator, a warning is
- issued at startup.</p>
+ <p>Similar to <seealso marker="#+IOt"><c>+IOt</c></seealso> but uses
+ percentages to set the number of IO poll threads to create, based on
+ the number of schedulers configured. If both <c>+IOPt</c> and
+ <c>+IOt</c> are used, <c>+IOPt</c> is ignored.
+ </p>
</item>
<tag><c><![CDATA[+l]]></c></tag>
<item>
@@ -870,7 +918,7 @@
<c><![CDATA[+S Schedulers:SchedulerOnline]]></c></tag>
<item>
<p>Sets the number of scheduler threads to create and scheduler threads
- to set online when SMP support has been enabled. The maximum for both
+ to set online. The maximum for both
values is 1024. If the Erlang runtime system is able to determine the
number of logical processors configured and logical processors
available, <c>Schedulers</c> defaults to logical processors
@@ -888,8 +936,6 @@
<p>Specifying value <c>0</c> for <c>Schedulers</c> or
<c>SchedulersOnline</c> resets the number of scheduler threads or
scheduler threads online, respectively, to its default value.</p>
- <p>This option is ignored if the emulator does not have SMP support
- enabled (see flag <seealso marker="#smp"><c>-smp</c></seealso>).</p>
</item>
<tag><marker id="+SP"/><c><![CDATA[+SP
SchedulersPercentage:SchedulersOnlinePercentage]]></c></tag>
@@ -897,8 +943,8 @@
<p>Similar to <seealso marker="#+S"><c>+S</c></seealso> but uses
percentages to set the number of scheduler threads to create, based
on logical processors configured, and scheduler threads to set online,
- based on logical processors available, when SMP support has been
- enabled. Specified values must be &gt; 0. For example,
+ based on logical processors available.
+ Specified values must be &gt; 0. For example,
<c>+SP 50:25</c> sets the number of scheduler threads to 50% of the
logical processors configured, and the number of scheduler threads
online to 25% of the logical processors available.
@@ -913,15 +959,13 @@
and 8 logical cores available, the combination of the options
<c>+S 4:4 +SP 50:25</c> (in either order) results in 2 scheduler
threads (50% of 4) and 1 scheduler thread online (25% of 4).</p>
- <p>This option is ignored if the emulator does not have SMP support
- enabled (see flag <seealso marker="#smp"><c>-smp</c></seealso>).</p>
</item>
<tag><marker id="+SDcpu"/><c><![CDATA[+SDcpu
DirtyCPUSchedulers:DirtyCPUSchedulersOnline]]></c></tag>
<item>
<p>Sets the number of dirty CPU scheduler threads to create and dirty
- CPU scheduler threads to set online when threading support has been
- enabled. The maximum for both values is 1024, and each value is
+ CPU scheduler threads to set online.
+ The maximum for both values is 1024, and each value is
further limited by the settings for normal schedulers:</p>
<list type="bulleted">
<item>The number of dirty CPU scheduler threads created cannot exceed
@@ -945,18 +989,14 @@
executing on ordinary schedulers. If the amount of dirty CPU
schedulers was allowed to be unlimited, dirty CPU bound jobs would
potentially starve normal jobs.</p>
- <p>This option is ignored if the emulator does not have threading
- support enabled. <em>This option is experimental</em> and
- is supported only if the emulator was configured and built with
- support for dirty schedulers enabled (it is disabled by default).</p>
</item>
<tag><marker id="+SDPcpu"/><c><![CDATA[+SDPcpu
DirtyCPUSchedulersPercentage:DirtyCPUSchedulersOnlinePercentage]]></c></tag>
<item>
<p>Similar to <seealso marker="#+SDcpu"><c>+SDcpu</c></seealso> but
uses percentages to set the number of dirty CPU scheduler threads to
- create and the number of dirty CPU scheduler threads to set online
- when threading support has been enabled. Specified values must be
+ create and the number of dirty CPU scheduler threads to set online.
+ Specified values must be
&gt; 0. For example, <c>+SDPcpu 50:25</c> sets the number of dirty
CPU scheduler threads to 50% of the logical processors configured
and the number of dirty CPU scheduler threads online to 25% of the
@@ -973,15 +1013,11 @@
the combination of the options <c>+SDcpu 4:4 +SDPcpu 50:25</c> (in
either order) results in 2 dirty CPU scheduler threads (50% of 4) and
1 dirty CPU scheduler thread online (25% of 4).</p>
- <p>This option is ignored if the emulator does not have threading
- support enabled. <em>This option is experimental</em> and
- is supported only if the emulator was configured and built with
- support for dirty schedulers enabled (it is disabled by default).</p>
</item>
<tag><marker id="+SDio"/><c><![CDATA[+SDio DirtyIOSchedulers]]></c></tag>
<item>
- <p>Sets the number of dirty I/O scheduler threads to create when
- threading support has been enabled. Valid range is 0-1024. By
+ <p>Sets the number of dirty I/O scheduler threads to create.
+ Valid range is 0-1024. By
default, the number of dirty I/O scheduler threads created is 10,
same as the default number of threads in the <seealso
marker="#async_thread_pool_size">async thread pool</seealso>.</p>
@@ -991,10 +1027,6 @@
expected to execute on dirty I/O schedulers. If the user should schedule CPU
bound jobs on dirty I/O schedulers, these jobs might starve ordinary
jobs executing on ordinary schedulers.</p>
- <p>This option is ignored if the emulator does not have threading
- support enabled. <em>This option is experimental</em> and
- is supported only if the emulator was configured and built with
- support for dirty schedulers enabled (it is disabled by default).</p>
</item>
<tag><c><![CDATA[+sFlag Value]]></c></tag>
<item>
@@ -1125,6 +1157,26 @@
without prior notice.</p>
</note>
</item>
+ <tag><marker id="+sbwtdcpu"/>
+ <c>+sbwtdcpu none|very_short|short|medium|long|very_long</c></tag>
+ <item>
+ <p>As <seealso marker="#+sbwt"><c>+sbwt</c></seealso> but affects
+ dirty CPU schedulers. Defaults to <c>short</c>.</p>
+ <note>
+ <p>This flag can be removed or changed at any time
+ without prior notice.</p>
+ </note>
+ </item>
+ <tag><marker id="+sbwtdio"/>
+ <c>+sbwtdio none|very_short|short|medium|long|very_long</c></tag>
+ <item>
+ <p>As <seealso marker="#+sbwt"><c>+sbwt</c></seealso> but affects
+ dirty IO schedulers. Defaults to <c>short</c>.</p>
+ <note>
+ <p>This flag can be removed or changed at any time
+ without prior notice.</p>
+ </note>
+ </item>
<tag><marker id="+scl"/><c>+scl true|false</c></tag>
<item>
<p>Enables or disables scheduler compaction of load. By default
@@ -1271,25 +1323,6 @@
<seealso marker="erlang#system_info_cpu_topology">
<c>erlang:system_info(cpu_topology)</c></seealso>.</p>
</item>
- <tag><marker id="+secio"/><c>+secio true|false</c></tag>
- <item>
- <p>Enables or disables eager check I/O scheduling. Defaults
- to <c>true</c>. The default was changed from <c>false</c>
- as from ERTS 7.0. The behavior 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 parameter name implies,
- schedulers are more eager to check for I/O when
- <c>true</c> is passed. This, however, also implies that
- execution of outstanding I/O operation is not
- prioritized to the same extent as when <c>false</c> is
- passed.</p>
- <p><seealso marker="erlang#system_info_eager_check_io">
- <c>erlang:system_info(eager_check_io)</c></seealso>
- returns the value of this parameter used when starting
- the virtual machine.</p>
- </item>
<tag><marker id="+sfwi"/><c>+sfwi Interval</c></tag>
<item>
<p>Sets scheduler-forced wakeup interval. All run queues are
@@ -1324,8 +1357,22 @@
<c><![CDATA[+sss size]]></c></tag>
<item>
<p>Suggested stack size, in kilowords, for scheduler threads.
- Valid range is 4-8192 kilowords. The default stack size is
- OS-dependent.</p>
+ Valid range is 20-8192 kilowords. The default suggested
+ stack size is 128 kilowords.</p>
+ </item>
+ <tag><marker id="dcpu_sched_thread_stack_size"/>
+ <c><![CDATA[+sssdcpu size]]></c></tag>
+ <item>
+ <p>Suggested stack size, in kilowords, for dirty CPU scheduler
+ threads. Valid range is 20-8192 kilowords. The default
+ suggested stack size is 40 kilowords.</p>
+ </item>
+ <tag><marker id="dio_sched_thread_stack_size"/>
+ <c><![CDATA[+sssdio size]]></c></tag>
+ <item>
+ <p>Suggested stack size, in kilowords, for dirty IO scheduler
+ threads. Valid range is 20-8192 kilowords. The default
+ suggested stack size is 40 kilowords.</p>
</item>
<tag><marker id="+stbt"/><c>+stbt BindType</c></tag>
<item>
@@ -1395,6 +1442,26 @@
notice.</p>
</note>
</item>
+ <tag><marker id="+swtdcpu"/>
+ <c>+swtdcpu very_low|low|medium|high|very_high</c></tag>
+ <item>
+ <p>As <seealso marker="#+swt"><c>+swt</c></seealso> but
+ affects dirty CPU schedulers. Defaults to <c>medium</c>.</p>
+ <note>
+ <p>This flag can be removed or changed at any time
+ without prior notice.</p>
+ </note>
+ </item>
+ <tag><marker id="+swtdio"/>
+ <c>+swtdio very_low|low|medium|high|very_high</c></tag>
+ <item>
+ <p>As <seealso marker="#+swt"><c>+swt</c></seealso> but affects
+ dirty IO schedulers. Defaults to <c>medium</c>.</p>
+ <note>
+ <p>This flag can be removed or changed at any time
+ without prior notice.</p>
+ </note>
+ </item>
</taglist>
</item>
<tag><marker id="+t"/><c><![CDATA[+t size]]></c></tag>
@@ -1513,32 +1580,27 @@
<item>
<p><em>Unix systems</em>: This variable gives the number of seconds
that the emulator is allowed to spend writing a crash dump. When the
- given number of seconds have elapsed, the emulator is terminated by a
- <c>SIGALRM</c> signal.</p>
- <p>If the variable is <em>not</em> set or set to <c>0</c> seconds
- (<c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c>), the runtime system does
- not even attempt to write the crash dump file. It only terminates.</p>
- <p>If the variable is set to negative value, such as
- <c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c>, the runtime system
- waits indefinitely for the crash dump file to be written.</p>
- <p>This variable is used with <seealso marker="kernel:heart">
- <c>heart(3)</c></seealso> if <c>heart</c> is running:</p>
+ given number of seconds have elapsed, the emulator is terminated.</p>
<taglist>
<tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag>
- <item>Suppresses the writing a crash dump file entirely, thus
- rebooting the runtime system immediately. This is the same as not
- setting the environment variable.
+ <item>If the variable is set to <c>0</c> seconds, the runtime system does
+ not even attempt to write the crash dump file. It only terminates.
+ This is the default if option <c>-heart</c> is passed to <c>erl</c>
+ and <c>ERL_CRASH_DUMP_SECONDS</c> is not set.
+ </item>
+ <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag>
+ <item>If the variable is set to a positive value <c>S</c>,
+ wait for <c>S</c> seconds to complete the crash dump file and
+ then terminates the runtime system with a <c>SIGALRM</c> signal.
</item>
<tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag>
- <item>Setting the environment variable to a negative value causes the
- termination of the runtime system to wait until the crash dump file
- has been completly written.
- </item>
- <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag>
- <item>Waits for <c>S</c> seconds to complete the crash dump file and
- then terminates the runtime system.
+ <item>A negative value causes the termination of the runtime system
+ to wait indefinitely until the crash dump file has been completly
+ written. This is the default if option <c>-heart</c> is <em>not</em>
+ passed to <c>erl</c> and <c>ERL_CRASH_DUMP_SECONDS</c> is not set.
</item>
</taglist>
+ <p>See also <seealso marker="kernel:heart"><c>heart(3)</c></seealso>.</p>
</item>
<tag><c><![CDATA[ERL_CRASH_DUMP_BYTES]]></c></tag>
<item>
@@ -1622,9 +1684,7 @@
<tag>The <c>.erlang</c> startup file</tag>
<item>
<p>When Erlang/OTP is started, the system searches for a file named
- <c>.erlang</c> in the directory where Erlang/OTP is started. If not
- found, the user's home directory is searched for an <c>.erlang</c>
- file.</p>
+ <c>.erlang</c> in the user's home directory.</p>
<p>If an <c>.erlang</c> file is found, it is assumed to contain valid
Erlang expressions. These expressions are evaluated as if they were
input to the shell.</p>
@@ -1676,4 +1736,3 @@ code:load_abs("..../user_default"). ]]></code>
<seealso marker="tools:make"><c>make(3)</c></seealso></p>
</section>
</comref>
-