1erl(1)                           User Commands                          erl(1)
2
3
4

NAME

6       erl - The Erlang emulator.
7

DESCRIPTION

9       The erl program starts an Erlang runtime system. The exact details (for
10       example, whether erl is a script or a program and which other  programs
11       it calls) are system-dependent.
12
13       Windows users probably want to use the werl program instead, which runs
14       in its own window with scrollbars and  supports  command-line  editing.
15       The  erl  program on Windows provides no line editing in its shell, and
16       on Windows 95 there is no way to scroll back to text that has  scrolled
17       off  the screen. The erl program must be used, however, in pipelines or
18       if you want to redirect standard input or output.
19
20   Note:
21       As from ERTS 5.9 (Erlang/OTP R15B) the runtime system does  by  default
22       not  bind  schedulers  to logical processors. For more information, see
23       system flag +sbt.
24
25

EXPORTS

27       erl <arguments>
28
29              Starts an Erlang runtime system.
30
31              The arguments can be divided into  emulator  flags,  flags,  and
32              plain arguments:
33
34                * Any  argument starting with character + is interpreted as an
35                  emulator flag.
36
37                  As indicated by the name, emulator flags control the  behav‐
38                  ior of the emulator.
39
40                * Any  argument  starting  with character - (hyphen) is inter‐
41                  preted as a flag, which is to be passed to the  Erlang  part
42                  of  the runtime system, more specifically to the init system
43                  process, see init(3).
44
45                  The init process itself interprets some of these flags,  the
46                  init  flags.  It  also  stores any remaining flags, the user
47                  flags. The latter can be retrieved by calling init:get_argu‐
48                  ment/1.
49
50                  A  small  number  of "-" flags exist, which now actually are
51                  emulator flags, see the description below.
52
53                * Plain arguments are not interpreted in  any  way.  They  are
54                  also  stored  by  the  init  process and can be retrieved by
55                  calling init:get_plain_arguments/0. Plain arguments can  oc‐
56                  cur  before  the  first  flag, or after a -- flag. Also, the
57                  -extra flag causes everything that follows to  become  plain
58                  arguments.
59
60              Examples:
61
62              % erl +W w -sname arnie +R 9 -s my_init -extra +bertie
63              (arnie@host)1> init:get_argument(sname).
64              {ok,[["arnie"]]}
65              (arnie@host)2> init:get_plain_arguments().
66              ["+bertie"]
67
68              Here  +W  w  and  +R 9 are emulator flags. -s my_init is an init
69              flag, interpreted by init. -sname arnie is a user  flag,  stored
70              by init. It is read by Kernel and causes the Erlang runtime sys‐
71              tem to become  distributed.  Finally,  everything  after  -extra
72              (that is, +bertie) is considered as plain arguments.
73
74              % erl -myflag 1
75              1> init:get_argument(myflag).
76              {ok,[["1"]]}
77              2> init:get_plain_arguments().
78              []
79
80              Here the user flag -myflag 1 is passed to and stored by the init
81              process. It is a user-defined  flag,  presumably  used  by  some
82              user-defined application.
83

FLAGS

85       In the following list, init flags are marked "(init flag)". Unless oth‐
86       erwise specified, all other flags are user flags, for which the  values
87       can  be  retrieved by calling init:get_argument/1. Notice that the list
88       of user flags is not exhaustive, there can be more application-specific
89       flags that instead are described in the corresponding application docu‐
90       mentation.
91
92         -- (init flag):
93           Everything following -- up to the next flag  (-flag  or  +flag)  is
94           considered   plain   arguments   and   can   be   retrieved   using
95           init:get_plain_arguments/0.
96
97         -Application Par Val:
98           Sets the application configuration parameter Par to the  value  Val
99           for the application Application; see app(4) and application(3).
100
101         -args_file FileName:
102           Command-line  arguments  are read from the file FileName. The argu‐
103           ments read from the file replace flag '-args_file FileName' on  the
104           resulting command line.
105
106           The  file  FileName is to be a plain text file and can contain com‐
107           ments and command-line arguments. A comment begins with a # charac‐
108           ter  and  continues until the next end of line character. Backslash
109           (\\) is used as quoting character. All command-line  arguments  ac‐
110           cepted  by erl are allowed, also flag -args_file FileName. Be care‐
111           ful not to cause circular  dependencies  between  files  containing
112           flag -args_file, though.
113
114           The  flag  -extra  is treated in special way. Its scope ends at the
115           end of the file. Arguments following an -extra flag  are  moved  on
116           the  command  line into the -extra section, that is, the end of the
117           command line following after an -extra flag.
118
119         -async_shell_start:
120           The initial Erlang shell does not read user input until the  system
121           boot  procedure has been completed (Erlang/OTP 5.4 and later). This
122           flag disables the start synchronization feature and lets the  shell
123           start in parallel with the rest of the system.
124
125         -boot File:
126           Specifies  the  name  of the boot file, File.boot, which is used to
127           start the system; see init(3). Unless  File  contains  an  absolute
128           path,  the  system  searches  for  File.boot  in  the  current  and
129           $ROOT/bin directories.
130
131           Defaults to $ROOT/bin/start.boot.
132
133         -boot_var Var Dir:
134           If the boot script contains a path variable Var other  than  $ROOT,
135           this  variable  is  expanded to Dir. Used when applications are in‐
136           stalled   in   another   directory   than   $ROOT/lib;   see   sys‐
137           tools:make_script/1,2 in SASL.
138
139         -code_path_cache:
140           Enables the code path cache of the code server; see code(3).
141
142         -compile Mod1 Mod2 ...:
143           Compiles  the  specified modules and then terminates (with non-zero
144           exit code if the compilation of some file did not succeed). Implies
145           -noinput.
146
147           Not recommended; use erlc instead.
148
149         -config Config [Config ...]:
150           Specifies  the name of one or more configuration files, Config.con‐
151           fig, which is used to configure applications; see app(4) and appli‐
152           cation(3).  See the documentation for the configuration file format
153           for a description of the configuration  format  and  the  order  in
154           which configuration parameters are read.
155
156         -configfd FD [FD ...]:
157           Specifies the name of one or more file descriptors (called configu‐
158           ration file descriptors from here on) with configuration  data  for
159           applications;  see app(4) and application(3). See the documentation
160           for the configuration file format for a description of the configu‐
161           ration  format  and the order in which configuration parameters are
162           read.
163
164           A configuration file descriptor will be read until its end and will
165           then be closed.
166
167           The content of a configuration file descriptor is stored so that it
168           can be reused when init:restart/0 or init:restart/1 is called.
169
170           The parameter -configfd 0 implies -noinput.
171
172     Note:
173         It is not recommended to use file descriptors  1  (standard  output),
174         and 2 (standard error) together with -configfd as these file descrip‐
175         tors are typically used to print information to the console the  pro‐
176         gram is running in.
177
178
179           Examples (Unix shell):
180
181         $ erl \ -noshell \ -configfd 3 \ -eval \ 'io:format("~p~n",[application:get_env(kernel, logger_level)]),erlang:halt()' 3< \ <(echo '[{kernel, [{logger_level, warning}]}].')
182         {ok,warning}
183
184
185         $ echo '[{kernel, [{logger_level, warning}]}].' > test1.config
186         $ echo '[{kernel, [{logger_level, error}]}].' > test2.config
187         $ erl \ -noshell \ -configfd 3 \ -configfd 4 \ -eval \ 'io:format("~p~n",[application:get_env(kernel, logger_level)]),erlang:halt()' \ 3< test1.config 4< test2.config
188         {ok,error}
189
190
191         -connect_all false:
192           This  flag is deprecated and has been replaced by the kernel appli‐
193           cation parameter connect_all.
194
195         -cookie Cookie:
196           Obsolete flag without any effect and common misspelling  for  -set‐
197           cookie. Use -setcookie instead.
198
199         -detached:
200           Starts  the Erlang runtime system detached from the system console.
201           Useful for  running  daemons  and  backgrounds  processes.  Implies
202           -noinput.
203
204         -disable-feature feature:
205           Disables  the  feature  feature  in the runtime system. The special
206           feature all can be used to disable all non permanent features.
207
208         -dist_listen true|false:
209           Specifies whether this node should be listening for  incoming  dis‐
210           tribution connections or not. By default a node will listen for in‐
211           coming connections. Setting this option to false implies -hidden.
212
213         -emu_args:
214           Useful for debugging. Prints the arguments sent to the emulator.
215
216         -emu_flavor emu|jit|smp:
217           Start an emulator of a different flavor. Normally only  one  flavor
218           is  available,  more can be added by building specific flavors. The
219           currently available flavors are: emu and jit. The smp flavor is  an
220           alias  for  the  current  default flavor. You can combine this flag
221           with --emu_type. You can get the current flavor at  run-time  using
222           erlang:system_info(emu_flavor). (The emulator with this flavor must
223           be built. You can build  a  specific  flavor  by  doing  make  FLA‐
224           VOR=$FLAVOR in the Erlang/OTP source repository.)
225
226         -emu_type Type:
227           Start  an  emulator  of a different type. For example, to start the
228           lock-counter emulator, use -emu_type lcnt. You can get the  current
229           type  at run-time using erlang:system_info(build_type). (The emula‐
230           tor of this type must already be built. Use  the  configure  option
231           --enable-lock-counter to build the lock-counter emulator.)
232
233         -enable-feature feature:
234           Enables the feature feature in the runtime system. The special fea‐
235           ture all can be used to enable all features.
236
237         -env Variable Value:
238           Sets the host OS environment variable Variable to the  value  Value
239           for the Erlang runtime system. Example:
240
241         % erl -env DISPLAY gin:0
242
243           In  this example, an Erlang runtime system is started with environ‐
244           ment variable DISPLAY set to gin:0.
245
246         -epmd_module Module (init flag):
247           Configures the module responsible to communicate to epmd.  Defaults
248           to erl_epmd.
249
250         -erl_epmd_port Port (init flag):
251           Configures  the  port used by erl_epmd to listen for connection and
252           connect to other nodes. See erl_epmd for more details. Defaults  to
253           0.
254
255         -eval Expr (init flag):
256           Makes init evaluate the expression Expr; see init(3).
257
258         -extra (init flag):
259           Everything  following  -extra is considered plain arguments and can
260           be retrieved using init:get_plain_arguments/0.
261
262         -heart:
263           Starts heartbeat monitoring  of  the  Erlang  runtime  system;  see
264           heart(3).
265
266         -hidden:
267           Starts  the Erlang runtime system as a hidden node, if it is run as
268           a distributed node. Hidden nodes always  establish  hidden  connec‐
269           tions to all other nodes except for nodes in the same global group.
270           Hidden connections are not published on any of the connected nodes,
271           that  is,  none  of the connected nodes are part of the result from
272           nodes/0  on  the  other  node.  See  also  hidden  global   groups;
273           global_group(3).
274
275         -hosts Hosts:
276           Specifies  the  IP  addresses  for  the  hosts on which Erlang boot
277           servers are running, see erl_boot_server(3). This flag is mandatory
278           if flag -loader inet is present.
279
280           The IP addresses must be specified in the standard form (four deci‐
281           mal numbers separated by  periods,  for  example,  "150.236.20.74".
282           Hosts names are not acceptable, but a broadcast address (preferably
283           limited to the local network) is.
284
285         -id Id:
286           Specifies the identity of the Erlang runtime system. If it  is  run
287           as  a  distributed  node, Id must be identical to the name supplied
288           together with flag -sname or -name.
289
290         -init_debug:
291           Makes init write some debug information while interpreting the boot
292           script.
293
294         -instr (emulator flag):
295           Selects  an instrumented Erlang runtime system (virtual machine) to
296           run, instead of the ordinary one. When running an instrumented run‐
297           time  system, some resource usage data can be obtained and analyzed
298           using the instrument module. Functionally, it behaves exactly  like
299           an ordinary Erlang runtime system.
300
301         -loader Loader:
302           Specifies the method used by erl_prim_loader to load Erlang modules
303           into the system; see erl_prim_loader(3).  Two  Loader  methods  are
304           supported:
305
306           * efile,  which  means  use  the local file system, this is the de‐
307             fault.
308
309           * inet, which means use a boot server on another machine. The flags
310             -id, -hosts and -setcookie must also be specified.
311
312           If  Loader is something else, the user-supplied Loader port program
313           is started.
314
315         -make:
316           Makes the Erlang runtime system invoke make:all()  in  the  current
317           working  directory  and then terminate; see make(3). Implies -noin‐
318           put.
319
320         -man Module:
321           Displays the manual page for the Erlang module  Module.  Only  sup‐
322           ported on Unix.
323
324         -mode interactive | embedded:
325           Modules  are auto loaded when they are first referenced if the run‐
326           time system runs in interactive mode, which is the default. In  em‐
327           bedded  mode modules are not auto loaded. The latter is recommended
328           when the boot script preloads all modules, as  conventionally  hap‐
329           pens in OTP releases. See code(3).
330
331         -name Name:
332           Makes  the Erlang runtime system into a distributed node. This flag
333           invokes all network servers necessary for a node to become distrib‐
334           uted; see net_kernel(3). It also ensures that epmd runs on the cur‐
335           rent host before Erlang is started (see epmd(1) and the -start_epmd
336           option) and that a magic cookie has been set (see -setcookie).
337
338           The  node name will be Name@Host, where Host is the fully qualified
339           host name of the current host. For short names, use flag -sname in‐
340           stead.
341
342           If  Name  is set to undefined the node will be started in a special
343           mode optimized to be the temporary client of another node. The node
344           will  then  request a dynamic node name from the first node it con‐
345           nects to. Read more in  Dynamic Node Name.
346
347     Warning:
348         Starting a  distributed  node  without  also  specifying  -proto_dist
349         inet_tls  will  expose the node to attacks that may give the attacker
350         complete access to the node and in extension the cluster. When  using
351         un-secure distributed nodes, make sure that the network is configured
352         to keep potential attackers out.
353
354
355         -no_epmd:
356           Specifies that the distributed node does not need epmd at all.
357
358           This option ensures that the Erlang runtime system does  not  start
359           epmd  and  does not start the erl_epmd process for distribution ei‐
360           ther.
361
362           This option only works if Erlang is started as a  distributed  node
363           with  the  -proto_dist option using an alternative protocol for Er‐
364           lang distribution which does not rely on epmd for node registration
365           and discovery. For more information, see How to implement an Alter‐
366           native Carrier for the Erlang Distribution.
367
368         -noinput:
369           Ensures that the Erlang runtime system never tries to read any  in‐
370           put. Implies -noshell.
371
372         -noshell:
373           Starts  an  Erlang runtime system with no shell. This flag makes it
374           possible to have the Erlang runtime system as a component in a  se‐
375           ries of Unix pipes.
376
377         -nostick:
378           Disables  the  sticky directory facility of the Erlang code server;
379           see code(3).
380
381         -oldshell:
382           Invokes the old Erlang shell from Erlang/OTP 3.3. The old shell can
383           still be used.
384
385         -pa Dir1 Dir2 ...:
386           Adds  the  specified directories to the beginning of the code path,
387           similar to code:add_pathsa/1. Note that the order of the given  di‐
388           rectories will be reversed in the resulting path.
389
390           As  an  alternative  to  -pa,  if  several  directories  are  to be
391           prepended to the code path and the directories have a common parent
392           directory,  that  parent  directory can be specified in environment
393           variable ERL_LIBS; see code(3).
394
395         -pz Dir1 Dir2 ...:
396           Adds the specified directories to the end of the code path, similar
397           to code:add_pathsz/1; see code(3).
398
399         -path Dir1 Dir2 ...:
400           Replaces the path specified in the boot script; see script(4).
401
402         -proto_dist Proto:
403
404
405           Specifies a protocol for Erlang distribution:
406
407           inet_tcp:
408             TCP over IPv4 (the default)
409
410           inet_tls:
411             Distribution  over TLS/SSL, See the  Using SSL for Erlang Distri‐
412             bution User's Guide for details on how to setup a secure distrib‐
413             uted node.
414
415           inet6_tcp:
416             TCP over IPv6
417
418           For example, to start up IPv6 distributed nodes:
419
420         % erl -name test@ipv6node.example.com -proto_dist inet6_tcp
421
422         -remsh Node:
423           Starts Erlang with a remote shell connected to Node.
424
425           If  no  -name  or  -sname  is  given the node will be started using
426           -sname undefined. If Node does not contain a hostname, one is auto‐
427           matically taken from -name or -sname
428
429     Note:
430         Before  OTP-23  the user needed to supply a valid -sname or -name for
431         -remsh to work. This is still the case if the target node is not run‐
432         ning OTP-23 or later.
433
434
435     Note:
436         The connecting node needs to have a proper shell with terminal emula‐
437         tion. This means that UNIX users must use  an  Erlang  compiled  with
438         terminal capabilities and Windows users must use werl(1).
439
440
441         -rsh Program:
442           Specifies  an alternative to ssh for starting a slave node on a re‐
443           mote host; see slave(3).
444
445         -run Mod [Func [Arg1, Arg2, ...]] (init flag):
446           Makes init call the specified function. Func defaults to start.  If
447           no  arguments  are provided, the function is assumed to be of arity
448           0. Otherwise it is assumed to  be  of  arity  1,  taking  the  list
449           [Arg1,Arg2,...]  as  argument. All arguments are passed as strings.
450           See init(3).
451
452         -s Mod [Func [Arg1, Arg2, ...]] (init flag):
453           Makes init call the specified function. Func defaults to start.  If
454           no  arguments  are provided, the function is assumed to be of arity
455           0. Otherwise it is assumed to  be  of  arity  1,  taking  the  list
456           [Arg1,Arg2,...] as argument. All arguments are passed as atoms. See
457           init(3).
458
459         -setcookie Cookie:
460           Sets  the  magic  cookie  of  the   node   to   Cookie;   see   er‐
461           lang:set_cookie/1. See see section Distributed Erlang in the Erlang
462           Reference Manual for more details.
463
464         -setcookie Node Cookie:
465           Sets the magic cookie for Node to Cookie; see erlang:set_cookie/2.
466
467         -shutdown_time Time:
468           Specifies how long time (in milliseconds) the init process  is  al‐
469           lowed  to spend shutting down the system. If Time milliseconds have
470           elapsed, all processes still existing are killed. Defaults  to  in‐
471           finity.
472
473         -sname Name:
474           Makes the Erlang runtime system into a distributed node, similar to
475           -name, but the host name portion of the node name Name@Host will be
476           the short name, not fully qualified.
477
478           This is sometimes the only way to run distributed Erlang if the Do‐
479           main Name System (DNS) is not running. No communication  can  exist
480           between  nodes running with flag -sname and those running with flag
481           -name, as node names must be unique in distributed Erlang systems.
482
483           If Name is set to undefined the node will be started in  a  special
484           mode optimized to be the temporary client of another node. The node
485           will then request a dynamic node name from the first node  it  con‐
486           nects to. Read more in  Dynamic Node Name.
487
488     Warning:
489         Starting  a  distributed  node  without  also  specifying -proto_dist
490         inet_tls will expose the node to attacks that may give  the  attacker
491         complete  access to the node and in extension the cluster. When using
492         un-secure distributed nodes, make sure that the network is configured
493         to keep potential attackers out.
494
495
496         -start_epmd true | false:
497           Specifies  whether  Erlang should start epmd on startup. By default
498           this is true, but if you prefer to start epmd manually, set this to
499           false.
500
501           This  only applies if Erlang is started as a distributed node, i.e.
502           if -name or -sname is specified. Otherwise,  epmd  is  not  started
503           even if -start_epmd true is given.
504
505           Note that a distributed node will fail to start if epmd is not run‐
506           ning.
507
508         -version (emulator flag):
509           Makes the emulator print its version number. The same as erl +V.
510

EMULATOR FLAGS

512       erl invokes the code for the Erlang emulator (virtual  machine),  which
513       supports the following flags:
514
515         +a size:
516           Suggested stack size, in kilowords, for threads in the async thread
517           pool. Valid range is 16-8192 kilowords. The default suggested stack
518           size is 16 kilowords, that is, 64 kilobyte on 32-bit architectures.
519           This small default size has been chosen because the number of async
520           threads can be large. The default size is enough for drivers deliv‐
521           ered with Erlang/OTP, but might not be large enough for  other  dy‐
522           namically linked-in drivers that use the driver_async() functional‐
523           ity. Notice that the value passed is only a suggestion, and it  can
524           even be ignored on some platforms.
525
526         +A size:
527           Sets  the  number  of  threads in async thread pool. Valid range is
528           1-1024. The async thread pool is used by linked-in drivers to  han‐
529           dle  work  that  may  take a very long time. Since OTP 21 there are
530           very few linked-in drivers in the default  Erlang/OTP  distribution
531           that uses the async thread pool. Most of them have been migrated to
532           dirty IO schedulers. Defaults to 1.
533
534         +B [c | d | i]:
535           Option c makes Ctrl-C interrupt the current shell instead of invok‐
536           ing  the  emulator  break  handler. Option d (same as specifying +B
537           without an extra option) disables the break handler. Option i makes
538           the emulator ignore any break signal.
539
540           If  option c is used with oldshell on Unix, Ctrl-C will restart the
541           shell process rather than interrupt it.
542
543           Notice that on Windows, this flag is only applicable for werl,  not
544           erl  (oldshell).  Notice  also  that  Ctrl-Break is used instead of
545           Ctrl-C on Windows.
546
547         +c true | false:
548           Enables or disables time correction:
549
550           true:
551             Enables time correction. This is the default if  time  correction
552             is supported on the specific platform.
553
554           false:
555             Disables time correction.
556
557           For  backward compatibility, the boolean value can be omitted. This
558           is interpreted as +c false.
559
560         +C no_time_warp | single_time_warp | multi_time_warp:
561           Sets time warp mode:
562
563           no_time_warp:
564              No time warp mode (the default)
565
566           single_time_warp:
567              Single time warp mode
568
569           multi_time_warp:
570              Multi-time warp mode
571
572         +d:
573           If the emulator detects an internal error (or runs out of  memory),
574           it,  by  default,  generates both a crash dump and a core dump. The
575           core dump is, however, not very useful as the  content  of  process
576           heaps is destroyed by the crash dump generation.
577
578           Option +d instructs the emulator to produce only a core dump and no
579           crash dump if an internal error is detected.
580
581           Calling erlang:halt/1 with a string argument still produces a crash
582           dump. On Unix systems, sending an emulator process a SIGUSR1 signal
583           also forces a crash dump.
584
585         +dcg DecentralizedCounterGroupsLimit:
586           Limits the number of decentralized counter groups  used  by  decen‐
587           tralized  counters  optimized  for  update operations in the Erlang
588           runtime system. By default, the limit is 256.
589
590           When the number of schedulers is less than or equal to  the  limit,
591           each  scheduler has its own group. When the number of schedulers is
592           larger than the  groups  limit,  schedulers  share  groups.  Shared
593           groups  degrade  the  performance  for updating counters while many
594           reader groups degrade the performance for reading counters. So, the
595           limit  is  a tradeoff between performance for update operations and
596           performance for read operations. Each group consumes  64  bytes  in
597           each counter.
598
599           Notice  that  a  runtime  system using decentralized counter groups
600           benefits from binding schedulers  to  logical  processors,  as  the
601           groups are distributed better between schedulers with this option.
602
603           This  option only affects decentralized counters used for the coun‐
604           ters that are keeping track of the memory consumption and the  num‐
605           ber  of terms in ETS tables of type ordered_set with the write_con‐
606           currency option activated.
607
608         +e Number:
609           Sets the maximum number of ETS tables. This limit is partially  ob‐
610           solete.
611
612         +ec:
613           Forces  option compressed on all ETS tables. Only intended for test
614           and evaluation.
615
616         +fnl:
617           The virtual machine works with filenames as if they are encoded us‐
618           ing  the  ISO Latin-1 encoding, disallowing Unicode characters with
619           code points > 255.
620
621           For more information about Unicode filenames, see  section  Unicode
622           Filenames  in  the STDLIB User's Guide. Notice that this value also
623           applies to command-line parameters and environment  variables  (see
624           section  Unicode in Environment and Parameters in the STDLIB User's
625           Guide).
626
627         +fnu[{w|i|e}]:
628           The virtual machine works with filenames as if they are encoded us‐
629           ing UTF-8 (or some other system-specific Unicode encoding). This is
630           the default on operating systems  that  enforce  Unicode  encoding,
631           that is, Windows MacOS X and Android.
632
633           The  +fnu  switch  can  be  followed  by  w, i, or e to control how
634           wrongly encoded filenames are to be reported:
635
636           * w means that a warning is sent to  the  error_logger  whenever  a
637             wrongly encoded filename is "skipped" in directory listings. This
638             is the default.
639
640           * i means that those wrongly encoded  filenames  are  silently  ig‐
641             nored.
642
643           * e means that the API function returns an error whenever a wrongly
644             encoded filename (or directory name) is encountered.
645
646           Notice that file:read_link/1 always returns an error  if  the  link
647           points to an invalid filename.
648
649           For  more  information about Unicode filenames, see section Unicode
650           Filenames in the STDLIB User's Guide. Notice that this  value  also
651           applies  to  command-line parameters and environment variables (see
652           section  Unicode in Environment and Parameters in the STDLIB User's
653           Guide).
654
655         +fna[{w|i|e}]:
656           Selection between +fnl and +fnu is done based on the current locale
657           settings in the OS. This means that if you have set  your  terminal
658           for  UTF-8 encoding, the filesystem is expected to use the same en‐
659           coding for filenames. This is the default on all operating systems,
660           except Android, MacOS X and Windows.
661
662           The  +fna  switch can be followed by w, i, or e. This has effect if
663           the locale settings cause the behavior of +fnu to be selected;  see
664           the description of +fnu above. If the locale settings cause the be‐
665           havior of +fnl to be selected, then w, i, or e have no effect.
666
667           For more information about Unicode filenames, see  section  Unicode
668           Filenames  in  the STDLIB User's Guide. Notice that this value also
669           applies to command-line parameters and environment  variables  (see
670           section  Unicode in Environment and Parameters in the STDLIB User's
671           Guide).
672
673         +hms Size:
674           Sets the default heap size of processes to the size Size.
675
676         +hmbs Size:
677           Sets the default binary virtual heap size of processes to the  size
678           Size.
679
680         +hmax Size:
681           Sets  the  default  maximum heap size of processes to the size Size
682           words. Defaults to 0, which means that  no  maximum  heap  size  is
683           used.  For  more  information, see process_flag(max_heap_size, Max‐
684           HeapSize).
685
686         +hmaxel true|false:
687           Sets whether to send an error logger message or not  for  processes
688           reaching the maximum heap size. Defaults to true. For more informa‐
689           tion, see process_flag(max_heap_size, MaxHeapSize).
690
691         +hmaxib true|false:
692           Sets whether to include the size of shared off-heap binaries in the
693           sum  compared against the maximum heap size. Defaults to false. For
694           more information, see process_flag(max_heap_size, MaxHeapSize).
695
696         +hmaxk true|false:
697           Sets whether to kill processes reaching the maximum  heap  size  or
698           not.    Default    to    true.    For    more    information,   see
699           process_flag(max_heap_size, MaxHeapSize).
700
701         +hpds Size:
702           Sets the initial process dictionary size of processes to  the  size
703           Size.
704
705         +hmqd off_heap|on_heap:
706           Sets  the default value of the message_queue_data process flag. De‐
707           faults to on_heap. If +hmqd is not passed, on_heap will be the  de‐
708           fault.  For  more information, see process_flag(message_queue_data,
709           MQD).
710
711         +IOp PollSets:
712           Sets the number of IO pollsets to use when polling  for  I/O.  This
713           option is only used on platforms that support concurrent updates of
714           a pollset, otherwise the same number of pollsets  are  used  as  IO
715           poll threads. The default is 1.
716
717         +IOt PollThreads:
718           Sets the number of IO poll threads to use when polling for I/O. The
719           maximum number of poll threads allowed is 1024. The default is 1.
720
721           A good way to check if more IO poll threads are needed  is  to  use
722           microstate  accounting  and see what the load of the IO poll thread
723           is. If it is high it could be a good idea to add more threads.
724
725         +IOPp PollSetsPercentage:
726           Similar to +IOp but uses  percentages  to  set  the  number  of  IO
727           pollsets to create, based on the number of poll threads configured.
728           If both +IOPp and +IOp are used, +IOPp is ignored.
729
730         +IOPt PollThreadsPercentage:
731           Similar to +IOt but uses percentages to set the number of  IO  poll
732           threads to create, based on the number of schedulers configured. If
733           both +IOPt and +IOt are used, +IOPt is ignored.
734
735         +IOs true|false:
736           Enable or disable scheduler thread poll  optimization.  Default  is
737           true.
738
739           If  enabled, file descriptors that are frequently read may be moved
740           to a special pollset used by scheduler threads. The objective is to
741           reduce  the number of system calls and thereby CPU load, but it can
742           in some cases increase scheduling latency for individual  file  de‐
743           scriptor input events.
744
745         +JPperf true|false|dump|map|fp|no_fp:
746           Enables or disables support for the perf profiler when running with
747           the JIT on Linux. Defaults to false.
748
749           This option can be combined multiple times to  enable  several  op‐
750           tions:
751
752           dump:
753             Gives  perf  detailed line information, so that the perf annotate
754             feature works.
755
756           map:
757             Gives perf a map over all module code, letting it  translate  ma‐
758             chine  code  addresses to Erlang source code locations. This also
759             enables frame pointers for Erlang code so that perf can walk  the
760             call  stacks  of Erlang processes, which costs one extra word per
761             stack frame.
762
763           fp:
764             Enables frame pointers independently of the map option.
765
766           no_fp:
767             Disables the frame pointers added by the map option.
768
769           true:
770             Enables map and dump.
771
772           false:
773             Disables all other options.
774
775           For more details about how to run perf see the perf support section
776           in the BeamAsm internal documentation.
777
778         +JMsingle true|false:
779           Enables  or  disables  the  use of single-mapped RWX memory for JIT
780           code. The default is to map JIT:ed machine code  into  two  regions
781           sharing the same physical pages, where one region is executable but
782           not writable, and the other writable but not  executable.  As  some
783           tools,  such as QEMU user mode emulation, cannot deal with the dual
784           mapping, this flags allows it to be disabled. This flag is automat‐
785           ically enabled by the +JPperf flag.
786
787         +L:
788           Prevents  loading  information about source filenames and line num‐
789           bers. This saves some memory, but exceptions do not contain  infor‐
790           mation about the filenames and line numbers.
791
792         +MFlag Value:
793           Memory allocator-specific flags. For more information, see erts_al‐
794           loc(3).
795
796         +pad true|false:
797           Since: OTP 25.3
798
799           The boolean value used with the +pad parameter determines  the  de‐
800           fault  value  of  the async_dist process flag of newly spawned pro‐
801           cesses. By default, if no +pad command line option is  passed,  the
802           async_dist flag will be set to false.
803
804           The  value  used in runtime can be inspected by calling erlang:sys‐
805           tem_info(async_dist).
806
807         +pc Range:
808           Sets the range of characters that the system considers printable in
809           heuristic  detection  of strings. This typically affects the shell,
810           debugger, and io:format functions (when ~tp is used in  the  format
811           string).
812
813           Two values are supported for Range:
814
815           latin1:
816             The default. Only characters in the ISO Latin-1 range can be con‐
817             sidered printable. This means that a character with a code  point
818             >  255  is  never  considered printable and that lists containing
819             such characters are displayed as lists of  integers  rather  than
820             text strings by tools.
821
822           unicode:
823             All  printable Unicode characters are considered when determining
824             if a list of integers is to be displayed in string  syntax.  This
825             can  give  unexpected results if, for example, your font does not
826             cover all Unicode characters.
827
828           See also io:printable_range/0 in STDLIB.
829
830         +P Number:
831           Sets the maximum number of simultaneously  existing  processes  for
832           this  system if a Number is passed as value. Valid range for Number
833           is [1024-134217727]
834
835           NOTE: The actual maximum chosen may be much larger than the  Number
836           passed. Currently the runtime system often, but not always, chooses
837           a value that is a power of 2. This might, however,  be  changed  in
838           the  future.  The actual value chosen can be checked by calling er‐
839           lang:system_info(process_limit).
840
841           The default value is 262144
842
843         +Q Number:
844           Sets the maximum number of simultaneously existing ports  for  this
845           system  if  a  Number is passed as value. Valid range for Number is
846           [1024-134217727]
847
848           NOTE: The actual maximum chosen may be much larger than the  actual
849           Number  passed. Currently the runtime system often, but not always,
850           chooses a value that is a power  of  2.  This  might,  however,  be
851           changed  in  the  future. The actual value chosen can be checked by
852           calling erlang:system_info(port_limit).
853
854           The default value used is normally 65536. However, if  the  runtime
855           system is able to determine maximum amount of file descriptors that
856           it is allowed to open and this value is larger than 65536, the cho‐
857           sen  value will increased to a value larger or equal to the maximum
858           amount of file descriptors that can be opened.
859
860           On Windows the default value is set to 8196 because the  normal  OS
861           limitations are set higher than most machines can handle.
862
863         +R ReleaseNumber:
864           Sets the compatibility mode.
865
866           The  distribution  mechanism is not backward compatible by default.
867           This flag sets the emulator in compatibility mode with  an  earlier
868           Erlang/OTP release ReleaseNumber. The release number must be in the
869           range <current release>-2..<current release>. This limits the  emu‐
870           lator,  making  it possible for it to communicate with Erlang nodes
871           (as well as C- and Java nodes) running that earlier release.
872
873     Note:
874         Ensure that all nodes (Erlang-, C-, and Java nodes) of a  distributed
875         Erlang  system is of the same Erlang/OTP release, or from two differ‐
876         ent Erlang/OTP releases X and Y, where all Y nodes have compatibility
877         mode X.
878
879
880         +r:
881           Forces ETS memory block to be moved on realloc.
882
883         +rg ReaderGroupsLimit:
884           Limits  the  number of reader groups used by read/write locks opti‐
885           mized for read operations in the Erlang runtime system. By  default
886           the reader groups limit is 64.
887
888           When  the  number of schedulers is less than or equal to the reader
889           groups limit, each scheduler has its own  reader  group.  When  the
890           number of schedulers is larger than the reader groups limit, sched‐
891           ulers share reader groups. Shared reader groups degrade  read  lock
892           and  read unlock performance while many reader groups degrade write
893           lock performance. So, the limit is a tradeoff  between  performance
894           for  read  operations  and  performance  for write operations. Each
895           reader group consumes 64 byte in each read/write lock.
896
897           Notice that a runtime system using shared  reader  groups  benefits
898           from binding schedulers to logical processors, as the reader groups
899           are distributed better between schedulers.
900
901         +S Schedulers:SchedulerOnline:
902           Sets the number  of  scheduler  threads  to  create  and  scheduler
903           threads  to set online. The maximum for both values is 1024. If the
904           Erlang runtime system is able to determine the  number  of  logical
905           processors  configured and logical processors available, Schedulers
906           defaults to logical processors configured, and SchedulersOnline de‐
907           faults  to logical processors available; otherwise the default val‐
908           ues are 1. If the emulator detects that it  is  subject  to  a  CPU
909           quota,  the  default value for SchedulersOnline will be limited ac‐
910           cordingly.
911
912           Schedulers can be omitted  if  :SchedulerOnline  is  not  and  con‐
913           versely.  The number of schedulers online can be changed at runtime
914           through erlang:system_flag(schedulers_online, SchedulersOnline).
915
916           If Schedulers or SchedulersOnline is specified as a  negative  num‐
917           ber,  the  value  is  subtracted from the default number of logical
918           processors configured  or  logical  processors  available,  respec‐
919           tively.
920
921           Specifying  value  0  for Schedulers or SchedulersOnline resets the
922           number of scheduler threads or scheduler  threads  online,  respec‐
923           tively, to its default value.
924
925         +SP SchedulersPercentage:SchedulersOnlinePercentage:
926           Similar  to  +S but uses percentages to set the number of scheduler
927           threads to create, based  on  logical  processors  configured,  and
928           scheduler threads to set online, based on logical processors avail‐
929           able. Specified values must be > 0. For example, +SP 50:25 sets the
930           number  of  scheduler threads to 50% of the logical processors con‐
931           figured, and the number of scheduler threads online to 25%  of  the
932           logical  processors  available. SchedulersPercentage can be omitted
933           if :SchedulersOnlinePercentage is not and conversely. The number of
934           schedulers  online  can  be  changed at runtime through erlang:sys‐
935           tem_flag(schedulers_online, SchedulersOnline).
936
937           This option interacts with +S settings. For example,  on  a  system
938           with  8 logical cores configured and 8 logical cores available, the
939           combination of the options +S 4:4 +SP 50:25 (in either  order)  re‐
940           sults  in 2 scheduler threads (50% of 4) and 1 scheduler thread on‐
941           line (25% of 4).
942
943         +SDcpu DirtyCPUSchedulers:DirtyCPUSchedulersOnline:
944           Sets the number of dirty CPU scheduler threads to create and  dirty
945           CPU scheduler threads to set online. The maximum for both values is
946           1024, and each value is further limited by the settings for  normal
947           schedulers:
948
949           * The  number  of dirty CPU scheduler threads created cannot exceed
950             the number of normal scheduler threads created.
951
952           * The number of dirty CPU scheduler threads  online  cannot  exceed
953             the number of normal scheduler threads online.
954
955           For  details,  see  the +S and +SP. By default, the number of dirty
956           CPU scheduler threads created equals the number of normal scheduler
957           threads  created, and the number of dirty CPU scheduler threads on‐
958           line equals the number of normal scheduler threads online.  DirtyC‐
959           PUSchedulers can be omitted if :DirtyCPUSchedulersOnline is not and
960           conversely. The number  of  dirty  CPU  schedulers  online  can  be
961           changed   at  runtime  through  erlang:system_flag(dirty_cpu_sched‐
962           ulers_online, DirtyCPUSchedulersOnline).
963
964           The amount of dirty CPU schedulers is limited by the amount of nor‐
965           mal  schedulers in order to limit the effect on processes executing
966           on ordinary schedulers. If the amount of dirty CPU  schedulers  was
967           allowed  to  be  unlimited,  dirty CPU bound jobs would potentially
968           starve normal jobs.
969
970           Typical users of the dirty CPU schedulers are large garbage collec‐
971           tions, json protocol encode/decoders written as nifs and matrix ma‐
972           nipulation libraries.
973
974           You can use msacc(3) in order to see the current load of the  dirty
975           CPU schedulers threads and adjust the number used accordingly.
976
977         +SDPcpu DirtyCPUSchedulersPercentage:DirtyCPUSchedulersOnlinePercent‐
978         age:
979           Similar to +SDcpu but uses percentages to set the number  of  dirty
980           CPU  scheduler threads to create and the number of dirty CPU sched‐
981           uler threads to set online. Specified values must be > 0. For exam‐
982           ple,  +SDPcpu  50:25 sets the number of dirty CPU scheduler threads
983           to 50% of the logical processors configured and the number of dirty
984           CPU  scheduler  threads  online  to  25%  of the logical processors
985           available. DirtyCPUSchedulersPercentage can be omitted if  :DirtyC‐
986           PUSchedulersOnlinePercentage  is  not and conversely. The number of
987           dirty CPU schedulers online can be changed at runtime  through  er‐
988           lang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
989           line).
990
991           This option interacts with +SDcpu settings. For example, on a  sys‐
992           tem  with 8 logical cores configured and 8 logical cores available,
993           the combination of the options +SDcpu 4:4 +SDPcpu 50:25 (in  either
994           order)  results  in  2 dirty CPU scheduler threads (50% of 4) and 1
995           dirty CPU scheduler thread online (25% of 4).
996
997         +SDio DirtyIOSchedulers:
998           Sets the number of dirty I/O scheduler  threads  to  create.  Valid
999           range  is  1-1024.  By  default,  the number of dirty I/O scheduler
1000           threads created is 10.
1001
1002           The amount of dirty IO schedulers is not limited by the  amount  of
1003           normal  schedulers  like  the  amount of dirty CPU schedulers. This
1004           since only I/O bound work is  expected  to  execute  on  dirty  I/O
1005           schedulers. If the user should schedule CPU bound jobs on dirty I/O
1006           schedulers, these jobs might starve ordinary jobs executing on  or‐
1007           dinary schedulers.
1008
1009           Typical users of the dirty IO schedulers are reading and writing to
1010           files.
1011
1012           You can use msacc(3) in order to see the current load of the  dirty
1013           IO schedulers threads and adjust the number used accordingly.
1014
1015         +sFlag Value:
1016           Scheduling specific flags.
1017
1018           +sbt BindType:
1019             Sets scheduler bind type.
1020
1021             Schedulers  can  also be bound using flag +stbt. The only differ‐
1022             ence between these two flags is how the following errors are han‐
1023             dled:
1024
1025             * Binding  of  schedulers  is not supported on the specific plat‐
1026               form.
1027
1028             * No available CPU topology. That is, the runtime system was  not
1029               able  to detect the CPU topology automatically, and no user-de‐
1030               fined CPU topology was set.
1031
1032             If any of these errors occur when +sbt has been passed, the  run‐
1033             time system prints an error message, and refuses to start. If any
1034             of these errors occur when +stbt has  been  passed,  the  runtime
1035             system  silently  ignores  the  error, and start up using unbound
1036             schedulers.
1037
1038             Valid BindTypes:
1039
1040             u:
1041               unbound - Schedulers are not bound to logical processors,  that
1042               is,  the  operating  system decides where the scheduler threads
1043               execute, and when to migrate them. This is the default.
1044
1045             ns:
1046               no_spread - Schedulers with  close  scheduler  identifiers  are
1047               bound as close as possible in hardware.
1048
1049             ts:
1050               thread_spread  - Thread refers to hardware threads (such as In‐
1051               tel's hyper-threads). Schedulers  with  low  scheduler  identi‐
1052               fiers,  are  bound  to  the first hardware thread of each core,
1053               then schedulers with higher scheduler identifiers are bound  to
1054               the second hardware thread of each core,and so on.
1055
1056             ps:
1057               processor_spread  -  Schedulers  are spread like thread_spread,
1058               but also over physical processor chips.
1059
1060             s:
1061               spread - Schedulers are spread as much as possible.
1062
1063             nnts:
1064               no_node_thread_spread - Like  thread_spread,  but  if  multiple
1065               Non-Uniform  Memory  Access  (NUMA) nodes exist, schedulers are
1066               spread over one NUMA node at a time, that is, all logical  pro‐
1067               cessors of one NUMA node are bound to schedulers in sequence.
1068
1069             nnps:
1070               no_node_processor_spread - Like processor_spread, but if multi‐
1071               ple NUMA nodes exist, schedulers are spread over one NUMA  node
1072               at a time, that is, all logical processors of one NUMA node are
1073               bound to schedulers in sequence.
1074
1075             tnnps:
1076               thread_no_node_processor_spread    -    A    combination     of
1077               thread_spread,  and  no_node_processor_spread.  Schedulers  are
1078               spread over hardware threads across NUMA nodes, but  schedulers
1079               are  only spread over processors internally in one NUMA node at
1080               a time.
1081
1082             db:
1083               default_bind - Binds schedulers the default  way.  Defaults  to
1084               thread_no_node_processor_spread  (which  can  change in the fu‐
1085               ture).
1086
1087             Binding of schedulers is only supported on newer Linux,  Solaris,
1088             FreeBSD, and Windows systems.
1089
1090             If  no  CPU topology is available when flag +sbt is processed and
1091             BindType is any other type than u, the runtime  system  fails  to
1092             start.  CPU  topology can be defined using flag +sct. Notice that
1093             flag +sct can have to be passed before flag +sbt on  the  command
1094             line (if no CPU topology has been automatically detected).
1095
1096             The runtime system does by default not bind schedulers to logical
1097             processors.
1098
1099       Note:
1100           If the Erlang runtime system is the only operating  system  process
1101           that binds threads to logical processors, this improves the perfor‐
1102           mance of the runtime system. However,  if  other  operating  system
1103           processes  (for  example  another  Erlang runtime system) also bind
1104           threads to logical processors, there can be a  performance  penalty
1105           instead.  This  performance penalty can sometimes be severe. If so,
1106           you are advised not to bind the schedulers.
1107
1108
1109             How schedulers are bound matters. For example, in situations when
1110             there  are  fewer  running  processes than schedulers online, the
1111             runtime system tries to migrate processes to schedulers with  low
1112             scheduler  identifiers.  The  more the schedulers are spread over
1113             the hardware, the more resources are  available  to  the  runtime
1114             system in such situations.
1115
1116       Note:
1117           If a scheduler fails to bind, this is often silently ignored, as it
1118           is not always possible to verify valid  logical  processor  identi‐
1119           fiers. If an error is reported, it is reported to the error_logger.
1120           If you want to verify that the schedulers have bound as  requested,
1121           call erlang:system_info(scheduler_bindings).
1122
1123
1124           +sbwt none|very_short|short|medium|long|very_long:
1125             Sets  scheduler  busy  wait  threshold.  Defaults  to medium. The
1126             threshold determines how long schedulers are to  busy  wait  when
1127             running out of work before going to sleep.
1128
1129       Note:
1130           This  flag  can be removed or changed at any time without prior no‐
1131           tice.
1132
1133
1134           +sbwtdcpu none|very_short|short|medium|long|very_long:
1135             As +sbwt but affects dirty CPU schedulers. Defaults to short.
1136
1137       Note:
1138           This flag can be removed or changed at any time without  prior  no‐
1139           tice.
1140
1141
1142           +sbwtdio none|very_short|short|medium|long|very_long:
1143             As +sbwt but affects dirty IO schedulers. Defaults to short.
1144
1145       Note:
1146           This  flag  can be removed or changed at any time without prior no‐
1147           tice.
1148
1149
1150           +scl true|false:
1151             Enables or disables scheduler  compaction  of  load.  By  default
1152             scheduler  compaction of load is enabled. When enabled, load bal‐
1153             ancing strives for a load  distribution,  which  causes  as  many
1154             scheduler  threads  as  possible to be fully loaded (that is, not
1155             run out of work). This is accomplished by migrating load (for ex‐
1156             ample,  runnable processes) into a smaller set of schedulers when
1157             schedulers frequently run out of work. When  disabled,  the  fre‐
1158             quency  with  which  schedulers run out of work is not taken into
1159             account by the load balancing logic.
1160
1161             +scl false is similar to +sub true, but +sub true  also  balances
1162             scheduler utilization between schedulers.
1163
1164           +sct CpuTopology:
1165
1166
1167             * <Id> = integer(); when 0 =< <Id> =< 65535
1168
1169             * <IdRange> = <Id>-<Id>
1170
1171             * <IdOrIdRange> = <Id> | <IdRange>
1172
1173             * <IdList> = <IdOrIdRange>,<IdOrIdRange> | <IdOrIdRange>
1174
1175             * <LogicalIds> = L<IdList>
1176
1177             * <ThreadIds> = T<IdList> | t<IdList>
1178
1179             * <CoreIds> = C<IdList> | c<IdList>
1180
1181             * <ProcessorIds> = P<IdList> | p<IdList>
1182
1183             * <NodeIds> = N<IdList> | n<IdList>
1184
1185             * <IdDefs>       =       <LogicalIds><ThreadIds><CoreIds><Proces‐
1186               sorIds><NodeIds>         |         <LogicalIds><ThreadIds><Cor‐
1187               eIds><NodeIds><ProcessorIds>
1188
1189             * CpuTopology = <IdDefs>:<IdDefs> | <IdDefs>
1190
1191             Sets  a  user-defined CPU topology. The user-defined CPU topology
1192             overrides any automatically detected CPU topology. The CPU topol‐
1193             ogy is used when binding schedulers to logical processors.
1194
1195             Uppercase  letters signify real identifiers and lowercase letters
1196             signify fake identifiers only used for description of the  topol‐
1197             ogy.  Identifiers  passed  as real identifiers can be used by the
1198             runtime system when trying to access specific hardware;  if  they
1199             are  incorrect the behavior is undefined. Faked logical CPU iden‐
1200             tifiers are not accepted, as there is no point  in  defining  the
1201             CPU  topology without real logical CPU identifiers. Thread, core,
1202             processor, and node identifiers can be omitted. If  omitted,  the
1203             thread ID defaults to t0, the core ID defaults to c0, the proces‐
1204             sor ID defaults to p0, and the node ID is left undefined.  Either
1205             each  logical  processor must belong to only one NUMA node, or no
1206             logical processors must belong to any NUMA nodes.
1207
1208             Both increasing and decreasing <IdRange>s are allowed.
1209
1210             NUMA node identifiers are system wide. That is, each NUMA node on
1211             the  system  must have a unique identifier. Processor identifiers
1212             are also system wide. Core identifiers are processor wide. Thread
1213             identifiers are core wide.
1214
1215             The  order  of  the identifier types implies the hierarchy of the
1216             CPU topology. The valid orders are as follows:
1217
1218             * <LogicalIds><ThreadIds><CoreIds><ProcessorIds><NodeIds>,   that
1219               is, thread is part of a core that is part of a processor, which
1220               is part of a NUMA node.
1221
1222             * <LogicalIds><ThreadIds><CoreIds><NodeIds><ProcessorIds>,   that
1223               is, thread is part of a core that is part of a NUMA node, which
1224               is part of a processor.
1225
1226             A CPU topology can consist of both processor external,  and  pro‐
1227             cessor  internal NUMA nodes as long as each logical processor be‐
1228             longs to only one NUMA node. If <ProcessorIds>  is  omitted,  its
1229             default  position  is  before  <NodeIds>. That is, the default is
1230             processor external NUMA nodes.
1231
1232             If a list of identifiers is used in an <IdDefs>:
1233
1234             * <LogicalIds> must be a list of identifiers.
1235
1236             * At least one other identifier type  besides  <LogicalIds>  must
1237               also have a list of identifiers.
1238
1239             * All  lists of identifiers must produce the same number of iden‐
1240               tifiers.
1241
1242             A simple example. A single quad core processor can  be  described
1243             as follows:
1244
1245           % erl +sct L0-3c0-3
1246           1> erlang:system_info(cpu_topology).
1247           [{processor,[{core,{logical,0}},
1248                        {core,{logical,1}},
1249                        {core,{logical,2}},
1250                        {core,{logical,3}}]}]
1251
1252             A  more  complicated  example with two quad core processors, each
1253             processor in its own NUMA node. The ordering of  logical  proces‐
1254             sors  is a bit weird. This to give a better example of identifier
1255             lists:
1256
1257           % erl +sct L0-1,3-2c0-3p0N0:L7,4,6-5c0-3p1N1
1258           1> erlang:system_info(cpu_topology).
1259           [{node,[{processor,[{core,{logical,0}},
1260                               {core,{logical,1}},
1261                               {core,{logical,3}},
1262                               {core,{logical,2}}]}]},
1263            {node,[{processor,[{core,{logical,7}},
1264                               {core,{logical,4}},
1265                               {core,{logical,6}},
1266                               {core,{logical,5}}]}]}]
1267
1268             As long as real identifiers are correct, it is OK to pass  a  CPU
1269             topology  that  is not a correct description of the CPU topology.
1270             When used with care this can be very useful. This  to  trick  the
1271             emulator  to bind its schedulers as you want. For example, if you
1272             want to run multiple Erlang runtime systems on the same  machine,
1273             you  want  to reduce the number of schedulers used and manipulate
1274             the CPU topology so that they bind to different logical CPUs.  An
1275             example, with two Erlang runtime systems on a quad core machine:
1276
1277           % erl +sct L0-3c0-3 +sbt db +S3:2 -detached -noinput -noshell -sname one
1278           % erl +sct L3-0c0-3 +sbt db +S3:2 -detached -noinput -noshell -sname two
1279
1280             In this example, each runtime system have two schedulers each on‐
1281             line, and all schedulers online will run on different  cores.  If
1282             we  change  to  one  scheduler  online on one runtime system, and
1283             three schedulers online on the other, all schedulers online  will
1284             still run on different cores.
1285
1286             Notice  that  a  faked CPU topology that does not reflect how the
1287             real CPU topology looks like is likely to  decrease  the  perfor‐
1288             mance of the runtime system.
1289
1290             For more information, see erlang:system_info(cpu_topology).
1291
1292           +ssrct:
1293             Skips reading CPU topology.
1294
1295       Note:
1296           Reading CPU topology slows down startup when starting many parallel
1297           instances of ERTS on systems with large amount of cores, using this
1298           flag might speed up execution in such scenarios.
1299
1300
1301           +sfwi Interval:
1302             Sets scheduler-forced wakeup interval. All run queues are scanned
1303             each Interval milliseconds. While there are  sleeping  schedulers
1304             in  the  system,  one  scheduler  is woken for each non-empty run
1305             queue found. Interval default to 0, meaning this feature is  dis‐
1306             abled.
1307
1308       Note:
1309           This  feature  has  been  introduced  as a temporary workaround for
1310           long-executing native code, and native code that does not bump  re‐
1311           ductions  properly  in  OTP.  When these bugs have been fixed, this
1312           flag will be removed.
1313
1314
1315           +spp Bool:
1316             Sets default scheduler hint for port parallelism. If set to true,
1317             the  virtual machine schedules port tasks when it improves paral‐
1318             lelism in the system. If set to false, the virtual machine  tries
1319             to  perform  port tasks immediately, improving latency at the ex‐
1320             pense of parallelism. Default to false. The default used  can  be
1321             inspected in runtime by calling erlang:system_info(port_parallel‐
1322             ism). The default can be overridden on port creation  by  passing
1323             option parallelism to erlang:open_port/2.
1324
1325           +sss size:
1326             Suggested  stack size, in kilowords, for scheduler threads. Valid
1327             range is 20-8192 kilowords. The default suggested stack  size  is
1328             128 kilowords.
1329
1330           +sssdcpu size:
1331             Suggested  stack  size,  in  kilowords,  for  dirty CPU scheduler
1332             threads. Valid range is 20-8192 kilowords. The default  suggested
1333             stack size is 40 kilowords.
1334
1335           +sssdio size:
1336             Suggested  stack  size,  in  kilowords,  for  dirty  IO scheduler
1337             threads. Valid range is 20-8192 kilowords. The default  suggested
1338             stack size is 40 kilowords.
1339
1340           +stbt BindType:
1341             Tries  to  set the scheduler bind type. The same as flag +sbt ex‐
1342             cept how some errors are handled. For more information, see +sbt.
1343
1344           +sub true|false:
1345             Enables or disables  scheduler utilization balancing of load.  By
1346             default  scheduler  utilization balancing is disabled and instead
1347             scheduler compaction of load is enabled, which strives for a load
1348             distribution that causes as many scheduler threads as possible to
1349             be fully loaded (that is, not run out of  work).  When  scheduler
1350             utilization  balancing  is  enabled,  the system instead tries to
1351             balance scheduler utilization between schedulers. That is, strive
1352             for equal scheduler utilization on all schedulers.
1353
1354             +sub  true  is only supported on systems where the runtime system
1355             detects  and  uses  a  monotonically  increasing  high-resolution
1356             clock. On other systems, the runtime system fails to start.
1357
1358             +sub  true  implies  +scl false. The difference between +sub true
1359             and +scl false is that +scl false does not  try  to  balance  the
1360             scheduler utilization.
1361
1362           +swct very_eager|eager|medium|lazy|very_lazy:
1363             Sets  scheduler  wake cleanup threshold. Defaults to medium. Con‐
1364             trols how eager schedulers are to be requesting wakeup because of
1365             certain  cleanup  operations.  When  a lazy setting is used, more
1366             outstanding cleanup operations can be left undone while a  sched‐
1367             uler  is  idling.  When  an eager setting is used, schedulers are
1368             more frequently woken, potentially increasing CPU-utilization.
1369
1370       Note:
1371           This flag can be removed or changed at any time without  prior  no‐
1372           tice.
1373
1374
1375           +sws default|legacy:
1376             Sets  scheduler wakeup strategy. Default strategy changed in ERTS
1377             5.10 (Erlang/OTP R16A). This strategy was known  as  proposal  in
1378             Erlang/OTP  R15. The legacy strategy was used as default from R13
1379             up to and including R15.
1380
1381       Note:
1382           This flag can be removed or changed at any time without  prior  no‐
1383           tice.
1384
1385
1386           +swt very_low|low|medium|high|very_high:
1387             Sets  scheduler wakeup threshold. Defaults to medium. The thresh‐
1388             old determines when to wake up sleeping schedulers when more work
1389             than  can  be handled by currently awake schedulers exists. A low
1390             threshold causes earlier wakeups, and  a  high  threshold  causes
1391             later wakeups. Early wakeups distribute work over multiple sched‐
1392             ulers faster, but work does more  easily  bounce  between  sched‐
1393             ulers.
1394
1395       Note:
1396           This  flag  can be removed or changed at any time without prior no‐
1397           tice.
1398
1399
1400           +swtdcpu very_low|low|medium|high|very_high:
1401             As +swt but affects dirty CPU schedulers. Defaults to medium.
1402
1403       Note:
1404           This flag can be removed or changed at any time without  prior  no‐
1405           tice.
1406
1407
1408           +swtdio very_low|low|medium|high|very_high:
1409             As +swt but affects dirty IO schedulers. Defaults to medium.
1410
1411       Note:
1412           This  flag  can be removed or changed at any time without prior no‐
1413           tice.
1414
1415
1416         +t size:
1417           Sets the maximum number of atoms the virtual  machine  can  handle.
1418           Defaults to 1,048,576.
1419
1420         +T Level:
1421           Enables  modified  timing and sets the modified timing level. Valid
1422           range is 0-9. The timing of the runtime system is changed.  A  high
1423           level usually means a greater change than a low level. Changing the
1424           timing can be very useful for finding timing-related bugs.
1425
1426           Modified timing affects the following:
1427
1428           Process spawning:
1429             A process calling spawn, spawn_link, spawn_monitor, or  spawn_opt
1430             is  scheduled  out  immediately  after  completing the call. When
1431             higher modified timing levels are used, the  caller  also  sleeps
1432             for a while after it is scheduled out.
1433
1434           Context reductions:
1435             The number of reductions a process is allowed to use before it is
1436             scheduled out is increased or reduced.
1437
1438           Input reductions:
1439             The number of reductions performed before  checking  I/O  is  in‐
1440             creased or reduced.
1441
1442     Note:
1443         Performance  suffers  when  modified  timing is enabled. This flag is
1444         only intended for testing and debugging.
1445
1446         return_to and return_from trace messages are lost when tracing on the
1447         spawn BIFs.
1448
1449         This flag can be removed or changed at any time without prior notice.
1450
1451
1452         +v:
1453           Verbose.
1454
1455         +V:
1456           Makes the emulator print its version number.
1457
1458         +W w | i | e:
1459           Sets  the  mapping  of  warning messages for error_logger. Messages
1460           sent to the error logger using one of the warning routines  can  be
1461           mapped  to  errors  (+W e), warnings (+W w), or information reports
1462           (+W i). Defaults to warnings. The current mapping can be  retrieved
1463           using  error_logger:warning_map/0.  For  more  information, see er‐
1464           ror_logger:warning_map/0 in Kernel.
1465
1466         +zFlag Value:
1467           Miscellaneous flags:
1468
1469           +zdbbl size:
1470             Sets the distribution buffer busy limit (dist_buf_busy_limit)  in
1471             kilobytes. Valid range is 1-2097151. Defaults to 1024.
1472
1473             A  larger  buffer  limit allows processes to buffer more outgoing
1474             messages over the distribution. When the buffer  limit  has  been
1475             reached,  sending  processes  will  be suspended until the buffer
1476             size has shrunk. The buffer limit is per distribution channel.  A
1477             higher limit gives lower latency and higher throughput at the ex‐
1478             pense of higher memory use.
1479
1480             This limit only affects processes that have disabled fully  asyn‐
1481             chronous distributed signaling .
1482
1483           +zdntgc time:
1484             Sets   the  delayed  node  table  garbage  collection  time  (de‐
1485             layed_node_table_gc) in seconds. Valid values are either infinity
1486             or an integer in the range 0-100000000. Defaults to 60.
1487
1488             Node  table entries that are not referred linger in the table for
1489             at least the amount of time that this parameter  determines.  The
1490             lingering  prevents  repeated deletions and insertions in the ta‐
1491             bles from occurring.
1492
1493           +zosrl limit:
1494             Sets a limit on the amount of outstanding requests made by a sys‐
1495             tem  process  orchestrating  system  wide changes. Valid range of
1496             this limit is [1,  134217727].  See  erlang:system_flag(outstand‐
1497             ing_system_requests_limit, Limit) for more information.
1498

ENVIRONMENT VARIABLES

1500         ERL_CRASH_DUMP:
1501           If  the  emulator  needs  to  write a crash dump, the value of this
1502           variable is the filename of the crash dump file. If the variable is
1503           not  set,  the name of the crash dump file is erl_crash.dump in the
1504           current directory.
1505
1506         ERL_CRASH_DUMP_NICE:
1507           Unix systems: If the emulator needs to write a crash dump, it  uses
1508           the  value  of this variable to set the nice value for the process,
1509           thus lowering its priority. Valid range is 1-39 (higher values  are
1510           replaced  with  39).  The  highest value, 39, gives the process the
1511           lowest priority.
1512
1513         ERL_CRASH_DUMP_SECONDS:
1514           Unix systems: This variable gives the number of  seconds  that  the
1515           emulator  is  allowed to spend writing a crash dump. When the given
1516           number of seconds have elapsed, the emulator is terminated.
1517
1518           ERL_CRASH_DUMP_SECONDS=0:
1519             If the variable is set to 0 seconds, the runtime system does  not
1520             even  attempt  to  write the crash dump file. It only terminates.
1521             This is the default  if  option  -heart  is  passed  to  erl  and
1522             ERL_CRASH_DUMP_SECONDS is not set.
1523
1524           ERL_CRASH_DUMP_SECONDS=S:
1525             If  the variable is set to a positive value S, wait for S seconds
1526             to complete the crash dump file and then terminates  the  runtime
1527             system with a SIGALRM signal.
1528
1529           ERL_CRASH_DUMP_SECONDS=-1:
1530             A  negative value causes the termination of the runtime system to
1531             wait indefinitely until the crash dump file has  been  completely
1532             written.  This  is  the default if option -heart is not passed to
1533             erl and ERL_CRASH_DUMP_SECONDS is not set.
1534
1535           See also heart(3).
1536
1537         ERL_CRASH_DUMP_BYTES:
1538           This variable sets the maximum size of a crash dump file in  bytes.
1539           The  crash dump will be truncated if this limit is exceeded. If the
1540           variable is not set, no size limit is enforced by default.  If  the
1541           variable  is  set to 0, the runtime system does not even attempt to
1542           write a crash dump file.
1543
1544           Introduced in ERTS 8.1.2 (Erlang/OTP 19.2).
1545
1546         ERL_AFLAGS:
1547           The content of this variable is added to the beginning of the  com‐
1548           mand line for erl.
1549
1550           Flag  -extra is treated in a special way. Its scope ends at the end
1551           of the environment variable content. Arguments following an  -extra
1552           flag  are  moved  on the command line into section -extra, that is,
1553           the end of the command line following an -extra flag.
1554
1555         ERL_ZFLAGS and ERL_FLAGS:
1556           The content of these variables are added to the end of the  command
1557           line for erl.
1558
1559           Flag  -extra is treated in a special way. Its scope ends at the end
1560           of the environment variable content. Arguments following an  -extra
1561           flag  are  moved  on the command line into section -extra, that is,
1562           the end of the command line following an -extra flag.
1563
1564         ERL_LIBS:
1565           Contains a list of additional library  directories  that  the  code
1566           server  searches  for  applications  and adds to the code path; see
1567           code(3).
1568
1569         ERL_EPMD_ADDRESS:
1570           Can be set to a comma-separated list of IP addresses, in which case
1571           the  epmd  daemon  listens only on the specified address(es) and on
1572           the loopback address (which is implicitly added to the list  if  it
1573           has not been specified).
1574
1575         ERL_EPMD_PORT:
1576           Can  contain  the  port number to use when communicating with epmd.
1577           The default port works fine in most cases. A different port can  be
1578           specified to allow nodes of independent clusters to co-exist on the
1579           same host. All nodes in a cluster must use the same epmd port  num‐
1580           ber.
1581

SIGNALS

1583       On  Unix  systems,  the Erlang runtime will interpret two types of sig‐
1584       nals.
1585
1586         SIGUSR1:
1587           A SIGUSR1 signal forces a crash dump.
1588
1589         SIGTERM:
1590           A SIGTERM will produce a stop message to the init process. This  is
1591           equivalent to a init:stop/0 call.
1592
1593           Introduced in ERTS 8.3 (Erlang/OTP 19.3)
1594
1595       The signal SIGUSR2 is reserved for internal usage. No other signals are
1596       handled.
1597

CONFIGURATION

1599       The standard Erlang/OTP system can be reconfigured to  change  the  de‐
1600       fault behavior on startup.
1601
1602         The .erlang startup file:
1603           When  Erlang/OTP  is  started, the system searches for a file named
1604           .erlang  in   the    user's   home   directory   and   then   file‐
1605           name:basedir(user_config, "erlang").
1606
1607           If  an .erlang file is found, it is assumed to contain valid Erlang
1608           expressions. These expressions are evaluated as if they were  input
1609           to the shell.
1610
1611           A typical .erlang file contains a set of search paths, for example:
1612
1613         io:format("executing user profile in $HOME/.erlang\n",[]).
1614         code:add_path("/home/calvin/test/ebin").
1615         code:add_path("/home/hobbes/bigappl-1.2/ebin").
1616         io:format(".erlang rc finished\n",[]).
1617
1618         user_default and shell_default:
1619           Functions  in  the shell that are not prefixed by a module name are
1620           assumed to be functional objects (funs), built-in functions (BIFs),
1621           or belong to the module user_default or shell_default.
1622
1623           To include private shell commands, define them in a module user_de‐
1624           fault and add the following argument as the first line in the  .er‐
1625           lang file:
1626
1627         code:load_abs("..../user_default").
1628
1629         erl:
1630           If  the  contents  of  .erlang are changed and a private version of
1631           user_default is defined, the Erlang/OTP environment can be  custom‐
1632           ized.  More  powerful changes can be made by supplying command-line
1633           arguments in the startup script  erl.  For  more  information,  see
1634           init(3).
1635

SEE ALSO

1637       epmd(1),  erl_prim_loader(3),  erts_alloc(3),  init(3), application(3),
1638       auth(3), code(3), erl_boot_server(3), heart(3), net_kernel(3), make(3)
1639
1640
1641
1642Ericsson AB                       erts 14.1.1                           erl(1)
Impressum