run_erl(1)

💖 run_erl 💖

okay bestie, welcome to the Erlang Module Definition manual, and today's main character is run_erl — a lil Unix-only program that does unbelievably important work and gets zero credit. this is run_erl(1), and no, you can't use it on Windows, it said Unix systems, plural, and it meant it. 🦋

---

✨ NAME ✨

run_erl — redirect Erlang input and output streams on Unix systems 💅

---

🌸 DESCRIPTION 🌸

okay so run_erl is specific to Unix systems, like that's its whole personality. what it does is redirect the standard input and standard output streams so that all output can be logged. and that's not even the best part — it also lets the program to_erl connect to the Erlang console, which means you can monitor and debug an embedded system remotely. yes. from afar. iconic. 👑

for more info about how to actually use it, go read the Embedded System User's Guide in System Documentation. iykyk.

run_erl [-daemon] pipe_dir/ log_dir "exec command arg1 arg2 ..."

here come the arguments, pay attention bestie, there's a ✨trick✨ in one of them:

• -daemon — okay this one is highly recommended, fr fr. it makes run_erl run in the background, completely detached from any controlling terminal, and the command returns to whoever called it immediately. if you don't use it, you have to start run_erl using several tricks in the shell to detach it completely from the terminal in use when starting it. several. tricks. in the shell. no thank you. 🫠 this option must be the first argument to run_erl on the command line — first. not second. first. 💀
• pipe_dir — this is the named pipe, usually /tmp/. and here's the thing bestie, it must be suffixed by a / (slash). like, /tmp/epipes/, not /tmp/epipes. the slash is load-bearing. do not take the slash away from her. 🎀
• log_dir — the log files live here, and there's a whole lil family of them:
  • one log file, run_erl.log, which logs progress and warnings from the run_erl program itself. that's her diary. 📓
  • 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 the sizes can be changed by environment variables, see the Environment Variables section below — we'll get there, don't worry 💜)
  • when the logs are full, run_erl deletes and reuses the oldest log file. recycling queen. ♻️
• "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. slay. ✨

---

🎀 Notes concerning the Log Files 🎀

while it's running, run_erl sends all output, uninterpreted, to a log file. no editing, no vibes-checking it, just raw. 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. it's a little carousel of logs bestie, round and round. 🎠

now, 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's a time stamp, and it's written, by default, after 15 minutes of inactivity. just a little "hey, still here 🫶".

also, if output from Erlang is logged, but more than 5 minutes (default) has passed since we last got anything from Erlang, a time stamp is written in the log.

the "ALIVE" messages look as follows:

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

and 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, more on that in a sec). it's 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. and yes, that can be changed too — 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 (you literally just read it, bestie, you're so prepared ✨).

• 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. timezone glow-up. 🌍
• 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 exist, that means #2 is the latest and #4 is the oldest. you will therefore get at most one less log file than the value set by RUN_ERL_LOG_GENERATIONS. the missing file IS the signal. it's giving detective work. 🔍

• 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 opened 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. 😭 so yeah. Ctrl+S is not your friend here. Ctrl+D is. 🫶

---

🦋 See Also 🦋

start(1), start_erl(1) — go read your siblings, bestie, they miss you 💜

---

and that's the whole page!! 🎀 brought to you by Ericsson AB, running erts 17.0.6, and this is run_erl(1) signing off. stay logged, stay detached from your controlling terminal, and remember: put the slash in pipe_dir. periodt. 💅✨👑