Index Index for
Section 5
Index Alphabetical
listing for A
Bottom of page Bottom of
page		 

atom_object_management(5)


NAME

  atom_object_management, BuildObj, IsObjBuilt, WriteObj, ReleaseObj - Allows
  an Atom tool's InstrumentAll routine to build, release, and write objects


SYNOPSIS

  #include <cmplrs/atom.inst.h>

  unsigned BuildObj(
	  Obj * );

  unsigned IsObjBuilt(
	  Obj * );

  void WriteObj(
	  Obj * );

  void ReleaseObj(
	  Obj * );


DESCRIPTION

  Atom's object management routines allow an Atom tool's InstrumentAll
  routine 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
  traversing the procedures in the object.  BuildObj builds the internal data
  structures Atom uses to manipulate the object. After the Atom tool
  traverses and instruments the object, the InstrumentAll routine must call
  the WriteObj routine to write out the instrumented version of the object.
  For example:

       unsigned InstrumentAll(int iargc, char **iargv)
       {
	   Obj *  obj;

	   AddCallProto("Startup()");
	   AddCallProto("Finish()");
	   AddCallProto("foo(int, REGV)");

	   AddCallProgram(ProgramBefore, "Startup");
	   AddCallProgram(ProgramAfter, "Finish");

	   for (obj = GetFirstObj();  obj;  obj = GetNextObj(obj))
	   {
	       if (BuildObj(obj))
		   return(1);

		   /* instrument obj */

	       WriteObj(obj);
	    }
	   return(0);
       }

  The WriteObj routine writes the instrumented version of the specified
  object, deallocating the internal data structures BuildObj previously
  created.

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

  Whenever possible, tools should build and write out each object only once.
  Some tools, however, may build and release an object several times,
  ultimately 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
  ResolveNamedProc 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.


RETURN VALUES

  These routines return values as described above.


FILES

  /usr/include/cmplrs/atom.inst.h
      Header file containing external definitions of Atom routines


SEE ALSO

  Commands: atom(1)

  Functions: atom_application_instrumentation(5),
  atom_application_navigation(5), atom_application_query(5),
  atom_application_symbols(5), atom_description_file(5),
  atom_instrumentation_routines(5), AnalHeapBase(5), Thread(5), Xlate(5)

  Programmer's Guide

Index Index for
Section 5
Index Alphabetical
listing for A
Top of page Top of
page