unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



atom_object_management(5)			    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 <&lt;cmplrs/atom.inst.h>&gt;


  unsigned BuildObj(
	  Obj *	);

  unsigned IsObjBuilt(
	  Obj *	);

  void WriteObj(
	  Obj *	);

  void ReleaseObj(
	  Obj *	);

DESCRIPTION

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

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)

  AtomTools: hiprof(5),	pixie(5), third(5)

  Functions: atom_application_instrumentation(5), atom_application_query(5),
  atom_application_navigation(5), atom_description_file(5),
  atom_application_resolvers(5), atom_instrumentation_routines(5), AnalHeap-
  Base(5), Xlate(5), Thread(5)

  Programmer's Guide