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_private { |
20 | namespace python { |
21 | class SWIGBridge; |
22 | } |
23 | } // namespace lldb_private |
24 | |
25 | namespace lldb { |
26 | |
27 | class SBEvent; |
28 | |
29 | class LLDB_API SBProcess { |
30 | public: |
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 ®ion_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 | |
451 | protected: |
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 | |