l4/pkg/cunit/doc/html/error_handling.html

   1 <HTML>
   2 <HEAD>
   3   <TITLE>CUnit - Error Handling</TITLE>
   4   <LINK REL=StyleSheet HREF="CUnit_doc.css" TYPE="text/css" TITLE="CUnit Basic Style" />
   5 </HEAD>
   6 <BODY>
   7 <DIV CLASS="NAVHEADER" >
   8 <TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0">
   9   <TR>
  10     <TH COLSPAN="3" ALIGN="center"><H3>CUnit Progammers Guide</H3></TH>
  11   </TR>
  12   <TR>
  13     <TD WIDTH="10%" ALIGN="left" VALIGN="bottom"><A HREF="running_tests.html" ACCESSKEY="P" >Prev</A></TD>
  14     <TD WIDTH="80%" ALIGN="center" VALIGN="bottom"><A HREF="index.html" ACCESSKEY="H" >Home</A></TD>
  15     <TD WIDTH="10%" ALIGN="right" VALIGN="bottom"><A HREF="index.html" ACCESSKEY="N" >Home</A></TD>
  16   </TR>
  17 </TABLE>
  18 <HR ALIGN="LEFT" WIDTH="100%">
  19
  20 <H2>6. Error Handling</H2>
  21
  22 <H3 ID="synopsis">6.1. Synopsis</H3>
  23 #include &lt;<A HREF="headers/CUError.h">CUnit/CUError.h</A>&gt;
  24 (included automatically by &lt;<A HREF="headers/CUnit.h">CUnit/CUnit.h</A>&gt;)
  25 <PRE>
  26   typedef enum <A HREF="#errorcodes">CU_ErrorCode</A>
  27   CU_ErrorCode   <A HREF="#geterror">CU_get_error</A>(void);
  28   const char*    <A HREF="#getmsg">CU_get_error_msg</A>(void);
  29
  30   typedef enum <A HREF="#actioncodes">CU_ErrorAction</A>
  31   void           <A HREF="#setaction">CU_set_error_action</A>(CU_ErrorAction action);
  32   CU_ErrorAction <A HREF="#getaction">CU_get_error_action</A>(void);
  33 </PRE>
  34 <P />
  35
  36 <H3 ID="errorhandling">6.2. CUnit Error Handling</H3>
  37 Most CUnit functions set an error code indicating the framework
  38 error status.  Some functions return the code, while others just
  39 set the code and return some other value.  Two functions are
  40 provided for examining the framework error status:
  41 <P CLASS="indent2">
  42   <CITE ID="geterror">CU_ErrorCode <B>CU_get_error</B>(void)</CITE><BR />
  43   <CITE ID="getmsg">const char* <B>CU_get_error_msg</B>(void)</CITE>
  44 </P>
  45 The first returns the error code itself, while the second returns a
  46 message describing the error status.  The error code is an
  47 <CODE>enum</CODE> of type <CITE>CU_ErrorCode</CITE> defined in
  48 &lt;<A HREF="headers/CUError.h">CUnit/CUError.h</A>&gt.
  49 The following error code values are defined:
  50 <P CLASS="indent5">
  51 <TABLE CELLPADDING=2>
  52   <TR>
  53     <TD><B>Error Value</B></TD>
  54     <TD><B>Description</B></TD>
  55   </TR>
  56   <TR>
  57     <TD><CITE>CUE_SUCCESS</CITE></TD>
  58     <TD>No error condition.</TD>
  59   </TR>
  60   <TR>
  61     <TD><CITE>CUE_NOMEMORY</CITE></TD>
  62     <TD>Memory allocation failed.</TD>
  63   </TR>
  64   <TR>
  65     <TD><CITE>CUE_NOREGISTRY</CITE></TD>
  66     <TD>Test registry not initialized.</TD>
  67   </TR>
  68   <TR>
  69     <TD><CITE>CUE_REGISTRY_EXISTS</CITE></TD>
  70     <TD>Attempt to CU_set_registry() without CU_cleanup_registry().</TD>
  71   </TR>
  72   <TR>
  73     <TD><CITE>CUE_NOSUITE</CITE></TD>
  74     <TD>A required CU_pSuite pointer was NULL.</TD>
  75   </TR>
  76   <TR>
  77     <TD><CITE>CUE_NO_SUITENAME</CITE></TD>
  78     <TD>Required CU_Suite name not provided.</TD>
  79   </TR>
  80   <TR>
  81     <TD><CITE>CUE_SINIT_FAILED</CITE></TD>
  82     <TD>Suite initialization failed.</TD>
  83   </TR>
  84   <TR>
  85     <TD><CITE>CUE_SCLEAN_FAILED</CITE></TD>
  86     <TD>Suite cleanup failed.</TD>
  87   </TR>
  88   <TR>
  89     <TD><CITE>CUE_DUP_SUITE</CITE></TD>
  90     <TD>Duplicate suite name not allowed.</TD>
  91   </TR>
  92   <TR>
  93     <TD><CITE>CUE_NOTEST</CITE></TD>
  94     <TD>A required CU_pTest pointer was NULL.</TD>
  95   </TR>
  96   <TR>
  97     <TD><CITE>CUE_NO_TESTNAME</CITE></TD>
  98     <TD>Required CU_Test name not provided.</TD>
  99   </TR>
 100   <TR>
 101     <TD><CITE>CUE_DUP_TEST</CITE></TD>
 102     <TD>Duplicate test case name not allowed.</TD>
 103   </TR>
 104   <TR>
 105     <TD><CITE>CUE_TEST_NOT_IN_SUITE</CITE></TD>
 106     <TD>Test is not registered in the specified suite.</TD>
 107   </TR>
 108   <TR>
 109     <TD><CITE>CUE_FOPEN_FAILED</CITE></TD>
 110     <TD>An error occurred opening a file.</TD>
 111   </TR>
 112   <TR>
 113     <TD><CITE>CUE_FCLOSE_FAILED</CITE></TD>
 114     <TD>An error occurred closing a file.</TD>
 115   </TR>
 116   <TR>
 117     <TD><CITE>CUE_BAD_FILENAME</CITE></TD>
 118     <TD>A bad filename was requested (NULL, empty, nonexistent, etc.).</TD>
 119   </TR>
 120   <TR>
 121     <TD><CITE>CUE_WRITE_ERROR</CITE></TD>
 122     <TD>An error occurred during a write to a file.</TD>
 123   </TR>
 124 </TABLE>
 125 </P>
 126
 127 <H3 ID="erroraction">6.3. Behavior Upon Framework Errors</H3>
 128 The default behavior when an error condition is encountered is for the
 129 error code to be set and execution continued.  There may be times when
 130 clients prefer for a test run to stop on a framework error, or even for
 131 the test application to exit.  This behavior can be set by the user,
 132 for which the following functions are provided:
 133 <P CLASS="indent2">
 134   <CITE ID="setaction">void <B>CU_set_error_action</B>(CU_ErrorAction action)</CITE><BR />
 135   <CITE ID="getaction">CU_ErrorAction <B>CU_get_error_action</B>(void)</CITE>
 136 </P>
 137 The error action code is an <CODE>enum</CODE> of type <CITE>CU_ErrorAction</CITE>
 138 defined in &lt;<A HREF="headers/CUError.h">CUnit/CUError.h</A>&gt.
 139 The following error action codes are defined:
 140 <P CLASS="indent5">
 141 <TABLE CELLPADDING=2>
 142   <TR>
 143     <TD><B>Error Value</B></TD>
 144     <TD><B>Description</B></TD>
 145   </TR>
 146   <TR>
 147     <TD><CITE>CUEA_IGNORE</CITE></TD>
 148     <TD>Runs should be continued when an error condition occurs (default)</TD>
 149   </TR>
 150   <TR>
 151     <TD><CITE>CUEA_FAIL</CITE></TD>
 152     <TD>Runs should be stopped when an error condition occurs</TD>
 153   </TR>
 154   <TR>
 155     <TD><CITE>CUEA_ABORT</CITE></TD>
 156     <TD>The application should exit() when an error conditions occurs</TD>
 157   </TR>
 158 </TABLE>
 159
 160 <H3 ID="deprecated">6.4. Deprecated v1 Variables & Functions</H3>
 161 The following variables and functions are deprecated as of version 2.
 162 To use these deprecated names, user code must be compiled with
 163 <CITE>USE_DEPRECATED_CUNIT_NAMES</CITE> defined.
 164 <P />
 165 <TABLE CELLPADDING=5 BORDER=2>
 166   <TR VALIGN="top">
 167     <TD><B>Deprecated Name</B></TD>
 168     <TD><B>Equivalent New Name</B></TD>
 169   </TR>
 170   <TR VALIGN="top">
 171     <TD><CODE>get_error()</CODE></TD>
 172     <TD><A HREF="#getmsg">CU_get_error_msg()</A></TD>
 173   </TR>
 174   <TR VALIGN="top">
 175     <TD><CODE>error_code</CODE></TD>
 176     <TD>None.  Use <A HREF="#getcode">CU_get_error()</A></TD>
 177   </TR>
 178 </TABLE>
 179
 180 <DIV CLASS="NAVFOOTER">
 181 <HR ALIGN="LEFT" WIDTH="100%">
 182 <TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0">
 183   <TR>
 184     <TD WIDTH="33%" ALIGN="left" VALIGN="top"><A HREF="running_tests.html" ACCESSKEY="P">Prev</A></TD>
 185     <TD WIDTH="34%" ALIGN="center" VALIGN="top"><A HREF="index.html" ACCESSKEY="H" >Home</A></TD>
 186     <TD WIDTH="33%" ALIGN="right" VALIGN="top">&nbsp;</TD>
 187   </TR>
 188   <TR>
 189     <TD WIDTH="33%" ALIGN="left" VALIGN="top">Running Tests</TD>
 190     <TD WIDTH="34%" ALIGN="center" VALIGN="top">&nbsp;</TD>
 191     <TD WIDTH="33%" ALIGN="right" VALIGN="top">&nbsp;</TD>
 192   </TR>
 193 </TABLE>
 194 </DIV>
 195
 196 </BODY>
 197 </HTML>
 198