- Generated by
1.11.0
|
stumpless 2.2.0
|
Types and functions for creating and modifying params. More...
Go to the source code of this file.
Data Structures | |
| struct | stumpless_param |
| A parameter within a structured data element. More... | |
Macros | |
| #define | STUMPLESS_MAX_PARAM_NAME_LENGTH 32 |
| The maximum length of a parameter name, as specified by RFC 5424. | |
Functions | |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * | stumpless_copy_param (const struct stumpless_param *param) |
| Creates a copy of a param. | |
| STUMPLESS_PUBLIC_FUNCTION void | stumpless_destroy_param (const struct stumpless_param *param) |
| Destroys a param, freeing any allocated memory. | |
| STUMPLESS_PUBLIC_FUNCTION const char * | stumpless_get_param_name (const struct stumpless_param *param) |
| Returns the name of the given param. | |
| STUMPLESS_PUBLIC_FUNCTION const char * | stumpless_get_param_value (const struct stumpless_param *param) |
| Returns the value of the given param. | |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * | stumpless_load_param (struct stumpless_param *param, const char *name, const char *value) |
| Loads a provided param with the given values. | |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * | stumpless_new_param (const char *name, const char *value) |
| Creates a new param with the given name and value. | |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * | stumpless_new_param_from_string (const char *string) |
| Creates a new param given a string by parsing the string and calling stumpless_new_param. | |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * | stumpless_set_param_name (struct stumpless_param *param, const char *name) |
| Sets the name of the given param. | |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * | stumpless_set_param_value (struct stumpless_param *param, const char *value) |
| Sets the value of the given param. | |
| STUMPLESS_PUBLIC_FUNCTION const char * | stumpless_param_to_string (const struct stumpless_param *param) |
| Returns the name and the value from param as a formatted string. | |
| STUMPLESS_PUBLIC_FUNCTION void | stumpless_unload_param (const struct stumpless_param *param) |
| Unloads a param. | |
Types and functions for creating and modifying params.
| #define STUMPLESS_MAX_PARAM_NAME_LENGTH 32 |
The maximum length of a parameter name, as specified by RFC 5424.
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_copy_param | ( | const struct stumpless_param * | param | ) |
Creates a copy of a param.
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 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.
| param | The param to copy. |
| STUMPLESS_PUBLIC_FUNCTION void stumpless_destroy_param | ( | const struct stumpless_param * | param | ) |
Destroys a param, 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.
| param | The param to destroy. |
| STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_param_name | ( | const struct stumpless_param * | param | ) |
Returns the name of the given param.
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 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.
| param | The param to get the name from. |
| STUMPLESS_PUBLIC_FUNCTION const char * stumpless_get_param_value | ( | const struct stumpless_param * | param | ) |
Returns the value of the given param.
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 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 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.
| param | The param to get the value from. |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_load_param | ( | struct stumpless_param * | param, |
| const char * | name, | ||
| const char * | value ) |
Loads a provided param with the given values.
This function will allocate less memory than stumpless_new_param, but will still allocate memory for the value of the param, which may be of variable length.
A param loaded using this function must be unloaded with stumpless_unload_param when it is no longer needed. Calling stumpless_destroy_param or any function that does (such as stumpless_destroy_entry_and_contents will result in memory corruption).
Thread Safety: MT-Safe race:param race:name race:value This function is thread safe, assuming that the param, name, and value are not changed by other threads during execution.
Async Signal Safety: AS-Unsafe heap lock This function is not safe to call from signal handlers due to the use of memory management functions to create the param's value as well as the use of a mutex initialization routine.
Async Cancel Safety: AC-Unsafe heap lock This function is not safe to call from threads that may be asynchronously cancelled, due to the use of memory management functions and a mutex initialization routine.
| param | The struct to load with the given values. |
| name | The name of the param. |
| value | The value of the param. This pointer will be stored and used over the lifetime of the param, and must be valid until stumpless_unload_param is called on this loaded param. |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_new_param | ( | const char * | name, |
| const char * | value ) |
Creates a new param with the given name and value.
Thread Safety: MT-Safe race:name race:value This function is thread safe, of course assuming that name and value are not changed by other threads during execution.
Async Signal Safety: AS-Unsafe heap lock This function is not safe to call from signal handlers due to the use of memory management functions to create the new param as well as the use of a mutex initialization routine.
Async Cancel Safety: AC-Unsafe heap lock This function is not safe to call from threads that may be asynchronously cancelled, due to the use of memory management functions and a mutex initialization routine.
| name | The name of the new param. Restricted to printable ASCII characters different from '=', ']' and '"'. |
| value | The value of the new param. The value must be UTF-8 string. |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_new_param_from_string | ( | const char * | string | ) |
Creates a new param given a string by parsing the string and calling stumpless_new_param.
**Thread Safety: MT-Safe This function is thread safe, assuming the the given string is not changed by other threads during execution.
Async Signal Safety: AS-Unsafe heap This function is not safe to call from signal handlers since it calls stumpless_new_param() which has usage of memory management functions.
Async Cancel Safety: AC_Unsafe heap This function is not safe to call from threads that may be asynchronously cancelled, since it calls stumpless_new_param() which has usage of memory management functions.
| string | The string to create the stumpless_param from. |
| STUMPLESS_PUBLIC_FUNCTION const char * stumpless_param_to_string | ( | const struct stumpless_param * | param | ) |
Returns the name and the value from param 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 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.
| param | The param to get the name and the value from. |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_set_param_name | ( | struct stumpless_param * | param, |
| const char * | name ) |
Sets the name of the given param.
Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate changes to the param 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.
| param | The param to set the name of. |
| name | The new name of param. Restricted to printable ASCII characters different from '=', ']' and '"'. |
| STUMPLESS_PUBLIC_FUNCTION struct stumpless_param * stumpless_set_param_value | ( | struct stumpless_param * | param, |
| const char * | value ) |
Sets the value of the given param.
Thread Safety: MT-Safe This function is thread safe. A mutex is used to coordinate changes to the param 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 value 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.
| param | The param to set the value of. |
| value | The new name of param. The value must be UTF-8 string. |
| STUMPLESS_PUBLIC_FUNCTION void stumpless_unload_param | ( | const struct stumpless_param * | param | ) |
Unloads a param.
Either this function, stumpless_unload_element_and_contents, or stumpless_unload_entry_and_contents must be used to clean up any param struct previously loaded with stumpless_load_param.
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.
| param | The param to unload. |
1.11.0