<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta name="robots" content="noindex">
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>cpl_error.h File Reference</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body bgcolor="#ffffff">
<!-- Generated by Doxygen 1.2.3-20001105 on Thu Mar 28 09:47:31 2002 -->
<center>
<a class="qindex" href="index.html">Main Page</a> <a class="qindex" href="hierarchy.html">Class Hierarchy</a> <a class="qindex" href="annotated.html">Compound List</a> <a class="qindex" href="files.html">File List</a> <a class="qindex" href="functions.html">Compound Members</a> <a class="qindex" href="globals.html">File Members</a> <a class="qindex" href="pages.html">Related Pages</a> </center>
<hr><h1>cpl_error.h File Reference</h1><code>#include "<a class="el" href="cpl_port_h-source.html">cpl_port.h</a>"</code><br>
<p>
<a href="cpl_error_h-source.html">Go to the source code of this file.</a><table border=0 cellpadding=0 cellspacing=0>
<tr><td colspan=2><br><h2>Defines</h2></td></tr>
<tr><td nowrap align=right valign=top><a name="a0" doxytag="cpl_error.h::CPLAssert"></a>
#define </td><td valign=bottom><b>CPLAssert</b>(expr)</td></tr>
<tr><td nowrap align=right valign=top><a name="a1" doxytag="cpl_error.h::CPLE_None"></a>
#define </td><td valign=bottom><b>CPLE_None</b> 0</td></tr>
<tr><td nowrap align=right valign=top><a name="a2" doxytag="cpl_error.h::CPLE_AppDefined"></a>
#define </td><td valign=bottom><b>CPLE_AppDefined</b> 1</td></tr>
<tr><td nowrap align=right valign=top><a name="a3" doxytag="cpl_error.h::CPLE_OutOfMemory"></a>
#define </td><td valign=bottom><b>CPLE_OutOfMemory</b> 2</td></tr>
<tr><td nowrap align=right valign=top><a name="a4" doxytag="cpl_error.h::CPLE_FileIO"></a>
#define </td><td valign=bottom><b>CPLE_FileIO</b> 3</td></tr>
<tr><td nowrap align=right valign=top><a name="a5" doxytag="cpl_error.h::CPLE_OpenFailed"></a>
#define </td><td valign=bottom><b>CPLE_OpenFailed</b> 4</td></tr>
<tr><td nowrap align=right valign=top><a name="a6" doxytag="cpl_error.h::CPLE_IllegalArg"></a>
#define </td><td valign=bottom><b>CPLE_IllegalArg</b> 5</td></tr>
<tr><td nowrap align=right valign=top><a name="a7" doxytag="cpl_error.h::CPLE_NotSupported"></a>
#define </td><td valign=bottom><b>CPLE_NotSupported</b> 6</td></tr>
<tr><td nowrap align=right valign=top><a name="a8" doxytag="cpl_error.h::CPLE_AssertionFailed"></a>
#define </td><td valign=bottom><b>CPLE_AssertionFailed</b> 7</td></tr>
<tr><td nowrap align=right valign=top><a name="a9" doxytag="cpl_error.h::CPLE_NoWriteAccess"></a>
#define </td><td valign=bottom><b>CPLE_NoWriteAccess</b> 8</td></tr>
<tr><td nowrap align=right valign=top><a name="a10" doxytag="cpl_error.h::CPLE_UserInterrupt"></a>
#define </td><td valign=bottom><b>CPLE_UserInterrupt</b> 9</td></tr>
<tr><td colspan=2><br><h2>Typedefs</h2></td></tr>
<tr><td nowrap align=right valign=top><a name="a11" doxytag="cpl_error.h::CPLErrorHandler"></a>
typedef void (* </td><td valign=bottom><b>CPLErrorHandler</b> )(CPLErr, int, const char*)</td></tr>
<tr><td colspan=2><br><h2>Enumerations</h2></td></tr>
<tr><td nowrap align=right valign=top>enum </td><td valign=bottom><b>CPLErr</b> { <br>
<b>CE_None</b> = 0,
<b>CE_Debug</b> = 1,
<b>CE_Warning</b> = 2,
<b>CE_Failure</b> = 3,
<br>
<b>CE_Fatal</b> = 4
<br>
}</td></tr>
<tr><td colspan=2><br><h2>Functions</h2></td></tr>
<tr><td nowrap align=right valign=top>void CPL_DLL </td><td valign=bottom><a class="el" href="cpl_error_h.html#a17">CPLError</a> (CPLErr eErrClass, int err_no, const char *fmt, ...)</td></tr>
<tr><td nowrap align=right valign=top><a name="a18" doxytag="cpl_error.h::CPLErrorV"></a>
void CPL_DLL </td><td valign=bottom><b>CPLErrorV</b> (CPLErr, int, const char *, va_list )</td></tr>
<tr><td nowrap align=right valign=top>void CPL_DLL </td><td valign=bottom><a class="el" href="cpl_error_h.html#a19">CPLErrorReset</a> ()</td></tr>
<tr><td nowrap align=right valign=top>int CPL_DLL </td><td valign=bottom><a class="el" href="cpl_error_h.html#a20">CPLGetLastErrorNo</a> ()</td></tr>
<tr><td nowrap align=right valign=top>CPLErr CPL_DLL </td><td valign=bottom><a class="el" href="cpl_error_h.html#a21">CPLGetLastErrorType</a> ()</td></tr>
<tr><td nowrap align=right valign=top>const char CPL_DLL* </td><td valign=bottom><a class="el" href="cpl_error_h.html#a22">CPLGetLastErrorMsg</a> ()</td></tr>
<tr><td nowrap align=right valign=top>CPLErrorHandler CPL_DLL </td><td valign=bottom><a class="el" href="cpl_error_h.html#a23">CPLSetErrorHandler</a> (CPLErrorHandler)</td></tr>
<tr><td nowrap align=right valign=top>void CPL_DLL </td><td valign=bottom><a class="el" href="cpl_error_h.html#a24">CPLPushErrorHandler</a> ( CPLErrorHandler )</td></tr>
<tr><td nowrap align=right valign=top>void CPL_DLL </td><td valign=bottom><a class="el" href="cpl_error_h.html#a25">CPLPopErrorHandler</a> ()</td></tr>
<tr><td nowrap align=right valign=top><a name="a26" doxytag="cpl_error.h::CPLDefaultErrorHandler"></a>
void CPL_DLL </td><td valign=bottom><b>CPLDefaultErrorHandler</b> ( CPLErr, int, const char * )</td></tr>
<tr><td nowrap align=right valign=top><a name="a27" doxytag="cpl_error.h::CPLQuietErrorHandler"></a>
void CPL_DLL </td><td valign=bottom><b>CPLQuietErrorHandler</b> ( CPLErr, int, const char * )</td></tr>
<tr><td nowrap align=right valign=top><a name="a28" doxytag="cpl_error.h::CPLLoggingErrorHandler"></a>
void CPL_DLL </td><td valign=bottom><b>CPLLoggingErrorHandler</b> ( CPLErr, int, const char * )</td></tr>
<tr><td nowrap align=right valign=top>void CPL_DLL </td><td valign=bottom><a class="el" href="cpl_error_h.html#a29">CPLDebug</a> ( const char *, const char *, ... )</td></tr>
<tr><td nowrap align=right valign=top>void CPL_DLL </td><td valign=bottom><a class="el" href="cpl_error_h.html#a30">_CPLAssert</a> ( const char *, const char *, int )</td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
<p>
CPL error handling services.
<p>
<hr><h2>Function Documentation</h2>
<a name="a29" doxytag="cpl_error.h::CPLDebug"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
void CPL_DLL CPLDebug (
</b></td>
<td valign="bottom"><b>
const char * <em>pszCategory</em>,
</b></td>
</tr>
<tr>
<td></td>
<td><b>
const char * <em>pszFormat</em>,
</b></td>
</tr>
<tr>
<td></td>
<td><b>
... )
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Display a debugging message.
<p>
The category argument is used in conjunction with the CPL_DEBUG environment variable to establish if the message should be displayed. If the CPL_DEBUG environment variable is not set, no debug messages are emitted (use CPLError(CE_Warning,...) to ensure messages are displayed). If CPL_DEBUG is set, but is an empty string or the word "ON" then all debug messages are shown. Otherwise only messages whose category appears somewhere within the CPL_DEBUG value are displayed (as determinted by strstr()).
<p>
Categories are usually an identifier for the subsystem producing the error. For instance "GDAL" might be used for the GDAL core, and "TIFF" for messages from the TIFF translator.<dl compact><dt>
<b>Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>pszCategory</em>
</td><td>
name of the debugging message category. </td></tr>
<tr><td valign=top><em>pszFormat</em>
</td><td>
printf() style format string for message to display. Remaining arguments are assumed to be for format. </td></tr>
</table>
</dl> </td>
</tr>
</table>
<a name="a17" doxytag="cpl_error.h::CPLError"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
void CPL_DLL CPLError (
</b></td>
<td valign="bottom"><b>
CPLErr <em>eErrClass</em>,
</b></td>
</tr>
<tr>
<td></td>
<td><b>
int <em>err_no</em>,
</b></td>
</tr>
<tr>
<td></td>
<td><b>
const char * <em>fmt</em>,
</b></td>
</tr>
<tr>
<td></td>
<td><b>
... )
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Report an error.
<p>
This function reports an error in a manner that can be hooked and reported appropriate by different applications.
<p>
The effect of this function can be altered by applications by installing a custom error handling using <a class="el" href="cpl_error_h.html#a23">CPLSetErrorHandler</a>().
<p>
The eErrClass argument can have the value CE_Warning indicating that the message is an informational warning, CE_Failure indicating that the action failed, but that normal recover mechanisms will be used or CE_Fatal meaning that a fatal error has occured, and that <a class="el" href="cpl_error_h.html#a17">CPLError</a>() should not return.
<p>
The default behaviour of <a class="el" href="cpl_error_h.html#a17">CPLError</a>() is to report errors to stderr, and to abort() after reporting a CE_Fatal error. It is expected that some applications will want to supress error reporting, and will want to install a C++ exception, or longjmp() approach to no local fatal error recovery.
<p>
Regardless of how application error handlers or the default error handler choose to handle an error, the error number, and message will be stored for recovery with <a class="el" href="cpl_error_h.html#a20">CPLGetLastErrorNo</a>() and <a class="el" href="cpl_error_h.html#a22">CPLGetLastErrorMsg</a>().<dl compact><dt>
<b>Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>eErrClass</em>
</td><td>
one of CE_Warning, CE_Failure or CE_Fatal. </td></tr>
<tr><td valign=top><em>err_no</em>
</td><td>
the error number (CPLE_*) from <a class="el" href="cpl_error_h.html">cpl_error.h</a>. </td></tr>
<tr><td valign=top><em>fmt</em>
</td><td>
a printf() style format string. Any additional arguments will be treated as arguments to fill in this format in a manner similar to printf(). </td></tr>
</table>
</dl> </td>
</tr>
</table>
<a name="a19" doxytag="cpl_error.h::CPLErrorReset"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
void CPL_DLL CPLErrorReset (
</b></td>
<td valign="bottom"><b>
)
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Erase any traces of previous errors.
<p>
This is normally used to ensure that an error which has been recovered from does not appear to be still in play with high level functions. </td>
</tr>
</table>
<a name="a22" doxytag="cpl_error.h::CPLGetLastErrorMsg"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
const char CPL_DLL* CPLGetLastErrorMsg (
</b></td>
<td valign="bottom"><b>
)
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Get the last error message.
<p>
Fetches the last error message posted with <a class="el" href="cpl_error_h.html#a17">CPLError</a>(), that hasn't been cleared by <a class="el" href="cpl_error_h.html#a19">CPLErrorReset</a>(). The returned pointer is to an internal string that should not be altered or freed.
<p>
<dl compact><dt>
<b>Returns: </b><dd>
the last error message, or NULL if there is no posted error message. </dl> </td>
</tr>
</table>
<a name="a20" doxytag="cpl_error.h::CPLGetLastErrorNo"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
int CPL_DLL CPLGetLastErrorNo (
</b></td>
<td valign="bottom"><b>
)
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Fetch the last error number.
<p>
This is the error number, not the error class.
<p>
<dl compact><dt>
<b>Returns: </b><dd>
the error number of the last error to occur, or CPLE_None (0) if there are no posted errors. </dl> </td>
</tr>
</table>
<a name="a21" doxytag="cpl_error.h::CPLGetLastErrorType"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
CPLErr CPL_DLL CPLGetLastErrorType (
</b></td>
<td valign="bottom"><b>
)
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Fetch the last error type.
<p>
This is the error class, not the error number.
<p>
<dl compact><dt>
<b>Returns: </b><dd>
the error number of the last error to occur, or CE_None (0) if there are no posted errors. </dl> </td>
</tr>
</table>
<a name="a25" doxytag="cpl_error.h::CPLPopErrorHandler"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
void CPL_DLL CPLPopErrorHandler (
</b></td>
<td valign="bottom"><b>
)
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Restore old CPLError handler.
<p>
Discards the current error handler, and restore the one in use before the last <a class="el" href="cpl_error_h.html#a24">CPLPushErrorHandler</a>() call. </td>
</tr>
</table>
<a name="a24" doxytag="cpl_error.h::CPLPushErrorHandler"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
void CPL_DLL CPLPushErrorHandler (
</b></td>
<td valign="bottom"><b>
CPLErrorHandler <em>pfnErrorHandler</em> )
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Assign new CPLError handler.
<p>
The old handler is "pushed down" onto a stack and can be easily restored with <a class="el" href="cpl_error_h.html#a25">CPLPopErrorHandler</a>(). Otherwise this works similarly to <a class="el" href="cpl_error_h.html#a23">CPLSetErrorHandler</a>() which contains more details on how error handlers work.<dl compact><dt>
<b>Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>pfnErrorHandler</em>
</td><td>
new error handler function. </td></tr>
</table>
</dl> </td>
</tr>
</table>
<a name="a23" doxytag="cpl_error.h::CPLSetErrorHandler"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
CPLErrorHandler CPL_DLL CPLSetErrorHandler (
</b></td>
<td valign="bottom"><b>
CPLErrorHandler <em>pfnErrorHandler</em> )
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Install custom error handler.
<p>
Allow the library's user to specify his own error handler function. A valid error handler is a C function with the following prototype:
<p>
<pre>
void MyErrorHandler(CPLErr eErrClass, int err_no, const char *msg)
</pre>
<p>
Pass NULL to come back to the default behavior. The default behaviour (<a class="el" href="cpl_error_h.html">CPLDefaultErrorHandler</a>()) is to write the message to stderr.
<p>
The msg will be a partially formatted error message not containing the "ERROR d:" portion emitted by the default handler. Message formatting is handled by <a class="el" href="cpl_error_h.html#a17">CPLError</a>() before calling the handler. If the error handler function is passed a CE_Fatal class error and returns, then <a class="el" href="cpl_error_h.html#a17">CPLError</a>() will call abort(). Applications wanting to interrupt this fatal behaviour will have to use longjmp(), or a C++ exception to indirectly exit the function.
<p>
Another standard error handler is <a class="el" href="cpl_error_h.html">CPLQuietErrorHandler</a>() which doesn't make any attempt to report the passed error or warning messages but will process debug messages via CPLDefaultErrorHandler.<dl compact><dt>
<b>Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>pfnErrorHandler</em>
</td><td>
new error handler function. </td></tr>
</table>
</dl><dl compact><dt>
<b>Returns: </b><dd>
returns the previously installed error handler. </dl> </td>
</tr>
</table>
<a name="a30" doxytag="cpl_error.h::_CPLAssert"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td nowrap valign="top"><b>
void CPL_DLL _CPLAssert (
</b></td>
<td valign="bottom"><b>
const char * <em>pszExpression</em>,
</b></td>
</tr>
<tr>
<td></td>
<td><b>
const char * <em>pszFile</em>,
</b></td>
</tr>
<tr>
<td></td>
<td><b>
int <em>iLine</em> )
</b></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Report failure of a logical assertion.
<p>
Applications would normally use the <a class="el" href="cpl_error_h.html">CPLAssert</a>() macro which expands into code calling <a class="el" href="cpl_error_h.html#a30">_CPLAssert</a>() only if the condition fails. <a class="el" href="cpl_error_h.html#a30">_CPLAssert</a>() will generate a CE_Fatal error call to <a class="el" href="cpl_error_h.html#a17">CPLError</a>(), indicating the file name, and line number of the failed assertion, as well as containing the assertion itself.
<p>
There is no reason for application code to call <a class="el" href="cpl_error_h.html#a30">_CPLAssert</a>() directly. </td>
</tr>
</table>
<hr><address><small>Generated at Thu Mar 28 09:47:31 2002 for GDAL by
<a href="http://www.stack.nl/~dimitri/doxygen/index.html">
<img src="doxygen.gif" alt="doxygen" align="middle" border=0
width=110 height=53></a>1.2.3-20001105 written by <a href="mailto:dimitri@stack.nl">Dimitri van Heesch</a>,
© 1997-2000</small></address>
</body>
</html>
