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