SDL 3.0
SDL_log.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 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 * # CategoryLog
24 *
25 * Simple log messages with priorities and categories. A message's
26 * SDL_LogPriority signifies how important the message is. A message's
27 * SDL_LogCategory signifies from what domain it belongs to. Every category
28 * has a minimum priority specified: when a message belongs to that category,
29 * it will only be sent out if it has that minimum priority or higher.
30 *
31 * SDL's own logs are sent below the default priority threshold, so they are
32 * quiet by default.
33 *
34 * You can change the log verbosity programmatically using
35 * SDL_SetLogPriority() or with SDL_SetHint(SDL_HINT_LOGGING, ...), or with
36 * the "SDL_LOGGING" environment variable. This variable is a comma separated
37 * set of category=level tokens that define the default logging levels for SDL
38 * applications.
39 *
40 * The category can be a numeric category, one of "app", "error", "assert",
41 * "system", "audio", "video", "render", "input", "test", or `*` for any
42 * unspecified category.
43 *
44 * The level can be a numeric level, one of "verbose", "debug", "info",
45 * "warn", "error", "critical", or "quiet" to disable that category.
46 *
47 * You can omit the category if you want to set the logging level for all
48 * categories.
49 *
50 * If this hint isn't set, the default log levels are equivalent to:
51 *
52 * `app=info,assert=warn,test=verbose,*=error`
53 *
54 * Here's where the messages go on different platforms:
55 *
56 * - Windows: debug output stream
57 * - Android: log output
58 * - Others: standard error output (stderr)
59 */
60
61#ifndef SDL_log_h_
62#define SDL_log_h_
63
64#include <SDL3/SDL_stdinc.h>
65
66#include <SDL3/SDL_begin_code.h>
67/* Set up for C function definitions, even when using C++ */
68#ifdef __cplusplus
69extern "C" {
70#endif
71
72/**
73 * The predefined log categories
74 *
75 * By default the application and gpu categories are enabled at the INFO
76 * level, the assert category is enabled at the WARN level, test is enabled at
77 * the VERBOSE level and all other categories are enabled at the ERROR level.
78 *
79 * \since This enum is available since SDL 3.1.3.
80 */
81typedef enum SDL_LogCategory
82{
93
94 /* Reserved for future SDL library use */
104
105 /* Beyond this point is reserved for application use, e.g.
106 enum {
107 MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM,
108 MYAPP_CATEGORY_AWESOME2,
109 MYAPP_CATEGORY_AWESOME3,
110 ...
111 };
112 */
115
116/**
117 * The predefined log priorities
118 *
119 * \since This enum is available since SDL 3.1.3.
120 */
121typedef enum SDL_LogPriority
122{
133
134
135/**
136 * Set the priority of all log categories.
137 *
138 * \param priority the SDL_LogPriority to assign.
139 *
140 * \threadsafety It is safe to call this function from any thread.
141 *
142 * \since This function is available since SDL 3.1.3.
143 *
144 * \sa SDL_ResetLogPriorities
145 * \sa SDL_SetLogPriority
146 */
147extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority);
148
149/**
150 * Set the priority of a particular log category.
151 *
152 * \param category the category to assign a priority to.
153 * \param priority the SDL_LogPriority to assign.
154 *
155 * \threadsafety It is safe to call this function from any thread.
156 *
157 * \since This function is available since SDL 3.1.3.
158 *
159 * \sa SDL_GetLogPriority
160 * \sa SDL_ResetLogPriorities
161 * \sa SDL_SetLogPriorities
162 */
163extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority);
164
165/**
166 * Get the priority of a particular log category.
167 *
168 * \param category the category to query.
169 * \returns the SDL_LogPriority for the requested category.
170 *
171 * \threadsafety It is safe to call this function from any thread.
172 *
173 * \since This function is available since SDL 3.1.3.
174 *
175 * \sa SDL_SetLogPriority
176 */
177extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category);
178
179/**
180 * Reset all priorities to default.
181 *
182 * This is called by SDL_Quit().
183 *
184 * \threadsafety It is safe to call this function from any thread.
185 *
186 * \since This function is available since SDL 3.1.3.
187 *
188 * \sa SDL_SetLogPriorities
189 * \sa SDL_SetLogPriority
190 */
191extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void);
192
193/**
194 * Set the text prepended to log messages of a given priority.
195 *
196 * By default SDL_LOG_PRIORITY_INFO and below have no prefix, and
197 * SDL_LOG_PRIORITY_WARN and higher have a prefix showing their priority, e.g.
198 * "WARNING: ".
199 *
200 * \param priority the SDL_LogPriority to modify.
201 * \param prefix the prefix to use for that log priority, or NULL to use no
202 * prefix.
203 * \returns true on success or false on failure; call SDL_GetError() for more
204 * information.
205 *
206 * \threadsafety It is safe to call this function from any thread.
207 *
208 * \since This function is available since SDL 3.1.3.
209 *
210 * \sa SDL_SetLogPriorities
211 * \sa SDL_SetLogPriority
212 */
213extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix);
214
215/**
216 * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
217 *
218 * \param fmt a printf() style message format string.
219 * \param ... additional parameters matching % tokens in the `fmt` string, if
220 * any.
221 *
222 * \threadsafety It is safe to call this function from any thread.
223 *
224 * \since This function is available since SDL 3.1.3.
225 *
226 * \sa SDL_LogCritical
227 * \sa SDL_LogDebug
228 * \sa SDL_LogError
229 * \sa SDL_LogInfo
230 * \sa SDL_LogMessage
231 * \sa SDL_LogMessageV
232 * \sa SDL_LogTrace
233 * \sa SDL_LogVerbose
234 * \sa SDL_LogWarn
235 */
236extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
237
238/**
239 * Log a message with SDL_LOG_PRIORITY_TRACE.
240 *
241 * \param category the category of the message.
242 * \param fmt a printf() style message format string.
243 * \param ... additional parameters matching % tokens in the **fmt** string,
244 * if any.
245 *
246 * \threadsafety It is safe to call this function from any thread.
247 *
248 * \since This function is available since SDL 3.1.3.
249 *
250 * \sa SDL_Log
251 * \sa SDL_LogCritical
252 * \sa SDL_LogDebug
253 * \sa SDL_LogError
254 * \sa SDL_LogInfo
255 * \sa SDL_LogMessage
256 * \sa SDL_LogMessageV
257 * \sa SDL_LogTrace
258 * \sa SDL_LogVerbose
259 * \sa SDL_LogWarn
260 */
261extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
262
263/**
264 * Log a message with SDL_LOG_PRIORITY_VERBOSE.
265 *
266 * \param category the category of the message.
267 * \param fmt a printf() style message format string.
268 * \param ... additional parameters matching % tokens in the **fmt** string,
269 * if any.
270 *
271 * \threadsafety It is safe to call this function from any thread.
272 *
273 * \since This function is available since SDL 3.1.3.
274 *
275 * \sa SDL_Log
276 * \sa SDL_LogCritical
277 * \sa SDL_LogDebug
278 * \sa SDL_LogError
279 * \sa SDL_LogInfo
280 * \sa SDL_LogMessage
281 * \sa SDL_LogMessageV
282 * \sa SDL_LogWarn
283 */
284extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
285
286/**
287 * Log a message with SDL_LOG_PRIORITY_DEBUG.
288 *
289 * \param category the category of the message.
290 * \param fmt a printf() style message format string.
291 * \param ... additional parameters matching % tokens in the **fmt** string,
292 * if any.
293 *
294 * \threadsafety It is safe to call this function from any thread.
295 *
296 * \since This function is available since SDL 3.1.3.
297 *
298 * \sa SDL_Log
299 * \sa SDL_LogCritical
300 * \sa SDL_LogError
301 * \sa SDL_LogInfo
302 * \sa SDL_LogMessage
303 * \sa SDL_LogMessageV
304 * \sa SDL_LogTrace
305 * \sa SDL_LogVerbose
306 * \sa SDL_LogWarn
307 */
308extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
309
310/**
311 * Log a message with SDL_LOG_PRIORITY_INFO.
312 *
313 * \param category the category of the message.
314 * \param fmt a printf() style message format string.
315 * \param ... additional parameters matching % tokens in the **fmt** string,
316 * if any.
317 *
318 * \threadsafety It is safe to call this function from any thread.
319 *
320 * \since This function is available since SDL 3.1.3.
321 *
322 * \sa SDL_Log
323 * \sa SDL_LogCritical
324 * \sa SDL_LogDebug
325 * \sa SDL_LogError
326 * \sa SDL_LogMessage
327 * \sa SDL_LogMessageV
328 * \sa SDL_LogTrace
329 * \sa SDL_LogVerbose
330 * \sa SDL_LogWarn
331 */
332extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
333
334/**
335 * Log a message with SDL_LOG_PRIORITY_WARN.
336 *
337 * \param category the category of the message.
338 * \param fmt a printf() style message format string.
339 * \param ... additional parameters matching % tokens in the **fmt** string,
340 * if any.
341 *
342 * \threadsafety It is safe to call this function from any thread.
343 *
344 * \since This function is available since SDL 3.1.3.
345 *
346 * \sa SDL_Log
347 * \sa SDL_LogCritical
348 * \sa SDL_LogDebug
349 * \sa SDL_LogError
350 * \sa SDL_LogInfo
351 * \sa SDL_LogMessage
352 * \sa SDL_LogMessageV
353 * \sa SDL_LogTrace
354 * \sa SDL_LogVerbose
355 */
356extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
357
358/**
359 * Log a message with SDL_LOG_PRIORITY_ERROR.
360 *
361 * \param category the category of the message.
362 * \param fmt a printf() style message format string.
363 * \param ... additional parameters matching % tokens in the **fmt** string,
364 * if any.
365 *
366 * \threadsafety It is safe to call this function from any thread.
367 *
368 * \since This function is available since SDL 3.1.3.
369 *
370 * \sa SDL_Log
371 * \sa SDL_LogCritical
372 * \sa SDL_LogDebug
373 * \sa SDL_LogInfo
374 * \sa SDL_LogMessage
375 * \sa SDL_LogMessageV
376 * \sa SDL_LogTrace
377 * \sa SDL_LogVerbose
378 * \sa SDL_LogWarn
379 */
380extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
381
382/**
383 * Log a message with SDL_LOG_PRIORITY_CRITICAL.
384 *
385 * \param category the category of the message.
386 * \param fmt a printf() style message format string.
387 * \param ... additional parameters matching % tokens in the **fmt** string,
388 * if any.
389 *
390 * \threadsafety It is safe to call this function from any thread.
391 *
392 * \since This function is available since SDL 3.1.3.
393 *
394 * \sa SDL_Log
395 * \sa SDL_LogDebug
396 * \sa SDL_LogError
397 * \sa SDL_LogInfo
398 * \sa SDL_LogMessage
399 * \sa SDL_LogMessageV
400 * \sa SDL_LogTrace
401 * \sa SDL_LogVerbose
402 * \sa SDL_LogWarn
403 */
404extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
405
406/**
407 * Log a message with the specified category and priority.
408 *
409 * \param category the category of the message.
410 * \param priority the priority of the message.
411 * \param fmt a printf() style message format string.
412 * \param ... additional parameters matching % tokens in the **fmt** string,
413 * if any.
414 *
415 * \threadsafety It is safe to call this function from any thread.
416 *
417 * \since This function is available since SDL 3.1.3.
418 *
419 * \sa SDL_Log
420 * \sa SDL_LogCritical
421 * \sa SDL_LogDebug
422 * \sa SDL_LogError
423 * \sa SDL_LogInfo
424 * \sa SDL_LogMessageV
425 * \sa SDL_LogTrace
426 * \sa SDL_LogVerbose
427 * \sa SDL_LogWarn
428 */
429extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category,
430 SDL_LogPriority priority,
431 SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
432
433/**
434 * Log a message with the specified category and priority.
435 *
436 * \param category the category of the message.
437 * \param priority the priority of the message.
438 * \param fmt a printf() style message format string.
439 * \param ap a variable argument list.
440 *
441 * \threadsafety It is safe to call this function from any thread.
442 *
443 * \since This function is available since SDL 3.1.3.
444 *
445 * \sa SDL_Log
446 * \sa SDL_LogCritical
447 * \sa SDL_LogDebug
448 * \sa SDL_LogError
449 * \sa SDL_LogInfo
450 * \sa SDL_LogMessage
451 * \sa SDL_LogTrace
452 * \sa SDL_LogVerbose
453 * \sa SDL_LogWarn
454 */
455extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category,
456 SDL_LogPriority priority,
457 SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
458
459/**
460 * The prototype for the log output callback function.
461 *
462 * This function is called by SDL when there is new text to be logged. A mutex
463 * is held so that this function is never called by more than one thread at
464 * once.
465 *
466 * \param userdata what was passed as `userdata` to
467 * SDL_SetLogOutputFunction().
468 * \param category the category of the message.
469 * \param priority the priority of the message.
470 * \param message the message being output.
471 *
472 * \since This datatype is available since SDL 3.1.3.
473 */
474typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
475
476/**
477 * Get the default log output function.
478 *
479 * \returns the default log output callback.
480 *
481 * \threadsafety It is safe to call this function from any thread.
482 *
483 * \since This function is available since SDL 3.2.0.
484 *
485 * \sa SDL_SetLogOutputFunction
486 * \sa SDL_GetLogOutputFunction
487 */
489
490/**
491 * Get the current log output function.
492 *
493 * \param callback an SDL_LogOutputFunction filled in with the current log
494 * callback.
495 * \param userdata a pointer filled in with the pointer that is passed to
496 * `callback`.
497 *
498 * \threadsafety It is safe to call this function from any thread.
499 *
500 * \since This function is available since SDL 3.1.3.
501 *
502 * \sa SDL_GetDefaultLogOutputFunction
503 * \sa SDL_SetLogOutputFunction
504 */
505extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
506
507/**
508 * Replace the default log output function with one of your own.
509 *
510 * \param callback an SDL_LogOutputFunction to call instead of the default.
511 * \param userdata a pointer that is passed to `callback`.
512 *
513 * \threadsafety It is safe to call this function from any thread.
514 *
515 * \since This function is available since SDL 3.1.3.
516 *
517 * \sa SDL_GetDefaultLogOutputFunction
518 * \sa SDL_GetLogOutputFunction
519 */
520extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata);
521
522
523/* Ends C function definitions when using C++ */
524#ifdef __cplusplus
525}
526#endif
527#include <SDL3/SDL_close_code.h>
528
529#endif /* SDL_log_h_ */
void SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata)
SDL_LogPriority
Definition: SDL_log.h:122
@ SDL_LOG_PRIORITY_TRACE
Definition: SDL_log.h:124
@ SDL_LOG_PRIORITY_INFO
Definition: SDL_log.h:127
@ SDL_LOG_PRIORITY_COUNT
Definition: SDL_log.h:131
@ SDL_LOG_PRIORITY_CRITICAL
Definition: SDL_log.h:130
@ SDL_LOG_PRIORITY_VERBOSE
Definition: SDL_log.h:125
@ SDL_LOG_PRIORITY_DEBUG
Definition: SDL_log.h:126
@ SDL_LOG_PRIORITY_ERROR
Definition: SDL_log.h:129
@ SDL_LOG_PRIORITY_INVALID
Definition: SDL_log.h:123
@ SDL_LOG_PRIORITY_WARN
Definition: SDL_log.h:128
bool SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix)
void SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_ResetLogPriorities(void)
void(* SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message)
Definition: SDL_log.h:474
SDL_LogPriority SDL_GetLogPriority(int category)
void SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(1)
void SDL_SetLogPriority(int category, SDL_LogPriority priority)
void SDL_LogMessageV(int category, SDL_LogPriority priority, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3)
void SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_SetLogPriorities(SDL_LogPriority priority)
void SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
SDL_LogCategory
Definition: SDL_log.h:82
@ SDL_LOG_CATEGORY_CUSTOM
Definition: SDL_log.h:113
@ SDL_LOG_CATEGORY_GPU
Definition: SDL_log.h:92
@ SDL_LOG_CATEGORY_RESERVED8
Definition: SDL_log.h:101
@ SDL_LOG_CATEGORY_RESERVED6
Definition: SDL_log.h:99
@ SDL_LOG_CATEGORY_ERROR
Definition: SDL_log.h:84
@ SDL_LOG_CATEGORY_RENDER
Definition: SDL_log.h:89
@ SDL_LOG_CATEGORY_RESERVED5
Definition: SDL_log.h:98
@ SDL_LOG_CATEGORY_RESERVED3
Definition: SDL_log.h:96
@ SDL_LOG_CATEGORY_INPUT
Definition: SDL_log.h:90
@ SDL_LOG_CATEGORY_TEST
Definition: SDL_log.h:91
@ SDL_LOG_CATEGORY_RESERVED9
Definition: SDL_log.h:102
@ SDL_LOG_CATEGORY_SYSTEM
Definition: SDL_log.h:86
@ SDL_LOG_CATEGORY_RESERVED10
Definition: SDL_log.h:103
@ SDL_LOG_CATEGORY_RESERVED4
Definition: SDL_log.h:97
@ SDL_LOG_CATEGORY_APPLICATION
Definition: SDL_log.h:83
@ SDL_LOG_CATEGORY_AUDIO
Definition: SDL_log.h:87
@ SDL_LOG_CATEGORY_RESERVED7
Definition: SDL_log.h:100
@ SDL_LOG_CATEGORY_ASSERT
Definition: SDL_log.h:85
@ SDL_LOG_CATEGORY_VIDEO
Definition: SDL_log.h:88
@ SDL_LOG_CATEGORY_RESERVED2
Definition: SDL_log.h:95
void SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata)
void SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_LogMessage(int category, SDL_LogPriority priority, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(3)
SDL_LogOutputFunction SDL_GetDefaultLogOutputFunction(void)
#define SDL_PRINTF_VARARG_FUNCV(fmtargnumber)
Definition: SDL_stdinc.h:580
#define SDL_PRINTF_FORMAT_STRING
Definition: SDL_stdinc.h:568
#define SDL_PRINTF_VARARG_FUNC(fmtargnumber)
Definition: SDL_stdinc.h:579