Provided by: yash_2.49-1_amd64 
NAME
yash - a POSIX-compliant command line shell
SYNOPSIS
yash [options...] [--] [operands...]
INTRODUCTION
Yet another shell (yash) is a command line shell for UNIX-like operating systems. The shell conforms to
the POSIX.1-2008 standard (for the most parts), and actually is more conforming than other
POSIX-conforming shells. Moreover, it has many features that are used for interactive use, such as
command history and command line editing.
This program can be freely modified and redistributed under the terms of GNU General Public License
(Version 2). Use of this program is all at your own risk. There is no warranty and the author is not
responsible for any consequences caused by use of this program.
This manual can be freely modified and redistributed under the terms of Creative Commons
Attribution-ShareAlike 2.1 Japan.
Yash is developed and maintained by 渡邊裕貴 (WATANABE Yuki) aka Magicant. Yash development project and
Yash’s homepage are hosted by OSDN.
INVOCATION
When invoked as a program, yash performs the predefined initialization steps and repeatedly reads and
executed commands. Command line arguments given in the invocation determines how the shell initializes
itself and executes commands.
Command line arguments
The syntax of command line arguments for yash conforms to POSIX. As defined in POSIX, arguments are
separated into options and operands. For more detailed explanation about options and operands, see
Command argument syntax. All options must come before operands. The interpretation of operands depends on
options specified.
When you specify the -c (--cmdline) option, you must give at least one operand. The shell interprets and
executes the first operand as a command string. The second operand, if any, is used to initialize the 0
special parameter. The other operands, if any, are used to initialize the positional parameters. When the
-c (--cmdline) option is specified, the shell does not read any file or the standard input (unless the
dot built-in is used).
If you specify the -s (--stdin) option, the shell reads the standard input, interprets the input as
commands, and executes them. All the operands given are used to initialize the positional parameters. The
0 special parameter is initialized to the name the shell is invoked as.
If you specify neither the -c (--cmdline) nor -s (--stdin) option, the shell reads a file, interprets the
file contents as commands, and executes them. The first operand specifies the pathname of the file. The
remaining operands are used to initialize the positional parameters. If you do not give any operands, the
shell reads the standard input as if the -s (--stdin) option is specified.
You cannot use both the -c (--cmdline) and -s (--stdin) options at a time.
If you specify either the --help or -V (--version) option, the shell never performs the usual
initialization or command execution. Instead, it just prints brief usage (for --help) or version
information (for -V and --version). If the -V (--version) option is accompanied by the -v (--verbose)
option, the shell prints a list of the available optional features as well.
If you specify the -i (--interactive) option, the shell goes into the interactive mode. If you specify
the +i (++interactive) option, conversely, the shell never goes into the interactive mode.
If you specify the -l (--login) option, the shell behaves as a login shell.
The --noprofile, --norcfile, --profile, and --rcfile options determine how the shell is initialized (see
below for details).
In addition to the options described above, you can specify options that can be specified to the set
built-in.
If the first operand is - and the options and the operands are not separated by --, the first operand is
ignored.
Initialization of yash
Yash initializes itself as follows:
1. Yash first parses the name it was invoked as. If the name starts with -, the shell behaves as a login
shell. If the name is sh (including names such as /bin/sh), the shell goes into the POSIXly-correct
mode.
2. If no operands are given and the standard input and standard error are both connected to a terminal,
the shell goes into the interactive mode unless the +i (++interactive) option is specified.
3. Job control is automatically enabled in an interactive shell unless the +m (++monitor) option is
specified.
4. Yash reads and executes commands from the following files (unless the real and effective user IDs of
the shell process are different or the real and effective group IDs of the shell process are
different):
1. If it is behaving as a login shell, the shell reads the file specified by the --profile=filename
option unless the --noprofile option is specified or the shell is in the POSIXly-correct mode.
If the --profile=filename option is not specified, the shell reads ~/.yash_profile as a default.
2. If in the interactive mode, the shell reads the file specified by the --rcfile=filename option
unless the --norcfile option is specified.
If the --rcfile=filename option is not specified, the shell instead reads the following files:
• If not in the POSIXly-correct mode, the shell reads ~/.yashrc. If it cannot be read, the
shell searches YASH_LOADPATH for a file named initialization/default.
• If in the POSIXly-correct mode, the shell performs parameter expansion on the value of the
ENV environment variable and treats the expansion result as the name of the file to read.
Note
Yash never automatically reads /etc/profile, /etc/yashrc, nor ~/.profile.
SYNTAX
The shell reads, parses, and executes command line by line. If there is more than one command on a line,
all the commands are parsed before executed. If a command is continued to next lines, the shell reads
more enough lines to complete the command. On a syntax error, the shell neither reads nor executes any
more commands.
Tokens and keywords
A command is composed of one or more tokens. In the shell syntax, a token is a word that is part of a
command. Normally, tokens are separated by whitespaces, that is, the space or tab character. Whitespaces
inside a command substitution or a parameter expansion, however, do not separate tokens.
The following symbols have special meanings in the shell syntax and in most cases separate tokens:
; & | < > ( ) [newline]
The following symbols do not separate tokens, but have syntactic meanings:
$ ` \ " ' * ? [ # ~ = %
The following tokens are treated as keywords depending on the context in which they appear:
! { } [[ case do done elif else esac fi
for function if in then until while
A token is treated as a keyword when:
• it is the first token of a command,
• it follows another keyword (except case, for, and in), or
• it is a non-first token of a command and is supposed to be a keyword to compose a composite command.
If a token begins with #, then the # and any following characters up to the end of the line are treated
as a comment, which is completely ignored in syntax parsing.
Quotations
If you want whitespaces, separator characters, or keywords described above to be treated as a normal
characters, you must quote the characters using appropriate quotation marks. Quotation marks are not
treated as normal characters unless they are themselves quoted. You can use the following three quotation
marks:
• A backslash (\) quotes a character that immediately follows.
The only exception about a backslash is the case where a backslash is followed by a newline. In this
case, the two characters are treated as a line continuation rather than a newline being quoted. The
two characters are removed from the input and the two lines surrounding the line continuation are
concatenated into a single line.
• A pair of single-quotation marks (') quote any characters between them except another
single-quotation. Note that newlines can be quoted using single-quotations.
• Double-quotation marks (") are like single-quotations, but they have a few exceptions: Parameter
expansion, command substitution, and arithmetic expansion are interpreted as usual even between
double-quotations. A backslash between double-quotations is treated as a quotation mark only when it
is followed by $, `, ", \, or a newline; other backslashes are treated as normal characters.
Aliases
Tokens that compose a command are subject to alias substitution. A token that matches the name of an
alias that has already been defined is substituted with the value of the alias before the command is
parsed.
Tokens that contain quotations are not alias-substituted since an alias name cannot contain quotation
marks. Keywords and command separator characters are not alias-substituted either.
There are two kinds of aliases: normal aliases and global aliases. A normal alias can only substitute the
first token of a command while a global alias can substitute any part of a command. Global aliases are
yash extension that is not defined in POSIX.
If a token is alias-substituted with the value of a normal alias that ends with a whitespace, the next
token is exceptionally subject to alias substitution for normal aliases.
The results of alias substitution are again subject to alias substitution for other aliases (but not for
the aliases that have been already applied).
You can define aliases using the alias built-in and remove using the unalias built-in.
Simple commands
A command that does not start with a keyword token is a simple command. Simple commands are executed as
defined in Execution of simple commands.
If the first and any number of following tokens of a simple command have the form name=value, they are
interpreted as variable assignments. A variable name must consist of one or more alphabets, digits and/or
underlines (_) and must not start with a digit. The first token that is not a variable assignment is
considered as a command name and all the following tokens (whether or not they have the form name=value)
as command arguments.
A variable assignment of the form var=(tokens) is interpreted as assignment to an array. You can write
any number of tokens between a pair of parentheses. Tokens can be separated by not only spaces and tabs
but also newlines.
Pipelines
A pipeline is a sequence of one or more simple commands, compound commands, and/or function definitions
that are separated by |.
A pipeline that has more than one subcommand is executed by executing each subcommand of the pipeline in
a subshell simultaneously. The standard output of each subcommand except the last one is redirected to
the standard input of the next subcommand. The standard input of the first subcommand and the standard
output of the last subcommand are not redirected.
The exit status of the pipeline is that of the last subcommand unless the pipe-fail option is enabled, in
which case the exit status of the pipeline is that of the last subcommand that exits with a non-zero exit
status. If all the subcommands exit with an exit status of zero, the exit status of the pipeline is also
zero.
A pipeline can be prefixed by !, in which case the exit status of the pipeline is reversed: the exit
status of the pipeline is 1 if that of the last subcommand is 0, and 0 otherwise.
Korn shell treats a word of the form !(...) as an extended pathname expansion pattern that is not defined
in POSIX. In the POSIXly-correct mode, the tokens ! and ( must be separated by one or more white spaces.
Note
When the execution of a pipeline finishes, at least the execution of the last subcommand has finished
since the exit status of the last subcommand defines that of the whole pipeline. The execution of
other subcommands, however, may not have finished then. On the other hand, the execution of the
pipeline may not finish soon after that of the last subcommand finished because the shell may choose
to wait for the execution of other subcommands to finish.
Note
The POSIX standard allows executing any of subcommands in the current shell rather than subshells,
though yash does not do so.
And/or lists
An and/or list is a sequence of one or more pipelines separated by && or ||.
An and/or list is executed by executing some of the pipelines conditionally. The first pipeline is always
executed. The other pipelines are either executed or not executed according to the exit status of the
previous pipelines.
• If two pipelines are separated by && and the exit status of the first pipeline is zero, the second
pipeline is executed.
• If two pipelines are separated by || and the exit status of the first pipeline is not zero, the
second pipeline is executed.
• In other cases, the execution of the and/or list ends: the second and any remaining pipelines are not
executed.
The exit status of an and/or list is that of the last pipeline that was executed.
Normally, an and/or list must be terminated by a semicolon, ampersand, or newline. See Command separators
and asynchronous commands.
Command separators and asynchronous commands
The whole input to the shell must be composed of any number of and/or lists separated by a semicolon or
ampersand. A terminating semicolon can be omitted if it is followed by ;;, ), or a newline. Otherwise, an
and/or list must be terminated by a semicolon or ampersand.
If an and/or list is terminated by a semicolon, it is executed synchronously: the shell waits for the
and/or list to finish before executing the next and/or list. If an and/or list is terminated by an
ampersand, it is executed asynchronously: after the execution of the and/or list is started, the next
and/or list is executed immediately. An asynchronous and/or list is always executed in a subshell and its
exit status is zero.
If the shell is not doing job control, the standard input of an asynchronous and/or list is automatically
redirected to /dev/null. Signal handlers of the and/or list for the SIGINT and SIGQUIT signals are set to
“ignore” the signal so that the execution of the and/or list cannot be stopped by those signals.
When the execution of an asynchronous and/or list is started, the shell remembers its process ID. You can
obtain the ID by referencing the ! special parameter. You can obtain the current and exit status of the
asynchronous list as well by using the jobs and wait built-ins.
Compound commands
Compound commands provide you with programmatic control of shell command execution.
Grouping
A grouping is a list of commands that is treated as a simple command.
Normal grouping syntax
{ command...; }
Subshell grouping syntax
(command...)
The { and } tokens are keywords, which must be separated from other tokens. The ( and ) tokens,
however, are special separators that need not to be separated.
In the normal grouping syntax, the commands in a grouping are executed in the current shell. In the
subshell grouping syntax, the commands are executed in a new subshell.
In the POSIXly-correct mode, a grouping must contain at least one command. If the shell is not in the
POSIXly-correct mode, a grouping may contain no commands.
The exit status of a grouping is that of the last command in the grouping. If the grouping contains
no commands, its exit status is that of the last executed command before the grouping.
If command
The if command performs a conditional branch.
Basic if command syntax
if condition...; then body...; fi
Syntax with the else clause
if condition...; then body...; else body...; fi
Syntax with the elif clause
if condition...; then body...; elif condition...; then body...; fi
Syntax with the elif clause
if condition...; then body...; elif condition...; then body...; else body...; fi
For all the syntaxes, the execution of an if command starts with the execution of the condition
commands that follows the if token. If the exit status of the condition commands is zero, the
condition is considered as “true”. In this case, the body commands that follows the then token are
executed and the execution of the if command finishes. If the exit status of the condition commands
is non-zero, the condition is considered as “false”. In this case, the condition commands for the
next elif clause are executed and the exit status is tested in the same manner as above. If there is
no elif clause, the body commands that follow the else token are executed and the execution of the if
command finishes. If there is no else clause either, the execution of the if command just ends.
An if command may have more than one elif-then clause.
The exit status of an if command is that of the body commands that were executed. The exit status is
zero if no body commands were executed, that is, all the conditions were false and there was no else
clause.
While and until loops
The while loop and until loop are simple loops with condition.
While loop syntax
while condition...; do body...; done
Until loop syntax
until condition...; do body...; done
If the shell is not in the POSIXly-correct mode, you can omit the condition and/or body commands of a
while/until loop.
The execution of a while loop is started by executing the condition commands. If the exit status of
the condition commands is zero, the shell executes the body commands and returns to the execution of
the condition commands. The condition and body commands are repeatedly executed until the exit status
of the condition commands is non-zero.
Note
The body commands are not executed at all if the first execution of the condition commands yields
a non-zero exit status.
An until loop is executed in the same manner as a while loop except that the condition to repeat the
loop is reversed: the body commands are executed when the exit status of the condition commands is
non-zero.
The exit status of a while/until loop is that of the last executed body command. The exit status is
zero if the body commands are empty or were not executed at all.
For loop
The for loop repeats commands with a variable assigned one of given values in each round.
For loop syntax
for varname in word...; do command...; done
for varname do command...; done
The word list after the in token may be empty, but the semicolon (or newline) before the do token is
required even in that case. The words are not treated as keywords, but you need to quote separator
characters (such as & and |) to include them as part of a word. The command list may be empty if not
in the POSIXly-correct mode.
The varname must be a portable (ASCII-only) name in the POSIXly-correct mode.
The execution of a for loop is started by expanding the words in the same manner as in the execution
of a simple command. If the in and word tokens are omitted, the shell assumes the word tokens to be
"$@". Next, the following steps are taken for each word expanded (in the order the words were
expanded):
1. Assign the word to the variable whose name is varname.
2. Execute the commands.
By default, if a for loop is executed within a function, varname is created as a local variable, even
if it already exists globally. Turning off the for-local shell option or enabling the POSIXly-correct
mode mode will disable this behavior.
If the expansion of the words yields no words, no variable is created and the commands are not
executed at all.
The exit status of a for loop is that of the last executed command. The exit status is zero if the
commands are not empty and not executed at all. If the commands are empty, the exit status is that of
the last executed command before the for loop.
If the variable is read-only, the execution of the for loop is interrupted and the exit status will
be non-zero.
Case command
The case command performs a pattern matching to select commands to execute.
Case command syntax
case word in caseitem... esac
Case item syntax
(patterns) command...;;
The word between the case and in tokens must be exactly one word. The word is not treated as a
keyword, but you need to quote separator characters (such as & and |) to include them as part of the
word. Between the in and esac tokens you can put any number of case items (may be none). You can omit
the first ( token of a case item and the last ;; token before the esac token. If the last command of
a case item is terminated by a semicolon, you can omit the semicolon as well. The commands in a case
item may be empty.
The patterns in a case item are one or more tokens each separated by a | token.
The execution of a case command starts with subjecting the word to the four expansions. Next, the
following steps are taken for each case item (in the order of appearance):
1. For each word in the patterns, expand the word in the same manner as the word and test if the
expanded pattern matches the expanded word. (If a pattern is found that matches the word, the
remaining patterns are not expanded nor tested, so some of the patterns may not be expanded. Yash
expands and tests the patterns in the order of appearance, but it may not be the case for other
shells.)
2. If one of the patterns was found to match the word in the previous step, the commands in this
case item are executed and the execution of the whole case item ends. Otherwise, proceed to the
next case item.
The exit status of a case command is that of the commands executed. The exit status is zero if no
commands were executed, that is, there were no case items, no matching pattern was found, or no
commands were associated with the matching pattern.
In the POSIXly-correct mode, the first pattern in a case item cannot be esac (even if you do not omit
the ( token).
Double-bracket command
The double-bracket command is a syntactic construct that works similarly to the test built-in. It
expands and evaluates the words between the brackets.
Double-bracket command syntax
[[ expression ]]
The expression can be a single primary or combination of primaries and operators. The expression
syntax is parsed when the command is parsed, not executed. Operators (either primary or non-primary)
must not be quoted, or it will be parsed as a normal word.
When the command is executed, operand words are subjected to the four expansions, but not brace
expansion, field splitting, or pathname expansion.
In the double-bracket command, the following primaries from the test built-in can be used:
Unary primaries
-b, -c, -d, -e, -f, -G, -g, -h, -k, -L, -N, -n, -O, -o, -p, -r, -S, -s, -t, -u, -w, -x, -z
Binary primaries
-ef, -eq, -ge, -gt, -le, -lt, -ne, -nt, -ot, -veq, -vge, -vgt, -vle, -vlt, -vne, ===, !==, =~, <,
>
Additionally, some binary primaries can be used to compare strings, which works slightly differently
from those for the test built-in: The = primary treats the right-hand-side operand word as a pattern
and tests if it matches the left-hand-side operand word. The == primary is the same as =. The !=
primary is negation of the = primary (reverse result).
The operand word of a primary must be quoted if it is ]] or can be confused with another primary
operator.
Note
More primaries may be added in future versions of the shell. You should quote any words that
start with a hyphen.
Note
The <= and >= binary primaries cannot be used in the double-bracket command because it cannot be
parsed correctly in the shell grammar.
The following operands (listed in the descending order of precedence) can be used to combine
primaries:
( expression )
A pair of parentheses change operator precedence.
! expression
An exclamation mark negates (reverses) the result.
expression && expression
A double ampersand represents logical conjugation (the “and” operation). The entire expression is
true if and only if the operand expressions are both true. The left-hand-side expression is first
expanded and tested. The right-hand-side is expanded only if the left-hand-side is true.
expression || expression
A double vertical line represents logical conjugation (the “or” operation). The entire expression
is false if and only if the operand expressions are both false. The left-hand-side expression is
first expanded and tested. The right-hand-side is expanded only if the left-hand-side is false.
Note
Unlike the test built-in, neither -a nor -o can be used as a binary operator in the
double-bracket command.
The exit status of the double-bracket command is 0 if expression is true, 1 if false, and 2 if it
cannot be evaluated because of expansion error or any other reasons.
Note
The double-bracket command is also supported in bash, ksh, mksh, and zsh, but not defined in the
POSIX standard. The behavior slightly differs between the shells. The test built-in should be
preferred over the double-bracket command for maximum portability.
Function definition
The function definition command defines a function.
Function definition syntax
funcname ( ) compound_command
function funcname compound_command
function funcname ( ) compound_command
In the first syntax without the function keyword, funcname cannot contain any special characters such as
semicolons and quotation marks. In the second and third syntax, which cannot be used in the
POSIXly-correct mode, funcname is subjected to the four expansions when executed. In the POSIXly-correct
mode, funcname is limited to a portable (ASCII-only) name.
When a function definition command is executed, a function whose name is funcname is defined with its
body being compound_command.
A function definition command cannot be directly redirected. Any redirections that follow a function
definition are associated with compound_command rather than the whole function definition command. In
func() { cat; } >/dev/null, for example, it is not func() { cat; } but { cat; } that is redirected.
The exit status of a function definition is zero if the function was defined without errors, and non-zero
otherwise.
PARAMETERS AND VARIABLES
Parameters are string values that are expanded in parameter expansion. There are three types of
parameters: positional parameters, special parameters and variables.
Positional parameters
Positional parameters are parameters that are identified by natural numbers. If there are three
positional parameters, for example, they are identified as 1, 2, and 3. You can obtain the number of
positional parameters by the # special parameter. The * and @ special parameters are expanded to all
positional parameters.
Positional parameters are initialized from the shell’s command line arguments when the shell is started
(see Command line arguments). In the initialization, the order of the operands are preserved as the order
of the positional parameters.
When the shell executes a function call, positional parameters are changed to the arguments to the
function call so that you can access the arguments while the function is being executed. Positional
parameters are restored to the original values when the execution of the function is finished.
Positional parameters can be manipulated by built-in commands like set and shift.
Note that 0 is not a positional parameter but a special parameter.
Special parameters
Special parameters are parameters each identified by a single symbol. They cannot be directly assigned to
by the user.
Yash provides the following special parameters:
0
The name of the shell executable file or the script file that was specified in the invocation of the
shell.
#
The number of current positional parameters. The value is a non-negative integer.
$
The process ID of the shell. The value is a positive integer and is never changed even in subshells.
-
Currently enabled shell options. The value is a concatenation of alphabet characters that are the
names of currently enabled single-character options that can be specified in shell invocation. The
value reflects changes of enabled options when you enable or disable options using the set built-in.
?
The exit status of the last executed pipeline. The value is a non-negative integer.
!
The process ID of the last executed asynchronous list.
*
This special parameter represents the whole positional parameters. When there is no positional
parameters, the value of this special parameter is the empty string. When there is more than one
positional parameter, the value is a concatenation of all the positional parameters, each of which is
separated as follows:
• If the IFS variable exists and its value is not empty, positional parameters are each separated
by the first character of the value of the IFS variable.
• If the IFS variable exists and has an empty value, positional parameters are just concatenated
without any separator.
• If the IFS variable does not exist, positional parameters are each separated by a space
character.
If field-splitting is applied to an expansion result of this parameter, the value is first split into
the original positional parameters and then further split depending on the current IFS variable. The
first splitting is performed even if the IFS variable is empty.
@
This special parameter represents the whole positional parameters like the * special parameter above.
The difference between the two is the results of expansion that occurs between a pair of
double-quotation marks. If the @ special parameter is expanded inside double-quotations, the result
is field-split into the exact positional parameter values. If there are no positional parameters, the
expansion yields no word rather than an empty word. (Even if the expansion is double-quoted, the
result is not always a single word.)
• When there are no positional parameters, the command words echo 1 "$@" 2 are expanded to the
three words echo, 1, and 2.
• When positional parameters are the three words 1, 2 2, and 3, the command words echo "$@" are
expanded to the four words echo, 1, 2 2, and 3, and the words echo "a$@b" to the four words echo,
a1, 2 2, and 3b.
Variables
Variables are parameters the user can assign values to. Each variable has a name that identifies it and a
value that defines the results of expansion.
A variable name is composed of one or more alphanumeric characters and underscores (_). A name cannot
start with a digit. Other characters may be used in a name depending on internationalization support of
your environment.
Variables that are exported to external commands are called environment variables. They are passed to all
external commands the shell invokes. Variables passed to the shell in invocation will be automatically
exported.
You can assign to variables by a simple command as well as the typeset built-in. You can remove variables
by using the unset built-in.
Variables used by the shell
The following variables are used by the shell for special purposes.
CDPATH
This variable is used by the cd built-in to find a destination directory.
COLUMNS
This variable specifies the width (the number of character columns) of the terminal screen. The
value affects the display of line-editing.
COMMAND_NOT_FOUND_HANDLER
When the shell cannot find a command to be executed, the value of this variable is interpreted
and executed instead. You can override the shell’s error handling behavior with this variable.
See Execution of simple commands for detail.
This feature is disabled in the POSIXly-correct mode.
DIRSTACK
This array variable is used by the shell to store the directory stack contents. If you modify the
value of this variable, the directory stack may be corrupted.
ECHO_STYLE
This variable specifies the behavior of the echo built-in.
ENV
When an interactive shell is started in the POSIXly-correct mode, the value of this variable is
used to find the initialization file. See Initialization of yash.
FCEDIT
This variable specifies an editor program used to edit command lines during execution of the fc
built-in.
HANDLED
This variable can be set in the command-not-found handler to tell the shell not to produce a
further error message. See Execution of simple commands for detail.
HISTFILE
This variable specifies the pathname of the file to save the command history in.
HISTRMDUP
This variable specifies the number of command history items to be checked for duplication. When
the shell is adding a new history item to the command history, if some of the most recent n items
have the same contents as the new one, then the duplicate existing items are removed from the
history before the new one is added, where n is the value of this variable.
If the value of this variable is 1, for example, the most recent item is removed when a new item
that have the same contents is added.
Items older than the nth recent item are not removed. No items are removed if the value of this
variable is 0. All items are subject to removal if the variable value is greater than or equal to
the value of the HISTSIZE variable.
HISTSIZE
This variable specifies the maximum number of items in the command history.
HOME
This variable specifies the pathname of the user’s home directory and affects results of tilde
expansion and cd built-in.
IFS
This variable specifies separators used in field splitting. The variable value is initialized to
the three characters of a space, a tab, and a newline when the shell is started.
LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME
These variables specify a locale in which the shell runs. The shell chooses the file input/output
encoding, the error message language, etc. according to the locale specified.
Unless the shell is interactive and not in the POSIXly-correct mode, the value of the LC_CTYPE
variable is considered only when the shell is started. Once the shell has been initialized,
changing the value of LC_CTYPE will have no effect on the shell’s behavior.
LINENO
The value of this variable is automatically set to the line number in which the currently
executed command appears in the file.
In the interactive shell, the line number is reset to 1 each time the shell reads and executes a
command.
If you assign to or remove this variable, it will no longer provide line numbers.
LINES
This variable specifies the height (the number of character lines) of the terminal screen. The
value affects the display of line-editing.
MAIL
This variable specifies the pathname of a file that is checked in mail checking.
MAILCHECK
This variable specifies how often the shell should do mail checking. The value has to be
specified as a positive integer in seconds. The value is initialized to the default value of 600
when the shell is started.
MAILPATH
This variable specifies the pathnames of files that are checked in mail checking.
NLSPATH
The POSIX standard prescribes that the value of this variable specifies pathname templates of
locale-dependent message data files, but yash does not use it.
OLDPWD
This variable is set to the previous working directory path when you change the working directory
by using the cd or other built-ins. This variable is exported by default.
OPTARG
When the getopts built-in parses an option that takes an argument, the argument value is assigned
to this variable.
OPTIND
The value of this variable specifies the index of an option that is to be parsed by the next
getopts built-in execution. This variable is initialized to 1 when the shell is started.
PATH
This variable specifies paths that are searched for a command in command search.
PPID
The value of this variable is the process ID of the shell’s parent process, which is a positive
integer. This variable is initialized when the shell is started. The value is not changed when
the shell makes a new subshell.
PROMPT_COMMAND
The shell interprets and executes the value of this variable before printing each command prompt
if the shell is interactive and not in the POSIXly-correct mode. This behavior is equivalent to
executing the command eval -i -- "${PROMPT_COMMAND-}" before each command prompt, but its exit
status does not affect the expansion of the ? special parameter in the next command.
PS1
This variable specifies the main command prompt string printed by an interactive shell. See
Prompts for the format of the variable value. The value is initialized to either $ or # depending
on whether the effective user ID of the shell process is zero or not.
PS1R
This variable specifies the auxiliary prompt string printed to the right of the cursor when you
input a command line to an interactive shell. See Prompts for the format of the variable value.
PS1S
This variable specifies the font style of command strings you enter to an interactive shell. See
Prompts for the format of the variable value.
PS2
This variable is like the PS1 variable, but it is used for the second and following lines of a
command that is longer than one line. See Prompts for the format of the variable value. The value
is initialized to > when the shell is started.
PS2R
This variable is like the PS1R variable, but it is used when PS2 is used. See Prompts for the
format of the variable value.
PS2S
This variable is like the PS1S variable, but it is used when PS2 is used. See Prompts for the
format of the variable value.
PS4
The value of this variable is printed before each command trace output when the xtrace option is
enabled. The value is subject to parameter expansion, command substitution, arithmetic expansion.
You can also use backslash notations if the shell is not in the POSIXly-correct mode. The value
is initialized to + when the shell is started.
PS4S
This variable is like the PS1S variable, but it is used when PS4 is used. You can use this
variable to modify font style of command trace output.
PWD
The value of this variable is the pathname of the current working directory. The value is set
when the shell is started and reset each time the working directory is changed by the cd or other
built-ins. This variable is exported by default.
RANDOM
You can use this variable to get random numbers. The value of this variable is a uniformly
distributed random integer between 0 and 32767 (inclusive). You will get a different number each
time the variable is expanded.
You can set the “seed” of random numbers by assigning a non-negative integer to the variable.
If you remove this variable, it will no longer work as a random number generator. If the shell
was invoked in the POSIXly-correct mode, this variable does not work as a random number
generator.
TERM
This variable specifies the type of the terminal in which the shell is running. The value affects
the behavior of line-editing. This variable has to be exported to take effect.
YASH_AFTER_CD
The shell interprets and executes the value of this variable after each time the shell’s working
directory is changed by the cd or other built-ins. This behavior is equivalent to executing the
command eval -i -- "${YASH_AFTER_CD-}" after the directory was changed.
YASH_LOADPATH
This variable specifies directories the dot built-in searches for a script file. More than one
directory can be specified by separating them by colons like the PATH variable. When the shell is
started, this variable is initialized to the pathname of the directory where common script files
are installed.
YASH_LE_TIMEOUT
This variable specifies how long the shell should wait for a next possible input from the
terminal when it encountered an ambiguous control sequence while line-editing. The value must be
specified in milliseconds. If you do not define this variable, the default value of 100
milliseconds is assumed.
YASH_PS1, YASH_PS1R, YASH_PS1S, YASH_PS2, YASH_PS2R, YASH_PS2S, YASH_PS4, YASH_PS4S
When not in the POSIXly-correct mode, if any of these variables is defined, it takes precedence
over the corresponding variable without the YASH_ prefix in the name (e.g. PS1). These variables
are ignored in the POSIXly-correct mode. You should define them to include yash-specific
notations in the prompt, so that unhandled notations do not mangle the prompt in the
POSIXly-correct mode.
YASH_VERSION
The value is initialized to the version number of the shell when the shell is started.
Arrays
An array is a variable that contains zero or more strings. The string values of an array are
identified by natural numbers (like positional parameters).
You can assign values to an array by using a simple command as well as the array built-in. You can
use the unset built-in to remove arrays.
Arrays cannot be exported as arrays. When an array is exported, it is treated as a normal variable
whose value is a concatenation of all the array values, each separated by a colon.
Arrays are not supported in the POSIXly-correct mode.
WORD EXPANSIONS
Word expansion is substitution of part of a word with another particular string. There are seven types of
word expansions:
1. Tilde expansion
2. Parameter expansion
3. Command substitution
4. Arithmetic expansion
5. Brace expansion
6. Field splitting
7. Pathname expansion (globbing)
These types of expansions are performed in the order specified above.
Tilde expansion, parameter expansion, command substitution, and arithmetic expansion are called the four
expansions.
Tilde expansion
In tilde expansion, parts of words that start with a tilde (~) are substituted with particular pathnames.
The part of each word that gets substituted is from the beginning of the word, which is a tilde, up to
(but not including) the first slash (/) in the word. If the word does not contain a slash, the whole word
is substituted. If any character in the substituted part is quoted, tilde expansion is not performed on
the word.
The results of expansion are determined by the format of the substituted part:
~
A single tilde is substituted with the value of the HOME variable.
~username
A tilde followed by a user name is substituted with the pathname of the user’s home directory.
~+
~+ is substituted with the value of the PWD variable.
~-
~- is substituted with the value of the OLDPWD variable.
~+n, ~-n
where n is a non-negative integer. This type of tilde expansion yields the pathname of a directory of
which ~+n or ~-n is the index in the directory stack.
When tilde expansion is performed on the value of a variable assignment that occurs during execution of a
simple command, the value is considered as a colon-separated list of words and those words are each
subject to tilde expansion. For example, the variable assignment
VAR=~/a:~/b:~/c
is equivalent to
VAR=/home/foo/a:/home/foo/b:/home/foo/c
if the value of HOME variable is /home/foo.
The POSIX standard does not prescribe how the shell should behave when it encounters an error during
tilde expansion (e.g., when the HOME variable is not defined). Yash silently ignores any errors during
tilde expansion; the part of the word that would be substituted is left intact.
In the POSIXly-correct mode, tilde expansion supports the formats of ~ and ~username only.
Parameter expansion
Parameter expansion expands to the value of a parameter.
The syntax of typical, simple parameter expansion is ${parameter}, which expands to the value of the
parameter whose name is parameter. You can omit the braces (e.g., $parameter) if
• parameter is a special parameter,
• parameter is a positional parameter whose index is a one-digit integer, or
• parameter is a variable and the parameter expansion is not followed by a character that can be used
as part of a variable name. For example, ${path}-name is equivalent to $path-name, but ${path}name
and $pathname are different.
If parameter is none of a special parameter, positional parameter, and variable, it is a syntax error.
(Some shells other than yash may treat such a case as an expansion error.)
If the unset option is disabled and the parameter is an undefined variable, it is an expansion error. If
the unset option is enabled, an undefined variable expands to the empty string.
More complex syntax of parameter expansion allows modifying the value of a parameter.
Parameter expansion
${ prefix parameter index modifier }
The spaces in the syntax definition above are for readability only and must be omitted. You can omit
prefix, index, and/or modifier.
Prefix
The prefix, if any, must be a hash sign (#). If a parameter expansion has the prefix, the result of
expansion is the number of characters in the value this expansion would be expanded to without the
prefix.
Parameter name
The parameter name (parameter) must be either
• a name of a special parameter, positional parameter, or variable; or
• another parameter expansion, command substitution, or arithmetic expansion.
The parameter expansion is expanded to the value of the parameter. If parameter is an array variable,
the values of the array are field-split like the @ special parameter unless the index [*] is
specified.
If parameter is another expansion, it is called a nested expansion. Nested expansion cannot be used
in the POSIXly-correct mode. The braces ({ }) of a nested parameter expansion cannot be omitted.
Index.sp An index allows extracting part of the parameter value (or some of array values).
Index
[word1]
[word1,word2]
where word1 and word2 are parsed in the same manner as normal tokens except that they are always
delimited by , or ] and can contain whitespace characters.
If there is an index in a parameter expansion, it is interpreted as follows:
1. Words word1 and word2 are subjected to parameter expansion, command substitution, and arithmetic
expansion.
2. If there is no word2 and if word1 expands to one of *, @, and #, then that is the interpretation of
index and the next step is not taken.
3. The results of the previous steps (the expanded word1 and word2) are interpreted and evaluated as an
arithmetic expression in the same manner as in arithmetic expansion. The resulting integers are the
interpretation of index. If the results are not integers, it is an expansion error. If there is no
word2, it is assumed that word2 is equal to word1.
If parameter is an array variable, the index specifies the part of the array. If parameter is either the
* or @ special parameter, the index specifies the index range of positional parameters. In other cases,
the index specifies the index range of a substring of the parameter value that is being expanded. In all
cases, the specified range of the array values, positional parameters, or parameter value remains in the
results of the expansion and other values are dropped.
If the interpretation of index is one or two integers, the following rules apply:
• If the interpreted index value is negative, it wraps around. For example, the index value of -1
corresponds to the last value/character.
• It is not an error when the index value is out of range. Existing values/characters within the range
are just selected.
• If the interpretation of either word1 or word2 is 0, the range is assumed empty and the expansion
results in nothing.
If the interpretation of index is one of *, @, and #, it is treated as follows:
*
If parameter is an array, all the array values are field-split or concatenated in the same manner as
the * special parameter. If parameter is the * or @ special parameter, the positional parameters are
likewise field-split or concatenated. In other cases, the interpretation of index is treated as if
the interpretation is the two integers 1 and -1.
@
The interpretation of index is treated as if the interpretation is the two integers 1 and -1.
#
The interpretation of the # index is special in that it does not simply specify a range. Instead, the
expanded values are substituted with the count.
If parameter is an array, the result of this parameter expansion will be the number of values in the
array being expanded. If parameter is the * or @ special parameter, the result will be the number of
current positional parameters. Otherwise, the result will be the number of characters in the value
that is being expanded.
If a parameter expansion does not contain an index, it is assumed to be [@]. In the POSIXly-correct mode,
index cannot be specified.
Example 1. Expansion of a normal variable
The following commands will print the string ABC:
var='123ABC789'
echo "${var[4,6]}"
Example 2. Expansion of positional parameters
The following commands will print the string 2 3 4:
set 1 2 3 4 5
echo "${*[2,-2]}"
Example 3. Expansion of an array
The following commands will print the string 2 3 4:
array=(1 2 3 4 5)
echo "${array[2,-2]}"
Modifier
You can modify the value to be expanded by using modifiers:
-word
If the parameter name (parameter) is an undefined variable, the parameter expansion is expanded
to word. It is not treated as an error if the unset option is disabled.
+word
If the parameter name (parameter) is an existing variable, the parameter expansion is expanded to
word. It is not treated as an error if the unset option is disabled.
=word
If the parameter name (parameter) is an undefined variable, word is assigned to the variable and
the parameter expansion is expanded to word. It is not treated as an error if the unset option is
disabled.
?word
If the parameter name (parameter) is an undefined variable, word is printed as an error message
to the standard error. If word is empty, the default error message is printed instead.
:-word, :+word, :=word, :?word
These are similar to the four types of modifiers above. The only difference is that, if parameter
exists and has an empty value, it is also treated as an undefined variable.
#word
The shell performs pattern matching against the value that is being expanded, using word as a
pattern. If word matches the beginning of the value, the matching part is removed from the value
and the other part remains as expansion results. The shortest matching is used if more than one
matching is possible.
##word
This is similar to #word above. The only difference is that the longest matching is used if more
than one matching is possible.
%word
This is similar to #word above. The only difference is that matching is tried at the end of the
value rather than at the beginning: if word matches the end of the value, the matching part is
removed from the value and the other part remains as expansion results.
%%word
This is similar to %word above. The only difference is that the longest matching is used if more
than one matching is possible.
/word1/word2
The shell performs pattern matching against the value that is being expanded, using word1 as a
pattern. If word1 matches any part of the value, the matching part is replaced with word2 and the
whole value after the replacement remains as expansion results. If word1 matches more than one
part of the value, only the first part is replaced. The shortest matching is replaced if more
than one matching is possible for the same starting point in the value.
This modifier cannot be used in the POSIXly-correct mode.
/#word1/word2
This is similar to /word1/word2 above. The only difference is that word1 matches only at the
beginning of the value being expanded.
/%word1/word2
This is similar to /word1/word2 above. The only difference is that word1 matches only at the end
of the value being expanded.
//word1/word2
This is similar to /word1/word2 above. The only difference is that all matched parts are replaced
if word1 matches more than one part of the value.
:/word1/word2
This is similar to /word1/word2 above. The only difference is that the value is replaced only
when word1 matches the whole value.
In all types of modifiers above, words are subjected to the four expansions when (and only when) they
are used.
If parameter is an array variable or the @ or * special parameter, modifiers affect each value of the
array or all positional parameters.
Command substitution
Command substitution expands to output of commands specified.
Command substitution
$(commands)
`commands`
When command substitution is evaluated, commands are executed by a subshell with output pipelined to the
shell. When the commands finished, command substitution is substituted with the output of the commands.
Any trailing newline characters in the output are ignored.
When command substitution of the form $(commands) is parsed, the commands are parsed carefully so that
complex commands such as nested command substitution are parsed correctly. If commands start with (, you
should put a space before commands so that the whole command substitution is not confused with arithmetic
expansion. If the shell is in the POSIXly-correctly mode, the commands are parsed each time the command
substitution is expanded; otherwise, commands are parsed only when the command substitution is parsed.
If command substitution is of the form `commands`, the commands are not parsed when the command
substitution is parsed; the commands are parsed each time the command substitution is expanded. The end
of commands is detected by the first backquote character (`) after the beginning of commands that is not
quoted by a backslash. Backquotes that are part of commands (typically used for nested command
substitution) must be quoted by backslashes. In commands, backslashes are treated as quotes only when
preceding a dollar ($), backquote, newline, or another backslash. Additionally, if the command
substitution occurs inside double quotes, double quotes in commands must be quoted with a backslash.
Those backslashes are removed before commands are parsed.
Arithmetic expansion
Arithmetic expansion evaluates an arithmetic expression and expands to the value of the expression.
Arithmetic expansion
$((expression))
When arithmetic expansion is expanded, the expression is subject to parameter expansion, command
substitution, and (nested) arithmetic expansion. The expression is parsed in (almost) same manner as an
expression of the C programming language.
Yash allows an expression to be either an integer (of the long type in C) or a floating-point number (of
the double type in C). An operation on integers yields an integer and an operation involving a
floating-point number yields a floating-point number. In the POSIXly-correct mode, you can use integers
only.
The following operators are available (in the order of precedence):
1. ( )
2. ++ -- (postfix operators)
3. ++ -- + - ~ ! (prefix operators)
4. * / %
5. + - (binary operators)
6. << >>
7. < <= > >=
8. == !=
9. &
10. ^
11. |
12. &&
13. ||
14. ? :
15. = *= /= %= += -= <<= >>= &= ^= |=
The ++ and -- operators cannot be used in the POSIXly-correct mode.
An atomic expression can be one of an integer literal, a floating-point number literal, and a variable.
Literals are parsed in the same manner as in C. An octal integer literal starts with 0, and hexadecimal
with 0x. A floating-point number literal may have an exponent (i.e. 1.23e+6). A variable with a
non-numeric value will result in an error when parsed as a number. An unset variable is treated as a
value of zero if the unset option is enabled.
In the POSIXly-correct mode, variables are always parsed as numbers. Otherwise, variables are parsed only
when they are used as numbers in computation. Unparsed variables are left intact.
set +o posixly-correct
foo=bar
echo $((0 ? foo : foo)) # prints "bar"
echo $((foo + 0)) # error
Brace expansion
Brace expansion expands to several split words with preceding and succeeding portions duplicated to each
split words. Brace expansion is expanded only when the brace-expand option is enabled.
Comma-separated brace expansion
{word1,word2,...,wordn}
Range brace expansion
{start..end}
{start..end..delta}
Comma-separated brace expansion is expanded to each comma-separated word. For example, a{1,2,3}b is
expanded to the three words a1b, a2b, and a3b.
Range brace expansion is expanded to integers in the range defined by start and end. The difference
between each integer can be defined by delta. If start is larger than end, the results will be in
descending order. When ..delta is omitted, it defaults to 1 or -1. For example, a{1..3}b is expanded to
the three words a1b, a2b, and a3b; and a{1..7..2}b to the four words a1b, a3b, a5b, and a7b.
Multiple brace expansions can be used in one word. Brace expansions can also be nested. You can quote
braces and/or commas to prevent them from being treated as brace expansion.
Any errors in brace expansion are silently ignored.
Field splitting
In field splitting, words are split at predefined separators.
Field splitting can occur only within parts of words that resulted from parameter expansion, command
substitution, and arithmetic expansion that are not between double-quotation marks. Expansion results of
the @ special parameter are exceptionally split even between double-quotation marks.
Separators used in field splitting are defined by the value of the IFS variable. If the variable does not
exist, the value is assumed to be the three characters of space, tab, and newline.
Characters included in the value of the IFS variable are called IFS characters. IFS characters that are
any of space, tab, and newline are called IFS whitespace and other IFS characters are called IFS
non-whitespace.
Field splitting is performed as follows:
1. The shell searches words for split points. A split point is one or more adjacent IFS characters
within the word portions where field splitting can occur. The following steps are taken for each
split point found.
2. If the split point includes one or more IFS non-whitespaces, all the IFS whitespaces in the split
point are ignored and the word is split at each IFS non-whitespace in the split point.
3. If the split point includes no IFS non-whitespaces, the word is split at the split point unless it is
at the beginning or end of the word.
4. The split points are removed from the results.
Finally, the last word is removed from the results if:
• the empty-last-field option is not enabled;
• the result is more than one word; and
• the last word is empty.
Note
Words are not split at all when the value of the IFS variable is empty.
Pathname expansion
Pathname expansion performs pattern matching and expands to pathnames matched by the pattern.
A word subjected to pathname expansion is treated as a pattern. If one or more pathnames are found that
are matched by the pattern, the pathnames become the results of the pathname expansion.
Pathname expansion is not performed when the glob option is disabled.
The shell searches readable directories for matching pathnames. Unreadable directories are silently
ignored.
The following options affect the behavior of pathname expansion:
null-glob
This option affects the result of pathname expansion when no matching pathnames are found. If
enabled, the result is no word. If disabled, the result is the original pattern word.
case-glob
This option specifies case-sensitivity in matching. If enabled, pattern matching is done
case-sensitively.
dot-glob
This option affects matching of filenames that start with a period (.). If disabled, a period at the
beginning of a filename does not match wildcard patterns (? and *) or bracket expressions. If
enabled, there is no such special treatment of periods.
mark-dirs
If enabled, each resulting pathname that is a directory name is suffixed by a slash (/).
extended-glob
This option enables the extension. (See below)
Any errors in pathname expansion are silently ignored. If the word is an invalid pattern, it just becomes
the result. The results depend on the null-glob option when no matching pathnames are found.
Pattern matching is done for each filename (or pathname component) of pathnames. The shell skips matching
for literal patterns that contain no wildcards or bracket expressions. As a result, the patterns /*/foo
and /*/fo[o] may yield different expansion results when the case-glob option is disabled; for example,
the pattern /*/fo[o] matches the pathname /bar/FOO but the pattern /*/foo does not because matching is
skipped for foo.
Extension in pathname expansion
The following patterns can be used when the extended-glob option is enabled.
**
The directory is searched recursively and the pattern matches any number of directory filenames
(each separated by a slash). Any directory whose name begins with a period is excluded from
search. For example, the pattern dir/**/file can match the pathnames dir/file, dir/foo/file,
dir/a/b/c/file, etc.
This pattern is not effective when appearing at the end of the whole pattern (i.e. foo/bar/**).
.**
This pattern is like **, but all directories are searched including ones with a name starting
with a period.
***
This pattern is like **, but if a symbolic link to a directory is found during recursive search,
the directory is searched recursively as well.
.***
This pattern is like ***, but all directories are searched including ones with a name starting
with a period.
PATTERN MATCHING NOTATION
Pattern matching notation is a syntax of patterns that represent particular sets of strings. When a
string is included in the set of strings a pattern represents, the pattern is said to match the string.
Whether a pattern matches a string or not is defined as follows.
Normal characters
A character that is not quoted or any of special characters defined below is a normal character, which
matches the character itself.
For example, the pattern abc matches the string abc, and not any other strings.
Single-character wildcard
The character ? matches any single character.
For example, the pattern a?c matches any three-character strings that starts with a and ends with c, such
as aac, abc, and a;c.
Multi-character wildcard
The character * matches any strings (of any length, including the empty string).
For example, the pattern a*c matches any string that starts with a and ends with c, such as ac, abc, and
a;xyz;c.
Bracket expression
A pattern that is enclosed by brackets ([ and ]) is a bracket expression. A bracket expression must have
at least one character between the brackets. The characters between the brackets are interpreted as a
bracket expression pattern, which is a below-defined special notation for bracket expression. A bracket
expression pattern represents a set of characters. The bracket expression matches any one of the
characters in the set the bracket expression pattern represents.
If the opening bracket ([) is followed by an exclamation mark (!), the exclamation is not treated as part
of the bracket expression pattern and the whole bracket expression instead matches a character that is
not included in the set the bracket expression pattern represents. If the opening bracket is followed by
a caret (^), it is treated like an exclamation mark as above (but shells other than yash may treat the
caret differently).
If the opening bracket (or the following exclamation or caret, if any) is followed by a closing bracket
(]), it is treated as part of the bracket expression pattern rather than the end of the bracket
expression. You cannot quote characters in the bracket expression pattern because quotation is treated
before bracket expression.
An opening bracket in a pattern is treated as a normal character if it is not the beginning of a valid
bracket expression.
Normal characters (in bracket expression pattern)
A character that is not any of special characters defined below is a normal character, which represents
the character itself.
For example, the bracket expression pattern abc represents the set of the three characters a, b, and c.
The bracket expression [abc] therefore matches any of the three characters.
Range expressions
A hyphen preceded and followed by a character (or collating symbol) is a range expression, which
represents the set of the two characters and all characters between the two in the collation order. A
collation order is an order of characters that is defined in the locale data.
If a hyphen is followed by a closing bracket (]), the bracket is treated as the end of the bracket
expression and the hyphen as a normal character.
For example, the range expression 3-5 represents the set of the three characters 3, 4, and 5. The bracket
expression [3-5-] therefore matches one of the four characters 3, 4, 5, and -.
Collating symbols
A collating symbol allows more than one character to be treated as a single character in matching. A
collating symbol is made up of one or more characters enclosed by the special brackets [. and .].
One or more characters that are treated as a single character in matching are called a collating element.
Precisely, a bracket expression pattern represents a set of collating elements and a bracket expression
matches a collating element rather than a character, but we do not differentiate them for brevity here.
For example, the character combination “ch” was treated as a single character in the traditional Spanish
language. If this character combination is registered as a collating element in the locale data, the
bracket expression [[.ch.]df] matches one of ch, d, and f.
Equivalence classes
An equivalence class represents a set of characters that are considered equivalent. A equivalence class
is made up of a character (or more precisely, a collating element) enclosed by the special brackets [=
and =].
An equivalence class represents the set of characters that consists of the character enclosed by the
brackets and the characters that are in the same primary equivalence class as the enclosed character. The
shell consults the locale data for the definition of equivalence classes in the current locale.
For example, if the six characters a, à, á, â, ã, ä are defined to be in the same primary equivalence
class, the bracket expressions [[=a=]], [[=à=]], and [[=á=]] match one of the six.
Character classes
A character class represents a predefined set of characters. A character class is made up of a class name
enclosed by the special brackets [: and :]. The shell consults the locale data for which class a
character belongs to.
The following character classes can be used in all locales:
[:lower:]
set of lowercase letters
[:upper:]
set of uppercase letters
[:alpha:]
set of letters, including the [:lower:] and [:upper:] classes.
[:digit:]
set of decimal digits
[:xdigit:]
set of hexadecimal digits
[:alnum:]
set of letters and digits, including the [:alpha:] and [:digit:] classes.
[:blank:]
set of blank characters, not including the newline character
[:space:]
set of space characters, including the newline character
[:punct:]
set of punctuations
[:print:]
set of printable characters
[:cntrl:]
set of control characters
For example, the bracket expression [[:lower:][:upper:]] matches a lower or upper case character. In
addition to the classes listed above, other classes may be used depending on the definition of the
current locale.
REDIRECTION
Redirection is a feature you can use to modify file descriptors of commands. By using redirection, you
can execute commands with their standard input/output connected with files or devices other than the
terminal.
You can do redirection by adding redirection operators to a command (simple command or compound command)
In a simple command, redirection operators may appear anywhere in the command as long as operator tokens
are separated from other tokens. In a compound command, redirection operators must appear at the end of
the command.
Redirection operators are processed before the command body is executed. More than one redirection
operator in a command are processed in the order of appearance. Redirection operators affect only the
command in which they appear, except when they appear in an exec built-in without command operands. That
is, file descriptors modified by redirection are restored after the command has finished.
A redirection operator starts with < or >. Redirection operators starting with < affects the standard
input (file descriptor 0) by default. Redirection operators starting with > affects the standard output
(file descriptor 1) by default. To affect another file descriptor, you can prefix a redirection operator
with a non-negative integer; the operator will affect the file descriptor specified by the integer. The
integer must immediately precede the < or > without any whitespaces in between. The integer must not be
quoted, either.
Redirection to files
The most common type of redirection is redirection to files.
Redirection of input
< token
Redirection of output
> token
>| token
>> token
Redirection of input and output
<> token
The token is subject to the four expansions. It is also subject to pathname expansion if the shell is
interactive. The expansion result is treated as the pathname of the file to which redirection is
performed. If the pathname expansion does not result in a single pathname, it is an error.
In redirection of input, the standard input is replaced with a file descriptor which is open for
read-only access to the target file. If the target file cannot be opened for read-only access, it is an
error.
In redirection of output, the standard output is replaced with a file descriptor which is open for
write-only access to the target file. If the target file cannot be opened for write-only access, it is an
error. If the target file does not exist, a new empty file is created and opened. If the target file
already exists, the file is opened as follows:
• For the >| operator, the file is emptied when opened if it is a regular file.
• For the > operator, the behavior is the same as the >| operator if the clobber option is enabled. If
the option is disabled and the file is a regular file, it is treated as an error.
• For the >> operator, the file is opened for appending; any output to the file descriptor is appended
to the end of the file.
In redirection of input and output, the standard input is replaced with a file descriptor which is open
for read-and-write access to the target file. If the file does not exist, a new empty file is created and
opened.
Socket redirection
If the pathname of the target file is of the form /dev/tcp/host/port or /dev/udp/host/port and the
file cannot be opened in the usual manner, a new socket is opened for communication with the port of
the host. The redirection replaces the standard input or output with the file descriptor to the
socket.
A stream socket is opened for the form /dev/tcp/host/port and a datagram socket for the form
/dev/udp/host/port. The protocol actually used for communication is determined by the socket library
the shell uses. Typically, stream sockets use TCP and datagram sockets UDP.
In socket redirection, the file descriptor is both readable and writable regardless of the type of
the redirection operator used.
Socket redirection is yash’s extension that is not defined in POSIX. Bash as well has socket
redirection as extension.
Duplication of file descriptors
Redirection allows duplicating or closing existing file descriptors.
Duplication of file descriptor
<& token
>& token
The token is subject to expansion as in redirection to files, but it is treated as a file descriptor
rather than a pathname. Thus the expanded token must be a non-negative integer.
The <& and >& operators duplicate the file descriptor specified by token to the standard input and
output, respectively. (The operators can be prefixed with a non-negative integer so that the file
descriptor is duplicated to a file descriptor other than the standard input or output.)
If the expanded token is a single hyphen rather than a non-negative integer, the file descriptor is
closed rather than duplicated. By default, the <& and >& operators close the standard input and output,
respectively, but the operators can be prefixed with a non-negative integer so that another file
descriptor is closed.
In the POSIXly-correct mode, a file descriptor must be readable when duplicated by the <& operator and
writable when duplicated by the >& operator.
Here documents and here strings
Here document and here string allow redirection to file descriptors that reads strings directly specified
in shell commands.
Here document
<< token
<<- token
Here string
<<< token
In a here document or here string, the standard input is replaced with a readable file descriptor. When
the command reads from the file descriptor, it will read the contents of the here document/string, which
is defined below.
When a here document operator (<< or <<-) appears in a command, the shell reads the contents of the here
document starting from the next line. The contents of here documents are not parsed nor executed as
commands. The token after the operand specifies a delimiter that indicates the end of the contents. (The
token is not subject to any expansion, but quotation is processed.) The contents of the here document is
terminated just before the first line containing the token only. When using the <<- operator, all tab
characters at the beginning of each line in the here document contents are removed and the delimiter
token may be preceded by tab characters.
If there are more than one here document operator on one line, the contents of the here documents are
parsed in order: The contents of the first here document starts from the next line and ends before the
first line containing the token that followed the first operator. Just after that line, the contents of
the second here document starts, and so on.
The contents of here documents are treated literally: whitespaces, tabs, etc. remain as is. The exception
is that, when the token is not quoted at all:
• the contents are subject to parameter expansion, command substitution, arithmetic expansion.
• a backslash in the contents is treated as quotation if and only if it precedes $, `, ", or another
backslash.
• a backslash followed by a newline is treated as line continuation.
In here string, the token after the operator is subject to expansion as in redirection to files. The
expansion result becomes the contents of the here string. A newline character is automatically appended
to the end of here string contents.
Here string is yash’s extension that is not defined in POSIX. Other shells like bash, ksh, and zsh have
the same feature.
Pipeline redirection
Pipeline redirection allows opening pipelines that can be used for arbitrary purposes.
Pipeline redirection
>>| token
The token is subject to expansion as in redirection to files, but it is treated as a file descriptor
rather than a pathname. Thus the expanded token must be a non-negative integer.
Pipeline redirection opens a new pipeline. The standard output (or the file descriptor specified before
the operator, if any) is replaced with the file descriptor open for writing to the pipeline. The file
descriptor specified by token is replaced with the file descriptor open for reading from the pipeline.
Pipeline redirection is yash’s extension that is not defined in POSIX.
Process redirection
Process redirection creates a pipeline connected to another command.
Process redirection
<(command...)
>(command...)
In process redirection, the command specified is executed in a subshell. If the process redirection is of
the form <(command...), the standard output of command is connected with a pipeline to the standard input
of the command the redirection is associated with. If the process redirection is of the form
>(command...), the standard input of command is connected with a pipeline to the standard output of the
command the redirection is associated with.
Process redirection is yash’s extension that is not defined in POSIX. Bash and zsh have a feature called
process substitution, which uses the same syntax as yash’s process redirection, but incompatibly differs
in behavior.
COMMAND EXECUTION
This section describes how commands are executed.
Execution of simple commands
A simple command is executed as follows:
1. All tokens in the simple command are expanded except for assignment and redirection tokens. If an
error occurs during expansion, the execution of the simple command is aborted with a non-zero exit
status.
In the following steps, the first word of the expansion results is referred to as command name, and
the other words as command arguments. If there is only one word of the expansion results, there are
no command argument words. If there are none of the expansion results, there is no command name
either.
2. Redirection specified in the command, if any, is processed. The word token after each redirection
operator is expanded. If an error occurs during processing redirection (including when expanding the
word token), the execution of this simple command is aborted with a non-zero exit status.
3. Assignments specified in the command, if any, are processed. For each assignment token, the value is
expanded and assigned to the specified variable. If an error occurs during assignments (including
when expanding the values to be assigned), the execution of this simple command is aborted with a
non-zero exit status.
• If there is no command name or the name denotes a special built-in, the assignments are
permanent: the assigned values remain after the command has finished (until the variable is
reassigned).
• Otherwise, the assignments are temporary: the assigned values only last during the execution of
this simple command.
The assigned variables are automatically exported when the command name is specified or the
all-export option is enabled.
Note
In other shells, assignments may behave differently: For special built-ins and functions,
assigned variables may not be exported. For functions, assigned variables may be persistent, that
is, may remain even after the execution of the simple command.
4. If there is no command name, the command execution ends with the exit status of zero (unless there
are any command substitutions in the command, in which case the exit status of the simple command is
that of the last executed command substitution).
5. A command to be executed is determined using the command search algorithm and the command is
executed.
• If the command is an external command, the command is executed by creating a new subshell and
calling the “exec” system call in the subshell. The command name and arguments are passed to the
executed command. Exported variables are passed to the executed command as environment variables.
• If the command is a built-in, the built-in is executed with the command arguments passed to the
built-in.
• If the command is a function, the contents of the function are executed with the command
arguments as function arguments.
If the command was executed, the exit status of this simple command is that of the executed command.
If the algorithm failed to determine a command, no command is executed and the exit status is 127. If
the shell failed to execute the determined command, the exit status is 126. If the executed command
was killed by a signal, the exit status is the signal number plus 384.
Note
In shells other than yash, the exit status may be different when the command was killed by a
signal, because the POSIX standard only requires that the exit status be "greater than 128."
If the shell is not in the POSIXly-correct mode and the algorithm failed to determine a command, the
command eval -i -- "${COMMAND_NOT_FOUND_HANDLER-}" is evaluated. During the command execution,
positional parameters are temporarily set to the command name and arguments that resulted in the
first step. Any local variables defined during the execution are removed when the execution is
finished. The HANDLED local variable is automatically defined with the initial value being the empty
string. If the HANDLED variable has a non-empty value when the execution of the command string is
finished, the shell pretends that the command was successfully determined and executed. The exit
status of the simple command is that of the command string in this case.
Command search
A command that is executed in a simple command is determined by the command name using the following
algorithm:
1. If the command name contains a slash (/), the whole name is treated as the pathname of an
external command. The external command is determined as the executed command.
2. If the command name is a special built-in, the built-in is determined as the executed command.
3. If the command name is the name of an existing function, the function is determined as the
executed command.
4. If the command name is a semi-special built-in, the built-in is determined as the executed
command.
5. If the command name is a regular built-in, the built-in is determined as the executed command
unless the shell is in the POSIXly-correct mode.
6. The shell searches the PATH for a executed command:
The value of the PATH variable is separated by colons. Each separated part is considered as a
directory pathname (an empty pathname denotes the current working directory). The shell searches
the directories (in the order of appearance) and checks if any directory directly contains an
executable regular file whose name is equal to the command name. If such a file is found:
• If the command name is the name of a built-in, the built-in is determined as the executed
command.
• Otherwise, the file is determined as the executed command. (The file will be executed as an
external command.)
If no such file is found, no command is determined as the executed command.
When the shell finds a file that matches the command name during the search above, the shell
remembers the pathname of the file if it is an absolute path. When the algorithm above is used for
the same command name again, the shell skips searching and directly determines the command to be
executed. If an executable regular file no longer exists at the remembered pathname, however, the
shell searches again to update the remembered pathname. You can manage remembered pathnames using the
hash built-in.
Termination of the shell
The shell exits when it reached the end of input and has parsed and executed all input commands or when
the exit built-in is executed. The exit status of the shell is that of the last command the shell
executed (or zero if no commands were executed). The exit status of the shell is always between 0 and 255
(inclusive). If the exit status of the last command is 256 or larger, the exit status of the shell will
be the remainder of the exit status divided by 256.
If an exit handler has been registered by the trap built-in, the handler is executed just before the
shell exits. The exit status of the commands executed in the handler does not affect the exit status of
the shell.
If a non-interactive shell encountered one of the following errors, the shell immediately exits with a
non-zero exit status:
• A command cannot be parsed due to an syntax error (except during shell initialization).
• An error occurs during execution of a special built-in in the POSIXly-correct mode.
• A redirection error occurs in a simple command whose command name is a special built-in and the shell
is in the POSIXly-correct mode.
• An assignment error occurs in a simple command.
• An error occurs during expansion (except during shell initialization).
Note
Some shells other than yash exit when they fail to find a command to execute in command search.
Functions
Functions allow executing a compound command as a simple command. A function can be defined by the
function definition command and executed by a simple command. You can use the unset built-in to remove
function definitions.
There are no functions predefined when yash is started.
A function is executed by executing its body, which is a compound command. While the function is being
executed, positional parameters are set to the arguments given to the function. The old positional
parameters are restored when the function execution finishes.
Local variables
Local variables are temporary variables that are defined in a function and exist during the function
execution only. They can be defined by the typeset built-in or implicitly created by a for loop. They
are removed when the function execution finishes.
Local variables may hide variables that have already been defined before the function execution had
started. An existing variable becomes inaccessible if a local variable of the same name is defined in
a function. The old variable becomes accessible again when the function execution finishes.
You cannot create a local variable when not executing a function. A normal variable is created if you
try to do so.
Command execution environment
The shell holds following properties during execution.
• The working directory
• Open file descriptors
• The file creation mask (umask)
• The set of signals whose handler is set to “ignore” (trap)
• Environment variables
• Resource limits (ulimit)
Those properties are inherited from the invoker of the shell to the shell, and from the shell to each
external command executed by the shell.
The properties can be changed during the execution of the shell by built-in commands, variable
assignments, etc.
Subshells
A subshell is a copy of the shell process. Subshells are used in execution of groupings, pipelines,
etc.
Subshells inherit functions, aliases, etc. defined in the shell as well as the properties above since
subshells are copies of the shell process. Notable exceptions are:
• Traps registered by the trap built-in are all reset in subshells except for ones whose action is
set to “ignore”. (See below)
• The interactive mode and job control are disabled in subshells. Jobs are not inherited by
subshells.
Subshells are executed independently of the original shell, so changes of any properties above do not
affect those of the original shell.
Note
If the subshell contains a single trap built-in, some shells (but not yash) may not reset the
traps on entry to the subshell.
INTERACTIVE MODE
The interactive mode is a mode of the shell intended for direct interaction with a user. If yash is in
the interactive mode, it is called an interactive shell.
Whether a shell runs in the interactive mode or not is determined in the invocation of the shell. After
the shell has started up, the interactive mode cannot be switched on or off.
When the shell is interactive:
• Initialization scripts are executed during invocation.
• The shell checks for mail and prints a command prompt when it reads a command. Job status changes are
also reported if job control is active. Line-editing may be used depending on the capability of the
terminal.
• Commands executed are automatically registered in command history.
• If a command executed by the shell is killed by a signal other than SIGINT and SIGPIPE, the shell
reports the fact to the standard error.
• The filename token is subject to pathname expansion in file redirection.
• The shell does not exit when it encounters a syntax or expansion error during command execution. (cf.
Termination of the shell)
• The shell does not exit when it receives the SIGINT, SIGTERM, or SIGQUIT signal.
• A signal handler can be changed by the trap built-in even if the handler had been set to “ignore”
when the shell was invoked.
• The value of the - special parameter contains i.
• The shell’s locale reflects the value of the LC_CTYPE variable whenever the value is changed (if the
shell is not in the POSIXly-correct mode).
• Commands are executed even when the exec option is off.
• The ignore-eof option takes effect when enabled.
• When the shell reaches the end of input or the exit built-in is executed, the shell checks if there
is any stopped job. If so, the shell prints a warning and does not actually exit.
• The suspend built-in by default cannot stop the shell if it is a session leader.
• The shell does not exit when the dot built-in fails to find a script file to read.
• The shell does not exit when the exec built-in fails to execute a command (if not in the
POSIXly-correct mode).
• When a job finished for which the wait built-in has been waiting, the fact is reported (only if job
control is active and not in the POSIXly-correct mode).
• A prompt is printed when the read built-in reads a second or following line.
Prompts
The interactive shell prints a prompt just before it reads a command. The contents of the prompt is
specified by the value of the PS1 and PS2 variables. The former is used for reading the first line of the
command and the latter for other lines.
When the prompt is printed, the variable value is subjected to parameter expansion, command substitution,
and arithmetic expansion (but note that the POSIX standard requires parameter expansion only). The result
of the expansion is parsed by the rules below to make the actual prompt string, which is printed to the
standard error.
In the POSIXly-correct mode, each exclamation mark (!) in the string is substituted with the command
history number of the command that is being input. Two adjacent exclamation marks (!!) are printed as a
single exclamation. Other characters are printed intact.
If the shell is not in the POSIXly-command mode, the following notations can be used to format the prompt
string. Notations are replaced with the strings designated in the list below. Characters that are not
interpreted as notations are printed intact.
\a
Bell character (ASCII code: 7)
\e
Escape character (ASCII code: 27)
\j
The number of jobs in the shell.
\n
Newline character (ASCII code: 10)
\r
Carriage return character (ASCII code: 13)
\!
The command history number of the command that is being input
\$
# if the shell’s effective user ID is 0; $ otherwise.
\\
Backslash
\[, \]
These two notations can surround part of the prompt string that is not visible on the terminal. The
surrounded part is ignored when the shell counts the number of characters that is displayed on the
terminal, thus making characters correctly aligned on the terminal when the prompt string contains
special invisible characters.
\ffontspecs.
When line-editing is active, this notation is replaced with special characters to change font styles
on the terminal if the terminal is capable of it. If line-editing is inactive or the terminal is
incapable of changing font styles, this notation is silently ignored. One or more of the following
can be used for fontspecs:
k
Change font color to black
r
Change font color to red
g
Change font color to green
y
Change font color to yellow
b
Change font color to blue
m
Change font color to magenta
c
Change font color to cyan
w
Change font color to white
K
Change background color to black
R
Change background color to red
G
Change background color to green
Y
Change background color to yellow
B
Change background color to blue
M
Change background color to magenta
C
Change background color to cyan
W
Change background color to white
t
Make font color or background brighter (can only be used just after one of the characters above)
d
Change font and background colors to normal
s
Make font standout
u
Make font underlined
v
Make font and background colors reversed
b
Make font blink
i
Make font dim
o
Make font bold
x
Make font invisible
D
Make color and style normal
The actual colors of font and background are defined by the terminal. Different terminals may use
different colors.
In addition to the normal prompt, a prompt string can be displayed to the right of the cursor if
line-editing is active. Those prompts are called right prompts. The contents of right prompts are defined
by the value of the PS1R and PS2R variables, each corresponding to the PS1 and PS2 variables.
Using the above-said notations, the font style of command strings the user inputs can be changed as well
as that of prompts. The font style of command strings is defined by the value of the PS1S and PS2S
variables, each corresponding to the PS1 and PS2 variables. The value can contain the \ffontspecs.
notation only.
When the shell is not in the POSIXly-correct mode, the prompt variables can be defined with a name
prefixed with YASH_ (e.g. YASH_PS1). This allows using a different prompt string than that in the
POSIXly-correct mode.
When the shell is not in the POSIXly-correct mode, the value of the PROMPT_COMMAND variable is executed
before each prompt.
Command history
Command history is a feature of the shell that remembers executed commands to allow re-executing them
later. Commands executed in the interactive mode are automatically saved in the command history. Saved
commands can be edited and re-executed using line-editing and the fc and history built-ins.
Commands are saved line by line. Lines that do not contain any non-whitespace characters are not saved in
the history. Lines that start with whitespaces are not saved when the hist-space option is on.
Command history is saved in a file. When history is first used after an interactive shell was started,
the shell opens a file to save history in. The filename is specified by the value of the HISTFILE
variable. If the file contains history data when opened, the data is restored to the shell’s history. The
file contents are updated in real time as the user inputs commands into the shell. If the HISTFILE
variable is not set or the file cannot be opened successfully, history is not saved in the file, but the
history feature will be functional in all other respects.
The number of commands saved in history is specified by the value of the HISTSIZE variable. The shell
automatically removes old history data so that the number of saved commands does not exceed the value. If
the HISTSIZE variable is not set or its value is not a natural number, 500 items will be saved in
history.
The shell looks at the value of the HISTFILE and HISTSIZE variables only when the history feature is
first used after the shell was started. “The history feature is used” when:
• the fc or history built-in is executed,
• line-editing is used (regardless of whether or not history data is recalled in line-editing), or
• a command is input to the shell
Therefore, the variables should be set in initialization scripts.
When more than one instance of yash shares a single history file, all the shells use the same history
data. As a result, commands that have been executed by a shell instance can be recalled on another shell
instance. Shells sharing the same history should have the same HISTSIZE value so that they manipulate
history data properly.
Yash’s history data file has its own format that is incompatible with other kinds of shells.
The HISTRMDUP variable can be set to remove duplicate history items.
Mail checking
An interactive shell can notify receipt of email. The shell periodically checks the modification
date/time of a file specified by the user. If the file has been modified since the previous check, the
shell prints a notification message (except when the shell is not in the POSIXly-correct mode and the
file is empty). By specifying a mailbox file to be checked, the shell will print a message when the file
has been modified, that is, some mail has been received.
Check is done just before the shell prints a command line prompt. The interval of checks can be specified
by the MAILCHECK variable in seconds. If the variable value is 0, check is done before every prompt. If
the variable value is not a non-negative integer, no checks are done.
The file whose modification time is checked is specified by the MAIL variable. The variable value should
be set to the pathname of the file.
If you want to check more than one file or customize the notification message, you can set the MAILPATH
variable instead of the MAIL variable. When the MAILPATH variable is set, the MAIL variable is ignored.
The value of the MAILPATH variable should be set to one or more colon-separated pathnames of files to be
checked. Each pathname can be followed by a percent sign (%) and a custom notification message, which is
printed when the corresponding file has been modified. If the pathname contains a percent sign, it should
be quoted by a backslash. The specified message is subject to parameter expansion. For example, if the
value of the MAILPATH variable is /foo/mail%New mail!:/bar/mailbox%You've got mail:/baz/mail\%data, the
shell will print
• New mail! when the file /foo/mail has been modified
• You've got mail when the file /bar/mailbox has been modified
• the default message when the file /baz/mail%data has been modified.
JOB CONTROL
Job control is a function of the shell that executes multiple commands simultaneously and
suspends/resumes the commands.
When job control is active:
• Every pipeline executed by the shell becomes a job. A job has its unique process group ID that is
shared among all processes in the job.
• If the processes of a job are suspended while the shell is waiting for the processes to finish, the
shell continues to the next command as if the process have finished. The shell remembers the job as
suspended so that it can be resumed later.
• If a job is executed synchronously, the shell sets the foreground process group of the terminal to
the process group of the job. When the job is finished (or suspended), the shell gets back to the
foreground.
• The subshell executing a command substitution has its own unique process group ID like a job.
However, the shell does not remember the subshell as a job, so it cannot be suspended or resumed.
• If the shell is interactive, job status is reported before every command line prompt as if the
command jobs -n is executed.
• The standard input of an asynchronous command is not automatically redirected to /dev/null.
• The shell does not exit when it receives the SIGTSTP signal.
• The value of the - special parameter contains m.
• When a job finished for which the wait built-in has been waiting, the fact is reported (only if the
shell is interactive and not in the POSIXly-correct mode).
When job control is inactive, processes executed by the shell have the same process group ID as the
shell. The shell treats asynchronous commands as an uncontrolled job.
You can use the following built-ins to manipulate jobs:
jobs
prints existing jobs
fg and bg
run jobs in the foreground or background
wait
waits for jobs to be finished (or suspended)
disown
forgets jobs
kill
sends a signal to jobs
An interactive job-controlling shell reports jobs status before every prompt by default. You can set the
following options to make the shell report status at other timings:
notify
the shell reports immediately whenever job status changes.
notify-le
the shell reports immediately when job status changes while line-editing.
A job is removed from the shell’s job list when:
• it has finished and the jobs built-in reported it,
• the wait built-in successfully waited for the job to finish, or
• the disown built-in removed the job.
Jobs are not removed from the list when an interactive shell automatically reports the status of jobs.
Note
The word “stop” is synonymous to “suspend” in the context of job control.
Job ID
Some built-ins use the following notation, which is called job ID, to specify a job to operate on:
%, %%, %+
the current job
%-
the previous job
%n
the job that has job number n, where n is a positive integer
%string
the job whose name begins with string
%?string
the job whose name contains string
The current job and previous job are jobs selected by the shell according to the following rules:
• When there is one or more suspended jobs, the current job is selected from them.
• When there is one or more suspended jobs other than the current job, the previous job is selected
from them.
• The current and previous jobs are always different. When the shell has only one job, it is the
current job and there is no previous job.
• When the current job finished, the previous job becomes the current job.
• When the current job is changed, the old current job becomes the previous job except when the old job
finished.
• When the foreground job is suspended, the job becomes the current job.
Yash has some options to modify the rules of the current/previous job selection. (The rules above have
priority over the options below.)
cur-async
When a new asynchronous command is started, it becomes the current job.
cur-bg
When a job is resumed by the bg built-in, the job becomes the current job.
cur-stop
When a job is suspended, it becomes the current job.
The current and previous jobs are not changed as long as the rules above are met.
The rules of the current/previous job selection defined in the POSIX standard are looser than yash’s
rules above. Other POSIX-compliant shells may select the current and previous jobs differently.
BUILT-IN COMMANDS
Built-in commands are commands that are implemented in the shell and are executed by the shell without
external programs.
Types of built-in commands
There are three types of built-in commands in yash: special built-in commands, semi-special built-in
commands and regular built-in commands.
Special built-in commands are much more important commands than others. They are executed regardless of
whether the corresponding external commands exist or not. Results of variable assignments that occur in a
simple command that invokes a special built-in last after the command has finished. Moreover, in the
POSIXly-correct mode, a non-interactive shell immediately exits with a non-zero exit status when a
redirect error, assignment error, or misuse of option or operand occurs in a special built-in command.
Semi special built-in commands are the second important built-in commands. They are executed regardless
of whether the corresponding external commands exist or not. In other parts they are the same as regular
built-in commands.
Regular built-in commands are less important built-in commands including commands that can be implemented
as external commands or are not listed in POSIX. In the POSIXly-correct mode, a regular built-in is
executed only when a corresponding external command is found in PATH.
Syntax of command arguments
In this section we explain common rules about command arguments. The built-in commands of yash follow the
rules unless otherwise stated.
There are two types of command arguments. One is options and the other is operands. An option is an
argument that starts with a hyphen (-) and changes the way the command behaves. Some options take
arguments. An operand is an argument that is not an option and specifies objects the command operates on.
If you specify more than one option to a command, the order of the options are normally not significant.
The order of operands, however, affects the command behavior.
An option is either a single-character option or a long option. A single-character option is identified
by one alphabetic character. A long option is identified by multiple alphabetic characters. The POSIX
standard only prescribes single-character options, so in the POSIXly-correct mode you cannot use long
options.
A single-character option is composed of a hyphen followed by a letter. For example, -a is a
single-character option. A single-character option that takes an argument requires the argument to be
just after the option name.
Example 4. The set built-in and single-character options
For the set built-in, -m is a single-character option that does not take an argument and -o is one that
takes an argument.
• set -o errexit -m
• set -oerrexit -m
In these two command lines, errexit is the argument to the -o option.
In the second example above, the -o option and its argument are combined into a single command line
argument. The POSIX standard deprecates that style and any POSIX-conforming applications must specify
options and their arguments as separate command line arguments, although yash accepts both styles.
You can combine single-character options that do not take arguments into a single command line argument.
For example, the three options -a, -b and -c can be combined into -abc.
A long option is composed of two hyphens followed by an option name. For example, --long-option is a long
option. You can omit some last characters of a long option name as long as it is not ambiguous. For
example, you can use --long instead of --long-option if there is no other options beginning with --long.
Like a single-character option, a long option that takes an argument requires the argument to be a
command line argument just after the option name or to be specified in the same command line argument as
the option name, separated by an equal sign (=).
Example 5. The fc built-in and long options
For the fc built-in, --quiet is a long option that does not take an argument and --editor is one that
takes an argument.
• fc --editor vi --quiet
• fc --editor=vi --quiet
In these command lines, vi is the argument to the --editor option.
Arguments that are not options (nor arguments to them) are interpreted as operands. The POSIX standard
requires all options should be specified before any operands. Therefore, in the POSIXly-correct mode, any
arguments that come after the first operand are interpreted as operands (even if they look like options).
If not in the POSIXly-correct mode, you can specify options after operand.
Regardless of whether the shell is in the POSIXly-correct mode or not, an argument that is just composed
of two hyphens (--) can be used as a separator between options and operands. All command line arguments
after the -- separator are interpreted as operands, so you can specify operands that start with a hyphen
correctly using the separator.
Example 6. Options and operands to the set built-in
• set -a -b -- -c -d
In this example, -a and -b are options and -c and -d are operands. The -- separator itself is neither an
option nor an operand.
Regardless of whether the shell is in the POSIXly-correct mode or not, an argument that is just composed
of a single hyphen (-) is interpreted as an operand.
LINE-EDITING
With the line-editing feature, you can edit the command text when you input a command to an interactive
shell. It not only works as a simple visual-interface editor, but also is integrated with the command
history. You can recall, edit, and execute commands in the history with line-editing instead of using the
fc built-in.
Line-editing has two editing modes, the vi and emacs modes, which each have their own key binding
settings. By switching editing modes, you can change key bindings used in line-editing. Each mode has a
corresponding shell option, which determines whether the mode is currently active or not. No more than
one mode can be active at a time, so the options for the other modes are automatically turned off when
you turn on the option for one mode. The whole line-editing feature is deactivated when those options are
off.
When an interactive shell is started, the vi mode is automatically activated if the standard input and
error are both connected to a terminal.
Line-editing can be used only when the standard input and error are both connected to a terminal. If not,
the shell silently falls back to the normal input mechanism. While line-editing is being used, the shell
uses the termios interface to change I/O settings of the terminal and the terminfo interface to parse
input key sequences.
Shell options on line-editing
The following options can be set by the set built-in to enable line-editing and choose an editing mode to
activate:
vi
activates the vi mode.
emacs
activates the emacs mode.
The other line-editing-related options are:
le-always-rp
When this options is enabled, the right prompt is always visible: when the cursor reaches the right
prompt, it moves to the next line from the original position, which would otherwise be overwritten by
input text.
le-comp-debug
When enabled, internal information is printed during completion, which will help debugging completion
scripts.
le-conv-meta
When enabled, the 8th bit of each input byte is always treated as a meta-key flag, regardless of
terminfo data.
le-no-conv-meta
When enabled, the 8th bit of each input byte is never treated as a meta-key flag, regardless of
terminfo data.
The le-conv-meta and le-no-conv-meta options cannot be both enabled at a time. When either is
enabled, the other is automatically disabled. When neither is enabled, the 8th bit may be treated as
a meta-key flag depending on terminfo data.
le-predict
activates command line prediction.
le-predict-empty
When enabled, and command line prediction is active, suggestions are also provided for empty input
lines.
le-prompt-sp
When enabled, the shell prints a special character sequence before printing each prompt so that every
prompt is printed at the beginning of a line.
This option is enabled by default.
le-visible-bell
When enabled, the shell flashes the terminal instead of sounding an alarm when an alert is required.
Editing modes
The vi mode is an editing mode that offers key bindings similar to that of the vi editor. The vi mode has
two sub-modes that are switched during editing: the insert and command modes. The sub-mode is always
reset to the insert mode when line-editing is started for a new command line. In the insert mode, most
characters are inserted to the buffer as typed. In the command mode, input characters are treated as
commands that move the cursor, insert/delete text, etc.
The emacs mode offers key bindings similar to the emacs editor. Most characters are inserted to the
buffer as typed, but more characters are treated as commands than the vi insert mode.
Another sub-mode is used while you enter search keywords. The sub-mode is called the search mode, which
offers slightly different key bindings depending on the active editing mode.
Line-editing commands
All characters the user enters while line-editing is active are treated as line-editing commands listed
below. The bindkey built-in allows customizing the key bindings of each mode (except for the search
mode).
The list below shows not only the functions of commands but also the default key bindings. The keywords
“vi-insert”, “vi-command”, “vi-search”, “emacs”, “emacs-search” means the vi insert mode, the vi command
mode, the search mode for the vi mode (the vi search mode), the emacs mode, and the search mode for the
emacs mode (the emacs search mode), respectively.
Some commands take an argument that affects the function of the commands. For example, the forward-char
command moves the cursor by as many characters as specified by the argument. To specify an argument, use
the digit-argument command just before another command that takes an argument.
Basic editing commands
noop
Do nothing.
vi-command
\^[
alert
Alert.
self-insert
Insert the input character at the current cursor position. Characters escaped by escape sequences
cannot be inserted.
vi-insert, emacs
\\
insert-tab
Insert a tab character at the current cursor position.
emacs
\^[\^I
expect-verbatim
Insert a character that is entered just after this command at the current cursor position. This
command can input a character that cannot be input by the self-insert command, except a null
character ('\0').
vi-insert, vi-search, emacs-search
\^V
emacs
\^Q, \^V
digit-argument
Pass the input digit to the next command as an argument.
This command can be bound to a digit or hyphen. To pass “12” as an argument to the forward-char
command in the vi mode, for example, enter 12l.
vi-command
1, 2, 3, 4, 5, 6, 7, 8, 9
emacs
\^[0, \^[1, \^[2, \^[3, \^[4, \^[5, \^[6, \^[7, \^[8, \^[9, \^[-,
bol-or-digit
Like the beginning-of-line command if there is no argument; like the digit-argument command
otherwise.
vi-command
0
accept-line
Finish editing the current line. A newline is automatically appended to the line. The line will
be executed by the shell.
If command line prediction is active, the current prediction (if any) is ignored. See also the
accept-prediction command.
vi-insert, vi-command, emacs, emacs-search
\^J, \^M
abort-line
Abandon the current buffer and finish editing as if an empty line was input.
vi-insert, vi-command, vi-search, emacs, emacs-search
\!, \^C
eof
Abandon the current buffer and finish editing as if the shell reached the end of input. This
normally makes the shell exit.
eof-if-empty
Like the eof command if the buffer is empty; like the alert command otherwise.
vi-insert, vi-command
\#, \^D
eof-or-delete
Like the eof command if the buffer is empty; like the delete-char command otherwise.
emacs
\#, \^D
accept-with-hash
If the current line does not begin with a hash sign (#) or there is no argument specified for
this command, a hash sign is inserted at the beginning of the line. Otherwise, the beginning hash
sign is removed from the line. Finally, the line is accepted like the accept-line command.
vi-command
#
emacs
\^[#
accept-prediction
Like the accept-line command, but include the predicted part.
setmode-viinsert
Switch to the vi insert mode.
vi-command
i, \I
setmode-vicommand
Switch to the vi command mode.
vi-insert
\^[
setmode-emacs
Switch to the emacs mode.
expect-char, abort-expect-char
These commands are not meant for use by the user. They are used by the shell to implement some
other commands.
redraw-all
Reprint the prompt and the current line to the terminal.
vi-insert, vi-command, vi-search, emacs, emacs-search
\^L
clear-and-redraw-all
Clear the terminal and reprint the prompt and the current line.
Motion commands
Motion commands move the cursor on the line. Most motion commands accept an argument. When passed an
argument, they repeat the cursor motion as many times as specified by the argument. Passing “4” as an
argument to the forward-char command, for example, advances the cursor by four characters.
The shell has several definitions of words as units of distance: A bigword is one or more adjacent
non-whitespace characters. A semiword is one or more adjacent characters that contain no whitespaces
or punctuations. An emacsword is one or more adjacent alphanumeric characters. A viword is either:
• one or more adjacent alphanumeric characters and/or underscores (_), or
• one or more adjacent characters that contain none of alphanumeric characters, underscores, and
whitespaces.
forward-char
Move the cursor to the next character.
vi-insert
\R
vi-command
l, (space), \R
emacs
\R, \^F
backward-char
Move the cursor to the previous character.
vi-insert
\L
vi-command
h, \B, \L, \?, \^H
emacs
\L, \^B
forward-bigword
Move the cursor to the next bigword.
vi-command
W
end-of-bigword
Move the cursor to the next end of a bigword.
vi-command
E
backward-bigword
Move the cursor to the previous bigword.
vi-command
B
forward-semiword
Move the cursor to the next semiword.
end-of-semiword
Move the cursor to the next end of a semiword.
backward-semiword
Move the cursor to the previous semiword.
forward-viword
Move the cursor to the next viword.
vi-command
w
end-of-viword
Move the cursor to the next end of a viword.
vi-command
e
backward-viword
Move the cursor to the previous viword.
vi-command
b
forward-emacsword
Move the cursor to the next emacsword.
emacs
\^[f, \^[F
backward-emacsword
Move the cursor to the previous emacsword.
emacs
\^[b, \^[B
beginning-of-line
Move the cursor to the beginning of the line.
vi-insert, vi-command
\H
emacs
\H, \^A
end-of-line
Move the cursor to the end of the line.
vi-insert
\E
vi-command
$, \E
emacs
\E, \^E
go-to-column
Move the cursor to the nth character on the line, where n is the argument. Assume n = 1 when no
argument.
vi-command
|
first-nonblank
Move the cursor to the first non-blank character on the line.
vi-command
^
find-char
Move the cursor to the first position where a character that is entered just after this command
appears after the current cursor position.
vi-command
f
emacs
\^]
find-char-rev
Move the cursor to the last position where a character that is entered just after this command
appears before the current cursor position.
vi-command
F
emacs
\^[\^]
till-char
Move the cursor to the first position just before a character that is entered just after this
command appears after the current cursor position.
vi-command
t
till-char-rev
Move the cursor to the last position just after a character that is entered just after this
command appears before the current cursor position.
vi-command
T
refind-char
Redo the last find-char, find-char-rev, till-char, till-char-rev command.
vi-command
;
refind-char-rev
Redo the last find-char, find-char-rev, till-char, till-char-rev command in the reverse
direction.
vi-command
,
Editing commands
Editing commands modify contents of the buffer. Most editing commands accept an argument. When passed
an argument, they repeat the modification as many times as specified by the argument.
Texts deleted by commands whose name starts with “kill” are saved in kill ring, from which deleted
contents can be restored to the buffer. The most recent 32 texts are kept in the kill ring.
delete-char
Delete a character at the current cursor position if no argument is passed; like the kill-char
command otherwise.
vi-insert, emacs
\X
delete-bigword
Delete a bigword at the current cursor position if no argument is passed; like the kill-bigword
command otherwise.
delete-semiword
Delete a semiword at the current cursor position if no argument is passed; like the kill-semiword
command otherwise.
delete-viword
Delete a viword at the current cursor position if no argument is passed; like the kill-viword
command otherwise.
delete-emacsword
Delete a emacsword at the current cursor position if no argument is passed; like the
kill-emacsword command otherwise.
backward-delete-char
Delete a character just before the current cursor position if no argument is passed; like the
backward-kill-char command otherwise.
vi-insert, emacs
\B, \?, \^H
backward-delete-bigword
Delete a bigword just before the current cursor position if no argument is passed; like the
backward-kill-bigword command otherwise.
backward-delete-semiword
Delete a semiword just before the current cursor position if no argument is passed; like the
backward-kill-semiword command otherwise.
vi-insert
\^W
backward-delete-viword
Delete a viword just before the current cursor position if no argument is passed; like the
backward-kill-viword command otherwise.
backward-delete-emacsword
Delete a emacsword just before the current cursor position if no argument is passed; like the
backward-kill-emacsword command otherwise.
delete-line
Delete the whole buffer contents.
forward-delete-line
Delete all characters from the current cursor position to the end of the buffer.
backward-delete-line
Delete all characters before the current cursor position.
vi-insert
\$, \^U
kill-char
Delete a character at the current cursor position and add it to the kill ring.
vi-command
x, \X
kill-bigword
Delete a bigword at the current cursor position and add it to the kill ring.
kill-semiword
Delete a semiword at the current cursor position and add it to the kill ring.
kill-viword
Delete a viword at the current cursor position and add it to the kill ring.
kill-emacsword
Delete a emacsword at the current cursor position and add it to the kill ring.
emacs
\^[d, \^[D
backward-kill-char
Delete a character just before the current cursor position and add it to the kill ring.
vi-command
X
backward-kill-bigword
Delete a bigword just before the current cursor position and add it to the kill ring.
emacs
\^W
backward-kill-semiword
Delete a semiword just before the current cursor position and add it to the kill ring.
backward-kill-viword
Delete a viword just before the current cursor position and add it to the kill ring.
backward-kill-emacsword
Delete a emacsword just before the current cursor position and add it to the kill ring.
emacs
\^[\B, \^[\?, \^[\^H
kill-line
Delete the whole buffer contents and add it to the kill ring.
forward-kill-line
Delete all characters from the current cursor position to the end of the buffer and add it to the
kill ring.
emacs
\^K
backward-kill-line
Delete all characters before the current cursor position and add it to the kill ring.
emacs
\$, \^U, \^X\B, \^X\?
put-before
Insert the last-killed text before the current cursor position and move the cursor to the last
character that was inserted.
vi-command
P
put
Insert the last-killed text after the current cursor position and move the cursor to the last
character that was inserted.
vi-command
p
put-left
Insert the last-killed text before the current cursor position and move the cursor to the last
character that was inserted.
emacs
\^Y
put-pop
Replace the just put text with the next older killed text.
This command can be used only just after the put-before, put, put-left, or put-pop command.
emacs
\^[y, \^[Y
undo
Cancel modification by the last editing command.
vi
u
emacs
\^_, \^X\$, \^X\^U
undo-all
Cancel all modification in the current buffer, restoring the initial contents.
vi
U
emacs
\^[\^R, \^[r, \^[R
cancel-undo
Cancel cancellation by the last undo or undo-all command.
vi
\^R
cancel-undo-all
Cancel all cancellation by all most recent undo and undo-all commands.
redo
Repeat modification by the last editing command.
vi-command
.
Completion commands
complete
Complete a word just before the cursor position and, if there is more than one candidate, show a
list of the candidates.
complete-next-candidate
Like the complete command when candidates are not being listed; otherwise, select the next
candidate in the list.
vi-insert, emacs
\^I
complete-prev-candidate
Like the complete command when candidates are not being listed; otherwise, select the previous
candidate in the list.
vi-insert, emacs
\bt
complete-next-column
Like the complete command when candidates are not being listed; otherwise, select the first
candidate in the next column in the list.
complete-prev-column
Like the complete command when candidates are not being listed; otherwise, select the first
candidate in the previous column in the list.
complete-next-page
Like the complete command when candidates are not being listed; otherwise, select the first
candidate in the next page in the list.
complete-prev-page
Like the complete command when candidates are not being listed; otherwise, select the first
candidate in the previous page in the list.
complete-list
Complete a word just before the cursor position.
If you pass no argument, a list of completion candidates is shown. Otherwise, the word is
completed with the nth candidate where n is the argument.
emacs
\^[?, \^[=
complete-all
Replace a word just before the cursor position with all possible completion candidates, each
separated by a space.
emacs
\^[*
complete-max
Complete a word just before the cursor position with the longest prefix of all possible
completion candidates.
complete-max-then-list
Works like the complete-max command for the first use, then like the complete command when used
successively.
complete-max-then-next-candidate
Works like the complete-max command for the first use, then like the complete-next-candidate
command when used successively.
complete-max-then-prev-candidate
Works like the complete-max command for the first use, then like the complete-prev-candidate
command when used successively.
clear-candidates
Clear the list of completion candidates.
Vi-specific commands
vi-replace-char
Replace the character at the cursor position with a character that is entered just after this
command.
vi-command
r
vi-insert-beginning
Move the cursor to the beginning of the line and switch to the vi insert mode.
vi-command
I
vi-append
Move the cursor to the next character and switch to the vi insert mode.
vi-command
I
vi-append-to-eol
Move the cursor to the end of the line and switch to the vi insert mode.
vi-command
A
vi-replace
Switch to the vi insert mode and start overwriting. While overwriting, the self-insert command
replaces the character at cursor position rather than inserting a character. Overwriting ends
when the editing mode is changed.
vi-command
R
vi-switch-case
Switch case of characters between the current and next cursor positions. This command must be
followed by a motion command, which determines the next cursor position.
vi-switch-case-char
Switch case of the character at the current cursor position and move the cursor to the next
character.
vi-command
~
vi-yank
Add to the kill ring the characters between the current and next cursor positions. This command
must be followed by a motion command, which determines the next cursor position.
vi-command
y
vi-yank-to-eol
Add to the kill ring the characters from the current cursor position to the end of the line.
vi-command
Y
vi-delete
Delete characters between the current and next cursor positions and add it to the kill ring. This
command must be followed by a motion command, which determines the next cursor position.
vi-command
d
vi-delete-to-eol
Delete the characters from the current cursor position to the end of the line and add it to the
kill ring.
vi-command
D
vi-change
Delete characters between the current and next cursor positions and switch to the vi insert mode.
This command must be followed by a motion command, which determines the next cursor position.
vi-command
c
vi-change-to-eol
Delete the characters from the current cursor position to the end of the line and switch to the
vi insert mode.
vi-command
C
vi-change-line
Delete the whole buffer contents and switch to the vi insert mode.
vi-command
S
vi-yank-and-change
Like the vi-change command, but the deleted text is added to the kill ring.
vi-yank-and-change-to-eol
Like the vi-change-to-eol command, but the deleted text is added to the kill ring.
vi-yank-and-change-line
Like the vi-change-line command, but the deleted text is added to the kill ring.
vi-substitute
Delete a character at the current cursor position, add it to the kill ring, and switch to the vi
insert mode.
vi-command
s
vi-append-last-bigword
Insert a space and the last bigword in the most recent command history entry just after the
current cursor position and switch to the vi insert mode. If argument n is passed, the nth
bigword in the entry is inserted instead of the last.
vi-command
_
vi-exec-alias
Execute the value of an alias named _c as editing commands where c is a character input just
after this command.
vi-command
@
vi-edit-and-accept
Start the vi editor to edit the current buffer contents. When the editor finished, the edited
buffer contents is accepted like the accept-line command unless the exit status of the editor is
non-zero.
vi-command
v
vi-complete-list
Like the complete-list command, but also switch to the vi insert mode.
vi-command
=
vi-complete-all
Like the complete-all command, but also switch to the vi insert mode.
vi-command
*
vi-complete-max
Like the complete-max command, but also switch to the vi insert mode.
vi-command
\\
vi-search-forward
Switch to the vi search mode and start forward history search.
vi-command
?
vi-search-backward
Switch to the vi search mode and start backward history search.
vi-command
/
Emacs-specific commands
emacs-transpose-chars
Move a character just before the cursor to the right.
emacs
\^T
emacs-transpose-words
Move an emacsword just before the cursor to the right.
emacs
\^[t, \^[T
emacs-downcase-word
Make an emacsword just after the cursor lowercase.
emacs
\^[l, \^[L
emacs-upcase-word
Make an emacsword just after the cursor uppercase.
emacs
\^[u, \^[U
emacs-capitalize-word
Capitalize the first letter of an emacsword just after the cursor.
emacs
\^[c, \^[u
emacs-delete-horizontal-space
Delete spaces around the cursor. If any argument was passed, delete spaces just before the cursor
only.
emacs
\^[\\
emacs-just-one-space
Delete spaces around the cursor and leave one space. If an argument is specified, leave as many
spaces as the argument.
emacs
\^[ (Escape followed by a space)
emacs-search-forward
Switch to the emacs search mode and start forward history search.
emacs
\^S
emacs-search-backward
Switch to the emacs search mode and start backward history search.
emacs
\^R
History-related commands
oldest-history
Recall the oldest entry in the history. If argument n is passed, the entry whose number is n is
recalled instead. The cursor position remains unchanged.
newest-history
Recall the newest entry in the history. If argument n is passed, the entry whose number is n is
recalled instead. The cursor position remains unchanged.
return-history
Return to the initial buffer corresponding to none of existing history entries. If argument n is
passed, the entry whose number is n is recalled instead. The cursor position remains unchanged.
oldest-history-bol
Recall the oldest entry in the history and move the cursor to the beginning of the line. If
argument n is passed, the entry whose number is n is recalled instead.
vi-command
G
newest-history-bol
Recall the newest entry in the history and move the cursor to the beginning of the line. If
argument n is passed, the entry whose number is n is recalled instead.
return-history-bol
Return to the initial buffer corresponding to none of existing history entries and move the
cursor to the beginning of the line. If argument n is passed, the entry whose number is n is
recalled instead.
vi-command
g
oldest-history-eol
Recall the oldest entry in the history and move the cursor to the end of the line. If argument n
is passed, the entry whose number is n is recalled instead.
emacs
\^[<
newest-history-eol
Recall the newest entry in the history and move the cursor to the end of the line. If argument n
is passed, the entry whose number is n is recalled instead.
return-history-eol
Return to the initial buffer corresponding to none of existing history entries and move the
cursor to the end of the line. If argument n is passed, the entry whose number is n is recalled
instead.
emacs
\^[>
next-history
Recall the next history entry. The cursor position remains unchanged.
prev-history
Recall the previous history entry. The cursor position remains unchanged.
next-history-bol
Recall the next history entry and move the cursor to the beginning of the line.
vi-command
j, +, \D, \^N
prev-history-bol
Recall the previous history entry and move the cursor to the beginning of the line.
vi-command
k, -, \U, \^P
next-history-eol
Recall the next history entry and move the cursor to the end of the line.
vi-insert, emacs
\D, \^N
prev-history-eol
Recall the previous history entry and move the cursor to the end of the line.
vi-insert, emacs
\U, \^P
search-again
Repeat the last command history search.
vi-command
n
search-again-rev
Repeat the last command history search in the reverse direction.
vi-command
N
search-again-forward
Repeat the last command history search in the forward direction.
search-again-backward
Repeat the last command history search in the backward direction.
beginning-search-forward
Recall the next history entry that starts with the same text as the text from the beginning of
the line up to the current cursor position. The cursor position remains unchanged.
beginning-search-backward
Recall the previous history entry that starts with the same text as the text from the beginning
of the line up to the current cursor position. The cursor position remains unchanged.
Search mode commands
srch-self-insert
Insert the input character at the current cursor position. Characters escaped by escape sequences
cannot be inserted.
vi-search, emacs-search
\\
srch-backward-delete-char
Delete the last character in the search text. If the text is empty:
• like the srch-abort-search command when in the vi search mode, or
• like the alert command when in the emacs search mode.
vi-search, emacs-search
\B, \?, \^H
srch-backward-delete-line
Delete the whole search text.
vi-search, emacs-search
\$, \^U
srch-continue-forward
Find the next matching history entry.
emacs-search
\^S
srch-continue-backward
Find the previous matching history entry.
emacs-search
\^R
srch-accept-search
Finish the search mode, accepting the result being shown.
vi-search
\^J, \^M
emacs-search
\^J, \^[
srch-abort-search
Abort search and restore the previous buffer contents.
vi-search
\^[
emacs-search
\^G
Escape sequences
In the bindkey built-in, escape sequences are used to represent special keys such as function keys and
arrow keys. Every escape sequence starts with a backslash (\) and thus there is also an escape sequence
for a backslash itself.
Below are available escape sequences:
\\
Backslash (\)
\B
Backspace
\D
Down arrow
\E
End
\H
Home
\I
Insert (Insert-char, Enter-insert-mode)
\L
Left arrow
\N
Page-down (Next-page)
\P
Page-up (Previous-page)
\R
Right arrow
\U
Up arrow
\X
Delete
\!
INTR
\#
EOF
\$
KILL
\?
ERASE
\^@
Ctrl + @
\^A, \^B, ..., \^Z
Ctrl + A, Ctrl + B, ..., Ctrl + Z
Note that Ctrl + I, Ctrl + J, and Ctrl + M are tab, newline, and carriage return, respectively.
\^[
Ctrl + [ (Escape)
\^\
Ctrl + \
\^]
Ctrl + ]
\^^
Ctrl + ^
\^_
Ctrl + _
\^?
Ctrl + ? (Delete)
\F00, \F01, ..., \F63
F0, F1, ..., F63
\a1
Top-left on keypad
\a3
Top-right on keypad
\b2
Center on keypad
\bg
Beginning
\bt
Back-tab
\c1
Bottom-left on keypad
\c3
Bottom-right on keypad
\ca
Clear-all-tabs
\cl
Close
\cn
Cancel
\co
Command
\cp
Copy
\cr
Create
\cs
Clear-screen or erase
\ct
Clear-tab
\dl
Delete-line
\ei
Exit-insert-mode
\el
Clear-to-end-of-line
\es
Clear-to-end-of-screen
\et
Enter (Send)
\ex
Exit
\fd
Find
\hp
Help
\il
Insert-line
\ll
Home-down
\me
Message
\mk
Mark
\ms
Mouse event
\mv
Move
\nx
Next-object
\on
Open
\op
Options
\pr
Print (Copy)
\pv
Previous-object
\rd
Redo
\re
Resume
\rf
Ref (Reference)
\rh
Refresh
\rp
Replace
\rs
Restart
\sf
Scroll-forward (Scroll-down)
\sl
Select
\sr
Scroll-backward (Scroll-up)
\st
Set-tab
\su
Suspend
\sv
Save
\ud
Undo
\SE
Shift + End
\SH
Shift + Home
\SI
Shift + Insert
\SL
Shift + Left arrow
\SR
Shift + Right arrow
\SX
Shift + Delete
\Sbg
Shift + Beginning
\Scn
Shift + Cancel
\Sco
Shift + Command
\Scp
Shift + Copy
\Scr
Shift + Create
\Sdl
Shift + Delete-line
\Sel
Shift + End-of-line
\Sex
Shift + Exit
\Sfd
Shift + Find
\Shp
Shift + Help
\Smg
Shift + Message
\Smv
Shift + Move
\Snx
Shift + Next
\Sop
Shift + Options
\Spr
Shift + Print
\Spv
Shift + Previous
\Srd
Shift + Redo
\Sre
Shift + Resume
\Srp
Shift + Replace
\Ssu
Shift + Suspend
\Ssv
Shift + Save
\Sud
Shift + Undo
INTR, EOF, KILL, and ERASE are special characters configured by the stty command. In a typical
configuration, they are sent by typing Ctrl+C, Ctrl+D, Ctrl+U, and Ctrl+H, respectively, but some
configuration uses Ctrl+? instead of Ctrl+H for ERASE.
Command line completion
By using the complete and complete-next-candidate commands, etc., you can complete command names,
options, and operands. By default, the complete-next-candidate command is bound with the Tab key in the
vi insert and emacs modes.
Type a few first letters of a command name or pathname and hit the Tab key, and a list of matching names
will be shown. You can choose a candidate from the list to complete the name by hitting the Tab key
again. If there is only one matching name, no list will be shown and the name will directly be completed.
If the name to be completed contains characters like * and ?, it is treated as a pattern. The name on the
command line will be directly substituted with all possible names matching the pattern (you cannot choose
from a list).
Normally, command names are completed with command names and command arguments with pathnames. However,
completion functions can be defined to refine completion results.
Completion details
When doing completion for the first time after the shell has been started, the INIT file is loaded as
if the command string . -AL completion/INIT is executed. If the file is not found, it is silently
ignored. This automatic loading is mainly intended for loading completion functions bundled with the
shell, but you can let the shell load your own functions by putting a file in the load path.
When completing a command name, the shell executes the completion//command function and when
completing a command argument, the completion//argument function. If those completion functions are
not defined, the shell just completes with command names or pathnames. When completing other names,
such as the user name in tilde expansion and the parameter name in parameter expansion, completion
functions are never used: the shell just completes with user names, parameter names, or whatever
applicable.
Completion functions are executed without any arguments. The following local variables are
automatically defined while executing completion functions:
IFS
The value is the three characters of a space, a tab, and a newline, which are the default value
of the variable.
WORDS
This variable is an array whose elements are a command name and arguments that have already been
entered before the argument being completed. When completing a command name, the array has no
elements.
TARGETWORD
The value is the partially entered command name or argument that is being completed.
Completion candidates are generated by executing the complete built-in during a completion function.
Completion functions must not perform I/O to the terminal, or displayed text will be corrupted.
Completion functions should run as quickly as possible for better user experience.
While a completion function is being executed:
• the POSIXly-correct mode and the err-return option are temporarily disabled,
• the err-exit option is temporarily ignored, and
• traps are not executed.
Command line prediction
This is an experimental feature. When the le-predict option is enabled, the shell automatically tries to
predict a command string fragment that follows the part of the command you have already typed in
line-editing.
For example, assume you have once typed the command ls Documents. Next time you start typing ls Doc, the
shell will show uments just after the cursor. If you are satisfied with this suggestion, you can move the
cursor to the right by the forward-char or any other motion commands instead of typing the rest of the
command. After moving the cursor after the last s, you can use the accept-line command to execute the
command. You can also use the accept-prediction command to immediately execute the suggested command
without moving the cursor.
To distinguish the typed part and the predicted part of a command string, you can change the font style
of the typed part by setting the PS1S variable. Customizing the font style of the predicted part is not
(yet) supported; it is always shown in the default style.
When you move the cursor to the right, the predicted part up to the cursor becomes the typed part as if
you actually typed it. Moving the cursor to the left does not turn the typed part back to the prediction.
Use deletion commands such as backward-delete-char to delete typed command fragment.
The predicted part of the command is shown only when the cursor is at the end of the typed part.
By default, the predicted part is shown after you start typing a command string. By enabling the
le-predict-empty option, the predicted part is also shown before you type the first character of the
command string.
The prediction algorithm suggests command fragments on the basis of the command history. The algorithm
considers recent history entries more probable. It also takes command succession patterns into account. A
predicted command fragment is not always a complete valid command because less probable part of the
fragment is excluded from prediction.
POSIXLY-CORRECT MODE
Yash behaves as defined in POSIX.1-2008, Shell & Utilities for the most part, but some functionalities
disobey POSIX for usability. When full POSIX-conformance is needed, you can enable the POSIXly-correct
mode to make yash obey POSIX as much as possible.
If yash is started with the name “sh”, the POSIXly-correct mode is automatically enabled. The -o
posixly-correct command-line option also enables the POSIXly-correct mode. After yash has been started,
the POSIXly-correct mode can be enabled by executing the command string set -o posixly-correct.
When the POSIXly-correct mode is on, yash not only tries to obey the requirements by POSIX, but also
treats as errors most conditions where the behavior is undefined or unspecified by POSIX. As a result,
most yash-specific functionalities are disabled in the POSIXly-correct mode.
Below is the complete list of the behavioral differences between when yash is in the POSIXly-correct mode
and when not. When the POSIXly-correct mode is enabled:
• Different initialization scripts are used.
• If the shell was started with the -c option, sh -c (instead of yash -c) is printed as the script
pathname on a syntax error.
• Global aliases are not substituted.
• Nested commands in a compound command must not be empty.
• The for loop iteration variable is created as global, regardless of the for-local shell option. The
variable must have a portable (ASCII-only) name.
• The first pattern in a case command cannot be esac.
• The ! keyword cannot be followed by ( without any whitespaces in-between.
• The double-bracket command cannot be used.
• The function keyword cannot be used for function definition. The function must have a portable
(ASCII-only) name.
• Simple commands cannot assign to arrays.
• Changing the value of the LC_CTYPE variable after the shell has been initialized does not affect the
shell’s locale.
• The RANDOM variable cannot be used to generate random numbers.
• Tilde expansion only expands ~ and ~username.
• Parameter expansion cannot be nested. No indexes or modifiers with word2 are allowed.
• The commands in a command substitution of the form $(commands) are parsed every time the substitution
is executed.
• In arithmetic expansion, fractional numbers and the ++ and -- operators cannot be used. All variables
must be numeric.
• The operand of a redirection cannot be the integer prefix to a next redirection operator.
• A compound command with a redirection cannot be immediately followed by a keyword like } and fi.
• In a redirection to a file, if the pathname expansion yielded more than one or no pathname, it is not
immediately treated as an error. Instead, the shell tries to treat the word before the expansion as a
pathname.
• A file descriptor must be readable and writable when duplicated by the <& and >& redirection
operator, respectively.
• Socket redirection, here strings, pipe redirection, and process redirection cannot be used.
• When executing a simple command, failure in command search does not trigger execution of the
COMMAND_NOT_FOUND_HANDLER variable.
• In command search, a regular built-in needs to have a corresponding external command for the built-in
to be found.
• Some built-ins behave differently. Especially, long command-line options (as well as some others)
cannot be used.
• A non-interactive shell exits when a special built-in is given a syntactically wrong arguments or
when an error occurs in assignment or redirection with a special built-in.
• An interactive shell does not execute the PROMPT_COMMAND variable before printing a prompt. The
values of the PS1, PS2, and PS4 variables are parsed differently. Prompt variables with a YASH_
prefix (e.g. YASH_PS1) are not used.
• In mail checking, a notification message is printed if the file has been modified, regardless of
whether the file is empty.
FREQUENTLY ASKED QUESTIONS AND TROUBLESHOOTING
How can I use Unicode (non-ASCII) characters?
You need to set locale environment variables to enable Unicode character support.
If the variables have already been configured for your preference, you probably don’t have to do
anything. To check the current locale configurations, you can use the locale command:
$ locale
LANG=
LC_CTYPE="en_US.utf8"
LC_NUMERIC="en_US.utf8"
LC_TIME="en_US.utf8"
LC_COLLATE="en_US.utf8"
LC_MONETARY="en_US.utf8"
LC_MESSAGES="en_US.utf8"
LC_PAPER="en_US.utf8"
LC_NAME="en_US.utf8"
LC_ADDRESS="en_US.utf8"
LC_TELEPHONE="en_US.utf8"
LC_MEASUREMENT="en_US.utf8"
LC_IDENTIFICATION="en_US.utf8"
LC_ALL=en_US.utf8
In this example, the locale command shows that all the locale setting categories are configured for the
English language, the United States region, and the UTF-8 encoding.
If the current configuration does not seem to match your preference, set the LC_ALL variable like this:
export LC_ALL=en_US.utf8
If you want to use other languages, regions, or encodings, you have to set the variable to a different
value. Please consult your OS’s documentation to learn how to configure these variables in detail.
If you want to apply the same configuration every time you start yash, write the command in ~/.yashrc or
~/.yash_profile.
If yash still rejects Unicode characters being entered, see the section below regarding line-editing.
Line-editing does not work
First, type echo $TERM and see if it prints a sane value. xterm is the safest value that should work on
any existing environment. Colored versions like xterm-16color and other terminal types like rxvt and
vt100 may also work. All possible values can be listed by the toe command. It’s most desirable to choose
a value that matches the actual terminal type you are using, but it might not work if the terminal type
you chose is not supported on the system on which yash is running. If so, try changing the TERM value by
export TERM=xterm, for example, to find a value that works.
If line-editing works but you have trouble entering Unicode (non-ASCII) characters, try enabling the
le-no-conv-meta option by set -o le-no-conv-meta.
FORMAL DEFINITION OF COMMAND SYNTAX
This chapter defines the syntax of the shell command language.
Note
Some of the syntactic features described below are not supported in the POSIXly-correct mode.
Tokenization
The characters of the input source code are first delimited into tokens. Tokens are delimited so that the
earlier token spans as long as possible. A sequence of one or more unquoted blank characters delimits a
token.
The following tokens are the operator tokens:
& && ( ) ; ;; | || < << <& <( <<- <<< <> > >> >& >( >>| >| (newline)
Note
Unlike other programming languages, the newline operator is a token rather than a white space.
Characters that are not blank nor part of an operator compose a word token. Words are parsed by the
following parsing expression grammar:
Word
(WordElement / !SpecialChar .)+
WordElement
\ . /
' (!' .)* ' /
" QuoteElement* " /
Parameter /
Arithmetic /
CommandSubstitution
QuoteElement
\ ([$`"\] / <newline>) /
Parameter /
Arithmetic /
CommandSubstitutionQuoted /
![`"\] .
Parameter
$ [@*#?-$! [:digit:]] /
$ PortableName /
$ ParameterBody
PortableName
![0-9] [0-9 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]+
ParameterBody
{ ParameterNumber? (ParameterName / ParameterBody / $ ParameterBody / Arithmetic /
CommandSubstitution) ParameterIndex? ParameterMatch? }
ParameterNumber
# ![}+=:/%] !([-?#] !})
ParameterName
[@*#?-$!] /
[[:alnum:] _]+
ParameterIndex
[ ParameterIndexWord (, ParameterIndexWord)? ]
ParameterIndexWord
(WordElement / !["'],] .)+
ParameterMatch
:? [-+=?] ParameterMatchWord /
(# / ## / % / %%) ParameterMatchWord /
(:/ / / [#%/]?) ParameterMatchWordNoSlash (/ ParameterMatchWord)?
ParameterMatchWord
(WordElement / !["'}] .)*
ParameterMatchWordNoSlash
(WordElement / !["'/}] .)*
Arithmetic
$(( ArithmeticBody* ))
ArithmeticBody
\ . /
Parameter /
Arithmetic /
CommandSubstitution /
( ArithmeticBody ) /
![`()] .
CommandSubstitution
$( CompleteProgram ) /
` CommandSubstitutionBody* `
CommandSubstitutionQuoted
$( CompleteProgram ) /
` CommandSubstitutionBodyQuoted* `
CommandSubstitutionBody
\ [$`\] /
!` .
CommandSubstitutionBodyQuoted
\ [$`\`] /
!` .
SpecialChar
[|&;<>()`\"' [:blank:]] / <newline>
The set of terminals of the grammar is the set of characters that can be handled on the environment in
which the shell is run (a.k.a. execution character set), with the exception that the set does not contain
the null character ('\0').
Strictly speaking, the definition above is not a complete parsing expression grammar because the rule for
CommandSubstitution (Quoted) depends on CompleteProgram which is a non-terminal of the syntax.
Token classification
After a word token is delimited, the token may be further classified as an IO_NUMBER token, reserved
word, name word, assignment word, or just normal word. Classification other than the normal word is
applied only when applicable in the context in which the word appears. See Tokens and keywords for
the list of the reserved words (keywords) and the context in which a word may be recognized as a
reserved word.
A token is an IO_NUMBER token iff it is composed of digit characters only and immediately followed by
< or >.
An assignment token is a token that starts with a name followed by =:
AssignmentWord
AssignmentPrefix Word
AssignmentPrefix
Name =
Name
![[:digit:]] \[[:alnum:] _]+
Comments
A comment begins with # and continues up to (but not including) the next newline character. Comments
are treated like a blank character and do not become part of a token. The initial # of a comment must
appear as if it would otherwise be the first character of a word token; Other #s are just treated as
part of a word token.
Comment
# (!<newline> .)*
Syntax
After tokens have been delimited, the sequence of the tokens is parsed according to the context-free
grammar defined below, where *, +, and ? should be interpreted in the same manner as standard regular
expression:
CompleteProgram
NL* | CompoundList
CompoundList
NL* AndOrList ((; | & | NL) CompleteProgram)?
AndOrList
Pipeline ((&& | ||) NL* Pipeline)*
Pipeline
!? Command (| NL* Command)*
Command
CompoundCommand Redirection* |
FunctionDefinition |
SimpleCommand
CompoundCommand
Subshell |
Grouping |
IfCommand |
ForCommand |
WhileCommand |
CaseCommand |
DoubleBracketCommand |
FunctionCommand
Subshell
( CompoundList )
Grouping
{ CompoundList }
IfCommand
if CompoundList then CompoundList (elif CompoundList then CompoundList)* (else CompoundList)? fi
ForCommand
for Name ((NL* in Word*)? (; | NL) NL*)? do CompoundList done
WhileCommand
(while | until) CompoundList do CompoundList done
CaseCommand
case Word NL* in NL* CaseList? esac
CaseList
CaseItem (;; NL* CaseList)?
CaseItem
(? Word (| Word)* ) CompleteProgram
DoubleBracketCommand
[[ Ors ]]
Ors
Ands (|| Ands)*
Ands
Nots (&& Nots)*
Nots
!* Primary
Primary
(-b | -c | -d | -e | -f | -G | -g | -h | -k | -L | -N | -n | -O | -o | -p | -r | -S | -s | -t | -u |
-w | -x | -z) Word |
Word (-ef | -eq | -ge | -gt | -le | -lt | -ne | -nt | -ot | -veq | -vge | -vgt | -vle | -vlt | -vne |
= | == | === | =~ | != | !== | < | >) Word |
( Ors ) |
Word
FunctionCommand
function Word (( ))? NL* CompoundCommand Redirection*
FunctionDefinition
Name ( ) NL* CompoundCommand Redirection*
SimpleCommand
(Assignment | Redirection) SimpleCommand? |
Word (Word | Redirection)*
Assignment
AssignmentWord |
AssignmentPrefix( NL* (Word NL*)* )
Redirection
IO_NUMBER? RedirectionOperator Word |
IO_NUMBER? <( CompleteProgram ) |
IO_NUMBER? >( CompleteProgram )
RedirectionOperator
< | <> | > | >| | >> | >>| | <& | >& | << | <<- | <<<
NL
<newline>
In the rule for Primary, Word tokens must not be ]]. Additionally, if a Primary starts with a Word, it
must not be any of the possible unary operators allowed in the rule.
In the rule for SimpleCommand, a Word token is accepted only when the token cannot be parsed as the first
token of an Assignment.
In the rule for Assignment, the ( token must immediately follow the AssignmentPrefix token, without any
blank characters in between.
Here-document contents do not appear as part of the grammar above. They are parsed just after the newline
(NL) token that follows the corresponding redirection operator.
Alias substitution
Word tokens are subject to alias substitution.
• If a word is going to be parsed as a Word of a SimpleCommand, the word is subjected to alias
substitution of any kind (normal and global aliases).
• If a word is the next token after the result of an alias substitution and the substitution string
ends with a blank character, then the word is also subjected to alias substitution of any kind.
• Other words are subjected to global alias substitution unless the shell is in the POSIXly-correct
mode.
Tokens that are classified as reserved words are not subject to alias substitution.
ALIAS BUILT-IN
The alias built-in defines and/or prints aliases.
Syntax
• alias [-gp] [name[=value]...]
Description
The alias built-in defines and/or prints aliases as specified by operands. The printed aliases can be
used as (part of) shell commands. The built-in prints all currently defined aliases when given no
operands.
Options
-g, --global
With this option, aliases are defined as global aliases; without this option, as normal aliases.
-p, --prefix
With this option, aliases are printed in a full command form like alias -g foo='bar'. Without this
option, only command operands are printed like foo='bar'.
Operands
name
The name of an alias that should be printed.
name=value
The name and value of an alias that is being defined.
Exit status
The exit status of the alias built-in is zero unless there is any error.
Notes
The characters that cannot be used in an alias name are the space, tab, newline, and any of
=$<>\'"`;&|()#. You can use any characters in an alias value.
The alias built-in is a semi-special built-in.
The POSIX standard defines no options for the alias built-in, thus no options are available in the
POSIXly correct mode.
ARRAY BUILT-IN
The array built-in prints or modifies arrays.
Syntax
• array
• array name [value...]
• array -d name [index...]
• array -i name index [value...]
• array -s name index value
Description
When executed without any option or operands, the built-in prints all array definitions to the standard
output in a form that can be parsed as commands.
When executed with name and values (but without an option), the built-in sets the values as the values of
the array named name.
With the -d (--delete) option, the built-in removes the indexth values of the array named name. The
number of values in the array will be decreased by the number of the indexes specified. If the indexth
value does not exist, it is silently ignored.
With the -i (--insert) option, the built-in inserts values into the array named name. The number of
values in the array will be increased by the number of the values specified. The values are inserted
between the indexth and next values. If index is zero, the values are inserted before the first value. If
index is larger than the number of values in the array, the values are appended after the last element.
With the -s (--set) option, the built-in sets value as the indexth value of the array named name. The
array must have at least index values.
Options
-d, --delete
Delete array values.
-i, --insert
Insert array values.
-s, --set
Set an array value.
Operands
name
The name of an array to operate on.
index
The index to an array element. The first element has the index of 1.
value
A string to which the array element is set.
Exit status
The exit status of the array built-in is zero unless there is any error.
Notes
The array built-in is not defined in the POSIX standard.
The command array name value... is equivalent to the assignment name=(value...).
BG BUILT-IN
The bg built-in resumes a job in the background.
Syntax
• bg [job...]
Description
The bg built-in sends the SIGCONT signal to the specified job. As a result, the job is resumed in the
background (if it has been suspended).
The name of the job is printed when the job is resumed.
The built-in can be used only when job control is enabled.
Operands
job
The job ID of the job to be resumed.
More than one job can be specified at a time. The current job is resumed if none is specified.
The percent sign (%) at the beginning of a job ID can be omitted if the shell is not in the
POSIXly-correct mode.
Exit status
The exit status of the bg built-in is zero unless there is any error.
Notes
The bg built-in is a semi-special built-in.
The POSIX standard provides that the built-in shall have no effect when the job is already running. The
bg built-in of yash, however, always sends the SIGCONT signal to the job.
BINDKEY BUILT-IN
The bindkey built-in prints or modifies key bindings used in line-editing.
Syntax
• bindkey -aev [key [command]]
• bindkey -l
Description
When executed with the -l (--list) option, the built-in lists all available line-editing commands to the
standard output.
When executed with one of the other options, the built-in prints or modifies key bindings for the editing
mode specified by the option:
• Without key or command, all currently defined bindings are printed to the standard output in a form
that can be parsed as commands that restore the current bindings when executed.
• With key but without command, only the binding for the given key is printed.
• With key and command, key is bound to command.
Options
-a, --vi-command
Print or modify bindings for the vi command mode.
-e, --emacs
Print or modify bindings for the emacs mode.
-v, --vi-insert
Print or modify bindings for the vi insert mode.
Operands
key
A character sequence of one or more keys that is bound to an editing command. The sequence may
include escape sequences.
command
A line-editing command to which key is bound. If command is a single hyphen (-), key is unbound.
Exit status
The exit status of the bindkey built-in is zero unless there is any error.
Notes
The bindkey built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
BREAK BUILT-IN
The break built-in aborts a loop being executed.
Syntax
• break [nest]
• break -i
Description
When executed without the -i (--iteration) option, the built-in aborts a currently executed for, while,
or until loop. When executed in nested loops, it aborts the nestth innermost loop. The default nest is
one. If the number of currently executed nested loops is less than nest, the built-in aborts the
outermost loop.
When executed with the -i (--iteration) option, the built-in aborts the currently executed (innermost)
iterative execution.
Options
-i, --iteration
Abort an iterative execution instead of a loop.
Operands
nest
The number of loops to abort, which must be a positive integer.
Exit status
The exit status of the break built-in is:
• zero if a loop was successfully aborted.
• that of the command that was executed just before the break built-in if an iterative execution was
successfully aborted.
Notes
The break built-in is a special built-in.
The POSIX standard defines no options for the break built-in; the built-in accepts no options in the
POSIXly-correct mode.
Treatment of currently executed loops that are not lexically enclosing the break built-in is unspecified
in POSIX. Examples of such loops include:
• A loop invoking a function in which the break built-in is used.
• A loop in which a trap action is executed in which the break built-in is used.
Yash does not allow breaking such loops.
CD BUILT-IN
The cd built-in changes the working directory.
Syntax
• cd [-L|-P] [directory]
Description
The cd built-in changes the working directory to the directory specified by the operand.
The pathname of the new working directory is assigned to the PWD variable, whose previous value is again
assigned to the OLDPWD variable. The new PWD value will not contain any . or .. components except when
the shell is in the POSIXly-correct mode and the new pathname begins with /...
If directory is a relative path that does not start with ‘.’ or ‘..’, paths in the CDPATH variable are
searched to find a new working directory. The search is done in a manner similar to the last step of
command search, but a directory is sought instead of an executable regular file. If a new working
directory was found from CDPATH, its pathname is printed to the standard output. If no applicable
directory was found in the search, directory is simply treated as a pathname relative to the current
working directory.
If the working directory was successfully changed, the value of the YASH_AFTER_CD variable is executed as
a command unless the shell is in the POSIXly-correct mode. If the variable is an array, its values are
executed iteratively (cf. eval built-in).
Options
-L, --logical
Symbolic links in the pathname of the new working directory are not resolved. The new value of the
PWD may include pathname components that are symbolic links.
-P, --physical
Symbolic links in the pathname of the new working directory are resolved. The new value of the PWD
variable never includes pathname components that are symbolic links.
--default-directory=directory
If this option is specified and the directory operand is omitted, the argument to this option is used
for the directory operand. If the directory operand is specified, this option is ignored.
The -L (--logical) and -P (--physical) options are mutually exclusive: only the last specified one is
effective. If neither is specified, -L is assumed.
Operands
directory
The pathname of the new working directory.
If directory is a single hyphen (‘-’), the value of the OLDPWD variable is assumed for the new
directory pathname, which is printed to the standard output.
If directory is omitted, the working directory is changed to the directory specified by the
--default-directory=... option. If that option is not specified either, the default is the home
directory.
Exit status
The exit status of the cd built-in is zero if the working directory was successfully changed and non-zero
if there was an error.
Notes
The cd built-in is a semi-special built-in.
The POSIX standard does not define the use of the YASH_AFTER_CD variable or the --default-directory=...
option. The standard does not allow using an option with a single hyphen operand.
The exit status of the commands in the YASH_AFTER_CD variable does not affect that of the cd built-in.
COLON BUILT-IN
The colon built-in does nothing.
Syntax
• : [argument...]
Description
The colon built-in does nothing. Any command line arguments are ignored.
Exit status
The exit status of the colon built-in is zero.
Notes
The colon built-in is a special built-in.
Arguments are expanded and redirections are performed as usual. The colon and true built-ins have the
same effect, but colon is a special built-in while true is a semi-special.
COMMAND BUILT-IN
The command built-in executes or identifies a command.
Syntax
• command [-befp] command [argument...]
• command -v|-V [-abefkp] command...
Description
Without the -v (--identify) or -V (--verbose-identify) option, the built-in executes command with
arguments in the same manner as the last step of execution of simple commands. The command is treated as
a built-in or external command or a function according to the options specified to the command built-in.
The shell does not exit on argument syntax error etc. even if the command is a special built-in
With the -v (--identify) option, command is identified. If the command is found in $PATH, its full
pathname is printed. If it is a keyword, function, or built-in that is not found in $PATH, the command
name is simply printed. If it is an alias, it is printed in the form like alias ll='ls -l'. If the
command is not found, nothing is printed and the exit status is non-zero.
The -V (--verbose-identify) option is similar to the -v (--identify) option, but the output format is
more human-friendly.
Options
-a, --alias
Search for the command as an alias. Must be used with the -v (--identify) or -V (--verbose-identify)
option.
-b, --builtin-command
Search for the command as a built-in.
-e, --external-command
Search for the command as an external command.
-f, --function
Search for the command as a function.
-k, --keyword
Search for the command as a keyword. Must be used with the -v (--identify) or -V (--verbose-identify)
option.
-p, --standard-path
Search the system’s default PATH instead of the current $PATH.
-v, --identify
Identify commands and print in the format defined in the POSIX standard.
-V, --verbose-identify
Identify commands and print in a human-friendly format.
If none of the -a (--alias), -b (--builtin-command), -e (--external-command), -f (--function), and -k
(--keyword) options is specified, the following defaults are assumed:
Without the -v (--identify) or -V (--verbose-identify) option
-b -e
With the -v (--identify) or -V (--verbose-identify) option
-a -b -e -f -k
Operands
command
A command to be executed or identified.
argument...
Arguments passed to the executed command.
Exit status
The exit status of the command built-in is:
Without the -v (--identify) or -V (--verbose-identify) option
the exit status of the executed command.
With the -v (--identify) or -V (--verbose-identify) option
zero unless there is any error.
Notes
The command built-in is a semi-special built-in.
In the POSIXly-correct mode, options other than -p, -v, and -V cannot be used and at most one command can
be specified. The POSIX standard does not allow specifying both -v and -V together, but yash does (only
the last specified one is effective).
COMPLETE BUILT-IN
The complete built-in generates completion candidates. This built-in can only be executed from completion
functions during command line completion.
Syntax
• complete [-A pattern] [-R pattern] [-T] [-P prefix] [-S suffix] [-abcdfghjkuv] [[-O] [-D description]
word...]
Description
The built-in generates completion candidates according to the specified arguments. No matter how
candidates are generated, only candidates that match the word being completed are generated.
Options
-A pattern, --accept=pattern
Only accept candidates that match the pattern specified by this option. When more than one of this
option is specified, only candidates that match all of the patterns are generated.
-D description, --description=description
Give a description of the word candidates. The description is shown beside the candidates in the
candidate list.
-O, --option
The candidates are treated as command line options. A hyphen is prepended to each candidate that is
treated as an option.
-P prefix, --prefix=prefix
Ignore prefix of the word being completed when generating candidates. The specified prefix must be
initial part of the word.
If the word being completed is file:///home/user/docume for example, the command line complete -P
file:// -f will generate pathname candidates that complete /home/user/docume.
-R pattern, --reject=pattern
Reject candidates that match the pattern specified by this option. When more than one of this option
is specified, only candidates that match none of the patterns are generated.
-S suffix, --suffix=suffix
Append suffix to each generated candidate.
-T, --no-termination
Do not append a space after the word is completed. Without this option, a space is appended to the
completed word so that you do not have to enter a space before the next word.
Options that select candidate types
-a, --alias
Aliases. (same as --normal-alias --global-alias)
--array-variable
Arrays.
--bindkey
Line-editing commands the bindkey built-in accepts.
-b, --builtin-command
Built-in commands. (same as --special-builtin --semi-special-builtin --regular-builtin)
-c, --command
Commands. (same as --builtin-command --external-command --function)
-d, --directory
Directories.
--dirstack-index
Valid indices of the directory stack.
--executable-file
Executable regular files.
--external-command
External commands.
-f, --file
Files (including directories).
--finished-job
Job IDs of finished jobs.
--function
Functions.
--global-alias
Global aliases.
-g, --group
User groups.
-h, --hostname
Host names.
-j, --job
Job IDs.
-k, --keyword
Keywords.
--normal-alias
Normal aliases.
--regular-builtin
Regular built-in commands.
--running-job
Job IDs of jobs that are being executed.
--scalar-variable
Variables that are not arrays.
--semi-special-builtin
Semi-special built-in commands.
--signal
Signals.
--special-builtin
Special built-in commands.
--stopped-job
Job IDs of jobs that are suspended.
-u, --username
Users' log-in names.
-v, --variable
Variables.
If the -d (--directory) option is specified without the -f (--file) option, the -S / -T options are
assumed.
Generated candidates for job IDs do not have leading percent signs (%). If the word being completed
starts with a percent sign, the -P % option should be specified.
Operands
Operands are treated as completion candidates.
Exit status
The exit status of the built-in is zero if one or more candidates were generated, one if no candidates
were generated, or larger than one if an error occurred.
Notes
The complete built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
CONTINUE BUILT-IN
The continue built-in skips an iteration of a loop being executed.
Syntax
• continue [nest]
• continue -i
Description
When executed without the -i (--iteration) option, the built-in aborts the current iteration of for,
while, or until loop and starts the next iteration of the loop. When executed in nested loops, it affects
the nestth innermost loop. The default nest is one. If the number of currently executed nested loops is
less than nest, the built-in affects the outermost loop.
When executed with the -i (--iteration) option, the built-in aborts the current iteration of (innermost)
iterative execution.
Options
-i, --iteration
Skip an iterative execution instead of a loop.
Operands
nest
The nestth innermost loop is affected. nest must be a positive integer.
Exit status
The exit status of the continue built-in is:
• zero if loop iteration was successfully skipped.
• that of the command that was executed just before the continue built-in if iterative execution was
successfully skipped.
Notes
The continue built-in is a special built-in.
The POSIX standard defines no options for the continue built-in; the built-in accepts no options in the
POSIXly-correct mode.
Treatment of currently executed loops that are not lexically enclosing the continue built-in is
unspecified in POSIX. Examples of such loops include:
• A loop invoking a function in which the continue built-in is used
• A loop in which a trap action is executed in which the continue built-in is used
Yash does not allow continuing such loops.
DIRS BUILT-IN
The dirs built-in prints the contents of the directory stack.
Syntax
• dirs [-cv] [index..]
Description
The directory stack is a feature that records history of working directories. You can use the pushd
built-in to save a working directory in the directory stack, the popd built-in to recall the saved
working directory, and the dirs built-in to see the stack contents. Those built-ins use the DIRSTACK
array and the PWD variable to save the stack contents. Modifying the array means modifying the stack
contents.
Directory stack entries are indexed by signed integers. The entry of index +0 is the current working
directory, +1 is the last saved directory, +2 is the second last, and so on. Negative indices are in the
reverse order: the entry of index -0 is the first saved directory, -1 is the second, and -n is the
current working directory if the stack has n entries,
When executed without the -c (--clear) option, the dirs built-in prints the current contents of the
directory stack to the standard output. With the -c (--clear) option, the built-in clears the directory
stack.
Options
-c, --clear
Clear the directory stack contents except for the current working directory, which has index +0.
-v, --verbose
Print indices when printing stack contents.
Operands
index
The index of a stack entry to be printed.
You can specify more than one index. If you do not specify any index, all the entries are printed.
Exit status
The exit status of the dirs built-in is zero unless there is any error.
Notes
The dirs built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
DISOWN BUILT-IN
The disown built-in removes jobs.
Syntax
• disown [-a] [job...}
Description
The disown built-in removes the specified jobs from the job list. The removed jobs will no longer be
job-controlled, but the job processes continue execution (unless they have been suspended).
Options
-a, --all
Removes all jobs.
Operands
job
The job ID of the job to be removed.
You can specify more than one job ID. If you do not specify any job ID, the current job is removed.
If the shell is not in the POSIXly-correct mode, the %-prefix of the job ID can be omitted.
Exit status
The exit status of the disown built-in is zero unless there is any error.
Notes
The disown built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
DOT BUILT-IN
The dot built-in reads a file and executes commands in it.
Syntax
• . [-AL] file [argument...]
Description
The dot built-in reads the specified file, parses its contents as commands, and executes them in the
current command execution environment.
If arguments are specified, positional parameters are temporarily set to them. The positional parameters
will be restored when the dot built-in finishes. If no arguments are specified, the positional parameters
are not changed.
If file does not contain any slashes, the shell searches $PATH for a readable (but not necessarily
executable) shell script file whose name is file in the same manner as command search. If no such file
was found, the shell searches the current working directory for a file unless in the POSIXly-correct
mode. To ensure that the file in the current working directory is used, start file with ‘./’.
Options
-A, --no-alias
Disable alias substitution while parsing.
-L, --autoload
Search $YASH_LOADPATH instead of $PATH, regardless of whether file contains slashes. The file value
is not considered relative to the current working directory.
The dot built-in treats as operands any command line arguments after the first operand.
Operands
file
The pathname of a file to be read.
arguments...
Strings to which positional parameters are set while execution.
Exit status
The exit status of the dot built-in is that of the last command executed. The exit status is zero if the
file contains no commands to execute and non-zero if a file was not found or could not be opened.
Notes
The dot built-in is a special built-in.
A non-interactive shell immediately exits with a non-zero exit status if the dot built-in fails to find
or open a file to execute.
The POSIX standard defines no options for the dot built-in; the built-in accepts no options in the
POSIXly-correct mode.
The POSIX standard does not define the arguments... operands. It is an error to specify the arguments...
operands in the POSIXly-correct mode.
ECHO BUILT-IN
The echo built-in prints its arguments.
Syntax
• echo [string...]
The built-in treats all command line arguments as operands except for the options described below. Any
word that cannot be parsed as an acceptable option is treated as an operand. Options must precede all
operands. Syntax errors never happen in the echo built-in.
Description
The echo built-in prints the operand strings followed by a newline to the standard output. The strings
are each separated by a space.
Escape sequences
The ECHO_STYLE variable and the -e option enable escape sequences that are replaced with
corresponding characters:
\a
Bell character (ASCII code: 7)
\b
Backspace (ASCII code: 8)
\c
Nothing. After this escape sequence, no characters are printed at all.
\e
Escape character (ASCII code: 27)
\f
Form feed character (ASCII code: 12)
\n
Newline character (ASCII code: 10)
\r
Carriage return character (ASCII code: 13)
\t
Horizontal tab character (ASCII code: 9)
\v
Vertical tab character (ASCII code: 11)
\\
Backslash
\0xxx
Character whose code is xxx, where xxx is an octal number of at most three digits.
When escape sequences are not enabled, they are just printed intact.
ECHO_STYLE variable
The ECHO_STYLE variable defines which options are accepted and whether escape sequences are enabled
by default. The variable value should be set to one of the following:
SYSV, XSI
No options are accepted. Escape sequences are always enabled.
BSD
The -n option is accepted. Escape sequences are never enabled.
GNU
The -n, -e, and -E options are accepted. Escape sequences are not enabled by default, but can be
enabled by the -e option.
ZSH
The -n, -e, and -E options are accepted. Escape sequences are enabled by default, but can be
disabled by the -E option.
DASH
The -n option is accepted. Escape sequences are always enabled.
RAW
No options are accepted. Escape sequences are never enabled.
When the ECHO_STYLE variable is not set, it defaults to SYSV.
Options
-n
Do not print a newline at the end.
-e
Enable escape sequences.
-E
Disable escape sequences.
Exit status
The exit status of the echo built-in is zero unless there is any error.
Notes
The POSIX standard does not define the ECHO_STYLE variable nor any options for the built-in. According to
POSIX, the behavior of the built-in is implementation-defined when the first argument is -n or when any
argument contains a backslash. For maximum portability, the printf built-in should be preferred over the
echo built-in.
Although many values for the ECHO_STYLE variable are defined on the basis of other existing
implementations, yash is not intended to exactly imitate those originals. Zsh’s echo built-in interprets
a single hyphen argument as a separator between options and operands. Yash does not support such use of
hyphen.
EVAL BUILT-IN
The eval built-in evaluates operands as commands.
Syntax
• eval [-i] [command...]
The eval built-in requires that all options precede operands. Any command line arguments after the first
operand are all treated as operands.
Description
The eval parses operands as commands and executes them in the current command execution environment.
When executed without the -i (--iteration) option, all the operands are concatenated into one string
(with a space inserted between each operand) and parsed/executed at once.
With the -i (--iteration) option, the built-in performs iterative execution: operands are parsed/executed
one by one. If the continue built-in is executed with the -i (--iteration) option during the iterative
execution, the execution of the current operand is aborted and the next operand is parsed/executed
immediately. The break built-in with the -i (--iteration) option is similar but the remaining operands
are not parsed/executed. The value of the ? special parameter is saved before the iterative execution is
started. The parameter value is restored to the saved one after each iteration.
Options
-i, --iteration
Perform iterative execution.
Operands
command
A string that is parsed and executed as commands.
Exit status
The exit status is zero if no command was specified or command contained no actual command that can be
executed. Otherwise, that is, if the eval built-in executed one or more commands, the exit status of the
eval built-in is that of the last executed command.
Notes
The eval built-in is a special built-in.
The POSIX standard defines no options for the eval built-in; the built-in accepts no options in the
POSIXly-correct mode.
EXEC BUILT-IN
The exec built-in replaces the shell process with another external command.
Syntax
• exec [-cf] [-a name] [command [argument...]]
The exec built-in requires that all options precede operands. It is important so that options to the exec
built-in are not confused with options to command. Any command line arguments after command are treated
as arguments.
Description
When the exec built-in is executed with command, the shell executes command with arguments in a manner
similar to the last step of execution of a simple command. The differences are that command is always
treated as an external command ignoring any existing functions and built-ins and that the exec system
call that starts the external command is called in the current command execution environment instead of a
subshell, replacing the shell process with the new command process.
If the shell is in the POSIXly-correct mode or not interactive, failure in execution of command causes
the shell to exit immediately.
If an interactive shell that is not in the POSIXly-correct mode has a stopped job, the shell prints a
warning message and refuses to execute command. Once the shell process is replaced with an external
command, information about the shell’s jobs is lost, so you will have to resume or kill the stopped jobs
by sending signals by hand. To force the shell to execute command regardless, specify the -f (--force)
option.
When executed without command, the built-in does nothing. As a side effect, however, redirection applied
to the built-in remains in the current command execution environment even after the built-in finished.
Options
-a name, --as=name
Pass name, instead of command, to the external command as its name.
-c, --clear
Pass to the external command only variables that are assigned in the simple command in which the
built-in is being executed. Other environment variables are not passed to the command.
-f, --force
Suppress warnings that would prevent command execution.
Operands
command
An external command to be executed.
argument...
Arguments to be passed to the command.
Exit status
If the shell process was successfully replaced with the external command, there is no exit status since
the shell process no longer exists.
The exit status is:
• 127 if the command was not found,
• 126 if the command was found but could not be executed, and
• zero if no command was specified.
Notes
The exec built-in is a special built-in.
The POSIX standard defines no options for the exec built-in; the built-in accepts no options in the
POSIXly-correct mode.
EXIT BUILT-IN
The exit built-in causes the shell process to exit.
Syntax
• exit [-f] [exit_status]
Description
The exit built-in causes the current shell (or subshell) process to exit.
If an interactive shell has a stopped job, the shell prints a warning message and refuses to exit. To
force the shell to exit regardless, specify the -f (--force) option or execute the built-in twice in a
row.
If an EXIT trap has been set, the shell executes the trap before exiting.
Options
-f, --force
Suppress warnings that would prevent the shell from exiting.
Operands
exit_status
A non-negative integer that will be the exit status of the exiting shell.
If this operand is omitted, the exit status of the shell will be that of the last command executed
before the exit built-in (but, if the built-in is executed during a trap, the exit status will be
that of the last command before the trap is entered).
If exit_status is 256 or larger, the actual exit status will be the remainder of exit_status divided
by 256.
Exit status
Because the built-in causes the shell to exit, there is no exit status of the built-in.
As an exception, if the shell refused to exit, the exit status of the built-in is non-zero.
Notes
The exit built-in is a special built-in.
The POSIX standard defines no options for the exit built-in; the built-in accepts no options in the
POSIXly-correct mode.
The POSIX standard provides that the exit_status operand should be between 0 and 255 (inclusive). Yash
accepts integers larger than 255 as an extension.
If the built-in is executed during an EXIT trap, the shell just exits without executing the trap again.
If exit_status was not specified, the exit status of the shell is what the exit status would be if the
trap had not been set. See also Termination of the shell.
EXPORT BUILT-IN
The export built-in marks variables for export to child processes.
Syntax
• export [-prX] [name[=value]...]
Description
The export built-in is equivalent to the typeset built-in with the -gx option.
Notes
The export built-in is a special built-in.
The POSIX standard defines the -p option only; other options cannot be used in the POSIXly-correct mode.
The POSIX does not allow using the option together with operands.
FALSE BUILT-IN
The false built-in does nothing unsuccessfully.
Syntax
• false
Description
The false built-in does nothing. Any command line arguments are ignored.
Exit status
The exit status of the false built-in is non-zero.
Notes
The false built-in is a semi-special built-in.
FC BUILT-IN
The fc built-in re-executes or prints commands from command history.
Syntax
• fc [-qr] [-e editor] [start [end]]
• fc -s[q] [old=new] [start]
• fc -l[nrv] [start [end]]
Description
When executed without the -l (--list) option, the built-in executes the commands in the command history
range specified by the operands. If the -s (--silent) option is not specified, the shell invokes an
editor which allows you to edit the commands before they are executed. The commands are executed when you
quit the editor. If the -s (--silent) option is specified, the commands are immediately executed. In
either case, the executed commands are printed to the standard output and added to the history.
When executed with the -l (--list) option, the built-in prints the commands in the command history range
specified by the operands. By default, commands are printed with their history entry numbers, but output
format can be changed using the -n (--no-numbers)) and -v (--verbose) options.
Options
-e editor, --editor=editor
Specify an editor that is used to edit commands.
If this option is not specified, the value of the FCEDIT variable is used. If the variable is not set
either, ed is used.
-l, --list
Print command history entries.
-n, --no-numbers
Don’t print entry numbers when printing history entries.
-q, --quiet
Don’t print commands before executing.
-r, --reverse
Reverse the order of command entries in the range.
-s, --silent
Execute commands without editing them.
-v, --verbose
Print execution time before each history entry when printing.
Operands
start and end
The start and end operands specify a range of command history entries that are executed or printed.
If one of the operands is an integer, it is treated as a history entry number. A negative integer
means the nth most recent entry where n is the absolute value of the integer. If one of the operands
is not an integer, it is treated as part of a command string: the most recent entry that starts with
the string is selected as the start or end of the range.
If the first entry of the range that is specified by start is newer than the last entry of the range
that is specified by end, the range is reversed as if the -r (--reverse) option was specified. (If
the option is already specified, it is cancelled.)
The default values for start and end are:
┌──────┬─────────┬───────────────┐
│ │ with -l │ without -l │
├──────┼─────────┼───────────────┤
│start │ -16 │ -1 │
├──────┼─────────┼───────────────┤
│end │ -16 │ same as start │
└──────┴─────────┴───────────────┘
old=new
An operand of this format replaces part of the command string. If the command string contains old, it
is replaced with new and the new string is executed. Only the first occurrence of old is replaced.
Exit status
If commands was executed, the exit status of the fc built-in is that of the last executed command.
Otherwise, the exit status is zero unless there is any error.
Notes
The fc built-in is a semi-special built-in.
The POSIX standard does not define the -q (--quiet) or -v (--verbose) options, so they cannot be used in
the POSIXly-correct mode.
Command history cannot be modified during line-editing.
FG BUILT-IN
The fg built-in resumes a job in the foreground.
Syntax
• fg [job...]
Description
The fg built-in brings the specified job to the foreground and sends the SIGCONT signal to the job. As a
result, the job is resumed in the foreground (if it has been suspended). The built-in then waits for the
job to finish and returns the exit status of it.
The name of the job is printed when the job is resumed. When not in the POSIXly-correct mode, the job
number is also printed.
The built-in can be used only when job control is enabled.
Operands
job
The job ID of the job to be resumed.
If more than one job is specified, they are resumed in order, one at a time. The current job is
resumed if none is specified.
The percent sign (%) at the beginning of a job ID can be omitted if the shell is not in the
POSIXly-correct mode.
Exit status
The exit status of the fg built-in is that of the (last) job resumed. The exit status is non-zero when
there was some error.
Notes
The fg built-in is a semi-special built-in.
You cannot specify more than one job in the POSIXly-correct mode.
GETOPTS BUILT-IN
The getopts built-in parses command options.
Syntax
• getopts optionlist variable [argument...]
Description
The getopts built-in parses single-character options that appear in arguments. Each time the built-in is
invoked, it parses one option and assigns the option character to variable.
The optionlist operand is a list of option characters that should be accepted by the parser. In
optionlist, an option that takes an argument should be specified as the option character followed by a
colon. For example, if you want the -a, -b and -c options to be parsed and the -b option to take an
argument, then optionlist should be ab:c.
When an option that takes an argument is parsed, the argument is assigned to the OPTARG variable.
When an option that is not specified in optionlist is found or when an option argument is missing, the
result depends on the first character of optionlist:
• If optionlist starts with a colon, the option character is assigned to the OPTARG variable and
variable is set to either ? (when the option is not in optionlist) or : (when the option argument is
missing).
• Otherwise, variable is set to ?, the OPTARG variable is unset, and an error message is printed.
The built-in parses one option for each execution. For all options in a set of command line arguments to
be parsed, the built-in has to be executed repeatedly with the same arguments. The built-in uses the
OPTIND variable to remember which argument should be parsed next. When the built-in is invoked for the
first time, the variable value must be 1, which is the default value. You must not modify the variable
until all the options have been parsed, when the built-in sets the variable to the index of the first
operand in arguments. (If there are no operands, it will be set to the number of arguments plus one.)
When you want to start parsing a new set of arguments, you have to reset the OPTIND variable to 1
beforehand.
Operands
optionlist
A list of options that should be accepted as valid options in parsing.
variable
The name of a variable the result is to be assigned to.
arguments
Command line arguments that are to be parsed.
When no arguments are given, the positional parameters are parsed.
Exit status
If an option is found, whether or not it is specified in optionlist, the exit status is zero. If there is
no more option to be parsed, the exit status is non-zero.
Example
aopt=false bopt= copt=false
while getopts ab:c opt
do
case $opt in
a) aopt=true ;;
b) bopt=$OPTARG ;;
c) copt=true ;;
\?) return 2 ;;
esac
done
if $aopt; then echo Option -a specified; fi
if [ -n "$bopt" ]; then echo Option -b $bopt specified; fi
if $copt; then echo Option -c specified; fi
shift $((OPTIND - 1))
echo Operands are: $*
Notes
In arguments that are parsed, options must precede operands. The built-in ends parsing when it encounters
the first operand.
The getopts built-in is a semi-special built-in.
The POSIX standard does not specify what will happen when the OPTIND variable is assigned a value other
than 1.
In the POSIXly-correct mode, option characters in optionlist must be alphanumeric.
HASH BUILT-IN
The hash built-in remembers, forgets, or reports command locations.
Syntax
• hash command...
• hash -r [command...]
• hash [-a]
• hash -d user...
• hash -dr [user...]
• hash -d
Description
When executed with commands but without options, the built-in immediately performs command path search
and caches commands' full paths.
When executed with the -r (--remove) option, it removes the paths of commands (or all cached paths if
none specified) from the cache.
When executed without options or commands, it prints the currently cached paths to the standard output.
With the -d (--directory) option, the built-in does the same things to the home directory cache, rather
than the command path cache. Cached home directory paths are used in tilde expansion.
Options
-a, --all
Print all cached paths.
Without this option, paths for built-ins are not printed.
-d, --directory
Affect the home directory cache instead of the command path cache.
-r, --remove
Remove cached paths.
Operands
command
The name of an external command (that does not contain any slash).
user
A user name.
Exit status
The exit status of the hash built-in is zero unless there is any error.
Notes
The shell automatically caches command and directory paths when executing a command or performing tilde
expansion, so normally there is no need to use this built-in explicitly to cache paths.
Assigning a value to the PATH variable removes all command paths from the cache as if hash -r was
executed.
The POSIX standard defines the -r option only: other options cannot be used in the POSIXly-correct mode.
The hash built-in is a semi-special built-in.
HELP BUILT-IN
The help built-in prints usage of built-ins.
Syntax
• help [built-in...]
Description
The help built-in prints a description of built-ins.
Operands
built-ins
Names of built-ins.
Exit status
The exit status of the help built-in is zero unless there is any error.
Notes
The help built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
Many built-ins of yash accept the --help option that prints the same description.
HISTORY BUILT-IN
The history built-in prints or edits command history.
Syntax
• history [-cF] [-d entry] [-s command] [-r file] [-w file] [count]
Description
The history built-in prints or edits command history.
When executed with an option, the built-in edits history according to the option. If more than one option
is specified, each option is processed in order.
When executed with the count operand, the built-in prints the most recent count history entries to the
standard output in the same manner as the fc built-in.
When executed with neither options nor operands, the built-in prints the whole history.
Options
-c, --clear
Clear all history entries completely.
-d entry, --delete=entry
Delete the specified entry. The entry should be specified in the same manner as the start and end
operands of the fc built-in.
-F, --flush-file
Rebuild the history file. This operation removes unused old data from the file.
-r file, --read=file
Read command lines from file and add them to the history. The file contents are treated as lines of
simple text.
-s command, --set=command
Add command as a new history entry after removing the most recent entry.
-w file, --write=file
Write the whole history to file. Any existing data in the file will be lost. The output format is
lines of simple text, each of which is a command string.
Operands
count
The number of entries to be printed.
Exit status
The exit status of the history built-in is zero unless there is any error.
Notes
The history built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
Command history cannot be modified during line-editing.
JOBS BUILT-IN
The jobs built-in reports job status.
Syntax
• jobs [-lnprs] [job...]
Description
The jobs built-in prints information of jobs the shell is currently controlling.
By default, the following information is printed for each job, line by line:
• the job number,
• the + or - symbol if the job is the current or previous job, respectively,
• the status, and
• the command string.
Options
-l, --verbose
Print the process ID, status, and command string for each process in the jobs.
-n, --new
Print new jobs only: jobs whose status has never been reported since the status changed.
-p, --pgid-only
Print process group IDs of jobs only.
-r, --running-only
Print running jobs only.
-s, --stopped-only
Print stopped jobs only.
Operands
jobs
The job IDs of jobs to be reported. When no job is specified, all jobs under the shell’s control are
reported.
The percent sign (%) at the beginning of a job ID can be omitted if the shell is not in the
POSIXly-correct mode.
Exit status
The exit status of the jobs built-in is zero unless there is any error.
Notes
The jobs built-in is a semi-special built-in.
The POSIX standard defines the -l and -p options only: other options cannot be used in the
POSIXly-correct mode. In the POSIXly-correct mode, the effect of the -l option is different in that
status is reported for each job rather than for each process.
The process group ID of a job executed by yash is equal to the process ID of the first command of the
pipeline that forms the job.
KILL BUILT-IN
The kill built-in sends a signal to processes.
Syntax
• kill [-signal|-s signal|-n signal] process...
• kill -l [-v] [signal...]
The kill built-in requires that all options precede operands. Any command line arguments after the first
operand are all treated as operands.
Description
When executed without the -l option, the built-in sends a signal to processes. The signal sent can be
specified by option. The SIGTERM signal is sent if no signal is specified.
When executed with the -l option, the built-in prints information of signals to the standard output. If
no signal is specified, information of all signals is printed.
Options
Signal-specifying options
-signal, -s signal, -n signal
A signal-specifying option specifies a signal to be sent to processes. signal can be specified
by name or number. If number 0 is specified, the built-in checks if a signal could be sent to the
processes but no signal is actually sent. Signal names are case-insensitive.
You can specify at most one signal-specifying option at a time.
Other options
-l
Print signal information instead of sending a signal.
-v
Print more signal information.
Without this option, the built-in prints the signal name only. This option adds the signal number
and a short description.
When the -v option is specified, the -l option can be omitted.
Operands
processes
Specify processes to which a signal is sent.
Processes can be specified by the process ID, the process group ID, or the job ID. The process group
ID must be prefixed with a hyphen (-) so that it is not treated as a process ID.
When 0 is specified as process, the signal is sent to the process group to which the shell process
belongs. When -1 is specified, the signal is sent to all processes on the system.
signal
Specify a signal of which information is printed.
The signal can be specified by the name, the number, or the exit status of a command that was killed
by the signal.
Exit status
The exit status of the kill built-in is zero unless there is any error. If the signal was sent to at
least one process, the exit status is zero even if the signal was not sent to all of the specified
processes.
Notes
The kill built-in is a semi-special built-in.
Command arguments that start with a hyphen should be used with care. The command kill -1 -2, for example,
sends signal 1 to process group 2 since -1 is treated as a signal-specifying option and -2 as an operand
that specifies a process group. The commands kill -- -1 -2 and kill -TERM -1 -2, on the other hand,
treats both -1 and -2 as operands.
The POSIX standard does not define the -n or -v options, so they cannot be used in the POSIXly-correct
mode. The standard does not allow specifying a signal number as the argument of the -s option or a signal
name as the signal operand.
The standard requires signal names to be specified without the SIG prefix, like INT and QUIT. If the
shell is not in the POSIXly-correct mode, the built-in accepts SIG-prefixed signal names as well.
LOCAL BUILT-IN
The local built-in prints or sets local variables.
Syntax
• local [-rxX] [name[=value]...]
Description
The local built-in is equivalent to the typeset built-in except that the -f (--functions) and -g
(--global) options cannot be used.
Notes
The local built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
POPD BUILT-IN
The popd built-in pops a directory from the directory stack.
Syntax
• popd [index]
Description
The popd built-in removes the last entry from the directory stack, returning to the previous working
directory. If index is given, the entry specified by index is removed instead of the last one.
Operands
index
The index of a directory stack entry you want to remove.
If omitted, +0 (the last entry) is assumed.
Exit status
The exit status of the popd built-in is zero unless there is any error.
Notes
It is an error to use this built-in when there is only one directory stack entry.
The popd built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
PRINTF BUILT-IN
The printf built-in prints formatted values.
Syntax
• printf format [value...]
Description
The printf built-in formats values according to format and prints them to the standard output. Unlike the
echo built-in, the printf built-in does not print a newline automatically.
The formatting process is very similar to that of the printf function in the C programming language. You
can use conversion specifications (which start with %) and escape sequences (which start with \) in
format. Any other characters that are not part of a conversion specification or escape sequence are
printed literally.
Conversion specifications
A conversion specification starts with a percent sign (%).
A conversion specification except %% consumes a value, which is formatted according to the
specification and printed. Each conversion specification consumes one value in the order of
appearance. If there are more values than conversion specifications, the entire format is
re-processed until all the values are consumed. If a value to be consumed is missing, it is assumed
to be an empty string (if the specification requires a string) or zero (if a number). If no values
are given, format is processed just once.
Available conversion specifications are:
%d, %i
prints a signed integer in decimal
%u
prints an unsigned integer in decimal
%o
prints an unsigned integer in octal
%x
prints an unsigned integer in lowercase hexadecimal
%X
prints an unsigned integer in uppercase hexadecimal
%f
prints a floating-point number in lowercase
%F
prints a floating-point number in uppercase
%e
prints a floating-point number with exponent in lowercase
%E
prints a floating-point number with exponent in uppercase
%g
the same as %f or %e, automatically selected
%G
the same as %F or %E, automatically selected
%c
prints the first character of string
%s
prints a string
%b
prints a string (recognizing escape sequences like the echo built-in)
%%
prints a percent sign (%)
For %g and %G, the specification that is actually used is %f or %F if the exponent part is between -5
and the precision (exclusive); %e or %E otherwise.
In a conversion specification except %%, the leading percent sign may be followed by flags, field
width, and/or precision in this order.
The flags are a sequence of any number of the following characters:
Minus sign (-)
With this flag, spaces are appended to the formatted value to fill up to the field width.
Otherwise, spaces are prepended.
Plus sign (+)
A plus or minus sign is always prepended to a number.
Space ( )
A space is prepended to a formatted number if it has no plus or minus sign.
Hash sign (#)
The value is formatted in an alternative form: For %o, the printed octal integer has at least one
leading zero. For %x and %X, a non-zero integer is formatted with 0x and 0X prefixes,
respectively. For %e, %E, %f, %F, %g, and %G, a decimal mark (a.k.a. radix character) is always
printed even if the value is an exact integer. For %g and %G, the printed number has at least one
digit in the fractional part.
Zero (0)
Zeros are prepended to a formatted number to fill up to the field width. This flag is ignored if
the minus flag is specified or if the conversion specification is %d, %i, %u, %o, %x, or %X with
a precision.
A field width is specified as a decimal integer that has no leading zeros.
A field width defines a minimum byte count of a formatted value. If the formatted value does not
reach the minimum byte count, so many spaces are prepended that the printed value has the specified
byte count.
A precision is specified as a period (.) followed by a decimal integer. If the integer is omitted
after the period, the precision is assumed to be zero.
For conversion specifications %d, %i, %u, %o, %x, and %X, a precision defines a minimum digit count.
If the formatted integer does not reach the minimum digit count, so many zeros are prepended that the
printed integer has the specified number of digits. The default precision is one for these conversion
specifications.
For conversion specifications %e, %E, %f, and %F, a precision defines the number of digits after the
decimal mark. The default precision is six for these conversion specifications.
For conversion specifications %g, and %G, a precision defines a maximum number of significant digits
in the printed value. The default precision is six for these conversion specifications.
For conversion specifications %s, and %b, a precision defines a maximum byte count of the printed
string. The default precision is infinity for these conversion specifications.
In the conversion specification %08.3f, the zero flag is specified, the field width is 8, and the
precision is 3. If this specification is applied to value 12.34, the output will be 0012.340.
Escape sequences
The following escape sequences are recognized in format:
\a
Bell character (ASCII code: 7)
\b
Backspace (ASCII code: 8)
\f
Form feed character (ASCII code: 12)
\n
Newline character (ASCII code: 10)
\r
Carriage return character (ASCII code: 13)
\t
Horizontal tab character (ASCII code: 9)
\v
Vertical tab character (ASCII code: 11)
\\
Backslash
\"
Double quotation
\'
Single quotation (apostrophe)
\xxx
Character whose code is xxx, where xxx is an octal number of at most three digits.
Operands
format
A string that defines how values should be formatted.
values
Values that are formatted according to format.
A value is either a number or a string.
When a numeric value is required, value can be a single or double quotation followed by a character,
instead of a normal number. For example, the command printf '%d' '"3' will print 51 on a typical
environment where character 3 has character code 51.
Exit status
The exit status of the printf built-in is zero unless there is any error.
Notes
The POSIX standard does not precisely define how multibyte characters should be handled by the built-in.
When you use the %s conversion specification with precision or the %c conversion specification, you may
obtain unexpected results if the formatted value contains a character that is represented by more than
one byte. Yash never prints only part of the bytes that represent a single multibyte character because
all multibyte characters are converted to wide characters when processed in the shell.
If the shell is not in the POSIXly-correct mode and the “long double” floating-point arithmetic is
supported on the running system, then “long double” is used for floating-point conversion specifications.
Otherwise, “double” is used.
PUSHD BUILT-IN
The pushd built-in pushes a directory into the directory stack.
Syntax
• pushd [-L|-P] [directory]
Description
The pushd built-in changes the working directory to directory in the same manner as the cd built-in and
adds it to the directory stack. If the working directory could not be changed successfully, the stack is
not modified.
Options
The pushd built-in accepts the following option as well as the options that can be used for the cd
built-in:
--remove-duplicates
If the new working directory has already been in the directory stack, the existing entry is removed
from the stack before the new directory is pushed into the stack.
Operands
directory
The pathname of the new working directory.
If directory is a single hyphen (‘-’), the value of the OLDPWD variable is assumed for the new
directory pathname, which is printed to the standard output.
If directory is an integer with a plus or minus sign, it is considered as an entry index of the
directory stack. The entry is removed from the stack and then pushed to the stack again.
If directory is omitted, the working directory is changed to the directory specified by the
--default-directory=... option. If that option is not specified either, the default is index +1.
Exit status
The exit status of the pushd built-in is zero unless there is any error.
Notes
The pushd built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
PWD BUILT-IN
The pwd built-in prints the current working directory.
Syntax
• pwd [-L|-P]
Description
The pwd built-in prints an absolute path to the shell’s current working directory to the standard output.
Options
-L, --logical
If the value of the PWD variable is an absolute path to the shell’s working directory and the path
does not contain any . or .. components, then the path is printed. Otherwise, the printed path is
the same as when the -P option is specified.
-P, --physical
The printed path does not contain any . or .. components, symbolic link components, or redundant
slashes.
The -L (--logical) and -P (--physical) options are mutually exclusive: only the last specified one is
effective. If neither is specified, -L is assumed.
Exit status
The exit status of the pwd built-in is zero unless there is any error.
Notes
The pwd built-in is a semi-special built-in.
READ BUILT-IN
The read built-in reads a line from the standard input.
Syntax
• read [-Aer] [-P|-p] variable...
Description
The read built-in reads a line of string from the standard input and assigns it to the specified
variables.
If the -r (--raw-mode) option is specified, all characters in the line are treated literally.
If the -r (--raw-mode) option is not specified, backslashes in the line are treated as quotations. If a
backslash is at the end of the line, it is treated as a line continuation. When the built-in reads the
next line, the PS2 variable is used as a prompt if the shell is interactive and the standard input is a
terminal.
The input line is subject to field splitting. The resulting words are assigned to variables in order. If
there are more words than variables, the last variable is assigned all the remaining words (as if the
words were not split). If the words are fewer than variables, the remaining variables are assigned empty
strings.
Options
-A, --array
Make the last variable an array. Instead of assigning a concatenation of the remaining words to a
normal variable, the words are assigned to an array.
-e, --line-editing
Use line-editing to read the line.
To use line-editing, all of the following conditions must also be met:
• The shell is interactive.
• The vi or emacs option is enabled.
• The standard input and standard error are connected to a terminal.
-P, --ps1
Print the PS1 variable as a prompt before reading the (first) line if the shell is interactive and
the standard input is a terminal.
-p prompt, --prompt=prompt
Print the specified prompt before reading the (first) line if the shell is interactive and the
standard input is a terminal.
-r, --raw-mode
Don’t treat backslashes as quotations.
Operands
variables
Names of variables to which input words are assigned.
Exit status
The exit status of the read built-in is zero unless there is any error.
Note that the exit status is non-zero if an end of input is encountered before reading the entire line.
Notes
The read built-in is a semi-special built-in.
The POSIX standard defines the -r option only: other options cannot be used in the POSIXly-correct mode.
The PS1R and PS1S variables affect the behavior of line-editing if the PS1 prompt is used. The same for
PS2.
READONLY BUILT-IN
The readonly built-in makes variables and functions read-only.
Syntax
• readonly [-pxX] [name[=value]...]
• readonly -f[p] [name...]
Description
The readonly built-in is equivalent to the typeset built-in with the -gr option.
Notes
The readonly built-in is a special built-in.
The POSIX standard defines the -p option only; other options cannot be used in the POSIXly-correct mode.
The POSIX does not allow using the option together with operands.
RETURN BUILT-IN
The return built-in returns from a function or script.
Syntax
• return [-n] [exit_status]
Description
When executed without the -n (--no-return) option, one of the following happens:
• If the shell is executing a function, the execution of the function is terminated.
• If the dot built-in is executing a script, the execution of the script is terminated.
• If the shell is executing a script during initialization, the execution of the script is terminated.
• If the shell is executing a trap, the execution of the trap is terminated for the currently handled
signal.
• Otherwise, the shell exits unless it is interactive.
When executed with the -n (--no-return) option, the built-in does nothing but return the specified
exit_status.
Options
-n, --no-return
Do not terminate a function, script, trap, or the shell.
Operands
exit_status
The exit status of the built-in.
The value must be a non-negative integer.
If omitted, the exit status of the last executed command is used. (But when the shell is executing a
trap, the exit status of the last command before the trap is used.)
Exit status
The exit status of the return built-in is defined by the exit_status operand. The exit status is used
also as the exit status of the terminated function, script, or the shell.
Notes
The return built-in is a special built-in.
The POSIX standard provides that the exit_status operand should be between 0 and 255 (inclusive). Yash
accepts integers larger than 255 as an extension.
In the POSIX standard, the behavior of the return built-in is defined only when the shell is executing a
function or script.
The POSIX standard defines no options for the return built-in; the built-in accepts no options in the
POSIXly-correct mode.
SET BUILT-IN
The set built-in sets shell options and positional parameters.
Syntax
• set [options] [operands]
• set -o
• set +o
The set built-in requires that all options precede operands. Any command line arguments after the first
operand are all treated as operands.
Description
When executed without any command arguments, the built-in prints a list of all existing variables to the
standard input in a form that can be reused as commands that will restore the variable definitions.
When -o is the only command argument, the built-in prints a list of shell options with their current
settings. When +o is the only command argument, the built-in prints commands that can be reused to
restore the current shell option settings.
In other cases, the built-in changes shell option settings and/or positional parameters.
Options
When one or more options are specified, the built-in enables or disables the shell options. A normal
hyphen-prefixed option enables a shell option. An option that is prefixed with a plus (+) instead of a
hyphen disables a shell option. For example, options -m, -o monitor, and --monitor enable the monitor
option and options +m, +o monitor, ++monitor disable it.
The name of a long option is case-insensitive and may include irrelevant non-alphanumeric characters,
which are ignored. For example, options --le-comp-debug and --LeCompDebug are equivalent. If no is
prepended to the name of a long option, the meaning is reversed. For example, --noallexport is equivalent
to ++allexport and ++nonotify to --notify.
An option can be specified in one of the following forms:
• a long option e.g. --allexport
• an -o option with a option name specified as the argument e.g. -o allexport
• a single-character option e.g. -a
Not all options can be specified as single-character options.
The available options are:
all-export (-a)
When enabled, all variables are automatically exported when assigned.
brace-expand
This option enables brace expansion.
case-glob
(Enabled by default) When enabled, pattern matching is case-sensitive in pathname expansion.
clobber (+C)
(Enabled by default) When enabled, the > redirection behaves the same as the >| redirection.
cur-async, cur-bg, cur-stop
(Enabled by default) These options affect choice of the current job (cf. job ID).
dot-glob
When enabled, periods at the beginning of filenames are not treated specially in pathname expansion.
emacs
This option enables line-editing in the emacs mode.
empty-last-field
When enabled, field splitting does not remove the last field even if it is empty.
err-exit (-e)
When enabled, if a pipeline ends with a non-zero exit status, the shell immediately exits unless the
following suppress condition is met:
• the pipeline is a condition of an if command or while or until loop;
• the pipeline is prefixed by !; or
• the pipeline is a single compound command other than a subshell grouping.
err-return
This option is like the err-exit option, but the return built-in is executed instead of the shell
exiting on a non-zero exit status. Unlike err-exit, the suppress condition does not apply inside a
function, subshell grouping, or script file.
exec (+n)
(Enabled by default) Commands are actually executed only when this option is enabled. Otherwise,
commands are just parsed and not executed. Disabling this option may be useful for syntax checking.
In an interactive shell, this option is always assumed enabled.
extended-glob
This option enables extension in pathname expansion.
for-local
(Enabled by default) If a for loop is executed within a function, this option causes the iteration
variable to be created as a local variable, even if the variable already exists globally. This option
has no effect if the POSIXly-correct mode is active.
glob (+f)
(Enabled by default) This option enables pathname expansion.
hash-on-def (-h)
When a function is defined when this option is enabled, the shell immediately performs command path
search for each command that appears in the function and caches the command’s full path.
hist-space
When enabled, command lines that start with a whitespace are not saved in command history.
ignore-eof
When enabled, an interactive shell does not exit when EOF (end of file) is input. This prevents the
shell from exiting when you accidentally hit Ctrl-D.
le-always-rp, le-comp-debug, le-conv-meta, le-no-conv-meta, le-predict, le-predict-empty, le-prompt-sp,
le-visible-bell
See shell options on line-editing.
mark-dirs
When enabled, resulting directory names are suffixed by a slash in pathname expansion.
monitor (-m)
This option enables job control. This option is enabled by default for an interactive shell.
notify (-b)
When the status of a job changes when this option is enabled, the shell immediately notifies at any
time. This option overrides the notify-le option.
notify-le
This option is similar to the notify option, but the status change is notified only while the shell
is waiting for input with line-editing.
null-glob
When enabled, in pathname expansion, patterns that do not match any pathname are removed from the
command line rather than left as is.
pipe-fail
When enabled, the exit status of a pipeline is zero if and only if all the subcommands of the
pipeline exit with an exit status of zero.
posixly-correct
This option enables the POSIXly-correct mode.
trace-all
(Enabled by default) When this option is disabled, the x-trace option is temporarily disabled while
the shell is executing commands defined in the COMMAND_NOT_FOUND_HANDLER, PROMPT_COMMAND, or
YASH_AFTER_CD variable.
unset (+u)
(Enabled by default) When enabled, an undefined parameter is expanded to an empty string in parameter
expansion and treated as zero in arithmetic expansion. When disabled, expansion of an undefined
parameter results in an error.
verbose (-v)
When enabled, the shell prints each command line to the standard error before parsing and executing
it.
vi
This option enables line-editing in the vi mode. This option is enabled by default in an interactive
shell if the standard input and error are both terminals.
x-trace (-x)
When enabled, the results of expansion are printed to the standard error for each simple command
being executed. When printed, each line is prepended with an expansion result of the PS4 variable.
See also the trace-all option.
Operands
If one or more operands are passed to the set built-in, current positional parameters are all removed and
the operands are set as new positional parameters. If the -- separator (cf. syntax of command arguments)
is passed, the positional parameters are set even when there are no operands, in which case new
positional parameters will be nothing.
Exit status
The exit status of the set built-in is zero unless there is any error.
Notes
The set built-in is a special built-in.
In the POSIX standard, available shell options are much limited. The standard does not define:
• long options such as --allexport,
• prepending no to negate an option,
• using uppercase letters and/or non-alphanumeric characters in option names
The options defined in the standard are:
• -a, -o allexport
• -e, -o errexit
• -m, -o monitor
• -C, -o noclobber
• -n, -o noexec
• -f, -o noglob
• -b, -o notify
• -u, -o nounset
• -v, -o verbose
• -x, -o xtrace
• -h
• -o ignoreeof
• -o nolog
• -o vi
Yash does not support the nolog option, which prevents function definitions from being added to command
history.
SHIFT BUILT-IN
The shift built-in removes some positional parameters or array values.
Syntax
• shift [-A array] [count]
Description
The shift built-in removes the first count positional parameters or array values, where count is
specified by the operand.
Options
-A array, --array=array
Remove first count values of array instead of positional parameters.
Operands
count
The number of positional parameters or array values to be removed.
It is an error if the actual number of positional parameters or array values is less than count. If
omitted, the default value is one. If negative, the last -count positional parameters or array values
are removed instead of the first ones.
Exit status
The exit status of the shift built-in is zero unless there is any error.
Notes
The shift built-in is a special built-in.
The number of positional parameters can be obtained with the # special parameter. The number of array
values can be obtained with ${array[#]}.
The POSIX standard defines no options for the shift built-in; the built-in accepts no options in the
POSIXly-correct mode.
Negative operands are not allowed in the POSIXly-correct mode.
SUSPEND BUILT-IN
The suspend built-in suspends the shell.
Syntax
• suspend [-f]
Description
The suspend built-in sends a SIGSTOP signal to all processes in the process group to which the shell
process belongs. The signal suspends the processes (including the shell). The suspended processes resume
when they receive a SIGCONT signal.
If the shell is interactive and its process group ID is equal to the process ID of the session leader,
the shell prints a warning message and refuses to send a signal unless the -f (--force) option is
specified. (In such a case, there is no other job-controlling shell that can send a SIGCONT signal to
resume the suspended shell, so the shell could never be resumed.)
Options
-f, --force
Suppress warnings that would prevent the shell from sending a signal.
Exit status
The exit status is zero if the signal was successfully sent and non-zero otherwise.
Notes
The suspend built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
TEST BUILT-IN
The test built-in evaluates an expression.
Syntax
• test expression
• [ expression ]
The test built-in does not distinguish options and operands; all command line arguments are interpreted
as expression. If the built-in is executed with the name [, expression must be followed by ].
Description
The test built-in evaluates expression as a conditional expression that is made up of operators and
operands described below. The exit status is 0 if the condition is true and 1 otherwise.
The unary operators below test a file. If the operand file is a symbolic link, the file referred to by
the link is tested (except for the -h and -L operators).
-b file
file is a block special file
-c file
file is a character special file
-d file
file is a directory
-e file
file exists
-f file
file is a regular file
-G file
file's group ID is same as the shell’s effective group ID
-g file
file's set-group-ID flag is set
-h file
same as -L
-k file
file's sticky bit is set
-L file
file is a symbolic link
-N file
file has not been accessed since last modified
-O file
file's user ID is same as the shell’s effective user ID
-p file
file is a FIFO (named pipe)
-r file
file is readable
-S file
file is a socket
-s file
file is not empty
-u file
file's set-user-ID flag is set
-w file
file is writable
-x file
file is executable
The unary operator below tests a file descriptor:
-t fd
fd is associated with a terminal
The unary operators below test a string:
-n string
string is not empty
-z string
string is empty
The unary operator below tests a shell option:
-o ?option
option is a valid shell option name
-o option
option is a valid shell option name that is enabled
The binary operators below compare files. Non-existing files are considered older than any existing
files.
file1 -nt file2
file1 is newer than file2
file1 -ot file2
file1 is older than file2
file1 -ef file2
file1 is a hard link to file2
The binary operators below compare strings:
string1 = string2, string1 == string2
string1 is the same string as string2
string1 != string2
string1 is not the same string as string2
The binary operators below compare strings according to the alphabetic order in the current locale:
string1 === string2
string1 is equal to string2
string1 !== string2
string1 is not equal to string2
string1 < string2
string1 is less than string2
string1 <= string2
string1 is less than or equal to string2
string1 > string2
string1 is greater than string2
string1 >= string2
string1 is greater than or equal to string2
The binary operator below performs pattern matching:
string =~ pattern
extended regular expression pattern matches (part of) string
The binary operators below compare integers:
v1 -eq v2
v1 is equal to v2
v1 -ne v2
v1 is not equal to v2
v1 -gt v2
v1 is greater than v2
v1 -ge v2
v1 is greater than or equal to v2
v1 -lt v2
v1 is less than v2
v1 -le v2
v1 is less than or equal to v2
The binary operators below compare version numbers:
v1 -veq v2
v1 is equal to v2
v1 -vne v2
v1 is not equal to v2
v1 -vgt v2
v1 is greater than v2
v1 -vge v2
v1 is greater than or equal to v2
v1 -vlt v2
v1 is less than v2
v1 -vle v2
v1 is less than or equal to v2
The operators below can be used to make complex expressions:
! expression
negate (reverse) the result
( expression )
change operator precedence
expression1 -a expression2
logical conjunction (and)
expression1 -o expression2
logical disjunction (or)
If the expression is a single word without operators, the -n operator is assumed. An empty expression
evaluates to false.
Comparison of version numbers
Comparison of version numbers is similar to comparison of strings in alphabetic order. The
differences are:
• Adjacent digits are treated as an integer. Integers are compared in mathematical order rather
than alphabetic order.
• Digits are considered larger than any non-digit characters.
For example, version numbers 0.1.2-3 and 00.001.02-3 are equal and 0.2.1 is smaller than 0.10.0.
Exit status
The exit status of the test built-in is 0 if expression is true and 1 otherwise. The exit status is 2 if
expression cannot be evaluated because of a syntax error or any other reasons.
Notes
Complex expressions may cause confusion and should be avoided. Use the shell’s compound commands. For
example, [ 1 -eq 1 ] && [ -t = 1 ] && ! [ foo ] is preferred over [ 1 -eq 1 -a -t = 1 -a ! foo ].
The POSIX standard provides that the exit status should be larger than 1 on error. The POSIX standard
does not define the following operators: -G, -k, -N, -O, -nt, -ot, -ef, ==, ===, !==, <, <=, >, >=, =~,
-veq, -vne, -vgt, -vge, -vlt, and -vle. POSIX neither specifies -o as a unary operator.
TIMES BUILT-IN
The times built-in prints CPU time usage.
Syntax
• times
Description
The times built-in prints the CPU times consumed by the shell process and its child processes to the
standard output.
The built-in prints two lines: the first line shows the CPU time of the shell process and the second one
that of its child processes (not including those which have not terminated). Each line shows the CPU
times consumed in the user and system mode.
Exit status
The exit status of the times built-in is zero unless there is any error.
Notes
The times built-in is a special built-in.
TRAP BUILT-IN
The trap built-in sets or prints signal handlers.
Syntax
• trap
• trap action signal...
• trap signal_number [signal...]
• trap -p [signal...]
Description
The trap built-in sets or prints actions that are taken when the shell receives signals. (Those actions
are called traps.)
When executed with action and one or more signals, the built-in sets the traps for signals to action. If
the shell receives one of the signals, the action will be taken.
If the first operand is signal_number instead of action, the built-in resets the traps for signal_number
and signals as if action was -.
When executed with the -p (--print) option or with no operands, the built-in prints currently set traps
to the standard output in a format that can be executed as commands that restore the current traps. If
one or more signals are specified, only those signals are printed. Otherwise, all signals with
non-default actions are printed. (In some situations, however, the built-in may print previous trap
settings instead of the current. See notes below.)
Options
-p, --print
Print current trap settings.
Operands
action
An action that will be taken when signal is received.
If action is a single hyphen (-), the action is reset to the default action that is defined by the
operating system. If action is an empty string, the signal is ignored on receipt. Otherwise, action
is treated as a command string: the string is parsed and executed as commands when the signal is
received. (If a signal is received while a command is being executed, the action is taken just after
the command finishes.)
signal
The number or name of a signal.
If signal is number 0 or name EXIT, it is treated as a special imaginary signal that is always
received when the shell exits. The action set for this signal is taken when the shell exits normally.
signal_number
This is like signal, but must be a number.
Exit status
The exit status of the trap built-in is zero unless there is any error.
Notes
The trap built-in is a special built-in.
The POSIX standard defines no options for the trap built-in; the built-in accepts no options in the
POSIXly-correct mode.
The POSIX standard requires that signal names must be specified without the SIG-prefix, like INT and
QUIT. As an extension, yash accepts SIG-prefixed names like SIGINT and SIGQUIT and treats signal names
case-insensitively.
Reusing output of the built-in
Output of the trap built-in can be saved in a variable, which can be later executed by the eval
built-in to restore the traps.
saved_traps=$(trap)
trap '...' INT
eval "$saved_traps"
There are some tricks behind the scenes to allow this idiom. You use a command substitution to save
the output of the trap built-in in the variable. The command substitution is executed in a subshell.
The subshell resets all traps (except ignored ones) at the beginning of itself. This seemingly would
result in (almost) empty output from the built-in that would fail to restore the traps as expected.
To avoid that pitfall, POSIX requires the shell to follow one of the two options below:
• If a command substitution just contains a single trap built-in, traps should not be reset when
the subshell is started to execute the built-in; or
• A subshell always resets the traps but remembers the previous traps. If the trap built-in is
executed in the subshell but no other trap built-in has been executed to modify traps in the
subshell, then the built-in should print the remembered traps.
Yash obeys the second.
TRUE BUILT-IN
The true built-in does nothing successfully.
Syntax
• true
Description
The true built-in does nothing. Any command line arguments are ignored.
Exit status
The exit status of the true built-in is zero.
Notes
The true built-in is a semi-special built-in.
The true and colon built-ins have the same effect, but true is a semi-special built-in while colon is a
special.
TYPE BUILT-IN
The type built-in identifies a command.
Syntax
• type [-abefkp] [command...]
Description
The type built-in is equivalent to the command built-in with the -V option.
Notes
The POSIX standard does not define the relation between the type and command built-ins. The standard does
not define options for the type built-in.
At least one command operand must be specified in the POSIXly-correct mode.
The type built-in is a semi-special built-in.
TYPESET BUILT-IN
The typeset built-in prints or sets variables or functions.
Syntax
• typeset [-gprxX] [variable[=value]...]
• typeset -f[pr] [function...]
Description
If executed without the -f (--functions) option, the typeset built-in prints or sets variables to the
standard output. Otherwise, it prints or sets functions.
If executed with the -p (--print) option, the built-in prints the variables or functions specified by
operands. Without the option, it sets variables or functions. If no operands are specified, it prints all
existing variables or functions, regardless of whether the -p (--print) option is specified.
Options
-f, --functions
Print or set functions rather than variables.
-g, --global
When setting a new variable, the variable will be a global variable if this option is specified.
Without this option, the variable would be a local variable.
When printing variables, all existing variables including global variables are printed if this option
is specified. Without this option, only local variables are printed.
-p, --print
Print variables or functions in a form that can be parsed and executed as commands that will restore
the currently set variables or functions.
-r, --readonly
When setting variables or functions, make them read-only.
When printing variables or functions, print read-only variables or functions only.
-x, --export
When setting variables, mark them for export, so that they will be exported to external commands.
When printing variables, print exported variables only.
-X, --unexport
When setting variables, cancel exportation of the variables.
Operands
variable (without value)
The name of a variable that is to be set or printed.
Without the -p (--print) option, the variable is defined (if not yet defined) but its value is not
set nor changed. Variables that are defined without values are treated as unset in parameter
expansion.
variable=value
The name of a variable and its new value.
The value is assigned to the variable (regardless of the -p (--print) option).
function
The name of an existing function that is to be set or printed.
Exit status
The exit status of the typeset built-in is zero unless there is any error.
Notes
A global variable cannot be newly defined if a local variable has already been defined with the same
name. The local variable will be set regardless of the -g (--global) option.
The typeset built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with
unspecified behavior.
The export and readonly built-ins are equivalent to the typeset built-in with the -gx and -gr options,
respectively. The local built-in is equivalent to the typeset built-in except that the -f (--functions)
and -g (--global) options cannot be used.
ULIMIT BUILT-IN
The ulimit built-in sets or prints a resource limit.
Syntax
• ulimit -a [-H|-S]
• ulimit [-H|-S] [-efilnqrstuvx] [limit]
Description
The ulimit built-in sets or prints a resource limit.
If executed with the -a (--all) option, the built-in prints the current limits for all resource types.
Otherwise, it sets or prints the limit of a single resource type. The resource type can be specified by
the options listed below. The resource limits will affect the current shell process and all commands
invoked from the shell.
Each resource type has two limit values: the hard and soft limit. You can change a soft limit freely as
long as it does not exceed the hard limit. You can decrease a hard limit but cannot increase it without a
proper permission.
When the -H (--hard) or -S (--soft) option is specified, the built-in sets or prints the hard or soft
limit, respectively. If neither of the options is specified, the built-in sets both the hard and soft
limit or prints the soft limit.
Options
-H, --hard
Set or print a hard limit.
-S, --soft
Set or print a soft limit.
-a, --all
Print all current limit settings.
The following options specify the type of resources. If none of them is specified, -f is the default. The
types of resources that can be set depend on the operating system.
-c, --core
Maximum size of core files created (in 512-byte blocks)
-d, --data
Maximum size of a process’s data segment (in kilobytes)
-e, --nice
Maximum scheduling priority (‘nice’)
-f, --fsize
Maximum size of files created by a process (in 512-byte blocks)
-i, --sigpending
Maximum number of pending signals
-l, --memlock
Maximum memory size that can be locked into RAM (in kilobytes)
-m, --rss
Maximum size of a process’s resident set (in kilobytes)
-n, --nofile
Maximum file descriptor + 1
-q, --msgqueue
Maximum size of POSIX message queues
-r, --rtprio
Maximum real-time scheduling priority
-s, --stack
Maximum size of a process’s stack (in kilobytes)
-t, --cpu
Maximum CPU time that can be used by a process (in seconds)
-u, --nproc
Maximum number of processes for a user
-v, --as
Maximum size of memory used by a process (in kilobytes)
-x, --locks
Maximum number of file locks
Operands
limit
A limit to be set.
The value must be a non-negative integer or one of hard, soft, and unlimited. If value is hard or
soft, the new limit is set to the current hard or soft limit. If limit is not specified, the current
limit is printed.
Exit status
The exit status of the ulimit built-in is zero unless there is any error.
Notes
The POSIX standard defines no options other than -f. It neither defines hard, soft, or unlimited for
limit values.
The ulimit built-in is a semi-special built-in.
UMASK BUILT-IN
The umask built-in sets or prints the file mode creation mask.
Syntax
• umask mask
• umask [-S]
Description
If executed without the mask operand, the built-in prints the current file mode creation mask of the
shell to the standard output in a form that can later be used as mask to restore the current mask.
Otherwise, the built-in sets the file mode creation mask to mask.
Options
-S, --symbolic
Print in the symbolic form instead of the octal integer form.
Operands
mask
The new file mode creation mask either in the symbolic or octal integer form.
Octal integer form
In the octal integer form, the mask is specified as a non-negative octal integer that is the sum of
the following permissions:
0400
read by owner
0200
write by owner
0100
execute/search by owner
0040
read by group
0020
write by group
0010
execute/search by group
0004
read by others
0002
write by others
0001
execute/search by others
Symbolic form
In the symbolic form, the mask is specified as a symbolic expression that denotes permissions that
are not included in the mask.
The entire expression is one or more clauses separated by comma. A clause is a sequence of whos
followed by one or more actions.
A who is one of:
u
owner
g
group
o
others
a
all of owner, group, and others
An empty sequence of whos is equivalent to who a.
An action is an operator followed by permission. An operator is one of:
=
set who's permission to permission
+
add permission to who's permission
-
remove permission from who's permission
and permission is one of:
r
read
w
write
x
execute/search
X
execute/search (only if some user already has execute/search permission)
s
set-user-ID and set-group-ID
u
user’s current permissions
g
group’s current permissions
o
others' current permissions
but more than one of r, w, x, X, and s can be specified after a single operand.
For example, the command umask u=rwx,go+r-w
• unmasks the user’s read, write, and execute/search permissions;
• unmasks the group’s and others' read permission; and
• masks the group’s and others' write permission.
Exit status
The exit status of the umask built-in is zero unless there is any error.
Notes
The umask built-in is a semi-special built-in.
The POSIX standard does not require the default output format (used when the -S option is not specified)
to be the octal integer form.
UNALIAS BUILT-IN
The unalias built-in undefines aliases.
Syntax
• unalias name...
• unalias -a
Description
The unalias built-in removes the definition of the aliases specified by operands.
Options
-a, --all
Undefine all aliases.
Operands
name
The name of an alias to be undefined.
Exit status
The exit status of the unalias built-in is zero unless there is any error. It is an error to specify the
name of a non-existing alias as name.
Notes
The unalias built-in is a semi-special built-in.
UNSET BUILT-IN
The unset built-in undefines variables or functions.
Syntax
• unset [-fv] [name...]
Description
The unset built-in removes the definition of the variables or functions specified by operands.
It is not an error if any of the specified variables or functions do not exist; they are silently
ignored.
Options
-f, --functions
Undefine functions.
-v, --variables
Undefine variables.
These options are mutually exclusive: only the last specified one is effective. If neither is specified,
-v is assumed.
Operands
name
The name of a variable or function to be undefined.
Exit status
The exit status of the unset built-in is zero unless there is any error.
Notes
The unset built-in is a special built-in.
Although yash does not do so, the POSIX standard allows removing a function if neither of the -f and -v
options is specified and the specified variable does not exist.
At least one name operand must be specified in the POSIXly-correct mode.
WAIT BUILT-IN
The wait built-in waits for jobs to terminate.
Syntax
• wait [job...]
Description
The wait built-in waits for background jobs to terminate. If job control is enabled, stopped jobs are
considered as terminated.
The built-in can be used to wait for asynchronous commands if job control is disabled.
If the shell receives a signal while the built-in is waiting and if a trap has been set for the signal,
then the trap is executed and the built-in immediately finishes (without waiting for the jobs). If the
shell receives a SIGINT signal when job control is enabled, the built-in aborts waiting.
If the shell is interactive, job-controlling, and not in the POSIXly-correct mode, the job status is
printed when the job is terminated or stopped.
Operands
job
The job ID of the job or the process ID of a process in the job.
If no jobs are specified, the built-in waits for all existing jobs.
If the specified job does not exist, the job is considered to have terminated with the exit status of
127.
Exit status
If no jobs were specified and the built-in successfully waited for all the jobs, the exit status is zero.
If one or more jobs were specified, the exit status is that of the last job.
If the built-in was aborted by a signal, the exit status is an integer (> 128) that denotes the signal.
If there was any other error, the exit status is between 1 and 126 (inclusive).
Notes
The wait built-in is a semi-special built-in.
The process ID of the last process of a job can be obtained by the ! special parameter. You can use the
jobs built-in as well to obtain process IDs of job processes.
AUTHOR
Yuki Watanabe <magicant@users.osdn.me>
Author.
2.49 2019-10-26 YASH(1)