Add dyninstAPI/BPatch_image.h

docs/dyninstAPI/developer/API.rst

@@ -21,6 +21,7 @@ DyninstAPI
   BPatch_flowGraph.h
   BPatch_frame.h
   BPatch_function.h
+  BPatch_image.h
   BPatch_libInfo.h
   BPatch_memoryAccessAdapter.h
   BPatch_private.h

docs/dyninstAPI/developer/BPatch_image.h.rst

@@ -0,0 +1,16 @@
+.. _`sec-dev:BPatch_image.h`:
+
+BPatch_image.h
+##############
+
+.. cpp:namespace:: dev
+
+.. cpp:class:: BPatch_image
+
+  .. cpp:function:: BPatch_image(BPatch_addressSpace *addSpace)
+  .. cpp:function:: BPatch_image()
+  .. cpp:function:: BPatch_module *findModule(mapped_module *base)
+  .. cpp:function:: BPatch_object *findObject(mapped_object *base)
+  .. cpp:function:: virtual ~BPatch_image()
+  .. cpp:function:: void getNewCodeRegions(std::vector<BPatch_function*>& newFuncs, std::vector<BPatch_function*>&modFuncs)
+  .. cpp:function:: void clearNewCodeRegions()

docs/dyninstAPI/public/BPatch_image.h.rst

@@ -3,172 +3,163 @@
 BPatch_image.h
 ##############
 
-.. cpp:class:: BPatch_image
+.. cpp:class:: BPatch_image: public BPatch_sourceObj
   
-  This class defines a program image (the executable associated with a
-  process). The only way to get a handle to a BPatch_image is via the
-  BPatch_process member function getImage.
+  **A program image (the executable associated with a process)**
 
-  .. cpp:function:: const BPatch_point *createInstPointAtAddr (caddr_t address)
+  The only way to get a handle to a BPatch_image is via :cpp:func:`BPatch_process::getImage`.
 
-    This function has been removed because it is not safe to use. Instead,
-    use findPoints:
+  .. cpp:type:: bool (*BPatchFunctionNameSieve) (const char *name, void* sieve_data)
+  .. cpp:type:: std::vector<std::pair<unsigned long, unsigned long> >::iterator arange_iter
+  .. cpp:type:: BPatch_Vector<BPatch_statement>::iterator statement_iter
 
-  .. cpp:function:: bool findPoints(Dyninst::Address addr, std::vector<BPatch_point *> &points);
+  .. cpp:function:: BPatch_thread* getThr()
 
-    Returns a vector of BPatch_points that correspond with the provided
-    address, one per function that includes an instruction at that address.
-    There will be one element if there is not overlapping code.
+    Return the BPatch_thread associated with this image
 
-  .. cpp:function:: std::vector<BPatch_variableExpr *> *getGlobalVariables()
+  .. cpp:function:: BPatch_addressSpace* getAddressSpace()
 
-    Return a vector of global variables that are defined in this image.
+    Return the BPatch_addressSpace associated with this image
 
-  .. cpp:function:: BPatch_process *getProcess()
+  .. cpp:function:: BPatch_process* getProcess()
 
-    Returns the BPatch_process associated with this image.
+    Return the BPatch_process associated with this image
 
-  .. cpp:function:: char *getProgramFileName(char *name, unsigned int len)
+  .. cpp:function:: bool getSourceObj(BPatch_Vector<BPatch_sourceObj*> &sources)
 
-    Fills provided buffer name with the program’s file name up to len
-    characters. The filename may include path information.
+    Fill a vector with children source objects (modules)
 
-  .. cpp:function:: bool getSourceObj(std::vector<BPatch_sourceObj *> &sources)
+  .. cpp:function:: BPatch_sourceObj* getObjParent()
 
-    Fill sources with the source objects (see section 4.6) that belong to
-    this image. If there are no source objects, the function returns false.
-    Otherwise, it returns true.
+    Return the parent of this image (always NULL since this is the top level)
 
-  .. cpp:function:: std::vector<BPatch_function *> *getProcedures(bool incUninstrumentable = false)
+  .. cpp:function:: bool getVariables(BPatch_Vector<BPatch_variableExpr*> &vars)
 
-    Return a vector of the functions in the image. If the
-    incUninstrumentable flag is set, the returned table of procedures will
-    include uninstrumentable functions. The default behavior is to omit
-    these functions.
+    Returns the global variables defined in this image
 
-  .. cpp:function:: void getObjects(std::vector<BPatch_object *> &objs)
+  .. cpp:function:: BPatch_Vector<BPatch_function*>* getProcedures(bool incUninstrumentable = false)
 
-    Fill in a vector of objects in the image.
+    Returns a list of all procedures in the image upon success
 
-  .. cpp:function:: std::vector<BPatch_module *> *getModules()
+  .. cpp:function:: bool getProcedures(BPatch_Vector<BPatch_function*> &procs, bool incUninstrumentable = false)
 
-    Return a vector of the modules in the image.
+    Returns a list of all procedures in the image
 
-  .. cpp:function:: bool getVariables(std::vector<BPatch_variableExpr *> &vars)
+  .. cpp:function:: BPatch_Vector<BPatch_parRegion*>* getParRegions(bool incUninstrumentable = false)
 
-    Fills vars with the global variables defined in this image. If there are
-    no variable, the function returns false. Otherwise, it returns true.
+    Returns a list of all parallel regions in the image
 
-  .. cpp:function:: std::vector<BPatch_function*> *findFunction( \
-       const char *name, \
-       std::vector<BPatch_function*> &funcs, \
-       bool showError = true, \
-       bool regex_case_sensitive = true, \
-       bool incUninstrumentable = false)
+  .. cpp:function:: BPatch_Vector<BPatch_module*>* getModules()
 
-    Return a vector of BPatch_functions corresponding to name, or NULL if
-    the function does not exist. If name contains a POSIX-extended regular
-    expression, and dont_use_regex is false, a regular expression search
-    will be performed on function names and matching BPatch_functions
-    returned. If showError is true, then Dyninst will report an error via
-    the BPatch::registerErrorCallback if no function is found.
+    Returns a vector of all modules in this image
 
-    If the incUninstrumentable flag is set, the returned table of procedures
-    will include uninstrumentable functions. The default behavior is to omit
-    these functions.
+  .. cpp:function:: void getObjects(std::vector<BPatch_object*> &objs)
+
+    Returns a vector of all objects in this image
+
+  .. cpp:function:: bool getModules(BPatch_Vector<BPatch_module*> &mods)
+
+    Returns a vector of all modules in this image
+
+  .. cpp:function:: BPatch_module* findModule(const char *name, bool substring_match = false)
+
+    Returns a module matching <name> if present in image.
+
+    If ``substring_match`` is ``true``, the first module that has ``name`` as a substring of its name
+    is returned. For example, to find "libpthread.so.1", search for "libpthread"  with ``substring_match``
+    set to ``true``.
+
+  .. cpp:function:: BPatch_Vector<BPatch_variableExpr*>* getGlobalVariables()
+
+    Returns the global variables defined in this image
+
+  .. cpp:function:: BPatch_Vector<BPatch_function*>* findFunction(const char* name, BPatch_Vector<BPatch_function*> &funcs,\
+                                                                  bool showError=true, bool regex_case_sensitive=true, \
+                                                                  bool incUninstrumentable = false)
+
+    Returns a vector of functions matching ``name``.
+
+    If ``name`` contains a POSIX-extended regular expression and ``dont_use_regex`` is ``false``, a regular expression search
+    is performed. If ``showError`` is ``true``, then errors are reported by :cpp:func:`BPatch::registerErrorCallback` if no
+    function is found. If ``incUninstrumentable`` is ``true``, the returned table of procedures include uninstrumentable
+    functions. The default behavior is to omit these functions.
 
     .. note::
-
        If name is not found to match any demangled function names in
        the module, the search is repeated as if name is a mangled function
        name. If this second search succeeds, functions with mangled names
        matching name are returned instead.
-
-  .. cpp:function:: std::vector<BPatch_function*> *findFunction( \
-       std::vector<BPatch_function*> &funcs, \
-       BPatchFunctionNameSieve bpsieve,\
-       void *sieve_data = NULL,\
-       int showError = 0,\
-       bool incUninstrumentable = false)
 
-    Return a vector of BPatch_functions according to the generalized
-    user-specified filter function bpsieve. This permits users to easily
-    build sets of functions according to their own specific criteria.
-    Internally, for each BPatch_function f in the image, this method makes a
-    call to bpsieve(f.getName(), sieve_data). The user-specified function
-    bpsieve is responsible for taking the name argument and determining if
-    it belongs in the output vector, possibly by using extra user-provided
-    information stored in sieve_data. If the name argument matches the
-    desired criteria, bpsieve should return true. If it does not, bpsieve
-    should return false.
+  .. cpp:function:: BPatch_Vector<BPatch_function*>* findFunction(BPatch_Vector<BPatch_function*> &funcs,\
+                                                                  BPatchFunctionNameSieve bpsieve, void *user_data=NULL,\
+                                                                  int showError=0, bool incUninstrumentable = false)
 
-    The function bpsieve should be defined in accordance with the typedef:
+    Returns a vector of functions matching criterion specified by user defined callback function bpsieve.
 
-  .. cpp:type:: bool (*BPatchFunctionNameSieve) (const char *name, void* sieve_data);
+  .. cpp:function:: BPatch_function* findFunction(unsigned long addr)
 
-    If the incUninstrumentable flag is set, the returned table of procedures
-    will include uninstrumentable functions. The default behavior is to omit
-    these functions.
+    Returns a function at a specified address
 
-  .. cpp:function:: bool findFunction(Dyninst::Address addr, std::vector<BPatch_function *>&funcs)
+  .. cpp:function:: bool findFunction(Dyninst::Address addr, BPatch_Vector<BPatch_function*> &funcs)
 
-    Find all functions that have code at the given address, addr. Dyninst
-    supports functions that share code, so this method may return more than
-    one BPatch_function. These functions are returned via the funcs output
-    parameter. This function returns true if it finds any functions, false
-    otherwise.
+    Returns a function at a specified address
 
-  .. cpp:function:: BPatch_variableExpr *findVariable(const char *name, bool showError = true)
+  .. cpp:function:: BPatch_variableExpr* findVariable(const char *name, bool showError=true)
 
-  .. cpp:function:: BPatch_variableExpr *findVariable(BPatch_point &scope, const char *name)
+    Returns global variable matching ``name`` in the image in the global scope.
 
-    second form of this method is not implemented on Windows.
+  .. cpp:function:: BPatch_variableExpr* findVariable(BPatch_point &scp, const char *nm, bool showError=true)
 
-    Performs a lookup and returns a handle to the named variable. The first
-    form of the function looks up only variables of global scope, and the
-    second form uses the passed BPatch_point as the scope of the variable.
-    The returned BPatch_variableExpr can be used to create references (uses)
-    of the variable in subsequent snippets. The scoping rules used will be
-    those of the source language. If the image was not compiled with
-    debugging symbols, this function will fail even if the variable is
-    defined in the passed scope.
+    Returns local variable matching name ``nm`` in function scope ``scp``.
 
-  .. cpp:function:: BPatch_type *findType(const char *name)
+    Not implemented on Windows.
 
-    Performs a lookup and returns a handle to the named type. The handle can
-    be used as an argument to BPatch_addressSpace::malloc to create new
-    variables of the corresponding type.
+  .. cpp:function:: BPatch_type* findType(const char *name)
 
-  .. cpp:function:: BPatch_module *findModule(const char *name, bool substring_match = false)
+    Returns a BPatch_type corresponding to <name>, if exists, NULL if not found
 
-    Returns a module named name if present in the image. If the match fails,
-    NULL is returned. If substring_match is true, the first module that has
-    name as a substring of its name is returned (e.g. to find
-    libpthread.so.1, search for libpthread with substring_match set to
-    true).
+  .. cpp:function:: bool findPoints(Dyninst::Address addr, std::vector<BPatch_point*> &points)
 
-  .. cpp:function:: bool getSourceLines(unsigned long addr, std::vector<BPatch_statement> & lines)
+    Returns a vector of BPatch_points that correspond with the provided address, one  per function that includes an instruction at that address. Will have one element  if there is not overlapping code.
 
-    Given an address addr, this function returns a vector of pairs of
-    filenames and line numbers at that address. This function is an alias
-    for BPatch_­process::getSourceLines (see section 4.4).
-
-  .. cpp:function:: bool getAddressRanges( const char * fileName, unsigned int lineNo, \
-       std::vector< std::pair< unsigned long, unsigned long > > & ranges )
+  .. cpp:function:: bool getAddressRanges(const char* fileName, unsigned int lineNo, std::vector<Dyninst::SymtabAPI::AddressRange>& ranges)
 
     Given a file name and line number, fileName and lineNo, this function
-    returns a list of address ranges that this source line was compiled
-    into. This function is an alias for BPatch_process::getAddressRanges
-    (see section 4.4).
-
-  .. cpp:function:: bool parseNewFunctions(std::vector<BPatch_module*> &newModules, \
-          const std::vector<Dyninst::Address> &funcEntryAddrs)
-
-    This function takes as input a list of function entry points indicated
-    by the funcEntryAddrs vector, which are used to seed parsing in whatever
-    modules they are found. All affected modules are placed in the
-    newModules vector, which includes any existing modules in which new
-    functions are found, as well as modules corresponding to new regions of
-    the binary, for which new BPatch_modules are created. The return value
-    is true in the event that at least one previously unknown function was
-    identified, or false otherwise.
+    returns a list of address ranges that this source line was compiled into.
+
+  .. cpp:function:: bool getSourceLines( unsigned long addr, BPatch_Vector<BPatch_statement> & lines )
+
+    Returns the source statements in ``lines`` that cover the address ``addr``.
+
+  .. cpp:function:: arange_iter getAddressRanges_begin(const char* fileName, unsigned int lineNo)
+  .. cpp:function:: arange_iter getAddressRanges_end(const char* fileName, unsigned int lineNo)
+  .. cpp:function:: statement_iter getSourceLines_begin(unsigned long addr)
+  .. cpp:function:: statement_iter getSourceLines_end(unsigned long addr)
+
+  .. cpp:function:: char* getProgramName(char *name, unsigned int len)
+
+    Fills provided buffer <name> with the program's name, up to <len> chars
+
+  .. cpp:function:: char* getProgramFileName(char *name, unsigned int len)
+
+    Fills provided buffer <name> with the program's file name,   which may include path information.
+
+  .. cpp:function:: bool parseNewFunctions(BPatch_Vector<BPatch_module*> &affectedModules, const BPatch_Vector<Dyninst::Address> &funcEntryAddrs)
+
+    This function uses function entry addresses to find and parse new functions using our control-flow traversal parsing.
+
+    funcEntryAddrs: this is a vector of function start addresses that seed the control-flow-traversal parsing.  If they lie in
+    an existing module they are parsed in that module, otherwise a new module is created.  In both cases the modules are added to
+    affectedModules
+
+    affectedModules: BPatch_modules will be added to this vector if no existing modules bounded the specified function entry points.
+    Unfortunately, new modules will also sometimes have to be created for dynamically created code in memory that does not map to the
+    file version of the binary.
+
+    Return value: This value is true if a new module was created or if new code was parsed in an existing module
+
+  .. cpp:function:: bool readString(Dyninst::Address addr, std::string &str, unsigned size_limit = 0)
+
+    Reads a string from the target process
+
+  .. cpp:function:: bool readString(BPatch_variableExpr *expr, std::string &str, unsigned size_limit = 0)