element.h File Reference

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

Go to the source code of this file.

Data Structures
struct	stumpless_element
	An element of structured data. More...

Macros
#define	STUMPLESS_MAX_ELEMENT_NAME_LENGTH   32
	The maximum length of an element name, as specified by RFC 5424.

Functions
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_add_new_param (struct stumpless_element *element, const char *param_name, const char *param_value)
	Creates a new param and adds it to the given element.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_add_param (struct stumpless_element *element, struct stumpless_param *param)
	Adds a param to an element.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_copy_element (const struct stumpless_element *element)
	Creates a copy of an element.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_destroy_element (const struct stumpless_element *element)
	An alias for stumpless_destroy_element_and_contents.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_destroy_element_and_contents (const struct stumpless_element *e)
	Destroys an element as well as all params that it contains, freeing any allocated memory.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_destroy_element_only (const struct stumpless_element *element)
	Destroys an element, freeing any allocated memory.
STUMPLESS_PUBLIC_FUNCTION bool	stumpless_element_has_param (const struct stumpless_element *element, const char *name)
	True if the given element has a param with the given name, false otherwise.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_element_to_string (const struct stumpless_element *element)
	Returns name and params from element as a formatted string.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_element_name (const struct stumpless_element *element)
	Returns the name of the given element.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_param *	stumpless_get_param_by_index (const struct stumpless_element *element, size_t index)
	Returns the param in the given element at the specified index.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_param *	stumpless_get_param_by_name (const struct stumpless_element *element, const char *name)
	Returns the first occurrence of a param with the given name in element, if it is found.
STUMPLESS_PUBLIC_FUNCTION size_t	stumpless_get_param_count (const struct stumpless_element *element)
	Returns the number of params in the given element.
STUMPLESS_PUBLIC_FUNCTION size_t	stumpless_get_param_index (const struct stumpless_element *element, const char *name)
	Gives the index of the first occurrence of a param with the given name in the given element.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_param_name_by_index (const struct stumpless_element *element, size_t index)
	Gets the name of the param with the given index in this element.
STUMPLESS_PUBLIC_FUNCTION size_t	stumpless_get_param_name_count (const struct stumpless_element *element, const char *name)
	Gives the number of params with the given name found in the given element.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_param_value_by_index (const struct stumpless_element *element, size_t index)
	Returns the value of the param at the given index in the given element.
STUMPLESS_PUBLIC_FUNCTION const char *	stumpless_get_param_value_by_name (const struct stumpless_element *element, const char *name)
	Returns the value of the first param with the given name in the given element.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_load_element (struct stumpless_element *element, const char *name)
	Loads a provided element with the given name.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_new_element (const char *name)
	Creates a new element with the given name.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_set_element_name (struct stumpless_element *element, const char *name)
	Sets the name of the given element.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_set_param (struct stumpless_element *element, size_t index, struct stumpless_param *param)
	Puts the param at the given index in the given element.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_set_param_value_by_index (struct stumpless_element *element, size_t index, const char *value)
	Sets the value of the param at the given index in the given element.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_element *	stumpless_set_param_value_by_name (struct stumpless_element *element, const char *name, const char *value)
	Sets the value of the first param with the given name in the given element.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_unload_element_and_contents (const struct stumpless_element *e)
	Unloads an element as well as all params that it contains.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_unload_element_only (const struct stumpless_element *element)
	Unloads an element, freeing any allocated memory.

Detailed Description

Types and functions for creating and modifying elements.

Macro Definition Documentation

STUMPLESS_MAX_ELEMENT_NAME_LENGTH

#define STUMPLESS_MAX_ELEMENT_NAME_LENGTH   32

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

Function Documentation

stumpless_add_new_param()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_add_new_param	(	struct stumpless_element *	element,
		const char *	param_name,
		const char *	param_value )

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

This is equivalent to calling stumpless_new_param() and passing the result directly stumpless_add_param().

Thread Safety: MT-Safe race:param_name race:param_value This function is thread safe, of course assuming that the param name and value or not changed by other threads during execution. A mutex is used to coordinate updates to the element 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 new param.

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

element	The element to add the new param to.
param_name	The name of the new param.
param_value	The value of the new param.

Returns

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

stumpless_add_param()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_add_param	(	struct stumpless_element *	element,
		struct stumpless_param *	param )

Adds a param to an element.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate updates to the element 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 adjust the array of params in the element.

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

element	The element to add the param to.
param	The param to add to element.

Returns

The modified element 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_copy_element()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_copy_element

(

const struct stumpless_element *

element

)

Creates a copy of an element.

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

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate the read of the element 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.

Since

release v1.6.0.

Parameters

element

The element to copy.

Returns

A new element 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_element()

STUMPLESS_PUBLIC_FUNCTION void stumpless_destroy_element

(

const struct stumpless_element *

element

)

An alias for stumpless_destroy_element_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_element_and_contents and stumpless_destroy_element_only functions in order to avoid unintentional memory leaks and use-after-free mistakes.

Parameters

element

The element to destroy.

stumpless_destroy_element_and_contents()

STUMPLESS_PUBLIC_FUNCTION void stumpless_destroy_element_and_contents

(

const struct stumpless_element *

e

)

Destroys an element as well as all 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

e	The element to destroy.

Examples

entry_example.c.

stumpless_destroy_element_only()

STUMPLESS_PUBLIC_FUNCTION void stumpless_destroy_element_only

(

const struct stumpless_element *

element

)

Destroys an element, freeing any allocated memory.

Associated 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

element

The element to destroy.

stumpless_element_has_param()

STUMPLESS_PUBLIC_FUNCTION bool stumpless_element_has_param	(	const struct stumpless_element *	element,
		const char *	name )

True if the given element has a param 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 element 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

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

Returns

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

stumpless_element_to_string()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_element_to_string

(

const struct stumpless_element *

element

)

Returns name and params from element as a formatted string.

The character buffer should be freed when no longer is needed by the caller.

Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate the read of the element 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 v2.2.0

Parameters

element

The element to get the name and params from.

Returns

The formatted string of name or name=[param1,...] if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_get_element_name()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_element_name

(

const struct stumpless_element *

element

)

Returns the name of the given element.

The 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 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 element 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

element

The element to get the name from.

Returns

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

stumpless_get_param_by_index()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_get_param_by_index	(	const struct stumpless_element *	element,
		size_t	index )

Returns the param in the given element at the specified index.

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

element	The element to get the param from.
index	The index of the param to retrieve.

Returns

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

stumpless_get_param_by_name()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_get_param_by_name	(	const struct stumpless_element *	element,
		const char *	name )

Returns the first occurrence of a param with the given name in element, if it is found.

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 simply need a count of params with a given name, then you can use stumpless_get_param_name_count to find this. If you need a reference to any other params, then you must loop through all params in the element using stumpless_get_param_by_index, checking each name.

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 element 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

element	The element to search.
name	The param name to search for.

Returns

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

stumpless_get_param_count()

STUMPLESS_PUBLIC_FUNCTION size_t stumpless_get_param_count

(

const struct stumpless_element *

element

)

Returns the number of params in the given element.

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

element

The element to get the param count of.

Returns

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

stumpless_get_param_index()

STUMPLESS_PUBLIC_FUNCTION size_t stumpless_get_param_index	(	const struct stumpless_element *	element,
		const char *	name )

Gives the index of the first occurrence of a param with the given name in the given element.

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 that this function does not recognize. If you simply need a count of params with a given name, then you can use stumpless_get_param_name_count to find this. If you need a reference to any other params, then you must loop through all params in the element using stumpless_get_param_by_index, checking each name.

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 element 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

element	The element to search for params with the given name.
name	The name to search params for.

Returns

The first instance of a param with name in element, if one exists. If there is no such param or an error is encountered, NULL is returned and an error code is set appropriately.

stumpless_get_param_name_by_index()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_param_name_by_index	(	const struct stumpless_element *	element,
		size_t	index )

Gets the name of the param with the given index in this element.

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 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 element 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

element	The element to get the param and name from.
index	The index of the param to get the name from.

Returns

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

stumpless_get_param_name_count()

STUMPLESS_PUBLIC_FUNCTION size_t stumpless_get_param_name_count	(	const struct stumpless_element *	element,
		const char *	name )

Gives the number of params with the given name found in the given element.

If you need to get an actual reference to any of these params beyond the first one, then you will need to loop through all params in the element using stumpless_get_param_by_index, checking each name.

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 element 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

element	The element to search for params.
name	The name to look for in params.

Returns

The number of params found with the given name in the given element. If an error is encountered, zero is returned and an error code is set appropriately.

stumpless_get_param_value_by_index()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_param_value_by_index	(	const struct stumpless_element *	element,
		size_t	index )

Returns the value of the param at the given index in the given element.

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 the read of the element 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

element	The element to retrieve the param and value from.
index	The index of the param to get the value from.

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_param_value_by_name()

STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_param_value_by_name	(	const struct stumpless_element *	element,
		const char *	name )

Returns the value of the first param with the given name in the given element.

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

If you need to get the value of a param with the given name beyond the first one, then you will need to loop through all params in the element using stumpless_get_param_by_index, checking each name.

Since

release v1.6.0

Parameters

element	The element to retrieve the param and value from.
name	The name of the param to get the value from.

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.

stumpless_load_element()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_load_element	(	struct stumpless_element *	element,
		const char *	name )

Loads a provided element with the given name.

Does not call any memory allocation routines, and is faster than stumpless_new_element as a result.

An element loaded using this function must be unloaded with stumpless_unload_element when it is no longer needed. Calling stumpless_destroy_element or any function that does (such as stumpless_destroy_entry_and_contents will result in memory corruption).

Thread Safety: MT-Safe race:element race:name This function is thread safe, assuming that the element and name are not changed by other threads during execution.

Async Signal Safety: AS-Unsafe lock This function is not safe to call from signal handlers due to the use of a mutex initialization routine. If STUMPLESS_THREAD_SAFETY_SUPPORTED is not defined, then this function is AS-Safe.

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 mutex initialization routine. If STUMPLESS_THREAD_SAFETY_SUPPORTED is not defined, then this function is AC-Safe.

Since

release v2.2.0

Parameters

element	The struct to load.
name	The name of the element.

Returns

A pointer to the loaded element, if no error is encountered. If an error is encountered, then NULL is returned and an error code is set appropriately.

stumpless_new_element()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_new_element

(

const char *

name

)

Creates a new element with the given name.

Thread Safety: MT-Safe race:name This function is thread safe, of course assuming that name is 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

name	The new name of the element. Valid name should have printable ASCII characters expect '=', ']' , '"' and should be 32 characters long

Returns

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

Examples

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

stumpless_set_element_name()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_set_element_name	(	struct stumpless_element *	element,
		const char *	name )

Sets the name of the given element.

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

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

element	The element to set the name of.
name	The new name of the element. Valid name should have printable ASCII characters expect '=', ']' , '"' and should be 32 characters long

Returns

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

stumpless_set_param()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_set_param	(	struct stumpless_element *	element,
		size_t	index,
		struct stumpless_param *	param )

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

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 element 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

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

Returns

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

stumpless_set_param_value_by_index()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_set_param_value_by_index	(	struct stumpless_element *	element,
		size_t	index,
		const char *	value )

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

Thread Safety: MT-Safe race:value This function is thread safe, of course assuming that the value is not changed during execution by another thread. A mutex is used to coordinate changes to the element 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.

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

element	The element to set the param on.
index	The index of the param to set the value of.
value	The new value to set on the param.

Returns

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

stumpless_set_param_value_by_name()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_element * stumpless_set_param_value_by_name	(	struct stumpless_element *	element,
		const char *	name,
		const char *	value )

Sets the value of the first param with the given name in the given element.

If a param of the given name is not found in the 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_param_by_index to find the params you want and then set the value using stumpless_set_param_value.

Thread Safety: MT-Safe race:name race:value This function is thread safe, of course assuming that the name and value are not changed during execution by another thread.. A mutex is used to coordinate changes to the element 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.

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

element	The element to set the param on.
name	The name of the param to set the value of (or create).
value	The new value to set on the param..

Returns

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

stumpless_unload_element_and_contents()

STUMPLESS_PUBLIC_FUNCTION void stumpless_unload_element_and_contents

(

const struct stumpless_element *

e

)

Unloads an element as well as all params that it contains.

Either this function or stumpless_unload_element_only must be used to clean up any element struct previously loaded with stumpless_load_element.

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

e	The element to unload.

stumpless_unload_element_only()

STUMPLESS_PUBLIC_FUNCTION void stumpless_unload_element_only

(

const struct stumpless_element *

element

)

Unloads an element, freeing any allocated memory.

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

Either this function or stumpless_unload_element_and_contents must be used to clean up any element struct previously loaded with stumpless_load_element.

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

element

The element to unload.