Starts an Erlang runtime system.

The arguments can be divided into emulator flags, flags, and plain arguments:

Examples:

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

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

-args_file FileName:

Command-line arguments are read from the file FileName. The arguments read from the file replace flag '-args_file FileName' on the resulting command line.

-async_shell_start:

The initial Erlang shell does not read user input until the system boot procedure has been completed (Erlang/OTP 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(3). Unless File contains an absolute path, the system searches for File.boot in the current and $ROOT/bin directories.

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

-code_path_cache:

Enables the code path cache of the code server; see code(3).

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

-config Config [Config ...]:

Specifies the name of one or more configuration files, Config.config, which is used to configure applications; see app(4) and application(3). See the documentation for the configuration file format for a description of the configuration format and the order in which configuration parameters are read.

-configfd FD [FD ...]:

Specifies the name of one or more file descriptors (called configuration file descriptors from here on) with configuration data for applications; see app(4) and application(3). See the documentation for the configuration file format for a description of the configuration format and the order in which configuration parameters are read.

$ erl \ -noshell \ -configfd 3 \ -eval \ 'io:format("~p~n",[application:get_env(kernel, logger_level)]),erlang:halt()' 3< \ <(echo '[{kernel, [{logger_level, warning}]}].')
{ok,warning}

$ echo '[{kernel, [{logger_level, warning}]}].' > test1.config
$ echo '[{kernel, [{logger_level, error}]}].' > test2.config
$ erl \ -noshell \ -configfd 3 \ -configfd 4 \ -eval \ 'io:format("~p~n",[application:get_env(kernel, logger_level)]),erlang:halt()' \ 3< test1.config 4< test2.config
{ok,error}

-connect_all false:

If this flag is present, global does not maintain a fully connected network of distributed Erlang nodes, and then global name registration cannot be used; see global(3).

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

-emu_args:

Useful for debugging. Prints the arguments sent to the emulator.

-emu_flavor emu|jit|smp:

Start an emulator of a different flavor. Normally only one flavor is available, more can be added by building specific flavors. The currently available flavors are: emu and jit. The smp flavor is an alias for the current default flavor. You can combine this flag with --emu_type. You can get the current flavor at run-time using erlang:system_info(emu_flavor). (The emulator with this flavor must be built. You can build a specific flavor by doing make FLAVOR=$FLAVOR in the Erlang/OTP source repository.)

-emu_type Type:

Start an emulator of a different type. For example, to start the lock-counter emulator, use -emu_type lcnt. You can get the current type at run-time using erlang:system_info(build_type). (The emulator of this type must already be built. Use the configure option --enable-lock-counter to build the lock-counter 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

-epmd_module Module (init flag):

Configures the module responsible to communicate to epmd. Defaults to erl_epmd.

-erl_epmd_port Port (init flag):

Configures the port used by erl_epmd to listen for connection and connect to other nodes. See erl_epmd for more details. Defaults to 0.

-eval Expr (init flag):

Makes init evaluate the expression Expr; see init(3).

-extra (init flag):

Everything following -extra is considered plain arguments and can be retrieved using init:get_plain_arguments/0.

-heart:

Starts heartbeat monitoring of the Erlang runtime system; see heart(3).

-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 any of the connected nodes, that is, none 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 Erlang boot servers are running, see erl_boot_server(3). This flag is mandatory if flag -loader inet is present.

-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 flag -sname or -name.

-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 analyzed using the instrument module. 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(3). Two Loader methods are supported:

-make:

Makes the Erlang runtime system invoke make:all() in the current working 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 interactive | embedded:

Modules are auto loaded when they are first referenced if the runtime system runs in interactive mode, which is the default. In embedded mode modules are not auto loaded. The latter is recommended when the boot script preloads all modules, as conventionally happens in OTP releases. See code(3).

-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(3). It is also ensured that epmd runs on the current host before Erlang is started; see epmd(1) and the -start_epmd option.

-dist_listen false -hidden -dist_auto_connect never

-no_epmd:

Specifies that the distributed node does not need epmd at all.

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

-oldshell:

Invokes the old Erlang shell from Erlang/OTP 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. Note that the order of the given directories will be reversed in the resulting path.

-pz Dir1 Dir2 ...:

Adds the specified directories to the end of the code path, similar to code:add_pathsz/1; see code(3).

-path Dir1 Dir2 ...:

Replaces the path specified in the boot script; see script(4).

-proto_dist Proto:

% erl -name test@ipv6node.example.com -proto_dist inet6_tcp

-remsh Node:

Starts Erlang with a remote shell connected to Node.

-rsh Program:

Specifies an alternative to ssh for starting a slave node on a remote host; see slave(3).

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

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

-setcookie Cookie:

Sets the magic cookie of the node to Cookie; see erlang:set_cookie/2.

-setcookie Node Cookie:

Sets the magic cookie for 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 milliseconds 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.

-start_epmd true | false:

Specifies whether Erlang should start epmd on startup. By default this is true, but if you prefer to start epmd manually, set this to false.

-version (emulator flag):

Makes the emulator print its version number. The same as erl +V.

+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, that is, 64 kilobyte on 32-bit architectures. This small default size has been chosen because the number of async threads can be large. The default size is enough for drivers delivered with Erlang/OTP, but might not be large enough for other dynamically linked-in drivers that use the driver_async() functionality. Notice that the value passed is only a suggestion, and it can even be ignored on some platforms.

+A size:

Sets the number of threads in async thread pool. Valid range is 1-1024. The async thread pool is used by linked-in drivers to handle work that may take a very long time. Since OTP 21 there are very few linked-in drivers in the default Erlang/OTP distribution that uses the async thread pool. Most of them have been migrated to dirty IO schedulers. Defaults to 1.

+B [c | d | i]:

Option c makes Ctrl-C interrupt the current shell instead of invoking the emulator break handler. Option d (same as specifying +B without an extra option) disables the break handler. Option i makes the emulator ignore any break signal.

+c true | false:

Enables or disables time correction:

+C no_time_warp | single_time_warp | multi_time_warp:

Sets time warp mode:

+d:

If the emulator detects an internal error (or runs out of memory), it, by default, generates both a crash dump and a core dump. The core dump is, however, not very useful as the content of process heaps is destroyed by the crash dump generation.

+dcg DecentralizedCounterGroupsLimit:

Limits the number of decentralized counter groups used by decentralized counters optimized for update operations in the Erlang runtime system. By default, the limit is 256.

+e Number:

Sets the maximum number of ETS tables. This limit is partially obsolete.

+ec:

Forces option compressed on all ETS tables. Only intended for test and evaluation.

+fnl:

The virtual machine works with filenames as if they are encoded using the ISO Latin-1 encoding, disallowing Unicode characters with code points > 255.

+fnu[{w|i|e}]:

The virtual machine works with filenames as if they are encoded using UTF-8 (or some other system-specific Unicode encoding). This is the default on operating systems that enforce Unicode encoding, that is, Windows MacOS X and Android.

+fna[{w|i|e}]:

Selection between +fnl and +fnu is done based on the current locale settings in the OS. This means that if you have set your terminal for UTF-8 encoding, the filesystem is expected to use the same encoding for filenames. This is the default on all operating systems, except Android, MacOS X and Windows.

+hms Size:

Sets the default heap size of processes to the size Size.

+hmbs Size:

Sets the default binary virtual heap size of processes to the size Size.

+hmax Size:

Sets the default maximum heap size of processes to the size Size. Defaults to 0, which means that no maximum heap size is used. For more information, see process_flag(max_heap_size, MaxHeapSize).

+hmaxel true|false:

Sets whether to send an error logger message or not for processes reaching the maximum heap size. Defaults to true. For more information, see process_flag(max_heap_size, MaxHeapSize).

+hmaxk true|false:

Sets whether to kill processes reaching the maximum heap size or not. Default to true. For more information, see process_flag(max_heap_size, MaxHeapSize).

+hpds Size:

Sets the initial process dictionary size of processes to the size Size.

+hmqd off_heap|on_heap:

Sets the default value of the message_queue_data process flag. Defaults to on_heap. If +hmqd is not passed, on_heap will be the default. For more information, see process_flag(message_queue_data, MQD).

+IOp PollSets:

Sets the number of IO pollsets to use when polling for I/O. This option is only used on platforms that support concurrent updates of a pollset, otherwise the same number of pollsets are used as IO poll threads. The default is 1.

+IOt PollThreads:

Sets the number of IO poll threads to use when polling for I/O. The maximum number of poll threads allowed is 1024. The default is 1.

+IOPp PollSetsPercentage:

Similar to +IOp but uses percentages to set the number of IO pollsets to create, based on the number of poll threads configured. If both +IOPp and +IOp are used, +IOPp is ignored.

+IOPt PollThreadsPercentage:

Similar to +IOt but uses percentages to set the number of IO poll threads to create, based on the number of schedulers configured. If both +IOPt and +IOt are used, +IOPt is ignored.

+JPperf true|false:

Enables or disables support for the `perf` profiler when running with the JIT on Linux. Defaults to false.

+L:

Prevents loading information about source filenames and line numbers. This saves some memory, but exceptions do not contain information about the filenames and line numbers.

+MFlag Value:

Memory allocator-specific flags. For more information, see erts_alloc(3).

+pc Range:

Sets the range of characters that the system considers printable in heuristic detection of strings. This typically affects the shell, debugger, and io:format functions (when ~tp is used in the format string).

+P Number:

Sets the maximum number of simultaneously existing processes for this system if a Number is passed as value. Valid range for Number is [1024-134217727]

+Q Number:

Sets the maximum number of simultaneously existing ports for this system if a Number is passed as value. Valid range for Number is [1024-134217727]

+R ReleaseNumber:

Sets the compatibility mode.

+r:

Forces ETS memory block to be moved on realloc.

+rg ReaderGroupsLimit:

Limits the number of reader groups used by read/write locks optimized for read operations in the Erlang runtime system. By default the reader groups limit is 64.

+S Schedulers:SchedulerOnline:

Sets the number of scheduler threads to create and scheduler threads to set online. The maximum for both values is 1024. If the Erlang runtime system is able to determine the number of logical processors configured and logical processors available, Schedulers defaults to logical processors configured, and SchedulersOnline defaults to logical processors available; otherwise the default values are 1. If the emulator detects that it is subject to a CPU quota, the default value for SchedulersOnline will be limited accordingly.

+SP SchedulersPercentage:SchedulersOnlinePercentage:

Similar to +S but uses percentages to set the number of scheduler threads to create, based on logical processors configured, and scheduler threads to set online, based on logical processors available. Specified values must be > 0. For example, +SP 50:25 sets the number of scheduler threads to 50% of the logical processors configured, and the number of scheduler threads online to 25% of the logical processors available. SchedulersPercentage can be omitted if :SchedulersOnlinePercentage is not and conversely. The number of schedulers online can be changed at runtime through erlang:system_flag(schedulers_online, SchedulersOnline).

+SDcpu DirtyCPUSchedulers:DirtyCPUSchedulersOnline:

Sets the number of dirty CPU scheduler threads to create and dirty CPU scheduler threads to set online. The maximum for both values is 1024, and each value is further limited by the settings for normal schedulers:

+SDPcpu DirtyCPUSchedulersPercentage:DirtyCPUSchedulersOnlinePercentage:

Similar to +SDcpu but uses percentages to set the number of dirty CPU scheduler threads to create and the number of dirty CPU scheduler threads to set online. Specified values must be > 0. For example, +SDPcpu 50:25 sets the number of dirty CPU scheduler threads to 50% of the logical processors configured and the number of dirty CPU scheduler threads online to 25% of the logical processors available. DirtyCPUSchedulersPercentage can be omitted if :DirtyCPUSchedulersOnlinePercentage is not and conversely. The number of dirty CPU schedulers online can be changed at runtime through erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline).

+SDio DirtyIOSchedulers:

Sets the number of dirty I/O scheduler threads to create. Valid range is 1-1024. By default, the number of dirty I/O scheduler threads created is 10.

+sFlag Value:

Scheduling specific flags.

% erl +sct L0-3c0-3
1> erlang:system_info(cpu_topology).
[{processor,[{core,{logical,0}},
             {core,{logical,1}},
             {core,{logical,2}},
             {core,{logical,3}}]}]

% erl +sct L0-1,3-2c0-3p0N0:L7,4,6-5c0-3p1N1
1> erlang:system_info(cpu_topology).
[{node,[{processor,[{core,{logical,0}},
                    {core,{logical,1}},
                    {core,{logical,3}},
                    {core,{logical,2}}]}]},
 {node,[{processor,[{core,{logical,7}},
                    {core,{logical,4}},
                    {core,{logical,6}},
                    {core,{logical,5}}]}]}]

% erl +sct L0-3c0-3 +sbt db +S3:2 -detached -noinput -noshell -sname one
% erl +sct L3-0c0-3 +sbt db +S3:2 -detached -noinput -noshell -sname two

+t size:

Sets the maximum number of atoms the virtual machine can handle. Defaults to 1,048,576.

+T Level:

Enables modified timing and sets the modified timing level. Valid range is 0-9. The timing of the runtime system is changed. A high level usually means a greater change than a low level. Changing the timing can be very useful for finding timing-related bugs.

return_to and return_from trace messages are lost when tracing on the spawn BIFs.

This flag can be removed or changed at any time without prior notice.

+v:

Verbose.

+V:

Makes the emulator print its version number.

+W w | i | e:

Sets the mapping of warning messages for error_logger. Messages sent to the error logger using one of the warning routines can be mapped to errors (+W e), warnings (+W w), or information reports (+W i). Defaults to warnings. The current mapping can be retrieved using error_logger:warning_map/0. For more information, see error_logger:warning_map/0 in Kernel.

+zFlag Value:

Miscellaneous flags:

ERL_CRASH_DUMP:

If the emulator needs to write a crash dump, the value of this variable is the filename of the crash dump file. If the variable is not set, the name of the crash dump file is erl_crash.dump in the current directory.

ERL_CRASH_DUMP_NICE:

Unix systems: If the emulator needs to write a crash dump, it uses the value of this variable to set the nice value for the process, thus lowering its priority. Valid range is 1-39 (higher values are replaced with 39). The highest value, 39, gives the process the lowest priority.

ERL_CRASH_DUMP_SECONDS:

Unix systems: This variable gives the number of seconds that the emulator is allowed to spend writing a crash dump. When the given number of seconds have elapsed, the emulator is terminated.

ERL_CRASH_DUMP_BYTES:

This variable sets the maximum size of a crash dump file in bytes. The crash dump will be truncated if this limit is exceeded. If the variable is not set, no size limit is enforced by default. If the variable is set to 0, the runtime system does not even attempt to write a crash dump file.

ERL_AFLAGS:

The content of this variable is added to the beginning of the command line for erl.

ERL_ZFLAGS and ERL_FLAGS:

The content of these variables are added to the end of the command line for erl.

ERL_LIBS:

Contains a list of additional library directories that the code server searches for applications and adds to the code path; see code(3).

ERL_EPMD_ADDRESS:

Can be set to a comma-separated list of IP addresses, in which case the epmd daemon listens only on the specified address(es) and on the loopback address (which is implicitly added to the list if it has not been specified).

ERL_EPMD_PORT:

Can contain the port number to use when communicating with epmd. The default port works fine in most cases. A different port can be specified to allow nodes of independent clusters to co-exist on the same host. All nodes in a cluster must use the same epmd port number.

SIGUSR1:

A SIGUSR1 signal forces a crash dump.

SIGTERM:

A SIGTERM will produce a stop message to the init process. This is equivalent to a init:stop/0 call.

The .erlang startup file:

When Erlang/OTP is started, the system searches for a file named .erlang in the user's home directory.

io:format("executing user profile in HOME/.erlang\n",[]).
code:add_path("/home/calvin/test/ebin").
code:add_path("/home/hobbes/bigappl-1.2/ebin").
io:format(".erlang rc finished\n",[]).    

user_default and shell_default:

Functions in the shell that are not prefixed by a module name are assumed to be functional objects (funs), built-in functions (BIFs), or belong to the module user_default or shell_default.

code:load_abs("..../user_default").    

erl:

If the contents of .erlang are changed and a private version of user_default is defined, the Erlang/OTP environment can be customized. More powerful changes can be made by supplying command-line arguments in the startup script erl. For more information, see init(3).