When an error occurs, the handle will keep track of a code that can
identify the cause. In this state the handle should not be used by any
other function that the ones described here.
The code can be retrieved by calling the proctal_error function. It takes a handle as argument and returns a code.
int error_code = proctal_error(proctal);
When 0 is returned then it means that there is no error.
Each error code has a corresponding macro definition:
Call the proctal_error_recover function to recover from an error. It takes a handle as argument and returns 1 on success and 0 on failure.
int result = proctal_error_recover(proctal);
On success, the error code is cleared for the given handle, making it
usable like normal again.
On failure, the handle is deemed unusable and must be destroyed.
You can also retrieve a description of the error in text by calling the proctal_error_message function. It takes a handle as argument and returns a pointer to a read-only C-style string.
const char *error_message = proctal_error_message(proctal);
If there is no error it returns a NULL pointer.
The error message is only meant for diagnostic purposes, such as logging and debugging. Don't actually show it to the user. Write messages that make sense in the context of your program.