Debian Codegraph @

libdrgn/drgn.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // SPDX-License-Identifier: LGPL-2.1-or-later
3
4 /**
5 * @file
6 *
7 * libdrgn public interface.
8 */
9
10 #ifndef DRGN_H
11 #define DRGN_H
12
13 // IWYU pragma: begin_exports
14 #include <stdbool.h>
15 #include <stddef.h>
16 #include <stdint.h>
17 // IWYU pragma: end_exports
18
19 #include <limits.h>
20 #include <stdarg.h>
21 #include <stdio.h>
22 #include <string.h>
23 #include <sys/types.h>
24
25 /**
26 * @mainpage
27 *
28 * libdrgn provides the functionality of the
29 * [drgn](https://github.com/osandov/drgn) programmable debugger as a library.
30 * It implements the main drgn abstractions: @ref Programs, @ref Types, @ref
31 * Objects, and @ref StackTraces. See [Topics](topics.html) for detailed
32 * documentation.
33 *
34 * @subsection ThreadSafety Thread Safety
35 *
36 * Only one thread at a time should access the same @ref drgn_program (including
37 * @ref drgn_object, @ref drgn_type, @ref drgn_stack_trace, etc. from that
38 * program). It is safe to use different @ref drgn_program%s from concurrent
39 * threads.
40 */
41
42 /** Major version of drgn. */
43 #define DRGN_VERSION_MAJOR 0
44 /** Minor version of drgn. */
45 #define DRGN_VERSION_MINOR 2
46 /** Patch level of drgn. */
47 #define DRGN_VERSION_PATCH 0
48
49 /**
50 * @defgroup ErrorHandling Error handling
51 *
52 * Error handling in libdrgn.
53 *
54 * Operations in libdrgn can fail for various reasons. libdrgn returns errors as
55 * @ref drgn_error.
56 *
57 * @{
58 */
59
60 /** Error code for a @ref drgn_error. */
61 enum drgn_error_code {
62 /** Cannot allocate memory. */
63 DRGN_ERROR_NO_MEMORY,
64 /** Stop iteration. */
65 DRGN_ERROR_STOP,
66 /** Miscellaneous error. */
67 DRGN_ERROR_OTHER,
68 /** Invalid argument. */
69 DRGN_ERROR_INVALID_ARGUMENT,
70 /** Integer overflow. */
71 DRGN_ERROR_OVERFLOW,
72 /** Maximum recursion depth exceeded. */
73 DRGN_ERROR_RECURSION,
74 /** System call error. */
75 DRGN_ERROR_OS,
76 /** One or more files do not have debug information. */
77 DRGN_ERROR_MISSING_DEBUG_INFO,
78 /** Syntax error while parsing. */
79 DRGN_ERROR_SYNTAX,
80 /** Entry not found. */
81 DRGN_ERROR_LOOKUP,
82 /** Bad memory access. */
83 DRGN_ERROR_FAULT,
84 /** Type error in expression. */
85 DRGN_ERROR_TYPE,
86 /** Division by zero. */
87 DRGN_ERROR_ZERO_DIVISION,
88 /** Array out of bounds */
89 DRGN_ERROR_OUT_OF_BOUNDS,
90 /** Operation was attempted with absent object. */
91 DRGN_ERROR_OBJECT_ABSENT,
92 /** Functionality is not implemented. */
93 DRGN_ERROR_NOT_IMPLEMENTED,
94 /** Number of defined error codes. */
95 DRGN_NUM_ERROR_CODES,
96 } __attribute__((__packed__));
97
98 /**
99 * libdrgn error.
100 *
101 * All functions in libdrgn that can return an error return this type.
102 */
103 struct drgn_error {
104 /** Error code. */
105 enum drgn_error_code code;
106 /**
107 * @private
108 *
109 * Whether this error needs to be passed to @ref drgn_error_destroy().
110 *
111 * This is @c true for the error codes returned from @ref
112 * drgn_error_create() and its related functions. Certain errors are
113 * statically allocated and do not need to be passed to @ref
114 * drgn_error_destroy() (but they can be).
115 */
116 bool needs_destroy;
117 /**
118 * If @c code is @c DRGN_ERROR_OS, then the error number returned from
119 * the system call.
120 */
121 int errnum;
122 /**
123 * If @c code is @c DRGN_ERROR_OS, then the path of the file which
124 * encountered the error if applicable. Otherwise, @c NULL.
125 */
126 char *path;
127 /**
128 * If @c code is @c DRGN_ERROR_FAULT, then the address of the read
129 * which encountered the error.
130 */
131 uint64_t address;
132 /** Human-readable error message. */
133 char *message;
134 };
135
136 /**
137 * Out of memory @ref drgn_error.
138 *
139 * This has a code of @ref DRGN_ERROR_NO_MEMORY. It can be returned if a memory
140 * allocation fails in order to avoid doing another memory allocation. It does
141 * not need to be passed to @ref drgn_error_destroy() (but it can be).
142 */
143 extern struct drgn_error drgn_enomem;
144
145 /**
146 * Non-fatal lookup @ref drgn_error.
147 *
148 * This has a code of @ref DRGN_ERROR_LOOKUP. It does not need to be passed to
149 * @ref drgn_error_destroy() (but it can be).
150 */
151 extern struct drgn_error drgn_not_found;
152
153 /**
154 * Create a @ref drgn_error.
155 *
156 * @param[in] code Error code.
157 * @param[in] message Human-readable error message. This string is copied.
158 * @return A new error with the given code and message. If there is a failure to
159 * allocate memory for the error or the message, @ref drgn_enomem is returned
160 * instead.
161 */
162 struct drgn_error *drgn_error_create(enum drgn_error_code code,
163 const char *message)
164 __attribute__((__returns_nonnull__));
165
166 /**
167 * Create a @ref drgn_error from a printf-style format.
168 *
169 * @param[in] code Error code.
170 * @param[in] format printf-style format string.
171 * @param[in] ... Arguments for the format string.
172 * @return A new error with the given code and formatted message. If there is a
173 * failure to allocate memory for the error or the message, @ref drgn_enomem is
174 * returned instead.
175 */
176 struct drgn_error *drgn_error_format(enum drgn_error_code code,
177 const char *format, ...)
178 __attribute__((__returns_nonnull__, __format__(__printf__, 2, 3)));
179
180 /**
181 * Create a @ref DRGN_ERROR_OS @ref drgn_error.
182 *
183 * @sa drgn_error_create().
184 *
185 * @param[in] errnum Error number (i.e., @c errno).
186 * @param[in] path If not @c NULL, the path of the file which encountered the
187 * error. This string is copied.
188 */
189 struct drgn_error *drgn_error_create_os(const char *message, int errnum,
190 const char *path)
191 __attribute__((__returns_nonnull__));
192
193 /**
194 * Create a @ref DRGN_ERROR_OS @ref drgn_error with a printf-style formatted
195 * path.
196 *
197 * @param[in] errnum Error number (i.e., @c errno).
198 * @param[in] path_format printf-style format string for path.
199 * @param[in] ... Arguments for the format string.
200 */
201 struct drgn_error *drgn_error_format_os(const char *message, int errnum,
202 const char *path_format, ...)
203 __attribute__((__returns_nonnull__, __format__(__printf__, 3, 4)));
204
205 /**
206 * Create a @ref DRGN_ERROR_FAULT @ref drgn_error.
207 *
208 * @param[in] message Human-readable error message. This string is copied.
209 * @param[in] address Address where the fault happened.
210 */
211 struct drgn_error *drgn_error_create_fault(const char *message, uint64_t address)
212 __attribute__((__returns_nonnull__));
213
214 /**
215 *
216 * Create a @ref DRGN_ERROR_FAULT @ref drgn_error with a printf-style formatted
217 * message.
218 *
219 * @param[in] address Address where the fault happened.
220 * @param[in] format printf-style format string for message.
221 * @param[in] ... Arguments for the format string.
222 */
223 struct drgn_error *drgn_error_format_fault(uint64_t address,
224 const char *format, ...)
225 __attribute__((__returns_nonnull__, __format__(__printf__, 2, 3)));
226
227 /*
228 * Create a copy of a @ref drgn_error.
229 *
230 * The source's error message and path are copied if necessary, so the source
231 * error can be destroyed without affecting the new error and vice versa.
232 *
233 * @param[in] src Error to copy.
234 * @return A new error with the same fields. If there is a failure to allocate
235 * memory, @ref drgn_enomem is returned instead.
236 */
237 struct drgn_error *drgn_error_copy(struct drgn_error *src)
238 __attribute__((__returns_nonnull__));
239
240 /**
241 * Return a string representation of a @ref drgn_error.
242 *
243 * @param[in] err Error to write.
244 * @return Returned string, or @c NULL if memory could not be allocated. On
245 * success, must be freed with @c free().
246 */
247 char *drgn_error_string(struct drgn_error *err);
248
249 /**
250 * Write a @ref drgn_error followed by a newline to a @c stdio stream.
251 *
252 * @param[in] file File to write to (usually @c stderr).
253 * @param[in] err Error to write.
254 * @return Non-negative on success, negative on failure.
255 */
256 int drgn_error_fwrite(FILE *file, struct drgn_error *err);
257
258 /**
259 * Write a @ref drgn_error followed by a newline to a file descriptor.
260 *
261 * @param[in] fd File descriptor to write to.
262 * @param[in] err Error to write.
263 * @return Non-negative on success, negative on failure.
264 */
265 int drgn_error_dwrite(int fd, struct drgn_error *err);
266
267 /**
268 * Free a @ref drgn_error.
269 *
270 * This must be called on any error returned from libdrgn unless otherwise
271 * noted.
272 *
273 * @param[in] err Error to destroy. If @c NULL, this is a no-op.
274 */
275 void drgn_error_destroy(struct drgn_error *err);
276
277 /** @} */
278
279
280 /**
281 * @defgroup Languages Languages
282 *
283 * Programming languages.
284 *
285 * @{
286 */
287
288 struct drgn_language; // IWYU pragma: export
289
290 /** C */
291 extern const struct drgn_language drgn_language_c;
292 /** C++ */
293 extern const struct drgn_language drgn_language_cpp;
294
295 /** Get the name of a @ref drgn_language. */
296 const char *drgn_language_name(const struct drgn_language *lang);
297
298 /** @} */
299
300 /**
301 * @ingroup Types
302 *
303 * Kinds of types.
304 *
305 * Every type in a program supported by libdrgn falls into one of these
306 * categories.
307 */
308 enum drgn_type_kind {
309 /** Void type. */
310 DRGN_TYPE_VOID = 1,
311 /** Integer type. */
312 DRGN_TYPE_INT,
313 /** Boolean type. */
314 DRGN_TYPE_BOOL,
315 /** Floating-point type. */
316 DRGN_TYPE_FLOAT,
317 /** Structure type. */
318 DRGN_TYPE_STRUCT,
319 /** Union type. */
320 DRGN_TYPE_UNION,
321 /** Class type. */
322 DRGN_TYPE_CLASS,
323 /** Enumerated type. */
324 DRGN_TYPE_ENUM,
325 /** Type definition (a.k.a.\ alias) type. */
326 DRGN_TYPE_TYPEDEF,
327 /** Pointer type. */
328 DRGN_TYPE_POINTER,
329 /** Array type. */
330 DRGN_TYPE_ARRAY,
331 /** Function type. */
332 DRGN_TYPE_FUNCTION,
333 } __attribute__((__packed__));
334
335 /**
336 * @ingroup Types
337 *
338 * Type qualifiers.
339 *
340 * Some languages, like C, have the notion of qualifiers which add properties to
341 * a type. Qualifiers are represented as a bitmask; each qualifier is a bit.
342 */
343 enum drgn_qualifiers {
344 /** Constant type. */
345 DRGN_QUALIFIER_CONST = (1 << 0),
346 /** Volatile type. */
347 DRGN_QUALIFIER_VOLATILE = (1 << 1),
348 /** Restrict type. */
349 DRGN_QUALIFIER_RESTRICT = (1 << 2),
350 /** Atomic type. */
351 DRGN_QUALIFIER_ATOMIC = (1 << 3),
352 /** Bitmask of all valid qualifiers. */
353 DRGN_ALL_QUALIFIERS = (1 << 4) - 1,
354 } __attribute__((__packed__));
355
356 /**
357 * @ingroup Types
358 *
359 * Qualified type.
360 *
361 * A type with qualifiers.
362 *
363 * @sa drgn_qualifiers
364 */
365 struct drgn_qualified_type {
366 /** Unqualified type. */
367 struct drgn_type *type;
368 /** Bitmask of qualifiers on this type. */
369 enum drgn_qualifiers qualifiers;
370 };
371
372 #ifndef DRGN_ACCESSOR_LINKAGE
373 #define DRGN_ACCESSOR_LINKAGE extern
374 #endif
375
376 /**
377 * @ingroup Types
378 *
379 * Get the program that a @ref drgn_type is from.
380 */
381 DRGN_ACCESSOR_LINKAGE
382 struct drgn_program *drgn_type_program(struct drgn_type *type);
383
384 /**
385 * @ingroup Types
386 *
387 * Get the language of a type.
388 */
389 DRGN_ACCESSOR_LINKAGE
390 const struct drgn_language *drgn_type_language(struct drgn_type *type);
391
392 /**
393 * @defgroup Platforms Platforms
394 *
395 * Program platforms (i.e., architecture and ABI).
396 *
397 * @{
398 */
399
400 /** An instruction set architecture. */
401 enum drgn_architecture {
402 DRGN_ARCH_UNKNOWN,
403 DRGN_ARCH_X86_64,
404 DRGN_ARCH_I386,
405 DRGN_ARCH_AARCH64,
406 DRGN_ARCH_ARM,
407 DRGN_ARCH_PPC64,
408 DRGN_ARCH_RISCV64,
409 DRGN_ARCH_RISCV32,
410 DRGN_ARCH_S390X,
411 DRGN_ARCH_S390,
412 };
413
414 /** Flags describing a @ref drgn_platform. */
415 enum drgn_platform_flags {
416 /** Platform is 64-bit. */
417 DRGN_PLATFORM_IS_64_BIT = (1 << 0),
418 /** Platform is little-endian. */
419 DRGN_PLATFORM_IS_LITTLE_ENDIAN = (1 << 1),
420 /** All valid platform flags. */
421 DRGN_ALL_PLATFORM_FLAGS = (1 << 2) - 1,
422 /** Use the default flags for the architecture. */
423 DRGN_PLATFORM_DEFAULT_FLAGS = UINT_MAX,
424 };
425
426 /**
427 * @struct drgn_platform
428 *
429 * The environment that a program runs on.
430 */
431 struct drgn_platform; // IWYU pragma: export
432
433 /**
434 * @struct drgn_register
435 *
436 * A processor register.
437 */
438 struct drgn_register; // IWYU pragma: export
439
440 /**
441 * Create a @ref drgn_platform.
442 *
443 * The returned platform should be destroyed with @ref drgn_platform_destroy().
444 */
445 struct drgn_error *drgn_platform_create(enum drgn_architecture arch,
446 enum drgn_platform_flags flags,
447 struct drgn_platform **ret);
448
449 /** Destroy a @ref drgn_platform. */
450 void drgn_platform_destroy(struct drgn_platform *platform);
451
452 /** Get the instruction set architecture of a @ref drgn_platform. */
453 enum drgn_architecture drgn_platform_arch(const struct drgn_platform *platform);
454
455 /** Get the flags of a @ref drgn_platform. */
456 enum drgn_platform_flags
457 drgn_platform_flags(const struct drgn_platform *platform);
458
459 /** Get the number of @ref drgn_register's on a @ref drgn_platform. */
460 size_t drgn_platform_num_registers(const struct drgn_platform *platform);
461
462 /** Get the @p n-th @ref drgn_register of a @ref drgn_platform. */
463 const struct drgn_register *
464 drgn_platform_register(const struct drgn_platform *platform, size_t n);
465
466 /** Get a @ref drgn_register in a @ref drgn_platform by its name. */
467 const struct drgn_register *
468 drgn_platform_register_by_name(const struct drgn_platform *platform,
469 const char *name);
470
471 /** Return whether two platforms are identical. */
472 bool drgn_platform_eq(struct drgn_platform *a, struct drgn_platform *b);
473
474 /** Platform that drgn was compiled for. */
475 extern const struct drgn_platform drgn_host_platform;
476
477 /**
478 * Get the names of a @ref drgn_register.
479 *
480 * @param[out] num_names_ret Returned number of names.
481 * @return Array of names.
482 */
483 const char * const *drgn_register_names(const struct drgn_register *reg,
484 size_t *num_names_ret);
485
486 /** @} */
487
488 struct drgn_object;
489 struct drgn_thread;
490
491 /**
492 * @defgroup Programs Programs
493 *
494 * Debugging programs.
495 *
496 * A program being debugged is represented by a @ref drgn_program.
497 *
498 * @{
499 */
500
501 /**
502 * @struct drgn_program
503 *
504 * Program being debugged.
505 *
506 * A @ref drgn_program represents a crashed or running program. It supports
507 * looking up objects (@ref drgn_program_find_object()) and types (@ref
508 * drgn_program_find_type()) by name and reading arbitrary memory from the
509 * program (@ref drgn_program_read_memory()).
510 *
511 * A @ref drgn_program is created with @ref drgn_program_from_core_dump(), @ref
512 * drgn_program_from_kernel(), or @ref drgn_program_from_pid(). It must be freed
513 * with @ref drgn_program_destroy().
514 */
515 struct drgn_program; // IWYU pragma: export
516
517 /** Flags which apply to a @ref drgn_program. */
518 enum drgn_program_flags {
519 /** The program is the Linux kernel. */
520 DRGN_PROGRAM_IS_LINUX_KERNEL = (1 << 0),
521 /** The program is currently running. */
522 DRGN_PROGRAM_IS_LIVE = (1 << 1),
523 /** The program is running on the local machine. */
524 DRGN_PROGRAM_IS_LOCAL = (1 << 2),
525 };
526
527 /**
528 * Create a @ref drgn_program.
529 *
530 * Usually, @ref drgn_program_from_core_dump(), @ref drgn_program_from_kernel(),
531 * and @ref drgn_program_from_pid() are more convenient to use. However, this
532 * can be used if more flexibility is required.
533 *
534 * @param[in] platform Platform that this program runs on, or @c NULL if it
535 * should be determined automatically. This is copied.
536 * @param[out] ret Returned program.
537 * @return @c NULL on success, non-@c NULL on error.
538 */
539 struct drgn_error *drgn_program_create(const struct drgn_platform *platform,
540 struct drgn_program **ret);
541
542 /**
543 * Free a @ref drgn_program.
544 *
545 * @param[in] prog Program to free.
546 */
547 void drgn_program_destroy(struct drgn_program *prog);
548
549 /**
550 * Callback implementing a memory read.
551 *
552 * @param[out] buf Buffer to read into.
553 * @param[in] address Address which we are reading from.
554 * @param[in] count Number of bytes to read.
555 * @param[in] offset Offset in bytes of @p address from the beginning of the
556 * segment.
557 * @param[in] arg Argument passed to @ref drgn_program_add_memory_segment().
558 * @param[in] physical Whether @c address is physical.
559 * @return @c NULL on success, non-@c NULL on error.
560 */
561 typedef struct drgn_error *(*drgn_memory_read_fn)(void *buf, uint64_t address,
562 size_t count, uint64_t offset,
563 void *arg, bool physical);
564
565 /**
566 * Register a segment of memory in a @ref drgn_program.
567 *
568 * If the segment overlaps a previously registered segment, the new segment
569 * takes precedence. If any part of the segment is beyond the maximum address,
570 * that part is ignored.
571 *
572 * @param[in] address Address of the segment.
573 * @param[in] size Size of the segment in bytes.
574 * @param[in] read_fn Callback to read from segment.
575 * @param[in] arg Argument to pass to @p read_fn.
576 * @param[in] physical Whether to add a physical memory segment.
577 * @return @c NULL on success, non-@c NULL on error.
578 */
579 struct drgn_error *
580 drgn_program_add_memory_segment(struct drgn_program *prog, uint64_t address,
581 uint64_t size, drgn_memory_read_fn read_fn,
582 void *arg, bool physical);
583
584 /**
585 * Return whether a filename containing a definition (@p haystack) matches a
586 * filename being searched for (@p needle).
587 *
588 * The path is matched from right to left, so a definition in
589 * <tt>/usr/include/stdio.h</tt> will match <tt>stdio.h</tt>,
590 * <tt>include/stdio.h</tt>, <tt>usr/include/stdio.h</tt>, and
591 * <tt>/usr/include/stdio.h</tt>. An empty or @c NULL @p needle matches any @p
592 * haystack.
593 */
594 bool drgn_filename_matches(const char *haystack, const char *needle);
595
596 enum {
597 /** Enable a handler after all enabled handlers. */
598 DRGN_HANDLER_REGISTER_ENABLE_LAST = SIZE_MAX,
599 /** Don't enable a handler. */
600 DRGN_HANDLER_REGISTER_DONT_ENABLE = SIZE_MAX - 1,
601 };
602
603 /** Type finder callback table. */
604 struct drgn_type_finder_ops {
605 /**
606 * Callback to destroy the type finder.
607 *
608 * This may be @c NULL.
609 *
610 * @param[in] arg Argument passed to @ref
611 * drgn_program_register_type_finder().
612 */
613 void (*destroy)(void *arg);
614 /**
615 * Callback for finding a type.
616 *
617 * @param[in] kinds Kinds of types to find, as a bitmask of bits shifted
618 * by @ref drgn_type_kind. E.g., `(1 << DRGN_TYPE_STRUCT) | (1 <<
619 * DRGN_TYPE_CLASS)` means to find a structure or class type.
620 * @param[in] name Name of type (or tag, for structs, unions, and
621 * enums). This is @em not null-terminated.
622 * @param[in] name_len Length of @p name.
623 * @param[in] filename Filename containing the type definition or @c
624 * NULL. This should be matched with @ref drgn_filename_matches().
625 * @param[in] arg Argument passed to @ref
626 * drgn_program_register_type_finder().
627 * @param[out] ret Returned type.
628 * @return @c NULL on success, non-@c NULL on error. In particular, if
629 * the type is not found, this should return &@ref drgn_not_found; any
630 * other errors are considered fatal.
631 */
632 struct drgn_error *(*find)(uint64_t kinds, const char *name,
633 size_t name_len, const char *filename,
634 void *arg, struct drgn_qualified_type *ret);
635 };
636
637 /**
638 * Register a type finding callback.
639 *
640 * @param[in] name Finder name. This is copied.
641 * @param[in] ops Callback table. This is copied.
642 * @param[in] arg Argument to pass to callbacks.
643 * @param[in] enable_index Insert the finder into the list of enabled finders at
644 * the given index. If @ref DRGN_HANDLER_REGISTER_ENABLE_LAST or greater than
645 * the number of enabled finders, insert it at the end. If @ref
646 * DRGN_HANDLER_REGISTER_DONT_ENABLE, don’t enable the finder.
647 */
648 struct drgn_error *
649 drgn_program_register_type_finder(struct drgn_program *prog, const char *name,
650 const struct drgn_type_finder_ops *ops,
651 void *arg, size_t enable_index);
652
653 /**
654 * Get the names of all registered type finders.
655 *
656 * The order of the names is arbitrary.
657 *
658 * @param[out] names_ret Returned array of names.
659 * @param[out] count_ret Returned number of names in @p names_ret.
660 */
661 struct drgn_error *
662 drgn_program_registered_type_finders(struct drgn_program *prog,
663 const char ***names_ret,
664 size_t *count_ret);
665
666 /**
667 * Set the list of enabled type finders.
668 *
669 * Finders are called in the same order as the list until a type is found.
670 *
671 * @param[in] names Names of finders to enable, in order.
672 * @param[in] count Number of names in @p names.
673 */
674 struct drgn_error *
675 drgn_program_set_enabled_type_finders(struct drgn_program *prog,
676 const char * const *names,
677 size_t count);
678
679 /**
680 * Get the names of enabled type finders, in order.
681 *
682 * @param[out] names_ret Returned array of names.
683 * @param[out] count_ret Returned number of names in @p names_ret.
684 */
685 struct drgn_error *drgn_program_enabled_type_finders(struct drgn_program *prog,
686 const char ***names_ret,
687 size_t *count_ret);
688
689 /** Flags for @ref drgn_program_find_object(). */
690 enum drgn_find_object_flags {
691 /** Find a constant (e.g., enumeration constant or macro). */
692 DRGN_FIND_OBJECT_CONSTANT = 1 << 0,
693 /** Find a function. */
694 DRGN_FIND_OBJECT_FUNCTION = 1 << 1,
695 /** Find a variable. */
696 DRGN_FIND_OBJECT_VARIABLE = 1 << 2,
697 /** Find any kind of object. */
698 DRGN_FIND_OBJECT_ANY = (1 << 3) - 1,
699 };
700
701 /** Object finder callback table. */
702 struct drgn_object_finder_ops {
703 /**
704 * Callback to destroy the object finder.
705 *
706 * This may be @c NULL.
707 *
708 * @param[in] arg Argument passed to @ref
709 * drgn_program_register_object_finder().
710 */
711 void (*destroy)(void *arg);
712 /**
713 * Callback for finding an object.
714 *
715 * @param[in] name Name of object. This is @em not null-terminated.
716 * @param[in] name_len Length of @p name.
717 * @param[in] filename Filename containing the object definition or @c
718 * NULL. This should be matched with @ref drgn_filename_matches().
719 * @param[in] flags Flags indicating what kind of object to look for.
720 * @param[in] arg Argument passed to @ref
721 * drgn_program_register_object_finder().
722 * @param[out] ret Returned object. This must only be modified on
723 * success.
724 * @return @c NULL on success, non-@c NULL on error. In particular, if
725 * the object is not found, this should return &@ref drgn_not_found; any
726 * other errors are considered fatal.
727 */
728 struct drgn_error *(*find)(const char *name, size_t name_len,
729 const char *filename,
730 enum drgn_find_object_flags flags,
731 void *arg, struct drgn_object *ret);
732 };
733
734 /**
735 * Register an object finding callback.
736 *
737 * @param[in] name Finder name. This is copied.
738 * @param[in] ops Callback table. This is copied.
739 * @param[in] arg Argument to pass to callbacks.
740 * @param[in] enable_index Insert the finder into the list of enabled finders at
741 * the given index. If @ref DRGN_HANDLER_REGISTER_ENABLE_LAST or greater than
742 * the number of enabled finders, insert it at the end. If @ref
743 * DRGN_HANDLER_REGISTER_DONT_ENABLE, don’t enable the finder.
744 */
745 struct drgn_error *
746 drgn_program_register_object_finder(struct drgn_program *prog, const char *name,
747 const struct drgn_object_finder_ops *ops,
748 void *arg, size_t enable_index);
749
750 /**
751 * Get the names of all registered object finders.
752 *
753 * The order of the names is arbitrary.
754 *
755 * @param[out] names_ret Returned array of names.
756 * @param[out] count_ret Returned number of names in @p names_ret.
757 */
758 struct drgn_error *
759 drgn_program_registered_object_finders(struct drgn_program *prog,
760 const char ***names_ret,
761 size_t *count_ret);
762
763 /**
764 * Set the list of enabled object finders.
765 *
766 * Finders are called in the same order as the list until a object is found.
767 *
768 * @param[in] names Names of finders to enable, in order.
769 * @param[in] count Number of names in @p names.
770 */
771 struct drgn_error *
772 drgn_program_set_enabled_object_finders(struct drgn_program *prog,
773 const char * const *names,
774 size_t count);
775
776 /**
777 * Get the names of enabled object finders, in order.
778 *
779 * @param[out] names_ret Returned array of names.
780 * @param[out] count_ret Returned number of names in @p names_ret.
781 */
782 struct drgn_error *
783 drgn_program_enabled_object_finders(struct drgn_program *prog,
784 const char ***names_ret, size_t *count_ret);
785
786 /**
787 * Set a @ref drgn_program to a core dump.
788 *
789 * @sa drgn_program_from_core_dump()
790 *
791 * @param[in] path Core dump file path.
792 * @return @c NULL on success, non-@c NULL on error.
793 */
794 struct drgn_error *drgn_program_set_core_dump(struct drgn_program *prog,
795 const char *path);
796
797 /**
798 * Set a @ref drgn_program to a core dump from a file descriptor.
799 *
800 * @param[in] fd Core dump file descriptor.
801 * @return @c NULL on success, non-@c NULL on error.
802 */
803 struct drgn_error *drgn_program_set_core_dump_fd(struct drgn_program *prog, int fd);
804
805 /**
806 * Set a @ref drgn_program to the running operating system kernel.
807 *
808 * @return @c NULL on success, non-@c NULL on error.
809 */
810 struct drgn_error *drgn_program_set_kernel(struct drgn_program *prog);
811
812 /**
813 * Set a @ref drgn_program to a custom Linux kernel target.
814 *
815 * This enables debugging a Linux kernel via a custom memory transport
816 * (e.g., RDMA, TCP/IP, or VMM introspection). It sets up page table walking
817 * for virtual address translation.
818 *
819 * Physical memory segment(s) must be registered via @ref
820 * drgn_program_add_memory_segment() with physical=true before reading memory.
821 * Platform must be set when creating the program.
822 *
823 * @param[in] vmcoreinfo Raw vmcoreinfo data. If vmcoreinfo was already set
824 * when creating the program, this is ignored.
825 * @param[in] vmcoreinfo_size Size of vmcoreinfo data in bytes.
826 * @param[in] is_live Whether the kernel is currently running.
827 * @return @c NULL on success, non-@c NULL on error.
828 */
829 struct drgn_error *
830 drgn_program_set_linux_kernel_custom(struct drgn_program *prog,
831 const char *vmcoreinfo,
832 size_t vmcoreinfo_size, bool is_live);
833
834 /**
835 * Set a @ref drgn_program to a running process.
836 *
837 * @sa drgn_program_from_pid()
838 *
839 * @param[in] pid Process ID.
840 * @return @c NULL on success, non-@c NULL on error.
841 */
842 struct drgn_error *drgn_program_set_pid(struct drgn_program *prog, pid_t pid);
843
844 /**
845 * Set a @ref drgn_program to a QEMU guest over the QEMU Machine Protocol (QMP).
846 *
847 * @param[in] address QMP socket address (Unix domain socket path or TCP address
848 * in `host:port` format).
849 * @return @c NULL on success, non-@c NULL on error.
850 */
851 struct drgn_error *drgn_program_set_qemu_qmp(struct drgn_program *prog,
852 const char *address);
853
854 /**
855 * Set a @ref drgn_program to a QEMU guest over a QEMU Machine Protocol (QMP)
856 * file descriptor.
857 *
858 * @param[in] fd QMP socket file descriptor.
859 * @return @c NULL on success, non-@c NULL on error.
860 */
861 struct drgn_error *drgn_program_set_qemu_qmp_fd(struct drgn_program *prog,
862 int fd);
863
864 /**
865 * Create a @ref drgn_program from a core dump file.
866 *
867 * The type of program (e.g., userspace or kernel) is determined automatically.
868 *
869 * @param[in] path Core dump file path.
870 * @param[out] ret Returned program.
871 * @return @c NULL on success, non-@c NULL on error.
872 */
873 struct drgn_error *drgn_program_from_core_dump(const char *path,
874 struct drgn_program **ret);
875
876 /**
877 * Create a @ref drgn_program from a core dump file descriptor.
878 *
879 * Same as @ref drgn_program_from_core_dump but with an already-opened file
880 * descriptor.
881 *
882 * @param[in] fd Core dump file path descriptor.
883 * @param[out] ret Returned program.
884 * @return @c NULL on success, non-@c NULL on error.
885 */
886 struct drgn_error *drgn_program_from_core_dump_fd(int fd,
887 struct drgn_program **ret);
888
889 /**
890 * Create a @ref drgn_program from the running operating system kernel.
891 *
892 * This requires root privileges.
893 *
894 * @param[out] ret Returned program.
895 * @return @c NULL on success, non-@c NULL on error.
896 */
897 struct drgn_error *drgn_program_from_kernel(struct drgn_program **ret);
898
899 /**
900 * Create a @ref drgn_program from the a running program.
901 *
902 * On Linux, this requires @c PTRACE_MODE_ATTACH_FSCREDS permissions (see
903 * <tt>ptrace(2)</tt>).
904 *
905 * @param[in] pid Process ID of the program to debug.
906 * @param[out] ret Returned program.
907 * @return @c NULL on success, non-@c NULL on error.
908 */
909 struct drgn_error *drgn_program_from_pid(pid_t pid, struct drgn_program **ret);
910
911 /** Get the set of @ref drgn_program_flags applying to a @ref drgn_program. */
912 enum drgn_program_flags drgn_program_flags(struct drgn_program *prog);
913
914 /**
915 * Get the platform of a @ref drgn_program.
916 *
917 * This remains valid until the program is destroyed. It should @em not be
918 * destroyed with @ref drgn_platform_destroy().
919 * @return non-@c NULL on success, @c NULL if the platform is not known yet.
920 */
921 const struct drgn_platform *drgn_program_platform(struct drgn_program *prog);
922
923 /**
924 * Get the size of an address in a @ref drgn_program.
925 *
926 * @param[out] ret Returned address size, in bytes.
927 */
928 struct drgn_error *drgn_program_address_size(struct drgn_program *prog,
929 uint64_t *ret);
930
931 /**
932 * Get the path of the core dump that a @ref drgn_program was created from.
933 *
934 * @return Path which is valid until the program is destroyed, or @c NULL if the
935 * program was not created from a core dump.
936 */
937 const char *drgn_program_core_dump_path(struct drgn_program *prog);
938
939 /** Get the default language of a @ref drgn_program. */
940 const struct drgn_language *drgn_program_language(struct drgn_program *prog);
941
942 /** Set the default language of a @ref drgn_program. */
943 void drgn_program_set_language(struct drgn_program *prog,
944 const struct drgn_language *lang);
945
946 /**
947 * Read from a program's memory.
948 *
949 * @param[in] prog Program to read from.
950 * @param[out] buf Buffer to read into.
951 * @param[in] address Starting address in memory to read.
952 * @param[in] count Number of bytes to read.
953 * @param[in] physical Whether @c address is physical. A program may support
954 * only virtual or physical addresses or both.
955 * @return @c NULL on success, non-@c NULL on error.
956 */
957 struct drgn_error *drgn_program_read_memory(struct drgn_program *prog,
958 void *buf, uint64_t address,
959 size_t count, bool physical);
960
961 /**
962 * Read a C string from a program's memory.
963 *
964 * This reads up to and including the terminating null byte.
965 *
966 * @param[in] prog Program to read from.
967 * @param[in] address Starting address in memory to read.
968 * @param[in] physical Whether @c address is physical. See @ref
969 * drgn_program_read_memory().
970 * @param[in] max_size Stop after this many bytes are read, not including the
971 * null byte. A null byte is appended to @p ret in this case.
972 * @param[out] ret Returned string. On success, it must be freed with @c free().
973 * On error, it is not modified.
974 * @return @c NULL on success, non-@c NULL on error.
975 */
976 struct drgn_error *drgn_program_read_c_string(struct drgn_program *prog,
977 uint64_t address, bool physical,
978 size_t max_size, char **ret);
979
980 struct drgn_error *drgn_program_read_u8(struct drgn_program *prog,
981 uint64_t address, bool physical,
982 uint8_t *ret);
983
984 struct drgn_error *drgn_program_read_u16(struct drgn_program *prog,
985 uint64_t address, bool physical,
986 uint16_t *ret);
987
988 struct drgn_error *drgn_program_read_u32(struct drgn_program *prog,
989 uint64_t address, bool physical,
990 uint32_t *ret);
991
992 struct drgn_error *drgn_program_read_u64(struct drgn_program *prog,
993 uint64_t address, bool physical,
994 uint64_t *ret);
995
996 struct drgn_error *drgn_program_read_word(struct drgn_program *prog,
997 uint64_t address, bool physical,
998 uint64_t *ret);
999
1000 /**
1001 * @defgroup MemorySearches Memory searches
1002 *
1003 * Searching program memory for values or patterns.
1004 *
1005 * @{
1006 */
1007
1008 /**
1009 * @struct drgn_memory_search_iterator
1010 *
1011 * An iterator over all matches of a value or pattern in memory.
1012 */
1013 struct drgn_memory_search_iterator; // IWYU pragma: export
1014
1015 /**
1016 * Search for all non-overlapping occurrences of a byte string in memory.
1017 *
1018 * @param needle[in] Byte string to search for. This is copied, so it need not
1019 * remain valid after this function returns.
1020 * @param[in] size Size of @p needle in bytes.
1021 * @param[in] alignment Only consider addresses aligned to this value. Must be a
1022 * power of two.
1023 * @param[out] ret Returned memory search iterator.
1024 */
1025 struct drgn_error *
1026 drgn_program_search_memory(struct drgn_program *prog, const void *needle,
1027 size_t size, uint64_t alignment,
1028 struct drgn_memory_search_iterator **ret);
1029
1030 /**
1031 * Search for all occurrences of an object's value in memory.
1032 *
1033 * @param[in] obj Object whose value to search for. Its value is copied, so it
1034 * need not remain valid after this function returns.
1035 * @param[out] ret Returned memory search iterator.
1036 */
1037 struct drgn_error *
1038 drgn_search_memory_for_object(const struct drgn_object *obj,
1039 struct drgn_memory_search_iterator **ret);
1040
1041 /**
1042 * Search for all occurrences of a 16-bit unsigned integer in memory.
1043 *
1044 * Natural alignment is assumed.
1045 *
1046 * @param[in] value Value to search for.
1047 * @param[out] ret Returned memory search iterator.
1048 */
1049 struct drgn_error *
1050 drgn_program_search_memory_u16(struct drgn_program *prog, uint16_t value,
1051 struct drgn_memory_search_iterator **ret);
1052
1053 /**
1054 * Like @ref drgn_program_search_memory_u16(), but for a 32-bit unsigned
1055 * integer.
1056 */
1057 struct drgn_error *
1058 drgn_program_search_memory_u32(struct drgn_program *prog, uint32_t value,
1059 struct drgn_memory_search_iterator **ret);
1060
1061 /**
1062 * Like @ref drgn_program_search_memory_u16(), but for a 64-bit unsigned
1063 * integer.
1064 */
1065 struct drgn_error *
1066 drgn_program_search_memory_u64(struct drgn_program *prog, uint64_t value,
1067 struct drgn_memory_search_iterator **ret);
1068
1069 /**
1070 * Like @ref drgn_program_search_memory_u16(), but for a program word-sized
1071 * unsigned integer.
1072 *
1073 * It is an error if @p value is out of range of the program word size.
1074 */
1075 struct drgn_error *
1076 drgn_program_search_memory_word(struct drgn_program *prog, uint64_t value,
1077 struct drgn_memory_search_iterator **ret);
1078
1079 /**
1080 * Search for all occurrences of one or more 16-bit unsigned integers in memory.
1081 *
1082 * Natural alignment is assumed.
1083 *
1084 * @param[in] values Values to search for. This is copied, so it need not remain
1085 * valid after this function returns. May be @c NULL if @p num_values is 0.
1086 * @param[in] num_values Number of values in @p values.
1087 * @param[in] ignore_mask Mask of bits to ignore when comparing to @p values.
1088 * @param[in] ranges Ranges to search for. `ranges[i][0]` is the minimum
1089 * (inclusive) and `ranges[i][1]` is the maximum (inclusive). This is copied, so
1090 * it need not remain valid after this function returns. May be @c NULL if @p
1091 * num_ranges is 0.
1092 * @param[in] num_ranges Number of ranges in @p ranges.
1093 * @param[out] ret Returned memory search iterator.
1094 */
1095 struct drgn_error *
1096 drgn_program_search_memory_u16_multi(struct drgn_program *prog,
1097 const uint16_t *values, size_t num_values,
1098 uint16_t ignore_mask,
1099 const uint16_t (*ranges)[2],
1100 size_t num_ranges,
1101 struct drgn_memory_search_iterator **ret);
1102
1103 /**
1104 * Like @ref drgn_program_search_memory_u16_multi(), but for 32-bit unsigned
1105 * integers.
1106 */
1107 struct drgn_error *
1108 drgn_program_search_memory_u32_multi(struct drgn_program *prog,
1109 const uint32_t *values, size_t num_values,
1110 uint32_t ignore_mask,
1111 const uint32_t (*ranges)[2],
1112 size_t num_ranges,
1113 struct drgn_memory_search_iterator **ret);
1114
1115 /**
1116 * Like @ref drgn_program_search_memory_u16_multi(), but for 64-bit unsigned
1117 * integers.
1118 */
1119 struct drgn_error *
1120 drgn_program_search_memory_u64_multi(struct drgn_program *prog,
1121 const uint64_t *values, size_t num_values,
1122 uint64_t ignore_mask,
1123 const uint64_t (*ranges)[2],
1124 size_t num_ranges,
1125 struct drgn_memory_search_iterator **ret);
1126
1127 /**
1128 * Like @ref drgn_program_search_memory_u16_multi(), but for program word-sized
1129 * unsigned integers.
1130 *
1131 * It is an error if any value is out of range of the program word size.
1132 */
1133 struct drgn_error *
1134 drgn_program_search_memory_word_multi(struct drgn_program *prog,
1135 const uint64_t *values, size_t num_values,
1136 uint64_t ignore_mask,
1137 const uint64_t (*ranges)[2],
1138 size_t num_ranges,
1139 struct drgn_memory_search_iterator **ret);
1140
1141 /**
1142 * Search for all non-overlapping matches of a regular expression pattern in
1143 * memory.
1144 *
1145 * @param[in] pattern PCRE regular expression to search for. This need not
1146 * remain valid after this function returns.
1147 * @param[in] pattern_len Length of @p pattern in bytes.
1148 * @param[in] utf8 If `false`, search for 8-bit strings. If `true`, search for
1149 * Unicode strings.
1150 * @param[out] ret Returned memory search iterator.
1151 */
1152 struct drgn_error *
1153 drgn_program_search_memory_regex(struct drgn_program *prog, const void *pattern,
1154 size_t pattern_len, bool utf8,
1155 struct drgn_memory_search_iterator **ret);
1156
1157 /** Destroy a @ref drgn_memory_search_iterator. */
1158 void drgn_memory_search_iterator_destroy(struct drgn_memory_search_iterator *it);
1159
1160 /** Get the program that a memory search iterator is from. */
1161 struct drgn_program *
1162 drgn_memory_search_iterator_program(const struct drgn_memory_search_iterator *it);
1163
1164 /**
1165 * Get the next match from a memory search.
1166 *
1167 * @param[out] addr_ret Returned address of match. May be @c NULL.
1168 * @param[out] match_ret Returned match. This is valid until the next call to
1169 * @ref drgn_memory_search_iterator_next() or @ref
1170 * drgn_memory_search_iterator_set_address_range() with the same @p it, or until
1171 * @p it is destroyed. May be @c NULL.
1172 * @param[out] match_len_ret Length of @p match_ret in bytes. May be @c NULL.
1173 */
1174 struct drgn_error *
1175 drgn_memory_search_iterator_next(struct drgn_memory_search_iterator *it,
1176 uint64_t *addr_ret, const void **match_ret,
1177 size_t *match_len_ret);
1178
1179 /**
1180 * Limit the address range of a memory search.
1181 *
1182 * This can be called before, during, or after iteration.
1183 *
1184 * @param[in] min_address Minimum address to search (inclusive).
1185 * @param[in] max_address Maximum address to search (inclusive).
1186 * @param[in] physical If `false`, search virtual memory. If `true`, search
1187 * physical memory.
1188 */
1189 struct drgn_error *
1190 drgn_memory_search_iterator_set_address_range(struct drgn_memory_search_iterator *it,
1191 uint64_t min_address,
1192 uint64_t max_address,
1193 bool physical);
1194
1195 /** @} */
1196
1197 /**
1198 * Find a type in a program by name.
1199 *
1200 * The returned type is valid for the lifetime of the @ref drgn_program.
1201 *
1202 * @param[in] prog Program.
1203 * @param[in] name Name of the type.
1204 * @param[in] filename Filename containing the type definition. This is matched
1205 * with @ref drgn_filename_matches(). If multiple definitions match, one is
1206 * returned arbitrarily.
1207 * @param[out] ret Returned type.
1208 * @return @c NULL on success, non-@c NULL on error.
1209 */
1210 struct drgn_error *drgn_program_find_type(struct drgn_program *prog,
1211 const char *name,
1212 const char *filename,
1213 struct drgn_qualified_type *ret);
1214
1215 /**
1216 * Find an object in a program by name.
1217 *
1218 * The object can be a variable, constant, or function depending on @p flags.
1219 *
1220 * @param[in] prog Program.
1221 * @param[in] name Name of the object.
1222 * @param[in] filename Filename containing the object definition. This is
1223 * matched with @ref drgn_filename_matches(). If multiple definitions match, one
1224 * is returned arbitrarily.
1225 * @param[in] flags Flags indicating what kind of object to look for.
1226 * @param[out] ret Returned object. This must have already been initialized with
1227 * @ref drgn_object_init().
1228 * @return @c NULL on success, non-@c NULL on error.
1229 */
1230 struct drgn_error *drgn_program_find_object(struct drgn_program *prog,
1231 const char *name,
1232 const char *filename,
1233 enum drgn_find_object_flags flags,
1234 struct drgn_object *ret);
1235
1236 /**
1237 * @ingroup Symbols
1238 *
1239 * @struct drgn_symbol
1240 *
1241 * A @ref drgn_symbol represents an entry in a program's symbol table.
1242 */
1243 struct drgn_symbol; // IWYU pragma: export
1244
1245 /**
1246 * Get the symbol containing the given address.
1247 *
1248 * @param[out] ret The returned symbol. It should be freed with @ref
1249 * drgn_symbol_destroy().
1250 * @return @c NULL on success, non-@c NULL on error.
1251 */
1252 struct drgn_error *
1253 drgn_program_find_symbol_by_address(struct drgn_program *prog, uint64_t address,
1254 struct drgn_symbol **ret);
1255
1256 /**
1257 * Get the symbol corresponding to the given name.
1258 *
1259 * @param[out] ret The returned symbol. It should be freed with @ref
1260 * drgn_symbol_destroy().
1261 * @return @c NULL on success, non-@c NULL on error.
1262 */
1263 struct drgn_error *drgn_program_find_symbol_by_name(struct drgn_program *prog,
1264 const char *name,
1265 struct drgn_symbol **ret);
1266
1267 /**
1268 * Get all global and local symbols, optionally with the given name.
1269 *
1270 * @param[in] prog Program.
1271 * @param[in] name Name to match. If @c NULL, returns all symbols.
1272 * @param[out] syms_ret Returned array of symbols. On success, this must be
1273 * freed with @ref drgn_symbols_destroy().
1274 * @param[out] count_ret Returned number of symbols in @p syms_ret.
1275 * @return @c NULL on success, non-@c NULL on error.
1276 */
1277 struct drgn_error *drgn_program_find_symbols_by_name(struct drgn_program *prog,
1278 const char *name,
1279 struct drgn_symbol ***syms_ret,
1280 size_t *count_ret);
1281
1282 /**
1283 * Get all symbols containing the given address.
1284 *
1285 * @param[in] prog Program.
1286 * @param[in] address Address to search for.
1287 * @param[out] syms_ret Returned array of symbols. On success, this must be
1288 * freed with @ref drgn_symbols_destroy().
1289 * @param[out] count_ret Returned number of symbols in @p syms_ret.
1290 * @return @c NULL on success, non-@c NULL on error.
1291 */
1292 struct drgn_error *drgn_program_find_symbols_by_address(struct drgn_program *prog,
1293 uint64_t address,
1294 struct drgn_symbol ***syms_ret,
1295 size_t *count_ret);
1296
1297 /** Flags for @ref drgn_symbol_finder_ops::find() */
1298 enum drgn_find_symbol_flags {
1299 /** Find symbols whose name matches the name argument */
1300 DRGN_FIND_SYMBOL_NAME = 1 << 0,
1301 /** Find symbols whose address matches the addr argument */
1302 DRGN_FIND_SYMBOL_ADDR = 1 << 1,
1303 /** Find only one symbol */
1304 DRGN_FIND_SYMBOL_ONE = 1 << 2,
1305 };
1306
1307 /** Result builder for @ref drgn_symbol_finder_ops::find() */
1308 struct drgn_symbol_result_builder;
1309
1310 /**
1311 * Add or set the return value for a symbol search
1312 *
1313 * Symbol finders should call this with each symbol search result. If the symbol
1314 * search was @ref DRGN_FIND_SYMBOL_ONE, then only the most recent symbol added
1315 * to the builder will be returned. Otherwise, all symbols added to the builder
1316 * are returned. Returns true on success, or false on an allocation failure.
1317 */
1318 bool
1319 drgn_symbol_result_builder_add(struct drgn_symbol_result_builder *builder,
1320 struct drgn_symbol *symbol);
1321
1322 /** Get the current number of results in a symbol search result. */
1323 size_t drgn_symbol_result_builder_count(const struct drgn_symbol_result_builder *builder);
1324
1325 /** Symbol finder callback table. */
1326 struct drgn_symbol_finder_ops {
1327 /**
1328 * Callback to destroy the symbol finder.
1329 *
1330 * This may be @c NULL.
1331 *
1332 * @param[in] arg Argument passed to @ref
1333 * drgn_program_register_symbol_finder().
1334 */
1335 void (*destroy)(void *arg);
1336 /**
1337 * Callback for finding one or more symbols.
1338 *
1339 * The callback should perform a symbol lookup based on the flags given
1340 * in @p flags. When multiple flags are provided, the effect should be
1341 * treated as a logical AND. Symbol results should be added to the
1342 * result builder @p builder, via @ref drgn_symbol_result_builder_add().
1343 * When @ref DRGN_FIND_SYMBOL_ONE is set, then the finding function
1344 * should only return the single best symbol result, and short-circuit
1345 * return.
1346 *
1347 * When no symbol is found, simply do not add any result to the builder.
1348 * No error should be returned in this case.
1349 *
1350 * @param[in] name Name of the symbol to match
1351 * @param[in] addr Address of the symbol to match
1352 * @param[in] flags Flags indicating the desired behavior of the search
1353 * @param[in] arg Argument passed to @ref
1354 * drgn_program_register_symbol_finder().
1355 * @param[in] builder Used to build the resulting symbol output
1356 */
1357 struct drgn_error *(*find)(const char *name, uint64_t addr,
1358 enum drgn_find_symbol_flags flags, void *arg,
1359 struct drgn_symbol_result_builder *builder);
1360 };
1361
1362 /**
1363 * Register a symbol finding callback.
1364 *
1365 * @param[in] name Finder name. This is copied.
1366 * @param[in] ops Callback table. This is copied.
1367 * @param[in] arg Argument to pass to callbacks.
1368 * @param[in] enable_index Insert the finder into the list of enabled finders at
1369 * the given index. If @ref DRGN_HANDLER_REGISTER_ENABLE_LAST or greater than
1370 * the number of enabled finders, insert it at the end. If @ref
1371 * DRGN_HANDLER_REGISTER_DONT_ENABLE, don’t enable the finder.
1372 */
1373 struct drgn_error *
1374 drgn_program_register_symbol_finder(struct drgn_program *prog, const char *name,
1375 const struct drgn_symbol_finder_ops *ops,
1376 void *arg, size_t enable_index);
1377
1378 /**
1379 * Get the names of all registered symbol finders.
1380 *
1381 * The order of the names is arbitrary.
1382 *
1383 * @param[out] names_ret Returned array of names.
1384 * @param[out] count_ret Returned number of names in @p names_ret.
1385 */
1386 struct drgn_error *
1387 drgn_program_registered_symbol_finders(struct drgn_program *prog,
1388 const char ***names_ret,
1389 size_t *count_ret);
1390
1391 /**
1392 * Set the list of enabled symbol finders.
1393 *
1394 * Finders are called in the same order as the list. In case of a search for
1395 * multiple symbols, then the results of all callbacks are concatenated. If the
1396 * search is for a single symbol, then the first callback which finds a symbol
1397 * will short-circuit the search.
1398 *
1399 * @param[in] names Names of finders to enable, in order.
1400 * @param[in] count Number of names in @p names.
1401 */
1402 struct drgn_error *
1403 drgn_program_set_enabled_symbol_finders(struct drgn_program *prog,
1404 const char * const *names,
1405 size_t count);
1406
1407 /**
1408 * Get the names of enabled symbol finders, in order.
1409 *
1410 * @param[out] names_ret Returned array of names.
1411 * @param[out] count_ret Returned number of names in @p names_ret.
1412 */
1413 struct drgn_error *
1414 drgn_program_enabled_symbol_finders(struct drgn_program *prog,
1415 const char ***names_ret, size_t *count_ret);
1416
1417 /** Element type and size. */
1418 struct drgn_element_info {
1419 /** Type of the element. */
1420 struct drgn_qualified_type qualified_type;
1421 /**
1422 * Size in bits of one element.
1423 *
1424 * Element @c i is at bit offset <tt>i * bit_size</tt>.
1425 */
1426 uint64_t bit_size;
1427 };
1428
1429 /**
1430 * Get the element type and size of an array or pointer @ref drgn_type.
1431 *
1432 * @param[in] prog Program.
1433 * @param[in] type Array or pointer. After this function is called, this type
1434 * must remain valid until the program is destroyed.
1435 * @param[out] ret Returned element information.
1436 * @return @c NULL on success, non-@c NULL on error.
1437 */
1438 struct drgn_error *drgn_program_element_info(struct drgn_program *prog,
1439 struct drgn_type *type,
1440 struct drgn_element_info *ret);
1441
1442 /** @} */
1443
1444 /**
1445 * @defgroup Modules Modules
1446 *
1447 * Modules in a program and debugging information.
1448 *
1449 * @{
1450 */
1451
1452 /**
1453 * An executable, library, or other binary file used by a program.
1454 *
1455 * Modules are uniquely identified by the combination of their kind (@ref
1456 * drgn_module_kind()), name (@ref drgn_module_name()), and info (@ref
1457 * drgn_module_info()).
1458 */
1459 struct drgn_module;
1460
1461 /** Kinds of modules. */
1462 enum drgn_module_kind {
1463 /**
1464 * Main module. For userspace programs, this is the executable. For the
1465 * Linux kernel, this is `vmlinux`.
1466 */
1467 DRGN_MODULE_MAIN,
1468 /** Shared library (a.k.a. dynamic library or dynamic shared object). */
1469 DRGN_MODULE_SHARED_LIBRARY,
1470 /** Virtual dynamic shared object (vDSO). */
1471 DRGN_MODULE_VDSO,
1472 /** Relocatable object (e.g., Linux kernel loadable module). */
1473 DRGN_MODULE_RELOCATABLE,
1474 /** Extra debugging information. */
1475 DRGN_MODULE_EXTRA,
1476 } __attribute__((__packed__));
1477
1478 /**
1479 * Find the created @ref drgn_module with the given @p name.
1480 *
1481 * If there are multiple modules with the given name, one is returned
1482 * arbitrarily.
1483 *
1484 * @return Module, or @c NULL if not found.
1485 */
1486 struct drgn_module *drgn_module_find_by_name(struct drgn_program *prog,
1487 const char *name);
1488
1489 /**
1490 * Find the created @ref drgn_module containing the given @p address.
1491 *
1492 * @return Module, or @c NULL if not found.
1493 */
1494 struct drgn_module *drgn_module_find_by_address(struct drgn_program *prog,
1495 uint64_t address);
1496
1497 /**
1498 * Find the main module.
1499 *
1500 * @param[in] name Module name, or @c NULL to match any name.
1501 */
1502 struct drgn_module *drgn_module_find_main(struct drgn_program *prog,
1503 const char *name);
1504
1505 /**
1506 * Find the main module, creating it if it doesn't already exist.
1507 *
1508 * @param[out] new_ret @c true if the module was newly created, @c false if it
1509 * was found.
1510 */
1511 struct drgn_error *drgn_module_find_or_create_main(struct drgn_program *prog,
1512 const char *name,
1513 struct drgn_module **ret,
1514 bool *new_ret);
1515
1516 /** Find a shared library module. */
1517 struct drgn_module *drgn_module_find_shared_library(struct drgn_program *prog,
1518 const char *name,
1519 uint64_t dynamic_address);
1520
1521 /**
1522 * Find a shared library module, creating it if it doesn't already exist.
1523 *
1524 * @param[out] new_ret @c true if the module was newly created, @c false if it
1525 * was found.
1526 */
1527 struct drgn_error *
1528 drgn_module_find_or_create_shared_library(struct drgn_program *prog,
1529 const char *name,
1530 uint64_t dynamic_address,
1531 struct drgn_module **ret,
1532 bool *new_ret);
1533
1534 /** Find a vDSO module. */
1535 struct drgn_module *drgn_module_find_vdso(struct drgn_program *prog,
1536 const char *name,
1537 uint64_t dynamic_address);
1538
1539 /**
1540 * Find a vDSO module, creating it if it doesn't already exist.
1541 *
1542 * @param[out] new_ret @c true if the module was newly created, @c false if it
1543 * was found.
1544 */
1545 struct drgn_error *drgn_module_find_or_create_vdso(struct drgn_program *prog,
1546 const char *name,
1547 uint64_t dynamic_address,
1548 struct drgn_module **ret,
1549 bool *new_ret);
1550
1551 /** Find a relocatable module. */
1552 struct drgn_module *drgn_module_find_relocatable(struct drgn_program *prog,
1553 const char *name,
1554 uint64_t address);
1555
1556 /**
1557 * Find a relocatable module, creating it if it doesn't already exist.
1558 *
1559 * @param[out] new_ret @c true if the module was newly created, @c false if it
1560 * was found.
1561 */
1562 struct drgn_error *
1563 drgn_module_find_or_create_relocatable(struct drgn_program *prog,
1564 const char *name, uint64_t address,
1565 struct drgn_module **ret, bool *new_ret);
1566
1567 /**
1568 * Find a created Linux kernel loadable module from a ``struct module *`` object.
1569 */
1570 struct drgn_error *
1571 drgn_module_find_linux_kernel_loadable(const struct drgn_object *module_obj,
1572 struct drgn_module **ret);
1573
1574 /**
1575 * Find a Linux kernel loadable module from a ``struct module *`` object, creating
1576 * it if it doesn't already exist.
1577 *
1578 * @param[out] new_ret @c true if the module was newly created, @c false if it
1579 * was found.
1580 */
1581 struct drgn_error *
1582 drgn_module_find_or_create_linux_kernel_loadable(const struct drgn_object *module_obj,
1583 struct drgn_module **ret,
1584 bool *new_ret);
1585
1586 /** Find an extra module. */
1587 struct drgn_module *drgn_module_find_extra(struct drgn_program *prog,
1588 const char *name, uint64_t id);
1589
1590 /**
1591 * Find an extra module, creating it if it doesn't already exist.
1592 *
1593 * @param[out] new_ret @c true if the module was newly created, @c false if it
1594 * was found.
1595 */
1596 struct drgn_error *drgn_module_find_or_create_extra(struct drgn_program *prog,
1597 const char *name,
1598 uint64_t id,
1599 struct drgn_module **ret,
1600 bool *new_ret);
1601
1602 /** Get the program that a module is from. */
1603 struct drgn_program *drgn_module_program(const struct drgn_module *module);
1604
1605 /** Get the kind of a module. */
1606 enum drgn_module_kind drgn_module_kind(const struct drgn_module *module);
1607
1608 /** Get the name of a module. */
1609 const char *drgn_module_name(const struct drgn_module *module);
1610
1611 /**
1612 * Get the kind-specific info of a module.
1613 *
1614 * - For the main module, it is always 0.
1615 * - For shared library and vDSO modules, it is the address of the dynamic
1616 * section.
1617 * - For relocatable modules, it is an address identifying the module (e.g., for
1618 * Linux kernel loadable modules, it is the base address).
1619 * - For extra modules, it is an arbitrary identification number.
1620 */
1621 uint64_t drgn_module_info(const struct drgn_module *module);
1622
1623 /**
1624 * Get the number of address ranges where a module is loaded.
1625 *
1626 * @param[out] ret Returned number of address ranges (zero if address ranges are
1627 * empty or not set).
1628 * @return @c true on success (including if address ranges are empty), @c false
1629 * if address ranges are not set.
1630 */
1631 bool drgn_module_num_address_ranges(const struct drgn_module *module,
1632 size_t *ret);
1633
1634 /**
1635 * Get the @p i-th address range where a module is loaded.
1636 *
1637 * @param[out] start_ret Minimum address (inclusive).
1638 * @param[out] end_ret Maximum address (exclusive).
1639 * @return @c true on success, @c false if @p i is out of bounds (i.e., if it is
1640 * greater than @ref drgn_module_num_address_ranges()).
1641 */
1642 bool drgn_module_address_range(const struct drgn_module *module, size_t i,
1643 uint64_t *start_ret, uint64_t *end_ret);
1644
1645 /**
1646 * Set the address range of a module.
1647 *
1648 * This is equivalent to:
1649 *
1650 * ```
1651 * uint64_t range[2] = {start, end};
1652 * drgn_module_set_address_ranges(module, &range, 1);
1653 * ```
1654 */
1655 struct drgn_error *drgn_module_set_address_range(struct drgn_module *module,
1656 uint64_t start, uint64_t end);
1657
1658 /**
1659 * Set the address ranges of a module.
1660 *
1661 * @param[in] ranges Ranges to set. The first element of each range is the
1662 * start. The second is the end. The start must be less than the end. This is
1663 * copied, so it need not remain valid after this function returns.
1664 * @param[in] num_ranges Number of ranges in @p ranges.
1665 */
1666 struct drgn_error *drgn_module_set_address_ranges(struct drgn_module *module,
1667 uint64_t ranges[][2],
1668 size_t num_ranges);
1669
1670 /** Unset the address ranges for a module. */
1671 void drgn_module_unset_address_ranges(struct drgn_module *module);
1672
1673 /** Return whether a module's address ranges contain @p address. */
1674 bool drgn_module_contains_address(const struct drgn_module *module,
1675 uint64_t address);
1676
1677 /**
1678 * Get the unique byte string (e.g., GNU build ID) identifying files used by
1679 * a module.
1680 *
1681 * @param[out] raw_ret Returned raw build ID. @c NULL if not known. Valid until
1682 * the build ID is changed.
1683 * @param[out] raw_len_ret Size of returned build ID, in bytes. 0 if not known.
1684 * @return Lowercase hexadecimal representation of build ID. @c NULL if not
1685 * known. Valid until the build ID is changed.
1686 */
1687 const char *drgn_module_build_id(const struct drgn_module *module,
1688 const void **raw_ret, size_t *raw_len_ret);
1689
1690 /**
1691 * Set the unique byte string (e.g., GNU build ID) identifying files used by a
1692 * module.
1693 *
1694 * @param[in] build_id New build ID.
1695 * @param[in] build_id_len New size of build ID, in bytes. May be 0 to unset the
1696 * build ID.
1697 */
1698 struct drgn_error *drgn_module_set_build_id(struct drgn_module *module,
1699 const void *build_id,
1700 size_t build_id_len);
1701
1702 /** Get the address of a section with the given name in a relocatable module. */
1703 struct drgn_error *drgn_module_get_section_address(struct drgn_module *module,
1704 const char *name,
1705 uint64_t *ret);
1706
1707 /**
1708 * Set the address of a section with the given name in a relocatable module.
1709 *
1710 * This is not allowed after a file has been assigned to the module.
1711 */
1712 struct drgn_error *drgn_module_set_section_address(struct drgn_module *module,
1713 const char *name,
1714 uint64_t address);
1715
1716 /**
1717 * Unset the address of a section with the given name in a relocatable module.
1718 *
1719 * This is not allowed after a file has been assigned to the module.
1720 */
1721 struct drgn_error *drgn_module_delete_section_address(struct drgn_module *module,
1722 const char *name);
1723
1724 /**
1725 * Get the number of section addresses currently set in a relocatable module.
1726 */
1727 struct drgn_error *drgn_module_num_section_addresses(struct drgn_module *module,
1728 size_t *ret);
1729
1730 /** Iterator over set section addresses in a relocatable module. */
1731 struct drgn_module_section_address_iterator;
1732
1733 /** Create a @ref drgn_module_section_address_iterator. */
1734 struct drgn_error *
1735 drgn_module_section_address_iterator_create(struct drgn_module *module,
1736 struct drgn_module_section_address_iterator **ret);
1737
1738 /** Destroy a @ref drgn_module_section_address_iterator. */
1739 void
1740 drgn_module_section_address_iterator_destroy(struct drgn_module_section_address_iterator *it);
1741
1742 /** Get the module that a @ref drgn_module_section_address_iterator is for. */
1743 struct drgn_module *
1744 drgn_module_section_address_iterator_module(struct drgn_module_section_address_iterator *it);
1745
1746 /**
1747 * Get the next section name and address from a @ref
1748 * drgn_module_section_address_iterator.
1749 *
1750 * @param[out] name_ret Returned name. Valid until the the next call to @ref
1751 * drgn_module_section_address_iterator_next() or @ref
1752 * drgn_module_section_address_iterator_destroy() on @it.
1753 * @param[out] address_ret Returned address.
1754 */
1755 struct drgn_error *
1756 drgn_module_section_address_iterator_next(struct drgn_module_section_address_iterator *it,
1757 const char **name_ret,
1758 uint64_t *address_ret);
1759
1760 /** Status of a file in a @ref drgn_module. */
1761 enum drgn_module_file_status {
1762 /** File has not been found and should be searched for. */
1763 DRGN_MODULE_FILE_WANT,
1764 /** File has already been found and assigned. */
1765 DRGN_MODULE_FILE_HAVE,
1766 /** File has not been found, but it should not be searched for. */
1767 DRGN_MODULE_FILE_DONT_WANT,
1768 /** File has not been found and is not needed. */
1769 DRGN_MODULE_FILE_DONT_NEED,
1770 /**
1771 * File has been found, but it requires a supplementary file before it
1772 * can be used.
1773 */
1774 DRGN_MODULE_FILE_WANT_SUPPLEMENTARY,
1775 };
1776
1777 /** Kind of supplementary file. */
1778 enum drgn_supplementary_file_kind {
1779 /** Not known or not needed. */
1780 DRGN_SUPPLEMENTARY_FILE_NONE,
1781 /**
1782 * GNU-style supplementary debug file referred to by a
1783 * ``.gnu_debugaltlink`` section.
1784 */
1785 DRGN_SUPPLEMENTARY_FILE_GNU_DEBUGALTLINK,
1786 };
1787
1788 /** Get the status of a module's loaded file. */
1789 enum drgn_module_file_status
1790 drgn_module_loaded_file_status(const struct drgn_module *module);
1791
1792 /** Set the status of a module's loaded file. */
1793 bool drgn_module_set_loaded_file_status(struct drgn_module *module,
1794 enum drgn_module_file_status status);
1795
1796 /**
1797 * Get whether a module wants a loaded file.
1798 *
1799 * For future-proofness, debug info finders should prefer this over comparing
1800 * @ref drgn_module_loaded_file_status() directly.
1801 */
1802 bool drgn_module_wants_loaded_file(const struct drgn_module *module);
1803
1804 /** Get the absolute path of a module's loaded file, or @c NULL if not known. */
1805 const char *drgn_module_loaded_file_path(const struct drgn_module *module);
1806
1807 /**
1808 * Get the difference between the load address in the program and addresses in a
1809 * module's loaded file.
1810 */
1811 uint64_t drgn_module_loaded_file_bias(const struct drgn_module *module);
1812
1813 enum drgn_module_file_status
1814 drgn_module_debug_file_status(const struct drgn_module *module);
1815
1816 bool drgn_module_set_debug_file_status(struct drgn_module *module,
1817 enum drgn_module_file_status status);
1818
1819 /**
1820 * Get whether a module wants a debug file.
1821 *
1822 * For future-proofness, debug info finders should prefer this over comparing
1823 * @ref drgn_module_debug_file_status() directly.
1824 */
1825 bool drgn_module_wants_debug_file(const struct drgn_module *module);
1826
1827 /** Get the absolute path of a module's debug file, or @c NULL if not known. */
1828 const char *drgn_module_debug_file_path(const struct drgn_module *module);
1829
1830 /**
1831 * Get the difference between the load address in the program and addresses in a
1832 * module's debug file.
1833 */
1834 uint64_t drgn_module_debug_file_bias(const struct drgn_module *module);
1835
1836 /** Get the kind of a module's supplementary debug file. */
1837 enum drgn_supplementary_file_kind
1838 drgn_module_supplementary_debug_file_kind(const struct drgn_module *module);
1839
1840 /**
1841 * Get the absolute path of a module's supplementary debug file, or @c NULL if
1842 * not known or not needed.
1843 */
1844 const char *
1845 drgn_module_supplementary_debug_file_path(const struct drgn_module *module);
1846
1847 /**
1848 * Get information about the supplementary debug file that a module currently
1849 * wants.
1850 *
1851 * @param[out] debug_file_path_ret Path of main file that wants the
1852 * supplementary file.
1853 * @param[out] supplementary_path_ret Path to supplementary file. This may be
1854 * absolute or relative to @p debug_file_path_ret.
1855 * @param[out] checksum_ret Unique identifier of the supplementary file.
1856 * @param[out] checksum_len_ret Size of unique identifier, in bytes.
1857 * @return Kind of supplementary file.
1858 */
1859 enum drgn_supplementary_file_kind
1860 drgn_module_wanted_supplementary_debug_file(struct drgn_module *module,
1861 const char **debug_file_path_ret,
1862 const char **supplementary_path_ret,
1863 const void **checksum_ret,
1864 size_t *checksum_len_ret);
1865
1866 /**
1867 * Return the object associated with this module.
1868 *
1869 * For some modules, there may be an object related to it. For example, drgn
1870 * automatically identifies the Linux kernel `struct module *` associated with
1871 * loadable modules, and associates it with them. Users may set or replace an
1872 * associated object with @ref drgn_set_module_object().
1873 *
1874 * @param[out] ret Initialized object where the module object is placed
1875 */
1876 struct drgn_error *
1877 drgn_module_object(const struct drgn_module *module, struct drgn_object *ret);
1878
1879 /**
1880 * Set the object associated with this module.
1881 * @param[in] obj A new (or replacement) object for the module
1882 */
1883 struct drgn_error *
1884 drgn_module_set_object(struct drgn_module *module, const struct drgn_object *obj);
1885
1886 /** Debugging information finder callback table. */
1887 struct drgn_debug_info_finder_ops {
1888 /**
1889 * Callback to destroy the debug info finder.
1890 *
1891 * This may be @c NULL.
1892 *
1893 * @param[in] arg Argument passed to @ref
1894 * drgn_program_register_debug_info_finder().
1895 */
1896 void (*destroy)(void *arg);
1897 /**
1898 * Callback for finding debug info.
1899 *
1900 * @param[in] modules Array of modules that want debugging information.
1901 * @param[in] num_modules Number of modules in @p modules.
1902 * @param[in] arg Argument passed to @ref
1903 * drgn_program_register_debug_info_finder().
1904 * @return @c NULL on success, non-@c NULL on error. It is not an error
1905 * for some debugging information to not be found.
1906 */
1907 struct drgn_error *(*find)(struct drgn_module * const *modules,
1908 size_t num_modules, void *arg);
1909 };
1910
1911 /**
1912 * Register a debugging information finding callback.
1913 *
1914 * @param[in] name Finder name. This is copied.
1915 * @param[in] ops Callback table. This is copied.
1916 * @param[in] arg Argument to pass to callbacks.
1917 * @param[in] enable_index Insert the finder into the list of enabled finders at
1918 * the given index. If @ref DRGN_HANDLER_REGISTER_ENABLE_LAST or greater than
1919 * the number of enabled finders, insert it at the end. If @ref
1920 * DRGN_HANDLER_REGISTER_DONT_ENABLE, don’t enable the finder.
1921 */
1922 struct drgn_error *
1923 drgn_program_register_debug_info_finder(struct drgn_program *prog,
1924 const char *name,
1925 const struct drgn_debug_info_finder_ops *ops,
1926 void *arg, size_t enable_index);
1927
1928 /**
1929 * Get the names of all registered debugging information finders.
1930 *
1931 * The order of the names is arbitrary.
1932 *
1933 * @param[out] names_ret Returned array of names.
1934 * @param[out] count_ret Returned number of names in @p names_ret.
1935 */
1936 struct drgn_error *
1937 drgn_program_registered_debug_info_finders(struct drgn_program *prog,
1938 const char ***names_ret,
1939 size_t *count_ret);
1940
1941 /**
1942 * Set the list of enabled debugging information finders.
1943 *
1944 * Finders are called in the same order as the list until all wanted files have
1945 * been found.
1946 *
1947 * @param[in] names Names of finders to enable, in order.
1948 * @param[in] count Number of names in @p names.
1949 */
1950 struct drgn_error *
1951 drgn_program_set_enabled_debug_info_finders(struct drgn_program *prog,
1952 const char * const *names,
1953 size_t count);
1954
1955 /**
1956 * Get the names of enabled debugging information finders, in order.
1957 *
1958 * @param[out] names_ret Returned array of names.
1959 * @param[out] count_ret Returned number of names in @p names_ret.
1960 */
1961 struct drgn_error *
1962 drgn_program_enabled_debug_info_finders(struct drgn_program *prog,
1963 const char ***names_ret,
1964 size_t *count_ret);
1965
1966 /** Options for debugging information searches. */
1967 struct drgn_debug_info_options;
1968
1969 /** Create a @ref drgn_debug_info_options with the default settings. */
1970 struct drgn_error *
1971 drgn_debug_info_options_create(struct drgn_debug_info_options **ret);
1972
1973 /** Destroy a @ref drgn_debug_info_options. */
1974 void
1975 drgn_debug_info_options_destroy(struct drgn_debug_info_options *options);
1976
1977 /** Set all options in @p dst to the same as @p src. */
1978 struct drgn_error *
1979 drgn_debug_info_options_copy(struct drgn_debug_info_options *dst,
1980 const struct drgn_debug_info_options *src);
1981
1982 /**
1983 * Get the list of directories to search for debugging information files.
1984 *
1985 * @return Null-terminated list of directories. Valid until @ref
1986 * drgn_debug_info_options_set_directories() or @ref
1987 * drgn_debug_info_options_destroy() is called on @p options.
1988 */
1989 const char * const *
1990 drgn_debug_info_options_get_directories(const struct drgn_debug_info_options *options);
1991
1992 /**
1993 * Set the list of directories to search for debugging information files.
1994 *
1995 * @param[in] value Null-terminated list of directories. It is copied, so it
1996 * need not remain valid after this function returns.
1997 */
1998 struct drgn_error *
1999 drgn_debug_info_options_set_directories(struct drgn_debug_info_options *options,
2000 const char * const *value)
2001 __attribute__((__nonnull__(1, 2)));
2002
2003 /** Get whether to try module names that look like filesystem paths. */
2004 bool
2005 drgn_debug_info_options_get_try_module_name(const struct drgn_debug_info_options *options);
2006
2007 /** Set whether to try module names that look like filesystem paths. */
2008 void
2009 drgn_debug_info_options_set_try_module_name(struct drgn_debug_info_options *options,
2010 bool value);
2011
2012 /** Get whether to try files by build ID. */
2013 bool
2014 drgn_debug_info_options_get_try_build_id(const struct drgn_debug_info_options *options);
2015
2016 /** Set whether to try files by build ID. */
2017 void
2018 drgn_debug_info_options_set_try_build_id(struct drgn_debug_info_options *options,
2019 bool value);
2020
2021 /**
2022 * Get the list of directories to search for by debug link.
2023 *
2024 * @return Null-terminated list of directories. Valid until @ref
2025 * drgn_debug_info_options_set_debug_link_directories() or @ref
2026 * drgn_debug_info_options_destroy() is called on @p options.
2027 */
2028 const char * const *
2029 drgn_debug_info_options_get_debug_link_directories(const struct drgn_debug_info_options *options);
2030
2031 /**
2032 * Set the list of directories to search for by debug link.
2033 *
2034 * @param[in] value Null-terminated list of directories. It is copied, so it
2035 * need not remain valid after this function returns.
2036 */
2037 struct drgn_error *
2038 drgn_debug_info_options_set_debug_link_directories(struct drgn_debug_info_options *options,
2039 const char * const *value)
2040 __attribute__((__nonnull__(1, 2)));
2041
2042 /** Get whether to try files by debug link. */
2043 bool
2044 drgn_debug_info_options_get_try_debug_link(const struct drgn_debug_info_options *options);
2045
2046 /** Set whether to try files by debug link. */
2047 void
2048 drgn_debug_info_options_set_try_debug_link(struct drgn_debug_info_options *options,
2049 bool value);
2050
2051 /** Get whether to try files via procfs for local processes. */
2052 bool
2053 drgn_debug_info_options_get_try_procfs(const struct drgn_debug_info_options *options);
2054
2055 /** Set whether to try files via procfs for local processes. */
2056 void
2057 drgn_debug_info_options_set_try_procfs(struct drgn_debug_info_options *options,
2058 bool value);
2059
2060 /** Get whether to try the vDSO embedded in a process's memory/core dump. */
2061 bool
2062 drgn_debug_info_options_get_try_embedded_vdso(const struct drgn_debug_info_options *options);
2063
2064 /** Set whether to try the vDSO embedded in a process's memory/core dump. */
2065 void
2066 drgn_debug_info_options_set_try_embedded_vdso(struct drgn_debug_info_options *options,
2067 bool value);
2068
2069 /**
2070 * Get whether to reuse a module's loaded file as its debug file or vice versa.
2071 */
2072 bool
2073 drgn_debug_info_options_get_try_reuse(const struct drgn_debug_info_options *options);
2074
2075 /**
2076 * Set whether to reuse a module's loaded file as its debug file or vice versa.
2077 */
2078 void
2079 drgn_debug_info_options_set_try_reuse(struct drgn_debug_info_options *options,
2080 bool value);
2081
2082 /** Get whether to try finding supplementary files. */
2083 bool
2084 drgn_debug_info_options_get_try_supplementary(const struct drgn_debug_info_options *options);
2085
2086 /** Set whether to try finding supplementary files. */
2087 void
2088 drgn_debug_info_options_set_try_supplementary(struct drgn_debug_info_options *options,
2089 bool value);
2090
2091 /**
2092 * Get the list of directories to search for kernel debugging information files.
2093 *
2094 * @return Null-terminated list of directories. Valid until @ref
2095 * drgn_debug_info_options_set_kernel_directories() or @ref
2096 * drgn_debug_info_options_destroy() is called on @p options.
2097 */
2098 const char * const *
2099 drgn_debug_info_options_get_kernel_directories(const struct drgn_debug_info_options *options);
2100
2101 /**
2102 * Set the list of directories to search for kernel debugging information files.
2103 *
2104 * @param[in] value Null-terminated list of directories. It is copied, so it
2105 * need not remain valid after this function returns.
2106 */
2107 struct drgn_error *
2108 drgn_debug_info_options_set_kernel_directories(struct drgn_debug_info_options *options,
2109 const char * const *value)
2110 __attribute__((__nonnull__(1, 2)));
2111
2112 /** Methods of searching for loadable kernel module debugging information. */
2113 enum drgn_kmod_search_method {
2114 DRGN_KMOD_SEARCH_NONE,
2115 DRGN_KMOD_SEARCH_DEPMOD,
2116 DRGN_KMOD_SEARCH_WALK,
2117 DRGN_KMOD_SEARCH_DEPMOD_OR_WALK,
2118 DRGN_KMOD_SEARCH_DEPMOD_AND_WALK,
2119 } __attribute__((__packed__));
2120
2121 /** Get how to search for loadable kernel module debugging information. */
2122 enum drgn_kmod_search_method
2123 drgn_debug_info_options_get_try_kmod(const struct drgn_debug_info_options *options);
2124
2125 /** Set how to search for loadable kernel module debugging information. */
2126 void
2127 drgn_debug_info_options_set_try_kmod(struct drgn_debug_info_options *options,
2128 enum drgn_kmod_search_method value);
2129
2130 /**
2131 * Get the default debugging information options for @p prog.
2132 *
2133 * @return Program options. May be modified as needed. Must not be passed to
2134 * @ref drgn_debug_info_options_destroy().
2135 */
2136 struct drgn_debug_info_options *
2137 drgn_program_debug_info_options(struct drgn_program *prog);
2138
2139 /**
2140 * Load debugging information for the given modules from the standard locations.
2141 *
2142 * @param[in] options Options to use, or @p NULL to use the program's default
2143 * options.
2144 */
2145 struct drgn_error *
2146 drgn_find_standard_debug_info(struct drgn_module * const *modules,
2147 size_t num_modules,
2148 struct drgn_debug_info_options *options);
2149
2150 /**
2151 * Try to use the given file for a module.
2152 *
2153 * @param[in] path Path to file.
2154 * @param[in] fd If nonnegative, an open file descriptor referring to the file.
2155 * This always takes ownership of the file descriptor even if the file is not
2156 * used or on error.
2157 * @param[in] force If @c true, don't check whether the file matches the module.
2158 */
2159 struct drgn_error *
2160 drgn_module_try_file(struct drgn_module *module, const char *path, int fd,
2161 bool force);
2162
2163 /** Iterator over a set of modules. */
2164 struct drgn_module_iterator;
2165
2166 /** Destroy a @ref drgn_module_iterator. */
2167 void
2168 drgn_module_iterator_destroy(struct drgn_module_iterator *it);
2169
2170 /** Get the program that a module iterator is from. */
2171 struct drgn_program *
2172 drgn_module_iterator_program(const struct drgn_module_iterator *it);
2173
2174 /**
2175 * Get the next module in a module iterator.
2176 *
2177 * @param[out] ret Returned module, or @c NULL if there are no more modules.
2178 * @param[out] new_ret Whether the module was newly created. May be @c NULL.
2179 */
2180 struct drgn_error *drgn_module_iterator_next(struct drgn_module_iterator *it,
2181 struct drgn_module **ret,
2182 bool *new_ret);
2183
2184 /** Create an iterator over created modules. */
2185 struct drgn_error *
2186 drgn_created_module_iterator_create(struct drgn_program *prog,
2187 struct drgn_module_iterator **ret);
2188
2189 /**
2190 * Create an iterator that determines what executables, libraries, etc. are
2191 * loaded in the program and creates modules to represent them.
2192 */
2193 struct drgn_error *
2194 drgn_loaded_module_iterator_create(struct drgn_program *prog,
2195 struct drgn_module_iterator **ret);
2196
2197 /**
2198 * Determine what executables, libraries, etc. are loaded in the program and
2199 * create modules to represent them.
2200 *
2201 * This is a shortcut for creating an iterator with @ref
2202 * drgn_loaded_module_iterator_create() and calling @ref
2203 * drgn_module_iterator_next() until it is exhausted.
2204 */
2205 struct drgn_error *
2206 drgn_create_loaded_modules(struct drgn_program *prog);
2207
2208 /**
2209 * Load debugging information for the given set of files and/or modules.
2210 *
2211 * @param[in] load_default Whether to load all debugging information for all
2212 * loaded modules. This implies @p load_main.
2213 * @param[in] load_main Whether to load all debugging information for the main
2214 * module.
2215 */
2216 struct drgn_error *drgn_program_load_debug_info(struct drgn_program *prog,
2217 const char **paths, size_t n,
2218 bool load_default,
2219 bool load_main);
2220
2221 /**
2222 * Load debugging information for the given modules using the enabled debugging
2223 * information finders.
2224 */
2225 struct drgn_error *drgn_load_module_debug_info(struct drgn_module **modules,
2226 size_t *num_modules);
2227
2228 /** @} */
2229
2230 /**
2231 * @defgroup Logging Logging
2232 *
2233 * Logging configuration.
2234 *
2235 * drgn can log to a file (@ref drgn_program_set_log_file()) or an arbitrary
2236 * callback (@ref drgn_program_set_log_callback()). Messages can be filtered
2237 * based on the log level (@ref drgn_program_set_log_level()).
2238 *
2239 * By default, the log file is set to `stderr` and the log level is @ref
2240 * DRGN_LOG_NONE, so logging is disabled.
2241 *
2242 * Additionally, drgn can display a progress bar for some operations, like
2243 * downloading debugging information. By default, progress bars are displayed on
2244 * standard error if standard error is a terminal, the log file is set to
2245 * `stderr`, and the log level is less than or equal to @ref DRGN_LOG_WARNING,
2246 * but this can be changed (@ref drgn_program_set_progress_file()).
2247 *
2248 * @{
2249 */
2250
2251 /** Log levels. */
2252 enum drgn_log_level {
2253 DRGN_LOG_DEBUG = 0,
2254 DRGN_LOG_INFO = 1,
2255 DRGN_LOG_WARNING = 2,
2256 DRGN_LOG_ERROR = 3,
2257 DRGN_LOG_CRITICAL = 4,
2258 };
2259 /** Don't log anything. */
2260 #define DRGN_LOG_NONE (DRGN_LOG_CRITICAL + 1)
2261
2262 /**
2263 * Set the minimum log level.
2264 *
2265 * Messages below this level will not be logged.
2266 *
2267 * @param[in] level Minimum @ref drgn_log_level to log, or @ref DRGN_LOG_NONE to
2268 * disable logging.
2269 */
2270 void drgn_program_set_log_level(struct drgn_program *prog, int level);
2271
2272 /**
2273 * Get the minimum log level.
2274 *
2275 * @return Minimum @ref drgn_log_level being logged, or @ref DRGN_LOG_NONE if
2276 * logging is disabled.
2277 */
2278 int drgn_program_get_log_level(struct drgn_program *prog);
2279
2280 /** Write logs to the given file. */
2281 void drgn_program_set_log_file(struct drgn_program *prog, FILE *file);
2282
2283 /**
2284 * Log callback.
2285 *
2286 * @param[in] prog Program message was logged to.
2287 * @param[in] arg `callback_arg` passed to @ref drgn_program_set_log_callback().
2288 * @param[in] level Message level.
2289 * @param[in] format printf-style format of message.
2290 * @param[in] ap Arguments for @p format.
2291 * @param[in] err Error to append after formatted message if non-@c NULL. This
2292 * can be formatted with @ref drgn_error_string(), @ref drgn_error_fwrite(), or
2293 * @ref drgn_error_dwrite().
2294 */
2295 typedef void drgn_log_fn(struct drgn_program *prog, void *arg,
2296 enum drgn_log_level level, const char *format,
2297 va_list ap, struct drgn_error *err);
2298
2299 /**
2300 * Set a callback to log to.
2301 *
2302 * @param[in] callback Callback to call for each log message. This is only
2303 * called if the message's level is at least the current log level.
2304 * @param[in] callback_arg Argument to pass to callback.
2305 */
2306 void drgn_program_set_log_callback(struct drgn_program *prog,
2307 drgn_log_fn *callback, void *callback_arg);
2308
2309 /**
2310 * Get the current log callback.
2311 *
2312 * @param[out] callback_ret Returned callback.
2313 * @param[out] callback_arg_ret Returned callback argument.
2314 */
2315 void drgn_program_get_log_callback(struct drgn_program *prog,
2316 drgn_log_fn **callback_ret,
2317 void **callback_arg_ret);
2318
2319 /**
2320 * Write progress bars to the given file.
2321 *
2322 * @param[in] file File, or @c NULL to disable progress bars.
2323 */
2324 void drgn_program_set_progress_file(struct drgn_program *prog, FILE *file);
2325
2326 /** @} */
2327
2328 /**
2329 * @defgroup Objects Objects
2330 *
2331 * Objects in a program.
2332 *
2333 * A @ref drgn_object represents an object (e.g., variable, constant, or
2334 * function) in a program.
2335 *
2336 * Various operators and helpers are defined on objects; see @ref
2337 * ObjectOperators and @ref ObjectHelpers.
2338 *
2339 * Many operations are language-specific. C is currently the only supported
2340 * language.
2341 *
2342 * In drgn's emulation of C:
2343 *
2344 * - Signed and unsigned integer arithmetic is reduced modulo 2^width.
2345 * - Integer division truncates towards zero.
2346 * - Modulo has the sign of the dividend.
2347 * - Division or modulo by 0 returns an error.
2348 * - Shifts are reduced modulo 2^width. In particular, a shift by a value
2349 * greater than the width returns 0.
2350 * - Shifts by a negative number return an error.
2351 * - Bitwise operators on signed integers act on the two's complement
2352 * representation.
2353 * - Pointer arithmetic is supported.
2354 * - Integer literal have the first type of @c int, @c long, <tt>long long</tt>,
2355 * and <tt>unsigned long long</tt> which can represent the value.
2356 * - Boolean literals have type @c int (@b not @c _Bool).
2357 * - Floating-point literals have type @c double.
2358 * @{
2359 */
2360
2361 /** Kinds of objects. */
2362 enum drgn_object_kind {
2363 /** Constant or temporary computed value. */
2364 DRGN_OBJECT_VALUE,
2365 /** In program memory. */
2366 DRGN_OBJECT_REFERENCE,
2367 /** Absent (e.g. optimized out). */
2368 DRGN_OBJECT_ABSENT,
2369 } __attribute__((__packed__));
2370
2371 /**
2372 * Object encodings.
2373 *
2374 * The value of a @ref drgn_object may be encoded in various ways depending on
2375 * its type. This determines which field of a @ref drgn_value is used.
2376 *
2377 * The incomplete encodings are only possible for reference objects; values have
2378 * a complete type.
2379 */
2380 enum drgn_object_encoding {
2381 /**
2382 * Memory buffer.
2383 *
2384 * This is used for objects with a structure, union, class, or array
2385 * type.
2386 */
2387 DRGN_OBJECT_ENCODING_BUFFER,
2388 /**
2389 * Signed integer.
2390 *
2391 * This is used for objects with a signed integer or signed enumerated
2392 * type no larger than 64 bits.
2393 */
2394 DRGN_OBJECT_ENCODING_SIGNED,
2395 /**
2396 * Unsigned integer.
2397 *
2398 * This is used for objects with a unsigned integer, boolean, or pointer
2399 * type no larger than 64 bits.
2400 */
2401 DRGN_OBJECT_ENCODING_UNSIGNED,
2402 /**
2403 * Big signed integer.
2404 *
2405 * This is used for objects with a signed integer or signed enumerated
2406 * type larger than 64 bits.
2407 */
2408 DRGN_OBJECT_ENCODING_SIGNED_BIG,
2409 /**
2410 * Big unsigned integer.
2411 *
2412 * This is used for objects with a unsigned integer, boolean, or pointer
2413 * type larger than 64 bits.
2414 */
2415 DRGN_OBJECT_ENCODING_UNSIGNED_BIG,
2416 /**
2417 * Floating-point value.
2418 *
2419 * This used for objects with a floating-point type.
2420 */
2421 DRGN_OBJECT_ENCODING_FLOAT,
2422 /**
2423 * No value.
2424 *
2425 * This is used for reference objects with a void or function type.
2426 */
2427 DRGN_OBJECT_ENCODING_NONE = -1,
2428 /**
2429 * Incomplete buffer value.
2430 *
2431 * This is used for reference objects with an incomplete structure,
2432 * union, class, or array type.
2433 */
2434 DRGN_OBJECT_ENCODING_INCOMPLETE_BUFFER = -2,
2435 /**
2436 * Incomplete integer value.
2437 *
2438 * This is used for reference objects with an incomplete enumerated
2439 * types.
2440 */
2441 DRGN_OBJECT_ENCODING_INCOMPLETE_INTEGER = -3,
2442 } __attribute__((__packed__));
2443
2444 /**
2445 * Return whether a type corresponding to an object encoding is complete.
2446 *
2447 * @sa drgn_type_is_complete()
2448 */
2449 static inline bool
2450 drgn_object_encoding_is_complete(enum drgn_object_encoding encoding)
2451 {
2452 return encoding >= 0;
2453 }
2454
2455 /** Value of a @ref drgn_object. */
2456 union drgn_value {
2457 /**
2458 * Pointer to an external buffer for a @ref DRGN_OBJECT_ENCODING_BUFFER,
2459 * @ref DRGN_OBJECT_ENCODING_SIGNED_BIG, or @ref
2460 * DRGN_OBJECT_ENCODING_UNSIGNED_BIG value.
2461 *
2462 * For @ref DRGN_OBJECT_ENCODING_BUFFER, this contains the object's
2463 * representation in the memory of the program.
2464 *
2465 * For @ref DRGN_OBJECT_ENCODING_SIGNED_BIG and @ref
2466 * DRGN_OBJECT_ENCODING_UNSIGNED_BIG, the representation of the value is
2467 * an implementation detail which may change.
2468 */
2469 char *bufp;
2470 /**
2471 * Inline buffer for a @ref DRGN_OBJECT_ENCODING_BUFFER value.
2472 *
2473 * Tiny buffers (see @ref drgn_value_is_inline()) are stored inline here
2474 * instead of in a separate allocation.
2475 */
2476 char ibuf[8];
2477 /** @ref DRGN_OBJECT_ENCODING_SIGNED value. */
2478 int64_t svalue;
2479 /** @ref DRGN_OBJECT_ENCODING_UNSIGNED value. */
2480 uint64_t uvalue;
2481 /** @ref DRGN_OBJECT_ENCODING_FLOAT value. */
2482 double fvalue;
2483 };
2484
2485 /**
2486 * Return the number of bytes needed to store the given number of bits.
2487 *
2488 * @param[in] bits Number of bits.
2489 */
2490 static inline uint64_t drgn_value_size(uint64_t bits)
2491 {
2492 return bits / CHAR_BIT + (bits % CHAR_BIT ? 1 : 0);
2493 }
2494
2495 /**
2496 * Return whether the given number of bits can be stored in the inline buffer of
2497 * a @ref drgn_value (@ref drgn_value::ibuf).
2498 *
2499 * @param[in] bits Number of bits.
2500 */
2501 static inline bool drgn_value_is_inline(uint64_t bits)
2502 {
2503 return bits <= CHAR_BIT * sizeof(((union drgn_value *)0)->ibuf);
2504 }
2505
2506 /** Reason object is absent. */
2507 enum drgn_absence_reason {
2508 /** Another reason not listed below. */
2509 DRGN_ABSENCE_REASON_OTHER,
2510 /** Object was optimized out by the compiler. */
2511 DRGN_ABSENCE_REASON_OPTIMIZED_OUT,
2512 /** Encountered unknown debugging information. */
2513 DRGN_ABSENCE_REASON_NOT_IMPLEMENTED,
2514 };
2515
2516 /**
2517 * Object in a program.
2518 *
2519 * A @ref drgn_object represents a symbol or value in a program. It can be in
2520 * the memory of the program (a "reference"), a temporary computed value (a
2521 * "value"), or "absent".
2522 *
2523 * A @ref drgn_object must be initialized with @ref drgn_object_init() before it
2524 * is used. It can then be set and otherwise changed repeatedly. When the object
2525 * is no longer needed, it must be deinitialized @ref drgn_object_deinit().
2526 *
2527 * It is more effecient to initialize an object once and reuse it rather than
2528 * creating a new one repeatedly (e.g., in a loop).
2529 *
2530 * Members of a @ref drgn_object should not be modified except through the
2531 * provided functions.
2532 */
2533 struct drgn_object {
2534 /** Type of this object. */
2535 struct drgn_type *type;
2536 /**
2537 * Size of this object in bits.
2538 *
2539 * This is usually the size of @ref drgn_object::type, but it may be
2540 * smaller if this is a bit field (@ref drgn_object::is_bit_field).
2541 */
2542 uint64_t bit_size;
2543 /** Qualifiers on @ref drgn_object::type. */
2544 enum drgn_qualifiers qualifiers;
2545 /** How this object is encoded. */
2546 enum drgn_object_encoding encoding;
2547 /** Kind of this object. */
2548 enum drgn_object_kind kind;
2549 /** Whether this object is a bit field. */
2550 bool is_bit_field;
2551 /**
2552 * Whether this object is little-endian.
2553 *
2554 * Valid only for scalars (i.e., @ref DRGN_OBJECT_ENCODING_SIGNED, @ref
2555 * DRGN_OBJECT_ENCODING_UNSIGNED, @ref DRGN_OBJECT_ENCODING_SIGNED_BIG,
2556 * @ref DRGN_OBJECT_ENCODING_UNSIGNED_BIG, @ref
2557 * DRGN_OBJECT_ENCODING_FLOAT, or @ref
2558 * DRGN_OBJECT_ENCODING_INCOMPLETE_INTEGER).
2559 */
2560 bool little_endian;
2561 /**
2562 * Offset in bits from @c address.
2563 *
2564 * Valid only for reference objects.
2565 */
2566 uint8_t bit_offset;
2567 union {
2568 /** Value of value object. */
2569 union drgn_value value;
2570 /** Address of reference object. */
2571 uint64_t address;
2572 /** Reason object is absent. */
2573 enum drgn_absence_reason absence_reason;
2574 };
2575 };
2576
2577 /** Return the number of bytes needed to store an object's value. */
2578 static inline uint64_t drgn_object_size(const struct drgn_object *obj)
2579 {
2580 return drgn_value_size(obj->bit_size);
2581 }
2582
2583 /**
2584 * Return whether an object's value can be stored in the inline buffer of a @ref
2585 * drgn_value (@ref drgn_value::ibuf).
2586 */
2587 static inline bool drgn_object_is_inline(const struct drgn_object *obj)
2588 {
2589 return drgn_value_is_inline(obj->bit_size);
2590 }
2591
2592 /** Return an object's buffer. */
2593 #define drgn_object_buffer(obj) ({ \
2594 __auto_type _obj = (obj); \
2595 drgn_object_is_inline(_obj) ? _obj->value.ibuf : _obj->value.bufp; \
2596 })
2597
2598 /** Get the type of a @ref drgn_object. */
2599 static inline struct drgn_qualified_type
2600 drgn_object_qualified_type(const struct drgn_object *obj)
2601 {
2602 return (struct drgn_qualified_type){
2603 .type = obj->type,
2604 .qualifiers = obj->qualifiers,
2605 };
2606 }
2607
2608 /**
2609 * Initialize a @ref drgn_object.
2610 *
2611 * The object is initialized to an absent object with a void type. This must be
2612 * paired with a call to @ref drgn_object_deinit().
2613 *
2614 * @param[in] obj Object to initialize.
2615 * @param[in] prog Program containing the object.
2616 */
2617 void drgn_object_init(struct drgn_object *obj, struct drgn_program *prog);
2618
2619 /**
2620 * Deinitialize a @ref drgn_object.
2621 *
2622 * The object cannot be used after this unless it is reinitialized with @ref
2623 * drgn_object_init().
2624 *
2625 * @param[in] obj Object to deinitialize.
2626 */
2627 void drgn_object_deinit(struct drgn_object *obj);
2628
2629 /**
2630 * Define and initialize a @ref drgn_object named @p obj that is automatically
2631 * deinitialized when it goes out of scope.
2632 *
2633 * This is equivalent to
2634 *
2635 * ```
2636 * struct drgn_object obj;
2637 * drgn_object_init(&obj, prog);
2638 * ...
2639 * drgn_object_deinit(&obj);
2640 * ```
2641 *
2642 * @param[in] obj Name of object.
2643 * @param[in] prog Program containing the object.
2644 */
2645 #define DRGN_OBJECT(obj, prog) \
2646 struct drgn_object obj \
2647 __attribute__((__cleanup__(drgn_object_deinit))) = \
2648 drgn_object_initializer(prog)
2649 struct drgn_object drgn_object_initializer(struct drgn_program *prog);
2650
2651 /** Get the program that a @ref drgn_object is from. */
2652 static inline struct drgn_program *
2653 drgn_object_program(const struct drgn_object *obj)
2654 {
2655 return drgn_type_program(obj->type);
2656 }
2657
2658 /** Get the language of a @ref drgn_object from its type. */
2659 static inline const struct drgn_language *
2660 drgn_object_language(const struct drgn_object *obj)
2661 {
2662 return drgn_type_language(obj->type);
2663 }
2664
2665 /**
2666 * @defgroup ObjectSetters Setters
2667 *
2668 * Object setters.
2669 *
2670 * Once a @ref drgn_object is initialized with @ref drgn_object_init(), it may
2671 * be set any number of times.
2672 *
2673 * @{
2674 */
2675
2676 /**
2677 * Set a @ref drgn_object to a signed value.
2678 *
2679 * @param[out] res Object to set.
2680 * @param[in] qualified_type Type to set to.
2681 * @param[in] svalue Value to set to.
2682 * @param[in] bit_field_size If the object should be a bit field, its size in
2683 * bits. Otherwise, 0.
2684 * @return @c NULL on success, non-@c NULL on error.
2685 */
2686 struct drgn_error *
2687 drgn_object_set_signed(struct drgn_object *res,
2688 struct drgn_qualified_type qualified_type,
2689 int64_t svalue, uint64_t bit_field_size);
2690
2691 /**
2692 * Set a @ref drgn_object to an unsigned value.
2693 *
2694 * @param[out] res Object to set.
2695 * @param[in] qualified_type Type to set to.
2696 * @param[in] uvalue Value to set to.
2697 * @param[in] bit_field_size If the object should be a bit field, its size in
2698 * bits. Otherwise, 0.
2699 * @return @c NULL on success, non-@c NULL on error.
2700 */
2701 struct drgn_error *
2702 drgn_object_set_unsigned(struct drgn_object *res,
2703 struct drgn_qualified_type qualified_type,
2704 uint64_t uvalue, uint64_t bit_field_size);
2705
2706 /**
2707 * Set a @ref drgn_object to a floating-point value.
2708 *
2709 * @param[out] res Object to set.
2710 * @param[in] qualified_type Type to set to.
2711 * @param[in] fvalue Value to set to.
2712 * @return @c NULL on success, non-@c NULL on error.
2713 */
2714 struct drgn_error *
2715 drgn_object_set_float(struct drgn_object *res,
2716 struct drgn_qualified_type qualified_type, double fvalue);
2717
2718 /**
2719 * Set a @ref drgn_object from a buffer.
2720 *
2721 * @param[out] res Object to set.
2722 * @param[in] qualified_type Type to set to.
2723 * @param[in] buf Buffer to set to. It is copied, so it need not remain valid
2724 * after this function returns.
2725 * @param[in] buf_size Size of @p buf, in bytes. `buf_size * 8` must be at least
2726 * `bit_size + bit_offset`, where @c bit_size is @p bit_field_size if non-zero
2727 * and the size of @p qualified_type in bits otherwise.
2728 * @param[in] bit_offset Offset of the value from the beginning of the buffer,
2729 * in bits. This is usually 0. It must be aligned to a byte unless the type is
2730 * scalar.
2731 * @param[in] bit_field_size If the object should be a bit field, its size in
2732 * bits. Otherwise, 0.
2733 * @return @c NULL on success, non-@c NULL on error.
2734 */
2735 struct drgn_error *
2736 drgn_object_set_from_buffer(struct drgn_object *res,
2737 struct drgn_qualified_type qualified_type,
2738 const void *buf, size_t buf_size,
2739 uint64_t bit_offset, uint64_t bit_field_size);
2740
2741 /**
2742 * Set a @ref drgn_object to a reference.
2743 *
2744 * @param[out] res Object to set.
2745 * @param[in] qualified_type Type to set to.
2746 * @param[in] address Address of the object.
2747 * @param[in] bit_offset Offset of the value from @p address, in bits. This is
2748 * usually 0.
2749 * @param[in] bit_field_size If the object should be a bit field, its size in
2750 * bits. Otherwise, 0.
2751 * @return @c NULL on success, non-@c NULL on error.
2752 */
2753 struct drgn_error *
2754 drgn_object_set_reference(struct drgn_object *res,
2755 struct drgn_qualified_type qualified_type,
2756 uint64_t address, uint64_t bit_offset,
2757 uint64_t bit_field_size);
2758
2759 /**
2760 * Set a @ref drgn_object as absent.
2761 *
2762 * @param[out] res Object to set.
2763 * @param[in] qualified_type Type to set to.
2764 * @param[in] reason Reason object is absent.
2765 * @param[in] bit_field_size If the object should be a bit field, its size in
2766 * bits. Otherwise, 0.
2767 * @return @c NULL on success, non-@c NULL on error.
2768 */
2769 struct drgn_error *
2770 drgn_object_set_absent(struct drgn_object *res,
2771 struct drgn_qualified_type qualified_type,
2772 enum drgn_absence_reason reason,
2773 uint64_t bit_field_size);
2774
2775 /**
2776 * Set a @ref drgn_object to a integer literal.
2777 *
2778 * This determines the type based on the programming language of the program
2779 * that the object belongs to.
2780 *
2781 * @param[out] res Object to set.
2782 * @param[in] uvalue Integer value.
2783 * @return @c NULL on success, non-@c NULL on error.
2784 */
2785 struct drgn_error *drgn_object_integer_literal(struct drgn_object *res,
2786 uint64_t uvalue);
2787
2788 /**
2789 * Set a @ref drgn_object to a boolean literal.
2790 *
2791 * This determines the type based on the programming language of the program
2792 * that the object belongs to.
2793 *
2794 * @param[out] res Object to set.
2795 * @param[in] bvalue Boolean value.
2796 * @return @c NULL on success, non-@c NULL on error.
2797 */
2798 struct drgn_error *drgn_object_bool_literal(struct drgn_object *res,
2799 bool bvalue);
2800
2801 /**
2802 * Set a @ref drgn_object to a floating-point literal.
2803 *
2804 * This determines the type based on the programming language of the program
2805 * that the object belongs to.
2806 *
2807 * @param[out] res Object to set.
2808 * @param[in] fvalue Floating-point value.
2809 * @return @c NULL on success, non-@c NULL on error.
2810 */
2811 struct drgn_error *drgn_object_float_literal(struct drgn_object *res,
2812 double fvalue);
2813
2814 /** @} */
2815
2816 /**
2817 * @defgroup ObjectHelpers Helpers
2818 *
2819 * Object helpers.
2820 *
2821 * Several helpers are provided for working with @ref drgn_object%s.
2822 *
2823 * Helpers which return a @ref drgn_object have the same calling convention: the
2824 * result object is the first argument, which must be initialized and may be the
2825 * same as the input object argument; the result is only modified if the helper
2826 * succeeds.
2827 *
2828 * @{
2829 */
2830
2831 /**
2832 * Set a @ref drgn_object to another object.
2833 *
2834 * This copies @c obj to @c res. If @c obj is a value, then @c res is set to a
2835 * value with the same type and value, and similarly if @c obj was a reference,
2836 * @c res is set to the same reference.
2837 *
2838 * @param[out] res Destination object.
2839 * @param[in] obj Source object.
2840 * @return @c NULL on success, non-@c NULL on error.
2841 */
2842 struct drgn_error *drgn_object_copy(struct drgn_object *res,
2843 const struct drgn_object *obj);
2844
2845 /**
2846 * Get a @ref drgn_object from a "fragment" of an object.
2847 *
2848 * This is a low-level interface used to implement @ref drgn_object_subscript(),
2849 * @ref drgn_object_member(), and @ref drgn_object_reinterpret(). Those
2850 * functions are usually more convenient.
2851 *
2852 * If multiple elements of an array are accessed (e.g., when iterating through
2853 * it), it can be more efficient to call @ref drgn_program_element_info() once
2854 * to get the required information and this function with the computed bit
2855 * offset for each element.
2856 *
2857 * If the same member of a type is accessed repeatedly (e.g., in a loop), it can
2858 * be more efficient to call @ref drgn_type_find_member() once to get the
2859 * required information and this function to access the member each time.
2860 *
2861 * @sa drgn_object_dereference_offset
2862 *
2863 * @param[out] res Destination object.
2864 * @param[in] obj Source object.
2865 * @param[in] qualified_type Result type.
2866 * @param[in] bit_offset Offset in bits from the beginning of @p obj.
2867 * @param[in] bit_field_size If the object should be a bit field, its size in
2868 * bits. Otherwise, 0.
2869 * @return @c NULL on success, non-@c NULL on error.
2870 */
2871 struct drgn_error *drgn_object_fragment(struct drgn_object *res,
2872 const struct drgn_object *obj,
2873 struct drgn_qualified_type qualified_type,
2874 int64_t bit_offset,
2875 uint64_t bit_field_size);
2876
2877 /**
2878 * Get a @ref drgn_object from dereferencing a pointer object with an offset.
2879 *
2880 * This is a low-level interface used to implement @ref drgn_object_subscript()
2881 * and @ref drgn_object_member_dereference(). Those functions are usually more
2882 * convenient, but this function can be more efficient if accessing multiple
2883 * elements or the same member multiple times.
2884 *
2885 * @sa drgn_object_fragment
2886 *
2887 * @param[out] res Dereferenced object.
2888 * @param[in] obj Pointer object.
2889 * @param[in] qualified_type Result type.
2890 * @param[in] bit_offset Offset in bits from the address given by the value of
2891 * @p obj.
2892 * @param[in] bit_field_size If the object should be a bit field, its size in
2893 * bits. Otherwise, 0.
2894 * @return @c NULL on success, non-@c NULL on error.
2895 */
2896 struct drgn_error *
2897 drgn_object_dereference_offset(struct drgn_object *res,
2898 const struct drgn_object *obj,
2899 struct drgn_qualified_type qualified_type,
2900 int64_t bit_offset, uint64_t bit_field_size);
2901
2902 /**
2903 * Read a @ref drgn_object.
2904 *
2905 * If @c obj is already a value, then this is equivalent to @ref
2906 * drgn_object_copy(). If @c is a reference, then this reads the reference and
2907 * sets @p res to the value.
2908 *
2909 * @param[out] res Object to set.
2910 * @param[in] obj Object to read.
2911 * @return @c NULL on success, non-@c NULL on error.
2912 */
2913 struct drgn_error *drgn_object_read(struct drgn_object *res,
2914 const struct drgn_object *obj);
2915
2916 /**
2917 * Read the value of a @ref drgn_object.
2918 *
2919 * If @p obj is a value, that value is returned directly. If @p is a reference,
2920 * the value is read into the provided temporary buffer.
2921 *
2922 * This must be paired with @ref drgn_object_deinit_value().
2923 *
2924 * @param[in] obj Object to read.
2925 * @param[in] value Temporary value to use if necessary.
2926 * @param[out] ret Pointer to the returned value, which is <tt>&obj->value</tt>
2927 * if @p obj is a value, or @p value if @p obj is a reference.
2928 * @return @c NULL on success, non-@c NULL on error.
2929 */
2930 struct drgn_error *drgn_object_read_value(const struct drgn_object *obj,
2931 union drgn_value *value,
2932 const union drgn_value **ret);
2933
2934 /**
2935 * Deinitialize a value which was read with @ref drgn_object_read_value().
2936 *
2937 * @param[in] obj Object which was read.
2938 * @param[in] value Value returned from @ref drgn_object_read_value() in @p ret.
2939 */
2940 void drgn_object_deinit_value(const struct drgn_object *obj,
2941 const union drgn_value *value);
2942
2943 /**
2944 * Get the binary representation of the value of a @ref drgn_object.
2945 *
2946 * @param[out] Buffer to read into. Size must be at least
2947 * `drgn_object_size(obj)`.
2948 */
2949 struct drgn_error *drgn_object_read_bytes(const struct drgn_object *obj,
2950 void *buf);
2951
2952 /**
2953 * Get the value of an object encoded with @ref
2954 * drgn_object_encoding::DRGN_OBJECT_ENCODING_SIGNED.
2955 *
2956 * If the object is not a signed integer, an error is returned.
2957 *
2958 * @param[in] obj Object to read.
2959 * @param[out] ret Returned value.
2960 * @return @c NULL on success, non-@c NULL on error.
2961 */
2962 struct drgn_error *drgn_object_read_signed(const struct drgn_object *obj,
2963 int64_t *ret);
2964
2965 /**
2966 * Get the value of an object encoded with @ref
2967 * drgn_object_encoding::DRGN_OBJECT_ENCODING_UNSIGNED.
2968 *
2969 * If the object is not an unsigned integer, an error is returned.
2970 *
2971 * @param[in] obj Object to read.
2972 * @param[out] ret Returned value.
2973 * @return @c NULL on success, non-@c NULL on error.
2974 */
2975 struct drgn_error *drgn_object_read_unsigned(const struct drgn_object *obj,
2976 uint64_t *ret);
2977
2978 /**
2979 * Get the value of an object encoded with @ref
2980 * drgn_object_encoding::DRGN_OBJECT_ENCODING_SIGNED or @ref
2981 * drgn_object_encoding::DRGN_OBJECT_ENCODING_UNSIGNED.
2982 *
2983 * If the object is not an integer, an error is returned.
2984 *
2985 * @param[in] obj Object to read.
2986 * @param[out] ret Returned value.
2987 * @return @c NULL on success, non-@c NULL on error.
2988 */
2989 struct drgn_error *drgn_object_read_integer(const struct drgn_object *obj,
2990 union drgn_value *ret);
2991
2992 /**
2993 * Get the value of an object encoded with @ref
2994 * drgn_object_encoding::DRGN_OBJECT_ENCODING_FLOAT.
2995 *
2996 * If the object does not have a floating-point type, an error is returned.
2997 *
2998 * @param[in] obj Object to read.
2999 * @param[out] ret Returned value.
3000 * @return @c NULL on success, non-@c NULL on error.
3001 */
3002 struct drgn_error *drgn_object_read_float(const struct drgn_object *obj,
3003 double *ret);
3004
3005 /**
3006 * Read the null-terminated string pointed to by a @ref drgn_object.
3007 *
3008 * This is only valid for pointers and arrays. The element type is ignored; this
3009 * operates byte-by-byte.
3010 *
3011 * For pointers and flexible arrays, this stops at the first null byte.
3012 *
3013 * For complete arrays, this stops at the first null byte or at the end of the
3014 * array.
3015 *
3016 * The returned string is always null-terminated.
3017 *
3018 * @param[in] obj Object to read.
3019 * @param[out] ret Returned string. On success, it must be freed with @c free().
3020 * On error, it is not modified.
3021 */
3022 struct drgn_error *drgn_object_read_c_string(const struct drgn_object *obj,
3023 char **ret);
3024
3025 /** Flags to control @ref drgn_format_object() output. */
3026 enum drgn_format_object_flags {
3027 DRGN_FORMAT_OBJECT_DEREFERENCE = 1 << 0,
3028 DRGN_FORMAT_OBJECT_SYMBOLIZE = 1 << 1,
3029 DRGN_FORMAT_OBJECT_STRING = 1 << 2,
3030 DRGN_FORMAT_OBJECT_CHAR = 1 << 3,
3031 DRGN_FORMAT_OBJECT_TYPE_NAME = 1 << 4,
3032 DRGN_FORMAT_OBJECT_MEMBER_TYPE_NAMES = 1 << 5,
3033 DRGN_FORMAT_OBJECT_ELEMENT_TYPE_NAMES = 1 << 6,
3034 DRGN_FORMAT_OBJECT_MEMBERS_SAME_LINE = 1 << 7,
3035 DRGN_FORMAT_OBJECT_ELEMENTS_SAME_LINE = 1 << 8,
3036 DRGN_FORMAT_OBJECT_MEMBER_NAMES = 1 << 9,
3037 DRGN_FORMAT_OBJECT_ELEMENT_INDICES = 1 << 10,
3038 DRGN_FORMAT_OBJECT_IMPLICIT_MEMBERS = 1 << 11,
3039 DRGN_FORMAT_OBJECT_IMPLICIT_ELEMENTS = 1 << 12,
3040 /** Default "pretty" flags. */
3041 DRGN_FORMAT_OBJECT_PRETTY = (DRGN_FORMAT_OBJECT_DEREFERENCE |
3042 DRGN_FORMAT_OBJECT_SYMBOLIZE |
3043 DRGN_FORMAT_OBJECT_STRING |
3044 DRGN_FORMAT_OBJECT_TYPE_NAME |
3045 DRGN_FORMAT_OBJECT_MEMBER_TYPE_NAMES |
3046 DRGN_FORMAT_OBJECT_ELEMENTS_SAME_LINE |
3047 DRGN_FORMAT_OBJECT_MEMBER_NAMES |
3048 DRGN_FORMAT_OBJECT_IMPLICIT_MEMBERS),
3049 DRGN_FORMAT_OBJECT_VALID_FLAGS = (1 << 13) - 1,
3050 };
3051
3052 /** Formatting options for @ref drgn_format_object(). */
3053 struct drgn_format_object_options {
3054 /**
3055 * Number of columns to limit output to when the expression can be
3056 * reasonably wrapped. The default is @c SIZE_MAX.
3057 */
3058 size_t columns;
3059 /**
3060 * Flags to control formatting. The default is @ref
3061 * DRGN_FORMAT_OBJECT_PRETTY.
3062 */
3063 enum drgn_format_object_flags flags;
3064 /** Base to format integers in (8, 10, or 16). The default is 10. */
3065 int integer_base;
3066 };
3067
3068 /**
3069 * Format a @ref drgn_object as a string.
3070 *
3071 * This will format the object similarly to an expression in its programming
3072 * language.
3073 *
3074 * @param[in] obj Object to format.
3075 * @param[in] options Formatting options, or @c NULL to use the default options.
3076 * @param[out] ret Returned string. On success, it must be freed with @c free().
3077 * On error, it is not modified.
3078 * @return @c NULL on success, non-@c NULL on error.
3079 */
3080 struct drgn_error *
3081 drgn_format_object(const struct drgn_object *obj,
3082 const struct drgn_format_object_options *options,
3083 char **ret);
3084
3085 /** @} */
3086
3087 /**
3088 * @defgroup ObjectOperators Operators
3089 *
3090 * Object operators.
3091 *
3092 * Various operators are defined on @ref drgn_object%s. These operators obey the
3093 * rules of the programming language of the given objects.
3094 *
3095 * Operators which return a @ref drgn_object have the same calling convention:
3096 * the result object is the first argument, which must be initialized and may be
3097 * the same as one or more of the operands; the result is only modified if the
3098 * operator succeeds.
3099 *
3100 * @{
3101 */
3102
3103 /**
3104 * Set a @ref drgn_object to the value of an object explicitly casted to a
3105 * another type.
3106 *
3107 * This uses the programming language's rules for explicit conversions, like the
3108 * cast operator.
3109 *
3110 * @sa drgn_object_implicit_convert(), drgn_object_reinterpret()
3111 *
3112 * @param[out] res Object to set. Always set to a value object.
3113 * @param[in] qualified_type New type.
3114 * @param[in] obj Object to cast.
3115 * @return @c NULL on success, non-@c NULL on error.
3116 */
3117 struct drgn_error *drgn_object_cast(struct drgn_object *res,
3118 struct drgn_qualified_type qualified_type,
3119 const struct drgn_object *obj);
3120
3121 /**
3122 * Set a @ref drgn_object to the value of an object implicitly converted to a
3123 * another type.
3124 *
3125 * This uses the programming language's rules for implicit conversions, like
3126 * when assigning to a variable or passing arguments to a function call.
3127 *
3128 * @sa drgn_object_cast(), drgn_object_reinterpret()
3129 *
3130 * @param[out] res Object to set. Always set to a value object.
3131 * @param[in] qualified_type New type.
3132 * @param[in] bit_field_size If the object should be a bit field, its size in
3133 * bits. Otherwise, 0.
3134 * @param[in] obj Object to convert.
3135 * @return @c NULL on success, non-@c NULL on error.
3136 */
3137 struct drgn_error *
3138 drgn_object_implicit_convert(struct drgn_object *res,
3139 struct drgn_qualified_type qualified_type,
3140 uint64_t bit_field_size,
3141 const struct drgn_object *obj);
3142
3143 /**
3144 * Set a @ref drgn_object to the representation of an object reinterpreted as
3145 * another type.
3146 *
3147 * This reinterprets the raw memory of the object, so an object can be
3148 * reinterpreted as any other type.
3149 *
3150 * @sa drgn_object_cast(), drgn_object_implicit_convert()
3151 *
3152 * @param[out] res Object to set. If @p obj is a value, set to a value. If @p
3153 * obj is a reference, set to a reference.
3154 * @param[in] qualified_type New type.
3155 * @param[in] obj Object to reinterpret.
3156 * @return @c NULL on success, non-@c NULL on error.
3157 */
3158 struct drgn_error *
3159 drgn_object_reinterpret(struct drgn_object *res,
3160 struct drgn_qualified_type qualified_type,
3161 const struct drgn_object *obj);
3162
3163 /**
3164 * @ref drgn_object binary operator.
3165 *
3166 * Binary operators apply any language-specific conversions to @p lhs and @p
3167 * rhs, apply the operator, and store the result in @p res.
3168 *
3169 * @param[out] res Operator result. May be the same as @p lhs and/or @p rhs.
3170 * @param[in] lhs Operator left hand side.
3171 * @param[in] rhs Operator right hand side.
3172 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3173 * error.
3174 */
3175 typedef struct drgn_error *drgn_binary_op(struct drgn_object *res,
3176 const struct drgn_object *lhs,
3177 const struct drgn_object *rhs);
3178
3179 /**
3180 * @ref drgn_object unary operator.
3181 *
3182 * Unary operators apply any language-specific conversions to @p obj, apply the
3183 * operator, and store the result in @p res.
3184 *
3185 * @param[out] res Operator result. May be the same as @p obj.
3186 * @param[in] obj Operand.
3187 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3188 * error.
3189 */
3190 typedef struct drgn_error *drgn_unary_op(struct drgn_object *res,
3191 const struct drgn_object *obj);
3192
3193 /**
3194 * Convert a @ref drgn_object to a boolean value.
3195 *
3196 * This gets the "truthiness" of an object according to its programming
3197 * language.
3198 *
3199 * @param[in] obj Object.
3200 * @param[out] ret Returned boolean value.
3201 * @return @c NULL on success, non-@c NULL on error.
3202 */
3203 struct drgn_error *drgn_object_bool(const struct drgn_object *obj, bool *ret);
3204
3205 /**
3206 * Compare the value of two @ref drgn_object%s.
3207 *
3208 * This applies any language-specific conversions to @p lhs and @p rhs and
3209 * compares the resulting values.
3210 *
3211 * @param[in] lhs Comparison left hand side.
3212 * @param[in] rhs Comparison right hand side.
3213 * @param[out] ret 0 if the operands are equal, < 0 if @p lhs < @p rhs, and > 0
3214 * if @p lhs > @p rhs.
3215 * @return @c NULL on success, non-@c NULL on error.
3216 */
3217 struct drgn_error *drgn_object_cmp(const struct drgn_object *lhs,
3218 const struct drgn_object *rhs, int *ret);
3219
3220 /** Add (@c +) two @ref drgn_object%s. */
3221 drgn_binary_op drgn_object_add;
3222 /** Subtract (@c -) a @ref drgn_object from another. */
3223 drgn_binary_op drgn_object_sub;
3224 /** Multiply (@c *) two @ref drgn_object%s. */
3225 drgn_binary_op drgn_object_mul;
3226 /** Divide (@c /) a @ref drgn_object by another. */
3227 drgn_binary_op drgn_object_div;
3228 /** Calculate the modulus (@c %) of two @ref drgn_object%s. */
3229 drgn_binary_op drgn_object_mod;
3230 /** Left shift (@c <<) a @ref drgn_object by another. */
3231 drgn_binary_op drgn_object_lshift;
3232 /** Right shift (@c >>) a @ref drgn_object by another. */
3233 drgn_binary_op drgn_object_rshift;
3234 /** Calculate the bitwise and (@c &) of two @ref drgn_object%s. */
3235 drgn_binary_op drgn_object_and;
3236 /** Calculate the bitwise or (@c |) of two @ref drgn_object%s. */
3237 drgn_binary_op drgn_object_or;
3238 /** Calculate the bitwise exclusive or (@c ^) of two @ref drgn_object%s. */
3239 drgn_binary_op drgn_object_xor;
3240 /** Apply unary plus (@c +) to a @ref drgn_object. */
3241 drgn_unary_op drgn_object_pos;
3242 /** Calculate the arithmetic negation (@c -) of a @ref drgn_object. */
3243 drgn_unary_op drgn_object_neg;
3244 /** Calculate the bitwise negation (@c ~) of a @ref drgn_object. */
3245 drgn_unary_op drgn_object_not;
3246
3247 /**
3248 * Get the address of (@c &) a @ref drgn_object as an object.
3249 *
3250 * This is only possible for reference objects, as value objects don't have an
3251 * address in the program.
3252 *
3253 * @param[out] res Resulting pointer value. May be the same as @p obj.
3254 * @param[in] obj Reference object.
3255 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3256 * error.
3257 */
3258 struct drgn_error *drgn_object_address_of(struct drgn_object *res,
3259 const struct drgn_object *obj);
3260
3261 /**
3262 * Subscript (@c []) a @ref drgn_object.
3263 *
3264 * This is applicable to pointers and arrays.
3265 *
3266 * @param[out] res Resulting element. May be the same as @p obj.
3267 * @param[in] obj Object to subscript.
3268 * @param[in] index Element index.
3269 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3270 * error.
3271 */
3272 struct drgn_error *drgn_object_subscript(struct drgn_object *res,
3273 const struct drgn_object *obj,
3274 int64_t index);
3275
3276 /**
3277 * Deference (@c *) a @ref drgn_object.
3278 *
3279 * This is equivalent to @ref drgn_object_subscript with an index of 0.
3280 *
3281 * @param[out] res Deferenced object. May be the same as @p obj.
3282 * @param[in] obj Object to dereference.
3283 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3284 * error.
3285 */
3286 static inline struct drgn_error *
3287 drgn_object_dereference(struct drgn_object *res, const struct drgn_object *obj)
3288 {
3289 return drgn_object_subscript(res, obj, 0);
3290 }
3291
3292 /**
3293 * Slice (i.e., get an array from a range of another array) a @ref drgn_object.
3294 *
3295 * This is applicable to pointers and arrays.
3296 *
3297 * @param[out] res Resulting array. May be the same as @p obj.
3298 * @param[in] obj Object to slice.
3299 * @param[in] start Start index (inclusive).
3300 * @param[in] end End index (exclusive).
3301 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3302 * error.
3303 */
3304 struct drgn_error *drgn_object_slice(struct drgn_object *res,
3305 const struct drgn_object *obj,
3306 int64_t start, int64_t end);
3307
3308 /**
3309 * Get a member of a structure, union, or class @ref drgn_object (@c .).
3310 *
3311 * @param[out] res Returned member. May be the same as @p obj.
3312 * @param[in] obj Object.
3313 * @param[in] member_name Name of member.
3314 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3315 * error.
3316 */
3317 struct drgn_error *drgn_object_member(struct drgn_object *res,
3318 const struct drgn_object *obj,
3319 const char *member_name);
3320
3321 /**
3322 * Get a member of a pointer @ref drgn_object (@c ->).
3323 *
3324 * This is applicable to pointers to structures and pointers to unions.
3325 *
3326 * @param[out] res Returned member. May be the same as @p obj.
3327 * @param[in] obj Object.
3328 * @param[in] member_name Name of member.
3329 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3330 * error.
3331 */
3332 struct drgn_error *drgn_object_member_dereference(struct drgn_object *res,
3333 const struct drgn_object *obj,
3334 const char *member_name);
3335
3336
3337 /**
3338 * Get a subobject (member or element) of this object.
3339 *
3340 * @param[out] res Returned subobject. May be the same as @p obj.
3341 * @param[in] obj Object.
3342 * @param[in] designator One or more member references or array subscripts.
3343 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3344 * error.
3345 */
3346 struct drgn_error *drgn_object_subobject(struct drgn_object *res,
3347 const struct drgn_object *obj,
3348 const char *member_designator);
3349
3350
3351 /**
3352 * Get the containing object of a member @ref drgn_object.
3353 *
3354 * This corresponds to the @c container_of() macro commonly used in C.
3355 *
3356 * @param[out] res Returned object. May be the same as @p obj.
3357 * @param[in] obj Pointer to a member.
3358 * @param[in] qualified_type Type which contains the member.
3359 * @param[in] member_designator Name of the member in @p qualified_type. This
3360 * can include one or more member references and zero or more array subscripts.
3361 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
3362 * error.
3363 */
3364 struct drgn_error *
3365 drgn_object_container_of(struct drgn_object *res, const struct drgn_object *obj,
3366 struct drgn_qualified_type qualified_type,
3367 const char *member_designator);
3368
3369 /**
3370 * Get the size of a @ref drgn_object in bytes.
3371 *
3372 * @param[in] obj Object.
3373 * @param[out] ret Returned size.
3374 * @return @c NULL on success, non-@c NULL on error.
3375 */
3376 struct drgn_error *drgn_object_sizeof(const struct drgn_object *obj,
3377 uint64_t *ret);
3378
3379 /** @} */
3380
3381 /** @} */
3382
3383 /**
3384 * @ingroup LazyObjects
3385 *
3386 * Callback to evaluate and/or free a @ref drgn_lazy_object.
3387 *
3388 * If @p res is not @c NULL, then this should return the object in @p res and
3389 * free @p arg if necessary. If this returns an error, it may be called again
3390 * (so @p arg must remain valid).
3391 *
3392 * If @p res is @c NULL, then this should free @p arg if necessary; it must not
3393 * return an error.
3394 *
3395 * @param[out] res Result object (if evaluating) or @c NULL (if freeing). This
3396 * is already initialized and should not be deinitialized on error.
3397 * @param[in] arg Callback argument passed to @ref
3398 * drgn_lazy_object_init_thunk().
3399 * @return @c NULL on success, non-@c NULL on error.
3400 */
3401 typedef struct drgn_error *drgn_object_thunk_fn(struct drgn_object *res,
3402 void *arg);
3403
3404 /**
3405 * @ingroup LazyObjects
3406 *
3407 * Lazily-evaluated object.
3408 *
3409 * A lazy object may be in two states: unevaluated, in which case a callback
3410 * must be called to evaluate the object, or evaluated, in which case the object
3411 * is cached. To evaluate an object, the callback is called, and the result is
3412 * cached.
3413 *
3414 * This is for internal use only.
3415 */
3416 union drgn_lazy_object {
3417 /** Object if it has already been evaluated. */
3418 struct drgn_object obj;
3419 /** Thunk if the object has not been evaluated yet. */
3420 struct {
3421 /**
3422 * Always @c NULL to indicate an unevaluated lazy object.
3423 *
3424 * This must be at the same offset as @ref drgn_object::type.
3425 */
3426 struct drgn_type *dummy_type;
3427 /** Program owning this thunk. */
3428 struct drgn_program *prog;
3429 /** Callback. */
3430 drgn_object_thunk_fn *fn;
3431 /** Argument passed to @ref drgn_lazy_object::thunk::fn. */
3432 void *arg;
3433 } thunk;
3434 };
3435
3436 /**
3437 * @defgroup Types Types
3438 *
3439 * Type descriptors.
3440 *
3441 * Types in a program are represented by @ref drgn_type.
3442 *
3443 * Type descriptors have various fields depending on the kind of type. For each
3444 * field @c foo, there is a @c drgn_type_kind_has_foo() helper which returns
3445 * whether the given kind of type has the field @c foo; a @c drgn_type_has_foo()
3446 * helper which does the same but takes a type; and a @c drgn_type_foo() helper
3447 * which returns the field. For members, enumerators, parameters, and template
3448 * parameters, there is also a @c drgn_type_num_foo() helper.
3449 *
3450 * @{
3451 */
3452
3453 /** Primitive types known to drgn. */
3454 enum drgn_primitive_type {
3455 /* Primitive C types. */
3456 DRGN_C_TYPE_VOID,
3457 DRGN_C_TYPE_CHAR,
3458 DRGN_C_TYPE_SIGNED_CHAR,
3459 DRGN_C_TYPE_UNSIGNED_CHAR,
3460 DRGN_C_TYPE_SHORT,
3461 DRGN_C_TYPE_UNSIGNED_SHORT,
3462 DRGN_C_TYPE_INT,
3463 DRGN_C_TYPE_UNSIGNED_INT,
3464 DRGN_C_TYPE_LONG,
3465 DRGN_C_TYPE_UNSIGNED_LONG,
3466 DRGN_C_TYPE_LONG_LONG,
3467 DRGN_C_TYPE_UNSIGNED_LONG_LONG,
3468 DRGN_C_TYPE_BOOL,
3469 DRGN_C_TYPE_FLOAT,
3470 DRGN_C_TYPE_DOUBLE,
3471 DRGN_C_TYPE_LONG_DOUBLE,
3472 DRGN_C_TYPE_SIZE_T,
3473 DRGN_C_TYPE_PTRDIFF_T,
3474 DRGN_PRIMITIVE_TYPE_NUM,
3475 DRGN_NOT_PRIMITIVE_TYPE = DRGN_PRIMITIVE_TYPE_NUM,
3476 /*
3477 * Make sure to update api_reference.rst and type.c when adding anything
3478 * here.
3479 */
3480 } __attribute__((__packed__));
3481
3482 /** Member of a structure, union, or class type. */
3483 struct drgn_type_member {
3484 /**
3485 * Member as an object.
3486 *
3487 * Access this with @ref drgn_member_object() or @ref
3488 * drgn_member_type().
3489 */
3490 union drgn_lazy_object object;
3491 /** Member name or @c NULL if it is unnamed. */
3492 const char *name;
3493 /**
3494 * Offset in bits from the beginning of the type to the beginning of
3495 * this member (i.e., for little-endian machines, the least significant
3496 * bit, and for big-endian machines, the most significant bit). Members
3497 * are usually aligned to at least a byte, so this is usually a multiple
3498 * of 8 (but that may not be the case for bit fields).
3499 */
3500 uint64_t bit_offset;
3501 };
3502
3503 /** Value of an enumerated type. */
3504 struct drgn_type_enumerator {
3505 /** Enumerator name. */
3506 const char *name;
3507 union {
3508 /** Enumerator value if the type is signed. */
3509 int64_t svalue;
3510 /** Enumerator value if the type is unsigned. */
3511 uint64_t uvalue;
3512 };
3513 };
3514
3515 /** Parameter of a function type. */
3516 struct drgn_type_parameter {
3517 /**
3518 * Parameter type and default argument.
3519 *
3520 * Access this with @ref drgn_parameter_default_argument() or @ref
3521 * drgn_parameter_type().
3522 */
3523 union drgn_lazy_object default_argument;
3524 /** Parameter name or @c NULL if it is unnamed. */
3525 const char *name;
3526 };
3527
3528 /** Template parameter of a structure, union, class, or function type. */
3529 struct drgn_type_template_parameter {
3530 /**
3531 * Template parameter type or value.
3532 *
3533 * Access this with @ref drgn_template_parameter_type() and @ref
3534 * drgn_template_parameter_object().
3535 */
3536 union drgn_lazy_object argument;
3537 /** Template parameter name or @c NULL if it is unnamed. */
3538 const char *name;
3539 /** Whether the argument is the default. */
3540 bool is_default;
3541 };
3542
3543 /**
3544 * @struct drgn_type
3545 *
3546 * Type descriptor.
3547 *
3548 * Access it with the getters in @ref Types.
3549 */
3550 struct drgn_type;
3551
3552 /** Get the kind of a type. */
3553 DRGN_ACCESSOR_LINKAGE
3554 enum drgn_type_kind drgn_type_kind(struct drgn_type *type);
3555
3556 /** Get the primitive type corresponding to a @ref drgn_type. */
3557 DRGN_ACCESSOR_LINKAGE
3558 enum drgn_primitive_type drgn_type_primitive(struct drgn_type *type);
3559
3560 /**
3561 * Get whether a type is complete (i.e., the type definition is known).
3562 *
3563 * This is always @c false for the void type. It may be @c false for structure,
3564 * union, class, enumerated, and array types, as well as typedef types where the
3565 * underlying type is one of those. Otherwise, it is always @c true.
3566 */
3567 DRGN_ACCESSOR_LINKAGE
3568 bool drgn_type_is_complete(struct drgn_type *type);
3569
3570 /**
3571 * Get whether a kind of type has a name. This is true for integer, boolean,
3572 * floating-point, and typedef types.
3573 */
3574 static inline bool drgn_type_kind_has_name(enum drgn_type_kind kind)
3575 {
3576 return (kind == DRGN_TYPE_INT ||
3577 kind == DRGN_TYPE_BOOL ||
3578 kind == DRGN_TYPE_FLOAT ||
3579 kind == DRGN_TYPE_TYPEDEF);
3580 }
3581 /** Get whether a type has a name. @sa drgn_type_kind_has_name() */
3582 static inline bool drgn_type_has_name(struct drgn_type *type)
3583 {
3584 return drgn_type_kind_has_name(drgn_type_kind(type));
3585 }
3586 /**
3587 * Get the name of a type. @ref drgn_type_has_name() must be true for this type.
3588 */
3589 DRGN_ACCESSOR_LINKAGE
3590 const char *drgn_type_name(struct drgn_type *type);
3591
3592 /**
3593 * Get whether a kind of type has a size. This is true for integer, boolean,
3594 * floating-point, structure, union, class, and pointer types.
3595 */
3596 static inline bool drgn_type_kind_has_size(enum drgn_type_kind kind)
3597 {
3598 return (kind == DRGN_TYPE_INT ||
3599 kind == DRGN_TYPE_BOOL ||
3600 kind == DRGN_TYPE_FLOAT ||
3601 kind == DRGN_TYPE_STRUCT ||
3602 kind == DRGN_TYPE_UNION ||
3603 kind == DRGN_TYPE_CLASS ||
3604 kind == DRGN_TYPE_POINTER);
3605 }
3606 /** Get whether a type has a size. @sa drgn_type_kind_has_size() */
3607 static inline bool drgn_type_has_size(struct drgn_type *type)
3608 {
3609 return drgn_type_kind_has_size(drgn_type_kind(type));
3610 }
3611 /**
3612 * Get the size of a type in bytes. @ref drgn_type_has_size() must be true for
3613 * this type.
3614 */
3615 DRGN_ACCESSOR_LINKAGE
3616 uint64_t drgn_type_size(struct drgn_type *type);
3617
3618 /**
3619 * Get whether a kind of type has a signedness. This is true for integer types.
3620 */
3621 static inline bool drgn_type_kind_has_is_signed(enum drgn_type_kind kind)
3622 {
3623 return kind == DRGN_TYPE_INT;
3624 }
3625 /** Get whether a type has a signedness. @sa drgn_type_kind_has_is_signed() */
3626 static inline bool drgn_type_has_is_signed(struct drgn_type *type)
3627 {
3628 return drgn_type_kind_has_is_signed(drgn_type_kind(type));
3629 }
3630 /**
3631 * Get the signedness of a type. @ref drgn_type_has_is_signed() must be true for
3632 * this type.
3633 */
3634 DRGN_ACCESSOR_LINKAGE
3635 bool drgn_type_is_signed(struct drgn_type *type);
3636
3637 /**
3638 * Get whether a kind of type has a byte order. This is true for integer,
3639 * boolean, floating-point, and pointer types.
3640 */
3641 static inline bool drgn_type_kind_has_little_endian(enum drgn_type_kind kind)
3642 {
3643 return (kind == DRGN_TYPE_INT ||
3644 kind == DRGN_TYPE_BOOL ||
3645 kind == DRGN_TYPE_FLOAT ||
3646 kind == DRGN_TYPE_POINTER);
3647 }
3648 /**
3649 * Get whether a type has a byte order. @sa drgn_type_kind_has_little_endian()
3650 */
3651 static inline bool drgn_type_has_little_endian(struct drgn_type *type)
3652 {
3653 return drgn_type_kind_has_little_endian(drgn_type_kind(type));
3654 }
3655 /**
3656 * Get the byte order of a type. @ref drgn_type_has_little_endian() must be true
3657 * for this type.
3658 *
3659 * @return @c true if the type is little-endian, @c false if it is big-endian.
3660 */
3661 DRGN_ACCESSOR_LINKAGE
3662 bool drgn_type_little_endian(struct drgn_type *type);
3663
3664 /**
3665 * Get whether a kind of type has a tag. This is true for structure, union,
3666 * class, and enumerated types.
3667 */
3668 static inline bool drgn_type_kind_has_tag(enum drgn_type_kind kind)
3669 {
3670 return (kind == DRGN_TYPE_STRUCT ||
3671 kind == DRGN_TYPE_UNION ||
3672 kind == DRGN_TYPE_CLASS ||
3673 kind == DRGN_TYPE_ENUM);
3674 }
3675 /** Get whether a type has a tag. @sa drgn_type_kind_has_tag() */
3676 static inline bool drgn_type_has_tag(struct drgn_type *type)
3677 {
3678 return drgn_type_kind_has_tag(drgn_type_kind(type));
3679 }
3680 /**
3681 * Get the tag of a type. @ref drgn_type_has_tag() must be true for this type.
3682 */
3683 DRGN_ACCESSOR_LINKAGE
3684 const char *drgn_type_tag(struct drgn_type *type);
3685
3686 /**
3687 * Get whether a kind of type has members. This is true for structure, union,
3688 * and class types.
3689 */
3690 static inline bool drgn_type_kind_has_members(enum drgn_type_kind kind)
3691 {
3692 return (kind == DRGN_TYPE_STRUCT ||
3693 kind == DRGN_TYPE_UNION ||
3694 kind == DRGN_TYPE_CLASS);
3695 }
3696 /** Get whether a type has members. @sa drgn_type_kind_has_members() */
3697 static inline bool drgn_type_has_members(struct drgn_type *type)
3698 {
3699 return drgn_type_kind_has_members(drgn_type_kind(type));
3700 }
3701 /**
3702 * Get the members of a type. @ref drgn_type_has_members() must be true for this
3703 * type.
3704 */
3705 DRGN_ACCESSOR_LINKAGE
3706 struct drgn_type_member *drgn_type_members(struct drgn_type *type);
3707 /**
3708 * Get the number of members of a type. @ref drgn_type_has_members() must be
3709 * true for this type. If the type is incomplete, this is always zero.
3710 */
3711 DRGN_ACCESSOR_LINKAGE
3712 size_t drgn_type_num_members(struct drgn_type *type);
3713
3714 /**
3715 * Get whether a kind of type has a wrapped type. This is true for enumerated,
3716 * typedef, pointer, array, and function types.
3717 */
3718 static inline bool drgn_type_kind_has_type(enum drgn_type_kind kind)
3719 {
3720 return (kind == DRGN_TYPE_ENUM ||
3721 kind == DRGN_TYPE_TYPEDEF ||
3722 kind == DRGN_TYPE_POINTER ||
3723 kind == DRGN_TYPE_ARRAY ||
3724 kind == DRGN_TYPE_FUNCTION);
3725 }
3726 /** Get whether a type has a wrapped type. @sa drgn_type_kind_has_type() */
3727 static inline bool drgn_type_has_type(struct drgn_type *type)
3728 {
3729 return drgn_type_kind_has_type(drgn_type_kind(type));
3730 }
3731 /**
3732 * Get the type wrapped by this type.
3733 *
3734 * For an enumerated type, this is the compatible integer type. It is @c NULL if
3735 * the enumerated type is incomplete.
3736 *
3737 * For a typedef type, this is the aliased type.
3738 *
3739 * For a pointer type, this is the referenced type.
3740 *
3741 * For an array type, this is the element type.
3742 *
3743 * For a function type, this is the return type.
3744 */
3745 DRGN_ACCESSOR_LINKAGE
3746 struct drgn_qualified_type drgn_type_type(struct drgn_type *type);
3747
3748 /**
3749 * Get whether a kind of type has enumerators. This is true for enumerated
3750 * types.
3751 */
3752 static inline bool drgn_type_kind_has_enumerators(enum drgn_type_kind kind)
3753 {
3754 return kind == DRGN_TYPE_ENUM;
3755 }
3756 /** Get whether a type has enumerators. @sa drgn_type_kind_has_enumerators() */
3757 static inline bool drgn_type_has_enumerators(struct drgn_type *type)
3758 {
3759 return drgn_type_kind_has_enumerators(drgn_type_kind(type));
3760 }
3761 /**
3762 * Get the enumerators of a type. @ref drgn_type_has_enumerators() must be true
3763 * for this type.
3764 */
3765 DRGN_ACCESSOR_LINKAGE
3766 struct drgn_type_enumerator *drgn_type_enumerators(struct drgn_type *type);
3767 /**
3768 * Get the number of enumerators of a type. @ref drgn_type_has_enumerators()
3769 * must be true for this type. If the type is incomplete, this is always zero.
3770 */
3771 DRGN_ACCESSOR_LINKAGE
3772 size_t drgn_type_num_enumerators(struct drgn_type *type);
3773
3774 /** Get whether a kind of type has a length. This is true for array types. */
3775 static inline bool drgn_type_kind_has_length(enum drgn_type_kind kind)
3776 {
3777 return kind == DRGN_TYPE_ARRAY;
3778 }
3779 /** Get whether a type has a length. @sa drgn_type_kind_has_length() */
3780 static inline bool drgn_type_has_length(struct drgn_type *type)
3781 {
3782 return drgn_type_kind_has_length(drgn_type_kind(type));
3783 }
3784 /**
3785 * Get the length of a type. @ref drgn_type_has_length() must be true for this
3786 * type. If the type is incomplete, this is always zero.
3787 */
3788 DRGN_ACCESSOR_LINKAGE
3789 uint64_t drgn_type_length(struct drgn_type *type);
3790
3791 /**
3792 * Get whether a kind of type has parameters. This is true for function types.
3793 */
3794 static inline bool drgn_type_kind_has_parameters(enum drgn_type_kind kind)
3795 {
3796 return kind == DRGN_TYPE_FUNCTION;
3797 }
3798 /** Get whether a type has parameters. @sa drgn_type_kind_has_parameters() */
3799 static inline bool drgn_type_has_parameters(struct drgn_type *type)
3800 {
3801 return drgn_type_kind_has_parameters(drgn_type_kind(type));
3802 }
3803 /**
3804 * Get the parameters of a type. @ref drgn_type_has_parameters() must be true
3805 * for this type.
3806 */
3807 DRGN_ACCESSOR_LINKAGE
3808 struct drgn_type_parameter *drgn_type_parameters(struct drgn_type *type);
3809 /**
3810 * Get the number of parameters of a type. @ref drgn_type_has_parameters() must
3811 * be true for this type.
3812 */
3813 DRGN_ACCESSOR_LINKAGE
3814 size_t drgn_type_num_parameters(struct drgn_type *type);
3815
3816 /**
3817 * Get whether a kind of type can be variadic. This is true for function types.
3818 */
3819 static inline bool drgn_type_kind_has_is_variadic(enum drgn_type_kind kind)
3820 {
3821 return kind == DRGN_TYPE_FUNCTION;
3822 }
3823 /** Get whether a type can be variadic. @sa drgn_type_kind_has_is_variadic() */
3824 static inline bool drgn_type_has_is_variadic(struct drgn_type *type)
3825 {
3826 return drgn_type_kind_has_is_variadic(drgn_type_kind(type));
3827 }
3828 /**
3829 * Get whether a type is variadic. @ref drgn_type_has_is_variadic() must be true
3830 * for this type.
3831 */
3832 DRGN_ACCESSOR_LINKAGE
3833 bool drgn_type_is_variadic(struct drgn_type *type);
3834
3835 /** Get whether a kind of type can have template parameters. */
3836 static inline bool
3837 drgn_type_kind_has_template_parameters(enum drgn_type_kind kind)
3838 {
3839 return (kind == DRGN_TYPE_STRUCT ||
3840 kind == DRGN_TYPE_UNION ||
3841 kind == DRGN_TYPE_CLASS ||
3842 kind == DRGN_TYPE_FUNCTION);
3843 }
3844 /** Get whether a type can have template parameters. */
3845 static inline bool drgn_type_has_template_parameters(struct drgn_type *type)
3846 {
3847 return drgn_type_kind_has_template_parameters(drgn_type_kind(type));
3848 }
3849 /**
3850 * Get the template parameters of a type. @ref
3851 * drgn_type_has_template_parameters() must be true for this type.
3852 */
3853 DRGN_ACCESSOR_LINKAGE
3854 struct drgn_type_template_parameter *
3855 drgn_type_template_parameters(struct drgn_type *type);
3856 /**
3857 * Get the number of template parameters of a type. @ref
3858 * drgn_type_has_template_parameters() must be true for this type.
3859 */
3860 DRGN_ACCESSOR_LINKAGE
3861 size_t drgn_type_num_template_parameters(struct drgn_type *type);
3862
3863 /** Remove all top-level typedefs from a @ref drgn_qualified_type. */
3864 struct drgn_qualified_type
3865 drgn_qualified_type_unaliased(struct drgn_qualified_type qualified_type);
3866
3867 /**
3868 * Get the object corresponding to a @ref drgn_type_member.
3869 *
3870 * @param[in] member Member.
3871 * @param[out] ret Returned object.
3872 * @return @c NULL on success, non-@c NULL on error.
3873 */
3874 struct drgn_error *drgn_member_object(struct drgn_type_member *member,
3875 const struct drgn_object **ret)
3876 __attribute__((__nonnull__(1, 2)));
3877
3878 /**
3879 * Get the type of a @ref drgn_type_member.
3880 *
3881 * @param[in] member Member.
3882 * @param[out] type_ret Returned type.
3883 * @param[out] bit_field_size_ret If the member is a bit field, returned size of
3884 * the field in bits. Otherwise, returned as 0. Can be @c NULL if not needed.
3885 * @return @c NULL on success, non-@c NULL on error.
3886 */
3887 struct drgn_error *drgn_member_type(struct drgn_type_member *member,
3888 struct drgn_qualified_type *type_ret,
3889 uint64_t *bit_field_size_ret)
3890 __attribute__((__nonnull__(1, 2)));
3891
3892 /**
3893 * Get the default argument of a @ref drgn_type_parameter.
3894 *
3895 * @param[in] parameter Parameter.
3896 * @param[out] ret Returned object.
3897 * @return @c NULL on success, non-@c NULL on error.
3898 */
3899 struct drgn_error *
3900 drgn_parameter_default_argument(struct drgn_type_parameter *parameter,
3901 const struct drgn_object **ret)
3902 __attribute__((__nonnull__(1, 2)));
3903
3904 /**
3905 * Get the type of a @ref drgn_type_parameter.
3906 *
3907 * @param[in] parameter Parameter.
3908 * @param[out] ret Returned type.
3909 * @return @c NULL on success, non-@c NULL on error.
3910 */
3911 struct drgn_error *drgn_parameter_type(struct drgn_type_parameter *parameter,
3912 struct drgn_qualified_type *ret)
3913 __attribute__((__nonnull__(1, 2)));
3914
3915 /**
3916 * Get the type of a @ref drgn_type_template_parameter.
3917 *
3918 * If the template parameter is a non-type template parameter, this is the type
3919 * of its value.
3920 *
3921 * @param[in] parameter Template parameter.
3922 * @param[out] ret Returned type.
3923 * @return @c NULL on success, non-@c NULL on error.
3924 */
3925 struct drgn_error *
3926 drgn_template_parameter_type(struct drgn_type_template_parameter *parameter,
3927 struct drgn_qualified_type *ret)
3928 __attribute__((__nonnull__(1, 2)));
3929
3930 /**
3931 * Get the value of a @ref drgn_type_template_parameter.
3932 *
3933 * @param[in] parameter Template parameter.
3934 * @param[out] ret Returned object. If @p parameter is a type template
3935 * parameter, this is returned as @c NULL.
3936 * @return @c NULL on success, non-@c NULL on error.
3937 */
3938 struct drgn_error *
3939 drgn_template_parameter_object(struct drgn_type_template_parameter *parameter,
3940 const struct drgn_object **ret)
3941 __attribute__((__nonnull__(1, 2)));
3942
3943 /**
3944 * Get the size of a type in bytes.
3945 *
3946 * Unlike @ref drgn_type_size(), this is applicable to any type which has a
3947 * meaningful size, including typedefs and arrays. Void, function, and
3948 * incomplete types do not have a size; an error is returned for those types.
3949 *
3950 * @param[in] type Type.
3951 * @param[out] ret Returned size.
3952 * @return @c NULL on success, non-@c NULL on error.
3953 */
3954 struct drgn_error *drgn_type_sizeof(struct drgn_type *type, uint64_t *ret);
3955
3956 /**
3957 * Get the alignment requirement of a type.
3958 *
3959 * This corresponds to @c _Alignof() in C.
3960 *
3961 * @param[in] type Type.
3962 * @param[out] ret Returned alignment.
3963 * @return @c NULL on success, non-@c NULL on error.
3964 */
3965 struct drgn_error *drgn_type_alignof(struct drgn_qualified_type qualified_type,
3966 uint64_t *ret);
3967
3968 /**
3969 * Get the offset in bytes of a member from the start of a structure, union, or
3970 * class type.
3971 *
3972 * This corresponds to @c offsetof() in C.
3973 *
3974 * @param[in] type Type which contains the member.
3975 * @param[in] member_designator Name of the member in @p type. This can include
3976 * one or more member references and zero or more array subscripts.
3977 */
3978 struct drgn_error *drgn_type_offsetof(struct drgn_type *type,
3979 const char *member_designator,
3980 uint64_t *ret);
3981
3982 /**
3983 * Like @ref drgn_type_find_member(), but takes the length of @p member_name.
3984 */
3985 struct drgn_error *
3986 drgn_type_find_member_len(struct drgn_type *type, const char *member_name,
3987 size_t member_name_len,
3988 struct drgn_type_member **member_ret,
3989 uint64_t *bit_offset_ret);
3990
3991 /**
3992 * Find a member in a @ref drgn_type by name.
3993 *
3994 * If the type has any unnamed members, this also matches members of those
3995 * unnamed members, recursively.
3996 *
3997 * @param[in] type Structure, union, or class type.
3998 * @param[in] member_name Name of member.
3999 * @param[out] member_ret Returned member.
4000 * @param[out] bit_offset_ret Returned offset in bits from the beginning of @p
4001 * type to the beginning of the member. This can be different from @ref
4002 * drgn_type_member::bit_offset if the returned member was found in an unnamed
4003 * member of @p type.
4004 */
4005 static inline struct drgn_error *
4006 drgn_type_find_member(struct drgn_type *type, const char *member_name,
4007 struct drgn_type_member **member_ret,
4008 uint64_t *bit_offset_ret)
4009 {
4010 return drgn_type_find_member_len(type, member_name, strlen(member_name),
4011 member_ret, bit_offset_ret);
4012 }
4013
4014 /** Like @ref drgn_type_has_member(), but takes the length of @p member_name. */
4015 struct drgn_error *drgn_type_has_member_len(struct drgn_type *type,
4016 const char *member_name,
4017 size_t member_name_len, bool *ret);
4018
4019 /**
4020 * Return whether a @ref drgn_type has a member with the given name.
4021 *
4022 * @param[in] type Structure, union, or class type.
4023 * @param[in] member_name Name of member.
4024 */
4025 static inline struct drgn_error *drgn_type_has_member(struct drgn_type *type,
4026 const char *member_name,
4027 bool *ret)
4028 {
4029 return drgn_type_has_member_len(type, member_name, strlen(member_name),
4030 ret);
4031 }
4032
4033 /**
4034 * Format the name of a type as a string.
4035 *
4036 * This will format the name of the type as it would be referred to in its
4037 * programming language.
4038 *
4039 * @param[in] qualified_type Type to format.
4040 * @param[out] ret Returned string. On success, it must be freed with @c free().
4041 * On error, it is not modified.
4042 * @return @c NULL on success, non-@c NULL on error.
4043 */
4044 struct drgn_error *
4045 drgn_format_type_name(struct drgn_qualified_type qualified_type, char **ret);
4046
4047 /**
4048 * Format the definition of a type as a string.
4049 *
4050 * This will format the type as it would be defined in its programming language.
4051 *
4052 * @param[in] qualified_type Type to format.
4053 * @param[out] ret Returned string. On success, it must be freed with @c free().
4054 * On error, it is not modified.
4055 * @return @c NULL on success, non-@c NULL on error.
4056 */
4057 struct drgn_error *drgn_format_type(struct drgn_qualified_type qualified_type,
4058 char **ret);
4059
4060
4061 /**
4062 * Format a variable declaration with the given type and name.
4063 *
4064 * This will format the variable as it would be declared in its programming
4065 * language.
4066 *
4067 * @param[in] qualified_type Variable type.
4068 * @param[in] name Variable name.
4069 * @param[out] ret Returned string. On success, it must be freed with @c free().
4070 * On error, it is not modified.
4071 * @return @c NULL on success, non-@c NULL on error.
4072 */
4073 struct drgn_error *
4074 drgn_format_variable_declaration(struct drgn_qualified_type qualified_type,
4075 const char *name, char **ret)
4076 __attribute__((__nonnull__(2, 3)));
4077
4078 /** @} */
4079
4080 /**
4081 * @defgroup Symbols Symbols
4082 *
4083 * Symbol table entries.
4084 *
4085 * @sa drgn_program_find_symbol_by_address()
4086 *
4087 * @{
4088 */
4089
4090 /** Symbol linkage behavior and visibility. */
4091 enum drgn_symbol_binding {
4092 DRGN_SYMBOL_BINDING_UNKNOWN,
4093 /*
4094 * These values match the ELF STB_* definitions (offset by 1). This is
4095 * an implementation detail; future values may not correspond 1:1 with
4096 * ELF definitions.
4097 */
4098 DRGN_SYMBOL_BINDING_LOCAL,
4099 DRGN_SYMBOL_BINDING_GLOBAL,
4100 DRGN_SYMBOL_BINDING_WEAK,
4101 DRGN_SYMBOL_BINDING_UNIQUE = 11, /* STB_GNU_UNIQUE + 1 */
4102 } __attribute__((__packed__));
4103
4104 /** Kind of entity represented by a symbol. */
4105 enum drgn_symbol_kind {
4106 /*
4107 * Like enum drgn_symbol_binding, these values match the ELF STT_*
4108 * definitions, but this will not necessarily be true for future values.
4109 */
4110 DRGN_SYMBOL_KIND_UNKNOWN,
4111 DRGN_SYMBOL_KIND_OBJECT,
4112 DRGN_SYMBOL_KIND_FUNC,
4113 DRGN_SYMBOL_KIND_SECTION,
4114 DRGN_SYMBOL_KIND_FILE,
4115 DRGN_SYMBOL_KIND_COMMON,
4116 DRGN_SYMBOL_KIND_TLS,
4117 DRGN_SYMBOL_KIND_IFUNC = 10, /* STT_GNU_IFUNC */
4118 } __attribute__((__packed__));
4119
4120 /** Describes the lifetime of an object provided to drgn */
4121 enum drgn_lifetime {
4122 /**
4123 * DRGN_LIFETIME_STATIC: the object is guaranteed to outlive the
4124 * drgn_program itself. drgn will not free or copy the object.
4125 */
4126 DRGN_LIFETIME_STATIC,
4127 /**
4128 * DRGN_LIFETIME_EXTERNAL: the object is externally managed. It will
4129 * live as long as the object it is associated with, but may be freed
4130 * after. drgn will never free the object. If drgn must copy a data
4131 * structure, the object will be duplicated, and drgn will own the new
4132 * object.
4133 */
4134 DRGN_LIFETIME_EXTERNAL,
4135 /**
4136 * DRGN_LIFETIME_OWNED: the object lifetime is managed by drgn. It
4137 * should be freed when the containing object is freed. If the
4138 * containing object is copied, it must also be copied.
4139 */
4140 DRGN_LIFETIME_OWNED,
4141 } __attribute__((__packed__));
4142
4143 /**
4144 * Create a new @ref drgn_symbol with the given values
4145 *
4146 * All parameters should be self-explanatory, except for @a name_lifetime.
4147 * Clients can use this to describe how drgn should treat the string @a name.
4148 * Strings with lifetime @c STATIC will never be copied or freed. Strings with
4149 * lifetime @c OWNED will always be copied or and freed with the symbol. Strings
4150 * with lifetime EXTERNAL will not be freed, but if the Symbol is copied, they
4151 * will be copied.
4152 */
4153 struct drgn_error *
4154 drgn_symbol_create(const char *name, uint64_t address, uint64_t size,
4155 enum drgn_symbol_binding binding, enum drgn_symbol_kind kind,
4156 enum drgn_lifetime name_lifetime, struct drgn_symbol **ret);
4157
4158 /** Destroy a @ref drgn_symbol. */
4159 void drgn_symbol_destroy(struct drgn_symbol *sym);
4160
4161 /**
4162 * Destroy each @ref drgn_symbol in @syms, and free the array.
4163 *
4164 * This will ignore any @c NULL entry in the array, allowing you to take
4165 * ownership of any symbol from the array prior to freeing the rest. For each
4166 * symbol you take ownership of, you must free it with @ref
4167 * drgn_symbol_destroy().
4168 */
4169 void drgn_symbols_destroy(struct drgn_symbol **syms, size_t count);
4170
4171 /**
4172 * Get the name of a @ref drgn_symbol.
4173 *
4174 * The returned string is valid until @p sym is destroyed. It should not be
4175 * freed.
4176 */
4177 const char *drgn_symbol_name(struct drgn_symbol *sym);
4178
4179 /** Get the start address of a @ref drgn_symbol. */
4180 uint64_t drgn_symbol_address(struct drgn_symbol *sym);
4181
4182 /** Get the size in bytes of a @ref drgn_symbol. */
4183 uint64_t drgn_symbol_size(struct drgn_symbol *sym);
4184
4185 /** Get the binding of a @ref drgn_symbol. */
4186 enum drgn_symbol_binding drgn_symbol_binding(struct drgn_symbol *sym);
4187
4188 /** Get the kind of a @ref drgn_symbol. */
4189 enum drgn_symbol_kind drgn_symbol_kind(struct drgn_symbol *sym);
4190
4191 /** Return whether two symbols are identical. */
4192 bool drgn_symbol_eq(struct drgn_symbol *a, struct drgn_symbol *b);
4193
4194 /** @} */
4195
4196 /**
4197 * @defgroup StackTraces Stack traces
4198 *
4199 * Call stacks and stack frames.
4200 *
4201 * @{
4202 */
4203
4204 struct drgn_stack_trace; // IWYU pragma: export
4205
4206 /** Destroy a @ref drgn_stack_trace. */
4207 void drgn_stack_trace_destroy(struct drgn_stack_trace *trace);
4208
4209 /** Get the @ref drgn_program that a @ref drgn_stack_trace came from. */
4210 struct drgn_program *drgn_stack_trace_program(struct drgn_stack_trace *trace);
4211
4212 /** Get the number of stack frames in a stack trace. */
4213 size_t drgn_stack_trace_num_frames(struct drgn_stack_trace *trace);
4214
4215 /**
4216 * Format a stack trace as a string.
4217 *
4218 * @param[out] ret Returned string. On success, it must be freed with @c free().
4219 * On error, it is not modified.
4220 * @return @c NULL on success, non-@c NULL on error.
4221 */
4222 struct drgn_error *drgn_format_stack_trace(struct drgn_stack_trace *trace,
4223 char **ret);
4224
4225 /** Return whether a stack frame was interrupted (e.g., by a signal). */
4226 bool drgn_stack_frame_interrupted(struct drgn_stack_trace *trace, size_t frame);
4227
4228 /**
4229 * Format a stack frame as a string.
4230 *
4231 * @param[out] ret Returned string. On success, it must be freed with @c free().
4232 * On error, it is not modified.
4233 * @return @c NULL on success, non-@c NULL on error.
4234 */
4235 struct drgn_error *drgn_format_stack_frame(struct drgn_stack_trace *trace,
4236 size_t frame, char **ret);
4237
4238 /**
4239 * Format the source code location of a stack frame as a string.
4240 *
4241 * @param[out] ret Returned string. On success, it must be freed with @c free().
4242 * On error, it is not modified.
4243 * @return @c NULL on success, non-@c NULL on error.
4244 */
4245 struct drgn_error *
4246 drgn_format_stack_frame_source(struct drgn_stack_trace *trace, size_t frame,
4247 char **ret);
4248
4249 /**
4250 * Get the best available name for a stack frame.
4251 *
4252 * @param[out] ret Returned name. On success, it must be freed with @c free().
4253 * On error, it is not modified.
4254 * @return @c NULL on success, non-@c NULL on error.
4255 */
4256 struct drgn_error *drgn_stack_frame_name(struct drgn_stack_trace *trace,
4257 size_t frame, char **ret);
4258
4259 /**
4260 * Get the name of the function at a stack frame.
4261 *
4262 * @return Function name. This is valid until the stack trace is destroyed; it
4263 * should not be freed. @c NULL if the name could not be determined.
4264 */
4265 const char *drgn_stack_frame_function_name(struct drgn_stack_trace *trace,
4266 size_t frame);
4267
4268 /**
4269 * Get the name of the function or symbol at a stack frame's source code
4270 * location.
4271 *
4272 * @param[out] ret Returned name, or @c NULL if not found. On success, it must
4273 * be freed with @c free(). On error, it is not modified.
4274 * @return @c NULL on success, non-@c NULL on error.
4275 */
4276 struct drgn_error *drgn_stack_frame_source_name(struct drgn_stack_trace *trace,
4277 size_t frame, char **ret);
4278
4279 /** Return whether a stack frame is for an inlined call. */
4280 bool drgn_stack_frame_is_inline(struct drgn_stack_trace *trace, size_t frame);
4281
4282 /**
4283 * Get the source code location of a stack frame.
4284 *
4285 * @param[out] line_ret Returned line number. Returned as 0 if unknown. May be
4286 * @c NULL if not needed.
4287 * @param[out] column_ret Returned column number. Returned as 0 if unknown. May
4288 * be @c NULL if not needed.
4289 * @return Filename. This is valid until the stack trace is destroyed; it should
4290 * not be freed. @c NULL if the location could not be determined (in which case
4291 * `*line_ret` and `*column_ret` are not modified).
4292 */
4293 const char *drgn_stack_frame_source(struct drgn_stack_trace *trace,
4294 size_t frame, int *line_ret,
4295 int *column_ret);
4296
4297 /**
4298 * Get the program counter at a stack frame.
4299 *
4300 * @param[out] ret Returned program counter.
4301 * @return @c true if the program counter is known, @c false if it is not.
4302 */
4303 bool drgn_stack_frame_pc(struct drgn_stack_trace *trace, size_t frame,
4304 uint64_t *ret);
4305
4306 /**
4307 * Get the stack pointer at a stack frame.
4308 *
4309 * @param[out] ret Returned stack pointer.
4310 * @return @c true if the stack pointer is known, @c false if it is not.
4311 */
4312 bool drgn_stack_frame_sp(struct drgn_stack_trace *trace, size_t frame,
4313 uint64_t *ret);
4314
4315 /**
4316 * Get the function symbol at a stack frame.
4317 *
4318 * @param[out] ret Returned symbol. On success, it should be freed with @ref
4319 * drgn_symbol_destroy(). On error, its contents are undefined.
4320 * @return @c NULL on success, non-@c NULL on error.
4321 */
4322 struct drgn_error *drgn_stack_frame_symbol(struct drgn_stack_trace *trace,
4323 size_t frame,
4324 struct drgn_symbol **ret);
4325
4326 /**
4327 * Get the names of local objects in the scope of this frame.
4328 *
4329 * The array of names must be freed with @ref drgn_stack_frame_locals_destroy().
4330 *
4331 * @param[out] names_ret Returned array of names. On success, must be freed with
4332 * @ref drgn_stack_frame_locals_destroy().
4333 * @param[out] count_ret Returned number of names in @p names_ret.
4334 * @return @c NULL on success, non-@c NULL on error
4335 */
4336 struct drgn_error *
4337 drgn_stack_frame_locals(struct drgn_stack_trace *trace, size_t frame,
4338 const char ***names_ret, size_t *count_ret);
4339
4340 /**
4341 * Free an array of names returned by @ref drgn_stack_frame_locals().
4342 *
4343 * The individual names from this array are invalid once this function is
4344 * called. Any string which will be used later should be copied.
4345 *
4346 * @param names Array of names returned by @ref drgn_stack_frame_locals().
4347 * @param count Count returned by @ref drgn_stack_frame_locals().
4348 */
4349 void drgn_stack_frame_locals_destroy(const char **names, size_t count);
4350
4351 /**
4352 * Find an object in the scope of a stack frame.
4353 *
4354 * @param[in] name Object name.
4355 * @param[out] ret Returned object. This must have already been initialized with
4356 * @ref drgn_object_init().
4357 * @return @c NULL on success, non-@c NULL on error.
4358 */
4359 struct drgn_error *
4360 drgn_stack_frame_find_object(struct drgn_stack_trace *trace, size_t frame,
4361 const char *name, struct drgn_object *ret);
4362
4363 /**
4364 * Get the value of a register in a stack frame.
4365 *
4366 * @param[in] reg Register to get. Must be from the platform of the program that
4367 * the trace was taken from.
4368 * @param[out] ret Returned register value.
4369 * @return @c true on success, @c false if the value is not known or the
4370 * register is too large to return in a @c uint64_t.
4371 */
4372 bool drgn_stack_frame_register(struct drgn_stack_trace *trace, size_t frame,
4373 const struct drgn_register *reg, uint64_t *ret);
4374
4375 /**
4376 * Get a stack trace for the thread with the given thread ID.
4377 *
4378 * @param[out] ret Returned stack trace. On success, it should be freed with
4379 * @ref drgn_stack_trace_destroy(). On error, its contents are undefined.
4380 * @return @c NULL on success, non-@c NULL on error.
4381 */
4382 struct drgn_error *drgn_program_stack_trace(struct drgn_program *prog,
4383 uint32_t tid,
4384 struct drgn_stack_trace **ret);
4385
4386 /**
4387 * Get a stack trace with the supplied list of program counters.
4388 *
4389 * @param[out] ret Returned stack trace. On success, it should be freed with
4390 * @ref drgn_stack_trace_destroy(). On error, its contents are undefined.
4391 * @return @c NULL on success, non-@c NULL on error.
4392 */
4393 struct drgn_error *
4394 drgn_program_stack_trace_from_pcs(struct drgn_program *prog,
4395 const uint64_t *pcs,
4396 size_t pcs_size,
4397 struct drgn_stack_trace **ret);
4398
4399 /**
4400 * Get a stack trace for the thread represented by @p obj.
4401 *
4402 * @sa drgn_program_stack_trace().
4403 */
4404 struct drgn_error *drgn_object_stack_trace(const struct drgn_object *obj,
4405 struct drgn_stack_trace **ret);
4406
4407 /** @} */
4408
4409 /**
4410 * @defgroup SourceLocations Source locations
4411 *
4412 * Source code locations.
4413 *
4414 * @{
4415 */
4416
4417 /**
4418 * @struct drgn_source_location_list
4419 *
4420 * List of source code locations.
4421 */
4422 struct drgn_source_location_list; // IWYU pragma: export
4423
4424 /** Destroy a @ref drgn_source_location_list. */
4425 void drgn_source_location_list_destroy(struct drgn_source_location_list *locs);
4426
4427 /**
4428 * Get the @ref drgn_program that a @ref drgn_source_location_list came from.
4429 */
4430 struct drgn_program *
4431 drgn_source_location_list_program(struct drgn_source_location_list *locs);
4432
4433 /** Get the number of locations in a source location list. */
4434 size_t drgn_source_location_list_length(struct drgn_source_location_list *locs);
4435
4436 /**
4437 * Format a source location list as a string.
4438 *
4439 * @param[out] ret Returned string. On success, it must be freed with @c free().
4440 * On error, it is not modified.
4441 * @return @c NULL on success, non-@c NULL on error.
4442 */
4443 struct drgn_error *
4444 drgn_format_source_location_list(struct drgn_source_location_list *locs,
4445 char **ret);
4446
4447 /**
4448 * Format a single location in a source location list as a string.
4449 *
4450 * @param[out] ret Returned string. On success, it must be freed with @c free().
4451 * On error, it is not modified.
4452 * @return @c NULL on success, non-@c NULL on error.
4453 */
4454 struct drgn_error *
4455 drgn_format_source_location_list_at(struct drgn_source_location_list *locs,
4456 size_t i, char **ret);
4457
4458 /**
4459 * Get the filename, line number, and column number at a single location in a
4460 * source location list.
4461 *
4462 * @param[out] line_ret Returned line number. Returned as 0 if unknown. May be
4463 * @c NULL if not needed.
4464 * @param[out] column_ret Returned column number. Returned as 0 if unknown. May
4465 * be @c NULL if not needed.
4466 * @return Filename. This is valid until the source location list is destroyed;
4467 * it should not be freed. @c NULL if the location could not be determined (in
4468 * which case `*line_ret` and `*column_ret` are not modified).
4469 */
4470 const char *
4471 drgn_source_location_list_source_at(struct drgn_source_location_list *locs,
4472 size_t i, int *line_ret, int *column_ret);
4473
4474 /**
4475 * Get the name of the function or symbol at a single location in a source
4476 * location list.
4477 *
4478 * @param[out] ret Returned name, or @c NULL if not found. On success, it must
4479 * be freed with @c free(). On error, it is not modified.
4480 * @return @c NULL on success, non-@c NULL on error.
4481 */
4482 struct drgn_error *
4483 drgn_source_location_list_name_at(struct drgn_source_location_list *locs,
4484 size_t i, char **ret);
4485
4486 /**
4487 * Find the source code location containing a code address.
4488 *
4489 * @param[in] address Code address.
4490 * @param[out] ret Returned source location list.
4491 * @return @c NULL on success, non-@c NULL on error.
4492 */
4493 struct drgn_error *
4494 drgn_program_source_location(struct drgn_program *prog, uint64_t address,
4495 struct drgn_source_location_list **ret);
4496
4497 /**
4498 * Find the source code location containing a code address given as a symbol
4499 * name or hexadecimal address, optionally followed by a `+` character and a
4500 * decimal or hexadecimal offset
4501 *
4502 * @param[in] address Code address.
4503 * @param[out] ret Returned source location list.
4504 * @return @c NULL on success, non-@c NULL on error.
4505 */
4506 struct drgn_error *
4507 drgn_program_addr2line(struct drgn_program *prog, const char *address,
4508 struct drgn_source_location_list **ret);
4509
4510 /** @} */
4511
4512 /**
4513 * @defgroup Threads Threads
4514 *
4515 * Threads in a program.
4516 *
4517 * @{
4518 */
4519
4520 /**
4521 * @struct drgn_thread
4522 *
4523 * A thread in a program.
4524 */
4525 struct drgn_thread;
4526
4527 /**
4528 * Create a copy of a @ref drgn_thread.
4529 *
4530 * @param[in] thread Thread to copy.
4531 * @param[out] ret Returned copy. On success, must be destroyed with @ref
4532 * drgn_thread_destroy().
4533 * @return @c NULL on success, non-@c NULL on error.
4534 */
4535 struct drgn_error *drgn_thread_dup(const struct drgn_thread *thread,
4536 struct drgn_thread **ret);
4537
4538 /** Free a @ref drgn_thread. */
4539 void drgn_thread_destroy(struct drgn_thread *thread);
4540
4541 /**
4542 * @struct drgn_thread_iterator
4543 *
4544 * An iterator over all the threads in a program.
4545 */
4546 struct drgn_thread_iterator;
4547
4548 /**
4549 * Get an iterator over all of the threads in the program.
4550 *
4551 * @param[out] ret Returned iterator, which can be advanced with @ref
4552 * drgn_thread_iterator_next, and must be destroyed with @ref
4553 * drgn_thread_iterator_destroy.
4554 * @return @c NULL on success, non-@c NULL on error.
4555 */
4556 struct drgn_error *
4557 drgn_thread_iterator_create(struct drgn_program *prog,
4558 struct drgn_thread_iterator **ret);
4559
4560 /** Free a @ref drgn_thread_iterator. */
4561 void drgn_thread_iterator_destroy(struct drgn_thread_iterator *it);
4562
4563 /**
4564 * Get the next thread from a @ref drgn_thread_iterator.
4565 *
4566 * @param[out] ret Borrowed thread handle, or @c NULL if there are no more
4567 * threads. This is valid until until the next call to @ref
4568 * drgn_thread_iterator_next() with the same @p it, or until @p it is destroyed.
4569 * It may be copied with @ref drgn_thread_dup() if it is needed for longer. This
4570 * must NOT be destroyed with @ref drgn_thread_destroy().
4571 * @return @c NULL on success, non-@c NULL on error.
4572 */
4573 struct drgn_error *drgn_thread_iterator_next(struct drgn_thread_iterator *it,
4574 struct drgn_thread **ret);
4575
4576 /**
4577 * Get the thread with the given thread ID.
4578 *
4579 * @param[in] tid Thread ID.
4580 * @param[out] ret New thread handle, or @c NULL if not found. On success, must
4581 * be destroyed with @ref drgn_thread_destroy().
4582 * @return @c NULL on success, non-@c NULL on error.
4583 */
4584 struct drgn_error *drgn_program_find_thread(struct drgn_program *prog,
4585 uint32_t tid,
4586 struct drgn_thread **ret);
4587
4588 /**
4589 * Get the main program thread.
4590 *
4591 * @param[out] ret Borrowed thread handle. This is valid for the lifetime of @p
4592 * prog. This must NOT be destroyed with @ref drgn_thread_destroy().
4593 * @return @c NULL on success, non-@c NULL on error.
4594 */
4595 struct drgn_error *drgn_program_main_thread(struct drgn_program *prog,
4596 struct drgn_thread **ret);
4597
4598 /**
4599 * Get the thread that caused the program to crash.
4600 *
4601 * @param[out] ret Borrowed thread handle. This is valid for the lifetime of @p
4602 * prog. This must NOT be destroyed with @ref drgn_thread_destroy().
4603 * @return @c NULL on success, non-@c NULL on error.
4604 */
4605 struct drgn_error *drgn_program_crashed_thread(struct drgn_program *prog,
4606 struct drgn_thread **ret);
4607
4608 /**
4609 * Get the object for the given thread. This is currently only defined for the
4610 * Linux kernel.
4611 *
4612 * @param[out] ret Returned object. This must not be modified and is valid for
4613 * the lifetime of @p thread. It can be copied with @ref drgn_object_copy() if
4614 * it is needed for longer.
4615 * @return @c NULL on success, non-@c NULL on error.
4616 */
4617 struct drgn_error *drgn_thread_object(struct drgn_thread *thread,
4618 const struct drgn_object **ret);
4619
4620 /**
4621 * Get a stack trace for the thread represented by @p thread.
4622 *
4623 * @sa drgn_program_stack_trace().
4624 */
4625 struct drgn_error *drgn_thread_stack_trace(struct drgn_thread *thread,
4626 struct drgn_stack_trace **ret);
4627
4628 /**
4629 * Get name for the thread represented by @p thread.
4630 *
4631 * @param[out] ret Returned thread name, or @c NULL if not found. On success, it
4632 * should be freed with free(). On error, it is not modified.
4633 * @return @c NULL on success, non-@c NULL on error.
4634 */
4635 struct drgn_error *drgn_thread_name(struct drgn_thread *thread, char **ret);
4636
4637 /** @} */
4638
4639 #endif /* DRGN_H */