libelf/libelf.h

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