CPL error handling services. More...

#include "cpl_port.h"
#include <stdarg.h>
#include <stddef.h>

Classes
class	CPLErrorHandlerPusher
	Class that installs a (thread-local) error handler on construction, and restore the initial one on destruction. More...

class	CPLErrorStateBackuper
	Class that saves the error state on construction, and restores it on destruction. More...

Macros
#define	CPLE_None 0
	No error.

#define	CPLE_AppDefined 1
	Application defined error.

#define	CPLE_OutOfMemory 2
	Out of memory error.

#define	CPLE_FileIO 3
	File I/O error.

#define	CPLE_OpenFailed 4
	Open failed.

#define	CPLE_IllegalArg 5
	Illegal argument.

#define	CPLE_NotSupported 6
	Not supported.

#define	CPLE_AssertionFailed 7
	Assertion failed.

#define	CPLE_NoWriteAccess 8
	No write access.

#define	CPLE_UserInterrupt 9
	User interrupted.

#define	CPLE_ObjectNull 10
	NULL object.

#define	CPLE_HttpResponse 11
	HTTP response.

#define	CPLE_AWSBucketNotFound 12
	AWSBucketNotFound.

#define	CPLE_AWSObjectNotFound 13
	AWSObjectNotFound.

#define	CPLE_AWSAccessDenied 14
	AWSAccessDenied.

#define	CPLE_AWSInvalidCredentials 15
	AWSInvalidCredentials.

#define	CPLE_AWSSignatureDoesNotMatch 16
	AWSSignatureDoesNotMatch.

#define	CPLE_AWSError 17
	VSIE_AWSError.

#define	CPLDebugOnly(...)
	Same as CPLDebug(), but expands to nothing for non-DEBUG builds. More...

#define	CPLAssert(expr)
	Assert on an expression. More...

#define	CPLAssertAlwaysEval(expr) CPL_IGNORE_RET_VAL(expr)
	Assert on an expression in DEBUG mode. More...

#define	VALIDATE_POINTER0(ptr, func)
	Validate that a pointer is not NULL. More...

#define	VALIDATE_POINTER1(ptr, func, rc)
	Validate that a pointer is not NULL, and return rc if it is NULL. More...

Typedefs
typedef int	CPLErrorNum
	Error number.

typedef void(*	CPLErrorHandler) (CPLErr, CPLErrorNum, const char *)
	Callback for a custom error handler.

Enumerations
enum	CPLErr { CE_None = 0 , CE_Debug = 1 , CE_Warning = 2 , CE_Failure = 3 , CE_Fatal = 4 }
	Error category.

Functions
void	CPLError (CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,...)
	Report an error. More...

void	CPLErrorV (CPLErr, CPLErrorNum, const char *, va_list)
	Same as CPLError() but with a va_list.

void	CPLEmergencyError (const char *)
	Fatal error when things are bad. More...

void	CPLErrorReset (void)
	Erase any traces of previous errors. More...

CPLErrorNum	CPLGetLastErrorNo (void)
	Fetch the last error number. More...

CPLErr	CPLGetLastErrorType (void)
	Fetch the last error type. More...

const char *	CPLGetLastErrorMsg (void)
	Get the last error message. More...

GUInt32	CPLGetErrorCounter (void)
	Get the error counter. More...

void *	CPLGetErrorHandlerUserData (void)
	Fetch the user data for the error context. More...

void	CPLErrorSetState (CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)
	Restore an error state, without emitting an error. More...

void	CPLCallPreviousHandler (CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)
	Call the previously installed error handler in the error handler stack. More...

void	CPLLoggingErrorHandler (CPLErr, CPLErrorNum, const char *)
	Error handler that logs into the file defined by the CPL_LOG configuration option, or stderr otherwise.

void	CPLDefaultErrorHandler (CPLErr, CPLErrorNum, const char *)
	Default error handler.

void	CPLQuietErrorHandler (CPLErr, CPLErrorNum, const char *)
	Error handler that does not do anything, except for debug messages.

void	CPLTurnFailureIntoWarning (int bOn)
	Whether failures should be turned into warnings.

CPLErrorHandler	CPLGetErrorHandler (void **ppUserData)
	Fetch the current error handler for the current error context. More...

CPLErrorHandler	CPLSetErrorHandler (CPLErrorHandler)
	Install custom error handler. More...

CPLErrorHandler	CPLSetErrorHandlerEx (CPLErrorHandler, void *)
	Install custom error handle with user's data. More...

void	CPLPushErrorHandler (CPLErrorHandler)
	Push a new CPLError handler. More...

void	CPLPushErrorHandlerEx (CPLErrorHandler, void *)
	Push a new CPLError handler with user data on the error context. More...

void	CPLSetCurrentErrorHandlerCatchDebug (int bCatchDebug)
	Set if the current error handler should intercept debug messages, or if they should be processed by the previous handler. More...

void	CPLPopErrorHandler (void)
	Pop error handler off stack. More...

void	CPLDebug (const char , const char ,...)
	Display a debugging message. More...

void	CPLDebugProgress (const char , const char ,...)
	Display a debugging message indicating a progression. More...

void	_CPLAssert (const char , const char , int)
	Report failure of a logical assertion. More...

Detailed Description

CPL error handling services.

Macro Definition Documentation

◆ CPLAssert

#define CPLAssert ( expr )

Assert on an expression.

Only enabled in DEBUG mode

◆ CPLAssertAlwaysEval

#define CPLAssertAlwaysEval ( expr ) CPL_IGNORE_RET_VAL(expr)

Assert on an expression in DEBUG mode.

Evaluate it also in non-DEBUG mode (useful to 'consume' a error return variable)

◆ CPLDebugOnly

#define CPLDebugOnly ( ... )

Same as CPLDebug(), but expands to nothing for non-DEBUG builds.

Since: GDAL 3.1

◆ VALIDATE_POINTER0

#define VALIDATE_POINTER0	(	ptr,
		func
	)

Value:

    do                                                                         \
    {                                                                          \
        if (CPL_NULLPTR == ptr)                                                \
        {                                                                      \
            CPLErr const ret = VALIDATE_POINTER_ERR;                           \
            CPLError(ret, CPLE_ObjectNull,                                     \
                     "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func));     \
            return;                                                            \
        }                                                                      \
    } while (0)

Validate that a pointer is not NULL.

◆ VALIDATE_POINTER1

#define VALIDATE_POINTER1	(	ptr,
		func,
		rc
	)

Value:

    do                                                                         \
    {                                                                          \
        if (CPL_NULLPTR == ptr)                                                \
        {                                                                      \
            CPLErr const ret = VALIDATE_POINTER_ERR;                           \
            CPLError(ret, CPLE_ObjectNull,                                     \
                     "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func));     \
            return (rc);                                                       \
        }                                                                      \
    } while (0)

Validate that a pointer is not NULL, and return rc if it is NULL.

Function Documentation

◆ _CPLAssert()

void _CPLAssert	(	const char *	pszExpression,
		const char *	pszFile,
		int	iLine
	)

Report failure of a logical assertion.

Applications would normally use the CPLAssert() macro which expands into code calling _CPLAssert() only if the condition fails. _CPLAssert() will generate a CE_Fatal error call to CPLError(), indicating the file name, and line number of the failed assertion, as well as containing the assertion itself.

There is no reason for application code to call _CPLAssert() directly.

◆ CPLCallPreviousHandler()

void CPLCallPreviousHandler	(	CPLErr	eErrClass,
		CPLErrorNum	err_no,
		const char *	pszMsg
	)

Call the previously installed error handler in the error handler stack.

Only to be used by a custom error handler that wants to forward events to the previous error handler.

Since: GDAL 3.8

◆ CPLDebug()

void CPLDebug	(	const char *	pszCategory,
		const char *	pszFormat,
			...
	)

Display a debugging message.

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 determined by strstr()).

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.

Parameters

pszCategory	name of the debugging message category.
pszFormat	printf() style format string for message to display. Remaining arguments are assumed to be for format.

◆ CPLDebugProgress()

void CPLDebugProgress	(	const char *	pszCategory,
		const char *	pszFormat,
			...
	)

Display a debugging message indicating a progression.

This is the same as CPLDebug(), except that when displaying on the terminal, it will erase the previous debug progress message. This is for example appropriate to display increasing percentages for a task.

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 determined by strstr()).

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.

Parameters

pszCategory	name of the debugging message category.
pszFormat	printf() style format string for message to display. Remaining arguments are assumed to be for format.

Since: 3.9

◆ CPLEmergencyError()

void CPLEmergencyError ( const char * pszMessage )

Fatal error when things are bad.

This function should be called in an emergency situation where it is unlikely that a regular error report would work. This would include in the case of heap exhaustion for even small allocations, or any failure in the process of reporting an error (such as TLS allocations).

This function should never return. After the error message has been reported as best possible, the application will abort() similarly to how CPLError() aborts on CE_Fatal class errors.

Parameters

pszMessage the error message to report.

◆ CPLError()

void CPLError	(	CPLErr	eErrClass,
		CPLErrorNum	err_no,
		const char *	fmt,
			...
	)

Report an error.

This function reports an error in a manner that can be hooked and reported appropriate by different applications.

The effect of this function can be altered by applications by installing a custom error handling using CPLSetErrorHandler().

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 occurred, and that CPLError() should not return.

The default behavior of CPLError() is to report errors to stderr, and to abort() after reporting a CE_Fatal error. It is expected that some applications will want to suppress error reporting, and will want to install a C++ exception, or longjmp() approach to no local fatal error recovery.

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 CPLGetLastErrorNo() and CPLGetLastErrorMsg().

Parameters

eErrClass	one of CE_Warning, CE_Failure or CE_Fatal.
err_no	the error number (CPLE_*) from cpl_error.h.
fmt	a printf() style format string. Any additional arguments will be treated as arguments to fill in this format in a manner similar to printf().

◆ CPLErrorReset()

void CPLErrorReset ( void )

Erase any traces of previous errors.

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.

◆ CPLErrorSetState()

void CPLErrorSetState	(	CPLErr	eErrClass,
		CPLErrorNum	err_no,
		const char *	pszMsg
	)

Restore an error state, without emitting an error.

Can be useful if a routine might call CPLErrorReset() and one wants to preserve the previous error state.

Since: GDAL 2.0

◆ CPLGetErrorCounter()

GUInt32 CPLGetErrorCounter ( void )

Get the error counter.

Fetches the number of errors emitted in the current error context, since the last call to CPLErrorReset()

Returns: the error counter.

Since: GDAL 2.3

◆ CPLGetErrorHandler()

CPLErrorHandler CPLGetErrorHandler ( void ** ppUserData )

Fetch the current error handler for the current error context.

This will be the last error handler pushed in the thread-local error stack with CPLPushErrorHandler()/CPLPushErrorHandlerEx(), or if the stack is empty, the global error handler set with CPLSetErrorHandler()/CPLSetErrorHandlerEx(), or the default global error handler.

Parameters

[out] ppUserData Pointer to store the user data pointer. May be NULL

Since: GDAL 3.7

◆ CPLGetErrorHandlerUserData()

void * CPLGetErrorHandlerUserData ( void )

Fetch the user data for the error context.

Fetches the user data for the current error context. You can set the user data for the error context when you add your handler by issuing CPLSetErrorHandlerEx() and CPLPushErrorHandlerEx(). Note that user data is primarily intended for providing context within error handlers themselves, but they could potentially be abused in other useful ways with the usual caveat emptor understanding.

Returns: the user data pointer for the error context

◆ CPLGetLastErrorMsg()

const char * CPLGetLastErrorMsg ( void )

Get the last error message.

Fetches the last error message posted with CPLError(), that hasn't been cleared by CPLErrorReset(). The returned pointer is to an internal string that should not be altered or freed.

Returns: the last error message, or an empty string ("") if there is no posted error message.

◆ CPLGetLastErrorNo()

CPLErrorNum CPLGetLastErrorNo ( void )

Fetch the last error number.

Fetches the last error number posted with CPLError(), that hasn't been cleared by CPLErrorReset(). This is the error number, not the error class.

Returns: the error number of the last error to occur, or CPLE_None (0) if there are no posted errors.

◆ CPLGetLastErrorType()

CPLErr CPLGetLastErrorType ( void )

Fetch the last error type.

Fetches the last error type posted with CPLError(), that hasn't been cleared by CPLErrorReset(). This is the error class, not the error number.

Returns: the error type of the last error to occur, or CE_None (0) if there are no posted errors.

◆ CPLPopErrorHandler()

void CPLPopErrorHandler ( void )

Pop error handler off stack.

Discards the current error handler on the error handler stack, and restores the one in use before the last CPLPushErrorHandler() call. This method has no effect if there are no error handlers on the current threads error handler stack.

◆ CPLPushErrorHandler()

void CPLPushErrorHandler ( CPLErrorHandler pfnErrorHandlerNew )

Push a new CPLError handler.

This pushes a new error handler on the thread-local error handler stack. This handler will be used until removed with CPLPopErrorHandler().

The CPLSetErrorHandler() docs have further information on how CPLError handlers work.

Parameters

pfnErrorHandlerNew new error handler function.

◆ CPLPushErrorHandlerEx()

void CPLPushErrorHandlerEx	(	CPLErrorHandler	pfnErrorHandlerNew,
		void *	pUserData
	)

Push a new CPLError handler with user data on the error context.

This pushes a new error handler on the thread-local error handler stack. This handler will be used until removed with CPLPopErrorHandler(). Obtain the user data back by using CPLGetErrorContext().

The CPLSetErrorHandler() docs have further information on how CPLError handlers work.

Parameters

pfnErrorHandlerNew	new error handler function.
pUserData	User data to put on the error context.

◆ CPLSetCurrentErrorHandlerCatchDebug()

void CPLSetCurrentErrorHandlerCatchDebug ( int bCatchDebug )

Set if the current error handler should intercept debug messages, or if they should be processed by the previous handler.

By default when installing a custom error handler, this one intercepts debug messages. In some cases, this might not be desirable and the user would prefer that the previous installed handler (or the default one if no previous installed handler exists in the stack) deal with it. In which case, this function should be called with bCatchDebug = FALSE.

Parameters

bCatchDebug FALSE if the current error handler should not intercept debug messages

Since: GDAL 2.1

◆ CPLSetErrorHandler()

CPLErrorHandler CPLSetErrorHandler ( CPLErrorHandler pfnErrorHandlerNew )

Install custom error handler.

Allow the library's user to specify an error handler function. A valid error handler is a C function with the following prototype:

    void MyErrorHandler(CPLErr eErrClass, int err_no, const char *msg)

Pass NULL to come back to the default behavior. The default behavior (CPLDefaultErrorHandler()) is to write the message to stderr.

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 CPLError() before calling the handler. If the error handler function is passed a CE_Fatal class error and returns, then CPLError() will call abort(). Applications wanting to interrupt this fatal behavior will have to use longjmp(), or a C++ exception to indirectly exit the function.

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.

Note that error handlers set with CPLSetErrorHandler() 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 precedence over the global error handlers set with CPLSetErrorHandler(). Generally speaking CPLSetErrorHandler() would be used to set a desired global error handler, while CPLPushErrorHandler() would be used to install a temporary local error handler, such as CPLQuietErrorHandler() to suppress error reporting in a limited segment of code.

Parameters

pfnErrorHandlerNew new error handler function.

Returns: returns the previously installed error handler.

◆ CPLSetErrorHandlerEx()

CPLErrorHandler CPLSetErrorHandlerEx	(	CPLErrorHandler	pfnErrorHandlerNew,
		void *	pUserData
	)

Install custom error handle with user's data.

This method is essentially CPLSetErrorHandler with an added pointer to pUserData. The pUserData is not returned in the CPLErrorHandler, however, and must be fetched via CPLGetErrorHandlerUserData.

Parameters

pfnErrorHandlerNew	new error handler function.
pUserData	User data to carry along with the error context.

Returns: returns the previously installed error handler.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CPLAssert

◆ CPLAssertAlwaysEval

◆ CPLDebugOnly

◆ VALIDATE_POINTER0

◆ VALIDATE_POINTER1

Function Documentation

◆ _CPLAssert()

◆ CPLCallPreviousHandler()

◆ CPLDebug()

◆ CPLDebugProgress()

◆ CPLEmergencyError()

◆ CPLError()

◆ CPLErrorReset()

◆ CPLErrorSetState()

◆ CPLGetErrorCounter()

◆ CPLGetErrorHandler()

◆ CPLGetErrorHandlerUserData()

◆ CPLGetLastErrorMsg()

◆ CPLGetLastErrorNo()

◆ CPLGetLastErrorType()

◆ CPLPopErrorHandler()

◆ CPLPushErrorHandler()

◆ CPLPushErrorHandlerEx()

◆ CPLSetCurrentErrorHandlerCatchDebug()

◆ CPLSetErrorHandler()

◆ CPLSetErrorHandlerEx()