<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>OGR: cpl_error.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.2-20100208 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li class="current"><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="files.html"><span>File List</span></a></li>
<li><a href="globals.html"><span>File Members</span></a></li>
</ul>
</div>
<div class="navpath"><a class="el" href="dir_9403295bfc17f2c2ba80cf17b83e4de3.html">port</a>
</div>
</div>
<div class="contents">
<h1>cpl_error.h File Reference</h1><code>#include "<a class="el" href="cpl__port_8h_source.html">cpl_port.h</a>"</code><br/>
<p><a href="cpl__error_8h_source.html">Go to the source code of this file.</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#aad2b98dd58e4de706a245faddac90403">CPLError</a> (CPLErr eErrClass, int err_no, const char *fmt,...)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#a29626fd8fdb658b19439beeb73a59560">CPLErrorReset</a> (void)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#a198afe56aced1d73226880aa90d39b99">CPLGetLastErrorNo</a> (void)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">CPLErr </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#a8df0d4e01034cf79202314c92251e920">CPLGetLastErrorType</a> (void)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">const char * </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#a7f71ade3bb0a0e9e45802975ec59ff5e">CPLGetLastErrorMsg</a> (void)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">CPLErrorHandler </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#a74d0e649d58180e621540bf73b58e4a2">CPLSetErrorHandler</a> (CPLErrorHandler)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#ad13c9c8f2037ddfd566c2a197f7b2537">CPLPushErrorHandler</a> (CPLErrorHandler)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#ac6c7c393c94b210e4be999f34fcb6680">CPLPopErrorHandler</a> (void)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#ad0c5d3481dd34c1f3a0f7775ebf74817">CPLDebug</a> (const char *, const char *,...)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="cpl__error_8h.html#ab032ae39a103f985abc8599d822c2630">_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 class="anchor" id="ab032ae39a103f985abc8599d822c2630"></a><!-- doxytag: member="cpl_error.h::_CPLAssert" ref="ab032ae39a103f985abc8599d822c2630" args="(const char *, const char *, int)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void _CPLAssert </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>pszExpression</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>pszFile</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>iLine</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Report failure of a logical assertion.</p>
<p>Applications would normally use the CPLAssert() macro which expands into code calling <a class="el" href="cpl__error_8h.html#ab032ae39a103f985abc8599d822c2630">_CPLAssert()</a> only if the condition fails. <a class="el" href="cpl__error_8h.html#ab032ae39a103f985abc8599d822c2630">_CPLAssert()</a> will generate a CE_Fatal error call to <a class="el" href="cpl__error_8h.html#aad2b98dd58e4de706a245faddac90403">CPLError()</a>, indicating the file name, and line number of the failed assertion, as well as containing the assertion itself.</p>
<p>There is no reason for application code to call <a class="el" href="cpl__error_8h.html#ab032ae39a103f985abc8599d822c2630">_CPLAssert()</a> directly. </p>
</div>
</div>
<a class="anchor" id="ad0c5d3481dd34c1f3a0f7775ebf74817"></a><!-- doxytag: member="cpl_error.h::CPLDebug" ref="ad0c5d3481dd34c1f3a0f7775ebf74817" args="(const char *, const char *,...)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void CPLDebug </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>pszCategory</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>pszFormat</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"> <em>...</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Display a debugging message.</p>
<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>
<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.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>pszCategory</em> </td><td>name of the debugging message category. </td></tr>
<tr><td valign="top"></td><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>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="aad2b98dd58e4de706a245faddac90403"></a><!-- doxytag: member="cpl_error.h::CPLError" ref="aad2b98dd58e4de706a245faddac90403" args="(CPLErr eErrClass, int err_no, const char *fmt,...)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void CPLError </td>
<td>(</td>
<td class="paramtype">CPLErr </td>
<td class="paramname"> <em>eErrClass</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>err_no</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>fmt</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"> <em>...</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Report an error.</p>
<p>This function reports an error in a manner that can be hooked and reported appropriate by different applications.</p>
<p>The effect of this function can be altered by applications by installing a custom error handling using <a class="el" href="cpl__error_8h.html#a74d0e649d58180e621540bf73b58e4a2">CPLSetErrorHandler()</a>.</p>
<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_8h.html#aad2b98dd58e4de706a245faddac90403">CPLError()</a> should not return.</p>
<p>The default behaviour of <a class="el" href="cpl__error_8h.html#aad2b98dd58e4de706a245faddac90403">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>
<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_8h.html#a198afe56aced1d73226880aa90d39b99">CPLGetLastErrorNo()</a> and <a class="el" href="cpl__error_8h.html#a7f71ade3bb0a0e9e45802975ec59ff5e">CPLGetLastErrorMsg()</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>eErrClass</em> </td><td>one of CE_Warning, CE_Failure or CE_Fatal. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>err_no</em> </td><td>the error number (CPLE_*) from <a class="el" href="cpl__error_8h.html">cpl_error.h</a>. </td></tr>
<tr><td valign="top"></td><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>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a29626fd8fdb658b19439beeb73a59560"></a><!-- doxytag: member="cpl_error.h::CPLErrorReset" ref="a29626fd8fdb658b19439beeb73a59560" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void CPLErrorReset </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Erase any traces of previous errors.</p>
<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. </p>
</div>
</div>
<a class="anchor" id="a7f71ade3bb0a0e9e45802975ec59ff5e"></a><!-- doxytag: member="cpl_error.h::CPLGetLastErrorMsg" ref="a7f71ade3bb0a0e9e45802975ec59ff5e" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">const char* CPLGetLastErrorMsg </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the last error message.</p>
<p>Fetches the last error message posted with <a class="el" href="cpl__error_8h.html#aad2b98dd58e4de706a245faddac90403">CPLError()</a>, that hasn't been cleared by <a class="el" href="cpl__error_8h.html#a29626fd8fdb658b19439beeb73a59560">CPLErrorReset()</a>. The returned pointer is to an internal string that should not be altered or freed.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>the last error message, or NULL if there is no posted error message. </dd></dl>
</div>
</div>
<a class="anchor" id="a198afe56aced1d73226880aa90d39b99"></a><!-- doxytag: member="cpl_error.h::CPLGetLastErrorNo" ref="a198afe56aced1d73226880aa90d39b99" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int CPLGetLastErrorNo </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Fetch the last error number.</p>
<p>This is the error number, not the error class.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>the error number of the last error to occur, or CPLE_None (0) if there are no posted errors. </dd></dl>
</div>
</div>
<a class="anchor" id="a8df0d4e01034cf79202314c92251e920"></a><!-- doxytag: member="cpl_error.h::CPLGetLastErrorType" ref="a8df0d4e01034cf79202314c92251e920" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">CPLErr CPLGetLastErrorType </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Fetch the last error type.</p>
<p>This is the error class, not the error number.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>the error number of the last error to occur, or CE_None (0) if there are no posted errors. </dd></dl>
</div>
</div>
<a class="anchor" id="ac6c7c393c94b210e4be999f34fcb6680"></a><!-- doxytag: member="cpl_error.h::CPLPopErrorHandler" ref="ac6c7c393c94b210e4be999f34fcb6680" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void CPLPopErrorHandler </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Pop error handler off stack.</p>
<p>Discards the current error handler on the error handler stack, and restores the one in use before the last <a class="el" href="cpl__error_8h.html#ad13c9c8f2037ddfd566c2a197f7b2537">CPLPushErrorHandler()</a> call. This method has no effect if there are no error handlers on the current threads error handler stack. </p>
</div>
</div>
<a class="anchor" id="ad13c9c8f2037ddfd566c2a197f7b2537"></a><!-- doxytag: member="cpl_error.h::CPLPushErrorHandler" ref="ad13c9c8f2037ddfd566c2a197f7b2537" args="(CPLErrorHandler)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void CPLPushErrorHandler </td>
<td>(</td>
<td class="paramtype">CPLErrorHandler </td>
<td class="paramname"> <em>pfnErrorHandlerNew</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Push a new CPLError handler.</p>
<p>This pushes a new error handler on the thread-local error handler stack. This handler will be used untill removed with <a class="el" href="cpl__error_8h.html#ac6c7c393c94b210e4be999f34fcb6680">CPLPopErrorHandler()</a>.</p>
<p>The <a class="el" href="cpl__error_8h.html#a74d0e649d58180e621540bf73b58e4a2">CPLSetErrorHandler()</a> docs have further information on how CPLError handlers work.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>pfnErrorHandlerNew</em> </td><td>new error handler function. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a74d0e649d58180e621540bf73b58e4a2"></a><!-- doxytag: member="cpl_error.h::CPLSetErrorHandler" ref="a74d0e649d58180e621540bf73b58e4a2" args="(CPLErrorHandler)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">CPLErrorHandler CPLSetErrorHandler </td>
<td>(</td>
<td class="paramtype">CPLErrorHandler </td>
<td class="paramname"> <em>pfnErrorHandlerNew</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Install custom error handler.</p>
<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 (CPLDefaultErrorHandler()) is to write the message to stderr.</p>
<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_8h.html#aad2b98dd58e4de706a245faddac90403">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_8h.html#aad2b98dd58e4de706a245faddac90403">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>
<p>Another standard error handler is CPLQuietErrorHandler() which doesn't make any attempt to report the passed error or warning messages but will process debug messages via CPLDefaultErrorHandler.</p>
<p>Note that error handlers set with <a class="el" href="cpl__error_8h.html#a74d0e649d58180e621540bf73b58e4a2">CPLSetErrorHandler()</a> apply to all threads in an application, while error handlers set with CPLPushErrorHandler are thread-local. However, any error handlers pushed with CPLPushErrorHandler (and not removed with CPLPopErrorHandler) take precidence over the global error handlers set with <a class="el" href="cpl__error_8h.html#a74d0e649d58180e621540bf73b58e4a2">CPLSetErrorHandler()</a>. Generally speaking <a class="el" href="cpl__error_8h.html#a74d0e649d58180e621540bf73b58e4a2">CPLSetErrorHandler()</a> would be used to set a desired global error handler, while <a class="el" href="cpl__error_8h.html#ad13c9c8f2037ddfd566c2a197f7b2537">CPLPushErrorHandler()</a> would be used to install a temporary local error handler, such as CPLQuietErrorHandler() to suppress error reporting in a limited segment of code.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>pfnErrorHandlerNew</em> </td><td>new error handler function. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>returns the previously installed error handler. </dd></dl>
</div>
</div>
</div>
<hr>
Generated for GDAL by
<a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.6.2-20100208.
</body>
</html>
