Objects of the InstPoint class represent instrumentation points. Member functions of this class enable the analysis tool to get information about the instrumentation point. Specifically, the analysis tool can:
This book uses two terms that you may not be familiar with. The term lhs refers to the left-hand side of an expression or operator, while the term rhs refers to the right-hand side.
Description
This enumeration type is used to describe the location of instrumentation relative to the instruction being instrumented. Not all locations are valid with all instrumentation point types. For call site instrumentation points, instrumentation may be placed before the instruction or after the instruction. Instrumentation points that are not attached to a location within an application or process, perhaps because they were created by a default constructor, are invalid.
The following are members of the enumerated type of InstPtLocation.
Table 7. InstPtLocation Enumeration Types
| Enumeration Type | Description |
|---|---|
| IPL_after | instrumentation is placed after the indicated instruction. |
| IPL_before | instrumentation is placed before the indicated instruction. |
| IPL_invalid | instrumentation point is not attached to a valid location. |
Description
This enumeration type describes the type of location that may be instrumented. Not all will be available within a given source object. Availability depends on source object type and options used when compiling the application process.
The following are members of the enumerated type of InstPtType.
Table 8. InstPtType Enumeration Types
| Enumeration Type | Description |
|---|---|
| IPT_function_call | The instrumentation point represents a call to a function or subroutine |
| IPT_function_entry | The instrumentation point represents the first executable instruction in a function or subroutine |
| IPT_function_exit | The instrumentation point represents the last executable instruction in a function or subroutine. Note that functions or subroutines with multiple exit points will always reach this instrumentation point |
| IPT_invalid | The instrumentation point does not represent a valid location |
See Also
class SourceObj
Synopsis
#include <InstPoint.h> InstPoint(void); InstPoint(const InstPoint ©);
Parameters
Description
Two constructors are provided with this class; a default constructor and a copy constructor. The default constructor can create storage, that is marked as containing invalid instrumentation points. This storage may later be assigned through an assignment from a valid instrumentation point.
The copy constructor performs an operation that is similar to assignment, but it works on an uninitialized object.
Exceptions
See Also
Class SourceObj, Process::install_probe
Synopsis
#include <InstPoint.h> AisAddress get_address(void) const;
Description
Returns the address in the target program where the instrumentation point occurs. If the instrumentation point is invalid, or the address is not available, this function returns a value of 0. This information is generally available only if the application is compiled with the -g (debug) flag.
Return Values
Returns the address of the instrumentation point or 0.
See Also
get_line
Synopsis
#include <InstPoint.h> SourceObj get_container(void) const;
Description
This function returns the source object that contains the instrumentation point. This allows a tool to start with an instrumentation point and explore the context in which it occurs, such as the function and module in which the instrumentation point resides.
Return Values
Returns the source object that contains the instrumentation point.
Synopsis
#include <InstPoint.h>
char *get_demangled_name(
char *buffer,
unsigned int len) const;
Parameters
Description
When the instrumentation point refers to a subroutine or function call site, this function places a null-terminated character string representing the demangled name of the function being called at the location specified by buffer. The name may be truncated if the len parameter is smaller than the length of the function name.
Return Values
Returns the pointer to buffer, containing the demangled name of the function. NULL is returned if this instrumentation point does not refer to a call site.
See Also
get_demangled_name_length, get_type
Synopsis
#include <InstPoint.h> unsigned int get_demangled_name_length(void) const;
Description
Returns the length, including the null-terminating byte, of the demangled name of the function that is being called at this point.
Return Values
If this point refers to a function call site, then the return value is the length of the demangled name of the function being called. If this point is not a function call site, then the return value is 0.
See Also
get_demangled_name, get_type
Synopsis
#include <InstPoint.h> int get_line(void) const;
Description
This function returns the approximate line number, in the source code, where the instrumentation point occurs. If the instrumentation point is invalid, or the address is not available, this function returns a value of -1. This information is generally available only if the application process is compiled with the -g (debug) flag.
Return Values
Returns the approximate line number in the source code or -1.
Synopsis
#include <InstPoint.h> InstPtLocation get_location(void) const;
Description
Returns the location of the instrumentation relative to the instrumentation point. Possible locations are IPL_invalid, IPL_before, and IPL_after. If the location is IPL_before, then instrumentation installed using this instrumentation point will occur immediately before the instruction is executed. If it is IPL_after, then instrumentation will be installed immediately after the instruction. When the instrumentation represents a function entry or function exit, or when it is not attached to a valid location within a process, the return value is IPL_invalid.
Return Values
See Also
get_type
Synopsis
#include <InstPoint.h>
char *get_mangled_name(
char *buffer,
unsigned int len) const;
Parameters
Description
When the instrumentation point refers to a subroutine or function call site, this function places a null-terminated character string representing the mangled name (function name with the data type encoded) of the function that is being called at the location specified by buffer. The name may be truncated if the len parameter is smaller than the length of the function name.
Return Values
Returns a pointer to buffer containing the mangled name of the function. The return value is NULL if this instrumentation point does not refer to a call site.
See Also
get_mangled_name_length, get_type
Synopsis
#include <InstPoint.h> unsigned int get_mangled_name_length(void) const;
Description
Returns the length, including the null-terminating byte, of the mangled name of the function that is being called at this point.
Return Values
If this point refers to a function call site, then the return value is the length of the mangled name of the function being called. If this point is not a function call site the return value is 0.
See Also
get_mangled_name, get_type
Synopsis
#include <InstPoint.h> InstPtType get_type(void) const;
Description
This function returns the type of this instrumentation point, such as beginning or end of a subroutine, at a function call site, etc.
Return Values
Returns the type of instrumentation point.
See Also
get_location
Synopsis
#include <InstPoint.h> InstPoint &operator = (const InstPoint ©);
Parameters
Description
Assigns the value of the right operand to the invoking object. The left operand is the invoking object.
For example,
InstPoint rhs, lhs; ... lhs = rhs;
assigns the value of rhs to lhs. Both values would then refer to the same InstPoint.
Return Values
Returns a reference to the invoking object.
Synopsis
#include <InstPoint.h> int operator == (const InstPoint &compare);
Parameters
Description
Compares two instrumentation points for equivalence. If the two points represent the same instrumentation site within the same version of the same file, this function returns 1. Otherwise, it returns 0.
Return Values
If the two objects are equivalent, this function returns 1. Otherwise, it returns 0.
Synopsis
#include <InstPoint.h> int operator != (const InstPoint &compare);
Parameters
Description
Compares two instrumentation sites for equivalence. If the two points represent the same instrumentation site within the same version of the same file, this function returns 0. Otherwise, it returns 1.
Return Values
If the two objects are equivalent, this function returns 0. Otherwise, it returns 1.