Exit Codes
Brett Lee
===============================================================================


1.  The # of bits *captured* from a return code varies.
    Here are some examples:

	shell scripts		- capture 8-bits
	tcl/expect scripts	- capture 8-bits
	perl scripts		- capture 16-bits
	c binaries		- capture 16-bits

2.  Below is a table that provides an overview.  I'll admit its not the
    simplest way to look at this, but with a little bit of clarification I
    hope its useful.

    There are three columns.  The left column shows what is captured when
    a program capturing either 8 or 16 bits calls an 8 bit capturing program.
    The middle column shows an 8 bit capturing program calling another 8 bit 
    capturing program.  The third column shows a 16 bit capturing program
    calling another 16 bit capturing program.

    Each column shows differing exit values on the left and the captured
    return code on the right, in this format:
    "Value of Exit code" -> "Value captured by the calling process".

    For example, the first entry in the first column indicates:
    The called process exitied with '-258', the calling process captured '254'.

    The first entry in the second column indicates:
    The called process exitied with '-258', the calling process captured '65054'.


(8/16-bit -> 8-bit)	(8-bit -> 16-bit)		(16-bit -> 16-bit)

    ...			    ...				   ...
-258 -> 254		-258 -> 65024 (254*256)		-258 -> 65024 (254*256)
-257 -> 255		-257 -> 65280 (255*256)		-257 -> 65280 (255*256)
-256 -> 0		-256 -> 0     (0*256)		-256 -> 0     (0*256)
-255 -> 1		-255 -> 256   (1*256)		-255 -> 256   (1*256)
    ...			    ...				    ...
  -2 -> 254		  -2 -> 65024 (254*256)		  -2 -> 65024 (254*256)
  -1 -> 255		  -1 -> 65280 (255*256)		  -1 -> 65280 (255*256)
   0 -> 0		   0 -> 0			   0 -> 0
   1 -> 1		   1 -> 1			   1 -> 256   (1*256)
   2 -> 2		   2 -> 2			   2 -> 512   (2*256)
    ...			    ...				    ...
 255 -> 255		 255 -> 255			 255 -> 65280 (255*256)
 256 -> 0		 256 -> 0     (0*256)		 256 -> 0     (0*256)
 257 -> 1		 257 -> 256   (1*256)		 257 -> 256   (1*256)
 258 -> 2		 258 -> 512   (2*256)		 258 -> 512   (2*256)
 259 -> 3		 259 -> 768   (3*256)		 259 -> 768   (3*256)
    ...			    ...  			     ...
 511 -> 255	         511 -> 65280 (255*256)		 511 -> 65280 (255*256)
 512 -> 0		 512 -> 0			 512 -> 0
 513 -> 1		 513 -> 256			 513 -> 256
 514 -> 2		 514 -> 512			 514 -> 512
    ...			    ...				    ...


This mess of a table can be summarized into these short rules:

Shell Scripts:
------------------
  Exit values are from 0 on up - negative exit values result in an error.
  If called by:
    shell      |       values > 255 predictably bitwised to 0-255
    tcl/expect |       values > 255 predictably bitwised to 0-255
    perl       |       values > 255 return as multiples of 256
    c          |       values > 255 return as multiples of 256

TCL / Expect Scripts:
----------------------
  Exit values can be both positive and negative.
  If called by:
    shell      |       values > 255 predictably bitwised to 0-255
                       values < 0 predictably bitwised to 0-255
    tcl/expect |       values > 255 predictably bitwised to 0-255
                       values < 0 predictably bitwised to 0-255
    perl       |       values > 255 return as multiples of 256
                       values < 0 return as multiples of 256
    c          |       values > 255 return as multiples of 256
                       values < 0 return as multiples of 256

Perl Scripts:
------------------
  Exit values can be both positive and negative.
  If called by:
    shell      |       values > 255 predictably bitwised to 0-255
                       values < 0 predictably bitwised to 0-255
    tcl/expect |       values > 255 predictably bitwised to 0-255
                       values < 0 predictably bitwised to 0-255
    perl       |       values > 0 return as multiples of 256
                       values < 0 return as multiples of 256
    c          |       values > 0 return as multiples of 256
                       values < 0 return as multiples of 256

C Binaries:
------------------
  Exit values can be both positive and negative.
  If called by:
    shell      |       values > 255 predictably bitwised to 0-255
                       values < 0 predictably bitwised to 0-255
    tcl/expect |       values > 255 predictably bitwised to 0-255
                       values < 0 predictably bitwised to 0-255
    perl       |       values > 0 return as multiples of 256
                       values < 0 return as multiples of 256
    c          |       values > 0 return as multiples of 256
                       values < 0 return as multiples of 256


3.  So, how do we make sense of this?

There has to be a formula I can use...

Remember that Shell and TCL scripts support 8-bit return codes.  Also notice
that the 8-bit programs returning exit codes between 0-255 work as expected.

The 16-bit languages "appear" different, but they too contain an 8-bit exit
code; it's just hidden in a 16-bit code.  To get at the actual 8-bit exit code,
a simple bitwise calculation is needed (right shifting by 8 bits).


Finally, here is an example how to get those extra bits out of the exit code:

Run this script to get an idea what Perl will return to the shell:

$ cat exitpl.sh 
#!/bin/bash

perl -le 'system "perl exit.pl 0";  $exit_code = $? >> 8; print "$exit_code"'
perl -le 'system "perl exit.pl 1";  $exit_code = $? >> 8; print "$exit_code"'
perl -le 'system "perl exit.pl -1"; $exit_code = $? >> 8; print "$exit_code"'

perl -le 'system "perl exit.pl -1"; 
          $exit_code = $? >> 8;
             print "Exit code: $exit_code";
          $signal_num  = ($? & 127); 
             print "Signal Number: $signal_num";
          $core_dumped = ($? & 128); 
             print "Core dumped: $core_dumped"
         ' # save the backtick :)
$ 


Or for a shorter version, pass in your own exit code:

$ cat exit.pl
#!/usr/bin/perl
my $RC = shift;
exit $RC;
$


Happy reading,
-Brett