sdl3_sys/generated/
error.rs

1//! Simple error message routines for SDL.
2//!
3//! Most apps will interface with these APIs in exactly one function: when
4//! almost any SDL function call reports failure, you can get a human-readable
5//! string of the problem from [`SDL_GetError()`].
6//!
7//! These strings are maintained per-thread, and apps are welcome to set their
8//! own errors, which is popular when building libraries on top of SDL for
9//! other apps to consume. These strings are set by calling [`SDL_SetError()`].
10//!
11//! A common usage pattern is to have a function that returns true for success
12//! and false for failure, and do this when something fails:
13//!
14//! ```c
15//! if (something_went_wrong) {
16//!    return SDL_SetError("The thing broke in this specific way: %d", errcode);
17//! }
18//! ```
19//!
20//! It's also common to just return `false` in this case if the failing thing
21//! is known to call [`SDL_SetError()`], so errors simply propagate through.
22
23use super::stdinc::*;
24
25unsafe extern "C" {
26    /// Set the SDL error message for the current thread.
27    ///
28    /// Calling this function will replace any previous error message that was set.
29    ///
30    /// This function always returns false, since SDL frequently uses false to
31    /// signify a failing result, leading to this idiom:
32    ///
33    /// ```c
34    /// if (error_code) {
35    ///     return SDL_SetError("This operation has failed: %d", error_code);
36    /// }
37    /// ```
38    ///
39    /// ## Parameters
40    /// - `fmt`: a printf()-style message format string.
41    /// - `...`: additional parameters matching % tokens in the `fmt` string, if
42    ///   any.
43    ///
44    /// ## Return value
45    /// Returns false.
46    ///
47    /// ## Thread safety
48    /// It is safe to call this function from any thread.
49    ///
50    /// ## Availability
51    /// This function is available since SDL 3.2.0.
52    ///
53    /// ## See also
54    /// - [`SDL_ClearError`]
55    /// - [`SDL_GetError`]
56    /// - [`SDL_SetErrorV`]
57    pub fn SDL_SetError(fmt: *const ::core::ffi::c_char, ...) -> ::core::primitive::bool;
58}
59
60unsafe extern "C" {
61    /// Set the SDL error message for the current thread.
62    ///
63    /// Calling this function will replace any previous error message that was set.
64    ///
65    /// ## Parameters
66    /// - `fmt`: a printf()-style message format string.
67    /// - `ap`: a variable argument list.
68    ///
69    /// ## Return value
70    /// Returns false.
71    ///
72    /// ## Thread safety
73    /// It is safe to call this function from any thread.
74    ///
75    /// ## Availability
76    /// This function is available since SDL 3.2.0.
77    ///
78    /// ## See also
79    /// - [`SDL_ClearError`]
80    /// - [`SDL_GetError`]
81    /// - [`SDL_SetError`]
82    pub fn SDL_SetErrorV(
83        fmt: *const ::core::ffi::c_char,
84        ap: crate::ffi::VaList,
85    ) -> ::core::primitive::bool;
86}
87
88unsafe extern "C" {
89    /// Set an error indicating that memory allocation failed.
90    ///
91    /// This function does not do any memory allocation.
92    ///
93    /// ## Return value
94    /// Returns false.
95    ///
96    /// ## Thread safety
97    /// It is safe to call this function from any thread.
98    ///
99    /// ## Availability
100    /// This function is available since SDL 3.2.0.
101    pub safe fn SDL_OutOfMemory() -> ::core::primitive::bool;
102}
103
104unsafe extern "C" {
105    /// Retrieve a message about the last error that occurred on the current
106    /// thread.
107    ///
108    /// It is possible for multiple errors to occur before calling [`SDL_GetError()`].
109    /// Only the last error is returned.
110    ///
111    /// The message is only applicable when an SDL function has signaled an error.
112    /// You must check the return values of SDL function calls to determine when to
113    /// appropriately call [`SDL_GetError()`]. You should *not* use the results of
114    /// [`SDL_GetError()`] to decide if an error has occurred! Sometimes SDL will set
115    /// an error string even when reporting success.
116    ///
117    /// SDL will *not* clear the error string for successful API calls. You *must*
118    /// check return values for failure cases before you can assume the error
119    /// string applies.
120    ///
121    /// Error strings are set per-thread, so an error set in a different thread
122    /// will not interfere with the current thread's operation.
123    ///
124    /// The returned value is a thread-local string which will remain valid until
125    /// the current thread's error string is changed. The caller should make a copy
126    /// if the value is needed after the next SDL API call.
127    ///
128    /// ## Return value
129    /// Returns a message with information about the specific error that occurred,
130    ///   or an empty string if there hasn't been an error message set since
131    ///   the last call to [`SDL_ClearError()`].
132    ///
133    /// ## Thread safety
134    /// It is safe to call this function from any thread.
135    ///
136    /// ## Availability
137    /// This function is available since SDL 3.2.0.
138    ///
139    /// ## See also
140    /// - [`SDL_ClearError`]
141    /// - [`SDL_SetError`]
142    pub safe fn SDL_GetError() -> *const ::core::ffi::c_char;
143}
144
145unsafe extern "C" {
146    /// Clear any previous error message for this thread.
147    ///
148    /// ## Return value
149    /// Returns true.
150    ///
151    /// ## Thread safety
152    /// It is safe to call this function from any thread.
153    ///
154    /// ## Availability
155    /// This function is available since SDL 3.2.0.
156    ///
157    /// ## See also
158    /// - [`SDL_GetError`]
159    /// - [`SDL_SetError`]
160    pub safe fn SDL_ClearError() -> ::core::primitive::bool;
161}
162
163/// A macro to standardize error reporting on unsupported operations.
164///
165/// This simply calls [`SDL_SetError()`] with a standardized error string, for
166/// convenience, consistency, and clarity.
167///
168/// ## Thread safety
169/// It is safe to call this macro from any thread.
170///
171/// ## Availability
172/// This macro is available since SDL 3.2.0.
173#[inline(always)]
174pub unsafe fn SDL_Unsupported() -> ::core::primitive::bool {
175    unsafe { SDL_SetError(c"That operation is not supported".as_ptr()) }
176}
177
178/// A macro to standardize error reporting on unsupported operations.
179///
180/// This simply calls [`SDL_SetError()`] with a standardized error string, for
181/// convenience, consistency, and clarity.
182///
183/// A common usage pattern inside SDL is this:
184///
185/// ```c
186/// bool MyFunction(const char *str) {
187///     if (!str) {
188///         return SDL_InvalidParamError("str");  // returns false.
189///     }
190///     DoSomething(str);
191///     return true;
192/// }
193/// ```
194///
195/// ## Thread safety
196/// It is safe to call this macro from any thread.
197///
198/// ## Availability
199/// This macro is available since SDL 3.2.0.
200#[inline(always)]
201pub unsafe fn SDL_InvalidParamError(param: *const ::core::ffi::c_char) -> ::core::primitive::bool {
202    unsafe { SDL_SetError(c"Parameter '%s' is invalid".as_ptr(), (param)) }
203}
204
205#[cfg(doc)]
206use crate::everything::*;
sdl3_sys/generated/error.rs

sdl3_sys/generated/
error.rs
