erl(1)

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.

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

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

    -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: De-activates the break handler for ^C and ^\ .

    +d size:

        Most memory blocks that are guaranteed never to be moved or removed once they have been allocated are placed in a special "definite alloc block" near the beginning of the emulators heap if there is space left in it. This flag sets the size (in Kb) of the "definite alloc block". Default size is 2048 Kb.

        Note: See also the note on memory allocation flags below.

    +h size:
        Sets the default heap size of processes to the size size.

    +l: Displays info while loading code.

    +P Number:
        Sets the total number of processes for this system. The Number must be in the range [15,32768].

    +s size:
        Sets the default stack size for Erlang processes to the size size.

    +S<subflag> <value>:

        sl_alloc specific flags, see sl_alloc(3) for further information.

        Note: See also the note on memory allocation flags below.

    +t Threshold:

        Sets the trim threshold. This is the maximum amount of free memory at the top of the heap (allocated by sbrk()) that will be keept by the allocator (not released to the operating system). When the amount of free memory at the top of the heap exceeds the trim threshold, the allocator will release it (by calling sbrk()). Threshold is given in kilobytes. Default trim threshold is 128 kilobytes.

        Note: This flag will only have any affect on the emulator when the emulator has been linked with the GNU C library. See also the note on memory allocation flags below.

    +T TopPad:

        Sets the top pad size. This is the amount of extra memory that will be allocated when sbrk() is called to get more memory from the operating system. TopPad is given in kilobytes. Default top pad size is 0 kilobytes.

        Note: This flag will only have any affect on the emulator when the emulator has been linked with the GNU C library. See also the note on memory allocation flags below.

    +v: Verbose

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

  Note:

Regarding memory allocation flags:

Only use the +S*, +T, +t, and +d flags if you are absolutely sure what you are doing. Unsuitable settings may cause serious performance degradation (and even a system crash) at any time during operation.

Most of these flags are highly implementation dependent, and they may be changed or removed without prior notice.

The memory allocator may use other values than those passed to it (even ignore them). It will for example most likely page align threshold values.

erlang:system_info(allocator) returns information about used memory allocator and memory allocation features.

Observe that the +M and +m flags have been removed.

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), sl_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