LIBELF(3)

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>
#include <gelf.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.

GELF INTERFACE
<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.

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. <gelf.h> provides gelf_xlatetom and gelf_xlatetof for class-independent translation between file and memory representations. 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. libelf functions returning a pointer return NULL on failure.

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 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.

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).

  Section Compression Header
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;

ch_type
    Compression format type. Legal values include ELFCOMPRESS_ZLIB, ELFCOMPRESS_ZSTD, the inclusive range between ELFCOMPRESS_LOOS to ELFCOMPRESS_HIOS as well as the inclusive range between ELFCOMPRESS_LOPROC and ELFCOMPRESS_HIPROC

    ELFCOMPRESS_ZLIB
        ZLIB/DEFLATE algorithm.
    ELFCOMPRESS_ZSTD
        Zstandard algorithm.
    ELFCOMPRESS_LOOS
        Start of OS-specific compression types.
    ELFCOMPRESS_HIOS
        End of OS-specific compression types.
    ELFCOMPRESS_LOPROC
        Start of processor-specific compression types.
    ELFCOMPRESS_HIPROC
        End of processor-specific compression types.

ch_reserved
    Space reserved for use by libelf.

ch_size
    Data size of uncompressed section.

ch_addralign
    Alignment of uncompressed section.

  Section Data
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;

d_buf
    Pointer to the actual data. Use elf_getdata to retrieve data in memory representation and elf_rawdata to retrieve data in file representation.

d_type
    The Elf_Type of this piece of data. See the Elf_Type enum in libelf.h for descriptions of each value.

d_version
    The ELF version for this data.

d_size
    The size in bytes of this data.

d_off
    The section offset of this data.

d_align
    The section alignment of this data.

  Archive Member Header
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;

ar_name
    Name of archive member.

ar_data
    File date.

ar_uid
    User ID.

ar_gid
    Group ID.

ar_mode
    File mode.

ar_size
    File size.

ar_rawname
    Original name of archive member.

  Archive Symbol Table Entry
typedef struct {
  char *as_name;
  size_t as_off;
  unsigned long int as_hash;
} Elf_Arsym;

as_name
    Symbol name.

as_off
    Offset for this file in the archive.

as_hash
    Hash value of the name.

GELF DATA STRUCTURES
GElf_ types are aliases for their Elf64_ equivalents. See elf(5) for more information regarding the underlying types.
GElf type | Underlying 64-bit type
GElf_Half | Elf64_Half
GElf_Word | Elf64_Word
GElf_Sword | Elf64_Sword
GElf_Xword | Elf64_Xword
GElf_Sxword | Elf64_Sxword
GElf_Addr | Elf64_Addr
GElf_Off | Elf64_Off
GElf_Ehdr | Elf64_Ehdr
GElf_Shdr | Elf64_Shdr
GElf_Section | Elf64_Section
GElf_Sym | Elf64_Sym
GElf_Syminfo | Elf64_Syminfo
GElf_Rel | Elf64_Rel
GElf_Rela | Elf64_Rela
GElf_Relr | Elf64_Relr
GElf_Phdr | Elf64_Phdr
GElf_Chdr | Elf64_Chdr
GElf_Dyn | Elf64_Dyn
GElf_Verdef | Elf64_Verdef
GElf_Verdaux | Elf64_Verdaux
GElf_Verneed | Elf64_Verneed
GElf_Vernaux | Elf64_Vernaux
GElf_Versym | Elf64_Versym
GElf_auxv_t | Elf64_auxv_t
GElf_Nhdr | Elf64_Nhdr
GElf_Move | Elf64_Move
GElf_Lib | Elf64_Lib

GELF MACROS
All GELF_ macros are aliases for their ELF64_ equivalents. See elf(5) for more information regarding the underlying macros.
GElf macro | Underlying 64-bit macro
GELF_ST_BIND | ELF64_ST_BIND
GELF_ST_TYPE | ELF64_ST_TYPE
GELF_ST_INFO | ELF64_ST_INFO
GELF_ST_VISIBILITY | ELF64_ST_VISIBILITY
GELF_M_INFO | ELF64_M_INFO
GELF_M_SIZE | ELF64_M_SIZE
GELF_M_SYM | ELF64_M_SYM
GELF_R_INFO | ELF64_R_INFO
GELF_R_TYPE | ELF64_R_TYPE
GELF_R_SYM | ELF64_R_SYM

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