Content-type: text/html
atom_application_resolvers, ResolveTargetProc, ResolveNamedProc, ReResolveProc - 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
NULL
if the called procedure is in an unbuilt object.
Use the ResolveTargetProc routine to resolve the target of a procedure call. Atom raises an error if the instruction identified by Inst is not in the instruction class (IClass) ClassSubroutine.
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. |
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.
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. |
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.
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 preceding section.
Header file containing external definitions of Atom routines
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), AnalHeapBase(5), Xlate(5), Thread(5)
Programmer's Guide