Provided by: yash_2.35-2_amd64 bug

NAME

       yash - a POSIX-compliant command line shell

SYNOPSIS

       yash [options...] [--] [operands...]

INTRODUCTION

       Yet anther 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 SourceForge.jp.

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 --version option, the shell never performs the usual
       initialization or command execution. Instead, it just prints brief usage (for --help) or
       version information (for --version). If the --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

               •   reads ~/.yashrc as a default if not in the POSIXly-correct mode; or

               •   performs parameter expansion on the value of the ENV environment variable and
                   treats the expansion result as the name of the file to read if in the
                   POSIXly-correct mode.

           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.

       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.

           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. (In the POSIXly-correct mode, the standard
       input is redirected if and only if the shell is interactive, regardless of whether job
       control is on. Moreover, the SIGINT and SIGQUIT signals are ignored even if job control is
       on.)

       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...; donefor 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. If you omit the in token and the following words, you must also omit the
           semicolon before the do token. However, the shell does not complain about the
           existence of the semicolon if not in the POSIXly-correct mode. The command list may be
           empty if not 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.

           Each word is assigned as a local variable except in the POSIXly-correct mode. If the
           expansion of the words yielded no words as a result, 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.

       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).

   Function definition
       The function definition command defines a function.

       Function definition syntax
           funcname ( ) compound_commandfunction funcname compound_commandfunction 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.

       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.

       @
           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, positional parameters are field-split rather than
           concatenated (in spite of the quotation). If there are no positional parameters, the
           expansion yields no word rather than an empty word.

           •   When there are no positional parameters, the command words echo 1 "$@" 2 is
               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 "$@" is 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 \$ when the shell is started. (In the POSIXly-correct mode, the initial value
               is 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.

           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_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 values of the array are concatenated into a single
           string. If parameter is the * or @ special parameter, all positional parameters are
           concatenated into a string. See the description of the * special parameter for how the
           values/positional parameters are separated in the result string. 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 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. The commands are parsed each time the command substitution is
       expanded.

   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.

   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 that are subject to field splitting. The following
           steps are taken for each split point found.

        2. If the split point includes one or more IFS non-whitespaces, any 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.

           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 or function,
               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.

        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).

       •   A special built-in is executed in the POSIXly-correct mode and the command arguments
           do not meet the syntax of the built-in’s arguments.

       •   An error occurs during redirection or assignment in a simple command whose command
           name is a special built-in and the shell is in the POSIXly-correct mode.

       •   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. 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:

           •   Signal handlers registered by the trap built-in are all reset in subshells except
               for ones whose action is set to “ignore”.

           •   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.

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 standard input of an asynchronous command is not automatically redirected to
           /dev/null (in the POSIXly-correct mode only).

       •   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 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 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 (unless in the POSIXly-correct mode).

       •   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 “finished” status is reported,

       •   the wait built-in successfully waited for the job to finish, or

       •   the disown built-in removed the job.

           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 -mset -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 --quietfc --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-inset -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-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.

               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
               Like the accept-line command, but:

               •   A hash sign (#) is inserted at the beginning of the line if there is none.

               •   Otherwise, the hash sign is removed from the beginning of the line.

               vi-command
                   #

               emacs
                   \^[#

           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.

           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 is temporarily disabled,

           •   the err-exit option is temporarily disabled, and

           •   traps are not executed.

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 mush 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.

       •   Global aliases are not substituted.

       •   Nested commands in a compound command must not be empty.

       •   Words expanded in a for loop are assigned as a global variable rather than a local.

       •   The first pattern in a case command cannot be esac.

       •   The function keyword cannot be used for function definition.

       •   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 are allowed.

       •   The commands in a command substitution of the form $(commands) are parsed every time
           the substitution is executed.

       •   Fractional numbers and the ++ and -- operators cannot be used in arithmetic expansion.

       •   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.

       •   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.

       •   asynchronous commands ignore the SIGINT and SIGQUIT signals even when job control is
           active. The standard input of asynchronous commands is redirected to /dev/null if the
           shell is not interactive, regardless of whether job control is active or not.

       •   Some built-ins behave differently. Especially, some command-line options 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.

       •   In mail checking, a notification message is printed if the file has been modified,
           regardless of whether the file is empty.

FORMAL DEFINITION OF COMMAND SYNTAX

       This chapter defines the syntax of shell commands as a parsing expression grammar.

       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').

       Below is a list of nonterminals of the grammar with corresponding parsing expressions. The
       list does not include rules for parsing contents and ends of here documents. In the
       POSIXly-correct mode, the grammar varies from the list below to disable non-POSIX
       functionalities.

       CompleteCommand
           SequenceEOF

       Sequence
           N* List*

       List
           Pipeline ((&& / ||) N* Pipeline)* ListSeparator

       Pipeline
           Bang?  Command (|N* Command)*

       Command
           CompoundCommandRedirection* /

           !RFunctionDefinition /

           !R SimpleCommand

       CompoundCommand
           Subshell / Grouping / IfCommand / ForCommand / WhileCommand / CaseCommand /
           FunctionCommand

       Subshell
           (Sequence)S*

       Grouping
           LeftBraceSequenceRightBrace

       IfCommand
           IfSequenceThen Sequence (Elif Sequence Then Sequence)* (Else Sequence)?  Fi

       ForCommand
           ForNameS* Separator? (InWord* Separator)?  DoSequenceDone

       WhileCommand
           (While / Until) SequenceDo Sequence Done

       CaseCommand
           CaseWordN* In N* CaseItem* Esac

       CaseItem
           !Esac ((S*)?  Word (| S* Word)* )Sequence (;; / &Esac)

       FunctionCommand
           FunctionWord ((S* ))?  N* CompoundCommandRedirection*

       FunctionDefinition
           NameS* ( S* )N* CompoundCommandRedirection*

       SimpleCommand
           &(Word / Redirection) (Assignment / Redirection)* (Word / Redirection)*

       Assignment
           Name=Word /

           Name =(N* (Word N*)* )

       Name
           ![[:digit:]] [[:alnum:] _]+

       PortableName
           ![0-9] [0-9ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]+

       Word
           (WordElement / !SpecialChar .)+ S*

       WordElement
           \ . / ' (!' .)*  ' / "QuoteElement* " / Parameter / Arithmetic / CommandSubstitution

       QuoteElement
           \ ([$`"\] / NL) / Parameter / Arithmetic / CommandSubstitution /

           ![`"\] .

       Parameter
           $ [@*#?-$!  [:digit:]] / $PortableName / $ParameterBody

       ParameterBody
           {ParameterNumber? (ParameterName / ParameterBody / Parameter) 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
           $(Sequence) / `CommandSubstitutionBody* `

       CommandSubstitutionBody
           \ [$`\] /

           !` .

       Redirection
           RedirectionFDRedirectionOperatorS* Word /

           RedirectionFD <(Sequence) /

           RedirectionFD >( Sequence )

       RedirectionFD
           [[:digit:]]*

       RedirectionOperator
           < / <> / > / >| / >> / >>| / <& / >& / << / <<- / <<<

       ListSeparator
           Separator / &N* /

           &) /

           &;;

       Separator
           ;N* / N+ / EOF

       N
           S* NL

       S
           [[:blank:]] / Comment

       Comment
           # (!NL .)*

       R
           Bang / LeftBrace / RightBrace / Case / Do / Done / Elif / Else / Esac / Fi / For / If
           / In / Then / Until / While

       Bang
           !D

       LeftBrace
           {D

       RightBrace
           }D

       Case
           caseD

       Do
           doD

       Done
           doneD

       Elif
           elifD

       Else
           elseD

       Esac
           esacD

       Fi
           fiD

       For
           forD

       Function
           functionD

       If
           ifD

       In
           inD

       Then
           thenD

       Until
           untilD

       While
           whileD

       D
           !WordS*

       SpecialChar
           [|&;<>()`\"' [:blank:]] / NL

       NL
           <newline>

       EOF
           !.

ALIAS BUILT-IN

       The alias built-in defines and/or prints aliases.

   Syntaxalias [-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.

   Syntaxarrayarray 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.

   Syntaxbg [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.

   Syntaxbindkey -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 not defined in the POSIX standard.

BREAK BUILT-IN

       The break built-in aborts a loop being executed.

   Syntaxbreak [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.

CD BUILT-IN

       The cd built-in changes the working directory.

   Syntaxcd [-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.

       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.

   Syntaxcommand [-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.

   Syntaxcomplete [-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 not defined in the POSIX standard.

CONTINUE BUILT-IN

       The continue built-in skips an iteration of a loop being executed.

   Syntaxcontinue [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.

DIRS BUILT-IN

       The dirs built-in prints the contents of the directory stack.

   Syntaxdirs [-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 not defined in the POSIX standard.

DISOWN BUILT-IN

       The disown built-in removes jobs.

   Syntaxdisown [-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 not defined in the POSIX standard.

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 that is not in the POSIXly-correct mode will immediately exit 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.

   Syntaxecho [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.

EVAL BUILT-IN

       The eval built-in evaluates operands as commands.

   Syntaxeval [-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.

   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.

   Syntaxexec [-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.

   Syntaxexit [-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.

   Syntaxexport [-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.

   Syntaxfalse

   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.

   Syntaxfc [-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, vi 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 -lwithout -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.

   Syntaxfg [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.

       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.

   Syntaxgetopts 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.

HASH BUILT-IN

       The hash built-in remembers, forgets, or reports command locations.

   Syntaxhash 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.

HELP BUILT-IN

       The help built-in prints usage of built-ins.

   Syntaxhelp [built-in...]

   Description
       The help built-in prints a description of built-ins.

       The built-in extracts part of the output of man yash and prints it to the standard output.
       Therefore, the manual page of yash must have been installed for the built-in to work.
       Depending on the formatting style of the man command, the built-in may not work as
       expected.

   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 not defined in the POSIX standard.

       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.

   Syntaxhistory [-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 not defined in the POSIX standard.

       Command history cannot be modified during line-editing.

JOBS BUILT-IN

       The jobs built-in reports job status.

   Syntaxjobs [-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.

   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.

   Syntaxkill [-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.

POPD BUILT-IN

       The popd built-in pops a directory from the directory stack.

   Syntaxpopd [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 not defined in the POSIX standard.

PRINTF BUILT-IN

       The printf built-in prints formatted values.

   Syntaxprintf 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.

PUSHD BUILT-IN

       The pushd built-in pushes a directory into the directory stack.

   Syntaxpushd [-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 not defined in the POSIX standard.

PWD BUILT-IN

       The pwd built-in prints the current working directory.

   Syntaxpwd [-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.

   Syntaxread [-Ar] variable...

   Description
       The read built-in reads a line of string from the standard input and assigns it to the
       specified variables. If the shell is interactive and line-editing is enabled, you can use
       line-editing when inputting a line.

       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 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.

       -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.

   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.

READONLY BUILT-IN

       The readonly built-in makes variables and functions read-only.

   Syntaxreadonly [-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.

   Syntaxreturn [-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 eval built-in is executing a command string, the execution of the command is
           terminated.

       •   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, evaluated command, 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, evaluated
       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.

   Syntaxset [options] [operands]set -oset +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.

       err-exit (-e)
           When enabled, if a pipeline ends with a non-zero exit status, the shell immediately
           exits unless:

           •   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.

       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.

       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-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.

       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, undefined parameters are expanded to empty strings
           in parameter expansion. When disabled, expansion of 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.

   Syntaxshift [count]

   Description
       The shift built-in removes the first count positional parameters.

   Operands
       count
           The number of positional parameters to be removed.

           It is an error if the actual number of positional parameters is less than count. If
           omitted, the default value is one.

   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.

SUSPEND BUILT-IN

       The suspend built-in suspends the shell.

   Syntaxsuspend [-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 not defined in the POSIX standard.

TEST BUILT-IN

       The test built-in evaluates an expression.

   Syntaxtest 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 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 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: -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.

   Syntaxtimes

   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.

   Syntaxtraptrap 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.

   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 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.

TRUE BUILT-IN

       The true built-in does nothing successfully.

   Syntaxtrue

   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.

   Syntaxtype [-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.

TYPESET BUILT-IN

       The typeset built-in prints or sets variables or functions.

   Syntaxtypeset [-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 POSIX standard does not define the typeset built-in.

       The export and readonly built-ins are equivalent to the typeset built-in with the -gx and
       -gr options, respectively.

ULIMIT BUILT-IN

       The ulimit built-in sets or prints a resource limit.

   Syntaxulimit -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.

UMASK BUILT-IN

       The umask built-in sets or prints the file mode creation mask.

   Syntaxumask maskumask [-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.

   Syntaxunalias 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.

   Syntaxunset [-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.

   Syntaxwait [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.

   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.sourceforge.jp>
           Author.

  2.35                                      2013-06-08                                    YASH(1)