4.2. Error handling internals

4.2.1. IGRAPH_ERROR — Trigger an error.
4.2.2. igraph_error — Trigger an error.
4.2.3. IGRAPH_CHECK — Check the return value of a function call.

If an error happens, the functions in the library call the IGRAPH_ERROR macro with a textual description of the error and an igraph error code. This macro calls (through the igraph_error() function) the installed error handler. Another useful macro is IGRAPH_CHECK(), this checks the return value of its argument which is normally a function call, and calls IGRAPH_ERROR if it is not IGRAPH_SUCCESS.

4.2.1. `IGRAPH_ERROR` — Trigger an error.

#define IGRAPH_ERROR(reason,igraph_errno)

igraph functions usually use this macro when they notice an error. It calls igraph_error() with the proper parameters and if that returns the macro returns the "calling" function as well, with the error code. If for some (suspicious) reason you want to call the error handler without returning from the current function, call igraph_error() directly.

Arguments:

`reason`:	Textual description of the error. This should be something more explaning than the text associated with the error code. Eg. if the error code is `IGRAPH_EINVAL`, its asssociated text (see `igraph_strerror()`) is "Invalid value" and this string should explain which parameter was invalid and maybe why.
`igraph_errno`:	The igraph error code.

4.2.2. `igraph_error` — Trigger an error.

int igraph_error(const char *reason, const char *file, int line,
		 int igraph_errno);

igraph functions usually call this fuction (most often via the IGRAPH_ERROR macro) if they notice an error. It calls the currently installed error handler function with the supplied arguments.

Arguments:

`reason`:	Textual description of the error.
`file`:	The source file in which the error was noticed.
`line`:	The number of line in the source file which triggered the error.
`igraph_errno`:	The igraph error code.

Returns:

the error code (if it returns)

4.2.3. `IGRAPH_CHECK` — Check the return value of a function call.

#define IGRAPH_CHECK(a)

Arguments:

a:

An expression, usually a function call.

Executes the expression and checks its value. If this is not IGRAPH_SUCCESS, it calls IGRAPH_ERROR with the value as the error code. Here is an example usage:

 IGRAPH_CHECK(vector_push_back(&v, 100));

There is only one reason to use this macro when writing igraph functions. If the user installs an error handler which returns to the auxilary calling code (like igraph_error_handler_ignore and igraph_error_handler_printignore), and the igraph function signalling the error is called from another igraph function then we need to make sure that the error is propagated back to the auxilary (ie. non-igraph) calling function. This is achieved by using IGRAPH_CHECK on every igraph call which can return an error code.