1run_erl(1)                       User Commands                      run_erl(1)
2
3
4

NAME

6       run_erl - Redirect Erlang input and output streams on Unix systems.
7

DESCRIPTION

9       The run_erl program is specific to Unix systems. This program redirects
10       the standard input and standard output streams so that all  output  can
11       be  logged.  It also lets the program to_erl connect to the Erlang con‐
12       sole, making it possible  to  monitor  and  debug  an  embedded  system
13       remotely.
14
15       For  more  information  about  the use, see the  Embedded System User's
16       Guide in System Documentation.
17

EXPORTS

19       run_erl [-daemon] pipe_dir/ log_dir "exec command arg1 arg2 ..."
20
21              Arguments:
22
23                -daemon:
24                  This option is highly recommended. It makes run_erl  run  in
25                  the background completely detached from any controlling ter‐
26                  minal and the command returns  to  the  caller  immediately.
27                  Without  this  option, run_erl must be started using several
28                  tricks in the shell to detach it completely from the  termi‐
29                  nal  in  use  when starting it. The option must be the first
30                  argument to run_erl on the command line.
31
32                pipe_dir:
33                  The named pipe, usually /tmp/. It must be suffixed  by  a  /
34                  (slash), that is, /tmp/epipes/, not /tmp/epipes.
35
36                log_dir:
37                  The log files, that is:
38
39                  * One  log  file, run_erl.log, which logs progress and warn‐
40                    ings from the run_erl program itself.
41
42                  * Up to five log files at maximum 100 KB each with the  con‐
43                    tent  of  the  standard  streams  from and to the command.
44                    (Both the number of logs and sizes can be changed by envi‐
45                    ronment   variables,  see  section  Environment  Variables
46                    below.)
47
48                    When the logs are full, run_erl  deletes  and  reuses  the
49                    oldest log file.
50
51                "exec command arg1 arg2 ...":
52                  A  space-separated  string specifying the program to be exe‐
53                  cuted. The second field is typically a command name such  as
54                  erl.
55

NOTES CONCERNING THE LOG FILES

57       While  running, run_erl sends all output, uninterpreted, to a log file.
58       The file is named erlang.log.N, where N is an integer. When the log  is
59       "full"  (default  log  size  is  100 KB), run_erl starts to log in file
60       erlang.log.(N+1), until N reaches a certain number (default 5),  where‐
61       upon  N  starts at 1 again and the oldest files start getting overwrit‐
62       ten.
63
64       If no output comes from the Erlang shell, but the Erlang machine  still
65       seems  to  be  alive, an "ALIVE" message is written to the log; it is a
66       time stamp and is written, by default, after 15 minutes of  inactivity.
67       Also,  if  output  from  Erlang  is  logged,  but  more  than 5 minutes
68       (default) has passed since last time we got  anything  from  Erlang,  a
69       time stamp is written in the log. The "ALIVE" messages look as follows:
70
71       ===== ALIVE <date-time-string>
72
73       The other time stamps look as follows:
74
75       ===== <date-time-string>
76
77       date-time-string  is  the date and time the message is written, default
78       in local time (can be changed to UTC if needed). It is  formatted  with
79       the ANSI-C function strftime using the format string %a %b %e %T %Z %Y,
80       which produces messages like ===== ALIVE Thu May 15 10:13:36 MEST 2003;
81       this can be changed, see the next section.
82

ENVIRONMENT VARIABLES

84       The  following  environment  variables  are  recognized  by run_erl and
85       change the logging behavior. For more  information,  see  the  previous
86       section.
87
88         RUN_ERL_LOG_ALIVE_MINUTES:
89           How  long to wait for output (in minutes) before writing an "ALIVE"
90           message to the log. Defaults to 15, minimum is 1.
91
92         RUN_ERL_LOG_ACTIVITY_MINUTES:
93           How long Erlang needs to be inactive before output is preceded with
94           a  time stamp. Defaults to RUN_ERL_LOG_ALIVE_MINUTES div 3, minimum
95           is 1.
96
97         RUN_ERL_LOG_ALIVE_FORMAT:
98           Specifies another format string  to  be  used  in  the  strftime  C
99           library  call.  That is, specifying this to "%e-%b-%Y, %T %Z" gives
100           log messages with time stamps like 15-May-2003, 10:23:04  MET.  For
101           more  information, see the documentation for the C library function
102           strftime. Defaults to "%a %b %e %T %Z %Y".
103
104         RUN_ERL_LOG_ALIVE_IN_UTC:
105           If set to anything else than 0, it makes  all  times  displayed  by
106           run_erl to be in UTC (GMT, CET, MET, without Daylight Saving Time),
107           rather than in local time. This does not affect  data  coming  from
108           Erlang,  only the logs output directly by run_erl. Application SASL
109           can be modified accordingly by setting the Erlang application vari‐
110           able utc_log to true.
111
112         RUN_ERL_LOG_GENERATIONS:
113           Controls  the  number  of  log files written before older files are
114           reused. Defaults to 5, minimum is 2, maximum is 1000.
115
116           Note that, as a way to  indicate  the  newest  file,  run_erl  will
117           delete  the  oldest  log  file  to  maintain  a  "hole" in the file
118           sequences. For example, if log files #1, #2, #4 and #5 exists, that
119           means  #2 is the latest and #4 is the oldest. You will therefore at
120           most get one less log file than the value set by RUN_ERL_LOG_GENER‐
121           ATIONS.
122
123         RUN_ERL_LOG_MAXSIZE:
124           The  size,  in  bytes,  of a log file before switching to a new log
125           file. Defaults to 100000, minimum is 1000, maximum is about 2^30.
126
127         RUN_ERL_DISABLE_FLOWCNTRL:
128           If defined, disables input and output  flow  control  for  the  pty
129           opend by run_erl. Useful if you want to remove any risk of acciden‐
130           tally blocking the flow control by using Ctrl-S (instead of  Ctrl-D
131           to  detach),  which  can  result  in  blocking  of  the entire Beam
132           process, and in the case of running heart as  supervisor  even  the
133           heart process becomes blocked when writing log message to terminal,
134           leaving the heart process unable to do its work.
135

SEE ALSO

137       start(1), start_erl(1)
138
139
140
141Ericsson AB                        erts 11.2                        run_erl(1)
Impressum