Provided by: erlang-manpages_10.b.7-1_all bug

NAME

       erl - The Erlang Emulator

DESCRIPTION

       The  erl  program  starts  the Erlang runtime system. The exact details
       (e.g. whether erl is a script or a program and which other programs  it
       calls) are system-dependent.

       Windows  95/98/2000/NT users will probably want to use the werl program
       instead, which run 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 the Erlang system.

              Any argument starting with a plus sign (+) is always interpreted
              as a system flag  (described  below),  regardless  of  where  it
              occurs on the command line (except after the flag -extra).

              Arguments  starting with a hyphen (-) are the start of a flag. A
              flag includes all following arguments up to  the  next  argument
              starting with a hyphen.

              Example:

              erl -sname arne -myflag 1 -s mod func arg

              Here  -sname arne is a flag and so are -myflag 1 and -s mod func
              arg. Note that these flags are treated differently. -sname  arne
              is  interpreted  by the OTP system, but it still included in the
              list of flags returned by init:get_arguments/0. -s mod func  arg
              is  also  treated specially and it is not included in the return
              value  for  init:get_arguments/0.  Finally,  -myflag  1  is  not
              interpreted  by the OTP system in any way, but it is included in
              init:get_arguments/0.

              Plain arguments are not interpreted in  any  way.  They  can  be
              retrieved  using init:get_plain_arguments/0. Plain arguments can
              occur in the following places: Before the first flag argument on
              the command line, or after a -- argument. Additionally, the flag
              -extra causes everything that follows to become plain arguments.

Flags

       The following flags are supported:

         --: Any  arguments  following  -- will not be interpreted in any way.
             They  can  be  retrieved   by   init:get_plain_arguments/0.   The
             exception   is  arguments  starting  with  a  +,  which  will  be
             interpreted as system flags (see below).

         -AppName Key Value:
             Overrides  the  Key  configuration  parameter  of   the   AppName
             application.  See  application(3).  This type of flag can also be
             retrieved using the init module.

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

         -boot File:
             Specifies  the  name of the boot script, File.boot, which is used
             to start the system. See init(3). UnlessFile contains an absolute
             path,  the  system  searches  for  File.boot  in  the current and
             <ERL_INSTALL_DIR>/bin directories.

             If this flag  is  omitted,  the  <ERL_INSTALL_DIR>/bin/start.boot
             boot script is used.

         -boot_var Var Directory [Var Directory]:
             If  the  boot  script  used  contains  another path variable than
             $ROOT, this variable must have a value assigned in order to start
             the  system.  A  boot  variable is used if user applications have
             been  installed  in  another   location   than   underneath   the
             <ERL_INSTALL_DIR>/lib directory. $Var is expanded to Directory in
             the boot script.

         -compile mod1 mod2 ....:
             Makes the Erlang system compile mod1.erl mod2.erl ....  and  then
             terminate  (with  non-zero  exit  code if the compilation of some
             file didn’t succeed). Implies -noinput.  Not  recommended  -  use
             erlc(1) instead.

         -config Config:
             Reads  the Config.config configuration file in order to configure
             the system. See 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:
             Obsolete flag without  any  effect  and  common  misspelling  for
             -setcookie.  Use -setcookie Cookie option if want to override the
             default cookie.

         -detached:
             Starts the Erlang 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
             of the Erlang system. For example:

             % erl -env DISPLAY gin:0

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

         -eval Expr:
             Passes the -eval flag to the init:boot() routine. See init(3).

         -extra:
             Any arguments following -extra will not  be  interpreted  in  any
             way. They can be retrieved by init:get_plain_arguments/0.

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

         -hidden:
             Starts the Erlang system as a hidden node if the system 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 aren’t 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 an Erlang  boot
             servers  are  running. This flag is mandatory if the -loader inet
             flag is present. On each host, there  must  be  one  Erlang  node
             running, on which the boot_server must be started.

             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 an broadcast address (preferably
             limited to the local network) is.

         -id Id:
             Specifies the identity of the Erlang system. If the  system  runs
             as  a distributed node, Id must be identical to the name supplied
             together with the -sname or -name distribution flags.

         -instr:

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

         -loader Loader:
             Specifies the name of the loader used to load Erlang modules into
             the  system. See erl_prim_loader(3). Loader can be efile (use the
             local file system),  or  inet  (load  using  the  boot_server  on
             another  Erlang  node).  If  Loader  is  something else, the user
             supplied Loader port program is started.

             If the -loader flag is omitted efile is assumed.

         -make:
             Makes the Erlang system invoke make:all()  in  the  current  work
             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 Mode:
             The  mode  flag  indicates  if  the   system   will   load   code
             automatically  at runtime, or if all code is loaded during system
             initialization. Mode can be either interactive to allow automatic
             code  loading,  or embedded to load all code during start-up. See
             code(3).

         -name Name:
             Makes the node a distributed node. This flag invokes all  network
             servers   necessary   for  a  node  to  become  distributed.  See
             net_kernel(3).

             The name of the node will be Name@Host, where Host is  the  fully
             qualified  host  name of the current host. This flag also ensures
             that epmd runs on the current host before Erlang is started.  See
             epmd(1).

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

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

         -nostick:
             Disables the sticky directory facility of the  code  server.  See
             code(3).

         -oldshell:
             Invokes  the  old  Erlang  shell from Erlang release 3.3. The old
             shell can still be used.

         -pa Directories:
             Adds the directories Directories to the head of the  search  path
             of  the  code  server,  as  if  code:add_pathsa/1 was called. See
             code(3).

         -pz Directories:
             Adds the directories Directories to the end of the search path of
             the code server, as if code:add_pathsa/1 was called. See code(3).

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

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

         -run Mod [Fun [Args]]:
             Passes the -run flag to the init:boot() routine. See init(3).

         -s Mod [Fun [Args]]:
             Passes the -s flag to the init:boot() routine. See init(3).

         -setcookie Cookie:
             Sets  the  magic  cookie  of  the  current  node  to  Cookie.  As
             erlang:set_cookie(node(), Cookie) is used, all other  nodes  will
             also be assumed to have their cookies set to Cookie. In this way,
             several nodes can share one magic cookie.  Erlang  magic  cookies
             are explained in auth(3).

         -sname Name:
             This  is  the same as the -name flag, with the exception that the
             host name portion of the node name will not be  fully  qualified.
             The  following  command  is used do start Erlang at the host with
             the name gin.eua.ericsson.se

             % erl -sname klacke
             Eshell V4.7 (abort with ^G)
             (klacke@gin)1>

             Only the host name portion of the node  name  will  be  relevant.
             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  systems  running with the -sname flag and
             those running with the -name flag, as node names must  be  unique
             in distributed Erlang systems.

         -version:
             Makes the system print out its version number.

       All  these flags are processed during the start-up of the Erlang kernel
       servers and before any user processes are started. All flags are passed
       to  init:boot(Args).  See  init(3).  All additional flags passed to the
       script will be passed to init:boot/2 as well, and they can be  accessed
       using the init module.

System Flags

       The  erl  script  invokes the code for the Erlang virtual machine. This
       program supports the following flags:

         +A size:
             Sets the pool size for device driver threads. 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  system 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  (include
             receive  after)  working. Instead, if the system time is changed,
             the time maintained by erlang:now/0 will only slowly be  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 would jump, timers would 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
             has kernel poll support. By default the kernel poll functionality
             is disabled. If the emulator doesn’t have kernel poll support and
             the +K flag is passed to the emulator, a  warning  is  issued  at
             startup.

         +l: Displays info while loading code.

         +M<subflag> <value>:

             Memory  allocator  specific  flags, see erts_alloc(3) for further
             information.

         +P Number:

             Sets the maximum number of concurrent processes for this  system.
             By  default  this value is 32768. The Number must be in the range
             [16, 134217727].

         +R ReleaseNumber:

             Sets the compatibility mode.

             By default, the emulator is only guaranteed to be compatible with
             other Erlang/OTP components from the same release as the emulator
             itself. For example, an emulator from the OTP R10 release is  not
             compatible with an emulator from the OTP R9 release by default.

             This  flag  sets  the  emulator  in compatibility mode of release
             ReleaseNumber. The ReleaseNumber must be in the range [7, current
             release].  This  makes it possible to communicate with Erlang/OTP
             components from earlier releases.

             Warning! You may  run  into  trouble  if  this  feature  is  used
             carelessly.  Always  make  sure that all communicating components
             are either from the same Erlang/OTP release, or  from  release  X
             and  release  Y  where  all  components  from  release  Y  are in
             compatibility mode of release X.

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

         +V: Prints the version of Erlang at start-up.

         +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 (which is the default), warnings  (+W  w)
             or  info  reports  (+W  i).  The current mapping can be retrieved
             using error_logger:warning_map/0.  See  the  error_logger  manual
             page for further descriptions.

   Note:
       The  +m,  +t,  and +T flags have changed to, respectively, +MYm, +MYtt,
       and +MYtp. The +d, and +S* flags have been removed.  See  erts_alloc(3)
       for further information.

       Example:

       % erl -name foo +B +l

       In  this  example, a distributed node is started with the break handler
       turned off and a lot of info is displayed while the code is loading.

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 Fröberg - support@erlang.ericsson.se
       Per Hedeland - support@erlang.ericsson.se
       Sebastian Strollo - support@erlang.ericsson.se
       Claes Wikström - support@erlang.ericsson.se
       Mike Williams - support@erlang.ericsson.se
       Robert Virding - support@erlang.ericsson.se
       Rickard Green - support@erlang.ericsson.se