Query

Files
file	query.h
	Runtime variable query tool API for debug builds.

Functions
int	query_init (int preferred_port)
	Initialize the query tool by spawning the controller process.
void	query_shutdown (void)
	Shutdown the query tool and terminate the controller process.
bool	query_is_active (void)
	Check if the query tool controller is currently active.
int	query_get_port (void)
	Get the port number of the active query server.

Convenience Macros
These macros provide a convenient interface that compiles out completely in release builds. Use these instead of calling the functions directly.
#define	QUERY_INIT(port)   query_init(port)
	Initialize query tool (debug builds only)
#define	QUERY_SHUTDOWN()   query_shutdown()
	Shutdown query tool (debug builds only)
#define	QUERY_ACTIVE()   query_is_active()
	Check if query tool is active (debug builds only)
#define	QUERY_PORT()   query_get_port()
	Get query server port (debug builds only)

Detailed Description

This header provides the public C API for the query tool, which enables runtime variable inspection via HTTP queries. The tool uses an external LLDB process to attach to the running application and read variable values.

Architecture

• Target process (ascii-chat) runs normally with debug symbols
• Controller process (ascii-query-server) attaches via LLDB
• HTTP server in controller accepts curl requests
• When target is stopped at breakpoint, controller is still running

Example Usage

// In your application startup (debug builds only)
int port = QUERY_INIT(9999);
if (port > 0) {
    printf("Query server at http://localhost:%d\n", port);
}
 
// ... application runs ...
 
// Query variables via curl:
// curl 'localhost:9999/query?file=src/server.c&line=100&name=client_count'
// curl 'localhost:9999/query?file=src/server.c&line=100&name=client.socket.fd&break'
// curl -X POST 'localhost:9999/continue'
 
// On shutdown
QUERY_SHUTDOWN();

Note: All functions and macros compile out completely in release builds (when NDEBUG is defined). The query tool has zero runtime overhead in production builds.

See also

docs/tooling/query.md for full documentation

docs/tooling/QUERY_TOOL_PLAN.md for implementation details

Macro Definition Documentation

QUERY_ACTIVE

#define QUERY_ACTIVE

(

)

query_is_active()

#include <query.h>

Check if query tool is active (debug builds only)

Returns

true if active, false otherwise (always false in release builds)

Definition at line 134 of file query.h.

QUERY_INIT

#define QUERY_INIT

(

port

)

query_init(port)

#include <query.h>

Initialize query tool (debug builds only)

Parameters

port	Preferred HTTP server port

Returns

Port number on success, -1 on failure (or in release builds)

Definition at line 123 of file query.h.

QUERY_PORT

#define QUERY_PORT

(

)

query_get_port()

#include <query.h>

Get query server port (debug builds only)

Returns

Port number if active, -1 otherwise (always -1 in release builds)

Definition at line 140 of file query.h.

QUERY_SHUTDOWN

#define QUERY_SHUTDOWN

(

)

query_shutdown()

#include <query.h>

Shutdown query tool (debug builds only)

Definition at line 128 of file query.h.

Function Documentation

query_get_port()

int query_get_port

(

void

)

#include <query.h>

Get the port number of the active query server.

Returns

The port number if active, -1 if not active

Note

Only available in debug builds (NDEBUG not defined)

Definition at line 407 of file query.c.

                         {
  return g_query_port;
}

query_init()

int query_init

(

int

preferred_port

)

#include <query.h>

Initialize the query tool by spawning the controller process.

This function spawns the ascii-query-server process, which attaches to the current process via LLDB and starts an HTTP server on the specified port.

The controller process is completely separate from the target process:

• Target can be stopped at breakpoints while controller serves HTTP
• Controller sends LLDB commands to read variables and control execution
• No instrumentation or code modification in the target is required

Parameters

preferred_port

The port number for the HTTP server (e.g., 9999)

Returns

The actual port number on success, -1 on failure

Note

Only available in debug builds (NDEBUG not defined)

The controller may take a moment to attach; this function waits for the HTTP server to become ready before returning

Platform notes:

• macOS: May require code signing with get-task-allow entitlement
• Linux: May require ptrace permissions (check /proc/sys/kernel/yama/ptrace_scope)
• Windows: Uses CreateProcess instead of fork/exec

Definition at line 216 of file query.c.

                                   {
  // Already initialized?
  if (g_query_active) {
    return g_query_port;
  }
 
  // Find the query server executable
  char server_path[1024];
  if (!find_query_server_path(server_path, sizeof(server_path))) {
    fprintf(stderr, "[query] Could not find ascii-query-server executable\n");
    fprintf(stderr, "[query] Set ASCIICHAT_QUERY_SERVER environment variable or ensure "
                    "it's in .deps-cache/query-tool/\n");
    return -1;
  }
 
#ifdef _WIN32
  // Windows implementation using CreateProcess
  WSADATA wsa_data;
  if (WSAStartup(MAKEWORD(2, 2), &wsa_data) != 0) {
    fprintf(stderr, "[query] WSAStartup failed\n");
    return -1;
  }
 
  char cmdline[2048];
  snprintf(cmdline, sizeof(cmdline), "\"%s\" --attach %lu --port %d", server_path, (unsigned long)GetCurrentProcessId(),
           preferred_port);
 
  STARTUPINFOA si;
  PROCESS_INFORMATION pi;
  memset(&si, 0, sizeof(si));
  si.cb = sizeof(si);
  memset(&pi, 0, sizeof(pi));
 
  // Create the controller process
  if (!CreateProcessA(NULL,               // Use command line
                      cmdline,            // Command line
                      NULL,               // Process security attributes
                      NULL,               // Thread security attributes
                      FALSE,              // Don't inherit handles
                      CREATE_NEW_CONSOLE, // Creation flags
                      NULL,               // Use parent's environment
                      NULL,               // Use parent's directory
                      &si, &pi)) {
    fprintf(stderr, "[query] Failed to start query server: error %lu\n", GetLastError());
    return -1;
  }
 
  g_controller_handle = pi.hProcess;
  g_controller_pid = pi.dwProcessId;
  CloseHandle(pi.hThread); // Don't need the thread handle
 
  fprintf(stderr, "[query] Started query server (PID %lu) on port %d\n", (unsigned long)g_controller_pid,
          preferred_port);
 
#else
  // Unix implementation using fork/exec
  pid_t self_pid = getpid();
 
  char port_str[16];
  char pid_str[16];
  snprintf(port_str, sizeof(port_str), "%d", preferred_port);
  snprintf(pid_str, sizeof(pid_str), "%d", self_pid);
 
  pid_t child = fork();
  if (child < 0) {
    fprintf(stderr, "[query] fork() failed: %s\n", strerror(errno));
    return -1;
  }
 
  if (child == 0) {
    // Child process: exec the controller
    // Redirect stdout/stderr to /dev/null or a log file to avoid clutter
    // (The controller has its own logging)
 
    execl(server_path, "ascii-query-server", "--attach", pid_str, "--port", port_str, (char *)NULL);
 
    // If exec fails
    fprintf(stderr, "[query] exec(%s) failed: %s\n", server_path, strerror(errno));
    _exit(1);
  }
 
  // Parent process
  g_controller_pid = child;
  fprintf(stderr, "[query] Started query server (PID %d) on port %d\n", child, preferred_port);
#endif
 
  // Wait for the HTTP server to become ready
  fprintf(stderr, "[query] Waiting for HTTP server to be ready...\n");
  if (!wait_for_http_ready(preferred_port, HEALTH_CHECK_TIMEOUT_MS)) {
    fprintf(stderr, "[query] Timeout waiting for query server to start\n");
    query_shutdown();
    return -1;
  }
 
  g_query_active = true;
  g_query_port = preferred_port;
 
  fprintf(stderr, "[query] Query server ready at http://localhost:%d\n", preferred_port);
  return preferred_port;
}

References errno, HEALTH_CHECK_TIMEOUT_MS, and query_shutdown().

query_is_active()

bool query_is_active

(

void

)

#include <query.h>

Check if the query tool controller is currently active.

Returns

true if the controller process is running and responsive

false if the controller is not running or not responding

Note

Only available in debug builds (NDEBUG not defined)

Definition at line 375 of file query.c.

                           {
  if (!g_query_active) {
    return false;
  }
 
// Verify the controller is still running
#ifdef _WIN32
  if (g_controller_handle != NULL) {
    DWORD exit_code;
    if (GetExitCodeProcess(g_controller_handle, &exit_code)) {
      if (exit_code != STILL_ACTIVE) {
        g_query_active = false;
        g_controller_handle = NULL;
        g_controller_pid = 0;
        return false;
      }
    }
  }
#else
  if (g_controller_pid > 0) {
    // Check if process is still alive
    if (kill(g_controller_pid, 0) != 0) {
      g_query_active = false;
      g_controller_pid = -1;
      return false;
    }
  }
#endif
 
  return g_query_active;
}

query_shutdown()

void query_shutdown

(

void

)

#include <query.h>

Shutdown the query tool and terminate the controller process.

This function cleanly terminates the ascii-query-server process. The target process continues running normally after shutdown.

Note

Safe to call even if query_init() was not called or failed

Only available in debug builds (NDEBUG not defined)

Definition at line 317 of file query.c.

                          {
  if (!g_query_active && g_controller_pid <= 0) {
    return;
  }
 
  fprintf(stderr, "[query] Shutting down query server...\n");
 
#ifdef _WIN32
  if (g_controller_handle != NULL) {
    // Send termination signal
    TerminateProcess(g_controller_handle, 0);
 
    // Wait for process to exit (with timeout)
    WaitForSingleObject(g_controller_handle, 3000);
 
    CloseHandle(g_controller_handle);
    g_controller_handle = NULL;
    g_controller_pid = 0;
  }
 
  // Clean up Winsock (matches WSAStartup in query_init)
  WSACleanup();
#else
  if (g_controller_pid > 0) {
    // Send SIGTERM for graceful shutdown
    kill(g_controller_pid, SIGTERM);
 
    // Wait for process to exit (with timeout)
    int status;
    int wait_count = 0;
    while (wait_count < 30) { // 3 second timeout
      pid_t result = waitpid(g_controller_pid, &status, WNOHANG);
      if (result == g_controller_pid) {
        break;
      }
      if (result < 0) {
        break;
      }
      usleep(100000); // 100ms
      wait_count++;
    }
 
    // If still running, force kill
    if (wait_count >= 30) {
      kill(g_controller_pid, SIGKILL);
      waitpid(g_controller_pid, &status, 0);
    }
 
    g_controller_pid = -1;
  }
#endif
 
  g_query_active = false;
  g_query_port = -1;
 
  fprintf(stderr, "[query] Query server stopped\n");
}

Referenced by query_init().