# erl

### COMMAND

erl

### COMMAND SUMMARY

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). Unless `File` 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, 268435456].
+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.

| 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

erts 5.4.8
Copyright © 1991-2005 Ericsson AB