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