= 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 ==

Memory handling functions are diverted in [source:/zzuf/trunk/src/lib-mem.c].

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.

== Signal functions ==

Memory handling functions are diverted in [source:/zzuf/trunk/src/lib-signal.c].

These functions need to be diverted to prevent the fuzzed application from intercepting fatal signals such as '''`SIGSEGV`'''.

== File and socket functions ==

File descriptor handling functions are diverted in [source:/zzuf/trunk/src/lib-fd.c] and [source:/zzuf/trunk/src/lib-stream.c].

The most important part of zzuf is the way file descriptor functions are diverted. It keeps track of all open file descriptors, decides whether to fuzz their data, and makes diverted reading functions behave accordingly.

=== Standard file descriptor functions ===

=== `FILE *` functions ===