GDAL

cpl_error.h
Go to the documentation of this file.
1/**********************************************************************
2 * $Id$
3 *
4 * Name: cpl_error.h
5 * Project: CPL - Common Portability Library
6 * Purpose: CPL Error handling
7 * Author: Daniel Morissette, danmo@videotron.ca
8 *
9 **********************************************************************
10 * Copyright (c) 1998, Daniel Morissette
11 *
12 * SPDX-License-Identifier: MIT
13 ****************************************************************************/
14
15#ifndef CPL_ERROR_H_INCLUDED
16#define CPL_ERROR_H_INCLUDED
17
18#include "cpl_port.h"
19
20#include <stdarg.h>
21#include <stddef.h>
22
23/*=====================================================================
24 Error handling functions (cpl_error.c)
25 =====================================================================*/
26
33 CPL_C_START
34
36 typedef enum
37{
38 CE_None = 0,
39 CE_Debug = 1,
40 CE_Warning = 2,
41 CE_Failure = 3,
42 CE_Fatal = 4
43} CPLErr;
44
45/* ==================================================================== */
46/* Well known error codes. */
47/* ==================================================================== */
48
49#ifdef STRICT_CPLERRORNUM_TYPE
50
51/* This is not appropriate for the general case, as there are parts */
52/* of GDAL which use custom error codes, but this can help diagnose confusions
53 */
54/* between CPLErr and CPLErrorNum */
55 typedef enum
56{
57 CPLE_None,
58 CPLE_AppDefined,
59 CPLE_OutOfMemory,
60 CPLE_FileIO,
61 CPLE_OpenFailed,
62 CPLE_IllegalArg,
63 CPLE_NotSupported,
64 CPLE_AssertionFailed,
65 CPLE_NoWriteAccess,
66 CPLE_UserInterrupt,
67 CPLE_ObjectNull,
68 CPLE_HttpResponse,
69 CPLE_AWSBucketNotFound,
70 CPLE_AWSObjectNotFound,
71 CPLE_AWSAccessDenied,
72 CPLE_AWSInvalidCredentials,
73 CPLE_AWSSignatureDoesNotMatch,
74} CPLErrorNum;
75
76#else
77
79 typedef int CPLErrorNum;
80
82#define CPLE_None 0
84#define CPLE_AppDefined 1
86#define CPLE_OutOfMemory 2
88#define CPLE_FileIO 3
90#define CPLE_OpenFailed 4
92#define CPLE_IllegalArg 5
94#define CPLE_NotSupported 6
96#define CPLE_AssertionFailed 7
98#define CPLE_NoWriteAccess 8
100#define CPLE_UserInterrupt 9
102#define CPLE_ObjectNull 10
103
104/*
105 * Filesystem-specific errors
106 */
108#define CPLE_HttpResponse 11
110#define CPLE_AWSBucketNotFound 12
112#define CPLE_AWSObjectNotFound 13
114#define CPLE_AWSAccessDenied 14
116#define CPLE_AWSInvalidCredentials 15
118#define CPLE_AWSSignatureDoesNotMatch 16
120#define CPLE_AWSError 17
121
122/* 100 - 299 reserved for GDAL */
123
124#endif
125
126 void CPL_DLL CPLError(CPLErr eErrClass, CPLErrorNum err_no,
127 CPL_FORMAT_STRING(const char *fmt), ...)
128 CPL_PRINT_FUNC_FORMAT(3, 4);
129 void CPL_DLL CPLErrorV(CPLErr, CPLErrorNum, const char *, va_list);
130 void CPL_DLL CPLEmergencyError(const char *) CPL_NO_RETURN;
131 void CPL_DLL CPL_STDCALL CPLErrorReset(void);
132 CPLErrorNum CPL_DLL CPL_STDCALL CPLGetLastErrorNo(void);
133 CPLErr CPL_DLL CPL_STDCALL CPLGetLastErrorType(void);
134const char CPL_DLL *CPL_STDCALL CPLGetLastErrorMsg(void);
135 GUInt32 CPL_DLL CPL_STDCALL CPLGetErrorCounter(void);
136 void CPL_DLL *CPL_STDCALL CPLGetErrorHandlerUserData(void);
137 void CPL_DLL CPLErrorSetState(CPLErr eErrClass, CPLErrorNum err_no,
138 const char *pszMsg);
139 void CPL_DLL CPLCallPreviousHandler(CPLErr eErrClass, CPLErrorNum err_no,
140 const char *pszMsg);
142 void CPL_DLL CPLCleanupErrorMutex(void);
146typedef void(CPL_STDCALL *CPLErrorHandler)(CPLErr, CPLErrorNum, const char *);
147
148 void CPL_DLL CPL_STDCALL CPLLoggingErrorHandler(CPLErr, CPLErrorNum,
149 const char *);
150 void CPL_DLL CPL_STDCALL CPLDefaultErrorHandler(CPLErr, CPLErrorNum,
151 const char *);
152 void CPL_DLL CPL_STDCALL CPLQuietErrorHandler(CPLErr, CPLErrorNum,
153 const char *);
154 void CPL_DLL CPLTurnFailureIntoWarning(int bOn);
155
156 CPLErrorHandler CPL_DLL CPLGetErrorHandler(void **ppUserData);
157
158 CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandler(CPLErrorHandler);
159 CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandlerEx(CPLErrorHandler,
160 void *);
161 void CPL_DLL CPL_STDCALL CPLPushErrorHandler(CPLErrorHandler);
162 void CPL_DLL CPL_STDCALL CPLPushErrorHandlerEx(CPLErrorHandler, void *);
163 void CPL_DLL CPL_STDCALL CPLSetCurrentErrorHandlerCatchDebug(int bCatchDebug);
164 void CPL_DLL CPL_STDCALL CPLPopErrorHandler(void);
165
166#ifdef WITHOUT_CPLDEBUG
167#define CPLDebug(...) \
168 do \
169 { \
170 } while (0) /* Eat all CPLDebug calls. */
171#define CPLDebugProgress(...) \
172 do \
173 { \
174 } while (0) /* Eat all CPLDebugProgress calls. */
175#else
176 void CPL_DLL CPLDebug(const char *, CPL_FORMAT_STRING(const char *), ...)
177 CPL_PRINT_FUNC_FORMAT(2, 3);
178 void CPL_DLL CPLDebugProgress(const char *, CPL_FORMAT_STRING(const char *),
179 ...) CPL_PRINT_FUNC_FORMAT(2, 3);
180#endif
181
182#ifdef DEBUG
186#define CPLDebugOnly(...) CPLDebug(__VA_ARGS__)
187#else
191#define CPLDebugOnly(...) \
192 do \
193 { \
194 } while (0)
195#endif
196
197 void CPL_DLL CPL_STDCALL _CPLAssert(const char *, const char *,
198 int) CPL_NO_RETURN;
199
200#if defined(DEBUG) && !defined(CPPCHECK)
202#define CPLAssert(expr) \
203 ((expr) ? (void)(0) : _CPLAssert(#expr, __FILE__, __LINE__))
206#define CPLAssertAlwaysEval(expr) CPLAssert(expr)
207#else
209#define CPLAssert(expr) \
210 do \
211 { \
212 } while (0)
213#ifdef __cplusplus
216#define CPLAssertAlwaysEval(expr) CPL_IGNORE_RET_VAL(expr)
217#else
220#define CPLAssertAlwaysEval(expr) (void)(expr)
221#endif
222#endif
223
224 CPL_C_END
225
227/*
228 * Helper macros used for input parameters validation.
229 */
230#ifdef DEBUG
231#define VALIDATE_POINTER_ERR CE_Fatal
232#else
233#define VALIDATE_POINTER_ERR CE_Failure
234#endif
235
238#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
239
240 extern "C++"
241{
243 template <class T> T *CPLAssertNotNull(T *x) CPL_RETURNS_NONNULL;
244
245 template <class T> T *CPLAssertNotNull(T *x)
246 {
247 CPLAssert(x);
248 return x;
249 }
250
251#include <memory>
252#include <string>
253
259 class CPL_DLL CPLErrorHandlerPusher
260 {
261 public:
265 explicit CPLErrorHandlerPusher(CPLErrorHandler hHandler)
266 {
267 CPLPushErrorHandler(hHandler);
268 }
269
273 CPLErrorHandlerPusher(CPLErrorHandler hHandler, void *user_data)
274 {
275 CPLPushErrorHandlerEx(hHandler, user_data);
276 }
277
279 ~CPLErrorHandlerPusher()
280 {
281 CPLPopErrorHandler();
282 }
283 };
284
288 class CPL_DLL CPLErrorStateBackuper
289 {
290 CPLErrorNum m_nLastErrorNum;
291 CPLErr m_nLastErrorType;
292 std::string m_osLastErrorMsg;
293 GUInt32 m_nLastErrorCounter;
294 std::unique_ptr<CPLErrorHandlerPusher> m_poErrorHandlerPusher;
295
296 public:
300 explicit CPLErrorStateBackuper(CPLErrorHandler hHandler = nullptr);
301
305 ~CPLErrorStateBackuper();
306 };
307}
308
309#ifdef GDAL_COMPILATION
311// internal only
312 bool CPLIsDefaultErrorHandlerAndCatchDebug();
314#endif
315
316#endif
317
319#define VALIDATE_POINTER0(ptr, func) \
320 do \
321 { \
322 if (CPL_NULLPTR == ptr) \
323 { \
324 CPLErr const ret = VALIDATE_POINTER_ERR; \
325 CPLError(ret, CPLE_ObjectNull, \
326 "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
327 return; \
328 } \
329 } while (0)
330
332#define VALIDATE_POINTER1(ptr, func, rc) \
333 do \
334 { \
335 if (CPL_NULLPTR == ptr) \
336 { \
337 CPLErr const ret = VALIDATE_POINTER_ERR; \
338 CPLError(ret, CPLE_ObjectNull, \
339 "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
340 return (rc); \
341 } \
342 } while (0)
343
344#endif /* CPL_ERROR_H_INCLUDED */
CPLErrorHandlerPusher
Class that installs a (thread-local) error handler on construction, and restore the initial one on de...
Definition cpl_error.h:260
CPLErrorHandlerPusher::CPLErrorHandlerPusher
CPLErrorHandlerPusher(CPLErrorHandler hHandler)
Constructor that installs a thread-local temporary error handler (typically CPLQuietErrorHandler)
Definition cpl_error.h:265
CPLErrorHandlerPusher::CPLErrorHandlerPusher
CPLErrorHandlerPusher(CPLErrorHandler hHandler, void *user_data)
Constructor that installs a thread-local temporary error handler, and its user data.
Definition cpl_error.h:273
CPLErrorHandlerPusher::~CPLErrorHandlerPusher
~CPLErrorHandlerPusher()
Destructor that restores the initial error handler.
Definition cpl_error.h:279
CPLErrorStateBackuper
Class that saves the error state on construction, and restores it on destruction.
Definition cpl_error.h:289
CPLE_IllegalArg
#define CPLE_IllegalArg
Illegal argument.
Definition cpl_error.h:92
CPLErrorSetState
void CPLErrorSetState(CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)
Restore an error state, without emitting an error.
Definition cpl_error.cpp:889
CPLGetErrorCounter
GUInt32 CPLGetErrorCounter(void)
Get the error counter.
Definition cpl_error.cpp:981
CPLE_AWSObjectNotFound
#define CPLE_AWSObjectNotFound
AWSObjectNotFound.
Definition cpl_error.h:112
CPLE_AssertionFailed
#define CPLE_AssertionFailed
Assertion failed.
Definition cpl_error.h:96
CPLPushErrorHandlerEx
void CPLPushErrorHandlerEx(CPLErrorHandler, void *)
Push a new CPLError handler with user data on the error context.
Definition cpl_error.cpp:1347
CPLE_AWSSignatureDoesNotMatch
#define CPLE_AWSSignatureDoesNotMatch
AWSSignatureDoesNotMatch.
Definition cpl_error.h:118
CPLE_None
#define CPLE_None
No error.
Definition cpl_error.h:82
CPLErrorReset
void CPLErrorReset(void)
Erase any traces of previous errors.
Definition cpl_error.cpp:813
CPLLoggingErrorHandler
void CPLLoggingErrorHandler(CPLErr, CPLErrorNum, const char *)
Error handler that logs into the file defined by the CPL_LOG configuration option,...
Definition cpl_error.cpp:1125
CPLE_NotSupported
#define CPLE_NotSupported
Not supported.
Definition cpl_error.h:94
CPLE_AWSInvalidCredentials
#define CPLE_AWSInvalidCredentials
AWSInvalidCredentials.
Definition cpl_error.h:116
CPLAssert
#define CPLAssert(expr)
Assert on an expression.
Definition cpl_error.h:209
CPLErr
CPLErr
Error category.
Definition cpl_error.h:37
CPLE_FileIO
#define CPLE_FileIO
File I/O error.
Definition cpl_error.h:88
CPLGetLastErrorNo
CPLErrorNum CPLGetLastErrorNo(void)
Fetch the last error number.
Definition cpl_error.cpp:910
CPLDebugProgress
void CPLDebugProgress(const char *, const char *,...)
Display a debugging message indicating a progression.
Definition cpl_error.cpp:783
CPLE_AppDefined
#define CPLE_AppDefined
Application defined error.
Definition cpl_error.h:84
CPLE_OpenFailed
#define CPLE_OpenFailed
Open failed.
Definition cpl_error.h:90
CPLGetLastErrorMsg
const char * CPLGetLastErrorMsg(void)
Get the last error message.
Definition cpl_error.cpp:958
CPLGetErrorHandler
CPLErrorHandler CPLGetErrorHandler(void **ppUserData)
Fetch the current error handler for the current error context.
Definition cpl_error.cpp:179
CPLSetErrorHandler
CPLErrorHandler CPLSetErrorHandler(CPLErrorHandler)
Install custom error handler.
Definition cpl_error.cpp:1303
CPLE_AWSAccessDenied
#define CPLE_AWSAccessDenied
AWSAccessDenied.
Definition cpl_error.h:114
CPLE_ObjectNull
#define CPLE_ObjectNull
NULL object.
Definition cpl_error.h:102
CPLDefaultErrorHandler
void CPLDefaultErrorHandler(CPLErr, CPLErrorNum, const char *)
Default error handler.
Definition cpl_error.cpp:1015
CPLGetLastErrorType
CPLErr CPLGetLastErrorType(void)
Fetch the last error type.
Definition cpl_error.cpp:934
CPLErrorNum
int CPLErrorNum
Error number.
Definition cpl_error.h:79
CPLGetErrorHandlerUserData
void * CPLGetErrorHandlerUserData(void)
Fetch the user data for the error context.
Definition cpl_error.cpp:151
CPLErrorHandler
void(* CPLErrorHandler)(CPLErr, CPLErrorNum, const char *)
Callback for a custom error handler.
Definition cpl_error.h:146
CPLTurnFailureIntoWarning
void CPLTurnFailureIntoWarning(int bOn)
Whether failures should be turned into warnings.
Definition cpl_error.cpp:1198
CPLCallPreviousHandler
void CPLCallPreviousHandler(CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)
Call the previously installed error handler in the error handler stack.
Definition cpl_error.cpp:1414
CPLEmergencyError
void CPLEmergencyError(const char *)
Fatal error when things are bad.
Definition cpl_error.cpp:494
_CPLAssert
void _CPLAssert(const char *, const char *, int)
Report failure of a logical assertion.
Definition cpl_error.cpp:1503
CPLE_HttpResponse
#define CPLE_HttpResponse
HTTP response.
Definition cpl_error.h:108
CPLE_AWSBucketNotFound
#define CPLE_AWSBucketNotFound
AWSBucketNotFound.
Definition cpl_error.h:110
CPLPopErrorHandler
void CPLPopErrorHandler(void)
Pop error handler off stack.
Definition cpl_error.cpp:1381
CPLDebug
void CPLDebug(const char *, const char *,...)
Display a debugging message.
Definition cpl_error.cpp:738
CPLPushErrorHandler
void CPLPushErrorHandler(CPLErrorHandler)
Push a new CPLError handler.
Definition cpl_error.cpp:1324
CPLE_NoWriteAccess
#define CPLE_NoWriteAccess
No write access.
Definition cpl_error.h:98
CPLE_UserInterrupt
#define CPLE_UserInterrupt
User interrupted.
Definition cpl_error.h:100
CPLErrorV
void CPLErrorV(CPLErr, CPLErrorNum, const char *, va_list)
Same as CPLError() but with a va_list.
Definition cpl_error.cpp:330
CPLQuietErrorHandler
void CPLQuietErrorHandler(CPLErr, CPLErrorNum, const char *)
Error handler that does not do anything, except for debug messages.
Definition cpl_error.cpp:1110
CPLE_OutOfMemory
#define CPLE_OutOfMemory
Out of memory error.
Definition cpl_error.h:86
CPLSetErrorHandlerEx
CPLErrorHandler CPLSetErrorHandlerEx(CPLErrorHandler, void *)
Install custom error handle with user's data.
Definition cpl_error.cpp:1230
CPLSetCurrentErrorHandlerCatchDebug
void CPLSetCurrentErrorHandlerCatchDebug(int bCatchDebug)
Set if the current error handler should intercept debug messages, or if they should be processed by t...
Definition cpl_error.cpp:1469
CPLError
void CPLError(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,...)
Report an error.
Definition cpl_error.cpp:314
cpl_port.h
Core portability definitions for CPL.
CPL_NO_RETURN
#define CPL_NO_RETURN
Qualifier for a function that does not return at all (terminates the process)
Definition cpl_port.h:983
CPL_C_END
#define CPL_C_END
Macro to end a block of C symbols.
Definition cpl_port.h:283
CPL_C_START
#define CPL_C_START
Macro to start a block of C symbols.
Definition cpl_port.h:279
CPL_FORMAT_STRING
#define CPL_FORMAT_STRING(arg)
Macro into which to wrap the format argument of a printf-like function.
Definition cpl_port.h:954
CPL_RETURNS_NONNULL
#define CPL_RETURNS_NONNULL
Qualifier for a function that does not return NULL.
Definition cpl_port.h:1002
GUInt32
unsigned int GUInt32
Unsigned int32 type.
Definition cpl_port.h:161
CPL_PRINT_FUNC_FORMAT
#define CPL_PRINT_FUNC_FORMAT(format_idx, arg_idx)
Tag a function to have printf() formatting.
Definition cpl_port.h:938