library.h

   1 /*
   2  * This file is part of ltrace.
   3  * Copyright (C) 2012 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 "callback.h"
  27 #include "sysdep.h"
  28
  29 struct Process;
  30 struct library;
  31
  32 enum toplt {
  33         LS_TOPLT_NONE = 0,      /* PLT not used for this symbol. */
  34         LS_TOPLT_EXEC,          /* PLT for this symbol is executable. */
  35 };
  36
  37 /* Dict interface.  */
  38 unsigned int target_address_hash(const void *key);
  39 int target_address_cmp(const void *key1, const void *key2);
  40
  41 /* For handling -l.  */
  42 struct library_exported_name {
  43         struct library_exported_name *next;
  44         const char *name;
  45         int own_name : 1;
  46 };
  47
  48 struct library_symbol {
  49         struct library_symbol *next;
  50         struct library *lib;
  51         const char *name;
  52         arch_addr_t enter_addr;
  53         enum toplt plt_type;
  54         int own_name : 1;
  55
  56         /* This is relevant for PLT symbols.  Latent PLT symbols are
  57          * those that don't match any of the -e rules, but that might
  58          * potentially become active if a library implementing them
  59          * appears that matches a -l rule.  Ltrace core is responsible
  60          * for clearing latent flag.  */
  61         int latent : 1;
  62
  63         /* Delayed symbols are those for which a breakpoint shouldn't
  64          * be enabled yet.  They are similar to latent symbols, but
  65          * backend is responsible for clearing the delayed flag.  See
  66          * proc_activate_delayed_symbol.  */
  67         int delayed : 1;
  68
  69         struct arch_library_symbol_data arch;
  70 };
  71
  72 /* Init LIBSYM.  NAME will be freed when LIBSYM is destroyed if
  73  * OWN_NAME.  ARCH has to be initialized by a separate call.  */
  74 int library_symbol_init(struct library_symbol *libsym,
  75                         arch_addr_t addr, const char *name, int own_name,
  76                         enum toplt type_of_plt);
  77
  78 /* Copy library symbol SYM into the area pointed-to by RETP.  Return 0
  79  * on success or a negative value on failure.  */
  80 int library_symbol_clone(struct library_symbol *retp,
  81                          struct library_symbol *sym);
  82
  83 /* Destroy library symbol.  This essentially just frees name if it's
  84  * owned.  It doesn't free the memory associated with SYM pointer
  85  * itself.  Returns 0 on success or a negative value in case of an
  86  * error (which would be an out of memory condition).  */
  87 void library_symbol_destroy(struct library_symbol *sym);
  88
  89 /* Compare two library symbols.  Returns a negative value, 0, or a
  90  * positive value, much like strcmp.  The function compares symbol
  91  * addresses, and if those are equal, it compares symbol names.  If
  92  * those are equal, too, the symbols are considered equal.  */
  93 int library_symbol_cmp(struct library_symbol *a, struct library_symbol *b);
  94
  95 /* Set a name for library symbol.  This frees the old name, if
  96  * that is owned.  */
  97 void library_symbol_set_name(struct library_symbol *libsym,
  98                              const char *name, int own_name);
  99
 100 /* A function that can be used as library_each_symbol callback.  Looks
 101  * for a symbol SYM for which library_symbol_cmp(SYM, STANDARD)
 102  * returns 0.  */
 103 enum callback_status library_symbol_equal_cb(struct library_symbol *libsym,
 104                                              void *standard);
 105
 106 /* A function that can be used as library_each_symbol callback.  Looks
 107  * for a symbol SYM for which strcmp(SYM->name, NAME) == 0.  */
 108 enum callback_status library_symbol_named_cb(struct library_symbol *libsym,
 109                                              void *name);
 110
 111 /* A function that can be used as library_each_symbol callback.  Looks
 112  * for a delayed symbol.  */
 113 enum callback_status library_symbol_delayed_cb(struct library_symbol *libsym,
 114                                                void *unused);
 115
 116 enum library_type {
 117         LT_LIBTYPE_MAIN,
 118         LT_LIBTYPE_DSO,
 119 };
 120
 121 /* XXX we might consider sharing libraries across processes.  Things
 122  * like libc will be opened by every single process, no point cloning
 123  * these everywhere.  But for now, keep the ownership structure
 124  * simple.  */
 125 struct library {
 126         struct library *next;
 127
 128         /* Unique key. Two library objects are considered equal, if
 129          * they have the same key.  */
 130         arch_addr_t key;
 131
 132         /* Address where the library is mapped.  */
 133         arch_addr_t base;
 134
 135         /* Absolute address of the entry point.  Useful for main
 136          * binary, though I suppose the value might be useful for the
 137          * dynamic linker, too (in case we ever want to do early
 138          * process tracing).  */
 139         arch_addr_t entry;
 140
 141         /* Address of PT_DYNAMIC segment.  */
 142         arch_addr_t dyn_addr;
 143
 144         /* Symbols associated with the library.  This includes a
 145          * symbols that don't have a breakpoint attached (yet).  */
 146         struct library_symbol *symbols;
 147
 148         /* List of names that this library implements, and that match
 149          * -l filter.  Each time a new library is mapped, its list of
 150          * exports is examined, and corresponding PLT slots are
 151          * enabled.  */
 152         struct library_exported_name *exported_names;
 153
 154         const char *soname;
 155         const char *pathname;
 156
 157         enum library_type type;
 158
 159         char own_soname : 1;
 160         char own_pathname : 1;
 161
 162         struct arch_library_data arch;
 163 };
 164
 165 /* Init LIB.  */
 166 void library_init(struct library *lib, enum library_type type);
 167
 168 /* Initialize RETP to a library identical to LIB.  Symbols are not
 169  * shared, but copied over.  Returns 0 on success and a negative value
 170  * in case of failure.  */
 171 int library_clone(struct library *retp, struct library *lib);
 172
 173 /* Destroy library.  Doesn't free LIB itself.  Symbols are destroyed
 174  * and freed.  */
 175 void library_destroy(struct library *lib);
 176
 177 /* Set library soname.  Frees the old name if necessary.  */
 178 void library_set_soname(struct library *lib,
 179                         const char *new_name, int own_name);
 180
 181 /* Set library pathname.  Frees the old name if necessary.  */
 182 void library_set_pathname(struct library *lib,
 183                           const char *new_name, int own_name);
 184
 185 /* Iterate through list of symbols of library LIB.  See callback.h for
 186  * notes on this interface.  */
 187 struct library_symbol *library_each_symbol
 188         (struct library *lib, struct library_symbol *start_after,
 189          enum callback_status (*cb)(struct library_symbol *, void *),
 190          void *data);
 191
 192 /* Add a new symbol SYM to LIB.  SYM is assumed owned, we need to
 193  * overwrite SYM->next.  */
 194 void library_add_symbol(struct library *lib, struct library_symbol *sym);
 195
 196 /* A function that can be used as proc_each_library callback.  Looks
 197  * for a library with the name passed in DATA.  PROC is ignored.  */
 198 enum callback_status library_named_cb(struct Process *proc,
 199                                       struct library *lib, void *name);
 200
 201 /* A function that can be used as proc_each_library callback.  Looks
 202  * for a library with given base.
 203  *
 204  * NOTE: The key is passed as a POINTER to arch_addr_t (that
 205  * because in general, arch_addr_t doesn't fit in void*).  */
 206 enum callback_status library_with_key_cb(struct Process *proc,
 207                                          struct library *lib, void *keyp);
 208
 209 /* XXX this should really be in backend.h (as on pmachata/revamp
 210  * branch), or, on this branch, in common.h.  But we need
 211  * arch_addr_t (which should also be in backend.h, I reckon), so
 212  * stuff it here for the time being.  */
 213 /* This function is implemented in the back end.  It is called for all
 214  * raw addresses as read from symbol tables etc.  If necessary on
 215  * given architecture, this function should translate the address
 216  * according to .opd or other indirection mechanism.  Returns 0 on
 217  * success and a negative value on failure.  */
 218 struct ltelf;
 219 int arch_translate_address(struct ltelf *lte,
 220                            arch_addr_t addr, arch_addr_t *ret);
 221 /* This is the same function as arch_translate_address, except it's
 222  * used at the point that we don't have ELF available anymore.  */
 223 int arch_translate_address_dyn(struct Process *proc,
 224                                arch_addr_t addr, arch_addr_t *ret);
 225
 226 #endif /* _LIBRARY_H_ */