1 /* Interface for libelf.
2 Copyright (C) 1998-2010, 2015 Red Hat, Inc.
3 This file is part of elfutils.
5 This file is free software; you can redistribute it and/or modify
6 it under the terms of either
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
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
18 or both in parallel, as here.
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.
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/>. */
33 #include <sys/types.h>
35 /* Get the ELF types. */
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. */
42 /* Section compression header. Used when SHF_COMPRESSED is set. */
46 Elf32_Word ch_type; /* Compression format. */
47 Elf32_Word ch_size; /* Uncompressed data size. */
48 Elf32_Word ch_addralign; /* Uncompressed data alignment. */
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. */
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. */
67 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
68 # define __nonnull_attribute__(...) __attribute__ ((__nonnull__ (__VA_ARGS__)))
69 # define __deprecated_attribute__ __attribute__ ((__deprecated__))
70 # define __pure_attribute__ __attribute__ ((__pure__))
71 # define __const_attribute__ __attribute__ ((__const__))
73 # define __nonnull_attribute__(...)
74 # define __deprecated_attribute__
75 # define __pure_attribute__
76 # define __const_attribute__
80 #define __noreturn_attribute__
82 #define __noreturn_attribute__ __attribute__ ((noreturn))
85 #ifdef __GNUC_STDC_INLINE__
86 # define __libdw_extern_inline extern __inline __attribute__ ((__gnu_inline__))
88 # define __libdw_extern_inline extern __inline
91 /* Known translation types. */
94 ELF_T_BYTE, /* unsigned char */
95 ELF_T_ADDR, /* Elf32_Addr, Elf64_Addr, ... */
96 ELF_T_DYN, /* Dynamic section record. */
97 ELF_T_EHDR, /* ELF header. */
98 ELF_T_HALF, /* Elf32_Half, Elf64_Half, ... */
99 ELF_T_OFF, /* Elf32_Off, Elf64_Off, ... */
100 ELF_T_PHDR, /* Program header. */
101 ELF_T_RELA, /* Relocation entry with addend. */
102 ELF_T_REL, /* Relocation entry. */
103 ELF_T_SHDR, /* Section header. */
104 ELF_T_SWORD, /* Elf32_Sword, Elf64_Sword, ... */
105 ELF_T_SYM, /* Symbol record. */
106 ELF_T_WORD, /* Elf32_Word, Elf64_Word, ... */
107 ELF_T_XWORD, /* Elf32_Xword, Elf64_Xword, ... */
108 ELF_T_SXWORD, /* Elf32_Sxword, Elf64_Sxword, ... */
109 ELF_T_VDEF, /* Elf32_Verdef, Elf64_Verdef, ... */
110 ELF_T_VDAUX, /* Elf32_Verdaux, Elf64_Verdaux, ... */
111 ELF_T_VNEED, /* Elf32_Verneed, Elf64_Verneed, ... */
112 ELF_T_VNAUX, /* Elf32_Vernaux, Elf64_Vernaux, ... */
113 ELF_T_NHDR, /* Elf32_Nhdr, Elf64_Nhdr, ... */
114 ELF_T_SYMINFO, /* Elf32_Syminfo, Elf64_Syminfo, ... */
115 ELF_T_MOVE, /* Elf32_Move, Elf64_Move, ... */
116 ELF_T_LIB, /* Elf32_Lib, Elf64_Lib, ... */
117 ELF_T_GNUHASH, /* GNU-style hash section. */
118 ELF_T_AUXV, /* Elf32_auxv_t, Elf64_auxv_t, ... */
119 ELF_T_CHDR, /* Compressed, Elf32_Chdr, Elf64_Chdr, ... */
120 /* Keep this the last entry. */
124 /* Descriptor for data to be converted to or from memory format. */
127 void *d_buf; /* Pointer to the actual data. */
128 Elf_Type d_type; /* Type of this piece of data. */
129 unsigned int d_version; /* ELF version. */
130 size_t d_size; /* Size in bytes. */
131 int64_t d_off; /* Offset into section. */
132 size_t d_align; /* Alignment in section. */
136 /* Commands for `...'. */
139 ELF_C_NULL, /* Nothing, terminate, or compute only. */
140 ELF_C_READ, /* Read .. */
141 ELF_C_RDWR, /* Read and write .. */
142 ELF_C_WRITE, /* Write .. */
143 ELF_C_CLR, /* Clear flag. */
144 ELF_C_SET, /* Set flag. */
145 ELF_C_FDDONE, /* Signal that file descriptor will not be
147 ELF_C_FDREAD, /* Read rest of data so that file descriptor
148 is not used anymore. */
149 /* The following are extensions. */
150 ELF_C_READ_MMAP, /* Read, but mmap the file if possible. */
151 ELF_C_RDWR_MMAP, /* Read and write, with mmap. */
152 ELF_C_WRITE_MMAP, /* Write, with mmap. */
153 ELF_C_READ_MMAP_PRIVATE, /* Read, but memory is writable, results are
154 not written to the file. */
155 ELF_C_EMPTY, /* Copy basic file data but not the content. */
156 /* Keep this the last entry. */
161 /* Flags for the ELF structures. */
165 #define ELF_F_DIRTY ELF_F_DIRTY
167 #define ELF_F_LAYOUT ELF_F_LAYOUT
168 ELF_F_PERMISSIVE = 0x8
169 #define ELF_F_PERMISSIVE ELF_F_PERMISSIVE
172 /* Flags for elf_compress[_gnu]. */
176 #define ELF_CHF_FORCE ELF_CHF_FORCE
179 /* Identification values for recognized object files. */
182 ELF_K_NONE, /* Unknown. */
183 ELF_K_AR, /* Archive. */
184 ELF_K_COFF, /* Stupid old COFF. */
185 ELF_K_ELF, /* ELF file. */
186 /* Keep this the last entry. */
191 /* Archive member header. */
194 char *ar_name; /* Name of archive member. */
195 time_t ar_date; /* File date. */
196 uid_t ar_uid; /* User ID. */
197 gid_t ar_gid; /* Group ID. */
198 mode_t ar_mode; /* File mode. */
199 int64_t ar_size; /* File size. */
200 char *ar_rawname; /* Original name of archive member. */
204 /* Archive symbol table entry. */
207 char *as_name; /* Symbol name. */
208 size_t as_off; /* Offset for this file in the archive. */
209 unsigned long int as_hash; /* Hash value of the name. */
213 /* Descriptor for the ELF file. */
214 typedef struct Elf Elf;
216 /* Descriptor for ELF file section. */
217 typedef struct Elf_Scn Elf_Scn;
224 /* Return descriptor for ELF file to work according to CMD. */
225 extern Elf *elf_begin (int __fildes, Elf_Cmd __cmd, Elf *__ref);
227 /* Create a clone of an existing ELF descriptor. */
228 extern Elf *elf_clone (Elf *__elf, Elf_Cmd __cmd);
230 /* Create descriptor for memory region. */
231 extern Elf *elf_memory (char *__image, size_t __size);
233 /* Advance archive descriptor to next element. */
234 extern Elf_Cmd elf_next (Elf *__elf);
236 /* Free resources allocated for ELF. */
237 extern int elf_end (Elf *__elf);
239 /* Update ELF descriptor and write file to disk. */
240 extern int64_t elf_update (Elf *__elf, Elf_Cmd __cmd);
242 /* Determine what kind of file is associated with ELF. */
243 extern Elf_Kind elf_kind (Elf *__elf) __pure_attribute__;
245 /* Get the base offset for an object file. */
246 extern int64_t elf_getbase (Elf *__elf);
249 /* Retrieve file identification data. */
250 extern char *elf_getident (Elf *__elf, size_t *__nbytes);
252 /* Retrieve class-dependent object file header. */
253 extern Elf32_Ehdr *elf32_getehdr (Elf *__elf);
254 /* Similar but this time the binary calls is ELFCLASS64. */
255 extern Elf64_Ehdr *elf64_getehdr (Elf *__elf);
257 /* Create ELF header if none exists. */
258 extern Elf32_Ehdr *elf32_newehdr (Elf *__elf);
259 /* Similar but this time the binary calls is ELFCLASS64. */
260 extern Elf64_Ehdr *elf64_newehdr (Elf *__elf);
262 /* Get the number of program headers in the ELF file. If the file uses
263 more headers than can be represented in the e_phnum field of the ELF
264 header the information from the sh_info field in the zeroth section
266 extern int elf_getphdrnum (Elf *__elf, size_t *__dst);
268 /* Retrieve class-dependent program header table. */
269 extern Elf32_Phdr *elf32_getphdr (Elf *__elf);
270 /* Similar but this time the binary calls is ELFCLASS64. */
271 extern Elf64_Phdr *elf64_getphdr (Elf *__elf);
273 /* Create ELF program header. */
274 extern Elf32_Phdr *elf32_newphdr (Elf *__elf, size_t __cnt);
275 /* Similar but this time the binary calls is ELFCLASS64. */
276 extern Elf64_Phdr *elf64_newphdr (Elf *__elf, size_t __cnt);
279 /* Get section at INDEX. */
280 extern Elf_Scn *elf_getscn (Elf *__elf, size_t __index);
282 /* Get section at OFFSET. */
283 extern Elf_Scn *elf32_offscn (Elf *__elf, Elf32_Off __offset);
284 /* Similar bug this time the binary calls is ELFCLASS64. */
285 extern Elf_Scn *elf64_offscn (Elf *__elf, Elf64_Off __offset);
287 /* Get index of section. */
288 extern size_t elf_ndxscn (Elf_Scn *__scn);
290 /* Get section with next section index. */
291 extern Elf_Scn *elf_nextscn (Elf *__elf, Elf_Scn *__scn);
293 /* Create a new section and append it at the end of the table. */
294 extern Elf_Scn *elf_newscn (Elf *__elf);
296 /* Get the section index of the extended section index table for the
297 given symbol table. */
298 extern int elf_scnshndx (Elf_Scn *__scn);
300 /* Get the number of sections in the ELF file. If the file uses more
301 sections than can be represented in the e_shnum field of the ELF
302 header the information from the sh_size field in the zeroth section
304 extern int elf_getshdrnum (Elf *__elf, size_t *__dst);
305 /* Sun messed up the implementation of 'elf_getshnum' in their implementation.
306 It was agreed to make the same functionality available under a different
307 name and obsolete the old name. */
308 extern int elf_getshnum (Elf *__elf, size_t *__dst)
309 __deprecated_attribute__;
312 /* Get the section index of the section header string table in the ELF
313 file. If the index cannot be represented in the e_shnum field of
314 the ELF header the information from the sh_link field in the zeroth
315 section header is used. */
316 extern int elf_getshdrstrndx (Elf *__elf, size_t *__dst);
317 /* Sun messed up the implementation of 'elf_getshnum' in their implementation.
318 It was agreed to make the same functionality available under a different
319 name and obsolete the old name. */
320 extern int elf_getshstrndx (Elf *__elf, size_t *__dst)
321 __deprecated_attribute__;
324 /* Retrieve section header of ELFCLASS32 binary. */
325 extern Elf32_Shdr *elf32_getshdr (Elf_Scn *__scn);
326 /* Similar for ELFCLASS64. */
327 extern Elf64_Shdr *elf64_getshdr (Elf_Scn *__scn);
329 /* Returns compression header for a section if section data is
330 compressed. Returns NULL and sets elf_errno if the section isn't
331 compressed or an error occurred. */
332 extern Elf32_Chdr *elf32_getchdr (Elf_Scn *__scn);
333 extern Elf64_Chdr *elf64_getchdr (Elf_Scn *__scn);
335 /* Compress or decompress the data of a section and adjust the section
338 elf_compress works by setting or clearing the SHF_COMPRESS flag
339 from the section Shdr and will encode or decode a Elf32_Chdr or
340 Elf64_Chdr at the start of the section data. elf_compress_gnu will
341 encode or decode any section, but is traditionally only used for
342 sections that have a name starting with ".debug" when
343 uncompressed or ".zdebug" when compressed and stores just the
344 uncompressed size. The GNU compression method is deprecated and
345 should only be used for legacy support.
347 elf_compress takes a compression type that should be either zero to
348 decompress or an ELFCOMPRESS algorithm to use for compression.
349 Currently only ELFCOMPRESS_ZLIB is supported. elf_compress_gnu
350 will compress in the traditional GNU compression format when
351 compress is one and decompress the section data when compress is
354 The FLAGS argument can be zero or ELF_CHF_FORCE. If FLAGS contains
355 ELF_CHF_FORCE then it will always compress the section, even if
356 that would not reduce the size of the data section (including the
357 header). Otherwise elf_compress and elf_compress_gnu will compress
358 the section only if the total data size is reduced.
360 On successful compression or decompression the function returns
361 one. If (not forced) compression is requested and the data section
362 would not actually reduce in size, the section is not actually
363 compressed and zero is returned. Otherwise -1 is returned and
366 It is an error to request compression for a section that already
367 has SHF_COMPRESSED set, or (for elf_compress) to request
368 decompression for an section that doesn't have SHF_COMPRESSED set.
369 It is always an error to call these functions on SHT_NOBITS
370 sections or if the section has the SHF_ALLOC flag set.
371 elf_compress_gnu will not check whether the section name starts
372 with ".debug" or .zdebug". It is the responsibilty of the caller
373 to make sure the deprecated GNU compression method is only called
374 on correctly named sections (and to change the name of the section
375 when using elf_compress_gnu).
377 All previous returned Shdrs and Elf_Data buffers are invalidated by
378 this call and should no longer be accessed.
380 Note that although this changes the header and data returned it
381 doesn't mark the section as dirty. To keep the changes when
382 calling elf_update the section has to be flagged ELF_F_DIRTY. */
383 extern int elf_compress (Elf_Scn *scn, int type, unsigned int flags);
384 extern int elf_compress_gnu (Elf_Scn *scn, int compress, unsigned int flags);
386 /* Set or clear flags for ELF file. */
387 extern unsigned int elf_flagelf (Elf *__elf, Elf_Cmd __cmd,
388 unsigned int __flags);
389 /* Similarly for the ELF header. */
390 extern unsigned int elf_flagehdr (Elf *__elf, Elf_Cmd __cmd,
391 unsigned int __flags);
392 /* Similarly for the ELF program header. */
393 extern unsigned int elf_flagphdr (Elf *__elf, Elf_Cmd __cmd,
394 unsigned int __flags);
395 /* Similarly for the given ELF section. */
396 extern unsigned int elf_flagscn (Elf_Scn *__scn, Elf_Cmd __cmd,
397 unsigned int __flags);
398 /* Similarly for the given ELF data. */
399 extern unsigned int elf_flagdata (Elf_Data *__data, Elf_Cmd __cmd,
400 unsigned int __flags);
401 /* Similarly for the given ELF section header. */
402 extern unsigned int elf_flagshdr (Elf_Scn *__scn, Elf_Cmd __cmd,
403 unsigned int __flags);
406 /* Get data from section while translating from file representation to
407 memory representation. The Elf_Data d_type is set based on the
408 section type if known. Otherwise d_type is set to ELF_T_BYTE. If
409 the section contains compressed data then d_type is always set to
411 extern Elf_Data *elf_getdata (Elf_Scn *__scn, Elf_Data *__data);
413 /* Get uninterpreted section content. */
414 extern Elf_Data *elf_rawdata (Elf_Scn *__scn, Elf_Data *__data);
416 /* Create new data descriptor for section SCN. */
417 extern Elf_Data *elf_newdata (Elf_Scn *__scn);
419 /* Get data translated from a chunk of the file contents as section data
420 would be for TYPE. The resulting Elf_Data pointer is valid until
421 elf_end (ELF) is called. */
422 extern Elf_Data *elf_getdata_rawchunk (Elf *__elf,
423 int64_t __offset, size_t __size,
427 /* Return pointer to string at OFFSET in section INDEX. */
428 extern char *elf_strptr (Elf *__elf, size_t __index, size_t __offset);
431 /* Return header of archive. */
432 extern Elf_Arhdr *elf_getarhdr (Elf *__elf);
434 /* Return offset in archive for current file ELF. */
435 extern int64_t elf_getaroff (Elf *__elf);
437 /* Select archive element at OFFSET. */
438 extern size_t elf_rand (Elf *__elf, size_t __offset);
440 /* Get symbol table of archive. */
441 extern Elf_Arsym *elf_getarsym (Elf *__elf, size_t *__narsyms);
444 /* Control ELF descriptor. */
445 extern int elf_cntl (Elf *__elf, Elf_Cmd __cmd);
447 /* Retrieve uninterpreted file contents. */
448 extern char *elf_rawfile (Elf *__elf, size_t *__nbytes);
451 /* Return size of array of COUNT elements of the type denoted by TYPE
452 in the external representation. The binary class is taken from ELF.
453 The result is based on version VERSION of the ELF standard. */
454 extern size_t elf32_fsize (Elf_Type __type, size_t __count,
455 unsigned int __version)
457 /* Similar but this time the binary calls is ELFCLASS64. */
458 extern size_t elf64_fsize (Elf_Type __type, size_t __count,
459 unsigned int __version)
463 /* Convert data structure from the representation in the file represented
464 by ELF to their memory representation. */
465 extern Elf_Data *elf32_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
466 unsigned int __encode);
467 /* Same for 64 bit class. */
468 extern Elf_Data *elf64_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
469 unsigned int __encode);
471 /* Convert data structure from to the representation in memory
472 represented by ELF file representation. */
473 extern Elf_Data *elf32_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
474 unsigned int __encode);
475 /* Same for 64 bit class. */
476 extern Elf_Data *elf64_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
477 unsigned int __encode);
480 /* Return error code of last failing function call. This value is kept
481 separately for each thread. */
482 extern int elf_errno (void);
484 /* Return error string for ERROR. If ERROR is zero, return error string
485 for most recent error or NULL is none occurred. If ERROR is -1 the
486 behaviour is similar to the last case except that not NULL but a legal
487 string is returned. */
488 extern const char *elf_errmsg (int __error);
491 /* Coordinate ELF library and application versions. */
492 extern unsigned int elf_version (unsigned int __version);
494 /* Set fill bytes used to fill holes in data structures. */
495 extern void elf_fill (int __fill);
497 /* Compute hash value. */
498 extern unsigned long int elf_hash (const char *__string)
501 /* Compute hash value using the GNU-specific hash function. */
502 extern unsigned long int elf_gnu_hash (const char *__string)
506 /* Compute simple checksum from permanent parts of the ELF file. */
507 extern long int elf32_checksum (Elf *__elf);
508 /* Similar but this time the binary calls is ELFCLASS64. */
509 extern long int elf64_checksum (Elf *__elf);
515 #endif /* libelf.h */