entry.h File Reference

Types and functions for creating and modifying entries. More...

Go to the source code of this file.

Data Structures
struct	stumpless_entry
	A log entry. More...

Macros
#define	STUMPLESS_MAX_PROCID_LENGTH   128
	The maximum length of a procid, as specified by RFC 5424.
#define	STUMPLESS_MAX_HOSTNAME_LENGTH   255
	The maximum length of a hostname, as specified by RFC 5424.
#define	STUMPLESS_MAX_APP_NAME_LENGTH   48
	The maximum length of an app name, as specified by RFC 5424.
#define	STUMPLESS_MAX_MSGID_LENGTH   32
	The maximum length of a msgid, as specified by RFC 5424.

Functions
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_add_element (struct stumpless_entry *entry, struct stumpless_element *element)
	Adds an element to an entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_add_new_element (struct stumpless_entry *entry, const char *name)
	Creates a new element with the given name and adds it to this entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_add_new_param_to_entry (struct stumpless_entry *entry, const char *element_name, const char *param_name, const char *param_value)
	Creates a new param and adds it to the given element in the given entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_copy_entry (const struct stumpless_entry *entry)
	Creates a copy of an entry.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_destroy_entry (const struct stumpless_entry *entry)
	An alias for stumpless_destroy_entry_and_contents.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_destroy_entry_and_contents (const struct stumpless_entry *entry)
	Destroys an entry as well as all elements and params that it contains, freeing any allocated memory.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_destroy_entry_only (const struct stumpless_entry *entry)
	Destroys an entry, freeing any allocated memory.
STUMPLESS_PUBLIC_FUNCTION bool	stumpless_entry_has_element (const struct stumpless_entry *entry, const char *name)
	True if the given entry has an element with the given name, false otherwise.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_get_element_by_index (const struct stumpless_entry *entry, size_t index)
	Returns the element at the given index in this Entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_get_element_by_name (const struct stumpless_entry *entry, const char *name)
	Returns the element with the given name in this entry, if it is found.
STUMPLESS_PUBLIC_FUNCTION size_t	stumpless_get_element_count (const struct stumpless_entry *entry)
	Returns the number of elements in the given entry.
STUMPLESS_PUBLIC_FUNCTION size_t	stumpless_get_element_index (const struct stumpless_entry *entry, const char *name)
	Returns the index of the element with the given name in this entry, if it is found.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_entry_app_name (const struct stumpless_entry *entry)
	Returns the app name of the given entry.
STUMPLESS_PUBLIC_FUNCTION enum stumpless_facility	stumpless_get_entry_facility (const struct stumpless_entry *entry)
	Returns the facility code of the given entry.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_entry_hostname (const struct stumpless_entry *entry)
	Returns the hostname of a given entry.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_entry_message (const struct stumpless_entry *entry)
	Returns the message of the given entry.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_entry_msgid (const struct stumpless_entry *entry)
	Returns the msgid of the given entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_param *	stumpless_get_entry_param_by_index (const struct stumpless_entry *entry, size_t element_index, size_t param_index)
	Gets the param from the element at the given index in an entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_param *	stumpless_get_entry_param_by_name (const struct stumpless_entry *entry, const char *element_name, const char *param_name)
	Gets the first param from the element with the given name in an entry.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_entry_param_value_by_index (const struct stumpless_entry *entry, size_t element_index, size_t param_index)
	Gets the value of the param from the element at the given index in an entry.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_entry_param_value_by_name (const struct stumpless_entry *entry, const char *element_name, const char *param_name)
	Gets the value of the first param from the element with the given name in an entry.
STUMPLESS_PUBLIC_FUNCTION int	stumpless_get_entry_prival (const struct stumpless_entry *entry)
	Returns the prival of the given entry, as defined in RFC 5424.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_entry_procid (const struct stumpless_entry *entry)
	Returns the procid of a given entry.
STUMPLESS_PUBLIC_FUNCTION enum stumpless_severity	stumpless_get_entry_severity (const struct stumpless_entry *entry)
	Returns the severity code of the given entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_load_entry (struct stumpless_entry *entry, enum stumpless_facility facility, enum stumpless_severity severity, const char *app_name, const char *msgid, const char *message,...)
	Loads an entry struct with the given characteristics.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_load_entry_str (struct stumpless_entry *entry, enum stumpless_facility facility, enum stumpless_severity severity, const char *app_name, const char *msgid, const char *message)
	Creates a new entry with the given characteristics.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_new_entry (enum stumpless_facility facility, enum stumpless_severity severity, const char *app_name, const char *msgid, const char *message,...)
	Creates a new entry with the given characteristics.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_new_entry_str (enum stumpless_facility facility, enum stumpless_severity severity, const char *app_name, const char *msgid, const char *message)
	Creates a new entry with the given characteristics.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_element (struct stumpless_entry *entry, size_t index, struct stumpless_element *element)
	Puts the element at the given index in the given entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_app_name (struct stumpless_entry *entry, const char *app_name)
	Sets the app name for an entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_facility (struct stumpless_entry *entry, enum stumpless_facility facility)
	Sets the facility of an entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_hostname (struct stumpless_entry *entry, const char *hostname)
	Sets the hostname of a given entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_message (struct stumpless_entry *entry, const char *message,...)
	Sets the message of a given entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_message_str (struct stumpless_entry *entry, const char *message)
	Sets the message of a given entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_message_str_w (struct stumpless_entry *entry, const wchar_t *message)
	Sets the message of a given entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_msgid (struct stumpless_entry *entry, const char *msgid)
	Sets the msgid for an entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_param_by_index (struct stumpless_entry *entry, size_t element_index, size_t param_index, struct stumpless_param *param)
	Puts the param in the element at the given index of an entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_param_value_by_index (struct stumpless_entry *entry, size_t element_index, size_t param_index, const char *value)
	Sets the value of the param in the element at the given index of an entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_param_value_by_name (struct stumpless_entry *entry, const char *element_name, const char *param_name, const char *value)
	Sets the value of the first param in the named element an entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_priority (struct stumpless_entry *entry, enum stumpless_facility facility, enum stumpless_severity severity)
	Sets the facility and severity of an entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_prival (struct stumpless_entry *entry, int prival)
	Sets the prival of an entry, as defined in RFC 5424.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_procid (struct stumpless_entry *entry, const char *procid)
	Sets the procid of a given entry.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	stumpless_set_entry_severity (struct stumpless_entry *entry, enum stumpless_severity severity)
	Sets the severity of an entry.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_unload_entry_and_contents (const struct stumpless_entry *entry)
	Unloads an entry as well as all elements that it contains.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_unload_entry_only (const struct stumpless_entry *entry)
	Unloads an entry, freeing any allocated memory.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	vstumpless_load_entry (struct stumpless_entry *entry, enum stumpless_facility facility, enum stumpless_severity severity, const char *app_name, const char *msgid, const char *message, va_list subs)
	Creates a new entry with the given parameters.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	vstumpless_new_entry (enum stumpless_facility facility, enum stumpless_severity severity, const char *app_name, const char *msgid, const char *message, va_list subs)
	Creates a new entry with the given parameters.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry *	vstumpless_set_entry_message (struct stumpless_entry *entry, const char *message, va_list subs)
	Sets the message of a given entry.

Detailed Description

Types and functions for creating and modifying entries.

Macro Definition Documentation

STUMPLESS_MAX_APP_NAME_LENGTH

#define STUMPLESS_MAX_APP_NAME_LENGTH   48

The maximum length of an app name, as specified by RFC 5424.

STUMPLESS_MAX_HOSTNAME_LENGTH

#define STUMPLESS_MAX_HOSTNAME_LENGTH   255

The maximum length of a hostname, as specified by RFC 5424.

STUMPLESS_MAX_MSGID_LENGTH

#define STUMPLESS_MAX_MSGID_LENGTH   32

The maximum length of a msgid, as specified by RFC 5424.

STUMPLESS_MAX_PROCID_LENGTH

#define STUMPLESS_MAX_PROCID_LENGTH   128

The maximum length of a procid, as specified by RFC 5424.

Function Documentation

stumpless_add_element()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_add_element	(	struct stumpless_entry *	entry,
		struct stumpless_element *	element )

Adds an element to an entry.

The element is appended to the end of the list of elements in this entry.

Note that duplicate elements are not allowed in RFC 5424, and as such attempts to add an element to an entry already having one with the same name will result in a STUMPLESS_DUPLICATE_ELEMENT error.

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

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

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 a lock that could be left locked as well as memory management functions.

Parameters

entry	The entry to add the element to.
element	The element to add to the entry.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

Examples

entry_example.c, file_example.c, socket_example.c, stream_example.c, tcp_example.c, and udp_example.c.

stumpless_add_new_element()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_add_new_element	(	struct stumpless_entry *	entry,
		const char *	name )

Creates a new element with the given name and adds it to this entry.

Note that duplicate elements are not allowed in RFC 5424, and as such attempts to add an element to an entry already having one with the same name will result in a STUMPLESS_DUPLICATE_ELEMENT error.

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

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

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 a lock that could be left locked as well as memory management functions.

Since

release v1.6.0.

Parameters

entry	The entry to add the new element to.
name	The name of the new element.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

Examples

filter_example.c.

stumpless_add_new_param_to_entry()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_add_new_param_to_entry	(	struct stumpless_entry *	entry,
		const char *	element_name,
		const char *	param_name,
		const char *	param_value )

Creates a new param and adds it to the given element in the given entry.

If an element with the given name does not exist in the given entry, then one will be created with the new param added to it.

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

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

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 a lock that could be left locked as well as memory management functions.

Since

release v1.6.0.

Parameters

entry	The entry to add the new param to.
element_name	The name of the element to add the param to. If an element with this name is not found, it will be created. Valid name should have printable ASCII characters expect '=', ']' , '"' and should be 32 characters long.
param_name	The name of the new param to add.
param_value	The value of the new param to add.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

Examples

journald_example.c, and sqlite3_example.c.

stumpless_copy_entry()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_copy_entry

(

const struct stumpless_entry *

entry

)

Creates a copy of an entry.

Copies of entries are 'deep' in that the copy also copies each of the elements that the original entry has, if any. This means that even if the elements or params of the original entry are destroyed, the equivalent ones in this entry will still be valid.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate the read of the entry with other accesses and modifications.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate access and the use of memory management functions to create the copy.

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 a lock that could be left locked as well as memory management functions.

Parameters

entry

The entry to copy.

Returns

A new entry that is a deep copy of the original. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_destroy_entry()

STUMPLESS_PUBLIC_FUNCTION void stumpless_destroy_entry

(

const struct stumpless_entry *

entry

)

An alias for stumpless_destroy_entry_and_contents.

Thread Safety: MT-Unsafe This function is not thread safe as it destroys resources that other threads would use if they tried to reference this struct.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the destruction of a lock that may be in use as well as the use of the memory deallocation function to release memory.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, as the cleanup of the lock may not be completed, and the memory deallocation function may not be AC-Safe itself.

Deprecated

This function has been deprecated in favor of the more descriptive and deliberate stumpless_destroy_entry_and_contents and stumpless_destroy_entry_only functions in order to avoid unintentional memory leaks and use-after-free mistakes.

Parameters

entry

The entry to destroy.

stumpless_destroy_entry_and_contents()

STUMPLESS_PUBLIC_FUNCTION void stumpless_destroy_entry_and_contents

(

const struct stumpless_entry *

entry

)

Destroys an entry as well as all elements and params that it contains, freeing any allocated memory.

Thread Safety: MT-Unsafe This function is not thread safe as it destroys resources that other threads would use if they tried to reference this struct.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the destruction of a lock that may be in use as well as the use of the memory deallocation function to release memory.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, as the cleanup of the lock may not be completed, and the memory deallocation function may not be AC-Safe itself.

Parameters

entry

The entry to destroy.

Examples

entry_example.c, file_example.c, filter_example.c, function_example.c, journald_example.c, socket_example.c, sqlite3_example.c, stream_example.c, tcp_example.c, udp_example.c, and wel_example.c.

stumpless_destroy_entry_only()

STUMPLESS_PUBLIC_FUNCTION void stumpless_destroy_entry_only

(

const struct stumpless_entry *

entry

)

Destroys an entry, freeing any allocated memory.

Associated elements and params are left untouched, and must be destroyed separately.

Thread Safety: MT-Unsafe This function is not thread safe as it destroys resources that other threads would use if they tried to reference this struct.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the destruction of a lock that may be in use as well as the use of the memory deallocation function to release memory.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, as the cleanup of the lock may not be completed, and the memory deallocation function may not be AC-Safe itself.

Parameters

entry

The entry to destroy.

Examples

entry_example.c.

stumpless_entry_has_element()

STUMPLESS_PUBLIC_FUNCTION bool stumpless_entry_has_element	(	const struct stumpless_entry *	entry,
		const char *	name )

True if the given entry has an element with the given name, false otherwise.

Thread Safety: MT-Safe race:name This function is thread safe, of course assuming that name is not changed by another thread during execution. A mutex is used to coordinate access to the entry with other accesses and modifications.

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

Since

release v1.6.0.

Parameters

entry	The entry to search for the element.
name	The name of the element to check for.

Returns

True if no error is encountered and the element is found. If the element is not found or an error is encountered, then false is returned and an error code is set appropriately.

stumpless_get_element_by_index()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_get_element_by_index	(	const struct stumpless_entry *	entry,
		size_t	index )

Returns the element at the given index in this Entry.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate access to the entry with other accesses and modifications.

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

Since

release v1.6.0.

Parameters

entry	The entry to search.
index	The index of the element to get.

Returns

The element if it is found in the entry, or NULL otherwise. If an error was encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_element_by_name()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_get_element_by_name	(	const struct stumpless_entry *	entry,
		const char *	name )

Returns the element with the given name in this entry, if it is found.

Thread Safety: MT-Safe race:name This function is thread safe, of course assuming that name is not changed by another thread during execution. A mutex is used to coordinate access to the entry with other accesses and modifications.

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

Since

release v1.6.0.

Parameters

entry	The entry to search.
name	The name of the element to search for.

Returns

The element if it is found in the entry, or NULL otherwise. If an error was encountered, then NULL is returned and an error code is set appropriately.

Examples

filter_example.c.

stumpless_get_element_count()

STUMPLESS_PUBLIC_FUNCTION size_t stumpless_get_element_count

(

const struct stumpless_entry *

entry

)

Returns the number of elements in the given entry.

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

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 the read of the entry.

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.0.0

Parameters

entry

The entry to get the element count of.

Returns

The number of elements entry has. If there is an error, zero is returned and an error code is set appropriately.

stumpless_get_element_index()

STUMPLESS_PUBLIC_FUNCTION size_t stumpless_get_element_index	(	const struct stumpless_entry *	entry,
		const char *	name )

Returns the index of the element with the given name in this entry, if it is found.

Thread Safety: MT-Safe race:name This function is thread safe, of course assuming that name is not changed by another thread during execution. A mutex is used to coordinate access to the entry with other accesses and modifications.

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

Since

release v1.6.0.

Parameters

entry	The entry to search.
name	The name of the element to search for.

Returns

The index of the element if it is found in the entry. If an error was encountered or the element does not exist in the entry, then 0 is returned and an error code is set appropriately.

stumpless_get_entry_app_name()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_entry_app_name

(

const struct stumpless_entry *

entry

)

Returns the app name of the given entry.

The character buffer returned must be freed by the caller when it is no longer needed to avoid memory leaks.

In versions prior to v2.0.0, the returned pointer was to the internal buffer used to store the name and was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate the read of the param with other accesses and modifications.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate access and the use of memory management functions to create the result.

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 a lock that could be left locked as well as memory management functions.

Since

release v1.6.0.

Parameters

entry

The entry to get the app name of.

Returns

The app name of the entry if no error is encountered. If an error was encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_entry_facility()

STUMPLESS_PUBLIC_FUNCTION enum stumpless_facility stumpless_get_entry_facility

(

const struct stumpless_entry *

entry

)

Returns the facility code of the given entry.

In versions prior to v2.0.0, this function returned an int, and -1 in the event of an error.

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

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 the read of the entry.

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 v1.6.0.

Parameters

entry

The entry to get the facility of.

Returns

The facility of the entry if no error is encountered. If an error was encountered, then an invalid facility is returned and an error code is set appropriately.

stumpless_get_entry_hostname()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_entry_hostname

(

const struct stumpless_entry *

entry

)

Returns the hostname of a given entry.

If hostname is not set it will return the machine hostname. The result character buffer must be freed by the caller when it is no longer needed to avoid memory leaks.

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

Async Signal Safety: AS-Unsafe lock heap 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 heap 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 as well as memory management functions.

Since

release v2.1.0

Parameters

entry

The entry to get the hostname of.

Returns

The hostname of the entry if no error is encountered. If an error was encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_entry_message()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_entry_message

(

const struct stumpless_entry *

entry

)

Returns the message of the given entry.

The character buffer returned must be freed by the caller when it is no longer needed to avoid memory leaks.

Note that if this message was originally set using format specifiers, the result will have them substituted, instead of the original placeholders.

It is also important to note that the message may be NULL if the entry does not have one. This differs from other fields like the app id or msgid, which will be an RFC 5424 NILVALUE '-' if they have not been set.

In versions prior to v2.0.0, the returned pointer was to the internal buffer used to store the name and was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate the read of the param with other accesses and modifications.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate access and the use of memory management functions to create the result.

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 a lock that could be left locked as well as memory management functions.

Since

release v1.6.0.

Parameters

entry

The entry to get the message of.

Returns

The message of the entry (which may be NULL). If an error was encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_entry_msgid()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_entry_msgid

(

const struct stumpless_entry *

entry

)

Returns the msgid of the given entry.

The character buffer returned must be freed by the caller when it is no longer needed to avoid memory leaks.

In versions prior to v2.0.0, the returned pointer was to the internal buffer used to store the name and was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate the read of the param with other accesses and modifications.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate access and the use of memory management functions to create the result.

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 a lock that could be left locked as well as memory management functions.

Since

release v1.6.0.

Parameters

entry

The entry to get the msgid of.

Returns

The msgid of the entry if no error is encountered. If an error was encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_entry_param_by_index()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_get_entry_param_by_index	(	const struct stumpless_entry *	entry,
		size_t	element_index,
		size_t	param_index )

Gets the param from the element at the given index in an entry.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate access to the entry with other accesses and modifications.

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

Since

release v1.6.0.

Parameters

entry	The entry to get the param from.
element_index	The index of the element to get the param from.
param_index	The index of the param to get from the element.

Returns

The param at the given index if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_entry_param_by_name()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_get_entry_param_by_name	(	const struct stumpless_entry *	entry,
		const char *	element_name,
		const char *	param_name )

Gets the first param from the element with the given name in an entry.

Note that an element may contain as many instances of a param as desired according to RFC 5424, and therefore there may be other param instances with the same name. If you need a reference to other params with the same name in the element, then you must loop through all params using stumpless_get_entry_param_by_index, checking each name.

Thread Safety: MT-Safe race:element_name race:param_name This function is thread safe, of course assuming that the names are not changed by another thread during execution. A mutex is used to coordinate access to the entry with other accesses and modifications.

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

Since

release v1.6.0.

Parameters

entry	The entry to get the param from.
element_name	The name of the element to get the param from.
param_name	The name of the param to get from the element.

Returns

The first param with the given name if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_entry_param_value_by_index()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_entry_param_value_by_index	(	const struct stumpless_entry *	entry,
		size_t	element_index,
		size_t	param_index )

Gets the value of the param from the element at the given index in an entry.

The result character buffer must be freed by the caller when it is no longer needed to avoid memory leaks.

In versions prior to v2.0.0, the returned pointer was to the internal buffer used to store the value and was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate access to the entry with other accesses and modifications.

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

Since

release v1.6.0.

Parameters

entry	The entry to get the param from.
element_index	The index of the element to get the param from.
param_index	The index of the param to get the value of.

Returns

The value of the param at the given index if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_entry_param_value_by_name()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_entry_param_value_by_name	(	const struct stumpless_entry *	entry,
		const char *	element_name,
		const char *	param_name )

Gets the value of the first param from the element with the given name in an entry.

The result character buffer must be freed by the caller when it is no longer needed to avoid memory leaks.

Note that an element may contain as many instances of a param as desired according to RFC 5424, and therefore there may be other param instances with the same name. If you need the value of other params with the same name in the element, then you must loop through all params using stumpless_get_entry_param_by_index, checking each name.

In versions prior to v2.0.0, the returned pointer was to the internal buffer used to store the value and was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues.

Thread Safety: MT-Safe race:element_name race:param_name This function is thread safe, of course assuming that the names are not changed by another thread during execution. A mutex is used to coordinate access to the entry with other accesses and modifications.

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

Since

release v1.6.0.

Parameters

entry	The entry to get the param from.
element_name	The name of the element to get the param from.
param_name	The name of the param to get from the element.

Returns

The value of the first param with the given name if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

Examples

function_example.c, and sqlite3_example.c.

stumpless_get_entry_prival()

STUMPLESS_PUBLIC_FUNCTION int stumpless_get_entry_prival

(

const struct stumpless_entry *

entry

)

Returns the prival of the given entry, as defined in RFC 5424.

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

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 the read of the entry.

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 v1.6.0.

Parameters

entry

The entry to get the prival of.

Returns

The prival of the entry if no error is encountered. If an error was encountered, then -1 is returned and an error code is set appropriately.

stumpless_get_entry_procid()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_entry_procid

(

const struct stumpless_entry *

entry

)

Returns the procid of a given entry.

If procid is not set it will return the ProcessID. The result character buffer must be freed by the caller when it is no longer needed to avoid memory leaks.

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

Async Signal Safety: AS-Unsafe lock heap 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 heap 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 as well as memory management functions.

Since

release v2.1.0

Parameters

entry

The entry to get the procid of.

Returns

The procid of the entry if no error is encountered. If an error was encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_entry_severity()

STUMPLESS_PUBLIC_FUNCTION enum stumpless_severity stumpless_get_entry_severity

(

const struct stumpless_entry *

entry

)

Returns the severity code of the given entry.

In versions prior to v2.0.0, this function returned an int, and -1 in the event of an error.

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

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 the read of the entry.

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 v1.6.0

Parameters

entry

The entry to get the severity of.

Returns

The severity of the entry if no error is encountered. If an error was encountered, then an invalid severity is returned and an error code is set appropriately.

stumpless_load_entry()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_load_entry	(	struct stumpless_entry *	entry,
		enum stumpless_facility	facility,
		enum stumpless_severity	severity,
		const char *	app_name,
		const char *	msgid,
		const char *	message,
			... )

Loads an entry struct with the given characteristics.

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

This function has the same behavior as stumpless_new_entry, except it does not create a new entry, instead loading an existing struct.

Since

release v2.2.0

Parameters

entry	The struct to load.
facility	The facility code of the event this entry describes. This should be a STUMPLESS_FACILITY value.
severity	The severity code of the event this entry describes. This should be a STUMPLESS_SEVERITY value.
app_name	The app_name of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
msgid	The message id of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
message	The message in the entry. This message may contain any format specifiers valid in printf. This also means that characters such as % need to be escaped as they would be in printf. If this is NULL, then it will be blank in the entry (no characters). 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

The loaded entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_load_entry_str()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_load_entry_str	(	struct stumpless_entry *	entry,
		enum stumpless_facility	facility,
		enum stumpless_severity	severity,
		const char *	app_name,
		const char *	msgid,
		const char *	message )

Creates a new entry with the given characteristics.

This function has the same behavior as stumpless_load_entry_str, except it does not create a new entry, instead loading an existing struct.

Since

release v2.2.0

Parameters

entry	The entry structure to load with the given fields.
facility	The facility code of the event this entry describes. This should be a STUMPLESS_FACILITY value.
severity	The severity code of the event this entry describes. This should be a STUMPLESS_SEVERITY value.
app_name	The app_name of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
msgid	The message id of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
message	The message in the entry. If this is NULL, then it will be blank in the entry (no characters). This must be a valid UTF-8 string in shortest form.

Returns

The loaded entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_new_entry()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_new_entry	(	enum stumpless_facility	facility,
		enum stumpless_severity	severity,
		const char *	app_name,
		const char *	msgid,
		const char *	message,
			... )

Creates a new entry with the given characteristics.

In versions prior to 2.0.0, the facility and severity parameters were int types instead of enums.

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

Thread Safety: MT-Safe race:app_name race:msgid race:message This function is thread safe, of course assuming that the string arguments are not changed by other threads during execution.

Async Signal Safety: AS-Unsafe heap This function is not safe to call from signal handlers due to the use of memory management functions to create the new element.

Async Cancel Safety: AC-Unsafe heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of memory management functions.

Parameters

facility	The facility code of the event this entry describes. This should be a STUMPLESS_FACILITY value.
severity	The severity code of the event this entry describes. This should be a STUMPLESS_SEVERITY value.
app_name	The app_name of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
msgid	The message id of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
message	The message in the entry. This message may contain any format specifiers valid in printf. This also means that characters such as % need to be escaped as they would be in printf. If this is NULL, then it will be blank in the entry (no characters). 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

The created entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

Examples

entry_example.c, file_example.c, filter_example.c, function_example.c, journald_example.c, socket_example.c, sqlite3_example.c, stream_example.c, tcp_example.c, udp_example.c, and wel_example.c.

stumpless_new_entry_str()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_new_entry_str	(	enum stumpless_facility	facility,
		enum stumpless_severity	severity,
		const char *	app_name,
		const char *	msgid,
		const char *	message )

Creates a new entry with the given characteristics.

Thread Safety: MT-Safe race:app_name race:msgid race:message This function is thread safe, of course assuming that the string arguments are not changed by other threads during execution.

Async Signal Safety: AS-Unsafe heap This function is not safe to call from signal handlers due to the use of memory management functions to create the new element.

Async Cancel Safety: AC-Unsafe heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of memory management functions.

Since

release v2.1.0

Parameters

facility	The facility code of the event this entry describes. This should be a STUMPLESS_FACILITY value.
severity	The severity code of the event this entry describes. This should be a STUMPLESS_SEVERITY value.
app_name	The app_name of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
msgid	The message id of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
message	The message in the entry. If this is NULL, then it will be blank in the entry (no characters). This must be a valid UTF-8 string in shortest form.

Returns

The created entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_element()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_element	(	struct stumpless_entry *	entry,
		size_t	index,
		struct stumpless_element *	element )

Puts the element at the given index in the given entry.

The element previously at this position will be removed from the entry, but it is NOT destroyed by this call. Callers must clean up this element separately.

An element cannot be set at an index position that does not already hold one. If this is attempted, then a STUMPLESS_INDEX_OUT_OF_BOUNDS error is raised.

Note that duplicate elements are not allowed in RFC 5424, and as such attempts to set an element of an entry which already contains another element with the same name will result in a STUMPLESS_DUPLICATE_ELEMENT error.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate changes to the entry with other accesses and modifications.

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

Since

release v1.6.0

Parameters

entry	The entry to set the element on.
index	The index to set to element.
element	The element to set at the given index.

Returns

The modified entry, if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_app_name()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_app_name	(	struct stumpless_entry *	entry,
		const char *	app_name )

Sets the app name for an entry.

Thread Safety: MT-Safe race:app_name This function is thread safe, of course assuming that the name is not changed by any other threads during execution. A mutex is used to coordinate changes to the entry while it is being modified.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate changes and the use of memory management functions to create the new name and free the old one.

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 a lock that could be left locked as well as memory management functions.

Parameters

entry	The entry for which the app name will be set.
app_name	A NULL-terminated string holding the new app_name for the entry. This will be copied in to the entry, and therefore may be modified or freed after this call without affecting the entry. If this is NULL, then a single '-' character will be used, as specified as the NILVALUE in RFC The app name length is restricted to be 48 characters or less.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_facility()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_facility	(	struct stumpless_entry *	entry,
		enum stumpless_facility	facility )

Sets the facility of an entry.

In versions prior to 2.0.0, the facility parameter was an int type instead of an enum.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate changes to the entry 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 v1.6.0.

Parameters

entry	The entry to set the facility of.
facility	The new facility of the entry. This must be a valid value according to RFC 5424, available as STUMPLESS_FACILITY constants.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_hostname()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_hostname	(	struct stumpless_entry *	entry,
		const char *	hostname )

Sets the hostname of a given entry.

If hostname is NULL it will set hostname to be the Machine hostname.

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

Async Signal Safety: AS-Unsafe lock heap 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 heap 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

entry	The entry to modify.
hostname	The new hostname to set on the entry.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_message()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_message	(	struct stumpless_entry *	entry,
		const char *	message,
			... )

Sets the message of a given entry.

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

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

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate changes and the use of memory management functions to create the new message and free the old one.

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 a lock that could be left locked as well as memory management functions.

Parameters

entry	The entry to modify.
message	The new message to set on the entry. This message may contain any format specifiers valid in printf. If this is NULL, then it will be blank in the entry (no characters). This also means that characters such as % need to be escaped as they would be 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

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

Examples

entry_example.c.

stumpless_set_entry_message_str()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_message_str	(	struct stumpless_entry *	entry,
		const char *	message )

Sets the message of a given entry.

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

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate changes and the use of memory management functions to create the new message and free the old one.

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 a lock that could be left locked as well as memory management functions.

Since

release v2.1.0

Parameters

entry	The entry to modify.
message	The new message to set on the entry. If this is NULL, then it will be blank in the entry (no characters). This must be a valid UTF-8 string in shortest form.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_message_str_w()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_message_str_w	(	struct stumpless_entry *	entry,
		const wchar_t *	message )

Sets the message of a given entry.

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

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate changes and the use of memory management functions to create the new message and free the old one.

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 a lock that could be left locked as well as memory management functions.

Since

release v2.2.0

Parameters

entry	The entry to modify.
message	The new message to set on the entry. If this is NULL, then it will be blank in the entry (no characters). This must be a valid UTF-16 string in shortest form.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_msgid()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_msgid	(	struct stumpless_entry *	entry,
		const char *	msgid )

Sets the msgid for an entry.

Thread Safety: MT-Safe race:msgid This function is thread safe, of course assuming that the msgid is not changed by any other threads during execution. A mutex is used to coordinate changes to the entry while it is being modified.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate changes and the use of memory management functions to create the new msgid and free the old one.

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 a lock that could be left locked as well as memory management functions.

Since

release v1.6.0.

Parameters

entry	The entry for which the msgid will be set.
msgid	A NULL-terminated string holding the new msgid for the entry. The string must be in the ASCII printable range 33 <= character <= 126 as specified in RFC5424. This will be copied in to the entry, and therefore may be modified or freed after this call without affecting the entry. If this is NULL, then a single '-' character will be used, as specified as the NILVALUE in RFC 5424.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_param_by_index()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_param_by_index	(	struct stumpless_entry *	entry,
		size_t	element_index,
		size_t	param_index,
		struct stumpless_param *	param )

Puts the param in the element at the given index of an entry.

The parameter previously at this position will be removed from the element, but it is NOT destroyed by this call. Callers must clean up this param separately.

A param cannot be set at an index position that does not already hold a param. If this is attempted, then a STUMPLESS_INDEX_OUT_OF_BOUNDS error is raised.

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

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

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 a lock that could be left locked as well as memory management functions.

Since

release v1.6.0

Parameters

entry	The entry to set the param on.
element_index	The index of the element to have the param.
param_index	The index to put the param at in the chosen element.
param	The param to set.

Returns

The modified entry, if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_param_value_by_index()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_param_value_by_index	(	struct stumpless_entry *	entry,
		size_t	element_index,
		size_t	param_index,
		const char *	value )

Sets the value of the param in the element at the given index of an entry.

Thread Safety: MT-Safe race:value This function is thread safe, of course assuming that value is not changed by any other threads during execution. A mutex is used to coordinate changes to the entry while it is being modified.

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

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 a lock that could be left locked as well as memory management functions.

Since

release v1.6.0

Parameters

entry	The entry to set the param value on.
element_index	The index of the element having the param to modify.
param_index	The index of the param to set the value of.
value	The new value to set on the param.

Returns

The modified entry, if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_param_value_by_name()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_param_value_by_name	(	struct stumpless_entry *	entry,
		const char *	element_name,
		const char *	param_name,
		const char *	value )

Sets the value of the first param in the named element an entry.

If an element with the given name is not found in the entry, one is created with the supplied name and added to the end of the entry.

If a param of the given name is not found in the named element, one is created with the supplied name and value and added to the end of the element.

If you need to set the value of a param with this name other than the first one, then you will need to loop through the params using stumpless_get_entry_param_by_index to find the params you want and then set the value using stumpless_set_entry_param_value_by_index.

Thread Safety: MT-Safe race:element_name race:param_name race:value This function is thread safe, of course assuming that the names and value are not changed by any other threads during execution. A mutex is used to coordinate changes to the entry while it is being modified.

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

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 a lock that could be left locked as well as memory management functions.

Since

release v1.6.0

Parameters

entry	The entry to set the param value on.
element_name	The name of the element having the param to modify.
param_name	The name of the param to set the value of.
value	The new value to set on the param.

Returns

The modified entry, if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

Examples

entry_example.c, and function_example.c.

stumpless_set_entry_priority()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_priority	(	struct stumpless_entry *	entry,
		enum stumpless_facility	facility,
		enum stumpless_severity	severity )

Sets the facility and severity of an entry.

In versions prior to 2.0.0, the facility and severity parameters were int types instead of enums.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate changes to the entry 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 v1.6.0.

Parameters

entry	The entry to set the priority values of.
facility	The new facility of the entry. This must be a valid value according to RFC 5424, available as STUMPLESS_FACILITY constants.
severity	The new severity of the entry. This must be a valid value according to RFC 5424, available as STUMPLESS_SEVERITY constants.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_prival()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_prival	(	struct stumpless_entry *	entry,
		int	prival )

Sets the prival of an entry, as defined in RFC 5424.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate changes to the entry 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 v1.6.0.

Parameters

entry	The entry to set the prival of.
prival	The new prival of the entry, as defined in RFC 5424. Only the first 8 bits of prival are considered: the rest are discarded after extracting the effective facility and severity.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_procid()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_procid	(	struct stumpless_entry *	entry,
		const char *	procid )

Sets the procid of a given entry.

If procid is NULL it will set procid to be the ProcessID.

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

Async Signal Safety: AS-Unsafe lock heap 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 heap 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

entry	The entry to modify.
procid	The new procid to set on the entry.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_set_entry_severity()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * stumpless_set_entry_severity	(	struct stumpless_entry *	entry,
		enum stumpless_severity	severity )

Sets the severity of an entry.

In versions prior to 2.0.0, the severity parameter was an int type instead of an enum.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate changes to the entry 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 v1.6.0.

Parameters

entry	The entry to set the severity of.
severity	The new severity of the entry. This must be a valid value according to RFC 5424, available as STUMPLESS_SEVERITY constants.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_unload_entry_and_contents()

STUMPLESS_PUBLIC_FUNCTION void stumpless_unload_entry_and_contents

(

const struct stumpless_entry *

entry

)

Unloads an entry as well as all elements that it contains.

Either this function or stumpless_unload_entry_only must be used to clean up any entry struct previously loaded with stumpless_load_entry.

Thread Safety: MT-Unsafe This function is not thread safe as it destroys resources that other threads would use if they tried to reference this struct.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the destruction of a lock that may be in use as well as the use of the memory deallocation function to release memory.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, as the cleanup of the lock may not be completed, and the memory deallocation function may not be AC-Safe itself.

Since

release v2.2.0

Parameters

entry

The entry to unload.

stumpless_unload_entry_only()

STUMPLESS_PUBLIC_FUNCTION void stumpless_unload_entry_only

(

const struct stumpless_entry *

entry

)

Unloads an entry, freeing any allocated memory.

Associated elements are left untouched, and must be unloaded separately.

Either this function or stumpless_unload_entry_and_contents must be used to clean up any entry struct previously loaded with stumpless_load_entry.

Thread Safety: MT-Unsafe This function is not thread safe as it destroys resources that other threads would use if they tried to reference this struct.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the destruction of a lock that may be in use as well as the use of the memory deallocation function to release memory.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, as the cleanup of the lock may not be completed, and the memory deallocation function may not be AC-Safe itself.

Since

release v2.2.0

Parameters

entry

The entry to unload.

vstumpless_load_entry()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * vstumpless_load_entry	(	struct stumpless_entry *	entry,
		enum stumpless_facility	facility,
		enum stumpless_severity	severity,
		const char *	app_name,
		const char *	msgid,
		const char *	message,
		va_list	subs )

Creates a new entry with the given parameters.

This function has the same behavior as vstumpless_new_entry, except it does not create a new entry, instead loading an existing struct.

Since

release v2.2.0

Parameters

entry	The struct to load.
facility	The facility code of the entry. This should be a STUMPLESS_FACILITY value.
severity	The severity code of the entry. This should be a STUMPLESS_SEVERITY value.
app_name	The app_name of the entry. If this is NULL, then it will be blank in the entry (a single '-' character). The app name length is restricted to be 48 characters or less.
msgid	The message id of the entry. If this is NULL, then it will be blank in the entry (a single '-' character). The string must be in the ASCII printable range 33 <= character <= 126 as specified in RFC5424.
message	The message in the entry. This message may contain any format specifiers valid in printf. If this is NULL, then it will be blank in the entry (no characters). This also means that characters such as % need to be escaped as they would be 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 them.

Returns

The loaded entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

vstumpless_new_entry()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * vstumpless_new_entry	(	enum stumpless_facility	facility,
		enum stumpless_severity	severity,
		const char *	app_name,
		const char *	msgid,
		const char *	message,
		va_list	subs )

Creates a new entry with the given parameters.

In versions prior to 2.0.0, the facility and severity parameters were int types instead of enums.

Thread Safety: MT-Safe race:app_name race:msgid race:message This function is thread safe, of course assuming that the string arguments are not changed by other threads during execution.

Async Signal Safety: AS-Unsafe heap This function is not safe to call from signal handlers due to the use of memory management functions to create the new element.

Async Cancel Safety: AC-Unsafe heap This function is not safe to call from threads that may be asynchronously cancelled, due to the use of memory management functions.

Parameters

facility	The facility code of the entry. This should be a STUMPLESS_FACILITY value.
severity	The severity code of the entry. This should be a STUMPLESS_SEVERITY value.
app_name	The app_name of the entry. If this is NULL, then it will be blank in the entry (a single '-' character). The app name length is restricted to be 48 characters or less.
msgid	The message id of the entry. If this is NULL, then it will be blank in the entry (a single '-' character). The string must be in the ASCII printable range 33 <= character <= 126 as specified in RFC5424.
message	The message in the entry. This message may contain any format specifiers valid in printf. If this is NULL, then it will be blank in the entry (no characters). This also means that characters such as % need to be escaped as they would be 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 them.

Returns

The created entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

vstumpless_set_entry_message()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_entry * vstumpless_set_entry_message	(	struct stumpless_entry *	entry,
		const char *	message,
		va_list	subs )

Sets the message of a given entry.

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

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the use of a non-reentrant lock to coordinate changes and the use of memory management functions to create the new message and free the old one.

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 a lock that could be left locked as well as memory management functions.

Parameters

entry	The entry to modify.
message	The new message to set on the entry. This message may contain any format specifiers valid in printf. If this is NULL, then it will be blank in the entry (no characters). Characters such as % need to be escaped as they would be 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 them.

Returns

The modified entry if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.