= zzuf internals =

This document is an attempt at explaining how zzuf works and how it can be extended to support more functions.

== Architecture overview ==

The zzuf software consists in two parts:
 * The `zzuf` executable
 * The `libzzuf` shared library

Here is the global workflow when zzuf fuzzes a process:
 * `zzuf` reads options from the command line.
 * `zzuf` writes fuzzing information to the environment
 * `zuff` preloads `libzzuf` into the called process and executes it
 * `libzzuf` reads fuzzing information from the envronment
 * `libzzuf` diverts standard function calls with its own ones
 * the called process runs normally, but any diverted call goes through `libzzuf` first

== Writing function diversions ==

Diverted functions are declared using the '''`NEW`''' macro. The address of the original function is stored into a global function pointer using the '''`ORIG`''' macro. The '''`LOADSYM`''' macro takes care of retrieving its address and storing it into the pointer.

For instance, this is how the '''`memalign`''' function is declared in its libc header, `malloc.h`:

{{{
#!c
void *memalign(size_t boundary, size_t size);
}}}

And here is how '''`memalign`''' is diverted:

{{{
#!c
#include <malloc.h>

#include "libzzuf.h"
#include "lib-load.h"

/* ... */

#if defined HAVE_MEMALIGN
static void * (*ORIG(memalign)) (size_t boundary, size_t size);
#endif

/* ... */

#if defined HAVE_MEMALIGN
void *NEW(memalign)(size_t boundary, size_t size)
{
    void *ret;
    LOADSYM(memalign);
    ret = ORIG(memalign)(boundary, size);
    /* ... */
    return ret;
}
#endif
}}}

== Memory functions ==

Functions such as '''`malloc`''' need to be diverted by zzuf in order to monitor global memory usage and detect severe memory leaks.

This creates a bootstrapping problem on some platforms: the diverted '''`calloc`''' calls the real '''`calloc`''', which needs to be loaded using '''`dlsym`'''. On Linux, '''`dlsym`''' calls '''`calloc`''', resulting in an infinite loop. To avoid this, we declare a private static buffer that memory allocation functions can use if the original function is not yet loaded.

=== Standard file descriptor functions ===

=== `FILE *` functions ===