libelf - Man Page

Elfutils library (libelf, libelf.so, -lelf)

#include <libelf.h>
#include <gelf.h>

The libelf library provides an API for reading, writing, and manipulating ELF (Executable and Linkable Format) files. ELF is a standard format for object files, shared libraries, core dumps, and executables.  See elf(5) for more information regarding ELF.

libelf provides routines for working with ELF object file headers, sections, symbol tables, relocation entries, and other key components.

The core of the library is based on Elf file descriptors representing ELF files, which can be read from, written to, or updated in-place. The elf_begin function initializes access to an ELF object, while additional functions like elf_getscn, elf_getdata, and elf_ndxscn provide access to specific parts of the ELF file.

<gelf.h> provides a class-independent interface to libelf that transparently handles both ELFCLASS32 and ELFCLASS64 binaries. This allows callers to avoid selecting libelf functions that are specialized for working with a particular class of ELF binary.

GElf_ types defined in <gelf.h> are aliases for their Elf64_ equivalents. Any conversions to Elf32_ types are handled internally by gelf_ functions. See Gelf Data Structures and Gelf Macros for more information. When using gelf_ functions that modify data structure values for ELFCLASS32 binaries, the size of the value should not exceed the maximum size of the ELFCLASS32 equivalent.

The libelf library distinguishes between the file representation of an ELF file and its memory representation.

File Representation refers to the format in which an ELF file is stored on disk. The fields in the file may use specific sizes, alignment, and byte ordering (endianness) that could be different from the native format used by the host system.

Memory Representation refers to the way the ELF data is organized when loaded into an application's memory. In memory, the data structures are typically converted into the native format of the host system (e.g., the system's endianness, word size, and alignment).

libelf provides the following functions to translate ELF data between file and memory representations: elf32_xlatetom, elf64_xlatetom, elf32_xlatetof, and elf64_xlatetof. <gelf.h> provides gelf_xlatetom and gelf_xlatetof for class-independent translation between file and memory representations.

See elf32_xlatetom(3) for more information.

To account for the possibility of multiple versions of the ELF specification, the ELF version number must be specified with the elf_version function before any other libelf functions. This function sets libelf's ELF version to the specified value.  At this time the only supported ELF version is EV_CURRENT.

Elf descriptors the central libelf object for accessing and manipulating ELF files.  They are created with the elf_begin, elf_clone, and elf_memory functions and closed with the elf_end function.

libelf also provides Elf_Scn and Elf_Data descriptors for ELF sections and section contents, respectively.  Members of the Elf_Data struct are described below. Members of the Elf and Elf_Scn structs are hidden from applications.

These descriptors can be acquired and modified using various functions provided by libelf.  See libelf.h for a complete list.

If a libelf function encounters an error it will set an internal error code that can be retrieved with elf_errno. Each thread maintains its own separate error code.  The meaning of each error code can be determined with elf_errmsg, which returns a string describing the error. libelf functions returning a pointer return NULL on failure.

libelf manages all of the memory it allocates and frees it with elf_end. The application must not call free on any memory allocated by libelf.

libelf uses the following prefix format. See libelf.h and gelf.h for more information.

elf_

Functions usable with both 32-bit and 64-bit ELF files.

elf32_

Functions usable with 32-bit ELF files.

elf64_

Functions usable with 64-bit ELF files.

Elf_

Type that represents data for both 32-bit and 64-bit ELF files.

Elf32_

Type that represents data for 32-bit ELF files.

Elf64_

Type that represents data for 64-bit ELF files.

ELF_C_

Elf_Cmd values used in functions such as elf_flagset and elf_cntl.

ELF_F_

Flags for ELF structures.

ELF_K_

Elf_Kind Identification values for recognized object file types.

ELF_T_

Elf_Type values representing the known types of ELF data such as ELF_T_BYTE, (unsigned char) ELF_T_REL, (relocation entry) or ELF_T_SYM (symbol record).

gelf_

Class-independent functions.

GElf_

Class-independent types.

GELF_

Class-independent macros.

libelf implements the following data structures, in addition to including the data structures given in the ELF specification (see elf(5) for more information).

typedef struct {
   Elf32_Word   ch_type;
   Elf32_Word   ch_size;
   Elf32_Word   ch_addralign;
} Elf32_Chdr;

typedef struct {
   Elf64_Word   ch_type;
   Elf64_Word   ch_reserved;
   Elf64_Xword  ch_size;
   Elf64_Xword  ch_addralign;
 } Elf64_Chdr;

typedef struct {
  void *d_buf;
  Elf_Type d_type;
  unsigned int d_version;
  size_t d_size;
  int64_t d_off;
  size_t d_align;
} Elf_Data;

typedef struct {
  char *ar_name;
  time_t ar_date;
  uid_t ar_uid;
  gid_t ar_gid;
  mode_t ar_mode;
  int64_t ar_size;
  char *ar_rawname;
} Elf_Arhdr;

typedef struct {
  char *as_name;
  size_t as_off;
  unsigned long int as_hash;
} Elf_Arsym;

GElf_ types are aliases for their Elf64_ equivalents. See elf(5) for more information regarding the underlying types.

All GELF_ macros are aliases for their ELF64_ equivalents. See elf(5) for more information regarding the underlying macros.

Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.

avrdude(1), elf32_checksum(3), elf32_fsize(3), elf32_getchdr(3), elf32_getphdr(3), elf32_getshdr(3), elf32_newehdr(3), elf32_newphdr(3), elf32_offscn(3), elf32_xlatetom(3), elf64_offscn(3), elf_begin(3), elf_cntl(3), elf_end(3), elf_fill(3), elf_flagelf(3), elf_getarhdr(3), elf_getaroff(3), elf_getarsym(3), elf_getbase(3), elf_getdata_rawchunk(3), elf_getident(3), elf_getphdrnum(3), elf_getscn(3), elf_getshdrnum(3), elf_getshdrstrndx(3), elf_hash(3), elf_kind(3), elf_memory(3), elf_ndxscn(3), elf_newdata(3), elf_newscn(3), elf_next(3), elf_nextscn(3), elf_rand(3), elf_rawdata(3), elf_rawfile(3), elf_scnshndx(3), elf_strptr(3), gelf_checksum(3), gelf_fsize(3), gelf_getauxv(3), gelf_getchdr(3), gelf_getclass(3), gelf_getdyn(3), gelf_getehdr(3), gelf_getlib(3), gelf_getmove(3), gelf_getnote(3), gelf_getphdr(3), gelf_getrel(3), gelf_getshdr(3), gelf_getsym(3), gelf_getsyminfo(3), gelf_getsymshndx(3), gelf_getversym(3), gelf_newehdr(3), gelf_newphdr(3), gelf_offscn(3), gelf_update_auxv(3), gelf_update_dyn(3), gelf_update_ehdr(3), gelf_update_lib(3), gelf_update_move(3), gelf_update_phdr(3), gelf_update_rel(3), gelf_update_shdr(3), gelf_update_sym(3), gelf_update_syminfo(3), gelf_update_symshndx(3), gelf_update_versym(3), gelf_xlatetom(3).

The man page gelf(3) is an alias of libelf(3).