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