NAME
discover - Sun Memory Error Discovery Tool
SYNOPSIS
discover
[-?] [-h] [-b browser] [-D directory] [-e n] [-E n]
[-f] [-H html_file] [-i datarace] [-k] [-K] [-l] [-m]
[-N lib] [-o file] [-s] [-S n] [-T] [-v] [-V]
[-w text_file] target
DESCRIPTION
The Sun Memory Error Discovery Tool (Discover) is a tool
used by software developers to detect programming errors
related to the allocation and use of program memory at run-
time.
Examples of errors detected by Discover include:
* Accessing uninitialized memory
* Reading from and writing to unallocated memory
* Accessing memory beyond allocated array bounds
* Using freed memory
* Freeing the wrong memory blocks
* Memory leaks
Here is a simple example of preparing, instrumenting, and
running an executable:
% cc -g -O2 test.c -o test.prep
% discover -w - -o test.disc test.prep
% ./test.disc
ERROR (UMR): accessing uninitialized data from address 0x5000c (4 bytes) at:
foo() + 0xdc <ui.c:6>
3: int *t;
4: foo() {
5: t = malloc(5*sizeof(int));
6:=> printf("%d0, t[1]);
7: }
8:
9: main()
main() + 0x1c
_start() + 0x108
block at 0x50008 (20 bytes long) was allocated at:
malloc() + 0x260
foo() + 0x24 <ui.c:5>
2:
3: int *t;
4: foo() {
5:=> t = malloc(5*sizeof(int));
6: printf("%d0, t[1]);
7: }
8:
main() + 0x1c
_start() + 0x108
***************** Discover Memory Report *****************
1 block at 1 location left allocated on heap with a total size of 20 bytes
1 block with total size of 20 bytes
malloc() + 0x260
foo() + 0x24 <ui.c:5>
2:
3: int *t;
4: foo() {
5:=> t = malloc(5*sizeof(int));
6: printf("%d0, t[1]);
7: }
8:
main() + 0x1c
_start() + 0x108
DISCOVER SUMMARY:
unique errors : 1 (1 total, 0 filtered)
unique warnings : 0 (0 total, 0 filtered)
REQUIREMENTS
Operating System Requirements
Discover works on Solaris 10 5/08 or later Solaris 10
updates.
Compiler Requirements
Discover works only with binaries compiled with the Sun
Studio 12 Update 1 compilers, Oracle Solaris Studio
Express 6/10 compilers, Oracle Solaris Studio 12.2 com-
pilers, or GCC for Sun Systems (GCCFSS) compilers
starting with version 4.2.0. To use Discover, the input
binary must be compiled and linked with optimizations
(-O or -xO[n] for Studio compilers and -O[n] for GCCFSS
compilers). When the binary is compiled with these
optimizations, additional information is added to help
Discover correctly instrument the binary. On older
operating systems, try the -xbinopt=prepare option
(SPARC platforms only). If you try to run Discover on
a binary that is not compiled as stated above, Discover
issues an error and does not instrument the binary.
Using the -g option while compiling the binary allows
Discover to produce more informative messages. If the
-g option is not used, Discover does not display source
code and line number information while reporting errors
and warnings. Instead it just displays program
counters (PCs) of the corresponding machine level
instructions, which may not be as helpful. Also, using
the -g option helps Discover produce more accurate
reports.
MESSAGES
Discover might produce the following error messages:
ERROR (UAR) reading from unallocated memory
ERROR (UAW) writing to unallocated memory
ERROR (FMR) reading from freed memory
ERROR (FMW) writing to freed memory
ERROR (UMR) accessing uninitialized data
ERROR (PIR) accessing partially initialized data
ERROR (ABR) reading memory beyond array bounds
ERROR (ABW) writing to memory beyond array bounds
ERROR (DFM) double freeing memory
ERROR (BFM) freeing wrong memory block
ERROR (BRP) bad address parameter for realloc
ERROR (SBR) read is beyond current stack bounds
ERROR (SBW) write is beyond current stack bounds
ERROR (IMR) read from invalid memory address
ERROR (IMW) write to invalid memory address
ERROR (FRP) freed pointer passed to realloc
ERROR (CGB) corrupted array guard block
Discover might produce the following warning messages:
WARNING (AZS) allocating zero size memory block
WARNING (NAR) non-annotated read
WANRING (NAW) non-annotated write
WARNING (SMR) speculative memory read
WARNING (SMW) speculative memory write
WARNING (UFR) unknown stack frame read
WARNING (UFW) unknown stack frame write
WARNING (USR) unknown status while reading
WARNING (USW) unknown status while writing
OPTIONS
The following options are supported:
-? or -h
Print help message.
-b browser
Start web browser browser automatically while running
the instrumented program (off by default).
-D directory
Use the specified cache directory. The default is
$HOME/SUNW_Bit_Cache.
-e n Show only n memory errors in the report (default is
show all errors).
-E n Show only n memory leaks in the report (default is 100)
-f Show offsets in the report (hidden by default).
-H html_file
Write analysis to specified HTML file. If html_file is
a relative pathname, it is placed relative to the work-
ing directory where the instrumented binary is run. If
%p is contained in the file name, it is replaced with
the process id. See -w for more details.
-i Instrument for data race detection. See the Oracle
Solaris Studio Thread Analyzer documentation.
-k Force reinstrumentation.
-K Do not read the bit.rc initialization files.
-l Run Discover in light mode. Provides faster program
execution, but the number of detected errors is lim-
ited. The input binary does not have to be specially
prepared.
-m Show mangled names in the report (hidden by default).
-N lib
Ignore lib.
-o file
Use specified instrumented output filename.
-s OK if dependent libraries are not instrumentable.
-S n Show only n stack frames in the report (default is 8).
-T Do not instrument libraries at run time.
-v Verbose.
-V Print version and exit without any further processing.
-w text_file
Write Discover analysis to text file (use "-" to
specify stderr). If text_file is a relative pathname,
it is placed relative to the working directory where
the instrumented binary is run. You can make the file
name unique for processes by asking the discover run-
time to add the process id to the name of the file.
This can be done by adding a %p string to the file
name. For instance, -w report.%p.txt flag generates a
file report.<process_id>.txt. If there are multiple %p
macros in the file name, only the first one is
replaced.
Discover can generate either a text report, using the -w
txtfile option, or an HTML report, using the -H html_file
option, or both, if both options are used.
If neither option is used, the default output is an HTML
file, outfile.html, where outfile is the basename of the
instrumented output file. The file is placed in the working
directory where the instrumented binary is run.
EXIT STATUS
The following exit values are returned:
0 All input files were output successfully.
1 An error occurred.
ENVIRONMENT VARIABLES
SUNW_DISCOVER_OPTIONS
The runtime behavior of instrumented binary can be
changed by setting this environment variable to a list
of discover flags (-b, -e, -E, -f, -H, -l, -L, -m, -S,
-w). For instance, if you want to change the number of
errors reported to 50 and limit the stack depth in the
report to 3, setting SUNW_DISCOVER_OPTIONS should be
set to "-E 50 -S 3".
EXAMPLES
EXAMPLE #1
By default Discover sends output to an HTML file.
% cat dtest_2.c
#include <stdio.h>
#include <stdlib.h>
int main(int argc, char *argv[])
{
char *cp;
cp = (char *)malloc(10);
cp[11] = 't';
return 0;
}
% cc -g -O1 -o dtest_2.prep dtest_2.c
% discover -o dtest_2.disc dtest_2.prep
% ./dtest_2.disc
% ls
dtest_2.c
dtest_2.prep*
dtest_2.disc*
dtest_2.disc.html
Notice that Discover did not print messages but generated an
HTML file that provides a summary and an easy-to-use click-
for-details interface.
EXAMPLE #2
We use the same program as in example #1, but specify the -w
- option to output report in text format to stderr.
% discover -w - -o dtest_2.disc dtest_2.prep
% ./dtest_2.disc
ERROR (ABW): writing to memory beyond array bounds at address 0x50013 (1 byte) at:
main() + 0x138 <dtest_2.c:7>
4: {
5: char *cp;
6: cp = (char *)malloc(10);
7:=> cp[11] = 't';
8: return 0;
9: }
_start() + 0x108
block at 0x50008 (10 bytes long) was allocated at:
malloc() + 0x260
main() + 0x94 <dtest_2.c:6>
3: int main(int argc, char *argv[])
4: {
5: char *cp;
6:=> cp = (char *)malloc(10);
7: cp[11] = 't';
8: return 0;
9: }
_start() + 0x108
***************** Discover Memory Report *****************
1 block at 1 location left allocated on heap with a total size of 10 bytes
1 block with total size of 10 bytes
malloc() + 0x260
main() + 0x94 <dtest_2.c:6>
3: int main(int argc, char *argv[])
4: {
5: char *cp;
6:=> cp = (char *)malloc(10);
7: cp[11] = 't';
8: return 0;
9: }
_start() + 0x108
DISCOVER SUMMARY:
unique errors : 1 (1 total, 0 filtered)
unique warnings : 0 (0 total, 0 filtered)
EXAMPLE #3
This example examines a program that contains a use of unin-
itialized data:
% cat dtest_3.c
#include <stdio.h>
#include <stdlib.h>
int main(int argc, char *argv[])
{
char s[10];
printf("s[1] = %d\n",s[1]);
return 0;
}
% cc -g -O1 -o dtest_3.prep dtest_3.c
% ./dtest_3.prep
s[1] = 5
% discover -w - -o dtest_3.disc dtest_3.prep
% ./dtest_3.disc
ERROR (UMR): accessing uninitialized data from address 0xffbff023 (1 byte) at:
main() + 0x4c [dtest_3.disc:0x3004c]
<dtest_3.c:7>:
4: int main(int argc, char *argv[])
5: {
6: char s[10];
7:=> printf("s[1] = %d\n",s[1]);
8: return 0;
9: }
10:
_start() + 0x108 [dtest_3.disc:0x107cc]
s[1] = 5
***************** Discover Memory Report *****************
No allocated memory left on program exit.
DISCOVER SUMMARY:
unique errors : 1 (1 total)
unique warnings : 0 (0 total)
FILES
DISCOVER AND BIT .rc FILES
Discover initializes its state by reading a series of .rc
files at startup. A system file,
<compiler_area>/prod/lib/postopt/bit.rc, provides default
values for certain variables. Discover reads this file
first, then $HOME/.bit.rc, if it exists, then `pwd`/.bit.rc,
if it exists.
The .rc files contain commands to set, append to, and remove
from variables. Whenever a set command is seen, the previous
value of the variable (if any) is discarded. An append
command will cause its argument to be appended (after a
colon separator) to the existing value of the variable. A
remove command will cause its argument to be removed (along
with a colon separator) from the existing value of the vari-
able.
The variables set in the .rc files include the list of
libraries to ignore while instrumenting, and lists of func-
tions or function prefixes to ignore when computing the per-
centage of nonannotated code in a binary.
For more information, see the header in the system .rc file.
SEE ALSO
bit(1), CC(1), cc(1), f77(1), f90(1), f95(1), gcc(1).