source: zzuf/trunk/doc/libzzuf.3.in @ 4236

Last change on this file since 4236 was 4236, checked in by sam, 5 years ago

Generate manual pages, so we can put the version number in them.

File size: 5.8 KB
Line 
1.TH libzzuf 3 "2010-01-06" "libzzuf @PACKAGE_VERSION@"
2.SH NAME
3libzzuf \- helper library for the zzuf multiple purpose fuzzer
4.SH DESCRIPTION
5.PP
6\fBlibzzuf\fR is a helper library automatically preloaded by \fBzzuf\fR when
7fuzzing applications, but it can also be used alone for debugging purposes or
8specific cases that cannot be covered by \fBzzuf\fR.
9.SH USAGE
10.PP
11\fBlibzzuf\fR must be preloaded using the operating system's default way of
12preloading libraries. For instance, on a typical Linux installation:
13.PP
14\fB    LD_PRELOAD=/usr/lib/zzuf/libzzuf.so\fR
15.SH ENVIRONMENT VARIABLES
16.PP
17\fBlibzzuf\fR's initial setup is done through environment variables. After
18they are read, no further information can be sent to the fuzzed process.
19
20All environment variables are optional.
21.TP
22\fBZZUF_DEBUG\fR
23This environment variable is set to the debugging level. 0 means no debugging
24information is sent to \fBzzuf\fR. 1 logs important information as well as
25all diverted functions. 2 logs fuzzing status and all optional file stream
26information.
27.TP
28\fBZZUF_DEBUGFD\fR
29This environment variable is set to a file descriptor where \fBlibzzuf\fR will
30send debugging information. This is used to send data to the main \fBzzuf\fR
31controlling binary.
32.TP
33\fBZZUF_SEED\fR
34This variable is set to the initial random seed. Corresponding \fBzzuf\fR flag:
35\fB\-\-seed\fR.
36.TP
37\fBZZUF_MINRATIO\fR, \fBZZUF_MAXRATIO\fR
38These variables are set to the minimal and maximal fuzzing ratios.
39Corresponding \fBzzuf\fR flag: \fB\-\-ratio\fR.
40.TP
41\fBZZUF_AUTOINC\fR
42If this variable is set, the random seed is incremented each time a new
43file is opened. Corresponding \fBzzuf\fR flag: \fB\-\-autoinc\fR.
44.TP
45\fBZZUF_BYTES\fR
46This variable contains byte ranges to which fuzzing should be restricted.
47Corresponding \fBzzuf\fR flag: \fB\-\-bytes\fR.
48.TP
49\fBZZUF_LIST\fR
50This variable contains file descriptor ranges to which fuzzing should be
51restricted. Corresponding \fBzzuf\fR flag: \fB\-\-list\fR.
52.TP
53\fBZZUF_NETWORK\fR
54If this variable is set, network mode is activated. Corresponding \fBzzuf\fR
55flag: \fB\-\-network\fR.
56.TP
57\fBZZUF_PORTS\fR
58This variable contains port ranges to which fuzzing should be restricted.
59Corresponding \fBzzuf\fR flag: \fB\-\-port\fR.
60.TP
61\fBZZUF_PROTECT\fR, \fBZZUF_REFUSE\fR
62These variables contain character ranges to protect or refuse. Corresponding
63\fBzzuf\fR flags: \fB\-\-protect\fR, \fB\-\-refuse\fR.
64.TP
65\fBZZUF_INCLUDE\fR, \fBZZUF_EXCLUDE\fR
66These variables contain regular expressions to indicate which files should be
67included or excluded from the list of fuzzed files. Corresponding \fBzzuf\fR
68flags: \fB\-\-include\fR, \fB\-\-exclude\fR.
69.TP
70\fBZZUF_SIGNAL\fR
71If this variable is set, the fuzzed process will be prevented from installing
72signal handlers that usually cause coredumps. Corresponding \fBzzuf\fR flag:
73\fB\-\-signal\fR.
74.TP
75\fBZZUF_MEMORY\fR
76This variable contains the maximum amount of memory that the fuzzed process
77is allowed to allocate. Corresponding \fBzzuf\fR flag: \fB\-\-max-memory\fR.
78.TP
79\fBZZUF_STDIN\fR
80If this variable is set, standard input will be fuzzed, too. Corresponding
81\fBzzuf\fR flag: \fB\-\-stdin\fR.
82.SH NOTES
83In order to intercept file and network operations, signal handlers and memory
84allocations, \fBlibzzuf\fR diverts and reimplements the following functions,
85which can sometimes be private C library symbols, too:
86.TP
87Unix file descriptor handling:
88\fBopen\fR(), \fBdup\fR(), \fBdup2\fR(), \fBlseek\fR(), \fBread\fR(),
89\fBreadv\fR(), \fBpread\fR(), \fBaccept\fR(), \fBsocket\fR(), \fBrecv\fR(),
90\fBrecvfrom\fR(), \fBrecvmsg\fR(), \fBaio_read\fR(), \fBaio_return\fR(),
91\fBclose\fR()
92.TP
93Standard IO streams:
94\fBfopen\fR(), \fBfreopen\fR(), \fBfseek\fR(), \fBfseeko\fR(), \fBrewind\fR(),
95\fBfread\fR(), \fBgetc\fR(), \fBgetchar\fR(), \fBfgetc\fR(), \fBfgets\fR(),
96\fBungetc\fR(), \fBfclose\fR()
97.TP
98Memory management:
99\fBmmap\fR(), \fBmunmap\fR(), \fBmalloc\fR(), \fBcalloc\fR(), \fBvalloc\fR(),
100\fBfree\fR(), \fBmemalign\fR(), \fBposix_memalign\fR()
101.TP
102Required on Linux:
103\fBopen64\fR(), \fBlseek64\fR(), \fBmmap64\fR(), \fB_IO_getc\fR(),
104\fBgetline\fR(), \fBgetdelim\fR(), \fB__getdelim\fR(), \fBgetc_unlocked\fR(),
105\fBgetchar_unlocked\fR(), \fBfgetc_unlocked\fR(), \fBfgets_unlocked\fR(),
106\fBfread_unlocked\fR(), \fB__uflow\fR()
107.TP
108Required on BSD systems:
109\fBfgetln\fR(), \fB__srefill\fR(), \fB__srget\fR()
110.TP
111Required on Mac OS X:
112\fBmap_fd\fR()
113.TP
114Required on HP-UX:
115\fB__open64\fR(), \fB__lseek64\fR(), \fB__filbuf\fR()
116.TP
117Required on OpenSolaris:
118\fBfreopen64\fR(), \fBfseeko64\fR(), \fBfsetpos64\fR()
119.TP
120Signal handling:
121\fBsignal\fR(), \fBsigaction\fR()
122.PP
123If an application manipulates file descriptors (reading data, seeking around)
124using functions that are not in that list, \fBlibzzuf\fR will not fuzz its
125input consistently and the results should not be trusted. You can use a tool
126such as \fBltrace(1)\fR on Linux to know the missing functions.
127.PP
128On BSD systems, such as FreeBSD or Mac OS X, \fB__srefill\fR() is enough to
129monitor all standard IO streams functions. On other systems, such as Linux,
130each function is reimplemented on a case by case basis. One important
131unimplemented function is \fBfscanf\fR(), because of its complexity. Missing
132functions will be added upon user request.
133.SH SEE ALSO
134.PP
135\fBzzuf(1)\fR, \fBld.so(8)\fR
136.SH AUTHOR
137.PP
138Copyright \(co 2002, 2007\-2010 Sam Hocevar <sam@hocevar.net>.
139.PP
140\fBlibzzuf\fR and this manual page are free software. They come without any
141warranty, to the extent permitted by applicable law. You can redistribute
142them and/or modify them under the terms of the Do What The Fuck You Want
143To Public License, Version 2, as published by Sam Hocevar. See
144\fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details.
145.PP
146\fBzzuf\fR's webpage can be found at \fBhttp://caca.zoy.org/wiki/zzuf\fR.
147An overview of the architecture and inner works is at
148\fBhttp://caca.zoy.org/wiki/zzuf/internals\fR.
Note: See TracBrowser for help on using the repository browser.