1 /* Public API to libctf.
2 Copyright (C) 2019 Free Software Foundation, Inc.
4 This file is part of libctf.
6 libctf is free software; you can redistribute it and/or modify it under
7 the terms of the GNU General Public License as published by the Free
8 Software Foundation; either version 3, or (at your option) any later
11 This program is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
14 See the GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with this program; see the file COPYING. If not see
18 <http://www.gnu.org/licenses/>. */
20 /* This header file defines the interfaces available from the CTF debugger
21 library, libctf. This API can be used by a debugger to operate on data in
22 the Compact ANSI-C Type Format (CTF). */
27 #include <sys/param.h>
28 #include <sys/types.h>
37 /* Clients can open one or more CTF containers and obtain a pointer to an
38 opaque ctf_file_t. Types are identified by an opaque ctf_id_t token.
39 They can also open or create read-only archives of CTF containers in a
42 These opaque definitions allow libctf to evolve without breaking clients. */
44 typedef struct ctf_file ctf_file_t
;
45 typedef struct ctf_archive_internal ctf_archive_t
;
46 typedef unsigned long ctf_id_t
;
48 /* This opaque definition allows libctf to accept BFD data structures without
49 importing all the BFD noise into users' namespaces. */
53 /* If the debugger needs to provide the CTF library with a set of raw buffers
54 for use as the CTF data, symbol table, and string table, it can do so by
55 filling in ctf_sect_t structures and passing them to ctf_bufopen().
57 The contents of this structure must always be in native endianness (no
58 byteswapping is performed). */
60 typedef struct ctf_sect
62 const char *cts_name
; /* Section name (if any). */
63 const void *cts_data
; /* Pointer to section data. */
64 size_t cts_size
; /* Size of data in bytes. */
65 size_t cts_entsize
; /* Size of each section entry (symtab only). */
68 /* A minimal symbol extracted from a linker's internal symbol table
71 typedef struct ctf_link_sym
73 /* The st_name will not be accessed outside the call to
74 ctf_link_shuffle_syms(). */
82 /* Indication of how to share types when linking. */
84 /* Share all types thare are not in conflict. The default. */
85 #define CTF_LINK_SHARE_UNCONFLICTED 0x0
87 /* Share only types that are used by multiple inputs. Not implemented yet. */
88 #define CTF_LINK_SHARE_DUPLICATED 0x1
90 /* Symbolic names for CTF sections. */
92 typedef enum ctf_sect_names
103 /* Encoding information for integers, floating-point values, and certain other
104 intrinsics can be obtained by calling ctf_type_encoding(), below. The flags
105 field will contain values appropriate for the type defined in <ctf.h>. */
107 typedef struct ctf_encoding
109 uint32_t cte_format
; /* Data format (CTF_INT_* or CTF_FP_* flags). */
110 uint32_t cte_offset
; /* Offset of value in bits. */
111 uint32_t cte_bits
; /* Size of storage in bits. */
114 typedef struct ctf_membinfo
116 ctf_id_t ctm_type
; /* Type of struct or union member. */
117 unsigned long ctm_offset
; /* Offset of member in bits. */
120 typedef struct ctf_arinfo
122 ctf_id_t ctr_contents
; /* Type of array contents. */
123 ctf_id_t ctr_index
; /* Type of array index. */
124 uint32_t ctr_nelems
; /* Number of elements. */
127 typedef struct ctf_funcinfo
129 ctf_id_t ctc_return
; /* Function return type. */
130 uint32_t ctc_argc
; /* Number of typed arguments to function. */
131 uint32_t ctc_flags
; /* Function attributes (see below). */
134 typedef struct ctf_lblinfo
136 ctf_id_t ctb_type
; /* Last type associated with the label. */
139 typedef struct ctf_snapshot_id
141 unsigned long dtd_id
; /* Highest DTD ID at time of snapshot. */
142 unsigned long snapshot_id
; /* Snapshot id at time of snapshot. */
145 #define CTF_FUNC_VARARG 0x1 /* Function arguments end with varargs. */
147 /* Functions that return a ctf_id_t use the following value to indicate failure.
148 ctf_errno() can be used to obtain an error code. Functions that return
149 a straight integral -1 also use ctf_errno(). */
150 #define CTF_ERR ((ctf_id_t) -1L)
152 #define ECTF_BASE 1000 /* Base value for libctf errnos. */
157 ECTF_FMT
= ECTF_BASE
, /* File is not in CTF or ELF format. */
158 ECTF_BFDERR
, /* BFD error. */
159 ECTF_CTFVERS
, /* CTF version is more recent than libctf. */
160 ECTF_BFD_AMBIGUOUS
, /* Ambiguous BFD target. */
161 ECTF_SYMTAB
, /* Symbol table uses invalid entry size. */
162 ECTF_SYMBAD
, /* Symbol table data buffer invalid. */
163 ECTF_STRBAD
, /* String table data buffer invalid. */
164 ECTF_CORRUPT
, /* File data corruption detected. */
165 ECTF_NOCTFDATA
, /* ELF file does not contain CTF data. */
166 ECTF_NOCTFBUF
, /* Buffer does not contain CTF data. */
167 ECTF_NOSYMTAB
, /* Symbol table data is not available. */
168 ECTF_NOPARENT
, /* Parent CTF container is not available. */
169 ECTF_DMODEL
, /* Data model mismatch. */
170 ECTF_LINKADDEDLATE
, /* File added to link too late. */
171 ECTF_ZALLOC
, /* Failed to allocate (de)compression buffer. */
172 ECTF_DECOMPRESS
, /* Failed to decompress CTF data. */
173 ECTF_STRTAB
, /* String table for this string is missing. */
174 ECTF_BADNAME
, /* String offset is corrupt w.r.t. strtab. */
175 ECTF_BADID
, /* Invalid type ID number. */
176 ECTF_NOTSOU
, /* Type is not a struct or union. */
177 ECTF_NOTENUM
, /* Type is not an enum. */
178 ECTF_NOTSUE
, /* Type is not a struct, union, or enum. */
179 ECTF_NOTINTFP
, /* Type is not an integer, float, or enum. */
180 ECTF_NOTARRAY
, /* Type is not an array. */
181 ECTF_NOTREF
, /* Type does not reference another type. */
182 ECTF_NAMELEN
, /* Buffer is too small to hold type name. */
183 ECTF_NOTYPE
, /* No type found corresponding to name. */
184 ECTF_SYNTAX
, /* Syntax error in type name. */
185 ECTF_NOTFUNC
, /* Symbol entry or type is not a function. */
186 ECTF_NOFUNCDAT
, /* No func info available for function. */
187 ECTF_NOTDATA
, /* Symtab entry does not refer to a data obj. */
188 ECTF_NOTYPEDAT
, /* No type info available for object. */
189 ECTF_NOLABEL
, /* No label found corresponding to name. */
190 ECTF_NOLABELDATA
, /* File does not contain any labels. */
191 ECTF_NOTSUP
, /* Feature not supported. */
192 ECTF_NOENUMNAM
, /* Enum element name not found. */
193 ECTF_NOMEMBNAM
, /* Member name not found. */
194 ECTF_RDONLY
, /* CTF container is read-only. */
195 ECTF_DTFULL
, /* CTF type is full (no more members allowed). */
196 ECTF_FULL
, /* CTF container is full. */
197 ECTF_DUPLICATE
, /* Duplicate member or variable name. */
198 ECTF_CONFLICT
, /* Conflicting type definition present. */
199 ECTF_OVERROLLBACK
, /* Attempt to roll back past a ctf_update. */
200 ECTF_COMPRESS
, /* Failed to compress CTF data. */
201 ECTF_ARCREATE
, /* Error creating CTF archive. */
202 ECTF_ARNNAME
, /* Name not found in CTF archive. */
203 ECTF_SLICEOVERFLOW
, /* Overflow of type bitness or offset in slice. */
204 ECTF_DUMPSECTUNKNOWN
, /* Unknown section number in dump. */
205 ECTF_DUMPSECTCHANGED
, /* Section changed in middle of dump. */
206 ECTF_NOTYET
/* Feature not yet implemented. */
209 /* The CTF data model is inferred to be the caller's data model or the data
210 model of the given object, unless ctf_setmodel() is explicitly called. */
211 #define CTF_MODEL_ILP32 1 /* Object data model is ILP32. */
212 #define CTF_MODEL_LP64 2 /* Object data model is LP64. */
214 # define CTF_MODEL_NATIVE CTF_MODEL_LP64
216 # define CTF_MODEL_NATIVE CTF_MODEL_ILP32
219 /* Dynamic CTF containers can be created using ctf_create(). The ctf_add_*
220 routines can be used to add new definitions to the dynamic container.
221 New types are labeled as root or non-root to determine whether they are
222 visible at the top-level program scope when subsequently doing a lookup. */
224 #define CTF_ADD_NONROOT 0 /* Type only visible in nested scope. */
225 #define CTF_ADD_ROOT 1 /* Type visible at top-level scope. */
227 /* These typedefs are used to define the signature for callback functions
228 that can be used with the iteration and visit functions below. */
230 typedef int ctf_visit_f (const char *name
, ctf_id_t type
, unsigned long offset
,
231 int depth
, void *arg
);
232 typedef int ctf_member_f (const char *name
, ctf_id_t membtype
,
233 unsigned long offset
, void *arg
);
234 typedef int ctf_enum_f (const char *name
, int val
, void *arg
);
235 typedef int ctf_variable_f (const char *name
, ctf_id_t type
, void *arg
);
236 typedef int ctf_type_f (ctf_id_t type
, void *arg
);
237 typedef int ctf_type_all_f (ctf_id_t type
, int flag
, void *arg
);
238 typedef int ctf_label_f (const char *name
, const ctf_lblinfo_t
*info
,
240 typedef int ctf_archive_member_f (ctf_file_t
*fp
, const char *name
, void *arg
);
241 typedef int ctf_archive_raw_member_f (const char *name
, const void *content
,
242 size_t len
, void *arg
);
243 typedef char *ctf_dump_decorate_f (ctf_sect_names_t sect
,
244 char *line
, void *arg
);
246 typedef struct ctf_dump_state ctf_dump_state_t
;
248 /* Opening. These mostly return an abstraction over both CTF files and CTF
249 archives: so they can be used to open both. CTF files will appear to be an
250 archive with one member named '.ctf'. The low-level functions
251 ctf_simple_open() and ctf_bufopen() return ctf_file_t's directly, and cannot
252 be used on CTF archives. */
254 extern ctf_archive_t
*ctf_bfdopen (struct bfd
*, int *);
255 extern ctf_archive_t
*ctf_bfdopen_ctfsect (struct bfd
*, const ctf_sect_t
*,
257 extern ctf_archive_t
*ctf_fdopen (int fd
, const char *filename
,
258 const char *target
, int *errp
);
259 extern ctf_archive_t
*ctf_open (const char *filename
,
260 const char *target
, int *errp
);
261 extern void ctf_close (ctf_archive_t
*);
262 extern ctf_sect_t
ctf_getdatasect (const ctf_file_t
*);
263 extern ctf_archive_t
*ctf_get_arc (const ctf_file_t
*);
264 extern ctf_archive_t
*ctf_arc_open (const char *, int *);
265 extern void ctf_arc_close (ctf_archive_t
*);
266 extern ctf_file_t
*ctf_arc_open_by_name (const ctf_archive_t
*,
267 const char *, int *);
268 extern ctf_file_t
*ctf_arc_open_by_name_sections (const ctf_archive_t
*,
271 const char *, int *);
273 /* The next functions return or close real CTF files, or write out CTF archives,
274 not opaque containers around either. */
276 extern ctf_file_t
*ctf_simple_open (const char *, size_t, const char *, size_t,
277 size_t, const char *, size_t, int *);
278 extern ctf_file_t
*ctf_bufopen (const ctf_sect_t
*, const ctf_sect_t
*,
279 const ctf_sect_t
*, int *);
280 extern void ctf_file_close (ctf_file_t
*);
282 extern int ctf_arc_write (const char *, ctf_file_t
**, size_t,
283 const char **, size_t);
284 extern int ctf_arc_write_fd (int, ctf_file_t
**, size_t, const char **,
287 extern const char *ctf_cuname (ctf_file_t
*);
288 extern void ctf_cuname_set (ctf_file_t
*, const char *);
289 extern ctf_file_t
*ctf_parent_file (ctf_file_t
*);
290 extern const char *ctf_parent_name (ctf_file_t
*);
291 extern void ctf_parent_name_set (ctf_file_t
*, const char *);
292 extern int ctf_type_isparent (ctf_file_t
*, ctf_id_t
);
293 extern int ctf_type_ischild (ctf_file_t
*, ctf_id_t
);
295 extern int ctf_import (ctf_file_t
*, ctf_file_t
*);
296 extern int ctf_setmodel (ctf_file_t
*, int);
297 extern int ctf_getmodel (ctf_file_t
*);
299 extern void ctf_setspecific (ctf_file_t
*, void *);
300 extern void *ctf_getspecific (ctf_file_t
*);
302 extern int ctf_errno (ctf_file_t
*);
303 extern const char *ctf_errmsg (int);
304 extern int ctf_version (int);
306 extern int ctf_func_info (ctf_file_t
*, unsigned long, ctf_funcinfo_t
*);
307 extern int ctf_func_args (ctf_file_t
*, unsigned long, uint32_t, ctf_id_t
*);
308 extern int ctf_func_type_info (ctf_file_t
*, ctf_id_t
, ctf_funcinfo_t
*);
309 extern int ctf_func_type_args (ctf_file_t
*, ctf_id_t
, uint32_t, ctf_id_t
*);
311 extern ctf_id_t
ctf_lookup_by_name (ctf_file_t
*, const char *);
312 extern ctf_id_t
ctf_lookup_by_symbol (ctf_file_t
*, unsigned long);
313 extern ctf_id_t
ctf_lookup_variable (ctf_file_t
*, const char *);
315 extern ctf_id_t
ctf_type_resolve (ctf_file_t
*, ctf_id_t
);
316 extern char *ctf_type_aname (ctf_file_t
*, ctf_id_t
);
317 extern char *ctf_type_aname_raw (ctf_file_t
*, ctf_id_t
);
318 extern ssize_t
ctf_type_lname (ctf_file_t
*, ctf_id_t
, char *, size_t);
319 extern char *ctf_type_name (ctf_file_t
*, ctf_id_t
, char *, size_t);
320 extern ssize_t
ctf_type_size (ctf_file_t
*, ctf_id_t
);
321 extern ssize_t
ctf_type_align (ctf_file_t
*, ctf_id_t
);
322 extern int ctf_type_kind (ctf_file_t
*, ctf_id_t
);
323 extern ctf_id_t
ctf_type_reference (ctf_file_t
*, ctf_id_t
);
324 extern ctf_id_t
ctf_type_pointer (ctf_file_t
*, ctf_id_t
);
325 extern int ctf_type_encoding (ctf_file_t
*, ctf_id_t
, ctf_encoding_t
*);
326 extern int ctf_type_visit (ctf_file_t
*, ctf_id_t
, ctf_visit_f
*, void *);
327 extern int ctf_type_cmp (ctf_file_t
*, ctf_id_t
, ctf_file_t
*, ctf_id_t
);
328 extern int ctf_type_compat (ctf_file_t
*, ctf_id_t
, ctf_file_t
*, ctf_id_t
);
330 extern int ctf_member_info (ctf_file_t
*, ctf_id_t
, const char *,
332 extern int ctf_array_info (ctf_file_t
*, ctf_id_t
, ctf_arinfo_t
*);
334 extern const char *ctf_enum_name (ctf_file_t
*, ctf_id_t
, int);
335 extern int ctf_enum_value (ctf_file_t
*, ctf_id_t
, const char *, int *);
337 extern void ctf_label_set (ctf_file_t
*, const char *);
338 extern const char *ctf_label_get (ctf_file_t
*);
340 extern const char *ctf_label_topmost (ctf_file_t
*);
341 extern int ctf_label_info (ctf_file_t
*, const char *, ctf_lblinfo_t
*);
343 extern int ctf_member_iter (ctf_file_t
*, ctf_id_t
, ctf_member_f
*, void *);
344 extern int ctf_enum_iter (ctf_file_t
*, ctf_id_t
, ctf_enum_f
*, void *);
345 extern int ctf_type_iter (ctf_file_t
*, ctf_type_f
*, void *);
346 extern int ctf_type_iter_all (ctf_file_t
*, ctf_type_all_f
*, void *);
347 extern int ctf_label_iter (ctf_file_t
*, ctf_label_f
*, void *);
348 extern int ctf_variable_iter (ctf_file_t
*, ctf_variable_f
*, void *);
349 extern int ctf_archive_iter (const ctf_archive_t
*, ctf_archive_member_f
*,
351 /* This function alone does not currently operate on CTF files masquerading
352 as archives, and returns -EINVAL: the raw data is no longer available. It is
353 expected to be used only by archiving tools, in any case, which have no need
354 to deal with non-archives at all. */
355 extern int ctf_archive_raw_iter (const ctf_archive_t
*,
356 ctf_archive_raw_member_f
*, void *);
357 extern char *ctf_dump (ctf_file_t
*, ctf_dump_state_t
**state
,
358 ctf_sect_names_t sect
, ctf_dump_decorate_f
*,
361 extern ctf_id_t
ctf_add_array (ctf_file_t
*, uint32_t,
362 const ctf_arinfo_t
*);
363 extern ctf_id_t
ctf_add_const (ctf_file_t
*, uint32_t, ctf_id_t
);
364 extern ctf_id_t
ctf_add_enum_encoded (ctf_file_t
*, uint32_t, const char *,
365 const ctf_encoding_t
*);
366 extern ctf_id_t
ctf_add_enum (ctf_file_t
*, uint32_t, const char *);
367 extern ctf_id_t
ctf_add_float (ctf_file_t
*, uint32_t,
368 const char *, const ctf_encoding_t
*);
369 extern ctf_id_t
ctf_add_forward (ctf_file_t
*, uint32_t, const char *,
371 extern ctf_id_t
ctf_add_function (ctf_file_t
*, uint32_t,
372 const ctf_funcinfo_t
*, const ctf_id_t
*);
373 extern ctf_id_t
ctf_add_integer (ctf_file_t
*, uint32_t, const char *,
374 const ctf_encoding_t
*);
375 extern ctf_id_t
ctf_add_slice (ctf_file_t
*, uint32_t, ctf_id_t
, const ctf_encoding_t
*);
376 extern ctf_id_t
ctf_add_pointer (ctf_file_t
*, uint32_t, ctf_id_t
);
377 extern ctf_id_t
ctf_add_type (ctf_file_t
*, ctf_file_t
*, ctf_id_t
);
378 extern ctf_id_t
ctf_add_typedef (ctf_file_t
*, uint32_t, const char *,
380 extern ctf_id_t
ctf_add_restrict (ctf_file_t
*, uint32_t, ctf_id_t
);
381 extern ctf_id_t
ctf_add_struct (ctf_file_t
*, uint32_t, const char *);
382 extern ctf_id_t
ctf_add_union (ctf_file_t
*, uint32_t, const char *);
383 extern ctf_id_t
ctf_add_struct_sized (ctf_file_t
*, uint32_t, const char *,
385 extern ctf_id_t
ctf_add_union_sized (ctf_file_t
*, uint32_t, const char *,
387 extern ctf_id_t
ctf_add_volatile (ctf_file_t
*, uint32_t, ctf_id_t
);
389 extern int ctf_add_enumerator (ctf_file_t
*, ctf_id_t
, const char *, int);
390 extern int ctf_add_member (ctf_file_t
*, ctf_id_t
, const char *, ctf_id_t
);
391 extern int ctf_add_member_offset (ctf_file_t
*, ctf_id_t
, const char *,
392 ctf_id_t
, unsigned long);
393 extern int ctf_add_member_encoded (ctf_file_t
*, ctf_id_t
, const char *,
394 ctf_id_t
, unsigned long,
395 const ctf_encoding_t
);
397 extern int ctf_add_variable (ctf_file_t
*, const char *, ctf_id_t
);
399 extern int ctf_set_array (ctf_file_t
*, ctf_id_t
, const ctf_arinfo_t
*);
401 extern ctf_file_t
*ctf_create (int *);
402 extern int ctf_update (ctf_file_t
*);
403 extern ctf_snapshot_id_t
ctf_snapshot (ctf_file_t
*);
404 extern int ctf_rollback (ctf_file_t
*, ctf_snapshot_id_t
);
405 extern int ctf_discard (ctf_file_t
*);
406 extern int ctf_write (ctf_file_t
*, int);
407 extern int ctf_gzwrite (ctf_file_t
*fp
, gzFile fd
);
408 extern int ctf_compress_write (ctf_file_t
* fp
, int fd
);
409 extern unsigned char *ctf_write_mem (ctf_file_t
*, size_t *, size_t threshold
);
411 extern int ctf_link_add_ctf (ctf_file_t
*, ctf_archive_t
*, const char *);
412 extern int ctf_link (ctf_file_t
*, int share_mode
);
413 typedef const char *ctf_link_strtab_string_f (uint32_t *offset
, void *arg
);
414 extern int ctf_link_add_strtab (ctf_file_t
*, ctf_link_strtab_string_f
*,
416 typedef ctf_link_sym_t
*ctf_link_iter_symbol_f (ctf_link_sym_t
*dest
,
418 extern int ctf_link_shuffle_syms (ctf_file_t
*, ctf_link_iter_symbol_f
*,
420 extern unsigned char *ctf_link_write (ctf_file_t
*, size_t *size
,
423 extern void ctf_setdebug (int debug
);
424 extern int ctf_getdebug (void);
430 #endif /* _CTF_API_H */