lib/ecoli_log.h

   1 /*
   2  * Copyright (c) 2016, Olivier MATZ <zer0@droids-corp.org>
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of the University of California, Berkeley nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 /**
  29  * Logging API
  30  *
  31  * This file provide logging helpers:
  32  * - logging functions, supporting printf-like format
  33  * - several debug level (similar to syslog)
  34  * - named log types
  35  * - redirection of log to a user functions (default logs nothing)
  36  */
  37
  38 #ifndef ECOLI_LOG_
  39 #define ECOLI_LOG_
  40
  41 #include <stdarg.h>
  42
  43 #include <ecoli_assert.h>
  44
  45 enum ec_log_level {
  46         EC_LOG_EMERG   = 0,  /* system is unusable               */
  47         EC_LOG_ALERT   = 1,  /* action must be taken immediately */
  48         EC_LOG_CRIT    = 2,  /* critical conditions              */
  49         EC_LOG_ERR     = 3,  /* error conditions                 */
  50         EC_LOG_WARNING = 4,  /* warning conditions               */
  51         EC_LOG_NOTICE  = 5,  /* normal but significant condition */
  52         EC_LOG_INFO    = 6,  /* informational                    */
  53         EC_LOG_DEBUG   = 7,  /* debug-level messages             */
  54 };
  55
  56 /**
  57  * Register a log type.
  58  *
  59  * This macro defines a function that will be called at startup (using
  60  * the "constructor" attribute). This function register the named type
  61  * passed as argument, and sets a static global variable
  62  * "ec_log_local_type". This variable is used as the default log type
  63  * for this file when using EC_LOG() or EC_VLOG().
  64  *
  65  * This macro can be present several times in a file. In this case, the
  66  * local log type is set to the last registered type.
  67  *
  68  * On error, the function aborts.
  69  *
  70  * @param name
  71  *   The name of the log to be registered.
  72  */
  73 #define EC_LOG_TYPE_REGISTER(name)                                      \
  74         static int name##_log_type;                                     \
  75         static int ec_log_local_type;                                   \
  76         __attribute__((constructor, used))                              \
  77         static void ec_log_register_##name(void)                        \
  78         {                                                               \
  79                 ec_log_local_type = ec_log_type_register(#name);        \
  80                 ec_assert_print(ec_log_local_type >= 0,                 \
  81                                 "cannot register log type.\n");         \
  82                 name##_log_type = ec_log_local_type;                    \
  83         }
  84
  85 /**
  86  * User log function type.
  87  *
  88  * It is advised that a user-defined log function drops all messages
  89  * that are at least as critical as ec_log_level_get(), as done by the
  90  * default handler.
  91  *
  92  * @param type
  93  *   The log type identifier.
  94  * @param level
  95  *   The log level.
  96  * @param opaque
  97  *   The opaque pointer that was passed to ec_log_fct_register().
  98  * @param str
  99  *   The string to log.
 100  * @return
 101  *   0 on success, -1 on error (errno is set).
 102  */
 103 typedef int (*ec_log_t)(int type, enum ec_log_level level, void *opaque,
 104                         const char *str);
 105
 106 /**
 107  * Register a user log function.
 108  *
 109  * @param usr_log
 110  *   Function pointer that will be invoked for each log call.
 111  *   If the parameter is NULL, ec_log_default_cb() is used.
 112  * @param opaque
 113  *   Opaque pointer passed to the log function.
 114  * @return
 115  *   0 on success, -1 on error (errno is set).
 116  */
 117 int ec_log_fct_register(ec_log_t usr_log, void *opaque);
 118
 119 /**
 120  * Register a named log type.
 121  *
 122  * Register a new log type, which is identified by its name. The
 123  * function returns a log identifier associated to the log name. If the
 124  * name is already registered, the function just returns its identifier.
 125  *
 126  * @param name
 127  *   The name of the log type.
 128  * @return
 129  *   The log type identifier on success (positive or zero), -1 on
 130  *   error (errno is set).
 131  */
 132 int ec_log_type_register(const char *name);
 133
 134 /**
 135  * Return the log name associated to the log type identifier.
 136  *
 137  * @param type
 138  *   The log type identifier.
 139  * @return
 140  *   The name associated to the log type, or "unknown". It always return
 141  *   a valid string (never NULL).
 142  */
 143 const char *ec_log_name(int type);
 144
 145 /**
 146  * Log a formatted string.
 147  *
 148  * @param type
 149  *   The log type identifier.
 150  * @param level
 151  *   The log level.
 152  * @param format
 153  *   The format string, followed by optional arguments.
 154  * @return
 155  *   0 on success, -1 on error (errno is set).
 156  */
 157 int ec_log(int type, enum ec_log_level level, const char *format, ...)
 158         __attribute__((format(__printf__, 3, 4)));
 159
 160 /**
 161  * Log a formatted string.
 162  *
 163  * @param type
 164  *   The log type identifier.
 165  * @param level
 166  *   The log level.
 167  * @param format
 168  *   The format string.
 169  * @param ap
 170  *   The list of arguments.
 171  * @return
 172  *   0 on success, -1 on error (errno is set).
 173  */
 174 int ec_vlog(int type, enum ec_log_level level, const char *format, va_list ap);
 175
 176 /**
 177  * Log a formatted string using the local log type.
 178  *
 179  * This macro requires that a log type is previously register with
 180  * EC_LOG_TYPE_REGISTER() since it uses the "ec_log_local_type"
 181  * variable.
 182  *
 183  * @param level
 184  *   The log level.
 185  * @param format
 186  *   The format string, followed by optional arguments.
 187  * @return
 188  *   0 on success, -1 on error (errno is set).
 189  */
 190 #define EC_LOG(level, args...) ec_log(ec_log_local_type, level, args)
 191
 192 /**
 193  * Log a formatted string using the local log type.
 194  *
 195  * This macro requires that a log type is previously register with
 196  * EC_LOG_TYPE_REGISTER() since it uses the "ec_log_local_type"
 197  * variable.
 198  *
 199  * @param level
 200  *   The log level.
 201  * @param format
 202  *   The format string.
 203  * @param ap
 204  *   The list of arguments.
 205  * @return
 206  *   0 on success, -1 on error (errno is set).
 207  */
 208 #define EC_VLOG(level, fmt, ap) ec_vlog(ec_log_local_type, level, fmt, ap)
 209
 210 /**
 211  * Default log handler.
 212  *
 213  * This is the default log function that is used by the library. By
 214  * default, it prints all logs whose level is WARNING or more critical.
 215  * This level can be changed with ec_log_level_set().
 216  *
 217  * @param type
 218  *   The log type identifier.
 219  * @param level
 220  *   The log level.
 221  * @param opaque
 222  *   Unused.
 223  * @param str
 224  *   The string to be logged.
 225  * @return
 226  *   0 on success, -1 on error (errno is set).
 227  */
 228 int ec_log_default_cb(int type, enum ec_log_level level, void *opaque,
 229                 const char *str);
 230
 231 /**
 232  * Set the global log level.
 233  *
 234  * This level is used by the default log handler, ec_log_default_cb().
 235  * All messages that are at least as critical as the default level are
 236  * displayed.
 237  *
 238  * It is advised
 239  *
 240  * @param level
 241  *   The log level to be set.
 242  * @return
 243  *   0 on success, -1 on error.
 244  */
 245 int ec_log_level_set(enum ec_log_level level);
 246
 247 /**
 248  * Get the global log level.
 249  *
 250  * This level is used by the default log handler, ec_log_default_cb().
 251  * All messages that are at least as critical as the default level are
 252  * displayed.
 253  *
 254  * @param level
 255  *   The log level to be set.
 256  * @return
 257  *   0 on success, -1 on error.
 258  */
 259 enum ec_log_level ec_log_level_get(void);
 260
 261 #endif