NAME

fo_init - initializes libfo to work.

SYNOPSIS

#include "fo.h"

void fo_init(void)

DESCRIPTION

libfo(7) initializes internal structures so function wrappers can work properly. It's crucial that this function is called as early as possible, best to call it first thing after main(). It's because fo_init(3) looks for original functions and stores their pointers in internal structure, so if you have overridden write() and you would call write() before caling fo_init(3) your program will most probably segfault.

fo_init(3) can be called multiple times, just note that all internal structures will be set back to initial state, so if you have installed some point of failure with fo_fail(3) and then call fo_init(3) your point of failure will reset and function will not return error.

AUTOMATIC CALL

When running unit tests, you can easily call fo_init(3) and fo_fail(3) functions but it is difficult if not impossible to do it when running functional tests. These are usually run by bash or python interpreters and test already compiled binary where there are no libfo calls to trigger failure. For that purpose you can compile libfo with -init linker option to call fo_init(3) right after library is loaded (you can think of it as main() for libs). Check libfo(7) to learn how to build library with -init flag. fo_init(3) can also load configuration of failing points from file when LIBFO_INIT_FILE environment variable is set.

Init is simple csv file in format, where leading spaces are ignored.

    function-name, countdown, ret, errno

One function per line. errno is string not int so you should use EINVAL and not 22. Single line is basically same as calling fo_fail(3) and so same rules apply here. So csv file:

    fread, 1, 0,    EINVAL
    fopen, 2, NULL, EACCES

is same as calling

    fo_fail(fo_fread, 1, 0, EINVAL);
    fo_fail(fo_fopen, 2, FO_NULL, EACCES);

RETURN VALUE

Function does not return anything, but calls exit() when it fails to get pointer to original function with dlsym(). This is because, when dlsym() fails, pointer to original function will be set to NULL which will lead to segfauly anyway, so it's better to crash program in known place to quickly find where error originates. Function will also print to standard error reason why dlsym() failed.

EXAMPLE

    #include "fo.h"

    int main(void)
    {
        fo_init();

        /* run your test code */

        return 0;
    }