= Zzuf tutorial =

'''WARNING''': this tutorial requires `zzuf` version 0.11 or later.

== Basics ==

Let’s start with a simple command that reads data from a file. We choose `hd`, the hexadecimal dump command, and tell it to read 32 bytes from `/dev/zero`:

{{{
% hd -vn 32 /dev/zero
00000000  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020
%
}}}

Now let’s fuzz `hd`’s input using `zzuf`. It’s completely straightforward: just prepend `zzuf` to the commandline.

{{{
% zzuf hd -vn 32 /dev/zero
00000000  00 00 02 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 02 00 00  00 00 00 00 00 00 00 00  |................|
00000020
%
}}}

We see that two `00` values have been changed to `02`s. `zzuf` '''intercepted''' `hd`'s opening of `/dev/zero` and automatically '''corrupted''' the bytes it read at random. Let’s do it again:

{{{
% zzuf hd -vn 32 /dev/zero
00000000  00 00 02 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 02 00 00  00 00 00 00 00 00 00 00  |................|
00000020
%
}}}

We get exactly the same output. This is a very important property of `zzuf`: its behaviour is '''reproducible'''.

== Altering the fuzzing ratio ==

The '''fuzzing ratio''' is the proportion of bits that `zzuf` changes. It is specified with the '''`-r` flag'''. The default fuzzing ratio is 0.004, meaning "fuzz 0.4% of the bits". 32 bytes is 256 bits, and 0.4% of 256 bits is approximately 1. `zzuf` should have fuzzed 1 bit, but since it fuzzes bits at random, 2 bits is not surprising.

Let’s try fuzzing more bits, for instance 5% of the bits, using '''`-r` 0.05''':

{{{
% zzuf -r 0.05 hd -vn 32 /dev/zero
00000000  00 01 00 00 00 00 44 00  04 80 00 40 21 00 0a 20  |......D....@!.. |
00000010  40 20 00 04 00 00 02 00  00 00 00 00 00 00 00 00  |@ ..............|
00000020
%
}}}

We see that 15 bits have been changed. 5% of 256 bits is 12.8, so here again the behaviour is as expected.

Now let’s fuzz fewer bits, for instance 0.1%, using '''`-r` 0.001''':

{{{
% zzuf -r 0.001 hd -vn 32 /dev/zero
00000000  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020
%
}}}

No bits have been changed, because 0.1% of 256 is 0.256, so there were few chances that the bits would be changed at all.

Very high fuzzing ratios can be specified, for instance 50%, using '''`-r` 0.5''':

{{{
% zzuf -r 0.5 hd -vn 32 /dev/zero  
00000000  c0 a0 20 b0 ad 40 07 c2  8a 14 30 1b 83 21 1a 69  |.. ..@....0..!.i|
00000010  11 28 05 07 30 00 70 01  43 08 62 c8 6d 45 e4 1a  |.(..0.p.C.b.mE..|
00000020
%
}}}