EXECLINE-EXITCODES(7)

💅 EXECLINE-EXITCODES(7) — like, the whole "how do I pass exit codes up the family tree" situation

okay so this is a page from the Miscellaneous Information Manual, and it's called execline-exitcodes — say it with me, bestie: execline-exitcodes(7) 🎀

✨ NAME ✨

execline-exitcodes — how to propagate exit codes up a process dynasty 👑

---

🌸 DESCRIPTION 🌸

so picture this. we've got a parent process P, right? and P is the child of a grandparent process G. and P spawns a child process C and then just... waits for it. classic. either C dies normally with an exit code from 0 to 255, or it gets killed by a signal. so the question is: how do we make sure P reports to G what actually happened to C, like, with as much precision as possible?? 💭

here's the problem, and it's lowkey tragic: there's more information in a wstat (that's the structure filled in by waitpid(2)) than a process can report by simply exiting. sure, P could exit with the same exit code as C — but then what's it supposed to do if C got killed by a signal? 😭

so one idea is: have P kill itself with the same signal that killed C. cute in theory! but actually no, that's not right, because P itself could get killed by a signal from another source, and G genuinely needs that info. "P has been killed by a signal" and "C has been killed by a signal" are two completely different pieces of information, so they should not be reported in the same way. periodt. 💅

so yeah, any way you look at it, there is always more information than we can report. that's just the vibes. 🙈

shells have their own convention[1] for reporting crashes, but since any exit code greater than 127 is reported as is, the information given by the shell is unreliable: "child exited 129" and "child was killed by SIGHUP" are indistinguishable. 💀 and when shells get nested? all bets are off — the information conveyed by exit codes becomes devoid of meaning pretty fast. we need something better, fr fr.

🦋 execline's solution 🦋

execline commands such as if(1), that can report a child's exit code, proceed that way when they're in the position of P:

• If C was killed by a signal: P exits 128 plus the signal number. 🔥
• If C exited 128 or more: P exits 128.
• Else, P exits with the same code as C.

rationale (aka why this slaps):

• 128+ exit codes are extremely rare and should report really problematic conditions; commands usually exit 127 or less. so if C exits 128+, it's more important to convey the information "something really bad happened, but the C process itself was not killed by a signal" than the exact nature of the event. the vibe matters more than the details, iykyk.
• commands following that convention can be nested. if P exits 129+, G knows that C was killed by a signal. if G also needs to report that to its parent, it will exit 128: G's parent will not know the signal number, but it will know that P reported 128 or more, so either C or a scion of C had problems. it's giving generational trauma but make it exit codes 🧚
• exact information is reported in the common case. slay.

⭐ Summary of common exit codes for execline programs ⭐

• 0 — Success. this code is rarely encountered, because most execline programs chainload into something else when they succeed, instead of exiting 0. main character energy: they simply don't stick around 💫
• 100 — Wrong usage.
• 111 — System call failed.
• 126 — Unable to chainload into another program (any other error than ENOENT).
• 127 — Unable to chainload into another program (executable not found).

---

💖 SEE ALSO 💖

forx(1), waitpid(2)

[1] https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#tag_18_08_02

this man page is ported from the authoritative documentation at: https://skarnet.org/software/execline/exitcodes.html 🌈

---

👑 AUTHORS 👑

• Laurent Bercot
• Alexis <flexibeast@gmail.com> (man page port)

---

and that's the whole page, bestie 🫶 this came to you straight from Debian, dated March 13, 2022 — mwah, go propagate some exit codes responsibly 💜✨