[go: up one dir, main page]
1/* Interface for libelf.
2 Copyright (C) 1998-2010, 2015 Red Hat, Inc.
3 This file is part of elfutils.
4
5 This file is free software; you can redistribute it and/or modify
6 it under the terms of either
7
8 * the GNU Lesser General Public License as published by the Free
9 Software Foundation; either version 3 of the License, or (at
10 your option) any later version
11
12 or
13
14 * the GNU General Public License as published by the Free
15 Software Foundation; either version 2 of the License, or (at
16 your option) any later version
17
18 or both in parallel, as here.
19
20 elfutils is distributed in the hope that it will be useful, but
21 WITHOUT ANY WARRANTY; without even the implied warranty of
22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23 General Public License for more details.
24
25 You should have received copies of the GNU General Public License and
26 the GNU Lesser General Public License along with this program. If
27 not, see <http://www.gnu.org/licenses/>. */
28
29#ifndef _LIBELF_H
30#define _LIBELF_H 1
31
32#include <stdint.h>
33#include <sys/types.h>
34
35/* Get the ELF types. */
36#include <elf.h>
37
38#ifndef SHF_COMPRESSED
39 /* Older glibc elf.h might not yet define the ELF compression types. */
40 #define SHF_COMPRESSED (1 << 11) /* Section with compressed data. */
41
42 /* Section compression header. Used when SHF_COMPRESSED is set. */
43
44 typedef struct
45 {
46 Elf32_Word ch_type; /* Compression format. */
47 Elf32_Word ch_size; /* Uncompressed data size. */
48 Elf32_Word ch_addralign; /* Uncompressed data alignment. */
49 } Elf32_Chdr;
50
51 typedef struct
52 {
53 Elf64_Word ch_type; /* Compression format. */
54 Elf64_Word ch_reserved;
55 Elf64_Xword ch_size; /* Uncompressed data size. */
56 Elf64_Xword ch_addralign; /* Uncompressed data alignment. */
57 } Elf64_Chdr;
58
59 /* Legal values for ch_type (compression algorithm). */
60 #define ELFCOMPRESS_ZLIB 1 /* ZLIB/DEFLATE algorithm. */
61 #define ELFCOMPRESS_LOOS 0x60000000 /* Start of OS-specific. */
62 #define ELFCOMPRESS_HIOS 0x6fffffff /* End of OS-specific. */
63 #define ELFCOMPRESS_LOPROC 0x70000000 /* Start of processor-specific. */
64 #define ELFCOMPRESS_HIPROC 0x7fffffff /* End of processor-specific. */
65#endif
66
67#ifndef ELFCOMPRESS_ZSTD
68 /* So ZSTD compression can be used even with an old system elf.h. */
69 #define ELFCOMPRESS_ZSTD 2 /* Zstandard algorithm. */
70#endif
71
72#ifndef SHT_RELR
73 /* So RELR defines/typedefs can be used even with an old system elf.h. */
74 #define SHT_RELR 19 /* RELR relative relocations */
75
76 /* RELR relocation table entry */
77 typedef Elf32_Word Elf32_Relr;
78 typedef Elf64_Xword Elf64_Relr;
79
80 #define DT_RELRSZ 35 /* Total size of RELR relative relocations */
81 #define DT_RELR 36 /* Address of RELR relative relocations */
82 #define DT_RELRENT 37 /* Size of one RELR relative relocaction */
83#endif
84
85#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
86# define __nonnull_attribute__(...) __attribute__ ((__nonnull__ (__VA_ARGS__)))
87# define __deprecated_attribute__ __attribute__ ((__deprecated__))
88# define __pure_attribute__ __attribute__ ((__pure__))
89# define __const_attribute__ __attribute__ ((__const__))
90#else
91# define __nonnull_attribute__(...)
92# define __deprecated_attribute__
93# define __pure_attribute__
94# define __const_attribute__
95#endif
96
97#if __GNUC__ < 4
98#define __noreturn_attribute__
99#else
100#define __noreturn_attribute__ __attribute__ ((noreturn))
101#endif
102
103#ifdef __GNUC_STDC_INLINE__
104# define __libdw_extern_inline extern __inline __attribute__ ((__gnu_inline__))
105#else
106# define __libdw_extern_inline extern __inline
107#endif
108
109/* Known translation types. */
110typedef enum
111{
112 ELF_T_BYTE, /* unsigned char */
113 ELF_T_ADDR, /* Elf32_Addr, Elf64_Addr, ... */
114 ELF_T_DYN, /* Dynamic section record. */
115 ELF_T_EHDR, /* ELF header. */
116 ELF_T_HALF, /* Elf32_Half, Elf64_Half, ... */
117 ELF_T_OFF, /* Elf32_Off, Elf64_Off, ... */
118 ELF_T_PHDR, /* Program header. */
119 ELF_T_RELA, /* Relocation entry with addend. */
120 ELF_T_REL, /* Relocation entry. */
121 ELF_T_SHDR, /* Section header. */
122 ELF_T_SWORD, /* Elf32_Sword, Elf64_Sword, ... */
123 ELF_T_SYM, /* Symbol record. */
124 ELF_T_WORD, /* Elf32_Word, Elf64_Word, ... */
125 ELF_T_XWORD, /* Elf32_Xword, Elf64_Xword, ... */
126 ELF_T_SXWORD, /* Elf32_Sxword, Elf64_Sxword, ... */
127 ELF_T_VDEF, /* Elf32_Verdef, Elf64_Verdef, ... */
128 ELF_T_VDAUX, /* Elf32_Verdaux, Elf64_Verdaux, ... */
129 ELF_T_VNEED, /* Elf32_Verneed, Elf64_Verneed, ... */
130 ELF_T_VNAUX, /* Elf32_Vernaux, Elf64_Vernaux, ... */
131 ELF_T_NHDR, /* Elf32_Nhdr, Elf64_Nhdr, ... */
132 ELF_T_SYMINFO, /* Elf32_Syminfo, Elf64_Syminfo, ... */
133 ELF_T_MOVE, /* Elf32_Move, Elf64_Move, ... */
134 ELF_T_LIB, /* Elf32_Lib, Elf64_Lib, ... */
135 ELF_T_GNUHASH, /* GNU-style hash section. */
136 ELF_T_AUXV, /* Elf32_auxv_t, Elf64_auxv_t, ... */
137 ELF_T_CHDR, /* Compressed, Elf32_Chdr, Elf64_Chdr, ... */
138 ELF_T_NHDR8, /* Special GNU Properties note. Same as Nhdr,
139 except padding. */
140 ELF_T_RELR, /* Relative relocation entry. */
141 /* Keep this the last entry. */
142 ELF_T_NUM
143} Elf_Type;
144
145/* Descriptor for data to be converted to or from memory format. */
146typedef struct
147{
148 void *d_buf; /* Pointer to the actual data. */
149 Elf_Type d_type; /* Type of this piece of data. */
150 unsigned int d_version; /* ELF version. */
151 size_t d_size; /* Size in bytes. */
152 int64_t d_off; /* Offset into section. */
153 size_t d_align; /* Alignment in section. */
154} Elf_Data;
155
156
157/* Commands for `...'. */
158typedef enum
159{
160 ELF_C_NULL, /* Nothing, terminate, or compute only. */
161 ELF_C_READ, /* Read .. */
162 ELF_C_RDWR, /* Read and write .. */
163 ELF_C_WRITE, /* Write .. */
164 ELF_C_CLR, /* Clear flag. */
165 ELF_C_SET, /* Set flag. */
166 ELF_C_FDDONE, /* Signal that file descriptor will not be
167 used anymore. */
168 ELF_C_FDREAD, /* Read rest of data so that file descriptor
169 is not used anymore. */
170 /* The following are extensions. */
171 ELF_C_READ_MMAP, /* Read, but mmap the file if possible. */
172 ELF_C_RDWR_MMAP, /* Read and write, with mmap. */
173 ELF_C_WRITE_MMAP, /* Write, with mmap. */
174 ELF_C_READ_MMAP_PRIVATE, /* Read, but memory is writable, results are
175 not written to the file. */
176 ELF_C_EMPTY, /* Copy basic file data but not the content. */
177 /* Keep this the last entry. */
178 ELF_C_NUM
179} Elf_Cmd;
180
181
182/* Flags for the ELF structures. */
183enum
184{
185 ELF_F_DIRTY = 0x1,
186#define ELF_F_DIRTY ELF_F_DIRTY
187 ELF_F_LAYOUT = 0x4,
188#define ELF_F_LAYOUT ELF_F_LAYOUT
189 ELF_F_PERMISSIVE = 0x8
190#define ELF_F_PERMISSIVE ELF_F_PERMISSIVE
191};
192
193/* Flags for elf_compress[_gnu]. */
194enum
195{
196 ELF_CHF_FORCE = 0x1
197#define ELF_CHF_FORCE ELF_CHF_FORCE
198};
199
200/* Identification values for recognized object files. */
201typedef enum
202{
203 ELF_K_NONE, /* Unknown. */
204 ELF_K_AR, /* Archive. */
205 ELF_K_COFF, /* Stupid old COFF. */
206 ELF_K_ELF, /* ELF file. */
207 /* Keep this the last entry. */
208 ELF_K_NUM
209} Elf_Kind;
210
211
212/* Archive member header. */
213typedef struct
214{
215 char *ar_name; /* Name of archive member. */
216 time_t ar_date; /* File date. */
217 uid_t ar_uid; /* User ID. */
218 gid_t ar_gid; /* Group ID. */
219 mode_t ar_mode; /* File mode. */
220 int64_t ar_size; /* File size. */
221 char *ar_rawname; /* Original name of archive member. */
222} Elf_Arhdr;
223
224
225/* Archive symbol table entry. */
226typedef struct
227{
228 char *as_name; /* Symbol name. */
229 size_t as_off; /* Offset for this file in the archive. */
230 unsigned long int as_hash; /* Hash value of the name. */
231} Elf_Arsym;
232
233
234/* Descriptor for the ELF file. */
235typedef struct Elf Elf;
236
237/* Descriptor for ELF file section. */
238typedef struct Elf_Scn Elf_Scn;
239
240
241#ifdef __cplusplus
242extern "C" {
243#endif
244
245/* Return descriptor for ELF file to work according to CMD. */
246extern Elf *elf_begin (int __fildes, Elf_Cmd __cmd, Elf *__ref);
247
248/* Create a clone of an existing ELF descriptor. */
249 extern Elf *elf_clone (Elf *__elf, Elf_Cmd __cmd);
250
251/* Create descriptor for memory region. */
252extern Elf *elf_memory (char *__image, size_t __size);
253
254/* Advance archive descriptor to next element. */
255extern Elf_Cmd elf_next (Elf *__elf);
256
257/* Free resources allocated for ELF. */
258extern int elf_end (Elf *__elf);
259
260/* Update ELF descriptor and write file to disk. */
261extern int64_t elf_update (Elf *__elf, Elf_Cmd __cmd);
262
263/* Determine what kind of file is associated with ELF. */
264extern Elf_Kind elf_kind (Elf *__elf) __pure_attribute__;
265
266/* Get the base offset for an object file. */
267extern int64_t elf_getbase (Elf *__elf);
268
269
270/* Retrieve file identification data. */
271extern char *elf_getident (Elf *__elf, size_t *__nbytes);
272
273/* Retrieve class-dependent object file header. */
274extern Elf32_Ehdr *elf32_getehdr (Elf *__elf);
275/* Similar but this time the binary calls is ELFCLASS64. */
276extern Elf64_Ehdr *elf64_getehdr (Elf *__elf);
277
278/* Create ELF header if none exists. */
279extern Elf32_Ehdr *elf32_newehdr (Elf *__elf);
280/* Similar but this time the binary calls is ELFCLASS64. */
281extern Elf64_Ehdr *elf64_newehdr (Elf *__elf);
282
283/* Get the number of program headers in the ELF file. If the file uses
284 more headers than can be represented in the e_phnum field of the ELF
285 header the information from the sh_info field in the zeroth section
286 header is used. */
287extern int elf_getphdrnum (Elf *__elf, size_t *__dst);
288
289/* Retrieve class-dependent program header table. */
290extern Elf32_Phdr *elf32_getphdr (Elf *__elf);
291/* Similar but this time the binary calls is ELFCLASS64. */
292extern Elf64_Phdr *elf64_getphdr (Elf *__elf);
293
294/* Create ELF program header. */
295extern Elf32_Phdr *elf32_newphdr (Elf *__elf, size_t __cnt);
296/* Similar but this time the binary calls is ELFCLASS64. */
297extern Elf64_Phdr *elf64_newphdr (Elf *__elf, size_t __cnt);
298
299
300/* Get section at INDEX. */
301extern Elf_Scn *elf_getscn (Elf *__elf, size_t __index);
302
303/* Get section at OFFSET. */
304extern Elf_Scn *elf32_offscn (Elf *__elf, Elf32_Off __offset);
305/* Similar but this time the binary calls is ELFCLASS64. */
306extern Elf_Scn *elf64_offscn (Elf *__elf, Elf64_Off __offset);
307
308/* Get index of section. */
309extern size_t elf_ndxscn (Elf_Scn *__scn);
310
311/* Get section with next section index. */
312extern Elf_Scn *elf_nextscn (Elf *__elf, Elf_Scn *__scn);
313
314/* Create a new section and append it at the end of the table. */
315extern Elf_Scn *elf_newscn (Elf *__elf);
316
317/* Get the section index of the extended section index table for the
318 given symbol table. */
319extern int elf_scnshndx (Elf_Scn *__scn);
320
321/* Get the number of sections in the ELF file. If the file uses more
322 sections than can be represented in the e_shnum field of the ELF
323 header the information from the sh_size field in the zeroth section
324 header is used. */
325extern int elf_getshdrnum (Elf *__elf, size_t *__dst);
326/* Sun messed up the implementation of 'elf_getshnum' in their implementation.
327 It was agreed to make the same functionality available under a different
328 name and obsolete the old name. */
329extern int elf_getshnum (Elf *__elf, size_t *__dst)
330 __deprecated_attribute__;
331
332
333/* Get the section index of the section header string table in the ELF
334 file. If the index cannot be represented in the e_shstrndx field of
335 the ELF header the information from the sh_link field in the zeroth
336 section header is used. */
337extern int elf_getshdrstrndx (Elf *__elf, size_t *__dst);
338/* Sun messed up the implementation of 'elf_getshstrndx' in their
339 implementation. It was agreed to make the same functionality available
340 under a different name and obsolete the old name. */
341extern int elf_getshstrndx (Elf *__elf, size_t *__dst)
342 __deprecated_attribute__;
343
344
345/* Retrieve section header of ELFCLASS32 binary. */
346extern Elf32_Shdr *elf32_getshdr (Elf_Scn *__scn);
347/* Similar for ELFCLASS64. */
348extern Elf64_Shdr *elf64_getshdr (Elf_Scn *__scn);
349
350/* Returns compression header for a section if section data is
351 compressed. Returns NULL and sets elf_errno if the section isn't
352 compressed or an error occurred. */
353extern Elf32_Chdr *elf32_getchdr (Elf_Scn *__scn);
354extern Elf64_Chdr *elf64_getchdr (Elf_Scn *__scn);
355
356/* Compress or decompress the data of a section and adjust the section
357 header.
358
359 elf_compress works by setting or clearing the SHF_COMPRESS flag
360 from the section Shdr and will encode or decode a Elf32_Chdr or
361 Elf64_Chdr at the start of the section data. elf_compress_gnu will
362 encode or decode any section, but is traditionally only used for
363 sections that have a name starting with ".debug" when
364 uncompressed or ".zdebug" when compressed and stores just the
365 uncompressed size. The GNU compression method is deprecated and
366 should only be used for legacy support.
367
368 elf_compress takes a compression type that should be either zero to
369 decompress or an ELFCOMPRESS algorithm to use for compression.
370 Currently ELFCOMPRESS_ZLIB and ELFCOMPRESS_ZSTD are supported.
371 elf_compress_gnu will compress in the traditional GNU compression
372 format when compress is one and decompress the section data when
373 compress is zero.
374
375 The FLAGS argument can be zero or ELF_CHF_FORCE. If FLAGS contains
376 ELF_CHF_FORCE then it will always compress the section, even if
377 that would not reduce the size of the data section (including the
378 header). Otherwise elf_compress and elf_compress_gnu will compress
379 the section only if the total data size is reduced.
380
381 On successful compression or decompression the function returns
382 one. If (not forced) compression is requested and the data section
383 would not actually reduce in size, the section is not actually
384 compressed and zero is returned. Otherwise -1 is returned and
385 elf_errno is set.
386
387 It is an error to request compression for a section that already
388 has SHF_COMPRESSED set, or (for elf_compress) to request
389 decompression for an section that doesn't have SHF_COMPRESSED set.
390 If a section has SHF_COMPRESSED set then calling elf_compress_gnu
391 will result in an error. The section has to be decompressed first
392 using elf_compress. Calling elf_compress on a section compressed
393 with elf_compress_gnu is fine, but probably useless.
394
395 It is always an error to call these functions on SHT_NOBITS
396 sections or if the section has the SHF_ALLOC flag set.
397 elf_compress_gnu will not check whether the section name starts
398 with ".debug" or .zdebug". It is the responsibility of the caller
399 to make sure the deprecated GNU compression method is only called
400 on correctly named sections (and to change the name of the section
401 when using elf_compress_gnu).
402
403 All previous returned Shdrs and Elf_Data buffers are invalidated by
404 this call and should no longer be accessed.
405
406 Note that although this changes the header and data returned it
407 doesn't mark the section as dirty. To keep the changes when
408 calling elf_update the section has to be flagged ELF_F_DIRTY. */
409extern int elf_compress (Elf_Scn *scn, int type, unsigned int flags);
410extern int elf_compress_gnu (Elf_Scn *scn, int compress, unsigned int flags);
411
412/* Set or clear flags for ELF file. */
413extern unsigned int elf_flagelf (Elf *__elf, Elf_Cmd __cmd,
414 unsigned int __flags);
415/* Similarly for the ELF header. */
416extern unsigned int elf_flagehdr (Elf *__elf, Elf_Cmd __cmd,
417 unsigned int __flags);
418/* Similarly for the ELF program header. */
419extern unsigned int elf_flagphdr (Elf *__elf, Elf_Cmd __cmd,
420 unsigned int __flags);
421/* Similarly for the given ELF section. */
422extern unsigned int elf_flagscn (Elf_Scn *__scn, Elf_Cmd __cmd,
423 unsigned int __flags);
424/* Similarly for the given ELF data. */
425extern unsigned int elf_flagdata (Elf_Data *__data, Elf_Cmd __cmd,
426 unsigned int __flags);
427/* Similarly for the given ELF section header. */
428extern unsigned int elf_flagshdr (Elf_Scn *__scn, Elf_Cmd __cmd,
429 unsigned int __flags);
430
431
432/* Get data from section while translating from file representation to
433 memory representation. The Elf_Data d_type is set based on the
434 section type if known. Otherwise d_type is set to ELF_T_BYTE. If
435 the section contains compressed data then d_type is always set to
436 ELF_T_CHDR. */
437extern Elf_Data *elf_getdata (Elf_Scn *__scn, Elf_Data *__data);
438
439/* Get uninterpreted section content. */
440extern Elf_Data *elf_rawdata (Elf_Scn *__scn, Elf_Data *__data);
441
442/* Create new data descriptor for section SCN. */
443extern Elf_Data *elf_newdata (Elf_Scn *__scn);
444
445/* Get data translated from a chunk of the file contents as section data
446 would be for TYPE. The resulting Elf_Data pointer is valid until
447 elf_end (ELF) is called. */
448extern Elf_Data *elf_getdata_rawchunk (Elf *__elf,
449 int64_t __offset, size_t __size,
450 Elf_Type __type);
451
452
453/* Return pointer to string at OFFSET in section INDEX. */
454extern char *elf_strptr (Elf *__elf, size_t __index, size_t __offset);
455
456
457/* Return header of archive. */
458extern Elf_Arhdr *elf_getarhdr (Elf *__elf);
459
460/* Return offset in archive for current file ELF. */
461extern int64_t elf_getaroff (Elf *__elf);
462
463/* Select archive element at OFFSET. */
464extern size_t elf_rand (Elf *__elf, size_t __offset);
465
466/* Get symbol table of archive. */
467extern Elf_Arsym *elf_getarsym (Elf *__elf, size_t *__narsyms);
468
469
470/* Control ELF descriptor. */
471extern int elf_cntl (Elf *__elf, Elf_Cmd __cmd);
472
473/* Retrieve uninterpreted file contents. */
474extern char *elf_rawfile (Elf *__elf, size_t *__nbytes);
475
476
477/* Return size of array of COUNT elements of the type denoted by TYPE
478 in the external representation. The binary class is taken from ELF.
479 The result is based on version VERSION of the ELF standard. */
480extern size_t elf32_fsize (Elf_Type __type, size_t __count,
481 unsigned int __version)
482 __const_attribute__;
483/* Similar but this time the binary calls is ELFCLASS64. */
484extern size_t elf64_fsize (Elf_Type __type, size_t __count,
485 unsigned int __version)
486 __const_attribute__;
487
488
489/* Convert data structure from the representation in the file represented
490 by ELF to their memory representation. */
491extern Elf_Data *elf32_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
492 unsigned int __encode);
493/* Same for 64 bit class. */
494extern Elf_Data *elf64_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
495 unsigned int __encode);
496
497/* Convert data structure from to the representation in memory
498 represented by ELF file representation. */
499extern Elf_Data *elf32_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
500 unsigned int __encode);
501/* Same for 64 bit class. */
502extern Elf_Data *elf64_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
503 unsigned int __encode);
504
505
506/* Return error code of last failing function call. This value is kept
507 separately for each thread. */
508extern int elf_errno (void);
509
510/* Return error string for ERROR. If ERROR is zero, return error string
511 for most recent error or NULL is none occurred. If ERROR is -1 the
512 behaviour is similar to the last case except that not NULL but a legal
513 string is returned. */
514extern const char *elf_errmsg (int __error);
515
516
517/* Coordinate ELF library and application versions. */
518extern unsigned int elf_version (unsigned int __version);
519
520/* Set fill bytes used to fill holes in data structures. */
521extern void elf_fill (int __fill);
522
523/* Compute hash value. */
524extern unsigned long int elf_hash (const char *__string)
525 __pure_attribute__;
526
527/* Compute hash value using the GNU-specific hash function. */
528extern unsigned long int elf_gnu_hash (const char *__string)
529 __pure_attribute__;
530
531
532/* Compute simple checksum from permanent parts of the ELF file. */
533extern long int elf32_checksum (Elf *__elf);
534/* Similar but this time the binary calls is ELFCLASS64. */
535extern long int elf64_checksum (Elf *__elf);
536
537#ifdef __cplusplus
538}
539#endif
540
541#endif /* libelf.h */
542

source code of include/libelf.h