lldb/bindings/interface/SBTargetDocstrings.i

   1 %feature("docstring",
   2 "Represents the target program running under the debugger.
   3
   4 SBTarget supports module, breakpoint, and watchpoint iterations. For example, ::
   5
   6     for m in target.module_iter():
   7         print m
   8
   9 produces: ::
  10
  11     (x86_64) /Volumes/data/lldb/svn/trunk/test/python_api/lldbutil/iter/a.out
  12     (x86_64) /usr/lib/dyld
  13     (x86_64) /usr/lib/libstdc++.6.dylib
  14     (x86_64) /usr/lib/libSystem.B.dylib
  15     (x86_64) /usr/lib/system/libmathCommon.A.dylib
  16     (x86_64) /usr/lib/libSystem.B.dylib(__commpage)
  17
  18 and, ::
  19
  20     for b in target.breakpoint_iter():
  21         print b
  22
  23 produces: ::
  24
  25     SBBreakpoint: id = 1, file ='main.cpp', line = 66, locations = 1
  26     SBBreakpoint: id = 2, file ='main.cpp', line = 85, locations = 1
  27
  28 and, ::
  29
  30     for wp_loc in target.watchpoint_iter():
  31         print wp_loc
  32
  33 produces: ::
  34
  35     Watchpoint 1: addr = 0x1034ca048 size = 4 state = enabled type = rw
  36         declare @ '/Volumes/data/lldb/svn/trunk/test/python_api/watchpoint/main.c:12'
  37         hit_count = 2     ignore_count = 0"
  38 ) lldb::SBTarget;
  39
  40 %feature("docstring", "
  41     Return the platform object associated with the target.
  42
  43     After return, the platform object should be checked for
  44     validity.
  45
  46     @return
  47         A platform object."
  48 ) lldb::SBTarget::GetPlatform;
  49
  50 %feature("docstring", "
  51     Install any binaries that need to be installed.
  52
  53     This function does nothing when debugging on the host system.
  54     When connected to remote platforms, the target's main executable
  55     and any modules that have their install path set will be
  56     installed on the remote platform. If the main executable doesn't
  57     have an install location set, it will be installed in the remote
  58     platform's working directory.
  59
  60     @return
  61         An error describing anything that went wrong during
  62         installation."
  63 ) lldb::SBTarget::Install;
  64
  65 %feature("docstring", "
  66     Launch a new process.
  67
  68     Launch a new process by spawning a new process using the
  69     target object's executable module's file as the file to launch.
  70     Arguments are given in argv, and the environment variables
  71     are in envp. Standard input and output files can be
  72     optionally re-directed to stdin_path, stdout_path, and
  73     stderr_path.
  74
  75     @param[in] listener
  76         An optional listener that will receive all process events.
  77         If listener is valid then listener will listen to all
  78         process events. If not valid, then this target's debugger
  79         (SBTarget::GetDebugger()) will listen to all process events.
  80
  81     @param[in] argv
  82         The argument array.
  83
  84     @param[in] envp
  85         The environment array.
  86
  87     @param[in] launch_flags
  88         Flags to modify the launch (@see lldb::LaunchFlags)
  89
  90     @param[in] stdin_path
  91         The path to use when re-directing the STDIN of the new
  92         process. If all stdXX_path arguments are NULL, a pseudo
  93         terminal will be used.
  94
  95     @param[in] stdout_path
  96         The path to use when re-directing the STDOUT of the new
  97         process. If all stdXX_path arguments are NULL, a pseudo
  98         terminal will be used.
  99
 100     @param[in] stderr_path
 101         The path to use when re-directing the STDERR of the new
 102         process. If all stdXX_path arguments are NULL, a pseudo
 103         terminal will be used.
 104
 105     @param[in] working_directory
 106         The working directory to have the child process run in
 107
 108     @param[in] launch_flags
 109         Some launch options specified by logical OR'ing
 110         lldb::LaunchFlags enumeration values together.
 111
 112     @param[in] stop_at_entry
 113         If false do not stop the inferior at the entry point.
 114
 115     @param[out]
 116         An error object. Contains the reason if there is some failure.
 117
 118     @return
 119          A process object for the newly created process.
 120
 121     For example,
 122
 123         process = target.Launch(self.dbg.GetListener(), None, None,
 124                                 None, '/tmp/stdout.txt', None,
 125                                 None, 0, False, error)
 126
 127     launches a new process by passing nothing for both the args and the envs
 128     and redirect the standard output of the inferior to the /tmp/stdout.txt
 129     file. It does not specify a working directory so that the debug server
 130     will use its idea of what the current working directory is for the
 131     inferior. Also, we ask the debugger not to stop the inferior at the
 132     entry point. If no breakpoint is specified for the inferior, it should
 133     run to completion if no user interaction is required."
 134 ) lldb::SBTarget::Launch;
 135
 136 %feature("docstring", "
 137     Launch a new process with sensible defaults.
 138
 139     :param argv: The argument array.
 140     :param envp: The environment array.
 141     :param working_directory: The working directory to have the child process run in
 142     :return: The newly created process.
 143     :rtype: SBProcess
 144
 145     A pseudo terminal will be used as stdin/stdout/stderr.
 146     No launch flags are passed and the target's debuger is used as a listener.
 147
 148     For example, ::
 149
 150         process = target.LaunchSimple(['X', 'Y', 'Z'], None, os.getcwd())
 151
 152     launches a new process by passing 'X', 'Y', 'Z' as the args to the
 153     executable."
 154 ) lldb::SBTarget::LaunchSimple;
 155
 156 %feature("docstring", "
 157     Load a core file
 158
 159     @param[in] core_file
 160         File path of the core dump.
 161
 162     @param[out] error
 163         An error explaining what went wrong if the operation fails.
 164         (Optional)
 165
 166     @return
 167          A process object for the newly created core file.
 168
 169     For example,
 170
 171         process = target.LoadCore('./a.out.core')
 172
 173     loads a new core file and returns the process object."
 174 ) lldb::SBTarget::LoadCore;
 175
 176 %feature("docstring", "
 177     Attach to process with pid.
 178
 179     @param[in] listener
 180         An optional listener that will receive all process events.
 181         If listener is valid then listener will listen to all
 182         process events. If not valid, then this target's debugger
 183         (SBTarget::GetDebugger()) will listen to all process events.
 184
 185     @param[in] pid
 186         The process ID to attach to.
 187
 188     @param[out]
 189         An error explaining what went wrong if attach fails.
 190
 191     @return
 192          A process object for the attached process."
 193 ) lldb::SBTarget::AttachToProcessWithID;
 194
 195 %feature("docstring", "
 196     Attach to process with name.
 197
 198     @param[in] listener
 199         An optional listener that will receive all process events.
 200         If listener is valid then listener will listen to all
 201         process events. If not valid, then this target's debugger
 202         (SBTarget::GetDebugger()) will listen to all process events.
 203
 204     @param[in] name
 205         Basename of process to attach to.
 206
 207     @param[in] wait_for
 208         If true wait for a new instance of 'name' to be launched.
 209
 210     @param[out]
 211         An error explaining what went wrong if attach fails.
 212
 213     @return
 214          A process object for the attached process."
 215 ) lldb::SBTarget::AttachToProcessWithName;
 216
 217 %feature("docstring", "
 218     Connect to a remote debug server with url.
 219
 220     @param[in] listener
 221         An optional listener that will receive all process events.
 222         If listener is valid then listener will listen to all
 223         process events. If not valid, then this target's debugger
 224         (SBTarget::GetDebugger()) will listen to all process events.
 225
 226     @param[in] url
 227         The url to connect to, e.g., 'connect://localhost:12345'.
 228
 229     @param[in] plugin_name
 230         The plugin name to be used; can be NULL.
 231
 232     @param[out]
 233         An error explaining what went wrong if the connect fails.
 234
 235     @return
 236          A process object for the connected process."
 237 ) lldb::SBTarget::ConnectRemote;
 238
 239 %feature("docstring", "
 240     Append the path mapping (from -> to) to the target's paths mapping list."
 241 ) lldb::SBTarget::AppendImageSearchPath;
 242
 243 %feature("docstring", "
 244     Find compile units related to this target and passed source
 245     file.
 246
 247     :param sb_file_spec: A :py:class:`lldb::SBFileSpec` object that contains source file
 248         specification.
 249     :return: The symbol contexts for all the matches.
 250     :rtype: SBSymbolContextList"
 251 ) lldb::SBTarget::FindCompileUnits;
 252
 253 %feature("docstring", "
 254     Architecture data byte width accessor
 255
 256     :return: The size in 8-bit (host) bytes of a minimum addressable unit from the Architecture's data bus.
 257
 258     "
 259 ) lldb::SBTarget::GetDataByteSize;
 260
 261 %feature("docstring", "
 262     Architecture code byte width accessor.
 263
 264     :return: The size in 8-bit (host) bytes of a minimum addressable unit from the Architecture's code bus.
 265
 266     "
 267 ) lldb::SBTarget::GetCodeByteSize;
 268
 269 %feature("docstring", "
 270     Find functions by name.
 271
 272     :param name: The name of the function we are looking for.
 273
 274     :param name_type_mask:
 275         A logical OR of one or more FunctionNameType enum bits that
 276         indicate what kind of names should be used when doing the
 277         lookup. Bits include fully qualified names, base names,
 278         C++ methods, or ObjC selectors.
 279         See FunctionNameType for more details.
 280
 281     :return:
 282         A lldb::SBSymbolContextList that gets filled in with all of
 283         the symbol contexts for all the matches."
 284 ) lldb::SBTarget::FindFunctions;
 285
 286 %feature("docstring", "
 287     Find global and static variables by name.
 288
 289     @param[in] name
 290         The name of the global or static variable we are looking
 291         for.
 292
 293     @param[in] max_matches
 294         Allow the number of matches to be limited to max_matches.
 295
 296     @return
 297         A list of matched variables in an SBValueList."
 298 ) lldb::SBTarget::FindGlobalVariables;
 299
 300  %feature("docstring", "
 301     Find the first global (or static) variable by name.
 302
 303     @param[in] name
 304         The name of the global or static variable we are looking
 305         for.
 306
 307     @return
 308         An SBValue that gets filled in with the found variable (if any)."
 309 ) lldb::SBTarget::FindFirstGlobalVariable;
 310
 311 %feature("docstring", "
 312     Resolve a current file address into a section offset address.
 313
 314     @param[in] file_addr
 315
 316     @return
 317         An SBAddress which will be valid if..."
 318 ) lldb::SBTarget::ResolveFileAddress;
 319
 320 %feature("docstring", "
 321     Read target memory. If a target process is running then memory
 322     is read from here. Otherwise the memory is read from the object
 323     files. For a target whose bytes are sized as a multiple of host
 324     bytes, the data read back will preserve the target's byte order.
 325
 326     @param[in] addr
 327         A target address to read from.
 328
 329     @param[out] buf
 330         The buffer to read memory into.
 331
 332     @param[in] size
 333         The maximum number of host bytes to read in the buffer passed
 334         into this call
 335
 336     @param[out] error
 337         Error information is written here if the memory read fails.
 338
 339     @return
 340         The amount of data read in host bytes."
 341 ) lldb::SBTarget::ReadMemory;
 342
 343 %feature("docstring", "
 344     Create a breakpoint using a scripted resolver.
 345
 346     @param[in] class_name
 347        This is the name of the class that implements a scripted resolver.
 348        The class should have the following signature: ::
 349
 350            class Resolver:
 351                def __init__(self, bkpt, extra_args):
 352                    # bkpt - the breakpoint for which this is the resolver.  When
 353                    # the resolver finds an interesting address, call AddLocation
 354                    # on this breakpoint to add it.
 355                    #
 356                    # extra_args - an SBStructuredData that can be used to
 357                    # parametrize this instance.  Same as the extra_args passed
 358                    # to BreakpointCreateFromScript.
 359
 360                def __get_depth__ (self):
 361                    # This is optional, but if defined, you should return the
 362                    # depth at which you want the callback to be called.  The
 363                    # available options are:
 364                    #    lldb.eSearchDepthModule
 365                    #    lldb.eSearchDepthCompUnit
 366                    # The default if you don't implement this method is
 367                    # eSearchDepthModule.
 368
 369                def __callback__(self, sym_ctx):
 370                    # sym_ctx - an SBSymbolContext that is the cursor in the
 371                    # search through the program to resolve breakpoints.
 372                    # The sym_ctx will be filled out to the depth requested in
 373                    # __get_depth__.
 374                    # Look in this sym_ctx for new breakpoint locations,
 375                    # and if found use bkpt.AddLocation to add them.
 376                    # Note, you will only get called for modules/compile_units that
 377                    # pass the SearchFilter provided by the module_list & file_list
 378                    # passed into BreakpointCreateFromScript.
 379
 380                def get_short_help(self):
 381                    # Optional, but if implemented return a short string that will
 382                    # be printed at the beginning of the break list output for the
 383                    # breakpoint.
 384
 385     @param[in] extra_args
 386        This is an SBStructuredData object that will get passed to the
 387        constructor of the class in class_name.  You can use this to
 388        reuse the same class, parametrizing it with entries from this
 389        dictionary.
 390
 391     @param module_list
 392        If this is non-empty, this will be used as the module filter in the
 393        SearchFilter created for this breakpoint.
 394
 395     @param file_list
 396        If this is non-empty, this will be used as the comp unit filter in the
 397        SearchFilter created for this breakpoint.
 398
 399     @return
 400         An SBBreakpoint that will set locations based on the logic in the
 401         resolver's search callback."
 402 ) lldb::SBTarget::BreakpointCreateFromScript;
 403
 404 %feature("docstring", "
 405     Read breakpoints from source_file and return the newly created
 406     breakpoints in bkpt_list.
 407
 408     @param[in] source_file
 409        The file from which to read the breakpoints
 410
 411     @param[out] bkpt_list
 412        A list of the newly created breakpoints.
 413
 414     @return
 415         An SBError detailing any errors in reading in the breakpoints."
 416 ) lldb::SBTarget::BreakpointsCreateFromFile;
 417
 418 %feature("docstring", "
 419     Read breakpoints from source_file and return the newly created
 420     breakpoints in bkpt_list.
 421
 422     @param[in] source_file
 423        The file from which to read the breakpoints
 424
 425     @param[in] matching_names
 426        Only read in breakpoints whose names match one of the names in this
 427        list.
 428
 429     @param[out] bkpt_list
 430        A list of the newly created breakpoints.
 431
 432     @return
 433         An SBError detailing any errors in reading in the breakpoints."
 434 ) lldb::SBTarget::BreakpointsCreateFromFile;
 435
 436 %feature("docstring", "
 437     Write breakpoints to dest_file.
 438
 439     @param[in] dest_file
 440        The file to which to write the breakpoints.
 441
 442     @return
 443         An SBError detailing any errors in writing in the breakpoints."
 444 ) lldb::SBTarget::BreakkpointsWriteToFile;
 445
 446 %feature("docstring", "
 447     Write breakpoints listed in bkpt_list to dest_file.
 448
 449     @param[in] dest_file
 450        The file to which to write the breakpoints.
 451
 452     @param[in] bkpt_list
 453        Only write breakpoints from this list.
 454
 455     @param[in] append
 456        If true, append the breakpoints in bkpt_list to the others
 457        serialized in dest_file.  If dest_file doesn't exist, then a new
 458        file will be created and the breakpoints in bkpt_list written to it.
 459
 460     @return
 461         An SBError detailing any errors in writing in the breakpoints."
 462 ) lldb::SBTarget::BreakpointsWriteToFile;
 463
 464 %feature("docstring", "
 465     Create an SBValue with the given name by treating the memory starting at addr as an entity of type.
 466
 467     @param[in] name
 468         The name of the resultant SBValue
 469
 470     @param[in] addr
 471         The address of the start of the memory region to be used.
 472
 473     @param[in] type
 474         The type to use to interpret the memory starting at addr.
 475
 476     @return
 477         An SBValue of the given type, may be invalid if there was an error reading
 478         the underlying memory."
 479 ) lldb::SBTarget::CreateValueFromAddress;
 480
 481 %feature("docstring", "
 482     Disassemble a specified number of instructions starting at an address.
 483
 484     :param base_addr: the address to start disassembly from.
 485     :param count: the number of instructions to disassemble.
 486     :param flavor_string: may be 'intel' or 'att' on x86 targets to specify that style of disassembly.
 487     :rtype: SBInstructionList
 488     "
 489 ) lldb::SBTarget::ReadInstructions;
 490
 491 %feature("docstring", "
 492     Disassemble the bytes in a buffer and return them in an SBInstructionList.
 493
 494     :param base_addr: used for symbolicating the offsets in the byte stream when disassembling.
 495     :param buf: bytes to be disassembled.
 496     :param size: (C++) size of the buffer.
 497     :rtype: SBInstructionList
 498     "
 499 ) lldb::SBTarget::GetInstructions;
 500
 501 %feature("docstring", "
 502     Disassemble the bytes in a buffer and return them in an SBInstructionList, with a supplied flavor.
 503
 504     :param base_addr: used for symbolicating the offsets in the byte stream when disassembling.
 505     :param flavor:  may be 'intel' or 'att' on x86 targets to specify that style of disassembly.
 506     :param buf: bytes to be disassembled.
 507     :param size: (C++) size of the buffer.
 508     :rtype: SBInstructionList
 509     "
 510 ) lldb::SBTarget::GetInstructionsWithFlavor;
 511
 512 %feature("docstring", "
 513     Returns true if the module has been loaded in this `SBTarget`.
 514     A module can be loaded either by the dynamic loader or by being manually
 515     added to the target (see `SBTarget.AddModule` and the ``target module add`` command).
 516
 517     :rtype: bool
 518     "
 519 ) lldb::SBTarget::IsLoaded;