Provided by:
erlang-manpages_10.b.7-1_all 
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