--- name: "gelf" section: "3" platform: "linux" package: "libelf" version: "0.197-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/libelf" --- # gelf(3) a library for accessing and manipulating ELF (Executable and Linkable Format) files Part of [libelf(3)](/libelf/3.md). ## NAME libelf - a library for accessing and manipulating ELF (Executable and Linkable Format) files ## LIBRARY Elfutils library (**libelf**, **libelf.so**, **-lelf**) ## SYNOPSIS ``` #include #include ``` ## 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)](/elf/5.md) 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 **\** 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 **\** 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**. **\** provides **gelf\_xlatetom** and **gelf\_xlatetof** for class-independent translation between file and memory representations. See [**elf32\_xlatetom**(3)](/elf32_xlatetom/3.md) 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)](/elf/5.md) 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)](/elf/5.md)** 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)](/elf/5.md)** 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 \ or https://sourceware.org/bugzilla/.