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