NAME

       run_erl - Redirect Erlang input and output streams on Solaris(R)

DESCRIPTION

       This  describes  the  run_erl 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  to_erl connect to the Erlang console making it possible to monitor and debug
       an embedded system remotely.

       You can read more about the use in the Embedded System User's Guide.

EXPORTS

       run_erl [-daemon] pipe_dir/ log_dir "exec command [command_arguments]"

              The run_erl program arguments are:

                -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:
                  This is where to put the named pipe, usually /tmp/. It shall be suffixed by a /
                  (slash), i.e. not /tmp/epipies, but /tmp/epipes/.

                log_dir:
                  This is where  the  log  files  are  written.  There  will  be  one  log  file,
                  run_erl.log  that log progress and warnings from the run_erl 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 run_erl
                  will delete and reuse the oldest log file.

                "exec command [command_arguments]":
                  In  the  third  argument  command is the to execute where everything written to
                  stdin and stdout is logged to log_dir.

NOTES CONCERNING THE LOG FILES

       While running, run_erl (as stated earlier) sends all output, uninterpreted, to a log file.
       The  file  is  called  erlang.log.N,  where N is a number. When the log is "full", default
       after 100KB, run_erl starts to log in file erlang.log.(N+1), 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:

             ===== ALIVE <date-time-string>

       while the other timestamps look like this:

             ===== <date-time-string>

       The date-time-string 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 strftime
       using the format string %a %b %e %T %Z %Y, which produces messages on the  line  of  =====
       ALIVE Thu May 15 10:13:36 MEST 2003, this can be changed, see below.

ENVIRONMENT VARIABLES

       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.

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

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

         RUN_ERL_LOG_ALIVE_FORMAT:
           Specifies another format string to be  used  in  the  strftime  C  library  call.  i.e
           specifying  this  to  "%e-%b-%Y, %T %Z" will give log messages with timestamps looking
           like 15-May-2003, 10:23:04 MET etc. See the documentation for the C  library  function
           strftime for more information. Default is "%a %b %e %T %Z %Y".

         RUN_ERL_LOG_ALIVE_IN_UTC:
           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 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 being reused.  Default
           is 5, minimum is 2, maximum is 1000.

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

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

SEE ALSO

       start_embedded(1)