1tutorial_log_page(3) Library Functions Manual tutorial_log_page(3)
2
6 tutorial_log_page - Log Tutorial
7
9 The Eina Log module provides logging facilities for libraries and
10 applications. It provides colored logging, basic logging levels (error,
11 warning, debug, info, critical) and loggers - called logging domains -
12 which will be covered on next sections.
13
15 Log messages can be displayed using the following macros:
16 · EINA_LOG_ERR(),
18 · EINA_LOG_INFO(),
19 · EINA_LOG_WARN(),
20 · EINA_LOG_DBG().
21 Here is an example:
22 #include <stdlib.h>
23 #include <stdio.h>
24 #include <Eina.h>
26 void test(int i)
28 {
29 EINA_LOG_DBG('Entering test');
30 if (i < 0)
32 {
33 EINA_LOG_ERR('Argument is negative');
34 return;
35 }
36 EINA_LOG_INFO('argument non negative');
38 EINA_LOG_DBG('Exiting test');
40 }
41 int main(void)
43 {
44 if (!eina_init())
45 {
46 printf('log during the initialization of Eina_Log module0);
47 return EXIT_FAILURE;
48 }
49 test(-1);
51 test(0);
52 eina_shutdown();
54 return EXIT_SUCCESS;
56 }
57 If you compiled Eina without debug mode, execution will yield only one
58 log message, which is 'argument is negative'.
59 Here we introduce the concept of logging domains (or loggers), which
60 might already be familiar to readers. It is basically a way to separate
61 a set of log messages into a context (e.g. a module) and provide a way
62 of controlling this set as a whole.
63 For example, suppose you have 3 different modules on your application
64 and you want to get logging only from one of them (e.g. create some
65 sort of filter). For achieving that, all you need to do is create a
66 logging domain for each module so that all logging inside a module can
67 be considered as a whole.
68 Logging domains are specified by a name, color applied to the name and
69 the level. The first two (name and color) are set through code, that
70 is, inside your application/module/library.
71 The level is used for controlling which messages should appear. It
72 specifies the lowest level that should be displayed (e.g. a message
73 with level 11 being logged on a domain with level set to 10 would be
74 displayed, while a message with level 9 wouldn't).
75 The domain level is set during runtime (in contrast with the name and
76 color) through the environment variable EINA_LOG_LEVELS. This variable
77 expects a list in the form domain_name1:level1,domain_name2:level2,...
78 . For example:
79 EINA_LOG_LEVELS=mymodule1:5,mymodule2:2,mymodule3:0 ./myapp
80 This line would set mymodule1 level to 5, mymodule2 level to 2 and
81 mymodule3 level to 0.
82 There's also a global logger to which EINA_LOG_(ERR, DBG, INFO, CRIT,
83 WARN) macros do log on. It is a logger that is created internally by
84 Eina Log with an empty name and can be used for general logging (where
85 logging domains do not apply).
86 Since this global logger doesn't have a name, you can't set its level
87 through EINA_LOG_LEVELS variable. Here we introduce a second
88 environment variable that is a bit more special: EINA_LOG_LEVEL.
89 This variable specifies the level of the global logging domain and the
90 level of domains that haven't been set through EINA_LOG_LEVELS. Here's
91 an example:
92 EINA_LOG_LEVEL=3 EINA_LOG_LEVELS=module1:10,module3:2 ./myapp
93 Supposing you have modules named 'module1', 'module2' and 'module3',
94 this line would result in module1 with level 10, module2 with level 3
95 and module3 with level 2. Note that module2's level wasn't specified,
96 so it's level is set to the global level. This way we can easily apply
97 filters to multiple domains with only one parameter
98 (EINA_LOG_LEVEL=num).
99 The global level (EINA_LOG_LEVEL) can also be set through code, using
100 eina_log_level_set() function.
101 While developing your libraries or applications, you may notice that
102 EINA_LOG_DOM_(ERR, DBG, INFO, CRIT, WARN) macros also print out
103 messages from eina itself. Here we introduce another environment
104 variable that is a bit more special: EINA_LOG_LEVELS_GLOB.
105 This variable allows you to disable the logging of any/all code in eina
106 itself. This is useful when developing your libraries or applications
107 so that you can see your own domain's messages easier without having to
108 sift through a lot of internal eina debug messages. Here's an example:
109 EINA_LOG_LEVEL=3 EINA_LOG_LEVELS_GLOB=eina_*:0 ./myapp
110 This will disable eina_log output from all internal eina code thus
111 allowing you to see your own domain messages easier.
113 The log module allows the user to change the way eina_log_print()
114 displays the messages. It suffices to pass to eina_log_print_cb_set()
115 the function used to display the message. That function must be of type
116 Eina_Log_Print_Cb. As a custom data can be passed to that callback,
117 powerful display messages can be displayed.
118 It is suggested to not use __FILE__, __FUNCTION__ or __LINE__ when
119 writing that callback, but when defining macros (like EINA_LOG_ERR()
120 and other macros).
121 Here is an example of custom callback, whose behavior can be changed at
122 runtime:
123 #include <stdlib.h>
124 #include <stdio.h>
125 #include <eina_log.h>
127 #define log(fmt, ...) eina_log_print(EINA_LOG_LEVEL_ERR, __FILE__, __FUNCTION__, __LINE__, fmt, ##__VA_ARGS__)
129 typedef struct _Data Data;
131 struct _Data
133 {
134 int to_stderr;
135 };
136 void print_cb(const Eina_Log_Domain *domain,
138 Eina_Log_Level level,
139 const char *file,
140 const char *fnc,
141 int line,
142 const char *fmt,
143 void *data,
144 va_list args)
145 {
146 Data *d;
147 FILE *output;
148 char *str;
149 d = (Data *)data;
151 if (d->to_stderr)
152 {
153 output = stderr;
154 str = 'stderr';
155 }
156 else
157 {
158 output = stdout;
159 str = 'stdout';
160 }
161 fprintf(output, '%s:%s:%s (%d) %s: ',
163 domain->domain_str, file, fnc, line, str);
164 vfprintf(output, fmt, args);
165 putc('0, output);
166 }
167 void test(Data *data, int i)
169 {
170 if (i < 0)
171 data->to_stderr = 0;
172 else
173 data->to_stderr = 1;
174 log('log message...');
176 }
177 int main(void)
179 {
180 Data data;
181 if (!eina_init())
183 {
184 printf('log during the initialization of Eina_Log module0);
185 return EXIT_FAILURE;
186 }
187 eina_log_print_cb_set(print_cb, &data);
189 test(&data, -1);
191 test(&data, 0);
192 eina_shutdown();
194 return EXIT_SUCCESS;
196 }
197Eina 2 Jul 2010 tutorial_log_page(3)