trace.h File Reference

Macro functions that log messages and entries for source tracing. More...

Go to the source code of this file.

Macros
#define	stump_t(...)
	Logs a message to the current target with debug severity, along with the file, line, and function of the invocation specified in a structured data element.
#define	stump_t_str(message)
	Logs a message to the current target with debug severity, along with the file, line, and function of the invocation specified in a structured data element.
#define	stump_t_entry(target, entry)   stumpless_trace_entry( ( target ), ( entry ), __FILE__, __LINE__, __func__ )
	Adds an entry to a given target with debug severity, along with the file, line, and function of the invocation specified in a structured data element.
#define	stump_t_log(target, priority, ...)
	Adds a message to a given target with the specified priority, along with the file, line, and function of the invocation specified in a structured data element.
#define	stump_t_log_str(target, priority, message)
	Adds a message to a given target with the specified priority, along with the file, line, and function of the invocation specified in a structured data element.
#define	stump_t_message(target, ...)
	Adds a message to a given target with trace severity, along with the file, line, and function of the invocation specified in a structured data element.
#define	stump_t_message_str(target, message)
	Adds a message to a given target with debug severity.
#define	stumplog_t(priority, ...)   stumplog_trace( ( priority ), __FILE__, __LINE__, __func__, __VA_ARGS__ )
	Adds a message to the current target with the specified priority, along with the file, line, and function of the invocation specified in a structured data element.
#define	stumplog_t_str(priority, message)   stumplog_trace_str( ( priority ), __FILE__, __LINE__, __func__, ( message ) )
	Adds a message to the current target with the specified priority, along with the file, line, and function of the invocation specified in a structured data element.

Detailed Description

Macro functions that log messages and entries for source tracing.

This is equivalent to a debug log severity with the addition of structured data fields that specify the source file and line of the call. While it shares the same severity as debug logs, it is considered below them and can be disabled separately from the debug level.

These can be turned into no-ops at compile time by defining STUMPLESS_DISABLE_TRACE_LEVEL during build, or at least before inclusion of this header (or stumpless.h).

Macro Definition Documentation

stump_t

#define stump_t

(

...

)

Value:

stumpless_trace_log( stumpless_get_current_target(  ),                         \
                     STUMPLESS_SEVERITY_DEBUG | STUMPLESS_DEFAULT_FACILITY,    \
                     __FILE__,                                                 \
                     __LINE__,                                                 \
                     __func__,                                                 \
                     __VA_ARGS__ )

Logs a message to the current target with debug severity, along with the file, line, and function of the invocation specified in a structured data element.

The trace information is added in an element named trace with params named file, line, and function for the respective pieces of information.

This function will be removed at compile time if STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is disabled, then this function is removed at compile time and will have no effect. Otherwise, it is equivalent to a call to stumpless_add_log with the provided message and calculated priority.

Note that if this function is disabled, then the arguments will not be evaluated, meaning that any side effects will not happen. Be sure that any side effects you rely on will not cause problems if they are left out during a build with trace level calls disabled.

This function will log the given message with a severity of STUMPLESS_SEVERITY_TRACE, and the facility defined by the STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then you will need to use stumplog_t instead.

The message must be a valid format specifier string provided along with the appropriate number of variable arguments afterwards. This means that it should not be a user-controlled value under any circumstances. If you need a safer alternative without the risks of format strings, use stump_t_str instead.

Thread Safety: MT-Safe env locale This function is thread safe. Different target types handle thread safety differently, as some require per-target locks and others can rely on system libraries to log safely, but all targets support thread safe logging in some manner. For target-specific information on how thread safety is supported and whether AS or AC safety can be assumed, refer to the documentation for the target's header file (in the stumpless/target include folder).

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers as some targets make use of non-reentrant locks to coordinate access. It also may make memory allocation calls to create internal cached structures, and memory allocation may not be signal safe.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of locks in some targets that could be left locked and the potential for memory allocation.

Parameters

...	The message to log, optionally along with the values for any format specifiers valid in printf. This must be a valid UTF-8 string in shortest form.

Returns

A non-negative value if no error is encountered. If an error is encountered, then a negative value is returned and an error code is set appropriately. If the function is disabled then the effective return value is zero, although a return value of zero does not guarantee that this function is disabled.

Examples

chain_example.c, filter_example.c, and severity_level_example.c.

stump_t_entry

#define stump_t_entry	(		target,
			entry )   stumpless_trace_entry( ( target ), ( entry ), __FILE__, __LINE__, __func__ )

Adds an entry to a given target with debug severity, along with the file, line, and function of the invocation specified in a structured data element.

The trace information is added in an element named trace with params named file, line, and function for the respective pieces of information.

This function will be removed at compile time if STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is disabled, then this function is removed at compile time and will have no effect. Otherwise, it is equivalent to a call to stumpless_add_entry with the provided target and entry.

Note that if this function is disabled, then the arguments will not be evaluated, meaning that any side effects will not happen. Be sure that any side effects you rely on will not cause problems if they are left out during a build with trace level calls disabled.

This call does not override the severity of the entry itself. Rather, it is intended to allow logging calls to be removed at compile time if the severity is known ahead of time.

Thread Safety: MT-Safe env locale This function is thread safe. Different target types handle thread safety differently, as some require per-target locks and others can rely on system libraries to log safely, but all targets support thread safe logging in some manner. For target-specific information on how thread safety is supported and whether AS or AC safety can be assumed, refer to the documentation for the target's header file (in the stumpless/target include folder).

Async Signal Safety: AS-Unsafe lock This function is not safe to call from signal handlers as some targets make use of non-reentrant locks to coordinate access.

Async Cancel Safety: AC-Unsafe lock This function is not safe to call from threads that may be asynchronously cancelled, due to the use of locks in some targets that could be left locked.

Parameters

target	The target to send the entry to.
entry	The entry to send to the target.

Returns

A non-negative value if no error is encountered. If an error is encountered, then a negative value is returned and an error code is set appropriately. If the function is disabled then the effective return value is zero, although a return value of zero does not guarantee that this function is disabled.

stump_t_log

#define stump_t_log	(		target,
			priority,
			... )

Value:

stumpless_trace_log( ( target ),                                               \
                     ( priority ),                                             \
                     __FILE__,                                                 \
                     __LINE__,                                                 \
                     __func__,                                                 \
                     __VA_ARGS__ )

Adds a message to a given target with the specified priority, along with the file, line, and function of the invocation specified in a structured data element.

The trace information is added in an element named trace with params named file, line, and function for the respective pieces of information.

This function will be removed at compile time if STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is disabled, then this function is removed at compile time and will have no effect. Otherwise, it is equivalent to a call to stumplog with the provided message and priority.

Note that if this function is disabled, then the arguments will not be evaluated, meaning that any side effects will not happen. Be sure that any side effects you rely on will not cause problems if they are left out during a build with trace level calls disabled.

The message must be a valid format specifier string provided along with the appropriate number of variable arguments afterwards. This means that it should not be a user-controlled value under any circumstances. If you need a safer alternative without the risks of format strings, use stump_t_log_str instead.

Thread Safety: MT-Safe env locale This function is thread safe. Different target types handle thread safety differently, as some require per-target locks and others can rely on system libraries to log safely, but all targets support thread safe logging in some manner. For target-specific information on how thread safety is supported and whether AS or AC safety can be assumed, refer to the documentation for the target's header file (in the stumpless/target include folder).

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers as some targets make use of non-reentrant locks to coordinate access. It also may make memory allocation calls to create internal cached structures, and memory allocation may not be signal safe.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of locks in some targets that could be left locked and the potential for memory allocation.

Parameters

target	The target to send the entry to.
priority	The priority of the message - this should be the bitwise or of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value.
...	The message to log, optionally along with the values for any format specifiers valid in printf. This must be a valid UTF-8 string in shortest form.

Returns

A non-negative value if no error is encountered. If an error is encountered, then a negative value is returned and an error code is set appropriately. If the function is disabled then the effective return value is zero, although a return value of zero does not guarantee that this function is disabled.

stump_t_log_str

#define stump_t_log_str	(		target,
			priority,
			message )

Value:

stumpless_trace_log_str( ( target ),                                           \
                         ( priority ),                                         \
                         __FILE__,                                             \
                         __LINE__,                                             \
                         __func__,                                             \
                         ( message ) )

Adds a message to a given target with the specified priority, along with the file, line, and function of the invocation specified in a structured data element.

The trace information is added in an element named trace with params named file, line, and function for the respective pieces of information.

This function will be removed at compile time if STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is disabled, then this function is removed at compile time and will have no effect. Otherwise, it is equivalent to a call to stump_t_log_str with the provided target, message, and priority.

Note that if this function is disabled, then the arguments will not be evaluated, meaning that any side effects will not happen. Be sure that any side effects you rely on will not cause problems if they are left out during a build with trace level calls disabled.

Thread Safety: MT-Safe env locale This function is thread safe. Different target types handle thread safety differently, as some require per-target locks and others can rely on system libraries to log safely, but all targets support thread safe logging in some manner. For target-specific information on how thread safety is supported and whether AS or AC safety can be assumed, refer to the documentation for the target's header file (in the stumpless/target include folder).

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers as some targets make use of non-reentrant locks to coordinate access. It also may make memory allocation calls to create internal cached structures, and memory allocation may not be signal safe.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of locks in some targets that could be left locked and the potential for memory allocation.

Since

release v2.1.0.

Parameters

target	The target to send the entry to.
priority	The priority of the message - this should be the bitwise or of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value.
message	The message to log. This must be a valid UTF-8 string in shortest form.

Returns

A non-negative value if no error is encountered. If an error is encountered, then a negative value is returned and an error code is set appropriately. If the function is disabled then the effective return value is zero, although a return value of zero does not guarantee that this function is disabled.

stump_t_message

#define stump_t_message	(		target,
			... )

Value:

stumpless_trace_log( ( target ),                                               \
                     STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_DEBUG,    \
                     __FILE__,                                                 \
                     __LINE__,                                                 \
                     __func__,                                                 \
                     __VA_ARGS__ )

Adds a message to a given target with trace severity, along with the file, line, and function of the invocation specified in a structured data element.

The trace information is added in an element named trace with params named file, line, and function for the respective pieces of information.

This function will be removed at compile time if STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is disabled, then this function is removed at compile time and will have no effect. Otherwise, it is equivalent to a call to stumpless_add_log with the provided message and calculated priority.

Note that if this function is disabled, then the arguments will not be evaluated, meaning that any side effects will not happen. Be sure that any side effects you rely on will not cause problems if they are left out during a build with trace level calls disabled.

This function will log the given message with a severity of STUMPLESS_SEVERITY_TRACE, and the facility defined by the STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then you will need to use stump_t_log instead.

The message must be a valid format specifier string provided along with the appropriate number of variable arguments afterwards. This means that it should not be a user-controlled value under any circumstances. If you need a safer alternative without the risks of format strings, use stump_t_message_str instead.

Thread Safety: MT-Safe env locale This function is thread safe. Different target types handle thread safety differently, as some require per-target locks and others can rely on system libraries to log safely, but all targets support thread safe logging in some manner. For target-specific information on how thread safety is supported and whether AS or AC safety can be assumed, refer to the documentation for the target's header file (in the stumpless/target include folder).

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers as some targets make use of non-reentrant locks to coordinate access. It also may make memory allocation calls to create internal cached structures, and memory allocation may not be signal safe.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of locks in some targets that could be left locked and the potential for memory allocation.

Parameters

target	The target to send the entry to.
...	The message to log, optionally along with the values for any format specifiers valid in printf. This must be a valid UTF-8 string in shortest form.

Returns

A non-negative value if no error is encountered. If an error is encountered, then a negative value is returned and an error code is set appropriately. If the function is disabled then the effective return value is zero, although a return value of zero does not guarantee that this function is disabled.

stump_t_message_str

#define stump_t_message_str	(		target,
			message )

Value:

stumpless_trace_log_str( ( target ),                                           \
                         STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_DEBUG,\
                         __FILE__,                                             \
                         __LINE__,                                             \
                         __func__,                                             \
                         ( message ) )

Adds a message to a given target with debug severity.

The entry has a structured data element added to it with the file, line, and function of the invocation specified.

The trace information is added in an element named trace with params named file, line, and function for the respective pieces of information.

This function will be removed at compile time if STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is disabled, then this function is removed at compile time and will have no effect. Otherwise, it is equivalent to a call to stumpless_add_log_str with the provided target and message.

Note that if this function is disabled, then the arguments will not be evaluated, meaning that any side effects will not happen. Be sure that any side effects you rely on will not cause problems if they are left out during a build with trace level calls disabled.

This function will log the given message with a severity of STUMPLESS_SEVERITY_TRACE, and the facility defined by the STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then you will need to use stump_t_log instead.

Thread Safety: MT-Safe env locale This function is thread safe. Different target types handle thread safety differently, as some require per-target locks and others can rely on system libraries to log safely, but all targets support thread safe logging in some manner. For target-specific information on how thread safety is supported and whether AS or AC safety can be assumed, refer to the documentation for the target's header file (in the stumpless/target include folder).

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers as some targets make use of non-reentrant locks to coordinate access. It also may make memory allocation calls to create internal cached structures, and memory allocation may not be signal safe.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of locks in some targets that could be left locked and the potential for memory allocation.

Since

release v2.1.0.

Parameters

target	The target to send the entry to.
message	The message to log. This must be a valid UTF-8 string in shortest form.

Returns

A non-negative value if no error is encountered. If an error is encountered, then a negative value is returned and an error code is set appropriately. If the function is disabled then the effective return value is zero, although a return value of zero does not guarantee that this function is disabled.

stump_t_str

#define stump_t_str

(

message

)

Value:

stumpless_trace_log_str( stumpless_get_current_target(  ),                     \
                         STUMPLESS_SEVERITY_DEBUG | STUMPLESS_DEFAULT_FACILITY,\
                         __FILE__,                                             \
                         __LINE__,                                             \
                         __func__,                                             \
                         ( message ) )

Logs a message to the current target with debug severity, along with the file, line, and function of the invocation specified in a structured data element.

The trace information is added in an element named trace with params named file, line, and function for the respective pieces of information.

This function will be removed at compile time if STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is disabled, then this function is removed at compile time and will have no effect. Otherwise, it is equivalent to a call to stumpless_add_log with the provided message and calculated priority.

Note that if this function is disabled, then the arguments will not be evaluated, meaning that any side effects will not happen. Be sure that any side effects you rely on will not cause problems if they are left out during a build with trace level calls disabled.

This function will log the given message with a severity of STUMPLESS_SEVERITY_TRACE, and the facility defined by the STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then you will need to use stumplog_em instead.

Thread Safety: MT-Safe env locale This function is thread safe. Different target types handle thread safety differently, as some require per-target locks and others can rely on system libraries to log safely, but all targets support thread safe logging in some manner. For target-specific information on how thread safety is supported and whether AS or AC safety can be assumed, refer to the documentation for the target's header file (in the stumpless/target include folder).

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers as some targets make use of non-reentrant locks to coordinate access. It also may make memory allocation calls to create internal cached structures, and memory allocation may not be signal safe.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of locks in some targets that could be left locked and the potential for memory allocation.

Since

release v2.1.0.

Parameters

message

The message to log. This must be a valid UTF-8 string in shortest form.

Returns

A non-negative value if no error is encountered. If an error is encountered, then a negative value is returned and an error code is set appropriately. If the function is disabled then the effective return value is zero, although a return value of zero does not guarantee that this function is disabled.

stumplog_t

#define stumplog_t	(		priority,
			... )   stumplog_trace( ( priority ), __FILE__, __LINE__, __func__, __VA_ARGS__ )

Adds a message to the current target with the specified priority, along with the file, line, and function of the invocation specified in a structured data element.

The trace information is added in an element named trace with params named file, line, and function for the respective pieces of information.

This function will be removed at compile time if STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is disabled, then this function is removed at compile time and will have no effect. Otherwise, it is equivalent to a call to stumplog with the provided priority and message.

Note that if this function is disabled, then the arguments will not be evaluated, meaning that any side effects will not happen. Be sure that any side effects you rely on will not cause problems if they are left out during a build with trace level calls disabled.

The message must be a valid format specifier string provided along with the appropriate number of variable arguments afterwards. This means that it should not be a user-controlled value under any circumstances. If you need a safer alternative without the risks of format strings, use stumplog_t_str instead.

Thread Safety: MT-Safe env locale This function is thread safe. Different target types handle thread safety differently, as some require per-target locks and others can rely on system libraries to log safely, but all targets support thread safe logging in some manner. For target-specific information on how thread safety is supported and whether AS or AC safety can be assumed, refer to the documentation for the target's header file (in the stumpless/target include folder).

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers as some targets make use of non-reentrant locks to coordinate access. It also may make memory allocation calls to create internal cached structures, and memory allocation may not be signal safe.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of locks in some targets that could be left locked and the potential for memory allocation.

Parameters

priority	The priority of the message - this should be the bitwise or of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value.
...	The message to log, optionally along with the values for any format specifiers valid in printf. This must be a valid UTF-8 string in shortest form.

stumplog_t_str

#define stumplog_t_str	(		priority,
			message )   stumplog_trace_str( ( priority ), __FILE__, __LINE__, __func__, ( message ) )

Adds a message to the current target with the specified priority, along with the file, line, and function of the invocation specified in a structured data element.

The trace information is added in an element named trace with params named file, line, and function for the respective pieces of information.

This function will be removed at compile time if STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is disabled, then this function is removed at compile time and will have no effect. Otherwise, it is equivalent to a call to stumplog_str with the provided message and calculated priority.

Note that if this function is disabled, then the arguments will not be evaluated, meaning that any side effects will not happen. Be sure that any side effects you rely on will not cause problems if they are left out during a build with trace level calls disabled.

Thread Safety: MT-Safe env locale This function is thread safe. Different target types handle thread safety differently, as some require per-target locks and others can rely on system libraries to log safely, but all targets support thread safe logging in some manner. For target-specific information on how thread safety is supported and whether AS or AC safety can be assumed, refer to the documentation for the target's header file (in the stumpless/target include folder).

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers as some targets make use of non-reentrant locks to coordinate access. It also may make memory allocation calls to create internal cached structures, and memory allocation may not be signal safe.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of locks in some targets that could be left locked and the potential for memory allocation.

Since

release v2.1.0.

Parameters

priority	The priority of the message - this should be the bitwise or of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value.
message	The message to log. This must be a valid UTF-8 string in shortest form.