Objects of the SourceObj class represent part of the source code structure associated with a target application process. A group of SourceObj class objects provide a hierarchical representation of the source code structure which the analysis tool can navigate. Member functions of this class enable the analysis tool to navigate the source code structure and identify instrumentation points.
Description
This predefined type is used for representing addresses in target applications. It is defined as an eight-byte unsigned integer.
Description
This enumeration type describes whether the source object to which it applies was compiled and linked with the 32-bit address memory model or the 64-bit address memory model enabled. All objects within a program are compiled and linked with the same model.
The following are members of the enumerated type of LpModel. Refer to DPCL Programming Guide for a full description of each status code.
Table 15. LpModel Enumeration Types
| Enumeration Type | Description |
|---|---|
| SOL_lp32 | 32-bit programming model |
| SOL_unknown_model | Unknown programming model |
Description
This enumeration type describes whether the source object to which it applies represents a whole program, module, function, data object, and so on.
The following are members of the enumerated type of SourceType. Refer to DPCL Programming Guide for a full description of each status code.
Table 16. SourceType Enumeration Types
| Enumeration Type | Description |
|---|---|
| SOT_data | Represents global data |
| SOT_function | Represents a function |
| SOT_module | Represents a source file |
| SOT_program | Represents the target application source structure |
| SOT_unknown_type | Source type is unknown |
Synopsis
#include <SourceObj.h> SourceObj(void); SourceObj(const SourceObj ©);
Parameters
Description
The default constructor creates an empty source object whose LP model and source type are each set to unknown. The default constructor is invoked when uninitialized source objects are created, such as in arrays of source objects. Objects within the array can be overwritten using an assignment operator (operator =).
The copy constructor is used to transfer the contents of an initialized object (the copy parameter) to an uninitialized object.
Exceptions
See Also
LpModel, Process::get_program_object, src_type
Synopsis
#include <SourceObj.h> AisAddress address_end(void) const;
Description
Returns the address of the last element associated with this source object. If the source object represents a scalar data object, then address_start and address_end return the same value. If the source object represents a function, then it returns the approximate address of the last instruction in the function. If the source object represents the program, then 0 is returned.
Return Values
Returns the address of the last element associated with this source object
See Also
address_start, line_end line_start, src_type
Synopsis
#include <SourceObj.h> AisAddress address_start(void) const;
Description
Returns the address of the first element associated with this source object. If the source object represents a scalar data object, then address_start and address_end return the same value. If the source object represents a function, then it returns the approximate address of the first instruction in the function. If the source object represents the program, then 0 is returned.
Return Values
Returns the address of the first element associated with this source object
See Also
address_end, line_end line_start, src_type
Synopsis
#include <SourceObj.h> AisStatus bexpand(const Process &proc);
Parameters
Description
Applies only to source objects with SourceType of SOT_module. The function requests that the details of an unexpanded module be supplied. Modules are not expanded when the client initially connects with a process. Modules that are not expanded cannot be examined for additional structure, such as data, functions, and instrumentation points. Recommended use is to establish a connection to a process, then expand those modules where one wishes to place instrumentation.
If the SourceType is not SOT_module, the function immediately returns with a status of ASC_operation_failed.
Note that the function submits the request to expand the source object and waits until the request has completed.
Return Values
The return value indicates whether the request for expansion was successfully executed.
See Also
expand, src_type
Synopsis
#include <SourceObj.h>
FunctionList *bget_function_list(
const Process &proc,
char *regexp,
AisStatus *sts);
Parameters
Description
Sends a request to the server to get, for a particular process, a list of function names that match a regular expression you supply.
Return Values
See Also
get_function_list
Synopsis
#include <SourceObj.h> SourceObj child(int index) const;
Parameters
Description
Returns the child indicated by the parameter index. Index must be greater than or equal to 0, and less than child_count(). When child() is given an index value that is outside of this range, it returns an empty source object, as created by the default constructor. Children can be variables, functions, modules, and so forth.
Return Values
Returns the child source object indicated by the parameter index.
See Also
child_count, obj_parent, src_type
Synopsis
#include <SourceObj.h> int child_count(void) const;
Description
Returns the number of child source objects associated with this source object. Empty source objects, created by the default constructor, return 0. Children can be variables, functions, modules, and so on.
Return Values
Returns the number of child source objects associated with this source object.
See Also
child, obj_parent, src_type
Synopsis
#include <SourceObj.h> InstPoint exclusive_point(int index) const;
Parameters
Description
Returns the instrumentation point indicated by the parameter index. Instrumentation points contained only within this source object are arranged in a list whose smallest index is 0 and whose largest index is exclusive_point_count() -1.
When exclusive_point is given an index value that is outside this range, it returns an empty InstPoint object, as would be created by the default constructor.
Return Values
Returns the instrumentation point indicated by the parameter index.
See Also
exclusive_point_count, inclusive_point
Synopsis
#include <SourceObj.h> int exclusive_point_count(void) const;
Description
Returns the number of instrumentation points associated with only this source object.
Return Values
Returns the number of instrumentation points associated with this source object.
See Also
exclusive_point
Synopsis
#include <SourceObj.h>
AisStatus expand(
const Process & proc,
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Applies only to source objects with SourceType of SOT_module. The function requests that the details of an unexpanded module be supplied. Modules are not expanded when the client initially connects with a process. Modules that are not expanded cannot be examined for additional structure, such as data, functions, and instrumentation points. Recommended use is to establish a connection to a process, then expand those modules where one wishes to place instrumentation.
If the SourceType is not SOT_module, the function immediately returns with a status of ASC_operation_failed.
Note that the function submits the request to expand the source object and returns immediately. It does not wait until the request has completed.
Return Values
The return value for expand indicates whether the request was successfully submitted, but indicates nothing about whether the request itself was successfully executed.
Callback Data
When the callback is invoked the callback function is passed a pointer to the source object as the callback object. The callback message is the request status, of type AisStatus, which contains one of the following status values:
See Also
bexpand, src_type
Synopsis
#include <SourceObj.h> ProbeType get_data_type(void) const;
Description
Returns the data type of the object when the object represents a variable. When the object represents something that is not a variable, it returns an error data type invalid (DEN_error_type).
Return Values
Returns the data type of the object. If the object represents something other than a variable, invalid is returned.
See Also
DataExpNodeType, ProbeType::get_node_type
Synopsis
#include <SourceObj.h>
char *get_demangled_name(
char *buffer,
unsigned int len) const;
Parameters
Description
When the invoking object of is of type SOT_function, this function copies into buffer a null-terminated character string representing the demangled name of an object when that object is a function. The name may be truncated if the len parameter is smaller than the length of the demangled name. A function's demangled name is the name of a function as it appears in the original source code of a program as seen by a compiler.
Return Values
Returns a pointer to buffer, which will contain at most len bytes of the demangled function name when the object is a function. If the object in question is not of type SOT_function, then NULL is returned.
See Also
get_demangled_name_length, get_mangled_name, src_type
Synopsis
#include <SourceObj.h> unsigned int get_demangled_name_length(void) const;
Description
Returns the length, including the null-terminating byte, of the demangled name of a function.
Return Values
When the object is a function, the length of the object's demangled name is returned. If the object is not a function, 0 is returned.
See Also
get_demangled_name
Synopsis
#include <SourceObj.h>
AisStatus get_function_list(
const Process &proc,
char *regexp,
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Sends a request to the server to get, for a particular process, a list of function names that match a regular expression you supply.
Note that the get_function_list function immediately returns control to the caller upon issuing the request to get the function list. The return value indicates only whether the request was successfully submitted.
Callback Data
The callback function is passed a pointer to the FunctionList object (containing the list of function names that match the supplied regular expression for the specified process) as the callback object. The callback message is the request status, of type AisStatus, which contains one of the following values:
Return Values
The return value for the get_function_list function indicates whether the request was successfully submitted.
See Also
bget_function_list
Synopsis
#include <SourceObj.h>
char *get_mangled_name(
char *buffer,
unsigned int len) const;
Parameters
Description
When the invoking object is of type SOT_function, this function copies into buffer a null-terminated character string representing the mangled name of an object when that object is a function. The name may be truncated if the len parameter is smaller than the length of the mangled name. A function's mangled name is the name of a function as it appears to the linker and loader. Name mangling is supported by compilers and linkers to resolve overloaded function names in object-oriented programming languages. In order to distinguish between two functions that have the same programmer-visible name, compilers encode parameter type information into the actual function name as it is seen by the linker and loader.
Mangled names include parameter data type information for some languages, notably C++, but not necessarily for all languages.
Return Values
Returns a pointer to buffer, which will contain at most len bytes of the mangled function name, when the object is a function. If the object in question is not of type SOT_function, then NULL is returned.
See Also
get_demangled_name, get_mangled_name_length, src_type
Synopsis
#include <SourceObj.h> unsigned int get_mangled_name(void) const;
Description
Returns the length, including the null-terminating byte, of the mangled name of a function.
Return Values
When the object is a function, the length of the object's mangled name is returned. If the object is not a function, 0 is returned.
See Also
get_mangled_name
Synopsis
#include <SourceObj.h> LpModel get_program_type(void) const;
Description
Returns an indicator of whether the program is using the 32-bit address memory model, or not. All functions within a program must use the same memory model. UNIX does not support mixed address models.
Return Values
Synopsis
#include <SourceObj.h> char *get_variable_name( char *buffer, int len) const;
Parameters
Description
Copies into buffer a null-terminated character string representing the name of the object when the object is a data variable. To check if an object is a data variable, look for a return type of SOT_data from src_type(). The name may be truncated if the len parameter is smaller than the length of the variable name.
Return Values
If the object is a data variable, a pointer to buffer, which will contain, at most, len bytes of the name is returned. If the object is not a data variable, 0 is returned.
See Also
get_variable_name_length, src_type
Synopsis
#include <SourceObj.h> unsigned int get_variable_name_length(void) const;
Description
Returns the length, including the null-terminating byte, of the name of the object when the object is a data variable.
Return Values
If the object is a data variable the return value is the length of the name. If the object is not a data variable, 0 is returned.
See Also
get_variable_name
Synopsis
#include <SourceObj.h> InstPoint inclusive_point(int index) const;
Parameters
Description
Returns the instrumentation point indicated by the parameter index. All instrumentation points contained within this source object and its children are arranged in a list whose smallest index is 0 and whose largest index is inclusive_point_count() -1.
When inclusive_point is given an index value that is outside this range, it returns an empty InstPoint object, as would be created by the default constructor.
Return Values
Returns the instrumentation point indicated by the index parameter.
See Also
child, exclusive_point, inclusive_point_count
Synopsis
#include <SourceObj.h> int inclusive_point_count(void) const;
Description
Returns the number of instrumentation points associated with this source object and all of its children.
Return Values
Returns the number of instrumentation points associated with this source object and all of its children.
See Also
inclusive_point
Synopsis
#include <SourceObj.h> int line_end(void) const;
Description
Returns the approximate source line number of the last line in the object. When the line number is unknown or undefined, the function returns -1. Line numbers identify lines for which the compiler generates assembler instructions.
Return Values
Returns the approximate line number of the last line in the object, or -1.
See Also
address_end, address_start, line_start, src_type
Synopsis
#include <SourceObj.h> int line_start(void) const;
Description
Returns the approximate source line number of the first line in the object. When the line number is unknown or undefined, the function returns -1. Line numbers identify lines for which the compiler generates assembler instructions.
Return Values
Returns the approximate line number of the first line in the object, or -1.
See Also
address_end, address_start, line_end, src_type
Synopsis
#include <SourceObj.h> char *module_name( char *buffer, unsigned int len) const;
Parameters
Description
Copies into buffer a null-terminated character string representation of the file name and path, if available, of the module that contains the object. The name may be truncated if the len parameter is smaller than the length of the module name.
Return Values
Returns a pointer to buffer, which will contain the file name and path, if available, of the module that contains this object. Returns 0 if the object is the program object, which is not contained within any module
See Also
module_name_length
Synopsis
#include <SourceObj.h> unsigned int module_name_length(void) const;
Description
Returns the length, including the null-terminating byte, of the file name and path, if available, of the module that contains the object.
Return Values
Returns the length of the file name and path, if available, of the module that contains this object. Returns 0 if the object is the program object, which is not contained within any module.
See Also
module_name
Synopsis
#include <SourceObj.h> SourceObj obj_parent(void) const;
Description
Returns the parent object of this object. For example, the parent object of a function object is a module object. If the SourceObj is a program or module object, this will return a new SourceObj of type SOT_unknown_type.
Return Values
Returns the parent object of the object, or an object of SOT_unknown_type.
See Also
child, child_count, src_type
Synopsis
#include <SourceObj.h> SourceObj &operator = (const SourceObj ©);
Parameters
Description
Transfers the contents of the copy parameter to the object.
Return Values
Returns a reference to the object.
Synopsis
#include <SourceObj.h>> int operator == (const SourceObj &compare);
Parameters
Description
Compares two source objects for equivalence. If the two objects represent the same portion of the program or application, this function returns 1. Otherwise it returns 0.
Return Values
Returns 1 if the two objects are equivalent. If the two objects are not equivalent, 0 is returned.
Synopsis
#include <SourceObj.h> int operator != (const SourceObj &compare);
Parameters
Description
Compares two source objects for equivalence. If the two objects represent the same portion of the program or application, this function returns 0. Otherwise, it returns 1.
Return Values
Returns 0 if the two objects are equivalent. If the two objects are not equivalent, 1 is returned.
Synopsis
#include <SourceObj.h> char *program_name( char *buffer, unsigned int len) const;
Parameters
Description
If the SourceObj is of type program, then this function copies into buffer a null-terminated character string representing the file name and path of the executable program (a.out). The name may be truncated if the len parameter is smaller than the length of the program name.
Return Values
Returns a pointer to buffer, which will contain the file name and path, if available, of the executable. Returns NULL if this information is not available.
See Also
program_name_length, src_type
Synopsis
#include <SourceObj.h> unsigned int program_name_length(void) const;
Description
Returns the length of the file name and path, if available, of the executable program (a.out).
Return Values
Returns the length of the file name and path of the executable. Returns 0 if this information is not available.
See Also
program_name
Synopsis
#include <SourceObj.h> ProbeExp reference(void) const;
Description
Creates a reference to a program function or variable that may be used in a probe expression. References to program functions may be used in creating calls to those functions, while references to program variables may be used to read, modify, or write those variables.
When the object does not represent a program function or variable, an undefined probe expression is returned. To check for an undefined probe expression, use get_data_type() to get the ProbeType, and then check for a ProbeType of DEN_error_type. To see if a SourceObj is a program function or variable, use src_type() and check for return types of SOT_function or SOT_data.
Exceptions
Return Values
Returns a reference to the program function or data, or an undefined probe expression.
See Also
ProbeExp::call, src_type
Synopsis
#include <SourceObj.h> SourceType src_type(void) const;
Description
Returns the type of source object represented by the object. The source object type corresponds to various objects within a program, such as modules, functions, variables, etc. If the source object does not correspond to a program or part of a program, the source object type is SOT_unknown_type.
Return Values
Returns the type of this source object.
See Also
get_variable_name, module_name, program_name,