[babeltrace.git] / include / babeltrace2 / logging.h

#ifndef BABELTRACE_LOGGING_H
#define BABELTRACE_LOGGING_H

/*
 * Copyright (c) 2017 Philippe Proulx <pproulx@efficios.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
@defgroup logging Logging
@ingroup apiref
@brief Logging.

@code
#include <babeltrace2/logging.h>
@endcode

The functions in this module control the Babeltrace library's logging
behaviour.

You can set the current global log level of the library with
bt_logging_set_global_level(). Note that, if the level you set is below
the minimal logging level (configured at build time, which you can get
with bt_logging_get_minimal_level()), the logging statement between the
current global log level and the minimal log level are not executed.

@file
@brief Logging functions.
@sa logging

@addtogroup logging
@{
*/

/**
@brief Log levels.
*/
typedef enum bt_logging_level {
	/// Additional, low-level debugging context information.
	BT_LOGGING_LEVEL_TRACE		= 1,

	/**
	Debugging information, only useful when searching for the
	cause of a bug.
	*/
	BT_LOGGING_LEVEL_DEBUG		= 2,

	/**
	Non-debugging information and failure to load optional
	subsystems.
	*/
	BT_LOGGING_LEVEL_INFO		= 3,

	/**
	Errors caused by a bad usage of the library, that is, a
	non-observance of the documented function preconditions.

	The library's and object's states remain consistent when a
	warning is issued.
	*/
	BT_LOGGING_LEVEL_WARN		= 4,

	/**
	An important error from which the library cannot recover, but
	the executed stack of functions can still return cleanly.
	*/
	BT_LOGGING_LEVEL_ERROR		= 5,

	/**
	The library cannot continue to work in this condition: it must
	terminate immediately, without even returning to the user's
	execution.
	*/
	BT_LOGGING_LEVEL_FATAL		= 6,

	/// Logging is disabled.
	BT_LOGGING_LEVEL_NONE		= 0xff,
} bt_logging_level;

/**
@brief	Returns the minimal log level of the Babeltrace library.

The minimal log level is defined at the library's build time. Any
logging statement with a level below the minimal log level is not
compiled. This means that it is useless, although possible, to set the
global log level with bt_logging_set_global_level() below this level.

@returns	Minimal, build time log level.

@sa bt_logging_get_global_level(): Returns the current global log level.
*/
extern bt_logging_level bt_logging_get_minimal_level(void);

/**
@brief	Returns the current global log level of the Babeltrace library.

@returns	Current global log level.

@sa bt_logging_set_global_level(): Sets the current global log level.
@sa bt_logging_get_minimal_level(): Returns the minimal log level.
*/
extern bt_logging_level bt_logging_get_global_level(void);

/**
@brief	Sets the current global log level of the Babeltrace library
	to \p log_level.

If \p log_level is below what bt_logging_get_minimal_level() returns,
the logging statements with a level between \p log_level and the minimal
log level cannot be executed.

@param[in] log_level	Library's new global log level.

@sa bt_logging_get_global_level(): Returns the global log level.
*/
extern void bt_logging_set_global_level(bt_logging_level log_level);

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_LOGGING_H */
Commit	Line	Data
beb0fb75 PP	1	#ifndef BABELTRACE_LOGGING_H
	2	#define BABELTRACE_LOGGING_H
	3
	4	/*
beb0fb75 PP	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>
beb0fb75 PP	29
	30	#ifdef __cplusplus
	31	extern "C" {
	32	#endif
	33
	34	/**
	35	@defgroup logging Logging
	36	@ingroup apiref
	37	@brief Logging.
	38
	39	@code
3fadfbc0	40	#include <babeltrace2/logging.h>
beb0fb75 PP	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	*/
4cdfc5e8	63	typedef enum bt_logging_level {
beb0fb75	64	/// Additional, low-level debugging context information.
ef267d12	65	BT_LOGGING_LEVEL_TRACE = 1,
beb0fb75 PP	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,
4cdfc5e8	103	} bt_logging_level;
beb0fb75 PP	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	*/
4cdfc5e8	117	extern bt_logging_level bt_logging_get_minimal_level(void);
beb0fb75 PP	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	*/
4cdfc5e8	127	extern bt_logging_level bt_logging_get_global_level(void);
beb0fb75 PP	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	*/
4cdfc5e8	141	extern void bt_logging_set_global_level(bt_logging_level log_level);
beb0fb75 PP	142
	143	/** @} */
	144
	145	#ifdef __cplusplus
	146	}
	147	#endif
	148
	149	#endif /* BABELTRACE_LOGGING_H */