libebl.h revision 361df7da6dfecd817b27e62b91752ac316d7cdd4 
1/* Interface for libebl.
2   Copyright (C) 2000, 2001, 2002, 2004, 2005 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 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.  */
63typedef struct ebl Ebl;
64
65
66/* Get backend handle for object associated with ELF handle.  */
67extern Ebl *ebl_openbackend (Elf *elf);
68/* Similar but without underlying ELF file.  */
69extern Ebl *ebl_openbackend_machine (GElf_Half machine);
70/* Similar but with emulation name given.  */
71extern Ebl *ebl_openbackend_emulation (const char *emulation);
72
73/* Free resources allocated for backend handle.  */
74extern void ebl_closebackend (Ebl *bh);
75
76
77/* Information about the descriptor.  */
78
79/* Get ELF machine.  */
80extern int ebl_get_elfmachine (Ebl *ebl) __attribute__ ((__pure__));
81
82/* Get ELF class.  */
83extern int ebl_get_elfclass (Ebl *ebl) __attribute__ ((__pure__));
84
85/* Get ELF data encoding.  */
86extern int ebl_get_elfdata (Ebl *ebl) __attribute__ ((__pure__));
87
88
89/* Function to call the callback functions including default ELF
90   handling.  */
91
92/* Return backend name.  */
93extern const char *ebl_backend_name (Ebl *ebl);
94
95/* Return relocation type name.  */
96extern const char *ebl_object_type_name (Ebl *ebl, int object,
97					 char *buf, size_t len);
98
99/* Return relocation type name.  */
100extern const char *ebl_reloc_type_name (Ebl *ebl, int reloc,
101					char *buf, size_t len);
102
103/* Check relocation type.  */
104extern bool ebl_reloc_type_check (Ebl *ebl, int reloc);
105
106/* Check relocation type use.  */
107extern bool ebl_reloc_valid_use (Ebl *ebl, int reloc);
108
109/* Check if relocation type is for simple absolute relocations.
110   Return ELF_T_{BYTE,HALF,SWORD,SXWORD} for a simple type, else ELF_T_NUM.  */
111extern Elf_Type ebl_reloc_simple_type (Ebl *ebl, int reloc);
112
113/* Return true if the symbol type is that referencing the GOT.  E.g.,
114   R_386_GOTPC.  */
115extern bool ebl_gotpc_reloc_check (Ebl *ebl, int reloc);
116
117/* Return segment type name.  */
118extern const char *ebl_segment_type_name (Ebl *ebl, int segment,
119					  char *buf, size_t len);
120
121/* Return section type name.  */
122extern const char *ebl_section_type_name (Ebl *ebl, int section,
123					  char *buf, size_t len);
124
125/* Return section name.  */
126extern const char *ebl_section_name (Ebl *ebl, int section, int xsection,
127				     char *buf, size_t len,
128				     const char *scnnames[], size_t shnum);
129
130/* Return machine flag names.  */
131extern const char *ebl_machine_flag_name (Ebl *ebl, GElf_Word flags,
132					  char *buf, size_t len);
133
134/* Check whether machine flag is valid.  */
135extern bool ebl_machine_flag_check (Ebl *ebl, GElf_Word flags);
136
137/* Return symbol type name.  */
138extern const char *ebl_symbol_type_name (Ebl *ebl, int symbol,
139					 char *buf, size_t len);
140
141/* Return symbol binding name.  */
142extern const char *ebl_symbol_binding_name (Ebl *ebl, int binding,
143					    char *buf, size_t len);
144
145/* Return dynamic tag name.  */
146extern const char *ebl_dynamic_tag_name (Ebl *ebl, int64_t tag,
147					 char *buf, size_t len);
148
149/* Check dynamic tag.  */
150extern bool ebl_dynamic_tag_check (Ebl *ebl, int64_t tag);
151
152/* Check whether given symbol's st_value and st_size are OK despite failing
153   normal checks.  */
154extern bool ebl_check_special_symbol (Ebl *ebl, GElf_Ehdr *ehdr,
155				      const GElf_Sym *sym, const char *name,
156				      const GElf_Shdr *destshdr);
157
158/* Return combined section header flags value.  */
159extern GElf_Word ebl_sh_flags_combine (Ebl *ebl, GElf_Word flags1,
160				       GElf_Word flags2);
161
162/* Return symbolic representation of OS ABI.  */
163extern const char *ebl_osabi_name (Ebl *ebl, int osabi, char *buf, size_t len);
164
165
166/* Return name of the note section type for a core file.  */
167extern const char *ebl_core_note_type_name (Ebl *ebl, uint32_t type, char *buf,
168					    size_t len);
169
170/* Return name of the note section type for an object file.  */
171extern const char *ebl_object_note_type_name (Ebl *ebl, uint32_t type,
172					      char *buf, size_t len);
173
174/* Print information about core note if available.  */
175extern void ebl_core_note (Ebl *ebl, const char *name, uint32_t type,
176			   uint32_t descsz, const char *desc);
177
178/* Print information about object note if available.  */
179extern void ebl_object_note (Ebl *ebl, const char *name, uint32_t type,
180			     uint32_t descsz, const char *desc);
181
182/* Check section name for being that of a debug informatino section.  */
183extern bool ebl_debugscn_p (Ebl *ebl, const char *name);
184
185/* Check whether given relocation is a copy relocation.  */
186extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc);
187
188/* Check whether section should be stripped.  */
189extern bool ebl_section_strip_p (Ebl *ebl, const GElf_Ehdr *ehdr,
190				 const GElf_Shdr *shdr, const char *name,
191				 bool remove_comment, bool only_remove_debug);
192
193/* Check if backend uses a bss PLT in this file.  */
194extern bool ebl_bss_plt_p (Ebl *ebl, GElf_Ehdr *ehdr);
195
196/* Return location expression to find return value given a
197   DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
198   function itself (whose DW_AT_type attribute describes its return type).
199   Returns -1 for a libdw error (see dwarf_errno).
200   Returns -2 for an unrecognized type formation.
201   Returns zero if the function has no return value (e.g. "void" in C).
202   Otherwise, *LOCOPS gets a location expression to find the return value,
203   and returns the number of operations in the expression.  The pointer is
204   permanently allocated at least as long as the Ebl handle is open.  */
205extern int ebl_return_value_location (Ebl *ebl,
206				      Dwarf_Die *functypedie,
207				      const Dwarf_Op **locops);
208
209/* Fill in register name information given DWARF register numbers.
210   If NAME is null, return the maximum REGNO + 1 that has a name.
211   Otherwise, store in NAME the name for DWARF register number REGNO
212   and return the number of bytes written (including '\0' terminator).
213   Return -1 if NAMELEN is too short or REGNO is negative or too large.
214   Return 0 if REGNO is unused (a gap in the DWARF number assignment).
215   On success, set *SETNAME to a description like "integer" or "FPU"
216   fit for "%s registers" title display, and *PREFIX to the string
217   that precedes NAME in canonical assembler syntax (e.g. "%" or "$").
218   The NAME string contains identifier characters only (maybe just digits).  */
219extern ssize_t ebl_register_name (Ebl *ebl,
220				  int regno, char *name, size_t namelen,
221				  const char **prefix, const char **setname);
222
223
224/* ELF string table handling.  */
225struct Ebl_Strtab;
226struct Ebl_Strent;
227
228/* Create new ELF string table object in memory.  */
229extern struct Ebl_Strtab *ebl_strtabinit (bool nullstr);
230
231/* Free resources allocated for ELF string table ST.  */
232extern void ebl_strtabfree (struct Ebl_Strtab *st);
233
234/* Add string STR (length LEN is != 0) to ELF string table ST.  */
235extern struct Ebl_Strent *ebl_strtabadd (struct Ebl_Strtab *st,
236					 const char *str, size_t len);
237
238/* Finalize string table ST and store size and memory location information
239   in DATA.  */
240extern void ebl_strtabfinalize (struct Ebl_Strtab *st, Elf_Data *data);
241
242/* Get offset in string table for string associated with SE.  */
243extern size_t ebl_strtaboffset (struct Ebl_Strent *se);
244
245/* Return the string associated with SE.  */
246extern const char *ebl_string (struct Ebl_Strent *se);
247
248
249/* ELF wide char string table handling.  */
250struct Ebl_WStrtab;
251struct Ebl_WStrent;
252
253/* Create new ELF wide char string table object in memory.  */
254extern struct Ebl_WStrtab *ebl_wstrtabinit (bool nullstr);
255
256/* Free resources allocated for ELF wide char string table ST.  */
257extern void ebl_wstrtabfree (struct Ebl_WStrtab *st);
258
259/* Add string STR (length LEN is != 0) to ELF string table ST.  */
260extern struct Ebl_WStrent *ebl_wstrtabadd (struct Ebl_WStrtab *st,
261					   const wchar_t *str, size_t len);
262
263/* Finalize string table ST and store size and memory location information
264   in DATA.  */
265extern void ebl_wstrtabfinalize (struct Ebl_WStrtab *st, Elf_Data *data);
266
267/* Get offset in wide char string table for string associated with SE.  */
268extern size_t ebl_wstrtaboffset (struct Ebl_WStrent *se);
269
270
271/* Generic string table handling.  */
272struct Ebl_GStrtab;
273struct Ebl_GStrent;
274
275/* Create new string table object in memory.  */
276extern struct Ebl_GStrtab *ebl_gstrtabinit (unsigned int width, bool nullstr);
277
278/* Free resources allocated for string table ST.  */
279extern void ebl_gstrtabfree (struct Ebl_GStrtab *st);
280
281/* Add string STR (length LEN is != 0) to string table ST.  */
282extern struct Ebl_GStrent *ebl_gstrtabadd (struct Ebl_GStrtab *st,
283					   const char *str, size_t len);
284
285/* Finalize string table ST and store size and memory location information
286   in DATA.  */
287extern void ebl_gstrtabfinalize (struct Ebl_GStrtab *st, Elf_Data *data);
288
289/* Get offset in wide char string table for string associated with SE.  */
290extern size_t ebl_gstrtaboffset (struct Ebl_GStrent *se);
291
292#endif	/* libebl.h */
293