Provided by: erlang-base-hipe_12.b.3-dfsg-1ubuntu1_i386 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(3erl).

                  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(3erl).

         -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(3erl).  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(3erl).

         -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(3erl).

         -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(3erl).

         -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(3erl).

         -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(3erl).

         -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(3erl).

         -hosts Hosts:
             Specifies the IP addresses for the hosts  on  which  Erlang  boot
             servers  are  running,  see  erl_boot_server(3erl).  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(3erl). 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(3erl). 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(3erl).   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(3erl). 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(3erl).

         -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(3erl). 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  specified  in  the   ERL_LIBS   environment
             variable. See code(3erl).

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

         -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(3erl).

         -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(3erl).

         -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(3erl).

         -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. By default -smp  auto  will  be  used
             unless a conflicting parameter has been passed, then -smp disable
             will be used. Currently only the -hybrid parameter conflicts with
             -smp auto.

             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(3erl) 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(3erl)  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_ZFLAGSand 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.

         ERL_LIBS:
             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(3erl).

SEE ALSO

       init(3erl),  erl_prim_loader(3erl),  erl_boot_server(3erl), code(3erl),
       application(3erl),    heart(3erl),    net_kernel(3erl),     auth(3erl),
       make(3erl), epmd(1), erts_alloc(3erl)