atom_application_symbols(5)atom_application_symbols(5)NAME
atom_application_symbols, FindObj, FindProc, FindEntry, FindInst, Find‐
ObjDepthFirst, GetTargetObj, GetTargetProc, GetTargetEntry, GetTar‐
getInst, 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
The name of a procedure entry point. 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. A procedure-calling instruction (bsr, jsr, or interprocedu‐
ral 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 proce‐
dure or entry name. The __INIT_00_ and __FINI_00_ routines are exam‐
ples 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 sym‐
bolic 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 con‐
taining 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 con‐
taining 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_navi‐
gation(5), atom_application_query(5), atom_description_file(5),
atom_instrumentation_routines(5), atom_object_management(5), AnalHeap‐
Base(5), Thread(5), Xlate(5)
Programmer's Guide
atom_application_symbols(5)