contrib/llvm-project/lldb/include/lldb/API/SBProcess.h

   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 <stdio.h>
  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   /// Start Tracing with the given SBTraceOptions.
 228   ///
 229   /// \param[in] options
 230   ///     Class containing trace options like trace buffer size, meta
 231   ///     data buffer size, TraceType and any custom parameters
 232   ///     {formatted as a JSON Dictionary}. In case of errors in
 233   ///     formatting, an error would be reported.
 234   ///     It must be noted that tracing options such as buffer sizes
 235   ///     or other custom parameters passed maybe invalid for some
 236   ///     trace technologies. In such cases the trace implementations
 237   ///     could choose to either throw an error or could round off to
 238   ///     the nearest valid options to start tracing if the passed
 239   ///     value is not supported. To obtain the actual used trace
 240   ///     options please use the GetTraceConfig API. For the custom
 241   ///     parameters, only the parameters recognized by the target
 242   ///     would be used and others would be ignored.
 243   ///
 244   /// \param[out] error
 245   ///     An error explaining what went wrong.
 246   ///
 247   /// \return
 248   ///     A SBTrace instance, which should be used
 249   ///     to get the trace data or other trace related operations.
 250   lldb::SBTrace StartTrace(SBTraceOptions &options, lldb::SBError &error);
 251
 252   uint32_t GetNumSupportedHardwareWatchpoints(lldb::SBError &error) const;
 253
 254   /// Load a shared library into this process.
 255   ///
 256   /// \param[in] remote_image_spec
 257   ///     The path for the shared library on the target what you want
 258   ///     to load.
 259   ///
 260   /// \param[out] error
 261   ///     An error object that gets filled in with any errors that
 262   ///     might occur when trying to load the shared library.
 263   ///
 264   /// \return
 265   ///     A token that represents the shared library that can be
 266   ///     later used to unload the shared library. A value of
 267   ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
 268   ///     library can't be opened.
 269   uint32_t LoadImage(lldb::SBFileSpec &remote_image_spec, lldb::SBError &error);
 270
 271   /// Load a shared library into this process.
 272   ///
 273   /// \param[in] local_image_spec
 274   ///     The file spec that points to the shared library that you
 275   ///     want to load if the library is located on the host. The
 276   ///     library will be copied over to the location specified by
 277   ///     remote_image_spec or into the current working directory with
 278   ///     the same filename if the remote_image_spec isn't specified.
 279   ///
 280   /// \param[in] remote_image_spec
 281   ///     If local_image_spec is specified then the location where the
 282   ///     library should be copied over from the host. If
 283   ///     local_image_spec isn't specified, then the path for the
 284   ///     shared library on the target what you want to load.
 285   ///
 286   /// \param[out] error
 287   ///     An error object that gets filled in with any errors that
 288   ///     might occur when trying to load the shared library.
 289   ///
 290   /// \return
 291   ///     A token that represents the shared library that can be
 292   ///     later used to unload the shared library. A value of
 293   ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
 294   ///     library can't be opened.
 295   uint32_t LoadImage(const lldb::SBFileSpec &local_image_spec,
 296                      const lldb::SBFileSpec &remote_image_spec,
 297                      lldb::SBError &error);
 298
 299   /// Load a shared library into this process, starting with a
 300   /// library name and a list of paths, searching along the list of
 301   /// paths till you find a matching library.
 302   ///
 303   /// \param[in] image_spec
 304   ///     The name of the shared library that you want to load.
 305   ///     If image_spec is a relative path, the relative path will be
 306   ///     appended to the search paths.
 307   ///     If the image_spec is an absolute path, just the basename is used.
 308   ///
 309   /// \param[in] paths
 310   ///     A list of paths to search for the library whose basename is
 311   ///     local_spec.
 312   ///
 313   /// \param[out] loaded_path
 314   ///     If the library was found along the paths, this will store the
 315   ///     full path to the found library.
 316   ///
 317   /// \param[out] error
 318   ///     An error object that gets filled in with any errors that
 319   ///     might occur when trying to search for the shared library.
 320   ///
 321   /// \return
 322   ///     A token that represents the shared library that can be
 323   ///     later passed to UnloadImage. A value of
 324   ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
 325   ///     library can't be opened.
 326   uint32_t LoadImageUsingPaths(const lldb::SBFileSpec &image_spec,
 327                                SBStringList &paths,
 328                                lldb::SBFileSpec &loaded_path,
 329                                lldb::SBError &error);
 330
 331   lldb::SBError UnloadImage(uint32_t image_token);
 332
 333   lldb::SBError SendEventData(const char *data);
 334
 335   /// Return the number of different thread-origin extended backtraces
 336   /// this process can support.
 337   ///
 338   /// When the process is stopped and you have an SBThread, lldb may be
 339   /// able to show a backtrace of when that thread was originally created,
 340   /// or the work item was enqueued to it (in the case of a libdispatch
 341   /// queue).
 342   ///
 343   /// \return
 344   ///   The number of thread-origin extended backtrace types that may be
 345   ///   available.
 346   uint32_t GetNumExtendedBacktraceTypes();
 347
 348   /// Return the name of one of the thread-origin extended backtrace
 349   /// methods.
 350   ///
 351   /// \param [in] idx
 352   ///   The index of the name to return.  They will be returned in
 353   ///   the order that the user will most likely want to see them.
 354   ///   e.g. if the type at index 0 is not available for a thread,
 355   ///   see if the type at index 1 provides an extended backtrace.
 356   ///
 357   /// \return
 358   ///   The name at that index.
 359   const char *GetExtendedBacktraceTypeAtIndex(uint32_t idx);
 360
 361   lldb::SBThreadCollection GetHistoryThreads(addr_t addr);
 362
 363   bool IsInstrumentationRuntimePresent(InstrumentationRuntimeType type);
 364
 365   /// Save the state of the process in a core file (or mini dump on Windows).
 366   lldb::SBError SaveCore(const char *file_name);
 367
 368   /// Query the address load_addr and store the details of the memory
 369   /// region that contains it in the supplied SBMemoryRegionInfo object.
 370   /// To iterate over all memory regions use GetMemoryRegionList.
 371   ///
 372   /// \param[in] load_addr
 373   ///     The address to be queried.
 374   ///
 375   /// \param[out] region_info
 376   ///     A reference to an SBMemoryRegionInfo object that will contain
 377   ///     the details of the memory region containing load_addr.
 378   ///
 379   /// \return
 380   ///     An error object describes any errors that occurred while
 381   ///     querying load_addr.
 382   lldb::SBError GetMemoryRegionInfo(lldb::addr_t load_addr,
 383                                     lldb::SBMemoryRegionInfo &region_info);
 384
 385   /// Return the list of memory regions within the process.
 386   ///
 387   /// \return
 388   ///     A list of all witin the process memory regions.
 389   lldb::SBMemoryRegionInfoList GetMemoryRegions();
 390
 391   /// Return information about the process.
 392   ///
 393   /// Valid process info will only be returned when the process is
 394   /// alive, use SBProcessInfo::IsValid() to check returned info is
 395   /// valid.
 396   lldb::SBProcessInfo GetProcessInfo();
 397
 398 protected:
 399   friend class SBAddress;
 400   friend class SBBreakpoint;
 401   friend class SBBreakpointLocation;
 402   friend class SBCommandInterpreter;
 403   friend class SBDebugger;
 404   friend class SBExecutionContext;
 405   friend class SBFunction;
 406   friend class SBModule;
 407   friend class SBTarget;
 408   friend class SBThread;
 409   friend class SBValue;
 410   friend class lldb_private::QueueImpl;
 411
 412   lldb::ProcessSP GetSP() const;
 413
 414   void SetSP(const lldb::ProcessSP &process_sp);
 415
 416   lldb::ProcessWP m_opaque_wp;
 417 };
 418
 419 } // namespace lldb
 420
 421 #endif // LLDB_API_SBPROCESS_H