atom_application_navigation(5)					File Formats Manual				    atom_application_navigation(5)

NAME

       atom_application_navigation,  GetFirstObj,  GetLastObj,	GetNextObj, GetPrevObj, GetFirstObjProc, GetLastObjProc, GetNextProc, GetPrevProc,
       GetFirstBlock, GetLastBlock, GetNextBlock, GetPrevBlock, GetFirstInst, GetLastInst,  GetNextInst,  GetPrevInst,	GetProcObj,  GetBlockProc,
       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 * ); 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 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 basic block.  An instruction.

									  Note

       Do not confuse the term object with an object module produced by a compiler.  The two terms are completely different.

       To traverse the list of objects in an application program, use the following 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
       corresponds 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 program, 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 routines: 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
       routine to obtain a pointer to the procedure that precedes the specified Proc.  If the specified Proc is the first procedure in the object,
       GetPrevProc 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 precedes 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 routines: Use the GetFirstInst or GetLastInst routine to obtain a  pointer
       to  the	first or last instruction in the specified Block.  Use the GetNextInst 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.	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.

       To  navigate  between the parts of an application, use the following routines: Use the GetProcObj routine to obtain a pointer to the object
       that contains the specified Proc.  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 contains the specified Inst.

RETURN VALUES

       These routines return pointers to Obj, Proc, 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)

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

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

       Programmer's Guide

														    atom_application_navigation(5)