source: zzuf/trunk/doc/libzzuf.3 @ 2552

Last change on this file since 2552 was 2552, checked in by Sam Hocevar, 12 years ago
  • Implement freopen64, fsetpos64 and fseeko64 for OpenSolaris?.
File size: 5.4 KB
Line 
1.TH libzzuf 3 "2008-06-10" "libzzuf"
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 a file descriptor where \fBlibzzuf\fR will
24send debugging information. This is used to send data to the main \fBzzuf\fR
25controlling binary.
26.TP
27\fBZZUF_SEED\fR
28This variable is set to the initial random seed. Corresponding \fBzzuf\fR flag:
29\fB\-\-seed\fR.
30.TP
31\fBZZUF_MINRATIO\fR, \fBZZUF_MAXRATIO\fR
32These variables are set to the minimal and maximal fuzzing ratios.
33Corresponding \fBzzuf\fR flag: \fB\-\-ratio\fR.
34.TP
35\fBZZUF_AUTOINC\fR
36If this variable is set, the random seed is incremented each time a new
37file is opened. Corresponding \fBzzuf\fR flag: \fB\-\-autoinc\fR.
38.TP
39\fBZZUF_BYTES\fR
40This variable contains byte ranges to which fuzzing should be restricted.
41Corresponding \fBzzuf\fR flag: \fB\-\-bytes\fR.
42.TP
43\fBZZUF_LIST\fR
44This variable contains file descriptor ranges to which fuzzing should be
45restricted. Corresponding \fBzzuf\fR flag: \fB\-\-list\fR.
46.TP
47\fBZZUF_NETWORK\fR
48If this variable is set, network mode is activated. Corresponding \fBzzuf\fR
49flag: \fB\-\-network\fR.
50.TP
51\fBZZUF_PORTS\fR
52This variable contains port ranges to which fuzzing should be restricted.
53Corresponding \fBzzuf\fR flag: \fB\-\-port\fR.
54.TP
55\fBZZUF_PROTECT\fR, \fBZZUF_REFUSE\fR
56These variables contain character ranges to protect or refuse. Corresponding
57\fBzzuf\fR flags: \fB\-\-protect\fR, \fB\-\-refuse\fR.
58.TP
59\fBZZUF_INCLUDE\fR, \fBZZUF_EXCLUDE\fR
60These variables contain regular expressions to indicate which files should be
61included or excluded from the list of fuzzed files. Corresponding \fBzzuf\fR
62flags: \fB\-\-include\fR, \fB\-\-exclude\fR.
63.TP
64\fBZZUF_SIGNAL\fR
65If this variable is set, the fuzzed process will be prevented from installing
66signal handlers that usually cause coredumps. Corresponding \fBzzuf\fR flag:
67\fB\-\-signal\fR.
68.TP
69\fBZZUF_MEMORY\fR
70This variable contains the maximum amount of memory that the fuzzed process
71is allowed to allocate. Corresponding \fBzzuf\fR flag: \fB\-\-max-memory\fR.
72.TP
73\fBZZUF_STDIN\fR
74If this variable is set, standard input will be fuzzed, too. Corresponding
75\fBzzuf\fR flag: \fB\-\-stdin\fR.
76.SH NOTES
77In order to intercept file and network operations, signal handlers and memory
78allocations, \fBlibzzuf\fR diverts and reimplements the following functions,
79which can sometimes be private C library symbols, too:
80.TP
81Unix file descriptor handling:
82\fBopen\fR(), \fBdup\fR(), \fBdup2\fR(), \fBlseek\fR(), \fBread\fR(),
83\fBreadv\fR(), \fBpread\fR(), \fBaccept\fR(), \fBsocket\fR(), \fBrecv\fR(),
84\fBrecvfrom\fR(), \fBrecvmsg\fR(), \fBaio_read\fR(), \fBaio_return\fR(),
85\fBclose\fR()
86.TP
87Standard IO streams:
88\fBfopen\fR(), \fBfreopen\fR(), \fBfseek\fR(), \fBfseeko\fR(), \fBrewind\fR(),
89\fBfread\fR(), \fBgetc\fR(), \fBgetchar\fR(), \fBfgetc\fR(), \fBfgets\fR(),
90\fBungetc\fR(), \fBfclose\fR()
91.TP
92Memory management:
93\fBmmap\fR(), \fBmunmap\fR(), \fBmalloc\fR(), \fBcalloc\fR(), \fBvalloc\fR(),
94\fBfree\fR(), \fBmemalign\fR(), \fBposix_memalign\fR()
95.TP
96Required on Linux:
97\fBopen64\fR(), \fBlseek64\fR(), \fBmmap64\fR(), \fB_IO_getc\fR(),
98\fBgetline\fR(), \fBgetdelim\fR(), \fB__getdelim\fR(), \fBgetc_unlocked\fR(),
99\fBgetchar_unlocked\fR(), \fBfgetc_unlocked\fR(), \fBfgets_unlocked\fR(),
100\fBfread_unlocked\fR()
101.TP
102Required on BSD systems:
103\fBfgetln\fR(), \fB__srefill\fR()
104.TP
105Required on Mac OS X:
106\fBmap_fd\fR()
107.TP
108Required on HP-UX:
109\fB__open64\fR(), \fB__lseek64\fR(), \fB__filbuf\fR()
110.TP
111Required on OpenSolaris:
112\fBfreopen64\fR(), \fBfseeko64\fR(), \fBfsetpos64\fR()
113.TP
114Signal handling:
115\fBsignal\fR(), \fBsigaction\fR()
116.PP
117If an application manipulates file descriptors (reading data, seeking around)
118using functions that are not in that list, \fBlibzzuf\fR will not fuzz its
119input consistently and the results should not be trusted. You can use a tool
120such as \fBltrace(1)\fR on Linux to know the missing functions.
121.PP
122On BSD systems, such as FreeBSD or Mac OS X, \fB__srefill\fR() is enough to
123monitor all standard IO streams functions. On other systems, such as Linux,
124each function is reimplemented on a case by case basis. One important
125unimplemented function is \fBfscanf\fR(), because of its complexity. Missing
126functions will be added upon user request.
127.SH SEE ALSO
128.PP
129\fBzzuf(1)\fR, \fBld.so(8)\fR
130.SH AUTHOR
131.PP
132Copyright \(co 2002, 2007\-2008 Sam Hocevar <sam@zoy.org>.
133.PP
134\fBlibzzuf\fR and this manual page are free software. They come without any
135warranty, to the extent permitted by applicable law. You can redistribute
136them and/or modify them under the terms of the Do What The Fuck You Want
137To Public License, Version 2, as published by Sam Hocevar. See
138\fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details.
139.PP
140\fBzzuf\fR's webpage can be found at \fBhttp://libcaca.zoy.org/wiki/zzuf\fR.
Note: See TracBrowser for help on using the repository browser.