NAME

       run_erl - Redirect Erlang input and output streams on Unix systems

DESCRIPTION

       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.

   Notes concerning the Log Files
       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.

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

   See Also
       start(1), start_erl(1)

Ericsson AB                                        erts 15.2.3                                        run_erl(1)