src/shl_llog.h

   1 /*
   2  * Library Log/Debug Interface
   3  * Copyright (c) 2012 David Herrmann <dh.herrmann@googlemail.com>
   4  * Dedicated to the Public Domain
   5  */
   6
   7 /*
   8  * Library Log/Debug Interface
   9  * Libraries should always avoid producing side-effects. This includes writing
  10  * log-messages of any kind. However, you often don't want to disable debugging
  11  * entirely, therefore, the core objects often contain a pointer to a function
  12  * which performs logging. If that pointer is NULL (default), logging is
  13  * disabled.
  14  *
  15  * This header should never be installed into the system! This is _no_ public
  16  * header. Instead, copy it into your application if you want and use it there.
  17  * Your public library API should include something like this:
  18  *
  19  *   typedef void (*MYPREFIX_log_t) (void *data,
  20  *                                   const char *file,
  21  *                                   int line,
  22  *                                   const char *func,
  23  *                                   const char *subs,
  24  *                                   unsigned int sev,
  25  *                                   const char *format,
  26  *                                   va_list args);
  27  *
  28  * And then the user can supply such a function when creating a new context
  29  * object of your library or simply supply NULL. Internally, you have a field of
  30  * type "MYPREFIX_log_t llog" in your main structure. If you pass this to the
  31  * convenience helpers like llog_dbg(), llog_warn() etc. it will automatically
  32  * use the "llog" field to print the message. If it is NULL, nothing is done.
  33  *
  34  * The arguments of the log-function are defined as:
  35  *   data: User-supplied data field that is passed straight through.
  36  *   file: Zero terminated string of the file-name where the log-message
  37  *         occurred. Can be NULL.
  38  *   line: Line number of @file where the message occurred. Set to 0 or smaller
  39  *         if not available.
  40  *   func: Function name where the log-message occurred. Can be NULL.
  41  *   subs: Subsystem where the message occurred (zero terminated). Can be NULL.
  42  *   sev: Severity of log-message. An integer between 0 and 7 as defined below.
  43  *        These are identical to the linux-kernel severities so there is no need
  44  *        to include these in your public API. Every app can define them
  45  *        themselves, if they need it.
  46  *   format: Format string. Must not be NULL.
  47  *   args: Argument array
  48  *
  49  * The user should also be able to optionally provide a data field which is
  50  * always passed unmodified as first parameter to the log-function. This allows
  51  * to add context to the logger.
  52  */
  53
  54 #ifndef SHL_LLOG_H_INCLUDED
  55 #define SHL_LLOG_H_INCLUDED
  56
  57 #include <stdarg.h>
  58 #include <stdbool.h>
  59 #include <stdlib.h>
  60
  61 enum llog_severity {
  62         LLOG_FATAL = 0,
  63         LLOG_ALERT = 1,
  64         LLOG_CRITICAL = 2,
  65         LLOG_ERROR = 3,
  66         LLOG_WARNING = 4,
  67         LLOG_NOTICE = 5,
  68         LLOG_INFO = 6,
  69         LLOG_DEBUG = 7,
  70         LLOG_SEV_NUM,
  71 };
  72
  73 typedef void (*llog_submit_t) (void *data,
  74                                const char *file,
  75                                int line,
  76                                const char *func,
  77                                const char *subs,
  78                                unsigned int sev,
  79                                const char *format,
  80                                va_list args);
  81
  82 static inline __attribute__((format(printf, 8, 9)))
  83 void llog_format(llog_submit_t llog,
  84                  void *data,
  85                  const char *file,
  86                  int line,
  87                  const char *func,
  88                  const char *subs,
  89                  unsigned int sev,
  90                  const char *format,
  91                  ...)
  92 {
  93         va_list list;
  94
  95         if (llog) {
  96                 va_start(list, format);
  97                 llog(data, file, line, func, subs, sev, format, list);
  98                 va_end(list);
  99         }
 100 }
 101
 102 #ifndef LLOG_SUBSYSTEM
 103 static const char *LLOG_SUBSYSTEM __attribute__((__unused__));
 104 #endif
 105
 106 #define LLOG_DEFAULT __FILE__, __LINE__, __func__, LLOG_SUBSYSTEM
 107
 108 #define llog_printf(obj, sev, format, ...) \
 109         llog_format((obj)->llog, \
 110                     (obj)->llog_data, \
 111                     LLOG_DEFAULT, \
 112                     (sev), \
 113                     (format), \
 114                     ##__VA_ARGS__)
 115 #define llog_dprintf(obj, data, sev, format, ...) \
 116         llog_format((obj), \
 117                     (data), \
 118                     LLOG_DEFAULT, \
 119                     (sev), \
 120                     (format), \
 121                     ##__VA_ARGS__)
 122
 123 static inline __attribute__((format(printf, 4, 5)))
 124 void llog_dummyf(llog_submit_t llog, void *data, unsigned int sev,
 125                  const char *format, ...)
 126 {
 127 }
 128
 129 /*
 130  * Helpers
 131  * They pick-up all the default values and submit the message to the
 132  * llog-subsystem. The llog_debug() function produces zero-code if
 133  * BUILD_ENABLE_DEBUG is not defined. Therefore, it can be heavily used for
 134  * debugging and will not have any side-effects.
 135  */
 136
 137 #ifdef BUILD_ENABLE_DEBUG
 138         #define llog_ddebug(obj, data, format, ...) \
 139                 llog_dprintf((obj), (data), LLOG_DEBUG, (format), ##__VA_ARGS__)
 140         #define llog_debug(obj, format, ...) \
 141                 llog_ddebug((obj)->llog, (obj)->llog_data, (format), ##__VA_ARGS__)
 142 #else
 143         #define llog_ddebug(obj, data, format, ...) \
 144                 llog_dummyf((obj), (data), LLOG_DEBUG, (format), ##__VA_ARGS__)
 145         #define llog_debug(obj, format, ...) \
 146                 llog_ddebug((obj)->llog, (obj)->llog_data, (format), ##__VA_ARGS__)
 147 #endif
 148
 149 #define llog_info(obj, format, ...) \
 150         llog_printf((obj), LLOG_INFO, (format), ##__VA_ARGS__)
 151 #define llog_dinfo(obj, data, format, ...) \
 152         llog_dprintf((obj), (data), LLOG_INFO, (format), ##__VA_ARGS__)
 153 #define llog_notice(obj, format, ...) \
 154         llog_printf((obj), LLOG_NOTICE, (format), ##__VA_ARGS__)
 155 #define llog_dnotice(obj, data, format, ...) \
 156         llog_dprintf((obj), (data), LLOG_NOTICE, (format), ##__VA_ARGS__)
 157 #define llog_warning(obj, format, ...) \
 158         llog_printf((obj), LLOG_WARNING, (format), ##__VA_ARGS__)
 159 #define llog_dwarning(obj, data, format, ...) \
 160         llog_dprintf((obj), (data), LLOG_WARNING, (format), ##__VA_ARGS__)
 161 #define llog_error(obj, format, ...) \
 162         llog_printf((obj), LLOG_ERROR, (format), ##__VA_ARGS__)
 163 #define llog_derror(obj, data, format, ...) \
 164         llog_dprintf((obj), (data), LLOG_ERROR, (format), ##__VA_ARGS__)
 165 #define llog_critical(obj, format, ...) \
 166         llog_printf((obj), LLOG_CRITICAL, (format), ##__VA_ARGS__)
 167 #define llog_dcritical(obj, data, format, ...) \
 168         llog_dprintf((obj), (data), LLOG_CRITICAL, (format), ##__VA_ARGS__)
 169 #define llog_alert(obj, format, ...) \
 170         llog_printf((obj), LLOG_ALERT, (format), ##__VA_ARGS__)
 171 #define llog_dalert(obj, data, format, ...) \
 172         llog_dprintf((obj), (data), LLOG_ALERT, (format), ##__VA_ARGS__)
 173 #define llog_fatal(obj, format, ...) \
 174         llog_printf((obj), LLOG_FATAL, (format), ##__VA_ARGS__)
 175 #define llog_dfatal(obj, data, format, ...) \
 176         llog_dprintf((obj), (data), LLOG_FATAL, (format), ##__VA_ARGS__)
 177
 178 #define llog_dbg llog_debug
 179 #define llog_warn llog_warning
 180 #define llog_err llog_error
 181 #define llog_crit llog_critical
 182
 183 /*
 184  * Default log messages
 185  * These macros can be used to produce default log messages. You can use them
 186  * directly in an "return" statement. The "v" variants automatically cast the
 187  * result to void so it can be used in return statements inside of void
 188  * functions. The "d" variants use the logging object directly as the parent
 189  * might not exist, yet.
 190  *
 191  * Most of the messages work only if debugging is enabled. This is, because they
 192  * are used in debug paths and would slow down normal applications.
 193  */
 194
 195 #define llog_dEINVAL(obj, data) \
 196         (llog_ddebug((obj), (data), "invalid arguments"), -EINVAL)
 197 #define llog_EINVAL(obj) \
 198         (llog_dEINVAL((obj)->llog, (obj)->llog_data))
 199 #define llog_vEINVAL(obj) \
 200         ((void)llog_EINVAL(obj))
 201 #define llog_vdEINVAL(obj, data) \
 202         ((void)llog_dEINVAL((obj), (data)))
 203
 204 #define llog_dEFAULT(obj, data) \
 205         (llog_ddebug((obj), (data), "operation failed"), -EFAULT)
 206 #define llog_EFAULT(obj) \
 207         (llog_dEFAULT((obj)->llog, (obj)->llog_data))
 208 #define llog_vEFAULT(obj) \
 209         ((void)llog_EFAULT(obj))
 210 #define llog_vdEFAULT(obj, data) \
 211         ((void)llog_dEFAULT((obj), (data)))
 212
 213 #define llog_dENOMEM(obj, data) \
 214         (llog_ddebug((obj), (data), "memory allocation failed"), -ENOMEM)
 215 #define llog_ENOMEM(obj) \
 216         (llog_dENOMEM((obj)->llog, (obj)->llog_data))
 217 #define llog_vENOMEM(obj) \
 218         ((void)llog_ENOMEM(obj))
 219 #define llog_vdENOMEM(obj, data) \
 220         ((void)llog_dENOMEM((obj), (data)))
 221
 222 #endif /* SHL_LLOG_H_INCLUDED */