include/babeltrace2/logging.h

   1 #ifndef BABELTRACE2_LOGGING_H
   2 #define BABELTRACE2_LOGGING_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the "Software"), to deal
   9  * in the Software without restriction, including without limitation the rights
  10  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11  * copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  20  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  23  * SOFTWARE.
  24  */
  25
  26 #ifndef __BT_IN_BABELTRACE_H
  27 # error "Please include <babeltrace2/babeltrace.h> instead."
  28 #endif
  29
  30 #include <babeltrace2/logging-defs.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37 @defgroup logging Logging
  38 @ingroup apiref
  39 @brief Logging.
  40
  41 @code
  42 #include <babeltrace2/logging.h>
  43 @endcode
  44
  45 The functions in this module control the Babeltrace library's logging
  46 behaviour.
  47
  48 You can set the current global log level of the library with
  49 bt_logging_set_global_level(). Note that, if the level you set is below
  50 the minimal logging level (configured at build time, which you can get
  51 with bt_logging_get_minimal_level()), the logging statement between the
  52 current global log level and the minimal log level are not executed.
  53
  54 @file
  55 @brief Logging functions.
  56 @sa logging
  57
  58 @addtogroup logging
  59 @{
  60 */
  61
  62 /**
  63 @brief Log levels.
  64 */
  65 typedef enum bt_logging_level {
  66         /// Additional, low-level debugging context information.
  67         BT_LOGGING_LEVEL_TRACE          = __BT_LOGGING_LEVEL_TRACE,
  68
  69         /**
  70         Debugging information, only useful when searching for the
  71         cause of a bug.
  72         */
  73         BT_LOGGING_LEVEL_DEBUG          = __BT_LOGGING_LEVEL_DEBUG,
  74
  75         /**
  76         Non-debugging information and failure to load optional
  77         subsystems.
  78         */
  79         BT_LOGGING_LEVEL_INFO           = __BT_LOGGING_LEVEL_INFO,
  80
  81         /**
  82         Errors caused by a bad usage of the library, that is, a
  83         non-observance of the documented function preconditions.
  84
  85         The library's and object's states remain consistent when a
  86         warning is issued.
  87         */
  88         BT_LOGGING_LEVEL_WARNING        = __BT_LOGGING_LEVEL_WARNING,
  89
  90         /**
  91         An important error from which the library cannot recover, but
  92         the executed stack of functions can still return cleanly.
  93         */
  94         BT_LOGGING_LEVEL_ERROR          = __BT_LOGGING_LEVEL_ERROR,
  95
  96         /**
  97         The library cannot continue to work in this condition: it must
  98         terminate immediately, without even returning to the user's
  99         execution.
 100         */
 101         BT_LOGGING_LEVEL_FATAL          = __BT_LOGGING_LEVEL_FATAL,
 102
 103         /// Logging is disabled.
 104         BT_LOGGING_LEVEL_NONE           = __BT_LOGGING_LEVEL_NONE,
 105 } bt_logging_level;
 106
 107 /**
 108 @brief  Returns the minimal log level of the Babeltrace library.
 109
 110 The minimal log level is defined at the library's build time. Any
 111 logging statement with a level below the minimal log level is not
 112 compiled. This means that it is useless, although possible, to set the
 113 global log level with bt_logging_set_global_level() below this level.
 114
 115 @returns        Minimal, build time log level.
 116
 117 @sa bt_logging_get_global_level(): Returns the current global log level.
 118 */
 119 extern bt_logging_level bt_logging_get_minimal_level(void);
 120
 121 /**
 122 @brief  Returns the current global log level of the Babeltrace library.
 123
 124 @returns        Current global log level.
 125
 126 @sa bt_logging_set_global_level(): Sets the current global log level.
 127 @sa bt_logging_get_minimal_level(): Returns the minimal log level.
 128 */
 129 extern bt_logging_level bt_logging_get_global_level(void);
 130
 131 /**
 132 @brief  Sets the current global log level of the Babeltrace library
 133         to \p log_level.
 134
 135 If \p log_level is below what bt_logging_get_minimal_level() returns,
 136 the logging statements with a level between \p log_level and the minimal
 137 log level cannot be executed.
 138
 139 @param[in] log_level    Library's new global log level.
 140
 141 @sa bt_logging_get_global_level(): Returns the global log level.
 142 */
 143 extern void bt_logging_set_global_level(bt_logging_level log_level);
 144
 145 /** @} */
 146
 147 #ifdef __cplusplus
 148 }
 149 #endif
 150
 151 #endif /* BABELTRACE2_LOGGING_H */