libelf.h revision 3cbdd387c752999255aea91600b5cfdefbeac7d0 
1/* Interface for libelf.
2   Copyright (C) 1998, 1999, 2000, 2002, 2004, 2005, 2006, 2007 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 _LIBELF_H
51#define _LIBELF_H 1
52
53#include <sys/types.h>
54
55/* Get the ELF types.  */
56#include <elf.h>
57
58
59/* Known translation types.  */
60typedef enum
61{
62  ELF_T_BYTE,                   /* unsigned char */
63  ELF_T_ADDR,                   /* Elf32_Addr, Elf64_Addr, ... */
64  ELF_T_DYN,                    /* Dynamic section record.  */
65  ELF_T_EHDR,                   /* ELF header.  */
66  ELF_T_HALF,                   /* Elf32_Half, Elf64_Half, ... */
67  ELF_T_OFF,                    /* Elf32_Off, Elf64_Off, ... */
68  ELF_T_PHDR,                   /* Program header.  */
69  ELF_T_RELA,                   /* Relocation entry with addend.  */
70  ELF_T_REL,                    /* Relocation entry.  */
71  ELF_T_SHDR,                   /* Section header.  */
72  ELF_T_SWORD,                  /* Elf32_Sword, Elf64_Sword, ... */
73  ELF_T_SYM,                    /* Symbol record.  */
74  ELF_T_WORD,                   /* Elf32_Word, Elf64_Word, ... */
75  ELF_T_XWORD,                  /* Elf32_Xword, Elf64_Xword, ... */
76  ELF_T_SXWORD,                 /* Elf32_Sxword, Elf64_Sxword, ... */
77  ELF_T_VDEF,                   /* Elf32_Verdef, Elf64_Verdef, ... */
78  ELF_T_VDAUX,                  /* Elf32_Verdaux, Elf64_Verdaux, ... */
79  ELF_T_VNEED,                  /* Elf32_Verneed, Elf64_Verneed, ... */
80  ELF_T_VNAUX,                  /* Elf32_Vernaux, Elf64_Vernaux, ... */
81  ELF_T_NHDR,                   /* Elf32_Nhdr, Elf64_Nhdr, ... */
82  ELF_T_SYMINFO,		/* Elf32_Syminfo, Elf64_Syminfo, ... */
83  ELF_T_MOVE,			/* Elf32_Move, Elf64_Move, ... */
84  ELF_T_LIB,			/* Elf32_Lib, Elf64_Lib, ... */
85  ELF_T_GNUHASH,		/* GNU-style hash section.  */
86  ELF_T_AUXV,			/* Elf32_auxv_t, Elf64_auxv_t, ... */
87  /* Keep this the last entry.  */
88  ELF_T_NUM
89} Elf_Type;
90
91/* Descriptor for data to be converted to or from memory format.  */
92typedef struct
93{
94  void *d_buf;			/* Pointer to the actual data.  */
95  Elf_Type d_type;		/* Type of this piece of data.  */
96  unsigned int d_version;	/* ELF version.  */
97  size_t d_size;		/* Size in bytes.  */
98  loff_t d_off;		/* Offset into section.  */
99  size_t d_align;		/* Alignment in section.  */
100} Elf_Data;
101
102
103/* Commands for `...'.  */
104typedef enum
105{
106  ELF_C_NULL,			/* Nothing, terminate, or compute only.  */
107  ELF_C_READ,			/* Read .. */
108  ELF_C_RDWR,			/* Read and write .. */
109  ELF_C_WRITE,			/* Write .. */
110  ELF_C_CLR,			/* Clear flag.  */
111  ELF_C_SET,			/* Set flag.  */
112  ELF_C_FDDONE,			/* Signal that file descriptor will not be
113				   used anymore.  */
114  ELF_C_FDREAD,			/* Read rest of data so that file descriptor
115				   is not used anymore.  */
116  /* The following are extensions.  */
117  ELF_C_READ_MMAP,		/* Read, but mmap the file if possible.  */
118  ELF_C_RDWR_MMAP,		/* Read and write, with mmap.  */
119  ELF_C_WRITE_MMAP,		/* Write, with mmap.  */
120  ELF_C_READ_MMAP_PRIVATE,	/* Read, but memory is writable, results are
121				   not written to the file.  */
122  ELF_C_EMPTY,			/* Copy basic file data but not the content. */
123  /* Keep this the last entry.  */
124  ELF_C_NUM
125} Elf_Cmd;
126
127
128/* Flags for the ELF structures.  */
129enum
130{
131  ELF_F_DIRTY = 0x1,
132#define ELF_F_DIRTY		ELF_F_DIRTY
133  ELF_F_LAYOUT = 0x4,
134#define ELF_F_LAYOUT		ELF_F_LAYOUT
135  ELF_F_PERMISSIVE = 0x8
136#define ELF_F_PERMISSIVE	ELF_F_PERMISSIVE
137};
138
139
140/* Identification values for recognized object files.  */
141typedef enum
142{
143  ELF_K_NONE,			/* Unknown.  */
144  ELF_K_AR,			/* Archive.  */
145  ELF_K_COFF,			/* Stupid old COFF.  */
146  ELF_K_ELF,			/* ELF file.  */
147  /* Keep this the last entry.  */
148  ELF_K_NUM
149} Elf_Kind;
150
151
152/* Archive member header.  */
153typedef struct
154{
155  char *ar_name;		/* Name of archive member.  */
156  time_t ar_date;		/* File date.  */
157  uid_t ar_uid;			/* User ID.  */
158  gid_t ar_gid;			/* Group ID.  */
159  mode_t ar_mode;		/* File mode.  */
160  loff_t ar_size;		/* File size.  */
161  char *ar_rawname;		/* Original name of archive member.  */
162} Elf_Arhdr;
163
164
165/* Archive symbol table entry.  */
166typedef struct
167{
168  char *as_name;		/* Symbol name.  */
169  size_t as_off;		/* Offset for this file in the archive.  */
170  unsigned long int as_hash;	/* Hash value of the name.  */
171} Elf_Arsym;
172
173
174/* Descriptor for the ELF file.  */
175typedef struct Elf Elf;
176
177/* Descriptor for ELF file section.  */
178typedef struct Elf_Scn Elf_Scn;
179
180
181#ifdef __cplusplus
182extern "C" {
183#endif
184
185/* Return descriptor for ELF file to work according to CMD.  */
186extern Elf *elf_begin (int __fildes, Elf_Cmd __cmd, Elf *__ref);
187
188/* Create a clone of an existing ELF descriptor.  */
189  extern Elf *elf_clone (Elf *__elf, Elf_Cmd __cmd);
190
191/* Create descriptor for memory region.  */
192extern Elf *elf_memory (char *__image, size_t __size);
193
194/* Advance archive descriptor to next element.  */
195extern Elf_Cmd elf_next (Elf *__elf);
196
197/* Free resources allocated for ELF.  */
198extern int elf_end (Elf *__elf);
199
200/* Update ELF descriptor and write file to disk.  */
201extern loff_t elf_update (Elf *__elf, Elf_Cmd __cmd);
202
203/* Determine what kind of file is associated with ELF.  */
204extern Elf_Kind elf_kind (Elf *__elf) __attribute__ ((__pure__));
205
206/* Get the base offset for an object file.  */
207extern loff_t elf_getbase (Elf *__elf);
208
209
210/* Retrieve file identification data.  */
211extern char *elf_getident (Elf *__elf, size_t *__nbytes);
212
213/* Retrieve class-dependent object file header.  */
214extern Elf32_Ehdr *elf32_getehdr (Elf *__elf);
215/* Similar but this time the binary calls is ELFCLASS64.  */
216extern Elf64_Ehdr *elf64_getehdr (Elf *__elf);
217
218/* Create ELF header if none exists.  */
219extern Elf32_Ehdr *elf32_newehdr (Elf *__elf);
220/* Similar but this time the binary calls is ELFCLASS64.  */
221extern Elf64_Ehdr *elf64_newehdr (Elf *__elf);
222
223/* Retrieve class-dependent program header table.  */
224extern Elf32_Phdr *elf32_getphdr (Elf *__elf);
225/* Similar but this time the binary calls is ELFCLASS64.  */
226extern Elf64_Phdr *elf64_getphdr (Elf *__elf);
227
228/* Create ELF program header.  */
229extern Elf32_Phdr *elf32_newphdr (Elf *__elf, size_t __cnt);
230/* Similar but this time the binary calls is ELFCLASS64.  */
231extern Elf64_Phdr *elf64_newphdr (Elf *__elf, size_t __cnt);
232
233
234/* Get section at INDEX.  */
235extern Elf_Scn *elf_getscn (Elf *__elf, size_t __index);
236
237/* Get section at OFFSET.  */
238extern Elf_Scn *elf32_offscn (Elf *__elf, Elf32_Off __offset);
239/* Similar bug this time the binary calls is ELFCLASS64.  */
240extern Elf_Scn *elf64_offscn (Elf *__elf, Elf64_Off __offset);
241
242/* Get index of section.  */
243extern size_t elf_ndxscn (Elf_Scn *__scn);
244
245/* Get section with next section index.  */
246extern Elf_Scn *elf_nextscn (Elf *__elf, Elf_Scn *__scn);
247
248/* Create a new section and append it at the end of the table.  */
249extern Elf_Scn *elf_newscn (Elf *__elf);
250
251/* Get the section index of the extended section index table for the
252   given symbol table.  */
253extern int elf_scnshndx (Elf_Scn *__scn);
254
255/* Get the number of sections in the ELF file.  If the file uses more
256   sections than can be represented in the e_shnum field of the ELF
257   header the information from the sh_size field in the zeroth section
258   header is used.  */
259extern int elf_getshnum (Elf *__elf, size_t *__dst);
260
261
262/* Get the section index of the section header string table in the ELF
263   file.  If the index cannot be represented in the e_shnum field of
264   the ELF header the information from the sh_link field in the zeroth
265   section header is used.  */
266extern int elf_getshstrndx (Elf *__elf, size_t *__dst);
267
268
269/* Retrieve section header of ELFCLASS32 binary.  */
270extern Elf32_Shdr *elf32_getshdr (Elf_Scn *__scn);
271/* Similar for ELFCLASS64.  */
272extern Elf64_Shdr *elf64_getshdr (Elf_Scn *__scn);
273
274
275/* Set or clear flags for ELF file.  */
276extern unsigned int elf_flagelf (Elf *__elf, Elf_Cmd __cmd,
277				 unsigned int __flags);
278/* Similarly for the ELF header.  */
279extern unsigned int elf_flagehdr (Elf *__elf, Elf_Cmd __cmd,
280				  unsigned int __flags);
281/* Similarly for the ELF program header.  */
282extern unsigned int elf_flagphdr (Elf *__elf, Elf_Cmd __cmd,
283				  unsigned int __flags);
284/* Similarly for the given ELF section.  */
285extern unsigned int elf_flagscn (Elf_Scn *__scn, Elf_Cmd __cmd,
286				 unsigned int __flags);
287/* Similarly for the given ELF data.  */
288extern unsigned int elf_flagdata (Elf_Data *__data, Elf_Cmd __cmd,
289				  unsigned int __flags);
290/* Similarly for the given ELF section header.  */
291extern unsigned int elf_flagshdr (Elf_Scn *__scn, Elf_Cmd __cmd,
292				  unsigned int __flags);
293
294
295/* Get data from section while translating from file representation
296   to memory representation.  */
297extern Elf_Data *elf_getdata (Elf_Scn *__scn, Elf_Data *__data);
298
299/* Get uninterpreted section content.  */
300extern Elf_Data *elf_rawdata (Elf_Scn *__scn, Elf_Data *__data);
301
302/* Create new data descriptor for section SCN.  */
303extern Elf_Data *elf_newdata (Elf_Scn *__scn);
304
305/* Get data translated from a chunk of the file contents as section data
306   would be for TYPE.  The resulting Elf_Data pointer is valid until
307   elf_end (ELF) is called.  */
308extern Elf_Data *elf_getdata_rawchunk (Elf *__elf,
309				       loff_t __offset, size_t __size,
310				       Elf_Type __type);
311
312
313/* Return pointer to string at OFFSET in section INDEX.  */
314extern char *elf_strptr (Elf *__elf, size_t __index, size_t __offset);
315
316
317/* Return header of archive.  */
318extern Elf_Arhdr *elf_getarhdr (Elf *__elf);
319
320/* Return offset in archive for current file ELF.  */
321extern loff_t elf_getaroff (Elf *__elf);
322
323/* Select archive element at OFFSET.  */
324extern size_t elf_rand (Elf *__elf, size_t __offset);
325
326/* Get symbol table of archive.  */
327extern Elf_Arsym *elf_getarsym (Elf *__elf, size_t *__narsyms);
328
329
330/* Control ELF descriptor.  */
331extern int elf_cntl (Elf *__elf, Elf_Cmd __cmd);
332
333/* Retrieve uninterpreted file contents.  */
334extern char *elf_rawfile (Elf *__elf, size_t *__nbytes);
335
336
337/* Return size of array of COUNT elements of the type denoted by TYPE
338   in the external representation.  The binary class is taken from ELF.
339   The result is based on version VERSION of the ELF standard.  */
340extern size_t elf32_fsize (Elf_Type __type, size_t __count,
341			   unsigned int __version)
342       __attribute__ ((__const__));
343/* Similar but this time the binary calls is ELFCLASS64.  */
344extern size_t elf64_fsize (Elf_Type __type, size_t __count,
345			   unsigned int __version)
346       __attribute__ ((__const__));
347
348
349/* Convert data structure from the representation in the file represented
350   by ELF to their memory representation.  */
351extern Elf_Data *elf32_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
352				 unsigned int __encode);
353/* Same for 64 bit class.  */
354extern Elf_Data *elf64_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
355				 unsigned int __encode);
356
357/* Convert data structure from to the representation in memory
358   represented by ELF file representation.  */
359extern Elf_Data *elf32_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
360				 unsigned int __encode);
361/* Same for 64 bit class.  */
362extern Elf_Data *elf64_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
363				 unsigned int __encode);
364
365
366/* Return error code of last failing function call.  This value is kept
367   separately for each thread.  */
368extern int elf_errno (void);
369
370/* Return error string for ERROR.  If ERROR is zero, return error string
371   for most recent error or NULL is none occurred.  If ERROR is -1 the
372   behaviour is similar to the last case except that not NULL but a legal
373   string is returned.  */
374extern const char *elf_errmsg (int __error);
375
376
377/* Coordinate ELF library and application versions.  */
378extern unsigned int elf_version (unsigned int __version);
379
380/* Set fill bytes used to fill holes in data structures.  */
381extern void elf_fill (int __fill);
382
383/* Compute hash value.  */
384extern unsigned long int elf_hash (const char *__string)
385       __attribute__ ((__pure__));
386
387/* Compute hash value using the GNU-specific hash function.  */
388extern unsigned long int elf_gnu_hash (const char *__string)
389       __attribute__ ((__pure__));
390
391
392/* Compute simple checksum from permanent parts of the ELF file.  */
393extern long int elf32_checksum (Elf *__elf);
394/* Similar but this time the binary calls is ELFCLASS64.  */
395extern long int elf64_checksum (Elf *__elf);
396
397#ifdef __cplusplus
398}
399#endif
400
401#endif  /* libelf.h */
402