lib: make trace IR API const-correct
[babeltrace.git] / include / babeltrace / logging.h
1 #ifndef BABELTRACE_LOGGING_H
2 #define BABELTRACE_LOGGING_H
3
4 /*
5 * Copyright (c) 2017 Philippe Proulx <pproulx@efficios.com>
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 #include <stdint.h>
27 #include <stdbool.h>
28 #include <stddef.h>
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 /**
35 @defgroup logging Logging
36 @ingroup apiref
37 @brief Logging.
38
39 @code
40 #include <babeltrace/logging.h>
41 @endcode
42
43 The functions in this module control the Babeltrace library's logging
44 behaviour.
45
46 You can set the current global log level of the library with
47 bt_logging_set_global_level(). Note that, if the level you set is below
48 the minimal logging level (configured at build time, which you can get
49 with bt_logging_get_minimal_level()), the logging statement between the
50 current global log level and the minimal log level are not executed.
51
52 @file
53 @brief Logging functions.
54 @sa logging
55
56 @addtogroup logging
57 @{
58 */
59
60 /**
61 @brief Log levels.
62 */
63 enum bt_logging_level {
64 /// Additional, low-level debugging context information.
65 BT_LOGGING_LEVEL_VERBOSE = 1,
66
67 /**
68 Debugging information, only useful when searching for the
69 cause of a bug.
70 */
71 BT_LOGGING_LEVEL_DEBUG = 2,
72
73 /**
74 Non-debugging information and failure to load optional
75 subsystems.
76 */
77 BT_LOGGING_LEVEL_INFO = 3,
78
79 /**
80 Errors caused by a bad usage of the library, that is, a
81 non-observance of the documented function preconditions.
82
83 The library's and object's states remain consistent when a
84 warning is issued.
85 */
86 BT_LOGGING_LEVEL_WARN = 4,
87
88 /**
89 An important error from which the library cannot recover, but
90 the executed stack of functions can still return cleanly.
91 */
92 BT_LOGGING_LEVEL_ERROR = 5,
93
94 /**
95 The library cannot continue to work in this condition: it must
96 terminate immediately, without even returning to the user's
97 execution.
98 */
99 BT_LOGGING_LEVEL_FATAL = 6,
100
101 /// Logging is disabled.
102 BT_LOGGING_LEVEL_NONE = 0xff,
103 };
104
105 /**
106 @brief Returns the minimal log level of the Babeltrace library.
107
108 The minimal log level is defined at the library's build time. Any
109 logging statement with a level below the minimal log level is not
110 compiled. This means that it is useless, although possible, to set the
111 global log level with bt_logging_set_global_level() below this level.
112
113 @returns Minimal, build time log level.
114
115 @sa bt_logging_get_global_level(): Returns the current global log level.
116 */
117 extern enum bt_logging_level bt_logging_get_minimal_level(void);
118
119 /**
120 @brief Returns the current global log level of the Babeltrace library.
121
122 @returns Current global log level.
123
124 @sa bt_logging_set_global_level(): Sets the current global log level.
125 @sa bt_logging_get_minimal_level(): Returns the minimal log level.
126 */
127 extern enum bt_logging_level bt_logging_get_global_level(void);
128
129 /**
130 @brief Sets the current global log level of the Babeltrace library
131 to \p log_level.
132
133 If \p log_level is below what bt_logging_get_minimal_level() returns,
134 the logging statements with a level between \p log_level and the minimal
135 log level cannot be executed.
136
137 @param[in] log_level Library's new global log level.
138
139 @sa bt_logging_get_global_level(): Returns the global log level.
140 */
141 extern void bt_logging_set_global_level(enum bt_logging_level log_level);
142
143 /** @} */
144
145 #ifdef __cplusplus
146 }
147 #endif
148
149 #endif /* BABELTRACE_LOGGING_H */
This page took 0.033649 seconds and 4 git commands to generate.