User Commands discover(1)
NAME
discover - Sun Memory Error Discovery Tool
SYNOPSIS
discover
[-?] [-h] [-k] [-o file] [-s] [-v] [-w txt_file]
[-D dir] [-H html_file] [-K] [-N lib] [-T] [-V] target
DESCRIPTION
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 runtime.
Examples of errors detected by Discover include:
* Accessing uninitialized memory.
* Reads from and writes to unallocated memory.
* Accessing memory beyond allocated array bounds.
* Use of freed memory.
* Freeing wrong memory blocks.
* Memory leaks.
Here is a simple example of preparing, instrumenting, and
running an executable:
% cc -g -O2 -xbinopt=prepare test.c -o test.prep
% discover -w - -o test.disc test.prep
% ./test.disc
ERROR (UAW): writing to unallocated memory at address 0x50014 (4 bytes) at:
main() + 0x58 [test.disc:0x30058]
<test.c:5>:
2: int main()
3: {
4: int *p = (int*) malloc(sizeof(int));
5:=> *(p+1) = 1;
6: return 0;
7: }
_start() + 0x108 [test.disc:0x107b4]
***************** Discover Memory Report *****************
1 block at 1 location left allocated on heap with a total size of 4 bytes
<...>
DISCOVER SUMMARY:
unique errors : 1 (1 total)
unique warnings : 0 (0 total)
The compiler options "-xbinopt=prepare" and "-O1" or greater
are required to prepare a binary for Discover. Also using
"-g" allows Discover to produce more informative messages.
Last change: February 2008 1
User Commands discover(1)
MESSAGES
Discover may 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 (AZS) allocating zero size memory block
OPTIONS
The following options are supported:
-? -h
Print help message.
-k Force reinstrumentation.
-o file
Instrumented output filename.
-s OK if dependent libraries are not instrumentable.
-v Verbose.
-w txt_file
Write Discover analysis to text file (use "-" to
specify stderr). If txt_file is a relative pathname,
it is placed relative to the working directory where
the instrumented binary is run.
-D dir
Cache Directory. The default is $HOME/SUNW_Bit_Cache.
-H html_file
Output analysis to HTML file. If html_file is a rela-
tive pathname, it is placed relative to the working
directory where the instrumented binary is run.
-K Do not read the bit.rc initialization files.
Last change: February 2008 2
User Commands discover(1)
-N lib
Ignore lib.
-T Do not instrument libraries at run time.
-V Print version.
USAGE
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
Discover supports a number of environment variables that
begin with the characters "SUNW_DISCOVER_". These environ-
ment variables must be set before the target program is run,
and they allow the user to control Discover behavior at run-
time. For example the name of the HTML report file can be
changed at runtime by setting environment variable
SUNW_DISCOVER_HTML to a new file name. Or the output to
stderr can be added by setting SUNW_DISCOVER_TEXT to "-".
The list of environment variables together with explanations
is provided below:
SUNW_DISCOVER_GUARD_SIZE
Integer value determines the size of array guard
blocks.
SUNW_DISCOVER_HTML
Sets the name of the Discover HTML report file.
SUNW_DISCOVER_LEAK_STACK_DEPTH
The number of function on top of the stack counted to
disambiguate memory leak locations. When set to 0 whole
stack is counted. Default value is 5.
SUNW_DISCOVER_MEMORY_LEAKS
If set to 1 will enable memory leak detection
Last change: February 2008 3
User Commands discover(1)
(default). When set to 0 value will disable memory
leak detection.
SUNW_DISCOVER_QUOTE_LINES
Sets the number of source lines included in the report.
Default value is 7.
SUNW_DISCOVER_STRONG_FREE
When set to 1 will allow application to reuse freed
memory (default). When set to 0 makes freed memory una-
vailable for the following allocation. Note that 0
value can significantly increase memory consumption of
the application.
SUNW_DISCOVER_TEXT
Sets the name of the Discover report file in text for-
mat. Default is not set. Setting to "-" will output
report to stderr.
SUNW_DISCOVER_WWW
If set to the name of the HTML browser program (e.g.
"mozilla"), it will force generation of the HTML report
and will launch the browser with the report. Default -
not set.
SUNW_BIT_CACHE_DIR
This environment variable, if set, specifies the root
directory for the cache where Discover stores instru-
mented shared libraries. Its setting overrides the
value specified by the -D cachedir flag, and the
default, which is $HOME/SUNW_Bit_Cache.
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 -xbinopt=prepare -o dtest_2.prep dtest_2.c
% discover -o dtest_2.disc dtest_2.prep
% ./dtest_2.disc
% ls
dtest_2.c
Last change: February 2008 4
User Commands discover(1)
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 "-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.disc:0x30138]
<dtest_2.c:8>:
5: {
6: char *cp;
7: cp = (char *)malloc(10);
8:=> cp[11] = 't';
9: return 0;
10: }
11:
_start() + 0x108 [dtest_2.disc:0x107cc]
block at 0x50008 (10 bytes long) was allocated at:
malloc() + 0x144 [libdiscover.so:0xe11c]
main() + 0x90 [dtest_2.disc:0x30090]
<dtest_2.c:7>:
4: int main(int argc, char *argv[])
5: {
6: char *cp;
7:=> cp = (char *)malloc(10);
8: cp[11] = 't';
9: return 0;
10: }
_start() + 0x108 [dtest_2.disc:0x107cc]
***************** Discover Memory Report *****************
1 block at 1 location left allocated on heap with a total size of 10 bytes
<...>
DISCOVER SUMMARY:
unique errors : 1 (1 total)
unique warnings : 0 (0 total)
EXAMPLE #3
This example examines a program that contains a use of unin-
itialized data:
Last change: February 2008 5
User Commands discover(1)
% 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 -xbinopt=prepare -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)
REQUIREMENTS
Operating System Requirements
The Discover software works only on Solaris versions 9
and 10. Correct results on newer versions of Solaris is
not guaranteed.
Patches
To run Discover-instrumented binaries on Solaris 9 sys-
tems earlier than S9U7, linker patch 112963-14 must be
installed.
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,
Last change: February 2008 6
User Commands discover(1)
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 com-
mand 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 variable.
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).
Last change: February 2008 7
Sign up or Log in to add a comment or watch this page.