|
|
atom_application_resolvers(5)
Contents
|
atom_application_resolvers, ResolveTargetProc, ResolveNamedProc,
ReResolveProc, ResolveObjNamedProc - Allows an
Atom tool's instrumentation routine to resolve procedure
names and call targets
#include <cmplrs/atom.inst.h>
void ResolveTargetProc(
Inst *,
ProcRes * ); void ResolveNamedProc(
const char *,
ProcRes * ); void ReResolveProc(
ProcRes * ); void ResolveObjNamedProc(
Obj *,
const char *,
ProcRes * );
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 follows:
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 ResolveTargetProc 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 [Toc] [Back]
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, ResolveTargetProc 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, ResolveTargetProc 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 [Toc] [Back]
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: If an external procedure has the
specified name and that procedure is exported to other
objects, return it. If an external procedure has the
specified name, return it. If more than one external procedure
has the name, return one at random. If a static
procedure has the specified name, return it. If more than
one static procedure has the name, return one at random.
If a hidden procedure has the specified name, return the
application's hidden procedure information. To find hidden
symbols in shared libraries, navigate the shared library
and use strcmp() on the procedure or entry name. The
__INIT_00_ and __FINI_00_ routines are examples of hidden
symbols.
Depending upon the circumstances under which it has been
called, ResolveNamedProc 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 BuildObj
and then calling ReResolveProc.
name Returned when the named procedure does not exist.
----------------------------------------------------------------------------
ReResolveProc Routine [Toc] [Back]
Use the ReResolveProc routine to complete a procedure resolution
if the procedure initially resided in an unbuilt
object. If the name in the specified ProcRes structure
exists in the object in the specified ProcRes structure,
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 [Toc] [Back]
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.
These routines return values as described in the DESCRIPTION
section.
Header file containing external definitions of Atom routines
Commands: atom(1)
Functions: atom_application_instrumentation(5),
atom_application_navigation(5), atom_application_query(5),
atom_application_symbols(5), atom_description_file(5),
atom_instrumentation_routines(5), atom_object_management(5), AnalHeapBase(5), Thread(5), Xlate(5)
Programmer's Guide
atom_application_resolvers(5)
[ Back ] |
