Module ape 

Actually Portable Executable (APE / cosmocc) support.

Cosmopolitan APE binaries start with a shell prologue rather than a native image header. A host without a binfmt_misc registration for them – stock NixOS among them – refuses them with ENOEXEC (“Exec format error”), and only a shell knows to retry.

This crate launches them through a loader: an explicit one (LOADER_ENV), else the loader embedded in the image (the default ape-loader feature; installed into a private, exec-capable cache, or a sealed memfd), else an installed ape, else the host shell.

• Spawns whose program and environment are known plan the loader before the spawn: SpawnSpec/AsyncProcess, argv NativeProcesses, and command / tokio_command for callers building their own command.
• A caller-built command keeps every caller setting and is retried once after a refusal, through execvp’s POSIX ENOEXEC shell rule (spawn_std).
• fork_guard / exclusive_fork_guard are the process-wide fork lock that keeps a freshly written loader out of concurrently forked children (ETXTBSY); a spawner outside this crate should hold fork_guard across its spawn.

Structs

ApeLaunch

How to run one APE image: loader image args....

ApeOptions

What a launch plan consults, as the child will see it.

Enums

LoaderKind

Which loader a planned launch runs the image through.

Constants

CACHE_DIR_ENV

Environment variable naming the preferred directory for loaders extracted from APE images. Tried before the host defaults; like them it is used only when owned by the current user, not group/world-writable, and on an exec-capable mount.

LOADER_ENV

Environment variable naming an explicit APE loader (an ape binary or a POSIX shell). Read from the child environment first, then this process’s.

MAGICS

Leading bytes of every APE image: MZqFpD=' (the standard header, also a valid DOS/PE MZ stub), jartsr=' (non-Windows), APEDBG=' (debug).

NEEDS_LOADER

An APE image is not a native Linux executable.

Functions

command

A std::process::Command for program that runs an APE image through its planned loader, with this process’s environment as the child’s.

embedded_loader

The host-runnable loader embedded in image, installed into the first usable cache_dirs entry (or, on Linux, a sealed memfd). None when the host runs APE natively, the image carries no valid loader for this host, or nothing could be materialized.

exclusive_fork_guard

Hold while a file that will be executed is open for writing.

extract_loader

Inflate and validate the Linux ELF loader image embeds for machine ("x86_64" or "aarch64").

fork_guard

Hold across a spawn so no executable is being written meanwhile.

gunzip

Decode one gzip member (RFC 1952), refusing output over limit bytes.

is_ape_file

Whether the file at path is an APE image. Unreadable files are not.

is_ape_header

Whether header begins with an APE magic.

is_exec_format_error

The kernel refused the image’s format.

loader_blob_range

(skip, count) of the gzip’d Linux loader for machine.

plan_launch

Plan how to run program if it resolves to an APE image.

prepare_std_retry

Prepare a caller-built command to be spawned again as an APE image.

resolve_program

Resolve program to the file the child’s execvp would execute: a path with a separator is taken as-is (relative to current_dir when given), a bare name is searched on path. The result is absolute.

retry_while_busy

Run spawn again while the host reports the program busy (ETXTBSY).

spawn_std

Spawn a caller-built command under the fork lock, retrying while the program is transiently busy (ETXTBSY) and once if the host refused it as an APE image.