library.h revision 522a6ca083c8b9e964548b0e79a4bdc8095d6e2e 
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 <gelf.h> // XXX
27
28struct Process;
29struct library;
30
31enum toplt {
32	LS_TOPLT_NONE = 0,	/* PLT not used for this symbol. */
33	LS_TOPLT_EXEC,		/* PLT for this symbol is executable. */
34	LS_TOPLT_POINT		/* PLT for this symbol is a non-executable. */
35};
36
37/* We should in general be able to trace 64-bit processes with 32-bit
38 * ltrace.  (At least PPC has several PTRACE requests related to
39 * tracing 64-on-32, so presumably it should be possible.)  But ltrace
40 * is currently hopelessly infested with using void* for host address.
41 * So keep with it, for now.  */
42typedef void *target_address_t;
43
44struct library_symbol {
45	struct library_symbol *next;
46	struct library *lib;
47	const char *name;
48	target_address_t enter_addr;
49	enum toplt plt_type;
50	char needs_init;
51	char is_weak;
52	char own_name;
53};
54
55/* Init LIBSYM.  NAME will be freed when LIBSYM is destroyed if
56 * OWN_NAME.  */
57void library_symbol_init(struct library_symbol *libsym, struct library *lib,
58			 target_address_t addr, const char *name, int own_name,
59			 enum toplt type_of_plt, int is_weak);
60
61/* Copy library symbol SYM into the area pointed-to by RETP.  Return 0
62 * on success or a negative value on failure.  */
63int library_symbol_clone(struct library_symbol *retp,
64			 struct library_symbol *sym);
65
66/* Destroy library symbol.  This essentially just frees name if it's
67 * owned.  It doesn't free the memory associated with SYM pointer
68 * itself.  Returns 0 on success or a negative value in case of an
69 * error (which would be an out of memory condition).  */
70void library_symbol_destroy(struct library_symbol *sym);
71
72/* Compare two library symbols.  Returns a negative value, 0, or a
73 * positive value, much like strcmp.  The function compares symbol
74 * addresses, and if those are equal, it compares symbol names.  If
75 * those are equal, too, the symbols are considered equal.  */
76int library_symbol_cmp(struct library_symbol *a, struct library_symbol *b);
77
78/* A function that can be used as library_each_symbol callback.  Looks
79 * for a symbol SYM for which library_symbol_cmp(SYM, STANDARD)
80 * returns 0.  */
81enum callback_status library_symbol_equal_cb(struct library_symbol *libsym,
82					     void *standard);
83
84/* XXX we might consider sharing libraries across processes.  Things
85 * like libc will be opened by every single process, no point cloning
86 * these everywhere.  But for now, keep the ownership structure
87 * simple.  */
88struct library {
89	struct library *next;
90
91	/* Address where the library is mapped.  Two library objects
92	 * are considered equal, if they have the same base.  */
93	target_address_t base;
94
95	/* Absolute address of the entry point.  Useful for main
96	 * binary, though I the value might be useful for the dynamic
97	 * linker, too (in case we ever want to do early process
98	 * tracing).  */
99	target_address_t entry;
100
101	/* Symbols associated with the library.  */
102	struct library_symbol *symbols;
103	const char *name;
104	char own_name;
105};
106
107/* Init LIB.  NAME will be freed when LIB is destroyed if
108 * OWN_NAME.  */
109void library_init(struct library *lib, const char *name, int own_name);
110
111/* Initialize RETP to a library identical to LIB.  Symbols are not
112 * shared, but copied over.  Returns 0 on success and a negative value
113 * in case of failure.  */
114int library_clone(struct library *retp, struct library *lib);
115
116/* Destroy library.  Doesn't free LIB itself.  */
117void library_destroy(struct library *lib);
118
119/* Set library name.  Frees the old name if necessary.  */
120void library_set_name(struct library *lib, const char *new_name, int own_name);
121
122/* Iterate through list of symbols of library LIB.  Restarts are
123 * supported via START (see each_process for details of iteration
124 * interface).  */
125struct library_symbol *library_each_symbol
126	(struct library *lib, struct library_symbol *start,
127	 enum callback_status (*cb)(struct library_symbol *, void *),
128	 void *data);
129
130/* Add a new symbol SYM to LIB.  SYM is assumed owned, we need to
131 * overwrite SYM->next.  */
132void library_add_symbol(struct library *lib, struct library_symbol *sym);
133
134/* A function that can be used as proc_each_library callback.  Looks
135 * for a library with the name passed in DATA.  PROC is ignored.  */
136enum callback_status library_named_cb(struct Process *proc,
137				      struct library *lib, void *name);
138
139/* A function that can be used as proc_each_library callback.  Looks
140 * for a library with given base.
141 *
142 * NOTE: The base is passed as a POINTER to target_address_t (that
143 * because in general, target_address_t doesn't fit in void*). */
144enum callback_status library_with_base_cb(struct Process *proc,
145					  struct library *lib, void *basep);
146
147#endif /* _LIBRARY_H_ */
148