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_resolvers(5)			atom_application_resolvers(5)



NAME

  atom_application_resolvers, ResolveTargetProc, ResolveNamedProc, ReResol-
  veProc, ResolveObjNamedProc -	Allows an Atom tool's instrumentation routine
  to resolve procedure names and call targets

SYNOPSIS

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


  void ResolveTargetProc(
	  Inst *,
	  ProcRes * );

  void ResolveNamedProc(
	  const	char *,
	  ProcRes * );

  void ReResolveProc(
	  ProcRes * );

  void ResolveObjNamedProc(
	  Obj *,
	  const	char *,
	  ProcRes * );

DESCRIPTION

  Atom's application resolver routines allow an	Atom tool's instrumentation
  routine to find a procedure by name and to find a target procedure for a
  call site.

  You can use these routines only from an Atom tool's instrumentation file.
  See atom(1) for a description	of Atom.

  These	routines return	a ProcRes structure, the format	of which is as fol-
  lows:

       typedef struct {
	   Obj *	 obj;  /* Object containing the	called procedure */
	   Proc	*	 proc; /* Called procedure */
	   const char *	 name; /* Name of the called procedure */
	   Inst	*	 inst; /* First	instruction of the called procedure */
       } ProcRes;

  If any of the	four pieces of information contained in	the ProcRes structure
  is unavailable, the routine sets the corresponding field to NULL.

  Certain tools	can simultaneously build several objects, instrument each
  one, and then	write each out.	 This has advantages for tools that call
  ResolveNamedProc or ResolveTargetProc. The ResolveNamedProc routine
  searches for the named procedure in all of the built objects.	 If the
  procedure exists in a	built object, it returns that procedure's Proc.	If
  the procedures exists	in an unbuilt object, it returns NULL.	The Resol-
  veTargetProc routine returns the Proc	called by a jsr	or bsr instruction.
  It also returns the Proc if the instruction is a branch (br, beq, and	so
  on) or jump (jmp) to the start of a procedure.  NULL is returned if the
  called procedure is in an unbuilt object.

  ResolveTargetProc Routine


  Use the ResolveTargetProc routine to resolve the target of a procedure
  call.	 Instructions identified by Inst must belong to	the instruction	class
  (Iclass) ClassSubroutine, or for interprocedural branches, ClassIbranch of
  ClassFBranch.	If the instruction is a	bsr/br/fbr to a	local label, Resol-
  veTargetProc returns NULL in all fields of the ProcRes structure.  Atom
  raises an error if the instruction identified	by Inst	is not a member	of
  ClassSubroutine, ClassIbranch, or ClassFbranch.

  Depending upon the circumstances under which it has been called, Resol-
  veTargetProc returns the following combinations of information:

  ___________________________________________________________________________
  Return Values		   When	Returned -
  ___________________________________________________________________________


  obj, proc, name, inst

			   Returned when the called procedure resides in a
			   built object	and the	procedure has a	name.


  obj, proc, inst

			   Returned when the called procedure resides in a
			   built object	and the	procedure does not have	a
			   name.
  obj, name

			   Returned when the called procedure resides in an
			   unbuilt object.  (Such a procedure always has a
			   name.)  When	this pair of values is returned, you
			   can subsequently resolve the	target procedure by
			   building the	target object with BuildObj and	then
			   calling ReResolveProc.
  name

			   Returned when the called procedure is not visible,
			   but its name	is known.
  --			   The called procedure	cannot be determined.
  ___________________________________________________________________________

  ResolveNamedProc Routine


  Use the ResolveNamedProc routine to return the procedure identified by the
  specified name string.  In the event that more than one procedure has	the
  specified name, ResolveNamedProc uses	the following  criteria	to determine
  which	procedure to return:

   1.  If an external procedure	has the	specified name and that	procedure is
       exported	to other objects, return it.

   2.  If an external procedure	has the	specified name,	return it.  If more
       than one	external procedure has the name, return	one at random.

   3.  If a static procedure has the specified name, return it.	If more	than
       one static procedure has	the name, return one at	random.

  Depending upon the circumstances under which it has been called, Resol-
  veNamedProc returns the following combinations of information:







  ___________________________________________________________________________
  Return Values		   When	Returned -
  ___________________________________________________________________________


  obj, proc, name, inst

			   Returned when the named procedure resides in	a
			   built object.

  obj, name

			   Returned when the named procedure resides in	an
			   unbuilt object. When	this pair of values is
			   returned, you can subsequently resolve the named
			   procedure by	building the target object with	Buil-
			   dObj	and then calling ReResolveProc.
  name			   Returned when the named procedure does not exist.
  ___________________________________________________________________________

  ReResolveProc	Routine


  Use the ReResolveProc	routine	to complete a procedure	resolution if the
  procedure initially resided in an unbuilt object. If the name	in the speci-
  fied ProcRes structure exists	in the object in the specified ProcRes struc-
  ture,	ReResolveProc returns the procedure and	a pointer to the first
  instruction in the ProcRes. If either	the object or the name are NULL,
  ReResolveProc	does nothing.

  ResolveObjNamedProc Routine


  Use the ResolveObjNamedProc routine to look in the specified object for the
  specified procedure. The routine checks the specified	object to see if it
  was linked symbolically. If so, ResolveObjNamedProc searches for the named
  procedure in the specified object first.  If the procedure is	not found, it
  then searches	in all of the built objects.  If the procedure exists in the
  specified object or in any other built object, ResolveObjNamedProc returns
  that procedure's Proc.  Otherwise, it	returns	NULL.

RETURN VALUES

  These	routines return	values as described in the DESCRIPTION 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_navigation(5), atom_description_file(5),
  atom_object_management(5), atom_instrumentation_routines(5), AnalHeap-
  Base(5), Xlate(5), Thread(5)

  Programmer's Guide