unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



atom_application_navigation(5)		       atom_application_navigation(5)



NAME

  atom_application_navigation, GetFirstObj, GetLastObj,	GetNextObj, GetPre-
  vObj,	GetFirstObjProc, GetLastObjProc, GetNextProc, GetPrevProc, GetFirst-
  Block, GetLastBlock, GetNextBlock, GetPrevBlock, GetFirstInst, GetLastInst,
  GetNextInst, GetPrevInst, GetProcObj,	GetBlockProc, GetInstBlock, GetInst-
  BranchTarget - Allows	an Atom	tool's instrumentation routine to find loca-
  tions	in an application program

SYNOPSIS

  #include <&lt;cmplrs/atom.inst.h>&gt;


  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:

  Program The entire application, including all	shared libraries.

  Obj	  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).

  Proc	  A procedure.

  Block	  A basic block.

  Inst	  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 follow-
  ing 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 fol-
       lows 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 pre-
       cedes the specified Obj.	 If the	specified Obj is the first object in
       the program, 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 pro-
       cedure 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	pro-
       cedure in the object, GetPrevProc returns a NULL	pointer.

  To traverse the list of basic	blocks in a procedure, use the following rou-
  tines:

    +  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 GetPrevInst 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 rou-
  tines:

    +  Use the GetProcObj routine to obtain a pointer to the object that con-
       tains 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

  /usr/include/cmplrs/atom.inst.h
      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), AnalHeap-
  Base(5), Xlate(5), Thread(5)

  Programmer's Guide