Changeset 1557 for zzuf/trunk/doc/zzuf.1Tweet

Timestamp:

Jan 4, 2007, 2:28:35 PM (14 years ago)

Author:

Sam Hocevar

Message:

• Improved manpage, especially the statistical effect of using -R.

File:

• zzuf/trunk/doc/zzuf.1 (modified) (12 diffs)

zzuf/trunk/doc/zzuf.1

@@ -9 +9 @@
               [\fB\-P\fR \fIlist\fR] [\fB\-R\fR \fIlist\fR]
 .br
-              [\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fICOMMAND\fR [\fIARGS\fR]...
+              [\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fIPROGRAM\fR [\fIARGS\fR]...
 .br
 \fBzzuf \-h\fR | \fB\-\-help\fR
@@ -23 +23 @@
 \fBZzuf\fR will run an application specified on its command line, one or
 several times, with optional arguments, and will report the application's
-behaviour on the standard output.
-.PP
-If you want to specify arguments for your application, put a \fB\-\-\fR
-marker before them on the command line, or \fBzzuf\fR will try to interpret
-them as arguments for itself.
+relevant behaviour on the standard output, eg:
+.PP
+.RS
+.nf
+\fBzzuf cat /dev/zero\fR
+.fi
+.RE
+.PP
+If you want to specify flags for your application, put a '\fB\-\-\fR'
+marker before them on the command line (otherwise \fBzzuf\fR will try to
+interpret them as arguments for itself), eg:
+.PP
+.RS
+.nf
+\fBzzuf \-B 1000 cat \-\- \-v /dev/zero\fR
+.fi
+.RE
 .SH OPTIONS
 .TP
@@ -77 +89 @@
 .RS
 .TP
+\fB\\0\fR
+null byte
+.TP
 \fB\\n\fR
 new line
@@ -86 +101 @@
 tabulation
 .TP
-\fB\\0\fR
-the null character
-.TP
 \fB\\x\fR\fINN\fR
 the byte whose hexadecimal value is \fINN\fR
@@ -97 +109 @@
 .IP
 You can use '\fB-\fR' to specify ranges. For instance, to protect all bytes
-from '\fB\\x01\fR' to ' ', use \fB\-P \(dq\\x01- \(dq\fR.
+from '\fB\\x01\fR' to ' ', use '\fB\-P \(dq\\x01- \(dq\fR'.
+
+The statistical outcome of this option should not be overlooked. Because
+\fBzzuf\fR cannot know the nature of the input data beforehands and must
+fuzz it even if only one byte of data was received, protecting characters
+may change the meaning of the \fB\-r\fR flag depending on the data being
+fuzzed. For instance, asking to fuzz 1% of input bits and to protect
+lowercase characters (using '\fB\-r 0.01 \-P a-z\fR') will result in an
+actual average fuzzing ratio of 0.9% with truly random data, 0.3% with
+random ASCII data and 0.2% with a normal English text.
 
 See also the \fB\-R\fR flag.
@@ -107 +128 @@
 .TP
 \fB\-r\fR, \fB\-\-ratio\fR=\fIratio\fR
-Specify the amount of bits that will be randomly fuzzed. A value of 0
+Specify the proportion of bits that will be randomly fuzzed. A value of 0
 will not fuzz anything. A value of 0.05 will fuzz 5% of the open files'
 bits. A value of 1.0 or more will fuzz all the bytes, theoretically making
@@ -160 +181 @@
 .RS
 .nf
-\fB# zzuf cat /etc/motd\fR
+\fBzzuf cat /etc/motd\fR
 .fi
 .RE
@@ -168 +189 @@
 .RS
 .nf
-\fB# zzuf -s 94324 -r 0.01 cat /etc/motd\fR
+\fBzzuf -s 94324 -r 0.01 cat /etc/motd\fR
 .fi
 .RE
@@ -177 +198 @@
 .RS
 .nf
-\fB# zzuf -P \(dq\\n\(dq -R \(dq\\0-\\x1f\\x7f-\\xff\(dq cat /etc/motd\fR
+\fBzzuf -P \(dq\\n\(dq -R \(dq\\0-\\x1f\\x7f-\\xff\(dq cat /etc/motd\fR
 .fi
 .RE
@@ -188 +209 @@
 .RS
 .nf
-\fB# zzuf -E \(dq\\.xml$\(dq convert -- foo.jpeg -format tga /dev/null\fR
+\fBzzuf -E \(dq\\.xml$\(dq convert -- foo.jpeg -format tga /dev/null\fR
 .fi
 .RE
@@ -199 +220 @@
 .RS
 .nf
-\fB# zzuf -c -s 87423 -r 0.01 vlc movie.avi\fR
-\fB# zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR
-\fB# vlc fuzzy-movie.avi\fR
+\fBzzuf -c -s 87423 -r 0.01 vlc movie.avi\fR
+\fBzzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR
+\fBvlc fuzzy-movie.avi\fR
 .fi
 .RE
@@ -213 +234 @@
 .RS
 .nf
-\fB# zzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 \\\fR
-\fB    mplayer movie.avi -- -benchmark -vo null -fps 1000\fR
+\fBzzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 \\\fR
+\fB  mplayer -- -benchmark -vo null -fps 1000 movie.avi\fR
 .fi
 .RE
 .SH BUGS
 .PP
-Only the most common file operations are implemented as of now: \fBopen\fR(),
+Due to \fBzzuf\fR using shared object preloading (\fBLD_PRELOAD\fR on most
+Unix systems, \fBDYLD_INSERT_LIBRARIES\fR on Mac OS X) to run its child
+processes, it will fail in the presence of any mechanism that disables
+preloading. For instance setuid root binaries will not be fuzzed when run
+as an unprivileged user. This limitation will probably not be addressed.
+.PP
+Network fuzzing is not implemented. This feature will be added.
+.PP
+It is not yet possible to insert or drop bytes from the input, to fuzz
+according to the file format, or to do all these complicated operations. These
+features are planned.
+.PP
+Only the most common file operations are implemented: \fBopen\fR(),
 \fBread\fR(), \fBfopen\fR(), \fBfseek\fR(), etc. One important unimplemented
-function is \fBfscanf\fR().
-.PP
-Network fuzzing is not implemented. It is not yet possible to insert or
-drop bytes from the input, to fuzz according to the file format, or to do
-all these complicated operations. They are planned, though.
-.PP
-Due to \fBzzuf\fR using \fBLD_PRELOAD\fR to run its child processes, it will
-fail in the presence of any mechanism that disables preloading. For instance
-setuid root binaries will not be fuzzed when run as an unprivileged user.
+function is \fBfscanf\fR(). These features will be implemented based on user
+request.
 .PP
 As of now, \fBzzuf\fR does not really support multithreaded applications. The
-behaviour with multithreaded applications where more than one thread do file
-descriptor operations is undefined.
+behaviour with multithreaded applications where more than one thread does file
+descriptor operations is undefined. This bug will be fixed.
+.PP
+Though best efforts are made, the reproducibility of \fBzzuf\fR's behaviour
+is guaranteed for subsequent calls with the same arguments but not for calls
+with different \fBzzuf\fR versions.
 .SH AUTHOR
 .PP