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"
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
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
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,
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,
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,
203
204 size_t ReadCStringFromMemory(addr_t addr, void *char_buf, size_t size,
206
207 uint64_t ReadUnsignedFromMemory(addr_t addr, uint32_t byte_size,
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
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,
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,
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 /// \{
411 /// \group Mask Address Methods
412 ///
413 /// \a type
414 /// All of the methods in this group take \a type argument
415 /// which is an AddressMaskType enum value.
416 /// There can be different address masks for code addresses and
417 /// data addresses, this argument can select which to get/set,
418 /// or to use when clearing non-addressable bits from an address.
419 /// This choice of mask can be important for example on AArch32
420 /// systems. Where instructions where instructions start on even addresses,
421 /// the 0th bit may be used to indicate that a function is thumb code. On
422 /// such a target, the eAddressMaskTypeCode may clear the 0th bit from an
423 /// address to get the actual address Whereas eAddressMaskTypeData would not.
424 ///
425 /// \a addr_range
426 /// Many of the methods in this group take an \a addr_range argument
427 /// which is an AddressMaskRange enum value.
428 /// Needing to specify the address range is highly unusual, and the
429 /// default argument can be used in nearly all circumstances.
430 /// On some architectures (e.g., AArch64), it is possible to have
431 /// different page table setups for low and high memory, so different
432 /// numbers of bits relevant to addressing. It is possible to have
433 /// a program running in one half of memory and accessing the other
434 /// as heap, so we need to maintain two different sets of address masks
435 /// to debug this correctly.
436
437 /// Get the current address mask that will be applied to addresses
438 /// before reading from memory.
439 ///
440 /// \param[in] type
441 /// See \ref Mask Address Methods description of this argument.
442 /// eAddressMaskTypeAny is often a suitable value when code and
443 /// data masks are the same on a given target.
444 ///
445 /// \param[in] addr_range
446 /// See \ref Mask Address Methods description of this argument.
447 /// This will default to eAddressMaskRangeLow which is the
448 /// only set of masks used normally.
449 ///
450 /// \return
451 /// The address mask currently in use. Bits which are not used
452 /// for addressing will be set to 1 in the mask.
453 lldb::addr_t GetAddressMask(
456
457 /// Set the current address mask that can be applied to addresses
458 /// before reading from memory.
459 ///
460 /// \param[in] type
461 /// See \ref Mask Address Methods description of this argument.
462 /// eAddressMaskTypeAll is often a suitable value when the
463 /// same mask is being set for both code and data.
464 ///
465 /// \param[in] mask
466 /// The address mask to set. Bits which are not used for addressing
467 /// should be set to 1 in the mask.
468 ///
469 /// \param[in] addr_range
470 /// See \ref Mask Address Methods description of this argument.
471 /// This will default to eAddressMaskRangeLow which is the
472 /// only set of masks used normally.
473 void SetAddressMask(
476
477 /// Set the number of bits used for addressing in this Process.
478 ///
479 /// On Darwin and similar systems, the addressable bits are expressed
480 /// as the number of low order bits that are relevant to addressing,
481 /// instead of a more general address mask.
482 /// This method calculates the correct mask value for a given number
483 /// of low order addressable bits.
484 ///
485 /// \param[in] type
486 /// See \ref Mask Address Methods description of this argument.
487 /// eAddressMaskTypeAll is often a suitable value when the
488 /// same mask is being set for both code and data.
489 ///
490 /// \param[in] num_bits
491 /// Number of bits that are used for addressing.
492 /// For example, a value of 42 indicates that the low 42 bits
493 /// are relevant for addressing, and that higher-order bits may
494 /// be used for various metadata like pointer authentication,
495 /// Type Byte Ignore, etc.
496 ///
497 /// \param[in] addr_range
498 /// See \ref Mask Address Methods description of this argument.
499 /// This will default to eAddressMaskRangeLow which is the
500 /// only set of masks used normally.
501 void
502 SetAddressableBits(AddressMaskType type, uint32_t num_bits,
504
505 /// Clear the non-address bits of an \a addr value and return a
506 /// virtual address in memory.
507 ///
508 /// Bits that are not used in addressing may be used for other purposes;
509 /// pointer authentication, or metadata in the top byte, or the 0th bit
510 /// of armv7 code addresses to indicate arm/thumb are common examples.
511 ///
512 /// \param[in] addr
513 /// The address that should be cleared of non-address bits.
514 ///
515 /// \param[in] type
516 /// See \ref Mask Address Methods description of this argument.
517 /// eAddressMaskTypeAny is the default value, correct when it
518 /// is unknown if the address is a code or data address.
520 FixAddress(lldb::addr_t addr,
522 /// \}
523
524 /// Allocate memory within the process.
525 ///
526 /// This function will allocate memory in the process's address space.
527 ///
528 /// \param[in] size
529 /// The size of the allocation requested.
530 ///
531 /// \param[in] permissions
532 /// Or together any of the lldb::Permissions bits. The
533 /// permissions on a given memory allocation can't be changed
534 /// after allocation. Note that a block that isn't set writable
535 /// can still be written from lldb, just not by the process
536 /// itself.
537 ///
538 /// \param[out] error
539 /// An error object that gets filled in with any errors that
540 /// might occur when trying allocate.
541 ///
542 /// \return
543 /// The address of the allocated buffer in the process, or
544 /// LLDB_INVALID_ADDRESS if the allocation failed.
545 lldb::addr_t AllocateMemory(size_t size, uint32_t permissions,
547
548 /// Deallocate memory in the process.
549 ///
550 /// This function will deallocate memory in the process's address
551 /// space that was allocated with AllocateMemory.
552 ///
553 /// \param[in] ptr
554 /// A return value from AllocateMemory, pointing to the memory you
555 /// want to deallocate.
556 ///
557 /// \return
558 /// An error object describes any errors that occurred while
559 /// deallocating.
560 ///
561 lldb::SBError DeallocateMemory(lldb::addr_t ptr);
562
563 lldb::SBScriptObject GetScriptedImplementation();
564
565 void GetStatus(SBStream &status);
566
567protected:
568 friend class SBAddress;
569 friend class SBBreakpoint;
573 friend class SBDebugger;
574 friend class SBExecutionContext;
575 friend class SBFunction;
576 friend class SBModule;
577 friend class SBPlatform;
578 friend class SBTarget;
579 friend class SBThread;
580 friend class SBValue;
582
583 friend class lldb_private::python::SWIGBridge;
584
585 SBProcess(const lldb::ProcessSP &process_sp);
586
587 lldb::ProcessSP GetSP() const;
588
589 void SetSP(const lldb::ProcessSP &process_sp);
590
592};
593
594} // namespace lldb
595
596#endif // LLDB_API_SBPROCESS_H
static size_t ReadCStringFromMemory(ExecutionContextScope *exe_scope, const Address &address, Stream *strm)
Definition: Address.cpp:192
static llvm::raw_ostream & error(Stream &strm)
#define LLDB_API
Definition: SBDefines.h:28
FLAGS_ANONYMOUS_ENUM()
Broadcaster event bits definitions.
Definition: SBProcess.h:32
lldb::ProcessWP m_opaque_wp
Definition: SBProcess.h:591
LLDB_DEPRECATED_FIXME("Use GetPluginName()", "GetPluginName()") const char *GetShortPluginName()
A class that represents a running process on the host machine.
Definition: SBAddress.h:15
AddressMaskRange
Used in the SBProcess AddressMask/FixAddress methods.
@ eAddressMaskRangeLow
StateType
Process and Thread States.
std::shared_ptr< lldb_private::Process > ProcessSP
Definition: lldb-forward.h:384
InstrumentationRuntimeType
uint64_t pid_t
Definition: lldb-types.h:83
ByteOrder
Byte ordering definitions.
std::weak_ptr< lldb_private::Process > ProcessWP
Definition: lldb-forward.h:387
class LLDB_API SBEvent
Definition: SBDefines.h:69
uint64_t addr_t
Definition: lldb-types.h:80
AddressMaskType
Used in the SBProcess AddressMask/FixAddress methods.
@ eAddressMaskTypeAny
std::shared_ptr< lldb_private::File > FileSP
Definition: lldb-forward.h:348
uint64_t tid_t
Definition: lldb-types.h:84