Log
[Tools]
The default log level value is set by default to EINA_LOG_LEVEL_DBG if Eina is compiled with debug mode, or to EINA_LOG_LEVEL_ERR otherwise. More...
Data Structures | |
struct | _Eina_Log_Domain |
Defines | |
#define | EINA_LOG(DOM, LEVEL, fmt,...) eina_log_print(DOM, LEVEL, __FILE__, __FUNCTION__, __LINE__, fmt, ##__VA_ARGS__) |
Logs a message on the specified domain, level and format. | |
#define | EINA_LOG_DOM_CRIT(DOM, fmt,...) EINA_LOG(DOM, EINA_LOG_LEVEL_CRITICAL, fmt, ##__VA_ARGS__) |
Logs a message with level CRITICAL on the specified domain and format. | |
#define | EINA_LOG_DOM_ERR(DOM, fmt,...) EINA_LOG(DOM, EINA_LOG_LEVEL_ERR, fmt, ##__VA_ARGS__) |
Logs a message with level ERROR on the specified domain and format. | |
#define | EINA_LOG_DOM_INFO(DOM, fmt,...) EINA_LOG(DOM, EINA_LOG_LEVEL_INFO, fmt, ##__VA_ARGS__) |
Logs a message with level INFO on the specified domain and format. | |
#define | EINA_LOG_DOM_DBG(DOM, fmt,...) EINA_LOG(DOM, EINA_LOG_LEVEL_DBG, fmt, ##__VA_ARGS__) |
Logs a message with level DEBUG on the specified domain and format. | |
#define | EINA_LOG_DOM_WARN(DOM, fmt,...) EINA_LOG(DOM, EINA_LOG_LEVEL_WARN, fmt, ##__VA_ARGS__) |
Logs a message with level WARN on the specified domain and format. | |
#define | EINA_LOG_CRIT(fmt,...) EINA_LOG(EINA_LOG_DOMAIN_GLOBAL, EINA_LOG_LEVEL_CRITICAL, fmt, ##__VA_ARGS__) |
Logs a message with level CRITICAL on the global domain with the specified format. | |
#define | EINA_LOG_ERR(fmt,...) EINA_LOG(EINA_LOG_DOMAIN_GLOBAL, EINA_LOG_LEVEL_ERR, fmt, ##__VA_ARGS__) |
Logs a message with level ERROR on the global domain with the specified format. | |
#define | EINA_LOG_INFO(fmt,...) EINA_LOG(EINA_LOG_DOMAIN_GLOBAL, EINA_LOG_LEVEL_INFO, fmt, ##__VA_ARGS__) |
Logs a message with level INFO on the global domain with the specified format. | |
#define | EINA_LOG_WARN(fmt,...) EINA_LOG(EINA_LOG_DOMAIN_GLOBAL, EINA_LOG_LEVEL_WARN, fmt, ##__VA_ARGS__) |
Logs a message with level WARN on the global domain with the specified format. | |
#define | EINA_LOG_DBG(fmt,...) EINA_LOG(EINA_LOG_DOMAIN_GLOBAL, EINA_LOG_LEVEL_DBG, fmt, ##__VA_ARGS__) |
Logs a message with level DEBUG on the global domain with the specified format. | |
Typedefs | |
typedef struct _Eina_Log_Domain | Eina_Log_Domain |
typedef enum _Eina_Log_Level | Eina_Log_Level |
typedef void(* | Eina_Log_Print_Cb )(const Eina_Log_Domain *d, Eina_Log_Level level, const char *file, const char *fnc, int line, const char *fmt, void *data, va_list args) |
Type for print callbacks. | |
Enumerations | |
enum | _Eina_Log_Level { EINA_LOG_LEVEL_CRITICAL, EINA_LOG_LEVEL_ERR, EINA_LOG_LEVEL_WARN, EINA_LOG_LEVEL_INFO, EINA_LOG_LEVEL_DBG, EINA_LOG_LEVELS, EINA_LOG_LEVEL_UNKNOWN = (-2147483647-1) } |
List of available logging levels. More... | |
Functions | |
EAPI void | eina_log_threads_enable (void) |
Enable logging module to handle threads. | |
EAPI void | eina_log_print_cb_set (Eina_Log_Print_Cb cb, void *data) |
Sets logging method to use. | |
EAPI void | eina_log_level_set (Eina_Log_Level level) |
Set the default log log level. | |
EAPI int | eina_log_domain_register (const char *name, const char *color) |
EAPI void | eina_log_domain_unregister (int domain) |
Forget about a logging domain registered by eina_log_domain_register(). | |
EAPI void | eina_log_print (int domain, Eina_Log_Level level, const char *file, const char *fnc, int line, const char *fmt,...) |
Print out log message using given domain and level. | |
EAPI void | EINA_PRINTF (6, 7) EINA_NOINSTRUMENT |
EAPI void | eina_log_vprint (int domain, Eina_Log_Level level, const char *file, const char *fnc, int line, const char *fmt, va_list args) |
Print out log message using given domain and level. | |
EAPI void | eina_log_print_cb_stdout (const Eina_Log_Domain *d, Eina_Log_Level level, const char *file, const char *fnc, int line, const char *fmt, void *data, va_list args) |
Alternative logging method, this will output to standard output stream. | |
EAPI void | eina_log_print_cb_stderr (const Eina_Log_Domain *d, Eina_Log_Level level, const char *file, const char *fnc, int line, const char *fmt, void *data, va_list args) |
Default logging method, this will output to standard error stream. | |
EAPI void | eina_log_print_cb_file (const Eina_Log_Domain *d, Eina_Log_Level level, const char *file, const char *fnc, int line, const char *fmt, void *data, va_list args) |
Alternative logging method, this will output to given file stream. | |
Eina_Bool | eina_log_init (void) |
Eina_Bool | eina_log_shutdown (void) |
static int | eina_log_domain_register_unlocked (const char *name, const char *color) |
static void | eina_log_domain_unregister_unlocked (int domain) |
static void | eina_log_print_unlocked (int domain, Eina_Log_Level level, const char *file, const char *fnc, int line, const char *fmt, va_list args) |
Variables | |
EAPI int | EINA_LOG_DOMAIN_GLOBAL |
EAPI void | EINA_NOINSTRUMENT |
Detailed Description
The default log level value is set by default to EINA_LOG_LEVEL_DBG if Eina is compiled with debug mode, or to EINA_LOG_LEVEL_ERR otherwise.
These functions provide log management for projects.
That value can be overwritten by setting the environment variable EINA_LOG_LEVEL. This function checks the value of that environment variable in the first call. Its value must be a number between 0 and 4, to match the log levels EINA_LOG_LEVEL_CRITICAL, EINA_LOG_LEVEL_ERR, EINA_LOG_LEVEL_WARN, EINA_LOG_LEVEL_INFO and EINA_LOG_LEVEL_DBG. That value can also be set later with eina_log_log_level_set(). When logging domains are created, they will get either this value or specific value given with EINA_LOG_LEVELS that takes the format 'domain_name:level,another_name:other_level'.
Format and verbosity of messages depend on the logging method, see eina_log_print_cb_set(). The default logging method is eina_log_print_cb_stderr(), which will output fancy colored messages to standard error stream. See its documentation on how to disable coloring, function or file/line print.
This module will optionally abort program execution if message level is below or equal to EINA_LOG_LEVEL_CRITICAL
and EINA_LOG_ABORT=1
.
To use the log system Eina must be initialized with eina_init() and later shut down with eina_shutdown(). The most generic way to print logs is to use eina_log_print() but the helper macros EINA_LOG_ERR(), EINA_LOG_INFO(), EINA_LOG_WARN() and EINA_LOG_DBG() should be used instead.
Here is a straightforward example:
#include <stdlib.h> #include <stdio.h> #include <eina_log.h> void test_warn(void) { EINA_LOG_WARN("Here is a warning message"); } int main(void) { if (!eina_init()) { printf("log during the initialization of Eina_Log module\n"); return EXIT_FAILURE; } test_warn(); eina_shutdown(); return EXIT_SUCCESS; }
Compile this code with the following command:
gcc -Wall -o test_Eina_Log test_eina.c `pkg-config --cflags --libs eina`
If Eina is compiled without debug mode, then executing the resulting program displays nothing because the default log level is EINA_LOG_LEVEL_ERR and we want to display a warning message, which level is strictly greater than the log level (see eina_log_print() for more informations). Now execute the program with:
EINA_LOG_LEVEL=2 ./test_eina_log
You should see a message displayed in the terminal.
For more information, you can look at the log Tutorial.
Define Documentation
#define EINA_LOG | ( | DOM, | |||
LEVEL, | |||||
fmt, | |||||
... | ) | eina_log_print(DOM, LEVEL, __FILE__, __FUNCTION__, __LINE__, fmt, ##__VA_ARGS__) |
Logs a message on the specified domain, level and format.
- Note:
- if
EINA_LOG_LEVEL_MAXIMUM
is defined, then messages larger than this value will be ignored regardless of current domain level, the eina_log_print() is not even called! Most compilers will just detect the two integers make the branch impossible and remove the branch and function call all together. Take this as optimization tip and possible remove debug messages from binaries to be deployed, saving on hot paths. Never defineEINA_LOG_LEVEL_MAXIMUM
on public header files.
Enumeration Type Documentation
enum _Eina_Log_Level |
List of available logging levels.
Function Documentation
EAPI void eina_log_threads_enable | ( | void | ) |
Enable logging module to handle threads.
There is no disable option on purpose, if it is enabled, there is no way back until you call the last eina_shutdown().
There is no function to retrieve if threads are enabled as one is not supposed to know this from outside.
After this call is executed at least once, if Eina was compiled with threads support then logging will lock around debug messages and threads that are not the main thread will have its identifier printed.
The main thread is considered the thread where the first eina_init() was called.
EAPI void eina_log_print_cb_set | ( | Eina_Log_Print_Cb | cb, | |
void * | data | |||
) |
Sets logging method to use.
By default, eina_log_print_cb_stderr() is used.
- Note:
- MT: safe to call from any thread.
- MT: given function cb will be called protected by mutex. This means you're safe from other calls but you should never call eina_log_print(), directly or indirectly.
EAPI void eina_log_level_set | ( | Eina_Log_Level | level | ) |
Set the default log log level.
- Parameters:
-
level The log level.
This function sets the log log level level
. It is used in eina_log_print().
EAPI int eina_log_domain_register | ( | const char * | name, | |
const char * | color | |||
) |
- Parameters:
-
name Domain name color Color of the domain name
- Returns:
- Domain index that will be used as the DOMAIN parameter on log macros. A negative return value means an log ocurred.
- Note:
- MT: safe to call from any thread.
EAPI void eina_log_domain_unregister | ( | int | domain | ) |
Forget about a logging domain registered by eina_log_domain_register().
- Parameters:
-
domain domain identifier as reported by eina_log_domain_register(), must be >= 0.
- Note:
- MT: safe to call from any thread.
EAPI void eina_log_print | ( | int | domain, | |
Eina_Log_Level | level, | |||
const char * | file, | |||
const char * | fnc, | |||
int | line, | |||
const char * | fmt, | |||
... | ||||
) |
Print out log message using given domain and level.
- Note:
- Usually you'll not use this function directly but the helper macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and so on. See eina_log.h
- Parameters:
-
domain logging domain to use or EINA_LOG_DOMAIN_GLOBAL
if you registered none. It is recommended that modules and applications have their own logging domain.level message level, those with level greater than user specified value (eina_log_level_set() or environment variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored. file filename that originated the call, must not be NULL
.fnc function that originated the call, must not be NULL
.line originating line in file. fmt printf-like format to use. Should not provide trailing '
' as it is automatically included.
- Note:
- MT: this function may be called from different threads if eina_log_threads_enable() was called before.
EAPI void eina_log_vprint | ( | int | domain, | |
Eina_Log_Level | level, | |||
const char * | file, | |||
const char * | fnc, | |||
int | line, | |||
const char * | fmt, | |||
va_list | args | |||
) |
Print out log message using given domain and level.
- Note:
- Usually you'll not use this function directly but the helper macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and so on. See eina_log.h
- Parameters:
-
domain logging domain to use or EINA_LOG_DOMAIN_GLOBAL
if you registered none. It is recommended that modules and applications have their own logging domain.level message level, those with level greater than user specified value (eina_log_level_set() or environment variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored. file filename that originated the call, must not be NULL
.fnc function that originated the call, must not be NULL
.line originating line in file. fmt printf-like format to use. Should not provide trailing '
' as it is automatically included.
- Note:
- MT: this function may be called from different threads if eina_log_threads_enable() was called before.
- See also:
- eina_log_print()
EAPI void eina_log_print_cb_stdout | ( | const Eina_Log_Domain * | d, | |
Eina_Log_Level | level, | |||
const char * | file, | |||
const char * | fnc, | |||
int | line, | |||
const char * | fmt, | |||
void * | data, | |||
va_list | args | |||
) |
Alternative logging method, this will output to standard output stream.
This method will colorize output based on domain provided color and message logging level. To disable color, set environment variable EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line information, set EINA_LOG_FILE_DISABLE=1 or EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is not acceptable to have both EINA_LOG_FILE_DISABLE and EINA_LOG_FUNCTION_DISABLE at the same time, in this case just EINA_LOG_FUNCTION_DISABLE will be considered and file information will be printed anyways.
- Note:
- MT: if threads are enabled, this function is called within locks.
- MT: Threads different from main thread will have thread id appended to domain name.
EAPI void eina_log_print_cb_stderr | ( | const Eina_Log_Domain * | d, | |
Eina_Log_Level | level, | |||
const char * | file, | |||
const char * | fnc, | |||
int | line, | |||
const char * | fmt, | |||
void * | data, | |||
va_list | args | |||
) |
Default logging method, this will output to standard error stream.
This method will colorize output based on domain provided color and message logging level. To disable color, set environment variable EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line information, set EINA_LOG_FILE_DISABLE=1 or EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is not acceptable to have both EINA_LOG_FILE_DISABLE and EINA_LOG_FUNCTION_DISABLE at the same time, in this case just EINA_LOG_FUNCTION_DISABLE will be considered and file information will be printed anyways.
- Note:
- MT: if threads are enabled, this function is called within locks.
- MT: Threads different from main thread will have thread id appended to domain name.
EAPI void eina_log_print_cb_file | ( | const Eina_Log_Domain * | d, | |
Eina_Log_Level | level, | |||
const char * | file, | |||
const char * | fnc, | |||
int | line, | |||
const char * | fmt, | |||
void * | data, | |||
va_list | args | |||
) |
Alternative logging method, this will output to given file stream.
This method will never output color.
- Note:
- MT: if threads are enabled, this function is called within locks.
- MT: Threads different from main thread will have thread id appended to domain name.