NAME    [Toc]    [Back]

       atom_application_symbols,  FindObj,  FindProc,  FindEntry,
       FindInst, FindObjDepthFirst, GetTargetObj,  GetTargetProc,
       GetTargetEntry,  GetTargetInst,  GetTargetName - Allows an
       Atom tool's instrumentation routine to find  entry  points
       by name or from procedure calls.

SYNOPSIS    [Toc]    [Back]

       #include <cmplrs/atom.inst.h>

       Obj * FindObj(
               const char *name ); Proc * FindProc(
               Obj *object,
               const char *name ); Entry * FindEntry(
               Obj *object,
               const char *name ); Inst * FindInst(
               Obj *object,
               const char *name ); Obj * FindObjDepthFirst(
               Obj *object,
               const char *name ); Obj * GetTargetObj(
               Inst *inst ); Proc * GetTargetProc(
               Inst *inst ); Entry * GetTargetEntry(
               Inst *inst ); Inst * GetTargetInst(
               Inst *inst ); const char * GetTargetName(
               Inst *inst );

PARAMETERS    [Toc]    [Back]

       The  name of a procedure entry point.  An instrumentationtime
 object (as returned by FindObj, FindObjDepthFirst, or
       GetTargetObj)  that defines the requested entry point. The
       object must have been built by calling BuildObj(5)  before
       it  is passed to FindProc, FindEntry, or FindInst.  A procedure-calling
 instruction (bsr, jsr,  or  interprocedural
       branch).  It  must  be in an object that has been built by
       calling BuildObj(5). Atom  raises  an  error  if  GetInstClass(5) would not return ClassSubroutine for the instruction.

DESCRIPTION    [Toc]    [Back]

       The Find* routines  resolve  the  named  symbol.   FindObj
       searches  for  the named entry point in all of the objects
       and returns the object that contains the entry point  with
       the name that is specified. It uses the same breadth-first
       algorithm as the linker to resolve the  symbol.   FindProc
       returns  the  procedure  that contains a main or alternate
       entry point with the specified name in the  given  object.
       FindEntry  returns  the main or alternate entry point with
       the specified name in the given object.  FindInst  returns
       the  first instruction at the address of the resolved symbol
 with the specified name in the given object. An  error
       is  printed  if FindProc, FindEntry, or FindInst is passed
       an unbuilt object.

                                  NOTE

       The FindProc and FindEntry APIs will always resolve a hidden
  symbol  to  the application's hidden symbol.  To find
       hidden symbols in shared libraries,  navigate  the  shared
       library  and  use strcmp() on the procedure or entry name.
       The __INIT_00_ and __FINI_00_  routines  are  examples  of
       hidden symbols.

       FindObjDepthFirst  conducts  a  depth-first search for the
       specified entry point name in the  context  of  an  object
       that was linked with the -B symbolic option. If the specified
 object was not linked  that  way,  Atom  will  search
       breadth-first. The object that contains the entry point is
       returned. The specified object may or may not be built.

       The GetTarget* routines resolve the target of a  procedure
       call  (bsr, jsr, or interprocedural branch).  GetTargetObj
       returns the object containing the target of the  procedure
       call.  The target object need not be built.  GetTargetName
       returns the name of the entry point that is the target  of
       the instruction.  GetTargetProc returns the procedure containing
 the  target.   GetTargetEntry  returns  the  entry
       point  that  is  the  target.   GetTargetInst  returns the
       instruction to which the specified  instruction  jumps  or
       branches.  An error is printed by GetTargetProc, GetTargetEntry,
 or GetTargetInst if the target instruction  is  in
       an unbuilt object. No error is reported by GetTargetObj or
       GetTargetName if the target is in an  unbuilt  object,  so
       the  resulting  object and name can be passed to FindProc,
       FindEntry, or FindInst to fully resolve  the  target  once
       the object has been built.

RETURN VALUES    [Toc]    [Back]

       The  functions  return the object, procedure, entry point,
       instruction or name to which the linker resolved the given
       name  or  procedure  call.  They return NULL if the symbol
       that they are seeking cannot be found (for example, if the
       named  symbol  is  not defined in the application, or if a
       computed jump has many possible targets).

       A tool can build all the objects that comprise an application,
  then instrument them, and then write them out. This
       is the most efficient way to use the Find*  or  GetTarget*
       routines, because the named or called Proc, Entry, or Inst
       will be in an object that has been built.  However,  there
       may  be  other  issues, such as memory use, that make this
       scheme impractical.  The typical  technique  of  building,
       instrumenting,  and  writing  one  object at a time avoids
       such issues, but procedure call targets in  other  objects
       cannot be provided without potentially rebuilding the target
 object. Named symbols in other objects can be found by
       first  calling FindObj to get the defining object and then
       finding the Proc, Entry, or Inst once the object  has  its
       turn to be built.

SEE ALSO    [Toc]    [Back]

       Commands: atom(1)

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

       Programmer's Guide



                                      atom_application_symbols(5)