{"id":82,"date":"2010-05-13T01:02:27","date_gmt":"2010-05-13T05:02:27","guid":{"rendered":"http:\/\/adamrosenfield.com\/blog\/?p=82"},"modified":"2011-02-23T02:27:12","modified_gmt":"2011-02-23T06:27:12","slug":"so-whats-in-an-exit-status-anyways","status":"publish","type":"post","link":"http:\/\/adamrosenfield.com\/blog\/2010\/05\/13\/so-whats-in-an-exit-status-anyways\/","title":{"rendered":"So what’s in an exit status anyways?"},"content":{"rendered":"

Last time<\/a>, we saw how we can capture a process’ core dump. The astute reader will have noticed that we seem to be pulling bits out of thin air:<\/p>\n

int status;\r\nif(wait(&status) < 0)\r\n  perror("wait");\r\nif(WIFSIGNALED(status) && WCOREDUMP(status))\r\n...<\/pre>\n
We’ve got a 32-bit exit status, and yet we seem to getting two more useful bits of information out of it from the WIFSIGNALED()<\/code> and WCOREDUMP()<\/code> macros.  How is that possible?<\/p>\n
Well, what you thought was a 32-bit exit status really isn’t 32 bits.  In fact, it’s quite a bit less than.  The C standard only guarantees one useful bit.  Quoth section 7.20.4.3, paragraph 5, of the C99 standard<\/a>, which describes the exit(3)<\/code><\/a> function:<\/p>\n
Finally, control is returned to the host environment. If the value of status<\/code> is zero or EXIT_SUCCESS<\/code>, an implementation-defined form of the status successful termination<\/em> is returned. If the value of status<\/code> is EXIT_FAILURE<\/code>, an implementation-defined form of the status unsuccessful termination<\/em> is returned. Otherwise the status returned is implementation-defined.<\/p><\/blockquote>\n
Recall that implementation-defined<\/em> means the C standard doesn’t define what happens, but the implementation<\/em> (in this case, the GNU C library, or the Microsoft C library, etc.) must document<\/b> the decision it made.  Contrast this with undefined behavior<\/em>, in which anything could happen (including erasing your hard drive), and nowhere does what happens have to be documented.<\/p>\n
So if you want to write portable code, you only get one bit of information in your exit status: successful or unsuccessful termination, which is often good enough for most applications.  If you go this route, it’s a good idea to use the EXIT_SUCCESS<\/code> and EXIT_FAILURE<\/code> macros, but it’s by no means necessary.  You can use still use 0 and something non-0 (1 is a popular\u2014and good\u2014choice), and it will still work pretty much anywhere if you’re not unlucky.  But the only truly 100% portable unsuccessful status is EXIT_FAILURE<\/code>.<\/p>\n
Screw that.  You want more than one bit of information in your exit status.  There’s a whole 32 bits (or occasionally 16 or 64 on some non-standard systems) in an int<\/code>, so why can’t we use them?  On Linux, the exit(3)<\/code> man page<\/a> clearly states we get 8 bits:<\/p>\n
The exit()<\/b> function causes normal process termination and the value of status & 0377<\/em> is returned to the parent (see wait<\/a><\/b>(2)<\/em>).<\/p><\/blockquote>\n
Mac OS X<\/a> likewise also provides 8 bits (though that fact is a little more subtle in the documentation there).  Windows fares better here\u2014it provides the full 32 bits via the GetExitCodeProcess()<\/code><\/a> function here\u2014but the discussion here is going to focus on Linux\/Mac OS X for now.<\/p>\n
8 bits.  Much more useful than 1, though not quite the 32 you might have been hoping for.  It’s enough to express a varied gamut of exit statuses (incorrect usage<\/em>, file not found<\/em>, other unexpected error<\/em>, etc.).<\/p>\n
A consequence of this behavior is if you exit with a status that is a multiple of 256, that’s indistinguishable from 0, which means you’re likely exiting with a successful status when you meant it to be unsuccessful.  Oops.<\/p>\n
As a quick example, try out these shell commands ($?<\/code> is a special parameter<\/a> that evaluates to the exit status of the last child process or pipeline ran by the shell):<\/p>\n
$ bash -c 'exit 5'; echo $?     # Prints 5\r\n$ bash -c 'exit 256'; echo $?   # Prints 0 (!)<\/pre>\n
Now that we’ve figured out we only have 8 bits that come with an exit status, it’s clear how the WIFSIGNALED()<\/code> and WCOREDUMP()<\/code> macros work: wait(2)<\/code><\/a> stuffs extra information into the status in addition to the child process’ exit status (you could have figured that out by reading the man page, but you obviously didn’t since you’re here reading this).<\/p>\n
One final word of caution: be careful about exit statuses above 128.  When a process is terminated due to a signal (say, because it segfaulted, resulting in a SIGSEGV<\/code>), the exit status is 128 plus the signal number.  Yes, a parent process can tell if the child process was terminated by a signal or by calling exit()<\/code> by checking with WIFSIGNALED()<\/code>, but it’s not always possible to get at that information when you want it.  If you’re executing commands in the bash shell, you can get at the exit status quite easily with $?<\/code>, but you can’t get at the other bits returned by wait()<\/code>, at least not in any way I know.  To keep things simple, if you never use exit statuses above 128, then anyone can unambiguously determine that an exit status of 0\u2013127 means a normal exit, and an exit status of 128\u2013255 means an abnormal exit.<\/p>\n
In summary, use only EXIT_SUCCESS<\/code> and EXIT_FAILURE<\/code> for maximally portable code, and otherwise use only 0\u2013127 for code that will be portable to Linux, Mac OS X, and Windows (and probably other not-uncommon systems that are still in current us but with which I’m not familiar enough to comment on).<\/p>\n","protected":false},"excerpt":{"rendered":"
Last time, we saw how we can capture a process’ core dump. The astute reader will have noticed that we seem to be pulling bits out of thin air: int status; if(wait(&status) < 0) perror("wait"); if(WIFSIGNALED(status) && WCOREDUMP(status)) … We’ve got a 32-bit exit status, and yet we seem to getting two more useful bits […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5],"tags":[],"class_list":["post-82","post","type-post","status-publish","format-standard","hentry","category-programming"],"_links":{"self":[{"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/posts\/82","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/comments?post=82"}],"version-history":[{"count":8,"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/posts\/82\/revisions"}],"predecessor-version":[{"id":195,"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/posts\/82\/revisions\/195"}],"wp:attachment":[{"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/media?parent=82"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/categories?post=82"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/adamrosenfield.com\/blog\/wp-json\/wp\/v2\/tags?post=82"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}