error.h File Reference

#include <stdbool.h>
#include <stdio.h>
#include <stumpless/config.h>
#include <stumpless/generator.h>

Go to the source code of this file.

Data Structures
struct	stumpless_error
	Information describing an error encountered by the library. More...

Macros
#define	STUMPLESS_FOREACH_ERROR(ERROR)
	A macro to implement error id enum and error string array. More...

Enumerations
enum	stumpless_error_id {   STUMPLESS_ADDRESS_FAILURE = ( 0 ), STUMPLESS_ARGUMENT_EMPTY = ( 1 ), STUMPLESS_ARGUMENT_TOO_BIG = ( 2 ), STUMPLESS_DUPLICATE_ELEMENT = ( 3 ),   STUMPLESS_ELEMENT_NOT_FOUND = ( 4 ), STUMPLESS_FILE_OPEN_FAILURE = ( 5 ), STUMPLESS_FILE_WRITE_FAILURE = ( 6 ), STUMPLESS_INDEX_OUT_OF_BOUNDS = ( 7 ),   STUMPLESS_INVALID_FACILITY = ( 8 ), STUMPLESS_INVALID_ID = ( 9 ), STUMPLESS_INVALID_SEVERITY = ( 10 ), STUMPLESS_MEMORY_ALLOCATION_FAILURE = ( 11 ),   STUMPLESS_NETWORK_PROTOCOL_UNSUPPORTED = ( 12 ), STUMPLESS_PARAM_NOT_FOUND = ( 13 ), STUMPLESS_SOCKET_BIND_FAILURE = ( 14 ), STUMPLESS_SOCKET_CONNECT_FAILURE = ( 15 ),   STUMPLESS_SOCKET_FAILURE = ( 16 ), STUMPLESS_SOCKET_SEND_FAILURE = ( 17 ), STUMPLESS_STREAM_WRITE_FAILURE = ( 18 ), STUMPLESS_TARGET_INCOMPATIBLE = ( 19 ),   STUMPLESS_TARGET_UNSUPPORTED = ( 20 ), STUMPLESS_TRANSPORT_PROTOCOL_UNSUPPORTED = ( 21 ), STUMPLESS_WINDOWS_EVENT_LOG_CLOSE_FAILURE = ( 22 ), STUMPLESS_WINDOWS_EVENT_LOG_OPEN_FAILURE = ( 23 ),   STUMPLESS_INVALID_ENCODING = ( 24 ), STUMPLESS_GETHOSTNAME_FAILURE = ( 25 ), STUMPLESS_FUNCTION_TARGET_FAILURE = ( 26 ), STUMPLESS_JOURNALD_FAILURE = ( 27 ),   STUMPLESS_WINDOWS_FAILURE = ( 28 ) }
	An (enum) identifier of the types of errors that might be encountered. More...

Functions
const struct stumpless_error *	stumpless_get_error (void)
	Retrieves the error encountered by the last library call. More...
enum stumpless_error_id	stumpless_get_error_id (const struct stumpless_error *err)
	Gets the error id of the given error. More...
const char *	stumpless_get_error_id_string (enum stumpless_error_id id)
	Gets the error string of the given error id. More...
FILE *	stumpless_get_error_stream (void)
	Gets the current stream that errors are written to. More...
bool	stumpless_has_error (void)
	True if the last call to a stumpless function encountered an error. More...
void	stumpless_perror (const char *prefix)
	Prints information about the current error to the error stream. More...
void	stumpless_set_error_stream (FILE *stream)
	Sets the stream to write errors to. More...

Detailed Description

Error codes and functions for detecting and assessing them.

Macro Definition Documentation

STUMPLESS_FOREACH_ERROR

#define STUMPLESS_FOREACH_ERROR

(

ERROR

)

A macro to implement error id enum and error string array.

Enumeration Type Documentation

stumpless_error_id

enum stumpless_error_id

An (enum) identifier of the types of errors that might be encountered.

Note that the same error may be encountered in different contexts with a different ultimate cause. To completely diagnose a problem, you will need to look at more than just the error id.

Note

The real implementation of enum values is now moved under STUMPLESS_FOREACH_ERROR(ERROR) macro.

Enumerator
STUMPLESS_ADDRESS_FAILURE	A provided network address was not valid. This might be formatting problem, or it might mean that a DNS lookup failed.
STUMPLESS_ARGUMENT_EMPTY	A required function parameter was NULL or empty.
STUMPLESS_ARGUMENT_TOO_BIG	A provided argument was too big, for example to fit into a buffer target.
STUMPLESS_DUPLICATE_ELEMENT	A duplicate of an already existing element was detected in an entry. Since release v1.6.0.
STUMPLESS_ELEMENT_NOT_FOUND	No element with the specified characteristics was found. Since release v1.6.0.
STUMPLESS_FILE_OPEN_FAILURE	Could not open a file.
STUMPLESS_FILE_WRITE_FAILURE	Could not write to a file.
STUMPLESS_INDEX_OUT_OF_BOUNDS	A provided index was not in a valid range.
STUMPLESS_INVALID_FACILITY	A provided facility code did not conform to RFC 5424.
STUMPLESS_INVALID_ID	A target or entry ID was not valid.
STUMPLESS_INVALID_SEVERITY	A provided severity code did not conform to RFC 5424. Since release v1.6.0.
STUMPLESS_MEMORY_ALLOCATION_FAILURE	A memory allocation or reallocation failed.
STUMPLESS_NETWORK_PROTOCOL_UNSUPPORTED	The given layer 3 protocol is not supported by this implementation.
STUMPLESS_PARAM_NOT_FOUND	No param with the specified characteristics was found. Since release v1.6.0.
STUMPLESS_SOCKET_BIND_FAILURE	Could not bind to a socket.
STUMPLESS_SOCKET_CONNECT_FAILURE	Could not connect to a socket.
STUMPLESS_SOCKET_FAILURE	Could not create a socket.
STUMPLESS_SOCKET_SEND_FAILURE	Could not send to a socket.
STUMPLESS_STREAM_WRITE_FAILURE	Could not write to a stream.
STUMPLESS_TARGET_INCOMPATIBLE	The requested operation is not valid on the given target type.
STUMPLESS_TARGET_UNSUPPORTED	The target type provided is unsupported by this implementation.
STUMPLESS_TRANSPORT_PROTOCOL_UNSUPPORTED	The given layer 4 protocol is not supported by this implementation.
STUMPLESS_WINDOWS_EVENT_LOG_CLOSE_FAILURE	Could not close the Windows Event Log.
STUMPLESS_WINDOWS_EVENT_LOG_OPEN_FAILURE	Could not open the Windows Event Log.
STUMPLESS_INVALID_ENCODING	A provided encoding does not conform to the standard.
STUMPLESS_GETHOSTNAME_FAILURE	The current hostname could not be retrieved.
STUMPLESS_FUNCTION_TARGET_FAILURE	A call to a function target's log function failed. * * Since release v2.1.0
STUMPLESS_JOURNALD_FAILURE	A call to a systemd journald function failed. * * Since release v2.1.0
STUMPLESS_WINDOWS_FAILURE	A general failure of a Windows API call. Details on what call failed and * why are provided in the error details. * * Since release v2.1.0

Function Documentation

stumpless_get_error()

const struct stumpless_error* stumpless_get_error

(

void

)

Retrieves the error encountered by the last library call.

The returned error struct is only valid until the next call to a stumpless function. After this, it should not be referred to, and if the error of any subsequent call is needed another call to stumpless_get_error must be made.

Note that the id is the only field of the error that is guaranteed to be set. Other members may or may not be set, depending on the context of the error.

If the code_type is NULL, then the code is not valid and should be ignored.

This function does not clear or update the per-thread error code for stumpless, as it is involved in the error handling process itself.

Thread Safety: MT-Safe This function is thread safe. No synchronization primitives are used as the returned pointer is specific to the thread of execution. As a result, the result should not be shared between threads.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers. If you do so, note that if it is called before a stumpless library function in the handler itself the result will not be meaningful.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be asynchronously cancelled.

Returns

A stumpless_error struct describing the error encountered by the last function call. If no error was encountered, this will be NULL.

stumpless_get_error_id()

enum stumpless_error_id stumpless_get_error_id

(

const struct stumpless_error *

err

)

Gets the error id of the given error.

Thread Safety: MT-Safe race:err This function is thread safe, as long as err is not modifed by other threads during this call.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be asynchronously cancelled.

Since

Release v1.5.0

Parameters

err	The error to get the id from. This must not be NULL.

Returns

The error id of the given error.

stumpless_get_error_id_string()

const char* stumpless_get_error_id_string

(

enum stumpless_error_id

id

)

Gets the error string of the given error id.

This is a string literal that should not be modified or freed by the caller.

Thread Safety: MT-Safe This function is thread safe.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be asynchronously cancelled.

Since

Release v1.6.0

Parameters

id	The error id to get the error string from.

Returns

The error string of the given error id.

stumpless_get_error_stream()

FILE* stumpless_get_error_stream

(

void

)

Gets the current stream that errors are written to.

Thread Safety: MT-Safe This function is thread safe. Atomic variables are used to store and retrieve the error stream.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be ansynchronously cancelled.

Returns

The current stream errors are written to.

stumpless_has_error()

bool stumpless_has_error

(

void

)

True if the last call to a stumpless function encountered an error.

To get the error itself, use the stumpless_get_error function.

Thread Safety: MT-Safe This function is thread safe. No synchronization primitives are used as the returned flag is specific to the thread of execution.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers. If you do so, note that if it is called before a stumpless library function in the handler itself the result will not be meaningful.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be asynchronously cancelled.

Since

release v1.6.0.

Returns

True if the last stumpless call had an error, false if not.

stumpless_perror()

void stumpless_perror

(

const char *

prefix

)

Prints information about the current error to the error stream.

A prefix can be added to the information if desired. If one is provided then it will be followed by a colon character and a space, followed by the error information. If it is not provided then the colon and space characters will not be printed.

The message will end with a newline.

If there is not currently an active error message, then nothing will be printed (not even the prefix).

Thread Safety: MT-Safe race:prefix This function is thread safe, of course assuming that prefix is not changed by other threads during execution. A lock is used to coordinate accesses to the error stream.

Async Signal Safety: AS-Unsafe lock This function is not safe to call from signal handlers, as it uses a non-reentrant lock to synchronize access to the error stream.

Async Cancel Safety: AC-Unsafe lock This function is not safe to call from threads that may be asynchronously cancelled, as the lock used to control access to the error stream may not be released after a cancellation.

Parameters

prefix

An optional prefix to print in front of the message. If this is NULL then it will simply be ignored.

stumpless_set_error_stream()

void stumpless_set_error_stream

(

FILE *

stream

)

Sets the stream to write errors to.

This will be stderr by default, but can be set to any stream. If it is set to NULL then error messages will not be printed (essentially skipping all stumpless_perror calls).

Thread Safety: MT-Safe This function is thread safe. Atomic variables are used to store and retrieve the error stream.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be ansynchronously cancelled.

Parameters

stream

The stream to write errors to. If this is NULL then the messages intended for the error stream will be ignored.