include/ecoli_log.h

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