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