run_erl - Redirect Erlang input and output streams on Unix
systems.
The run_erl program is specific to Unix systems. This
program redirects the standard input and standard output streams so that all
output can be logged. It also lets the program to_erl connect to the
Erlang console, making it possible to monitor and debug an embedded system
remotely.
For more information about the use, see the Embedded System User's
Guide in System Documentation.
run_erl [-daemon] pipe_dir/ log_dir "exec command arg1
arg2 ..."
Arguments:
- -daemon:
- This option is highly recommended. It makes run_erl run in the
background completely detached from any controlling terminal and the
command returns to the caller immediately. Without this option,
run_erl must be started using several tricks in the shell to detach
it completely from the terminal in use when starting it. The option must
be the first argument to run_erl on the command line.
- pipe_dir:
- The named pipe, usually /tmp/. It must be suffixed by a /
(slash), that is, /tmp/epipes/, not /tmp/epipes.
- log_dir:
- The log files, that is:
- *
- One log file, run_erl.log, which logs progress and warnings from
the run_erl program itself.
- *
- Up to five log files at maximum 100 KB each with the content of the
standard streams from and to the command. (Both the number of logs and
sizes can be changed by environment variables, see section Environment
Variables below.)
When the logs are full, run_erl deletes and reuses the
oldest log file.
- "exec command arg1 arg2 ...":
- A space-separated string specifying the program to be executed. The second
field is typically a command name such as erl.
While running, run_erl sends all output, uninterpreted, to
a log file. The file is named erlang.log.N, where N is an
integer. When the log is "full" (default log size is 100 KB),
run_erl starts to log in file erlang.log.(N+1), until N
reaches a certain number (default 5), whereupon N starts at 1 again
and the oldest files start getting overwritten.
If no output comes from the Erlang shell, but the Erlang machine
still seems to be alive, an "ALIVE" message is written to the log;
it is a time stamp and is written, by default, after 15 minutes of
inactivity. Also, if output from Erlang is logged, but more than 5 minutes
(default) has passed since last time we got anything from Erlang, a time
stamp is written in the log. The "ALIVE" messages look as
follows:
===== ALIVE <date-time-string>
The other time stamps look as follows:
===== <date-time-string>
date-time-string is the date and time the message is
written, default in local time (can be changed to UTC if needed). It is
formatted with the ANSI-C function strftime using the format string
%a %b %e %T %Z %Y, which produces messages like ===== ALIVE Thu
May 15 10:13:36 MEST 2003; this can be changed, see the next
section.
The following environment variables are recognized by
run_erl and change the logging behavior. For more information, see
the previous section.
- RUN_ERL_LOG_ALIVE_MINUTES:
- How long to wait for output (in minutes) before writing an
"ALIVE" message to the log. Defaults to 15, minimum is 1.
- RUN_ERL_LOG_ACTIVITY_MINUTES:
- How long Erlang needs to be inactive before output is preceded with a time
stamp. Defaults to RUN_ERL_LOG_ALIVE_MINUTES div 3, minimum is
1.
- RUN_ERL_LOG_ALIVE_FORMAT:
- Specifies another format string to be used in the strftime C
library call. That is, specifying this to "%e-%b-%Y, %T
%Z" gives log messages with time stamps like 15-May-2003,
10:23:04 MET. For more information, see the documentation for the C
library function strftime. Defaults to "%a %b %e %T %Z
%Y".
- RUN_ERL_LOG_ALIVE_IN_UTC:
- If set to anything else than 0, it makes all times displayed by
run_erl to be in UTC (GMT, CET, MET, without Daylight Saving Time),
rather than in local time. This does not affect data coming from Erlang,
only the logs output directly by run_erl. Application SASL can be
modified accordingly by setting the Erlang application variable
utc_log to true.
- RUN_ERL_LOG_GENERATIONS:
- Controls the number of log files written before older files are reused.
Defaults to 5, minimum is 2, maximum is 1000.
Note that, as a way to indicate the newest file, run_erl
will delete the oldest log file to maintain a "hole" in the file
sequences. For example, if log files #1, #2, #4 and #5 exists, that means #2
is the latest and #4 is the oldest. You will therefore at most get one less
log file than the value set by RUN_ERL_LOG_GENERATIONS.
- RUN_ERL_LOG_MAXSIZE:
- The size, in bytes, of a log file before switching to a new log file.
Defaults to 100000, minimum is 1000, maximum is about 2^30.
- RUN_ERL_DISABLE_FLOWCNTRL:
- If defined, disables input and output flow control for the pty opend by
run_erl. Useful if you want to remove any risk of accidentally
blocking the flow control by using Ctrl-S (instead of Ctrl-D to detach),
which can result in blocking of the entire Beam process, and in the case
of running heart as supervisor even the heart process becomes blocked when
writing log message to terminal, leaving the heart process unable to do
its work.