|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /**
|
|
|
23 * # CategoryError
|
|
|
24 *
|
|
|
25 * Simple error message routines for SDL.
|
|
|
26 *
|
|
|
27 * Most apps will interface with these APIs in exactly one function: when
|
|
|
28 * almost any SDL function call reports failure, you can get a human-readable
|
|
|
29 * string of the problem from SDL_GetError().
|
|
|
30 *
|
|
|
31 * These strings are maintained per-thread, and apps are welcome to set their
|
|
|
32 * own errors, which is popular when building libraries on top of SDL for
|
|
|
33 * other apps to consume. These strings are set by calling SDL_SetError().
|
|
|
34 *
|
|
|
35 * A common usage pattern is to have a function that returns true for success
|
|
|
36 * and false for failure, and do this when something fails:
|
|
|
37 *
|
|
|
38 * ```c
|
|
|
39 * if (something_went_wrong) {
|
|
|
40 * return SDL_SetError("The thing broke in this specific way: %d", errcode);
|
|
|
41 * }
|
|
|
42 * ```
|
|
|
43 *
|
|
|
44 * It's also common to just return `false` in this case if the failing thing
|
|
|
45 * is known to call SDL_SetError(), so errors simply propagate through.
|
|
|
46 */
|
|
|
47
|
|
|
48 #ifndef SDL_error_h_
|
|
|
49 #define SDL_error_h_
|
|
|
50
|
|
|
51 #include <SDL3/SDL_stdinc.h>
|
|
|
52
|
|
|
53 #include <SDL3/SDL_begin_code.h>
|
|
|
54 /* Set up for C function definitions, even when using C++ */
|
|
|
55 #ifdef __cplusplus
|
|
|
56 extern "C" {
|
|
|
57 #endif
|
|
|
58
|
|
|
59 /* Public functions */
|
|
|
60
|
|
|
61
|
|
|
62 /**
|
|
|
63 * Set the SDL error message for the current thread.
|
|
|
64 *
|
|
|
65 * Calling this function will replace any previous error message that was set.
|
|
|
66 *
|
|
|
67 * This function always returns false, since SDL frequently uses false to
|
|
|
68 * signify a failing result, leading to this idiom:
|
|
|
69 *
|
|
|
70 * ```c
|
|
|
71 * if (error_code) {
|
|
|
72 * return SDL_SetError("This operation has failed: %d", error_code);
|
|
|
73 * }
|
|
|
74 * ```
|
|
|
75 *
|
|
|
76 * \param fmt a printf()-style message format string.
|
|
|
77 * \param ... additional parameters matching % tokens in the `fmt` string, if
|
|
|
78 * any.
|
|
|
79 * \returns false.
|
|
|
80 *
|
|
|
81 * \threadsafety It is safe to call this function from any thread.
|
|
|
82 *
|
|
|
83 * \since This function is available since SDL 3.2.0.
|
|
|
84 *
|
|
|
85 * \sa SDL_ClearError
|
|
|
86 * \sa SDL_GetError
|
|
|
87 * \sa SDL_SetErrorV
|
|
|
88 */
|
|
|
89 extern SDL_DECLSPEC bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
|
|
|
90
|
|
|
91 /**
|
|
|
92 * Set the SDL error message for the current thread.
|
|
|
93 *
|
|
|
94 * Calling this function will replace any previous error message that was set.
|
|
|
95 *
|
|
|
96 * \param fmt a printf()-style message format string.
|
|
|
97 * \param ap a variable argument list.
|
|
|
98 * \returns false.
|
|
|
99 *
|
|
|
100 * \threadsafety It is safe to call this function from any thread.
|
|
|
101 *
|
|
|
102 * \since This function is available since SDL 3.2.0.
|
|
|
103 *
|
|
|
104 * \sa SDL_ClearError
|
|
|
105 * \sa SDL_GetError
|
|
|
106 * \sa SDL_SetError
|
|
|
107 */
|
|
|
108 extern SDL_DECLSPEC bool SDLCALL SDL_SetErrorV(SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(1);
|
|
|
109
|
|
|
110 /**
|
|
|
111 * Set an error indicating that memory allocation failed.
|
|
|
112 *
|
|
|
113 * This function does not do any memory allocation.
|
|
|
114 *
|
|
|
115 * \returns false.
|
|
|
116 *
|
|
|
117 * \threadsafety It is safe to call this function from any thread.
|
|
|
118 *
|
|
|
119 * \since This function is available since SDL 3.2.0.
|
|
|
120 */
|
|
|
121 extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void);
|
|
|
122
|
|
|
123 /**
|
|
|
124 * Retrieve a message about the last error that occurred on the current
|
|
|
125 * thread.
|
|
|
126 *
|
|
|
127 * It is possible for multiple errors to occur before calling SDL_GetError().
|
|
|
128 * Only the last error is returned.
|
|
|
129 *
|
|
|
130 * The message is only applicable when an SDL function has signaled an error.
|
|
|
131 * You must check the return values of SDL function calls to determine when to
|
|
|
132 * appropriately call SDL_GetError(). You should *not* use the results of
|
|
|
133 * SDL_GetError() to decide if an error has occurred! Sometimes SDL will set
|
|
|
134 * an error string even when reporting success.
|
|
|
135 *
|
|
|
136 * SDL will *not* clear the error string for successful API calls. You *must*
|
|
|
137 * check return values for failure cases before you can assume the error
|
|
|
138 * string applies.
|
|
|
139 *
|
|
|
140 * Error strings are set per-thread, so an error set in a different thread
|
|
|
141 * will not interfere with the current thread's operation.
|
|
|
142 *
|
|
|
143 * The returned value is a thread-local string which will remain valid until
|
|
|
144 * the current thread's error string is changed. The caller should make a copy
|
|
|
145 * if the value is needed after the next SDL API call.
|
|
|
146 *
|
|
|
147 * \returns a message with information about the specific error that occurred,
|
|
|
148 * or an empty string if there hasn't been an error message set since
|
|
|
149 * the last call to SDL_ClearError().
|
|
|
150 *
|
|
|
151 * \threadsafety It is safe to call this function from any thread.
|
|
|
152 *
|
|
|
153 * \since This function is available since SDL 3.2.0.
|
|
|
154 *
|
|
|
155 * \sa SDL_ClearError
|
|
|
156 * \sa SDL_SetError
|
|
|
157 */
|
|
|
158 extern SDL_DECLSPEC const char * SDLCALL SDL_GetError(void);
|
|
|
159
|
|
|
160 /**
|
|
|
161 * Clear any previous error message for this thread.
|
|
|
162 *
|
|
|
163 * \returns true.
|
|
|
164 *
|
|
|
165 * \threadsafety It is safe to call this function from any thread.
|
|
|
166 *
|
|
|
167 * \since This function is available since SDL 3.2.0.
|
|
|
168 *
|
|
|
169 * \sa SDL_GetError
|
|
|
170 * \sa SDL_SetError
|
|
|
171 */
|
|
|
172 extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void);
|
|
|
173
|
|
|
174 /**
|
|
|
175 * \name Internal error functions
|
|
|
176 *
|
|
|
177 * \internal
|
|
|
178 * Private error reporting function - used internally.
|
|
|
179 */
|
|
|
180 /* @{ */
|
|
|
181
|
|
|
182 /**
|
|
|
183 * A macro to standardize error reporting on unsupported operations.
|
|
|
184 *
|
|
|
185 * This simply calls SDL_SetError() with a standardized error string, for
|
|
|
186 * convenience, consistency, and clarity.
|
|
|
187 *
|
|
|
188 * \threadsafety It is safe to call this macro from any thread.
|
|
|
189 *
|
|
|
190 * \since This macro is available since SDL 3.2.0.
|
|
|
191 */
|
|
|
192 #define SDL_Unsupported() SDL_SetError("That operation is not supported")
|
|
|
193
|
|
|
194 /**
|
|
|
195 * A macro to standardize error reporting on unsupported operations.
|
|
|
196 *
|
|
|
197 * This simply calls SDL_SetError() with a standardized error string, for
|
|
|
198 * convenience, consistency, and clarity.
|
|
|
199 *
|
|
|
200 * A common usage pattern inside SDL is this:
|
|
|
201 *
|
|
|
202 * ```c
|
|
|
203 * bool MyFunction(const char *str) {
|
|
|
204 * if (!str) {
|
|
|
205 * return SDL_InvalidParamError("str"); // returns false.
|
|
|
206 * }
|
|
|
207 * DoSomething(str);
|
|
|
208 * return true;
|
|
|
209 * }
|
|
|
210 * ```
|
|
|
211 *
|
|
|
212 * \threadsafety It is safe to call this macro from any thread.
|
|
|
213 *
|
|
|
214 * \since This macro is available since SDL 3.2.0.
|
|
|
215 */
|
|
|
216 #define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param))
|
|
|
217
|
|
|
218 /* @} *//* Internal error functions */
|
|
|
219
|
|
|
220 /* Ends C function definitions when using C++ */
|
|
|
221 #ifdef __cplusplus
|
|
|
222 }
|
|
|
223 #endif
|
|
|
224 #include <SDL3/SDL_close_code.h>
|
|
|
225
|
|
|
226 #endif /* SDL_error_h_ */
|
