src/log.h

   1 /*
   2  * Log/Debug Interface
   3  * Copyright (c) 2011-2012 David Herrmann <dh.herrmann@googlemail.com>
   4  * Dedicated to the Public Domain
   5  */
   6
   7 /*
   8  * Log/Debug Interface
   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
  14  * log-files.
  15  *
  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
  19  * filtered.
  20  *
  21  * Define BUILD_ENABLE_DEBUG before including this header to enable
  22  * debug-messages for this file.
  23  */
  24
  25 #ifndef LOG_H_INCLUDED
  26 #define LOG_H_INCLUDED
  27
  28 #include <stdarg.h>
  29 #include <stdbool.h>
  30 #include <stdlib.h>
  31
  32 /*
  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
  40  *  - sev: the severity
  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.
  50  *
  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.
  55  *
  56  * Config Object:
  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.
  61  *
  62  * Filter Object:
  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.
  67  *
  68  * log_set_config(config):
  69  * This sets the global config which is used if no filter applies.
  70  *
  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.
  76  *
  77  * log_rm_filter(id):
  78  * This removes the filter with ID=id.
  79  *
  80  * log_clean_filters():
  81  * This removes all filters. This frees all allocated memory by the filters.
  82  *
  83  *
  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
  86  * source-file:
  87  *   #define LOG_CONFIG LOG_CONFIG_ALL(options...)
  88  * Where LOG_CONFIG_ALL() can be replaced by LOG_CONFIG_DEBUG, LOG_CONFIG_INFO
  89  * and so on.
  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
  94  * this, though.
  95  */
  96
  97 enum log_severity {
  98         LOG_FATAL = 0,
  99         LOG_ALERT = 1,
 100         LOG_CRITICAL = 2,
 101         LOG_ERROR = 3,
 102         LOG_WARNING = 4,
 103         LOG_NOTICE = 5,
 104         LOG_INFO = 6,
 105         LOG_DEBUG = 7,
 106         LOG_SEV_NUM,
 107 };
 108
 109 #define LOG_STRMAX 128
 110
 111 struct log_filter {
 112         char file[LOG_STRMAX];
 113         int line;
 114         char func[LOG_STRMAX];
 115         char subs[LOG_STRMAX];
 116 };
 117
 118 struct log_config {
 119         int sev[LOG_SEV_NUM];
 120 };
 121
 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), \
 132         } }
 133
 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)
 140
 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();
 146
 147 /*
 148  * Log-Functions
 149  * These functions pass a log-message to the log-subsystem. Handy helpers are
 150  * provided below. You almost never use these directly.
 151  *
 152  * log_submit:
 153  * Submit the message to the log-subsystem. This is the backend of all other
 154  * loggers.
 155  *
 156  * log_format:
 157  * Same as log_submit but first converts the arguments into a va_list object.
 158  *
 159  * log_llog:
 160  * Same as log_submit but used as connection to llog. It uses the default config
 161  * for every message.
 162  *
 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.
 170  *
 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.
 177  */
 178
 179 __attribute__((format(printf, 7, 0)))
 180 void log_submit(const char *file,
 181                 int line,
 182                 const char *func,
 183                 const struct log_config *config,
 184                 const char *subs,
 185                 unsigned int sev,
 186                 const char *format,
 187                 va_list args);
 188
 189 __attribute__((format(printf, 7, 8)))
 190 void log_format(const char *file,
 191                 int line,
 192                 const char *func,
 193                 const struct log_config *config,
 194                 const char *subs,
 195                 unsigned int sev,
 196                 const char *format,
 197                 ...);
 198
 199 __attribute__((format(printf, 7, 0)))
 200 void log_llog(void *data,
 201               const char *file,
 202               int line,
 203               const char *func,
 204               const char *subs,
 205               unsigned int sev,
 206               const char *format,
 207               va_list args);
 208
 209 int log_set_file(const char *file);
 210 void log_print_init(const char *appname);
 211
 212 static inline __attribute__((format(printf, 2, 3)))
 213 void log_dummyf(unsigned int sev, const char *format, ...)
 214 {
 215 }
 216
 217 /*
 218  * Default values
 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.
 229  *
 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, ...);
 237  *
 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, ...);
 242  *
 243  * log_printf is the same as log_format(LOG_DEFAULT, sev, format, ...) and is
 244  * the most basic wrapper that you can use.
 245  */
 246
 247 #ifndef LOG_CONFIG
 248 extern const struct log_config LOG_CONFIG;
 249 #endif
 250
 251 #ifndef LOG_SUBSYSTEM
 252 extern const char *LOG_SUBSYSTEM;
 253 #endif
 254
 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
 258
 259 #define log_printf(sev, format, ...) \
 260         log_format(LOG_DEFAULT, (sev), (format), ##__VA_ARGS__)
 261
 262 /*
 263  * Helpers
 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.
 268  */
 269
 270 #ifdef BUILD_ENABLE_DEBUG
 271         #define log_debug(format, ...) \
 272                 log_printf(LOG_DEBUG, (format), ##__VA_ARGS__)
 273 #else
 274         #define log_debug(format, ...) \
 275                 log_dummyf(LOG_DEBUG, (format), ##__VA_ARGS__)
 276 #endif
 277
 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__)
 292
 293 #define log_dbg log_debug
 294 #define log_warn log_warning
 295 #define log_err log_error
 296 #define log_crit log_critical
 297
 298 #endif /* LOG_H_INCLUDED */