typedef void igraph_error_handler_t(const char *reason, const char *file,
                                    int line, igraph_error_t igraph_errno);

This is the type of the error handler functions.

Arguments: 

IGRAPH_FUNCATTR_NORETURN igraph_error_handler_t igraph_error_handler_abort;

The default error handler, prints an error message and aborts the program.

igraph_error_handler_t igraph_error_handler_ignore;

This error handler frees the temporarily allocated memory and returns with the error code.

igraph_error_handler_t igraph_error_handler_printignore;

Frees temporarily allocated memory, prints an error message to the standard error and returns with the error code.

typedef igraph_error_type_t igraph_error_t;

This type is used as the return type of igraph functions that return an error code. It is a type alias because igraph_error_t used to be an int, and was used slightly differenly than igraph_error_type_t.

typedef enum {
    IGRAPH_SUCCESS           = 0,
    IGRAPH_FAILURE           = 1,
    IGRAPH_ENOMEM            = 2,
    IGRAPH_PARSEERROR        = 3,
    IGRAPH_EINVAL            = 4,
    IGRAPH_EXISTS            = 5,
    IGRAPH_EINVEVECTOR       = 6,
    IGRAPH_EINVVID           = 7,
    IGRAPH_NONSQUARE         = 8,
    IGRAPH_EINVMODE          = 9,
    IGRAPH_EFILE             = 10,
    IGRAPH_UNIMPLEMENTED     = 12,
    IGRAPH_INTERRUPTED       = 13,
    IGRAPH_DIVERGED          = 14,
    IGRAPH_ARPACK_PROD       = 15,   /* unused, reserved */
    IGRAPH_ARPACK_NPOS       = 16,
    IGRAPH_ARPACK_NEVNPOS    = 17,
    IGRAPH_ARPACK_NCVSMALL   = 18,
    IGRAPH_ARPACK_NONPOSI    = 19,
    IGRAPH_ARPACK_WHICHINV   = 20,
    IGRAPH_ARPACK_BMATINV    = 21,
    IGRAPH_ARPACK_WORKLSMALL = 22,
    IGRAPH_ARPACK_TRIDERR    = 23,
    IGRAPH_ARPACK_ZEROSTART  = 24,
    IGRAPH_ARPACK_MODEINV    = 25,
    IGRAPH_ARPACK_MODEBMAT   = 26,
    IGRAPH_ARPACK_ISHIFT     = 27,
    IGRAPH_ARPACK_NEVBE      = 28,
    IGRAPH_ARPACK_NOFACT     = 29,
    IGRAPH_ARPACK_FAILED     = 30,
    IGRAPH_ARPACK_HOWMNY     = 31,
    IGRAPH_ARPACK_HOWMNYS    = 32,
    IGRAPH_ARPACK_EVDIFF     = 33,
    IGRAPH_ARPACK_SHUR       = 34,
    IGRAPH_ARPACK_LAPACK     = 35,
    IGRAPH_ARPACK_UNKNOWN    = 36,
    IGRAPH_ENEGLOOP          = 37,
    IGRAPH_EINTERNAL         = 38,
    IGRAPH_ARPACK_MAXIT      = 39,
    IGRAPH_ARPACK_NOSHIFT    = 40,
    IGRAPH_ARPACK_REORDER    = 41,
    IGRAPH_EDIVZERO          = 42,
    IGRAPH_GLP_EBOUND        = 43,
    IGRAPH_GLP_EROOT         = 44,
    IGRAPH_GLP_ENOPFS        = 45,
    IGRAPH_GLP_ENODFS        = 46,
    IGRAPH_GLP_EFAIL         = 47,
    IGRAPH_GLP_EMIPGAP       = 48,
    IGRAPH_GLP_ETMLIM        = 49,
    IGRAPH_GLP_ESTOP         = 50,
    IGRAPH_EATTRIBUTES       = 51,
    IGRAPH_EATTRCOMBINE      = 52,
    IGRAPH_ELAPACK           = 53,
    IGRAPH_EDRL IGRAPH_DEPRECATED_ENUMVAL = 54,
    IGRAPH_EOVERFLOW         = 55,
    IGRAPH_EGLP              = 56,
    IGRAPH_CPUTIME           = 57,
    IGRAPH_EUNDERFLOW        = 58,
    IGRAPH_ERWSTUCK          = 59,
    IGRAPH_STOP              = 60,
    IGRAPH_ERANGE            = 61,
    IGRAPH_ENOSOL            = 62
} igraph_error_type_t;

These are the possible values returned by igraph functions. Note that these are interesting only if you defined an error handler with igraph_set_error_handler(). Otherwise the program is aborted and the function causing the error never returns.

Values: 

const char *igraph_strerror(const igraph_error_t igraph_errno);

This is a simple utility function, it gives a short general textual description for an igraph error code.

Arguments: 

Returns: 

typedef void igraph_warning_handler_t(const char *reason,
                                      const char *file, int line);

Currently it is defined to have the same type as igraph_error_handler_t, although the last (error code) argument is not used.

igraph_warning_handler_t *igraph_set_warning_handler(igraph_warning_handler_t *new_handler);

Install the supplied warning handler function.

Arguments: 

Returns: 

#define IGRAPH_WARNING(reason)

This is the usual way of triggering a warning from an igraph function. It calls igraph_warning().

Arguments: 

#define IGRAPH_WARNINGF(reason, ...)

igraph functions can use this macro when they notice a warning and want to pass on extra information to the user about what went wrong. It calls igraph_warningf() with the proper parameters and no error code.

Arguments: 

void igraph_warning(const char *reason, const char *file, int line);

Call this function if you want to trigger a warning from within a function that uses igraph.

Arguments: 

Returns: 

void igraph_warningf(const char *reason, const char *file, int line, ...);

This function is similar to igraph_warning(), but uses a printf-like syntax. It substitutes the additional arguments into the reason template string and calls igraph_warning().

Arguments: 

void igraph_warning_handler_ignore(const char *reason, const char *file, int line);

This warning handler function simply ignores all warnings.

Arguments: 

void igraph_warning_handler_print(const char *reason, const char *file, int line);

This warning handler function simply prints all warnings to the standard error.

Arguments: 

The contents of the rest of this chapter might be useful only for those who want to create an interface to igraph from another language, or use igraph from a GUI application. Most readers can safely skip to the next chapter.

You can write and install error handlers simply by defining a function of type igraph_error_handler_t and calling igraph_set_error_handler(). This feature is useful for interface writers, as igraph will have the chance to signal errors the appropriate way. For example, the R interface uses R's native printing facilities to communicate errors, while the Python interface converts them into Python exceptions.

The two main tasks of the error handler are to report the error (i.e. print the error message) and ensure proper resource cleanup. This is ensured by calling IGRAPH_FINALLY_FREE(), which deallocates some of the temporary memory to avoid memory leaks. Note that this may invalidate the error message buffer reason passed to the error handler. Do not access it after having called IGRAPH_FINALLY_FREE().

As of igraph 0.10, temporary memory is dellocated in stages, through multiple calls to the error handler (and indirectly to IGRAPH_FINALLY_FREE()). Therefore, error handlers that do not abort the program immediately are expected to return. The error handler should not perform a longjmp, as this may lead to some of the memory not getting freed.

igraph_error_handler_t *igraph_set_error_handler(igraph_error_handler_t *new_handler);

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.

#define IGRAPH_ERROR(reason, igraph_errno)

#define IGRAPH_ERRORF(reason, igraph_errno, ...)

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

igraph_error_t igraph_errorf(const char *reason, const char *file, int line,
                             igraph_error_t igraph_errno, ...);

#define IGRAPH_CHECK(expr)

 IGRAPH_CHECK(vector_push_back(&v, 100)); 

#define IGRAPH_CHECK_CALLBACK(expr, code)

If a function runs into an error (and the program is not aborted) the error handler should deallocate all temporary memory. This is done by storing the address and the destroy function of all temporary objects in a stack. The IGRAPH_FINALLY function declares an object as temporary by placing its address in the stack. If an igraph function returns with success it calls IGRAPH_FINALLY_CLEAN() with the number of objects to remove from the stack. If an error happens however, the error handler should call IGRAPH_FINALLY_FREE() to deallocate each object added to the stack. This means that the temporary objects allocated in the calling function (and etc.) will be freed as well.

#define IGRAPH_FINALLY(func, ptr)

void IGRAPH_FINALLY_CLEAN(int num);

igraph_vector_t vector;
igraph_vector_init(&vector, 10);
IGRAPH_FINALLY(igraph_vector_destroy, &vector);
// use vector
igraph_vector_destroy(&vector);
IGRAPH_FINALLY_CLEAN(1);

void IGRAPH_FINALLY_FREE(void);

There are some simple rules to keep in order to have functions behaving well in erroneous situations. First, check the arguments of the functions and call IGRAPH_ERROR() if they are invalid. Second, call IGRAPH_FINALLY on each dynamically allocated object and call IGRAPH_FINALLY_CLEAN() with the proper argument before returning. Third, use IGRAPH_CHECK on all igraph function calls which can generate errors.

The size of the stack used for this bookkeeping is fixed, and small. If you want to allocate several objects, write a destroy function which can deallocate all of these. See the adjlist.c file in the igraph source for an example.

For some functions these mechanisms are simply not flexible enough. These functions should define their own error handlers and restore the error handler before they return.

#include <igraph.h>

/* Create the condensation of a directed graph.
 * See https://en.wikipedia.org/wiki/Strongly_connected_component#Definitions
 * This example demonstrates how to write a basic igraph function, complete
 * with error handling. */
igraph_error_t condensation(const igraph_t *graph, igraph_t *cond) {
    igraph_vector_int_t membership;

    /* Data structures such as vector must be initialized in igraph before use. */
    IGRAPH_CHECK(igraph_vector_int_init(&membership, 0));

    /* Adding the initialized vector to the "finally" stack ensures that it will
     * be automatically destroyed if an error occurs. */
    IGRAPH_FINALLY(igraph_vector_int_destroy, &membership);

    /* Functions that return an error code can be wrapped in IGRAPH_CHECK to pass that error
     * up to the caller. */
    IGRAPH_CHECK(igraph_connected_components(graph, &membership, /* csize */ NULL, /* no */ NULL, IGRAPH_STRONG));

    /* To compute the condensation, we simply contract strongly connected components.
     * Since igraph_contract_vertices() modifies graphs in-place, we make a copy first. */
    IGRAPH_CHECK(igraph_copy(cond, graph));

    /* Since we are not done creating the condensation yet, we add 'cond' to the
     * "finally" stack, so that it will be destroyed if an error occurs. */
    IGRAPH_FINALLY(igraph_destroy, cond);

    /* Contract strongly connected components. */
    IGRAPH_CHECK(igraph_contract_vertices(cond, &membership, NULL));

    /* igraph_contract_vertices() preserves all edges, some of which become
     * parallel edges or self-loops after the contraction. We simplify these. */
    IGRAPH_CHECK(igraph_simplify(cond, /* remove_multiple */ true, /* remove_loops */ true, NULL));

    /* Data structures that are no longer needed must be explicitly destroyed.
     * If they were added to the "finally" stack, they must be removed explicitly,
     * in the opposite order to how they were added. IGRAPH_FINALLY_CLEAN removes
     * the indicated number of entries from the "finally" stack. We remove
     * 'membership' because it was destroyed, and 'cond' because the responsibility
     * to destroy it is now with the caller. */
    igraph_vector_int_destroy(&membership);
    IGRAPH_FINALLY_CLEAN(2);

    return IGRAPH_SUCCESS; /* return with no error */
}

int main(void) {
    igraph_t graph, cond;

    /* Create a random directed graph with mean degree 2 and compute its condensation. */
    igraph_erdos_renyi_game_gnm(&graph, 100, 200, IGRAPH_DIRECTED, IGRAPH_NO_LOOPS);
    condensation(&graph, &cond);

    printf("Number of vertices in the condensation: %" IGRAPH_PRId "\n", igraph_vcount(&cond));
    igraph_write_graph_edgelist(&cond, stdout);

    /* Destroy data structures that are no longer needed. */
    igraph_destroy(&graph);
    igraph_destroy(&cond);

    return 0;
}

In some rare situations, igraph may encounter an internal error that cannot be fully handled. In this case, it will call the current fatal error handler. The default fatal error handler simply prints the error and aborts the program.

Fatal error handlers do not return. Typically, they might abort the the program immediately, or in the case of the high-level igraph interfaces, they might return to the top level using a longjmp(). The fatal error handler is only called when a serious error has occurred, and as a result igraph may be in an inconsistent state. The purpose of returning to the top level is to give the user a chance to save their work instead of aborting immediately. However, the program session should be restarted as soon as possible.

Most projects that use igraph will use the default fatal error handler.

typedef void igraph_fatal_handler_t(const char *reason, const char *file, int line);

igraph_fatal_handler_t *igraph_set_fatal_handler(igraph_fatal_handler_t *new_handler);

IGRAPH_FUNCATTR_NORETURN igraph_fatal_handler_t igraph_fatal_handler_abort;

#define IGRAPH_FATAL(reason)

#define IGRAPH_FATALF(reason, ...)

#define IGRAPH_ASSERT(condition)

void igraph_fatal(const char *reason, const char *file, int line);

void igraph_fatalf(const char *reason, const char *file, int line, ...);

It is likely that the igraph error handling method is not thread-safe, mainly because of the static global stack which is used to store the address of the temporarily allocated objects. This issue might be addressed in a later version of igraph.