LLDB API Documentation

SBProcess.h
Go to the documentation of this file.
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,
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 
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_
class LLDB_API SBProcess
Definition: SBDefines.h:67
class LLDB_API SBEvent
Definition: SBDefines.h:47
FLAGS_ANONYMOUS_ENUM()
Broadcaster event bits definitions.
Definition: SBProcess.h:28
lldb::ProcessWP m_opaque_wp
Definition: SBProcess.h:374