The method used to instrument libraries at runtime for bit and
discover has an issue that can lead to incomplete analysis in discover
and undercounts in bit analyze -M, bit coverage -M, collect -c on,
collect -c coverage, and bit collect -M [-c].

In some cases, the issue can lead to incorrect program execution.

Many libraries are not instrumented because the library is not
annotated. Currently this includes all system and compiler-supplied
libraries.  Or, sometimes the user chooses to exclude a library from
instrumentation using the -N option. We will use the latter method to
illustrate the examples below.

In the current implementation, when a library is loaded that is NOT
instrumented, none of its dependent libraries are instrumented. This
can cause undercounting and incomplete analysis.

Incorrect program execution can arise because we can load two versions
of a library, both an instrumented and uninstrumented version, in the
same process. This can happen when the library is a dependent of two
different libraries, one of which is instrumented, and the other
uninstrumented. If the dependent library keeps state in static
variables, for instance, this can cause trouble.

It is difficult to predict how this problem would manifest in user
programs. However, if a bit- or discover-instrumented version of a program
runs differently from the noninstrumented version, run pldd(1)
on the process to obtain a list of loaded libraries, and inspect the
output to see if any library is loaded in both an instrumented and
noninstrumented form.

In such a case, you might see both:

/Max/Tom/Alice/libChandra.so
--and--
.../SUNW_Bit_cache/count/Max/Tom/Alice/a34c260f2502b526fc3f103755ef1df1_1193765328/libChandra.so

The simplest way to work around the issue, when it arises, is to
simply exclude the dually-loaded library from being instrumented by
using the -N option, or by adding an entry to .bit.rc telling
bit/discover/collect to ignore the library. This will fix the
incorrect execution problem. (Note that collect -c does not have a -N
option, so users of collect -c will have to use the latter method.)

Working around the undercounting (or, in the case of discover,
incomplete analysis) problem is more complex, and users of collect -c
will not be able to use it. They will have to use bit directly.

Let us say a program, a.out, depends on two libraries, lib_a.so and
lib_b.so, and both of them depend on lib_c.so. The dependency can be
expressed explicitly on the link line, or dynamically by calling
dlopen() at runtime.

Further let us say the user wishes to exclude lib_a.so from analysis
and instruments using the commands:

discover -N lib_a.so a.out
or
bit instrument -M -N lib_a.so a.out

When a.out is run, lib_c.so will be loaded both in an instrumented and
uninstrumented form.

To work around this using discover, first instrument the dually-loaded
library in place:

discover lib_c.so

Then exclude the library when instrumenting a.out:

discover -N lib_a.so -N lib_c.so a.out

When a.out is run, it will pick up the previously-instrumented version
of lib_c.so and do its analysis using that.

For bit, the workaround is more complex. There are two different ways
to do it.

BIT Method 1:

mkdir sav
cp lib_c.so sav
bit instrument -o lib_c.so lib_c.so
bit instrument -M -N lib_a.so -N lib_c.so a.out

run a.out

cp sav/lib_c.so lib_c.so
bit analyze -e -M -l lib_c.so a.out  

BIT Method 2:

bit instrument -R lib_c.so
bit instrument -M -N lib_a.so -N lib_c.so a.out

run a.out

bit analyze -e -R lib_c.so
bit analyze -e -M a.out

The last two commands will produce two experiments. They should be
analyzed together in the analyzer or er_print:

analyzer test.1.er test.2.er