LIEF Docs Extended Sponsor

C++

Parser

class Parser

Main interface to parse an executable regardless of its format.

Subclassed by LIEF::ELF::Parser, LIEF::MachO::BinaryParser, LIEF::MachO::Parser, LIEF::PE::Parser

Public Static Functions

static std::unique_ptr<Binary> parse(const std::string &filename)

Construct an LIEF::Binary from the given filename.

See also

LIEF::MachO::Parser::parse

Warning

If the target file is a FAT Mach-O, it will return the last one

static std::unique_ptr<Binary> parse(const std::vector<uint8_t> &raw)

Construct an LIEF::Binary from the given raw data.

See also

LIEF::MachO::Parser::parse

Warning

If the target file is a FAT Mach-O, it will return the last one

static std::unique_ptr<Binary> parse(std::unique_ptr<BinaryStream> stream)

Construct an LIEF::Binary from the given stream.

See also

LIEF::MachO::Parser::parse

Warning

If the target file is a FAT Mach-O, it will return the last one

Binary

class Binary : public LIEF::Object

Generic interface representing a binary executable.

This class provides a unified interface across multiple binary formats such as ELF, PE, Mach-O, and others. It enables users to access binary components like headers, sections, symbols, relocations, and functions in a format-agnostic way.

Subclasses like LIEF::PE::Binary implement format-specific API

Subclassed by LIEF::ELF::Binary, LIEF::MachO::Binary, LIEF::PE::Binary

Public Types

enum class VA_TYPES

Enumeration of virtual address types used for patching and memory access.

Values:

enumerator AUTO = 0

Automatically determine if the address is absolute or relative (default behavior).

enumerator RVA = 1

Relative Virtual Address (RVA), offset from image base.

enumerator VA = 2

Absolute Virtual Address.

enum FORMATS

Values:

enumerator UNKNOWN = 0
enumerator ELF
enumerator PE
enumerator MACHO
enumerator OAT
using functions_t = std::vector<Function>
using sections_t = std::vector<Section*>

Internal container.

using it_sections = ref_iterator<sections_t>

Iterator that outputs LIEF::Section&.

using it_const_sections = const_ref_iterator<sections_t>

Iterator that outputs const LIEF::Section&.

using symbols_t = std::vector<Symbol*>

Internal container.

using it_symbols = ref_iterator<symbols_t>

Iterator that outputs LIEF::Symbol&.

using it_const_symbols = const_ref_iterator<symbols_t>

Iterator that outputs const LIEF::Symbol&.

using relocations_t = std::vector<Relocation*>

Internal container.

using it_relocations = ref_iterator<relocations_t>

Iterator that outputs LIEF::Relocation&.

using it_const_relocations = const_ref_iterator<relocations_t>

Iterator that outputs const LIEF::Relocation&.

using instructions_it = iterator_range<assembly::Instruction::Iterator>

Instruction iterator.

Public Functions

Binary()
Binary(FORMATS fmt)
~Binary() override
Binary &operator=(const Binary&) = delete
Binary(const Binary&) = delete
inline FORMATS format() const

Executable format (ELF, PE, Mach-O) of the underlying binary.

inline Header header() const

Return the abstract header of the binary.

inline it_symbols symbols()

Return an iterator over the abstracted symbols in which the elements can be modified.

inline it_const_symbols symbols() const

Return an iterator over the abstracted symbols in which the elements can’t be modified.

inline bool has_symbol(const std::string &name) const

Check if a Symbol with the given name exists.

const Symbol *get_symbol(const std::string &name) const

Return the Symbol with the given name If the symbol does not exist, return a nullptr.

inline Symbol *get_symbol(const std::string &name)
inline it_sections sections()

Return an iterator over the binary’s sections (LIEF::Section).

inline it_const_sections sections() const
virtual void remove_section(const std::string &name, bool clear = false) = 0

Remove all the sections in the underlying binary.

inline it_relocations relocations()

Return an iterator over the binary relocations (LIEF::Relocation).

inline it_const_relocations relocations() const
virtual uint64_t entrypoint() const = 0

Binary’s entrypoint (if any).

inline uint64_t original_size() const

Binary’s original size.

inline functions_t exported_functions() const

Return the functions exported by the binary.

inline std::vector<std::string> imported_libraries() const

Return libraries which are imported by the binary.

inline functions_t imported_functions() const

Return functions imported by the binary.

virtual result<uint64_t> get_function_address(const std::string &func_name) const

Return the address of the given function name.

virtual void accept(Visitor &visitor) const override

Method so that a visitor can visit us.

std::vector<uint64_t> xref(uint64_t address) const
virtual void patch_address(uint64_t address, const std::vector<uint8_t> &patch_value, VA_TYPES addr_type = VA_TYPES::AUTO) = 0

Patch the content at virtual address address with patch_value.

Parameters:

  • address – [in] Address to patch

  • patch_value – [in] Patch to apply

  • addr_type – [in] Specify if the address should be used as an absolute virtual address or a RVA

virtual void patch_address(uint64_t address, uint64_t patch_value, size_t size = sizeof(uint64_t), VA_TYPES addr_type = VA_TYPES::AUTO) = 0

Patch the address with the given value.

Parameters:

  • address – [in] Address to patch

  • patch_value – [in] Patch to apply

  • size – [in] Size of the value in bytes (1, 2, … 8)

  • addr_type – [in] Specify if the address should be used as an absolute virtual address or an RVA

virtual span<const uint8_t> get_content_from_virtual_address(uint64_t virtual_address, uint64_t size, VA_TYPES addr_type = VA_TYPES::AUTO) const = 0

Return the content located at the given virtual address.

template<class T>
inline LIEF::result<T> get_int_from_virtual_address(uint64_t va, VA_TYPES addr_type = VA_TYPES::AUTO) const

Get the integer value at the given virtual address.

inline void original_size(uint64_t size)

Change binary’s original size.

Warning

This function should be used carefully as some optimizations can be performed with this value

virtual bool is_pie() const = 0

Check if the binary is position independent.

virtual bool has_nx() const = 0

Check if the binary uses NX protection.

virtual uint64_t imagebase() const = 0

Default image base address if the ASLR is not enabled.

virtual functions_t ctor_functions() const = 0

Constructor functions that are called prior any other functions.

virtual result<uint64_t> offset_to_virtual_address(uint64_t offset, uint64_t slide = 0) const = 0

Convert the given offset into a virtual address.

Parameters:

  • offset – [in] The offset to convert.

  • slide – [in] If not 0, it will replace the default base address (if any)

inline virtual std::ostream &print(std::ostream &os) const
DebugInfo *debug_info() const

Return the debug info if present. It can be either a LIEF::dwarf::DebugInfo or a LIEF::pdb::DebugInfo.

For ELF and Mach-O binaries, it returns the given DebugInfo object only if the binary embeds the DWARF debug info in the binary itself.

For PE file, this function tries to find the external PDB using the LIEF::PE::CodeViewPDB::filename() output (if present). One can also use LIEF::pdb::load() or LIEF::pdb::DebugInfo::from_file() to get PDB debug info.

Warning

This function requires LIEF’s extended version otherwise it always returns a nullptr

instructions_it disassemble(uint64_t address, size_t size) const

Disassemble code starting at the given virtual address and with the given size.

auto insts = binary->disassemble(0xacde, 100);
for (std::unique_ptr<assembly::Instruction> inst : insts) {
  std::cout << inst->to_string() << '\n';
}

See also

LIEF::assembly::Instruction

instructions_it disassemble(uint64_t address) const

Disassemble code starting at the given virtual address.

auto insts = binary->disassemble(0xacde);
for (std::unique_ptr<assembly::Instruction> inst : insts) {
  std::cout << inst->to_string() << '\n';
}

See also

LIEF::assembly::Instruction

instructions_it disassemble(const std::string &function) const

Disassemble code for the given symbol name.

auto insts = binary->disassemble("__libc_start_main");
for (std::unique_ptr<assembly::Instruction> inst : insts) {
  std::cout << inst->to_string() << '\n';
}

See also

LIEF::assembly::Instruction

instructions_it disassemble(const uint8_t *buffer, size_t size, uint64_t address = 0) const

Disassemble code provided by the given buffer at the specified address parameter.

See also

LIEF::assembly::Instruction

inline instructions_it disassemble(const std::vector<uint8_t> &buffer, uint64_t address = 0) const

Disassemble code provided by the given vector of bytes at the specified address parameter.

See also

LIEF::assembly::Instruction

inline instructions_it disassemble(LIEF::span<const uint8_t> buffer, uint64_t address = 0) const
inline instructions_it disassemble(LIEF::span<uint8_t> buffer, uint64_t address = 0) const
std::vector<uint8_t> assemble(uint64_t address, const std::string &Asm, assembly::AssemblerConfig &config = assembly::AssemblerConfig::default_config())

Assemble and patch the provided assembly code at the specified address.

The function returns the generated assembly bytes

bin->assemble(0x12000440, R"asm(
  xor rax, rbx;
  mov rcx, rax;
)asm");

If you need to configure the assembly engine or to define addresses for symbols, you can provide your own assembly::AssemblerConfig.

std::vector<uint8_t> assemble(uint64_t address, const llvm::MCInst &inst)

Assemble and patch the address with the given LLVM MCInst.

Warning

Because of ABI compatibility, this MCInst can only be used with the same version of LLVM used by LIEF (see documentation)

std::vector<uint8_t> assemble(uint64_t address, const std::vector<llvm::MCInst> &insts)

Assemble and patch the address with the given LLVM MCInst.

Warning

Because of ABI compatibility, this MCInst can only be used with the same version of LLVM used by LIEF (see documentation)

virtual uint64_t page_size() const

Get the default memory page size according to the architecture and the format of the current binary.

DebugInfo *load_debug_info(const std::string &path)

Load and associate an external debug file (e.g., DWARF or PDB) with this binary.

This method attempts to load the debug information from the file located at the given path, and binds it to the current binary instance. If successful, it returns a pointer to the loaded DebugInfo object.

Note

This function does not verify that the debug file matches the binary’s unique identifier (e.g., build ID, GUID).

Warning

It is the caller’s responsibility to ensure that the debug file is compatible with the binary. Incorrect associations may lead to inconsistent or invalid results.

Parameters:

path – Path to the external debug file (e.g., .dwarf, .pdb)

Returns:

Pointer to the loaded DebugInfo object on success, or nullptr on failure.

inline virtual uint64_t virtual_size() const

Size of the binary when mapped in memory.

Friends

inline friend std::ostream &operator<<(std::ostream &os, const Binary &binary)

Section

class Section : public LIEF::Object

Class which represents an abstracted section.

Subclassed by LIEF::COFF::Section, LIEF::ELF::Section, LIEF::MachO::Section, LIEF::PE::Section

Public Functions

Section() = default
inline Section(std::string name)
~Section() override = default
Section &operator=(const Section&) = default
Section(const Section&) = default
inline virtual std::string_view name() const

Section’s name.

inline virtual std::string_view fullname() const

Return the complete section’s name which might include trailing (0) bytes.

inline virtual span<const uint8_t> content() const

Section’s content.

inline virtual void size(uint64_t size)

Change the section size.

inline virtual uint64_t size() const

Section’s size (size in the binary, not the virtual size).

inline virtual uint64_t offset() const

Offset in the binary.

inline virtual uint64_t virtual_address() const

Address where the section should be mapped.

inline virtual void virtual_address(uint64_t virtual_address)
inline virtual void name(std::string name)

Change the section’s name.

inline virtual void content(const std::vector<uint8_t>&)

Change section content.

inline virtual void offset(uint64_t offset)
double entropy() const

Section’s entropy.

size_t search(uint64_t integer, size_t pos, size_t size) const
size_t search(const std::vector<uint8_t> &pattern, size_t pos = 0) const
size_t search(const std::string &pattern, size_t pos = 0) const
size_t search(uint64_t integer, size_t pos = 0) const
std::vector<size_t> search_all(uint64_t v, size_t size) const
std::vector<size_t> search_all(uint64_t v) const
std::vector<size_t> search_all(const std::string &v) const
virtual void accept(Visitor &visitor) const override

Method so that the visitor can visit us.

Public Static Attributes

static size_t npos = -1

Friends

friend std::ostream &operator<<(std::ostream &os, const Section &entry)

Symbol

class Symbol : public LIEF::Object

This class represents a symbol in an executable format.

Subclassed by LIEF::COFF::Symbol, LIEF::ELF::Symbol, LIEF::Function, LIEF::MachO::Symbol, LIEF::PE::DelayImportEntry, LIEF::PE::ExportEntry, LIEF::PE::ImportEntry

Public Functions

Symbol() = default
inline Symbol(std::string name)
inline Symbol(std::string name, uint64_t value)
inline Symbol(std::string name, uint64_t value, uint64_t size)
Symbol(const Symbol&) = default
Symbol &operator=(const Symbol&) = default
Symbol(Symbol&&) = default
Symbol &operator=(Symbol&&) = default
~Symbol() override = default
void swap(Symbol &other) noexcept
inline virtual std::string_view name() const

Return the symbol’s name.

inline virtual std::string &name()
inline virtual void name(std::string name)

Set symbol name.

inline virtual uint64_t value() const

Symbol’s value which is usually the address of the symbol.

inline virtual void value(uint64_t value)
inline virtual uint64_t size() const

The size of the symbol (when applicable).

inline virtual void size(uint64_t value)
virtual void accept(Visitor &visitor) const override

Method so that the visitor can visit us.

Friends

friend std::ostream &operator<<(std::ostream &os, const Symbol &entry)

Relocation

class Relocation : public LIEF::Object

Class which represents an abstracted Relocation.

Subclassed by LIEF::COFF::Relocation, LIEF::ELF::Relocation, LIEF::MachO::Relocation, LIEF::PE::RelocationEntry

Public Functions

Relocation() = default
inline Relocation(uint64_t address, uint8_t size)

Constructor from a relocation’s address and size.

~Relocation() override = default
Relocation &operator=(const Relocation&) = default
Relocation(const Relocation&) = default
inline void swap(Relocation &other)
inline virtual uint64_t address() const

Relocation’s address.

inline virtual size_t size() const

Relocation size in bits.

inline virtual void address(uint64_t address)
inline virtual void size(size_t size)
virtual void accept(Visitor &visitor) const override

Method so that the visitor can visit us.

inline virtual bool operator<(const Relocation &rhs) const

Comparison based on the Relocation’s address.

inline virtual bool operator<=(const Relocation &rhs) const

Comparison based on the Relocation’s address.

inline virtual bool operator>(const Relocation &rhs) const

Comparison based on the Relocation’s address.

inline virtual bool operator>=(const Relocation &rhs) const

Comparison based on the Relocation’s address.

Friends

friend std::ostream &operator<<(std::ostream &os, const Relocation &entry)

Function

class Function : public LIEF::Symbol

Class that represents a function in the binary.

Public Types

enum class FLAGS : uint32_t

Flags used to characterize the semantics of the function.

Values:

enumerator NONE = 0
enumerator CONSTRUCTOR = 1 << 0

The function acts as a constructor.

Usually this flag is associated with functions that are located in the .init_array, __mod_init_func or .tls sections

enumerator DESTRUCTOR = 1 << 1

The function acts as a destructor.

Usually this flag is associated with functions that are located in the .fini_array or __mod_term_func sections

enumerator DEBUG_INFO = 1 << 2

The function is associated with Debug information.

enumerator EXPORTED = 1 << 3

The function is exported by the binary and the address() method returns its virtual address in the binary.

enumerator IMPORTED = 1 << 4

The function is imported by the binary and the address() should return 0.

Public Functions

Function() = default
inline Function(const std::string &name)
inline Function(uint64_t address)
inline Function(const std::string &name, uint64_t address)
inline Function(const std::string &name, uint64_t address, FLAGS flags)
Function(const Function&) = default
Function &operator=(const Function&) = default
~Function() override = default
std::vector<FLAGS> flags_list() const

List of FLAGS.

inline FLAGS flags() const
inline Function &add(FLAGS f)

Add a flag to the current function.

inline bool has(FLAGS f) const

Check if the function has the given flag.

inline uint64_t address() const

Address of the current function. For functions that are set with the FLAGS::IMPORTED flag, this value is likely 0.

inline void address(uint64_t address)
virtual void accept(Visitor &visitor) const override

Friends

friend std::ostream &operator<<(std::ostream &os, const Function &entry)