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 withoutPATH, or the tracer reported the program missing:not_found, withSTATUS_NOT_FOUND; - the lookup found only a location that cannot be run, or the tracer reported the
program not executable:
not_executable, withSTATUS_NOT_EXECUTABLE; - the tracer could not start the program for another reason:
start_failed, withSTATUS_NOT_EXECUTABLEtoo, since the program was found but could not be invoked; - the tracer failed:
failed, withSTATUS_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§
- Execute
Request - The command that
kizz executeruns, as its caller gives it. - Executed
- What a run of
kizz executegave.
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
requestthroughtracer, keeping the terminal and with the process tree, whilecancelcarries 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 executefor a command whose outcome isoutcome: 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_FOUNDwhen the program is not found;STATUS_NOT_EXECUTABLEwhen it is found but cannot be run or started; andSTATUS_FAILEDwhen 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, asmessagesays:failed, withSTATUS_FAILED, and a report whose command holds the placeholder process and says that the trace is incomplete.