GDAL

cpl_error.h
Go to the documentation of this file.
1/**********************************************************************
2 *
3 * Name: cpl_error.h
4 * Project: CPL - Common Portability Library
5 * Purpose: CPL Error handling
6 * Author: Daniel Morissette, danmo@videotron.ca
7 *
8 **********************************************************************
9 * Copyright (c) 1998, Daniel Morissette
10 *
11 * SPDX-License-Identifier: MIT
12 ****************************************************************************/
13
14#ifndef CPL_ERROR_H_INCLUDED
15#define CPL_ERROR_H_INCLUDED
16
17#include "cpl_port.h"
18
19#include <stdarg.h>
20#include <stdbool.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_BucketNotFound,
70 CPLE_ObjectNotFound,
71 CPLE_AccessDenied,
72 CPLE_InvalidCredentials,
73 CPLE_SignatureDoesNotMatch,
74 CPLE_ObjectStorageGenericError,
75} CPLErrorNum;
76
77#else
78
80 typedef int CPLErrorNum;
81
83#define CPLE_None 0
85#define CPLE_AppDefined 1
87#define CPLE_OutOfMemory 2
89#define CPLE_FileIO 3
91#define CPLE_OpenFailed 4
93#define CPLE_IllegalArg 5
95#define CPLE_NotSupported 6
97#define CPLE_AssertionFailed 7
99#define CPLE_NoWriteAccess 8
101#define CPLE_UserInterrupt 9
103#define CPLE_ObjectNull 10
104
105/*
106 * Filesystem-specific errors
107 */
109#define CPLE_HttpResponse 11
111#define CPLE_BucketNotFound 12
113#define CPLE_ObjectNotFound 13
115#define CPLE_AccessDenied 14
117#define CPLE_InvalidCredentials 15
119#define CPLE_SignatureDoesNotMatch 16
121#define CPLE_ObjectStorageGenericError 17
122
123/* 100 - 299 reserved for GDAL */
124
125#endif
126
131#define CPLE_AWSBucketNotFound CPLE_BucketNotFound
132
137#define CPLE_AWSObjectNotFound CPLE_ObjectNotFound
138
143#define CPLE_AWSAccessDenied CPLE_AccessDenied
144
149#define CPLE_AWSInvalidCredentials CPLE_InvalidCredentials
150
155#define CPLE_AWSSignatureDoesNotMatch CPLE_SignatureDoesNotMatch
156
161#define CPLE_AWSError CPLE_ObjectStorageGenericError
162
163 void CPL_DLL CPLError(CPLErr eErrClass, CPLErrorNum err_no,
164 CPL_FORMAT_STRING(const char *fmt), ...)
165 CPL_PRINT_FUNC_FORMAT(3, 4);
166
167#ifdef GDAL_COMPILATION
168
169 const char CPL_DLL *CPLSPrintf(CPL_FORMAT_STRING(const char *fmt), ...)
170 CPL_PRINT_FUNC_FORMAT(1, 2) CPL_WARN_UNUSED_RESULT;
171
177#define CPLErrorOnce(eErrClass, err_no, ...) \
178 do \
179 { \
180 static bool lbCPLErrorOnce = false; \
181 if (!lbCPLErrorOnce) \
182 { \
183 lbCPLErrorOnce = true; \
184 const char *lCPLErrorMsg = CPLSPrintf(__VA_ARGS__); \
185 const size_t lCPLErrorMsgLen = strlen(lCPLErrorMsg); \
186 const char *lCPLErrorMsgSuffix = \
187 " Further messages of this type will be suppressed."; \
188 if (lCPLErrorMsgLen && lCPLErrorMsg[lCPLErrorMsgLen - 1] == '.') \
189 CPLError((eErrClass), (err_no), "%s%s", lCPLErrorMsg, \
190 lCPLErrorMsgSuffix); \
191 else \
192 CPLError((eErrClass), (err_no), "%s.%s", lCPLErrorMsg, \
193 lCPLErrorMsgSuffix); \
194 } \
195 } while (0)
196#endif
197
198 void CPL_DLL CPLErrorV(CPLErr, CPLErrorNum, const char *, va_list);
199 void CPL_DLL CPLEmergencyError(const char *) CPL_NO_RETURN;
200 void CPL_DLL CPL_STDCALL CPLErrorReset(void);
201 CPLErrorNum CPL_DLL CPL_STDCALL CPLGetLastErrorNo(void);
202 CPLErr CPL_DLL CPL_STDCALL CPLGetLastErrorType(void);
203 const char CPL_DLL *CPL_STDCALL CPLGetLastErrorMsg(void);
204 GUInt32 CPL_DLL CPL_STDCALL CPLGetErrorCounter(void);
205 void CPL_DLL *CPL_STDCALL CPLGetErrorHandlerUserData(void);
206 void CPL_DLL CPLErrorSetState(CPLErr eErrClass, CPLErrorNum err_no,
207 const char *pszMsg);
208#if defined(GDAL_COMPILATION) && defined(__cplusplus)
209 extern "C++"
210{
211 void CPL_DLL CPLErrorSetState(CPLErr eErrClass, CPLErrorNum err_no,
212 const char *pszMsg,
213 const GUInt32 *pnErrorCounter);
214}
215#endif
216
217 void CPL_DLL CPLCallPreviousHandler(CPLErr eErrClass, CPLErrorNum err_no,
218 const char *pszMsg);
220 void CPL_DLL CPLCleanupErrorMutex(void);
224 typedef void(CPL_STDCALL *CPLErrorHandler)(CPLErr, CPLErrorNum, const char *);
225
226 void CPL_DLL CPL_STDCALL CPLLoggingErrorHandler(CPLErr, CPLErrorNum,
227 const char *);
228 void CPL_DLL CPL_STDCALL CPLDefaultErrorHandler(CPLErr, CPLErrorNum,
229 const char *);
230 void CPL_DLL CPL_STDCALL CPLQuietErrorHandler(CPLErr, CPLErrorNum,
231 const char *);
232 void CPL_DLL CPL_STDCALL CPLQuietWarningsErrorHandler(CPLErr, CPLErrorNum,
233 const char *);
234 void CPL_DLL CPLTurnFailureIntoWarning(int bOn);
235
236 CPLErrorHandler CPL_DLL CPLGetErrorHandler(void **ppUserData);
237
238 CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandler(CPLErrorHandler);
239 CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandlerEx(CPLErrorHandler,
240 void *);
241 void CPL_DLL CPL_STDCALL CPLPushErrorHandler(CPLErrorHandler);
242 void CPL_DLL CPL_STDCALL CPLPushErrorHandlerEx(CPLErrorHandler, void *);
243 void CPL_DLL CPL_STDCALL CPLSetCurrentErrorHandlerCatchDebug(int bCatchDebug);
244 void CPL_DLL CPL_STDCALL CPLPopErrorHandler(void);
245
246#ifdef WITHOUT_CPLDEBUG
247#define CPLDebug(...) \
248 do \
249 { \
250 } while (0) /* Eat all CPLDebug calls. */
251#define CPLDebugProgress(...) \
252 do \
253 { \
254 } while (0) /* Eat all CPLDebugProgress calls. */
255
256#ifdef GDAL_COMPILATION
262#define CPLDebugOnce(...) \
263 do \
264 { \
265 } while (0)
266#endif
267
268#else
269 void CPL_DLL CPLDebug(const char *, CPL_FORMAT_STRING(const char *), ...)
270 CPL_PRINT_FUNC_FORMAT(2, 3);
271 void CPL_DLL CPLDebugProgress(const char *, CPL_FORMAT_STRING(const char *),
272 ...) CPL_PRINT_FUNC_FORMAT(2, 3);
273
274#ifdef GDAL_COMPILATION
280#define CPLDebugOnce(category, ...) \
281 do \
282 { \
283 static bool lbCPLDebugOnce = false; \
284 if (!lbCPLDebugOnce) \
285 { \
286 lbCPLDebugOnce = true; \
287 const char *lCPLDebugMsg = CPLSPrintf(__VA_ARGS__); \
288 const size_t lCPLErrorMsgLen = strlen(lCPLDebugMsg); \
289 const char *lCPLDebugMsgSuffix = \
290 " Further messages of this type will be suppressed."; \
291 if (lCPLErrorMsgLen && lCPLDebugMsg[lCPLErrorMsgLen - 1] == '.') \
292 CPLDebug((category), "%s%s", lCPLDebugMsg, \
293 lCPLDebugMsgSuffix); \
294 else \
295 CPLDebug((category), "%s.%s", lCPLDebugMsg, \
296 lCPLDebugMsgSuffix); \
297 } \
298 } while (0)
299#endif
300
301#endif
302
303#if defined(DEBUG) || defined(GDAL_DEBUG)
307#define CPLDebugOnly(...) CPLDebug(__VA_ARGS__)
308#else
312#define CPLDebugOnly(...) \
313 do \
314 { \
315 } while (0)
316#endif
317
318 void CPL_DLL CPL_STDCALL _CPLAssert(const char *, const char *,
319 int) CPL_NO_RETURN;
320
321#if defined(DEBUG) && !defined(CPPCHECK)
323#define CPLAssert(expr) \
324 ((expr) ? (void)(0) : _CPLAssert(#expr, __FILE__, __LINE__))
327#define CPLAssertAlwaysEval(expr) CPLAssert(expr)
328#else
330#define CPLAssert(expr) \
331 do \
332 { \
333 } while (0)
334#ifdef __cplusplus
337#define CPLAssertAlwaysEval(expr) CPL_IGNORE_RET_VAL(expr)
338#else
341#define CPLAssertAlwaysEval(expr) (void)(expr)
342#endif
343#endif
344
345 CPL_C_END
346
348/*
349 * Helper macros used for input parameters validation.
350 */
351#ifdef DEBUG
352#define VALIDATE_POINTER_ERR CE_Fatal
353#else
354#define VALIDATE_POINTER_ERR CE_Failure
355#endif
356
359#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
360
361 extern "C++"
362{
364 template <class T> T *CPLAssertNotNull(T *x) CPL_RETURNS_NONNULL;
365
366 template <class T> T *CPLAssertNotNull(T *x)
367 {
368 CPLAssert(x);
369 return x;
370 }
371
372#include <memory>
373#include <string>
374
380 class CPL_DLL CPLErrorHandlerPusher
381 {
382 public:
386 explicit CPLErrorHandlerPusher(CPLErrorHandler hHandler)
387 {
388 CPLPushErrorHandler(hHandler);
389 }
390
394 CPLErrorHandlerPusher(CPLErrorHandler hHandler, void *user_data)
395 {
396 CPLPushErrorHandlerEx(hHandler, user_data);
397 }
398
400 ~CPLErrorHandlerPusher()
401 {
402 CPLPopErrorHandler();
403 }
404 };
405
409 class CPL_DLL CPLErrorStateBackuper
410 {
411 CPLErrorNum m_nLastErrorNum;
412 CPLErr m_nLastErrorType;
413 std::string m_osLastErrorMsg;
414 GUInt32 m_nLastErrorCounter;
415 std::unique_ptr<CPLErrorHandlerPusher> m_poErrorHandlerPusher;
416
417 public:
421 explicit CPLErrorStateBackuper(CPLErrorHandler hHandler = nullptr);
422
426 ~CPLErrorStateBackuper();
427 };
428
432 class CPL_DLL CPLTurnFailureIntoWarningBackuper
433 {
434 public:
435 CPLTurnFailureIntoWarningBackuper()
436 {
437 CPLTurnFailureIntoWarning(true);
438 }
439
440 ~CPLTurnFailureIntoWarningBackuper()
441 {
442 CPLTurnFailureIntoWarning(false);
443 }
444 };
445}
446
447#ifdef GDAL_COMPILATION
449// internal only
450 bool CPLIsDefaultErrorHandlerAndCatchDebug();
452#endif
453
454#endif
455
457#define VALIDATE_POINTER0(ptr, func) \
458 do \
459 { \
460 if (CPL_NULLPTR == ptr) \
461 { \
462 CPLErr const ret = VALIDATE_POINTER_ERR; \
463 CPLError(ret, CPLE_ObjectNull, \
464 "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
465 return; \
466 } \
467 } while (0)
468
470#define VALIDATE_POINTER1(ptr, func, rc) \
471 do \
472 { \
473 if (CPL_NULLPTR == ptr) \
474 { \
475 CPLErr const ret = VALIDATE_POINTER_ERR; \
476 CPLError(ret, CPLE_ObjectNull, \
477 "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
478 return (rc); \
479 } \
480 } while (0)
481
482#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:381
CPLErrorHandlerPusher::CPLErrorHandlerPusher
CPLErrorHandlerPusher(CPLErrorHandler hHandler)
Constructor that installs a thread-local temporary error handler (typically CPLQuietErrorHandler)
Definition cpl_error.h:386
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:394
CPLErrorHandlerPusher::~CPLErrorHandlerPusher
~CPLErrorHandlerPusher()
Destructor that restores the initial error handler.
Definition cpl_error.h:400
CPLErrorStateBackuper
Class that saves the error state on construction, and restores it on destruction.
Definition cpl_error.h:410
CPLTurnFailureIntoWarningBackuper
Class that turns errors into warning on construction, and restores the previous state on destruction.
Definition cpl_error.h:433
CPLQuietWarningsErrorHandler
void CPLQuietWarningsErrorHandler(CPLErr, CPLErrorNum, const char *)
Error handler that ignores CE_Warning messages.
Definition cpl_error.cpp:1117
CPLE_IllegalArg
#define CPLE_IllegalArg
Illegal argument.
Definition cpl_error.h:93
CPLErrorSetState
void CPLErrorSetState(CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)
Restore an error state, without emitting an error.
Definition cpl_error.cpp:884
CPLGetErrorCounter
GUInt32 CPLGetErrorCounter(void)
Get the error counter.
Definition cpl_error.cpp:975
CPLE_AssertionFailed
#define CPLE_AssertionFailed
Assertion failed.
Definition cpl_error.h:97
CPLPushErrorHandlerEx
void CPLPushErrorHandlerEx(CPLErrorHandler, void *)
Push a new CPLError handler with user data on the error context.
Definition cpl_error.cpp:1355
CPLE_None
#define CPLE_None
No error.
Definition cpl_error.h:83
CPLE_ObjectNotFound
#define CPLE_ObjectNotFound
VSIE_ObjectNotFound.
Definition cpl_error.h:113
CPLErrorReset
void CPLErrorReset(void)
Erase any traces of previous errors.
Definition cpl_error.cpp:809
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:1133
CPLE_NotSupported
#define CPLE_NotSupported
Not supported.
Definition cpl_error.h:95
CPLAssert
#define CPLAssert(expr)
Assert on an expression.
Definition cpl_error.h:330
CPLErr
CPLErr
Error category.
Definition cpl_error.h:37
CPLE_FileIO
#define CPLE_FileIO
File I/O error.
Definition cpl_error.h:89
CPLGetLastErrorNo
CPLErrorNum CPLGetLastErrorNo(void)
Fetch the last error number.
Definition cpl_error.cpp:905
CPLDebugProgress
void CPLDebugProgress(const char *, const char *,...)
Display a debugging message indicating a progression.
Definition cpl_error.cpp:779
CPLE_AppDefined
#define CPLE_AppDefined
Application defined error.
Definition cpl_error.h:85
CPLE_OpenFailed
#define CPLE_OpenFailed
Open failed.
Definition cpl_error.h:91
CPLGetLastErrorMsg
const char * CPLGetLastErrorMsg(void)
Get the last error message.
Definition cpl_error.cpp:953
CPLGetErrorHandler
CPLErrorHandler CPLGetErrorHandler(void **ppUserData)
Fetch the current error handler for the current error context.
Definition cpl_error.cpp:175
CPLSetErrorHandler
CPLErrorHandler CPLSetErrorHandler(CPLErrorHandler)
Install custom error handler.
Definition cpl_error.cpp:1311
CPLE_AccessDenied
#define CPLE_AccessDenied
VSIE_AccessDenied.
Definition cpl_error.h:115
CPLE_ObjectNull
#define CPLE_ObjectNull
NULL object.
Definition cpl_error.h:103
CPLDefaultErrorHandler
void CPLDefaultErrorHandler(CPLErr, CPLErrorNum, const char *)
Default error handler.
Definition cpl_error.cpp:1009
CPLGetLastErrorType
CPLErr CPLGetLastErrorType(void)
Fetch the last error type.
Definition cpl_error.cpp:929
CPLErrorNum
int CPLErrorNum
Error number.
Definition cpl_error.h:80
CPLGetErrorHandlerUserData
void * CPLGetErrorHandlerUserData(void)
Fetch the user data for the error context.
Definition cpl_error.cpp:147
CPLErrorHandler
void(* CPLErrorHandler)(CPLErr, CPLErrorNum, const char *)
Callback for a custom error handler.
Definition cpl_error.h:224
CPLTurnFailureIntoWarning
void CPLTurnFailureIntoWarning(int bOn)
Whether failures should be turned into warnings.
Definition cpl_error.cpp:1206
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:1422
CPLE_InvalidCredentials
#define CPLE_InvalidCredentials
VSIE_InvalidCredentials.
Definition cpl_error.h:117
CPLEmergencyError
void CPLEmergencyError(const char *)
Fatal error when things are bad.
Definition cpl_error.cpp:490
CPLE_SignatureDoesNotMatch
#define CPLE_SignatureDoesNotMatch
VSIE_SignatureDoesNotMatch.
Definition cpl_error.h:119
_CPLAssert
void _CPLAssert(const char *, const char *, int)
Report failure of a logical assertion.
Definition cpl_error.cpp:1510
CPLE_HttpResponse
#define CPLE_HttpResponse
HTTP response.
Definition cpl_error.h:109
CPLPopErrorHandler
void CPLPopErrorHandler(void)
Pop error handler off stack.
Definition cpl_error.cpp:1389
CPLE_BucketNotFound
#define CPLE_BucketNotFound
VSIE_BucketNotFound.
Definition cpl_error.h:111
CPLDebug
void CPLDebug(const char *, const char *,...)
Display a debugging message.
Definition cpl_error.cpp:734
CPLPushErrorHandler
void CPLPushErrorHandler(CPLErrorHandler)
Push a new CPLError handler.
Definition cpl_error.cpp:1332
CPLE_NoWriteAccess
#define CPLE_NoWriteAccess
No write access.
Definition cpl_error.h:99
CPLE_ObjectStorageGenericError
#define CPLE_ObjectStorageGenericError
VSIE_ObjectStorageGenericError.
Definition cpl_error.h:121
CPLE_UserInterrupt
#define CPLE_UserInterrupt
User interrupted.
Definition cpl_error.h:101
CPLErrorV
void CPLErrorV(CPLErr, CPLErrorNum, const char *, va_list)
Same as CPLError() but with a va_list.
Definition cpl_error.cpp:326
CPLQuietErrorHandler
void CPLQuietErrorHandler(CPLErr, CPLErrorNum, const char *)
Error handler that does not do anything, except for debug messages.
Definition cpl_error.cpp:1104
CPLE_OutOfMemory
#define CPLE_OutOfMemory
Out of memory error.
Definition cpl_error.h:87
CPLSetErrorHandlerEx
CPLErrorHandler CPLSetErrorHandlerEx(CPLErrorHandler, void *)
Install custom error handle with user's data.
Definition cpl_error.cpp:1238
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:1476
CPLError
void CPLError(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,...)
Report an error.
Definition cpl_error.cpp:310
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:889
CPL_C_END
#define CPL_C_END
Macro to end a block of C symbols.
Definition cpl_port.h:289
CPL_C_START
#define CPL_C_START
Macro to start a block of C symbols.
Definition cpl_port.h:285
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:860
CPL_RETURNS_NONNULL
#define CPL_RETURNS_NONNULL
Qualifier for a function that does not return NULL.
Definition cpl_port.h:908
GUInt32
unsigned int GUInt32
Unsigned int32 type.
Definition cpl_port.h:167
CPL_PRINT_FUNC_FORMAT
#define CPL_PRINT_FUNC_FORMAT(format_idx, arg_idx)
Tag a function to have printf() formatting.
Definition cpl_port.h:844
CPL_WARN_UNUSED_RESULT
#define CPL_WARN_UNUSED_RESULT
Qualifier to warn when the return value of a function is not used.
Definition cpl_port.h:870