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
19namespace lldb_private {
20namespace python {
21class SWIGBridge;
22}
23} // namespace lldb_private
24
25namespace lldb {
26
27class SBEvent;
28
29class LLDB_API SBProcess {
30public:
31 /// Broadcaster event bits definitions.
32 FLAGS_ANONYMOUS_ENUM(){eBroadcastBitStateChanged = (1 << 0),
33 eBroadcastBitInterrupt = (1 << 1),
34 eBroadcastBitSTDOUT = (1 << 2),
35 eBroadcastBitSTDERR = (1 << 3),
36 eBroadcastBitProfileData = (1 << 4),
37 eBroadcastBitStructuredData = (1 << 5)};
38
39 SBProcess();
40
41 SBProcess(const lldb::SBProcess &rhs);
42
43 const lldb::SBProcess &operator=(const lldb::SBProcess &rhs);
44
45 ~SBProcess();
46
47 static const char *GetBroadcasterClassName();
48
49 const char *GetPluginName();
50
51 LLDB_DEPRECATED_FIXME("Use GetPluginName()", "GetPluginName()")
52 const char *GetShortPluginName();
53
54 void Clear();
55
56 explicit operator bool() const;
57
58 bool IsValid() const;
59
60 lldb::SBTarget GetTarget() const;
61
62 lldb::ByteOrder GetByteOrder() const;
63
64 size_t PutSTDIN(const char *src, size_t src_len);
65
66 size_t GetSTDOUT(char *dst, size_t dst_len) const;
67
68 size_t GetSTDERR(char *dst, size_t dst_len) const;
69
70 size_t GetAsyncProfileData(char *dst, size_t dst_len) const;
71
72#ifndef SWIG
73 void ReportEventState(const lldb::SBEvent &event, FILE *out) const;
74#endif
75
76 void ReportEventState(const lldb::SBEvent &event, SBFile file) const;
77
78 void ReportEventState(const lldb::SBEvent &event, FileSP BORROWED) const;
79
80 void AppendEventStateReport(const lldb::SBEvent &event,
81 lldb::SBCommandReturnObject &result);
82
83 /// Remote connection related functions. These will fail if the
84 /// process is not in eStateConnected. They are intended for use
85 /// when connecting to an externally managed debugserver instance.
86 bool RemoteAttachToProcessWithID(lldb::pid_t pid, lldb::SBError &error);
87
88 bool RemoteLaunch(char const **argv, char const **envp,
89 const char *stdin_path, const char *stdout_path,
90 const char *stderr_path, const char *working_directory,
91 uint32_t launch_flags, bool stop_at_entry,
92 lldb::SBError &error);
93
94 // Thread related functions
95 uint32_t GetNumThreads();
96
97 lldb::SBThread GetThreadAtIndex(size_t index);
98
99 lldb::SBThread GetThreadByID(lldb::tid_t sb_thread_id);
100
101 lldb::SBThread GetThreadByIndexID(uint32_t index_id);
102
103 lldb::SBThread GetSelectedThread() const;
104
105 // Function for lazily creating a thread using the current OS plug-in. This
106 // function will be removed in the future when there are APIs to create
107 // SBThread objects through the interface and add them to the process through
108 // the SBProcess API.
109 lldb::SBThread CreateOSPluginThread(lldb::tid_t tid, lldb::addr_t context);
110
111 bool SetSelectedThread(const lldb::SBThread &thread);
112
113 bool SetSelectedThreadByID(lldb::tid_t tid);
114
115 bool SetSelectedThreadByIndexID(uint32_t index_id);
116
117 // Queue related functions
118 uint32_t GetNumQueues();
119
120 lldb::SBQueue GetQueueAtIndex(size_t index);
121
122 // Stepping related functions
123
124 lldb::StateType GetState();
125
126 int GetExitStatus();
127
128 const char *GetExitDescription();
129
130 /// Gets the process ID
131 ///
132 /// Returns the process identifier for the process as it is known
133 /// on the system on which the process is running. For unix systems
134 /// this is typically the same as if you called "getpid()" in the
135 /// process.
136 ///
137 /// \return
138 /// Returns LLDB_INVALID_PROCESS_ID if this object does not
139 /// contain a valid process object, or if the process has not
140 /// been launched. Returns a valid process ID if the process is
141 /// valid.
142 lldb::pid_t GetProcessID();
143
144 /// Gets the unique ID associated with this process object
145 ///
146 /// Unique IDs start at 1 and increment up with each new process
147 /// instance. Since starting a process on a system might always
148 /// create a process with the same process ID, there needs to be a
149 /// way to tell two process instances apart.
150 ///
151 /// \return
152 /// Returns a non-zero integer ID if this object contains a
153 /// valid process object, zero if this object does not contain
154 /// a valid process object.
155 uint32_t GetUniqueID();
156
157 uint32_t GetAddressByteSize() const;
158
159 lldb::SBError Destroy();
160
161 lldb::SBError Continue();
162
163 lldb::SBError Stop();
164
165 lldb::SBError Kill();
166
167 lldb::SBError Detach();
168
169 lldb::SBError Detach(bool keep_stopped);
170
171 lldb::SBError Signal(int signal);
172
173 lldb::SBUnixSignals GetUnixSignals();
174
175 void SendAsyncInterrupt();
176
177 uint32_t GetStopID(bool include_expression_stops = false);
178
179 /// Gets the stop event corresponding to stop ID.
180 //
181 /// Note that it wasn't fully implemented and tracks only the stop
182 /// event for the last natural stop ID.
183 ///
184 /// \param [in] stop_id
185 /// The ID of the stop event to return.
186 ///
187 /// \return
188 /// The stop event corresponding to stop ID.
189 lldb::SBEvent GetStopEventForStopID(uint32_t stop_id);
190
191 /// If the process is a scripted process, changes its state to the new state.
192 /// No-op otherwise.
193 ///
194 /// \param [in] new_state
195 /// The new state that the scripted process should be set to.
196 ///
197 void ForceScriptedState(StateType new_state);
198
199 size_t ReadMemory(addr_t addr, void *buf, size_t size, lldb::SBError &error);
200
201 size_t WriteMemory(addr_t addr, const void *buf, size_t size,
202 lldb::SBError &error);
203
204 size_t ReadCStringFromMemory(addr_t addr, void *char_buf, size_t size,
205 lldb::SBError &error);
206
207 uint64_t ReadUnsignedFromMemory(addr_t addr, uint32_t byte_size,
208 lldb::SBError &error);
209
210 lldb::addr_t ReadPointerFromMemory(addr_t addr, lldb::SBError &error);
211
212 // Events
213 static lldb::StateType GetStateFromEvent(const lldb::SBEvent &event);
214
215 static bool GetRestartedFromEvent(const lldb::SBEvent &event);
216
217 static size_t GetNumRestartedReasonsFromEvent(const lldb::SBEvent &event);
218
219 static const char *
220 GetRestartedReasonAtIndexFromEvent(const lldb::SBEvent &event, size_t idx);
221
222 static lldb::SBProcess GetProcessFromEvent(const lldb::SBEvent &event);
223
224 static bool GetInterruptedFromEvent(const lldb::SBEvent &event);
225
226 static lldb::SBStructuredData
227 GetStructuredDataFromEvent(const lldb::SBEvent &event);
228
229 static bool EventIsProcessEvent(const lldb::SBEvent &event);
230
231 static bool EventIsStructuredDataEvent(const lldb::SBEvent &event);
232
233 lldb::SBBroadcaster GetBroadcaster() const;
234
235 static const char *GetBroadcasterClass();
236
237 bool GetDescription(lldb::SBStream &description);
238
239 SBStructuredData GetExtendedCrashInformation();
240
241 uint32_t GetNumSupportedHardwareWatchpoints(lldb::SBError &error) const;
242
243 /// Load a shared library into this process.
244 ///
245 /// \param[in] remote_image_spec
246 /// The path for the shared library on the target what you want
247 /// to load.
248 ///
249 /// \param[out] error
250 /// An error object that gets filled in with any errors that
251 /// might occur when trying to load the shared library.
252 ///
253 /// \return
254 /// A token that represents the shared library that can be
255 /// later used to unload the shared library. A value of
256 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
257 /// library can't be opened.
258 uint32_t LoadImage(lldb::SBFileSpec &remote_image_spec, lldb::SBError &error);
259
260 /// Load a shared library into this process.
261 ///
262 /// \param[in] local_image_spec
263 /// The file spec that points to the shared library that you
264 /// want to load if the library is located on the host. The
265 /// library will be copied over to the location specified by
266 /// remote_image_spec or into the current working directory with
267 /// the same filename if the remote_image_spec isn't specified.
268 ///
269 /// \param[in] remote_image_spec
270 /// If local_image_spec is specified then the location where the
271 /// library should be copied over from the host. If
272 /// local_image_spec isn't specified, then the path for the
273 /// shared library on the target what you want to load.
274 ///
275 /// \param[out] error
276 /// An error object that gets filled in with any errors that
277 /// might occur when trying to load the shared library.
278 ///
279 /// \return
280 /// A token that represents the shared library that can be
281 /// later used to unload the shared library. A value of
282 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
283 /// library can't be opened.
284 uint32_t LoadImage(const lldb::SBFileSpec &local_image_spec,
285 const lldb::SBFileSpec &remote_image_spec,
286 lldb::SBError &error);
287
288 /// Load a shared library into this process, starting with a
289 /// library name and a list of paths, searching along the list of
290 /// paths till you find a matching library.
291 ///
292 /// \param[in] image_spec
293 /// The name of the shared library that you want to load.
294 /// If image_spec is a relative path, the relative path will be
295 /// appended to the search paths.
296 /// If the image_spec is an absolute path, just the basename is used.
297 ///
298 /// \param[in] paths
299 /// A list of paths to search for the library whose basename is
300 /// local_spec.
301 ///
302 /// \param[out] loaded_path
303 /// If the library was found along the paths, this will store the
304 /// full path to the found library.
305 ///
306 /// \param[out] error
307 /// An error object that gets filled in with any errors that
308 /// might occur when trying to search for the shared library.
309 ///
310 /// \return
311 /// A token that represents the shared library that can be
312 /// later passed to UnloadImage. A value of
313 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
314 /// library can't be opened.
315 uint32_t LoadImageUsingPaths(const lldb::SBFileSpec &image_spec,
316 SBStringList &paths,
317 lldb::SBFileSpec &loaded_path,
318 lldb::SBError &error);
319
320 lldb::SBError UnloadImage(uint32_t image_token);
321
322 lldb::SBError SendEventData(const char *data);
323
324 /// Return the number of different thread-origin extended backtraces
325 /// this process can support.
326 ///
327 /// When the process is stopped and you have an SBThread, lldb may be
328 /// able to show a backtrace of when that thread was originally created,
329 /// or the work item was enqueued to it (in the case of a libdispatch
330 /// queue).
331 ///
332 /// \return
333 /// The number of thread-origin extended backtrace types that may be
334 /// available.
335 uint32_t GetNumExtendedBacktraceTypes();
336
337 /// Return the name of one of the thread-origin extended backtrace
338 /// methods.
339 ///
340 /// \param [in] idx
341 /// The index of the name to return. They will be returned in
342 /// the order that the user will most likely want to see them.
343 /// e.g. if the type at index 0 is not available for a thread,
344 /// see if the type at index 1 provides an extended backtrace.
345 ///
346 /// \return
347 /// The name at that index.
348 const char *GetExtendedBacktraceTypeAtIndex(uint32_t idx);
349
350 lldb::SBThreadCollection GetHistoryThreads(addr_t addr);
351
352 bool IsInstrumentationRuntimePresent(InstrumentationRuntimeType type);
353
354 /// Save the state of the process in a core file.
355 ///
356 /// \param[in] file_name - The name of the file to save the core file to.
357 ///
358 /// \param[in] flavor - Specify the flavor of a core file plug-in to save.
359 /// Currently supported flavors include "mach-o" and "minidump"
360 ///
361 /// \param[in] core_style - Specify the style of a core file to save.
362 lldb::SBError SaveCore(const char *file_name, const char *flavor,
363 SaveCoreStyle core_style);
364
365 /// Save the state of the process with the a flavor that matches the
366 /// current process' main executable (if supported).
367 ///
368 /// \param[in] file_name - The name of the file to save the core file to.
369 lldb::SBError SaveCore(const char *file_name);
370
371 /// Query the address load_addr and store the details of the memory
372 /// region that contains it in the supplied SBMemoryRegionInfo object.
373 /// To iterate over all memory regions use GetMemoryRegionList.
374 ///
375 /// \param[in] load_addr
376 /// The address to be queried.
377 ///
378 /// \param[out] region_info
379 /// A reference to an SBMemoryRegionInfo object that will contain
380 /// the details of the memory region containing load_addr.
381 ///
382 /// \return
383 /// An error object describes any errors that occurred while
384 /// querying load_addr.
385 lldb::SBError GetMemoryRegionInfo(lldb::addr_t load_addr,
386 lldb::SBMemoryRegionInfo &region_info);
387
388 /// Return the list of memory regions within the process.
389 ///
390 /// \return
391 /// A list of all witin the process memory regions.
392 lldb::SBMemoryRegionInfoList GetMemoryRegions();
393
394 /// Return information about the process.
395 ///
396 /// Valid process info will only be returned when the process is
397 /// alive, use SBProcessInfo::IsValid() to check returned info is
398 /// valid.
399 lldb::SBProcessInfo GetProcessInfo();
400
401 /// Get the file specification for the core file that is currently being used
402 /// for the process. If the process is not loaded from a core file, then an
403 /// invalid file specification will be returned.
404 ///
405 /// \return
406 /// The path to the core file for this target or an invalid file spec if
407 /// the process isn't loaded from a core file.
408 lldb::SBFileSpec GetCoreFile();
409
410 /// Allocate memory within the process.
411 ///
412 /// This function will allocate memory in the process's address space.
413 ///
414 /// \param[in] size
415 /// The size of the allocation requested.
416 ///
417 /// \param[in] permissions
418 /// Or together any of the lldb::Permissions bits. The
419 /// permissions on a given memory allocation can't be changed
420 /// after allocation. Note that a block that isn't set writable
421 /// can still be written from lldb, just not by the process
422 /// itself.
423 ///
424 /// \param[out] error
425 /// An error object that gets filled in with any errors that
426 /// might occur when trying allocate.
427 ///
428 /// \return
429 /// The address of the allocated buffer in the process, or
430 /// LLDB_INVALID_ADDRESS if the allocation failed.
431 lldb::addr_t AllocateMemory(size_t size, uint32_t permissions,
432 lldb::SBError &error);
433
434 /// Deallocate memory in the process.
435 ///
436 /// This function will deallocate memory in the process's address
437 /// space that was allocated with AllocateMemory.
438 ///
439 /// \param[in] ptr
440 /// A return value from AllocateMemory, pointing to the memory you
441 /// want to deallocate.
442 ///
443 /// \return
444 /// An error object describes any errors that occurred while
445 /// deallocating.
446 ///
447 lldb::SBError DeallocateMemory(lldb::addr_t ptr);
448
449 lldb::SBScriptObject GetScriptedImplementation();
450
451protected:
452 friend class SBAddress;
453 friend class SBBreakpoint;
454 friend class SBBreakpointCallbackBaton;
455 friend class SBBreakpointLocation;
456 friend class SBCommandInterpreter;
457 friend class SBDebugger;
458 friend class SBExecutionContext;
459 friend class SBFunction;
460 friend class SBModule;
461 friend class SBPlatform;
462 friend class SBTarget;
463 friend class SBThread;
464 friend class SBValue;
465 friend class lldb_private::QueueImpl;
466
467 friend class lldb_private::python::SWIGBridge;
468
469 SBProcess(const lldb::ProcessSP &process_sp);
470
471 lldb::ProcessSP GetSP() const;
472
473 void SetSP(const lldb::ProcessSP &process_sp);
474
475 lldb::ProcessWP m_opaque_wp;
476};
477
478} // namespace lldb
479
480#endif // LLDB_API_SBPROCESS_H
481

source code of lldb/include/lldb/API/SBProcess.h