1359575Sdim//===-- SWIG Interface for SBProcess ----------------------------*- C++ -*-===// 2359575Sdim// 3359575Sdim// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4359575Sdim// See https://llvm.org/LICENSE.txt for license information. 5359575Sdim// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6359575Sdim// 7359575Sdim//===----------------------------------------------------------------------===// 8359575Sdim 9359575Sdimnamespace lldb { 10359575Sdim 11359575Sdim%feature("docstring", 12359575Sdim"Represents the process associated with the target program. 13359575Sdim 14359575SdimSBProcess supports thread iteration. For example (from test/lldbutil.py), 15359575Sdim 16359575Sdim# ================================================== 17359575Sdim# Utility functions related to Threads and Processes 18359575Sdim# ================================================== 19359575Sdim 20359575Sdimdef get_stopped_threads(process, reason): 21359575Sdim '''Returns the thread(s) with the specified stop reason in a list. 22359575Sdim 23359575Sdim The list can be empty if no such thread exists. 24359575Sdim ''' 25359575Sdim threads = [] 26359575Sdim for t in process: 27359575Sdim if t.GetStopReason() == reason: 28359575Sdim threads.append(t) 29359575Sdim return threads 30359575Sdim 31359575Sdim... 32359575Sdim" 33359575Sdim) SBProcess; 34359575Sdimclass SBProcess 35359575Sdim{ 36359575Sdimpublic: 37359575Sdim enum 38359575Sdim { 39359575Sdim eBroadcastBitStateChanged = (1 << 0), 40359575Sdim eBroadcastBitInterrupt = (1 << 1), 41359575Sdim eBroadcastBitSTDOUT = (1 << 2), 42359575Sdim eBroadcastBitSTDERR = (1 << 3), 43359575Sdim eBroadcastBitProfileData = (1 << 4), 44359575Sdim eBroadcastBitStructuredData = (1 << 5) 45359575Sdim }; 46359575Sdim 47359575Sdim SBProcess (); 48359575Sdim 49359575Sdim SBProcess (const lldb::SBProcess& rhs); 50359575Sdim 51359575Sdim ~SBProcess(); 52359575Sdim 53359575Sdim static const char * 54359575Sdim GetBroadcasterClassName (); 55359575Sdim 56359575Sdim const char * 57359575Sdim GetPluginName (); 58359575Sdim 59359575Sdim const char * 60359575Sdim GetShortPluginName (); 61359575Sdim 62359575Sdim void 63359575Sdim Clear (); 64359575Sdim 65359575Sdim bool 66359575Sdim IsValid() const; 67359575Sdim 68359575Sdim explicit operator bool() const; 69359575Sdim 70359575Sdim lldb::SBTarget 71359575Sdim GetTarget() const; 72359575Sdim 73359575Sdim lldb::ByteOrder 74359575Sdim GetByteOrder() const; 75359575Sdim 76359575Sdim %feature("autodoc", " 77359575Sdim Writes data into the current process's stdin. API client specifies a Python 78359575Sdim string as the only argument.") PutSTDIN; 79359575Sdim size_t 80359575Sdim PutSTDIN (const char *src, size_t src_len); 81359575Sdim 82359575Sdim %feature("autodoc", " 83359575Sdim Reads data from the current process's stdout stream. API client specifies 84359575Sdim the size of the buffer to read data into. It returns the byte buffer in a 85359575Sdim Python string.") GetSTDOUT; 86359575Sdim size_t 87359575Sdim GetSTDOUT (char *dst, size_t dst_len) const; 88359575Sdim 89359575Sdim %feature("autodoc", " 90359575Sdim Reads data from the current process's stderr stream. API client specifies 91359575Sdim the size of the buffer to read data into. It returns the byte buffer in a 92359575Sdim Python string.") GetSTDERR; 93359575Sdim size_t 94359575Sdim GetSTDERR (char *dst, size_t dst_len) const; 95359575Sdim 96359575Sdim size_t 97359575Sdim GetAsyncProfileData(char *dst, size_t dst_len) const; 98359575Sdim 99359575Sdim void 100359575Sdim ReportEventState (const lldb::SBEvent &event, SBFile out) const; 101359575Sdim 102359575Sdim void 103359575Sdim ReportEventState (const lldb::SBEvent &event, FileSP BORROWED) const; 104359575Sdim 105359575Sdim void 106359575Sdim AppendEventStateReport (const lldb::SBEvent &event, lldb::SBCommandReturnObject &result); 107359575Sdim 108359575Sdim %feature("docstring", " 109359575Sdim Remote connection related functions. These will fail if the 110359575Sdim process is not in eStateConnected. They are intended for use 111359575Sdim when connecting to an externally managed debugserver instance.") RemoteAttachToProcessWithID; 112359575Sdim bool 113359575Sdim RemoteAttachToProcessWithID (lldb::pid_t pid, 114359575Sdim lldb::SBError& error); 115359575Sdim 116359575Sdim %feature("docstring", 117359575Sdim "See SBTarget.Launch for argument description and usage." 118359575Sdim ) RemoteLaunch; 119359575Sdim bool 120359575Sdim RemoteLaunch (char const **argv, 121359575Sdim char const **envp, 122359575Sdim const char *stdin_path, 123359575Sdim const char *stdout_path, 124359575Sdim const char *stderr_path, 125359575Sdim const char *working_directory, 126359575Sdim uint32_t launch_flags, 127359575Sdim bool stop_at_entry, 128359575Sdim lldb::SBError& error); 129359575Sdim 130359575Sdim //------------------------------------------------------------------ 131359575Sdim // Thread related functions 132359575Sdim //------------------------------------------------------------------ 133359575Sdim uint32_t 134359575Sdim GetNumThreads (); 135359575Sdim 136359575Sdim %feature("autodoc", " 137359575Sdim Returns the INDEX'th thread from the list of current threads. The index 138359575Sdim of a thread is only valid for the current stop. For a persistent thread 139359575Sdim identifier use either the thread ID or the IndexID. See help on SBThread 140359575Sdim for more details.") GetThreadAtIndex; 141359575Sdim lldb::SBThread 142359575Sdim GetThreadAtIndex (size_t index); 143359575Sdim 144359575Sdim %feature("autodoc", " 145359575Sdim Returns the thread with the given thread ID.") GetThreadByID; 146359575Sdim lldb::SBThread 147359575Sdim GetThreadByID (lldb::tid_t sb_thread_id); 148359575Sdim 149359575Sdim %feature("autodoc", " 150359575Sdim Returns the thread with the given thread IndexID.") GetThreadByIndexID; 151359575Sdim lldb::SBThread 152359575Sdim GetThreadByIndexID (uint32_t index_id); 153359575Sdim 154359575Sdim %feature("autodoc", " 155359575Sdim Returns the currently selected thread.") GetSelectedThread; 156359575Sdim lldb::SBThread 157359575Sdim GetSelectedThread () const; 158359575Sdim 159359575Sdim %feature("autodoc", " 160359575Sdim Lazily create a thread on demand through the current OperatingSystem plug-in, if the current OperatingSystem plug-in supports it.") CreateOSPluginThread; 161359575Sdim lldb::SBThread 162359575Sdim CreateOSPluginThread (lldb::tid_t tid, lldb::addr_t context); 163359575Sdim 164359575Sdim bool 165359575Sdim SetSelectedThread (const lldb::SBThread &thread); 166359575Sdim 167359575Sdim bool 168359575Sdim SetSelectedThreadByID (lldb::tid_t tid); 169359575Sdim 170359575Sdim bool 171359575Sdim SetSelectedThreadByIndexID (uint32_t index_id); 172359575Sdim 173359575Sdim //------------------------------------------------------------------ 174359575Sdim // Queue related functions 175359575Sdim //------------------------------------------------------------------ 176359575Sdim uint32_t 177359575Sdim GetNumQueues (); 178359575Sdim 179359575Sdim lldb::SBQueue 180359575Sdim GetQueueAtIndex (uint32_t index); 181359575Sdim 182359575Sdim //------------------------------------------------------------------ 183359575Sdim // Stepping related functions 184359575Sdim //------------------------------------------------------------------ 185359575Sdim 186359575Sdim lldb::StateType 187359575Sdim GetState (); 188359575Sdim 189359575Sdim int 190359575Sdim GetExitStatus (); 191359575Sdim 192359575Sdim const char * 193359575Sdim GetExitDescription (); 194359575Sdim 195359575Sdim %feature("autodoc", " 196359575Sdim Returns the process ID of the process.") GetProcessID; 197359575Sdim lldb::pid_t 198359575Sdim GetProcessID (); 199359575Sdim 200359575Sdim %feature("autodoc", " 201359575Sdim Returns an integer ID that is guaranteed to be unique across all process instances. This is not the process ID, just a unique integer for comparison and caching purposes.") GetUniqueID; 202359575Sdim uint32_t 203359575Sdim GetUniqueID(); 204359575Sdim 205359575Sdim uint32_t 206359575Sdim GetAddressByteSize() const; 207359575Sdim 208359575Sdim %feature("docstring", " 209359575Sdim Kills the process and shuts down all threads that were spawned to 210359575Sdim track and monitor process.") Destroy; 211359575Sdim lldb::SBError 212359575Sdim Destroy (); 213359575Sdim 214359575Sdim lldb::SBError 215359575Sdim Continue (); 216359575Sdim 217359575Sdim lldb::SBError 218359575Sdim Stop (); 219359575Sdim 220359575Sdim %feature("docstring", "Same as Destroy(self).") Destroy; 221359575Sdim lldb::SBError 222359575Sdim Kill (); 223359575Sdim 224359575Sdim lldb::SBError 225359575Sdim Detach (); 226359575Sdim 227359575Sdim %feature("docstring", "Sends the process a unix signal.") Signal; 228359575Sdim lldb::SBError 229359575Sdim Signal (int signal); 230359575Sdim 231359575Sdim lldb::SBUnixSignals 232359575Sdim GetUnixSignals(); 233359575Sdim 234359575Sdim %feature("docstring", " 235359575Sdim Returns a stop id that will increase every time the process executes. If 236359575Sdim include_expression_stops is true, then stops caused by expression evaluation 237359575Sdim will cause the returned value to increase, otherwise the counter returned will 238359575Sdim only increase when execution is continued explicitly by the user. Note, the value 239359575Sdim will always increase, but may increase by more than one per stop.") GetStopID; 240359575Sdim uint32_t 241359575Sdim GetStopID(bool include_expression_stops = false); 242359575Sdim 243359575Sdim void 244359575Sdim SendAsyncInterrupt(); 245359575Sdim 246359575Sdim %feature("autodoc", " 247359575Sdim Reads memory from the current process's address space and removes any 248359575Sdim traps that may have been inserted into the memory. It returns the byte 249359575Sdim buffer in a Python string. Example: 250359575Sdim 251359575Sdim # Read 4 bytes from address 'addr' and assume error.Success() is True. 252359575Sdim content = process.ReadMemory(addr, 4, error) 253359575Sdim new_bytes = bytearray(content)") ReadMemory; 254359575Sdim size_t 255359575Sdim ReadMemory (addr_t addr, void *buf, size_t size, lldb::SBError &error); 256359575Sdim 257359575Sdim %feature("autodoc", " 258359575Sdim Writes memory to the current process's address space and maintains any 259359575Sdim traps that might be present due to software breakpoints. Example: 260359575Sdim 261359575Sdim # Create a Python string from the byte array. 262359575Sdim new_value = str(bytes) 263359575Sdim result = process.WriteMemory(addr, new_value, error) 264359575Sdim if not error.Success() or result != len(bytes): 265359575Sdim print('SBProcess.WriteMemory() failed!')") WriteMemory; 266359575Sdim size_t 267359575Sdim WriteMemory (addr_t addr, const void *buf, size_t size, lldb::SBError &error); 268359575Sdim 269359575Sdim %feature("autodoc", " 270359575Sdim Reads a NULL terminated C string from the current process's address space. 271359575Sdim It returns a python string of the exact length, or truncates the string if 272359575Sdim the maximum character limit is reached. Example: 273359575Sdim 274359575Sdim # Read a C string of at most 256 bytes from address '0x1000' 275359575Sdim error = lldb.SBError() 276359575Sdim cstring = process.ReadCStringFromMemory(0x1000, 256, error) 277359575Sdim if error.Success(): 278359575Sdim print('cstring: ', cstring) 279359575Sdim else 280359575Sdim print('error: ', error)") ReadCStringFromMemory; 281359575Sdim 282359575Sdim size_t 283359575Sdim ReadCStringFromMemory (addr_t addr, void *char_buf, size_t size, lldb::SBError &error); 284359575Sdim 285359575Sdim %feature("autodoc", " 286359575Sdim Reads an unsigned integer from memory given a byte size and an address. 287359575Sdim Returns the unsigned integer that was read. Example: 288359575Sdim 289359575Sdim # Read a 4 byte unsigned integer from address 0x1000 290359575Sdim error = lldb.SBError() 291359575Sdim uint = ReadUnsignedFromMemory(0x1000, 4, error) 292359575Sdim if error.Success(): 293359575Sdim print('integer: %u' % uint) 294359575Sdim else 295359575Sdim print('error: ', error)") ReadUnsignedFromMemory; 296359575Sdim 297359575Sdim uint64_t 298359575Sdim ReadUnsignedFromMemory (addr_t addr, uint32_t byte_size, lldb::SBError &error); 299359575Sdim 300359575Sdim %feature("autodoc", " 301359575Sdim Reads a pointer from memory from an address and returns the value. Example: 302359575Sdim 303359575Sdim # Read a pointer from address 0x1000 304359575Sdim error = lldb.SBError() 305359575Sdim ptr = ReadPointerFromMemory(0x1000, error) 306359575Sdim if error.Success(): 307359575Sdim print('pointer: 0x%x' % ptr) 308359575Sdim else 309359575Sdim print('error: ', error)") ReadPointerFromMemory; 310359575Sdim 311359575Sdim lldb::addr_t 312359575Sdim ReadPointerFromMemory (addr_t addr, lldb::SBError &error); 313359575Sdim 314359575Sdim 315359575Sdim // Events 316359575Sdim static lldb::StateType 317359575Sdim GetStateFromEvent (const lldb::SBEvent &event); 318359575Sdim 319359575Sdim static bool 320359575Sdim GetRestartedFromEvent (const lldb::SBEvent &event); 321359575Sdim 322359575Sdim static size_t 323359575Sdim GetNumRestartedReasonsFromEvent (const lldb::SBEvent &event); 324359575Sdim 325359575Sdim static const char * 326359575Sdim GetRestartedReasonAtIndexFromEvent (const lldb::SBEvent &event, size_t idx); 327359575Sdim 328359575Sdim static lldb::SBProcess 329359575Sdim GetProcessFromEvent (const lldb::SBEvent &event); 330359575Sdim 331359575Sdim static bool 332359575Sdim GetInterruptedFromEvent (const lldb::SBEvent &event); 333359575Sdim 334359575Sdim static lldb::SBStructuredData 335359575Sdim GetStructuredDataFromEvent (const lldb::SBEvent &event); 336359575Sdim 337359575Sdim static bool 338359575Sdim EventIsProcessEvent (const lldb::SBEvent &event); 339359575Sdim 340359575Sdim static bool 341359575Sdim EventIsStructuredDataEvent (const lldb::SBEvent &event); 342359575Sdim 343359575Sdim lldb::SBBroadcaster 344359575Sdim GetBroadcaster () const; 345359575Sdim 346359575Sdim bool 347359575Sdim GetDescription (lldb::SBStream &description); 348359575Sdim 349359575Sdim uint32_t 350359575Sdim GetNumSupportedHardwareWatchpoints (lldb::SBError &error) const; 351359575Sdim 352359575Sdim uint32_t 353359575Sdim LoadImage (lldb::SBFileSpec &image_spec, lldb::SBError &error); 354359575Sdim 355359575Sdim %feature("autodoc", " 356359575Sdim Load the library whose filename is given by image_spec looking in all the 357359575Sdim paths supplied in the paths argument. If successful, return a token that 358359575Sdim can be passed to UnloadImage and fill loaded_path with the path that was 359359575Sdim successfully loaded. On failure, return 360359575Sdim lldb.LLDB_INVALID_IMAGE_TOKEN.") LoadImageUsingPaths; 361359575Sdim uint32_t 362359575Sdim LoadImageUsingPaths(const lldb::SBFileSpec &image_spec, 363359575Sdim SBStringList &paths, 364359575Sdim lldb::SBFileSpec &loaded_path, 365359575Sdim SBError &error); 366359575Sdim 367359575Sdim lldb::SBError 368359575Sdim UnloadImage (uint32_t image_token); 369359575Sdim 370359575Sdim lldb::SBError 371359575Sdim SendEventData (const char *event_data); 372359575Sdim 373359575Sdim %feature("autodoc", " 374359575Sdim Return the number of different thread-origin extended backtraces 375359575Sdim this process can support as a uint32_t. 376359575Sdim When the process is stopped and you have an SBThread, lldb may be 377359575Sdim able to show a backtrace of when that thread was originally created, 378359575Sdim or the work item was enqueued to it (in the case of a libdispatch 379359575Sdim queue).") GetNumExtendedBacktraceTypes; 380359575Sdim 381359575Sdim uint32_t 382359575Sdim GetNumExtendedBacktraceTypes (); 383359575Sdim 384359575Sdim %feature("autodoc", " 385359575Sdim Takes an index argument, returns the name of one of the thread-origin 386359575Sdim extended backtrace methods as a str.") GetExtendedBacktraceTypeAtIndex; 387359575Sdim 388359575Sdim const char * 389359575Sdim GetExtendedBacktraceTypeAtIndex (uint32_t idx); 390359575Sdim 391359575Sdim lldb::SBThreadCollection 392359575Sdim GetHistoryThreads (addr_t addr); 393359575Sdim 394359575Sdim bool 395359575Sdim IsInstrumentationRuntimePresent(lldb::InstrumentationRuntimeType type); 396359575Sdim 397359575Sdim lldb::SBError 398359575Sdim SaveCore(const char *file_name); 399359575Sdim 400359575Sdim lldb::SBTrace 401359575Sdim StartTrace(SBTraceOptions &options, lldb::SBError &error); 402359575Sdim 403359575Sdim lldb::SBError 404359575Sdim GetMemoryRegionInfo(lldb::addr_t load_addr, lldb::SBMemoryRegionInfo ®ion_info); 405359575Sdim 406359575Sdim lldb::SBMemoryRegionInfoList 407359575Sdim GetMemoryRegions(); 408359575Sdim 409359575Sdim %feature("autodoc", " 410359575Sdim Get information about the process. 411359575Sdim Valid process info will only be returned when the process is alive, 412359575Sdim use IsValid() to check if the info returned is valid. 413359575Sdim 414359575Sdim process_info = process.GetProcessInfo() 415359575Sdim if process_info.IsValid(): 416359575Sdim process_info.GetProcessID()") GetProcessInfo; 417359575Sdim lldb::SBProcessInfo 418359575Sdim GetProcessInfo(); 419359575Sdim 420359575Sdim STRING_EXTENSION(SBProcess) 421359575Sdim 422359575Sdim#ifdef SWIGPYTHON 423359575Sdim %pythoncode %{ 424359575Sdim def __get_is_alive__(self): 425359575Sdim '''Returns "True" if the process is currently alive, "False" otherwise''' 426359575Sdim s = self.GetState() 427359575Sdim if (s == eStateAttaching or 428359575Sdim s == eStateLaunching or 429359575Sdim s == eStateStopped or 430359575Sdim s == eStateRunning or 431359575Sdim s == eStateStepping or 432359575Sdim s == eStateCrashed or 433359575Sdim s == eStateSuspended): 434359575Sdim return True 435359575Sdim return False 436359575Sdim 437359575Sdim def __get_is_running__(self): 438359575Sdim '''Returns "True" if the process is currently running, "False" otherwise''' 439359575Sdim state = self.GetState() 440359575Sdim if state == eStateRunning or state == eStateStepping: 441359575Sdim return True 442359575Sdim return False 443359575Sdim 444359575Sdim def __get_is_stopped__(self): 445359575Sdim '''Returns "True" if the process is currently stopped, "False" otherwise''' 446359575Sdim state = self.GetState() 447359575Sdim if state == eStateStopped or state == eStateCrashed or state == eStateSuspended: 448359575Sdim return True 449359575Sdim return False 450359575Sdim 451359575Sdim class threads_access(object): 452359575Sdim '''A helper object that will lazily hand out thread for a process when supplied an index.''' 453359575Sdim def __init__(self, sbprocess): 454359575Sdim self.sbprocess = sbprocess 455359575Sdim 456359575Sdim def __len__(self): 457359575Sdim if self.sbprocess: 458359575Sdim return int(self.sbprocess.GetNumThreads()) 459359575Sdim return 0 460359575Sdim 461359575Sdim def __getitem__(self, key): 462359575Sdim if type(key) is int and key < len(self): 463359575Sdim return self.sbprocess.GetThreadAtIndex(key) 464359575Sdim return None 465359575Sdim 466359575Sdim def get_threads_access_object(self): 467359575Sdim '''An accessor function that returns a modules_access() object which allows lazy thread access from a lldb.SBProcess object.''' 468359575Sdim return self.threads_access (self) 469359575Sdim 470359575Sdim def get_process_thread_list(self): 471359575Sdim '''An accessor function that returns a list() that contains all threads in a lldb.SBProcess object.''' 472359575Sdim threads = [] 473359575Sdim accessor = self.get_threads_access_object() 474359575Sdim for idx in range(len(accessor)): 475359575Sdim threads.append(accessor[idx]) 476359575Sdim return threads 477359575Sdim 478359575Sdim def __iter__(self): 479359575Sdim '''Iterate over all threads in a lldb.SBProcess object.''' 480359575Sdim return lldb_iter(self, 'GetNumThreads', 'GetThreadAtIndex') 481359575Sdim 482359575Sdim def __len__(self): 483359575Sdim '''Return the number of threads in a lldb.SBProcess object.''' 484359575Sdim return self.GetNumThreads() 485359575Sdim 486359575Sdim 487359575Sdim threads = property(get_process_thread_list, None, doc='''A read only property that returns a list() of lldb.SBThread objects for this process.''') 488359575Sdim thread = property(get_threads_access_object, None, doc='''A read only property that returns an object that can access threads by thread index (thread = lldb.process.thread[12]).''') 489359575Sdim is_alive = property(__get_is_alive__, None, doc='''A read only property that returns a boolean value that indicates if this process is currently alive.''') 490359575Sdim is_running = property(__get_is_running__, None, doc='''A read only property that returns a boolean value that indicates if this process is currently running.''') 491359575Sdim is_stopped = property(__get_is_stopped__, None, doc='''A read only property that returns a boolean value that indicates if this process is currently stopped.''') 492359575Sdim id = property(GetProcessID, None, doc='''A read only property that returns the process ID as an integer.''') 493359575Sdim target = property(GetTarget, None, doc='''A read only property that an lldb object that represents the target (lldb.SBTarget) that owns this process.''') 494359575Sdim num_threads = property(GetNumThreads, None, doc='''A read only property that returns the number of threads in this process as an integer.''') 495359575Sdim selected_thread = property(GetSelectedThread, SetSelectedThread, doc='''A read/write property that gets/sets the currently selected thread in this process. The getter returns a lldb.SBThread object and the setter takes an lldb.SBThread object.''') 496359575Sdim state = property(GetState, None, doc='''A read only property that returns an lldb enumeration value (see enumerations that start with "lldb.eState") that represents the current state of this process (running, stopped, exited, etc.).''') 497359575Sdim exit_state = property(GetExitStatus, None, doc='''A read only property that returns an exit status as an integer of this process when the process state is lldb.eStateExited.''') 498359575Sdim exit_description = property(GetExitDescription, None, doc='''A read only property that returns an exit description as a string of this process when the process state is lldb.eStateExited.''') 499359575Sdim broadcaster = property(GetBroadcaster, None, doc='''A read only property that an lldb object that represents the broadcaster (lldb.SBBroadcaster) for this process.''') 500359575Sdim %} 501359575Sdim#endif 502359575Sdim 503359575Sdim}; 504359575Sdim 505359575Sdim} // namespace lldb 506