atom_object_management, BuildObj, IsObjBuilt, WriteObj, ReleaseObj - Allows
an Atom tool's InstrumentAll routine to build, release, and write objects
Obj * );
Obj * );
Obj * );
Obj * );
Atom's object management routines allow an Atom tool's InstrumentAll rou-
tine to build, write, and release objects.
You can use these routines only from an Atom tool's instrumentation file.
See atom(1) for a description of Atom.
An InstrumentAll routine must call the BuildObj routine before calling
AddCallObj to add analysis routine calls to the object and before travers-
ing the procedures in the object. BuildObj builds the internal data struc-
tures Atom uses to manipulate the object. After the Atom tool traverses
and instruments the object, the InstrumentAll routine must call the Wri-
teObj routine to write out the instrumented version of the object. For
unsigned InstrumentAll(int iargc, char **iargv)
Obj * obj;
for (obj = GetFirstObj(); obj; obj = GetNextObj(obj))
/* instrument obj */
The WriteObj routine writes the instrumented version of the specified
object, deallocating the internal data structures BuildObj previously
Note that BuildObj may return an error code. It returns a nonzero value
(and issues an appropriate error message) if it encounters an error in the
executable file for the Obj0. You should propagate this error value back to
Atom by returning 1 from InstrumentAll.
The ReleaseObj routine deallocates the internal data structures for the
given object, but does not write out the instrumented version the object.
You should not call ReleaseObj if you have added any analysis routine calls
to the object.
The IsObjBuilt routine returns a nonzero value if the specified object has
been built with BuildObj, but not yet written with WriteObj or unbuilt with
Whenever possible, tools should build and write out each object only once.
Some tools, however, may build and release an object several times, ulti-
mately writing out its instrumented version. This can be very time-
consuming for a tool with very large objects.
Similarly, tools should normally build only one object at a time. Certain
tools may simultaneously build several objects, instrument each one, and
then write each out. This has advantages for tools that call Resol-
veNamedProc or ResolveTargetProc. However, having more than one large
object built at a single time will cause Atom to run slowly and to consume
a large amount of memory.
These routines return values as described above.
Header file containing external definitions of Atom routines
AtomTools: hiprof(5), pixie(5), third(5)
Functions: atom_application_instrumentation(5), atom_application_query(5),
atom_application_resolvers(5), atom_instrumentation_routines(5), AnalHeap-
Base(5), Xlate(5), Thread(5)