log.h File Reference

Logging infrastructure. More...

#include <sstream>
#include <libcamera/base/private.h>
#include <libcamera/base/class.h>
#include <libcamera/base/utils.h>

Include dependency graph for log.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	libcamera::LogCategory
	A category of log message. More...
class	libcamera::LogMessage
	Internal log message representation. More...
class	libcamera::Loggable
	Base class to support log message extensions. More...

Namespaces
	libcamera
	Top-level libcamera namespace.

Macros
#define	LOG_DECLARE_CATEGORY(name)
	Declare a category of log messages. More...
#define	LOG_DEFINE_CATEGORY(name)
	Define a category of log messages. More...
#define	LOG(category, severity)
	Log a message. More...
#define	ASSERT(condition)
	Abort program execution if assertion fails. More...

Enumerations
enum	libcamera::LogSeverity {   LogInvalid = -1, libcamera::LogDebug = 0, libcamera::LogInfo, libcamera::LogWarning,   libcamera::LogError, libcamera::LogFatal }

Functions
LogMessage	libcamera::_log (const LogCategory *category, LogSeverity severity, const char *fileName, unsigned int line)
	Create a temporary LogMessage object to log a message. More...

Detailed Description

Logging infrastructure.

libcamera includes a logging infrastructure used through the library that allows inspection of internal operation in a user-configurable way. The log messages are grouped in categories that represent areas of libcamera, and output of messages for each category can be controlled by independent log levels.

The levels are configurable through the LIBCAMERA_LOG_LEVELS environment variable that contains a comma-separated list of 'category:level' pairs.

The category names are strings and can include a wildcard ('*') character at the end to match multiple categories.

The level are either numeric values, or strings containing the log level name. The available log levels are DEBUG, INFO, WARN, ERROR and FATAL. Log message with a level higher than or equal to the configured log level for their category are output to the log, while other messages are silently discarded.

By default log messages are output to std::cerr. They can be redirected to a log file by setting the LIBCAMERA_LOG_FILE environment variable to the name of the file. The file must be writable and is truncated if it exists. If any error occurs when opening the file, the file is ignored and the log is output to std::cerr.

Macro Definition Documentation

ASSERT

#define ASSERT

(

condition

)

Abort program execution if assertion fails.

If condition is false, ASSERT() logs an error message with the Fatal log level and aborts program execution.

If the macro NDEBUG is defined before including log.h, ASSERT() generates no code.

Using conditions that have side effects with ASSERT() is not recommended, as these effects would depend on whether NDEBUG is defined or not. Similarly, ASSERT() should not be used to check for errors that can occur under normal conditions as those checks would then be removed when compiling with NDEBUG.

LOG

#define LOG	(		category,
			severity
	)

Log a message.

Parameters

[in]	category	Category (optional)
[in]	severity	Severity

Return an std::ostream reference to which a message can be logged using the iostream API. The category, if specified, sets the message category. When absent the default category is used. The severity controls whether the message is printed or discarded, depending on the log level for the category.

If the severity is set to Fatal, execution is aborted and the program terminates immediately after printing the message.

Warning

Logging from the destructor of a global object, either directly or indirectly, results in undefined behaviour.

Todo:

Allow logging from destructors of global objects to the largest possible extent

LOG_DECLARE_CATEGORY

#define LOG_DECLARE_CATEGORY

(

name

)

Declare a category of log messages.

This macro is used to declare a log category defined in another compilation unit by the LOG_DEFINE_CATEGORY() macro.

The LOG_DECLARE_CATEGORY() macro must be used in the libcamera namespace.

See also

LogCategory

LOG_DEFINE_CATEGORY

#define LOG_DEFINE_CATEGORY

(

name

)

Define a category of log messages.

This macro is used to define a log category that can then be used with the LOGC() macro. Category names shall be unique, if a category is shared between compilation units, it shall be defined in one compilation unit only and declared with LOG_DECLARE_CATEGORY() in the other compilation units.

The LOG_DEFINE_CATEGORY() macro must be used in the libcamera namespace.

See also

LogCategory