include/ctf-api.h

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