Error handling

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:

• PROCTAL_ERROR_OUT_OF_MEMORY

• PROCTAL_ERROR_PERMISSION_DENIED

• PROCTAL_ERROR_WRITE_FAILURE

• PROCTAL_ERROR_READ_FAILURE

• PROCTAL_ERROR_UNKNOWN

• PROCTAL_ERROR_UNIMPLEMENTED

• PROCTAL_ERROR_UNSUPPORTED

• PROCTAL_ERROR_UNSUPPORTED_WATCH_READ

• PROCTAL_ERROR_UNSUPPORTED_WATCH_READ_EXECUTE

• PROCTAL_ERROR_UNSUPPORTED_WATCH_WRITE_EXECUTE

• PROCTAL_ERROR_UNSUPPORTED_WATCH_READ_WRITE_EXECUTE

• PROCTAL_ERROR_PROGRAM_NOT_FOUND

• PROCTAL_ERROR_PROGRAM_NOT_SET

• PROCTAL_ERROR_INJECTION_LOCATION_NOT_FOUND

• PROCTAL_ERROR_PROGRAM_SEGFAULT

• PROCTAL_ERROR_PROGRAM_EXITED

• PROCTAL_ERROR_PROGRAM_STOPPED

• PROCTAL_ERROR_PROGRAM_UNTAMEABLE

• PROCTAL_ERROR_PROGRAM_TRAPPED

• PROCTAL_ERROR_INTERRUPT

• PROCTAL_ERROR_PROGRAM_INTERRUPT

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.