discover(1)discover(1)NAMEdiscover - Memory Error Discovery Tool
SYNOPSISdiscover
[-?] [-h] [-a] [-b browser] [-c [ - | lib | file]] [-D dir] [-e
num] [-E num] [-f] [-F [parent|child]] [-H html_file] [-i] [-k]
[-K] [-l] [-m] [-n] [-N lib] [-o file] [-s] [-S num] [-T] [-v]
[-V] [-w txt_file] target
DESCRIPTION
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 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)
To use Discover, the input binary must be compiled
using compiler version Sun Studio 12 Update 1, Oracle Solaris Studio
12.2, or higher, or GCC for Solaris Systems 4.2.0 or higher, on a
machine with Solaris 10 update 6 or higher (or Oracle Solaris 11
Express). On older OSes try -xbinopt=prepare flag (SPARC platforms
only). Using the -g option allows Discover to produce more informative
messages.
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 (CGB) corrupted array guard block
ERROR (OLP) overlapping source and destination
WARNING (AZS) allocating zero size memory block
WARNING (NAR) non-annotated read
WARNING (NAW) non-annotated write
WARNING (SMR) speculative memory read
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:
-Print help message.
-a Write error data to binary_name.analyze/dynamic directory for
use by the Code Analyzer.
-b browser
Start web browser browserautomatically while running the instru‐
mented program (off by default).
-c [- | lib | file]
Check for errors in all libraries, or in lib, or in the
libraries listed (separated by new lines) in file. The default
is to not check for errors in libraries.
-D dir 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).
-F [parent | child]
Determines what happens if a binary you have instrumented with
Discover forks while you are running it. By default, Discover
continues to collect memory access error data from the parent
process. If you want Discover to follow the fork and collect
memory access data from the child process, specify -F child.
-H html_file
Output analysis to HTML file. If html_file is a relative path‐
name, it is placed relative to the working directory where the
instrumented binary is run. If the file name contains %p, it
will be replaced with the process id. See -w for more details.
-i Instrument for data race detection. See Oracle 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 limited. The input binary
does not have to be specially prepared.
-m Show mangled names in the report (hidden by default).
-n Do not check for errors in executables. The default is to check
for errors in executables.
-N lib Ignore lib.
-o file
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 txt_file
Write Discover analysis to text file (use "-" to specify
stderr). If txt_file is a relative pathname, it is placed rela‐
tive to the working directory where the instrumented binary is
run. Discover users can make the file name unique for processes
by asking the discover runtime 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 will generate a file
report.<process_id>.txt. If there are multiple %p macros in the
file name, only the first one will be replaced.
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
SUNW_DISCOVER_OPTIONS
The runtime behavior of instrumented binary can be changed by
setting this environment variable to a list of discover flags
(-a, -b, -e, -E, -f, -F, -H, -l, -L, -m, -S, -w). For instance,
if the user wants to change the number of errors reported to 50
and limit the stack depth in the report to 3, setting SUNW_DIS‐
COVER_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 "-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 uninitialized
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)
REQUIREMENTS
Operating System Requirements
The Discover software works on Solaris versions 10 update 6 or
higher and Oracle Solaris 11 Express.
Compiler Requirements
Discover software works only with binaries compiled with Sun
Studio 12 Update 1 compiler, Oracle Solaris Studio 12.2, or
higher, or GCC for Solaris Systems (GCCFSS) compiler starting
with version 4.2.0. 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 when build‐
ing the binary is strongly recommended. If you do not use the
-g option, Discover does not display source code and line number
information when reporting errors and warnings. Instead it just
displays program counters(PCs) of the corresponding machine
level instructions, which might not be as helpful. Also, using
the -g option helps the Discover software produce more accurate
results.
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, pro‐
vides 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 vari‐
ables. Whenever a set command is seen, the previous value of the vari‐
able (if any) is discarded. An append command causes its argument to be
appended (after a colon separator) to the existing value of the vari‐
able. A remove command causes 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 functions or function prefixes
to ignore when computing the percentage of nonannotated code in a
binary.
For more information, see the header in the system .rc file.
SEE ALSObit(1), CC(1), cc(1), f77(1), f90(1), f95(1), gcc(1)code-analyzer(1).
September 2011 discover(1)
