diff options
Diffstat (limited to 'erts/doc/src/run_erl.xml')
| -rw-r--r-- | erts/doc/src/run_erl.xml | 285 |
1 files changed, 169 insertions, 116 deletions
diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl.xml index 28e94c6da8..fa36457489 100644 --- a/erts/doc/src/run_erl.xml +++ b/erts/doc/src/run_erl.xml @@ -4,20 +4,21 @@ <comref> <header> <copyright> - <year>1999</year><year>2013</year> + <year>1999</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + 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> @@ -27,137 +28,189 @@ <docno></docno> <approved></approved> <checked></checked> - <date>99-12-15</date> + <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 Solaris®</comsummary> + <comsummary>Redirect Erlang input and output streams on Unix systems.</comsummary> <description> - <p>This describes the <c><![CDATA[run_erl]]></c> program specific to - Solaris/Linux. This program redirect the standard input and standard - output streams so that all output can be logged. It also let 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>You can read more about the use in the <c><![CDATA[Embedded System User's Guide]]></c>.</p> + <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> + <name>run_erl [-daemon] pipe_dir/ log_dir "exec command + arg1 arg2 ..."</name> + <fsummary>Start the Erlang emulator without attached terminal.</fsummary> <desc> - <p>The <c><![CDATA[run_erl]]></c> program arguments are:</p> + <p>Arguments:</p> <taglist> - <tag>-daemon</tag> - <item>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.</item> - <tag>pipe_dir</tag> - <item>This is where to put the named pipe, usually - <c><![CDATA[/tmp/]]></c> on Unix or <c><![CDATA[/pipe/]]></c> on OSE. It shall be suffixed by a <c><![CDATA[/]]></c> (slash), - i.e. not <c><![CDATA[/tmp/epipies]]></c>, but <c><![CDATA[/tmp/epipes/]]></c>. </item> - <tag>log_dir</tag> - <item>This is where the log files are written. There will be one - log file, <c><![CDATA[run_erl.log]]></c> that log progress and - warnings from the <c><![CDATA[run_erl]]></c> program itself and there - will be up to five log files at maximum 100KB each (both - number of logs and sizes can be - changed by environment variables, see below) with - the content of the standard streams from and to the - command. When the logs are full <c><![CDATA[run_erl]]></c> will delete - and reuse the oldest log file.</item> - <tag>"exec command [command_arguments]"</tag> - <item>In the third argument <c><![CDATA[command]]></c> is the to execute - where everything written to stdin and stdout is logged to - <c><![CDATA[log_dir]]></c>.</item> + <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 arg1 arg2 ..."</c></tag> + <item> + <p>A space-separated string specifying the program to be executed. + The second field is typically a command name such as <c>erl</c>.</p> + </item> </taglist> </desc> </func> </funcs> <section> - <title>Notes concerning the log files</title> - <p>While running, run_erl (as stated earlier) sends all output, - uninterpreted, to a log file. The file is called - <c><![CDATA[erlang.log.N]]></c>, where N is a number. When the log is "full", - default after 100KB, run_erl starts to log in file - <c><![CDATA[erlang.log.(N+1)]]></c>, until N reaches a certain number (default - 5), where after 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 timestamp and is written, by default, - after 15 minutes of inactivity. Also, if output from erlang is - logged but it's been more than 5 minutes (default) since last time - we got anything from erlang, a timestamp is written in the - log. The "ALIVE" messages look like this:</p> + <title>Notes concerning the Log Files</title> + <p>While running, <c>run_erl</c> 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>while the other timestamps look like this:</p> +===== ALIVE <date-time-string> ]]></code> + + <p>The other time stamps look as follows:</p> + <code type="none"><![CDATA[ - ===== <date-time-string> - ]]></code> - <p>The <c><![CDATA[date-time-string]]></c> is the date and time the message is - written, default in local time (can be changed to GMT if one wants - to) and 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 on the line of <c><![CDATA[===== ALIVE Thu May 15 10:13:36 MEST 2003]]></c>, this can be changed, see below.</p> +===== <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> - <title>Environment variables</title> - <p>The following environment variables are recognized by run_erl - and change the logging behavior. Also see the notes above to get - more info on how the log behaves.</p> + <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>RUN_ERL_LOG_ALIVE_MINUTES</tag> - <item>How long to wait for output (in minutes) before writing an - "ALIVE" message to the log. Default is 15, can never be less - than 1.</item> - <tag>RUN_ERL_LOG_ACTIVITY_MINUTES</tag> - <item>How long erlang need to be inactive before output will be - preceded with a timestamp. Default is - RUN_ERL_LOG_ALIVE_MINUTES div 3, but never less than 1.</item> - <tag>RUN_ERL_LOG_ALIVE_FORMAT</tag> - <item>Specifies another format string to be used in the strftime - C library call. i.e specifying this to <c><![CDATA["%e-%b-%Y, %T %Z"]]></c> - will give log messages with timestamps looking like - <c><![CDATA[15-May-2003, 10:23:04 MET]]></c> etc. See the documentation - for the C library function strftime for more - information. Default is <c><![CDATA["%a %b %e %T %Z %Y"]]></c>.</item> - <tag>RUN_ERL_LOG_ALIVE_IN_UTC</tag> - <item>If set to anything else than "0", it will make all - times displayed by run_erl to be in UTC (GMT,CET,MET, without - DST), rather than - in local time. This does not affect data coming from erlang, - only the logs output directly by run_erl. The application - <c><![CDATA[sasl]]></c> can be modified accordingly by setting the erlang - application variable <c><![CDATA[utc_log]]></c> to <c><![CDATA[true]]></c>.</item> - <tag>RUN_ERL_LOG_GENERATIONS</tag> - <item>Controls the number of log files written before older - files are being reused. Default is 5, minimum is 2, maximum is 1000.</item> - <tag>RUN_ERL_LOG_MAXSIZE</tag> - <item>The size (in bytes) of a log file before switching to a - new log file. Default is 100000, minimum is 1000 and maximum is - approximately 2^30.</item> - <tag>RUN_ERL_DISABLE_FLOWCNTRL</tag> - <item>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 hit Ctrl-S (instead of Ctrl-D to detach). - Which may result in blocking of the entire beam process - and in the case of running heart as supervisor - even the heart process will be blocked when writing log message to terminal. - Leaving the heart process unable to do its work.</item> + <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 + SASL 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> + <p>Note that, as a way to indicate the newest file, <c>run_erl</c> 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 + <c>RUN_ERL_LOG_GENERATIONS</c>.</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>start(1), start_erl(1)</p> + <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> |