Provided by: erlang-manpages_11.b.5-1_all bug

NAME

       erl - The Erlang Emulator

DESCRIPTION

       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 output.

EXPORTS

       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 specifically 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.

                * 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 arguments.

              Example:

              %erl +W w -sname arnie +R 9 -s my_init -extra +bertie

              (arnie@host)1>init:get_argument(sname).

              {ok,[["arnie"]]}
              (arnie@host)2>init:get_plain_arguments().

              ["+bertie"]

              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).

              {ok,[["1"]]}
              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.

Flags

       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).

         -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  careful  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.

         -async_shell_start:
             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 contains 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.

         -code_path_cache:
             Enables the code path cache of the code server, see code(3).

         -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:
             Specifies the name of a configuration file, Config.config,  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 global(3).

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

         -detached:
             Starts  the  Erlang  runtime  system  detached  from  the  system
             console. Useful for running daemons and backgrounds processes.

         -emu_args:
             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 arguments and can
             be retrieved using init:get_plain_arguments/0.

         -heart:
             Starts heart beat monitoring of the Erlang  runtime  system.  See
             heart(3).

         -hidden:
             Starts  the  Erlang runtime system as a hidden node, if it is run
             as a distributed  node.  Hidden  nodes  always  establish  hidden
             connections  to  all  other  nodes  except  for nodes in the same
             global group. Hidden connections are not published on neither  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 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 "150.236.20.74".  Hosts
             names  are  not  acceptable,  but a broadcast address (preferably
             limited to the local network) 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 flag.

         -init_debug:
             Makes init write some debug information  while  interpreting  the
             boot script.

         -instr (emulator flag):

             Selects  an  instrumented Erlang runtime system (virtual machine)
             to run, instead of the ordinary one. When running 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.

         -make:
             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
             (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.

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

         -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.

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

         -oldshell:
             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).

         -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):
             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
             erlang:set_cookie/2.

         -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 qualified.

             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.  This  is  currently  the  default
             behavior. -smp auto will probably be the  default  behavior  some
             time in the future.

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

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

Emulator Flags

       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
             sufficiently 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 emulator 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.

         +c: Disable compensation for sudden changes of system time.

             Normally,   erlang:now/0  will  not  immediately  reflect  sudden
             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.

         +h Size:
             Sets the default 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 startup.

         +l: Enables auto load tracing, displaying info while loading code.

         +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 compatibility mode with
             an earlier Erlang/OTP release ReleaseNumber. 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.

             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 "regular" R10 nodes, as R9 and
             "regular" R10 nodes are not compatible.

         +r: Force ets memory block to be moved on realloc.

         +S Number:

             Sets  the number of scheduler threads to use when SMP support has
             been enabled. Valid range is 1-1024. If the Erlang runtime system
             is able to determine the number of processor cores available, the
             default value will equal the this value; otherwise,  the  default
             value will be one.

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

         +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
                   completing 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 trace messages will be  lost  when
             tracing on the spawn BIFs. This flag may be removed or changed at
             any time without prior notice.

         +V: Makes the emulator print out its version number.

         +v: Verbose.

         +W w | i:
             Sets the mapping of warning messages for  error_logger.  Messages
             sent to the error logger using one of the warning 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:warning_map/0.  See  error_logger(3)   for   further
             information.

Environment variables

         ERL_CRASH_DUMP:
             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 directory.

         ERL_CRASH_DUMP_NICE:
             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.

         ERL_CRASH_DUMP_SECONDS:
             Unix systems: This variable gives the number of seconds 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 signal.

         ERL_AFLAGS:
             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.

         ERL_ZFLAGS and ERL_FLAGS:
             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.

See Also

       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)

AUTHORS

       Joe Armstrong - support@erlang.ericsson.se
       Magnus Froberg - support@erlang.ericsson.se
       Per Hedeland - support@erlang.ericsson.se
       Sebastian Strollo - support@erlang.ericsson.se
       Claes Wikstrom - support@erlang.ericsson.se
       Mike Williams - support@erlang.ericsson.se
       Robert Virding - support@erlang.ericsson.se
       Rickard Green - support@erlang.ericsson.se