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:
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 (in this case, by default, a.out.html) that you can view in your web browser. You can use the -w option when you instrument the binary to request that the report be written to an ASCII file or to stderr.
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 Binaries Must Be Prepared Correctly.
When Discover instruments a binary, it adds code to it 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.
Discover produces the most accurate results if the entire program, including all shared libraries, is instrumented. By default, when you instrument the main executable, Discover inserts code such that when you run the program, Discover automatically instruments all shared libraries as they are opened, whether they are statically linked in the program or dynamically opened by dlopen().
All shared libraries used by the program should be prepared as described in Binaries Must Be Prepared 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.
Some libraries might not be possible to prepare, or they might not be instrumentable for some other reason. To provide for this case, with some loss of accuracy, 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
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 as ignorable 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 use the following options with the discover command to instrument a binary.
Write the instrumented binary to file. By default, the instrumented binary overwrites the input binary.
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 filename unique for each time you run the binary, add the string %p to the filename to ask the Discover runtime to include the process id. For example, the option -w report.%p.txt generates a report file with the filename report.process_id.txt. If you include %p in the filename more than once, only the first instance is replaced with the process id.
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.
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 filename unique for each time you run the binary, add the string %p to the filename to ask the Discover runtime to include the process id. For example, the option -H report.%p.html generates a report file with the filename report.process_id.html. If you include %p in the filename 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 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).
Show mangled names in the report (default is to show de-mangled names).
Show only n stack frames in the report (default is 8).
Run Discover in light mode. This option provides faster execution of your program and the program does not have to be specially prepared as described in Binaries Must Be Prepared Correctly, but the number of errors detected is limited.
Instrument for data race detection using the 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 the Performance Analyzer (see the Oracle Solaris Studio 12.2: Thread Analyzer User’s Guide).
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.
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 /, matching is done on the full absolute pathname of the library. Otherwise, matching is done on the basename of the library.
Do not read the bit.rc initialization files (see bit.rc Initialization Files).
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. Repeat the option for more information.
Print Discover version information and exit.
Discover initializes its state by reading a series of bit.rc files at startup. A system file, Oracle_Solaris_Studio_installation_directory/prod/lib/postopt/bit.rc, provides default values for certain variables. Discover 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 to, and remove from certain variables. 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 nonannotated (not prepared) code in a binary.
For more information, refer to the comments in the header of the system bit.rc file.
You can change the runtime behavior of an instrumented binary by setting the SUNW_DISCOVER_OPTIONS environment variable to a list of the command-line options -b, -e, -E, -f, -H, -l, -L, -m, -S, and -w. For example, if you want to change the number of errors reported to 50 and limit the stack depth in the report to 3, you would set the environment variable to -e 50 -s 3.
By default, if a binary you have instrumented with Discover forks while you are running it, 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, set the SUNW_DISCOVER_FOLLOW_FORK_MODE environment variable.