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 <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 */