3014634511977e2ee5bf53759ffdd0cc40df5359
[platform/upstream/elfutils.git] / libebl / libebl.h
1 /* Interface for libebl.
2    Copyright (C) 2000, 2001, 2002, 2004, 2005, 2006 Red Hat, Inc.
3    This file is part of Red Hat elfutils.
4
5    Red Hat elfutils is free software; you can redistribute it and/or modify
6    it under the terms of the GNU General Public License as published by the
7    Free Software Foundation; version 2 of the License.
8
9    Red Hat elfutils is distributed in the hope that it will be useful, but
10    WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12    General Public License for more details.
13
14    You should have received a copy of the GNU General Public License along
15    with Red Hat elfutils; if not, write to the Free Software Foundation,
16    Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA.
17
18    In addition, as a special exception, Red Hat, Inc. gives You the
19    additional right to link the code of Red Hat elfutils with code licensed
20    under any Open Source Initiative certified open source license
21    (http://www.opensource.org/licenses/index.php) which requires the
22    distribution of source code with any binary distribution and to
23    distribute linked combinations of the two.  Non-GPL Code permitted under
24    this exception must only link to the code of Red Hat elfutils through
25    those well defined interfaces identified in the file named EXCEPTION
26    found in the source code files (the "Approved Interfaces").  The files
27    of Non-GPL Code may instantiate templates or use macros or inline
28    functions from the Approved Interfaces without causing the resulting
29    work to be covered by the GNU General Public License.  Only Red Hat,
30    Inc. may make changes or additions to the list of Approved Interfaces.
31    Red Hat's grant of this exception is conditioned upon your not adding
32    any new exceptions.  If you wish to add a new Approved Interface or
33    exception, please contact Red Hat.  You must obey the GNU General Public
34    License in all respects for all of the Red Hat elfutils code and other
35    code used in conjunction with Red Hat elfutils except the Non-GPL Code
36    covered by this exception.  If you modify this file, you may extend this
37    exception to your version of the file, but you are not obligated to do
38    so.  If you do not wish to provide this exception without modification,
39    you must delete this exception statement from your version and license
40    this file solely under the GPL without exception.
41
42    Red Hat elfutils is an included package of the Open Invention Network.
43    An included package of the Open Invention Network is a package for which
44    Open Invention Network licensees cross-license their patents.  No patent
45    license is granted, either expressly or impliedly, by designation as an
46    included package.  Should you wish to participate in the Open Invention
47    Network licensing program, please visit www.openinventionnetwork.com
48    <http://www.openinventionnetwork.com>.  */
49
50 #ifndef _LIBEBL_H
51 #define _LIBEBL_H 1
52
53 #include <gelf.h>
54 #include "libdw.h"
55 #include <stdbool.h>
56 #include <stddef.h>
57 #include <stdint.h>
58
59 #include "elf-knowledge.h"
60
61
62 /* Opaque type for the handle.  */
63 typedef struct ebl Ebl;
64
65
66 #ifdef __cplusplus
67 extern "C" {
68 #endif
69
70 /* Get backend handle for object associated with ELF handle.  */
71 extern Ebl *ebl_openbackend (Elf *elf);
72 /* Similar but without underlying ELF file.  */
73 extern Ebl *ebl_openbackend_machine (GElf_Half machine);
74 /* Similar but with emulation name given.  */
75 extern Ebl *ebl_openbackend_emulation (const char *emulation);
76
77 /* Free resources allocated for backend handle.  */
78 extern void ebl_closebackend (Ebl *bh);
79
80
81 /* Information about the descriptor.  */
82
83 /* Get ELF machine.  */
84 extern int ebl_get_elfmachine (Ebl *ebl) __attribute__ ((__pure__));
85
86 /* Get ELF class.  */
87 extern int ebl_get_elfclass (Ebl *ebl) __attribute__ ((__pure__));
88
89 /* Get ELF data encoding.  */
90 extern int ebl_get_elfdata (Ebl *ebl) __attribute__ ((__pure__));
91
92
93 /* Function to call the callback functions including default ELF
94    handling.  */
95
96 /* Return backend name.  */
97 extern const char *ebl_backend_name (Ebl *ebl);
98
99 /* Return relocation type name.  */
100 extern const char *ebl_object_type_name (Ebl *ebl, int object,
101                                          char *buf, size_t len);
102
103 /* Return relocation type name.  */
104 extern const char *ebl_reloc_type_name (Ebl *ebl, int reloc,
105                                         char *buf, size_t len);
106
107 /* Check relocation type.  */
108 extern bool ebl_reloc_type_check (Ebl *ebl, int reloc);
109
110 /* Check relocation type use.  */
111 extern bool ebl_reloc_valid_use (Ebl *ebl, int reloc);
112
113 /* Check if relocation type is for simple absolute relocations.
114    Return ELF_T_{BYTE,HALF,SWORD,SXWORD} for a simple type, else ELF_T_NUM.  */
115 extern Elf_Type ebl_reloc_simple_type (Ebl *ebl, int reloc);
116
117 /* Return true if the symbol type is that referencing the GOT.  E.g.,
118    R_386_GOTPC.  */
119 extern bool ebl_gotpc_reloc_check (Ebl *ebl, int reloc);
120
121 /* Return segment type name.  */
122 extern const char *ebl_segment_type_name (Ebl *ebl, int segment,
123                                           char *buf, size_t len);
124
125 /* Return section type name.  */
126 extern const char *ebl_section_type_name (Ebl *ebl, int section,
127                                           char *buf, size_t len);
128
129 /* Return section name.  */
130 extern const char *ebl_section_name (Ebl *ebl, int section, int xsection,
131                                      char *buf, size_t len,
132                                      const char *scnnames[], size_t shnum);
133
134 /* Return machine flag names.  */
135 extern const char *ebl_machine_flag_name (Ebl *ebl, GElf_Word flags,
136                                           char *buf, size_t len);
137
138 /* Check whether machine flag is valid.  */
139 extern bool ebl_machine_flag_check (Ebl *ebl, GElf_Word flags);
140
141 /* Return symbol type name.  */
142 extern const char *ebl_symbol_type_name (Ebl *ebl, int symbol,
143                                          char *buf, size_t len);
144
145 /* Return symbol binding name.  */
146 extern const char *ebl_symbol_binding_name (Ebl *ebl, int binding,
147                                             char *buf, size_t len);
148
149 /* Return dynamic tag name.  */
150 extern const char *ebl_dynamic_tag_name (Ebl *ebl, int64_t tag,
151                                          char *buf, size_t len);
152
153 /* Check dynamic tag.  */
154 extern bool ebl_dynamic_tag_check (Ebl *ebl, int64_t tag);
155
156 /* Check whether given symbol's st_value and st_size are OK despite failing
157    normal checks.  */
158 extern bool ebl_check_special_symbol (Ebl *ebl, GElf_Ehdr *ehdr,
159                                       const GElf_Sym *sym, const char *name,
160                                       const GElf_Shdr *destshdr);
161
162 /* Return combined section header flags value.  */
163 extern GElf_Word ebl_sh_flags_combine (Ebl *ebl, GElf_Word flags1,
164                                        GElf_Word flags2);
165
166 /* Return symbolic representation of OS ABI.  */
167 extern const char *ebl_osabi_name (Ebl *ebl, int osabi, char *buf, size_t len);
168
169
170 /* Return name of the note section type for a core file.  */
171 extern const char *ebl_core_note_type_name (Ebl *ebl, uint32_t type, char *buf,
172                                             size_t len);
173
174 /* Return name of the note section type for an object file.  */
175 extern const char *ebl_object_note_type_name (Ebl *ebl, uint32_t type,
176                                               char *buf, size_t len);
177
178 /* Print information about core note if available.  */
179 extern void ebl_core_note (Ebl *ebl, const char *name, uint32_t type,
180                            uint32_t descsz, const char *desc);
181
182 /* Print information about object note if available.  */
183 extern void ebl_object_note (Ebl *ebl, const char *name, uint32_t type,
184                              uint32_t descsz, const char *desc);
185
186 /* Check section name for being that of a debug informatino section.  */
187 extern bool ebl_debugscn_p (Ebl *ebl, const char *name);
188
189 /* Check whether given relocation is a copy relocation.  */
190 extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc);
191
192 /* Check whether section should be stripped.  */
193 extern bool ebl_section_strip_p (Ebl *ebl, const GElf_Ehdr *ehdr,
194                                  const GElf_Shdr *shdr, const char *name,
195                                  bool remove_comment, bool only_remove_debug);
196
197 /* Check if backend uses a bss PLT in this file.  */
198 extern bool ebl_bss_plt_p (Ebl *ebl, GElf_Ehdr *ehdr);
199
200 /* Return location expression to find return value given a
201    DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
202    function itself (whose DW_AT_type attribute describes its return type).
203    Returns -1 for a libdw error (see dwarf_errno).
204    Returns -2 for an unrecognized type formation.
205    Returns zero if the function has no return value (e.g. "void" in C).
206    Otherwise, *LOCOPS gets a location expression to find the return value,
207    and returns the number of operations in the expression.  The pointer is
208    permanently allocated at least as long as the Ebl handle is open.  */
209 extern int ebl_return_value_location (Ebl *ebl,
210                                       Dwarf_Die *functypedie,
211                                       const Dwarf_Op **locops);
212
213 /* Fill in register name information given DWARF register numbers.
214    If NAME is null, return the maximum REGNO + 1 that has a name.
215    Otherwise, store in NAME the name for DWARF register number REGNO
216    and return the number of bytes written (including '\0' terminator).
217    Return -1 if NAMELEN is too short or REGNO is negative or too large.
218    Return 0 if REGNO is unused (a gap in the DWARF number assignment).
219    On success, set *SETNAME to a description like "integer" or "FPU"
220    fit for "%s registers" title display, and *PREFIX to the string
221    that precedes NAME in canonical assembler syntax (e.g. "%" or "$").
222    The NAME string contains identifier characters only (maybe just digits).  */
223 extern ssize_t ebl_register_name (Ebl *ebl,
224                                   int regno, char *name, size_t namelen,
225                                   const char **prefix, const char **setname);
226
227
228 /* ELF string table handling.  */
229 struct Ebl_Strtab;
230 struct Ebl_Strent;
231
232 /* Create new ELF string table object in memory.  */
233 extern struct Ebl_Strtab *ebl_strtabinit (bool nullstr);
234
235 /* Free resources allocated for ELF string table ST.  */
236 extern void ebl_strtabfree (struct Ebl_Strtab *st);
237
238 /* Add string STR (length LEN is != 0) to ELF string table ST.  */
239 extern struct Ebl_Strent *ebl_strtabadd (struct Ebl_Strtab *st,
240                                          const char *str, size_t len);
241
242 /* Finalize string table ST and store size and memory location information
243    in DATA.  */
244 extern void ebl_strtabfinalize (struct Ebl_Strtab *st, Elf_Data *data);
245
246 /* Get offset in string table for string associated with SE.  */
247 extern size_t ebl_strtaboffset (struct Ebl_Strent *se);
248
249 /* Return the string associated with SE.  */
250 extern const char *ebl_string (struct Ebl_Strent *se);
251
252
253 /* ELF wide char string table handling.  */
254 struct Ebl_WStrtab;
255 struct Ebl_WStrent;
256
257 /* Create new ELF wide char string table object in memory.  */
258 extern struct Ebl_WStrtab *ebl_wstrtabinit (bool nullstr);
259
260 /* Free resources allocated for ELF wide char string table ST.  */
261 extern void ebl_wstrtabfree (struct Ebl_WStrtab *st);
262
263 /* Add string STR (length LEN is != 0) to ELF string table ST.  */
264 extern struct Ebl_WStrent *ebl_wstrtabadd (struct Ebl_WStrtab *st,
265                                            const wchar_t *str, size_t len);
266
267 /* Finalize string table ST and store size and memory location information
268    in DATA.  */
269 extern void ebl_wstrtabfinalize (struct Ebl_WStrtab *st, Elf_Data *data);
270
271 /* Get offset in wide char string table for string associated with SE.  */
272 extern size_t ebl_wstrtaboffset (struct Ebl_WStrent *se);
273
274
275 /* Generic string table handling.  */
276 struct Ebl_GStrtab;
277 struct Ebl_GStrent;
278
279 /* Create new string table object in memory.  */
280 extern struct Ebl_GStrtab *ebl_gstrtabinit (unsigned int width, bool nullstr);
281
282 /* Free resources allocated for string table ST.  */
283 extern void ebl_gstrtabfree (struct Ebl_GStrtab *st);
284
285 /* Add string STR (length LEN is != 0) to string table ST.  */
286 extern struct Ebl_GStrent *ebl_gstrtabadd (struct Ebl_GStrtab *st,
287                                            const char *str, size_t len);
288
289 /* Finalize string table ST and store size and memory location information
290    in DATA.  */
291 extern void ebl_gstrtabfinalize (struct Ebl_GStrtab *st, Elf_Data *data);
292
293 /* Get offset in wide char string table for string associated with SE.  */
294 extern size_t ebl_gstrtaboffset (struct Ebl_GStrent *se);
295
296 #ifdef __cplusplus
297 }
298 #endif
299
300 #endif  /* libebl.h */