aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_log.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_log.h')
-rw-r--r--libraries/eina/src/include/eina_log.h903
1 files changed, 0 insertions, 903 deletions
diff --git a/libraries/eina/src/include/eina_log.h b/libraries/eina/src/include/eina_log.h
deleted file mode 100644
index 186397d..0000000
--- a/libraries/eina/src/include/eina_log.h
+++ /dev/null
@@ -1,903 +0,0 @@
1/* EINA - EFL data type library
2 * Copyright (C) 2007-2008 Jorge Luis Zapata Muga, Cedric Bail
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library;
16 * if not, see <http://www.gnu.org/licenses/>.
17 */
18
19#ifndef EINA_LOG_H_
20#define EINA_LOG_H_
21
22#include <stdlib.h>
23#include <stdarg.h>
24#include <sys/types.h>
25
26#include "eina_types.h"
27
28#define EINA_COLOR_LIGHTRED "\033[31;1m"
29#define EINA_COLOR_RED "\033[31m"
30#define EINA_COLOR_LIGHTBLUE "\033[34;1m"
31#define EINA_COLOR_BLUE "\033[34m"
32#define EINA_COLOR_GREEN "\033[32;1m"
33#define EINA_COLOR_YELLOW "\033[33;1m"
34#define EINA_COLOR_ORANGE "\033[0;33m"
35#define EINA_COLOR_WHITE "\033[37;1m"
36#define EINA_COLOR_LIGHTCYAN "\033[36;1m"
37#define EINA_COLOR_CYAN "\033[36m"
38#define EINA_COLOR_RESET "\033[0m"
39#define EINA_COLOR_HIGH "\033[1m"
40
41
42/**
43 * @page tutorial_log_page Log Tutorial
44 *
45 * @section tutorial_log_introduction Introduction
46 *
47 * The Eina Log module provides logging facilities for libraries and
48 * applications. It provides colored logging, basic logging levels (error,
49 * warning, debug, info, critical) and loggers - called logging domains -
50 * which will be covered on next sections.
51 *
52 * @section tutorial_log_basic_usage Basic Usage
53 *
54 * Log messages can be displayed using the following macros:
55 *
56 * @li EINA_LOG_ERR(),
57 * @li EINA_LOG_INFO(),
58 * @li EINA_LOG_WARN(),
59 * @li EINA_LOG_DBG().
60 *
61 * Here is an example:
62 *
63 * @include eina_log_02.c
64 *
65 * If you compiled Eina without debug mode, execution will yield only one log
66 * message, which is "argument is negative".
67 *
68 * Here we introduce the concept of logging domains (or loggers), which might
69 * already be familiar to readers. It is basically a way to separate a set of
70 * log messages into a context (e.g. a module) and provide a way of controlling
71 * this set as a whole.
72 *
73 * For example, suppose you have 3 different modules on your application and you
74 * want to get logging only from one of them (e.g. create some sort of filter).
75 * For achieving that, all you need to do is create a logging domain for each
76 * module so that all logging inside a module can be considered as a whole.
77 *
78 * Logging domains are specified by a name, color applied to the name and the
79 * level. The first two (name and color) are set through code, that is, inside
80 * your application/module/library.
81 *
82 * The level is used for controlling which messages should appear. It
83 * specifies the lowest level that should be displayed (e.g. a message
84 * with level 11 being logged on a domain with level set to 10 would be
85 * displayed, while a message with level 9 wouldn't).
86 *
87 * The domain level is set during runtime (in contrast with the name and
88 * color) through the environment variable EINA_LOG_LEVELS. This variable
89 * expects a list in the form domain_name1:level1,domain_name2:level2,... . For
90 * example:
91 *
92 * @verbatim EINA_LOG_LEVELS=mymodule1:5,mymodule2:2,mymodule3:0 ./myapp@endverbatim
93 *
94 * This line would set mymodule1 level to 5, mymodule2 level to 2 and mymodule3
95 * level to 0.
96 *
97 * There's also a global logger to which EINA_LOG_(ERR, DBG, INFO, CRIT, WARN)
98 * macros do log on. It is a logger that is created internally by Eina Log with
99 * an empty name and can be used for general logging (where logging domains do
100 * not apply).
101 *
102 * Since this global logger doesn't have a name, you can't set its level through
103 * EINA_LOG_LEVELS variable. Here we introduce a second environment variable
104 * that is a bit more special: EINA_LOG_LEVEL.
105 *
106 * This variable specifies the level of the global logging domain and the level
107 * of domains that haven't been set through EINA_LOG_LEVELS. Here's an example:
108 *
109 * @verbatim EINA_LOG_LEVEL=3 EINA_LOG_LEVELS=module1:10,module3:2 ./myapp@endverbatim
110 *
111 * Supposing you have modules named "module1", "module2" and "module3", this
112 * line would result in module1 with level 10, module2 with level 3 and module3
113 * with level 2. Note that module2's level wasn't specified, so it's level is
114 * set to the global level. This way we can easily apply filters to multiple
115 * domains with only one parameter (EINA_LOG_LEVEL=num).
116 *
117 * The global level (EINA_LOG_LEVEL) can also be set through code, using
118 * eina_log_level_set() function.
119 *
120 * While developing your libraries or applications, you may notice that
121 * EINA_LOG_DOM_(ERR, DBG, INFO, CRIT, WARN) macros also print out
122 * messages from eina itself. Here we introduce another environment variable
123 * that is a bit more special: EINA_LOG_LEVELS_GLOB.
124 *
125 * This variable allows you to disable the logging of any/all code in eina itself.
126 * This is useful when developing your libraries or applications so that you can
127 * see your own domain's messages easier without having to sift through a lot of
128 * internal eina debug messages. Here's an example:
129 *
130 * @verbatim EINA_LOG_LEVEL=3 EINA_LOG_LEVELS_GLOB=eina_*:0 ./myapp@endverbatim
131 *
132 * This will disable eina_log output from all internal eina code thus allowing
133 * you to see your own domain messages easier.
134 *
135 * @section tutorial_log_advanced_display Advanced usage of print callbacks
136 *
137 * The log module allows the user to change the way
138 * eina_log_print() displays the messages. It suffices to pass to
139 * eina_log_print_cb_set() the function used to display the
140 * message. That function must be of type #Eina_Log_Print_Cb. As a
141 * custom data can be passed to that callback, powerful display
142 * messages can be displayed.
143 *
144 * It is suggested to not use __FILE__, __FUNCTION__ or __LINE__ when
145 * writing that callback, but when defining macros (like
146 * EINA_LOG_ERR() and other macros).
147 *
148 * Here is an example of custom callback, whose behavior can be
149 * changed at runtime:
150 *
151 * @include eina_log_03.c
152 * @example eina_log_02.c
153 * @example eina_log_03.c
154 */
155
156/**
157 * @addtogroup Eina_Log_Group Log
158 *
159 * @brief Full-featured logging system.
160 *
161 * Eina provides eina_log_print(), a standard function to manage all
162 * logging messages. This function may be called directly or using the
163 * helper macros such as EINA_LOG_DBG(), EINA_LOG_ERR() or those that
164 * take a specific domain as argument EINA_LOG_DOM_DBG(),
165 * EINA_LOG_DOM_ERR(). Internally, eina_log_print() will call the
166 * function defined with eina_log_print_cb_set(), that defaults to
167 * eina_log_print_cb_stderr(), but may be changed to do whatever you
168 * need, such as networking or syslog logging.
169 *
170 * The logging system is thread safe once initialized with
171 * eina_log_threads_enable(). The thread that calls this function
172 * first is considered "main thread" and other threads will have their
173 * thread id (pthread_self()) printed in the log message so it is easy
174 * to detect from where it is coming.
175 *
176 * Log domains is the Eina way to differentiate messages. There might
177 * be different domains to represent different modules, different
178 * feature-set, different categories and so on. Filtering can be
179 * applied to domain names by means of @c EINA_LOG_LEVELS environment
180 * variable or eina_log_domain_level_set().
181 *
182 * The different logging levels serve to customize the amount of
183 * debugging one want to take and may be used to automatically call
184 * abort() once some given level message is printed. This is
185 * controlled by environment variable @c EINA_LOG_ABORT and the level
186 * to be considered critical with @c EINA_LOG_ABORT_LEVEL. These can
187 * be changed with eina_log_abort_on_critical_set() and
188 * eina_log_abort_on_critical_level_set().
189 *
190 * The default maximum level to print is defined by environment
191 * variable @c EINA_LOG_LEVEL, but may be set per-domain with @c
192 * EINA_LOG_LEVELS. It will default to #EINA_LOG_ERR. This can be
193 * changed with eina_log_level_set().
194 *
195 * To use the log system Eina must be initialized with eina_init() and
196 * later shut down with eina_shutdown(). Here is a straightforward
197 * example:
198 *
199 * @include eina_log_01.c
200 *
201 * Compile this code with the following command:
202 *
203 * @verbatim gcc -Wall -o eina_log_01 eina_log_01.c `pkg-config --cflags --libs eina`@endverbatim
204 *
205 * Now execute the program with:
206 *
207 * @verbatim EINA_LOG_LEVEL=2 ./eina_log_01@endverbatim
208 *
209 * You should see a message displayed in the terminal.
210 *
211 * For more information, you can look at the @ref tutorial_log_page.
212 *
213 * @example eina_log_01.c
214 */
215
216/**
217 * @addtogroup Eina_Tools_Group Tools
218 *
219 * @{
220 */
221
222/**
223 * @defgroup Eina_Log_Group Log
224 *
225 * @{
226 */
227
228/**
229 * EINA_LOG_DOMAIN_GLOBAL is the general purpose log domain to be
230 * used, it is always registered and available everywhere.
231 */
232EAPI extern int EINA_LOG_DOMAIN_GLOBAL;
233
234#ifndef EINA_LOG_DOMAIN_DEFAULT
235
236/**
237 * @def EINA_LOG_DOMAIN_DEFAULT
238 * This macro defines the domain to use with the macros EINA_LOG_DOM_DBG(),
239 * EINA_LOG_DOM_INFO(), EINA_LOG_DOM_WARN(), EINA_LOG_DOM_ERR() and
240 * EINA_LOG_DOM_CRIT().
241 *
242 * If not defined prior to the inclusion of this header, then it
243 * defaults to #EINA_LOG_DOMAIN_GLOBAL.
244 *
245 * @note One may like to redefine this in its code to avoid typing too
246 * much. In this case the recommended way is:
247 *
248 * @code
249 * #include <Eina.h>
250 * #undef EINA_LOG_DOMAIN_DEFAULT
251 * #define EINA_LOG_DOMAIN_DEFAULT _log_dom
252 * static int _log_dom = -1;
253 *
254 * int main(void)
255 * {
256 * eina_init();
257 * _log_dom = eina_log_domain_register("mydom", EINA_COLOR_CYAN);
258 * EINA_LOG_ERR("using my own domain");
259 * return 0;
260 * }
261 * @endcode
262 *
263 * @warning If one defines the domain prior to inclusion of this
264 * header, the defined log domain symbol must be defined
265 * prior as well, otherwise the inlined functions defined by
266 * Eina will fail to find the symbol, causing build failure.
267 *
268 * @code
269 * #define EINA_LOG_DOMAIN_DEFAULT _log_dom
270 * static int _log_dom = -1; // must come before inclusion of Eina.h!
271 * #include <Eina.h>
272 *
273 * int main(void)
274 * {
275 * eina_init();
276 * _log_dom = eina_log_domain_register("mydom", EINA_COLOR_CYAN);
277 * EINA_LOG_ERR("using my own domain");
278 * return 0;
279 * }
280 * @endcode
281 *
282 */
283# define EINA_LOG_DOMAIN_DEFAULT EINA_LOG_DOMAIN_GLOBAL
284
285#endif /* EINA_LOG_DOMAIN_DEFAULT */
286
287/**
288 * @def EINA_LOG(DOM, LEVEL, fmt, ...)
289 * Logs a message on the specified domain, level and format.
290 *
291 * @note if @c EINA_LOG_LEVEL_MAXIMUM is defined, then messages larger
292 * than this value will be ignored regardless of current domain
293 * level, the eina_log_print() is not even called! Most
294 * compilers will just detect the two integers make the branch
295 * impossible and remove the branch and function call all
296 * together. Take this as optimization tip and possible remove
297 * debug messages from binaries to be deployed, saving on hot
298 * paths. Never define @c EINA_LOG_LEVEL_MAXIMUM on public
299 * header files.
300 */
301#ifdef EINA_ENABLE_LOG
302# ifdef EINA_LOG_LEVEL_MAXIMUM
303# define EINA_LOG(DOM, LEVEL, fmt, ...) \
304 do { \
305 if (LEVEL <= EINA_LOG_LEVEL_MAXIMUM) { \
306 eina_log_print(DOM, LEVEL, __FILE__, __FUNCTION__, __LINE__, \
307 fmt, ## __VA_ARGS__); } \
308 } while (0)
309# else
310# define EINA_LOG(DOM, LEVEL, fmt, ...) \
311 eina_log_print(DOM, \
312 LEVEL, \
313 __FILE__, \
314 __FUNCTION__, \
315 __LINE__, \
316 fmt, \
317 ## __VA_ARGS__)
318# endif
319#else
320#define EINA_LOG(DOM, LEVEL, fmt, ...) \
321 do { (void) DOM; (void) LEVEL; (void) fmt; } while (0)
322#endif
323
324/**
325 * @def EINA_LOG_DOM_CRIT(DOM, fmt, ...)
326 * Logs a message with level CRITICAL on the specified domain and format.
327 */
328#define EINA_LOG_DOM_CRIT(DOM, fmt, ...) \
329 EINA_LOG(DOM, EINA_LOG_LEVEL_CRITICAL, fmt, ## __VA_ARGS__)
330
331/**
332 * @def EINA_LOG_DOM_ERR(DOM, fmt, ...)
333 * Logs a message with level ERROR on the specified domain and format.
334 */
335#define EINA_LOG_DOM_ERR(DOM, fmt, ...) \
336 EINA_LOG(DOM, EINA_LOG_LEVEL_ERR, fmt, ## __VA_ARGS__)
337
338/**
339 * @def EINA_LOG_DOM_INFO(DOM, fmt, ...)
340 * Logs a message with level INFO on the specified domain and format.
341 */
342#define EINA_LOG_DOM_INFO(DOM, fmt, ...) \
343 EINA_LOG(DOM, EINA_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__)
344
345/**
346 * @def EINA_LOG_DOM_DBG(DOM, fmt, ...)
347 * Logs a message with level DEBUG on the specified domain and format.
348 */
349#define EINA_LOG_DOM_DBG(DOM, fmt, ...) \
350 EINA_LOG(DOM, EINA_LOG_LEVEL_DBG, fmt, ## __VA_ARGS__)
351
352/**
353 * @def EINA_LOG_DOM_WARN(DOM, fmt, ...)
354 * Logs a message with level WARN on the specified domain and format.
355 */
356#define EINA_LOG_DOM_WARN(DOM, fmt, ...) \
357 EINA_LOG(DOM, EINA_LOG_LEVEL_WARN, fmt, ## __VA_ARGS__)
358
359/**
360 * @def EINA_LOG_CRIT(fmt, ...)
361 * Logs a message with level CRITICAL on the default domain with the specified
362 * format.
363 */
364#define EINA_LOG_CRIT(fmt, ...) \
365 EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, \
366 EINA_LOG_LEVEL_CRITICAL, \
367 fmt, \
368 ## __VA_ARGS__)
369
370/**
371 * @def EINA_LOG_ERR(fmt, ...)
372 * Logs a message with level ERROR on the default domain with the specified
373 * format.
374 */
375#define EINA_LOG_ERR(fmt, ...) \
376 EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_ERR, fmt, ## __VA_ARGS__)
377
378/**
379 * @def EINA_LOG_INFO(fmt, ...)
380 * Logs a message with level INFO on the default domain with the specified
381 * format.
382 */
383#define EINA_LOG_INFO(fmt, ...) \
384 EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__)
385
386/**
387 * @def EINA_LOG_WARN(fmt, ...)
388 * Logs a message with level WARN on the default domain with the specified
389 * format.
390 */
391#define EINA_LOG_WARN(fmt, ...) \
392 EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_WARN, fmt, ## __VA_ARGS__)
393
394/**
395 * @def EINA_LOG_DBG(fmt, ...)
396 * Logs a message with level DEBUG on the default domain with the specified
397 * format.
398 */
399#define EINA_LOG_DBG(fmt, ...) \
400 EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_DBG, fmt, ## __VA_ARGS__)
401
402/**
403 * @typedef Eina_Log_Domain
404 * The domain used for logging.
405 */
406typedef struct _Eina_Log_Domain Eina_Log_Domain;
407
408/**
409 * @struct _Eina_Log_Domain
410 * The domain used for logging.
411 */
412struct _Eina_Log_Domain
413{
414 int level; /**< Max level to log */
415 const char *domain_str; /**< Formatted string with color to print */
416 const char *name; /**< Domain name */
417 size_t namelen; /**< strlen(name) */
418
419 /* Private */
420 Eina_Bool deleted : 1; /**< Flags deletion of domain, a free slot */
421};
422
423/**
424 * Enable logging module to handle threads.
425 *
426 * There is no disable option on purpose, if it is enabled, there is
427 * no way back until you call the last eina_shutdown().
428 *
429 * There is no function to retrieve if threads are enabled as one is
430 * not supposed to know this from outside.
431 *
432 * After this call is executed at least once, if Eina was compiled
433 * with threads support then logging will lock around debug messages
434 * and threads that are not the main thread will have its identifier
435 * printed.
436 *
437 * The main thread is considered the thread where the first
438 * eina_init() was called.
439 */
440EAPI void eina_log_threads_enable(void);
441
442/**
443 * @enum _Eina_Log_Level
444 * List of available logging levels.
445 */
446typedef enum _Eina_Log_Level
447{
448 EINA_LOG_LEVEL_CRITICAL, /**< Critical log level */
449 EINA_LOG_LEVEL_ERR, /**< Error log level */
450 EINA_LOG_LEVEL_WARN, /**< Warning log level */
451 EINA_LOG_LEVEL_INFO, /**< Information log level */
452 EINA_LOG_LEVEL_DBG, /**< Debug log level */
453 EINA_LOG_LEVELS, /**< Count of default log levels */
454 EINA_LOG_LEVEL_UNKNOWN = (-2147483647 - 1) /**< Unknown level */
455} Eina_Log_Level;
456
457/**
458 * @typedef Eina_Log_Print_Cb
459 * Type for print callbacks.
460 */
461typedef void (*Eina_Log_Print_Cb)(const Eina_Log_Domain *d,
462 Eina_Log_Level level,
463 const char *file, const char *fnc, int line,
464 const char *fmt, void *data, va_list args);
465
466/*
467 * Customization
468 */
469
470/**
471 * Sets logging method to use.
472 *
473 * @param cb The callback to call when printing a log.
474 * @param data The data to pass to the callback.
475 *
476 * By default, eina_log_print_cb_stderr() is used.
477 *
478 * @note MT: safe to call from any thread.
479 *
480 * @note MT: given function @a cb will be called protected by mutex.
481 * This means you're safe from other calls but you should never
482 * call eina_log_print(), directly or indirectly.
483 */
484EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_NONNULL(1);
485
486
487/**
488 * @brief Set the default log level.
489 *
490 * @param level The log level.
491 *
492 * This function sets the log level @p level. It is used in
493 * eina_log_print().
494 *
495 * @note this is initially set to envvar EINA_LOG_LEVEL by eina_init().
496 *
497 * @see eina_log_level_get()
498 */
499EAPI void eina_log_level_set(int level);
500
501/**
502 * @brief Get the default log level.
503 *
504 * @return the log level that limits eina_log_print().
505 *
506 * @see eina_log_level_set()
507 */
508EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT;
509
510static inline Eina_Bool eina_log_level_check(int level);
511
512/**
513 * Checks if current thread is the main thread.
514 *
515 * @return #EINA_TRUE if threads were enabled and the current thread
516 * is the one that called eina_log_threads_init(). If there is
517 * no thread support (compiled with --disable-pthreads) or
518 * they were not enabled, then #EINA_TRUE is also
519 * returned. The only case where #EINA_FALSE is returned is
520 * when threads were successfully enabled but the current
521 * thread is not the main (one that called
522 * eina_log_threads_init()).
523 */
524EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UNUSED_RESULT;
525
526
527/**
528 * @brief Set if color logging should be disabled.
529 *
530 * @param disabled if #EINA_TRUE, color logging should be disabled.
531 *
532 * @note this is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init().
533 *
534 * @see eina_log_color_disable_get()
535 */
536EAPI void eina_log_color_disable_set(Eina_Bool disabled);
537
538/**
539 * @brief Get if color logging should be disabled.
540 *
541 * @return if #EINA_TRUE, color logging should be disabled.
542 *
543 * @see eina_log_color_disable_set()
544 */
545EAPI Eina_Bool eina_log_color_disable_get(void) EINA_WARN_UNUSED_RESULT;
546
547/**
548 * @brief Set if originating file name logging should be disabled.
549 *
550 * @param disabled if #EINA_TRUE, file name logging should be disabled.
551 *
552 * @note this is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init().
553 *
554 * @see eina_log_file_disable_get()
555 */
556EAPI void eina_log_file_disable_set(Eina_Bool disabled);
557
558/**
559 * @brief Get if originating file name logging should be disabled.
560 *
561 * @return if #EINA_TRUE, file name logging should be disabled.
562 *
563 * @see eina_log_file_disable_set()
564 */
565EAPI Eina_Bool eina_log_file_disable_get(void) EINA_WARN_UNUSED_RESULT;
566
567/**
568 * @brief Set if originating function name logging should be disabled.
569 *
570 * @param disabled if #EINA_TRUE, function name logging should be disabled.
571 *
572 * @note this is initially set to envvar EINA_LOG_FUNCTION_DISABLE by
573 * eina_init().
574 *
575 * @see eina_log_function_disable_get()
576 */
577EAPI void eina_log_function_disable_set(Eina_Bool disabled);
578
579/**
580 * @brief Get if originating function name logging should be disabled.
581 *
582 * @return if #EINA_TRUE, function name logging should be disabled.
583 *
584 * @see eina_log_function_disable_set()
585 */
586EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSED_RESULT;
587
588/**
589 * @brief Set if critical messages should abort the program.
590 *
591 * @param abort_on_critical if #EINA_TRUE, messages with level equal
592 * or smaller than eina_log_abort_on_critical_level_get() will
593 * abort the program.
594 *
595 * @note this is initially set to envvar EINA_LOG_ABORT by
596 * eina_init().
597 *
598 * @see eina_log_abort_on_critical_get()
599 * @see eina_log_abort_on_critical_level_set()
600 */
601EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_critical);
602
603/**
604 * @brief Get if critical messages should abort the program.
605 *
606 * @return if #EINA_TRUE, any messages with level equal or smaller
607 * than eina_log_abort_on_critical_level_get() will abort the
608 * program.
609 *
610 * @see eina_log_abort_on_critical_set()
611 * @see eina_log_abort_on_critical_level_set()
612 */
613EAPI Eina_Bool eina_log_abort_on_critical_get(void) EINA_WARN_UNUSED_RESULT;
614
615/**
616 * @brief Set level that triggers abort if abort-on-critical is set.
617 *
618 * @param critical_level levels equal or smaller than the given value
619 * will trigger program abortion if
620 * eina_log_abort_on_critical_get() returns #EINA_TRUE.
621 *
622 * @note this is initially set to envvar EINA_LOG_ABORT_LEVEL by
623 * eina_init().
624 *
625 * @see eina_log_abort_on_critical_level_get()
626 * @see eina_log_abort_on_critical_get()
627 */
628EAPI void eina_log_abort_on_critical_level_set(int critical_level);
629
630/**
631 * @brief Get level that triggers abort if abort-on-critical is set.
632 *
633 * @return critical level equal or smaller than value will trigger
634 * program abortion if eina_log_abort_on_critical_get() returns
635 * #EINA_TRUE.
636 *
637 * @see eina_log_abort_on_critical_level_set()
638 * @see eina_log_abort_on_critical_get()
639 */
640EAPI int eina_log_abort_on_critical_level_get(void) EINA_WARN_UNUSED_RESULT;
641
642
643/**
644 * Set the domain level given its name.
645 *
646 * This call has the same effect as setting
647 * EINA_LOG_LEVELS=&lt;@p domain_name&gt;:&lt;@p level&gt;
648 *
649 * @param domain_name domain name to change the level. It may be of a
650 * still not registered domain. If the domain is not registered
651 * yet, it will be saved as a pending set and applied upon
652 * registration.
653 * @param level level to use to limit eina_log_print() for given domain.
654 */
655EAPI void eina_log_domain_level_set(const char *domain_name, int level) EINA_ARG_NONNULL(1);
656
657/**
658 * Get the domain level given its name.
659 *
660 * @param domain_name domain name to retrieve the level. It may be of
661 * a still not registered domain. If the domain is not
662 * registered yet, but there is a pending value, either from
663 * eina_log_domain_level_set(),EINA_LOG_LEVELS environment
664 * variable or from EINA_LOG_LEVELS_GLOB, these are
665 * returned. If nothing else was found, then the global/default
666 * level (eina_log_level_get()) is returned.
667 *
668 * @return level to use to limit eina_log_print() for given
669 * domain. On error (@p domain_name == NULL),
670 * EINA_LOG_LEVEL_UNKNOWN is returned.
671 *
672 * @see eina_log_domain_level_set()
673 * @see eina_log_domain_registered_level_get()
674 */
675EAPI int eina_log_domain_level_get(const char *domain_name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
676
677/**
678 * Get the domain level given its identifier.
679 *
680 * @param domain identifier, so it must be previously registered with
681 * eina_log_domain_register(). It's a much faster version of
682 * eina_log_domain_level_get(), but relies on domain being
683 * present.
684 *
685 * @return level to use to limit eina_log_print() for given domain. On
686 * error EINA_LOG_LEVEL_UNKNOWN is returned.
687 */
688EAPI int eina_log_domain_registered_level_get(int domain) EINA_WARN_UNUSED_RESULT;
689
690static inline Eina_Bool eina_log_domain_level_check(int domain, int level);
691
692/*
693 * Logging domains
694 */
695
696/**
697 * @param name Domain name
698 * @param color Color of the domain name
699 *
700 * @return Domain index that will be used as the DOMAIN parameter on log
701 * macros. A negative return value means an log occurred.
702 *
703 * @note MT: safe to call from any thread.
704 */
705EAPI int eina_log_domain_register(const char *name, const char *color) EINA_ARG_NONNULL(1);
706
707/**
708 * Forget about a logging domain registered by eina_log_domain_register()
709 *
710 * @param domain domain identifier as reported by eina_log_domain_register(),
711 * must be >= 0.
712 *
713 * @note MT: safe to call from any thread.
714 */
715EAPI void eina_log_domain_unregister(int domain);
716
717/*
718 * Logging functions.
719 */
720
721/**
722 * Print out log message using given domain and level.
723 *
724 * @note Usually you'll not use this function directly but the helper
725 * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
726 * so on. See eina_log.h
727 *
728 * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
729 * you registered none. It is recommended that modules and
730 * applications have their own logging domain.
731 * @param level message level, those with level greater than user
732 * specified value (eina_log_level_set() or environment
733 * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
734 * @param file filename that originated the call, must @b not be @c NULL.
735 * @param function function that originated the call, must @b not be @c NULL.
736 * @param line originating line in @a file.
737 * @param fmt printf-like format to use. Should not provide trailing
738 * '\n' as it is automatically included.
739 *
740 * @note MT: this function may be called from different threads if
741 * eina_log_threads_enable() was called before.
742 */
743EAPI void eina_log_print(int domain,
744 Eina_Log_Level level,
745 const char *file,
746 const char *function,
747 int line,
748 const char *fmt,
749 ...) EINA_ARG_NONNULL(3, 4, 6) EINA_PRINTF(6, 7) EINA_NOINSTRUMENT;
750
751/**
752 * Print out log message using given domain and level.
753 *
754 * @note Usually you'll not use this function directly but the helper
755 * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
756 * so on. See eina_log.h
757 *
758 * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
759 * you registered none. It is recommended that modules and
760 * applications have their own logging domain.
761 * @param level message level, those with level greater than user
762 * specified value (eina_log_level_set() or environment
763 * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
764 * @param file filename that originated the call, must @b not be @c NULL.
765 * @param fnc function that originated the call, must @b not be @c NULL.
766 * @param line originating line in @a file.
767 * @param fmt printf-like format to use. Should not provide trailing
768 * '\n' as it is automatically included.
769 * @param args the arguments needed by the format.
770 *
771 * @note MT: this function may be called from different threads if
772 * eina_log_threads_enable() was called before.
773 *
774 * @see eina_log_print()
775 */
776EAPI void eina_log_vprint(int domain,
777 Eina_Log_Level level,
778 const char *file,
779 const char *fnc,
780 int line,
781 const char *fmt,
782 va_list args) EINA_ARG_NONNULL(3, 4, 6) EINA_NOINSTRUMENT;
783
784/*
785 * Logging methods (change how logging is done).
786 */
787
788/**
789 * @brief Alternative logging method, this will output to standard output stream.
790 *
791 * @param d The domain.
792 * @param level The level.
793 * @param file The file which is logged.
794 * @param fnc The function which is logged.
795 * @param line The line which is logged.
796 * @param fmt The ouptut format to use.
797 * @param data Not used.
798 * @param args The arguments needed by the format.
799 *
800 * This method will colorize output based on domain provided color and
801 * message logging level. To disable color, set environment variable
802 * EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line
803 * information, set EINA_LOG_FILE_DISABLE=1 or
804 * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is
805 * not acceptable to have both EINA_LOG_FILE_DISABLE and
806 * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just
807 * EINA_LOG_FUNCTION_DISABLE will be considered and file information
808 * will be printed anyways.
809 *
810 * @note MT: if threads are enabled, this function is called within locks.
811 * @note MT: Threads different from main thread will have thread id
812 * appended to domain name.
813 */
814EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d,
815 Eina_Log_Level level,
816 const char *file,
817 const char *fnc,
818 int line,
819 const char *fmt,
820 void *data,
821 va_list args);
822
823/**
824 * @brief Default logging method, this will output to standard error stream.
825 *
826 * @param d The domain.
827 * @param level The level.
828 * @param file The file which is logged.
829 * @param fnc The function which is logged.
830 * @param line The line which is logged.
831 * @param fmt The ouptut format to use.
832 * @param data Not used.
833 * @param args The arguments needed by the format.
834 *
835 * This method will colorize output based on domain provided color and
836 * message logging level.
837 *
838 * To disable color, set environment variable
839 * EINA_LOG_COLOR_DISABLE=1. To enable color, even if directing to a
840 * file or when using a non-supported color terminal, use
841 * EINA_LOG_COLOR_DISABLE=0. If EINA_LOG_COLOR_DISABLE is unset (or
842 * -1), then Eina will disable color if terminal ($TERM) is
843 * unsupported or if redirecting to a file.
844
845 . Similarly, to disable file and line
846 * information, set EINA_LOG_FILE_DISABLE=1 or
847 * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is
848 * not acceptable to have both EINA_LOG_FILE_DISABLE and
849 * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just
850 * EINA_LOG_FUNCTION_DISABLE will be considered and file information
851 * will be printed anyways.
852 *
853 * @note MT: if threads are enabled, this function is called within locks.
854 * @note MT: Threads different from main thread will have thread id
855 * appended to domain name.
856 */
857EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d,
858 Eina_Log_Level level,
859 const char *file,
860 const char *fnc,
861 int line,
862 const char *fmt,
863 void *data,
864 va_list args);
865
866/**
867 * Alternative logging method, this will output to given file stream.
868 *
869 * @param d The domain.
870 * @param level Not used.
871 * @param file The file which is logged.
872 * @param fnc The function which is logged.
873 * @param line The line which is logged.
874 * @param fmt The ouptut format to use.
875 * @param data The file which will store the output (as a FILE *).
876 * @param args The arguments needed by the format.
877 *
878 * This method will never output color.
879 *
880 * @note MT: if threads are enabled, this function is called within locks.
881 * @note MT: Threads different from main thread will have thread id
882 * appended to domain name.
883 */
884EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d,
885 Eina_Log_Level level,
886 const char *file,
887 const char *fnc,
888 int line,
889 const char *fmt,
890 void *data,
891 va_list args);
892
893#include "eina_inline_log.x"
894
895/**
896 * @}
897 */
898
899/**
900 * @}
901 */
902
903#endif /* EINA_LOG_H_ */
generated by cgit v1.1 at 2024-08-27 20:35:21 +0000