Module util 

Small formatting/parsing helpers shared by the other modules.

Structs

FileLock

Advisory exclusive lock on a file. Held for the lifetime of the value.

Constants

GLYPH_FAIL

✕

GLYPH_INFO

◆

GLYPH_PASS

✓

GLYPH_WARN

▲

Functions

check_regular_chain

Check that base/rel is a chain of real directories ending in a regular file, with no symlink at any component. Read-only; used before hashing or restoring a store file.

command_for

A Command for a trusted tool (cargo, rustc) or a user program: relative names are resolved through tool_path to an absolute path.

copy_file_hashed

Copy a regular file into a new destination (O_EXCL) while hashing it. Refuses symlinks/FIFOs/devices and never follows a destination symlink. Returns (bytes, sha256).

copy_file_verified

Copy + verify a recorded size/hash. On mismatch the new destination is removed and the operation fails (never installs unverified bytes).

create_dir_chain_nofollow

Create a directory chain under an existing base without following any symlink component. rel must already have been validated (only normal components). New components are 0700.

create_private_dir_all

Create a directory tree with mode 0700 (Unix), refusing a symlinked or foreign-owned final directory. Existing directories are tightened to 0700.

dim

Dimmed — labels, legends, secondary detail.

ensure_private_dir

Verify (and, when possible, repair) an existing private directory.

ensure_windows_user_path

error_block

One failure rendered in the tool’s visual language: a red ✕ line, the message’s own continuation lines indented beneath it, then any anyhow causes as dim rows. Plain glyphs when colors are off.

euid

Effective uid. Only meaningful on Unix; 0 elsewhere (permission checks are skipped there and documented as such).

fail

Red — failures.

force_remove_dir

Remove a tree robustly: read-only files (a wrapper’s store, copies that inherited the read-only attribute) block remove_dir_all on Windows, so clear the flag and retry once; report the original error if it still fails.

green

Brand-green text (#92D293) — section titles and success accents.

heading

Bold brand green — top-level headings.

human_age

Age of a timestamp, human-readable (“3.4 days”).

human_bytes

1234567 -> "1.2 MiB" style, compact.

human_duration

Compact duration for humans (“3.4 s”, “1.2 min”, “2.1 h”).

info

Calm blue — neutral info.

is_reparse_point

Is this a Windows reparse point (symlink/junction/mount point)? On Unix symlinks are handled by file_type().is_symlink.

is_windows_reserved

Windows reserved device names (case-insensitive, before the first dot). CON, NUL, COM1, CON.txt, LPT9.log, …

on_path

Is program reachable through PATH? (bare which, no extra crate)

owned_by_us

Is this file owned by the current effective user? (always true off Unix)

parse_duration

Parse "30d", "2w", "12h", "90m", "45s" or plain seconds "45".

read_small_text

Read a small regular file without following a symlink and without blocking on FIFOs/devices. Returns an error on non-regular or oversized inputs.

read_small_text_follow

Like read_small_text but follows a user’s config symlink (dotfiles); still refuses FIFOs/devices and oversized inputs.

read_trusted_config

Read a global config file from an already-open-like trusted path: O_NOFOLLOW, regular-file-only, owned by the current euid, and not group/world-writable. The ownership/mode checks use fstat on the opened descriptor, so a symlink/file swap between a path check and this read cannot redirect the trust anchor.

sha256_file

SHA-256 of a regular file (lowercase hex). Callers that accept untrusted paths must reject symlinks with symlink_metadata first.

tool_path

Resolve an executable to an absolute path. This is the Windows CWD-search fix: Command::new("cargo") must never be used directly.

validate_component

One path component: no separators, no ./.., no NUL, no Windows drive/ADS separator, no trailing dot/space, no reserved device stem. Use for manifest fields that must be one directory or file name (name, profile, memo, parity keys).

validate_rel

A relative path with only normal components. Rejects absolute paths, .., ., NUL, drive prefixes, and backslash/forward-slash tricks. This is the single gate for every manifest path that reaches the filesystem.

warn

Amber — warnings.

which

Is program installed at all (PATH or cargo bin dir)?

which_path

Absolute path of program if discoverable — first on PATH, then as a fallback in Cargo’s own bin dir ($CARGO_HOME/bin, e.g. C:\Users\<user>\.cargo\bin), which rustup tools live in but isn’t on PATH in every shell. Returns None when not found anywhere.

write_atomic_private

Atomically replace a private config file. The temp is created with O_EXCL and mode 0600 in the same directory, then renamed over the target. Renaming replaces a planted symlink instead of following it (on Unix); on Windows a pre-existing symlink is removed first, never followed.