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