zxsh is a modern, lightweight, POSIX-like command shell implemented in Rust. It is designed specifically for the Fuchsia operating system to serve as a fast, robust, and minimal shell environment, intended to replace the NetBSD-derived dash shell (zircon/third_party/uapp/dash).
Unlike traditional ASTs which rely on recursive heap-allocated structures (such as Box<Node>), zxsh compiles commands into a flat, relocatable Abstract Syntax Tree (src/parser/ast.rs, src/relative.rs).
relative::Ptr<T>, relative::Slice<T>, and relative::BStr). Pointer dereferencing is bounds-checked against the containing buffer (relative::Buffer), ensuring memory safety without pointer patching during reallocation.Command, WordPart, Redirect, CaseItem) implement zerocopy traits (FromBytes, IntoBytes, Immutable, KnownLayout), allowing direct in-place access and serialization.SubshellPayloadHeader in src/subshell.rs) and transfers it via a startup handle (fuchsia_runtime::HandleType::User0). The spawned zxsh subshell process takes the handle on startup and executes the AST in place without reparsing or tree allocations.Because zxsh runs in early-boot and recovery environments, keeping the binary size small is a primary design goal:
String and str are largely replaced by BString and BStr types from the bstr crate (src/string.rs). These operate directly on arbitrary [u8] byte slices (complying with Bourne shell path/variable byte semantics) and are compiled without the "unicode" feature to eliminate large Unicode validation tables.src/errors.rs) for Zircon (zx_status_str) and I/O (io_err_str) error codes.src/sort.rs) to avoid compiling the standard library's larger generic sorting routines.FlatMap and FlatSet structures (src/collections.rs) for variables, functions, aliases, and limits, avoiding the overhead and SipHash hashing dependencies of standard HashMap and HashSet.-Copt-level=z (optimize-for-size in BUILD.gn) to minimize binary footprint on BootFS.In interactive mode (src/repl/mod.rs):
line-editor library (//src/lib/line-editor) for history management and interactive line editing.src/repl/completion.rs) for commands in PATH as well as filesystem paths.PS1 (default $ ), PS2 (default > ), and PS4 (xtrace prefix, default + ).zxsh implements standard POSIX shell grammar and execution semantics:
cmd arg1 arg2), pipelines (cmd1 | cmd2 | cmd3) with optional status negation (! cmd1 | cmd2), and command blocks ({ cmd; }).if ...; then ...; elif ...; then ...; else ...; fiwhile ...; do ...; done, until ...; do ...; done, for var in ...; do ...; donecase word in [(] pattern) ... ;; esac&& (logical AND), || (logical OR), ; and newline (sequence), & (asynchronous background execution)break [n], continue [n]fname() { ... }) with local variable scoping (local) and positional argument isolation.$VAR, ${VAR}, ${VAR:-default}, ${VAR:=default}, ${VAR:?error}, ${VAR:+alt}, string length ${#VAR}, suffix removal ${VAR%pattern} / ${VAR%%pattern}, and prefix removal ${VAR#pattern} / ${VAR##pattern}.$? (exit status), $# (arg count), $$ (PID), $! (last background PID), $* / $@ (all args), $- (current options), $0 (script/shell name), and positional $1..$9, ${10}.$(command) and legacy backticks `command`.$(( expression )) supporting arithmetic (+, -, *, /, %), pre/post-increment and decrement (++, --), bitwise (&, |, ^, ~, <<, >>), comparisons (<, <=, >, >=, ==, !=), logical (&&, ||, !), ternary (? :), assignment (=, +=, -=, etc.), comma (,), decimal, octal (0...), and hexadecimal (0x...) constants, variables, and grouping.*, ?, and character classes [...] (including ranges [a-z] and negations [!...] / [^...]).$IFS, single quotes '...', double quotes "...", and backslash escapes \.< file, output > file (truncation) / >> file (append), and read-write <> file>| file (overriding noclobber / set -C)>&fd, <&fd and closing >&-, <&-<< EOF and <<- EOF (with or without parameter expansion; small heredocs are written inline to the pipe, while large heredocs use a streaming worker thread to prevent pipe deadlocks)/dev/null redirection emulation via fdio::create_fd_null&, jobs, fg, bg, wait)trap (supports EXIT, INT, TERM, HUP, QUIT)zxsh supports a rich set of builtins implemented across dedicated modules:
Implemented in src/builtins/essential.rs and src/builtins/mod.rs:
cd, chdir, pwd (supports -L logical and -P physical modes)export, readonly, local, unsetalias, unaliasset, shift, getoptseval, exec, exit, returnbreak, continuejobs, fg, bg, waittrap (signal trap registration and inspection)read (reads line from standard input with -r raw mode and $IFS field splitting)type (identifies command as builtin, function, alias, or external binary)command (executes command bypassing shell functions and aliases)hash (displays or manages cached executable path lookups)ulimit (manages resource limits such as file size, stack, open files, CPU time)umask (displays or updates file mode creation mask in octal or symbolic format). (source), :, true, falseImplemented in src/builtins/file_utils.rs to allow filesystem operations without the overhead of spawning external processes:
ls (directory and file listing; supports -l long format)cp (copy files; supports -f)mv (move/rename files; supports -f)rm (remove files and directories; supports -r/-R, -f)mkdir (create directories; supports -p)echo (src/builtins/echo.rs): Prints arguments with escape sequence processing (\n, \t, \c, octal escapes) and -n flag support.printf (src/builtins/printf.rs): POSIX standard formatted output supporting format specifiers (%s, %c, %d, %i, %o, %u, %x, %X, %f, %F, %e, %E, %g, %G, %a, %A, %b, %%), width and precision modifiers (including *), and formatting flags (-, +, space, #, 0).test / [ (src/builtins/test.rs): Full POSIX expression evaluation:-e, -r, -w, -x, -f, -d, -s, -c, -b, -p, -h, -L, -S, -u, -g, -k, -t, -O, -G, -nt, -ot, -ef-z, -n, =, ==, !=, <, >-eq, -ne, -lt, -le, -gt, -ge!, -a, -o, ( ... )list (src/builtins/list.rs): Displays numbered lines of a file (list <filename>).msleep (src/builtins/msleep.rs): Sleeps for a specified number of milliseconds (msleep <msecs>).dump (src/builtins/dump.rs): Formats and prints a hexadecimal/ASCII dump of a file (dump <filename>).times (src/builtins/times.rs): Prints accumulated user and system CPU times for the shell and child processes.Implemented in src/builtins/fuchsia.rs:
dm / power: Connects to fuchsia.hardware.power.statecontrol.Admin to control device power states:dm poweroff / dm shutdown / power off / power shutdowndm reboot / power rebootdm reboot-bootloader (or rb) / power reboot-bootloader (or rb)dm reboot-recovery (or rr) / power reboot-recovery (or rr)dm help / power helpk: Connects to fuchsia.kernel.DebugBroker to execute kernel debug commands directly from the shell (e.g. k thread). Forwards poweroff, reboot, and reboot-bootloader commands to dm.zxsh supports multiple execution modes (src/main.rs, src/args.rs):
zxsh # or force interactive mode: zxsh -i
zxsh -c "echo 'Hello from zxsh!'" # with positional arguments: zxsh -c 'echo "$1 $2"' script_name "foo" "bar"
zxsh /path/to/script.sh [args...]
zxsh -s [args...] # or forced stdin reading: zxsh - [args...]
HandleType::User0) containing a serialized AST and shell environment in a VMO.Supported single-letter flags (set with -, clear with +) and -o / +o options:
| Flag | Option Name | Description |
|---|---|---|
-a | allexport | Automatically export all defined or modified variables |
-b | notify | Report background job termination immediately |
-C | noclobber | Prevent redirection from overwriting existing files |
-e | errexit | Exit immediately if a command exits non-zero |
-f | noglob | Disable pathname expansion (globbing) |
-i | interactive | Force shell to run interactively |
-I | ignoreeof | Ignore EOF (Ctrl-D) when reading from stdin |
-l | login | Run as a login shell |
-m | monitor | Enable job control |
-n | noexec | Read commands but do not execute them |
-s | stdin | Read commands from standard input |
-u | nounset | Treat unset variables as an error during expansion |
-v | verbose | Print shell input lines as they are read |
-x | xtrace | Print commands and arguments as they are executed |
-E | emacs | Enable Emacs line editing mode |
-V | vi | Enable Vi line editing mode |
Unlike POSIX shells on Linux/macOS, zxsh on Fuchsia does not support implicit inheritance of non-standard file descriptors (FDs other than 0, 1, and 2) for external commands.
For example, if you run:
exec 3>file.txt my_external_command >&3
Or:
my_external_command 3>file.txt
The child process my_external_command will NOT inherit FD 3. It will start with FD 3 closed.
This is a design limitation of the Fuchsia process creation model (fdio_spawn / fuchsia.process.Launcher), which requires explicit transfer of handles and does not support cloning the entire file descriptor table to child processes by default. This behavior matches the Fuchsia port of dash (zircon/third_party/uapp/dash).
Redirections of standard streams (0, 1, 2) are fully supported for all commands.
zxsh includes a comprehensive test suite covering parser grammar, AST serialization, evaluations, expansions, arithmetic, builtins, and parity testing against dash.
To run the test suite:
fx test zxsh_tests
Unit tests are organized in src/tests/ and cover:
dash for all shell builtins