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 * Permission is hereby granted, free of charge, to any person obtaining a
13 * copy of this software and associated documentation files (the "Software"),
14 * to deal in the Software without restriction, including without limitation
15 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 * and/or sell copies of the Software, and to permit persons to whom the
17 * Software is furnished to do so, subject to the following conditions:
18 *
19 * The above copyright notice and this permission notice shall be included
20 * in all copies or substantial portions of the Software.
21 *
22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
25 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
28 * DEALINGS IN THE SOFTWARE.
29 ****************************************************************************/
30
31#ifndef CPL_ERROR_H_INCLUDED
32#define CPL_ERROR_H_INCLUDED
33
34#include "cpl_port.h"
35
36#include <stdarg.h>
37#include <stddef.h>
38
39/*=====================================================================
40 Error handling functions (cpl_error.c)
41 =====================================================================*/
42
49 CPL_C_START
50
52 typedef enum
53{
54 CE_None = 0,
55 CE_Debug = 1,
56 CE_Warning = 2,
57 CE_Failure = 3,
58 CE_Fatal = 4
59} CPLErr;
60
61/* ==================================================================== */
62/* Well known error codes. */
63/* ==================================================================== */
64
65#ifdef STRICT_CPLERRORNUM_TYPE
66
67/* This is not appropriate for the general case, as there are parts */
68/* of GDAL which use custom error codes, but this can help diagnose confusions
69 */
70/* between CPLErr and CPLErrorNum */
71typedef enum
72{
73 CPLE_None,
74 CPLE_AppDefined,
75 CPLE_OutOfMemory,
76 CPLE_FileIO,
77 CPLE_OpenFailed,
78 CPLE_IllegalArg,
79 CPLE_NotSupported,
80 CPLE_AssertionFailed,
81 CPLE_NoWriteAccess,
82 CPLE_UserInterrupt,
83 CPLE_ObjectNull,
84 CPLE_HttpResponse,
85 CPLE_AWSBucketNotFound,
86 CPLE_AWSObjectNotFound,
87 CPLE_AWSAccessDenied,
88 CPLE_AWSInvalidCredentials,
89 CPLE_AWSSignatureDoesNotMatch,
90} CPLErrorNum;
91
92#else
93
95 typedef int CPLErrorNum;
96
98#define CPLE_None 0
100#define CPLE_AppDefined 1
102#define CPLE_OutOfMemory 2
104#define CPLE_FileIO 3
106#define CPLE_OpenFailed 4
108#define CPLE_IllegalArg 5
110#define CPLE_NotSupported 6
112#define CPLE_AssertionFailed 7
114#define CPLE_NoWriteAccess 8
116#define CPLE_UserInterrupt 9
118#define CPLE_ObjectNull 10
119
120/*
121 * Filesystem-specific errors
122 */
124#define CPLE_HttpResponse 11
126#define CPLE_AWSBucketNotFound 12
128#define CPLE_AWSObjectNotFound 13
130#define CPLE_AWSAccessDenied 14
132#define CPLE_AWSInvalidCredentials 15
134#define CPLE_AWSSignatureDoesNotMatch 16
136#define CPLE_AWSError 17
137
138/* 100 - 299 reserved for GDAL */
139
140#endif
141
142void CPL_DLL CPLError(CPLErr eErrClass, CPLErrorNum err_no,
143 CPL_FORMAT_STRING(const char *fmt), ...)
144 CPL_PRINT_FUNC_FORMAT(3, 4);
145void CPL_DLL CPLErrorV(CPLErr, CPLErrorNum, const char *, va_list);
146void CPL_DLL CPLEmergencyError(const char *) CPL_NO_RETURN;
147void CPL_DLL CPL_STDCALL CPLErrorReset(void);
148 CPLErrorNum CPL_DLL CPL_STDCALL CPLGetLastErrorNo(void);
149 CPLErr CPL_DLL CPL_STDCALL CPLGetLastErrorType(void);
150const char CPL_DLL *CPL_STDCALL CPLGetLastErrorMsg(void);
151 GUInt32 CPL_DLL CPL_STDCALL CPLGetErrorCounter(void);
152void CPL_DLL *CPL_STDCALL CPLGetErrorHandlerUserData(void);
153void CPL_DLL CPLErrorSetState(CPLErr eErrClass, CPLErrorNum err_no,
154 const char *pszMsg);
155void CPL_DLL CPLCallPreviousHandler(CPLErr eErrClass, CPLErrorNum err_no,
156 const char *pszMsg);
158void CPL_DLL CPLCleanupErrorMutex(void);
162typedef void(CPL_STDCALL *CPLErrorHandler)(CPLErr, CPLErrorNum, const char *);
163
164void CPL_DLL CPL_STDCALL CPLLoggingErrorHandler(CPLErr, CPLErrorNum,
165 const char *);
166void CPL_DLL CPL_STDCALL CPLDefaultErrorHandler(CPLErr, CPLErrorNum,
167 const char *);
168void CPL_DLL CPL_STDCALL CPLQuietErrorHandler(CPLErr, CPLErrorNum,
169 const char *);
170void CPLTurnFailureIntoWarning(int bOn);
171
172 CPLErrorHandler CPL_DLL CPLGetErrorHandler(void **ppUserData);
173
174 CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandler(CPLErrorHandler);
175 CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandlerEx(CPLErrorHandler,
176 void *);
177void CPL_DLL CPL_STDCALL CPLPushErrorHandler(CPLErrorHandler);
178void CPL_DLL CPL_STDCALL CPLPushErrorHandlerEx(CPLErrorHandler, void *);
179void CPL_DLL CPL_STDCALL CPLSetCurrentErrorHandlerCatchDebug(int bCatchDebug);
180void CPL_DLL CPL_STDCALL CPLPopErrorHandler(void);
181
182#ifdef WITHOUT_CPLDEBUG
183#define CPLDebug(...) /* Eat all CPLDebug calls. */
184#define CPLDebugProgress(...) /* Eat all CPLDebugProgress calls. */
185#else
186void CPL_DLL CPLDebug(const char *, CPL_FORMAT_STRING(const char *), ...)
187 CPL_PRINT_FUNC_FORMAT(2, 3);
188void CPL_DLL CPLDebugProgress(const char *, CPL_FORMAT_STRING(const char *),
189 ...) CPL_PRINT_FUNC_FORMAT(2, 3);
190#endif
191
192#ifdef DEBUG
196#define CPLDebugOnly(...) CPLDebug(__VA_ARGS__)
197#else
201#define CPLDebugOnly(...)
202#endif
203
204void CPL_DLL CPL_STDCALL _CPLAssert(const char *, const char *,
205 int) CPL_NO_RETURN;
206
207#if defined(DEBUG) && !defined(CPPCHECK)
209#define CPLAssert(expr) \
210 ((expr) ? (void)(0) : _CPLAssert(#expr, __FILE__, __LINE__))
213#define CPLAssertAlwaysEval(expr) CPLAssert(expr)
214#else
216#define CPLAssert(expr)
217#ifdef __cplusplus
220#define CPLAssertAlwaysEval(expr) CPL_IGNORE_RET_VAL(expr)
221#else
224#define CPLAssertAlwaysEval(expr) (void)(expr)
225#endif
226#endif
227
228 CPL_C_END
229
231/*
232 * Helper macros used for input parameters validation.
233 */
234#ifdef DEBUG
235#define VALIDATE_POINTER_ERR CE_Fatal
236#else
237#define VALIDATE_POINTER_ERR CE_Failure
238#endif
239
242#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
243
244extern "C++"
245{
247 template <class T> T *CPLAssertNotNull(T *x) CPL_RETURNS_NONNULL;
248
249 template <class T> T *CPLAssertNotNull(T *x)
250 {
251 CPLAssert(x);
252 return x;
253 }
254
255#include <memory>
256#include <string>
257
263 class CPL_DLL CPLErrorHandlerPusher
264 {
265 public:
269 explicit CPLErrorHandlerPusher(CPLErrorHandler hHandler)
270 {
271 CPLPushErrorHandler(hHandler);
272 }
273
277 CPLErrorHandlerPusher(CPLErrorHandler hHandler, void *user_data)
278 {
279 CPLPushErrorHandlerEx(hHandler, user_data);
280 }
281
283 ~CPLErrorHandlerPusher()
284 {
285 CPLPopErrorHandler();
286 }
287 };
288
292 class CPL_DLL CPLErrorStateBackuper
293 {
294 CPLErrorNum m_nLastErrorNum;
295 CPLErr m_nLastErrorType;
296 std::string m_osLastErrorMsg;
297 GUInt32 m_nLastErrorCounter;
298 std::unique_ptr<CPLErrorHandlerPusher> m_poErrorHandlerPusher;
299
300 public:
304 explicit CPLErrorStateBackuper(CPLErrorHandler hHandler = nullptr);
305
309 ~CPLErrorStateBackuper();
310 };
311}
312
313#ifdef GDAL_COMPILATION
315// internal only
316bool CPLIsDefaultErrorHandlerAndCatchDebug();
318#endif
319
320#endif
321
323#define VALIDATE_POINTER0(ptr, func) \
324 do \
325 { \
326 if (CPL_NULLPTR == ptr) \
327 { \
328 CPLErr const ret = VALIDATE_POINTER_ERR; \
329 CPLError(ret, CPLE_ObjectNull, \
330 "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
331 return; \
332 } \
333 } while (0)
334
336#define VALIDATE_POINTER1(ptr, func, rc) \
337 do \
338 { \
339 if (CPL_NULLPTR == ptr) \
340 { \
341 CPLErr const ret = VALIDATE_POINTER_ERR; \
342 CPLError(ret, CPLE_ObjectNull, \
343 "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
344 return (rc); \
345 } \
346 } while (0)
347
348#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:264
CPLErrorHandlerPusher::CPLErrorHandlerPusher
CPLErrorHandlerPusher(CPLErrorHandler hHandler)
Constructor that installs a thread-local temporary error handler (typically CPLQuietErrorHandler)
Definition: cpl_error.h:269
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:277
CPLErrorHandlerPusher::~CPLErrorHandlerPusher
~CPLErrorHandlerPusher()
Destructor that restores the initial error handler.
Definition: cpl_error.h:283
CPLErrorStateBackuper
Class that saves the error state on construction, and restores it on destruction.
Definition: cpl_error.h:293
CPLE_IllegalArg
#define CPLE_IllegalArg
Illegal argument.
Definition: cpl_error.h:108
CPLErrorSetState
void CPLErrorSetState(CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)
Restore an error state, without emitting an error.
Definition: cpl_error.cpp:898
CPLGetErrorCounter
GUInt32 CPLGetErrorCounter(void)
Get the error counter.
Definition: cpl_error.cpp:990
CPLE_AWSObjectNotFound
#define CPLE_AWSObjectNotFound
AWSObjectNotFound.
Definition: cpl_error.h:128
CPLE_AssertionFailed
#define CPLE_AssertionFailed
Assertion failed.
Definition: cpl_error.h:112
CPLPushErrorHandlerEx
void CPLPushErrorHandlerEx(CPLErrorHandler, void *)
Push a new CPLError handler with user data on the error context.
Definition: cpl_error.cpp:1356
CPLE_AWSSignatureDoesNotMatch
#define CPLE_AWSSignatureDoesNotMatch
AWSSignatureDoesNotMatch.
Definition: cpl_error.h:134
CPLE_None
#define CPLE_None
No error.
Definition: cpl_error.h:98
CPLErrorReset
void CPLErrorReset(void)
Erase any traces of previous errors.
Definition: cpl_error.cpp:822
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:1134
CPLE_NotSupported
#define CPLE_NotSupported
Not supported.
Definition: cpl_error.h:110
CPLE_AWSInvalidCredentials
#define CPLE_AWSInvalidCredentials
AWSInvalidCredentials.
Definition: cpl_error.h:132
CPLAssert
#define CPLAssert(expr)
Assert on an expression.
Definition: cpl_error.h:216
CPLErr
CPLErr
Error category.
Definition: cpl_error.h:53
CPLE_FileIO
#define CPLE_FileIO
File I/O error.
Definition: cpl_error.h:104
CPLGetLastErrorNo
CPLErrorNum CPLGetLastErrorNo(void)
Fetch the last error number.
Definition: cpl_error.cpp:919
CPLDebugProgress
void CPLDebugProgress(const char *, const char *,...)
Display a debugging message indicating a progression.
Definition: cpl_error.cpp:792
CPLE_AppDefined
#define CPLE_AppDefined
Application defined error.
Definition: cpl_error.h:100
CPLE_OpenFailed
#define CPLE_OpenFailed
Open failed.
Definition: cpl_error.h:106
CPLGetLastErrorMsg
const char * CPLGetLastErrorMsg(void)
Get the last error message.
Definition: cpl_error.cpp:967
CPLGetErrorHandler
CPLErrorHandler CPLGetErrorHandler(void **ppUserData)
Fetch the current error handler for the current error context.
Definition: cpl_error.cpp:195
CPLSetErrorHandler
CPLErrorHandler CPLSetErrorHandler(CPLErrorHandler)
Install custom error handler.
Definition: cpl_error.cpp:1312
CPLE_AWSAccessDenied
#define CPLE_AWSAccessDenied
AWSAccessDenied.
Definition: cpl_error.h:130
CPLE_ObjectNull
#define CPLE_ObjectNull
NULL object.
Definition: cpl_error.h:118
CPLDefaultErrorHandler
void CPLDefaultErrorHandler(CPLErr, CPLErrorNum, const char *)
Default error handler.
Definition: cpl_error.cpp:1024
CPLGetLastErrorType
CPLErr CPLGetLastErrorType(void)
Fetch the last error type.
Definition: cpl_error.cpp:943
CPLErrorNum
int CPLErrorNum
Error number.
Definition: cpl_error.h:95
CPLGetErrorHandlerUserData
void * CPLGetErrorHandlerUserData(void)
Fetch the user data for the error context.
Definition: cpl_error.cpp:167
CPLErrorHandler
void(* CPLErrorHandler)(CPLErr, CPLErrorNum, const char *)
Callback for a custom error handler.
Definition: cpl_error.h:162
CPLTurnFailureIntoWarning
void CPLTurnFailureIntoWarning(int bOn)
Whether failures should be turned into warnings.
Definition: cpl_error.cpp:1207
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:1423
CPLEmergencyError
void CPLEmergencyError(const char *)
Fatal error when things are bad.
Definition: cpl_error.cpp:510
_CPLAssert
void _CPLAssert(const char *, const char *, int)
Report failure of a logical assertion.
Definition: cpl_error.cpp:1512
CPLE_HttpResponse
#define CPLE_HttpResponse
HTTP response.
Definition: cpl_error.h:124
CPLE_AWSBucketNotFound
#define CPLE_AWSBucketNotFound
AWSBucketNotFound.
Definition: cpl_error.h:126
CPLPopErrorHandler
void CPLPopErrorHandler(void)
Pop error handler off stack.
Definition: cpl_error.cpp:1390
CPLDebug
void CPLDebug(const char *, const char *,...)
Display a debugging message.
Definition: cpl_error.cpp:747
CPLPushErrorHandler
void CPLPushErrorHandler(CPLErrorHandler)
Push a new CPLError handler.
Definition: cpl_error.cpp:1333
CPLE_NoWriteAccess
#define CPLE_NoWriteAccess
No write access.
Definition: cpl_error.h:114
CPLE_UserInterrupt
#define CPLE_UserInterrupt
User interrupted.
Definition: cpl_error.h:116
CPLErrorV
void CPLErrorV(CPLErr, CPLErrorNum, const char *, va_list)
Same as CPLError() but with a va_list.
Definition: cpl_error.cpp:346
CPLQuietErrorHandler
void CPLQuietErrorHandler(CPLErr, CPLErrorNum, const char *)
Error handler that does not do anything, except for debug messages.
Definition: cpl_error.cpp:1119
CPLE_OutOfMemory
#define CPLE_OutOfMemory
Out of memory error.
Definition: cpl_error.h:102
CPLSetErrorHandlerEx
CPLErrorHandler CPLSetErrorHandlerEx(CPLErrorHandler, void *)
Install custom error handle with user's data.
Definition: cpl_error.cpp:1239
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:1478
CPLError
void CPLError(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,...)
Report an error.
Definition: cpl_error.cpp:330
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:995
CPL_C_END
#define CPL_C_END
Macro to end a block of C symbols.
Definition: cpl_port.h:299
CPL_C_START
#define CPL_C_START
Macro to start a block of C symbols.
Definition: cpl_port.h:295
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:966
CPL_RETURNS_NONNULL
#define CPL_RETURNS_NONNULL
Qualifier for a function that does not return NULL.
Definition: cpl_port.h:1014
GUInt32
unsigned int GUInt32
Unsigned int32 type.
Definition: cpl_port.h:177
CPL_PRINT_FUNC_FORMAT
#define CPL_PRINT_FUNC_FORMAT(format_idx, arg_idx)
Tag a function to have printf() formatting.
Definition: cpl_port.h:950