include/ecoli_log.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
   3  */
   4
   5 /**
   6  * Logging API
   7  *
   8  * This file provide logging helpers:
   9  * - logging functions, supporting printf-like format
  10  * - several debug level (similar to syslog)
  11  * - named log types
  12  * - redirection of log to a user functions (default logs nothing)
  13  */
  14
  15 #ifndef ECOLI_LOG_
  16 #define ECOLI_LOG_
  17
  18 #include <stdarg.h>
  19 #include <syslog.h>
  20
  21 #include <ecoli_assert.h>
  22
  23 enum ec_log_level {
  24         EC_LOG_EMERG   = 0,  /* system is unusable               */
  25         EC_LOG_ALERT   = 1,  /* action must be taken immediately */
  26         EC_LOG_CRIT    = 2,  /* critical conditions              */
  27         EC_LOG_ERR     = 3,  /* error conditions                 */
  28         EC_LOG_WARNING = 4,  /* warning conditions               */
  29         EC_LOG_NOTICE  = 5,  /* normal but significant condition */
  30         EC_LOG_INFO    = 6,  /* informational                    */
  31         EC_LOG_DEBUG   = 7,  /* debug-level messages             */
  32 };
  33
  34 /**
  35  * Register a log type.
  36  *
  37  * This macro defines a function that will be called at startup (using
  38  * the "constructor" attribute). This function registers the named type
  39  * passed as argument, and sets a static global variable
  40  * "ec_log_local_type". This variable is used as the default log type
  41  * for this file when using EC_LOG() or EC_VLOG().
  42  *
  43  * This macro can be present several times in a file. In this case, the
  44  * local log type is set to the last registered type.
  45  *
  46  * On error, the function aborts.
  47  *
  48  * @param name
  49  *   The name of the log to be registered.
  50  */
  51 #define EC_LOG_TYPE_REGISTER(name)                                      \
  52         static int name##_log_type;                                     \
  53         static int ec_log_local_type;                                   \
  54         __attribute__((constructor, used))                              \
  55         static void ec_log_register_##name(void)                        \
  56         {                                                               \
  57                 ec_log_local_type = ec_log_type_register(#name);        \
  58                 ec_assert_print(ec_log_local_type >= 0,                 \
  59                                 "cannot register log type.\n");         \
  60                 name##_log_type = ec_log_local_type;                    \
  61         }
  62
  63 /**
  64  * User log function type.
  65  *
  66  * It is advised that a user-defined log function drops all messages
  67  * that are at least as critical as ec_log_level_get(), as done by the
  68  * default handler.
  69  *
  70  * @param type
  71  *   The log type identifier.
  72  * @param level
  73  *   The log level.
  74  * @param opaque
  75  *   The opaque pointer that was passed to ec_log_fct_register().
  76  * @param str
  77  *   The string to log.
  78  * @return
  79  *   0 on success, -1 on error (errno is set).
  80  */
  81 typedef int (*ec_log_t)(int type, enum ec_log_level level, void *opaque,
  82                         const char *str);
  83
  84 /**
  85  * Register a user log function.
  86  *
  87  * @param usr_log
  88  *   Function pointer that will be invoked for each log call.
  89  *   If the parameter is NULL, ec_log_default_cb() is used.
  90  * @param opaque
  91  *   Opaque pointer passed to the log function.
  92  * @return
  93  *   0 on success, -1 on error (errno is set).
  94  */
  95 int ec_log_fct_register(ec_log_t usr_log, void *opaque);
  96
  97 /**
  98  * Register a named log type.
  99  *
 100  * Register a new log type, which is identified by its name. The
 101  * function returns a log identifier associated to the log name. If the
 102  * name is already registered, the function just returns its identifier.
 103  *
 104  * @param name
 105  *   The name of the log type.
 106  * @return
 107  *   The log type identifier on success (positive or zero), -1 on
 108  *   error (errno is set).
 109  */
 110 int ec_log_type_register(const char *name);
 111
 112 /**
 113  * Return the log name associated to the log type identifier.
 114  *
 115  * @param type
 116  *   The log type identifier.
 117  * @return
 118  *   The name associated to the log type, or "unknown". It always return
 119  *   a valid string (never NULL).
 120  */
 121 const char *ec_log_name(int type);
 122
 123 /**
 124  * Log a formatted string.
 125  *
 126  * @param type
 127  *   The log type identifier.
 128  * @param level
 129  *   The log level.
 130  * @param format
 131  *   The format string, followed by optional arguments.
 132  * @return
 133  *   0 on success, -1 on error (errno is set).
 134  */
 135 int ec_log(int type, enum ec_log_level level, const char *format, ...)
 136         __attribute__((format(__printf__, 3, 4)));
 137
 138 /**
 139  * Log a formatted string.
 140  *
 141  * @param type
 142  *   The log type identifier.
 143  * @param level
 144  *   The log level.
 145  * @param format
 146  *   The format string.
 147  * @param ap
 148  *   The list of arguments.
 149  * @return
 150  *   0 on success, -1 on error (errno is set).
 151  */
 152 int ec_vlog(int type, enum ec_log_level level, const char *format, va_list ap);
 153
 154 /**
 155  * Log a formatted string using the local log type.
 156  *
 157  * This macro requires that a log type is previously register with
 158  * EC_LOG_TYPE_REGISTER() since it uses the "ec_log_local_type"
 159  * variable.
 160  *
 161  * @param level
 162  *   The log level.
 163  * @param format
 164  *   The format string, followed by optional arguments.
 165  * @return
 166  *   0 on success, -1 on error (errno is set).
 167  */
 168 #define EC_LOG(level, args...) ec_log(ec_log_local_type, level, args)
 169
 170 /**
 171  * Log a formatted string using the local log type.
 172  *
 173  * This macro requires that a log type is previously register with
 174  * EC_LOG_TYPE_REGISTER() since it uses the "ec_log_local_type"
 175  * variable.
 176  *
 177  * @param level
 178  *   The log level.
 179  * @param format
 180  *   The format string.
 181  * @param ap
 182  *   The list of arguments.
 183  * @return
 184  *   0 on success, -1 on error (errno is set).
 185  */
 186 #define EC_VLOG(level, fmt, ap) ec_vlog(ec_log_local_type, level, fmt, ap)
 187
 188 /**
 189  * Default log handler.
 190  *
 191  * This is the default log function that is used by the library. By
 192  * default, it prints all logs whose level is WARNING or more critical.
 193  * This level can be changed with ec_log_level_set().
 194  *
 195  * @param type
 196  *   The log type identifier.
 197  * @param level
 198  *   The log level.
 199  * @param opaque
 200  *   Unused.
 201  * @param str
 202  *   The string to be logged.
 203  * @return
 204  *   0 on success, -1 on error (errno is set).
 205  */
 206 int ec_log_default_cb(int type, enum ec_log_level level, void *opaque,
 207                 const char *str);
 208
 209 /**
 210  * Set the global log level.
 211  *
 212  * This level is used by the default log handler, ec_log_default_cb().
 213  * All messages that are at least as critical as the default level are
 214  * displayed.
 215  *
 216  * It is advised
 217  *
 218  * @param level
 219  *   The log level to be set.
 220  * @return
 221  *   0 on success, -1 on error.
 222  */
 223 int ec_log_level_set(enum ec_log_level level);
 224
 225 /**
 226  * Get the global log level.
 227  *
 228  * This level is used by the default log handler, ec_log_default_cb().
 229  * All messages that are at least as critical as the default level are
 230  * displayed.
 231  *
 232  * @param level
 233  *   The log level to be set.
 234  * @return
 235  *   0 on success, -1 on error.
 236  */
 237 enum ec_log_level ec_log_level_get(void);
 238
 239 #endif