SDL_assert.h File Reference
`#include <SDL3/SDL_stdinc.h>`
`#include <SDL3/SDL_begin_code.h>`
`#include <SDL3/SDL_close_code.h>`
Include dependency graph for SDL_assert.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures

struct | SDL_AssertData

## Macros

#define | SDL_ASSERT_LEVEL 1
#define | SDL_FUNCTION "???"
#define | SDL_FILE __FILE__
#define | SDL_LINE __LINE__
#define | SDL_NULL_WHILE_LOOP_CONDITION (0)
#define | SDL_disabled_assert(condition) do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION)
#define | SDL_AssertBreakpoint() SDL_TriggerBreakpoint()
#define | SDL_enabled_assert(condition)
#define | SDL_assert(condition) SDL_disabled_assert(condition)
#define | SDL_assert_release(condition) SDL_disabled_assert(condition)
#define | SDL_assert_paranoid(condition) SDL_disabled_assert(condition)
#define | SDL_assert_always(condition) SDL_enabled_assert(condition)

## Typedefs

typedef SDL_AssertState(* | SDL_AssertionHandler) (const SDL_AssertData *data, void *userdata)

## Enumerations

enum | SDL_AssertState { SDL_ASSERTION_RETRY , SDL_ASSERTION_BREAK , SDL_ASSERTION_ABORT , SDL_ASSERTION_IGNORE , SDL_ASSERTION_ALWAYS_IGNORE }

## Functions

SDL_AssertState | SDL_ReportAssertion (SDL_AssertData *data, const char *func, const char *file, int line) SDL_ANALYZER_NORETURN
void | SDL_SetAssertionHandler (SDL_AssertionHandler handler, void *userdata)
SDL_AssertionHandler | SDL_GetDefaultAssertionHandler (void)
SDL_AssertionHandler | SDL_GetAssertionHandler (void **puserdata)
const SDL_AssertData * | SDL_GetAssertionReport (void)
void | SDL_ResetAssertionReport (void)

## Macro Definition Documentation

## SDL_assert

#define SDL_assert | ( |  | condition | ) | SDL_disabled_assert(condition)

Definition at line 474 of file SDL_assert.h.

## SDL_assert_always

#define SDL_assert_always | ( |  | condition | ) | SDL_enabled_assert(condition)

An assertion test that is always performed.

This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You almost never want to use this, as it could trigger on an end-user's system, crashing your program.

One can set the environment variable "SDL_ASSERT" to one of several strings ("abort", "break", "retry", "ignore", "always_ignore") to force a default behavior, which may be desirable for automation purposes. If your platform requires GUI interfaces to happen on the main thread but you're debugging an assertion in a background thread, it might be desirable to set this to "break" so that your debugger takes control as soon as assert is triggered, instead of risking a bad UI interaction (deadlock, etc) in the application.

Parameters

  condition | boolean value to test.

\threadsafety It is safe to call this macro from any thread.

Since
  This macro is available since SDL 3.2.0.

Definition at line 514 of file SDL_assert.h.

## SDL_ASSERT_LEVEL

#define SDL_ASSERT_LEVEL 1

# CategoryAssert

A helpful assertion macro!

SDL assertions operate like your usual `assert` macro, but with some added features:

- It uses a trick with the `sizeof` operator, so disabled assertions vaporize out of the compiled code, but variables only referenced in the assertion won't trigger compiler warnings about being unused.
- It is safe to use with a dangling-else: `if (x) SDL_assert(y); else do_something();`
- It works the same everywhere, instead of counting on various platforms' compiler and C runtime to behave.
- It provides multiple levels of assertion (SDL_assert, SDL_assert_release, SDL_assert_paranoid) instead of a single all-or-nothing option.
- It offers a variety of responses when an assertion fails (retry, trigger the debugger, abort the program, ignore the failure once, ignore it for the rest of the program's run).
- It tries to show the user a dialog by default, if possible, but the app can provide a callback to handle assertion failures however they like.
- It lets failed assertions be retried. Perhaps you had a network failure and just want to retry the test after plugging your network cable back in? You can.
- It lets the user ignore an assertion failure, if there's a harmless problem that one can continue past.
- It lets the user mark an assertion as ignored for the rest of the program's run; if there's a harmless problem that keeps popping up.
- It provides statistics and data on all failed assertions to the app.
- It allows the default assertion handler to be controlled with environment variables, in case an automated script needs to control it.
- It can be used as an aid to Clang's static analysis; it will treat SDL assertions as universally true (under the assumption that you are serious about the asserted claims and that your debug builds will detect when these claims were wrong). This can help the analyzer avoid false positives.

To use it: compile a debug build and just sprinkle around tests to check your code!

Definition at line 103 of file SDL_assert.h.

## SDL_assert_paranoid

#define SDL_assert_paranoid | ( |  | condition | ) | SDL_disabled_assert(condition)

Definition at line 476 of file SDL_assert.h.

## SDL_assert_release

#define SDL_assert_release | ( |  | condition | ) | SDL_disabled_assert(condition)

Definition at line 475 of file SDL_assert.h.

## SDL_AssertBreakpoint

#define SDL_AssertBreakpoint | ( |  | ) | SDL_TriggerBreakpoint()

Definition at line 337 of file SDL_assert.h.

## SDL_disabled_assert

#define SDL_disabled_assert | ( |  | condition | ) | do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION)

The macro used when an assertion is disabled.

This isn't for direct use by apps, but this is the code that is inserted when an SDL_assert is disabled (perhaps in a release build).

The code does nothing, but wraps `condition` in a sizeof operator, which generates no code and has no side effects, but avoid compiler warnings about unused variables.

Parameters

  condition | the condition to assert (but not actually run here).

Since
  This macro is available since SDL 3.2.0.

Definition at line 255 of file SDL_assert.h.

{ (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION)
SDL_NULL_WHILE_LOOP_CONDITION
#define SDL_NULL_WHILE_LOOP_CONDITION
Definition SDL_assert.h:238

## SDL_enabled_assert

#define SDL_enabled_assert | ( |  | condition | ) |

Value:
do { \
while ( !(condition) ) { \
static struct SDL_AssertData sdl_assert_data = { false, 0, #condition, NULL, 0, NULL, NULL }; \
const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \
if (sdl_assert_state == SDL_ASSERTION_RETRY) { \
continue; /* go again. */ \
} else if (sdl_assert_state == SDL_ASSERTION_BREAK) { \
SDL_AssertBreakpoint(); \
} \
break; /* not retrying. */ \
} \
} while (SDL_NULL_WHILE_LOOP_CONDITION)
SDL_AssertState
SDL_AssertState
Definition SDL_assert.h:272
SDL_ASSERTION_RETRY
@ SDL_ASSERTION_RETRY
Definition SDL_assert.h:273
SDL_ASSERTION_BREAK
@ SDL_ASSERTION_BREAK
Definition SDL_assert.h:274
SDL_FILE
#define SDL_FILE
Definition SDL_assert.h:187
SDL_ReportAssertion
SDL_AssertState SDL_ReportAssertion(SDL_AssertData *data, const char *func, const char *file, int line) SDL_ANALYZER_NORETURN
SDL_FUNCTION
#define SDL_FUNCTION
Definition SDL_assert.h:179
SDL_LINE
#define SDL_LINE
Definition SDL_assert.h:194
NULL
#define NULL
Definition SDL_begin_code.h:417
SDL_AssertData
Definition SDL_assert.h:290
SDL_AssertData::condition
const char * condition
Definition SDL_assert.h:293

The macro used when an assertion is enabled.

This isn't for direct use by apps, but this is the code that is inserted when an SDL_assert is enabled.

The `do {} while(0)` avoids dangling else problems:

if (x) SDL_assert(y); else blah();
SDL_assert
#define SDL_assert(condition)
Definition SDL_assert.h:474

... without the do/while, the "else" could attach to this macro's "if". We try to handle just the minimum we need here in a macro...the loop, the static vars, and break points. The heavy lifting is handled in SDL_ReportAssertion().

Parameters

  condition | the condition to assert.

Since
  This macro is available since SDL 3.2.0.

Definition at line 362 of file SDL_assert.h.

{ \
while ( !(condition) ) { \
static struct SDL_AssertData sdl_assert_data = { false, 0, #condition, NULL, 0, NULL, NULL }; \
const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \
if (sdl_assert_state == SDL_ASSERTION_RETRY) { \
continue; /* go again. */ \
} else if (sdl_assert_state == SDL_ASSERTION_BREAK) { \
SDL_AssertBreakpoint(); \
} \
break; /* not retrying. */ \
} \
} while (SDL_NULL_WHILE_LOOP_CONDITION)

## SDL_FILE

#define SDL_FILE __FILE__

A macro that reports the current file being compiled.

Since
  This macro is available since SDL 3.2.0.

Definition at line 187 of file SDL_assert.h.

## SDL_FUNCTION

#define SDL_FUNCTION "???"

Definition at line 179 of file SDL_assert.h.

## SDL_LINE

#define SDL_LINE __LINE__

A macro that reports the current line number of the file being compiled.

Since
  This macro is available since SDL 3.2.0.

Definition at line 194 of file SDL_assert.h.

## SDL_NULL_WHILE_LOOP_CONDITION

#define SDL_NULL_WHILE_LOOP_CONDITION (0)

Definition at line 238 of file SDL_assert.h.

## Typedef Documentation

## SDL_AssertionHandler

typedef SDL_AssertState(* SDL_AssertionHandler) (const SDL_AssertData *data, void *userdata)

A callback that fires when an SDL assertion fails.

Parameters

  data | a pointer to the SDL_AssertData structure corresponding to the current assertion.
  userdata | what was passed as `userdata` to SDL_SetAssertionHandler().

Returns
  an SDL_AssertState value indicating how to handle the failure.

\threadsafety This callback may be called from any thread that triggers an assert at any time.

Since
  This datatype is available since SDL 3.2.0.

Definition at line 530 of file SDL_assert.h.

## Enumeration Type Documentation

## SDL_AssertState

enum SDL_AssertState

Possible outcomes from a triggered assertion.

When an enabled assertion triggers, it may call the assertion handler (possibly one provided by the app via SDL_SetAssertionHandler), which will return one of these values, possibly after asking the user.

Then SDL will respond based on this outcome (loop around to retry the condition, try to break in a debugger, kill the program, or ignore the problem).

Since
  This enum is available since SDL 3.2.0.

Enumerator
SDL_ASSERTION_RETRY | Retry the assert immediately.
SDL_ASSERTION_BREAK | Make the debugger trigger a breakpoint.
SDL_ASSERTION_ABORT | Terminate the program.
SDL_ASSERTION_IGNORE | Ignore the assert.
SDL_ASSERTION_ALWAYS_IGNORE | Ignore the assert from now on.

Definition at line 271 of file SDL_assert.h.

{
SDL_ASSERTION_RETRY, /**< Retry the assert immediately. */
SDL_ASSERTION_BREAK, /**< Make the debugger trigger a breakpoint. */
SDL_ASSERTION_ABORT, /**< Terminate the program. */
SDL_ASSERTION_IGNORE, /**< Ignore the assert. */
SDL_ASSERTION_ALWAYS_IGNORE /**< Ignore the assert from now on. */
} SDL_AssertState;
SDL_ASSERTION_ABORT
@ SDL_ASSERTION_ABORT
Definition SDL_assert.h:275
SDL_ASSERTION_IGNORE
@ SDL_ASSERTION_IGNORE
Definition SDL_assert.h:276
SDL_ASSERTION_ALWAYS_IGNORE
@ SDL_ASSERTION_ALWAYS_IGNORE
Definition SDL_assert.h:277

## Function Documentation

## SDL_GetAssertionHandler()

SDL_AssertionHandler SDL_GetAssertionHandler | ( | void ** | puserdata | ) |

extern

Get the current assertion handler.

This returns the function pointer that is called when an assertion is triggered. This is either the value last passed to SDL_SetAssertionHandler(), or if no application-specified function is set, is equivalent to calling SDL_GetDefaultAssertionHandler().

The parameter `puserdata` is a pointer to a void*, which will store the "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value will always be NULL for the default handler. If you don't care about this data, it is safe to pass a NULL pointer to this function to ignore it.

Parameters

  puserdata | pointer which is filled with the "userdata" pointer that was passed to SDL_SetAssertionHandler().

Returns
  the SDL_AssertionHandler that is called when an assert triggers.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_SetAssertionHandler

## SDL_GetAssertionReport()

const SDL_AssertData * SDL_GetAssertionReport | ( | void |  | ) |

extern

Get a list of all assertion failures.

This function gets all assertions triggered since the last call to SDL_ResetAssertionReport(), or the start of the program.

The proper way to examine this data looks something like this:

const SDL_AssertData *item = SDL_GetAssertionReport();
while (item) {
printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
item->condition, item->function, item->filename,
item->linenum, item->trigger_count,
item->always_ignore ? "yes" : "no");
item = item->next;
}
SDL_GetAssertionReport
const SDL_AssertData * SDL_GetAssertionReport(void)
SDL_AssertData::next
const struct SDL_AssertData * next
Definition SDL_assert.h:297
SDL_AssertData::trigger_count
unsigned int trigger_count
Definition SDL_assert.h:292
SDL_AssertData::function
const char * function
Definition SDL_assert.h:296
SDL_AssertData::filename
const char * filename
Definition SDL_assert.h:294
SDL_AssertData::linenum
int linenum
Definition SDL_assert.h:295
SDL_AssertData::always_ignore
bool always_ignore
Definition SDL_assert.h:291

Returns
  a list of all failed assertions or NULL if the list is empty. This memory should not be modified or freed by the application. This pointer remains valid until the next call to SDL_Quit() or SDL_ResetAssertionReport().

\threadsafety This function is not thread safe. Other threads calling SDL_ResetAssertionReport() simultaneously, may render the returned pointer invalid.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_ResetAssertionReport

## SDL_GetDefaultAssertionHandler()

SDL_AssertionHandler SDL_GetDefaultAssertionHandler | ( | void |  | ) |

extern

Get the default assertion handler.

This returns the function pointer that is called by default when an assertion is triggered. This is an internal function provided by SDL, that is used for assertions when SDL_SetAssertionHandler() hasn't been used to provide a different function.

Returns
  the default SDL_AssertionHandler that is called when an assert triggers.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetAssertionHandler

## SDL_ReportAssertion()

SDL_AssertState SDL_ReportAssertion | ( | SDL_AssertData * | data,
|  | const char * | func,
|  | const char * | file,
|  | int | line
| ) |  |

extern

Never call this directly.

Use the SDL_assert macros instead.

Parameters

  data | assert data structure.
  func | function name.
  file | file name.
  line | line number.

Returns
  assert state.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

## SDL_ResetAssertionReport()

void SDL_ResetAssertionReport | ( | void |  | ) |

extern

Clear the list of all assertion failures.

This function will clear the list of all assertions triggered up to that point. Immediately following this call, SDL_GetAssertionReport will return no items. In addition, any previously-triggered assertions will be reset to a trigger_count of zero, and their always_ignore state will be false.

\threadsafety This function is not thread safe. Other threads triggering an assertion, or simultaneously calling this function may cause memory leaks or crashes.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetAssertionReport

## SDL_SetAssertionHandler()

void SDL_SetAssertionHandler | ( | SDL_AssertionHandler | handler,
|  | void * | userdata
| ) |  |

extern

Set an application-defined assertion handler.

This function allows an application to show its own assertion UI and/or force the response to an assertion failure. If the application doesn't provide this, SDL will try to do the right thing, popping up a system-specific GUI dialog, and probably minimizing any fullscreen windows.

This callback may fire from any thread, but it runs wrapped in a mutex, so it will only fire from one thread at a time.

This callback is NOT reset to SDL's internal handler upon SDL_Quit()!

Parameters

  handler | the SDL_AssertionHandler function to call when an assertion fails or NULL for the default handler.
  userdata | a pointer that is passed to `handler`.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetAssertionHandler