Module util 

Widely useful small utilities.

Structs

DroppingStderr

RetryingStderr for output whose loss must not change how a capped run ends: hermit’s own log when it goes to stderr, and the stack traces that --stacktrace-event and --preemption-stacktrace print there.

RawFd

A descriptor opened with a raw syscall, closed with one when dropped.

RetryingStderr

A Write for the supervisor’s own diagnostics on fd 2 that survives a NONBLOCKING description.

Constants

STDERR_DIAGNOSTIC_DEADLINE

Total wall-clock ALL diagnostic writes in ONE PROCESS may spend waiting for a reader that is not draining. Hermit forks, so read the fork note below before treating this as the whole exit path’s budget.

Functions

canonicalize

path with every symbolic link followed and every . and .. resolved, as glibc’s realpath (std::fs::canonicalize) gives it: relative paths from the working directory, and the same errors for an empty path (ENOENT), a missing component (ENOENT), a component that is not a directory but is followed by more, by ., .. or a trailing / (ENOTDIR), and links nested too deep (ELOOP after 40, Linux’s MAXSYMLINKS).

describe_io_error

Describes error without asking the C library for an errno message.

descriptor_names

The descriptor numbers the linux_dirent64 records in records name: each entry whose name is a decimal number (a descriptor directory’s), in order, leaving out . and ...

find_in_directory

Calls visit with each name in directory path, without . and .., in the kernel’s order, until it returns Some, and returns that value (None when every name was visited).

find_in_open_directory

find_in_directory of a directory already open at directory, from its current offset.

init_shared_stderr_deadline_origin

Create the origin cell every hermit process of this invocation shares.

punch_out_print

A simple debugging helper function that makes it easy to printf-debug through layers of stdout/stderr caputure, such as when running under buck test/tpx.

raw_lstat

The status of the file at path, not following a link in its last component, by a raw newfstatat.

raw_read_file

The whole contents of the file at path, read with raw syscalls. Meant for small files such as procfs entries.

raw_read_link

The target of the link at path, by a raw readlinkat.

raw_read_listing

The whole contents of the procfs listing at path, read with raw syscalls and without allocating between reads, so that where the tool shares the guest’s process its own allocator maps nothing while the kernel walks the address space: the buffer is allocated before the first read, and a listing that fills it is read again, from the start, into one twice the size.

raw_result

raw_syscall’s result as an io::Result.

raw_stat

The status of the file at path, following links, by a raw newfstatat.

raw_syscall^⚠

Issues syscall number with args through the syscall instruction itself on x86-64, returning the kernel’s result (a negative errno on failure). Under in-guest LiteInst Detcore runs inside the guest, where libc’s wrappers (open, fstat, syscall, …) are dynamic symbols the program or a preloaded library may define, and allocate in.

raw_zero_result

raw_syscall’s result for a syscall whose only success value is 0 (fstat, pipe2, socketpair, …): any other value is refused, a negative one as the error it names. raw_result would take a positive return as success, which for such a call the kernel never gives.

rcbs_to_duration

A helper function to convert a number of Retired Conditional Branches (RCBS) into a std::time::Duration via the NANOS_PER_RCB defined in types.rs.

truncated

A little better than the builtin string truncation in format strings, because it includes ellipses.