SDTS_AL
Macros | Typedefs | Enumerations | Functions
cpl_error.h File Reference
#include "cpl_port.h"
#include <stdarg.h>
#include <stddef.h>

Go to the source code of this file.

Macros

#define CPLE_None   0
 
#define CPLE_AppDefined   1
 
#define CPLE_OutOfMemory   2
 
#define CPLE_FileIO   3
 
#define CPLE_OpenFailed   4
 
#define CPLE_IllegalArg   5
 
#define CPLE_NotSupported   6
 
#define CPLE_AssertionFailed   7
 
#define CPLE_NoWriteAccess   8
 
#define CPLE_UserInterrupt   9
 
#define CPLE_ObjectNull   10
 
#define CPLE_HttpResponse   11
 
#define CPLE_AWSBucketNotFound   12
 
#define CPLE_AWSObjectNotFound   13
 
#define CPLE_AWSAccessDenied   14
 
#define CPLE_AWSInvalidCredentials   15
 
#define CPLE_AWSSignatureDoesNotMatch   16
 
#define CPLAssert(expr)
 
#define VALIDATE_POINTER0(ptr, func)
 
#define VALIDATE_POINTER1(ptr, func, rc)
 

Typedefs

typedef int CPLErrorNum
 
typedef void(CPL_STDCALL * CPLErrorHandler) (CPLErr, CPLErrorNum, const char *)
 

Enumerations

enum  CPLErr
 

Functions

void CPL_DLL void CPL_DLL CPLErrorV (CPLErr, CPLErrorNum, const char *, va_list)
 
void CPL_DLL CPLEmergencyError (const char *) CPL_NO_RETURN
 
void CPL_DLL CPL_STDCALL CPLErrorReset (void)
 
CPLErrorNum CPL_DLL CPL_STDCALL CPLGetLastErrorNo (void)
 
CPLErr CPL_DLL CPL_STDCALL CPLGetLastErrorType (void)
 
const char CPL_DLL *CPL_STDCALL CPLGetLastErrorMsg (void)
 
void CPL_DLL *CPL_STDCALL CPLGetErrorHandlerUserData (void)
 
void CPL_DLL CPLErrorSetState (CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)
 
void CPL_DLL CPL_STDCALL CPLLoggingErrorHandler (CPLErr, CPLErrorNum, const char *)
 
void CPL_DLL CPL_STDCALL CPLDefaultErrorHandler (CPLErr, CPLErrorNum, const char *)
 
void CPL_DLL CPL_STDCALL CPLQuietErrorHandler (CPLErr, CPLErrorNum, const char *)
 
void CPLTurnFailureIntoWarning (int bOn)
 
CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandler (CPLErrorHandler)
 
CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandlerEx (CPLErrorHandler, void *)
 
void CPL_DLL CPL_STDCALL CPLPushErrorHandler (CPLErrorHandler)
 
void CPL_DLL CPL_STDCALL CPLPushErrorHandlerEx (CPLErrorHandler, void *)
 
void CPL_DLL CPL_STDCALL CPLSetCurrentErrorHandlerCatchDebug (int bCatchDebug)
 
void CPL_DLL CPL_STDCALL CPLPopErrorHandler (void)
 
void CPL_DLL CPL_STDCALL void CPL_DLL CPL_STDCALL _CPLAssert (const char *, const char *, int) CPL_NO_RETURN
 

Detailed Description

CPL error handling services.

Macro Definition Documentation

◆ CPLAssert

#define CPLAssert (   expr)

Assert on an expression. Only enabled in DEBUG mode

◆ CPLE_AppDefined

#define CPLE_AppDefined   1

Application defined error

◆ CPLE_AssertionFailed

#define CPLE_AssertionFailed   7

Assertion failed

◆ CPLE_AWSAccessDenied

#define CPLE_AWSAccessDenied   14

AWSAccessDenied

◆ CPLE_AWSBucketNotFound

#define CPLE_AWSBucketNotFound   12

AWSBucketNotFound

◆ CPLE_AWSInvalidCredentials

#define CPLE_AWSInvalidCredentials   15

AWSInvalidCredentials

◆ CPLE_AWSObjectNotFound

#define CPLE_AWSObjectNotFound   13

AWSObjectNotFound

◆ CPLE_AWSSignatureDoesNotMatch

#define CPLE_AWSSignatureDoesNotMatch   16

AWSSignatureDoesNotMatch

◆ CPLE_FileIO

#define CPLE_FileIO   3

File I/O error

◆ CPLE_HttpResponse

#define CPLE_HttpResponse   11

HTTP response

◆ CPLE_IllegalArg

#define CPLE_IllegalArg   5

Illegal argument

◆ CPLE_None

#define CPLE_None   0

No error

◆ CPLE_NotSupported

#define CPLE_NotSupported   6

Not supported

◆ CPLE_NoWriteAccess

#define CPLE_NoWriteAccess   8

No write access

◆ CPLE_ObjectNull

#define CPLE_ObjectNull   10

NULL object

◆ CPLE_OpenFailed

#define CPLE_OpenFailed   4

Open failed

◆ CPLE_OutOfMemory

#define CPLE_OutOfMemory   2

Out of memory error

◆ CPLE_UserInterrupt

#define CPLE_UserInterrupt   9

User interrupted

◆ VALIDATE_POINTER0

#define VALIDATE_POINTER0 (   ptr,
  func 
)
Value:
do { if( NULL == ptr ) \
{ \
CPLErr const ret = VALIDATE_POINTER_ERR; \
CPLError( ret, CPLE_ObjectNull, \
"Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
return; }} while(0)
#define CPLE_ObjectNull
Definition: cpl_error.h:118

Validate that a pointer is not NULL

◆ VALIDATE_POINTER1

#define VALIDATE_POINTER1 (   ptr,
  func,
  rc 
)
Value:
do { if( NULL == ptr ) \
{ \
CPLErr const ret = VALIDATE_POINTER_ERR; \
CPLError( ret, CPLE_ObjectNull, \
"Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
return (rc); }} while(0)
#define CPLE_ObjectNull
Definition: cpl_error.h:118

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

Typedef Documentation

◆ CPLErrorHandler

typedef void(CPL_STDCALL * CPLErrorHandler) (CPLErr, CPLErrorNum, const char *)

Callback for a custom error handler

◆ CPLErrorNum

typedef int CPLErrorNum

Error number

Enumeration Type Documentation

◆ CPLErr

enum CPLErr

Error category

Function Documentation

◆ _CPLAssert()

void CPL_DLL CPL_STDCALL void CPL_DLL CPL_STDCALL _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.

◆ CPLDefaultErrorHandler()

void CPL_DLL CPL_STDCALL CPLDefaultErrorHandler ( CPLErr  eErrClass,
CPLErrorNum  nError,
const char *  pszErrorMsg 
)

Default error handler.

◆ CPLEmergencyError()

void CPL_DLL 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
pszMessagethe error message to report.

◆ CPLErrorReset()

void CPL_DLL CPL_STDCALL 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 CPL_DLL 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

◆ CPLErrorV()

void CPL_DLL void CPL_DLL CPLErrorV ( CPLErr  eErrClass,
CPLErrorNum  err_no,
const char *  fmt,
va_list  args 
)

Same as CPLError() but with a va_list

◆ CPLGetErrorHandlerUserData()

void CPL_DLL* CPL_STDCALL 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 CPL_DLL* CPL_STDCALL 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 NULL if there is no posted error message.

◆ CPLGetLastErrorNo()

CPLErrorNum CPL_DLL CPL_STDCALL 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 CPL_DLL CPL_STDCALL 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.

◆ CPLLoggingErrorHandler()

void CPL_DLL CPL_STDCALL CPLLoggingErrorHandler ( CPLErr  eErrClass,
CPLErrorNum  nError,
const char *  pszErrorMsg 
)

Error handler that logs into the file defined by the CPL_LOG configuration option, or stderr otherwise.

◆ CPLPopErrorHandler()

void CPL_DLL CPL_STDCALL 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 CPL_DLL CPL_STDCALL 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
pfnErrorHandlerNewnew error handler function.

◆ CPLPushErrorHandlerEx()

void CPL_DLL CPL_STDCALL 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
pfnErrorHandlerNewnew error handler function.
pUserDataUser data to put on the error context.

◆ CPLQuietErrorHandler()

void CPL_DLL CPL_STDCALL CPLQuietErrorHandler ( CPLErr  eErrClass,
CPLErrorNum  nError,
const char *  pszErrorMsg 
)

Error handler that does not do anything, except for debug messages.

◆ CPLSetCurrentErrorHandlerCatchDebug()

void CPL_DLL CPL_STDCALL 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
bCatchDebugFALSE if the current error handler should not intercept debug messages
Since
GDAL 2.1

◆ CPLSetErrorHandler()

CPLErrorHandler CPL_DLL CPL_STDCALL 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 behaviour (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 behaviour 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
pfnErrorHandlerNewnew error handler function.
Returns
returns the previously installed error handler.

◆ CPLSetErrorHandlerEx()

CPLErrorHandler CPL_DLL CPL_STDCALL 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
pfnErrorHandlerNewnew error handler function.
pUserDataUser data to carry along with the error context.
Returns
returns the previously installed error handler.

◆ CPLTurnFailureIntoWarning()

void CPLTurnFailureIntoWarning ( int  bOn)

Whether failures should be turned into warnings.