atom_application_navigation(5)atom_application_navigation(5)NAME
atom_application_navigation, GetFirstObj, GetLastObj, GetNextObj, Get‐
PrevObj, GetFirstObjProc, GetLastObjProc, GetNextProc, GetPrevProc,
GetFirstEntry, GetLastEntry, GetNextEntry, GetPrevEntry, GetEntryProc,
GetEntryBlock, GetFirstBlock, GetLastBlock, GetNextBlock, GetPrevBlock,
GetFirstInst, GetLastInst, GetNextInst, GetPrevInst, GetProcObj, Get‐
BlockProc, GetInstBlock, GetInstBranchTarget - Allows an Atom tool's
instrumentation routine to find locations in an application program
SYNOPSIS
#include <cmplrs/atom.inst.h>
Obj *GetFirstObj(
void ); Obj *GetLastObj(
void ); Obj *GetNextObj(
Obj * ); Obj *GetPrevObj(
Obj * ); Proc *GetFirstObjProc(
Obj * ); Proc *GetLastObjProc(
Obj * ); Proc *GetNextProc(
Proc * ); Proc *GetPrevProc(
Proc * ); Entry *GetFirstEntry(
Proc * ); Entry *GetLastEntry(
Proc * ); Entry *GetNextEntry(
Entry * ); Entry *GetPrevEntry(
Entry * ); Proc *GetEntryProc(
Entry * ); Block *GetEntryBlock(
Entry * ); Block *GetFirstBlock(
Proc * ); Block *GetLastBlock(
Proc * ); Block *GetNextBlock(
Block * ); Block *GetPrevBlock(
Block * ); Inst *GetFirstInst(
Block * ); Inst *GetLastInst(
Block * ); Inst *GetNextInst(
Inst * ); Inst *GetPrevInst(
Inst * ); Inst *GetInstBranchTarget(
Inst * ); Obj *GetProcObj(
Proc * ); Proc *GetBlockProc(
Block * ); Block *GetInstBlock(
Inst * );
DESCRIPTION
Atom's application navigation routines allow an instrumentation routine
to locate areas of an application that are interesting to monitor or
analyze.
You can use these routines only from an Atom tool's instrumentation
file. See atom(1) for a description of Atom.
Atom allows you to view an application with the following granularity:
The entire application, including all shared libraries. Either the
main executable or a shared library. An object comprises a list of
procedures and has it own set of attributes (for example, each object
has its own name). A procedure. A main or alternate entry point. A
basic block. An instruction.
Note
Do not confuse the term object with an object module produced by a com‐
piler. The two terms are completely different.
To traverse the list of objects in an application program, use the fol‐
lowing routines: Use the GetFirstObj or GetLastObj routine to obtain a
pointer to the first or last object in the program. Nonshared programs,
have only one object. For call-shared programs, the first object cor‐
responds to the main program and the remaining objects are its shared
libraries. Use the GetNextObj routine to obtain a pointer to the
object that follows the specified Obj. If the specified Obj is the
last object in the program, GetNextObj returns a NULL pointer. Use the
GetPrevObj routine to obtain a pointer to the object that precedes the
specified Obj. If the specified Obj is the first object in the pro‐
gram, GetPrevObj returns a NULL pointer.
Note
Because the Instrument routine is called for each object in the pro‐
gram, the object traversal routines in the Instrument do not need to be
used routine.
To traverse the list of procedures in an object, use the following rou‐
tines: Use the GetFirstObjProc or GetLastObjProc routine to obtain a
pointer to the first or last procedure in the specified Obj. Use the
GetNextProc routine to obtain a pointer to the procedure that follows
the specified Proc. If the specified Proc is the last procedure in the
object, GetNextProc returns a NULL pointer. Use the GetPrevProc rou‐
tine to obtain a pointer to the procedure that precedes the specified
Proc. If the specified Proc is the first procedure in the object, Get‐
PrevProc returns a NULL pointer.
To traverse the list of entries in a procedure, use the following rou‐
tines: Use the GetFirstEntry or GetLastEntry routine to obtain a
pointer to the first or last entry in the specified Proc. Use the Get‐
NextEntry routine to obtain a pointer to the entry that follows the
specified Entry. If the specified Entry is the last entry in the pro‐
cedure, GetNextEntry returns a NULL pointer. Use the GetPrevEntry rou‐
tine to obtain a pointer to the entry that precedes the specified
Entry. If the specified Entry is the first entry in the procedure,
GetPrevEntry returns a NULL pointer.
To traverse the list of basic blocks in a procedure, use the following
routines: Use the GetFirstBlock or GetLastBlock routine to obtain a
pointer to the first or last basic block in the specified Proc. Use
the GetNextBlock routine to obtain a pointer to the basic block that
follows the specified Block. If the specified Block is the last basic
block in the procedure, GetNextBlock returns a NULL pointer. Use the
GetPrevBlock routine to obtain a pointer to the basic block that pre‐
cedes the specified Block. If the specified Block is the first basic
block in the procedure, GetPrevBlock returns a NULL pointer.
To traverse the instructions in a basic block, use the following rou‐
tines: Use the GetFirstInst or GetLastInst routine to obtain a pointer
to the first or last instruction in the specified Block. Use the Get‐
NextInst routine to obtain a pointer to the instruction that follows
the specified Inst. If the specified Inst is the last instruction in
the basic block, GetNextInst returns a NULL pointer. Use the Get‐
PrevInst routine to obtain a pointer to the instruction that precedes
the specified Inst. If the specified Inst is the first instruction in
the basic block, GetPrevInst returns a NULL pointer.
To navigate between the parts of an application, use the following rou‐
tines: Use the GetProcObj routine to obtain a pointer to the object
that contains the specified Proc. Use the GetEntryProc routine to
obtain a pointer to the procedure that contains the specified Entry.
Use the GetEntryBlock routine to obtain a pointer to the first basic
block in the specified Entry. Use the GetBlockProc routine to obtain a
pointer to the procedure that contains the specified Block. Use the
GetInstBlock routine to obtain a pointer to the basic block that con‐
tains the specified Inst. Use the GetInstBranchTarget routine to
obtain a pointer to the instruction that is the target of Inst. An
error is raised if Inst is not a branch instruction.
RETURN VALUES
These routines return pointers to Obj, Proc, Entry, Block, and Inst
structures, or NULL pointers, as described in the preceding section.
FILES
Header file containing external definitions of Atom routines
SEE ALSO
Commands: atom(1)
Functions: atom_application_instrumentation(5), atom_applica‐
tion_query(5), atom_application_symbols(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_navigation(5)