atom_application_resolvers(5)atom_application_resolvers(5)NAME
atom_application_resolvers, ResolveTargetProc, ResolveNamedProc, ReRe‐
solveProc, ResolveObjNamedProc - Allows an Atom tool's instrumentation
routine to resolve procedure names and call targets
SYNOPSIS
#include <cmplrs/atom.inst.h>
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 instrumenta‐
tion 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
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, Clas‐
sIbranch 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, 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: 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 pro‐
cedure information. To find hidden symbols in shared libraries, navi‐
gate 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, 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
specified ProcRes structure exists in the object in the specified Pro‐
cRes 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
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 proce‐
dure 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
Header file containing external definitions of Atom routines
SEE ALSO
Commands: atom(1)
Functions: atom_application_instrumentation(5), atom_application_navi‐
gation(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)