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