ProvSQL C/C++ API
Adding support for provenance and uncertainty management to PostgreSQL databases
Loading...
Searching...
No Matches
external_tool.cpp File Reference

Implementation of the external-tool helpers. More...

#include "postgres.h"
#include "provsql_utils.h"
#include "miscadmin.h"
#include <signal.h>
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <unistd.h>
#include <sys/wait.h>
#include "external_tool.h"
#include "Circuit.h"
#include "ToolRegistry.h"
#include "process_memory.h"
#include "provsql_interrupt.h"
#include "provsql_config.h"
#include <chrono>
#include <string>
#include <unordered_map>
Include dependency graph for external_tool.cpp:

Go to the source code of this file.

Functions

static int run_in_own_pgroup (const std::string &cmdline)
int run_external_tool (const std::string &cmdline)
 Run a shell command line in its own process group, optionally extending PATH, interruptible by query cancel / statement_timeout.
std::string find_external_tool (const std::string &name)
 Locate an external tool by name.
std::string format_external_tool_status (int rv, const std::string &tool)
 Decode a system() return value into a human-readable message.
bool toolAvailable (const provsql::ToolRecord &rec)
 True iff a registry tool can currently be used.

Variables

static const char * DEFAULT_PATH
static bool tool_memory_exceeded = false
 Set by run_in_own_pgroup when it killed a tool that took the statement past provsql.max_memory.
static double tool_time_limit_ms = 0.
 Time limit, in ms, of the innermost ExternalToolTimeLimit scope (0: none).
static bool tool_time_exceeded = false
 Set by run_in_own_pgroup when it killed a tool that ran past tool_time_limit_ms.

Detailed Description

Implementation of the external-tool helpers.

Reads the provsql.tool_search_path GUC (exposed as provsql_tool_search_path) and uses it both to extend $PATH around system() and to drive the pre-flight find_external_tool() lookup.

Definition in file external_tool.cpp.

Function Documentation

◆ find_external_tool()

std::string find_external_tool ( const std::string & name)

Locate an external tool by name.

Searches provsql_tool_search_path (colon-separated), then $PATH, for an executable file matching name (via access(X_OK)). Returns the full path on success, or the empty string if nothing matches.

Names containing a slash are treated as paths and tested directly without any directory walk.

Parameters
nameBare executable name (e.g. "d4") or a path.
Returns
Resolved path, or "" if name is not found.

Definition at line 224 of file external_tool.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ format_external_tool_status()

std::string format_external_tool_status ( int rv,
const std::string & tool )

Decode a system() return value into a human-readable message.

Parameters
rvReturn value from system() (or run_external_tool()).
toolTool name, used as the message subject.
Returns
Empty string when rv indicates success; otherwise a message that distinguishes "not found at runtime" (shell exit 127), "not executable" (126), "killed by signal N", "exited with status N", or system() itself failing.

Definition at line 271 of file external_tool.cpp.

Here is the caller graph for this function:

◆ run_external_tool()

int run_external_tool ( const std::string & cmdline)

Run a shell command line in its own process group, optionally extending PATH, interruptible by query cancel / statement_timeout.

If provsql_tool_search_path is non-empty, it is prepended (with :) to $PATH for the duration and restored afterwards. The command runs via /bin/sh -c as a process-group leader; while it runs the parent polls for a pending cancel/terminate and, if one fires, SIGKILLs the whole group (reaching tools that fork workers) and lets CHECK_FOR_INTERRUPTS raise it.

Parameters
cmdlineShell command line, passed verbatim to /bin/sh -c.
Returns
A wait(2) status (decode with WIFEXITED etc., as a system() return), or -1 if fork failed.

Definition at line 167 of file external_tool.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ run_in_own_pgroup()

int run_in_own_pgroup ( const std::string & cmdline)
static

Definition at line 84 of file external_tool.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ toolAvailable()

bool toolAvailable ( const provsql::ToolRecord & rec)

True iff a registry tool can currently be used.

A kcmcp record needs a configured endpoint (no live connect probe, mirroring how a CLI tool only needs its binary on PATH). A cli record needs its binary (when set) and every dependency to resolve on the backend's PATH via find_external_tool. This is the single availability predicate consulted both by the compile/wmc tool selection and by the provsql.tools view.

Definition at line 292 of file external_tool.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

Variable Documentation

◆ DEFAULT_PATH

const char* DEFAULT_PATH
static
Initial value:
=
"/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

Definition at line 40 of file external_tool.cpp.

◆ tool_memory_exceeded

bool tool_memory_exceeded = false
static

Set by run_in_own_pgroup when it killed a tool that took the statement past provsql.max_memory.

Definition at line 63 of file external_tool.cpp.

◆ tool_time_exceeded

bool tool_time_exceeded = false
static

Set by run_in_own_pgroup when it killed a tool that ran past tool_time_limit_ms.

Definition at line 71 of file external_tool.cpp.

◆ tool_time_limit_ms

double tool_time_limit_ms = 0.
static

Time limit, in ms, of the innermost ExternalToolTimeLimit scope (0: none).

Definition at line 67 of file external_tool.cpp.