GDAL

Classes | Macros | Typedefs | Enumerations | Functions
cpl_error.h File Reference

CPL error handling services. More...

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

Go to the source code of this file.

## 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...
class | CPLTurnFailureIntoWarningBackuper
| Class that turns errors into warning on construction, and restores the previous state 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_BucketNotFound 12
| VSIE_BucketNotFound.
#define | CPLE_ObjectNotFound 13
| VSIE_ObjectNotFound.
#define | CPLE_AccessDenied 14
| VSIE_AccessDenied.
#define | CPLE_InvalidCredentials 15
| VSIE_InvalidCredentials.
#define | CPLE_SignatureDoesNotMatch 16
| VSIE_SignatureDoesNotMatch.
#define | CPLE_ObjectStorageGenericError 17
| VSIE_ObjectStorageGenericError.
#define | CPLE_AWSBucketNotFound CPLE_BucketNotFound
| Deprecated alias for CPLE_BucketNotFound.
#define | CPLE_AWSObjectNotFound CPLE_ObjectNotFound
| Deprecated alias for CPLE_ObjectNotFound.
#define | CPLE_AWSAccessDenied CPLE_AccessDenied
| Deprecated alias for CPLE_AccessDenied.
#define | CPLE_AWSInvalidCredentials CPLE_InvalidCredentials
| Deprecated alias for CPLE_AWSInvalidCredentials.
#define | CPLE_AWSSignatureDoesNotMatch CPLE_SignatureDoesNotMatch
| Deprecated alias for CPLE_SignatureDoesNotMatch.
#define | CPLE_AWSError CPLE_ObjectStorageGenericError
| Deprecated alias for CPLE_ObjectStorageGenericError.
#define | CPLDebugOnly(...)
| Same as CPLDebug(), but expands to nothing for non-DEBUG builds.
#define | CPLAssert(expr)
| Assert on an expression.
#define | CPLAssertAlwaysEval(expr) CPL_IGNORE_RET_VAL(expr)
| Assert on an expression in DEBUG mode.
#define | VALIDATE_POINTER0(ptr, func)
| Validate that a pointer is not NULL.
#define | VALIDATE_POINTER1(ptr, func, rc)
| Validate that a pointer is not NULL, and return rc if it is NULL.

## 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.
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.
void | CPLErrorReset (void)
| Erase any traces of previous errors.
CPLErrorNum | CPLGetLastErrorNo (void)
| Fetch the last error number.
CPLErr | CPLGetLastErrorType (void)
| Fetch the last error type.
const char * | CPLGetLastErrorMsg (void)
| Get the last error message.
GUInt32 | CPLGetErrorCounter (void)
| Get the error counter.
void * | CPLGetErrorHandlerUserData (void)
| Fetch the user data for the error context.
void | CPLErrorSetState (CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)
| Restore an error state, without emitting an error.
void | CPLCallPreviousHandler (CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)
| Call the previously installed error handler in the error handler stack.
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 | CPLQuietWarningsErrorHandler (CPLErr, CPLErrorNum, const char *)
| Error handler that ignores CE_Warning 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.
CPLErrorHandler | CPLSetErrorHandler (CPLErrorHandler)
| Install custom error handler.
CPLErrorHandler | CPLSetErrorHandlerEx (CPLErrorHandler, void *)
| Install custom error handle with user's data.
void | CPLPushErrorHandler (CPLErrorHandler)
| Push a new CPLError handler.
void | CPLPushErrorHandlerEx (CPLErrorHandler, void *)
| Push a new CPLError handler with user data on the error context.
void | CPLSetCurrentErrorHandlerCatchDebug (int bCatchDebug)
| Set if the current error handler should intercept debug messages, or if they should be processed by the previous handler.
void | CPLPopErrorHandler (void)
| Pop error handler off stack.
void | CPLDebug (const char *, const char *,...)
| Display a debugging message.
void | CPLDebugProgress (const char *, const char *,...)
| Display a debugging message indicating a progression.
void | _CPLAssert (const char *, const char *, int)
| Report failure of a logical assertion.

## Detailed Description

CPL error handling services.

## Macro Definition Documentation

## ◆ CPLAssert

#define CPLAssert | ( |  | expr | ) |

Value:
do \
{ \
} while (0)

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 | ( |  | ... | ) |

Value:
do \
{ \
} while (0)

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

Since
  GDAL 3.1

## ◆ CPLE_AWSAccessDenied

#define CPLE_AWSAccessDenied CPLE_AccessDenied

Deprecated alias for CPLE_AccessDenied.

Deprecated:
  since 3.12

## ◆ CPLE_AWSBucketNotFound

#define CPLE_AWSBucketNotFound CPLE_BucketNotFound

Deprecated alias for CPLE_BucketNotFound.

Deprecated:
  since 3.12

## ◆ CPLE_AWSError

#define CPLE_AWSError CPLE_ObjectStorageGenericError

Deprecated alias for CPLE_ObjectStorageGenericError.

Deprecated:
  since 3.12

## ◆ CPLE_AWSInvalidCredentials

#define CPLE_AWSInvalidCredentials CPLE_InvalidCredentials

Deprecated alias for CPLE_AWSInvalidCredentials.

Deprecated:
  since 3.12

## ◆ CPLE_AWSObjectNotFound

#define CPLE_AWSObjectNotFound CPLE_ObjectNotFound

Deprecated alias for CPLE_ObjectNotFound.

Deprecated:
  since 3.12

## ◆ CPLE_AWSSignatureDoesNotMatch

#define CPLE_AWSSignatureDoesNotMatch CPLE_SignatureDoesNotMatch

Deprecated alias for CPLE_SignatureDoesNotMatch.

Deprecated:
  since 3.12

## ◆ 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)
CPLErr
CPLErr
Error category.
Definition cpl_error.h:37
CPLE_ObjectNull
#define CPLE_ObjectNull
NULL object.
Definition cpl_error.h:103

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.

## ◆ 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.

## ◆ 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

## ◆ 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.