libelf/libelf.h

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