LLDB API Documentation

- Main Page
- Namespaces
- Classes
- Files

- File List

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,
71 lldb::SBCommandReturnObject &result);
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
224 static lldb::SBStructuredData
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_
lldb::SBBroadcaster
Definition: SBBroadcaster.h:17
lldb::SBThread
Definition: SBThread.h:21
lldb::SBProcess
class LLDB_API SBProcess
Definition: SBDefines.h:67
lldb::SBMemoryRegionInfo
Definition: SBMemoryRegionInfo.h:18
lldb::SBBreakpoint
Definition: SBBreakpoint.h:17
SBDefines.h
lldb::SBStructuredData
Definition: SBStructuredData.h:18
lldb::SBQueue
Definition: SBQueue.h:20
SBQueue.h
lldb::SBCommandInterpreter
Definition: SBCommandInterpreter.h:66
lldb::SBValue
Definition: SBValue.h:22
lldb::SBEvent
class LLDB_API SBEvent
Definition: SBDefines.h:47
lldb::SBProcess::FLAGS_ANONYMOUS_ENUM
FLAGS_ANONYMOUS_ENUM()
Broadcaster event bits definitions.
Definition: SBProcess.h:28
lldb::SBProcess::m_opaque_wp
lldb::ProcessWP m_opaque_wp
Definition: SBProcess.h:374
lldb::SBAddress
Definition: SBAddress.h:18
lldb::SBFileSpec
Definition: SBFileSpec.h:17
lldb::SBModule
Definition: SBModule.h:21
lldb::SBDebugger
Definition: SBDebugger.h:35
lldb::SBFunction
Definition: SBFunction.h:19
lldb::SBProcess
Definition: SBProcess.h:23
lldb::SBExecutionContext
Definition: SBExecutionContext.h:21
lldb::SBEvent
Definition: SBEvent.h:22
lldb::SBThreadCollection
Definition: SBThreadCollection.h:17
lldb::SBError
Definition: SBError.h:17
SBError.h
lldb::SBUnixSignals
Definition: SBUnixSignals.h:18
lldb::SBMemoryRegionInfoList
Definition: SBMemoryRegionInfoList.h:19
lldb::SBStream
Definition: SBStream.h:19
lldb::SBBreakpointLocation
Definition: SBBreakpointLocation.h:18
lldb::SBCommandReturnObject
Definition: SBCommandReturnObject.h:25
SBTarget.h
lldb::SBTarget
Definition: SBTarget.h:34