NAME

libelf - a library for accessing and manipulating ELF (Executable and Linkable Format) files

LIBRARY

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

SYNOPSIS

#include <libelf.h>

DESCRIPTION

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.

FILE VS MEMORY REPRESENTATION

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.

See elf32_xlatetom(3) for more information.

ELF VERSION

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.

DESCRIPTORS

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.

ERROR HANDLING

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.

MEMORY MANAGEMENT

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.

NAMESPACE

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

DATA STRUCTURES

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;

REPORTING BUGS

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