dl_elf_enumerator.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Jarosław Pelczar <jarek@jpelczar.com>
//
// SPDX-License-Identifier: BSD-2-Clause
 
#pragma once
 
#if !defined(__linux__) && !defined(__FreeBSD__) && !defined(__OpenBSD__) && !defined(__NetBSD__) &&                   \
    !defined(__DragonFly__)
#error "microfmt/inspector/dl_elf_enumerator.hpp only supports Linux and BSD systems"
#endif
 
#include <cstdint>
#include <cstring>
#include <dlfcn.h>
#include <link.h>
 
#include "../microfmt.hpp"
#include "elf_enumerator.hpp"
 
namespace microfmt::detail {
 
inline bool dl_phdr_image_bounds(const dl_phdr_info &info, uintptr_t &out_base, uintptr_t &out_size) noexcept {
  uintptr_t min_vaddr = 0;
  uintptr_t max_vaddr = 0;
  bool have_load = false;
 
  RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
 
  for (size_t i = 0; i < static_cast<size_t>(info.dlpi_phnum); ++i) {
    const auto &phdr = info.dlpi_phdr[i];
    if (phdr.p_type != PT_LOAD)
      continue;
    const auto start = static_cast<uintptr_t>(phdr.p_vaddr);
    const auto end = start + static_cast<uintptr_t>(phdr.p_memsz);
    if (!have_load || start < min_vaddr)
      min_vaddr = start;
    if (!have_load || end > max_vaddr)
      max_vaddr = end;
    have_load = true;
  }
 
  RELOCO_END_UNSAFE_BUFFER_USAGE;
 
  if (!have_load)
    return false;
  out_base = static_cast<uintptr_t>(info.dlpi_addr) + min_vaddr;
  out_size = max_vaddr - min_vaddr;
  return true;
}
 
#if defined(PT_ARM_EXIDX)
inline bool dl_phdr_exidx_bounds(const dl_phdr_info &info, uintptr_t &out_start, uintptr_t &out_end) noexcept {
  uintptr_t start = 0;
  uintptr_t end = 0;
  bool have_exidx = false;
 
  RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
 
  for (size_t i = 0; i < static_cast<size_t>(info.dlpi_phnum); ++i) {
    const auto &phdr = info.dlpi_phdr[i];
    if (phdr.p_type != PT_ARM_EXIDX)
      continue;
    start = static_cast<uintptr_t>(info.dlpi_addr) + static_cast<uintptr_t>(phdr.p_vaddr);
    end = start + static_cast<uintptr_t>(phdr.p_memsz);
    have_exidx = true;
    break;
  }
 
  RELOCO_END_UNSAFE_BUFFER_USAGE;
 
  if (!have_exidx || end <= start)
    return false;
  out_start = start;
  out_end = end;
  return true;
}
#endif // defined(PT_ARM_EXIDX)
 
#if defined(PT_GNU_EH_FRAME)
 
// Subset of the DW_EH_PE_* pointer-encoding constants (from the LSB/libgcc
// `.eh_frame_hdr` ABI) needed to decode the `eh_frame_ptr` field. Only the
// application/format combinations GCC and Clang actually emit are handled.
inline constexpr unsigned char k_dw_eh_pe_omit = 0xff;
inline constexpr unsigned char k_dw_eh_pe_format_mask = 0x0f;
inline constexpr unsigned char k_dw_eh_pe_application_mask = 0x70;
inline constexpr unsigned char k_dw_eh_pe_udata4 = 0x03;
inline constexpr unsigned char k_dw_eh_pe_sdata4 = 0x0b;
inline constexpr unsigned char k_dw_eh_pe_pcrel = 0x10;
inline constexpr unsigned char k_dw_eh_pe_absptr_application = 0x00;
 
// decodes raw bytes of a target address space; casts, pointers and offsets are bounded by the explicit lengths checked
// here.
RELOCO_BEGIN_UNSAFE_CODE
inline bool decode_eh_frame_hdr(uintptr_t hdr_start, uintptr_t hdr_end, uintptr_t &out_eh_frame_start) noexcept {
  // 4-byte fixed header + at least a 4-byte encoded eh_frame_ptr field.
  if (hdr_end < hdr_start || hdr_end - hdr_start < 8)
    return false;
 
  RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
  // NOLINTNEXTLINE(performance-no-int-to-ptr)
  const auto *bytes = reinterpret_cast<const unsigned char *>(hdr_start);
  const unsigned char version = bytes[0];
  const unsigned char eh_frame_ptr_enc = bytes[1];
  RELOCO_END_UNSAFE_BUFFER_USAGE;
 
  if (version != 1 || eh_frame_ptr_enc == k_dw_eh_pe_omit)
    return false;
 
  const unsigned char format = static_cast<unsigned char>(eh_frame_ptr_enc & k_dw_eh_pe_format_mask);
  const unsigned char application = static_cast<unsigned char>(eh_frame_ptr_enc & k_dw_eh_pe_application_mask);
  if (application != k_dw_eh_pe_pcrel && application != k_dw_eh_pe_absptr_application)
    return false; // Uncommon application; not worth mis-decoding.
  if (format != k_dw_eh_pe_udata4 && format != k_dw_eh_pe_sdata4)
    return false; // Uncommon format; not worth mis-decoding.
 
  const uintptr_t field_addr = hdr_start + 4;
  int32_t raw_value = 0;
  RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
  // NOLINTNEXTLINE(performance-no-int-to-ptr)
  std::memcpy(&raw_value, reinterpret_cast<const void *>(field_addr), sizeof(raw_value));
  RELOCO_END_UNSAFE_BUFFER_USAGE;
 
  const uintptr_t value = (format == k_dw_eh_pe_udata4) ? static_cast<uintptr_t>(static_cast<uint32_t>(raw_value))
                                                        : static_cast<uintptr_t>(raw_value);
 
  out_eh_frame_start = (application == k_dw_eh_pe_pcrel) ? field_addr + value : value;
  return true;
}
RELOCO_END_UNSAFE_CODE
 
inline bool dl_phdr_eh_frame_bounds(const dl_phdr_info &info, uintptr_t &out_start, uintptr_t &out_end) noexcept {
  uintptr_t hdr_start = 0;
  uintptr_t hdr_end = 0;
  bool have_eh_frame_hdr = false;
 
  RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
 
  for (size_t i = 0; i < static_cast<size_t>(info.dlpi_phnum); ++i) {
    const auto &phdr = info.dlpi_phdr[i];
    if (phdr.p_type != PT_GNU_EH_FRAME)
      continue;
    hdr_start = static_cast<uintptr_t>(info.dlpi_addr) + static_cast<uintptr_t>(phdr.p_vaddr);
    hdr_end = hdr_start + static_cast<uintptr_t>(phdr.p_memsz);
    have_eh_frame_hdr = true;
    break;
  }
 
  RELOCO_END_UNSAFE_BUFFER_USAGE;
 
  if (!have_eh_frame_hdr)
    return false;
 
  uintptr_t eh_frame_start = 0;
  if (!decode_eh_frame_hdr(hdr_start, hdr_end, eh_frame_start))
    return false;
 
  out_start = eh_frame_start;
  out_end = UINTPTR_MAX;
  return true;
}
#endif // defined(PT_GNU_EH_FRAME)
 
struct MICROFMT_API_CLASS RELOCO_POINTER dl_enumerate_state {
  span<elf_image_info> buffer;
  size_t count{0};
};
 
// decodes raw bytes of a target address space; casts, pointers and offsets are bounded by the explicit lengths checked
// here.
RELOCO_BEGIN_UNSAFE_CODE
inline int dl_enumerate_callback(dl_phdr_info *info, size_t, void *data) noexcept {
  auto &state = *static_cast<dl_enumerate_state *>(data);
  if (state.count >= state.buffer.size())
    return 1; // Buffer already full; stop iterating.
 
  uintptr_t base = 0;
  uintptr_t size = 0;
  if (!dl_phdr_image_bounds(*info, base, size))
    return 0; // No PT_LOAD segments (e.g. the Linux VDSO on some ABIs); skip.
 
  elf_image_info entry{};
  entry.image_name =
      (info->dlpi_name != nullptr && info->dlpi_name[0] != '\0') ? string_view(info->dlpi_name) : string_view("");
  entry.load_base = base;
  entry.image_size = size;
#if defined(PT_ARM_EXIDX)
  dl_phdr_exidx_bounds(*info, entry.exidx_start, entry.exidx_end);
#endif
#if defined(PT_GNU_EH_FRAME)
  dl_phdr_eh_frame_bounds(*info, entry.debug_frame_start, entry.debug_frame_end);
#endif
  state.buffer[state.count++] = entry;
  return 0;
}
RELOCO_END_UNSAFE_CODE
 
inline bool dl_enumerate_images(span<elf_image_info> out_buffer, size_t &out_count) noexcept {
  dl_enumerate_state state{out_buffer, 0};
  ::dl_iterate_phdr(&dl_enumerate_callback, &state);
  out_count = state.count;
  return true;
}
 
struct MICROFMT_API_CLASS dl_find_size_state {
  uintptr_t target_base{};
  uintptr_t size{0};
  uintptr_t exidx_start{0};
  uintptr_t exidx_end{0};
  uintptr_t debug_frame_start{0};
  uintptr_t debug_frame_end{0};
  bool found{false};
};
 
// decodes raw bytes of a target address space; casts, pointers and offsets are bounded by the explicit lengths checked
// here.
RELOCO_BEGIN_UNSAFE_CODE
inline int dl_find_size_callback(dl_phdr_info *info, size_t, void *data) noexcept {
  auto &state = *static_cast<dl_find_size_state *>(data);
  uintptr_t base = 0;
  uintptr_t size = 0;
  if (!dl_phdr_image_bounds(*info, base, size))
    return 0;
  if (base == state.target_base) {
    state.size = size;
#if defined(PT_ARM_EXIDX)
    dl_phdr_exidx_bounds(*info, state.exidx_start, state.exidx_end);
#endif
#if defined(PT_GNU_EH_FRAME)
    dl_phdr_eh_frame_bounds(*info, state.debug_frame_start, state.debug_frame_end);
#endif
    state.found = true;
    return 1; // Match found; stop iterating.
  }
  return 0;
}
RELOCO_END_UNSAFE_CODE
 
// decodes raw bytes of a target address space; casts, pointers and offsets are bounded by the explicit lengths checked
// here.
RELOCO_BEGIN_UNSAFE_CODE
inline bool dl_find_by_pc(uintptr_t pc, elf_image_info &out_info) noexcept {
  Dl_info info{};
  // NOLINTNEXTLINE(performance-no-int-to-ptr)
  if (::dladdr(reinterpret_cast<const void *>(pc), &info) == 0 || info.dli_fbase == nullptr)
    return false;
 
  elf_image_info result{};
  result.image_name =
      (info.dli_fname != nullptr && info.dli_fname[0] != '\0') ? string_view(info.dli_fname) : string_view("");
  result.load_base = reinterpret_cast<uintptr_t>(info.dli_fbase);
 
  dl_find_size_state size_state{result.load_base};
  ::dl_iterate_phdr(&dl_find_size_callback, &size_state);
  if (size_state.found) {
    result.image_size = size_state.size;
    result.exidx_start = size_state.exidx_start;
    result.exidx_end = size_state.exidx_end;
    result.debug_frame_start = size_state.debug_frame_start;
    result.debug_frame_end = size_state.debug_frame_end;
  }
 
  out_info = result;
  return true;
}
RELOCO_END_UNSAFE_CODE
 
} // namespace microfmt::detail
 
namespace microfmt {
 
struct dl_elf_enumerator_tag {};
 
struct dl_elf_enumerator_context {};
 
template <> struct elf_image_enumerator_traits<dl_elf_enumerator_tag> {
  using context_type = dl_elf_enumerator_context;
 
  static bool enumerate(value_ref<const context_type>, span<elf_image_info> buffer, size_t &count) noexcept {
    return detail::dl_enumerate_images(buffer, count);
  }
 
  static bool find_by_pc(value_ref<const context_type>, uintptr_t pc, elf_image_info &out_info) noexcept {
    return detail::dl_find_by_pc(pc, out_info);
  }
};
 
} // namespace microfmt