src/include/eina_log.h

   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 on 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 on 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__, __FUNCTION__ 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__, __FUNCTION__, __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                  __FUNCTION__,          \
 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
 424 /**
 425  * Enable logging module to handle threads.
 426  *
 427  * There is no disable option on purpose, if it is enabled, there is
 428  * no way back until you call the last eina_shutdown().
 429  *
 430  * There is no function to retrieve if threads are enabled as one is
 431  * not supposed to know this from outside.
 432  *
 433  * After this call is executed at least once, if Eina was compiled
 434  * with threads support then logging will lock around debug messages
 435  * and threads that are not the main thread will have its identifier
 436  * printed.
 437  *
 438  * The main thread is considered the thread where the first
 439  * eina_init() was called.
 440  */
 441 EAPI void eina_log_threads_enable(void);
 442
 443 /**
 444  * @enum _Eina_Log_Level
 445  * List of available logging levels.
 446  */
 447 typedef enum _Eina_Log_Level
 448 {
 449    EINA_LOG_LEVEL_CRITICAL, /**< Critical log level */
 450    EINA_LOG_LEVEL_ERR, /**< Error log level */
 451    EINA_LOG_LEVEL_WARN, /**< Warning log level */
 452    EINA_LOG_LEVEL_INFO, /**< Information log level */
 453    EINA_LOG_LEVEL_DBG, /**< Debug log level */
 454    EINA_LOG_LEVELS, /**< Count of default log levels */
 455    EINA_LOG_LEVEL_UNKNOWN = (-2147483647 - 1) /**< Unknown level */
 456 } Eina_Log_Level;
 457
 458 /**
 459  * @typedef Eina_Log_Print_Cb
 460  * Type for print callbacks.
 461  */
 462 typedef void (*Eina_Log_Print_Cb)(const Eina_Log_Domain *d,
 463                                   Eina_Log_Level level,
 464                                   const char *file, const char *fnc, int line,
 465                                   const char *fmt, void *data, va_list args);
 466
 467 /*
 468  * Customization
 469  */
 470
 471 /**
 472  * Sets logging method to use.
 473  *
 474  * @param cb The callback to call when printing a log.
 475  * @param data The data to pass to the callback.
 476  *
 477  * By default, eina_log_print_cb_stderr() is used.
 478  *
 479  * @note MT: safe to call from any thread.
 480  *
 481  * @note MT: given function @a cb will be called protected by mutex.
 482  *       This means you're safe from other calls but you should never
 483  *       call eina_log_print(), directly or indirectly.
 484  */
 485 EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_NONNULL(1);
 486
 487
 488 /**
 489  * @brief Set the default log level.
 490  *
 491  * @param level The log level.
 492  *
 493  * This function sets the log level @p level. It is used in
 494  * eina_log_print().
 495  *
 496  * @note this is initially set to envvar EINA_LOG_LEVEL by eina_init().
 497  *
 498  * @see eina_log_level_get()
 499  */
 500 EAPI void eina_log_level_set(int level);
 501
 502 /**
 503  * @brief Get the default log level.
 504  *
 505  * @return the log level that limits eina_log_print().
 506  *
 507  * @see eina_log_level_set()
 508  */
 509 EAPI int  eina_log_level_get(void) EINA_WARN_UNUSED_RESULT;
 510
 511 static inline Eina_Bool eina_log_level_check(int level);
 512
 513 /**
 514  * Checks if current thread is the main thread.
 515  *
 516  * @return #EINA_TRUE if threads were enabled and the current thread
 517  *         is the one that called eina_log_threads_init(). If there is
 518  *         no thread support (compiled with --disable-pthreads) or
 519  *         they were not enabled, then #EINA_TRUE is also
 520  *         returned. The only case where #EINA_FALSE is returned is
 521  *         when threads were successfully enabled but the current
 522  *         thread is not the main (one that called
 523  *         eina_log_threads_init()).
 524  */
 525 EAPI Eina_Bool          eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UNUSED_RESULT;
 526
 527
 528 /**
 529  * @brief Set if color logging should be disabled.
 530  *
 531  * @param disabled if #EINA_TRUE, color logging should be disabled.
 532  *
 533  * @note this is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init().
 534  *
 535  * @see eina_log_color_disable_get()
 536  */
 537 EAPI void               eina_log_color_disable_set(Eina_Bool disabled);
 538
 539 /**
 540  * @brief Get if color logging should be disabled.
 541  *
 542  * @return if #EINA_TRUE, color logging should be disabled.
 543  *
 544  * @see eina_log_color_disable_set()
 545  */
 546 EAPI Eina_Bool          eina_log_color_disable_get(void) EINA_WARN_UNUSED_RESULT;
 547
 548 /**
 549  * @brief Set if originating file name logging should be disabled.
 550  *
 551  * @param disabled if #EINA_TRUE, file name logging should be disabled.
 552  *
 553  * @note this is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init().
 554  *
 555  * @see eina_log_file_disable_get()
 556  */
 557 EAPI void               eina_log_file_disable_set(Eina_Bool disabled);
 558
 559 /**
 560  * @brief Get if originating file name logging should be disabled.
 561  *
 562  * @return if #EINA_TRUE, file name logging should be disabled.
 563  *
 564  * @see eina_log_file_disable_set()
 565  */
 566 EAPI Eina_Bool          eina_log_file_disable_get(void) EINA_WARN_UNUSED_RESULT;
 567
 568 /**
 569  * @brief Set if originating function name logging should be disabled.
 570  *
 571  * @param disabled if #EINA_TRUE, function name logging should be disabled.
 572  *
 573  * @note this is initially set to envvar EINA_LOG_FUNCTION_DISABLE by
 574  *       eina_init().
 575  *
 576  * @see eina_log_function_disable_get()
 577  */
 578 EAPI void               eina_log_function_disable_set(Eina_Bool disabled);
 579
 580 /**
 581  * @brief Get if originating function name logging should be disabled.
 582  *
 583  * @return if #EINA_TRUE, function name logging should be disabled.
 584  *
 585  * @see eina_log_function_disable_set()
 586  */
 587 EAPI Eina_Bool          eina_log_function_disable_get(void) EINA_WARN_UNUSED_RESULT;
 588
 589 /**
 590  * @brief Set if critical messages should abort the program.
 591  *
 592  * @param abort_on_critical if #EINA_TRUE, messages with level equal
 593  *        or smaller than eina_log_abort_on_critical_level_get() will
 594  *        abort the program.
 595  *
 596  * @note this is initially set to envvar EINA_LOG_ABORT by
 597  *       eina_init().
 598  *
 599  * @see eina_log_abort_on_critical_get()
 600  * @see eina_log_abort_on_critical_level_set()
 601  */
 602 EAPI void               eina_log_abort_on_critical_set(Eina_Bool abort_on_critical);
 603
 604 /**
 605  * @brief Get if critical messages should abort the program.
 606  *
 607  * @return if #EINA_TRUE, any messages with level equal or smaller
 608  *         than eina_log_abort_on_critical_level_get() will abort the
 609  *         program.
 610  *
 611  * @see eina_log_abort_on_critical_set()
 612  * @see eina_log_abort_on_critical_level_set()
 613  */
 614 EAPI Eina_Bool          eina_log_abort_on_critical_get(void) EINA_WARN_UNUSED_RESULT;
 615
 616 /**
 617  * @brief Set level that triggers abort if abort-on-critical is set.
 618  *
 619  * @param critical_level levels equal or smaller than the given value
 620  *        will trigger program abortion if
 621  *        eina_log_abort_on_critical_get() returns #EINA_TRUE.
 622  *
 623  * @note this is initially set to envvar EINA_LOG_ABORT_LEVEL by
 624  *       eina_init().
 625  *
 626  * @see eina_log_abort_on_critical_level_get()
 627  * @see eina_log_abort_on_critical_get()
 628  */
 629 EAPI void               eina_log_abort_on_critical_level_set(int critical_level);
 630
 631 /**
 632  * @brief Get level that triggers abort if abort-on-critical is set.
 633  *
 634  * @return critical level equal or smaller than value will trigger
 635  *        program abortion if eina_log_abort_on_critical_get()
 636  *        returns #EINA_TRUE.
 637  *
 638  * @see eina_log_abort_on_critical_level_set()
 639  * @see eina_log_abort_on_critical_get()
 640  */
 641 EAPI int                eina_log_abort_on_critical_level_get(void) EINA_WARN_UNUSED_RESULT;
 642
 643
 644 /**
 645  * Set the domain level given its name.
 646  *
 647  * This call has the same effect as setting
 648  * EINA_LOG_LEVELS=&lt;@p domain_name&gt;:&lt;@p level&gt;
 649  *
 650  * @param domain_name domain name to change the level. It may be of a
 651  *        still not registered domain. If the domain is not registered
 652  *        yet, it will be saved as a pending set and applied upon
 653  *        registration.
 654  * @param level level to use to limit eina_log_print() for given domain.
 655  */
 656 EAPI void               eina_log_domain_level_set(const char *domain_name, int level) EINA_ARG_NONNULL(1);
 657
 658 /**
 659  * Get the domain level given its name.
 660  *
 661  * @param domain_name domain name to retrieve the level. It may be of
 662  *        a still not registered domain. If the domain is not
 663  *        registered yet, but there is a pending value, either from
 664  *        eina_log_domain_level_set(),EINA_LOG_LEVELS environment
 665  *        variable or from EINA_LOG_LEVELS_GLOB, these are
 666  *        returned. If nothing else was found, then the global/default
 667  *        level (eina_log_level_get()) is returned.
 668  *
 669  * @return level to use to limit eina_log_print() for given
 670  *         domain. On error (@p domain_name == NULL),
 671  *         EINA_LOG_LEVEL_UNKNOWN is returned.
 672  *
 673  * @see eina_log_domain_level_set()
 674  * @see eina_log_domain_registered_level_get()
 675  */
 676 EAPI int                eina_log_domain_level_get(const char *domain_name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 677
 678 /**
 679  * Get the domain level given its identifier.
 680  *
 681  * @param domain identifier, so it must be previously registered with
 682  *        eina_log_domain_register(). It's a much faster version of
 683  *        eina_log_domain_level_get(), but relies on domain being
 684  *        present.
 685  *
 686  * @return #EINA_TRUE if level should be printed, #EINA_FALSE if not.
 687  *         (domain's level is greater or equal @a level).
 688  */
 689 EAPI int                eina_log_domain_registered_level_get(int domain) EINA_WARN_UNUSED_RESULT;
 690
 691 static inline Eina_Bool eina_log_domain_level_check(int domain, int level);
 692
 693 /*
 694  * Logging domains
 695  */
 696
 697 /**
 698  * @param name Domain name
 699  * @param color Color of the domain name
 700  *
 701  * @return Domain index that will be used as the DOMAIN parameter on log
 702  *         macros. A negative return value means an log occurred.
 703  *
 704  * @note MT: safe to call from any thread.
 705  */
 706 EAPI int  eina_log_domain_register(const char *name, const char *color) EINA_ARG_NONNULL(1);
 707
 708 /**
 709  * Forget about a logging domain registered by eina_log_domain_register()
 710  *
 711  * @param domain domain identifier as reported by eina_log_domain_register(),
 712  *        must be >= 0.
 713  *
 714  * @note MT: safe to call from any thread.
 715  */
 716 EAPI void eina_log_domain_unregister(int domain);
 717
 718 /*
 719  * Logging functions.
 720  */
 721
 722 /**
 723  * Print out log message using given domain and level.
 724  *
 725  * @note Usually you'll not use this function directly but the helper
 726  *       macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
 727  *       so on. See eina_log.h
 728  *
 729  * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
 730  *        you registered none. It is recommended that modules and
 731  *        applications have their own logging domain.
 732  * @param level message level, those with level greater than user
 733  *        specified value (eina_log_level_set() or environment
 734  *        variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
 735  * @param file filename that originated the call, must @b not be @c NULL.
 736  * @param function function that originated the call, must @b not be @c NULL.
 737  * @param line originating line in @a file.
 738  * @param fmt printf-like format to use. Should not provide trailing
 739  *        '\n' as it is automatically included.
 740  *
 741  * @note MT: this function may be called from different threads if
 742  *       eina_log_threads_enable() was called before.
 743  */
 744 EAPI void eina_log_print(int            domain,
 745                          Eina_Log_Level level,
 746                          const char    *file,
 747                          const char    *function,
 748                          int            line,
 749                          const char    *fmt,
 750                          ...) EINA_ARG_NONNULL(3, 4, 6) EINA_PRINTF(6, 7) EINA_NOINSTRUMENT;
 751
 752 /**
 753  * Print out log message using given domain and level.
 754  *
 755  * @note Usually you'll not use this function directly but the helper
 756  *       macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
 757  *       so on. See eina_log.h
 758  *
 759  * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
 760  *        you registered none. It is recommended that modules and
 761  *        applications have their own logging domain.
 762  * @param level message level, those with level greater than user
 763  *        specified value (eina_log_level_set() or environment
 764  *        variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
 765  * @param file filename that originated the call, must @b not be @c NULL.
 766  * @param fnc function that originated the call, must @b not be @c NULL.
 767  * @param line originating line in @a file.
 768  * @param fmt printf-like format to use. Should not provide trailing
 769  *        '\n' as it is automatically included.
 770  * @param args the arguments needed by the format.
 771  *
 772  * @note MT: this function may be called from different threads if
 773  *       eina_log_threads_enable() was called before.
 774  *
 775  * @see eina_log_print()
 776  */
 777 EAPI void eina_log_vprint(int            domain,
 778                           Eina_Log_Level level,
 779                           const char    *file,
 780                           const char    *fnc,
 781                           int            line,
 782                           const char    *fmt,
 783                           va_list        args) EINA_ARG_NONNULL(3, 4, 6) EINA_NOINSTRUMENT;
 784
 785 /*
 786  * Logging methods (change how logging is done).
 787  */
 788
 789 /**
 790  * @brief Alternative logging method, this will output to standard output stream.
 791  *
 792  * @param d The domain.
 793  * @param level The level.
 794  * @param file The file which is logged.
 795  * @param fnc The function which is logged.
 796  * @param line The line which is logged.
 797  * @param fmt The ouptut format to use.
 798  * @param data Not used.
 799  * @param args The arguments needed by the format.
 800  *
 801  * This method will colorize output based on domain provided color and
 802  * message logging level. To disable color, set environment variable
 803  * EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line
 804  * information, set EINA_LOG_FILE_DISABLE=1 or
 805  * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is
 806  * not acceptable to have both EINA_LOG_FILE_DISABLE and
 807  * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just
 808  * EINA_LOG_FUNCTION_DISABLE will be considered and file information
 809  * will be printed anyways.
 810  *
 811  * @note MT: if threads are enabled, this function is called within locks.
 812  * @note MT: Threads different from main thread will have thread id
 813  *       appended to domain name.
 814  */
 815 EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d,
 816                                    Eina_Log_Level         level,
 817                                    const char            *file,
 818                                    const char            *fnc,
 819                                    int                    line,
 820                                    const char            *fmt,
 821                                    void                  *data,
 822                                    va_list                args);
 823
 824 /**
 825  * @brief Default logging method, this will output to standard error stream.
 826  *
 827  * @param d The domain.
 828  * @param level The level.
 829  * @param file The file which is logged.
 830  * @param fnc The function which is logged.
 831  * @param line The line which is logged.
 832  * @param fmt The ouptut format to use.
 833  * @param data Not used.
 834  * @param args The arguments needed by the format.
 835  *
 836  * This method will colorize output based on domain provided color and
 837  * message logging level.
 838  *
 839  * To disable color, set environment variable
 840  * EINA_LOG_COLOR_DISABLE=1. To enable color, even if directing to a
 841  * file or when using a non-supported color terminal, use
 842  * EINA_LOG_COLOR_DISABLE=0. If EINA_LOG_COLOR_DISABLE is unset (or
 843  * -1), then Eina will disable color if terminal ($TERM) is
 844  * unsupported or if redirecting to a file.
 845
 846    . Similarly, to disable file and line
 847  * information, set EINA_LOG_FILE_DISABLE=1 or
 848  * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is
 849  * not acceptable to have both EINA_LOG_FILE_DISABLE and
 850  * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just
 851  * EINA_LOG_FUNCTION_DISABLE will be considered and file information
 852  * will be printed anyways.
 853  *
 854  * @note MT: if threads are enabled, this function is called within locks.
 855  * @note MT: Threads different from main thread will have thread id
 856  *       appended to domain name.
 857  */
 858 EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d,
 859                                    Eina_Log_Level         level,
 860                                    const char            *file,
 861                                    const char            *fnc,
 862                                    int                    line,
 863                                    const char            *fmt,
 864                                    void                  *data,
 865                                    va_list                args);
 866
 867 /**
 868  * Alternative logging method, this will output to given file stream.
 869  *
 870  * @param d The domain.
 871  * @param level Not used.
 872  * @param file The file which is logged.
 873  * @param fnc The function which is logged.
 874  * @param line The line which is logged.
 875  * @param fmt The ouptut format to use.
 876  * @param data The file which will store the output (as a FILE *).
 877  * @param args The arguments needed by the format.
 878  *
 879  * This method will never output color.
 880  *
 881  * @note MT: if threads are enabled, this function is called within locks.
 882  * @note MT: Threads different from main thread will have thread id
 883  *       appended to domain name.
 884  */
 885 EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d,
 886                                  Eina_Log_Level         level,
 887                                  const char            *file,
 888                                  const char            *fnc,
 889                                  int                    line,
 890                                  const char            *fmt,
 891                                  void                  *data,
 892                                  va_list                args);
 893
 894 /**
 895  * Configure console color of given file.
 896  *
 897  * @param fp file to configure console color (usually stderr or stdout).
 898  * @param color a VT color code such as #EINA_COLOR_RED or #EINA_COLOR_RESET.
 899  *
 900  * @note if color is disabled, nothing is done. See
 901  *       eina_log_color_disable_get()
 902  * @note on windows, both @a fp and @a color is converted automatically.
 903  *
 904  * @since 1.7
 905  */
 906 EAPI void eina_log_console_color_set(FILE *fp,
 907                                      const char *color) EINA_ARG_NONNULL(1, 2);
 908
 909 #include "eina_inline_log.x"
 910
 911 /**
 912  * @}
 913  */
 914
 915 /**
 916  * @}
 917  */
 918
 919 #endif /* EINA_LOG_H_ */