Index for Section 5

Alphabetical listing for A

Bottom of page

atom_application_symbols(5)
NAME
  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
  #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
  name
      The name of a procedure entry point.

  object
      An instrumentation-time 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.

  inst
      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
  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
  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
  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

Index for Section 5

Alphabetical listing for A

Top of page