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. */ 68typedef 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. */ 101typedef 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 `...'. */ 113typedef 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. */ 138enum 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]. */ 149enum 150{ 151 ELF_CHF_FORCE = 0x1 152#define ELF_CHF_FORCE ELF_CHF_FORCE 153}; 154 155/* Identification values for recognized object files. */ 156typedef 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. */ 168typedef 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. */ 181typedef 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. */ 190typedef struct Elf Elf; 191 192/* Descriptor for ELF file section. */ 193typedef struct Elf_Scn Elf_Scn; 194 195 196#ifdef __cplusplus 197extern "C" { 198#endif 199 200/* Return descriptor for ELF file to work according to CMD. */ 201extern 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. */ 207extern Elf *elf_memory (char *__image, size_t __size); 208 209/* Advance archive descriptor to next element. */ 210extern Elf_Cmd elf_next (Elf *__elf); 211 212/* Free resources allocated for ELF. */ 213extern int elf_end (Elf *__elf); 214 215/* Update ELF descriptor and write file to disk. */ 216extern int64_t elf_update (Elf *__elf, Elf_Cmd __cmd); 217 218/* Determine what kind of file is associated with ELF. */ 219extern Elf_Kind elf_kind (Elf *__elf) __attribute__ ((__pure__)); 220 221/* Get the base offset for an object file. */ 222extern int64_t elf_getbase (Elf *__elf); 223 224 225/* Retrieve file identification data. */ 226extern char *elf_getident (Elf *__elf, size_t *__nbytes); 227 228/* Retrieve class-dependent object file header. */ 229extern Elf32_Ehdr *elf32_getehdr (Elf *__elf); 230/* Similar but this time the binary calls is ELFCLASS64. */ 231extern Elf64_Ehdr *elf64_getehdr (Elf *__elf); 232 233/* Create ELF header if none exists. */ 234extern Elf32_Ehdr *elf32_newehdr (Elf *__elf); 235/* Similar but this time the binary calls is ELFCLASS64. */ 236extern 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. */ 242extern int elf_getphdrnum (Elf *__elf, size_t *__dst); 243 244/* Retrieve class-dependent program header table. */ 245extern Elf32_Phdr *elf32_getphdr (Elf *__elf); 246/* Similar but this time the binary calls is ELFCLASS64. */ 247extern Elf64_Phdr *elf64_getphdr (Elf *__elf); 248 249/* Create ELF program header. */ 250extern Elf32_Phdr *elf32_newphdr (Elf *__elf, size_t __cnt); 251/* Similar but this time the binary calls is ELFCLASS64. */ 252extern Elf64_Phdr *elf64_newphdr (Elf *__elf, size_t __cnt); 253 254 255/* Get section at INDEX. */ 256extern Elf_Scn *elf_getscn (Elf *__elf, size_t __index); 257 258/* Get section at OFFSET. */ 259extern Elf_Scn *elf32_offscn (Elf *__elf, Elf32_Off __offset); 260/* Similar bug this time the binary calls is ELFCLASS64. */ 261extern Elf_Scn *elf64_offscn (Elf *__elf, Elf64_Off __offset); 262 263/* Get index of section. */ 264extern size_t elf_ndxscn (Elf_Scn *__scn); 265 266/* Get section with next section index. */ 267extern Elf_Scn *elf_nextscn (Elf *__elf, Elf_Scn *__scn); 268 269/* Create a new section and append it at the end of the table. */ 270extern Elf_Scn *elf_newscn (Elf *__elf); 271 272/* Get the section index of the extended section index table for the 273 given symbol table. */ 274extern 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. */ 280extern 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. */ 284extern 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. */ 292extern 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. */ 296extern int elf_getshstrndx (Elf *__elf, size_t *__dst) 297 __attribute__ ((__deprecated__)); 298 299 300/* Retrieve section header of ELFCLASS32 binary. */ 301extern Elf32_Shdr *elf32_getshdr (Elf_Scn *__scn); 302/* Similar for ELFCLASS64. */ 303extern 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. */ 308extern Elf32_Chdr *elf32_getchdr (Elf_Scn *__scn); 309extern 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. */ 359extern int elf_compress (Elf_Scn *scn, int type, unsigned int flags); 360extern int elf_compress_gnu (Elf_Scn *scn, int compress, unsigned int flags); 361 362/* Set or clear flags for ELF file. */ 363extern unsigned int elf_flagelf (Elf *__elf, Elf_Cmd __cmd, 364 unsigned int __flags); 365/* Similarly for the ELF header. */ 366extern unsigned int elf_flagehdr (Elf *__elf, Elf_Cmd __cmd, 367 unsigned int __flags); 368/* Similarly for the ELF program header. */ 369extern unsigned int elf_flagphdr (Elf *__elf, Elf_Cmd __cmd, 370 unsigned int __flags); 371/* Similarly for the given ELF section. */ 372extern unsigned int elf_flagscn (Elf_Scn *__scn, Elf_Cmd __cmd, 373 unsigned int __flags); 374/* Similarly for the given ELF data. */ 375extern unsigned int elf_flagdata (Elf_Data *__data, Elf_Cmd __cmd, 376 unsigned int __flags); 377/* Similarly for the given ELF section header. */ 378extern 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. */ 387extern Elf_Data *elf_getdata (Elf_Scn *__scn, Elf_Data *__data); 388 389/* Get uninterpreted section content. */ 390extern Elf_Data *elf_rawdata (Elf_Scn *__scn, Elf_Data *__data); 391 392/* Create new data descriptor for section SCN. */ 393extern 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. */ 398extern 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. */ 404extern char *elf_strptr (Elf *__elf, size_t __index, size_t __offset); 405 406 407/* Return header of archive. */ 408extern Elf_Arhdr *elf_getarhdr (Elf *__elf); 409 410/* Return offset in archive for current file ELF. */ 411extern int64_t elf_getaroff (Elf *__elf); 412 413/* Select archive element at OFFSET. */ 414extern size_t elf_rand (Elf *__elf, size_t __offset); 415 416/* Get symbol table of archive. */ 417extern Elf_Arsym *elf_getarsym (Elf *__elf, size_t *__narsyms); 418 419 420/* Control ELF descriptor. */ 421extern int elf_cntl (Elf *__elf, Elf_Cmd __cmd); 422 423/* Retrieve uninterpreted file contents. */ 424extern 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. */ 430extern 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. */ 434extern 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. */ 441extern Elf_Data *elf32_xlatetom (Elf_Data *__dest, const Elf_Data *__src, 442 unsigned int __encode); 443/* Same for 64 bit class. */ 444extern 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. */ 449extern Elf_Data *elf32_xlatetof (Elf_Data *__dest, const Elf_Data *__src, 450 unsigned int __encode); 451/* Same for 64 bit class. */ 452extern 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. */ 458extern 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. */ 464extern const char *elf_errmsg (int __error); 465 466 467/* Coordinate ELF library and application versions. */ 468extern unsigned int elf_version (unsigned int __version); 469 470/* Set fill bytes used to fill holes in data structures. */ 471extern void elf_fill (int __fill); 472 473/* Compute hash value. */ 474extern unsigned long int elf_hash (const char *__string) 475 __attribute__ ((__pure__)); 476 477/* Compute hash value using the GNU-specific hash function. */ 478extern 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. */ 483extern long int elf32_checksum (Elf *__elf); 484/* Similar but this time the binary calls is ELFCLASS64. */ 485extern long int elf64_checksum (Elf *__elf); 486 487#ifdef __cplusplus 488} 489#endif 490 491#endif /* libelf.h */ 492