svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
discover(1)
discover(1) User Commands discover(1)
NAME
discover - Memory Error Discovery Tool
SYNOPSIS
discover
[-?] [-h] [-a] [-A [on|off]] [-b browser]
[-c [- | lib [:scope...]| file] [-D dir] [-e num]
[-E num] [-f] [-F [parent|child|both]] [-H html-file]
[-i [datarace|memcheck|adi]] [-k] [-K] [-l] [-m]
[-n] [-N lib] [-o file] [-P [on|off]] [-S num]
[-T] [-v] [-V] [-w txt-file] target[:scope]
DESCRIPTION
Memory Error Discovery Tool (Discover) is a tool used by software de‐
velopers to detect programming errors related to the allocation and use
of program memory at runtime.
Examples of errors detected by Discover include:
o Accessing uninitialized memory
o Reads from and writes to unallocated memory
o Accessing memory beyond allocated array bounds
o Use of freed memory
o Freeing wrong memory blocks
o Memory leaks
The following is a simple example of preparing, instrumenting, and run‐
ning an executable:
% cc -g 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
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
***************** 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
DISCOVER SUMMARY:
unique errors : 1 (1 total, 0 filtered)
unique warnings : 0 (0 total, 0 filtered)
If a stripped binary is instrumented, Discover will automatically
switch to light mode.
To use Discover, the input binary must be compiled using compiler ver‐
sion Oracle Solaris 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 So‐
laris 11 Express), or Oracle Enterprise Linux versions 6.x or 7.x. Us‐
ing the -g option allows Discover to produce more informative messages.
Discover is incompatible with binaries compiled with -xlinkopt.
MESSAGES
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
OPTIONS
The following options are supported:
-h
Print help message.
-a
Write error data to binary-name.analyze/dynamic directory for use
by Code Analyzer.
-A [on|off]
Turn on or off the allocation/free stack traces. Default is set to
on with a stack depth of 8. This option is only available with the
-i adi flag.
-b browser
Start web browser browser automatically while running the instru‐
mented program (off by default).
-c [- | lib [:scope...]| 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.
Limit the scope of checking of the library by adding colon-sepa‐
rated files or directories. The scope can be an ELF file or a di‐
rectory. If an ELF file is specified, all functions defined in the
file are checked. If a directory is specified, all files in the di‐
rectory 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.
-D dir
Location of the cache directory where Discover runtime caches in‐
strumented binaries. The default is $HOME/SUNW_Bit_Cache.
-e n
Show only n memory errors in the report (default is show all er‐
rors).
-E n
Show only n memory leaks in the report (default is 100). This op‐
tion is only meaningful with -i memcheck, which is the default
mode.
-f
Show offsets in the report (hidden by default).
-F [parent | child | both]
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.
-H html-file
Output analysis to HTML file. If html-file is a relative pathname,
it is placed relative to the working directory where the instru‐
mented binary is run. If the file name contains %p, it will be re‐
placed with the process ID. See -w for more details.
-i [datarace|memcheck|adi]
Determines instrumentation of Discover. If datarace is specified,
instrument for data race detection. See Oracle Developer Studio
Thread Analyzer documentation. If memcheck is specified, instrument
for memory error checking. This is the default. If adi is speci‐
fied, instrument for hardware assisted checking using the SPARC M7
processor ADI feature. This feature is only available with Oracle
Solaris 11.3 and later OS running on SPARC M7 processor.
-k
Force reinstrumentation of shared libraries instead of using the
instrumented libraries from the cache directory.
-K
Do not read the bit.rc initialization files.
-l
Run Discover in light mode. Provides faster execution of your pro‐
gram and finds any memory access errors earlier on than when run‐
ning it in full mode. The input binary does not have to be spe‐
cially instrumented. This option is only meaningful in -i memcheck
mode and has no effect with -i adi or -i datarace.
-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.
-P [on|off]
Turn on or off precise ADI mode. Default is on. This option is only
available with the -i adi flag.
-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 relative to the work‐
ing 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 re‐
port.%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. Using -w - will use stderr.
target[:scope]
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.
USAGE
Discover can generate either a text report, using the -w txt-file op‐
tion, 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 in‐
strumented 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 set‐
ting this environment variable to a list of Discover flags (-a, -A,
-b, -e, -E, -f, -F, -H, -l, -L, -m, -P, -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_OP‐
TIONS should be set to "-E 50 -S 3".
EXAMPLES
Example 1 Send output to an HTML file.
By default, Discover sends any 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 -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 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: }
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: }
***************** 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: }
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 -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: }
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
Compiler Requirements
Discover's default full-mode works only with binaries compiled with Or‐
acle Solaris Studio 12 Update 1 compiler, Oracle Solaris Studio 12.2,
or a later release. Discover in light mode (with the -l option) or ADI
mode (with the -i
adi option) do not have compiler requirements. If
you try to run Discover in full mode on a binary that is not compiled
with a supported compiler, Discover issues an error and does not in‐
strument 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 er‐
rors 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.
Instrumenting Shared Libraries
Discover produces the most accurate results if the entire program, in‐
cluding 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=install-dir/lib/compilers/bitdl.so a.out
For 64-bit applications on Oracle Linux, use the following:
% LD_AUDIT=install-dir/lib/compilers/amd64/bitdl.so a.out
This mechanism might not work in all environments running Oracle Enter‐
prise 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 Developer Studio 12.5: Discover and Uncover User's Guide.
FILES
Discover and Bit .rc Files
Discover initializes its state by reading a series of .rc files at
startup. A system file, compiler_area/lib/compilers/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 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 ig‐
nore while instrumenting, and lists of functions or function prefixes
to ignore when computing the percentage of nonannotated code in a bi‐
nary.
For more information, see the header in the system .rc file.
SEE ALSO
codean(1), code-analyzer(1), CC(1), cc(1), f77(1), f90(1), f95(1),
gcc(1), bit(3F)
Studio 12.6 December 2016 discover(1)