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 #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__))
72 #else
73 # define __nonnull_attribute__(...)
74 # define __deprecated_attribute__
75 # define __pure_attribute__
76 # define __const_attribute__
77 #endif
78 
79 #if __GNUC__ < 4
80 #define __noreturn_attribute__
81 #else
82 #define __noreturn_attribute__ __attribute__ ((noreturn))
83 #endif
84 
85 #ifdef __GNUC_STDC_INLINE__
86 # define __libdw_extern_inline extern __inline __attribute__ ((__gnu_inline__))
87 #else
88 # define __libdw_extern_inline extern __inline
89 #endif
90 
91 /* Known translation types.  */
92 typedef enum
93 {
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   ELF_T_NHDR8,			/* Special GNU Properties note.  Same as Nhdr,
121 				   except padding.  */
122   /* Keep this the last entry.  */
123   ELF_T_NUM
124 } Elf_Type;
125 
126 /* Descriptor for data to be converted to or from memory format.  */
127 typedef struct
128 {
129   void *d_buf;			/* Pointer to the actual data.  */
130   Elf_Type d_type;		/* Type of this piece of data.  */
131   unsigned int d_version;	/* ELF version.  */
132   size_t d_size;		/* Size in bytes.  */
133   int64_t d_off;		/* Offset into section.  */
134   size_t d_align;		/* Alignment in section.  */
135 } Elf_Data;
136 
137 
138 /* Commands for `...'.  */
139 typedef enum
140 {
141   ELF_C_NULL,			/* Nothing, terminate, or compute only.  */
142   ELF_C_READ,			/* Read .. */
143   ELF_C_RDWR,			/* Read and write .. */
144   ELF_C_WRITE,			/* Write .. */
145   ELF_C_CLR,			/* Clear flag.  */
146   ELF_C_SET,			/* Set flag.  */
147   ELF_C_FDDONE,			/* Signal that file descriptor will not be
148 				   used anymore.  */
149   ELF_C_FDREAD,			/* Read rest of data so that file descriptor
150 				   is not used anymore.  */
151   /* The following are extensions.  */
152   ELF_C_READ_MMAP,		/* Read, but mmap the file if possible.  */
153   ELF_C_RDWR_MMAP,		/* Read and write, with mmap.  */
154   ELF_C_WRITE_MMAP,		/* Write, with mmap.  */
155   ELF_C_READ_MMAP_PRIVATE,	/* Read, but memory is writable, results are
156 				   not written to the file.  */
157   ELF_C_EMPTY,			/* Copy basic file data but not the content. */
158   /* Keep this the last entry.  */
159   ELF_C_NUM
160 } Elf_Cmd;
161 
162 
163 /* Flags for the ELF structures.  */
164 enum
165 {
166   ELF_F_DIRTY = 0x1,
167 #define ELF_F_DIRTY		ELF_F_DIRTY
168   ELF_F_LAYOUT = 0x4,
169 #define ELF_F_LAYOUT		ELF_F_LAYOUT
170   ELF_F_PERMISSIVE = 0x8
171 #define ELF_F_PERMISSIVE	ELF_F_PERMISSIVE
172 };
173 
174 /* Flags for elf_compress[_gnu].  */
175 enum
176 {
177   ELF_CHF_FORCE = 0x1
178 #define ELF_CHF_FORCE ELF_CHF_FORCE
179 };
180 
181 /* Identification values for recognized object files.  */
182 typedef enum
183 {
184   ELF_K_NONE,			/* Unknown.  */
185   ELF_K_AR,			/* Archive.  */
186   ELF_K_COFF,			/* Stupid old COFF.  */
187   ELF_K_ELF,			/* ELF file.  */
188   /* Keep this the last entry.  */
189   ELF_K_NUM
190 } Elf_Kind;
191 
192 
193 /* Archive member header.  */
194 typedef struct
195 {
196   char *ar_name;		/* Name of archive member.  */
197   time_t ar_date;		/* File date.  */
198   uid_t ar_uid;			/* User ID.  */
199   gid_t ar_gid;			/* Group ID.  */
200   mode_t ar_mode;		/* File mode.  */
201   int64_t ar_size;		/* File size.  */
202   char *ar_rawname;		/* Original name of archive member.  */
203 } Elf_Arhdr;
204 
205 
206 /* Archive symbol table entry.  */
207 typedef struct
208 {
209   char *as_name;		/* Symbol name.  */
210   size_t as_off;		/* Offset for this file in the archive.  */
211   unsigned long int as_hash;	/* Hash value of the name.  */
212 } Elf_Arsym;
213 
214 
215 /* Descriptor for the ELF file.  */
216 typedef struct Elf Elf;
217 
218 /* Descriptor for ELF file section.  */
219 typedef struct Elf_Scn Elf_Scn;
220 
221 
222 #ifdef __cplusplus
223 extern "C" {
224 #endif
225 
226 /* Return descriptor for ELF file to work according to CMD.  */
227 extern Elf *elf_begin (int __fildes, Elf_Cmd __cmd, Elf *__ref);
228 
229 /* Create a clone of an existing ELF descriptor.  */
230   extern Elf *elf_clone (Elf *__elf, Elf_Cmd __cmd);
231 
232 /* Create descriptor for memory region.  */
233 extern Elf *elf_memory (char *__image, size_t __size);
234 
235 /* Advance archive descriptor to next element.  */
236 extern Elf_Cmd elf_next (Elf *__elf);
237 
238 /* Free resources allocated for ELF.  */
239 extern int elf_end (Elf *__elf);
240 
241 /* Update ELF descriptor and write file to disk.  */
242 extern int64_t elf_update (Elf *__elf, Elf_Cmd __cmd);
243 
244 /* Determine what kind of file is associated with ELF.  */
245 extern Elf_Kind elf_kind (Elf *__elf) __pure_attribute__;
246 
247 /* Get the base offset for an object file.  */
248 extern int64_t elf_getbase (Elf *__elf);
249 
250 
251 /* Retrieve file identification data.  */
252 extern char *elf_getident (Elf *__elf, size_t *__nbytes);
253 
254 /* Retrieve class-dependent object file header.  */
255 extern Elf32_Ehdr *elf32_getehdr (Elf *__elf);
256 /* Similar but this time the binary calls is ELFCLASS64.  */
257 extern Elf64_Ehdr *elf64_getehdr (Elf *__elf);
258 
259 /* Create ELF header if none exists.  */
260 extern Elf32_Ehdr *elf32_newehdr (Elf *__elf);
261 /* Similar but this time the binary calls is ELFCLASS64.  */
262 extern Elf64_Ehdr *elf64_newehdr (Elf *__elf);
263 
264 /* Get the number of program headers in the ELF file.  If the file uses
265    more headers than can be represented in the e_phnum field of the ELF
266    header the information from the sh_info field in the zeroth section
267    header is used.  */
268 extern int elf_getphdrnum (Elf *__elf, size_t *__dst);
269 
270 /* Retrieve class-dependent program header table.  */
271 extern Elf32_Phdr *elf32_getphdr (Elf *__elf);
272 /* Similar but this time the binary calls is ELFCLASS64.  */
273 extern Elf64_Phdr *elf64_getphdr (Elf *__elf);
274 
275 /* Create ELF program header.  */
276 extern Elf32_Phdr *elf32_newphdr (Elf *__elf, size_t __cnt);
277 /* Similar but this time the binary calls is ELFCLASS64.  */
278 extern Elf64_Phdr *elf64_newphdr (Elf *__elf, size_t __cnt);
279 
280 
281 /* Get section at INDEX.  */
282 extern Elf_Scn *elf_getscn (Elf *__elf, size_t __index);
283 
284 /* Get section at OFFSET.  */
285 extern Elf_Scn *elf32_offscn (Elf *__elf, Elf32_Off __offset);
286 /* Similar bug this time the binary calls is ELFCLASS64.  */
287 extern Elf_Scn *elf64_offscn (Elf *__elf, Elf64_Off __offset);
288 
289 /* Get index of section.  */
290 extern size_t elf_ndxscn (Elf_Scn *__scn);
291 
292 /* Get section with next section index.  */
293 extern Elf_Scn *elf_nextscn (Elf *__elf, Elf_Scn *__scn);
294 
295 /* Create a new section and append it at the end of the table.  */
296 extern Elf_Scn *elf_newscn (Elf *__elf);
297 
298 /* Get the section index of the extended section index table for the
299    given symbol table.  */
300 extern int elf_scnshndx (Elf_Scn *__scn);
301 
302 /* Get the number of sections in the ELF file.  If the file uses more
303    sections than can be represented in the e_shnum field of the ELF
304    header the information from the sh_size field in the zeroth section
305    header is used.  */
306 extern int elf_getshdrnum (Elf *__elf, size_t *__dst);
307 /* Sun messed up the implementation of 'elf_getshnum' in their implementation.
308    It was agreed to make the same functionality available under a different
309    name and obsolete the old name.  */
310 extern int elf_getshnum (Elf *__elf, size_t *__dst)
311      __deprecated_attribute__;
312 
313 
314 /* Get the section index of the section header string table in the ELF
315    file.  If the index cannot be represented in the e_shstrndx field of
316    the ELF header the information from the sh_link field in the zeroth
317    section header is used.  */
318 extern int elf_getshdrstrndx (Elf *__elf, size_t *__dst);
319 /* Sun messed up the implementation of 'elf_getshstrndx' in their
320    implementation.  It was agreed to make the same functionality available
321    under a different name and obsolete the old name.  */
322 extern int elf_getshstrndx (Elf *__elf, size_t *__dst)
323      __deprecated_attribute__;
324 
325 
326 /* Retrieve section header of ELFCLASS32 binary.  */
327 extern Elf32_Shdr *elf32_getshdr (Elf_Scn *__scn);
328 /* Similar for ELFCLASS64.  */
329 extern Elf64_Shdr *elf64_getshdr (Elf_Scn *__scn);
330 
331 /* Returns compression header for a section if section data is
332    compressed.  Returns NULL and sets elf_errno if the section isn't
333    compressed or an error occurred.  */
334 extern Elf32_Chdr *elf32_getchdr (Elf_Scn *__scn);
335 extern Elf64_Chdr *elf64_getchdr (Elf_Scn *__scn);
336 
337 /* Compress or decompress the data of a section and adjust the section
338    header.
339 
340    elf_compress works by setting or clearing the SHF_COMPRESS flag
341    from the section Shdr and will encode or decode a Elf32_Chdr or
342    Elf64_Chdr at the start of the section data.  elf_compress_gnu will
343    encode or decode any section, but is traditionally only used for
344    sections that have a name starting with ".debug" when
345    uncompressed or ".zdebug" when compressed and stores just the
346    uncompressed size.  The GNU compression method is deprecated and
347    should only be used for legacy support.
348 
349    elf_compress takes a compression type that should be either zero to
350    decompress or an ELFCOMPRESS algorithm to use for compression.
351    Currently only ELFCOMPRESS_ZLIB is supported.  elf_compress_gnu
352    will compress in the traditional GNU compression format when
353    compress is one and decompress the section data when compress is
354    zero.
355 
356    The FLAGS argument can be zero or ELF_CHF_FORCE.  If FLAGS contains
357    ELF_CHF_FORCE then it will always compress the section, even if
358    that would not reduce the size of the data section (including the
359    header).  Otherwise elf_compress and elf_compress_gnu will compress
360    the section only if the total data size is reduced.
361 
362    On successful compression or decompression the function returns
363    one.  If (not forced) compression is requested and the data section
364    would not actually reduce in size, the section is not actually
365    compressed and zero is returned.  Otherwise -1 is returned and
366    elf_errno is set.
367 
368    It is an error to request compression for a section that already
369    has SHF_COMPRESSED set, or (for elf_compress) to request
370    decompression for an section that doesn't have SHF_COMPRESSED set.
371    If a section has SHF_COMPRESSED set then calling elf_compress_gnu
372    will result in an error.  The section has to be decompressed first
373    using elf_compress.  Calling elf_compress on a section compressed
374    with elf_compress_gnu is fine, but probably useless.
375 
376    It is always an error to call these functions on SHT_NOBITS
377    sections or if the section has the SHF_ALLOC flag set.
378    elf_compress_gnu will not check whether the section name starts
379    with ".debug" or .zdebug".  It is the responsibility of the caller
380    to make sure the deprecated GNU compression method is only called
381    on correctly named sections (and to change the name of the section
382    when using elf_compress_gnu).
383 
384    All previous returned Shdrs and Elf_Data buffers are invalidated by
385    this call and should no longer be accessed.
386 
387    Note that although this changes the header and data returned it
388    doesn't mark the section as dirty.  To keep the changes when
389    calling elf_update the section has to be flagged ELF_F_DIRTY.  */
390 extern int elf_compress (Elf_Scn *scn, int type, unsigned int flags);
391 extern int elf_compress_gnu (Elf_Scn *scn, int compress, unsigned int flags);
392 
393 /* Set or clear flags for ELF file.  */
394 extern unsigned int elf_flagelf (Elf *__elf, Elf_Cmd __cmd,
395 				 unsigned int __flags);
396 /* Similarly for the ELF header.  */
397 extern unsigned int elf_flagehdr (Elf *__elf, Elf_Cmd __cmd,
398 				  unsigned int __flags);
399 /* Similarly for the ELF program header.  */
400 extern unsigned int elf_flagphdr (Elf *__elf, Elf_Cmd __cmd,
401 				  unsigned int __flags);
402 /* Similarly for the given ELF section.  */
403 extern unsigned int elf_flagscn (Elf_Scn *__scn, Elf_Cmd __cmd,
404 				 unsigned int __flags);
405 /* Similarly for the given ELF data.  */
406 extern unsigned int elf_flagdata (Elf_Data *__data, Elf_Cmd __cmd,
407 				  unsigned int __flags);
408 /* Similarly for the given ELF section header.  */
409 extern unsigned int elf_flagshdr (Elf_Scn *__scn, Elf_Cmd __cmd,
410 				  unsigned int __flags);
411 
412 
413 /* Get data from section while translating from file representation to
414    memory representation.  The Elf_Data d_type is set based on the
415    section type if known.  Otherwise d_type is set to ELF_T_BYTE.  If
416    the section contains compressed data then d_type is always set to
417    ELF_T_CHDR.  */
418 extern Elf_Data *elf_getdata (Elf_Scn *__scn, Elf_Data *__data);
419 
420 /* Get uninterpreted section content.  */
421 extern Elf_Data *elf_rawdata (Elf_Scn *__scn, Elf_Data *__data);
422 
423 /* Create new data descriptor for section SCN.  */
424 extern Elf_Data *elf_newdata (Elf_Scn *__scn);
425 
426 /* Get data translated from a chunk of the file contents as section data
427    would be for TYPE.  The resulting Elf_Data pointer is valid until
428    elf_end (ELF) is called.  */
429 extern Elf_Data *elf_getdata_rawchunk (Elf *__elf,
430 				       int64_t __offset, size_t __size,
431 				       Elf_Type __type);
432 
433 
434 /* Return pointer to string at OFFSET in section INDEX.  */
435 extern char *elf_strptr (Elf *__elf, size_t __index, size_t __offset);
436 
437 
438 /* Return header of archive.  */
439 extern Elf_Arhdr *elf_getarhdr (Elf *__elf);
440 
441 /* Return offset in archive for current file ELF.  */
442 extern int64_t elf_getaroff (Elf *__elf);
443 
444 /* Select archive element at OFFSET.  */
445 extern size_t elf_rand (Elf *__elf, size_t __offset);
446 
447 /* Get symbol table of archive.  */
448 extern Elf_Arsym *elf_getarsym (Elf *__elf, size_t *__narsyms);
449 
450 
451 /* Control ELF descriptor.  */
452 extern int elf_cntl (Elf *__elf, Elf_Cmd __cmd);
453 
454 /* Retrieve uninterpreted file contents.  */
455 extern char *elf_rawfile (Elf *__elf, size_t *__nbytes);
456 
457 
458 /* Return size of array of COUNT elements of the type denoted by TYPE
459    in the external representation.  The binary class is taken from ELF.
460    The result is based on version VERSION of the ELF standard.  */
461 extern size_t elf32_fsize (Elf_Type __type, size_t __count,
462 			   unsigned int __version)
463        __const_attribute__;
464 /* Similar but this time the binary calls is ELFCLASS64.  */
465 extern size_t elf64_fsize (Elf_Type __type, size_t __count,
466 			   unsigned int __version)
467        __const_attribute__;
468 
469 
470 /* Convert data structure from the representation in the file represented
471    by ELF to their memory representation.  */
472 extern Elf_Data *elf32_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
473 				 unsigned int __encode);
474 /* Same for 64 bit class.  */
475 extern Elf_Data *elf64_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
476 				 unsigned int __encode);
477 
478 /* Convert data structure from to the representation in memory
479    represented by ELF file representation.  */
480 extern Elf_Data *elf32_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
481 				 unsigned int __encode);
482 /* Same for 64 bit class.  */
483 extern Elf_Data *elf64_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
484 				 unsigned int __encode);
485 
486 
487 /* Return error code of last failing function call.  This value is kept
488    separately for each thread.  */
489 extern int elf_errno (void);
490 
491 /* Return error string for ERROR.  If ERROR is zero, return error string
492    for most recent error or NULL is none occurred.  If ERROR is -1 the
493    behaviour is similar to the last case except that not NULL but a legal
494    string is returned.  */
495 extern const char *elf_errmsg (int __error);
496 
497 
498 /* Coordinate ELF library and application versions.  */
499 extern unsigned int elf_version (unsigned int __version);
500 
501 /* Set fill bytes used to fill holes in data structures.  */
502 extern void elf_fill (int __fill);
503 
504 /* Compute hash value.  */
505 extern unsigned long int elf_hash (const char *__string)
506        __pure_attribute__;
507 
508 /* Compute hash value using the GNU-specific hash function.  */
509 extern unsigned long int elf_gnu_hash (const char *__string)
510        __pure_attribute__;
511 
512 
513 /* Compute simple checksum from permanent parts of the ELF file.  */
514 extern long int elf32_checksum (Elf *__elf);
515 /* Similar but this time the binary calls is ELFCLASS64.  */
516 extern long int elf64_checksum (Elf *__elf);
517 
518 #ifdef __cplusplus
519 }
520 #endif
521 
522 #endif  /* libelf.h */
523