106c3fb27SDimitry Andric %feature("docstring", 206c3fb27SDimitry Andric "Represents the process associated with the target program. 306c3fb27SDimitry Andric 406c3fb27SDimitry Andric SBProcess supports thread iteration. For example (from test/lldbutil.py), :: 506c3fb27SDimitry Andric 606c3fb27SDimitry Andric # ================================================== 706c3fb27SDimitry Andric # Utility functions related to Threads and Processes 806c3fb27SDimitry Andric # ================================================== 906c3fb27SDimitry Andric 1006c3fb27SDimitry Andric def get_stopped_threads(process, reason): 1106c3fb27SDimitry Andric '''Returns the thread(s) with the specified stop reason in a list. 1206c3fb27SDimitry Andric 1306c3fb27SDimitry Andric The list can be empty if no such thread exists. 1406c3fb27SDimitry Andric ''' 1506c3fb27SDimitry Andric threads = [] 1606c3fb27SDimitry Andric for t in process: 1706c3fb27SDimitry Andric if t.GetStopReason() == reason: 1806c3fb27SDimitry Andric threads.append(t) 1906c3fb27SDimitry Andric return threads 2006c3fb27SDimitry Andric " 2106c3fb27SDimitry Andric ) lldb::SBProcess; 2206c3fb27SDimitry Andric 2306c3fb27SDimitry Andric %feature("autodoc", " 2406c3fb27SDimitry Andric Writes data into the current process's stdin. API client specifies a Python 2506c3fb27SDimitry Andric string as the only argument." 2606c3fb27SDimitry Andric ) lldb::SBProcess::PutSTDIN; 2706c3fb27SDimitry Andric 2806c3fb27SDimitry Andric %feature("autodoc", " 2906c3fb27SDimitry Andric Reads data from the current process's stdout stream. API client specifies 3006c3fb27SDimitry Andric the size of the buffer to read data into. It returns the byte buffer in a 3106c3fb27SDimitry Andric Python string." 3206c3fb27SDimitry Andric ) lldb::SBProcess::GetSTDOUT; 3306c3fb27SDimitry Andric 3406c3fb27SDimitry Andric %feature("autodoc", " 3506c3fb27SDimitry Andric Reads data from the current process's stderr stream. API client specifies 3606c3fb27SDimitry Andric the size of the buffer to read data into. It returns the byte buffer in a 3706c3fb27SDimitry Andric Python string." 3806c3fb27SDimitry Andric ) lldb::SBProcess::GetSTDERR; 3906c3fb27SDimitry Andric 4006c3fb27SDimitry Andric %feature("docstring", " 4106c3fb27SDimitry Andric Remote connection related functions. These will fail if the 4206c3fb27SDimitry Andric process is not in eStateConnected. They are intended for use 4306c3fb27SDimitry Andric when connecting to an externally managed debugserver instance." 4406c3fb27SDimitry Andric ) lldb::SBProcess::RemoteAttachToProcessWithID; 4506c3fb27SDimitry Andric 4606c3fb27SDimitry Andric %feature("docstring", 4706c3fb27SDimitry Andric "See SBTarget.Launch for argument description and usage." 4806c3fb27SDimitry Andric ) lldb::SBProcess::RemoteLaunch; 4906c3fb27SDimitry Andric 5006c3fb27SDimitry Andric %feature("autodoc", " 5106c3fb27SDimitry Andric Returns the INDEX'th thread from the list of current threads. The index 5206c3fb27SDimitry Andric of a thread is only valid for the current stop. For a persistent thread 5306c3fb27SDimitry Andric identifier use either the thread ID or the IndexID. See help on SBThread 5406c3fb27SDimitry Andric for more details." 5506c3fb27SDimitry Andric ) lldb::SBProcess::GetThreadAtIndex; 5606c3fb27SDimitry Andric 5706c3fb27SDimitry Andric %feature("autodoc", " 5806c3fb27SDimitry Andric Returns the thread with the given thread ID." 5906c3fb27SDimitry Andric ) lldb::SBProcess::GetThreadByID; 6006c3fb27SDimitry Andric 6106c3fb27SDimitry Andric %feature("autodoc", " 6206c3fb27SDimitry Andric Returns the thread with the given thread IndexID." 6306c3fb27SDimitry Andric ) lldb::SBProcess::GetThreadByIndexID; 6406c3fb27SDimitry Andric 6506c3fb27SDimitry Andric %feature("autodoc", " 6606c3fb27SDimitry Andric Returns the currently selected thread." 6706c3fb27SDimitry Andric ) lldb::SBProcess::GetSelectedThread; 6806c3fb27SDimitry Andric 6906c3fb27SDimitry Andric %feature("autodoc", " 7006c3fb27SDimitry Andric Lazily create a thread on demand through the current OperatingSystem plug-in, if the current OperatingSystem plug-in supports it." 7106c3fb27SDimitry Andric ) lldb::SBProcess::CreateOSPluginThread; 7206c3fb27SDimitry Andric 7306c3fb27SDimitry Andric %feature("autodoc", " 7406c3fb27SDimitry Andric Returns the process ID of the process." 7506c3fb27SDimitry Andric ) lldb::SBProcess::GetProcessID; 7606c3fb27SDimitry Andric 7706c3fb27SDimitry Andric %feature("autodoc", " 7806c3fb27SDimitry Andric 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." 7906c3fb27SDimitry Andric ) lldb::SBProcess::GetUniqueID; 8006c3fb27SDimitry Andric 8106c3fb27SDimitry Andric %feature("docstring", " 8206c3fb27SDimitry Andric Kills the process and shuts down all threads that were spawned to 8306c3fb27SDimitry Andric track and monitor process." 8406c3fb27SDimitry Andric ) lldb::SBProcess::Destroy; 8506c3fb27SDimitry Andric 8606c3fb27SDimitry Andric %feature("docstring", "Same as Destroy(self).") lldb::SBProcess::Kill; 8706c3fb27SDimitry Andric 8806c3fb27SDimitry Andric %feature("docstring", "Sends the process a unix signal.") lldb::SBProcess::Signal; 8906c3fb27SDimitry Andric 9006c3fb27SDimitry Andric %feature("docstring", " 9106c3fb27SDimitry Andric Returns a stop id that will increase every time the process executes. If 9206c3fb27SDimitry Andric include_expression_stops is true, then stops caused by expression evaluation 9306c3fb27SDimitry Andric will cause the returned value to increase, otherwise the counter returned will 9406c3fb27SDimitry Andric only increase when execution is continued explicitly by the user. Note, the value 9506c3fb27SDimitry Andric will always increase, but may increase by more than one per stop." 9606c3fb27SDimitry Andric ) lldb::SBProcess::GetStopID; 9706c3fb27SDimitry Andric 9806c3fb27SDimitry Andric %feature("autodoc", " 9906c3fb27SDimitry Andric Reads memory from the current process's address space and removes any 10006c3fb27SDimitry Andric traps that may have been inserted into the memory. It returns the byte 10106c3fb27SDimitry Andric buffer in a Python string. Example: :: 10206c3fb27SDimitry Andric 10306c3fb27SDimitry Andric # Read 4 bytes from address 'addr' and assume error.Success() is True. 10406c3fb27SDimitry Andric content = process.ReadMemory(addr, 4, error) 10506c3fb27SDimitry Andric new_bytes = bytearray(content)" 10606c3fb27SDimitry Andric ) lldb::SBProcess::ReadMemory; 10706c3fb27SDimitry Andric 10806c3fb27SDimitry Andric %feature("autodoc", " 10906c3fb27SDimitry Andric Writes memory to the current process's address space and maintains any 11006c3fb27SDimitry Andric traps that might be present due to software breakpoints. Example: :: 11106c3fb27SDimitry Andric 11206c3fb27SDimitry Andric # Create a Python string from the byte array. 11306c3fb27SDimitry Andric new_value = str(bytes) 11406c3fb27SDimitry Andric result = process.WriteMemory(addr, new_value, error) 11506c3fb27SDimitry Andric if not error.Success() or result != len(bytes): 11606c3fb27SDimitry Andric print('SBProcess.WriteMemory() failed!')" 11706c3fb27SDimitry Andric ) lldb::SBProcess::WriteMemory; 11806c3fb27SDimitry Andric 11906c3fb27SDimitry Andric %feature("autodoc", " 12006c3fb27SDimitry Andric Reads a NULL terminated C string from the current process's address space. 12106c3fb27SDimitry Andric It returns a python string of the exact length, or truncates the string if 12206c3fb27SDimitry Andric the maximum character limit is reached. Example: :: 12306c3fb27SDimitry Andric 12406c3fb27SDimitry Andric # Read a C string of at most 256 bytes from address '0x1000' 12506c3fb27SDimitry Andric error = lldb.SBError() 12606c3fb27SDimitry Andric cstring = process.ReadCStringFromMemory(0x1000, 256, error) 12706c3fb27SDimitry Andric if error.Success(): 12806c3fb27SDimitry Andric print('cstring: ', cstring) 12906c3fb27SDimitry Andric else 13006c3fb27SDimitry Andric print('error: ', error)" 13106c3fb27SDimitry Andric ) lldb::SBProcess::ReadCStringFromMemory; 13206c3fb27SDimitry Andric 13306c3fb27SDimitry Andric 13406c3fb27SDimitry Andric %feature("autodoc", " 13506c3fb27SDimitry Andric Reads an unsigned integer from memory given a byte size and an address. 13606c3fb27SDimitry Andric Returns the unsigned integer that was read. Example: :: 13706c3fb27SDimitry Andric 13806c3fb27SDimitry Andric # Read a 4 byte unsigned integer from address 0x1000 13906c3fb27SDimitry Andric error = lldb.SBError() 14006c3fb27SDimitry Andric uint = ReadUnsignedFromMemory(0x1000, 4, error) 14106c3fb27SDimitry Andric if error.Success(): 14206c3fb27SDimitry Andric print('integer: %u' % uint) 14306c3fb27SDimitry Andric else 14406c3fb27SDimitry Andric print('error: ', error)" 14506c3fb27SDimitry Andric ) lldb::SBProcess::ReadUnsignedFromMemory; 14606c3fb27SDimitry Andric 14706c3fb27SDimitry Andric 14806c3fb27SDimitry Andric %feature("autodoc", " 14906c3fb27SDimitry Andric Reads a pointer from memory from an address and returns the value. Example: :: 15006c3fb27SDimitry Andric 15106c3fb27SDimitry Andric # Read a pointer from address 0x1000 15206c3fb27SDimitry Andric error = lldb.SBError() 15306c3fb27SDimitry Andric ptr = ReadPointerFromMemory(0x1000, error) 15406c3fb27SDimitry Andric if error.Success(): 15506c3fb27SDimitry Andric print('pointer: 0x%x' % ptr) 15606c3fb27SDimitry Andric else 15706c3fb27SDimitry Andric print('error: ', error)" 15806c3fb27SDimitry Andric ) lldb::SBProcess::ReadPointerFromMemory; 15906c3fb27SDimitry Andric 16006c3fb27SDimitry Andric 16106c3fb27SDimitry Andric %feature("autodoc", " 16206c3fb27SDimitry Andric Returns the implementation object of the process plugin if available. None 16306c3fb27SDimitry Andric otherwise." 16406c3fb27SDimitry Andric ) lldb::SBProcess::GetScriptedImplementation; 16506c3fb27SDimitry Andric 16606c3fb27SDimitry Andric %feature("autodoc", " 16706c3fb27SDimitry Andric Returns the process' extended crash information." 16806c3fb27SDimitry Andric ) lldb::SBProcess::GetExtendedCrashInformation; 16906c3fb27SDimitry Andric 17006c3fb27SDimitry Andric %feature("autodoc", " 17106c3fb27SDimitry Andric Load the library whose filename is given by image_spec looking in all the 17206c3fb27SDimitry Andric paths supplied in the paths argument. If successful, return a token that 17306c3fb27SDimitry Andric can be passed to UnloadImage and fill loaded_path with the path that was 17406c3fb27SDimitry Andric successfully loaded. On failure, return 17506c3fb27SDimitry Andric lldb.LLDB_INVALID_IMAGE_TOKEN." 17606c3fb27SDimitry Andric ) lldb::SBProcess::LoadImageUsingPaths; 17706c3fb27SDimitry Andric 17806c3fb27SDimitry Andric %feature("autodoc", " 17906c3fb27SDimitry Andric Return the number of different thread-origin extended backtraces 18006c3fb27SDimitry Andric this process can support as a uint32_t. 18106c3fb27SDimitry Andric When the process is stopped and you have an SBThread, lldb may be 18206c3fb27SDimitry Andric able to show a backtrace of when that thread was originally created, 18306c3fb27SDimitry Andric or the work item was enqueued to it (in the case of a libdispatch 18406c3fb27SDimitry Andric queue)." 18506c3fb27SDimitry Andric ) lldb::SBProcess::GetNumExtendedBacktraceTypes; 18606c3fb27SDimitry Andric 18706c3fb27SDimitry Andric %feature("autodoc", " 18806c3fb27SDimitry Andric Takes an index argument, returns the name of one of the thread-origin 18906c3fb27SDimitry Andric extended backtrace methods as a str." 19006c3fb27SDimitry Andric ) lldb::SBProcess::GetExtendedBacktraceTypeAtIndex; 19106c3fb27SDimitry Andric 19206c3fb27SDimitry Andric %feature("autodoc", " 19306c3fb27SDimitry Andric Get information about the process. 19406c3fb27SDimitry Andric Valid process info will only be returned when the process is alive, 19506c3fb27SDimitry Andric use IsValid() to check if the info returned is valid. :: 19606c3fb27SDimitry Andric 19706c3fb27SDimitry Andric process_info = process.GetProcessInfo() 19806c3fb27SDimitry Andric if process_info.IsValid(): 19906c3fb27SDimitry Andric process_info.GetProcessID()" 20006c3fb27SDimitry Andric ) lldb::SBProcess::GetProcessInfo; 20106c3fb27SDimitry Andric 20206c3fb27SDimitry Andric %feature("autodoc", " 20306c3fb27SDimitry Andric Allocates a block of memory within the process, with size and 20406c3fb27SDimitry Andric access permissions specified in the arguments. The permissions 20506c3fb27SDimitry Andric argument is an or-combination of zero or more of 20606c3fb27SDimitry Andric lldb.ePermissionsWritable, lldb.ePermissionsReadable, and 20706c3fb27SDimitry Andric lldb.ePermissionsExecutable. Returns the address 20806c3fb27SDimitry Andric of the allocated buffer in the process, or 20906c3fb27SDimitry Andric lldb.LLDB_INVALID_ADDRESS if the allocation failed." 21006c3fb27SDimitry Andric ) lldb::SBProcess::AllocateMemory; 21106c3fb27SDimitry Andric 212*5f757f3fSDimitry Andric %feature("autodoc", "Get default process broadcaster class name (lldb.process)." 213*5f757f3fSDimitry Andric ) lldb::SBProcess::GetBroadcasterClass; 214*5f757f3fSDimitry Andric 215*5f757f3fSDimitry Andric 21606c3fb27SDimitry Andric %feature("autodoc", " 21706c3fb27SDimitry Andric Deallocates the block of memory (previously allocated using 21806c3fb27SDimitry Andric AllocateMemory) given in the argument." 21906c3fb27SDimitry Andric ) lldb::SBProcess::DeallocateMemory; 220