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§
- Access
Bits - 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.
- Changed
Read - A file that changed during a run after the command first read it or ran it.
- Content
Hash - 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.
- File
Meta - 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.
- Program
Path - The absolute path of a program that a step ran.
- Step
Record - What is recorded about one run of a step, by step key, and the tasks that own the record.
- Step
Spec Record - 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.
- Entry
Kind - The type of a directory entry, as the listing reports it, without following symbolic links.
- NotCached
Reason - Why the result of a run was not cached.
- Path
State - The state of a touched path when its step finished.
- Recorded
Output - A step’s raw captured output, exactly as the command wrote it.
- RunReason
- Why a step ran.
- Special
Kind - A device, FIFO, or socket, which is recorded by type only.
- Step
Exit - 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 asa file changed after the command read it: in.txt (the command wrote it). - connections_
text - The connections
connectionsas text, each shown byConnection::textwithpath, in the order given:127.0.0.1:80,127.0.0.1:80 and Unix socket /run/s, ora, b and cfor several, andno connectionfor 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, orsystem calls 400 and 1000000for several, in the order given.