- Generated by
1.11.0
|
stumpless 2.2.0
|
Error codes and functions for detecting and assessing them. More...
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. | |
Enumerations | |
| enum | stumpless_error_id { STUMPLESS_GENERATE_ENUM =(STUMPLESS_ADDRESS_FAILURE, 0) STUMPLESS_GENERATE_ENUM(STUMPLESS_ARGUMENT_EMPTY, 1) STUMPLESS_GENERATE_ENUM(STUMPLESS_ARGUMENT_TOO_BIG, 2) STUMPLESS_GENERATE_ENUM(STUMPLESS_DUPLICATE_ELEMENT, 3) STUMPLESS_GENERATE_ENUM(STUMPLESS_ELEMENT_NOT_FOUND, 4) STUMPLESS_GENERATE_ENUM(STUMPLESS_FILE_OPEN_FAILURE, 5) STUMPLESS_GENERATE_ENUM(STUMPLESS_FILE_WRITE_FAILURE, 6) STUMPLESS_GENERATE_ENUM(STUMPLESS_INDEX_OUT_OF_BOUNDS, 7) STUMPLESS_GENERATE_ENUM(STUMPLESS_INVALID_FACILITY, 8) STUMPLESS_GENERATE_ENUM(STUMPLESS_INVALID_ID, 9) STUMPLESS_GENERATE_ENUM(STUMPLESS_INVALID_SEVERITY, 10) STUMPLESS_GENERATE_ENUM(STUMPLESS_MEMORY_ALLOCATION_FAILURE, 11) STUMPLESS_GENERATE_ENUM(STUMPLESS_NETWORK_PROTOCOL_UNSUPPORTED, 12) STUMPLESS_GENERATE_ENUM(STUMPLESS_PARAM_NOT_FOUND, 13) STUMPLESS_GENERATE_ENUM(STUMPLESS_SOCKET_BIND_FAILURE, 14) STUMPLESS_GENERATE_ENUM(STUMPLESS_SOCKET_CONNECT_FAILURE, 15) STUMPLESS_GENERATE_ENUM(STUMPLESS_SOCKET_FAILURE, 16) STUMPLESS_GENERATE_ENUM(STUMPLESS_SOCKET_SEND_FAILURE, 17) STUMPLESS_GENERATE_ENUM(STUMPLESS_STREAM_WRITE_FAILURE, 18) STUMPLESS_GENERATE_ENUM(STUMPLESS_TARGET_INCOMPATIBLE, 19) STUMPLESS_GENERATE_ENUM(STUMPLESS_TARGET_UNSUPPORTED, 20) STUMPLESS_GENERATE_ENUM(STUMPLESS_TRANSPORT_PROTOCOL_UNSUPPORTED, 21) STUMPLESS_GENERATE_ENUM(STUMPLESS_WINDOWS_EVENT_LOG_CLOSE_FAILURE, 22) STUMPLESS_GENERATE_ENUM(STUMPLESS_WINDOWS_EVENT_LOG_OPEN_FAILURE, 23) STUMPLESS_GENERATE_ENUM(STUMPLESS_INVALID_ENCODING, 24) STUMPLESS_GENERATE_ENUM(STUMPLESS_GETHOSTNAME_FAILURE, 25 ) STUMPLESS_GENERATE_ENUM(STUMPLESS_FUNCTION_TARGET_FAILURE, 26 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_JOURNALD_FAILURE, 27 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_WINDOWS_FAILURE, 28 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_INVALID_PARAM_STRING, 29 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_SQLITE3_BUSY, 30 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_SQLITE3_CALLBACK_FAILURE, 31 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_SQLITE3_FAILURE, 32 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_NETWORK_CLOSED, 33 ) } |
| An (enum) identifier of the types of errors that might be encountered. More... | |
Functions | |
| STUMPLESS_PUBLIC_FUNCTION const struct stumpless_error * | stumpless_get_error (void) |
| Retrieves the error encountered by the last library call. | |
| STUMPLESS_PUBLIC_FUNCTION enum stumpless_error_id | stumpless_get_error_id (const struct stumpless_error *err) |
| Gets the error id of the given error. | |
| STUMPLESS_PUBLIC_FUNCTION const char * | stumpless_get_error_id_string (enum stumpless_error_id id) |
| Gets the error string of the given error id. | |
| STUMPLESS_PUBLIC_FUNCTION FILE * | stumpless_get_error_stream (void) |
| Gets the current stream that errors are written to. | |
| STUMPLESS_PUBLIC_FUNCTION bool | stumpless_has_error (void) |
| True if the last call to a stumpless function encountered an error. | |
| STUMPLESS_PUBLIC_FUNCTION void | stumpless_perror (const char *prefix) |
| Prints information about the current error to the error stream. | |
| STUMPLESS_PUBLIC_FUNCTION void | stumpless_set_error_stream (FILE *stream) |
| Sets the stream to write errors to. | |
Error codes and functions for detecting and assessing them.
| #define STUMPLESS_FOREACH_ERROR | ( | ERROR | ) |
A macro to implement error id enum and error string array.
| 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.
See STUMPLESS_FOREACH_ERROR() and STUMPLESS_GENERATE_ENUM() for how this enumeration is generated.
| Enumerator | |
|---|---|
| STUMPLESS_GENERATE_ENUM | A provided network address was not valid. This might be formatting problem, or it might mean that a DNS lookup failed. |
| STUMPLESS_PUBLIC_FUNCTION 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.
| STUMPLESS_PUBLIC_FUNCTION 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.
| err | The error to get the id from. This must not be NULL. |
| STUMPLESS_PUBLIC_FUNCTION 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.
| id | The error id to get the error string from. |
| STUMPLESS_PUBLIC_FUNCTION 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.
| STUMPLESS_PUBLIC_FUNCTION 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.
| STUMPLESS_PUBLIC_FUNCTION 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.
| prefix | An optional prefix to print in front of the message. If this is NULL then it will simply be ignored. |
| STUMPLESS_PUBLIC_FUNCTION 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.
| stream | The stream to write errors to. If this is NULL then the messages intended for the error stream will be ignored. |
1.11.0