Once you have prepared the target binary, the next step is to instrument it. Instrumentation adds code in strategic places so that discover can keep track of memory operations while the binary is running.
You instrument a binary using the discover command. For example, the following command instruments the binary a.out and overwrites the input a.out with the instrumented a.out:
discover a.out
When you run the instrumented binary, discover monitors the program's use of memory. During the run, discover writes a report detailing any memory access errors to an HTML file that you can view in your web browser. The default file name is a.out.html. To request that the report be written to an ASCII file or to stderr, use the –w option when you instrument the binary.
To specify that you want discover to do write-only instrumentation of the binary, use the –n option.
When discover instruments a binary, if it finds any code that it cannot instrument because it is not annotated, it displays a warning like the following:
discover: (warning): a.out: 80% of code instrumented (16 out of 20 functions)
Non-annotated code could come from assembly language code linked into the binary, or from modules compiled with compilers or on operating systems older than those listed in Prepare Binaries Correctly.
When discover instruments a binary, it adds code to the binary that works with the runtime linker to instrument dependent shared libraries when they are loaded at runtime. The instrumented libraries are stored in a cache where they can be reused if the original has not changed since it was last instrumented. By default, the cache directory is $HOME/SUNW_Bit_Cache. You can change the directory with the –D option .
The discover utility 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. To specify that you want discover to skip checking for errors in executables, use the –n option.
You can use the –c option to specify that you want discover to check for errors in the dependent shared libraries and libraries dynamically opened by dlopen(). You can also use the –c option to avoid checking for errors in a specific library. Although discover does not report any errors in that library, because it needs to track the memory state of the entire address space to correctly detect memory errors, it records allocations and memory initializations in the entire program including all shared libraries.
The discover utility runtime uses the linker audit interface, also called the rtld-audit or LD_AUDIT 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:
% LD_AUDIT=install-dir/lib/compilers/postopt/bitdl.so a.out
For 64-bit applications on Oracle Linux:
% LD_AUDIT=install-dir/lib/compilers/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 discover has no issues on Oracle Enterprise Linux 5.x.
You should prepare all shared libraries used by the program as described in Prepare Binaries Correctly. By default, if the runtime linker encounters an unprepared library, a fatal error occurs. You can, however, tell discover to ignore one or more libraries.
You might not be able to prepare or instrument some libraries . You can tell discover to ignore these libraries with the –s, –T, or –N option (see Instrumentation Options) or with specifications in bit.rc files (see bit.rc Initialization Files). Some accuracy might be lost.
If a library cannot be instrumented and is not designated as ignorable, then either discover fails at instrumentation time or your program fails at runtime with an error message.
By default, discover uses specifications in the system bit.rc file to set certain system and compiler-supplied libraries to be ignored because they are not prepared. The effect on accuracy is minimal because discover knows the memory characteristics of the most commonly used libraries.
You can specify an executable or library using the –c option. You can further qualify a target executable or target library by restricting the memory access checking to certain object files.
For example, if the target library is libx.so and the target executable is a.out, you would use the following command:
$ discover -c libx.so -o a.out.disc a.out
You can also limit the checking of any target by adding colon-separated files or directories. Files can be ELF files or directories. If you specify an ELF file, all functions defined in the file are checked. If you specify a directory, all files in the directory are recursively used.
$ discover -o a.out.disc a.out:t1.0:dir
$ discover -c libx.so:l1.o:12.o -o a.out.disc a.out
You can use the following options with the discover command to instrument a binary.
Write the error data to binary-name.analyze/dynamic directory for use by Code Analyzer.
Start web browser browser automatically while running the instrumented program (off by default).
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 (default is to hide them).
Write discover's report on the binary in HTML format to html-file. This file is created when you run the instrumented binary. If html-file is a relative pathname, it is placed relative to the working directory where you run the instrumented binary. To make the file name unique for each time you run the binary, add the string %p to the filename to instruct the discover runtime to include the process ID. For example, the option –H report.%p.html generates a report file with the file name report.process-ID.html. If you include %p in the file name more than once, only the first instance is replaced with the process ID.
If you do not specify this option or the –w option, the report is written in HTML format to output-file.html, where output-file is the basename of the instrumented binary. The file is placed in the working directory where you run the instrumented binary.
You can specify both this option and the –w option to write the report in both text and HTML formats.
Show mangled names in the report (default is to show demangled names).
Write the instrumented binary to file. By default, the instrumented binary overwrites the input binary.
Show only n stack frames in the report (default is 8).
Write discover's report on the binary to text-file. The file is created when you run the instrumented binary. If text-file is a relative pathname, the file is placed relative to the working directory where you run the instrumented binary. To make the file name unique for each time you run the binary, add the string %p to the file name to ask the discover runtime to include the process ID. For example, the option –w report.%p.txt generates a report file with the file name report.process-ID.txt. If you include %p in the file name more than once, only the first instance is replaced with the process ID. Specifying –w - will output in stderr.
If you do not specify this option or the –H option, the report is written in HTML format to output-file.html, where output-file is the basename of the instrumented binary. The file is placed in the working directory where you run the instrumented binary.
You can specify both this option and the –H option to write the report in both text and HTML formats.
Turn on or off allocation/free stack traces (default is on with stack depth 8). This flag can only be specified when instrumenting for hardware-assisted checking, using the –i adi option. For better runtime performance, allocation/free stack trace collection can be turned off with this option. This option can only be used if you have Oracle Solaris Studio 12.4 , 4/15 Platform Specific Enhancement (PSE) installed.
Check for errors in all libraries, or in the specified library, or in the libraries listed separated by new lines in the specified file. The default is not to check for errors in libraries. You can limit the scope of checking of the library by adding colon-separated files or directories. For more information, see Checking Parts of a Library or an Executable.
Specify what you want to happen 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 both parent and child processes. If you want discover to follow only the parent process, specify –F parent. If you want Discover to follow only the child process, specify –F child.
Determines instrumentation type of discover (default is memcheck).
If datarace is specified, instrument for data race detection using Thread Analyzer. When you use this option, only data race detection is done at runtime; no other memory checking is done. The instrumented binary must be run with the collect command to generate an experiment that you can view in Performance Analyzer. For more information, see Oracle Solaris Studio 12.4: Thread Analyzer User’s Guide . If memcheck is specified, instrument for memory error checking. If adi is specified, instrument for hardware-assisted checking using the SPARC M7 processor ADI feature. This feature is only available with Oracle Solaris 11.3 running on SPARC M7 processor. The –i adi option can only be used if you have Oracle Solaris Studio 12.4 , 4/15 Platform Specific Enhancement (PSE) installed.
Do not read the bit.rc initialization files (see bit.rc Initialization Files).
Run discover in light mode. This option provides faster execution of your program and the program does not have to be specially prepared, but the number of errors detected is limited.
Do not check for errors in executables.
Do not instrument any dependent shared library matching the prefix library. If the initial characters of a library name match library, the library is ignored. If library begins with a slash (/), matching is done on the full absolute pathname of the library. Otherwise, matching is done on the basename of the library.
Turn on or off precise ADI mode. Default is on. This flag can only be specified when instrumenting for hardware-assisted checking, using the –i adi option. For better runtime performance, you can turn off precise ADI mode with this option. This option can only be used if you have Oracle Solaris Studio 12.4 , 4/15 Platform Specific Enhancement (PSE) installed.
Issue a warning but do not flag an error if an attempt is made to instrument an uninstrumentable binary.
Instrument the named binary only. Do not instrument any dependent shared libraries at runtime.
Use cache-directory as the root directory for storing cached instrumented binaries. By default, the cache directory is $HOME/SUNW_Bit_Cache.
Force reinstrumentation of any libraries found in the cache.
Help. Print a short usage message and exit.
Verbose. Print a log of what discover is doing. Specify the option twice for more information.
Print discover version information and exit.
The discover utility initializes its state by reading a series of bit.rc files at startup. A system file, Oracle-Solaris-Studio-installation-directory/prod/lib/bit.rc, provides default values for certain variables. The discover utility reads this file first, followed by $HOME/.bit.rc if it exists, and current-directory/.bit.rc if it exists.
The bit.rc files contain commands to set, append, or remove certain variable values. When discover reads a set command, it discards the previous value, if any, of the variable. When it reads an append command, it appends the argument (after a colon separator) to the existing value of the variable. When it reads a remove command, it removes the argument and its colon separator from the existing value of the variable.
The variables set in the bit.rc files include the list of libraries to ignore when instrumenting, and lists of functions or function prefixes to ignore when computing the percentage of non-annotated (not prepared) code in a binary.
For more information, refer to the comments in the header of the system bit.rc file.