log.h File Reference

Logging interfaces. More...

Data Structures
struct	spdk_log_flag

Macros
#define	SPDK_DEBUGLOG_FLAG_ENABLED(name)   false
#define	SPDK_NOTICELOG(...)    spdk_log(SPDK_LOG_NOTICE, __FILE__, __LINE__, __func__, __VA_ARGS__)
#define	SPDK_WARNLOG(...)    spdk_log(SPDK_LOG_WARN, __FILE__, __LINE__, __func__, __VA_ARGS__)
#define	SPDK_ERRLOG(...)    spdk_log(SPDK_LOG_ERROR, __FILE__, __LINE__, __func__, __VA_ARGS__)
#define	SPDK_PRINTF(...)    spdk_log(SPDK_LOG_NOTICE, NULL, -1, NULL, __VA_ARGS__)
#define	SPDK_INFOLOG(flag, ...)
#define	SPDK_ERRLOG_RATELIMIT(...)
#define	SPDK_DEBUGLOG(...)   do { } while (0)
#define	SPDK_LOGDUMP(...)   do { } while (0)
#define	SPDK_LOG_REGISTER_COMPONENT(flag)
#define	SPDK_LOG_DEPRECATION_REGISTER(tag, desc, release, rate)
#define	SPDK_LOG_DEPRECATED(tag)    spdk_log_deprecated(_deprecated_##tag, __FILE__, __LINE__, __func__)

Typedefs
typedef void	logfunc(int level, const char *file, const int line, const char *func, const char *format, va_list args)
	for passing user-provided log call
typedef int(*	spdk_log_for_each_deprecation_fn) (void *ctx, struct spdk_deprecation *deprecation)
	Callback function for spdk_log_for_each_deprecation().

Enumerations
enum	spdk_log_level {   SPDK_LOG_DISABLED = -1 , SPDK_LOG_ERROR , SPDK_LOG_WARN , SPDK_LOG_NOTICE ,   SPDK_LOG_INFO , SPDK_LOG_DEBUG }

Functions
void	spdk_log_open (logfunc *logf)
	Initialize the logging module.
void	spdk_log_close (void)
	Close the currently active log.
void	spdk_log_enable_timestamps (bool value)
	Enable or disable timestamps.
void	spdk_log_set_level (enum spdk_log_level level)
	Set the log level threshold to log messages.
enum spdk_log_level	spdk_log_get_level (void)
	Get the current log level threshold.
int	spdk_log_to_syslog_level (enum spdk_log_level level)
	Get syslog level based on SPDK current log level threshold.
void	spdk_log_set_print_level (enum spdk_log_level level)
	Set the current log level threshold for printing to stderr.
enum spdk_log_level	spdk_log_get_print_level (void)
	Get the current log level print threshold.
void	spdk_log (enum spdk_log_level level, const char *file, const int line, const char *func, const char *format,...)
	Write messages to the log file.
void	spdk_vlog (enum spdk_log_level level, const char *file, const int line, const char *func, const char *format, va_list ap)
	Same as spdk_log except that instead of being called with variable number of arguments it is called with an argument list as defined in stdarg.h.
void	spdk_flog (FILE *fp, const char *file, const int line, const char *func, const char *format,...)
	Write messages to the log file.
void	spdk_vflog (FILE *fp, const char *file, const int line, const char *func, const char *format, va_list ap)
	Same as spdk_flog except that instead of being called with variable number of arguments it is called with an argument list as defined in stdarg.h.
void	spdk_log_dump (FILE *fp, const char *label, const void *buf, size_t len)
	Log the contents of a raw buffer to a file.
void	spdk_log_register_flag (const char *name, struct spdk_log_flag *flag)
	Register a log flag.
struct spdk_log_flag *	spdk_log_get_first_flag (void)
	Get the first registered log flag.
struct spdk_log_flag *	spdk_log_get_next_flag (struct spdk_log_flag *flag)
	Get the next registered log flag.
bool	spdk_log_get_flag (const char *flag)
	Check whether the log flag exists and is enabled.
int	spdk_log_set_flag (const char *flag)
	Enable the log flag.
int	spdk_log_clear_flag (const char *flag)
	Clear a log flag.
void	spdk_log_usage (FILE *f, const char *log_arg)
	Show all the log flags and their usage.
int	spdk_log_deprecation_register (const char *tag, const char *description, const char *remove_release, uint32_t rate_limit_seconds, struct spdk_deprecation **reg)
	Register a deprecation.
void	spdk_log_deprecated (struct spdk_deprecation *deprecation, const char *file, uint32_t line, const char *func)
	Indicate that a deprecated feature was used.
int	spdk_log_for_each_deprecation (void *ctx, spdk_log_for_each_deprecation_fn fn)
	Iterate over all deprecations, calling a callback on each of them.
const char *	spdk_deprecation_get_tag (const struct spdk_deprecation *deprecation)
	Get a deprecation's tag.
const char *	spdk_deprecation_get_description (const struct spdk_deprecation *deprecation)
	Get a deprecation's description.
const char *	spdk_deprecation_get_remove_release (const struct spdk_deprecation *deprecation)
	Get a deprecation's planned removal release.
uint64_t	spdk_deprecation_get_hits (const struct spdk_deprecation *deprecation)
	Get the number of times that a deprecation's code has been executed.

Detailed Description

Logging interfaces.

Macro Definition Documentation

SPDK_ERRLOG_RATELIMIT

#define SPDK_ERRLOG_RATELIMIT

(

...

)

Value:

        do {                                                    \
                static uint64_t last_tsc = 0;                   \
                static uint64_t squashed = 0;                   \
                uint64_t tsc = spdk_get_ticks();                \
                if (tsc > last_tsc + spdk_get_ticks_hz()) {     \
                        last_tsc = tsc;                         \
                        SPDK_ERRLOG(__VA_ARGS__);               \
                        if (squashed > 0) {                     \
                                SPDK_ERRLOG("(same message squashed %" PRIu64 " times)\n", \
                                            squashed);          \
                                squashed = 0;                   \
                        }                                       \
                } else {                                        \
                        squashed++;                             \
                }                                               \
        } while (0)

SPDK_INFOLOG

#define SPDK_INFOLOG	(		flag,
			... )

Value:

        do {                                                                                    \
                extern struct spdk_log_flag SPDK_LOG_##flag;                                    \
                if (SPDK_LOG_##flag.enabled) {                                                  \
                        spdk_log(SPDK_LOG_INFO, __FILE__, __LINE__, __func__, __VA_ARGS__);     \
                }                                                                               \
        } while (0)

SPDK_LOG_DEPRECATION_REGISTER

#define SPDK_LOG_DEPRECATION_REGISTER	(		tag,
			desc,
			release,
			rate )

Value:

        static struct spdk_deprecation *_deprecated_##tag; \
        static void __attribute__((constructor)) _spdk_deprecation_register_##tag(void) \
        { \
                int rc; \
                rc = spdk_log_deprecation_register(#tag, desc, release, rate, &_deprecated_##tag); \
                (void)rc; \
                assert(rc == 0); \
        }

SPDK_LOG_REGISTER_COMPONENT

#define SPDK_LOG_REGISTER_COMPONENT

(

flag

)

Value:

struct spdk_log_flag SPDK_LOG_##flag = { \
        .name = #flag, \
        .enabled = false, \
}; \
__attribute__((constructor)) static void register_flag_##flag(void) \
{ \
        spdk_log_register_flag(#flag, &SPDK_LOG_##flag); \
}

Typedef Documentation

logfunc

typedef void logfunc(int level, const char *file, const int line, const char *func, const char *format, va_list args)

for passing user-provided log call

Parameters

level	Log level threshold.
file	Name of the current source file.
line	Current source file line.
func	Current source function name.
format	Format string to the message.
args	Additional arguments for format string.

spdk_log_for_each_deprecation_fn

typedef int(* spdk_log_for_each_deprecation_fn) (void *ctx, struct spdk_deprecation *deprecation)

Callback function for spdk_log_for_each_deprecation().

Parameters

ctx	Context passed via spdk_log_for_each_deprecation().
deprecation	Pointer to a deprecation structure.

Returns

0 to continue iteration or non-zero to stop iteration.

Enumeration Type Documentation

spdk_log_level

enum spdk_log_level

Enumerator
SPDK_LOG_DISABLED	All messages will be suppressed.

Function Documentation

spdk_deprecation_get_description()

const char * spdk_deprecation_get_description

(

const struct spdk_deprecation *

deprecation

)

Get a deprecation's description.

Parameters

deprecation

A pointer to an spdk_deprecation.

Returns

The deprecation's description.

spdk_deprecation_get_hits()

uint64_t spdk_deprecation_get_hits

(

const struct spdk_deprecation *

deprecation

)

Get the number of times that a deprecation's code has been executed.

Parameters

deprecation

A pointer to an spdk_deprecation.

Returns

The deprecation's planned removal release.

spdk_deprecation_get_remove_release()

const char * spdk_deprecation_get_remove_release

(

const struct spdk_deprecation *

deprecation

)

Get a deprecation's planned removal release.

Parameters

deprecation

A pointer to an spdk_deprecation.

Returns

The deprecation's planned removal release.

spdk_deprecation_get_tag()

const char * spdk_deprecation_get_tag

(

const struct spdk_deprecation *

deprecation

)

Get a deprecation's tag.

Parameters

deprecation

A pointer to an spdk_deprecation.

Returns

The deprecation's tag.

spdk_flog()

void spdk_flog	(	FILE *	fp,
		const char *	file,
		const int	line,
		const char *	func,
		const char *	format,
			... )

Write messages to the log file.

If level is set to SPDK_LOG_DISABLED, this log message won't be written.

Parameters

fp	File to hold the log.
file	Name of the current source file.
line	Current source line number.
func	Current source function name.
format	Format string to the message.

spdk_log()

void spdk_log	(	enum spdk_log_level	level,
		const char *	file,
		const int	line,
		const char *	func,
		const char *	format,
			... )

Write messages to the log file.

If level is set to SPDK_LOG_DISABLED, this log message won't be written.

Parameters

level	Log level threshold.
file	Name of the current source file.
line	Current source line number.
func	Current source function name.
format	Format string to the message.

spdk_log_clear_flag()

int spdk_log_clear_flag

(

const char *

flag

)

Clear a log flag.

The name of the flag can be a glob pattern (as expanded by fnmatch(3)), in which case all matching flags will be cleared.

Parameters

flag	Log flag to clear.

Returns

0 on success, negative errno on failure.

spdk_log_close()

void spdk_log_close

(

void

)

Close the currently active log.

Messages after this call will be dropped.

spdk_log_deprecated()

void spdk_log_deprecated	(	struct spdk_deprecation *	deprecation,
		const char *	file,
		uint32_t	line,
		const char *	func )

Indicate that a deprecated feature was used.

Most consumers will use SPDK_LOG_DEPRECATED() instead.

Parameters

deprecation	The deprecated feature that was used.
file	The name of the source file where the deprecated feature was used.
line	The line in file where where the deprecated feature was used.
func	The name of the function where where the deprecated feature was used.

spdk_log_deprecation_register()

int spdk_log_deprecation_register	(	const char *	tag,
		const char *	description,
		const char *	remove_release,
		uint32_t	rate_limit_seconds,
		struct spdk_deprecation **	reg )

Register a deprecation.

Most consumers will use SPDK_LOG_DEPRECATION_REGISTER() instead.

Parameters

tag	A unique string that will appear in each log message and should appear in documentation.
description	A descriptive string that will also be logged.
rate_limit_seconds	If non-zero, log messages related to this deprecation will appear no more frequently than this interval.
remove_release	The release when the deprecated support will be removed.
reg	Pointer to storage for newly allocated deprecation handle.

Returns

0 on success or negative errno on failure.

spdk_log_dump()

void spdk_log_dump	(	FILE *	fp,
		const char *	label,
		const void *	buf,
		size_t	len )

Log the contents of a raw buffer to a file.

Parameters

fp	File to hold the log.
label	Label to print to the file.
buf	Buffer that holds the log information.
len	Length of buffer to dump.

spdk_log_for_each_deprecation()

int spdk_log_for_each_deprecation	(	void *	ctx,
		spdk_log_for_each_deprecation_fn	fn )

Iterate over all deprecations, calling a callback on each of them.

Iteration will stop early if the callback function returns non-zero.

Parameters

ctx	Context to pass to the callback.
fn	Callback function

Returns

The value from the last callback called or 0 if there are no deprecations.

spdk_log_get_first_flag()

struct spdk_log_flag * spdk_log_get_first_flag

(

void

)

Get the first registered log flag.

Returns

The first registered log flag.

spdk_log_get_flag()

bool spdk_log_get_flag

(

const char *

flag

)

Check whether the log flag exists and is enabled.

Returns

true if enabled, or false otherwise.

spdk_log_get_level()

enum spdk_log_level spdk_log_get_level

(

void

)

Get the current log level threshold.

Returns

the current log level threshold.

spdk_log_get_next_flag()

struct spdk_log_flag * spdk_log_get_next_flag

(

struct spdk_log_flag *

flag

)

Get the next registered log flag.

Parameters

flag	The current log flag.

Returns

The next registered log flag.

spdk_log_get_print_level()

enum spdk_log_level spdk_log_get_print_level

(

void

)

Get the current log level print threshold.

Returns

the current log level print threshold.

spdk_log_open()

void spdk_log_open

(

logfunc *

logf

)

Initialize the logging module.

Messages prior to this call will be dropped.

spdk_log_register_flag()

void spdk_log_register_flag	(	const char *	name,
		struct spdk_log_flag *	flag )

Register a log flag.

Parameters

name	Name of the log flag.
flag	Log flag to be added.

spdk_log_set_flag()

int spdk_log_set_flag

(

const char *

flag

)

Enable the log flag.

The name of the flag can be a glob pattern (as expanded by fnmatch(3)), in which case all matching flags will be set.

Parameters

flag	Log flag to be enabled.

Returns

0 on success, negative errno on failure.

spdk_log_set_level()

void spdk_log_set_level

(

enum spdk_log_level

level

)

Set the log level threshold to log messages.

Messages with a higher level than this are ignored.

Parameters

level

Log level threshold to set to log messages.

spdk_log_set_print_level()

void spdk_log_set_print_level

(

enum spdk_log_level

level

)

Set the current log level threshold for printing to stderr.

Messages with a level less than or equal to this level are also printed to stderr. You can use SPDK_LOG_DISABLED to completely suppress log printing.

Parameters

level

Log level threshold for printing to stderr.

spdk_log_to_syslog_level()

int spdk_log_to_syslog_level

(

enum spdk_log_level

level

)

Get syslog level based on SPDK current log level threshold.

Parameters

level

Log level threshold

Returns

-1 for disable log print, otherwise is syslog level.

spdk_log_usage()

void spdk_log_usage	(	FILE *	f,
		const char *	log_arg )

Show all the log flags and their usage.

Parameters

f	File to hold all the flags' information.
log_arg	Command line option to set/enable the log flag.

spdk_vflog()

void spdk_vflog	(	FILE *	fp,
		const char *	file,
		const int	line,
		const char *	func,
		const char *	format,
		va_list	ap )

Same as spdk_flog except that instead of being called with variable number of arguments it is called with an argument list as defined in stdarg.h.

Parameters

fp	File to hold the log.
file	Name of the current source file.
line	Current source line number.
func	Current source function name.
format	Format string to the message.
ap	printf arguments

spdk_vlog()

void spdk_vlog	(	enum spdk_log_level	level,
		const char *	file,
		const int	line,
		const char *	func,
		const char *	format,
		va_list	ap )

Same as spdk_log except that instead of being called with variable number of arguments it is called with an argument list as defined in stdarg.h.

Parameters

level	Log level threshold.
file	Name of the current source file.
line	Current source line number.
func	Current source function name.
format	Format string to the message.
ap	printf arguments