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. */ 110 typedef 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. */ 146 typedef 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 `...'. */ 158 typedef 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. */ 183 enum 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]. */ 194 enum 195 { 196 ELF_CHF_FORCE = 0x1 197 #define ELF_CHF_FORCE ELF_CHF_FORCE 198 }; 199 200 /* Identification values for recognized object files. */ 201 typedef 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. */ 213 typedef 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. */ 226 typedef 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. */ 235 typedef struct Elf Elf; 236 237 /* Descriptor for ELF file section. */ 238 typedef struct Elf_Scn Elf_Scn; 239 240 241 #ifdef __cplusplus 242 extern "C" { 243 #endif 244 245 /* Return descriptor for ELF file to work according to CMD. */ 246 extern 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. */ 252 extern Elf *elf_memory (char *__image, size_t __size); 253 254 /* Advance archive descriptor to next element. */ 255 extern Elf_Cmd elf_next (Elf *__elf); 256 257 /* Free resources allocated for ELF. */ 258 extern int elf_end (Elf *__elf); 259 260 /* Update ELF descriptor and write file to disk. */ 261 extern int64_t elf_update (Elf *__elf, Elf_Cmd __cmd); 262 263 /* Determine what kind of file is associated with ELF. */ 264 extern Elf_Kind elf_kind (Elf *__elf) __pure_attribute__; 265 266 /* Get the base offset for an object file. */ 267 extern int64_t elf_getbase (Elf *__elf); 268 269 270 /* Retrieve file identification data. */ 271 extern char *elf_getident (Elf *__elf, size_t *__nbytes); 272 273 /* Retrieve class-dependent object file header. */ 274 extern Elf32_Ehdr *elf32_getehdr (Elf *__elf); 275 /* Similar but this time the binary calls is ELFCLASS64. */ 276 extern Elf64_Ehdr *elf64_getehdr (Elf *__elf); 277 278 /* Create ELF header if none exists. */ 279 extern Elf32_Ehdr *elf32_newehdr (Elf *__elf); 280 /* Similar but this time the binary calls is ELFCLASS64. */ 281 extern 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. */ 287 extern int elf_getphdrnum (Elf *__elf, size_t *__dst); 288 289 /* Retrieve class-dependent program header table. */ 290 extern Elf32_Phdr *elf32_getphdr (Elf *__elf); 291 /* Similar but this time the binary calls is ELFCLASS64. */ 292 extern Elf64_Phdr *elf64_getphdr (Elf *__elf); 293 294 /* Create ELF program header. */ 295 extern Elf32_Phdr *elf32_newphdr (Elf *__elf, size_t __cnt); 296 /* Similar but this time the binary calls is ELFCLASS64. */ 297 extern Elf64_Phdr *elf64_newphdr (Elf *__elf, size_t __cnt); 298 299 300 /* Get section at INDEX. */ 301 extern Elf_Scn *elf_getscn (Elf *__elf, size_t __index); 302 303 /* Get section at OFFSET. */ 304 extern Elf_Scn *elf32_offscn (Elf *__elf, Elf32_Off __offset); 305 /* Similar but this time the binary calls is ELFCLASS64. */ 306 extern Elf_Scn *elf64_offscn (Elf *__elf, Elf64_Off __offset); 307 308 /* Get index of section. */ 309 extern size_t elf_ndxscn (Elf_Scn *__scn); 310 311 /* Get section with next section index. */ 312 extern Elf_Scn *elf_nextscn (Elf *__elf, Elf_Scn *__scn); 313 314 /* Create a new section and append it at the end of the table. */ 315 extern Elf_Scn *elf_newscn (Elf *__elf); 316 317 /* Get the section index of the extended section index table for the 318 given symbol table. */ 319 extern 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. */ 325 extern 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. */ 329 extern 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. */ 337 extern 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. */ 341 extern int elf_getshstrndx (Elf *__elf, size_t *__dst) 342 __deprecated_attribute__; 343 344 345 /* Retrieve section header of ELFCLASS32 binary. */ 346 extern Elf32_Shdr *elf32_getshdr (Elf_Scn *__scn); 347 /* Similar for ELFCLASS64. */ 348 extern 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. */ 353 extern Elf32_Chdr *elf32_getchdr (Elf_Scn *__scn); 354 extern 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. */ 409 extern int elf_compress (Elf_Scn *scn, int type, unsigned int flags); 410 extern int elf_compress_gnu (Elf_Scn *scn, int compress, unsigned int flags); 411 412 /* Set or clear flags for ELF file. */ 413 extern unsigned int elf_flagelf (Elf *__elf, Elf_Cmd __cmd, 414 unsigned int __flags); 415 /* Similarly for the ELF header. */ 416 extern unsigned int elf_flagehdr (Elf *__elf, Elf_Cmd __cmd, 417 unsigned int __flags); 418 /* Similarly for the ELF program header. */ 419 extern unsigned int elf_flagphdr (Elf *__elf, Elf_Cmd __cmd, 420 unsigned int __flags); 421 /* Similarly for the given ELF section. */ 422 extern unsigned int elf_flagscn (Elf_Scn *__scn, Elf_Cmd __cmd, 423 unsigned int __flags); 424 /* Similarly for the given ELF data. */ 425 extern unsigned int elf_flagdata (Elf_Data *__data, Elf_Cmd __cmd, 426 unsigned int __flags); 427 /* Similarly for the given ELF section header. */ 428 extern 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. */ 437 extern Elf_Data *elf_getdata (Elf_Scn *__scn, Elf_Data *__data); 438 439 /* Get uninterpreted section content. */ 440 extern Elf_Data *elf_rawdata (Elf_Scn *__scn, Elf_Data *__data); 441 442 /* Create new data descriptor for section SCN. */ 443 extern 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. */ 448 extern 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. */ 454 extern char *elf_strptr (Elf *__elf, size_t __index, size_t __offset); 455 456 457 /* Return header of archive. */ 458 extern Elf_Arhdr *elf_getarhdr (Elf *__elf); 459 460 /* Return offset in archive for current file ELF. */ 461 extern int64_t elf_getaroff (Elf *__elf); 462 463 /* Select archive element at OFFSET. */ 464 extern size_t elf_rand (Elf *__elf, size_t __offset); 465 466 /* Get symbol table of archive. */ 467 extern Elf_Arsym *elf_getarsym (Elf *__elf, size_t *__narsyms); 468 469 470 /* Control ELF descriptor. */ 471 extern int elf_cntl (Elf *__elf, Elf_Cmd __cmd); 472 473 /* Retrieve uninterpreted file contents. */ 474 extern 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. */ 480 extern 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. */ 484 extern 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. */ 491 extern Elf_Data *elf32_xlatetom (Elf_Data *__dest, const Elf_Data *__src, 492 unsigned int __encode); 493 /* Same for 64 bit class. */ 494 extern 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. */ 499 extern Elf_Data *elf32_xlatetof (Elf_Data *__dest, const Elf_Data *__src, 500 unsigned int __encode); 501 /* Same for 64 bit class. */ 502 extern 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. */ 508 extern 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. */ 514 extern const char *elf_errmsg (int __error); 515 516 517 /* Coordinate ELF library and application versions. */ 518 extern unsigned int elf_version (unsigned int __version); 519 520 /* Set fill bytes used to fill holes in data structures. */ 521 extern void elf_fill (int __fill); 522 523 /* Compute hash value. */ 524 extern unsigned long int elf_hash (const char *__string) 525 __pure_attribute__; 526 527 /* Compute hash value using the GNU-specific hash function. */ 528 extern 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. */ 533 extern long int elf32_checksum (Elf *__elf); 534 /* Similar but this time the binary calls is ELFCLASS64. */ 535 extern long int elf64_checksum (Elf *__elf); 536 537 #ifdef __cplusplus 538 } 539 #endif 540 541 #endif /* libelf.h */ 542