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