source/api.rst

   1 API
   2 ===
   3
   4 The APIs for the individual programming languages all derive from the
   5 C++ structure of ``src/core`` adapted to the native spelling of the
   6 respective programming language. As an example, all from within guile
   7 all methods are available as ``classname-functionname`` with
   8 name-components separated by dashes instead of CamelCase.
   9
  10 Function
  11 --------
  12
  13 .. cpp:class:: Function
  14
  15    Represents a function in the binary. Functions are typically the
  16    target of ``call`` instructions and are composed of
  17    :cpp:class:`BasicBlock`
  18
  19 .. cpp:function:: std::string Function::getName() const
  20
  21    Returns the Name of the function
  22
  23 .. cpp:function:: void Function::setName(const std::string& new_name)
  24
  25    Updates the Name of the Function. Also takes care to notify all
  26    consumers of the changed name so the new name is displayed
  27    consistently
  28
  29 .. cpp:function:: bool Function::isDynamic() const
  30
  31    Returns whether the Function is of the dynamic type. Dynamic
  32    functions are the ones which are imported from shared libraries and
  33    not structly part of the binary at hand.
  34
  35 .. cpp:function:: uint64_t Function::getStartAddress() const
  36
  37 .. cpp:function:: InformationManager* Function::getManager() const
  38
  39 .. cpp:function:: void Function::addBasicBlock(BasicBlock* block)
  40
  41 .. cpp:function:: const std::map<uint64_t, BasicBlock*>& Function::blocks()
  42
  43 BasicBlock
  44 ----------
  45 .. cpp:class:: BasicBlock
  46
  47 .. cpp:function:: uint64_t BasicBlock::getStartAddress() const
  48 .. cpp:function:: uint64_t BasicBlock::getEndAddress() const
  49 .. cpp:function:: void BasicBlock::setStartAddress(uint64_t address)
  50 .. cpp:function:: void BasicBlock::setEndAddress(uint64_t address)
  51 .. cpp:function:: InformationManager* BasicBlock::getManager() const
  52 .. cpp:function:: uint64_t BasicBlock::getNextBlock(size_t index) const
  53
  54    index may either be 0 or 1 returning the following basic block. It
  55    will only return a value different from ``NULL`` if the last
  56    instruction was a conditional jump. In this case the Block returned
  57    for 1 is the block reached when the jump is not taken
  58
  59 .. cpp:function:: void BasicBlock::setNextBlock(size_t index, uint64_t address)
  60 .. cpp:function:: std::string BasicBlock::getName() const
  61
  62    Returns a generated name for the block. This is only intended for
  63    display. Currently it is ``BLOCK_startaddress_endaddress``. The
  64    block may not be uniqly identified by the name
  65
  66 .. cpp:function:: std::vector<Instruction> BasicBlock::getInstructions() const
  67
  68 Comment
  69 -------
  70
  71 .. cpp:class:: Comment
  72
  73 .. cpp:function:: bool Comment::isLocal() const
  74
  75    Comments, which are valid for every instance of an address are
  76    considered *global* while comments only valid within the
  77    context of the current function are considered *local*
  78
  79 .. cpp:function:: void Comment::setText(const std::string& text)
  80
  81    Updates the text of an comment and takes care of notifying all
  82    consumers of the change.
  83
  84 .. cpp:function:: std::string Comment::getText() const
  85
  86    Returns the current text of the comment without any :doc:`macros` expanded.
  87
  88 .. cpp:function:: uint64_t Comment::getAddress()
  89
  90    Returns address this comment talks about
  91
  92 .. cpp:function:: Function* Comment::getLocation()
  93
  94    Returns the function, the comment talks about, or NULL if the
  95    function is local
  96
  97
  98 InformationManager
  99 ------------------
 100
 101 .. cpp:class:: InformationManager
 102
 103    Core frida information storage. Keeps track of all known
 104    information and notifies the consumers like the GUI of all changes
 105    to its data structures
 106
 107 .. cpp:function:: Disassembler* InformationManager::getDisassembler()
 108
 109 .. cpp:function:: uint64_t InformationManager::getEntryAddress()
 110
 111    Returns the entry address of the binary as read from the ELF / COFF
 112    header or 0 if the information is not available
 113
 114 .. cpp:function:: Function* InformationManager::getFunction(uint64_t address)
 115 .. cpp:function:: std::map<uint64_t, Function*>::const_iterator \
 116                                   InformationManager::beginFunctions()
 117 .. cpp:function:: std::map<uint64_t, Function*>::const_iterator \
 118                                   InformationManager::endFunctions()
 119
 120 .. cpp:function:: BasicBlock* InformationManager::getBasicBlock(uint64_t address)
 121 .. cpp:function:: std::map<uint64_t, BasicBlock*>::const_iterator \
 122                                   InformationManager::beginBasicBlocks()
 123 .. cpp:function:: std::map<uint64_t, BasicBlock*>::const_iterator \
 124                                   InformationManager::endBasicBlocks()
 125
 126 .. cpp:function:: std::pair< \
 127                                   std::multimap<uint64_t, Comment*>::const_iterator, \
 128                                   std::multimap<uint64_t, Comment*>::const_iterator> \
 129                                   InformationManager::getComments(uint64_t address)
 130
 131    There may be several comments for a given address and some of them
 132    may be global comments while others are just local
 133    ones. :cpp:func:`getComments` therefore returns an iterator over
 134    all such :cpp:class:`Comments <Comment>`
 135
 136 .. cpp:function:: std::multimap<uint64_t,Comment*>::const_iterator \
 137                                   InformationManager::beginComments()
 138 .. cpp:function:: std::multimap<uint64_t,Comment*>::const_iterator \
 139                                   InformationManager::endComments()
 140
 141 Disassembler
 142 ------------
 143
 144 .. cpp:class:: Disassembler
 145
 146    Interface implemented by all Disassemblers. Can be used by scripts
 147    to start actions
 148
 149 .. cpp:function:: Function * Disassembler::disassembleFunctionAt(uint64_t address)
 150
 151    Starts recursive disassembling starting at the given ``address``
 152
 153 .. cpp:function:: Function * Disassembler::disassembleFunctionAt(uint64_t address, \
 154    const std::string& name)
 155
 156    The same as :cpp:func:`Disassmebler::disassembleFunctionAt` but
 157    also assigns the given name to the function starting at
 158    ``address``. All further functions will get a default name again.
 159
 160 .. cpp:function:: std::vector<Instruction> \
 161                                   Disassembler::getInstructions(const BasicBlock* block)
 162
 163    Returns a stream of instructions making up the :cpp:class:`BasicBlock`