Skip to main content

Module step

Module step 

Source
Expand description

The contents of step records.

A StepRecord holds what kizz knows about one run of a step: the full step specification, every Observation with its recorded PathState, how the command ended, its raw captured output, how long it ran, when it ran, why it ran, and the tasks that own it.

Every type here is encoded by the rules of “Step keys”: definite lengths, fields in a fixed order, and maps sorted by key. Paths and names are byte strings, so paths that are not UTF-8 survive unchanged.

Structs§

AccessBits
The combined kinds of access a step made to one path, one bit per kind.
Attribute
One extended attribute of a path: its name, and a BLAKE3 hash of its value.
Attributes
The extended attributes recorded with a path whose attributes a step read or listed: those of the path itself and, for a symbolic link, those of what it points to, each sorted by name. A file system without attributes records none.
ChangedRead
A file that changed during a run after the command first read it or ran it.
ContentHash
A BLAKE3 hash: of a file’s content, of a directory’s entries, or of a task program.
Difference
One recorded path that a cache check found changed.
DirEntry
One entry of a listed directory.
FileMeta
The metadata of a regular file that a cache check compares.
Listing
The recorded contents of a listed directory, in the order the file system returned its entries when kizz read it. Entry inode numbers are not recorded.
Observation
One path a step touched, how it touched it, and its state when the step finished.
Owner
The owner of a file or directory: its user and group numbers.
ProgramPath
The absolute path of a program that a step ran.
StepRecord
What is recorded about one run of a step, by step key, and the tasks that own the record.
StepSpecRecord
The full specification of a step, as its run() call gave it, with the values that place it in its task: the task program hash and the occurrence number.
Times
The modification and change times of a regular file or a directory, in nanoseconds since the Unix epoch. Access times are never recorded.

Enums§

Capture
How a step captured its output, as its specification gave it.
Change
What changed about one recorded path, as a cache check found it.
Connection
A connection that a command made to a service outside the trace: an IPv4 or IPv6 address and port, or a Unix socket by path or abstract name. What came back is an input that kizz cannot see, so it warns about the connection, and the result is still cached.
EntryKind
The type of a directory entry, as the listing reports it, without following symbolic links.
NotCachedReason
Why the result of a run was not cached.
PathState
The state of a touched path when its step finished.
RecordedOutput
A step’s raw captured output, exactly as the command wrote it.
RunReason
Why a step ran.
SpecialKind
A device, FIFO, or socket, which is recorded by type only.
StepExit
How a recorded step ended.

Constants§

MAX_LISTED_NAMES
The most entries a listed directory may have for its names to be kept.
PERMISSION_BITS
The permission bits of a mode: the low twelve bits, the set-user-ID, set-group-ID, and sticky bits included.

Functions§

changed_reads_text
The reason for files that changed during a run after the command first read them, with each path shown by path: how many files changed, then each file with who changed it, such as a file changed after the command read it: in.txt (the command wrote it).
connections_text
The connections connections as text, each shown by Connection::text with path, in the order given: 127.0.0.1:80, 127.0.0.1:80 and Unix socket /run/s, or a, b and c for several, and no connection for none.
permission_bits
The permission bits of mode, without its file type.
system_call_numbers
The numbers of system calls that the tracer does not know, as text: system call 400, or system calls 400 and 1000000 for several, in the order given.