<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
<header>
<copyright>
<year>1999</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>run_erl</title>
<prepared>Kent Boortz</prepared>
<responsible></responsible>
<docno></docno>
<approved></approved>
<checked></checked>
<date>1999-12-15</date>
<rev></rev>
<file>run_erl.xml</file>
</header>
<com>run_erl</com>
<comsummary>Redirect Erlang input and output streams on Unix systems.</comsummary>
<description>
<p>The <c><![CDATA[run_erl]]></c> 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 <c><![CDATA[to_erl]]></c> connect to the Erlang console, making
it possible to monitor and debug an embedded system remotely.</p>
<p>For more information about the use, see the
<seealso marker="doc/embedded:embedded_solaris">
Embedded System User's Guide</seealso> in System Documentation.</p>
</description>
<funcs>
<func>
<name>run_erl [-daemon] pipe_dir/ log_dir "exec command
[command_arguments]"</name>
<fsummary>Start the Erlang emulator without attached terminal.</fsummary>
<desc>
<p>Arguments:</p>
<taglist>
<tag><c>-daemon</c></tag>
<item>
<p>This option is highly recommended. It makes <c>run_erl</c> run
in the background completely detached from any controlling
terminal and the command returns to the caller immediately.
Without this option, <c>run_erl</c> 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 <c>run_erl</c> on the command line.</p>
</item>
<tag><c>pipe_dir</c></tag>
<item>
<p>The named pipe, usually <c><![CDATA[/tmp/]]></c>. It must be
suffixed by a <c><![CDATA[/]]></c> (slash), that is,
<c><![CDATA[/tmp/epipes/]]></c>, not
<c><![CDATA[/tmp/epipes]]></c>.</p>
</item>
<tag><c>log_dir</c></tag>
<item>
<p>The log files, that is:</p>
<list type="bulleted">
<item>
<p>One log file, <c><![CDATA[run_erl.log]]></c>, which logs
progress and warnings from the <c><![CDATA[run_erl]]></c>
program itself.</p>
</item>
<item>
<p>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 <seealso
marker="#environment_variables">Environment Variables</seealso>
below.)</p>
<p>When the logs are full, <c><![CDATA[run_erl]]></c> deletes
and reuses the oldest log file.</p>
</item>
</list>
</item>
<tag><c>"exec command [command_arguments]"</c></tag>
<item>
<p>In the third argument, <c><![CDATA[command]]></c> is the
executable to execute where everything written to <c>stdin</c>
and <c>stdout</c> is logged to <c><![CDATA[log_dir]]></c>.</p>
</item>
</taglist>
</desc>
</func>
</funcs>
<section>
<title>Notes concerning the Log Files</title>
<p>While running, <c>run_erl</c> (as stated earlier) sends all output,
uninterpreted, to a log file. The file is named
<c><![CDATA[erlang.log.N]]></c>, where <c>N</c> is an integer. When the
log is "full" (default log size is 100 KB), <c>run_erl</c> starts to log
in file <c><![CDATA[erlang.log.(N+1)]]></c>, until <c>N</c> reaches a
certain number (default 5), whereupon <c>N</c> starts at 1 again and
the oldest files start getting overwritten.</p>
<p>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:</p>
<code type="none"><![CDATA[
===== ALIVE <date-time-string> ]]></code>
<p>The other time stamps look as follows:</p>
<code type="none"><![CDATA[
===== <date-time-string> ]]></code>
<p><c><![CDATA[date-time-string]]></c> 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 <c><![CDATA[strftime]]></c>
using the format string <c><![CDATA[%a %b %e %T %Z %Y]]></c>, which
produces messages like
<c><![CDATA[===== ALIVE Thu May 15 10:13:36 MEST 2003]]></c>; this can
be changed, see the next section.</p>
</section>
<section>
<marker id="environment_variables"/>
<title>Environment Variables</title>
<p>The following environment variables are recognized by <c>run_erl</c>
and change the logging behavior. For more information, see the previous
section.</p>
<taglist>
<tag><c>RUN_ERL_LOG_ALIVE_MINUTES</c></tag>
<item>
<p>How long to wait for output (in minutes) before writing an
"ALIVE" message to the log. Defaults to 15, minimum is 1.</p>
</item>
<tag><c>RUN_ERL_LOG_ACTIVITY_MINUTES</c></tag>
<item>
<p>How long Erlang needs to be inactive before output is
preceded with a time stamp. Defaults to
<c>RUN_ERL_LOG_ALIVE_MINUTES div 3</c>, minimum is 1.</p>
</item>
<tag><c>RUN_ERL_LOG_ALIVE_FORMAT</c></tag>
<item>
<p>Specifies another format string to be used in the <c>strftime</c>
C library call. That is, specifying this to
<c><![CDATA["%e-%b-%Y, %T %Z"]]></c> gives
log messages with time stamps like
<c><![CDATA[15-May-2003, 10:23:04 MET]]></c>. For more information,
see the documentation for the C library function <c>strftime</c>.
Defaults to <c><![CDATA["%a %b %e %T %Z %Y"]]></c>.</p>
</item>
<tag><c>RUN_ERL_LOG_ALIVE_IN_UTC</c></tag>
<item>
<p>If set to anything else than <c>0</c>, it makes all
times displayed by <c>run_erl</c> 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 <c>run_erl</c>. Application
<c>SASL</c> can be modified accordingly by setting the Erlang
application variable <c><![CDATA[utc_log]]></c> to
<c><![CDATA[true]]></c>.</p>
</item>
<tag><c>RUN_ERL_LOG_GENERATIONS</c></tag>
<item>
<p>Controls the number of log files written before older
files are reused. Defaults to 5, minimum is 2, maximum is 1000.</p>
</item>
<tag><c>RUN_ERL_LOG_MAXSIZE</c></tag>
<item>
<p>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.</p>
</item>
<tag><c>RUN_ERL_DISABLE_FLOWCNTRL</c></tag>
<item>
<p>If defined, disables input and output flow control for the pty
opend by <c>run_erl</c>. 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.</p>
</item>
</taglist>
</section>
<section>
<title>See Also</title>
<p><seealso marker="start"><c>start(1)</c></seealso>,
<seealso marker="start_erl"><c>start_erl(1)</c></seealso></p>
</section>
</comref>
