man pages section 1: User Commands

Exit Print View

Updated: July 2014

erl (1)


erl - The Erlang Emulator


Please see following description for synopsis


User Commands                                              erl(1)

     erl - The Erlang Emulator

     The  erl  program starts an Erlang runtime system. The exact
     details (for example, whether erl is a script or  a  program
     and which other programs it calls) are system-dependent.

     Windows  users  probably  wants  to  use  the  werl  program
     instead, which runs in its own window  with  scrollbars  and
     supports  command-line  editing.  The erl program on Windows
     provides no line editing in its shell,  and  on  Windows  95
     there  is  no  way to scroll back to text which has scrolled
     off the screen. The erl program must be  used,  however,  in
     pipelines  or if you want to redirect standard input or out-

     As of ERTS version 5.9 (OTP-R15B) the runtime system will by
     default  not bind schedulers to logical processors. For more
     information see documentation of the +sbt system flag.

     erl <arguments>

          Starts an Erlang runtime system.

          The arguments can be divided into emulator flags, flags
          and plain arguments:

            * Any  argument  starting  with  the  character  + is
              interpreted as an emulator flag.

              As indicated by the name, emulator  flags  controls
              the behavior of the emulator.

            * Any argument starting with the character - (hyphen)
              is interpreted as a flag which should be passed  to
              the Erlang part of the runtime system, more specif-
              ically to the init system process, see init(3).

              The init process itself interprets  some  of  these
              flags, the init flags. It also stores any remaining
              flags, the user flags. The latter can be  retrieved
              by calling init:get_argument/1.

              It  can  be  noted that there are a small number of
              "-" flags which now actually  are  emulator  flags,
              see the description below.

Ericsson AB         Last change: erts                   1

User Commands                                              erl(1)

            * Plain  arguments  are  not  interpreted in any way.
              They are also stored by the init process and can be
              retrieved  by  calling  init:get_plain_arguments/0.
              Plain arguments can occur before the first flag, or
              after  a  --  flag.  Additionally,  the flag -extra
              causes everything  that  follows  to  become  plain


          % erl +W w -sname arnie +R 9 -s my_init -extra +bertie
          (arnie@host)1> init:get_argument(sname).
          (arnie@host)2> init:get_plain_arguments().

          Here +W w and +R 9 are emulator flags. -s my_init is an
          init flag, interpreted by init. -sname arnie is a  user
          flag,  stored  by  init.  It is read by Kernel and will
          cause the Erlang runtime system to become  distributed.
          Finally,  everything after -extra (that is, +bertie) is
          considered as plain arguments.

          % erl -myflag 1
          1> init:get_argument(myflag).
          2> init:get_plain_arguments().

          Here the user flag -myflag 1 is passed to and stored by
          the init process. It is a user defined flag, presumably
          used by some user defined application.

     In the following list, init flags are  marked  (init  flag).
     Unless  otherwise specified, all other flags are user flags,
     for  which  the  values  can   be   retrieved   by   calling
     init:get_argument/1. Note that the list of user flags is not
     exhaustive, there may be  additional,  application  specific
     flags  which  instead  are  documented  in the corresponding
     application documentation.

       --(init flag):
         Everything following -- up to the next  flag  (-flag  or
         +flag)   is   considered  plain  arguments  and  can  be
         retrieved using init:get_plain_arguments/0.

       -Application Par Val:
         Sets the application configuration parameter Par to  the
         value  Val  for  the application Application, see app(4)
         and application(3).

Ericsson AB         Last change: erts                   2

User Commands                                              erl(1)

       -args_file FileName:
         Command line arguments are read from the file  FileName.
         The arguments read from the file replace the '-args_file
         FileName' flag on the resulting command line.

         The file FileName should be a plain text  file  and  may
         contain  comments  and command line arguments. A comment
         begins with a # character and continues until  next  end
         of  line  character.  Backslash  (\\) is used as quoting
         character. All command line arguments  accepted  by  erl
         are allowed, also the -args_file FileName flag. Be care-
         ful not to cause  circular  dependencies  between  files
         containing the -args_file flag, though.

         The  -extra flag is treated specially. Its scope ends at
         the end of the file. Arguments following an -extra  flag
         are  moved  on the command line into the -extra section,
         i.e. the end of the  command  line  following  after  an
         -extra flag.

         The  initial Erlang shell does not read user input until
         the system boot procedure has been completed (Erlang 5.4
         and later). This flag disables the start synchronization
         feature and lets the shell start in  parallel  with  the
         rest of the system.

       -boot File:
         Specifies the name of the boot file, File.boot, which is
         used to start the system. See init(3). Unless File  con-
         tains   an   absolute  path,  the  system  searches  for
         File.boot in the current and $ROOT/bin directories.

         Defaults to $ROOT/bin/start.boot.

       -boot_var Var Dir:
         If the boot script contains a path  variable  Var  other
         than  $ROOT, this variable is expanded to Dir. Used when
         applications are installed  in  another  directory  than
         $ROOT/lib, see systools:make_script/1,2.

         Enables  the  code  path  cache  of the code server, see

       -compile Mod1 Mod2 ...:
         Compiles the specified modules and then terminates (with
         non-zero  exit  code if the compilation of some file did
         not succeed). Implies -noinput. Not  recommended  -  use
         erlc instead.

       -config Config:

Ericsson AB         Last change: erts                   3

User Commands                                              erl(1)

         Specifies  the name of a configuration file, Config.con-
         fig, which is used to configure applications. See app(4)
         and application(3).

       -connect_all false:
         If  this  flag  is  present,  global will not maintain a
         fully connected network of distributed Erlang nodes, and
         then  global  name  registration  cannot  be  used.  See

       -cookie Cookie:
         Obsolete flag without any effect and common  misspelling
         for -setcookie. Use -setcookie instead.

         Starts  the Erlang runtime system detached from the sys-
         tem console. Useful for running daemons and  backgrounds
         processes. Implies -noinput.

         Useful  for  debugging.  Prints out the actual arguments
         sent to the emulator.

       -env Variable Value:
         Sets the host OS environment variable  Variable  to  the
         value Value for the Erlang runtime system. Example:

       % erl -env DISPLAY gin:0

         In  this  example,  an  Erlang runtime system is started
         with the DISPLAY environment variable set to gin:0.

       -eval Expr(init flag):
         Makes init evaluate the expression Expr, see init(3).

       -extra(init flag):
         Everything following -extra is  considered  plain  argu-
         ments  and  can  be retrieved using init:get_plain_argu-

         Starts heart beat monitoring of the Erlang runtime  sys-
         tem. See heart(3).

         Starts the Erlang runtime system as a hidden node, if it
         is run as a distributed node. Hidden nodes always estab-
         lish  hidden  connections  to all other nodes except for
         nodes in the same global group. Hidden  connections  are
         not  published  on  either  of the connected nodes, i.e.
         neither of the connected nodes are part  of  the  result
         from  nodes/0  on the other node. See also hidden global

Ericsson AB         Last change: erts                   4

User Commands                                              erl(1)

         groups, global_group(3).

       -hosts Hosts:
         Specifies the IP addresses for the hosts on which Erlang
         boot  servers  are running, see erl_boot_server(3). This
         flag is mandatory if the -loader inet flag is present.

         The IP addresses must be  given  in  the  standard  form
         (four  decimal numbers separated by periods, for example
         "". Hosts names are not acceptable,  but  a
         broadcast  address (preferably limited to the local net-
         work) is.

       -id Id:
         Specifies the identity of the Erlang runtime system.  If
         it is run as a distributed node, Id must be identical to
         the name supplied together  with  the  -sname  or  -name

         Makes init write some debug information while interpret-
         ing the boot script.

       -instr(emulator flag):
         Selects an instrumented Erlang runtime  system  (virtual
         machine)  to run, instead of the ordinary one. When run-
         ning an instrumented runtime system, some resource usage
         data  can  be  obtained  and  analysed  using the module
         instrument. Functionally, it  behaves  exactly  like  an
         ordinary Erlang runtime system.

       -loader Loader:
         Specifies  the  method  used  by erl_prim_loader to load
         Erlang modules into the system. See  erl_prim_loader(3).
         Two  Loader methods are supported, efile and inet. efile
         means use the local file system, this  is  the  default.
         inet means use a boot server on another machine, and the
         -id, -hosts and -setcookie flags must  be  specified  as
         well.  If  Loader  is  something else, the user supplied
         Loader port program is started.

         Makes the Erlang runtime system invoke make:all() in the
         current   working  directory  and  then  terminate.  See
         make(3). Implies -noinput.

       -man Module:
         Displays the manual page for the Erlang  module  Module.
         Only supported on Unix.

       -mode interactive | embedded:
         Indicates  if  the  system  should load code dynamically

Ericsson AB         Last change: erts                   5

User Commands                                              erl(1)

         (interactive), or if all code should  be  loaded  during
         system  initialization (embedded), see code(3). Defaults
         to interactive.

       -name Name:
         Makes the Erlang runtime system into a distributed node.
         This  flag  invokes  all network servers necessary for a
         node to become distributed.  See  net_kernel(3).  It  is
         also  ensured  that epmd runs on the current host before
         Erlang is started. See epmd(1).

         The name of the node will be Name@Host,  where  Host  is
         the  fully  qualified host name of the current host. For
         short names, use the -sname flag instead.

         Ensures that the Erlang runtime system  never  tries  to
         read any input. Implies -noshell.

         Starts an Erlang runtime system with no shell. This flag
         makes it possible to have the Erlang runtime system as a
         component in a series of UNIX pipes.

         Disables  the  sticky  directory  facility of the Erlang
         code server, see code(3).

         Invokes the old Erlang shell from Erlang  3.3.  The  old
         shell can still be used.

       -pa Dir1 Dir2 ...:
         Adds  the  specified directories to the beginning of the
         code path, similar to code:add_pathsa/1. See code(3). As
         an  alternative to -pa, if several directories are to be
         prepended to the code and the directories have a  common
         parent  directory, that parent directory could be speci-
         fied in the ERL_LIBS environment variable. See  code(3).

       -pz Dir1 Dir2 ...:
         Adds  the  specified  directories to the end of the code
         path, similar to code:add_pathsz/1. See code(3).

       -remsh Node:
         Starts Erlang with a remote shell connected to Node.

       -rsh Program:
         Specifies an alternative to rsh  for  starting  a  slave
         node on a remote host. See slave(3).

       -run Mod [Func [Arg1, Arg2, ...]](init flag):

Ericsson AB         Last change: erts                   6

User Commands                                              erl(1)

         Makes init call the specified function. Func defaults to
         start. If no arguments are  provided,  the  function  is
         assumed  to be of arity 0. Otherwise it is assumed to be
         of arity 1, taking the list [Arg1,Arg2,...] as argument.
         All arguments are passed as strings. See init(3).

       -s Mod [Func [Arg1, Arg2, ...]](init flag):
         Makes init call the specified function. Func defaults to
         start. If no arguments are  provided,  the  function  is
         assumed  to be of arity 0. Otherwise it is assumed to be
         of arity 1, taking the list [Arg1,Arg2,...] as argument.
         All arguments are passed as atoms. See init(3).

       -setcookie Cookie:
         Sets  the  magic  cookie  of  the  node  to  Cookie, see

       -shutdown_time Time:
         Specifies how  long  time  (in  milliseconds)  the  init
         process is allowed to spend shutting down the system. If
         Time ms have elapsed, all processes still  existing  are
         killed. Defaults to infinity.

       -sname Name:
         Makes the Erlang runtime system into a distributed node,
         similar to -name, but the host name portion of the  node
         name  Name@Host will be the short name, not fully quali-

         This is sometimes the only way to run distributed Erlang
         if  the  DNS  (Domain Name System) is not running. There
         can be no communication between nodes running  with  the
         -sname  flag  and  those running with the -name flag, as
         node names must be unique in distributed Erlang systems.

       -smp [enable|auto|disable]:
         -smp  enable  and  -smp starts the Erlang runtime system
         with SMP support enabled. This may fail  if  no  runtime
         system  with  SMP support is available. -smp auto starts
         the Erlang runtime system with SMP support enabled if it
         is  available  and  more  than one logical processor are
         detected. -smp disable starts a runtime  system  without
         SMP support.

         NOTE:  The  runtime  system with SMP support will not be
         available on all supported platforms. See  also  the  +S

       -version(emulator flag):
         Makes  the  emulator  print  out its version number. The
         same as erl +V.

Ericsson AB         Last change: erts                   7

User Commands                                              erl(1)

     erl invokes  the  code  for  the  Erlang  emulator  (virtual
     machine), which supports the following flags:

       +a size:
         Suggested  stack  size, in kilowords, for threads in the
         async-thread pool. Valid range is 16-8192 kilowords. The
         default  suggested  stack  size is 16 kilowords, i.e, 64
         kilobyte on 32-bit  architectures.  This  small  default
         size  has  been chosen since the amount of async-threads
         might be quite large. The default  size  is  enough  for
         drivers delivered with Erlang/OTP, but might not be suf-
         ficiently large for other dynamically linked in  drivers
         that use the driver_async() functionality. Note that the
         value passed is only a suggestion, and it might even  be
         ignored on some platforms.

       +A size:
         Sets  the  number of threads in async thread pool, valid
         range is 0-1024. Default is 0.

       +B [c | d | i]:
         The c option makes Ctrl-C interrupt  the  current  shell
         instead  of  invoking  the emulator break handler. The d
         option (same as specifying +B without an  extra  option)
         disables  the break handler. The i option makes the emu-
         lator ignore any break signal.

         If the c option is used with oldshell  on  Unix,  Ctrl-C
         will restart the shell process rather than interrupt it.

         Note that on Windows, this flag is only  applicable  for
         werl,  not  erl (oldshell). Note also that Ctrl-Break is
         used instead of Ctrl-C on Windows.

         Disable compensation for sudden changes of system  time.

         Normally, erlang:now/0 will not immediately reflect sud-
         den changes in the system time, in order to keep  timers
         (including  receive-after)  working.  Instead,  the time
         maintained by erlang:now/0 is  slowly  adjusted  towards
         the  new  system  time.  (Slowly  means  in  one percent
         adjustments; if the time is off by one minute, the  time
         will be adjusted in 100 minutes.)

         When  the  +c option is given, this slow adjustment will
         not take place. Instead erlang:now/0 will always reflect
         the  current  system time. Note that timers are based on
         erlang:now/0. If the system time jumps, timers then time
         out at the wrong time.

Ericsson AB         Last change: erts                   8

User Commands                                              erl(1)

         If  the  emulator detects an internal error (or runs out
         of memory), it will by default  generate  both  a  crash
         dump  and  a core dump. The core dump will, however, not
         be very useful since the content  of  process  heaps  is
         destroyed by the crash dump generation.

         The  +d  option instructs the emulator to only produce a
         core dump and no crash dump  if  an  internal  error  is

         Calling  erlang:halt/1 with a string argument will still
         produce a crash dump.

       +e Number:
         Set max number of ETS tables.

         Force the compressed option  on  all  ETS  tables.  Only
         intended for test and evaluation.

         The  VM  works  with  file  names as if they are encoded
         using  the  ISO-latin-1  encoding,  disallowing  Unicode
         characters  with  codepoints beyond 255. This is default
         on operating systems that have transparent file  naming,
         i.e. all Unixes except MacOSX.

         The  VM  works  with  file  names as if they are encoded
         using UTF-8  (or  some  other  system  specific  Unicode
         encoding). This is the default on operating systems that
         enforce Unicode encoding, i.e. Windows and MacOSX.

         By enabling Unicode file  name  translation  on  systems
         where  this is not default, you open up to the possibil-
         ity that some file names can not be interpreted  by  the
         VM  and therefore will be returned to the program as raw
         binaries. The option is therefore considered  experimen-

         Selection  between  +fnl  and  +fnu is done based on the
         current locale settings in the OS, meaning that  if  you
         have  set your terminal for UTF-8 encoding, the filesys-
         tem is expected to use the same encoding  for  filenames
         (use with care).

       +hms Size:
         Sets  the  default  heap  size  of processes to the size

Ericsson AB         Last change: erts                   9

User Commands                                              erl(1)

       +hmbs Size:
         Sets the default binary virtual heap size  of  processes
         to the size Size.

       +K true | false:
         Enables or disables the kernel poll functionality if the
         emulator supports it. Default is  false  (disabled).  If
         the  emulator  does  not support kernel poll, and the +K
         flag is passed to the emulator, a warning is  issued  at

         Enables auto load tracing, displaying info while loading

         Don't load information about source filenames  and  line
         numbers. This will save some memory, but exceptions will
         not contain information about  the  filenames  and  line

       +MFlag Value:
         Memory  allocator  specific flags, see erts_alloc(3) for
         further information.

       +P Number:
         Sets the maximum number of concurrent processes for this
         system.  Number  must  be  in  the  range 16..134217727.
         Default is 32768.

       +R ReleaseNumber:
         Sets the compatibility mode.

         The distribution mechanism is not  backwards  compatible
         by  default. This flags sets the emulator in compatibil-
         ity mode with an earlier Erlang/OTP release  ReleaseNum-
         ber. The release number must be in the range 7..<current
         release>. This limits the emulator, making  it  possible
         for  it  to communicate with Erlang nodes (as well as C-
         and Java nodes) running that earlier release.

         For example, an R10 node is not automatically compatible
         with  an  R9  node,  but R10 nodes started with the +R 9
         flag can co-exist with R9 nodes in the same  distributed
         Erlang system, they are R9-compatible.

         Note:  Make sure all nodes (Erlang-, C-, and Java nodes)
         of a distributed Erlang system is of the same Erlang/OTP
         release, or from two different Erlang/OTP releases X and
         Y, where all Y nodes have compatibility mode X.

Ericsson AB         Last change: erts                  10

User Commands                                              erl(1)

         For example: A distributed Erlang system can consist  of
         R10  nodes,  or of R9 nodes and R9-compatible R10 nodes,
         but not of R9 nodes, R9-compatible R10 nodes and  "regu-
         lar"  R10  nodes,  as R9 and "regular" R10 nodes are not

         Force ets memory block to be moved on realloc.

       +rg ReaderGroupsLimit:
         Limits the amount of reader groups  used  by  read/write
         locks  optimized  for read operations in the Erlang run-
         time system. By default the reader groups  limit  equals

         When  the  amount of schedulers is less than or equal to
         the reader groups limit,  each  scheduler  has  its  own
         reader  group.  When  the amount of schedulers is larger
         than the reader groups limit,  schedulers  share  reader
         groups. Shared reader groups degrades read lock and read
         unlock performance while a large amount of reader groups
         degrades  write  lock  performance,  so  the  limit is a
         tradeoff between performance  for  read  operations  and
         performance for write operations. Each reader group cur-
         rently consumes 64 byte in each  read/write  lock.  Also
         note  that  a  runtime system using shared reader groups
         benefits from binding schedulers to logical  processors,
         since  the  reader groups are distributed better between

       +S Schedulers:SchedulerOnline:
         Sets the amount  of  scheduler  threads  to  create  and
         scheduler  threads  to  set  online when SMP support has
         been enabled. Valid range for both values are 1-1024. If
         the  Erlang  runtime  system  is  able  to determine the
         amount of logical processors configured and logical pro-
         cessors  available,  Schedulers  will default to logical
         processors configured, and SchedulersOnline will default
         to  logical processors available; otherwise, the default
         values will be 1. Schedulers may be omitted  if  :Sched-
         ulerOnline  is  not and vice versa. The amount of sched-
         ulers online can be changed at run time via  erlang:sys-
         tem_flag(schedulers_online, SchedulersOnline).

         This  flag  will be ignored if the emulator doesn't have
         SMP support enabled (see the -smp flag).

       +sFlag Value:
         Scheduling specific flags.

         +sbt BindType:
           Set scheduler bind type. Currently valid BindTypes:

Ericsson AB         Last change: erts                  11

User Commands                                              erl(1)

             unbound - Schedulers will not be  bound  to  logical
             processors, i.e., the operating system decides where
             the scheduler threads execute, and when  to  migrate
             them. This is the default.

             no_spread  - Schedulers with close scheduler identi-
             fiers will be bound as close as  possible  in  hard-

             thread_spread  -  Thread  refers to hardware threads
             (e.g. Intel's hyper-threads).  Schedulers  with  low
             scheduler  identifiers,  will  be bound to the first
             hardware thread of each core, then  schedulers  with
             higher  scheduler  identifiers  will be bound to the
             second hardware thread of each core, etc.

             processor_spread - Schedulers will  be  spread  like
             thread_spread,  but  also  over  physical  processor

             spread - Schedulers will be spread as much as possi-

             no_node_thread_spread  -  Like thread_spread, but if
             multiple  NUMA  (Non-Uniform  Memory  Access)  nodes
             exists, schedulers will be spread over one NUMA node
             at a time, i.e., all logical processors of one  NUMA
             node will be bound to schedulers in sequence.

             no_node_processor_spread  -  Like  processor_spread,
             but if multiple NUMA nodes exists,  schedulers  will
             be  spread  over  one NUMA node at a time, i.e., all
             logical processors of one NUMA node will be bound to
             schedulers in sequence.

             thread_no_node_processor_spread  -  A combination of
             thread_spread, and no_node_processor_spread.  Sched-
             ulers  will  be  spread over hardware threads across
             NUMA nodes, but schedulers will only be spread  over
             processors internally in one NUMA node at a time.

             default_bind  -  Binds  schedulers  the default way.
             Currently          the          default           is

Ericsson AB         Last change: erts                  12

User Commands                                              erl(1)

             thread_no_node_processor_spread  (which might change
             in the future).

           Binding of schedulers is currently only  supported  on
           newer Linux, Solaris, FreeBSD, and Windows systems.

           If  no CPU topology is available when the +sbt flag is
           processed and BindType is any other type than  u,  the
           runtime system will fail to start. CPU topology can be
           defined using the +sct flag. Note that the  +sct  flag
           may have to be passed before the +sbt flag on the com-
           mand line (in case no CPU topology has been  automati-
           cally detected).

           The runtime system will by default not bind schedulers
           to logical processors.

           NOTE: If the Erlang runtime system is the only operat-
           ing  system process that binds threads to logical pro-
           cessors, this improves the performance of the  runtime
           system.  However,  if other operating system processes
           (as for example another Erlang  runtime  system)  also
           bind  threads  to logical processors, there might be a
           performance penalty instead. In some cases  this  per-
           formance penalty might be severe. If this is the case,
           you are advised to not bind the schedulers.

           How schedulers are bound matters. For example, in sit-
           uations  when  there  are fewer running processes than
           schedulers online, the runtime system tries to migrate
           processes  to  schedulers  with  low scheduler identi-
           fiers. The more the schedulers  are  spread  over  the
           hardware,  the more resources will be available to the
           runtime system in such situations.

           NOTE: If a scheduler fails to bind, this will often be
           silently  ignored. This since it isn't always possible
           to verify valid logical processor identifiers.  If  an
           error   is  reported,  it  will  be  reported  to  the
           error_logger. If you want to verify  that  the  sched-
           ulers   actually   have   bound   as  requested,  call

         +sbwt none|very_short|short|medium|long|very_long:
           Set scheduler busy wait threshold. Default is  medium.
           The  threshold  determines  how long schedulers should
           busy wait when running out of  work  before  going  to

           NOTE:  This flag may be removed or changed at any time
           without prior notice.

Ericsson AB         Last change: erts                  13

User Commands                                              erl(1)

         +scl true|false:
           Enable or disable scheduler  compaction  of  load.  By
           default  scheduler compaction of load is enabled. When
           enabled, load balancing will strive for a load distri-
           bution  which causes as many scheduler threads as pos-
           sible to be fully loaded (i.e., not run out of  work).
           This  is accomplished by migrating load (e.g. runnable
           processes) into  a  smaller  set  of  schedulers  when
           schedulers  frequently run out of work. When disabled,
           the frequency with which schedulers run  out  of  work
           will  not  be taken into account by the load balancing

         +sct CpuTopology:

           * <Id> = integer(); when 0 =< <Id> =< 65535

           * <IdRange> = <Id>-<Id>

           * <IdOrIdRange> = <Id> | <IdRange>

           * <IdList>     =     <IdOrIdRange>,<IdOrIdRange>     |

           * <LogicalIds> = L<IdList>

           * <ThreadIds> = T<IdList> | t<IdList>

           * <CoreIds> = C<IdList> | c<IdList>

           * <ProcessorIds> = P<IdList> | p<IdList>

           * <NodeIds> = N<IdList> | n<IdList>

           * <IdDefs>  = <LogicalIds><ThreadIds><CoreIds><Proces-
             sorIds><NodeIds>   |    <LogicalIds><ThreadIds><Cor-

           * CpuTopology = <IdDefs>:<IdDefs> | <IdDefs>

           Set  a user defined CPU topology. The user defined CPU
           topology will override any automatically detected  CPU
           topology. The CPU topology is used when binding sched-
           ulers to logical processors.

           Upper-case letters signify real identifiers and lower-
           case  letters  signify  fake identifiers only used for
           description of the  topology.  Identifiers  passed  as
           real  identifiers  may  be  used by the runtime system
           when trying to access specific hardware  and  if  they
           are  not  correct  the  behavior  is  undefined. Faked

Ericsson AB         Last change: erts                  14

User Commands                                              erl(1)

           logical CPU identifiers are not accepted  since  there
           is  no point in defining the CPU topology without real
           logical CPU identifiers. Thread, core, processor,  and
           node  identifiers may be left out. If left out, thread
           id defaults to t0, core id defaults to  c0,  processor
           id defaults to p0, and node id will be left undefined.
           Either each logical processor must belong to  one  and
           only  one  NUMA  node,  or  no logical processors must
           belong to any NUMA nodes.

           Both increasing and decreasing <IdRange>s are allowed.

           NUMA  node  identifiers are system wide. That is, each
           NUMA node on the system have to have a unique  identi-
           fier. Processor identifiers are also system wide. Core
           identifiers are processor wide. Thread identifiers are
           core wide.

           The  order of the identifier types imply the hierarchy
           of the CPU topology. Valid orders  are  either  <Logi-
           calIds><ThreadIds><CoreIds><ProcessorIds><NodeIds>, or
           sorIds>.  That  is,  thread is part of a core which is
           part of a processor which is part of a NUMA  node,  or
           thread  is part of a core which is part of a NUMA node
           which is part of a processor. A cpu topology can  con-
           sist  of both processor external, and processor inter-
           nal NUMA nodes  as  long  as  each  logical  processor
           belongs  to  one  and  only one NUMA node. If <Proces-
           sorIds> is left out,  its  default  position  will  be
           before  <NodeIds>.  That  is, the default is processor
           external NUMA nodes.

           If a list of identifiers is used in an <IdDefs>:

           * <LogicalIds> have to be a list of identifiers.

           * At least one other identifier type apart from <Logi-
             calIds> also have to have a list of identifiers.

           * All  lists  of  identifiers have to produce the same
             amount of identifiers.

           A simple example. A single quad core processor may  be
           described this way:

         % erl +sct L0-3c0-3
         1> erlang:system_info(cpu_topology).

Ericsson AB         Last change: erts                  15

User Commands                                              erl(1)

           A  little more complicated example. Two quad core pro-
           cessors. Each processor in  its  own  NUMA  node.  The
           ordering of logical processors is a little weird. This
           in order to give a better example of identifier lists:

         % erl +sct L0-1,3-2c0-3p0N0:L7,4,6-5c0-3p1N1
         1> erlang:system_info(cpu_topology).

           As  long as real identifiers are correct it is okay to
           pass a CPU topology that is not a correct  description
           of  the  CPU  topology.  When  used with care this can
           actually be very useful. This in order  to  trick  the
           emulator to bind its schedulers as you want. For exam-
           ple, if you want to run multiple Erlang  runtime  sys-
           tems  on  the  same  machine,  you  want to reduce the
           amount of  schedulers  used  and  manipulate  the  CPU
           topology  so that they bind to different logical CPUs.
           An example, with two Erlang runtime systems on a  quad
           core machine:

         % erl +sct L0-3c0-3 +sbt db +S3:2 -detached -noinput -noshell -sname one
         % erl +sct L3-0c0-3 +sbt db +S3:2 -detached -noinput -noshell -sname two

           In  this  example  each runtime system have two sched-
           ulers each online, and all schedulers online will  run
           on  different  cores.  If  we  change to one scheduler
           online on one runtime  system,  and  three  schedulers
           online  on the other, all schedulers online will still
           run on different cores.

           Note that a faked CPU topology that does  not  reflect
           how  the  real  CPU  topology  looks like is likely to
           decrease the performance of the runtime system.

           For     more     information,     see      erlang:sys-

         +sws default|legacy|proposal:
           Set  scheduler wakeup strategy. Default is legacy (has
           been used since OTP-R13B). The  proposal  strategy  is
           the currently proposed strategy for OTP-R16. Note that
           the proposal strategy might change during OTP-R15.

Ericsson AB         Last change: erts                  16

User Commands                                              erl(1)

           NOTE: This flag may be removed or changed at any  time
           without prior notice.

         +swt very_low|low|medium|high|very_high:
           Set scheduler wakeup threshold. Default is medium. The
           threshold determines when to wake up  sleeping  sched-
           ulers  when more work than can be handled by currently
           awake schedulers exist. A  low  threshold  will  cause
           earlier wakeups, and a high threshold will cause later
           wakeups. Early wakeups will distribute work over  mul-
           tiple  schedulers  faster,  but  work will more easily
           bounce between schedulers.

           NOTE: This flag may be removed or changed at any  time
           without prior notice.

         +sss size:
           Suggested  stack  size,  in  kilowords,  for scheduler
           threads. Valid range is 4-8192 kilowords. The  default
           stack size is OS dependent.

       +t size:
         Set  the  maximum  number  of  atoms  the VM can handle.
         Default is 1048576.

       +T Level:
         Enables modified timing and  sets  the  modified  timing
         level.  Currently  valid range is 0-9. The timing of the
         runtime system will change. A high level usually means a
         greater change than a low level. Changing the timing can
         be very useful for finding timing related bugs.

         Currently, modified timing affects the following:

         Process spawning:
           A process calling spawn, spawn_link, spawn_monitor, or
           spawn_opt will be scheduled out immediately after com-
           pleting the call. When higher modified  timing  levels
           are used, the caller will also sleep for a while after
           being scheduled out.

         Context reductions:
           The amount of reductions a process is a allowed to use
           before being scheduled out is increased or reduced.

         Input reductions:
           The amount of reductions performed before checking I/O
           is increased or reduced.

         NOTE: Performance will suffer when  modified  timing  is
         enabled.  This  flag  is  only  intended for testing and
         debugging. Also  note  that  return_to  and  return_from

Ericsson AB         Last change: erts                  17

User Commands                                              erl(1)

         trace  messages  will  be lost when tracing on the spawn
         BIFs. This flag may be removed or changed  at  any  time
         without prior notice.

         Makes the emulator print out its version number.


       +W w | i:
         Sets  the  mapping of warning messages for error_logger.
         Messages sent to the error logger using one of the warn-
         ing  routines  can be mapped either to errors (default),
         warnings (+W w), or info reports  (+W  i).  The  current
         mapping   can   be  retrieved  using  error_logger:warn-
         ing_map/0. See error_logger(3) for further  information.

       +zFlag Value:
         Miscellaneous flags.

         +zdbbl size:
           Set     the    distribution    buffer    busy    limit
           (dist_buf_busy_limit) in  kilobytes.  Valid  range  is
           1-2097151. Default is 1024.

           A  larger  buffer limit will allow processes to buffer
           more outgoing messages over the distribution. When the
           buffer  limit has been reached, sending processes will
           be suspended until the buffer  size  has  shrunk.  The
           buffer  limit  is  per  distribution channel. A higher
           limit will give lower latency and higher throughput at
           the expense of higher memory usage.

         If  the  emulator needs to write a crash dump, the value
         of this variable will be the file name of the crash dump
         file.  If the variable is not set, the name of the crash
         dump file will be erl_crash.dump in the  current  direc-

         Unix  systems:  If  the  emulator needs to write a crash
         dump, it will use the value of this variable to set  the
         nice  value for the process, thus lowering its priority.
         The allowable range is 1 through 39 (higher values  will
         be  replaced  with 39). The highest value, 39, will give
         the process the lowest priority.

         Unix systems: This variable gives the number of  seconds

Ericsson AB         Last change: erts                  18

User Commands                                              erl(1)

         that  the  emulator  will  be allowed to spend writing a
         crash dump.  When  the  given  number  of  seconds  have
         elapsed,  the  emulator  will be terminated by a SIGALRM

         If the environment variable is not set or it is  set  to
         zero seconds, ERL_CRASH_DUMP_SECONDS=0, the runtime sys-
         tem will not even attempt to write the crash dump  file.
         It will just terminate.

         If  the  environment  variable is set to negative valie,
         e.g. ERL_CRASH_DUMP_SECONDS=-1, the runtime system  will
         wait indefinitely for the crash dump file to be written.

         This environment variable is  used  in  conjuction  with
         heart if heart is running:

           Suppresses  the  writing  a  crash dump file entirely,
           thus rebooting the runtime system immediately. This is
           the same as not setting the environment variable.

           Setting  the  environment variable to a negative value
           will cause the termination of the  runtime  system  to
           wait  until  the  crash  dump  file has been completly

           Will wait for S seconds to  complete  the  crash  dump
           file and then terminate the runtime system.

         The  content  of this environment variable will be added
         to the beginning of the command line for erl.

         The -extra flag is treated specially. Its scope ends  at
         the  end  of the environment variable content. Arguments
         following an -extra flag are moved on the  command  line
         into  the  -extra  section,  i.e. the end of the command
         line following after an -extra flag.

         The content of these environment variables will be added
         to the end of the command line for erl.

         The  -extra flag is treated specially. Its scope ends at
         the end of the environment variable  content.  Arguments
         following  an  -extra flag are moved on the command line
         into the -extra section, i.e. the  end  of  the  command
         line following after an -extra flag.

Ericsson AB         Last change: erts                  19

User Commands                                              erl(1)

         This  environment variable contains a list of additional
         library directories that the code server will search for
         applications and add to the code path. See code(3).

         This  environment  variable  may be set to a comma-sepa-
         rated list of IP addresses, in which case the epmd  dae-
         mon will listen only on the specified address(es) and on
         the loopback address (which is implicitly added  to  the
         list if it has not been specified).

         This environment variable can contain the port number to
         use when communicating with epmd. The default port  will
         work  fine in most cases. A different port can be speci-
         fied to allow nodes of independent clusters to  co-exist
         on  the  same  host. All nodes in a cluster must use the
         same epmd port number.

     The standard  Erlang/OTP  system  can  be  re-configured  to
     change the default behavior on start-up.

       The .erlang Start-up File:
         When  Erlang/OTP  is  started, the system searches for a
         file named .erlang in the directory where Erlang/OTP  is
         started.  If  not  found,  the  user's home directory is
         searched for an .erlang file.

         If an .erlang file is found, it is  assumed  to  contain
         valid  Erlang  expressions. These expressions are evalu-
         ated as if they were input to the shell.

         A typical .erlang file contains a set of  search  paths,
         for example:

               io:format("executing user profile in HOME/.erlang\n",[]).
               io:format(".erlang rc finished\n",[]).

       user_default and shell_default:
         Functions  in the shell which are not prefixed by a mod-
         ule name are assumed to be  functional  objects  (Funs),
         built-in  functions  (BIFs),  or  belong  to  the module
         user_default or shell_default.

         To include private shell commands, define them in a mod-
         ule  user_default  and add the following argument as the
         first line in the .erlang file.

Ericsson AB         Last change: erts                  20

User Commands                                              erl(1)


         If the contents of .erlang are  changed  and  a  private
         version  of  user_default  is defined, it is possible to
         customize  the  Erlang/OTP  environment.  More  powerful
         changes  can be made by supplying command line arguments
         in the start-up script erl. Refer to erl(1) and  init(3)
         for further information.

     See   attributes(5)   for   descriptions  of  the  following

     |Availability   | runtime/erlang   |
     |Stability      | Uncommitted      |
     init(3),  erl_prim_loader(3),  erl_boot_server(3),  code(3),
     application(3),  heart(3),  net_kernel(3), auth(3), make(3),
     epmd(1), erts_alloc(3)

     This  software  was   built   from   source   available   at    The  original
     community       source       was       downloaded       from

     Further  information about this software can be found on the
     open source community website at

Ericsson AB         Last change: erts                  21