3 * Copyright (c) 2011-2012 David Herrmann <dh.herrmann@googlemail.com>
4 * Dedicated to the Public Domain
9 * This interface provides basic logging to a single file or stderr. By default,
10 * all log-messages are forwarded to stderr but you can change this to an
11 * arbitrary file. However, no complex file-rotation/backup functions are
12 * supported so you should use the default (stderr) and use a proper init-system
13 * like systemd to do log-rotations. This can also forward stderr messages into
16 * Besides simple log-functions this also provides run-time filters so special
17 * debug messages can be enabled/disabled. This should be used for
18 * debugging-only because it may slow-down your application if every message is
21 * Define BUILD_ENABLE_DEBUG before including this header to enable
22 * debug-messages for this file.
25 #ifndef LOG_H_INCLUDED
26 #define LOG_H_INCLUDED
33 * Log Messages and Filters
34 * A log message consists of:
35 * - file: the source file where the call was made
36 * - line: the corresponding line number
37 * - func: the function name
38 * - config: special configuration for this message only
39 * - subs: the subsystem
41 * - format: format string
42 * - args: arguments depending on format string
43 * Depending on this information the log system decides whether the message is
44 * discarded or logged and what information is included. To allow fine-grained
45 * configuration you can add log_filter and log_config objects. A log_filter
46 * object specifies to what messages the log_config object shall apply. If a
47 * log_filter does not match, then the corresponding log_config is ignored.
48 * The log_config specifies whether a message is discarded, logged or whether
49 * other filters shall be searched.
51 * The "config" field of every log-message does not have a corresponding
52 * log_filter object. Instead, it is assumed that the config object only applies
53 * to this single message. This allows to specify special behavior for every
54 * single message but also refer to global filters.
57 * A log_config object contains a severity-array. Each severity is the index of
58 * an integer in the array. If the integer is 0, then messages with the given
59 * severity are discarded, if is is 1, then they are logged. If it is 2, then
60 * the config object is ignored and global filters will be used.
63 * A filter object specifies what messages are affected by the corresponding
64 * config object. file, func and subs are strings. If they are empty (length=0)
65 * then they are not used for matching. If line is smaller than 0 then it is
66 * ignored. Otherwise all given information must match.
68 * log_set_config(config):
69 * This sets the global config which is used if no filter applies.
71 * log_add_filter(filter, config):
72 * This adds a new filter to the global filter-list. If the filter matches the
73 * given config shall apply. This returns a negative error code on failure.
74 * Otherwise it returns an ID which can be used to remove the filter again.
75 * An ID is always >= 0.
78 * This removes the filter with ID=id.
80 * log_clean_filters():
81 * This removes all filters. This frees all allocated memory by the filters.
84 * If you want to set a config option which shall apply to all log-messages in
85 * a single source-file, then you can add the following line to the head of the
87 * #define LOG_CONFIG LOG_CONFIG_ALL(options...)
88 * Where LOG_CONFIG_ALL() can be replaced by LOG_CONFIG_DEBUG, LOG_CONFIG_INFO
90 * The LOG_CONFIG_*() macros create a log_config object on the stack and are
91 * used for convenience. You can also provide your own log_config object here.
92 * This LOG_CONFIG constant is picked up by all log-helpers which are provided
93 * below. The raw log_submit and log_format() functions are not affected by
109 #define LOG_STRMAX 128
112 char file[LOG_STRMAX];
114 char func[LOG_STRMAX];
115 char subs[LOG_STRMAX];
119 int sev[LOG_SEV_NUM];
122 #define LOG_CONFIG_ALL(debug, info, notice, warning, error, critical, alert, fatal) \
123 (struct log_config){ .sev = { \
124 [LOG_DEBUG] = (debug), \
125 [LOG_INFO] = (info), \
126 [LOG_NOTICE] = (notice), \
127 [LOG_WARNING] = (warning), \
128 [LOG_ERROR] = (error), \
129 [LOG_CRITICAL] = (critical), \
130 [LOG_ALERT] = (alert), \
131 [LOG_FATAL] = (fatal), \
134 #define LOG_CONFIG_DEBUG(debug) \
135 LOG_CONFIG_ALL((debug), 2, 2, 2, 2, 2, 2, 2)
136 #define LOG_CONFIG_INFO(debug, info) \
137 LOG_CONFIG_ALL((debug), (info), 2, 2, 2, 2, 2, 2)
138 #define LOG_CONFIG_WARNING(debug, info, notice, warning) \
139 LOG_CONFIG_ALL((debug), (info), (notice), (warning), 2, 2, 2, 2)
141 void log_set_config(const struct log_config *config);
142 int log_add_filter(const struct log_filter *filter,
143 const struct log_config *config);
144 void log_rm_filter(int handle);
145 void log_clean_filter();
149 * These functions pass a log-message to the log-subsystem. Handy helpers are
150 * provided below. You almost never use these directly.
153 * Submit the message to the log-subsystem. This is the backend of all other
157 * Same as log_submit but first converts the arguments into a va_list object.
160 * Same as log_submit but used as connection to llog. It uses the default config
163 * log_set_file(file):
164 * This opens the file specified by \file and redirects all new messages to this
165 * file. If \file is NULL, then the default is used which is stderr.
166 * Messages are appended to the file and no file-locks are used so you cannot
167 * use a single file for multiple processes.
168 * No log-file-rotations or other backup/rotation functions are supported. Use a
169 * proper init system like systemd to do this.
171 * log_print_init(appname):
172 * This prints a message with build-time/date and appname to the log. You should
173 * invoke this very early in your program. It is not required, though. However,
174 * every message is prepended with a time-offset since application-start. This
175 * offset is measured since the first log-message is sent so you should send
176 * some log-message at application start. This is a handy-helper to do this.
179 __attribute__((format(printf, 7, 0)))
180 void log_submit(const char *file,
183 const struct log_config *config,
189 __attribute__((format(printf, 7, 8)))
190 void log_format(const char *file,
193 const struct log_config *config,
199 __attribute__((format(printf, 7, 0)))
200 void log_llog(void *data,
209 int log_set_file(const char *file);
210 void log_print_init(const char *appname);
212 static inline __attribute__((format(printf, 2, 3)))
213 void log_dummyf(unsigned int sev, const char *format, ...)
219 * All helpers automatically pick-up the file, line, func, config and subsystem
220 * parameters for a log-message. file, line and func are generated with
221 * __FILE__, __LINE__ and __func__ and should almost never be replaced. The
222 * config argument is by default NULL so global filters apply. You can use the
223 * #define LOG_CONFIG ...
224 * method to overwrite this. It is described above in detail.
225 * The subsystem is by default an empty string. To overwrite this, add this
226 * line to the top of your source file:
227 * #define LOG_SUBSYSTEM "mysubsystem"
228 * Then all following log-messages will use this string as subsystem.
230 * If you want to change one of these, you need to directly use log_submit and
231 * log_format. If you want the defaults for file, line and func you can use:
232 * log_format(LOG_DEFAULT_BASE, config, subsys, sev, format, ...);
233 * If you want the default config, use:
234 * log_format(LOG_DEFAULT_CONF, subsys, sev, format, ...);
235 * If you want all default values, use:
236 * log_format(LOG_DEFAULT, sev, format, ...);
238 * If you want to change a single value, this is the default line that is used
239 * internally. Adjust it to your needs:
240 * log_format(__FILE__, __LINE__, __func__, &LOG_CONFIG, LOG_SUBSYSTEM,
241 * LOG_ERROR, "your format string: %s %d", "some args", 5, ...);
243 * log_printf is the same as log_format(LOG_DEFAULT, sev, format, ...) and is
244 * the most basic wrapper that you can use.
248 extern const struct log_config LOG_CONFIG;
251 #ifndef LOG_SUBSYSTEM
252 extern const char *LOG_SUBSYSTEM;
255 #define LOG_DEFAULT_BASE __FILE__, __LINE__, __func__
256 #define LOG_DEFAULT_CONF LOG_DEFAULT_BASE, &LOG_CONFIG
257 #define LOG_DEFAULT LOG_DEFAULT_CONF, LOG_SUBSYSTEM
259 #define log_printf(sev, format, ...) \
260 log_format(LOG_DEFAULT, (sev), (format), ##__VA_ARGS__)
264 * The pick-up all the default values and submit the message to the
265 * log-subsystem. The log_debug() function produces zero-code if
266 * BUILD_ENABLE_DEBUG is not defined. Therefore, it can be heavily used for
267 * debugging and will not have any side-effects.
270 #ifdef BUILD_ENABLE_DEBUG
271 #define log_debug(format, ...) \
272 log_printf(LOG_DEBUG, (format), ##__VA_ARGS__)
274 #define log_debug(format, ...) \
275 log_dummyf(LOG_DEBUG, (format), ##__VA_ARGS__)
278 #define log_info(format, ...) \
279 log_printf(LOG_INFO, (format), ##__VA_ARGS__)
280 #define log_notice(format, ...) \
281 log_printf(LOG_NOTICE, (format), ##__VA_ARGS__)
282 #define log_warning(format, ...) \
283 log_printf(LOG_WARNING, (format), ##__VA_ARGS__)
284 #define log_error(format, ...) \
285 log_printf(LOG_ERROR, (format), ##__VA_ARGS__)
286 #define log_critical(format, ...) \
287 log_printf(LOG_CRITICAL, (format), ##__VA_ARGS__)
288 #define log_alert(format, ...) \
289 log_printf(LOG_ALERT, (format), ##__VA_ARGS__)
290 #define log_fatal(format, ...) \
291 log_printf(LOG_FATAL, (format), ##__VA_ARGS__)
293 #define log_dbg log_debug
294 #define log_warn log_warning
295 #define log_err log_error
296 #define log_crit log_critical
298 #endif /* LOG_H_INCLUDED */