Linux Certif

Toute la documentation sur la certification Linux LPI

Eina_Log_Group

NAME

Log -

Full-featured logging system.

Data Structures

struct _Eina_Log_Domain
The domain used for logging.

Defines

#define EINA_LOG(DOM, LEVEL, fmt,...) eina_log_print(DOM, LEVEL, __FILE__, __FUNCTION__, __LINE__, fmt, ##__VA_ARGS__)

#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_DEFAULT, EINA_LOG_LEVEL_CRITICAL, fmt, ##__VA_ARGS__)
Logs a message with level CRITICAL on the default domain with the specified format.
#define EINA_LOG_ERR(fmt,...) EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_ERR, fmt, ##__VA_ARGS__)
Logs a message with level ERROR on the default domain with the specified format.
#define EINA_LOG_INFO(fmt,...) EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_INFO, fmt, ##__VA_ARGS__)
Logs a message with level INFO on the default domain with the specified format.
#define EINA_LOG_WARN(fmt,...) EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_WARN, fmt, ##__VA_ARGS__)
Logs a message with level WARN on the default domain with the specified format.
#define EINA_LOG_DBG(fmt,...) EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_DBG, fmt, ##__VA_ARGS__)
Logs a message with level DEBUG on the default domain with the specified format.

Typedefs

typedef struct _Eina_Log_Domain Eina_Log_Domain
The domain used for logging.
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.

Functions

static Eina_Bool eina_log_level_check (int level)
Checks whenever the given level should be printed out.
static Eina_Bool eina_log_domain_level_check (int domain, int level)
Checks whenever the given level should be printed out.
static const char * eina_log_level_name_get (int level, char name[4])
Function to format the level as a 3 character (+1 null byte) string.
static const char * eina_log_level_color_get (int level)
Function to get recommended color value for level.
static const char * eina_log_level_color_if_enabled_get (int level)
Function to get recommended color value for level, if colors are enabled.
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 (int level)
Set the default log level.
EAPI int eina_log_level_get (void)
Get the default log level.
EAPI Eina_Bool eina_log_main_thread_check (void)
Checks if current thread is the main thread.
EAPI void eina_log_color_disable_set (Eina_Bool disabled)
Set if color logging should be disabled.
EAPI Eina_Bool eina_log_color_disable_get (void)
Get if color logging should be disabled.
EAPI void eina_log_file_disable_set (Eina_Bool disabled)
Set if originating file name logging should be disabled.
EAPI Eina_Bool eina_log_file_disable_get (void)
Get if originating file name logging should be disabled.
EAPI void eina_log_function_disable_set (Eina_Bool disabled)
Set if originating function name logging should be disabled.
EAPI Eina_Bool eina_log_function_disable_get (void)
Get if originating function name logging should be disabled.
EAPI void eina_log_abort_on_critical_set (Eina_Bool abort_on_critical)
Set if critical messages should abort the program.
EAPI Eina_Bool eina_log_abort_on_critical_get (void)
Get if critical messages should abort the program.
EAPI void eina_log_abort_on_critical_level_set (int critical_level)
Set level that triggers abort if abort-on-critical is set.
EAPI int eina_log_abort_on_critical_level_get (void)
Get level that triggers abort if abort-on-critical is set.
EAPI void eina_log_domain_level_set (const char *domain_name, int level)
Set the domain level given its name.
EAPI int eina_log_domain_level_get (const char *domain_name)
Get the domain level given its name.
EAPI int eina_log_domain_registered_level_get (int domain)
Get the domain level given its identifier.
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.
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
EINA_LOG_DOMAIN_GLOBAL is the general purpose log domain to be used, it is always registered and available everywhere.
EAPI void EINA_NOINSTRUMENT

Detailed Description

Full-featured logging system.

Eina provides eina_log_print(), a standard function to manage all logging messages. This function may be called directly or using the helper macros such as EINA_LOG_DBG(), EINA_LOG_ERR() or those that take a specific domain as argument EINA_LOG_DOM_DBG(), EINA_LOG_DOM_ERR(). Internally, eina_log_print() will call the function defined with eina_log_print_cb_set(), that defaults to eina_log_print_cb_stderr(), but may be changed to do whatever you need, such as networking or syslog logging.

The logging system is thread safe once initialized with eina_log_threads_enable(). The thread that calls this function first is considered 'main thread' and other threads will have their thread id (pthread_self()) printed in the log message so it is easy to detect from where it is coming.

Log domains is the Eina way to differentiate messages. There might be different domains to represent different modules, different feature-set, different categories and so on. Filtering can be applied to domain names by means of EINA_LOG_LEVELS environment variable or eina_log_domain_level_set().

The different logging levels serve to customize the amount of debugging one want to take and may be used to automatically call abort() once some given level message is printed. This is controlled by environment variable EINA_LOG_ABORT and the level to be considered critical with EINA_LOG_ABORT_LEVEL. These can be changed with eina_log_abort_on_critical_set() and eina_log_abort_on_critical_level_set().

The default maximum level to print is defined by environment variable EINA_LOG_LEVEL, but may be set per-domain with EINA_LOG_LEVELS. It will default to EINA_LOG_ERR. This can be changed with eina_log_level_set().

To use the log system Eina must be initialized with eina_init() and later shut down with eina_shutdown(). 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);
         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`
 

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.

Enumeration Type Documentation

enum _Eina_Log_Level

List of available logging levels.

Enumerator:

EINA_LOG_LEVEL_CRITICAL

Critical log level.

EINA_LOG_LEVEL_ERR

Error log level.

EINA_LOG_LEVEL_WARN

Warning log level.

EINA_LOG_LEVEL_INFO

Information log level.

EINA_LOG_LEVEL_DBG

Debug log level.

EINA_LOG_LEVELS

Count of default log levels.

EINA_LOG_LEVEL_UNKNOWN

Unknown level.

Function Documentation

static Eina_Bool eina_log_level_check (int level) [inline, static]

Checks whenever the given level should be printed out. This is useful to enable certain blocks of code just when given level is to be used.

  #include <Eina.h>
 
  void my_func(void *data)
  {
     if (eina_log_level_check(EINA_LOG_LEVEL_WARN))
        expensive_debugging_code(data);
 
     my_func_code(data);
  }
 

Returns:

EINA_TRUE if level is equal or smaller than the current global logging level.

static Eina_Bool eina_log_domain_level_check (int domain, int level) [inline, static]

Checks whenever the given level should be printed out. This is useful to enable certain blocks of code just when given level is to be used.

  #include <Eina.h>
 
  extern int _my_log_dom;
 
  void my_func(void *data)
  {
     if (eina_log_domain_level_check(_my_log_dom, EINA_LOG_LEVEL_WARN))
        expensive_debugging_code(data);
 
     my_func_code(data);
  }
 

Returns:

EINA_TRUE if level is equal or smaller than the current domain logging level.

static const char* eina_log_level_name_get (int level, char name[4]) [inline, static]

Function to format the level as a 3 character (+1 null byte) string. This function converts the given level to a known string name (CRI, ERR, WRN, INF or DBG) or a zero-padded 3-character string. In any case the last byte will contain a trailing null byte.

If extreme level values are used (greater than 999 and smaller than -99), then the value will just consider the less significant part. This is so uncommon that users should handle this in their code.

Parameters:

level what level value to use.
name where to write the actual value.

Returns:

pointer to name.

static const char* eina_log_level_color_get (int level) [inline, static]

Function to get recommended color value for level. This function will not check if colors are enabled or not before returning the level color. If you desire such check, use eina_log_level_color_if_enabled_get().

Parameters:

level what level value to use.

Returns:

pointer to null byte terminated ANSI color string to be used in virtual terminals supporting VT100 color codes.

See also:

eina_log_level_color_if_enabled_get()

static const char* eina_log_level_color_if_enabled_get (int level) [inline, static]

Function to get recommended color value for level, if colors are enabled. This function will check if colors are enabled or not before returning the level color. If colors are disabled, then empty string is returned.

Parameters:

level what level value to use.

Returns:

pointer to null byte terminated ANSI color string to be used in virtual terminals supporting VT100 color codes. If colors are disabled, the empty string is returned.

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 (int level)

Set the default log level. Parameters:

level The log level.

This function sets the log level level. It is used in eina_log_print().

Note:

this is initially set to envvar EINA_LOG_LEVEL by eina_init().

See also:

eina_log_level_get()

EAPI int eina_log_level_get (void)

Get the default log level. Returns:

the log level that limits eina_log_print().

See also:

eina_log_level_set()

EAPI Eina_Bool eina_log_main_thread_check (void)

Checks if current thread is the main thread. Returns:

EINA_TRUE if threads were enabled and the current thread is the one that called eina_log_threads_init(). If there is no thread support (compiled with --disable-pthreads) or they were not enabled, then EINA_TRUE is also returned. The only case where EINA_FALSE is returned is when threads were successfully enabled but the current thread is not the main (one that called eina_log_threads_init()).

EAPI void eina_log_color_disable_set (Eina_Bool disabled)

Set if color logging should be disabled. Parameters:

disabled if EINA_TRUE, color logging should be disabled.

Note:

this is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init().

See also:

eina_log_color_disable_get()

EAPI Eina_Bool eina_log_color_disable_get (void)

Get if color logging should be disabled. Returns:

if EINA_TRUE, color logging should be disabled.

See also:

eina_log_color_disable_set()

EAPI void eina_log_file_disable_set (Eina_Bool disabled)

Set if originating file name logging should be disabled. Parameters:

disabled if EINA_TRUE, file name logging should be disabled.

Note:

this is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init().

See also:

eina_log_file_disable_get()

EAPI Eina_Bool eina_log_file_disable_get (void)

Get if originating file name logging should be disabled. Returns:

if EINA_TRUE, file name logging should be disabled.

See also:

eina_log_file_disable_set()

EAPI void eina_log_function_disable_set (Eina_Bool disabled)

Set if originating function name logging should be disabled. Parameters:

disabled if EINA_TRUE, function name logging should be disabled.

Note:

this is initially set to envvar EINA_LOG_FUNCTION_DISABLE by eina_init().

See also:

eina_log_function_disable_get()

EAPI Eina_Bool eina_log_function_disable_get (void)

Get if originating function name logging should be disabled. Returns:

if EINA_TRUE, function name logging should be disabled.

See also:

eina_log_function_disable_set()

EAPI void eina_log_abort_on_critical_set (Eina_Bool abort_on_critical)

Set if critical messages should abort the program. Parameters:

abort_on_critical if EINA_TRUE, messages with level equal or smaller than eina_log_abort_on_critical_level_get() will abort the program.

Note:

this is initially set to envvar EINA_LOG_ABORT by eina_init().

See also:

eina_log_abort_on_critical_get()
eina_log_abort_on_critical_level_set()

EAPI Eina_Bool eina_log_abort_on_critical_get (void)

Get if critical messages should abort the program. Returns:

if EINA_TRUE, any messages with level equal or smaller than eina_log_abort_on_critical_level_get() will abort the program.

See also:

eina_log_abort_on_critical_set()
eina_log_abort_on_critical_level_set()

EAPI void eina_log_abort_on_critical_level_set (int critical_level)

Set level that triggers abort if abort-on-critical is set. Parameters:

critical_level levels equal or smaller than the given value will trigger program abortion if eina_log_abort_on_critical_get() returns EINA_TRUE.

Note:

this is initially set to envvar EINA_LOG_ABORT_LEVEL by eina_init().

See also:

eina_log_abort_on_critical_level_get()
eina_log_abort_on_critical_get()

EAPI int eina_log_abort_on_critical_level_get (void)

Get level that triggers abort if abort-on-critical is set. Returns:

critical level equal or smaller than value will trigger program abortion if eina_log_abort_on_critical_get() returns EINA_TRUE.

See also:

eina_log_abort_on_critical_level_set()
eina_log_abort_on_critical_get()

EAPI void eina_log_domain_level_set (const char * domain_name, int level)

Set the domain level given its name. This call has the same effect as setting EINA_LOG_LEVELS=<domain_name>:<level>

Parameters:

domain_name domain name to change the level. It may be of a still not registered domain. If the domain is not registered yet, it will be saved as a pending set and applied upon registration.
level level to use to limit eina_log_print() for given domain.

EAPI int eina_log_domain_level_get (const char * domain_name)

Get the domain level given its name. Parameters:

domain_name domain name to retrieve the level. It may be of a still not registered domain. If the domain is not registered yet, but there is a pending value, either from eina_log_domain_level_set(),EINA_LOG_LEVELS environment variable or from EINA_LOG_LEVELS_GLOB, these are returned. If nothing else was found, then the global/default level (eina_log_level_get()) is returned.

Returns:

level to use to limit eina_log_print() for given domain. On error (domain_name == NULL), EINA_LOG_LEVEL_UNKNOWN is returned.

See also:

eina_log_domain_level_set()
eina_log_domain_registered_level_get()

EAPI int eina_log_domain_registered_level_get (int domain)

Get the domain level given its identifier. Parameters:

domain identifier, so it must be previously registered with eina_log_domain_register(). It's a much faster version of eina_log_domain_level_get(), but relies on domain being present.

Returns:

level to use to limit eina_log_print() for given domain. On error EINA_LOG_LEVEL_UNKNOWN is returned.

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 '

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 '

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. To enable color, even if directing to a file or when using a non-supported color terminal, use EINA_LOG_COLOR_DISABLE=0. If EINA_LOG_COLOR_DISABLE is unset (or -1), then Eina will disable color if terminal ($TERM) is unsupported or if redirecting to a file.

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.

Author

Generated automatically by Doxygen for Eina from the source code.