Logging

Detailed Description

Classes
class	BinaryNinja::LogListener
class	BinaryNinja::Logger
	Logger is a class allowing scoped logging to the console. More...
class	BinaryNinja::LogRegistry
	A class allowing registering and retrieving Loggers. More...
class	BinaryNinja::LoggerIndentScope
	RAII helper that indents/dedents a Logger inside a scope. More...

Functions
void	BinaryNinja::Log (BNLogLevel level, const char *fmt,...)
	Logs to the error console with the given BNLogLevel.
void	BinaryNinja::LogTrace (const char *fmt,...)
	LogTrace only writes text to the error console if the console is set to log level: DebugLog Log level and the build is not a DEBUG build (i.e.
void	BinaryNinja::LogDebug (const char *fmt,...)
	LogDebug only writes text to the error console if the console is set to log level: DebugLog Log level DebugLog is the most verbose logging level in release builds.
void	BinaryNinja::LogInfo (const char *fmt,...)
	LogInfo always writes text to the error console, and corresponds to the log level: InfoLog.
void	BinaryNinja::LogWarn (const char *fmt,...)
	LogWarn writes text to the error console including a warning icon, and also shows a warning icon in the bottom pane.
void	BinaryNinja::LogError (const char *fmt,...)
	LogError writes text to the error console and pops up the error console.
void	BinaryNinja::LogAlert (const char *fmt,...)
	LogAlert pops up a message box displaying the alert message and logs to the error console.
template<typename... T>
void	BinaryNinja::LogF (BNLogLevel level, fmt::format_string< T... > format, T &&... args)
	Logs to the error console with the given BNLogLevel.
template<typename... T>
void	BinaryNinja::LogTraceF (fmt::format_string< T... > format, T &&... args)
	LogTrace only writes text to the error console if the console is set to log level: DebugLog Log level and the build is not a DEBUG build (i.e.
template<typename... T>
void	BinaryNinja::LogDebugF (fmt::format_string< T... > format, T &&... args)
	LogDebug only writes text to the error console if the console is set to log level: DebugLog Log level DebugLog is the most verbose logging level in release builds.
template<typename... T>
void	BinaryNinja::LogInfoF (fmt::format_string< T... > format, T &&... args)
	LogInfo always writes text to the error console, and corresponds to the log level: InfoLog.
template<typename... T>
void	BinaryNinja::LogWarnF (fmt::format_string< T... > format, T &&... args)
	LogWarn writes text to the error console including a warning icon, and also shows a warning icon in the bottom pane.
template<typename... T>
void	BinaryNinja::LogErrorF (fmt::format_string< T... > format, T &&... args)
	LogError writes text to the error console and pops up the error console.
template<typename... T>
void	BinaryNinja::LogAlertF (fmt::format_string< T... > format, T &&... args)
	LogAlert pops up a message box displaying the alert message and logs to the error console.
void	BinaryNinja::LogToStdout (BNLogLevel minimumLevel)
	Redirects the minimum level passed to standard out.
void	BinaryNinja::LogToStderr (BNLogLevel minimumLevel)
	Redirects the minimum level passed to standard error.
bool	BinaryNinja::LogToFile (BNLogLevel minimumLevel, const std::string &path, bool append=false)
	Redirects minimum log level to the file at `path`, optionally appending rather than overwriting.
void	BinaryNinja::CloseLogs ()
	Close all log files.

---

Class Documentation

BinaryNinja::LogListener

class BinaryNinja::LogListener

Public Member Functions
virtual	~LogListener ()
virtual void	LogMessage (size_t session, BNLogLevel level, const std::string &msg, const std::string &logger_name="", size_t tid=0)=0
virtual void	CloseLog ()
virtual BNLogLevel	GetLogLevel ()
Static Public Member Functions
static void	RegisterLogListener (LogListener *listener)
static void	UnregisterLogListener (LogListener *listener)
static void	UpdateLogListeners ()

Constructor & Destructor Documentation

~LogListener()

virtual BinaryNinja::LogListener::~LogListener ( )

inlinevirtual

Member Function Documentation

RegisterLogListener()

void LogListener::RegisterLogListener ( LogListener * listener )

static

UnregisterLogListener()

void LogListener::UnregisterLogListener ( LogListener * listener )

static

UpdateLogListeners()

void LogListener::UpdateLogListeners ( )

static

LogMessage()

virtual void BinaryNinja::LogListener::LogMessage ( size_t session, BNLogLevel level, const std::string & msg, const std::string & logger_name = "", size_t tid = 0 )

pure virtual

Implemented in LogListModel.

CloseLog()

virtual void BinaryNinja::LogListener::CloseLog ( )

inlinevirtual

GetLogLevel()

virtual BNLogLevel BinaryNinja::LogListener::GetLogLevel ( )

inlinevirtual

Reimplemented in LogListModel.

BinaryNinja::Logger

class BinaryNinja::Logger

Logger is a class allowing scoped logging to the console.

Public Member Functions
	Logger (BNLogger *logger)
	Logger (const std::string &loggerName, size_t sessionId=0)
	Create a logger with the specified name and session ID.
void	Log (BNLogLevel level, const char *fmt,...)
	Logs to the error console with the given BNLogLevel.
void	LogTrace (const char *fmt,...)
	LogTrace only writes text to the error console if the console is set to log level: DebugLog Log level and the build is not a DEBUG build (i.e.
void	LogDebug (const char *fmt,...)
	LogDebug only writes text to the error console if the console is set to log level: DebugLog Log level DebugLog is the most verbose logging level in release builds.
void	LogInfo (const char *fmt,...)
	LogInfo always writes text to the error console, and corresponds to the log level: InfoLog.
void	LogWarn (const char *fmt,...)
	LogWarn writes text to the error console including a warning icon, and also shows a warning icon in the bottom pane.
void	LogError (const char *fmt,...)
	LogError writes text to the error console and pops up the error console.
void	LogAlert (const char *fmt,...)
	LogAlert pops up a message box displaying the alert message and logs to the error console.
template<typename... T>
void	LogF (BNLogLevel level, fmt::format_string< T... > format, T &&... args)
	Logs to the error console with the given BNLogLevel.
template<typename... T>
void	LogTraceF (fmt::format_string< T... > format, T &&... args)
	LogTrace only writes text to the error console if the console is set to log level: DebugLog Log level and the build is not a DEBUG build (i.e.
template<typename... T>
void	LogDebugF (fmt::format_string< T... > format, T &&... args)
	LogDebug only writes text to the error console if the console is set to log level: DebugLog Log level DebugLog is the most verbose logging level in release builds.
template<typename... T>
void	LogInfoF (fmt::format_string< T... > format, T &&... args)
	LogInfo always writes text to the error console, and corresponds to the log level: InfoLog.
template<typename... T>
void	LogWarnF (fmt::format_string< T... > format, T &&... args)
	LogWarn writes text to the error console including a warning icon, and also shows a warning icon in the bottom pane.
template<typename... T>
void	LogErrorF (fmt::format_string< T... > format, T &&... args)
	LogError writes text to the error console and pops up the error console.
template<typename... T>
void	LogAlertF (fmt::format_string< T... > format, T &&... args)
	LogAlert pops up a message box displaying the alert message and logs to the error console.
std::string	GetName ()
	Get the name registered for this Logger.
size_t	GetSessionId ()
	Get the session ID registered for this logger.
void	Indent ()
	Indent the logger's indentation level by one.
void	Dedent ()
	Decrease the logger's indentation level by one.
void	ResetIndent ()
	Set the logger's indentation level to zero.
std::string	GetIndent () const
	Get the string to prepend to log messages to indent them.
Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNLogger, BNNewLoggerReference, BNFreeLogger >
	CoreRefCountObject ()
virtual	~CoreRefCountObject ()
BNLogger *	GetObject () const
void	AddRef ()
void	Release ()
void	AddRefForRegistration ()
void	ReleaseForRegistration ()
void	AddRefForCallback ()
void	ReleaseForCallback ()
Friends
struct	Iterator

Additional Inherited Members
Static Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNLogger, BNNewLoggerReference, BNFreeLogger >
static BNLogger *	GetObject (CoreRefCountObject *obj)
static BNLogger *	GetObject (const CoreRefCountObject *obj)
Public Attributes inherited from BinaryNinja::CoreRefCountObject< BNLogger, BNNewLoggerReference, BNFreeLogger >
std::atomic< int >	m_refs
bool	m_registeredRef
BNLogger *	m_object

Constructor & Destructor Documentation

Logger() [1/2]

Logger::Logger

(

BNLogger *

logger

)

Logger() [2/2]

BinaryNinja::Logger::Logger	(	const std::string &	loggerName,
		size_t	sessionId = 0 )

Create a logger with the specified name and session ID.

Warning

You may want to use LogRegistry::CreateLogger and LogRegistry::GetLogger instead of this. If you already have access to a BinaryView, you may want to use bv->CreateLogger() instead of this.

See also

BinaryView::CreateLogger()

auto logger = Logger("MyPluginName", 0);

Session ID corresponds to the tab for the specified BinaryView, and the default of 0 will log to *all tabs*.

See also

FileMetadata::GetSessionId()

Parameters

loggerName	Name of the logger to create
sessionId	Session ID for the logger.

Member Function Documentation

Log()

void Logger::Log	(	BNLogLevel	level,
		const char *	fmt,
			... )

Logs to the error console with the given BNLogLevel.

Thread Safe:

Yes

Parameters

level	BNLogLevel debug log level
fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogTrace()

void Logger::LogTrace	(	const char *	fmt,
			... )

LogTrace only writes text to the error console if the console is set to log level: DebugLog Log level and the build is not a DEBUG build (i.e.

the preprocessor directive _DEBUG is defined)

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogDebug()

void Logger::LogDebug	(	const char *	fmt,
			... )

LogDebug only writes text to the error console if the console is set to log level: DebugLog Log level DebugLog is the most verbose logging level in release builds.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogInfo()

void Logger::LogInfo	(	const char *	fmt,
			... )

LogInfo always writes text to the error console, and corresponds to the log level: InfoLog.

Log level InfoLog is the second most verbose logging level.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogWarn()

void Logger::LogWarn	(	const char *	fmt,
			... )

LogWarn writes text to the error console including a warning icon, and also shows a warning icon in the bottom pane.

LogWarn corresponds to the log level: WarningLog.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogError()

void Logger::LogError	(	const char *	fmt,
			... )

LogError writes text to the error console and pops up the error console.

Additionally, Errors in the console log include a error icon. LogError corresponds to the log level: ErrorLog.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogAlert()

void Logger::LogAlert	(	const char *	fmt,
			... )

LogAlert pops up a message box displaying the alert message and logs to the error console.

LogAlert corresponds to the log level: AlertLog.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogF()

template<typename... T>

void BinaryNinja::Logger::LogF ( BNLogLevel level, fmt::format_string< T... > format, T &&... args )

inline

Logs to the error console with the given BNLogLevel.

Thread Safe:

Yes

Parameters

level	BNLogLevel debug log level
format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogTraceF()

template<typename... T>

void BinaryNinja::Logger::LogTraceF ( fmt::format_string< T... > format, T &&... args )

inline

LogTrace only writes text to the error console if the console is set to log level: DebugLog Log level and the build is not a DEBUG build (i.e.

the preprocessor directive _DEBUG is defined)

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogDebugF()

template<typename... T>

void BinaryNinja::Logger::LogDebugF ( fmt::format_string< T... > format, T &&... args )

inline

LogDebug only writes text to the error console if the console is set to log level: DebugLog Log level DebugLog is the most verbose logging level in release builds.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogInfoF()

template<typename... T>

void BinaryNinja::Logger::LogInfoF ( fmt::format_string< T... > format, T &&... args )

inline

LogInfo always writes text to the error console, and corresponds to the log level: InfoLog.

Log level InfoLog is the second most verbose logging level.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogWarnF()

template<typename... T>

void BinaryNinja::Logger::LogWarnF ( fmt::format_string< T... > format, T &&... args )

inline

LogWarn writes text to the error console including a warning icon, and also shows a warning icon in the bottom pane.

LogWarn corresponds to the log level: WarningLog.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogErrorF()

template<typename... T>

void BinaryNinja::Logger::LogErrorF ( fmt::format_string< T... > format, T &&... args )

inline

LogError writes text to the error console and pops up the error console.

Additionally, Errors in the console log include a error icon. LogError corresponds to the log level: ErrorLog.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogAlertF()

template<typename... T>

void BinaryNinja::Logger::LogAlertF ( fmt::format_string< T... > format, T &&... args )

inline

LogAlert pops up a message box displaying the alert message and logs to the error console.

LogAlert corresponds to the log level: AlertLog.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

GetName()

string Logger::GetName

(

)

Get the name registered for this Logger.

Thread Safe:

Yes

Returns

The logger name

GetSessionId()

size_t Logger::GetSessionId

(

)

Get the session ID registered for this logger.

Thread Safe:

Yes

Returns

The logger session ID

Indent()

void Logger::Indent

(

)

Indent the logger's indentation level by one.

Dedent()

void Logger::Dedent

(

)

Decrease the logger's indentation level by one.

ResetIndent()

void Logger::ResetIndent

(

)

Set the logger's indentation level to zero.

GetIndent()

string Logger::GetIndent

(

)

const

Get the string to prepend to log messages to indent them.

Returns

Indentation string

Friends And Related Symbol Documentation

Iterator

friend struct Iterator

friend

BinaryNinja::LogRegistry

class BinaryNinja::LogRegistry

A class allowing registering and retrieving Loggers.

See also

BinaryView::CreateLogger

Static Public Member Functions
static Ref< Logger >	CreateLogger (const std::string &loggerName, size_t sessionId=0)
	Create a logger with the specified name and session ID.
static Ref< Logger >	GetLogger (const std::string &loggerName, size_t sessionId=0)
	Get a logger with the specified name and session ID.
static std::vector< std::string >	GetLoggerNames ()
	Get the list of registered Logger names.

Member Function Documentation

CreateLogger()

Ref< Logger > LogRegistry::CreateLogger ( const std::string & loggerName, size_t sessionId = 0 )

static

Create a logger with the specified name and session ID.

Thread Safe:

Yes

Note

If you already have a BinaryView, you may want to use BinaryView::CreateLogger instead of this.

auto sessionID = bv->GetFile()->GetSessionId();
auto logger = LogRegistry::CreateLogger("MyPluginName", sessionID);

Session ID corresponds to the tab for the specified BinaryView, and the default of 0 will log to *all tabs*.

See also

FileMetadata::GetSessionId()

Parameters

loggerName	Name of the logger to create
sessionId	Session ID for the logger

Returns

The created logger

GetLogger()

Ref< Logger > LogRegistry::GetLogger ( const std::string & loggerName, size_t sessionId = 0 )

static

Get a logger with the specified name and session ID.

Thread Safe:

Yes

auto sessionID = bv->GetFile()->GetSessionId();
auto logger = LogRegistry::GetLogger("MyPluginName", sessionID);

Session ID corresponds to the tab for the specified BinaryView, and the default of 0 will log to *all tabs*.

See also

FileMetadata::GetSessionId()

Parameters

loggerName	Name of the logger to create
sessionId	Session ID for the logger

Returns

The created logger

GetLoggerNames()

vector< string > LogRegistry::GetLoggerNames ( )

static

Get the list of registered Logger names.

Thread Safe:

Yes

Returns

a list of registered logger names

BinaryNinja::LoggerIndentScope

class BinaryNinja::LoggerIndentScope

RAII helper that indents/dedents a Logger inside a scope.

Public Member Functions
	LoggerIndentScope (Ref< Logger > logger)
	~LoggerIndentScope ()

Constructor & Destructor Documentation

LoggerIndentScope()

BinaryNinja::LoggerIndentScope::LoggerIndentScope ( Ref< Logger > logger )

inline

~LoggerIndentScope()

BinaryNinja::LoggerIndentScope::~LoggerIndentScope ( )

inline

Function Documentation

Log()

void BinaryNinja::Log	(	BNLogLevel	level,
		const char *	fmt,
			... )

Logs to the error console with the given BNLogLevel.

Thread Safe:

Yes

Parameters

level	BNLogLevel debug log level
fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogTrace()

void BinaryNinja::LogTrace	(	const char *	fmt,
			... )

LogTrace only writes text to the error console if the console is set to log level: DebugLog Log level and the build is not a DEBUG build (i.e.

the preprocessor directive _DEBUG is defined)

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogDebug()

void BinaryNinja::LogDebug	(	const char *	fmt,
			... )

LogDebug only writes text to the error console if the console is set to log level: DebugLog Log level DebugLog is the most verbose logging level in release builds.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogInfo()

void BinaryNinja::LogInfo	(	const char *	fmt,
			... )

LogInfo always writes text to the error console, and corresponds to the log level: InfoLog.

Log level InfoLog is the second most verbose logging level.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogWarn()

void BinaryNinja::LogWarn	(	const char *	fmt,
			... )

LogWarn writes text to the error console including a warning icon, and also shows a warning icon in the bottom pane.

LogWarn corresponds to the log level: WarningLog.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogError()

void BinaryNinja::LogError	(	const char *	fmt,
			... )

LogError writes text to the error console and pops up the error console.

Additionally, Errors in the console log include a error icon. LogError corresponds to the log level: ErrorLog.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogAlert()

void BinaryNinja::LogAlert	(	const char *	fmt,
			... )

LogAlert pops up a message box displaying the alert message and logs to the error console.

LogAlert corresponds to the log level: AlertLog.

Thread Safe:

Yes

Parameters

fmt	C-style format string.
...	Variable arguments corresponding to the format string.

LogF()

template<typename... T>

void BinaryNinja::LogF	(	BNLogLevel	level,
		fmt::format_string< T... >	format,
		T &&...	args )

Logs to the error console with the given BNLogLevel.

Thread Safe:

Yes

Parameters

level	BNLogLevel debug log level
format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogTraceF()

template<typename... T>

void BinaryNinja::LogTraceF	(	fmt::format_string< T... >	format,
		T &&...	args )

LogTrace only writes text to the error console if the console is set to log level: DebugLog Log level and the build is not a DEBUG build (i.e.

the preprocessor directive _DEBUG is defined)

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogDebugF()

template<typename... T>

void BinaryNinja::LogDebugF	(	fmt::format_string< T... >	format,
		T &&...	args )

LogDebug only writes text to the error console if the console is set to log level: DebugLog Log level DebugLog is the most verbose logging level in release builds.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogInfoF()

template<typename... T>

void BinaryNinja::LogInfoF	(	fmt::format_string< T... >	format,
		T &&...	args )

LogInfo always writes text to the error console, and corresponds to the log level: InfoLog.

Log level InfoLog is the second most verbose logging level.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogWarnF()

template<typename... T>

void BinaryNinja::LogWarnF	(	fmt::format_string< T... >	format,
		T &&...	args )

LogWarn writes text to the error console including a warning icon, and also shows a warning icon in the bottom pane.

LogWarn corresponds to the log level: WarningLog.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogErrorF()

template<typename... T>

void BinaryNinja::LogErrorF	(	fmt::format_string< T... >	format,
		T &&...	args )

LogError writes text to the error console and pops up the error console.

Additionally, Errors in the console log include a error icon. LogError corresponds to the log level: ErrorLog.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogAlertF()

template<typename... T>

void BinaryNinja::LogAlertF	(	fmt::format_string< T... >	format,
		T &&...	args )

LogAlert pops up a message box displaying the alert message and logs to the error console.

LogAlert corresponds to the log level: AlertLog.

Thread Safe:

Yes

Parameters

format	fmt-style format string.
...	Variable arguments corresponding to the format string.

LogToStdout()

void BinaryNinja::LogToStdout

(

BNLogLevel

minimumLevel

)

Redirects the minimum level passed to standard out.

Thread Safe:

Yes

Parameters

minimumLevel

minimum level to log to stdout

LogToStderr()

void BinaryNinja::LogToStderr

(

BNLogLevel

minimumLevel

)

Redirects the minimum level passed to standard error.

Thread Safe:

Yes

Parameters

minimumLevel

minimum level to log to stderr

LogToFile()

bool BinaryNinja::LogToFile	(	BNLogLevel	minimumLevel,
		const std::string &	path,
		bool	append = false )

Redirects minimum log level to the file at `path`, optionally appending rather than overwriting.

Thread Safe:

Yes

Parameters

minimumLevel	minimum level to log to stderr
path	Path to log to
append	Optional flag for specifying appending. True = append, False = overwrite.

CloseLogs()

void BinaryNinja::CloseLogs

(

)

Close all log files.