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