discover
[-?] [-h] [-a] [-b browser]
[-c [- | lib [:scope...]| file] [-D dir] [-e num]
[-E num] [-f] [-F [parent|child|both]] [-H html_file]
[-i] [-k] [-K] [-l] [-m] [-n] [-N lib] [-o file]
[-s] [-S num] [-T] [-v] [-V] [-w txt_file] target[:scope]
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
The following 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 later updates, or GCC for Oracle Solaris Systems 4.2.0 or higher, on a machine with Oracle Solaris 10 update 6 or later updates (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. Discover is incompatible with binaries compiled with -xlinkopt.
Discover can 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
The following options are supported:
Print help message.
Write error data to binary_name.analyze/dynamic directory for use by the Code Analyzer.
Start web browser browser automatically while running the instrumented program (off by default).
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.
Limit the scope of checking of the library by adding colon-separated files or directories. The scope can be an ELF file or a directory. If an ELF file is specified, all functions defined in the file are checked. If a directory is specified, all files in the directory are recursively used. For example, -c libt.so:/abc/t1.o:t2.o:dir checks the library libt.so only for the functions defined in /abc/t1.o, t2.o, and all ELF files under dir. If the libraries are list using the -c file option, scope can be added to any line in the list.
Cache Directory. The default is $HOME/SUNW_Bit_Cache.
Show only n memory errors in the report (default is show all errors).
Show only n memory leaks in the report (default is 100)
Show offsets in the report (hidden by default).
Determines what happens if a binary you instrumented with Discover forks while you are running it. By default, Discover continues to collect memory access error data from both parent and child processes. If you want Discover to only follow the parent process, specify -F parent. If you want Discover to only follow the child process, specify -F child.
Output analysis to HTML file. If html_file is a relative pathname, 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.
Instrument for data race detection. See Oracle Studio Thread Analyzer documentation.
Force reinstrumentation.
Do not read the bit.rc initialization files.
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.
Show mangled names in the report (hidden by default).
Do not check for errors in executables. The default is to check for errors in executables.
Ignore lib.
Instrumented output filename.
OK if dependent libraries are not instrumentable.
Show only n stack frames in the report (default is 8).
Do not instrument libraries at run time.
Verbose.
Print version and exit without any further processing.
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. You 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 generates a file report.process_ID.txt. If there are multiple %p macros in the file name, only the first one will be replaced.
Limit the target's scope of checking by adding colon-separated files or directories. The scope can be an ELF file or a directory. If an ELF file is specified, all functions defined in the file are checked. If a directory is specified, all files in the directory are recursively used. For example, a.out:/abc/t1.o:t2.o:dir checks the target a.out only for the functions defined in /abc/t1.o, t2.o, and all ELF files under dir.
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.
The following exit values are returned:
All input files were output successfully.
An error occurred.
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 you want to change the number of errors reported to 50 and limit the stack depth in the report to 3, the setting SUNW_DISCOVER_OPTIONS should be set to "-E 50 -S 3".
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 Output report in text format to stderr.This example uses 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 Examines a program that contains a use of uninitialized data.
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)
The Discover software works on Oracle Solaris versions 10 update 6 or later updates and Oracle Solaris 11 Express.
Discover software works only with binaries compiled with Sun Studio 12 Update 1 compiler, Oracle Solaris Studio 12.2, Oracle Solaris Studio 12.3, or Oracle Solaris Studio 13. 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 building 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. Binaries compiled with the -xlinkopt flag are incompatible with Discover.
Discover produces the most accurate results if the entire program, including all shared libraries, is instrumented. By default, Discover checks and reports memory errors only in executables. Discover runtime uses the linker audit interface, also called the rtld-audit or the LD_AUDIT environment variable to automatically load instrumented shared libraries from Discover's cache directory. On Oracle Solaris, the audit interface is used by default. On Linux, you need to set LD_AUDIT on the command line while running the instrumented binary.
For 32-bit applications on Oracle Linux, use the following:
% LD_AUDIT=/compiler/prod/lib/postopt/bitdl.so a.out
For 64-bit applications on Oracle Linux, use the following:
% LD_AUDIT=/compiler/prod/lib/postopt/amd64/bitdl.so a.out
This mechanism might not work in all environments running Oracle Enterprise Linux 5.x. If no library instrumentation is needed and LD_AUDIT is not set, there are no issues with Discover on Oracle Enterprise Linux 5.x. For more information about preparing binaries correctly, see the Oracle Solaris Studio: Discover and Uncover User's Guide.
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 causes its argument to be appended (after a colon separator) to the existing value of the variable. 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.
code-analyzer (1) , CC (1) , cc (1) , f77 (1) , f90 (1) , f95 (1) , gcc(1), bit (3F)