Instrumenting a Prepared Binary

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 (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.

You can use the -n option to specify that you want Discover to do write-only instrumentation of the binary.

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 Binaries Must Be Prepared Correctly.

Caching Shared Libraries

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.

Instrumenting Shared Libraries

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. 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 use the -n option to specify that you want Discover to skip checking for errors in executables.

If you use the -c option to avoid checking for errors in a specific library, Discover does not report any errors in that library. However, Discover needs to track the memory state of the entire address space to correctly detect memory errors, so it records allocations and memory initializations in the entire program including all shared libraries.

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.

Ignoring 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.

Command Line Options

You can use the following options with the discover command to instrument a binary.

Output Options

-a

Write the error data to binary_name.analyze/dynamic directory for use by the Code Analyzer.

-b browser

Start web browser browser automatically while running the instrumented program (off by default).

-o file

Write the instrumented binary to file. By default, the instrumented binary overwrites the input binary.

-w text_file

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.

-H html_file

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.

-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 (default is to hide them).

-m

Show mangled names in the report (default is to show de-mangled names).

-S n

Show only n stack frames in the report (default is 8).

Instrumentation Options

-c [ - | library | file ]

Check for errors in all libraries, or in the specified library, or in the libraries listed in the specified file.

-n

Do not check for errors in executables.

-l

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.

-F [parent | child]

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 the parent process. If you want Discover to follow the fork and collect memory access data from the child process, specify -F child.

-i

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.3 Thread Analyzer User's Guide).

-s

Issue a warning, but do not flag an error, if an attempt is made to instrument an uninstrumentable binary.

-T

Instrument the named binary only. Do not instrument any dependent shared libraries at runtime.

-N library

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.

-K

Do not read the bit.rc initialization files (see bit.rc Initialization Files).

Caching Options

-D cache_directory

Use cache_directory as the root directory for storing cached instrumented binaries. By default, the cache directory is $HOME/SUNW_Bit_Cache.

-k

Force reinstrumentation of any libraries found in the cache.

Other Options

-h or -?

Help. Print a short usage message and exit.

-v

Verbose. Print a log of what Discover is doing. Repeat the option for more information.

-V

Print Discover version information and exit.

bit.rc Initialization Files

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.

SUNW_DISCOVER_OPTIONS Environment Variable

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, -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.

SUNW_DISCOVER_FOLLOW_FORK_MODE Environment Variable

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.