Error processing functions¶
#include <frontg8/error.h>
Typedefs
-
typedef
fg8_error_t
¶ The opaque error pointer type.
This type carries generic error information. The library uses this type throughout the whole codebase to communicate error conditions back to the your code. There is no way to construct objects of this type except indirectly by forcefully causing a function to reach an error condition. See fg8_error_message and fg8_error_destroy for information on how to make use of this type.
- Author
- Felix Morgner
- Since
- 0.1.0
Functions
-
char const*
fg8_error_message
(fg8_error_t const error)¶ Retrieve the error message contained in an fg8_error_t object.
Being an opaque type, it is not possible to directly read the content of the error object. You can use this function to extract the error message contained in an fg8_error_t object. Calling this function on a
NULL
object will return aNULL
pointer. The string (char const *
) returned by the function is a standardNULL
terminated C string. The memory of the string is owned by the error object.- Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
#include <frontg8/error.h> #include <stdio.h> // other includes ... int main() { fg8_error_t error; // Do something that might produce an error ... if(error) { printf("ERROR: %s", fg8_error_message(error)); } // Do the rest ... }
- Return
- A pointer to the message contained in the error or
NULL
if there was no error. The memory of the message is managed by the error object and the user code MUST NEVER callfree()
or equivalent on it. - Author
- Felix Morgner
- Since
- 0.1.0
- Parameters
error
-The error object whose message should be retrieved. Might be
NULL
.
-
void
fg8_error_destroy
(fg8_error_t const error)¶ Destroy an error object.
A lot of the libraries functions take a pointer to fg8_error_t (see fg8_protocol_message_encrypted_create for an example) in order to be able to communicate error conditions back to the calling code. As long as you reuse the same error object, you don’t need to worry about memory management, the library will take care of that for you. There are some situations, where YOU need to take care of the error object. For example, if you do not want to reuse the same error object or at the end of the relevant scope, you must use fg8_error_destroy to cleanly destroy the error object and release its memory. Note that you MUST NEVER call
free()
or equivalent on an error object.- Example
1 2 3 4 5 6 7 8 9 10 11 12
#include <frontg8/error.h> #include <stdio.h> // other includes ... int main() { fg8_error_t error; // Do something that stores an error in error ... fg8_error_destroy(error); }
- Author
- Felix Morgner
- Since
- 0.1.0
- Warning
Calling destroy multiple times on the same error object will result in undefined behaviour
All pointers to the message formerly contained in the error object may point to invalid memory after destruction.
- Parameters
error
-The error object to be destroyed