1 /* Public API to libctf. 2 Copyright (C) 2019-2024 Free Software Foundation, Inc. 3 4 This file is part of libctf. 5 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 9 version. 10 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. 15 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/>. */ 19 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). */ 23 24 #ifndef _CTF_API_H 25 #define _CTF_API_H 26 27 #include <sys/types.h> 28 #include <ctf.h> 29 #include <zlib.h> 30 31 #ifdef __cplusplus 32 extern "C" 33 { 34 #endif 35 36 /* Clients can open one or more CTF containers and obtain a pointer to an 37 opaque ctf_dict_t. Types are identified by an opaque ctf_id_t token. 38 They can also open or create read-only archives of CTF containers in a 39 ctf_archive_t. 40 41 These opaque definitions allow libctf to evolve without breaking clients. */ 42 43 typedef struct ctf_dict ctf_dict_t; 44 typedef struct ctf_archive_internal ctf_archive_t; 45 typedef unsigned long ctf_id_t; 46 47 /* This opaque definition allows libctf to accept BFD data structures without 48 importing all the BFD noise into users' namespaces. */ 49 50 struct bfd; 51 52 /* If the debugger needs to provide the CTF library with a set of raw buffers 53 for use as the CTF data, symbol table, and string table, it can do so by 54 filling in ctf_sect_t structures and passing them to ctf_bufopen. 55 56 The contents of this structure must always be in native endianness. At read 57 time, the symbol table endianness is derived from the BFD target (if BFD is 58 in use): if a BFD target is not in use, please call ctf_symsect_endianness or 59 ctf_arc_symsect_endianness. */ 60 61 typedef struct ctf_sect 62 { 63 const char *cts_name; /* Section name (if any). */ 64 const void *cts_data; /* Pointer to section data. */ 65 size_t cts_size; /* Size of data in bytes. */ 66 size_t cts_entsize; /* Size of each section entry (symtab only). */ 67 } ctf_sect_t; 68 69 /* A minimal symbol extracted from a linker's internal symbol table 70 representation. The symbol name can be given either via st_name or via a 71 strtab offset in st_nameidx, which corresponds to one of the string offsets 72 communicated via the ctf_link_add_strtab callback. */ 73 74 typedef struct ctf_link_sym 75 { 76 /* The st_name and st_nameidx will not be accessed outside the call to 77 ctf_link_shuffle_syms. If you set st_nameidx to offset zero, make sure 78 to set st_nameidx_set as well. */ 79 80 const char *st_name; 81 size_t st_nameidx; 82 int st_nameidx_set; 83 uint32_t st_symidx; 84 uint32_t st_shndx; 85 uint32_t st_type; 86 uint32_t st_value; 87 } ctf_link_sym_t; 88 89 /* Flags applying to this specific link. */ 90 91 /* Share all types that are not in conflict. The default. */ 92 #define CTF_LINK_SHARE_UNCONFLICTED 0x0 93 94 /* Share only types that are used by multiple inputs. */ 95 #define CTF_LINK_SHARE_DUPLICATED 0x1 96 97 /* Do a nondeduplicating link, or otherwise deduplicate "less hard", trading off 98 CTF output size for link time. */ 99 #define CTF_LINK_NONDEDUP 0x2 100 101 /* Create empty outputs for all registered CU mappings even if no types are 102 emitted into them. */ 103 #define CTF_LINK_EMPTY_CU_MAPPINGS 0x4 104 105 /* Omit the content of the variables section. */ 106 #define CTF_LINK_OMIT_VARIABLES_SECTION 0x8 107 108 /* If *unset*, filter out entries corresponding to linker-reported symbols 109 from the variable section, and filter out all entries with no linker-reported 110 symbols from the data object and function info sections: if set, do no 111 filtering and leave all entries in place. (This is a negative-sense flag 112 because it is rare to want symbols the linker has not reported as present to 113 stick around in the symtypetab sections nonetheless: relocatable links are 114 the only likely case.) */ 115 #define CTF_LINK_NO_FILTER_REPORTED_SYMS 0x10 116 117 /* Symbolic names for CTF sections. */ 118 119 typedef enum ctf_sect_names 120 { 121 CTF_SECT_HEADER, 122 CTF_SECT_LABEL, 123 CTF_SECT_OBJT, 124 CTF_SECT_OBJTIDX = CTF_SECT_OBJT, 125 CTF_SECT_FUNC, 126 CTF_SECT_FUNCIDX = CTF_SECT_FUNC, 127 CTF_SECT_VAR, 128 CTF_SECT_TYPE, 129 CTF_SECT_STR 130 } ctf_sect_names_t; 131 132 /* Encoding information for integers, floating-point values, and certain other 133 intrinsics can be obtained by calling ctf_type_encoding, below. The flags 134 field will contain values appropriate for the type defined in <ctf.h>. */ 135 136 typedef struct ctf_encoding 137 { 138 uint32_t cte_format; /* Data format (CTF_INT_* or CTF_FP_* flags). */ 139 uint32_t cte_offset; /* Offset of value in bits. */ 140 uint32_t cte_bits; /* Size of storage in bits. */ 141 } ctf_encoding_t; 142 143 typedef struct ctf_membinfo 144 { 145 ctf_id_t ctm_type; /* Type of struct or union member. */ 146 unsigned long ctm_offset; /* Offset of member in bits. */ 147 } ctf_membinfo_t; 148 149 typedef struct ctf_arinfo 150 { 151 ctf_id_t ctr_contents; /* Type of array contents. */ 152 ctf_id_t ctr_index; /* Type of array index. */ 153 uint32_t ctr_nelems; /* Number of elements. */ 154 } ctf_arinfo_t; 155 156 typedef struct ctf_funcinfo 157 { 158 ctf_id_t ctc_return; /* Function return type. */ 159 uint32_t ctc_argc; /* Number of typed arguments to function. */ 160 uint32_t ctc_flags; /* Function attributes (see below). */ 161 } ctf_funcinfo_t; 162 163 typedef struct ctf_lblinfo 164 { 165 ctf_id_t ctb_type; /* Last type associated with the label. */ 166 } ctf_lblinfo_t; 167 168 typedef struct ctf_snapshot_id 169 { 170 unsigned long dtd_id; /* Highest DTD ID at time of snapshot. */ 171 unsigned long snapshot_id; /* Snapshot id at time of snapshot. */ 172 } ctf_snapshot_id_t; 173 174 #define CTF_FUNC_VARARG 0x1 /* Function arguments end with varargs. */ 175 176 /* Functions that return a ctf_id_t use the following value to indicate failure. 177 ctf_errno can be used to obtain an error code. Functions that return 178 a straight integral -1 also use ctf_errno. */ 179 #define CTF_ERR ((ctf_id_t) -1L) 180 181 /* This macro holds information about all the available ctf errors. 182 It is used to form both an enum holding all the error constants, 183 and also the error strings themselves. To use, define _CTF_FIRST 184 and _CTF_ITEM to expand as you like, then mention the macro name. 185 See the enum after this for an example. */ 186 #define _CTF_ERRORS \ 187 _CTF_FIRST (ECTF_FMT, "File is not in CTF or ELF format.") \ 188 _CTF_ITEM (ECTF_BFDERR, "BFD error.") \ 189 _CTF_ITEM (ECTF_CTFVERS, "CTF dict version is too new for libctf.") \ 190 _CTF_ITEM (ECTF_BFD_AMBIGUOUS, "Ambiguous BFD target.") \ 191 _CTF_ITEM (ECTF_SYMTAB, "Symbol table uses invalid entry size.") \ 192 _CTF_ITEM (ECTF_SYMBAD, "Symbol table data buffer is not valid.") \ 193 _CTF_ITEM (ECTF_STRBAD, "String table data buffer is not valid.") \ 194 _CTF_ITEM (ECTF_CORRUPT, "File data structure corruption detected.") \ 195 _CTF_ITEM (ECTF_NOCTFDATA, "File does not contain CTF data.") \ 196 _CTF_ITEM (ECTF_NOCTFBUF, "Buffer does not contain CTF data.") \ 197 _CTF_ITEM (ECTF_NOSYMTAB, "Symbol table information is not available.") \ 198 _CTF_ITEM (ECTF_NOPARENT, "The parent CTF dictionary is unavailable.") \ 199 _CTF_ITEM (ECTF_DMODEL, "Data model mismatch.") \ 200 _CTF_ITEM (ECTF_LINKADDEDLATE, "File added to link too late.") \ 201 _CTF_ITEM (ECTF_ZALLOC, "Failed to allocate (de)compression buffer.") \ 202 _CTF_ITEM (ECTF_DECOMPRESS, "Failed to decompress CTF data.") \ 203 _CTF_ITEM (ECTF_STRTAB, "External string table is not available.") \ 204 _CTF_ITEM (ECTF_BADNAME, "String name offset is corrupt.") \ 205 _CTF_ITEM (ECTF_BADID, "Invalid type identifier.") \ 206 _CTF_ITEM (ECTF_NOTSOU, "Type is not a struct or union.") \ 207 _CTF_ITEM (ECTF_NOTENUM, "Type is not an enum.") \ 208 _CTF_ITEM (ECTF_NOTSUE, "Type is not a struct, union, or enum.") \ 209 _CTF_ITEM (ECTF_NOTINTFP, "Type is not an integer, float, or enum.") \ 210 _CTF_ITEM (ECTF_NOTARRAY, "Type is not an array.") \ 211 _CTF_ITEM (ECTF_NOTREF, "Type does not reference another type.") \ 212 _CTF_ITEM (ECTF_NAMELEN, "Buffer is too small to hold type name.") \ 213 _CTF_ITEM (ECTF_NOTYPE, "No type found corresponding to name.") \ 214 _CTF_ITEM (ECTF_SYNTAX, "Syntax error in type name.") \ 215 _CTF_ITEM (ECTF_NOTFUNC, "Symbol table entry or type is not a function.") \ 216 _CTF_ITEM (ECTF_NOFUNCDAT, "No function information available for function.") \ 217 _CTF_ITEM (ECTF_NOTDATA, "Symbol table entry does not refer to a data object.") \ 218 _CTF_ITEM (ECTF_NOTYPEDAT, "No type information available for symbol.") \ 219 _CTF_ITEM (ECTF_NOLABEL, "No label found corresponding to name.") \ 220 _CTF_ITEM (ECTF_NOLABELDATA, "File does not contain any labels.") \ 221 _CTF_ITEM (ECTF_NOTSUP, "Feature not supported.") \ 222 _CTF_ITEM (ECTF_NOENUMNAM, "Enum element name not found.") \ 223 _CTF_ITEM (ECTF_NOMEMBNAM, "Member name not found.") \ 224 _CTF_ITEM (ECTF_RDONLY, "CTF container is read-only.") \ 225 _CTF_ITEM (ECTF_DTFULL, "CTF type is full (no more members allowed).") \ 226 _CTF_ITEM (ECTF_FULL, "CTF container is full.") \ 227 _CTF_ITEM (ECTF_DUPLICATE, "Duplicate member or variable name.") \ 228 _CTF_ITEM (ECTF_CONFLICT, "Conflicting type is already defined.") \ 229 _CTF_ITEM (ECTF_OVERROLLBACK, "Attempt to roll back past a ctf_update.") \ 230 _CTF_ITEM (ECTF_COMPRESS, "Failed to compress CTF data.") \ 231 _CTF_ITEM (ECTF_ARCREATE, "Error creating CTF archive.") \ 232 _CTF_ITEM (ECTF_ARNNAME, "Name not found in CTF archive.") \ 233 _CTF_ITEM (ECTF_SLICEOVERFLOW, "Overflow of type bitness or offset in slice.") \ 234 _CTF_ITEM (ECTF_DUMPSECTUNKNOWN, "Unknown section number in dump.") \ 235 _CTF_ITEM (ECTF_DUMPSECTCHANGED, "Section changed in middle of dump.") \ 236 _CTF_ITEM (ECTF_NOTYET, "Feature not yet implemented.") \ 237 _CTF_ITEM (ECTF_INTERNAL, "Internal error: assertion failure.") \ 238 _CTF_ITEM (ECTF_NONREPRESENTABLE, "Type not representable in CTF.") \ 239 _CTF_ITEM (ECTF_NEXT_END, "End of iteration.") \ 240 _CTF_ITEM (ECTF_NEXT_WRONGFUN, "Wrong iteration function called.") \ 241 _CTF_ITEM (ECTF_NEXT_WRONGFP, "Iteration entity changed in mid-iterate.") \ 242 _CTF_ITEM (ECTF_FLAGS, "CTF header contains flags unknown to libctf.") \ 243 _CTF_ITEM (ECTF_NEEDSBFD, "This feature needs a libctf with BFD support.") \ 244 _CTF_ITEM (ECTF_INCOMPLETE, "Type is not a complete type.") \ 245 _CTF_ITEM (ECTF_NONAME, "Type name must not be empty.") 246 247 #define ECTF_BASE 1000 /* Base value for libctf errnos. */ 248 249 enum 250 { 251 #define _CTF_FIRST(NAME, STR) NAME = ECTF_BASE 252 #define _CTF_ITEM(NAME, STR) , NAME 253 _CTF_ERRORS 254 #undef _CTF_ITEM 255 #undef _CTF_FIRST 256 }; 257 258 #define ECTF_NERR (ECTF_NONAME - ECTF_BASE + 1) /* Count of CTF errors. */ 259 260 /* The CTF data model is inferred to be the caller's data model or the data 261 model of the given object, unless ctf_setmodel is explicitly called. */ 262 #define CTF_MODEL_ILP32 1 /* Object data model is ILP32. */ 263 #define CTF_MODEL_LP64 2 /* Object data model is LP64. */ 264 #ifdef _LP64 265 # define CTF_MODEL_NATIVE CTF_MODEL_LP64 266 #else 267 # define CTF_MODEL_NATIVE CTF_MODEL_ILP32 268 #endif 269 270 /* Dynamic CTF containers can be created using ctf_create. The ctf_add_* 271 routines can be used to add new definitions to the dynamic container. 272 New types are labeled as root or non-root to determine whether they are 273 visible at the top-level program scope when subsequently doing a lookup. */ 274 275 #define CTF_ADD_NONROOT 0 /* Type only visible in nested scope. */ 276 #define CTF_ADD_ROOT 1 /* Type visible at top-level scope. */ 277 278 /* Flags for ctf_member_next. */ 279 280 #define CTF_MN_RECURSE 0x1 /* Recurse into unnamed members. */ 281 282 /* These typedefs are used to define the signature for callback functions that 283 can be used with the iteration and visit functions below. There is also a 284 family of iteration functions that do not require callbacks. */ 285 286 typedef int ctf_visit_f (const char *name, ctf_id_t type, unsigned long offset, 287 int depth, void *arg); 288 typedef int ctf_member_f (const char *name, ctf_id_t membtype, 289 unsigned long offset, void *arg); 290 typedef int ctf_enum_f (const char *name, int val, void *arg); 291 typedef int ctf_variable_f (const char *name, ctf_id_t type, void *arg); 292 typedef int ctf_type_f (ctf_id_t type, void *arg); 293 typedef int ctf_type_all_f (ctf_id_t type, int flag, void *arg); 294 typedef int ctf_label_f (const char *name, const ctf_lblinfo_t *info, 295 void *arg); 296 typedef int ctf_archive_member_f (ctf_dict_t *fp, const char *name, void *arg); 297 typedef int ctf_archive_raw_member_f (const char *name, const void *content, 298 size_t len, void *arg); 299 typedef char *ctf_dump_decorate_f (ctf_sect_names_t sect, 300 char *line, void *arg); 301 302 typedef struct ctf_dump_state ctf_dump_state_t; 303 304 /* Iteration state for the _next functions, and allocators/copiers/freers for 305 it. (None of these are needed for the simple case of iterating to the end: 306 the _next functions allocate and free the iterators for you.) 307 308 The _next iterators all work in similar ways: they take things to query (a 309 dict, a name, a type ID, something like that), then a ctf_next_t iterator 310 arg which must be the address of a variable whose value is NULL on first 311 call, and will be set to NULL again once iteration has completed. 312 313 They return something important about the thing being iterated over (often a 314 type ID or a name); on end of iteration they instead return return CTF_ERR, 315 -1, or NULL and set the error ECTF_NEXT_END on the dict. They can often 316 provide more information too: this is done via pointer parameters (e.g. the 317 membname and membtype in ctf_member_next()). These parameters are always 318 optional and can be set to NULL if not needed. 319 320 Errors other than end-of-iteration will return CTF_ERR/-1/NULL and set the 321 error to something other than ECTF_NEXT_END, and *not* destroy the iterator: 322 you should either recover somehow and continue iterating, or call 323 ctf_next_destroy() on it. (You can call ctf_next_destroy() on a NULL 324 iterator, so it's safe to just unconditionally do it after iteration has 325 completed.) */ 326 327 typedef struct ctf_next ctf_next_t; 328 extern ctf_next_t *ctf_next_create (void); 329 extern void ctf_next_destroy (ctf_next_t *); 330 extern ctf_next_t *ctf_next_copy (ctf_next_t *); 331 332 /* Opening. These mostly return an abstraction over both CTF files and CTF 333 archives: so they can be used to open both. CTF files will appear to be an 334 archive with one member named '.ctf'. 335 336 All these functions except for ctf_close use BFD and can open anything BFD 337 can open, hunting down the .ctf section for you, so are not available in the 338 libctf-nobfd flavour of the library. If you want to provide the CTF section 339 yourself, you can do that with ctf_bfdopen_ctfsect. */ 340 341 extern ctf_archive_t *ctf_bfdopen (struct bfd *, int *); 342 extern ctf_archive_t *ctf_bfdopen_ctfsect (struct bfd *, const ctf_sect_t *, 343 int *); 344 extern ctf_archive_t *ctf_fdopen (int fd, const char *filename, 345 const char *target, int *errp); 346 extern ctf_archive_t *ctf_open (const char *filename, 347 const char *target, int *errp); 348 extern void ctf_close (ctf_archive_t *); 349 350 /* Return the data, symbol, or string sections used by a given CTF dict. */ 351 extern ctf_sect_t ctf_getdatasect (const ctf_dict_t *); 352 extern ctf_sect_t ctf_getsymsect (const ctf_dict_t *); 353 extern ctf_sect_t ctf_getstrsect (const ctf_dict_t *); 354 355 /* Set the endianness of the symbol section, which may be different from 356 the endianness of the CTF dict. Done for you by ctf_open and ctf_fdopen, 357 but direct calls to ctf_bufopen etc with symbol sections provided must 358 do so explicitly. */ 359 360 extern void ctf_symsect_endianness (ctf_dict_t *, int little_endian); 361 extern void ctf_arc_symsect_endianness (ctf_archive_t *, int little_endian); 362 363 /* Open CTF archives from files or raw section data, and close them again. 364 Closing may munmap() the data making up the archive, so should not be 365 done until all dicts are finished with and closed themselves. 366 367 Almost all functions that open archives will also open raw CTF dicts, which 368 are treated as if they were archives with only one member. 369 370 Some of these functions take optional raw symtab and strtab section content 371 in the form of ctf_sect_t structures. For CTF in ELF files, the more 372 convenient opening functions above extract these .dynsym and its associated 373 string table (usually .dynsym) whenever the CTF_F_DYNSTR flag is set in the 374 CTF preamble (which it almost always will be for linked objects, but not for 375 .o files). If you use ctf_arc_bufopen and do not specify symbol/string 376 tables, the ctf_*_lookuup_symbol functions will fail with ECTF_NOSYMTAB. 377 378 Like many other convenient opening functions, ctf_arc_open needs BFD and is 379 not available in libctf-nobfd. */ 380 381 extern ctf_archive_t *ctf_arc_open (const char *, int *); 382 extern ctf_archive_t *ctf_arc_bufopen (const ctf_sect_t *ctfsect, 383 const ctf_sect_t *symsect, 384 const ctf_sect_t *strsect, 385 int *); 386 extern void ctf_arc_close (ctf_archive_t *); 387 388 /* Get the archive a given dictionary came from (if any). */ 389 390 extern ctf_archive_t *ctf_get_arc (const ctf_dict_t *); 391 392 /* Return the number of members in an archive. */ 393 394 extern size_t ctf_archive_count (const ctf_archive_t *); 395 396 /* Open a dictionary with a given name, given a CTF archive and 397 optionally symbol and string table sections to accompany it (if the 398 archive was oriiginally opened from an ELF file via ctf_open*, or 399 if string or symbol tables were explicitly passed when the archive 400 was opened, this can be used to override that choice). The dict 401 should be closed with ctf_dict_close() when done. 402 403 (The low-level functions ctf_simple_open and ctf_bufopen return 404 ctf_dict_t's directly, and cannot be used on CTF archives: use these 405 functions instead.) */ 406 407 extern ctf_dict_t *ctf_dict_open (const ctf_archive_t *, 408 const char *, int *); 409 extern ctf_dict_t *ctf_dict_open_sections (const ctf_archive_t *, 410 const ctf_sect_t *symsect, 411 const ctf_sect_t *strsect, 412 const char *, int *); 413 414 /* Look up symbols' types in archives by index or name, returning the dict 415 and optionally type ID in which the type is found. Lookup results are 416 cached so future lookups are faster. Needs symbol tables and (for name 417 lookups) string tables to be known for this CTF archive. */ 418 419 extern ctf_dict_t *ctf_arc_lookup_symbol (ctf_archive_t *, 420 unsigned long symidx, 421 ctf_id_t *, int *errp); 422 extern ctf_dict_t *ctf_arc_lookup_symbol_name (ctf_archive_t *, 423 const char *name, 424 ctf_id_t *, int *errp); 425 extern void ctf_arc_flush_caches (ctf_archive_t *); 426 427 /* The next functions return or close real CTF files, or write out CTF 428 archives, not archives or ELF files containing CTF content. As with 429 ctf_dict_open_sections, they can be passed symbol and string table 430 sections. */ 431 432 extern ctf_dict_t *ctf_simple_open (const char *ctfsect, size_t ctfsect_size, 433 const char *symsect, size_t symsect_size, 434 size_t symsect_entsize, 435 const char *strsect, size_t strsect_size, 436 int *errp); 437 extern ctf_dict_t *ctf_bufopen (const ctf_sect_t *ctfsect, 438 const ctf_sect_t *symsect, 439 const ctf_sect_t *strsect, int *); 440 extern void ctf_ref (ctf_dict_t *); 441 extern void ctf_dict_close (ctf_dict_t *); 442 443 /* CTF dicts may be in a parent/child relationship, where the child dicts 444 contain the name of their originating compilation unit and the name of 445 their parent. Dicts opened from CTF archives have this relationship set 446 up already, but if opening via raw low-level calls, you need to figure 447 out which dict is the parent and set it on the child via ctf_import(). */ 448 449 extern const char *ctf_cuname (ctf_dict_t *); 450 extern ctf_dict_t *ctf_parent_dict (ctf_dict_t *); 451 extern const char *ctf_parent_name (ctf_dict_t *); 452 extern int ctf_type_isparent (ctf_dict_t *, ctf_id_t); 453 extern int ctf_type_ischild (ctf_dict_t *, ctf_id_t); 454 extern int ctf_import (ctf_dict_t *, ctf_dict_t *); 455 456 /* Set these names (used when creating dicts). */ 457 458 extern int ctf_cuname_set (ctf_dict_t *, const char *); 459 extern int ctf_parent_name_set (ctf_dict_t *, const char *); 460 461 /* Set and get the CTF data model (see above). */ 462 463 extern int ctf_setmodel (ctf_dict_t *, int); 464 extern int ctf_getmodel (ctf_dict_t *); 465 466 /* CTF dicts can carry a single (in-memory-only) non-persistent pointer to 467 arbitrary data. No meaning is attached to this data and the dict does 468 not own it: nothing is done to it when the dict is closed. */ 469 470 extern void ctf_setspecific (ctf_dict_t *, void *); 471 extern void *ctf_getspecific (ctf_dict_t *); 472 473 /* Error handling. ctf dicts carry a system errno value or one of the 474 CTF_ERRORS above, which are returned via ctf_errno. The return value of 475 ctf_errno is only meaningful when the immediately preceding CTF function 476 call returns an error code. 477 478 There are four possible sorts of error return: 479 480 - From opening functions, a return value of NULL and the error returned 481 via an errp instead of via ctf_errno; all other functions return return 482 errors via ctf_errno. 483 484 - Functions returning a ctf_id_t are in error if the return value == CTF_ERR 485 - Functions returning an int are in error if their return value < 0 486 - Functions returning a pointer are in error if their return value == 487 NULL. */ 488 489 extern int ctf_errno (ctf_dict_t *); 490 extern const char *ctf_errmsg (int); 491 492 /* Return the version of CTF dicts written by writeout functions. The 493 argument must currently be zero. All dicts with versions below the value 494 returned by this function can be read by the library. CTF dicts written 495 by other non-GNU CTF libraries (e.g. that in FreeBSD) are not compatible 496 and cannot be read by this library. */ 497 498 extern int ctf_version (int); 499 500 /* Given a symbol table index corresponding to a function symbol, return info on 501 the type of a given function's arguments or return value. Vararg functions 502 have a final arg with CTF_FUNC_VARARG on in ctc_flags. */ 503 504 extern int ctf_func_info (ctf_dict_t *, unsigned long, ctf_funcinfo_t *); 505 extern int ctf_func_args (ctf_dict_t *, unsigned long, uint32_t, ctf_id_t *); 506 507 /* As above, but for CTF_K_FUNCTION types in CTF dicts. */ 508 509 extern int ctf_func_type_info (ctf_dict_t *, ctf_id_t, ctf_funcinfo_t *); 510 extern int ctf_func_type_args (ctf_dict_t *, ctf_id_t, uint32_t, ctf_id_t *); 511 512 /* Look up function or data symbols by name and return their CTF type ID, 513 if any. (For both function symbols and data symbols that are function 514 pointers, the types are of kind CTF_K_FUNCTION.) */ 515 516 extern ctf_id_t ctf_lookup_by_symbol (ctf_dict_t *, unsigned long); 517 extern ctf_id_t ctf_lookup_by_symbol_name (ctf_dict_t *, const char *); 518 519 /* Traverse all (function or data) symbols in a dict, one by one, and return the 520 type of each and (if NAME is non-NULL) optionally its name. */ 521 522 extern ctf_id_t ctf_symbol_next (ctf_dict_t *, ctf_next_t **, 523 const char **name, int functions); 524 525 /* Look up a type by name: some simple C type parsing is done, but this is by no 526 means comprehensive. Structures, unions and enums need "struct ", "union " 527 or "enum " on the front, as usual in C. */ 528 529 extern ctf_id_t ctf_lookup_by_name (ctf_dict_t *, const char *); 530 531 /* Look up a variable, which is a name -> type mapping with no specific 532 relationship to a symbol table. Before linking, everything with types in the 533 symbol table will be in the variable table as well; after linking, only those 534 typed functions and data objects that are not asssigned to symbols by the 535 linker are left in the variable table here. */ 536 537 extern ctf_id_t ctf_lookup_variable (ctf_dict_t *, const char *); 538 539 /* Type lookup functions. */ 540 541 /* Strip qualifiers and typedefs off a type, returning the base type. 542 543 Stripping also stops when we hit slices (see ctf_add_slice below), so it is 544 possible (given a chain looking like const -> slice -> typedef -> int) to 545 still have a typedef after you're done with this, but in that case it is a 546 typedef of a type with a *different width* (because this slice has not been 547 applied to it). 548 549 Most of the time you don't need to call this: the type-querying functions 550 will do it for you (as noted below). */ 551 552 extern ctf_id_t ctf_type_resolve (ctf_dict_t *, ctf_id_t); 553 554 /* Get the name of a type, including any const/volatile/restrict qualifiers 555 (cvr-quals), and return it as a new dynamically-allocated string. 556 (The 'a' stands for 'a'llocated.) */ 557 558 extern char *ctf_type_aname (ctf_dict_t *, ctf_id_t); 559 560 /* As above, but with no cvr-quals. */ 561 562 extern char *ctf_type_aname_raw (ctf_dict_t *, ctf_id_t); 563 564 /* A raw name that is owned by the ctf_dict_t and will live as long as it 565 does. Do not change the value this function returns! */ 566 567 extern const char *ctf_type_name_raw (ctf_dict_t *, ctf_id_t); 568 569 /* Like ctf_type_aname, but print the string into the passed buffer, truncating 570 if necessary and setting ECTF_NAMELEN on the errno: return the actual number 571 of bytes needed (not including the trailing \0). Consider using 572 ctf_type_aname instead. */ 573 574 extern ssize_t ctf_type_lname (ctf_dict_t *, ctf_id_t, char *, size_t); 575 576 /* Like ctf_type_lname, but return the string, or NULL if truncated. 577 Consider using ctf_type_aname instead. */ 578 579 extern char *ctf_type_name (ctf_dict_t *, ctf_id_t, char *, size_t); 580 581 /* Return the size or alignment of a type. Types with no meaningful size, like 582 function types, return 0 as their size; incomplete types set ECTF_INCOMPLETE. 583 The type is resolved for you, so cvr-quals and typedefs can be passsed in. */ 584 585 extern ssize_t ctf_type_size (ctf_dict_t *, ctf_id_t); 586 extern ssize_t ctf_type_align (ctf_dict_t *, ctf_id_t); 587 588 /* Return the kind of a type (CTF_K_* constant). Slices are considered to be 589 the kind they are a slice of. Forwards to incomplete structs, etc, return 590 CTF_K_FORWARD (but deduplication resolves most forwards to their concrete 591 types). */ 592 593 extern int ctf_type_kind (ctf_dict_t *, ctf_id_t); 594 595 /* Return the kind of a type (CTF_K_* constant). Slices are considered to be 596 the kind they are a slice of; forwards are considered to be the kind they are 597 a forward of. */ 598 599 extern int ctf_type_kind_forwarded (ctf_dict_t *, ctf_id_t); 600 601 /* Return the type a pointer, typedef, cvr-qual, or slice refers to, or return 602 an ECTF_NOTREF error otherwise. ctf_type_kind pretends that slices are 603 actually the type they are a slice of: this is usually want you want, but if 604 you want to find out if a type was actually a slice of some (usually-wider) 605 base type, you can call ctf_type_reference on it: a non-error return means 606 it was a slice. */ 607 608 extern ctf_id_t ctf_type_reference (ctf_dict_t *, ctf_id_t); 609 610 /* Return the encoding of a given type. No attempt is made to resolve the 611 type first, so passing in typedefs etc will yield an error. */ 612 613 extern int ctf_type_encoding (ctf_dict_t *, ctf_id_t, ctf_encoding_t *); 614 615 /* Given a type, return some other type that is a pointer to this type (if any 616 exists), or return ECTF_NOTYPE otherwise. If non exists, try resolving away 617 typedefs and cvr-quals and check again (so if you call this on foo_t, you 618 might get back foo *). No attempt is made to hunt for pointers to qualified 619 versions of the type passed in. */ 620 621 extern ctf_id_t ctf_type_pointer (ctf_dict_t *, ctf_id_t); 622 623 /* Return 1 if two types are assignment-compatible. */ 624 625 extern int ctf_type_compat (ctf_dict_t *, ctf_id_t, ctf_dict_t *, ctf_id_t); 626 627 /* Recursively visit the members of any type, calling the ctf_visit_f for each. */ 628 629 extern int ctf_type_visit (ctf_dict_t *, ctf_id_t, ctf_visit_f *, void *); 630 631 /* Comparison function that defines an ordering over types. If the types are in 632 different dicts, the ordering may vary between different openings of the same 633 dicts. */ 634 635 extern int ctf_type_cmp (ctf_dict_t *, ctf_id_t, ctf_dict_t *, ctf_id_t); 636 637 /* Get the name of an enumerator given its value, or vice versa. If many 638 enumerators have the same value, the first with that value is returned. */ 639 640 extern const char *ctf_enum_name (ctf_dict_t *, ctf_id_t, int); 641 extern int ctf_enum_value (ctf_dict_t *, ctf_id_t, const char *, int *); 642 643 /* Get the size and member type of an array. */ 644 645 extern int ctf_array_info (ctf_dict_t *, ctf_id_t, ctf_arinfo_t *); 646 647 /* Get info on specific named members of structs or unions, and count the number 648 of members in a struct, union, or enum. */ 649 650 extern int ctf_member_info (ctf_dict_t *, ctf_id_t, const char *, 651 ctf_membinfo_t *); 652 extern int ctf_member_count (ctf_dict_t *, ctf_id_t); 653 654 /* Iterators. */ 655 656 /* ctf_member_next is a _next-style iterator that can additionally traverse into 657 the members of unnamed structs nested within this struct as if they were 658 direct members, if CTF_MN_RECURSE is passed in the flags. */ 659 660 extern int ctf_member_iter (ctf_dict_t *, ctf_id_t, ctf_member_f *, void *); 661 extern ssize_t ctf_member_next (ctf_dict_t *, ctf_id_t, ctf_next_t **, 662 const char **name, ctf_id_t *membtype, 663 int flags); 664 extern int ctf_enum_iter (ctf_dict_t *, ctf_id_t, ctf_enum_f *, void *); 665 extern const char *ctf_enum_next (ctf_dict_t *, ctf_id_t, ctf_next_t **, 666 int *); 667 668 /* Iterate over all types in a dict. ctf_type_iter_all recurses over all types: 669 ctf_type_iter recurses only over types with user-visible names (for which 670 CTF_ADD_ROOT was passed). All such types are returned, even if they are 671 things like pointers that intrinsically have no name: this is the only effect 672 of CTF_ADD_ROOT for such types. ctf_type_next allows you to choose whether 673 to see hidden types or not with the want_hidden arg: if set, the flag (if 674 passed) returns the hidden state of each type in turn. */ 675 676 extern int ctf_type_iter (ctf_dict_t *, ctf_type_f *, void *); 677 extern int ctf_type_iter_all (ctf_dict_t *, ctf_type_all_f *, void *); 678 extern ctf_id_t ctf_type_next (ctf_dict_t *, ctf_next_t **, 679 int *flag, int want_hidden); 680 681 extern int ctf_variable_iter (ctf_dict_t *, ctf_variable_f *, void *); 682 extern ctf_id_t ctf_variable_next (ctf_dict_t *, ctf_next_t **, 683 const char **); 684 685 /* ctf_archive_iter and ctf_archive_next open each member dict for you, 686 automatically importing any parent dict as usual: ctf_archive_iter closes the 687 dict on return from ctf_archive_member_f, but for ctf_archive_next the caller 688 must close each dict returned. If skip_parent is set, the parent dict is 689 skipped on the basis that it's already been seen in every child dict (but if 690 no child dicts exist, this will lead to nothing being returned). 691 692 If an open fails, ctf_archive_iter returns -1 early (losing the error), but 693 ctf_archive_next both passes back the error in the passed errp and allows you 694 to iterate past errors (until the usual ECTF_NEXT_END is returned). */ 695 696 extern int ctf_archive_iter (const ctf_archive_t *, ctf_archive_member_f *, 697 void *); 698 extern ctf_dict_t *ctf_archive_next (const ctf_archive_t *, ctf_next_t **, 699 const char **, int skip_parent, int *errp); 700 701 /* Pass the raw content of each archive member in turn to 702 ctf_archive_raw_member_f. 703 704 This function alone does not currently operate on CTF files masquerading as 705 archives, and returns -EINVAL: the raw data is no longer available. It is 706 expected to be used only by archiving tools, in any case, which have no need 707 to deal with non-archives at all. (There is currently no _next analogue of 708 this function.) */ 709 710 extern int ctf_archive_raw_iter (const ctf_archive_t *, 711 ctf_archive_raw_member_f *, void *); 712 713 /* Dump the contents of a section in a CTF dict. STATE is an 714 iterator which should be a pointer to a variable set to NULL. The decorator 715 is called with each line in turn and can modify it or allocate and return a 716 new one. ctf_dump accumulates all the results and returns a single giant 717 multiline string. */ 718 719 extern char *ctf_dump (ctf_dict_t *, ctf_dump_state_t **state, 720 ctf_sect_names_t sect, ctf_dump_decorate_f *, 721 void *arg); 722 723 /* Error-warning reporting: an 'iterator' that returns errors and warnings from 724 the error/warning list, in order of emission. Errors and warnings are popped 725 after return: the caller must free the returned error-text pointer. */ 726 extern char *ctf_errwarning_next (ctf_dict_t *, ctf_next_t **, 727 int *is_warning, int *errp); 728 729 /* Creation. */ 730 731 /* Create a new, empty dict. If creation fails, return NULL and put a CTF error 732 code in the passed-in int (if set). */ 733 extern ctf_dict_t *ctf_create (int *); 734 735 /* Add specific types to a dict. You can add new types to any dict, but you can 736 only add members to types that have been added since this dict was read in 737 (you cannot read in a dict, look up a type in it, then add members to 738 it). All adding functions take a uint32_t CTF_ADD_ROOT / CTF_ADD_NONROOT 739 flag to indicate whether this type should be visible to name lookups via 740 ctf_lookup_by_name et al. */ 741 742 extern ctf_id_t ctf_add_array (ctf_dict_t *, uint32_t, 743 const ctf_arinfo_t *); 744 extern ctf_id_t ctf_add_const (ctf_dict_t *, uint32_t, ctf_id_t); 745 extern ctf_id_t ctf_add_enum_encoded (ctf_dict_t *, uint32_t, const char *, 746 const ctf_encoding_t *); 747 extern ctf_id_t ctf_add_enum (ctf_dict_t *, uint32_t, const char *); 748 extern ctf_id_t ctf_add_float (ctf_dict_t *, uint32_t, 749 const char *, const ctf_encoding_t *); 750 extern ctf_id_t ctf_add_forward (ctf_dict_t *, uint32_t, const char *, 751 uint32_t); 752 extern ctf_id_t ctf_add_function (ctf_dict_t *, uint32_t, 753 const ctf_funcinfo_t *, const ctf_id_t *); 754 extern ctf_id_t ctf_add_integer (ctf_dict_t *, uint32_t, const char *, 755 const ctf_encoding_t *); 756 757 /* Add a "slice", which wraps some integral type and changes its encoding 758 (useful for bitfields, etc). In most respects slices are treated the same 759 kind as the type they wrap: only ctf_type_reference can see the difference, 760 returning the wrapped type. */ 761 762 extern ctf_id_t ctf_add_slice (ctf_dict_t *, uint32_t, ctf_id_t, const ctf_encoding_t *); 763 extern ctf_id_t ctf_add_pointer (ctf_dict_t *, uint32_t, ctf_id_t); 764 extern ctf_id_t ctf_add_type (ctf_dict_t *, ctf_dict_t *, ctf_id_t); 765 extern ctf_id_t ctf_add_typedef (ctf_dict_t *, uint32_t, const char *, 766 ctf_id_t); 767 extern ctf_id_t ctf_add_restrict (ctf_dict_t *, uint32_t, ctf_id_t); 768 769 /* Struct and union addition. Straight addition uses possibly-confusing rules 770 to guess the final size of the struct/union given its members: to explicitly 771 state the size of the struct or union (to report compiler-generated padding, 772 etc) use the _sized variants. */ 773 774 extern ctf_id_t ctf_add_struct (ctf_dict_t *, uint32_t, const char *); 775 extern ctf_id_t ctf_add_union (ctf_dict_t *, uint32_t, const char *); 776 extern ctf_id_t ctf_add_struct_sized (ctf_dict_t *, uint32_t, const char *, 777 size_t); 778 extern ctf_id_t ctf_add_union_sized (ctf_dict_t *, uint32_t, const char *, 779 size_t); 780 781 /* Note that CTF cannot encode a given type. This usually returns an 782 ECTF_NONREPRESENTABLE error when queried. Mostly useful for struct members, 783 variables, etc, to point to. */ 784 785 extern ctf_id_t ctf_add_unknown (ctf_dict_t *, uint32_t, const char *); 786 extern ctf_id_t ctf_add_volatile (ctf_dict_t *, uint32_t, ctf_id_t); 787 788 /* Add an enumerator to an enum (the name is a misnomer). We do not currently 789 validate that enumerators have unique names, even though C requires it: in 790 future this may change. */ 791 792 extern int ctf_add_enumerator (ctf_dict_t *, ctf_id_t, const char *, int); 793 794 /* Add a member to a struct or union, either at the next available offset (with 795 suitable padding for the alignment) or at a specific offset, and possibly 796 with a specific encoding (creating a slice for you). Offsets need not be 797 unique, and need not be added in ascending order. */ 798 799 extern int ctf_add_member (ctf_dict_t *, ctf_id_t, const char *, ctf_id_t); 800 extern int ctf_add_member_offset (ctf_dict_t *, ctf_id_t, const char *, 801 ctf_id_t, unsigned long); 802 extern int ctf_add_member_encoded (ctf_dict_t *, ctf_id_t, const char *, 803 ctf_id_t, unsigned long, 804 const ctf_encoding_t); 805 806 extern int ctf_add_variable (ctf_dict_t *, const char *, ctf_id_t); 807 808 /* Set the size and member and index types of an array. */ 809 810 extern int ctf_set_array (ctf_dict_t *, ctf_id_t, const ctf_arinfo_t *); 811 812 /* Add a function oor object symbol type with a particular name, without saying 813 anything about the actual symbol index. (The linker will then associate them 814 with actual symbol indexes using the ctf_link functions below.) */ 815 816 extern int ctf_add_objt_sym (ctf_dict_t *, const char *, ctf_id_t); 817 extern int ctf_add_func_sym (ctf_dict_t *, const char *, ctf_id_t); 818 819 /* Snapshot/rollback. Call ctf_update to snapshot the state of a dict: 820 a later call to ctf_discard then deletes all types added since (but not new 821 members, enumerands etc). Call ctf_snapshot to return a snapshot ID: pass 822 one of these IDs to ctf_rollback to discard all types added since the 823 corresponding call to ctf_snapshot. */ 824 825 extern int ctf_update (ctf_dict_t *); 826 extern ctf_snapshot_id_t ctf_snapshot (ctf_dict_t *); 827 extern int ctf_rollback (ctf_dict_t *, ctf_snapshot_id_t); 828 extern int ctf_discard (ctf_dict_t *); 829 830 /* Dict writeout. 831 832 ctf_write: write out an uncompressed dict to an fd. 833 ctf_compress_write: write out a compressed dict to an fd (currently always 834 gzip, but this may change in future). 835 ctf_write_mem: write out a dict to a buffer and return it and its size, 836 compressing it if its uncompressed size is over THRESHOLD. */ 837 838 extern int ctf_write (ctf_dict_t *, int); 839 extern int ctf_compress_write (ctf_dict_t * fp, int fd); 840 extern unsigned char *ctf_write_mem (ctf_dict_t *, size_t *, size_t threshold); 841 842 /* Create a CTF archive named FILE from CTF_DICTS inputs with NAMES (or write it 843 to the passed-in fd). */ 844 845 extern int ctf_arc_write (const char *file, ctf_dict_t **ctf_dicts, size_t, 846 const char **names, size_t); 847 extern int ctf_arc_write_fd (int, ctf_dict_t **, size_t, const char **, 848 size_t); 849 850 /* Linking. These functions are used by ld to link .ctf sections in input 851 object files into a single .ctf section which is an archive possibly 852 containing members containing types whose names collide across multiple 853 compilation units, but they are usable by other programs as well and are not 854 private to the linker. */ 855 856 /* Add a CTF archive to the link with a given NAME (usually the name of the 857 containing object file). The dict added to is usually a new dict created 858 with ctf_create which will be filled with types corresponding to the shared 859 dict in the output (conflicting types in child dicts in the output archive 860 are stored in internal space inside this dict, but are not easily visible 861 until after ctf_link_write below). 862 863 The NAME need not be unique (but usually is). */ 864 865 extern int ctf_link_add_ctf (ctf_dict_t *, ctf_archive_t *, const char *name); 866 867 /* Do the deduplicating link, filling the dict with types. The FLAGS are the 868 CTF_LINK_* flags above. */ 869 870 extern int ctf_link (ctf_dict_t *, int flags); 871 872 /* Symtab linker handling, called after ctf_link to set up the symbol type 873 information used by ctf_*_lookup_symbol. */ 874 875 /* Add strings to the link from the ELF string table, repeatedly calling 876 ADD_STRING to add each string and its corresponding offset in turn. */ 877 878 typedef const char *ctf_link_strtab_string_f (uint32_t *offset, void *arg); 879 extern int ctf_link_add_strtab (ctf_dict_t *, 880 ctf_link_strtab_string_f *add_string, void *); 881 882 /* Note that a given symbol will be public with a given set of properties. 883 If the symbol has been added with that name via ctf_add_{func,objt}_sym, 884 this symbol type will end up in the symtypetabs and can be looked up via 885 ctf_*_lookup_symbol after the dict is read back in. */ 886 887 extern int ctf_link_add_linker_symbol (ctf_dict_t *, ctf_link_sym_t *); 888 889 /* Impose an ordering on symbols, as defined by the strtab and symbol 890 added by earlier calls to the above two functions. */ 891 892 extern int ctf_link_shuffle_syms (ctf_dict_t *); 893 894 /* Return the serialized form of this ctf_linked dict as a new 895 dynamically-allocated string, compressed if size over THRESHOLD. 896 897 May be a CTF dict or a CTF archive (this library mostly papers over the 898 differences so you can open both the same way, treat both as ctf_archive_t 899 and so on). */ 900 901 extern unsigned char *ctf_link_write (ctf_dict_t *, size_t *size, 902 size_t threshold); 903 904 /* Specialist linker functions. These functions are not used by ld, but can be 905 used by other programs making use of the linker machinery for other purposes 906 to customize its output. Must be called befoore ctf_link. */ 907 908 /* Add an entry to rename a given compilation unit to some other name. This 909 is only used if conflicting types are found in that compilation unit: they 910 will instead be placed in the child dict named TO. Many FROMs can map to one 911 TO: all the types are placed together in that dict, with any whose names 912 collide as a result being marked as non-root types. */ 913 914 extern int ctf_link_add_cu_mapping (ctf_dict_t *, const char *from, 915 const char *to); 916 917 /* Allow CTF archive names to be tweaked at the last minute before writeout. 918 Unlike cu-mappings, this cannot transform names so that they collide: it's 919 meant for unusual use cases that use names for archive members that are not 920 exactly the same as CU names but are modified in some systematic way. */ 921 typedef char *ctf_link_memb_name_changer_f (ctf_dict_t *, 922 const char *, void *); 923 extern void ctf_link_set_memb_name_changer 924 (ctf_dict_t *, ctf_link_memb_name_changer_f *, void *); 925 926 /* Filter out unwanted variables, which can be very voluminous, and (unlike 927 symbols) cause the CTF string table to grow to hold their names. The 928 variable filter should return nonzero if a variable should not appear in the 929 output. */ 930 typedef int ctf_link_variable_filter_f (ctf_dict_t *, const char *, ctf_id_t, 931 void *); 932 extern int ctf_link_set_variable_filter (ctf_dict_t *, 933 ctf_link_variable_filter_f *, void *); 934 935 /* Turn debugging off and on, and get its value. This is the same as setting 936 LIBCTF_DEBUG in the environment. */ 937 extern void ctf_setdebug (int debug); 938 extern int ctf_getdebug (void); 939 940 /* Deprecated aliases for existing functions and types. */ 941 942 struct ctf_file; 943 typedef struct ctf_dict ctf_file_t; 944 extern void ctf_file_close (ctf_file_t *); 945 extern ctf_dict_t *ctf_parent_file (ctf_dict_t *); 946 extern ctf_dict_t *ctf_arc_open_by_name (const ctf_archive_t *, 947 const char *, int *); 948 extern ctf_dict_t *ctf_arc_open_by_name_sections (const ctf_archive_t *arc, 949 const ctf_sect_t *symsect, 950 const ctf_sect_t *strsect, 951 const char *name, int *errp); 952 953 /* Deprecated witeout function to write out a gzip-compressed dict. Unlike all 954 the other writeout functions, this even compresses the header (it has to, 955 since it's passed a gzFile), so the caller must also decompress it, since 956 ctf_open() etc cannot tell it is a CTF dict or how large it is before 957 decompression. */ 958 959 extern int ctf_gzwrite (ctf_dict_t *fp, gzFile fd); 960 961 /* Deprecated functions with no current use. */ 962 963 extern const char *ctf_label_topmost (ctf_dict_t *); 964 extern int ctf_label_info (ctf_dict_t *, const char *, ctf_lblinfo_t *); 965 extern int ctf_label_iter (ctf_dict_t *, ctf_label_f *, void *); 966 extern int ctf_label_next (ctf_dict_t *, ctf_next_t **, const char **); /* TBD */ 967 968 #ifdef __cplusplus 969 } 970 #endif 971 972 #endif /* _CTF_API_H */ 973