library.h

   1 /*
   2  * This file is part of ltrace.
   3  * Copyright (C) 2012,2013 Petr Machata, Red Hat Inc.
   4  * Copyright (C) 2006 Paul Gilliam, IBM Corporation
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License as
   8  * published by the Free Software Foundation; either version 2 of the
   9  * License, or (at your option) any later 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.  See the GNU
  14  * 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; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  19  * 02110-1301 USA
  20  */
  21
  22 #ifndef LIBRARY_H
  23 #define LIBRARY_H
  24
  25 #include <stdint.h>
  26 #include <stdbool.h>
  27
  28 #if defined(HAVE_LIBDW)
  29 # include <elfutils/libdwfl.h>
  30 #endif
  31
  32 #include "dict.h"
  33 #include "callback.h"
  34 #include "forward.h"
  35 #include "sysdep.h"
  36
  37 enum toplt {
  38         LS_TOPLT_NONE = 0,      /* PLT not used for this symbol. */
  39         LS_TOPLT_EXEC,          /* PLT for this symbol is executable. */
  40 };
  41
  42 /* Dict interface.  */
  43 size_t arch_addr_hash(const arch_addr_t *addr);
  44 int arch_addr_eq(const arch_addr_t *addr1, const arch_addr_t *addr2);
  45
  46
  47 /* For handling -l and for handling library export aliases (different symbol
  48  * name, same address)
  49  *
  50  * This structure needs to
  51  * - store (addr, name) tuples
  52  * - be searchable by addr (when populating)
  53  * - be searchable by name (when looking for aliases)
  54  * - be enumeratable (by activate_latent_in())
  55  */
  56 struct library_exported_names {
  57         // I store the data in several structures to facilitate different types
  58         // of access
  59         struct dict names; // maps a name to an address
  60         struct dict addrs; // maps an address to a vect of names
  61 };
  62
  63 struct library_symbol {
  64         struct library_symbol *next;
  65         struct library *lib;
  66         const char *name;
  67         arch_addr_t enter_addr;
  68         enum toplt plt_type;
  69
  70         /* If this is non-NULL, this prototype is used instead of
  71          * looking up one in LIB->protolib.  */
  72         struct prototype *proto;
  73
  74         int own_name : 1;
  75
  76         /* This is relevant for PLT symbols.  Latent PLT symbols are
  77          * those that don't match any of the -e rules, but that might
  78          * potentially become active if a library implementing them
  79          * appears that matches a -l rule.  Ltrace core is responsible
  80          * for clearing latent flag.  */
  81         int latent : 1;
  82
  83         /* Delayed symbols are those for which a breakpoint shouldn't
  84          * be enabled yet.  They are similar to latent symbols, but
  85          * backend is responsible for clearing the delayed flag.  See
  86          * proc_activate_delayed_symbol.  */
  87         int delayed : 1;
  88
  89         struct arch_library_symbol_data arch;
  90         struct os_library_symbol_data os;
  91 };
  92
  93 /* Init LIBSYM.  NAME will be freed when LIBSYM is destroyed if
  94  * OWN_NAME.  ARCH has to be initialized by a separate call.  */
  95 int library_symbol_init(struct library_symbol *libsym,
  96                         arch_addr_t addr, const char *name, int own_name,
  97                         enum toplt type_of_plt);
  98
  99 /* Copy library symbol SYM into the area pointed-to by RETP.  Return 0
 100  * on success or a negative value on failure.  */
 101 int library_symbol_clone(struct library_symbol *retp,
 102                          struct library_symbol *sym);
 103
 104 /* Destroy library symbol.  This essentially just frees name if it's
 105  * owned.  It doesn't free the memory associated with SYM pointer
 106  * itself.  Returns 0 on success or a negative value in case of an
 107  * error (which would be an out of memory condition).  */
 108 void library_symbol_destroy(struct library_symbol *sym);
 109
 110 /* Compare two library symbols.  Returns a negative value, 0, or a
 111  * positive value, much like strcmp.  The function compares symbol
 112  * addresses, and if those are equal, it compares symbol names.  If
 113  * those are equal, too, the symbols are considered equal.  */
 114 int library_symbol_cmp(struct library_symbol *a, struct library_symbol *b);
 115
 116 /* Set a name for library symbol.  This frees the old name, if
 117  * that is owned.  */
 118 void library_symbol_set_name(struct library_symbol *libsym,
 119                              const char *name, int own_name);
 120
 121 /* A function that can be used as library_each_symbol callback.  Looks
 122  * for a symbol SYM for which library_symbol_cmp(SYM, STANDARD)
 123  * returns 0.  */
 124 enum callback_status library_symbol_equal_cb(struct library_symbol *libsym,
 125                                              void *standard);
 126
 127 /* A function that can be used as library_each_symbol callback.  Looks
 128  * for a symbol SYM for which strcmp(SYM->name, NAME) == 0.  */
 129 enum callback_status library_symbol_named_cb(struct library_symbol *libsym,
 130                                              void *name);
 131
 132 /* A function that can be used as library_each_symbol callback.  Looks
 133  * for a delayed symbol.  */
 134 enum callback_status library_symbol_delayed_cb(struct library_symbol *libsym,
 135                                                void *unused);
 136
 137 enum library_type {
 138         LT_LIBTYPE_MAIN,
 139         LT_LIBTYPE_DSO,
 140         LT_LIBTYPE_SYSCALL,
 141 };
 142
 143 /* XXX we might consider sharing libraries across processes.  Things
 144  * like libc will be opened by every single process, no point cloning
 145  * these everywhere.  But for now, keep the ownership structure
 146  * simple.  */
 147 struct library {
 148         struct library *next;
 149
 150         /* Unique key. Two library objects are considered equal, if
 151          * they have the same key.  */
 152         arch_addr_t key;
 153
 154         /* Address where the library is mapped.  */
 155         arch_addr_t base;
 156
 157         /* Absolute address of the entry point.  Useful for main
 158          * binary, though I suppose the value might be useful for the
 159          * dynamic linker, too (in case we ever want to do early
 160          * process tracing).  */
 161         arch_addr_t entry;
 162
 163         /* Address of PT_DYNAMIC segment.  */
 164         arch_addr_t dyn_addr;
 165
 166         /* Symbols associated with the library.  This includes a
 167          * symbols that don't have a breakpoint attached (yet).  */
 168         struct library_symbol *symbols;
 169
 170         /* List of names that this library implements, and that match
 171          * -l filter.  Each time a new library is mapped, its list of
 172          * exports is examined, and corresponding PLT slots are
 173          * enabled. This data structure also keeps track of export
 174          * addresses to find symbols with different names, but same
 175          * addresses */
 176         struct library_exported_names exported_names;
 177
 178         /* Prototype library associated with this library.  */
 179         struct protolib *protolib;
 180
 181         const char *soname;
 182         const char *pathname;
 183
 184         enum library_type type;
 185
 186         char own_soname : 1;
 187         char own_pathname : 1;
 188         bool should_activate_latent : 1;
 189
 190         struct arch_library_data arch;
 191         struct os_library_data os;
 192
 193 #if defined(HAVE_LIBDW)
 194         Dwfl_Module *dwfl_module;
 195 #endif
 196 };
 197
 198 /* Init LIB.  */
 199 int library_init(struct library *lib, enum library_type type);
 200
 201 /* Initialize RETP to a library identical to LIB.  Symbols are not
 202  * shared, but copied over.  Returns 0 on success and a negative value
 203  * in case of failure.  */
 204 int library_clone(struct library *retp, struct library *lib);
 205
 206 /* Destroy library.  Doesn't free LIB itself.  Symbols are destroyed
 207  * and freed.  */
 208 void library_destroy(struct library *lib);
 209
 210 /* Set library soname.  Frees the old name if necessary.  */
 211 void library_set_soname(struct library *lib,
 212                         const char *new_name, int own_name);
 213
 214 /* Set library pathname.  Frees the old name if necessary.  */
 215 void library_set_pathname(struct library *lib,
 216                           const char *new_name, int own_name);
 217
 218 /* Iterate through list of symbols of library LIB.  See callback.h for
 219  * notes on this interface.  */
 220 struct library_symbol *library_each_symbol
 221         (struct library *lib, struct library_symbol *start_after,
 222          enum callback_status (*cb)(struct library_symbol *, void *),
 223          void *data);
 224
 225 /* Add a new symbol SYM to LIB.  SYM is assumed owned, we need to
 226  * overwrite SYM->next.  */
 227 void library_add_symbol(struct library *lib, struct library_symbol *sym);
 228
 229 /* A function that can be used as proc_each_library callback.  Looks
 230  * for a library with the name passed in DATA.  PROC is ignored.  */
 231 enum callback_status library_named_cb(struct process *proc,
 232                                       struct library *lib, void *name);
 233
 234 /* A function that can be used as proc_each_library callback.  Looks
 235  * for a library with given base.
 236  *
 237  * NOTE: The key is passed as a POINTER to arch_addr_t (that
 238  * because in general, arch_addr_t doesn't fit in void*).  */
 239 enum callback_status library_with_key_cb(struct process *proc,
 240                                          struct library *lib, void *keyp);
 241
 242 /* XXX this should really be in backend.h (as on pmachata/revamp
 243  * branch), or, on this branch, in common.h.  But we need
 244  * arch_addr_t (which should also be in backend.h, I reckon), so
 245  * stuff it here for the time being.  */
 246 /* This function is implemented in the back end.  It is called for all
 247  * raw addresses as read from symbol tables etc.  If necessary on
 248  * given architecture, this function should translate the address
 249  * according to .opd or other indirection mechanism.  Returns 0 on
 250  * success and a negative value on failure.  */
 251 struct ltelf;
 252 int arch_translate_address(struct ltelf *lte,
 253                            arch_addr_t addr, arch_addr_t *ret);
 254 /* This is the same function as arch_translate_address, except it's
 255  * used at the point that we don't have ELF available anymore.  */
 256 int arch_translate_address_dyn(struct process *proc,
 257                                arch_addr_t addr, arch_addr_t *ret);
 258
 259
 260 /* Pushes a name/address tuple to the list of a library's exports. Returns 0 on
 261  * success
 262  */
 263 int library_exported_names_push(struct library_exported_names *names,
 264                                 uint64_t addr, char *name,
 265                                 int own_name );
 266
 267 /* Iterates through the a library's export list, reporting each symbol that is
 268  * an alias of the given 'aliasname' symbol. This 'aliasname' symbol itself is
 269  * NOT reported, so if this symbol is unique, the callback is not called at all.
 270  *
 271  * If we want to iterate through the whole alias list, set
 272  * name_start_after=NULL. If we want to start iterating immediately past a
 273  * particular symbol name, pass a pointer to this symbol name in
 274  * name_start_after. This must be a pointer in the internal dict, preferably
 275  * returned by an earlier call to this function
 276  *
 277  * If the callback fails at any point, a pointer to the failing key is returned.
 278  * On success, returns NULL. The returned pointer can be passed back to this
 279  * function in name_start_after to resume skipping this element
 280  */
 281 const char** library_exported_names_each_alias(
 282         struct library_exported_names *names,
 283         const char *aliasname,
 284         const char **name_start_after,
 285         enum callback_status (*cb)(const char *,
 286                                    void *),
 287         void *data);
 288
 289 /* Returns 0 if the exported names list does not contain a given name, or 1 if
 290  * it does */
 291 int library_exported_names_contains(struct library_exported_names *names,
 292                                     const char *queryname);
 293
 294 #endif /* LIBRARY_H */