Skip to main content

Module execute

Module execute 

Source
Expand description

Running one command for kizz execute (“Observing any command with kizz execute”), through the tracer interface and without the cache.

execute takes the command’s arguments, the caller’s whole environment and working directory (ExecuteRequest), and the handle through which the caller forwards signals. It looks the program up with the lookup of run() (search_program), through the caller’s PATH, and names the outcome of each checked location through the tracer’s error-name query. When it finds a program, it runs it through the tracer with the caller’s environment and working directory unchanged, keeping the terminal and asking for the process tree. It returns how the command ended (CommandOutcome), the exit status of kizz execute (exit_status), and the observation Report of the one command, in which the lookup’s probes are observations of the command’s first program. It never opens the store.

The outcomes and their statuses:

  • the program exited with a code: exited, with that code;
  • a signal killed it: signaled, with 128 plus the signal’s number;
  • the lookup found no location, or a name without / met an environment without PATH, or the tracer reported the program missing: not_found, with STATUS_NOT_FOUND;
  • the lookup found only a location that cannot be run, or the tracer reported the program not executable: not_executable, with STATUS_NOT_EXECUTABLE;
  • the tracer could not start the program for another reason: start_failed, with STATUS_NOT_EXECUTABLE too, since the program was found but could not be invoked;
  • the tracer failed: failed, with STATUS_FAILED, and the report says that the trace is incomplete and names the failure.

When the lookup fails, no process starts, and the report’s command holds one placeholder process whose program is the name that kizz looked up, with every location that the lookup checked.

The report never claims a complete trace that the tracer reported otherwise: a reason that the trace is incomplete, an unknown system call or a connection that the run reports but that no program of its tree lists is put on the first program of the command’s first process, and a tracer that gives no tree gets the tree of one process with everything the run reports.

not_executed gives the outcome, status and report of a command that kizz could not run because it failed itself before the start, such as when it could not set up the handling of signals.

Structs§

ExecuteRequest
The command that kizz execute runs, as its caller gives it.
Executed
What a run of kizz execute gave.

Constants§

STATUS_FAILED
The exit status when kizz itself fails after it accepted the command line: the tracer failed, or the report could not be written.
STATUS_NOT_EXECUTABLE
The exit status when the program is found but cannot be run or started.
STATUS_NOT_FOUND
The exit status when the program is not found.

Functions§

execute
Run the command of request through tracer, keeping the terminal and with the process tree, while cancel carries the signals that the caller forwards; return its outcome, the exit status and the report, as the module’s documentation says.
exit_status
The exit status of kizz execute for a command whose outcome is outcome: the program’s exit code, its low eight bits as the system reports them; 128 plus the number of the signal that killed it; STATUS_NOT_FOUND when the program is not found; STATUS_NOT_EXECUTABLE when it is found but cannot be run or started; and STATUS_FAILED when the tracer failed. A signal number that does not fit gives 255.
not_executed
The outcome, status and report of the command of request, which kizz did not run because it failed itself before the start, as message says: failed, with STATUS_FAILED, and a report whose command holds the placeholder process and says that the trace is incomplete.