Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

isobjbuilt(5) [osf1 man page]

atom_object_management(5)					File Formats Manual					 atom_object_management(5)

NAME
atom_object_management, BuildObj, IsObjBuilt, WriteObj, ReleaseObj - Allows an Atom tool's InstrumentAll routine to build, release, and write objects SYNOPSIS
#include <cmplrs/atom.inst.h> unsigned BuildObj( Obj * ); unsigned IsObjBuilt( Obj * ); void WriteObj( Obj * ); void ReleaseObj( Obj * ); DESCRIPTION
Atom's object management routines allow an Atom tool's InstrumentAll routine to build, write, and release objects. You can use these routines only from an Atom tool's instrumentation file. See atom(1) for a description of Atom. An InstrumentAll routine must call the BuildObj routine before calling AddCallObj to add analysis routine calls to the object and before traversing the procedures in the object. BuildObj builds the internal data structures Atom uses to manipulate the object. After the Atom tool traverses and instruments the object, the InstrumentAll routine must call the WriteObj routine to write out the instrumented version of the object. For example: unsigned InstrumentAll(int iargc, char **iargv) { Obj * obj; AddCallProto("Startup()"); AddCallProto("Finish()"); AddCallProto("foo(int, REGV)"); AddCallProgram(ProgramBefore, "Startup"); AddCallProgram(ProgramAfter, "Finish"); for (obj = GetFirstObj(); obj; obj = GetNextObj(obj)) { if (BuildObj(obj)) return(1); /* instrument obj */ WriteObj(obj); } return(0); } The WriteObj routine writes the instrumented version of the specified object, deallocating the internal data structures BuildObj previously created. Note that BuildObj may return an error code. It returns a nonzero value (and issues an appropriate error message) if it encounters an error in the executable file for the Obj0. You should propagate this error value back to Atom by returning 1 from InstrumentAll. The ReleaseObj routine deallocates the internal data structures for the given object, but does not write out the instrumented version the object. You should not call ReleaseObj if you have added any analysis routine calls to the object. The IsObjBuilt routine returns a nonzero value if the specified object has been built with BuildObj, but not yet written with WriteObj or unbuilt with ReleaseObj. Whenever possible, tools should build and write out each object only once. Some tools, however, may build and release an object several times, ultimately writing out its instrumented version. This can be very time-consuming for a tool with very large objects. Similarly, tools should normally build only one object at a time. Certain tools may simultaneously build several objects, instrument each one, and then write each out. This has advantages for tools that call ResolveNamedProc or ResolveTargetProc. However, having more than one large object built at a single time will cause Atom to run slowly and to consume a large amount of memory. RETURN VALUES
These routines return values as described above. FILES
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_application_resolvers(5), atom_instrumentation_routines(5), AnalHeapBase(5), Xlate(5), Thread(5) Programmer's Guide atom_object_management(5)

Check Out this Related Man Page

atom_instrumentation_routines(5)				File Formats Manual				  atom_instrumentation_routines(5)

NAME
atom_instrumentation_routines, Instrument, InstrumentAll, InstrumentInit, InstrumentFini - Atom tool instrumentation routines SYNOPSIS
#include <cmplrs/atom.inst.h> void Instrument( int iargc, char **iargv, Obj *obj ); void InstrumentInit( int iargc, char **iargv ); void InstrumentFini( void ); unsigned InstrumentAll( int iargc, char **iargv ); DESCRIPTION
Atom invokes a tool's instrumentation routine on a given application program when that program is specified as the appl_prog parameter to the atom(1) command, and either of the following is true: The tool is named in an argument to the -tool flag of an atom command. By default, Atom looks for named tools in the /usr/lib/cmplrs/atom/tools and /usr/lib/cmplrs/atom/examples directories. The file containing the instrumentation routine is specified as the instrum_file parameter of an atom command. The instrumentation routine contains the code that traverses the objects, procedures, basic blocks, and instructions to locate instrumenta- tion points; adds calls to analysis procedures; and builds the instrumented version of an application. An instrumentation routine can employ one of the following interfaces based on the needs of the tool: Atom calls the Instrument routine for each eligible object in the application program. As a result, an Instrument routine should not call AddCallProgram and does not need to use the object navigation routines (GetFirstObj, GetLastObj, GetNextObj, and GetPrevObj). Because Atom automatically writes each object before passing the next to the Instrument routine, the Instrument routine should never call the BuildObj, WriteObj, or ReleaseObj routines. If an Instrument routine calls the ResolveTargetProc or ResolveNamedProc routine for a procedure name that exists in another object, the routine sets the proc field in the ProcRes structure to NULL. If the tool uses ResolveNamedProc to add special instrumentation code to a specific procedure, it can use a construct like the following: Instrument(int iargc, char **iargv, Obj *obj) { ProcRes pres; ResolveNamedProc("malloc", &pres); if (pres.proc != NULL) { AddCallProc(pres.proc, ProcBefore, "foo"); <Add special instrumentation code> } } Because malloc exists in only one of the objects, this construct adds the special instrumentation code to malloc exactly once - when its object is instrumented. When using the Instrument interface, you can define an InstrumentInit routine to perform tasks required before Atom calls Instrument for the first object (such as defining analysis routine prototypes, adding program level instrumentation calls, and performing global initializations). Atom passes the arguments specified in the -toolargs flag to the atom command to the InstrumentInit rou- tine. You can also define an InstrumentFini routine to perform tasks required after Atom calls Instrument for the last object (such as global cleanup). Atom passes no parameters to the InstrumentFini routine. Atom restricts an InstrumentInit or InstrumentFini routine to using only a subset of the Atom routines. In general terms, either routine is allowed to add prototypes, add program level analysis calls, traverse objects, and perform some queries about objects. Neither can traverse the procedures in any object. Specifically, InstrumentInit and InstrumentFini can call only the following routines: AddCallProto GetFirstObj GetLastObj GetNextObj GetPrevObj Calls to GetObjInfo that do not specify an ObjInfoType of ObjNumberProcs, ObjNumberBlocks, or ObjNumberInsts GetObjName GetObjOutName GetAnalName GetObjInstArray GetObjInstCount GetProgInfo Additionally, an InstrumentInit routine can call AddCallProgram. Normally a tool does not use any Atom routines in an Instru- mentFini routine. Atom calls the InstrumentAll routine once for the entire application program, thus allowing a tool's instrumenta- tion code itself to determine how to traverse the application's objects. With this method, you do not specify InstrumentInit or InstrumentFini routines. The InstrumentAll routine does everything. Because of this, an InstrumentAll routine must call the Atom object navigation routines itself and use the BuildObj, WriteObj, or ReleaseObj routine to manage the application's objects. A typical InstrumentAll routine might contain the following code: unsigned InstrumentAll(int iargc, char **iargv) { Obj * obj; AddCallProto("Startup()"); AddCallProto("Finish()"); AddCallProto("foo(int, REGV)"); AddCallProgram(ProgramBefore, "Startup"); AddCallProgram(ProgramAfter, "Finish"); for (obj = GetFirstObj(); obj; obj = GetNextObj(obj)) { if (BuildObj(obj)) return(1); /* instrument obj */ WriteObj(obj); } return(0); } The InstrumentAll routine first adds the prototypes for the analysis routine and then adds the program-level analysis calls. Next, it traverses the objects in the program, calling BuildObj to build the internal Atom data structures for each object before travers- ing that object's procedures or adding analysis calls to the object. Afterwards, it calls WriteObj to write out the instrumented version of the given object and deallocate the internal data structures that BuildObj created. Note that, because BuildObj may return an error code, the InstrumentAll routine propagates this error return back to Atom by returning 1. An InstrumentAll routine must return zero (0) to Atom if the tool completes successfully, or 1 if it encounters an error. Atom terminates with an error code if the routine returns 1. Regardless of the instrumentation routine interface, Atom passes the arguments specified in the -toolargs flag to the routine. In the case of the Instrument interface, Atom also passes a pointer to the current object. An Atom tool should use one of the following methods of specifying analysis routines to instrument an entire object or application program: If an analysis routine applies to something contained within a single object, use AddCallObj. An example of this is an analysis routine that initializes some data for a procedure. If an analysis routine applies to the entire program, call AddCallProgram from an Instrumen- tInit routine (when using the Instrument interface) or from the InstrumentAll routine. An example of this is an analysis routine that opens an output file or parses command line options. RETURN VALUES
These routines return values as described in the preceding section. FILES
Header file containing external definitions of Atom routines SEE ALSO
Commands: atom(1) Atom Tools: hiprof(5), pixie(5), third(5) Functions: atom_application_instrumentation(5), atom_application_query(5), atom_application_navigation(5), atom_description_file(5), atom_application_resolvers(5), atom_object_management(5), AnalHeapBase(5), Xlate(5), Thread(5) Programmer's Guide atom_instrumentation_routines(5)
Man Page