libelf/libelf.h

   1 /* Interface for libelf.
   2    Copyright (C) 1998-2010 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 <sys/types.h>
  33
  34 /* Get the ELF types.  */
  35 #include <elf.h>
  36
  37
  38 /* Known translation types.  */
  39 typedef enum
  40 {
  41   ELF_T_BYTE,                   /* unsigned char */
  42   ELF_T_ADDR,                   /* Elf32_Addr, Elf64_Addr, ... */
  43   ELF_T_DYN,                    /* Dynamic section record.  */
  44   ELF_T_EHDR,                   /* ELF header.  */
  45   ELF_T_HALF,                   /* Elf32_Half, Elf64_Half, ... */
  46   ELF_T_OFF,                    /* Elf32_Off, Elf64_Off, ... */
  47   ELF_T_PHDR,                   /* Program header.  */
  48   ELF_T_RELA,                   /* Relocation entry with addend.  */
  49   ELF_T_REL,                    /* Relocation entry.  */
  50   ELF_T_SHDR,                   /* Section header.  */
  51   ELF_T_SWORD,                  /* Elf32_Sword, Elf64_Sword, ... */
  52   ELF_T_SYM,                    /* Symbol record.  */
  53   ELF_T_WORD,                   /* Elf32_Word, Elf64_Word, ... */
  54   ELF_T_XWORD,                  /* Elf32_Xword, Elf64_Xword, ... */
  55   ELF_T_SXWORD,                 /* Elf32_Sxword, Elf64_Sxword, ... */
  56   ELF_T_VDEF,                   /* Elf32_Verdef, Elf64_Verdef, ... */
  57   ELF_T_VDAUX,                  /* Elf32_Verdaux, Elf64_Verdaux, ... */
  58   ELF_T_VNEED,                  /* Elf32_Verneed, Elf64_Verneed, ... */
  59   ELF_T_VNAUX,                  /* Elf32_Vernaux, Elf64_Vernaux, ... */
  60   ELF_T_NHDR,                   /* Elf32_Nhdr, Elf64_Nhdr, ... */
  61   ELF_T_SYMINFO,                /* Elf32_Syminfo, Elf64_Syminfo, ... */
  62   ELF_T_MOVE,                   /* Elf32_Move, Elf64_Move, ... */
  63   ELF_T_LIB,                    /* Elf32_Lib, Elf64_Lib, ... */
  64   ELF_T_GNUHASH,                /* GNU-style hash section.  */
  65   ELF_T_AUXV,                   /* Elf32_auxv_t, Elf64_auxv_t, ... */
  66   /* Keep this the last entry.  */
  67   ELF_T_NUM
  68 } Elf_Type;
  69
  70 /* Descriptor for data to be converted to or from memory format.  */
  71 typedef struct
  72 {
  73   void *d_buf;                  /* Pointer to the actual data.  */
  74   Elf_Type d_type;              /* Type of this piece of data.  */
  75   unsigned int d_version;       /* ELF version.  */
  76   size_t d_size;                /* Size in bytes.  */
  77   loff_t d_off;                 /* Offset into section.  */
  78   size_t d_align;               /* Alignment in section.  */
  79 } Elf_Data;
  80
  81
  82 /* Commands for `...'.  */
  83 typedef enum
  84 {
  85   ELF_C_NULL,                   /* Nothing, terminate, or compute only.  */
  86   ELF_C_READ,                   /* Read .. */
  87   ELF_C_RDWR,                   /* Read and write .. */
  88   ELF_C_WRITE,                  /* Write .. */
  89   ELF_C_CLR,                    /* Clear flag.  */
  90   ELF_C_SET,                    /* Set flag.  */
  91   ELF_C_FDDONE,                 /* Signal that file descriptor will not be
  92                                    used anymore.  */
  93   ELF_C_FDREAD,                 /* Read rest of data so that file descriptor
  94                                    is not used anymore.  */
  95   /* The following are extensions.  */
  96   ELF_C_READ_MMAP,              /* Read, but mmap the file if possible.  */
  97   ELF_C_RDWR_MMAP,              /* Read and write, with mmap.  */
  98   ELF_C_WRITE_MMAP,             /* Write, with mmap.  */
  99   ELF_C_READ_MMAP_PRIVATE,      /* Read, but memory is writable, results are
 100                                    not written to the file.  */
 101   ELF_C_EMPTY,                  /* Copy basic file data but not the content. */
 102   /* Keep this the last entry.  */
 103   ELF_C_NUM
 104 } Elf_Cmd;
 105
 106
 107 /* Flags for the ELF structures.  */
 108 enum
 109 {
 110   ELF_F_DIRTY = 0x1,
 111 #define ELF_F_DIRTY             ELF_F_DIRTY
 112   ELF_F_LAYOUT = 0x4,
 113 #define ELF_F_LAYOUT            ELF_F_LAYOUT
 114   ELF_F_PERMISSIVE = 0x8
 115 #define ELF_F_PERMISSIVE        ELF_F_PERMISSIVE
 116 };
 117
 118
 119 /* Identification values for recognized object files.  */
 120 typedef enum
 121 {
 122   ELF_K_NONE,                   /* Unknown.  */
 123   ELF_K_AR,                     /* Archive.  */
 124   ELF_K_COFF,                   /* Stupid old COFF.  */
 125   ELF_K_ELF,                    /* ELF file.  */
 126   /* Keep this the last entry.  */
 127   ELF_K_NUM
 128 } Elf_Kind;
 129
 130
 131 /* Archive member header.  */
 132 typedef struct
 133 {
 134   char *ar_name;                /* Name of archive member.  */
 135   time_t ar_date;               /* File date.  */
 136   uid_t ar_uid;                 /* User ID.  */
 137   gid_t ar_gid;                 /* Group ID.  */
 138   mode_t ar_mode;               /* File mode.  */
 139   loff_t ar_size;               /* File size.  */
 140   char *ar_rawname;             /* Original name of archive member.  */
 141 } Elf_Arhdr;
 142
 143
 144 /* Archive symbol table entry.  */
 145 typedef struct
 146 {
 147   char *as_name;                /* Symbol name.  */
 148   size_t as_off;                /* Offset for this file in the archive.  */
 149   unsigned long int as_hash;    /* Hash value of the name.  */
 150 } Elf_Arsym;
 151
 152
 153 /* Descriptor for the ELF file.  */
 154 typedef struct Elf Elf;
 155
 156 /* Descriptor for ELF file section.  */
 157 typedef struct Elf_Scn Elf_Scn;
 158
 159
 160 #ifdef __cplusplus
 161 extern "C" {
 162 #endif
 163
 164 /* Return descriptor for ELF file to work according to CMD.  */
 165 extern Elf *elf_begin (int __fildes, Elf_Cmd __cmd, Elf *__ref);
 166
 167 /* Create a clone of an existing ELF descriptor.  */
 168   extern Elf *elf_clone (Elf *__elf, Elf_Cmd __cmd);
 169
 170 /* Create descriptor for memory region.  */
 171 extern Elf *elf_memory (char *__image, size_t __size);
 172
 173 /* Advance archive descriptor to next element.  */
 174 extern Elf_Cmd elf_next (Elf *__elf);
 175
 176 /* Free resources allocated for ELF.  */
 177 extern int elf_end (Elf *__elf);
 178
 179 /* Update ELF descriptor and write file to disk.  */
 180 extern loff_t elf_update (Elf *__elf, Elf_Cmd __cmd);
 181
 182 /* Determine what kind of file is associated with ELF.  */
 183 extern Elf_Kind elf_kind (Elf *__elf) __attribute__ ((__pure__));
 184
 185 /* Get the base offset for an object file.  */
 186 extern loff_t elf_getbase (Elf *__elf);
 187
 188
 189 /* Retrieve file identification data.  */
 190 extern char *elf_getident (Elf *__elf, size_t *__nbytes);
 191
 192 /* Retrieve class-dependent object file header.  */
 193 extern Elf32_Ehdr *elf32_getehdr (Elf *__elf);
 194 /* Similar but this time the binary calls is ELFCLASS64.  */
 195 extern Elf64_Ehdr *elf64_getehdr (Elf *__elf);
 196
 197 /* Create ELF header if none exists.  */
 198 extern Elf32_Ehdr *elf32_newehdr (Elf *__elf);
 199 /* Similar but this time the binary calls is ELFCLASS64.  */
 200 extern Elf64_Ehdr *elf64_newehdr (Elf *__elf);
 201
 202 /* Get the number of program headers in the ELF file.  If the file uses
 203    more headers than can be represented in the e_phnum field of the ELF
 204    header the information from the sh_info field in the zeroth section
 205    header is used.  */
 206 extern int elf_getphdrnum (Elf *__elf, size_t *__dst);
 207
 208 /* Retrieve class-dependent program header table.  */
 209 extern Elf32_Phdr *elf32_getphdr (Elf *__elf);
 210 /* Similar but this time the binary calls is ELFCLASS64.  */
 211 extern Elf64_Phdr *elf64_getphdr (Elf *__elf);
 212
 213 /* Create ELF program header.  */
 214 extern Elf32_Phdr *elf32_newphdr (Elf *__elf, size_t __cnt);
 215 /* Similar but this time the binary calls is ELFCLASS64.  */
 216 extern Elf64_Phdr *elf64_newphdr (Elf *__elf, size_t __cnt);
 217
 218
 219 /* Get section at INDEX.  */
 220 extern Elf_Scn *elf_getscn (Elf *__elf, size_t __index);
 221
 222 /* Get section at OFFSET.  */
 223 extern Elf_Scn *elf32_offscn (Elf *__elf, Elf32_Off __offset);
 224 /* Similar bug this time the binary calls is ELFCLASS64.  */
 225 extern Elf_Scn *elf64_offscn (Elf *__elf, Elf64_Off __offset);
 226
 227 /* Get index of section.  */
 228 extern size_t elf_ndxscn (Elf_Scn *__scn);
 229
 230 /* Get section with next section index.  */
 231 extern Elf_Scn *elf_nextscn (Elf *__elf, Elf_Scn *__scn);
 232
 233 /* Create a new section and append it at the end of the table.  */
 234 extern Elf_Scn *elf_newscn (Elf *__elf);
 235
 236 /* Get the section index of the extended section index table for the
 237    given symbol table.  */
 238 extern int elf_scnshndx (Elf_Scn *__scn);
 239
 240 /* Get the number of sections in the ELF file.  If the file uses more
 241    sections than can be represented in the e_shnum field of the ELF
 242    header the information from the sh_size field in the zeroth section
 243    header is used.  */
 244 extern int elf_getshdrnum (Elf *__elf, size_t *__dst);
 245 /* Sun messed up the implementation of 'elf_getshnum' in their implementation.
 246    It was agreed to make the same functionality available under a different
 247    name and obsolete the old name.  */
 248 extern int elf_getshnum (Elf *__elf, size_t *__dst)
 249      __attribute__ ((__deprecated__));
 250
 251
 252 /* Get the section index of the section header string table in the ELF
 253    file.  If the index cannot be represented in the e_shnum field of
 254    the ELF header the information from the sh_link field in the zeroth
 255    section header is used.  */
 256 extern int elf_getshdrstrndx (Elf *__elf, size_t *__dst);
 257 /* Sun messed up the implementation of 'elf_getshnum' in their implementation.
 258    It was agreed to make the same functionality available under a different
 259    name and obsolete the old name.  */
 260 extern int elf_getshstrndx (Elf *__elf, size_t *__dst)
 261      __attribute__ ((__deprecated__));
 262
 263
 264 /* Retrieve section header of ELFCLASS32 binary.  */
 265 extern Elf32_Shdr *elf32_getshdr (Elf_Scn *__scn);
 266 /* Similar for ELFCLASS64.  */
 267 extern Elf64_Shdr *elf64_getshdr (Elf_Scn *__scn);
 268
 269
 270 /* Set or clear flags for ELF file.  */
 271 extern unsigned int elf_flagelf (Elf *__elf, Elf_Cmd __cmd,
 272                                  unsigned int __flags);
 273 /* Similarly for the ELF header.  */
 274 extern unsigned int elf_flagehdr (Elf *__elf, Elf_Cmd __cmd,
 275                                   unsigned int __flags);
 276 /* Similarly for the ELF program header.  */
 277 extern unsigned int elf_flagphdr (Elf *__elf, Elf_Cmd __cmd,
 278                                   unsigned int __flags);
 279 /* Similarly for the given ELF section.  */
 280 extern unsigned int elf_flagscn (Elf_Scn *__scn, Elf_Cmd __cmd,
 281                                  unsigned int __flags);
 282 /* Similarly for the given ELF data.  */
 283 extern unsigned int elf_flagdata (Elf_Data *__data, Elf_Cmd __cmd,
 284                                   unsigned int __flags);
 285 /* Similarly for the given ELF section header.  */
 286 extern unsigned int elf_flagshdr (Elf_Scn *__scn, Elf_Cmd __cmd,
 287                                   unsigned int __flags);
 288
 289
 290 /* Get data from section while translating from file representation
 291    to memory representation.  */
 292 extern Elf_Data *elf_getdata (Elf_Scn *__scn, Elf_Data *__data);
 293
 294 /* Get uninterpreted section content.  */
 295 extern Elf_Data *elf_rawdata (Elf_Scn *__scn, Elf_Data *__data);
 296
 297 /* Create new data descriptor for section SCN.  */
 298 extern Elf_Data *elf_newdata (Elf_Scn *__scn);
 299
 300 /* Get data translated from a chunk of the file contents as section data
 301    would be for TYPE.  The resulting Elf_Data pointer is valid until
 302    elf_end (ELF) is called.  */
 303 extern Elf_Data *elf_getdata_rawchunk (Elf *__elf,
 304                                        loff_t __offset, size_t __size,
 305                                        Elf_Type __type);
 306
 307
 308 /* Return pointer to string at OFFSET in section INDEX.  */
 309 extern char *elf_strptr (Elf *__elf, size_t __index, size_t __offset);
 310
 311
 312 /* Return header of archive.  */
 313 extern Elf_Arhdr *elf_getarhdr (Elf *__elf);
 314
 315 /* Return offset in archive for current file ELF.  */
 316 extern loff_t elf_getaroff (Elf *__elf);
 317
 318 /* Select archive element at OFFSET.  */
 319 extern size_t elf_rand (Elf *__elf, size_t __offset);
 320
 321 /* Get symbol table of archive.  */
 322 extern Elf_Arsym *elf_getarsym (Elf *__elf, size_t *__narsyms);
 323
 324
 325 /* Control ELF descriptor.  */
 326 extern int elf_cntl (Elf *__elf, Elf_Cmd __cmd);
 327
 328 /* Retrieve uninterpreted file contents.  */
 329 extern char *elf_rawfile (Elf *__elf, size_t *__nbytes);
 330
 331
 332 /* Return size of array of COUNT elements of the type denoted by TYPE
 333    in the external representation.  The binary class is taken from ELF.
 334    The result is based on version VERSION of the ELF standard.  */
 335 extern size_t elf32_fsize (Elf_Type __type, size_t __count,
 336                            unsigned int __version)
 337        __attribute__ ((__const__));
 338 /* Similar but this time the binary calls is ELFCLASS64.  */
 339 extern size_t elf64_fsize (Elf_Type __type, size_t __count,
 340                            unsigned int __version)
 341        __attribute__ ((__const__));
 342
 343
 344 /* Convert data structure from the representation in the file represented
 345    by ELF to their memory representation.  */
 346 extern Elf_Data *elf32_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
 347                                  unsigned int __encode);
 348 /* Same for 64 bit class.  */
 349 extern Elf_Data *elf64_xlatetom (Elf_Data *__dest, const Elf_Data *__src,
 350                                  unsigned int __encode);
 351
 352 /* Convert data structure from to the representation in memory
 353    represented by ELF file representation.  */
 354 extern Elf_Data *elf32_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
 355                                  unsigned int __encode);
 356 /* Same for 64 bit class.  */
 357 extern Elf_Data *elf64_xlatetof (Elf_Data *__dest, const Elf_Data *__src,
 358                                  unsigned int __encode);
 359
 360
 361 /* Return error code of last failing function call.  This value is kept
 362    separately for each thread.  */
 363 extern int elf_errno (void);
 364
 365 /* Return error string for ERROR.  If ERROR is zero, return error string
 366    for most recent error or NULL is none occurred.  If ERROR is -1 the
 367    behaviour is similar to the last case except that not NULL but a legal
 368    string is returned.  */
 369 extern const char *elf_errmsg (int __error);
 370
 371
 372 /* Coordinate ELF library and application versions.  */
 373 extern unsigned int elf_version (unsigned int __version);
 374
 375 /* Set fill bytes used to fill holes in data structures.  */
 376 extern void elf_fill (int __fill);
 377
 378 /* Compute hash value.  */
 379 extern unsigned long int elf_hash (const char *__string)
 380        __attribute__ ((__pure__));
 381
 382 /* Compute hash value using the GNU-specific hash function.  */
 383 extern unsigned long int elf_gnu_hash (const char *__string)
 384        __attribute__ ((__pure__));
 385
 386
 387 /* Compute simple checksum from permanent parts of the ELF file.  */
 388 extern long int elf32_checksum (Elf *__elf);
 389 /* Similar but this time the binary calls is ELFCLASS64.  */
 390 extern long int elf64_checksum (Elf *__elf);
 391
 392 #ifdef __cplusplus
 393 }
 394 #endif
 395
 396 #endif  /* libelf.h */