LIBELF(3)

💖 LIBELF — the libelf manual, but make it make sense 💖

okay bestie, sit down, hydrate, because we're about to talk about the Elfutils library — that's libelf, libelf.so, and -lelf if you're linking, iykyk. This is the whole programmer's manual and I am not skipping a single crumb. 🍓

---

✨ NAME ✨

libelf — a library for accessing and manipulating ELF (Executable and Linkable Format) files. that's the whole vibe. 💅

---

📚 LIBRARY 📚

Elfutils library, fr fr: libelf, libelf.so, -lelf.

---

🎀 SYNOPSIS 🎀

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

two headers, that's it, that's the whole entry point, slay. ✨

---

🌸 DESCRIPTION 🌸

So the libelf library hands you an API for reading, writing, and manipulating ELF (Executable and Linkable Format) files. And ELF? ELF is the standard format for object files, shared libraries, core dumps, and executables. if you wanna know more about ELF itself, go read elf(5), it's giving lore. 📖

libelf gives you routines for working with ELF object file headers, sections, symbol tables, relocation entries, and other key components. the whole squad. 🫶

The core of the library is based on Elf file descriptors representing ELF files — you can read from them, write to them, or update them in-place (main character energy, no copying required). The elf_begin function initializes access to an ELF object, while other functions like elf_getscn, elf_getdata, and elf_ndxscn give you access to specific parts of the ELF file. literally the friend group of functions. 💖

---

🌈 GELF INTERFACE 🌈

<gelf.h> provides a class-independent interface to libelf that transparently handles both ELFCLASS32 and ELFCLASS64 binaries. meaning: you don't have to go pick which libelf function is specialized for which class of ELF binary. it just works. obsessed. 😌

The GElf_ types defined in <gelf.h> are aliases for their Elf64_ equivalents. Any conversions to Elf32_ types are handled internally by gelf_ functions. Wanna see them? Peep GELF DATA STRUCTURES and GELF MACROS below. 👀

⚠️ heads up bestie: when you're 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. don't be out here overflowing, it's not cute. 💀

---

🦋 FILE VS MEMORY REPRESENTATION 🦋

The libelf library distinguishes between the file representation of an ELF file and its memory representation. two completely different eras, same girl.

File Representation = 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. it's got its own whole aesthetic. 💅

Memory Representation = 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). home turf energy. 🏠

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

See elf32_xlatetom(3) for more info. go read it, it's a good time. ✨

---

⭐ ELF VERSION ⭐

Because there might be multiple versions of the ELF specification out there (chaos, honestly), the ELF version number must be specified with the elf_version function before any other libelf functions. She sets libelf's ELF version to the specified value. Periodt. 🔥

💀 At this time the only supported ELF version is EV_CURRENT. that's it. that's the one.

---

👑 DESCRIPTORS 👑

Elf descriptors are the central libelf object for accessing and manipulating ELF files. They're created with the elf_begin, elf_clone, and elf_memory functions and closed with the elf_end function. open them, use them, close them — like a good houseguest. 🎀

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 (scroll down, bestie). Members of the Elf and Elf_Scn structs are hidden from applications. 🙈 like, mind your business, they're private.

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 you can retrieve with elf_errno. And get this — each thread maintains its own separate error code, so no cross-thread drama. 🧵✨

The meaning of each error code can be determined with elf_errmsg, which returns a string describing the error. And libelf functions returning a pointer return NULL on failure. classic. 💀

---

🧚 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. don't do it. not your memory, not your business. hands off. 🙅♀️

---

💜 NAMESPACE 💜

libelf uses the following prefix format. See libelf.h and gelf.h for more information. (iykyk — the prefix tells you exactly what you're dealing with)

• 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). so this is the bonus content, the extra lore. ✨

🎀 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. (not yours, bestie)
• 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. here's the full glow-up chart, every single one: 👇

• 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. same energy, macro edition: 💅

• 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 🫶

Found a bug? (not me manifesting one 😭) Report bugs to <elfutils-devel@sourceware.org> or at https://sourceware.org/bugzilla/. the devs wanna hear it, fr fr. 💖

---

and that's the whole page, bestie!! 🦋 this was the Libelf Programmer's Manual, dated 2024-10-18, and the page itself is filed under LIBELF(3). go forth and manipulate some ELF files responsibly, mwah 💅✨🌸