lldb/bindings/interface/SBModuleDocstrings.i

   1 %feature("docstring",
   2 "Represents an executable image and its associated object and symbol files.
   3
   4 The module is designed to be able to select a single slice of an
   5 executable image as it would appear on disk and during program
   6 execution.
   7
   8 You can retrieve SBModule from :py:class:`SBSymbolContext` , which in turn is available
   9 from SBFrame.
  10
  11 SBModule supports symbol iteration, for example, ::
  12
  13     for symbol in module:
  14         name = symbol.GetName()
  15         saddr = symbol.GetStartAddress()
  16         eaddr = symbol.GetEndAddress()
  17
  18 and rich comparison methods which allow the API program to use, ::
  19
  20     if thisModule == thatModule:
  21         print('This module is the same as that module')
  22
  23 to test module equality.  A module also contains object file sections, namely
  24 :py:class:`SBSection` .  SBModule supports section iteration through section_iter(), for
  25 example, ::
  26
  27     print('Number of sections: %d' % module.GetNumSections())
  28     for sec in module.section_iter():
  29         print(sec)
  30
  31 And to iterate the symbols within a SBSection, use symbol_in_section_iter(), ::
  32
  33     # Iterates the text section and prints each symbols within each sub-section.
  34     for subsec in text_sec:
  35         print(INDENT + repr(subsec))
  36         for sym in exe_module.symbol_in_section_iter(subsec):
  37             print(INDENT2 + repr(sym))
  38             print(INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType()))
  39
  40 produces this following output: ::
  41
  42     [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text
  43         id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870)
  44         symbol type: code
  45         id = {0x00000008}, name = 'thread_func(void*)', range = [0x0000000100001870-0x00000001000019b0)
  46         symbol type: code
  47         id = {0x0000000c}, name = 'main', range = [0x00000001000019b0-0x0000000100001d5c)
  48         symbol type: code
  49         id = {0x00000023}, name = 'start', address = 0x0000000100001780
  50         symbol type: code
  51     [0x0000000100001d5c-0x0000000100001da4) a.out.__TEXT.__stubs
  52         id = {0x00000024}, name = '__stack_chk_fail', range = [0x0000000100001d5c-0x0000000100001d62)
  53         symbol type: trampoline
  54         id = {0x00000028}, name = 'exit', range = [0x0000000100001d62-0x0000000100001d68)
  55         symbol type: trampoline
  56         id = {0x00000029}, name = 'fflush', range = [0x0000000100001d68-0x0000000100001d6e)
  57         symbol type: trampoline
  58         id = {0x0000002a}, name = 'fgets', range = [0x0000000100001d6e-0x0000000100001d74)
  59         symbol type: trampoline
  60         id = {0x0000002b}, name = 'printf', range = [0x0000000100001d74-0x0000000100001d7a)
  61         symbol type: trampoline
  62         id = {0x0000002c}, name = 'pthread_create', range = [0x0000000100001d7a-0x0000000100001d80)
  63         symbol type: trampoline
  64         id = {0x0000002d}, name = 'pthread_join', range = [0x0000000100001d80-0x0000000100001d86)
  65         symbol type: trampoline
  66         id = {0x0000002e}, name = 'pthread_mutex_lock', range = [0x0000000100001d86-0x0000000100001d8c)
  67         symbol type: trampoline
  68         id = {0x0000002f}, name = 'pthread_mutex_unlock', range = [0x0000000100001d8c-0x0000000100001d92)
  69         symbol type: trampoline
  70         id = {0x00000030}, name = 'rand', range = [0x0000000100001d92-0x0000000100001d98)
  71         symbol type: trampoline
  72         id = {0x00000031}, name = 'strtoul', range = [0x0000000100001d98-0x0000000100001d9e)
  73         symbol type: trampoline
  74         id = {0x00000032}, name = 'usleep', range = [0x0000000100001d9e-0x0000000100001da4)
  75         symbol type: trampoline
  76     [0x0000000100001da4-0x0000000100001e2c) a.out.__TEXT.__stub_helper
  77     [0x0000000100001e2c-0x0000000100001f10) a.out.__TEXT.__cstring
  78     [0x0000000100001f10-0x0000000100001f68) a.out.__TEXT.__unwind_info
  79     [0x0000000100001f68-0x0000000100001ff8) a.out.__TEXT.__eh_frame
  80 "
  81 ) lldb::SBModule;
  82
  83 %feature("docstring", "
  84     Check if the module is file backed.
  85
  86     @return
  87
  88         True, if the module is backed by an object file on disk.
  89         False, if the module is backed by an object file in memory."
  90 ) lldb::SBModule::IsFileBacked;
  91
  92 %feature("docstring", "
  93     Get const accessor for the module file specification.
  94
  95     This function returns the file for the module on the host system
  96     that is running LLDB. This can differ from the path on the
  97     platform since we might be doing remote debugging.
  98
  99     @return
 100         A const reference to the file specification object."
 101 ) lldb::SBModule::GetFileSpec;
 102
 103 %feature("docstring", "
 104     Get accessor for the module platform file specification.
 105
 106     Platform file refers to the path of the module as it is known on
 107     the remote system on which it is being debugged. For local
 108     debugging this is always the same as Module::GetFileSpec(). But
 109     remote debugging might mention a file '/usr/lib/liba.dylib'
 110     which might be locally downloaded and cached. In this case the
 111     platform file could be something like:
 112     '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
 113     The file could also be cached in a local developer kit directory.
 114
 115     @return
 116         A const reference to the file specification object."
 117 ) lldb::SBModule::GetPlatformFileSpec;
 118
 119 %feature("docstring", "Returns the UUID of the module as a Python string."
 120 ) lldb::SBModule::GetUUIDString;
 121
 122 %feature("docstring", "
 123     Find compile units related to this module and passed source
 124     file.
 125
 126     @param[in] sb_file_spec
 127         A :py:class:`SBFileSpec` object that contains source file
 128         specification.
 129
 130     @return
 131         A :py:class:`SBSymbolContextList` that gets filled in with all of
 132         the symbol contexts for all the matches."
 133 ) lldb::SBModule::FindCompileUnits;
 134
 135 %feature("docstring", "
 136     Find functions by name.
 137
 138     @param[in] name
 139         The name of the function we are looking for.
 140
 141     @param[in] name_type_mask
 142         A logical OR of one or more FunctionNameType enum bits that
 143         indicate what kind of names should be used when doing the
 144         lookup. Bits include fully qualified names, base names,
 145         C++ methods, or ObjC selectors.
 146         See FunctionNameType for more details.
 147
 148     @return
 149         A symbol context list that gets filled in with all of the
 150         matches."
 151 ) lldb::SBModule::FindFunctions;
 152
 153 %feature("docstring", "
 154     Get all types matching type_mask from debug info in this
 155     module.
 156
 157     @param[in] type_mask
 158         A bitfield that consists of one or more bits logically OR'ed
 159         together from the lldb::TypeClass enumeration. This allows
 160         you to request only structure types, or only class, struct
 161         and union types. Passing in lldb::eTypeClassAny will return
 162         all types found in the debug information for this module.
 163
 164     @return
 165         A list of types in this module that match type_mask"
 166 ) lldb::SBModule::GetTypes;
 167
 168 %feature("docstring", "
 169     Find global and static variables by name.
 170
 171     @param[in] target
 172         A valid SBTarget instance representing the debuggee.
 173
 174     @param[in] name
 175         The name of the global or static variable we are looking
 176         for.
 177
 178     @param[in] max_matches
 179         Allow the number of matches to be limited to max_matches.
 180
 181     @return
 182         A list of matched variables in an SBValueList."
 183 ) lldb::SBModule::FindGlobalVariables;
 184
 185 %feature("docstring", "
 186     Find the first global (or static) variable by name.
 187
 188     @param[in] target
 189         A valid SBTarget instance representing the debuggee.
 190
 191     @param[in] name
 192         The name of the global or static variable we are looking
 193         for.
 194
 195     @return
 196         An SBValue that gets filled in with the found variable (if any)."
 197 ) lldb::SBModule::FindFirstGlobalVariable;
 198
 199 %feature("docstring", "
 200     Returns the number of modules in the module cache. This is an
 201     implementation detail exposed for testing and should not be relied upon.
 202
 203     @return
 204         The number of modules in the module cache."
 205 ) lldb::SBModule::GetNumberAllocatedModules;
 206
 207 %feature("docstring", "
 208     Removes all modules which are no longer needed by any part of LLDB from
 209     the module cache.
 210
 211     This is an implementation detail exposed for testing and should not be
 212     relied upon. Use SBDebugger::MemoryPressureDetected instead to reduce
 213     LLDB's memory consumption during execution.
 214 ") lldb::SBModule::GarbageCollectAllocatedModules;