symbols.c

Go to the documentation of this file.

 
// Platform-specific binary names
#ifdef _WIN32
#define LLVM_SYMBOLIZER_BIN "llvm-symbolizer.exe"
#define ADDR2LINE_BIN "addr2line.exe"
#define popen _popen
#define pclose _pclose
#else
#define LLVM_SYMBOLIZER_BIN "llvm-symbolizer"
#define ADDR2LINE_BIN "addr2line"
#endif
 
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <stdatomic.h>
 
#ifndef _WIN32
#include <unistd.h>
#else
#include <windows.h>
#endif
 
#include <ascii-chat/platform/symbols.h>
#include <ascii-chat/platform/system.h>
#include <ascii-chat/common.h>
#include <ascii-chat/uthash/uthash.h>
#include <ascii-chat/platform/rwlock.h>
#include <ascii-chat/platform/init.h>
#include <ascii-chat/util/path.h>
#include <ascii-chat/util/string.h>
 
// ============================================================================
// Constants
// ============================================================================
 
// Sentinel string for failed allocations (replaces NULL in middle of array)
#define NULL_SENTINEL "[NULL]"
 
// ============================================================================
// Symbolizer Type Selection
// ============================================================================
 
typedef enum {
  SYMBOLIZER_NONE = 0,      // No symbolizer available, use raw addresses
  SYMBOLIZER_LLVM = 1,      // llvm-symbolizer (preferred on all platforms)
  SYMBOLIZER_ADDR2LINE = 2, // addr2line (fallback)
} symbolizer_type_t;
 
static symbolizer_type_t g_symbolizer_type = SYMBOLIZER_NONE;
static atomic_bool g_symbolizer_detected = false;
static atomic_bool g_llvm_symbolizer_checked = false;
static atomic_bool g_llvm_symbolizer_available = false;
static char g_llvm_symbolizer_cmd[PLATFORM_MAX_PATH_LENGTH];
static atomic_bool g_addr2line_checked = false;
static atomic_bool g_addr2line_available = false;
static char g_addr2line_cmd[PLATFORM_MAX_PATH_LENGTH];
static static_mutex_t g_symbolizer_detection_mutex = STATIC_MUTEX_INIT;
 
// ============================================================================
// Cache State
// ============================================================================
 
typedef struct {
  void *addr;
  char *symbol;
  UT_hash_handle hh;
} symbol_entry_t;
 
static symbol_entry_t *g_symbol_cache = NULL; // uthash uses structure pointer as head
static rwlock_t g_symbol_cache_lock = {0};    // External locking for thread safety
static atomic_bool g_symbol_cache_initialized = false;
 
// Statistics
static atomic_uint_fast64_t g_cache_hits = 0;
static atomic_uint_fast64_t g_cache_misses = 0;
 
// ============================================================================
// Helper Functions
// ============================================================================
 
static bool symbolizer_path_is_executable(const char *path) {
#ifdef _WIN32
  if (!path || path[0] == '\0') {
    return false;
  }
 
  DWORD attrs = GetFileAttributesA(path);
  if (attrs == INVALID_FILE_ATTRIBUTES) {
    return false;
  }
  if (attrs & FILE_ATTRIBUTE_DIRECTORY) {
    return false;
  }
 
  HANDLE handle = CreateFileA(path, GENERIC_READ, FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, OPEN_EXISTING,
                              FILE_ATTRIBUTE_NORMAL, NULL);
  if (handle == INVALID_HANDLE_VALUE) {
    return false;
  }
 
  CloseHandle(handle);
  return true;
#else
  return (path && path[0] != '\0' && access(path, X_OK) == 0);
#endif
}
 
static const char *get_llvm_symbolizer_command(void) {
  if (!atomic_load(&g_llvm_symbolizer_checked)) {
    static_mutex_lock(&g_symbolizer_detection_mutex);
    if (!atomic_load(&g_llvm_symbolizer_checked)) {
      const char *env_path = SAFE_GETENV("LLVM_SYMBOLIZER_PATH");
      bool available = false;
 
      g_llvm_symbolizer_cmd[0] = '\0';
 
      if (env_path && env_path[0] != '\0') {
        if (symbolizer_path_is_executable(env_path)) {
          SAFE_STRNCPY(g_llvm_symbolizer_cmd, env_path, sizeof(g_llvm_symbolizer_cmd));
          available = true;
          log_dev("Using llvm-symbolizer from LLVM_SYMBOLIZER_PATH: %s", env_path);
        } else {
          log_warn("LLVM_SYMBOLIZER_PATH is set but not executable: %s", env_path);
        }
      }
 
      if (!available && platform_is_binary_in_path(LLVM_SYMBOLIZER_BIN)) {
        available = true;
        g_llvm_symbolizer_cmd[0] = '\0'; // Use binary name from PATH
        log_dev("Found %s in PATH", LLVM_SYMBOLIZER_BIN);
      }
 
      atomic_store(&g_llvm_symbolizer_available, available);
      atomic_store(&g_llvm_symbolizer_checked, true);
    }
    static_mutex_unlock(&g_symbolizer_detection_mutex);
  }
 
  if (!atomic_load(&g_llvm_symbolizer_available)) {
    return NULL;
  }
 
  if (g_llvm_symbolizer_cmd[0] != '\0') {
    return g_llvm_symbolizer_cmd;
  }
 
  return LLVM_SYMBOLIZER_BIN;
}
 
static const char *get_addr2line_command(void) {
  if (!atomic_load(&g_addr2line_checked)) {
    static_mutex_lock(&g_symbolizer_detection_mutex);
    if (!atomic_load(&g_addr2line_checked)) {
      const char *env_path = SAFE_GETENV("ADDR2LINE_PATH");
      bool available = false;
 
      g_addr2line_cmd[0] = '\0';
 
      if (env_path && env_path[0] != '\0') {
        if (symbolizer_path_is_executable(env_path)) {
          SAFE_STRNCPY(g_addr2line_cmd, env_path, sizeof(g_addr2line_cmd));
          available = true;
          log_dev("Using addr2line from ADDR2LINE_PATH: %s", env_path);
        } else {
          log_warn("ADDR2LINE_PATH is set but not executable: %s", env_path);
        }
      }
 
      if (!available && platform_is_binary_in_path(ADDR2LINE_BIN)) {
        available = true;
        g_addr2line_cmd[0] = '\0'; // Use binary name from PATH
        log_dev("Found %s in PATH", ADDR2LINE_BIN);
      }
 
      atomic_store(&g_addr2line_available, available);
      atomic_store(&g_addr2line_checked, true);
    }
    static_mutex_unlock(&g_symbolizer_detection_mutex);
  }
 
  if (!atomic_load(&g_addr2line_available)) {
    return NULL;
  }
 
  if (g_addr2line_cmd[0] != '\0') {
    return g_addr2line_cmd;
  }
 
  return ADDR2LINE_BIN;
}
 
static symbolizer_type_t detect_symbolizer(void) {
  // Prefer llvm-symbolizer on all platforms (including macOS)
  // We handle ASLR ourselves using dyld APIs on macOS
  const char *llvm_symbolizer = get_llvm_symbolizer_command();
  if (llvm_symbolizer) {
    log_dev("Using llvm-symbolizer for symbol resolution");
    return SYMBOLIZER_LLVM;
  }
 
  const char *addr2line_cmd = get_addr2line_command();
  if (addr2line_cmd) {
    log_debug("Using addr2line command: %s", addr2line_cmd);
    return SYMBOLIZER_ADDR2LINE;
  }
 
  log_warn("No symbolizer found in PATH (tried %s, %s) - using native backend", LLVM_SYMBOLIZER_BIN, ADDR2LINE_BIN);
  return SYMBOLIZER_NONE;
}
 
// ============================================================================
// Public API Implementation
// ============================================================================
 
asciichat_error_t symbol_cache_init(void) {
  bool expected = false;
  if (!atomic_compare_exchange_strong(&g_symbol_cache_initialized, &expected, true)) {
    return 0; // Already initialized
  }
 
  // Detect which symbolizer is available (once at init)
  expected = false;
  if (atomic_compare_exchange_strong(&g_symbolizer_detected, &expected, true)) {
    g_symbolizer_type = detect_symbolizer();
  }
 
  // Initialize rwlock for thread safety (uthash requires external locking)
  if (rwlock_init(&g_symbol_cache_lock) != 0) {
    atomic_store(&g_symbol_cache_initialized, false);
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize symbol cache rwlock");
  }
 
  // Initialize uthash head to NULL (required)
  g_symbol_cache = NULL;
 
  atomic_store(&g_cache_hits, 0);
  atomic_store(&g_cache_misses, 0);
 
  log_dev("Symbol cache initialized");
  return 0;
}
 
void symbol_cache_destroy(void) {
  if (!atomic_load(&g_symbol_cache_initialized)) {
    return;
  }
 
  // Mark as uninitialized FIRST to prevent new inserts during cleanup
  atomic_store(&g_symbol_cache_initialized, false);
 
  // Acquire write lock to prevent any concurrent operations
  rwlock_wrlock(&g_symbol_cache_lock);
 
  // Count entries before freeing for debugging
  size_t entry_count = HASH_COUNT(g_symbol_cache);
 
  // Free all symbol entries using HASH_ITER
  symbol_entry_t *entry = NULL, *tmp = NULL;
  size_t freed_count = 0;
  HASH_ITER(hh, g_symbol_cache, entry, tmp) {
    if (entry) {
      HASH_DEL(g_symbol_cache, entry);
      if (entry->symbol) {
        free(entry->symbol);
      }
      free(entry);
      freed_count++;
    }
  }
 
  // Release lock and destroy rwlock
  rwlock_wrunlock(&g_symbol_cache_lock);
  rwlock_destroy(&g_symbol_cache_lock);
 
  g_symbol_cache = NULL;
 
  log_dev("Symbol cache cleaned up: %zu entries counted, %zu entries freed (hits=%llu, misses=%llu)", entry_count,
          freed_count, (unsigned long long)atomic_load(&g_cache_hits),
          (unsigned long long)atomic_load(&g_cache_misses));
}
 
const char *symbol_cache_lookup(void *addr) {
  if (!atomic_load(&g_symbol_cache_initialized) || !addr) {
    return NULL;
  }
 
  rwlock_rdlock(&g_symbol_cache_lock);
 
  symbol_entry_t *entry = NULL;
  HASH_FIND_PTR(g_symbol_cache, &addr, entry);
 
  const char *result = NULL;
  if (entry) {
    // Copy string while holding lock to prevent use-after-free
    result = platform_strdup(entry->symbol);
    atomic_fetch_add(&g_cache_hits, 1);
  } else {
    atomic_fetch_add(&g_cache_misses, 1);
  }
 
  rwlock_rdunlock(&g_symbol_cache_lock);
  return result;
}
 
bool symbol_cache_insert(void *addr, const char *symbol) {
  if (!atomic_load(&g_symbol_cache_initialized) || !addr || !symbol) {
    return false;
  }
 
  // Acquire write lock to make the entire operation atomic
  rwlock_wrlock(&g_symbol_cache_lock);
 
  // Double-check cache is still initialized after acquiring lock
  // (cleanup might have marked it uninitialized between our check and lock acquisition)
  if (!atomic_load(&g_symbol_cache_initialized)) {
    rwlock_wrunlock(&g_symbol_cache_lock);
    return false;
  }
 
  // Check if entry already exists
  symbol_entry_t *existing = NULL;
  HASH_FIND_PTR(g_symbol_cache, &addr, existing);
 
  if (existing) {
    // Entry exists - update symbol if different
    if (existing->symbol && strcmp(existing->symbol, symbol) != 0) {
      // Free old symbol and allocate new one
      free(existing->symbol);
      existing->symbol = platform_strdup(symbol);
      if (!existing->symbol) {
        rwlock_wrunlock(&g_symbol_cache_lock);
        return false;
      }
    }
    rwlock_wrunlock(&g_symbol_cache_lock);
    return true;
  }
 
  // Create new entry
  symbol_entry_t *entry = (symbol_entry_t *)malloc(sizeof(symbol_entry_t));
  if (!entry) {
    rwlock_wrunlock(&g_symbol_cache_lock);
    return false;
  }
 
  entry->addr = addr;
  entry->symbol = platform_strdup(symbol);
  if (!entry->symbol) {
    free(entry);
    rwlock_wrunlock(&g_symbol_cache_lock);
    return false;
  }
 
  // Add to hash table
  HASH_ADD_PTR(g_symbol_cache, addr, entry);
 
  // Release lock
  rwlock_wrunlock(&g_symbol_cache_lock);
 
  return true;
}
 
void symbol_cache_get_stats(uint64_t *hits_out, uint64_t *misses_out, size_t *entries_out) {
  if (hits_out) {
    *hits_out = atomic_load(&g_cache_hits);
  }
  if (misses_out) {
    *misses_out = atomic_load(&g_cache_misses);
  }
  if (entries_out) {
    rwlock_rdlock(&g_symbol_cache_lock);
    *entries_out = HASH_COUNT(g_symbol_cache);
    rwlock_rdunlock(&g_symbol_cache_lock);
  }
}
 
void symbol_cache_print_stats(void) {
  uint64_t hits = atomic_load(&g_cache_hits);
  uint64_t misses = atomic_load(&g_cache_misses);
 
  rwlock_rdlock(&g_symbol_cache_lock);
  size_t entries = HASH_COUNT(g_symbol_cache);
  rwlock_rdunlock(&g_symbol_cache_lock);
 
  uint64_t total = hits + misses;
  double hit_rate = total > 0 ? (100.0 * (double)hits / (double)total) : 0.0;
 
  log_debug("Symbol Cache Stats: %zu entries, %llu hits, %llu misses (%.1f%% hit rate)", entries,
            (unsigned long long)hits, (unsigned long long)misses, hit_rate);
}
 
// ============================================================================
// Batch Resolution with llvm-symbolizer and addr2line
// ============================================================================
 
static char *parse_llvm_symbolizer_result(FILE *fp, void *addr) {
  char func_name[512] = "??";
  char file_location[512] = "??:0";
  char blank_line[8];
 
  // Read function name line
  if (fgets(func_name, sizeof(func_name), fp) == NULL) {
    return NULL;
  }
  func_name[strcspn(func_name, "\n")] = '\0';
 
  // Read file location line
  if (fgets(file_location, sizeof(file_location), fp) == NULL) {
    return NULL;
  }
  file_location[strcspn(file_location, "\n")] = '\0';
 
  // Read blank separator line (and discard it)
  if (fgets(blank_line, sizeof(blank_line), fp) == NULL) {
    // End of output - not an error
  }
 
  // Remove column number (last :N) from file_location
  char *last_colon = strrchr(file_location, ':');
  if (last_colon) {
    *last_colon = '\0';
  }
 
  // Extract relative path and COPY IT IMMEDIATELY
  // IMPORTANT: extract_project_relative_path uses a static buffer internally.
  // SAFE_MALLOC's debug memory tracking also calls extract_project_relative_path,
  // which would overwrite the static buffer. So we must copy before allocating.
  const char *rel_path_tmp = extract_project_relative_path(file_location);
  char rel_path[512];
  SAFE_STRNCPY(rel_path, rel_path_tmp, sizeof(rel_path));
 
  // Allocate result buffer (AFTER copying rel_path to local storage)
  char *result = SAFE_MALLOC(1024, char *);
  if (!result) {
    return NULL;
  }
 
  // Format symbol
  bool has_func = (strcmp(func_name, "??") != 0 && strlen(func_name) > 0);
  bool has_file =
      (strcmp(file_location, "??:0") != 0 && strcmp(file_location, "??:?") != 0 && strcmp(file_location, "??") != 0);
 
  // Remove () from function name if present (llvm-symbolizer includes them)
  char clean_func[512];
  SAFE_STRNCPY(clean_func, func_name, sizeof(clean_func));
  char *paren = strstr(clean_func, "()");
  if (paren) {
    *paren = '\0';
  }
 
  if (!has_func && !has_file) {
    SAFE_SNPRINTF(result, 1024, "%p", addr);
  } else if (has_func && has_file) {
    SAFE_SNPRINTF(result, 1024, "%s() (%s)", clean_func, rel_path);
  } else if (has_func) {
    SAFE_SNPRINTF(result, 1024, "%s()", clean_func);
  } else {
    SAFE_SNPRINTF(result, 1024, "%s (unknown function)", rel_path);
  }
 
  return result;
}
 
static char **run_llvm_symbolizer_batch(void *const *buffer, int size) {
  if (size <= 0 || !buffer) {
    return NULL;
  }
 
  const char *symbolizer_cmd = get_llvm_symbolizer_command();
  if (!symbolizer_cmd) {
    log_debug("llvm-symbolizer not available - skipping symbolization");
    return NULL;
  }
 
  // Allocate result array
  char **result = SAFE_CALLOC((size_t)(size + 1), sizeof(char *), char **);
  if (!result) {
    return NULL;
  }
 
  // ============================================================================
  // Unified platform-agnostic implementation using get_binary_file_address_offsets()
  // ============================================================================
 
  // Group addresses by binary using platform-independent interface
  // Works identically on Linux, macOS, and Windows
  typedef struct {
    char binary_path[PLATFORM_MAX_PATH_LENGTH];
    uintptr_t file_offsets[64]; // Max addresses per binary
    int original_indices[64];
    int count;
  } binary_group_t;
 
  binary_group_t groups[8]; // Support up to 8 different binaries
  int num_groups = 0;
 
  // First pass: Call get_binary_file_address_offsets() for each address
  // (same function works on all platforms - zero #ifdefs needed!)
  for (int i = 0; i < size; i++) {
    platform_binary_match_t match;
    if (get_binary_file_address_offsets(buffer[i], &match, 1) == 0) {
      // Could not find binary - use raw address as fallback
      result[i] = SAFE_MALLOC(32, char *);
      if (result[i]) {
        SAFE_SNPRINTF(result[i], 32, "%p", buffer[i]);
      }
      continue;
    }
 
    // Find or create group for this binary
    int group_idx = -1;
    for (int g = 0; g < num_groups; g++) {
      if (strcmp(groups[g].binary_path, match.path) == 0) {
        group_idx = g;
        break;
      }
    }
 
    if (group_idx < 0 && num_groups < 8) {
      group_idx = num_groups++;
      SAFE_STRNCPY(groups[group_idx].binary_path, match.path, sizeof(groups[group_idx].binary_path));
      groups[group_idx].count = 0;
    }
 
    if (group_idx >= 0 && groups[group_idx].count < 64) {
      int idx = groups[group_idx].count++;
      groups[group_idx].file_offsets[idx] = match.file_offset;
      groups[group_idx].original_indices[idx] = i;
    }
  }
 
  // Second pass: batch symbolize each group
  for (int g = 0; g < num_groups; g++) {
    if (groups[g].count == 0) {
      continue;
    }
 
    // Escape binary path for shell
    char escaped_binary_path[PLATFORM_MAX_PATH_LENGTH * 2];
    if (!escape_path_for_shell(groups[g].binary_path, escaped_binary_path, sizeof(escaped_binary_path))) {
      continue;
    }
 
    // Build command with all addresses for this binary
    char cmd[8192];
    int offset = safe_snprintf(cmd, sizeof(cmd), "%s --demangle --output-style=LLVM --relativenames -e %s ",
                               symbolizer_cmd, escaped_binary_path);
 
    for (int j = 0; j < groups[g].count && offset < (int)sizeof(cmd) - 32; j++) {
      int n =
          safe_snprintf(cmd + offset, sizeof(cmd) - (size_t)offset, "0x%lx ", (unsigned long)groups[g].file_offsets[j]);
      if (n > 0) {
        offset += n;
      }
    }
 
    // Suppress stderr
    strncat(cmd, "2>/dev/null", sizeof(cmd) - strlen(cmd) - 1);
 
    FILE *fp = popen(cmd, "r");
    if (!fp) {
      continue;
    }
 
    // Extract binary name (basename) for display
    const char *binary_name = strrchr(groups[g].binary_path, '/');
    if (!binary_name) {
      binary_name = strrchr(groups[g].binary_path, '\\');
    }
    binary_name = binary_name ? binary_name + 1 : groups[g].binary_path;
 
    // Parse results in order
    for (int j = 0; j < groups[g].count; j++) {
      int orig_idx = groups[g].original_indices[j];
      char *parsed = parse_llvm_symbolizer_result(fp, buffer[orig_idx]);
 
      if (parsed) {
        // Prepend binary name in brackets
        char *with_binary = SAFE_MALLOC(1024, char *);
        if (with_binary) {
          SAFE_SNPRINTF(with_binary, 1024, "[%s] %s", binary_name, parsed);
          SAFE_FREE(parsed);
          result[orig_idx] = with_binary;
        } else {
          result[orig_idx] = parsed;
        }
      } else {
        // Fallback: show raw address with binary name
        result[orig_idx] = SAFE_MALLOC(256, char *);
        if (result[orig_idx]) {
          SAFE_SNPRINTF(result[orig_idx], 256, "[%s] %p", binary_name, buffer[orig_idx]);
        }
      }
    }
 
    pclose(fp);
  }
 
  return result;
}
 
static char **run_addr2line_batch(void *const *buffer, int size) {
  if (size <= 0 || !buffer) {
    log_error("Invalid parameters: buffer=%p, size=%d", (void *)buffer, size);
    return NULL;
  }
 
  const char *addr2line_cmd = get_addr2line_command();
  if (!addr2line_cmd) {
    log_debug("addr2line not available - skipping symbolization");
    return NULL;
  }
 
  // Get executable path
  char exe_path[PLATFORM_MAX_PATH_LENGTH];
  if (!platform_get_executable_path(exe_path, sizeof(exe_path))) {
    return NULL;
  }
 
  // SECURITY: Validate executable path to prevent command injection
  // Paths from system APIs should be safe, but validate to be thorough
  if (!validate_shell_safe(exe_path, ".-/\\:")) {
    log_error("Invalid executable path - contains unsafe characters: %s", exe_path);
    return NULL;
  }
 
  // Escape exe_path for shell (auto-detects platform and quoting needs)
  char escaped_exe_path_buf[PLATFORM_MAX_PATH_LENGTH * 2];
  if (!escape_path_for_shell(exe_path, escaped_exe_path_buf, sizeof(escaped_exe_path_buf))) {
    log_error("Failed to escape executable path for shell command");
    return NULL;
  }
  const char *escaped_exe_path = escaped_exe_path_buf;
 
  if (!validate_shell_safe(addr2line_cmd, ".-/\\:_")) {
    log_warn("addr2line path contains unsafe characters: %s", addr2line_cmd);
    return NULL;
  }
 
  // Escape addr2line command for shell (auto-detects platform and quoting needs)
  char escaped_addr2line_buf[PLATFORM_MAX_PATH_LENGTH * 2];
  if (!escape_path_for_shell(addr2line_cmd, escaped_addr2line_buf, sizeof(escaped_addr2line_buf))) {
    log_error("Failed to escape addr2line path for shell command");
    return NULL;
  }
  const char *escaped_addr2line_cmd = escaped_addr2line_buf;
 
  // Build addr2line command
  char cmd[4096];
  int offset = safe_snprintf(cmd, sizeof(cmd), "%s -e %s -f -C -i ", escaped_addr2line_cmd, escaped_exe_path);
  if (offset <= 0 || offset >= (int)sizeof(cmd)) {
    log_error("Failed to build addr2line command");
    return NULL;
  }
 
  // Use explicit hex format with 0x prefix since Windows %p doesn't include it
  for (int i = 0; i < size; i++) {
    int n = safe_snprintf(cmd + offset, sizeof(cmd) - (size_t)offset, "0x%llx ", (unsigned long long)buffer[i]);
    if (n <= 0 || offset + n >= (int)sizeof(cmd)) {
      log_error("Failed to build addr2line command");
      break;
    }
    offset += n;
  }
 
  // Execute addr2line
  FILE *fp = popen(cmd, "r");
  if (!fp) {
    log_error("Failed to execute addr2line command");
    return NULL;
  }
 
  // Allocate result array
  char **result = SAFE_CALLOC((size_t)(size + 1), sizeof(char *), char **);
  if (!result) {
    pclose(fp);
    return NULL;
  }
 
  // Parse output
  for (int i = 0; i < size; i++) {
    char func_name[256];
    char file_line[512];
 
    if (fgets(func_name, sizeof(func_name), fp) == NULL) {
      break;
    }
    if (fgets(file_line, sizeof(file_line), fp) == NULL) {
      break;
    }
 
    // Remove newlines
    func_name[strcspn(func_name, "\n")] = '\0';
    file_line[strcspn(file_line, "\n")] = '\0';
 
    // Extract relative path and COPY IT IMMEDIATELY
    // IMPORTANT: extract_project_relative_path uses a static buffer internally.
    // SAFE_MALLOC's debug memory tracking also calls extract_project_relative_path,
    // which would overwrite the static buffer. So we must copy before allocating.
    const char *rel_path_tmp = extract_project_relative_path(file_line);
    char rel_path[512];
    SAFE_STRNCPY(rel_path, rel_path_tmp, sizeof(rel_path));
 
    // Allocate result buffer (AFTER copying rel_path to local storage)
    result[i] = SAFE_MALLOC(1024, char *);
 
    // Format symbol
    bool has_func = (strcmp(func_name, "??") != 0);
    bool has_file = (strcmp(file_line, "??:0") != 0 && strcmp(file_line, "??:?") != 0);
 
    if (!has_func && !has_file) {
      // Complete unknown - show raw address
      SAFE_SNPRINTF(result[i], 1024, "%p", buffer[i]);
    } else if (has_func && has_file) {
      // Best case - both function and file:line known
      if (strstr(rel_path, ":") != NULL) {
        SAFE_SNPRINTF(result[i], 1024, "%s in %s()", rel_path, func_name);
      } else {
        SAFE_SNPRINTF(result[i], 1024, "%s() at %s", func_name, rel_path);
      }
    } else if (has_func) {
      // Function known but file unknown (common for library functions)
      SAFE_SNPRINTF(result[i], 1024, "%s() at %p", func_name, buffer[i]);
    } else {
      // File known but function unknown (rare)
      SAFE_SNPRINTF(result[i], 1024, "%s (unknown function)", rel_path);
    }
  }
 
  pclose(fp);
  return result;
}
 
char **symbol_cache_resolve_batch(void *const *buffer, int size) {
  if (size <= 0 || !buffer) {
    log_error("Invalid parameters: buffer=%p, size=%d", (void *)buffer, size);
    return NULL;
  }
 
  // DO NOT auto-initialize here - causes circular dependency during lock_debug_init()
  // The cache must be initialized explicitly by platform_init() before use
  if (!atomic_load(&g_symbol_cache_initialized)) {
    // Cache not initialized - fall back to uncached resolution
    // This happens during early initialization before platform_init() completes
    char **result = run_llvm_symbolizer_batch(buffer, size);
    if (!result) {
      result = run_addr2line_batch(buffer, size);
    }
    return result;
  }
 
  // Allocate result array (size + 1 for NULL terminator)
  // CALLOC zeros the memory, so result[size] is already NULL
  char **result = SAFE_CALLOC((size_t)(size + 1), sizeof(char *), char **);
  if (!result) {
    return NULL;
  }
 
  // Ensure NULL terminator is explicitly set (CALLOC already did this, but be explicit)
  result[size] = NULL;
 
  // First pass: check cache for all addresses
  int uncached_count = 0;
  void *uncached_addrs[size];
  int uncached_indices[size];
 
  for (int i = 0; i < size; i++) {
    const char *cached = symbol_cache_lookup(buffer[i]);
    if (cached) {
      // Cache hit - symbol_cache_lookup already duplicated the string
      result[i] = (char *)cached;
    } else {
      // Cache miss - track for batch resolution
      uncached_addrs[uncached_count] = buffer[i];
      uncached_indices[uncached_count] = i;
      uncached_count++;
    }
  }
 
  // Second pass: resolve uncached addresses with selected symbolizer
  if (uncached_count > 0) {
    char **resolved = NULL;
 
    // Use the detected symbolizer type
    switch (g_symbolizer_type) {
    case SYMBOLIZER_LLVM:
      resolved = run_llvm_symbolizer_batch(uncached_addrs, uncached_count);
      break;
    case SYMBOLIZER_ADDR2LINE:
      resolved = run_addr2line_batch(uncached_addrs, uncached_count);
      break;
    case SYMBOLIZER_NONE:
    default:
      // No symbolizer available - will fall through to raw address handling
      resolved = NULL;
      break;
    }
 
    if (resolved) {
      for (int i = 0; i < uncached_count; i++) {
        int orig_idx = uncached_indices[i];
        if (resolved[i]) {
          result[orig_idx] = platform_strdup(resolved[i]);
          // If strdup failed, use sentinel string instead of NULL
          if (!result[orig_idx]) {
            log_error("Failed to duplicate string for result[%d]", orig_idx);
            result[orig_idx] = platform_strdup(NULL_SENTINEL);
          }
          // Only insert into cache if strdup succeeded (and it's not the sentinel)
          if (result[orig_idx] && strcmp(result[orig_idx], NULL_SENTINEL) != 0) {
            if (!symbol_cache_insert(uncached_addrs[i], resolved[i])) {
              log_error("Failed to insert symbol into cache for result[%d]", orig_idx);
            }
          }
          SAFE_FREE(resolved[i]);
        } else {
          // resolved[i] is NULL - use sentinel string
          if (!result[orig_idx]) {
            result[orig_idx] = platform_strdup(NULL_SENTINEL);
          }
        }
        if (!result[orig_idx]) {
          log_error("Failed to allocate memory for result[%d]", orig_idx);
        }
      }
 
      SAFE_FREE(resolved);
 
    } else {
      // addr2line failed - fill uncached entries with raw addresses or sentinel
      for (int i = 0; i < uncached_count; i++) {
        int orig_idx = uncached_indices[i];
        if (!result[orig_idx]) {
          result[orig_idx] = SAFE_MALLOC(32, char *);
          if (result[orig_idx]) {
            SAFE_SNPRINTF(result[orig_idx], 32, "%p", uncached_addrs[i]);
          } else {
            result[orig_idx] = platform_strdup(NULL_SENTINEL);
          }
        }
        if (!result[orig_idx]) {
          log_error("Failed to allocate memory for result[%d]", orig_idx);
        }
      }
    }
  }
 
  return result;
}
 
void symbol_cache_free_symbols(char **symbols) {
  if (!symbols) {
    return;
  }
 
  // The array is NULL-terminated (allocated with size+1, with result[size] = NULL)
  // The terminator is a SINGLE NULL at index 'size'
  // Failed allocations use the NULL_SENTINEL string "[NULL]" instead of NULL,
  // so there are no NULL entries in the middle - only at the terminator
  // This makes iteration safe: we can iterate until we find the first NULL (the terminator)
 
  // Iterate through entries, freeing all non-NULL entries until we hit the NULL terminator
  for (int i = 0; i < 64; i++) { // Reasonable limit to prevent infinite loop
    if (symbols[i] == NULL) {
      // Found NULL - this is the terminator, stop here
      break;
    }
 
    // Found a non-NULL entry - check if it's the sentinel string
    // Both regular strings and sentinel strings are allocated (with strdup),
    // so we free them all
    SAFE_FREE(symbols[i]);
    symbols[i] = NULL; // Clear pointer after freeing
  }
 
  // Free the array itself
  SAFE_FREE(symbols);
}