contrib/llvm/tools/lldb/include/lldb/API/SBProcess.h

   1 //===-- SBProcess.h ---------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLDB_SBProcess_h_
  11 #define LLDB_SBProcess_h_
  12
  13 #include "lldb/API/SBDefines.h"
  14 #include "lldb/API/SBError.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   //------------------------------------------------------------------
  26   /// Broadcaster event bits definitions.
  27   //------------------------------------------------------------------
  28   FLAGS_ANONYMOUS_ENUM(){eBroadcastBitStateChanged = (1 << 0),
  29                          eBroadcastBitInterrupt = (1 << 1),
  30                          eBroadcastBitSTDOUT = (1 << 2),
  31                          eBroadcastBitSTDERR = (1 << 3),
  32                          eBroadcastBitProfileData = (1 << 4),
  33                          eBroadcastBitStructuredData = (1 << 5)};
  34
  35   SBProcess();
  36
  37   SBProcess(const lldb::SBProcess &rhs);
  38
  39   const lldb::SBProcess &operator=(const lldb::SBProcess &rhs);
  40
  41   SBProcess(const lldb::ProcessSP &process_sp);
  42
  43   ~SBProcess();
  44
  45   static const char *GetBroadcasterClassName();
  46
  47   const char *GetPluginName();
  48
  49   // DEPRECATED: use GetPluginName()
  50   const char *GetShortPluginName();
  51
  52   void Clear();
  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 AppendEventStateReport(const lldb::SBEvent &event,
  71                               lldb::SBCommandReturnObject &result);
  72
  73   //------------------------------------------------------------------
  74   /// Remote connection related functions. These will fail if the
  75   /// process is not in eStateConnected. They are intended for use
  76   /// when connecting to an externally managed debugserver instance.
  77   //------------------------------------------------------------------
  78   bool RemoteAttachToProcessWithID(lldb::pid_t pid, lldb::SBError &error);
  79
  80   bool RemoteLaunch(char const **argv, char const **envp,
  81                     const char *stdin_path, const char *stdout_path,
  82                     const char *stderr_path, const char *working_directory,
  83                     uint32_t launch_flags, bool stop_at_entry,
  84                     lldb::SBError &error);
  85
  86   //------------------------------------------------------------------
  87   // Thread related functions
  88   //------------------------------------------------------------------
  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   //------------------------------------------------------------------
 100   // Function for lazily creating a thread using the current OS
 101   // plug-in. This function will be removed in the future when there
 102   // are APIs to create SBThread objects through the interface and add
 103   // them to the process through the SBProcess API.
 104   //------------------------------------------------------------------
 105   lldb::SBThread CreateOSPluginThread(lldb::tid_t tid, lldb::addr_t context);
 106
 107   bool SetSelectedThread(const lldb::SBThread &thread);
 108
 109   bool SetSelectedThreadByID(lldb::tid_t tid);
 110
 111   bool SetSelectedThreadByIndexID(uint32_t index_id);
 112
 113   //------------------------------------------------------------------
 114   // Queue related functions
 115   //------------------------------------------------------------------
 116   uint32_t GetNumQueues();
 117
 118   lldb::SBQueue GetQueueAtIndex(size_t index);
 119
 120   //------------------------------------------------------------------
 121   // Stepping related functions
 122   //------------------------------------------------------------------
 123
 124   lldb::StateType GetState();
 125
 126   int GetExitStatus();
 127
 128   const char *GetExitDescription();
 129
 130   //------------------------------------------------------------------
 131   /// Gets the process ID
 132   ///
 133   /// Returns the process identifier for the process as it is known
 134   /// on the system on which the process is running. For unix systems
 135   /// this is typically the same as if you called "getpid()" in the
 136   /// process.
 137   ///
 138   /// @return
 139   ///     Returns LLDB_INVALID_PROCESS_ID if this object does not
 140   ///     contain a valid process object, or if the process has not
 141   ///     been launched. Returns a valid process ID if the process is
 142   ///     valid.
 143   //------------------------------------------------------------------
 144   lldb::pid_t GetProcessID();
 145
 146   //------------------------------------------------------------------
 147   /// Gets the unique ID associated with this process object
 148   ///
 149   /// Unique IDs start at 1 and increment up with each new process
 150   /// instance. Since starting a process on a system might always
 151   /// create a process with the same process ID, there needs to be a
 152   /// way to tell two process instances apart.
 153   ///
 154   /// @return
 155   ///     Returns a non-zero integer ID if this object contains a
 156   ///     valid process object, zero if this object does not contain
 157   ///     a valid process object.
 158   //------------------------------------------------------------------
 159   uint32_t GetUniqueID();
 160
 161   uint32_t GetAddressByteSize() const;
 162
 163   lldb::SBError Destroy();
 164
 165   lldb::SBError Continue();
 166
 167   lldb::SBError Stop();
 168
 169   lldb::SBError Kill();
 170
 171   lldb::SBError Detach();
 172
 173   lldb::SBError Detach(bool keep_stopped);
 174
 175   lldb::SBError Signal(int signal);
 176
 177   lldb::SBUnixSignals GetUnixSignals();
 178
 179   void SendAsyncInterrupt();
 180
 181   uint32_t GetStopID(bool include_expression_stops = false);
 182
 183   //------------------------------------------------------------------
 184   /// Gets the stop event corresponding to stop ID.
 185   //
 186   /// Note that it wasn't fully implemented and tracks only the stop
 187   /// event for the last natural stop ID.
 188   ///
 189   /// @param [in] stop_id
 190   ///   The ID of the stop event to return.
 191   ///
 192   /// @return
 193   ///   The stop event corresponding to stop ID.
 194   //------------------------------------------------------------------
 195   lldb::SBEvent GetStopEventForStopID(uint32_t stop_id);
 196
 197   size_t ReadMemory(addr_t addr, void *buf, size_t size, lldb::SBError &error);
 198
 199   size_t WriteMemory(addr_t addr, const void *buf, size_t size,
 200                      lldb::SBError &error);
 201
 202   size_t ReadCStringFromMemory(addr_t addr, void *buf, size_t size,
 203                                lldb::SBError &error);
 204
 205   uint64_t ReadUnsignedFromMemory(addr_t addr, uint32_t byte_size,
 206                                   lldb::SBError &error);
 207
 208   lldb::addr_t ReadPointerFromMemory(addr_t addr, lldb::SBError &error);
 209
 210   // Events
 211   static lldb::StateType GetStateFromEvent(const lldb::SBEvent &event);
 212
 213   static bool GetRestartedFromEvent(const lldb::SBEvent &event);
 214
 215   static size_t GetNumRestartedReasonsFromEvent(const lldb::SBEvent &event);
 216
 217   static const char *
 218   GetRestartedReasonAtIndexFromEvent(const lldb::SBEvent &event, size_t idx);
 219
 220   static lldb::SBProcess GetProcessFromEvent(const lldb::SBEvent &event);
 221
 222   static bool GetInterruptedFromEvent(const lldb::SBEvent &event);
 223
 224   static lldb::SBStructuredData
 225   GetStructuredDataFromEvent(const lldb::SBEvent &event);
 226
 227   static bool EventIsProcessEvent(const lldb::SBEvent &event);
 228
 229   static bool EventIsStructuredDataEvent(const lldb::SBEvent &event);
 230
 231   lldb::SBBroadcaster GetBroadcaster() const;
 232
 233   static const char *GetBroadcasterClass();
 234
 235   bool GetDescription(lldb::SBStream &description);
 236
 237   uint32_t GetNumSupportedHardwareWatchpoints(lldb::SBError &error) const;
 238
 239   //------------------------------------------------------------------
 240   /// Load a shared library into this process.
 241   ///
 242   /// @param[in] remote_image_spec
 243   ///     The path for the shared library on the target what you want
 244   ///     to load.
 245   ///
 246   /// @param[out] error
 247   ///     An error object that gets filled in with any errors that
 248   ///     might occur when trying to load the shared library.
 249   ///
 250   /// @return
 251   ///     A token that represents the shared library that can be
 252   ///     later used to unload the shared library. A value of
 253   ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
 254   ///     library can't be opened.
 255   //------------------------------------------------------------------
 256   uint32_t LoadImage(lldb::SBFileSpec &remote_image_spec, lldb::SBError &error);
 257
 258   //------------------------------------------------------------------
 259   /// Load a shared library into this process.
 260   ///
 261   /// @param[in] local_image_spec
 262   ///     The file spec that points to the shared library that you
 263   ///     want to load if the library is located on the host. The
 264   ///     library will be copied over to the location specified by
 265   ///     remote_image_spec or into the current working directory with
 266   ///     the same filename if the remote_image_spec isn't specified.
 267   ///
 268   /// @param[in] remote_image_spec
 269   ///     If local_image_spec is specified then the location where the
 270   ///     library should be copied over from the host. If
 271   ///     local_image_spec isn't specified, then the path for the
 272   ///     shared library on the target what you want to load.
 273   ///
 274   /// @param[out] error
 275   ///     An error object that gets filled in with any errors that
 276   ///     might occur when trying to load the shared library.
 277   ///
 278   /// @return
 279   ///     A token that represents the shared library that can be
 280   ///     later used to unload the shared library. A value of
 281   ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
 282   ///     library can't be opened.
 283   //------------------------------------------------------------------
 284   uint32_t LoadImage(const lldb::SBFileSpec &local_image_spec,
 285                      const lldb::SBFileSpec &remote_image_spec,
 286                      lldb::SBError &error);
 287
 288   lldb::SBError UnloadImage(uint32_t image_token);
 289
 290   lldb::SBError SendEventData(const char *data);
 291
 292   //------------------------------------------------------------------
 293   /// Return the number of different thread-origin extended backtraces
 294   /// this process can support.
 295   ///
 296   /// When the process is stopped and you have an SBThread, lldb may be
 297   /// able to show a backtrace of when that thread was originally created,
 298   /// or the work item was enqueued to it (in the case of a libdispatch
 299   /// queue).
 300   ///
 301   /// @return
 302   ///   The number of thread-origin extended backtrace types that may be
 303   ///   available.
 304   //------------------------------------------------------------------
 305   uint32_t GetNumExtendedBacktraceTypes();
 306
 307   //------------------------------------------------------------------
 308   /// Return the name of one of the thread-origin extended backtrace
 309   /// methods.
 310   ///
 311   /// @param [in] idx
 312   ///   The index of the name to return.  They will be returned in
 313   ///   the order that the user will most likely want to see them.
 314   ///   e.g. if the type at index 0 is not available for a thread,
 315   ///   see if the type at index 1 provides an extended backtrace.
 316   ///
 317   /// @return
 318   ///   The name at that index.
 319   //------------------------------------------------------------------
 320   const char *GetExtendedBacktraceTypeAtIndex(uint32_t idx);
 321
 322   lldb::SBThreadCollection GetHistoryThreads(addr_t addr);
 323
 324   bool IsInstrumentationRuntimePresent(InstrumentationRuntimeType type);
 325
 326   // Save the state of the process in a core file (or mini dump on Windows).
 327   lldb::SBError SaveCore(const char *file_name);
 328
 329   //------------------------------------------------------------------
 330   /// Query the address load_addr and store the details of the memory
 331   /// region that contains it in the supplied SBMemoryRegionInfo object.
 332   /// To iterate over all memory regions use GetMemoryRegionList.
 333   ///
 334   /// @param[in] load_addr
 335   ///     The address to be queried.
 336   ///
 337   /// @param[out] region_info
 338   ///     A reference to an SBMemoryRegionInfo object that will contain
 339   ///     the details of the memory region containing load_addr.
 340   ///
 341   /// @return
 342   ///     An error object describes any errors that occurred while
 343   ///     querying load_addr.
 344   //------------------------------------------------------------------
 345   lldb::SBError GetMemoryRegionInfo(lldb::addr_t load_addr,
 346                                     lldb::SBMemoryRegionInfo &region_info);
 347
 348   //------------------------------------------------------------------
 349   /// Return the list of memory regions within the process.
 350   ///
 351   /// @return
 352   ///     A list of all witin the process memory regions.
 353   //------------------------------------------------------------------
 354   lldb::SBMemoryRegionInfoList GetMemoryRegions();
 355
 356 protected:
 357   friend class SBAddress;
 358   friend class SBBreakpoint;
 359   friend class SBBreakpointLocation;
 360   friend class SBCommandInterpreter;
 361   friend class SBDebugger;
 362   friend class SBExecutionContext;
 363   friend class SBFunction;
 364   friend class SBModule;
 365   friend class SBTarget;
 366   friend class SBThread;
 367   friend class SBValue;
 368   friend class lldb_private::QueueImpl;
 369
 370   lldb::ProcessSP GetSP() const;
 371
 372   void SetSP(const lldb::ProcessSP &process_sp);
 373
 374   lldb::ProcessWP m_opaque_wp;
 375 };
 376
 377 } // namespace lldb
 378
 379 #endif // LLDB_SBProcess_h_