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. 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. 341 /// 342 /// \param[in] file_name - The name of the file to save the core file to. 343 /// 344 /// \param[in] flavor - Specify the flavor of a core file plug-in to save. 345 /// Currently supported flavors include "mach-o" and "minidump" 346 /// 347 /// \param[in] core_style - Specify the style of a core file to save. 348 lldb::SBError SaveCore(const char *file_name, const char *flavor, 349 SaveCoreStyle core_style); 350 351 /// Save the state of the process with the a flavor that matches the 352 /// current process' main executable (if supported). 353 /// 354 /// \param[in] file_name - The name of the file to save the core file to. 355 lldb::SBError SaveCore(const char *file_name); 356 357 /// Query the address load_addr and store the details of the memory 358 /// region that contains it in the supplied SBMemoryRegionInfo object. 359 /// To iterate over all memory regions use GetMemoryRegionList. 360 /// 361 /// \param[in] load_addr 362 /// The address to be queried. 363 /// 364 /// \param[out] region_info 365 /// A reference to an SBMemoryRegionInfo object that will contain 366 /// the details of the memory region containing load_addr. 367 /// 368 /// \return 369 /// An error object describes any errors that occurred while 370 /// querying load_addr. 371 lldb::SBError GetMemoryRegionInfo(lldb::addr_t load_addr, 372 lldb::SBMemoryRegionInfo ®ion_info); 373 374 /// Return the list of memory regions within the process. 375 /// 376 /// \return 377 /// A list of all witin the process memory regions. 378 lldb::SBMemoryRegionInfoList GetMemoryRegions(); 379 380 /// Return information about the process. 381 /// 382 /// Valid process info will only be returned when the process is 383 /// alive, use SBProcessInfo::IsValid() to check returned info is 384 /// valid. 385 lldb::SBProcessInfo GetProcessInfo(); 386 387 /// Allocate memory within the process. 388 /// 389 /// This function will allocate memory in the process's address space. 390 /// 391 /// \param[in] size 392 /// The size of the allocation requested. 393 /// 394 /// \param[in] permissions 395 /// Or together any of the lldb::Permissions bits. The 396 /// permissions on a given memory allocation can't be changed 397 /// after allocation. Note that a block that isn't set writable 398 /// can still be written from lldb, just not by the process 399 /// itself. 400 /// 401 /// \param[out] error 402 /// An error object that gets filled in with any errors that 403 /// might occur when trying allocate. 404 /// 405 /// \return 406 /// The address of the allocated buffer in the process, or 407 /// LLDB_INVALID_ADDRESS if the allocation failed. 408 lldb::addr_t AllocateMemory(size_t size, uint32_t permissions, 409 lldb::SBError &error); 410 411 /// Deallocate memory in the process. 412 /// 413 /// This function will deallocate memory in the process's address 414 /// space that was allocated with AllocateMemory. 415 /// 416 /// \param[in] ptr 417 /// A return value from AllocateMemory, pointing to the memory you 418 /// want to deallocate. 419 /// 420 /// \return 421 /// An error object describes any errors that occurred while 422 /// deallocating. 423 /// 424 lldb::SBError DeallocateMemory(lldb::addr_t ptr); 425 426 protected: 427 friend class SBAddress; 428 friend class SBBreakpoint; 429 friend class SBBreakpointLocation; 430 friend class SBCommandInterpreter; 431 friend class SBDebugger; 432 friend class SBExecutionContext; 433 friend class SBFunction; 434 friend class SBModule; 435 friend class SBTarget; 436 friend class SBThread; 437 friend class SBValue; 438 friend class lldb_private::QueueImpl; 439 440 lldb::ProcessSP GetSP() const; 441 442 void SetSP(const lldb::ProcessSP &process_sp); 443 444 lldb::ProcessWP m_opaque_wp; 445 }; 446 447 } // namespace lldb 448 449 #endif // LLDB_API_SBPROCESS_H 450