Error handling

Almost all API calls can fail, for instance because an invalid handle is supplied. Since C does not support any kind of exceptions, such failures are reported through the return value. Which value is used to indicate an error depends on the return type; refer to the data type section for more information. However, this value only indicates something went wrong, not what went wrong. The following function can be used for that.

dqcs_error_get()

Returns a pointer to the latest error message.

const char *dqcs_error_get(void)

Call this to get extra information when another function returns a failure code. The returned pointer is temporary and therefore should NOT be free()d. It will become invalid when a new error occurs.

The mechanism for reporting errors to DQCsim from within a callback is the same, but reversed: you first set the error string yourself, and then return the value that indicates that an error occurred. You can set the error as follows.

dqcs_error_set()

Sets the latest error message string.

void dqcs_error_set(const char *msg)

This must be called by callback functions when an error occurs within the callback, otherwise the upstream result for dqcs_error_get() will be undefined.

If msg is set to NULL, the error string is cleared instead.