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