POSIX Shell

The shell splits input into tokens at newline characters, operator characters, and whitespace boundaries following a defined precedence.

Multi-character operators (&&, ||, <<, >>, etc.) are recognized as single tokens rather than sequences of single-character operators.

Contiguous characters that are not operators or unquoted whitespace form a single word token.

A # character that is not quoted and appears where a new token could begin introduces a comment that extends to the next newline.

Words like if, then, else, fi, do, done, case, esac, while, until, for, in, and function are recognized as reserved when they appear where a command name is expected.

A reserved word that appears as an argument to a command (not in command position) is treated as an ordinary word.

When alias expansion is enabled, the shell replaces alias names with their definitions before further token processing.

Alias expansion is off by default in non-interactive mode per POSIX.

If an alias definition ends with a blank, the next word after the alias is also checked for alias substitution. Self-referencing aliases must not loop infinitely.

Tricky edge case: alias a='b ' with alias b='a ' must terminate.

A sequence of digits immediately preceding a redirection operator (< or >) is recognized as a file descriptor number, not a word.

An unquoted newline terminates the current command, functioning equivalently to a semicolon in most contexts.

A backslash immediately followed by a newline is removed, joining the next line to the current one before tokenization.

The << and <<- operators are recognized as introducing here-documents. The delimiter word follows on the same line; the body extends to a line matching the delimiter exactly.

A backslash preserves the literal value of the following character, except when followed by a newline (which triggers line continuation).

Characters enclosed in single quotes retain their literal meaning. No expansion or substitution occurs inside single quotes.

Double quotes preserve literal values except for $, `, \, and !. Parameter expansion, command substitution, and arithmetic expansion are performed inside double quotes.

Inside double quotes, backslash retains its escaping meaning only before $, `, \, ", and newline. Before other characters the backslash is preserved literally.

The $'...' form interprets backslash escape sequences (\\n, \\t, \\xHH, \\uHHHH, etc.) within single quotes, producing the corresponding byte values.

Added to POSIX in 2024 edition. Was previously a bash/ksh extension.

The $"..." form is intended for locale-dependent string translation. The shell may translate the enclosed string or treat it as a plain double-quoted string.

gbash treats $\"...\" identically to \"...\". Most shells do the same in practice.

After all expansions, unquoted quote characters (single, double, backslash) that were not produced by expansion are removed from the final word.

Any form of quoting (backslash, single quotes, double quotes) on any character of a reserved word prevents it from being recognized as reserved.

An unquoted tilde at the start of a word or after an unquoted colon in an assignment is replaced with the value of HOME (for bare ~) or the home directory of the named user (for ~user).

gbash uses sandbox user metadata; ~user resolves within the sandbox.

In variable assignments, tilde expansion also occurs after unquoted colons, enabling paths like PATH=~:~/bin to expand each tilde.

A dollar sign followed by a name or braced name is replaced with the variable's value, or the empty string if unset (unless nounset is active).

Shell parameters set from command-line arguments or function invocations are accessed as $1-$9 and ${10}, ${11}, etc.

The shell provides read-only special parameters for argument lists, argument count, last exit status, shell PID, last background PID, invocation name, and current option flags.

$$ and $! are virtual PIDs in gbash.

When "$@" is expanded inside double quotes, each positional parameter becomes a separate field, preserving argument boundaries.

Inside double quotes, "$*" expands to a single field with all positional parameters joined by the first character of IFS.

Substitutes the expansion of word when var is unset (or unset/null with the colon form). The variable itself is not modified.

Like default value, but also assigns the expanded word to var when the substitution triggers.

If var is unset (or unset/null with the colon form), the shell writes word to stderr and exits (in non-interactive shells).

Substitutes the expansion of word when var IS set (and non-null with the colon form). Returns empty otherwise.

Expands to the length in characters of the variable's value.

Removes the shortest (# form) or longest (## form) prefix matching the pattern from the variable's value.

Removes the shortest (% form) or longest (%% form) suffix matching the pattern from the variable's value.

Extracts a substring starting at the given offset for the given length. Negative offsets count from the end (requires a space or parentheses to disambiguate from default-value syntax).

Added in POSIX 2024. Negative offset edge cases differ across shells.

Replaces the first match of pattern in the variable's value with the replacement string. The // form replaces all matches. The /# and /% forms anchor to the start or end respectively.

Added in POSIX 2024. Anchored forms are tested in OILS patsub tests.

Converts the first character (^ or ,) or all characters (^^ or ,,) of the variable's value to uppercase or lowercase respectively.

Added in POSIX 2024.

Executes command in a subshell and replaces the construct with the command's standard output, with trailing newlines removed.

The older `command` form performs the same substitution as $(command) but has different quoting rules for nested backslashes and backticks.

Nested backtick quoting is a common edge-case source.

The $(...) form can be nested to arbitrary depth. Each level starts a new parsing context.

The shell evaluates the arithmetic expression and replaces the construct with the decimal result. Standard integer operators (+, -, *, /, %, comparisons, bitwise, logical) are supported.

Inside arithmetic expressions, variable names are recognized and expanded without requiring a $ prefix.

Arithmetic expressions support = and compound assignment operators (+=, -=, *=, /=, %=, <<=, >>=, &=, ^=, |=).

The expr ? expr : expr ternary conditional is supported in arithmetic expressions.

The comma operator evaluates both operands and returns the value of the right operand.

The ++var, var++, --var, and var-- operators modify a variable and return the value before or after modification.

Added in POSIX 2024.

The ** operator raises the left operand to the power of the right.

Added in POSIX 2024. Right-associative.

Expansions are performed in a defined sequence. Tilde expansion first, then parameter/command/arithmetic in a single pass left-to-right, then field splitting, then pathname expansion, then quote removal.

The ordering is a frequent source of subtle bugs across shells.

Brace expansion generates multiple words from comma-separated alternatives or numeric/alphabetic sequences. Not part of POSIX; originated in csh/bash.

Bash extension. Controlled by set -B / set +B.

Process substitution connects a command's output or input to a file-like path that other commands can read from or write to.

Bash/ksh extension. gbash implements this with sandbox-owned pipes.

Expands to the value of the variable whose name is stored in var.

Bash extension. POSIX uses namerefs instead.

$LINENO expands to the current line number within the script or function being executed.

After expansion, unquoted results of parameter expansion, command substitution, and arithmetic expansion are split into fields at sequences of IFS whitespace characters (space, tab, newline by default).

Non-whitespace characters in IFS act as explicit delimiters. Each occurrence produces a field boundary. Adjacent IFS non-whitespace characters produce empty fields between them.

Common pitfall: IFS=: with value 'a::b' must produce three fields.

When IFS is set to the empty string, no field splitting occurs. The entire expansion result becomes a single field.

When IFS is unset, field splitting behaves as if IFS were set to space, tab, and newline.

Sequences of IFS whitespace at the beginning or end of an expansion result do not produce empty leading or trailing fields.

Expansions occurring within double quotes are not subject to field splitting (except "$@" which splits on argument boundaries).

When IFS contains both whitespace and non-whitespace characters, IFS whitespace is trimmed around non-whitespace delimiters, and the non-whitespace character alone acts as the delimiter.

Subtle interaction. IFS=' :' with ' a : b ' should produce [a, b].

An unquoted * in a word matches any string of zero or more characters in filenames.

An unquoted ? matches exactly one character in filenames.

Bracket expressions match a single character from a set or range. Supports character ranges [a-z], negation [!abc] or [^abc], and named classes like [:alpha:].

Filenames beginning with a period are not matched by * or ? unless the pattern also begins with a literal period.

dotglob shopt overrides this behavior (bash extension).

A slash in a pathname can only be matched by a literal slash in the pattern, never by *, ?, or bracket expressions.

When a glob pattern matches no files, the pattern word is left unchanged (unless nullglob or failglob are enabled).

nullglob and failglob are bash extensions.

When the noglob option is set, pathname expansion is not performed and glob characters are treated as literal.

Pathnames generated by globbing are sorted according to the current locale's collation sequence.

gbash uses deterministic UTF-8 sorting which may differ from locale-based collation in some edge cases.

When extglob is enabled, extended pattern matching operators allow matching zero-or-one, zero-or-more, one-or-more, exactly-one, or none of the given patterns.

Bash/ksh extension enabled by shopt -s extglob.

When globstar is enabled, ** in a pathname matches zero or more directories recursively.

Bash extension enabled by shopt -s globstar.

Opens the named file for reading on stdin (fd 0) or the specified file descriptor.

Opens the named file for writing on stdout (fd 1) or the specified file descriptor. Creates the file if it does not exist; truncates it if it does.

Opens the named file for appending on stdout or the specified file descriptor. Creates the file if it does not exist.

When the noclobber option is set, > fails if the target file exists and is a regular file. The >| operator overrides this protection.

Reads input until a line containing only the delimiter is found. If the delimiter is unquoted, parameter expansion, command substitution, and arithmetic expansion occur in the body.

When any part of the delimiter word is quoted, no expansion is performed in the here-document body.

The <<- form strips leading tab characters from each line of the here-document body and from the closing delimiter line.

Provides the expansion of word as stdin to a command, with a trailing newline appended.

Bash/ksh/zsh extension, not in POSIX.

Duplicates file descriptor m onto descriptor n. The >&m form is for output descriptors; <&m is for input descriptors.

Closes file descriptor n.

Opens the named file for both reading and writing on the specified descriptor (default fd 0).

A command may have multiple redirections which are applied left-to-right before the command executes.

Redirections may be placed after compound commands (if, while, for, case, brace groups, subshells) and apply to all commands within the construct.

The shell allocates a file descriptor >= 10 and assigns the number to the named variable.

Bash 4.1+ extension.

A simple command is a sequence of variable assignments and redirections, optionally followed by a command name and arguments. The command name is looked up and executed.

Variable assignments preceding a command name are placed in the environment of that command only (temporary bindings). If the command is a special builtin, the assignments persist.

temp-binding behavior has known xfails for edge cases.

When a simple command has assignments but no command name, the assignments take effect in the current shell environment.

The shell searches for commands in order: special builtins, shell functions, regular builtins, then external commands via PATH.

gbash has no PATH-based external command search; all commands are registry-backed.

If a command cannot be found, the exit status is 127.

If a command is found but cannot be executed (e.g., missing execute permission), the exit status is 126.

Not applicable to gbash's registry model; all registered commands are executable.

A command consisting only of redirections applies them in the current environment. A command of only assignments sets variables in the current environment.

The exec builtin with a command argument replaces the shell process. Without a command argument, redirections are applied to the current shell.

exec with a command does not replace the process in gbash (no real exec). exec with redirections works.

The | operator creates a pipeline where the standard output of the command on the left is connected to the standard input of the command on the right.

The exit status of a pipeline is the exit status of the last command in the pipeline.

Prefixing a pipeline with ! inverts its exit status: zero becomes one, and non-zero becomes zero.

When pipefail is set, the pipeline exit status is the rightmost command that exited with non-zero status, or zero if all succeeded.

Added to POSIX in 2024. Was previously a bash extension.

The PIPESTATUS array variable contains the exit status of each command in the most recent pipeline.

Bash extension.

Commands separated by ; are executed sequentially. The shell waits for each command to complete before starting the next.

The right command executes only if the left command exits with status zero.

The right command executes only if the left command exits with non-zero status.

A command terminated by & is executed asynchronously. The shell does not wait for it to complete and sets $! to its process ID.

gbash supports basic background execution but with virtual PIDs and no job control.

Each command in a pipeline may execute in a subshell. Variable assignments in pipeline stages do not affect the parent shell (unless lastpipe is enabled for the final stage).

lastpipe support is a bash extension that gbash implements.

Executes the then-body if the condition command list exits with status zero. Supports elif chains and a final else clause.

Repeatedly executes the body while the condition command list exits with status zero.

Repeatedly executes the body until the condition command list exits with status zero (opposite of while).

The for var in word... form iterates over the expanded word list, assigning each word to the variable and executing the body.

The for var (without in) iterates over the positional parameters, equivalent to for var in \"$@\".

Arithmetic for loop that evaluates init once, tests cond before each iteration, and evaluates step after each iteration.

Bash/ksh extension.

Matches a word against patterns and executes the corresponding command list for the first matching pattern. Patterns support shell wildcards. Multiple patterns per clause are separated by |.

The ;& terminator falls through to the next clause's commands unconditionally. The ;;& terminator continues testing subsequent patterns.

Added to POSIX in 2024. Previously a bash extension.

Groups commands for execution in the current shell environment. Unlike a subshell, variable assignments and redirections persist.

Executes the command list in a subshell environment. Variable changes, directory changes, and other state modifications do not affect the parent shell.

gbash simulates subshells with state cloning, not fork.

Evaluates an arithmetic expression. Returns exit status 0 if the result is non-zero, and status 1 if the result is zero.

Bash/ksh extension.

Extended test command with pattern matching (==), regex matching (=~), and logical operators (&&, ||, !) without the quoting pitfalls of the [ command.

Bash/ksh extension. Not in POSIX (which uses test/[ only).

Displays a numbered menu from a word list, reads the user's choice, and assigns the selected word to a variable.

Bash/ksh extension. Limited utility in sandbox/non-interactive mode.

break exits the innermost (or Nth) enclosing loop. continue skips to the next iteration of the innermost (or Nth) enclosing loop.

break/continue in loop conditions has a known xfail.

Whether empty bodies in if/then/fi or while/do/done are accepted or rejected is not specified by POSIX. Bash accepts them.

gbash has xfails for empty then/fi and empty do/done cases.

Defines a shell function that can be invoked as a simple command. The body is any compound command (typically a brace group).

The function name { ... } syntax is an alternative way to define functions.

Bash/ksh extension.

When a function is invoked, the arguments become the function's positional parameters. The caller's positional parameters are saved and restored when the function returns.

The return builtin causes the function to exit with the given status (or the status of the last command if no argument).

The local builtin creates function-scoped variables that are destroyed when the function returns. POSIX does not require local variables but most shells support them.

local is a bash extension. POSIX added it in 2024 as an XSI extension.

Functions execute in the current shell environment (not a subshell). Variable assignments in a function are visible to the caller unless the variable is declared local.

Functions can call themselves recursively. Each invocation gets its own positional parameters.

POSIX requires function names to be valid shell names. Whether names containing $, -, or other non-name characters are accepted is unspecified.

Known xfails for function names with $ and command sub.

Variable assignments preceding special builtins (break, :, ., continue, eval, exec, exit, export, readonly, return, set, shift, times, trap, unset) persist in the shell environment after the builtin completes.

Certain errors in special builtins (like a redirection error) may cause a non-interactive shell to exit, unlike regular builtins.

gbash may not exit on all POSIX-required special-builtin errors.

The : command does nothing and exits with status 0. Used for side effects of expansions in its arguments.

Reads and executes commands from a file in the current shell environment. The file is searched for in PATH if not found by pathname.

Concatenates all arguments with spaces and executes the result as a shell command in the current environment.

Marks named variables to be included in the environment of subsequently executed commands.

Marks named variables as readonly. Subsequent attempts to assign or unset them produce an error.

Some readonly assignment edge cases have known xfails.

With option flags, enables or disables shell behaviors. With arguments after --, replaces positional parameters. Without arguments, lists all shell variables.

Shifts positional parameters by the specified count (default 1). $1 becomes the value of $(1+n), and $# decreases by n.

Prints accumulated user and system CPU times for the shell and its children.

gbash reports synthetic times. Known xfail for format differences.

Associates a command string with a signal or pseudo-signal. When the signal arrives, the command is executed. Supports EXIT, ERR, DEBUG, and RETURN traps.

Removes the named variable from the shell environment. With -f, removes the named function.

Dynamic scoping with unset has known edge-case xfails.

Exits the shell with the given status (or the status of the last command executed). EXIT traps are executed before termination.

Evaluates a conditional expression and returns 0 (true) or 1 (false). Supports file tests, string tests, integer comparisons, and logical operators.

Writes its arguments separated by spaces to stdout, followed by a newline.

echo -n and -e behavior is implementation-defined in POSIX. gbash follows bash.

Formats and prints arguments according to a format string, similar to C printf. Supports %s, %d, %o, %x, %f, %e, %g, %b, %q, etc.

Reads a line from standard input and splits it according to IFS into the named variables. The last variable receives the remainder.

Changes the current working directory. Supports -, CDPATH search, and -P (physical) vs -L (logical) path handling.

Prints the absolute pathname of the current working directory. Supports -P (physical, no symlinks) and -L (logical, default).

Indicates how each argument would be interpreted as a command name (alias, function, builtin, file, or keyword).

type -P and type -a have known xfails on Darwin.

Executes a command bypassing shell function lookup. With -v, describes the command. With -p, searches only the default PATH.

command -p has a known xfail (default PATH differs in sandbox).

Parses option flags from positional parameters according to an option string. Sets OPTARG and OPTIND.

Gets or sets the file mode creation mask. Supports both symbolic and octal notation.

Waits for the specified process or job to complete and returns its exit status. Without arguments, waits for all background children.

gbash wait works for virtual background jobs only.

Sends a signal (default SIGTERM) to the specified process IDs or job specifications.

gbash kill only operates on virtual PIDs within the shell family.

Remembers the locations of commands found via PATH search. With -r, clears the remembered locations.

In gbash, all commands are registry-backed so hashing is a no-op concept.

Sets variable attributes such as integer (-i), readonly (-r), export (-x), lowercase (-l), uppercase (-u), array (-a), associative (-A), and nameref (-n).

Bash extension. Core to bash scripting patterns.

Reads lines from stdin into an indexed array variable.

Bash extension.

Evaluates each argument as an arithmetic expression.

Bash extension.

Enables or disables shell builtin commands by name.

Bash extension.

When invoked with -c, the shell reads commands from the provided string operand rather than from a file or stdin.

When invoked with a filename argument, the shell reads and executes commands from that file.

In interactive mode, the shell reads commands from standard input when no script file or -c string is provided.

gbash is non-interactive by design; stdin reading is through the API.

When set, the shell exits immediately if a simple command fails, unless the command is part of a condition (if, while, until, && / || chain, or negated with !).

Numerous edge cases. Existing OILS tests cover many of them.

When set, expanding an unset variable (other than $@ and $*) produces an error and causes the shell to exit.

When set, the shell writes each input line to stderr before executing it.

When set, the shell writes each command to stderr (prefixed by the expansion of PS4) before execution.

Known xfail for escape style of unprintable characters.

When set, the shell reads commands but does not execute them. Used for syntax checking.

When set, all variable assignments are automatically exported.

When set, output redirection with > fails if the file already exists and is a regular file.

An exit status of zero indicates the command completed successfully.

Non-zero exit statuses from 1 to 125 indicate various command-defined error conditions.

A command found but not executable (permission denied) should produce exit status 126.

Not applicable to gbash registry model.

A command that cannot be found produces exit status 127.

When a command is terminated by a signal, the exit status is 128 plus the signal number.

gbash implements this for trapped signals on virtual PIDs.

In the context of errexit, failures in conditions of if/while/until, in commands negated with !, and in the left side of && or || do not trigger an immediate exit.

Complex area. Tested extensively in OILS errexit tests.

The $? special parameter always holds the exit status of the most recently completed foreground command or pipeline.

When set, shell functions, command substitutions, and subshell environments inherit the ERR trap from the parent.

Bash extension.

A syntax error in a non-interactive shell causes it to exit with a non-zero status.

A trap registered for EXIT is executed when the shell terminates, whether by reaching the end of input, executing exit, or receiving a fatal signal.

The shell can register handlers for standard signals. When the signal is received, the handler command is executed.

gbash routes signals through a virtual mechanism; not all signals are deliverable.

Invoking trap without arguments outputs the currently set traps in a form suitable for re-evaluation.

Setting a trap action to the empty string causes the signal to be ignored.

Setting a trap action to - resets the signal disposition to the default.

When a subshell is created, traps that were set to be ignored are inherited. Traps set to a command string are reset to default in the subshell.

The ERR trap fires after any simple command exits with non-zero status, subject to errexit-like exemptions.

Bash extension.

The DEBUG trap fires before each simple command, for command, case command, and select command.

Bash extension.

The RETURN trap fires each time a function or sourced script returns.

Bash extension.

POSIX job control allows suspending, resuming, and switching between foreground and background jobs using bg, fg, and jobs.

gbash does not implement job control. No process suspension or TTY.

When monitor mode is enabled, the shell places each pipeline in its own process group and reports job completions.

gbash does not implement process groups or job monitoring.

POSIX defines job specifications for referring to background jobs by number, by current/previous status, or by command prefix.

gbash does not implement job specifications.

When a pipeline reader exits, writers should receive SIGPIPE and terminate rather than blocking or accumulating output.

Known xfail for SIGPIPE regression test.

Variables are assigned using name=value syntax. The value undergoes tilde expansion, parameter expansion, command substitution, arithmetic expansion, and quote removal.

The += operator appends to an existing variable's value (or adds to an array).

Bash extension.

Variables marked with export are included in the environment of all subsequently executed commands.

A subshell receives a copy of the parent's variables, functions, traps, and other state. Modifications in the subshell do not affect the parent.

Variable assignments before a command name are placed in the environment of that command only and do not persist (unless the command is a special builtin).

Edge cases around temp bindings have known xfails in OILS tests.

The IFS variable determines the characters used for field splitting after expansion and by the read builtin.

The PATH variable contains a colon-separated list of directories to search for external commands.

gbash does not search PATH for host binaries. PATH is used for . (source) file lookup.

The HOME variable's value is substituted for ~ in tilde expansion.

PWD holds the current working directory pathname. OLDPWD holds the previous working directory (set by cd).

Bash-style indexed arrays with arr[i]=val syntax, ${arr[@]}, ${arr[*]}, ${#arr[@]}, and ${!arr[@]}.

Bash extension. Core to many bash scripts.

Associative arrays declared with declare -A, supporting arbitrary string keys.

Bash extension.

A nameref variable acts as an alias for another variable. Reading or assigning the nameref operates on the referenced variable.

Bash 4.3+ extension.

Each expansion of $RANDOM yields a pseudo-random integer between 0 and 32767. Assigning to RANDOM seeds the generator.

Bash extension. gbash's RANDOM is seedable for deterministic replay.

SECONDS expands to the number of seconds since the shell started (or since last assigned).

Bash extension.

Shell variables use dynamic scoping in functions. A function sees the caller's variables unless local is used. Unset in dynamic scope reveals the previous scope's value.

Multiple known xfails for dynamic-unset and tempenv interactions.