1 //===-- SBProcess.h ---------------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_API_SBPROCESS_H 10 #define LLDB_API_SBPROCESS_H 11 12 #include "lldb/API/SBDefines.h" 13 #include "lldb/API/SBError.h" 14 #include "lldb/API/SBProcessInfo.h" 15 #include "lldb/API/SBQueue.h" 16 #include "lldb/API/SBTarget.h" 17 #include <cstdio> 18 19 namespace lldb { 20 21 class SBEvent; 22 23 class LLDB_API SBProcess { 24 public: 25 /// Broadcaster event bits definitions. FLAGS_ANONYMOUS_ENUM()26 FLAGS_ANONYMOUS_ENUM(){eBroadcastBitStateChanged = (1 << 0), 27 eBroadcastBitInterrupt = (1 << 1), 28 eBroadcastBitSTDOUT = (1 << 2), 29 eBroadcastBitSTDERR = (1 << 3), 30 eBroadcastBitProfileData = (1 << 4), 31 eBroadcastBitStructuredData = (1 << 5)}; 32 33 SBProcess(); 34 35 SBProcess(const lldb::SBProcess &rhs); 36 37 const lldb::SBProcess &operator=(const lldb::SBProcess &rhs); 38 39 SBProcess(const lldb::ProcessSP &process_sp); 40 41 ~SBProcess(); 42 43 static const char *GetBroadcasterClassName(); 44 45 const char *GetPluginName(); 46 47 // DEPRECATED: use GetPluginName() 48 const char *GetShortPluginName(); 49 50 void Clear(); 51 52 explicit operator bool() const; 53 54 bool IsValid() const; 55 56 lldb::SBTarget GetTarget() const; 57 58 lldb::ByteOrder GetByteOrder() const; 59 60 size_t PutSTDIN(const char *src, size_t src_len); 61 62 size_t GetSTDOUT(char *dst, size_t dst_len) const; 63 64 size_t GetSTDERR(char *dst, size_t dst_len) const; 65 66 size_t GetAsyncProfileData(char *dst, size_t dst_len) const; 67 68 void ReportEventState(const lldb::SBEvent &event, FILE *out) const; 69 70 void ReportEventState(const lldb::SBEvent &event, SBFile file) const; 71 72 void ReportEventState(const lldb::SBEvent &event, FileSP file) const; 73 74 void AppendEventStateReport(const lldb::SBEvent &event, 75 lldb::SBCommandReturnObject &result); 76 77 /// Remote connection related functions. These will fail if the 78 /// process is not in eStateConnected. They are intended for use 79 /// when connecting to an externally managed debugserver instance. 80 bool RemoteAttachToProcessWithID(lldb::pid_t pid, lldb::SBError &error); 81 82 bool RemoteLaunch(char const **argv, char const **envp, 83 const char *stdin_path, const char *stdout_path, 84 const char *stderr_path, const char *working_directory, 85 uint32_t launch_flags, bool stop_at_entry, 86 lldb::SBError &error); 87 88 // Thread related functions 89 uint32_t GetNumThreads(); 90 91 lldb::SBThread GetThreadAtIndex(size_t index); 92 93 lldb::SBThread GetThreadByID(lldb::tid_t sb_thread_id); 94 95 lldb::SBThread GetThreadByIndexID(uint32_t index_id); 96 97 lldb::SBThread GetSelectedThread() const; 98 99 // Function for lazily creating a thread using the current OS plug-in. This 100 // function will be removed in the future when there are APIs to create 101 // SBThread objects through the interface and add them to the process through 102 // the SBProcess API. 103 lldb::SBThread CreateOSPluginThread(lldb::tid_t tid, lldb::addr_t context); 104 105 bool SetSelectedThread(const lldb::SBThread &thread); 106 107 bool SetSelectedThreadByID(lldb::tid_t tid); 108 109 bool SetSelectedThreadByIndexID(uint32_t index_id); 110 111 // Queue related functions 112 uint32_t GetNumQueues(); 113 114 lldb::SBQueue GetQueueAtIndex(size_t index); 115 116 // Stepping related functions 117 118 lldb::StateType GetState(); 119 120 int GetExitStatus(); 121 122 const char *GetExitDescription(); 123 124 /// Gets the process ID 125 /// 126 /// Returns the process identifier for the process as it is known 127 /// on the system on which the process is running. For unix systems 128 /// this is typically the same as if you called "getpid()" in the 129 /// process. 130 /// 131 /// \return 132 /// Returns LLDB_INVALID_PROCESS_ID if this object does not 133 /// contain a valid process object, or if the process has not 134 /// been launched. Returns a valid process ID if the process is 135 /// valid. 136 lldb::pid_t GetProcessID(); 137 138 /// Gets the unique ID associated with this process object 139 /// 140 /// Unique IDs start at 1 and increment up with each new process 141 /// instance. Since starting a process on a system might always 142 /// create a process with the same process ID, there needs to be a 143 /// way to tell two process instances apart. 144 /// 145 /// \return 146 /// Returns a non-zero integer ID if this object contains a 147 /// valid process object, zero if this object does not contain 148 /// a valid process object. 149 uint32_t GetUniqueID(); 150 151 uint32_t GetAddressByteSize() const; 152 153 lldb::SBError Destroy(); 154 155 lldb::SBError Continue(); 156 157 lldb::SBError Stop(); 158 159 lldb::SBError Kill(); 160 161 lldb::SBError Detach(); 162 163 lldb::SBError Detach(bool keep_stopped); 164 165 lldb::SBError Signal(int signal); 166 167 lldb::SBUnixSignals GetUnixSignals(); 168 169 void SendAsyncInterrupt(); 170 171 uint32_t GetStopID(bool include_expression_stops = false); 172 173 /// Gets the stop event corresponding to stop ID. 174 // 175 /// Note that it wasn't fully implemented and tracks only the stop 176 /// event for the last natural stop ID. 177 /// 178 /// \param [in] stop_id 179 /// The ID of the stop event to return. 180 /// 181 /// \return 182 /// The stop event corresponding to stop ID. 183 lldb::SBEvent GetStopEventForStopID(uint32_t stop_id); 184 185 size_t ReadMemory(addr_t addr, void *buf, size_t size, lldb::SBError &error); 186 187 size_t WriteMemory(addr_t addr, const void *buf, size_t size, 188 lldb::SBError &error); 189 190 size_t ReadCStringFromMemory(addr_t addr, void *buf, size_t size, 191 lldb::SBError &error); 192 193 uint64_t ReadUnsignedFromMemory(addr_t addr, uint32_t byte_size, 194 lldb::SBError &error); 195 196 lldb::addr_t ReadPointerFromMemory(addr_t addr, lldb::SBError &error); 197 198 // Events 199 static lldb::StateType GetStateFromEvent(const lldb::SBEvent &event); 200 201 static bool GetRestartedFromEvent(const lldb::SBEvent &event); 202 203 static size_t GetNumRestartedReasonsFromEvent(const lldb::SBEvent &event); 204 205 static const char * 206 GetRestartedReasonAtIndexFromEvent(const lldb::SBEvent &event, size_t idx); 207 208 static lldb::SBProcess GetProcessFromEvent(const lldb::SBEvent &event); 209 210 static bool GetInterruptedFromEvent(const lldb::SBEvent &event); 211 212 static lldb::SBStructuredData 213 GetStructuredDataFromEvent(const lldb::SBEvent &event); 214 215 static bool EventIsProcessEvent(const lldb::SBEvent &event); 216 217 static bool EventIsStructuredDataEvent(const lldb::SBEvent &event); 218 219 lldb::SBBroadcaster GetBroadcaster() const; 220 221 static const char *GetBroadcasterClass(); 222 223 bool GetDescription(lldb::SBStream &description); 224 225 SBStructuredData GetExtendedCrashInformation(); 226 227 uint32_t GetNumSupportedHardwareWatchpoints(lldb::SBError &error) const; 228 229 /// Load a shared library into this process. 230 /// 231 /// \param[in] remote_image_spec 232 /// The path for the shared library on the target what you want 233 /// to load. 234 /// 235 /// \param[out] error 236 /// An error object that gets filled in with any errors that 237 /// might occur when trying to load the shared library. 238 /// 239 /// \return 240 /// A token that represents the shared library that can be 241 /// later used to unload the shared library. A value of 242 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared 243 /// library can't be opened. 244 uint32_t LoadImage(lldb::SBFileSpec &remote_image_spec, lldb::SBError &error); 245 246 /// Load a shared library into this process. 247 /// 248 /// \param[in] local_image_spec 249 /// The file spec that points to the shared library that you 250 /// want to load if the library is located on the host. The 251 /// library will be copied over to the location specified by 252 /// remote_image_spec or into the current working directory with 253 /// the same filename if the remote_image_spec isn't specified. 254 /// 255 /// \param[in] remote_image_spec 256 /// If local_image_spec is specified then the location where the 257 /// library should be copied over from the host. If 258 /// local_image_spec isn't specified, then the path for the 259 /// shared library on the target what you want to load. 260 /// 261 /// \param[out] error 262 /// An error object that gets filled in with any errors that 263 /// might occur when trying to load the shared library. 264 /// 265 /// \return 266 /// A token that represents the shared library that can be 267 /// later used to unload the shared library. A value of 268 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared 269 /// library can't be opened. 270 uint32_t LoadImage(const lldb::SBFileSpec &local_image_spec, 271 const lldb::SBFileSpec &remote_image_spec, 272 lldb::SBError &error); 273 274 /// Load a shared library into this process, starting with a 275 /// library name and a list of paths, searching along the list of 276 /// paths till you find a matching library. 277 /// 278 /// \param[in] image_spec 279 /// The name of the shared library that you want to load. 280 /// If image_spec is a relative path, the relative path will be 281 /// appended to the search paths. 282 /// If the image_spec is an absolute path, just the basename is used. 283 /// 284 /// \param[in] paths 285 /// A list of paths to search for the library whose basename is 286 /// local_spec. 287 /// 288 /// \param[out] loaded_path 289 /// If the library was found along the paths, this will store the 290 /// full path to the found library. 291 /// 292 /// \param[out] error 293 /// An error object that gets filled in with any errors that 294 /// might occur when trying to search for the shared library. 295 /// 296 /// \return 297 /// A token that represents the shared library that can be 298 /// later passed to UnloadImage. A value of 299 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared 300 /// library can't be opened. 301 uint32_t LoadImageUsingPaths(const lldb::SBFileSpec &image_spec, 302 SBStringList &paths, 303 lldb::SBFileSpec &loaded_path, 304 lldb::SBError &error); 305 306 lldb::SBError UnloadImage(uint32_t image_token); 307 308 lldb::SBError SendEventData(const char *data); 309 310 /// Return the number of different thread-origin extended backtraces 311 /// this process can support. 312 /// 313 /// When the process is stopped and you have an SBThread, lldb may be 314 /// able to show a backtrace of when that thread was originally created, 315 /// or the work item was enqueued to it (in the case of a libdispatch 316 /// queue). 317 /// 318 /// \return 319 /// The number of thread-origin extended backtrace types that may be 320 /// available. 321 uint32_t GetNumExtendedBacktraceTypes(); 322 323 /// Return the name of one of the thread-origin extended backtrace 324 /// methods. 325 /// 326 /// \param [in] idx 327 /// The index of the name to return. They will be returned in 328 /// the order that the user will most likely want to see them. 329 /// e.g. if the type at index 0 is not available for a thread, 330 /// see if the type at index 1 provides an extended backtrace. 331 /// 332 /// \return 333 /// The name at that index. 334 const char *GetExtendedBacktraceTypeAtIndex(uint32_t idx); 335 336 lldb::SBThreadCollection GetHistoryThreads(addr_t addr); 337 338 bool IsInstrumentationRuntimePresent(InstrumentationRuntimeType type); 339 340 /// Save the state of the process in a core file (or mini dump on Windows). 341 lldb::SBError SaveCore(const char *file_name); 342 343 /// Query the address load_addr and store the details of the memory 344 /// region that contains it in the supplied SBMemoryRegionInfo object. 345 /// To iterate over all memory regions use GetMemoryRegionList. 346 /// 347 /// \param[in] load_addr 348 /// The address to be queried. 349 /// 350 /// \param[out] region_info 351 /// A reference to an SBMemoryRegionInfo object that will contain 352 /// the details of the memory region containing load_addr. 353 /// 354 /// \return 355 /// An error object describes any errors that occurred while 356 /// querying load_addr. 357 lldb::SBError GetMemoryRegionInfo(lldb::addr_t load_addr, 358 lldb::SBMemoryRegionInfo ®ion_info); 359 360 /// Return the list of memory regions within the process. 361 /// 362 /// \return 363 /// A list of all witin the process memory regions. 364 lldb::SBMemoryRegionInfoList GetMemoryRegions(); 365 366 /// Return information about the process. 367 /// 368 /// Valid process info will only be returned when the process is 369 /// alive, use SBProcessInfo::IsValid() to check returned info is 370 /// valid. 371 lldb::SBProcessInfo GetProcessInfo(); 372 373 /// Allocate memory within the process. 374 /// 375 /// This function will allocate memory in the process's address space. 376 /// 377 /// \param[in] size 378 /// The size of the allocation requested. 379 /// 380 /// \param[in] permissions 381 /// Or together any of the lldb::Permissions bits. The 382 /// permissions on a given memory allocation can't be changed 383 /// after allocation. Note that a block that isn't set writable 384 /// can still be written from lldb, just not by the process 385 /// itself. 386 /// 387 /// \param[out] error 388 /// An error object that gets filled in with any errors that 389 /// might occur when trying allocate. 390 /// 391 /// \return 392 /// The address of the allocated buffer in the process, or 393 /// LLDB_INVALID_ADDRESS if the allocation failed. 394 lldb::addr_t AllocateMemory(size_t size, uint32_t permissions, 395 lldb::SBError &error); 396 397 /// Deallocate memory in the process. 398 /// 399 /// This function will deallocate memory in the process's address 400 /// space that was allocated with AllocateMemory. 401 /// 402 /// \param[in] ptr 403 /// A return value from AllocateMemory, pointing to the memory you 404 /// want to deallocate. 405 /// 406 /// \return 407 /// An error object describes any errors that occurred while 408 /// deallocating. 409 /// 410 lldb::SBError DeallocateMemory(lldb::addr_t ptr); 411 412 protected: 413 friend class SBAddress; 414 friend class SBBreakpoint; 415 friend class SBBreakpointLocation; 416 friend class SBCommandInterpreter; 417 friend class SBDebugger; 418 friend class SBExecutionContext; 419 friend class SBFunction; 420 friend class SBModule; 421 friend class SBTarget; 422 friend class SBThread; 423 friend class SBValue; 424 friend class lldb_private::QueueImpl; 425 426 lldb::ProcessSP GetSP() const; 427 428 void SetSP(const lldb::ProcessSP &process_sp); 429 430 lldb::ProcessWP m_opaque_wp; 431 }; 432 433 } // namespace lldb 434 435 #endif // LLDB_API_SBPROCESS_H 436