Fallible - README

Fallible

Fault injection library for stress-testing failure scenarios.

Fallible is a helper library for fault injection. It is useful to stress-test scenarios that are unlikely to happen on routine tests, such as malloc or fopen returning NULL. Combined with Valgrind it asserts that your code is doing the proper clean-up in cases of failure.

Fallible depends on Valgrind.

Usage

// leaky.c
#include <string.h>

#ifdef ENABLE_FAULT_INJECTION
#include <fallible/alloc.h>
#endif

int main() {
    char *aaa = malloc(100);
    if (!aaa) {
        return 1;
    }
    strcpy(aaa, "a safe use of strcpy");

    char *bbb = malloc(100);
    if (!bbb) {
        // free(aaa);
        return 1;
    }
    strcpy(bbb, "not unsafe, but aaa is leaking");

    free(bbb);
    free(aaa);
    return 0;
}

Compile with -DENABLE_FAULT_INJECTION and run fallible-check.1:

$ c99 -DENABLE_FAULT_INJECTION -o leaky leaky.c -lfallible
$ fallible-check ./leaky
Valgrind failed when we did not expect it to:
(...suppressed output...)
# exit status is 1

Installation

Get the latest tarball and install it:

wget https://git.euandreh.xyz/fallible/snapshot/fallible-main.tar.gz
pax -rzvf fallible-main.tar.gz # or similarly: tar xvf fallible-main.tar.gz
cd fallible-main
make
[sudo] make install

The requirements are a C99 compiler on a POSIX.1-2008 environment (_POSIX_C_SOURCE 200809L) and Valgrind.

Documentation

Documentation is available via installed man pages, also available online:

  1. core:
  1. helpers:

Contributing

Extra tools used for development are:

For running the extra development-only checks, run:

$ make dev-check

and for generating the documentation HTML and website, run:

$ make public

Links

Releases