bofc manual pages




libfo is a tiny library that allows user to simulate errors of POSIX, libc and any other functions you will add.  


libfo is a library designed to override any function (including those from POSIX and libc) to create rquested point of failures. Library does not required to make any changes in production code, everything is done from test suite. Library is designed in a way, that you generate code once and integrate it directly into your project. Yes, you can build shared object and install it somewhere in PATH, but then you won't be able to run tests on machines which does not provide libfo or that instance of libfo does not have overridden function you might need. It's not worth it.  


First (and optionally) you might want to create file with all functions you might want to create point of failure for. Functions should be separated by newline like this

    $ cat flist

Next you need to generate fo.c and fo.h that will be incuded in your project. Check fogen(1) program for details on how to generate those files.

Copy generated files fo.c and fo.h somewhere to your testing directory and configure your build system to create shared object from fo.c. This step is important, library needs to be built separately and as shared object for everything to work. could be compiled with:

    $ gcc -fPIC -c fo.c -o fo.o
    $ gcc -shared -fPIC -Wl,-soname, -o fo.o -lc

Or if you want to run functional tests run from shell or python, and have no way of adding fo_fail(3) calls you might want to compile library with linked `-init' option:

    $ gcc -fPIC -c fo.c -o fo.o
    $ gcc -shared -fPIC -Wl,-soname, \
        -Wl,-init,fo_init -o fo.o -lc

and LIBFO_INIT_FILE envvar set to initialize and set failing points from file. Refer to fo_init(3) for more information how to do it.

Install some point of failures with fo_fail(3) and write some test code with it.

When you run your test program, remember to run it with (path may vary) like

    $ LD_PRELOAD=./ test-program

so all functions are overridden by libfo.

You might want to take a look at "tst" directory in libfo sources, test case is super small and easy (there really isn't much to test) to understand how to run tests with libfo.  


fogen(1), fo_init(3), fo_fail(3).

7 November 2019 (v0.2.1)