#include <stdarg.h>
#include <stumpless/config.h>

Functions
int	stump (const char *message,...)
	Logs a message to the default target. More...

int	stump_str (const char *message)
	Logs a message to the default target. More...

int	stump_trace (const char file, int line, const char func, const char *message,...)
	Logs a message to the default target, along with the file, line, and function information specified in a structured data element. More...

int	stump_trace_str (const char file, int line, const char func, const char *message)
	Logs a message to the default target, along with the file, line, and function information specified in a structured data element. More...

void	stumplog (int priority, const char *message,...)
	Logs a message to the current target with the given priority. More...

int	stumplog_set_mask (int mask)
	Sets the log mask of the current target. More...

void	stumplog_str (int priority, const char *message)
	Logs a message to the current target with the given priority. More...

void	stumplog_trace (int priority, const char file, int line, const char func, const char *message,...)
	Logs a message to the default target with the given priority, along with the file, line, and function information specified in a structured data element. More...

void	stumplog_trace_str (int priority, const char file, int line, const char func, const char *message)
	Logs a message to the default target with the given priority, along with the file, line, and function information specified in a structured data element. More...

int	vstump (const char *message, va_list subs)
	Logs a message to the default target. More...

int	vstump_trace (const char file, int line, const char func, const char *message, va_list subs)
	Logs a message to the default target, along with the file, line, and function information specified in a structured data element. More...

void	vstumplog (int priority, const char *message, va_list subs)
	Logs a message to the default target with the given priority. More...

void	vstumplog_trace (int priority, const char file, int line, const char func, const char *message, va_list subs)
	Logs a message to the default target with the given priority, along with the file, line, and function information specified in a structured data element. More...

Detailed Description

Convenience functions for creating and writing simple log entries.

Function Documentation

◆ stump()

int stump	(	const char *	message,
			...
	)

Logs a message to the default target.

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_str instead.

Thread Safety: MT-Safe 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

message	The message to log, optionally containing any format specifiers valid in `printf`. This must be a valid UTF-8 string in shortest form.
...	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given.

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 entry was rejected by the target's filter, then 0 is returned.

◆ stump_str()

int stump_str ( const char * message )

Logs a message to the default target.

Thread Safety: MT-Safe 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 entry was rejected by the target's filter, then 0 is returned.

◆ stump_trace()

int stump_trace	(	const char *	file,
		int	line,
		const char *	func,
		const char *	message,
			...
	)

Logs a message to the default target, along with the file, line, and function information 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.

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_trace_str instead.

Thread Safety: MT-Safe 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

file	The name of the source file the message should be tied to.
line	The line in the source file that the message should be tied to.
func	The name of the function that the message should be tied to.
message	The message to log, optionally containing any format specifiers valid in `printf`. This must be a valid UTF-8 string in shortest form.
...	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given.

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 entry was rejected by the target's filter, then 0 is returned.

◆ stump_trace_str()

int stump_trace_str	(	const char *	file,
		int	line,
		const char *	func,
		const char *	message
	)

Logs a message to the default target, along with the file, line, and function information 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.

Thread Safety: MT-Safe 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

file	The name of the source file the message should be tied to.
line	The line in the source file that the message should be tied to.
func	The name of the function that the message should be tied 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 entry was rejected by the target's filter, then 0 is returned.

◆ stumplog()

void stumplog	(	int	priority,
		const char *	message,
			...
	)

Logs a message to the current target with the given priority.

This function can serve as a replacement for the traditional syslog function.

For detailed information on what the current target will be for a given system, check the stumpless_get_current_target() function documentation.

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_str instead.

Thread Safety: MT-Safe 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.
message	The message to log, optionally containing any format specifiers valid in `printf`. This must be a valid UTF-8 string in shortest form.
...	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given.

◆ stumplog_set_mask()

int stumplog_set_mask ( int mask )

Sets the log mask of the current target.

The mask is a bit field of severities that this target will allow if the default mask-based filter is in use. These can be formed and checked using the STUMPLESS_SEVERITY_MASK and STUMPLESS_SEVERITY_MASK_UPTO macros, and combining them using bitwise or operations.

This function can serve as a replacement for the traditional setlogmask function.

For detailed information on what the current target will be for a given system, check the stumpless_get_current_target() function documentation.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate changes to the target while it is being modified.

Async Signal Safety: AS-Unsafe lock This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate changes.

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 a lock that could be left locked.

Since: release v2.1.0

Parameters

mask	The mask to use with the target.

Returns: The previous mask that was in use on the current target. If the mask could not be retrieved, 0 is returned and an error code is set appropriately.

◆ stumplog_str()

void stumplog_str	(	int	priority,
		const char *	message
	)

Logs a message to the current target with the given priority.

This function can serve as a replacement for the traditional syslog function.

For detailed information on what the current target will be for a given system, check the stumpless_get_current_target() function documentation.

Thread Safety: MT-Safe 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.

◆ stumplog_trace()

void stumplog_trace	(	int	priority,
		const char *	file,
		int	line,
		const char *	func,
		const char *	message,
			...
	)

Logs a message to the default target with the given priority, along with the file, line, and function information 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 can serve as a replacement for the traditional syslog function.

For detailed information on what the default target will be for a given system, check the stumpless_get_default_target() function documentation.

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_trace_str instead.

Thread Safety: MT-Safe 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.
file	The name of the source file the entry should be tied to.
line	The line in the source file that the entry should be tied to.
func	The name of the function that the entry should be tied to.
message	The message to log, optionally containing any format specifiers valid in `printf`. This must be a valid UTF-8 string in shortest form.
...	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given.

◆ stumplog_trace_str()

void stumplog_trace_str	(	int	priority,
		const char *	file,
		int	line,
		const char *	func,
		const char *	message
	)

Logs a message to the default target with the given priority, along with the file, line, and function information 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 can serve as a replacement for the traditional syslog function.

For detailed information on what the default target will be for a given system, check the stumpless_get_default_target() function documentation.

Thread Safety: MT-Safe 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.
file	The name of the source file the entry should be tied to.
line	The line in the source file that the entry should be tied to.
func	The name of the function that the entry should be tied to.
message	The message to log. This must be a valid UTF-8 string in shortest form.

◆ vstump()

int vstump	(	const char *	message,
		va_list	subs
	)

Logs a message to the default target.

Thread Safety: MT-Safe 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

message	The message to log, optionally containing any format specifiers valid in `printf`.
subs	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given. This list must be started via `va_start` before being used, and `va_end` should be called afterwards, as this function does not call it.

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 entry was rejected by the target's filter, then 0 is returned.

◆ vstump_trace()

int vstump_trace	(	const char *	file,
		int	line,
		const char *	func,
		const char *	message,
		va_list	subs
	)

Logs a message to the default target, along with the file, line, and function information 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.

Thread Safety: MT-Safe 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

file	The name of the source file the message should be tied to.
line	The line in the source file that the message should be tied to.
func	The name of the function that the message should be tied to.
message	The message to log, optionally containing any format specifiers valid in `printf`.
subs	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given. This list must be started via `va_start` before being used, and `va_end` should be called afterwards, as this function does not call it.

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 entry was rejected by the target's filter, then 0 is returned.

◆ vstumplog()

void vstumplog	(	int	priority,
		const char *	message,
		va_list	subs
	)

Logs a message to the default target with the given priority.

Can serve as a replacement for the traditional vsyslog function.

For detailed information on what the default target will be for a given system, check the stumpless_get_default_target() function documentation.

Thread Safety: MT-Safe 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.
message	The message to log, optionally containing any format specifiers valid in `printf`.
subs	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given. This list must be started via `va_start` before being used, and `va_end` should be called afterwards, as this function does not call it.

◆ vstumplog_trace()

void vstumplog_trace	(	int	priority,
		const char *	file,
		int	line,
		const char *	func,
		const char *	message,
		va_list	subs
	)

Logs a message to the default target with the given priority, along with the file, line, and function information 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 can serve as a replacement for the traditional vsyslog function.

For detailed information on what the default target will be for a given system, check the stumpless_get_default_target() function documentation.

Thread Safety: MT-Safe 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.
file	The name of the source file the message should be tied to.
line	The line in the source file that the message should be tied to.
func	The name of the function that the message should be tied to.
message	The message to log, optionally containing any format specifiers valid in `printf`.
subs	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given. This list must be started via `va_start` before being used, and `va_end` should be called afterwards, as this function does not call it.

Functions

Detailed Description

Function Documentation

◆ stump()

◆ stump_str()

◆ stump_trace()

◆ stump_trace_str()

◆ stumplog()

◆ stumplog_set_mask()

◆ stumplog_str()

◆ stumplog_trace()

◆ stumplog_trace_str()

◆ vstump()

◆ vstump_trace()

◆ vstumplog()

◆ vstumplog_trace()