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
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.
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.
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
27 #if defined(HAVE_LIBDW)
28 # include <elfutils/libdwfl.h>
37 LS_TOPLT_NONE = 0, /* PLT not used for this symbol. */
38 LS_TOPLT_EXEC, /* PLT for this symbol is executable. */
42 size_t arch_addr_hash(const arch_addr_t *addr);
43 int arch_addr_eq(const arch_addr_t *addr1, const arch_addr_t *addr2);
46 /* For handling -l and for handling library export aliases (different symbol
49 * This structure needs to
50 * - store (addr, name) tuples
51 * - be searchable by addr (when populating)
52 * - be searchable by name (when looking for aliases)
53 * - be enumeratable (by activate_latent_in())
55 struct library_exported_names {
56 // I store the data in several structures to facilitate different types
58 struct dict names; // maps a name to an address
59 struct dict addrs; // maps an address to a vect of names
62 struct library_symbol {
63 struct library_symbol *next;
66 arch_addr_t enter_addr;
69 /* If this is non-NULL, this prototype is used instead of
70 * looking up one in LIB->protolib. */
71 struct prototype *proto;
75 /* This is relevant for PLT symbols. Latent PLT symbols are
76 * those that don't match any of the -e rules, but that might
77 * potentially become active if a library implementing them
78 * appears that matches a -l rule. Ltrace core is responsible
79 * for clearing latent flag. */
82 /* Delayed symbols are those for which a breakpoint shouldn't
83 * be enabled yet. They are similar to latent symbols, but
84 * backend is responsible for clearing the delayed flag. See
85 * proc_activate_delayed_symbol. */
88 struct arch_library_symbol_data arch;
89 struct os_library_symbol_data os;
92 /* Init LIBSYM. NAME will be freed when LIBSYM is destroyed if
93 * OWN_NAME. ARCH has to be initialized by a separate call. */
94 int library_symbol_init(struct library_symbol *libsym,
95 arch_addr_t addr, const char *name, int own_name,
96 enum toplt type_of_plt);
98 /* Copy library symbol SYM into the area pointed-to by RETP. Return 0
99 * on success or a negative value on failure. */
100 int library_symbol_clone(struct library_symbol *retp,
101 struct library_symbol *sym);
103 /* Destroy library symbol. This essentially just frees name if it's
104 * owned. It doesn't free the memory associated with SYM pointer
105 * itself. Returns 0 on success or a negative value in case of an
106 * error (which would be an out of memory condition). */
107 void library_symbol_destroy(struct library_symbol *sym);
109 /* Compare two library symbols. Returns a negative value, 0, or a
110 * positive value, much like strcmp. The function compares symbol
111 * addresses, and if those are equal, it compares symbol names. If
112 * those are equal, too, the symbols are considered equal. */
113 int library_symbol_cmp(struct library_symbol *a, struct library_symbol *b);
115 /* Set a name for library symbol. This frees the old name, if
117 void library_symbol_set_name(struct library_symbol *libsym,
118 const char *name, int own_name);
120 /* A function that can be used as library_each_symbol callback. Looks
121 * for a symbol SYM for which library_symbol_cmp(SYM, STANDARD)
123 enum callback_status library_symbol_equal_cb(struct library_symbol *libsym,
126 /* A function that can be used as library_each_symbol callback. Looks
127 * for a symbol SYM for which strcmp(SYM->name, NAME) == 0. */
128 enum callback_status library_symbol_named_cb(struct library_symbol *libsym,
131 /* A function that can be used as library_each_symbol callback. Looks
132 * for a delayed symbol. */
133 enum callback_status library_symbol_delayed_cb(struct library_symbol *libsym,
142 /* XXX we might consider sharing libraries across processes. Things
143 * like libc will be opened by every single process, no point cloning
144 * these everywhere. But for now, keep the ownership structure
147 struct library *next;
149 /* Unique key. Two library objects are considered equal, if
150 * they have the same key. */
153 /* Address where the library is mapped. */
156 /* Absolute address of the entry point. Useful for main
157 * binary, though I suppose the value might be useful for the
158 * dynamic linker, too (in case we ever want to do early
159 * process tracing). */
162 /* Address of PT_DYNAMIC segment. */
163 arch_addr_t dyn_addr;
165 /* Symbols associated with the library. This includes a
166 * symbols that don't have a breakpoint attached (yet). */
167 struct library_symbol *symbols;
169 /* List of names that this library implements, and that match
170 * -l filter. Each time a new library is mapped, its list of
171 * exports is examined, and corresponding PLT slots are
172 * enabled. This data structure also keeps track of export
173 * addresses to find symbols with different names, but same
175 struct library_exported_names exported_names;
177 /* Prototype library associated with this library. */
178 struct protolib *protolib;
181 const char *pathname;
183 enum library_type type;
186 char own_pathname : 1;
188 struct arch_library_data arch;
189 struct os_library_data os;
191 #if defined(HAVE_LIBDW)
192 Dwfl_Module *dwfl_module;
197 int library_init(struct library *lib, enum library_type type);
199 /* Initialize RETP to a library identical to LIB. Symbols are not
200 * shared, but copied over. Returns 0 on success and a negative value
201 * in case of failure. */
202 int library_clone(struct library *retp, struct library *lib);
204 /* Destroy library. Doesn't free LIB itself. Symbols are destroyed
206 void library_destroy(struct library *lib);
208 /* Set library soname. Frees the old name if necessary. */
209 void library_set_soname(struct library *lib,
210 const char *new_name, int own_name);
212 /* Set library pathname. Frees the old name if necessary. */
213 void library_set_pathname(struct library *lib,
214 const char *new_name, int own_name);
216 /* Iterate through list of symbols of library LIB. See callback.h for
217 * notes on this interface. */
218 struct library_symbol *library_each_symbol
219 (struct library *lib, struct library_symbol *start_after,
220 enum callback_status (*cb)(struct library_symbol *, void *),
223 /* Add a new symbol SYM to LIB. SYM is assumed owned, we need to
224 * overwrite SYM->next. */
225 void library_add_symbol(struct library *lib, struct library_symbol *sym);
227 /* A function that can be used as proc_each_library callback. Looks
228 * for a library with the name passed in DATA. PROC is ignored. */
229 enum callback_status library_named_cb(struct process *proc,
230 struct library *lib, void *name);
232 /* A function that can be used as proc_each_library callback. Looks
233 * for a library with given base.
235 * NOTE: The key is passed as a POINTER to arch_addr_t (that
236 * because in general, arch_addr_t doesn't fit in void*). */
237 enum callback_status library_with_key_cb(struct process *proc,
238 struct library *lib, void *keyp);
240 /* XXX this should really be in backend.h (as on pmachata/revamp
241 * branch), or, on this branch, in common.h. But we need
242 * arch_addr_t (which should also be in backend.h, I reckon), so
243 * stuff it here for the time being. */
244 /* This function is implemented in the back end. It is called for all
245 * raw addresses as read from symbol tables etc. If necessary on
246 * given architecture, this function should translate the address
247 * according to .opd or other indirection mechanism. Returns 0 on
248 * success and a negative value on failure. */
250 int arch_translate_address(struct ltelf *lte,
251 arch_addr_t addr, arch_addr_t *ret);
252 /* This is the same function as arch_translate_address, except it's
253 * used at the point that we don't have ELF available anymore. */
254 int arch_translate_address_dyn(struct process *proc,
255 arch_addr_t addr, arch_addr_t *ret);
258 /* Pushes a name/address tuple to the list of a library's exports. Returns 0 on
261 int library_exported_names_push(struct library_exported_names *names,
262 uint64_t addr, const char *name,
265 /* Iterates through the a library's export list. The callback is called for
266 * every symbol a library exports. Symbol aliases do not apply here. If multiple
267 * symbols are defined at the same address, each is reported here.
269 * If we want to iterate through the whole list, set name_start_after=NULL. If
270 * we want to start iterating immediately past a particular symbol name, pass a
271 * pointer to this symbol name in name_start_after. This must be a pointer in
272 * the internal dict, preferably returned by an earlier call to this function
274 * If the callback fails at any point, a pointer to the failing key is returned.
275 * On success, returns NULL. The returned pointer can be passed back to this
276 * function in name_start_after to resume skipping this element
278 const char** library_exported_names_each(
279 const struct library_exported_names *names,
280 const char **name_start_after,
281 enum callback_status (*cb)(const char *,
285 /* Iterates through the a library's export list, reporting each symbol that is
286 * an alias of the given 'aliasname' symbol. This 'aliasname' symbol itself is
287 * NOT reported, so if this symbol is unique, the callback is not called at all.
289 * If we want to iterate through the whole alias list, set
290 * name_start_after=NULL. If we want to start iterating immediately past a
291 * particular symbol name, pass a pointer to this symbol name in
292 * name_start_after. This must be a pointer in the internal dict, preferably
293 * returned by an earlier call to this function
295 * If the callback fails at any point, a pointer to the failing key is returned.
296 * On success, returns NULL. The returned pointer can be passed back to this
297 * function in name_start_after to resume skipping this element
299 const char** library_exported_names_each_alias(
300 const struct library_exported_names *names,
301 const char *aliasname,
302 const char **name_start_after,
303 enum callback_status (*cb)(const char *,
307 #endif /* _LIBRARY_H_ */