What should my program's exit code be if I caught a signal?

Question

I think I may have been doing this wrong for a while, because we just switched to systemd and it's considering my cleanly-killed process to have ended unsuccessfully.

Basically I listen for SIGHUP, SIGINT and SIGTERM and then (by passing the signal code back up to main) cleanly e.g. return 128+SIGHUP.

I expected this to be used to populate $?, but now I think I understand that the shell is responsible for giving $? such a value, and then only if the signal was unhandled. So even if the process exited ultimately due a signal, because the signal was handled, $? will end up being 0 and all evidence that a signal had anything to do with the exiting will be lost. Is that right?

When handling SIGHUP and cleanly exiting, should I return EXIT_SUCCESS from main?

I guess it depends. If the termination by the signal is considered a successful run of the binary then yes. If those signals indicate an error then EXIT_FAILURE. — Hayt, Sep 01 '16 at 10:53
@Hayt: So the takeaway is that I shouldn't be doing _anything_ to incorporate the signal code into the process exit code either way? — Lightness Races in Orbit, Sep 01 '16 at 10:54
Is being terminated or hung up a sign that your program failed in its task? — StoryTeller - Unslander Monica, Sep 01 '16 at 10:56
@StoryTeller: No. (And, even if it were, I would still return only `EXIT_FAILURE` rather than incorporating a signal code?) — Lightness Races in Orbit, Sep 01 '16 at 10:58
Return codes can be whatever you define them to be. But if you dont need the signal in the return code there is no reason to incorperate them. Also you would have to make sure your return code+signal would not be the same value as another return code + signal so it's unique — Hayt, Sep 01 '16 at 10:59
@Hayt: Alright I'll go for 0 or 1 regardless of signal handling antics. Could someone write up an answer? :) — Lightness Races in Orbit, Sep 01 '16 at 11:00

score 9 · Accepted Answer · edited May 23 '17 at 12:01

The convention of returning 128 + <signal number> is promoted by the Advanced Bash Scripting Guide among others (https://stackoverflow.com/a/1535733/567292), but is only for the case when your program fails as a result of receiving the signal.

If your program receives the signal, does not handle it, and is terminated as a result, the exit status (as provided e.g. by wait) will be similar but instead of bit 7 set will have a higher bit set to indicate WIFSIGNALED as opposed to WIFEXITED. If you are running in a shell, this is then translated by the shell to give an exit status ($?) in the range 128-255 (i.e., with bit 7 set), so as far as a shell script is concerned, a program returning 128+n is indistinguishable from a program terminating because a signal was unhandled:

[...] When reporting the exit status with the special parameter '?', the shell shall report the full eight bits of exit status available. The exit status of a command that terminated because it received a signal shall be reported as greater than 128.

If your program receives a signal then successfully exits, this is considered a successful termination, so your program should return EXIT_SUCCESS.

Perfect, thanks :) This has been a "bug" in my event framework for some six years. Whoops... — Lightness Races in Orbit, Sep 01 '16 at 11:34

score 2 · Answer 2 · answered Sep 01 '16 at 11:02

Return Codes are usually what you specify them. When you want to include signal to exit codes, you have to make sure they still stay unique.

If you don't need the signal in the exit code there seems to be no reason to include them though.

Whether to return EXIT_SUCCESS or EXIT_FAILURE is up to you/your program whether the termination counts as success or failure.

score 0 · Answer 3 · answered May 16 '23 at 17:24

One reason why your program should return a non-zero exit code on a signal, even if your program cleanups everything up nicely, is that if your program is used in Bash scripts like:

your_program && next_program

and user presses ctrl-c, it will terminate your_program but next_program will continue to run, which is not something a user would expect.

Example issue reporting this: https://github.com/conan-io/conan/issues/2360

I think in daemons it might be more reasonable to return 0.

What should my program's exit code be if I caught a signal?

3 Answers3