1YASH(1)                                                                YASH(1)
2
3
4

NAME

6       yash - a POSIX-compliant command line shell
7

SYNOPSIS

9       yash [options...] [--] [operands...]
10

INTRODUCTION

12       Yet another shell (yash) is a command line shell for UNIX-like
13       operating systems. The shell conforms to the POSIX.1-2008 standard (for
14       the most parts), and actually is more conforming than other
15       POSIX-conforming shells. Moreover, it has many features that are used
16       for interactive use, such as command history and command line editing.
17
18       This program can be freely modified and redistributed under the terms
19       of GNU General Public License (Version 2). Use of this program is all
20       at your own risk. There is no warranty and the author is not
21       responsible for any consequences caused by use of this program.
22
23       This manual can be freely modified and redistributed under the terms of
24       Creative Commons Attribution-ShareAlike 2.1 Japan.
25
26       Yash is developed and maintained by 渡邊裕貴 (WATANABE Yuki) aka
27       Magicant. Yash development project and Yash’s homepage are hosted by
28       OSDN.
29

INVOCATION

31       When invoked as a program, yash performs the predefined initialization
32       steps and repeatedly reads and executed commands. Command line
33       arguments given in the invocation determines how the shell initializes
34       itself and executes commands.
35
36   Command line arguments
37       The syntax of command line arguments for yash conforms to POSIX. As
38       defined in POSIX, arguments are separated into options and operands.
39       For more detailed explanation about options and operands, see Command
40       argument syntax. All options must come before operands. The
41       interpretation of operands depends on options specified.
42
43       When you specify the -c (--cmdline) option, you must give at least one
44       operand. The shell interprets and executes the first operand as a
45       command string. The second operand, if any, is used to initialize the 0
46       special parameter. The other operands, if any, are used to initialize
47       the positional parameters. When the -c (--cmdline) option is specified,
48       the shell does not read any file or the standard input (unless the dot
49       built-in is used).
50
51       If you specify the -s (--stdin) option, the shell reads the standard
52       input, interprets the input as commands, and executes them. All the
53       operands given are used to initialize the positional parameters. The 0
54       special parameter is initialized to the name the shell is invoked as.
55
56       If you specify neither the -c (--cmdline) nor -s (--stdin) option, the
57       shell reads a file, interprets the file contents as commands, and
58       executes them. The first operand specifies the pathname of the file.
59       The remaining operands are used to initialize the positional
60       parameters. If you do not give any operands, the shell reads the
61       standard input as if the -s (--stdin) option is specified.
62
63       You cannot use both the -c (--cmdline) and -s (--stdin) options at a
64       time.
65
66       If you specify either the --help or -V (--version) option, the shell
67       never performs the usual initialization or command execution. Instead,
68       it just prints brief usage (for --help) or version information (for -V
69       and --version). If the -V (--version) option is accompanied by the -v
70       (--verbose) option, the shell prints a list of the available optional
71       features as well.
72
73       If you specify the -i (--interactive) option, the shell goes into the
74       interactive mode. If you specify the +i (++interactive) option,
75       conversely, the shell never goes into the interactive mode.
76
77       If you specify the -l (--login) option, the shell behaves as a login
78       shell.
79
80       The --noprofile, --norcfile, --profile, and --rcfile options determine
81       how the shell is initialized (see below for details).
82
83       In addition to the options described above, you can specify options
84       that can be specified to the set built-in.
85
86       If the first operand is - and the options and the operands are not
87       separated by --, the first operand is ignored.
88
89   Initialization of yash
90       Yash initializes itself as follows:
91
92        1. Yash first parses the name it was invoked as. If the name starts
93           with -, the shell behaves as a login shell. If the name is sh
94           (including names such as /bin/sh), the shell goes into the
95           POSIXly-correct mode.
96
97        2. If no operands are given and the standard input and standard error
98           are both connected to a terminal, the shell goes into the
99           interactive mode unless the +i (++interactive) option is specified.
100
101        3. Job control is automatically enabled in an interactive shell unless
102           the +m (++monitor) option is specified.
103
104        4. Yash reads and executes commands from the following files (unless
105           the real and effective user IDs of the shell process are different
106           or the real and effective group IDs of the shell process are
107           different):
108
109            1. If it is behaving as a login shell, the shell reads the file
110               specified by the --profile=filename option unless the
111               --noprofile option is specified or the shell is in the
112               POSIXly-correct mode.
113
114               If the --profile=filename option is not specified, the shell
115               reads ~/.yash_profile as a default.
116
117            2. If in the interactive mode, the shell reads the file specified
118               by the --rcfile=filename option unless the --norcfile option is
119               specified.
120
121               If the --rcfile=filename option is not specified, the shell
122               instead reads the following files:
123
124               •   If not in the POSIXly-correct mode, the shell reads
125                   ~/.yashrc. If it cannot be read, the shell searches
126                   YASH_LOADPATH for a file named initialization/default.
127
128               •   If in the POSIXly-correct mode, the shell performs
129                   parameter expansion on the value of the ENV environment
130                   variable and treats the expansion result as the name of the
131                   file to read.
132
133           Note
134           Yash never automatically reads /etc/profile, /etc/yashrc, nor
135           ~/.profile.
136

SYNTAX

138       The shell reads, parses, and executes command line by line. If there is
139       more than one command on a line, all the commands are parsed before
140       executed. If a command is continued to next lines, the shell reads more
141       enough lines to complete the command. On a syntax error, the shell
142       neither reads nor executes any more commands.
143
144   Tokens and keywords
145       A command is composed of one or more tokens. In the shell syntax, a
146       token is a word that is part of a command. Normally, tokens are
147       separated by whitespaces, that is, the space or tab character.
148       Whitespaces inside a command substitution or a parameter expansion,
149       however, do not separate tokens.
150
151       The following symbols have special meanings in the shell syntax and in
152       most cases separate tokens:
153
154           ; & | < > ( ) [newline]
155
156       The following symbols do not separate tokens, but have syntactic
157       meanings:
158
159           $ ` \ " ' * ? [ # ~ = %
160
161       The following tokens are treated as keywords depending on the context
162       in which they appear:
163
164           ! { } [[ case do done elif else esac fi
165           for function if in then until while
166
167       A token is treated as a keyword when:
168
169       •   it is the first token of a command,
170
171       •   it follows another keyword (except case, for, and in), or
172
173       •   it is a non-first token of a command and is supposed to be a
174           keyword to compose a composite command.
175
176       If a token begins with #, then the # and any following characters up to
177       the end of the line are treated as a comment, which is completely
178       ignored in syntax parsing.
179
180   Quotations
181       If you want whitespaces, separator characters, or keywords described
182       above to be treated as a normal characters, you must quote the
183       characters using appropriate quotation marks. Quotation marks are not
184       treated as normal characters unless they are themselves quoted. You can
185       use the following three quotation marks:
186
187       •   A backslash (\) quotes a character that immediately follows.
188
189           The only exception about a backslash is the case where a backslash
190           is followed by a newline. In this case, the two characters are
191           treated as a line continuation rather than a newline being quoted.
192           The two characters are removed from the input and the two lines
193           surrounding the line continuation are concatenated into a single
194           line.
195
196       •   A pair of single-quotation marks (') quote any characters between
197           them except another single-quotation. Note that newlines can be
198           quoted using single-quotations.
199
200       •   Double-quotation marks (") are like single-quotations, but they
201           have a few exceptions: Parameter expansion, command substitution,
202           and arithmetic expansion are interpreted as usual even between
203           double-quotations. A backslash between double-quotations is treated
204           as a quotation mark only when it is followed by $, `, ", \, or a
205           newline; other backslashes are treated as normal characters.
206
207   Aliases
208       Tokens that compose a command are subject to alias substitution. A
209       token that matches the name of an alias that has already been defined
210       is substituted with the value of the alias before the command is
211       parsed.
212
213       Tokens that contain quotations are not alias-substituted since an alias
214       name cannot contain quotation marks. Keywords and command separator
215       characters are not alias-substituted either.
216
217       There are two kinds of aliases: normal aliases and global aliases. A
218       normal alias can only substitute the first token of a command while a
219       global alias can substitute any part of a command. Global aliases are
220       yash extension that is not defined in POSIX.
221
222       If a token is alias-substituted with the value of a normal alias that
223       ends with a whitespace, the next token is exceptionally subject to
224       alias substitution for normal aliases.
225
226       The results of alias substitution are again subject to alias
227       substitution for other aliases (but not for the aliases that have been
228       already applied).
229
230       You can define aliases using the alias built-in and remove using the
231       unalias built-in.
232
233   Simple commands
234       A command that does not start with a keyword token is a simple command.
235       Simple commands are executed as defined in Execution of simple
236       commands.
237
238       If the first and any number of following tokens of a simple command
239       have the form name=value, they are interpreted as variable assignments.
240       A variable name must consist of one or more alphabets, digits and/or
241       underlines (_) and must not start with a digit. The first token that is
242       not a variable assignment is considered as a command name and all the
243       following tokens (whether or not they have the form name=value) as
244       command arguments.
245
246       A variable assignment of the form var=(tokens) is interpreted as
247       assignment to an array. You can write any number of tokens between a
248       pair of parentheses. Tokens can be separated by not only spaces and
249       tabs but also newlines.
250
251   Pipelines
252       A pipeline is a sequence of one or more simple commands, compound
253       commands, and/or function definitions that are separated by |.
254
255       A pipeline that has more than one subcommand is executed by executing
256       each subcommand of the pipeline in a subshell simultaneously. The
257       standard output of each subcommand except the last one is redirected to
258       the standard input of the next subcommand. The standard input of the
259       first subcommand and the standard output of the last subcommand are not
260       redirected.
261
262       The exit status of the pipeline is that of the last subcommand unless
263       the pipe-fail option is enabled, in which case the exit status of the
264       pipeline is that of the last subcommand that exits with a non-zero exit
265       status. If all the subcommands exit with an exit status of zero, the
266       exit status of the pipeline is also zero.
267
268       A pipeline can be prefixed by !, in which case the exit status of the
269       pipeline is reversed: the exit status of the pipeline is 1 if that of
270       the last subcommand is 0, and 0 otherwise.
271
272       Korn shell treats a word of the form !(...) as an extended pathname
273       expansion pattern that is not defined in POSIX. In the POSIXly-correct
274       mode, the tokens ! and ( must be separated by one or more white spaces.
275
276           Note
277           When the execution of a pipeline finishes, at least the execution
278           of the last subcommand has finished since the exit status of the
279           last subcommand defines that of the whole pipeline. The execution
280           of other subcommands, however, may not have finished then. On the
281           other hand, the execution of the pipeline may not finish soon after
282           that of the last subcommand finished because the shell may choose
283           to wait for the execution of other subcommands to finish.
284
285           Note
286           The POSIX standard allows executing any of subcommands in the
287           current shell rather than subshells, though yash does not do so.
288
289   And/or lists
290       An and/or list is a sequence of one or more pipelines separated by &&
291       or ||.
292
293       An and/or list is executed by executing some of the pipelines
294       conditionally. The first pipeline is always executed. The other
295       pipelines are either executed or not executed according to the exit
296       status of the previous pipelines.
297
298       •   If two pipelines are separated by && and the exit status of the
299           first pipeline is zero, the second pipeline is executed.
300
301       •   If two pipelines are separated by || and the exit status of the
302           first pipeline is not zero, the second pipeline is executed.
303
304       •   In other cases, the execution of the and/or list ends: the second
305           and any remaining pipelines are not executed.
306
307       The exit status of an and/or list is that of the last pipeline that was
308       executed.
309
310       Normally, an and/or list must be terminated by a semicolon, ampersand,
311       or newline. See Command separators and asynchronous commands.
312
313   Command separators and asynchronous commands
314       The whole input to the shell must be composed of any number of and/or
315       lists separated by a semicolon or ampersand. A terminating semicolon
316       can be omitted if it is followed by ;;, ), or a newline. Otherwise, an
317       and/or list must be terminated by a semicolon or ampersand.
318
319       If an and/or list is terminated by a semicolon, it is executed
320       synchronously: the shell waits for the and/or list to finish before
321       executing the next and/or list. If an and/or list is terminated by an
322       ampersand, it is executed asynchronously: after the execution of the
323       and/or list is started, the next and/or list is executed immediately.
324       An asynchronous and/or list is always executed in a subshell and its
325       exit status is zero.
326
327       If the shell is not doing job control, the standard input of an
328       asynchronous and/or list is automatically redirected to /dev/null.
329       Signal handlers of the and/or list for the SIGINT and SIGQUIT signals
330       are set to “ignore” the signal so that the execution of the and/or list
331       cannot be stopped by those signals.
332
333       When the execution of an asynchronous and/or list is started, the shell
334       remembers its process ID. You can obtain the ID by referencing the !
335       special parameter. You can obtain the current and exit status of the
336       asynchronous list as well by using the jobs and wait built-ins.
337
338   Compound commands
339       Compound commands provide you with programmatic control of shell
340       command execution.
341
342       Grouping
343           A grouping is a list of commands that is treated as a simple
344           command.
345
346           Normal grouping syntax
347               { command...; }
348
349           Subshell grouping syntax
350               (command...)
351
352           The { and } tokens are keywords, which must be separated from other
353           tokens. The ( and ) tokens, however, are special separators that
354           need not to be separated.
355
356           In the normal grouping syntax, the commands in a grouping are
357           executed in the current shell. In the subshell grouping syntax, the
358           commands are executed in a new subshell.
359
360           In the POSIXly-correct mode, a grouping must contain at least one
361           command. If the shell is not in the POSIXly-correct mode, a
362           grouping may contain no commands.
363
364           The exit status of a grouping is that of the last command in the
365           grouping. If the grouping contains no commands, its exit status is
366           that of the last executed command before the grouping.
367
368       If command
369           The if command performs a conditional branch.
370
371           Basic if command syntax
372               if condition...; then body...; fi
373
374           Syntax with the else clause
375               if condition...; then body...; else body...; fi
376
377           Syntax with the elif clause
378               if condition...; then body...; elif condition...; then body...;
379               fi
380
381           Syntax with the elif clause
382               if condition...; then body...; elif condition...; then body...;
383               else body...; fi
384
385           For all the syntaxes, the execution of an if command starts with
386           the execution of the condition commands that follows the if token.
387           If the exit status of the condition commands is zero, the condition
388           is considered as “true”. In this case, the body commands that
389           follows the then token are executed and the execution of the if
390           command finishes. If the exit status of the condition commands is
391           non-zero, the condition is considered as “false”. In this case, the
392           condition commands for the next elif clause are executed and the
393           exit status is tested in the same manner as above. If there is no
394           elif clause, the body commands that follow the else token are
395           executed and the execution of the if command finishes. If there is
396           no else clause either, the execution of the if command just ends.
397
398           An if command may have more than one elif-then clause.
399
400           The exit status of an if command is that of the body commands that
401           were executed. The exit status is zero if no body commands were
402           executed, that is, all the conditions were false and there was no
403           else clause.
404
405       While and until loops
406           The while loop and until loop are simple loops with condition.
407
408           While loop syntax
409               while condition...; do body...; done
410
411           Until loop syntax
412               until condition...; do body...; done
413
414           If the shell is not in the POSIXly-correct mode, you can omit the
415           condition and/or body commands of a while/until loop.
416
417           The execution of a while loop is started by executing the condition
418           commands. If the exit status of the condition commands is zero, the
419           shell executes the body commands and returns to the execution of
420           the condition commands. The condition and body commands are
421           repeatedly executed until the exit status of the condition commands
422           is non-zero.
423
424               Note
425               The body commands are not executed at all if the first
426               execution of the condition commands yields a non-zero exit
427               status.
428
429           An until loop is executed in the same manner as a while loop except
430           that the condition to repeat the loop is reversed: the body
431           commands are executed when the exit status of the condition
432           commands is non-zero.
433
434           The exit status of a while/until loop is that of the last executed
435           body command. The exit status is zero if the body commands are
436           empty or were not executed at all.
437
438       For loop
439           The for loop repeats commands with a variable assigned one of given
440           values in each round.
441
442           For loop syntax
443               for varname in word...; do command...; done
444
445               for varname do command...; done
446
447           The word list after the in token may be empty, but the semicolon
448           (or newline) before the do token is required even in that case. The
449           words are not treated as keywords, but you need to quote separator
450           characters (such as & and |) to include them as part of a word. The
451           command list may be empty if not in the POSIXly-correct mode.
452
453           The varname must be a portable (ASCII-only) name in the
454           POSIXly-correct mode.
455
456           The execution of a for loop is started by expanding the words in
457           the same manner as in the execution of a simple command. If the in
458           and word tokens are omitted, the shell assumes the word tokens to
459           be "$@". Next, the following steps are taken for each word expanded
460           (in the order the words were expanded):
461
462            1. Assign the word to the variable whose name is varname.
463
464            2. Execute the commands.
465
466           By default, if a for loop is executed within a function, varname is
467           created as a local variable, even if it already exists globally.
468           Turning off the for-local shell option or enabling the
469           POSIXly-correct mode mode will disable this behavior.
470
471           If the expansion of the words yields no words, no variable is
472           created and the commands are not executed at all.
473
474           The exit status of a for loop is that of the last executed command.
475           The exit status is zero if the commands are not empty and not
476           executed at all. If the commands are empty, the exit status is that
477           of the last executed command before the for loop.
478
479           If the variable is read-only, the execution of the for loop is
480           interrupted and the exit status will be non-zero.
481
482       Case command
483           The case command performs a pattern matching to select commands to
484           execute.
485
486           Case command syntax
487               case word in caseitem... esac
488
489           Case item syntax
490               (patterns) command...;;
491
492           The word between the case and in tokens must be exactly one word.
493           The word is not treated as a keyword, but you need to quote
494           separator characters (such as & and |) to include them as part of
495           the word. Between the in and esac tokens you can put any number of
496           case items (may be none). You can omit the first ( token of a case
497           item and the last ;; token before the esac token. If the last
498           command of a case item is terminated by a semicolon, you can omit
499           the semicolon as well. The commands in a case item may be empty.
500
501           The patterns in a case item are one or more tokens each separated
502           by a | token.
503
504           The execution of a case command starts with subjecting the word to
505           the four expansions. Next, the following steps are taken for each
506           case item (in the order of appearance):
507
508            1. For each word in the patterns, expand the word in the same
509               manner as the word and test if the expanded pattern matches the
510               expanded word. (If a pattern is found that matches the word,
511               the remaining patterns are not expanded nor tested, so some of
512               the patterns may not be expanded. Yash expands and tests the
513               patterns in the order of appearance, but it may not be the case
514               for other shells.)
515
516            2. If one of the patterns was found to match the word in the
517               previous step, the commands in this case item are executed and
518               the execution of the whole case item ends. Otherwise, proceed
519               to the next case item.
520
521           The exit status of a case command is that of the commands executed.
522           The exit status is zero if no commands were executed, that is,
523           there were no case items, no matching pattern was found, or no
524           commands were associated with the matching pattern.
525
526           In the POSIXly-correct mode, the first pattern in a case item
527           cannot be esac (even if you do not omit the ( token).
528
529       Double-bracket command
530           The double-bracket command is a syntactic construct that works
531           similarly to the test built-in. It expands and evaluates the words
532           between the brackets.
533
534           Double-bracket command syntax
535               [[ expression ]]
536
537           The expression can be a single primary or combination of primaries
538           and operators. The expression syntax is parsed when the command is
539           parsed, not executed. Operators (either primary or non-primary)
540           must not be quoted, or it will be parsed as a normal word.
541
542           When the command is executed, operand words are subjected to the
543           four expansions, but not brace expansion, field splitting, or
544           pathname expansion.
545
546           In the double-bracket command, the following primaries from the
547           test built-in can be used:
548
549           Unary primaries
550               -b, -c, -d, -e, -f, -G, -g, -h, -k, -L, -N, -n, -O, -o, -p, -r,
551               -S, -s, -t, -u, -w, -x, -z
552
553           Binary primaries
554               -ef, -eq, -ge, -gt, -le, -lt, -ne, -nt, -ot, -veq, -vge, -vgt,
555               -vle, -vlt, -vne, ===, !==, =~, <, >
556
557           Additionally, some binary primaries can be used to compare strings,
558           which works slightly differently from those for the test built-in:
559           The = primary treats the right-hand-side operand word as a pattern
560           and tests if it matches the left-hand-side operand word. The ==
561           primary is the same as =. The != primary is negation of the =
562           primary (reverse result).
563
564           The operand word of a primary must be quoted if it is ]] or can be
565           confused with another primary operator.
566
567               Note
568               More primaries may be added in future versions of the shell.
569               You should quote any words that start with a hyphen.
570
571               Note
572               The <= and >= binary primaries cannot be used in the
573               double-bracket command because it cannot be parsed correctly in
574               the shell grammar.
575
576           The following operands (listed in the descending order of
577           precedence) can be used to combine primaries:
578
579           ( expression )
580               A pair of parentheses change operator precedence.
581
582           ! expression
583               An exclamation mark negates (reverses) the result.
584
585           expression && expression
586               A double ampersand represents logical conjugation (the “and”
587               operation). The entire expression is true if and only if the
588               operand expressions are both true. The left-hand-side
589               expression is first expanded and tested. The right-hand-side is
590               expanded only if the left-hand-side is true.
591
592           expression || expression
593               A double vertical line represents logical conjugation (the “or”
594               operation). The entire expression is false if and only if the
595               operand expressions are both false. The left-hand-side
596               expression is first expanded and tested. The right-hand-side is
597               expanded only if the left-hand-side is false.
598
599               Note
600               Unlike the test built-in, neither -a nor -o can be used as a
601               binary operator in the double-bracket command.
602
603           The exit status of the double-bracket command is 0 if expression is
604           true, 1 if false, and 2 if it cannot be evaluated because of
605           expansion error or any other reasons.
606
607               Note
608               The double-bracket command is also supported in bash, ksh,
609               mksh, and zsh, but not defined in the POSIX standard. The
610               behavior slightly differs between the shells. The test built-in
611               should be preferred over the double-bracket command for maximum
612               portability.
613
614   Function definition
615       The function definition command defines a function.
616
617       Function definition syntax
618           funcname ( ) compound_command
619
620           function funcname compound_command
621
622           function funcname ( ) compound_command
623
624       In the first syntax without the function keyword, funcname cannot
625       contain any special characters such as semicolons and quotation marks.
626       In the second and third syntax, which cannot be used in the
627       POSIXly-correct mode, funcname is subjected to the four expansions when
628       executed. In the POSIXly-correct mode, funcname is limited to a
629       portable (ASCII-only) name.
630
631       When a function definition command is executed, a function whose name
632       is funcname is defined with its body being compound_command.
633
634       A function definition command cannot be directly redirected. Any
635       redirections that follow a function definition are associated with
636       compound_command rather than the whole function definition command. In
637       func() { cat; } >/dev/null, for example, it is not func() { cat; } but
638       { cat; } that is redirected.
639
640       The exit status of a function definition is zero if the function was
641       defined without errors, and non-zero otherwise.
642

PARAMETERS AND VARIABLES

644       Parameters are string values that are expanded in parameter expansion.
645       There are three types of parameters: positional parameters, special
646       parameters and variables.
647
648   Positional parameters
649       Positional parameters are parameters that are identified by natural
650       numbers. If there are three positional parameters, for example, they
651       are identified as 1, 2, and 3. You can obtain the number of positional
652       parameters by the # special parameter. The * and @ special parameters
653       are expanded to all positional parameters.
654
655       Positional parameters are initialized from the shell’s command line
656       arguments when the shell is started (see Command line arguments). In
657       the initialization, the order of the operands are preserved as the
658       order of the positional parameters.
659
660       When the shell executes a function call, positional parameters are
661       changed to the arguments to the function call so that you can access
662       the arguments while the function is being executed. Positional
663       parameters are restored to the original values when the execution of
664       the function is finished.
665
666       Positional parameters can be manipulated by built-in commands like set
667       and shift.
668
669       Note that 0 is not a positional parameter but a special parameter.
670
671   Special parameters
672       Special parameters are parameters each identified by a single symbol.
673       They cannot be directly assigned to by the user.
674
675       Yash provides the following special parameters:
676
677       0
678           The name of the shell executable file or the script file that was
679           specified in the invocation of the shell.
680
681       #
682           The number of current positional parameters. The value is a
683           non-negative integer.
684
685       $
686           The process ID of the shell. The value is a positive integer and is
687           never changed even in subshells.
688
689       -
690           Currently enabled shell options. The value is a concatenation of
691           alphabet characters that are the names of currently enabled
692           single-character options that can be specified in shell invocation.
693           The value reflects changes of enabled options when you enable or
694           disable options using the set built-in.
695
696       ?
697           The exit status of the last executed pipeline. The value is a
698           non-negative integer.
699
700       !
701           The process ID of the last executed asynchronous list.
702
703       *
704           This special parameter represents the whole positional parameters.
705           When there is no positional parameters, the value of this special
706           parameter is the empty string. When there is more than one
707           positional parameter, the value is a concatenation of all the
708           positional parameters, each of which is separated as follows:
709
710           •   If the IFS variable exists and its value is not empty,
711               positional parameters are each separated by the first character
712               of the value of the IFS variable.
713
714           •   If the IFS variable exists and has an empty value, positional
715               parameters are just concatenated without any separator.
716
717           •   If the IFS variable does not exist, positional parameters are
718               each separated by a space character.
719
720           If field-splitting is applied to an expansion result of this
721           parameter, the value is first split into the original positional
722           parameters and then further split depending on the current IFS
723           variable. The first splitting is performed even if the IFS variable
724           is empty.
725
726       @
727           This special parameter represents the whole positional parameters
728           like the * special parameter above. The difference between the two
729           is the results of expansion that occurs between a pair of
730           double-quotation marks. If the @ special parameter is expanded
731           inside double-quotations, the result is field-split into the exact
732           positional parameter values. If there are no positional parameters,
733           the expansion yields no word rather than an empty word. (Even if
734           the expansion is double-quoted, the result is not always a single
735           word.)
736
737           •   When there are no positional parameters, the command words echo
738               1 "$@" 2 are expanded to the three words echo, 1, and 2.
739
740           •   When positional parameters are the three words 1, 2 2, and 3,
741               the command words echo "$@" are expanded to the four words
742               echo, 1, 2 2, and 3, and the words echo "a$@b" to the four
743               words echo, a1, 2 2, and 3b.
744
745   Variables
746       Variables are parameters the user can assign values to. Each variable
747       has a name that identifies it and a value that defines the results of
748       expansion.
749
750       A variable name is composed of one or more alphanumeric characters and
751       underscores (_). A name cannot start with a digit. Other characters may
752       be used in a name depending on internationalization support of your
753       environment.
754
755       Variables that are exported to external commands are called environment
756       variables. They are passed to all external commands the shell invokes.
757       Variables passed to the shell in invocation will be automatically
758       exported.
759
760       You can assign to variables by a simple command as well as the typeset
761       built-in. You can remove variables by using the unset built-in.
762
763       Variables used by the shell
764           The following variables are used by the shell for special purposes.
765
766           CDPATH
767               This variable is used by the cd built-in to find a destination
768               directory.
769
770           COLUMNS
771               This variable specifies the width (the number of character
772               columns) of the terminal screen. The value affects the display
773               of line-editing.
774
775           COMMAND_NOT_FOUND_HANDLER
776               When the shell cannot find a command to be executed, the value
777               of this variable is interpreted and executed instead. You can
778               override the shell’s error handling behavior with this
779               variable. See Execution of simple commands for detail.
780
781               This feature is disabled in the POSIXly-correct mode.
782
783           DIRSTACK
784               This array variable is used by the shell to store the directory
785               stack contents. If you modify the value of this variable, the
786               directory stack may be corrupted.
787
788           ECHO_STYLE
789               This variable specifies the behavior of the echo built-in.
790
791           ENV
792               When an interactive shell is started in the POSIXly-correct
793               mode, the value of this variable is used to find the
794               initialization file. See Initialization of yash.
795
796           FCEDIT
797               This variable specifies an editor program used to edit command
798               lines during execution of the fc built-in.
799
800           HANDLED
801               This variable can be set in the command-not-found handler to
802               tell the shell not to produce a further error message. See
803               Execution of simple commands for detail.
804
805           HISTFILE
806               This variable specifies the pathname of the file to save the
807               command history in.
808
809           HISTRMDUP
810               This variable specifies the number of command history items to
811               be checked for duplication. When the shell is adding a new
812               history item to the command history, if some of the most recent
813               n items have the same contents as the new one, then the
814               duplicate existing items are removed from the history before
815               the new one is added, where n is the value of this variable.
816
817               If the value of this variable is 1, for example, the most
818               recent item is removed when a new item that have the same
819               contents is added.
820
821               Items older than the nth recent item are not removed. No items
822               are removed if the value of this variable is 0. All items are
823               subject to removal if the variable value is greater than or
824               equal to the value of the HISTSIZE variable.
825
826           HISTSIZE
827               This variable specifies the maximum number of items in the
828               command history.
829
830           HOME
831               This variable specifies the pathname of the user’s home
832               directory and affects results of tilde expansion and cd
833               built-in.
834
835           IFS
836               This variable specifies separators used in field splitting. The
837               variable value is initialized to the three characters of a
838               space, a tab, and a newline when the shell is started.
839
840           LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY,
841           LC_NUMERIC, LC_TIME
842               These variables specify a locale in which the shell runs. The
843               shell chooses the file input/output encoding, the error message
844               language, etc. according to the locale specified.
845
846               Unless the shell is interactive and not in the POSIXly-correct
847               mode, the value of the LC_CTYPE variable is considered only
848               when the shell is started. Once the shell has been initialized,
849               changing the value of LC_CTYPE will have no effect on the
850               shell’s behavior.
851
852           LINENO
853               The value of this variable is automatically set to the line
854               number in which the currently executed command appears in the
855               file.
856
857               In the interactive shell, the line number is reset to 1 each
858               time the shell reads and executes a command.
859
860               If you assign to or remove this variable, it will no longer
861               provide line numbers.
862
863           LINES
864               This variable specifies the height (the number of character
865               lines) of the terminal screen. The value affects the display of
866               line-editing.
867
868           MAIL
869               This variable specifies the pathname of a file that is checked
870               in mail checking.
871
872           MAILCHECK
873               This variable specifies how often the shell should do mail
874               checking. The value has to be specified as a positive integer
875               in seconds. The value is initialized to the default value of
876               600 when the shell is started.
877
878           MAILPATH
879               This variable specifies the pathnames of files that are checked
880               in mail checking.
881
882           NLSPATH
883               The POSIX standard prescribes that the value of this variable
884               specifies pathname templates of locale-dependent message data
885               files, but yash does not use it.
886
887           OLDPWD
888               This variable is set to the previous working directory path
889               when you change the working directory by using the cd or other
890               built-ins. This variable is exported by default.
891
892           OPTARG
893               When the getopts built-in parses an option that takes an
894               argument, the argument value is assigned to this variable.
895
896           OPTIND
897               The value of this variable specifies the index of an option
898               that is to be parsed by the next getopts built-in execution.
899               This variable is initialized to 1 when the shell is started.
900
901           PATH
902               This variable specifies paths that are searched for a command
903               in command search.
904
905           PPID
906               The value of this variable is the process ID of the shell’s
907               parent process, which is a positive integer. This variable is
908               initialized when the shell is started. The value is not changed
909               when the shell makes a new subshell.
910
911           PROMPT_COMMAND
912               The shell interprets and executes the value of this variable
913               before printing each command prompt if the shell is interactive
914               and not in the POSIXly-correct mode. This behavior is
915               equivalent to executing the command eval -i --
916               "${PROMPT_COMMAND-}" before each command prompt, but its exit
917               status does not affect the expansion of the ?  special
918               parameter in the next command.
919
920           PS1
921               This variable specifies the main command prompt string printed
922               by an interactive shell. See Prompts for the format of the
923               variable value. The value is initialized to either $ or #
924               depending on whether the effective user ID of the shell process
925               is zero or not.
926
927           PS1R
928               This variable specifies the auxiliary prompt string printed to
929               the right of the cursor when you input a command line to an
930               interactive shell. See Prompts for the format of the variable
931               value.
932
933           PS1S
934               This variable specifies the font style of command strings you
935               enter to an interactive shell. See Prompts for the format of
936               the variable value.
937
938           PS2
939               This variable is like the PS1 variable, but it is used for the
940               second and following lines of a command that is longer than one
941               line. See Prompts for the format of the variable value. The
942               value is initialized to > when the shell is started.
943
944           PS2R
945               This variable is like the PS1R variable, but it is used when
946               PS2 is used. See Prompts for the format of the variable value.
947
948           PS2S
949               This variable is like the PS1S variable, but it is used when
950               PS2 is used. See Prompts for the format of the variable value.
951
952           PS4
953               The value of this variable is printed before each command trace
954               output when the xtrace option is enabled. The value is subject
955               to parameter expansion, command substitution, arithmetic
956               expansion. You can also use backslash notations if the shell is
957               not in the POSIXly-correct mode. The value is initialized to +
958               when the shell is started.
959
960           PS4S
961               This variable is like the PS1S variable, but it is used when
962               PS4 is used. You can use this variable to modify font style of
963               command trace output.
964
965           PWD
966               The value of this variable is the pathname of the current
967               working directory. The value is set when the shell is started
968               and reset each time the working directory is changed by the cd
969               or other built-ins. This variable is exported by default.
970
971           RANDOM
972               You can use this variable to get random numbers. The value of
973               this variable is a uniformly distributed random integer between
974               0 and 32767 (inclusive). You will get a different number each
975               time the variable is expanded.
976
977               You can set the “seed” of random numbers by assigning a
978               non-negative integer to the variable.
979
980               If you remove this variable, it will no longer work as a random
981               number generator. If the shell was invoked in the
982               POSIXly-correct mode, this variable does not work as a random
983               number generator.
984
985           TERM
986               This variable specifies the type of the terminal in which the
987               shell is running. The value affects the behavior of
988               line-editing. This variable has to be exported to take effect.
989
990           YASH_AFTER_CD
991               The shell interprets and executes the value of this variable
992               after each time the shell’s working directory is changed by the
993               cd or other built-ins. This behavior is equivalent to executing
994               the command eval -i -- "${YASH_AFTER_CD-}" after the directory
995               was changed.
996
997           YASH_LOADPATH
998               This variable specifies directories the dot built-in searches
999               for a script file. More than one directory can be specified by
1000               separating them by colons like the PATH variable. When the
1001               shell is started, this variable is initialized to the pathname
1002               of the directory where common script files are installed.
1003
1004           YASH_LE_TIMEOUT
1005               This variable specifies how long the shell should wait for a
1006               next possible input from the terminal when it encountered an
1007               ambiguous control sequence while line-editing. The value must
1008               be specified in milliseconds. If you do not define this
1009               variable, the default value of 100 milliseconds is assumed.
1010
1011           YASH_PS1, YASH_PS1R, YASH_PS1S, YASH_PS2, YASH_PS2R, YASH_PS2S,
1012           YASH_PS4, YASH_PS4S
1013               When not in the POSIXly-correct mode, if any of these variables
1014               is defined, it takes precedence over the corresponding variable
1015               without the YASH_ prefix in the name (e.g.  PS1). These
1016               variables are ignored in the POSIXly-correct mode. You should
1017               define them to include yash-specific notations in the prompt,
1018               so that unhandled notations do not mangle the prompt in the
1019               POSIXly-correct mode.
1020
1021           YASH_VERSION
1022               The value is initialized to the version number of the shell
1023               when the shell is started.
1024
1025       Arrays
1026           An array is a variable that contains zero or more strings. The
1027           string values of an array are identified by natural numbers (like
1028           positional parameters).
1029
1030           You can assign values to an array by using a simple command as well
1031           as the array built-in. You can use the unset built-in to remove
1032           arrays.
1033
1034           Arrays cannot be exported as arrays. When an array is exported, it
1035           is treated as a normal variable whose value is a concatenation of
1036           all the array values, each separated by a colon.
1037
1038           Arrays are not supported in the POSIXly-correct mode.
1039

WORD EXPANSIONS

1041       Word expansion is substitution of part of a word with another
1042       particular string. There are seven types of word expansions:
1043
1044        1. Tilde expansion
1045
1046        2. Parameter expansion
1047
1048        3. Command substitution
1049
1050        4. Arithmetic expansion
1051
1052        5. Brace expansion
1053
1054        6. Field splitting
1055
1056        7. Pathname expansion (globbing)
1057
1058       These types of expansions are performed in the order specified above.
1059
1060       Tilde expansion, parameter expansion, command substitution, and
1061       arithmetic expansion are called the four expansions.
1062
1063   Tilde expansion
1064       In tilde expansion, parts of words that start with a tilde (~) are
1065       substituted with particular pathnames. The part of each word that gets
1066       substituted is from the beginning of the word, which is a tilde, up to
1067       (but not including) the first slash (/) in the word. If the word does
1068       not contain a slash, the whole word is substituted. If any character in
1069       the substituted part is quoted, tilde expansion is not performed on the
1070       word.
1071
1072       The results of expansion are determined by the format of the
1073       substituted part:
1074
1075       ~
1076           A single tilde is substituted with the value of the HOME variable.
1077
1078       ~username
1079           A tilde followed by a user name is substituted with the pathname of
1080           the user’s home directory.
1081
1082       ~+
1083           ~+ is substituted with the value of the PWD variable.
1084
1085       ~-
1086           ~- is substituted with the value of the OLDPWD variable.
1087
1088       ~+n, ~-n
1089           where n is a non-negative integer. This type of tilde expansion
1090           yields the pathname of a directory of which ~+n or ~-n is the index
1091           in the directory stack.
1092
1093       When tilde expansion is performed on the value of a variable assignment
1094       that occurs during execution of a simple command, the value is
1095       considered as a colon-separated list of words and those words are each
1096       subject to tilde expansion. For example, the variable assignment
1097
1098           VAR=~/a:~/b:~/c
1099
1100       is equivalent to
1101
1102           VAR=/home/foo/a:/home/foo/b:/home/foo/c
1103
1104       if the value of HOME variable is /home/foo.
1105
1106       The POSIX standard does not prescribe how the shell should behave when
1107       it encounters an error during tilde expansion (e.g., when the HOME
1108       variable is not defined). Yash silently ignores any errors during tilde
1109       expansion; the part of the word that would be substituted is left
1110       intact.
1111
1112       In the POSIXly-correct mode, tilde expansion supports the formats of ~
1113       and ~username only.
1114
1115   Parameter expansion
1116       Parameter expansion expands to the value of a parameter.
1117
1118       The syntax of typical, simple parameter expansion is ${parameter},
1119       which expands to the value of the parameter whose name is parameter.
1120       You can omit the braces (e.g., $parameter) if
1121
1122parameter is a special parameter,
1123
1124parameter is a positional parameter whose index is a one-digit
1125           integer, or
1126
1127parameter is a variable and the parameter expansion is not followed
1128           by a character that can be used as part of a variable name.  For
1129           example, ${path}-name is equivalent to $path-name, but ${path}name
1130           and $pathname are different.
1131
1132       If parameter is none of a special parameter, positional parameter, and
1133       variable, it is a syntax error. (Some shells other than yash may treat
1134       such a case as an expansion error.)
1135
1136       If the unset option is disabled and the parameter is an undefined
1137       variable, it is an expansion error. If the unset option is enabled, an
1138       undefined variable expands to the empty string.
1139
1140       More complex syntax of parameter expansion allows modifying the value
1141       of a parameter.
1142
1143       Parameter expansion
1144           ${ prefix parameter index modifier }
1145
1146       The spaces in the syntax definition above are for readability only and
1147       must be omitted. You can omit prefix, index, and/or modifier.
1148
1149       Prefix
1150           The prefix, if any, must be a hash sign (#). If a parameter
1151           expansion has the prefix, the result of expansion is the number of
1152           characters in the value this expansion would be expanded to without
1153           the prefix.
1154
1155       Parameter name
1156           The parameter name (parameter) must be either
1157
1158           •   a name of a special parameter, positional parameter, or
1159               variable; or
1160
1161           •   another parameter expansion, command substitution, or
1162               arithmetic expansion.
1163
1164           The parameter expansion is expanded to the value of the parameter.
1165           If parameter is an array variable, the values of the array are
1166           field-split like the @ special parameter unless the index [*] is
1167           specified.
1168
1169           If parameter is another expansion, it is called a nested expansion.
1170           Nested expansion cannot be used in the POSIXly-correct mode. The
1171           braces ({ }) of a nested parameter expansion cannot be omitted.
1172       Index.sp An index allows extracting part of the parameter value (or
1173       some of array values).
1174
1175       Index
1176           [word1]
1177
1178           [word1,word2]
1179
1180       where word1 and word2 are parsed in the same manner as normal tokens
1181       except that they are always delimited by , or ] and can contain
1182       whitespace characters.
1183
1184       If there is an index in a parameter expansion, it is interpreted as
1185       follows:
1186
1187        1. Words word1 and word2 are subjected to parameter expansion, command
1188           substitution, and arithmetic expansion.
1189
1190        2. If there is no word2 and if word1 expands to one of *, @, and #,
1191           then that is the interpretation of index and the next step is not
1192           taken.
1193
1194        3. The results of the previous steps (the expanded word1 and word2)
1195           are interpreted and evaluated as an arithmetic expression in the
1196           same manner as in arithmetic expansion. The resulting integers are
1197           the interpretation of index. If the results are not integers, it is
1198           an expansion error. If there is no word2, it is assumed that word2
1199           is equal to word1.
1200
1201       If parameter is an array variable, the index specifies the part of the
1202       array. If parameter is either the * or @ special parameter, the index
1203       specifies the index range of positional parameters. In other cases, the
1204       index specifies the index range of a substring of the parameter value
1205       that is being expanded. In all cases, the specified range of the array
1206       values, positional parameters, or parameter value remains in the
1207       results of the expansion and other values are dropped.
1208
1209       If the interpretation of index is one or two integers, the following
1210       rules apply:
1211
1212       •   If the interpreted index value is negative, it wraps around. For
1213           example, the index value of -1 corresponds to the last
1214           value/character.
1215
1216       •   It is not an error when the index value is out of range. Existing
1217           values/characters within the range are just selected.
1218
1219       •   If the interpretation of either word1 or word2 is 0, the range is
1220           assumed empty and the expansion results in nothing.
1221
1222       If the interpretation of index is one of *, @, and #, it is treated as
1223       follows:
1224
1225       *
1226           If parameter is an array, all the array values are field-split or
1227           concatenated in the same manner as the * special parameter. If
1228           parameter is the * or @ special parameter, the positional
1229           parameters are likewise field-split or concatenated. In other
1230           cases, the interpretation of index is treated as if the
1231           interpretation is the two integers 1 and -1.
1232
1233       @
1234           The interpretation of index is treated as if the interpretation is
1235           the two integers 1 and -1.
1236
1237       #
1238           The interpretation of the # index is special in that it does not
1239           simply specify a range. Instead, the expanded values are
1240           substituted with the count.
1241
1242           If parameter is an array, the result of this parameter expansion
1243           will be the number of values in the array being expanded. If
1244           parameter is the * or @ special parameter, the result will be the
1245           number of current positional parameters. Otherwise, the result will
1246           be the number of characters in the value that is being expanded.
1247
1248       If a parameter expansion does not contain an index, it is assumed to be
1249       [@]. In the POSIXly-correct mode, index cannot be specified.
1250
1251       Example 1. Expansion of a normal variable
1252
1253       The following commands will print the string ABC:
1254
1255           var='123ABC789'
1256           echo "${var[4,6]}"
1257
1258       Example 2. Expansion of positional parameters
1259
1260       The following commands will print the string 2 3 4:
1261
1262           set 1 2 3 4 5
1263           echo "${*[2,-2]}"
1264
1265       Example 3. Expansion of an array
1266
1267       The following commands will print the string 2 3 4:
1268
1269           array=(1 2 3 4 5)
1270           echo "${array[2,-2]}"
1271
1272       Modifier
1273           You can modify the value to be expanded by using modifiers:
1274
1275           -word
1276               If the parameter name (parameter) is an undefined variable, the
1277               parameter expansion is expanded to word. It is not treated as
1278               an error if the unset option is disabled.
1279
1280           +word
1281               If the parameter name (parameter) is an existing variable, the
1282               parameter expansion is expanded to word. It is not treated as
1283               an error if the unset option is disabled.
1284
1285           =word
1286               If the parameter name (parameter) is an undefined variable,
1287               word is assigned to the variable and the parameter expansion is
1288               expanded to word. It is not treated as an error if the unset
1289               option is disabled.
1290
1291           ?word
1292               If the parameter name (parameter) is an undefined variable,
1293               word is printed as an error message to the standard error. If
1294               word is empty, the default error message is printed instead.
1295
1296           :-word, :+word, :=word, :?word
1297               These are similar to the four types of modifiers above. The
1298               only difference is that, if parameter exists and has an empty
1299               value, it is also treated as an undefined variable.
1300
1301           #word
1302               The shell performs pattern matching against the value that is
1303               being expanded, using word as a pattern. If word matches the
1304               beginning of the value, the matching part is removed from the
1305               value and the other part remains as expansion results. The
1306               shortest matching is used if more than one matching is
1307               possible.
1308
1309           ##word
1310               This is similar to #word above. The only difference is that the
1311               longest matching is used if more than one matching is possible.
1312
1313           %word
1314               This is similar to #word above. The only difference is that
1315               matching is tried at the end of the value rather than at the
1316               beginning: if word matches the end of the value, the matching
1317               part is removed from the value and the other part remains as
1318               expansion results.
1319
1320           %%word
1321               This is similar to %word above. The only difference is that the
1322               longest matching is used if more than one matching is possible.
1323
1324           /word1/word2
1325               The shell performs pattern matching against the value that is
1326               being expanded, using word1 as a pattern. If word1 matches any
1327               part of the value, the matching part is replaced with word2 and
1328               the whole value after the replacement remains as expansion
1329               results. If word1 matches more than one part of the value, only
1330               the first part is replaced. The shortest matching is replaced
1331               if more than one matching is possible for the same starting
1332               point in the value.
1333
1334               This modifier cannot be used in the POSIXly-correct mode.
1335
1336           /#word1/word2
1337               This is similar to /word1/word2 above. The only difference is
1338               that word1 matches only at the beginning of the value being
1339               expanded.
1340
1341           /%word1/word2
1342               This is similar to /word1/word2 above. The only difference is
1343               that word1 matches only at the end of the value being expanded.
1344
1345           //word1/word2
1346               This is similar to /word1/word2 above. The only difference is
1347               that all matched parts are replaced if word1 matches more than
1348               one part of the value.
1349
1350           :/word1/word2
1351               This is similar to /word1/word2 above. The only difference is
1352               that the value is replaced only when word1 matches the whole
1353               value.
1354
1355           In all types of modifiers above, words are subjected to the four
1356           expansions when (and only when) they are used.
1357
1358           If parameter is an array variable or the @ or * special parameter,
1359           modifiers affect each value of the array or all positional
1360           parameters.
1361
1362   Command substitution
1363       Command substitution expands to output of commands specified.
1364
1365       Command substitution
1366           $(commands)
1367
1368           `commands`
1369
1370       When command substitution is evaluated, commands are executed by a
1371       subshell with output pipelined to the shell. When the commands
1372       finished, command substitution is substituted with the output of the
1373       commands. Any trailing newline characters in the output are ignored.
1374
1375       When command substitution of the form $(commands) is parsed, the
1376       commands are parsed carefully so that complex commands such as nested
1377       command substitution are parsed correctly. If commands start with (,
1378       you should put a space before commands so that the whole command
1379       substitution is not confused with arithmetic expansion. If the shell is
1380       in the POSIXly-correctly mode, the commands are parsed each time the
1381       command substitution is expanded; otherwise, commands are parsed only
1382       when the command substitution is parsed.
1383
1384       If command substitution is of the form `commands`, the commands are not
1385       parsed when the command substitution is parsed; the commands are parsed
1386       each time the command substitution is expanded. The end of commands is
1387       detected by the first backquote character (`) after the beginning of
1388       commands that is not quoted by a backslash. Backquotes that are part of
1389       commands (typically used for nested command substitution) must be
1390       quoted by backslashes. In commands, backslashes are treated as quotes
1391       only when preceding a dollar ($), backquote, newline, or another
1392       backslash. Additionally, if the command substitution occurs inside
1393       double quotes, double quotes in commands must be quoted with a
1394       backslash. Those backslashes are removed before commands are parsed.
1395
1396   Arithmetic expansion
1397       Arithmetic expansion evaluates an arithmetic expression and expands to
1398       the value of the expression.
1399
1400       Arithmetic expansion
1401           $((expression))
1402
1403       When arithmetic expansion is expanded, the expression is subject to
1404       parameter expansion, command substitution, and (nested) arithmetic
1405       expansion. The expression is parsed in (almost) same manner as an
1406       expression of the C programming language.
1407
1408       Yash allows an expression to be either an integer (of the long type in
1409       C) or a floating-point number (of the double type in C). An operation
1410       on integers yields an integer and an operation involving a
1411       floating-point number yields a floating-point number. In the
1412       POSIXly-correct mode, you can use integers only.
1413
1414       The following operators are available (in the order of precedence):
1415
1416        1. ( )
1417
1418        2. ++ -- (postfix operators)
1419
1420        3. ++ -- + - ~ !  (prefix operators)
1421
1422        4. * / %
1423
1424        5. + - (binary operators)
1425
1426        6. << >>
1427
1428        7. < <= > >=
1429
1430        8. == !=
1431
1432        9. &
1433
1434       10. ^
1435
1436       11. |
1437
1438       12. &&
1439
1440       13. ||
1441
1442       14. ? :
1443
1444       15. = *= /= %= += -= <<= >>= &= ^= |=
1445
1446       The ++ and -- operators cannot be used in the POSIXly-correct mode.
1447
1448       An atomic expression can be one of an integer literal, a floating-point
1449       number literal, and a variable. Literals are parsed in the same manner
1450       as in C. An octal integer literal starts with 0, and hexadecimal with
1451       0x. A floating-point number literal may have an exponent (i.e.
1452       1.23e+6). A variable with a non-numeric value will result in an error
1453       when parsed as a number. An unset variable is treated as a value of
1454       zero if the unset option is enabled.
1455
1456       In the POSIXly-correct mode, variables are always parsed as numbers.
1457       Otherwise, variables are parsed only when they are used as numbers in
1458       computation. Unparsed variables are left intact.
1459
1460           set +o posixly-correct
1461           foo=bar
1462           echo $((0 ? foo : foo)) # prints "bar"
1463           echo $((foo + 0))       # error
1464
1465   Brace expansion
1466       Brace expansion expands to several split words with preceding and
1467       succeeding portions duplicated to each split words. Brace expansion is
1468       expanded only when the brace-expand option is enabled.
1469
1470       Comma-separated brace expansion
1471           {word1,word2,...,wordn}
1472
1473       Range brace expansion
1474           {start..end}
1475
1476           {start..end..delta}
1477
1478       Comma-separated brace expansion is expanded to each comma-separated
1479       word. For example, a{1,2,3}b is expanded to the three words a1b, a2b,
1480       and a3b.
1481
1482       Range brace expansion is expanded to integers in the range defined by
1483       start and end. The difference between each integer can be defined by
1484       delta. If start is larger than end, the results will be in descending
1485       order. When ..delta is omitted, it defaults to 1 or -1. For example,
1486       a{1..3}b is expanded to the three words a1b, a2b, and a3b; and
1487       a{1..7..2}b to the four words a1b, a3b, a5b, and a7b.
1488
1489       Multiple brace expansions can be used in one word. Brace expansions can
1490       also be nested. You can quote braces and/or commas to prevent them from
1491       being treated as brace expansion.
1492
1493       Any errors in brace expansion are silently ignored.
1494
1495   Field splitting
1496       In field splitting, words are split at predefined separators.
1497
1498       Field splitting can occur only within parts of words that resulted from
1499       parameter expansion, command substitution, and arithmetic expansion
1500       that are not between double-quotation marks. Expansion results of the @
1501       special parameter are exceptionally split even between double-quotation
1502       marks.
1503
1504       Separators used in field splitting are defined by the value of the IFS
1505       variable. If the variable does not exist, the value is assumed to be
1506       the three characters of space, tab, and newline.
1507
1508       Characters included in the value of the IFS variable are called IFS
1509       characters. IFS characters that are any of space, tab, and newline are
1510       called IFS whitespace and other IFS characters are called IFS
1511       non-whitespace.
1512
1513       Field splitting is performed as follows:
1514
1515        1. The shell searches words for split points. A split point is one or
1516           more adjacent IFS characters within the word portions where field
1517           splitting can occur. The following steps are taken for each split
1518           point found.
1519
1520        2. If the split point includes one or more IFS non-whitespaces, all
1521           the IFS whitespaces in the split point are ignored and the word is
1522           split at each IFS non-whitespace in the split point.
1523
1524        3. If the split point includes no IFS non-whitespaces, the word is
1525           split at the split point unless it is at the beginning or end of
1526           the word.
1527
1528        4. The split points are removed from the results.
1529
1530       Finally, the last word is removed from the results if:
1531
1532       •   the empty-last-field option is not enabled;
1533
1534       •   the result is more than one word; and
1535
1536       •   the last word is empty.
1537
1538           Note
1539           Words are not split at all when the value of the IFS variable is
1540           empty.
1541
1542   Pathname expansion
1543       Pathname expansion performs pattern matching and expands to pathnames
1544       matched by the pattern.
1545
1546       A word subjected to pathname expansion is treated as a pattern. If one
1547       or more pathnames are found that are matched by the pattern, the
1548       pathnames become the results of the pathname expansion.
1549
1550       Pathname expansion is not performed when the glob option is disabled.
1551
1552       The shell searches readable directories for matching pathnames.
1553       Unreadable directories are silently ignored.
1554
1555       The following options affect the behavior of pathname expansion:
1556
1557       null-glob
1558           This option affects the result of pathname expansion when no
1559           matching pathnames are found. If enabled, the result is no word. If
1560           disabled, the result is the original pattern word.
1561
1562       case-glob
1563           This option specifies case-sensitivity in matching. If enabled,
1564           pattern matching is done case-sensitively.
1565
1566       dot-glob
1567           This option affects matching of filenames that start with a period
1568           (.). If disabled, a period at the beginning of a filename does not
1569           match wildcard patterns (?  and *) or bracket expressions. If
1570           enabled, there is no such special treatment of periods.
1571
1572       mark-dirs
1573           If enabled, each resulting pathname that is a directory name is
1574           suffixed by a slash (/).
1575
1576       extended-glob
1577           This option enables the extension. (See below)
1578
1579       Any errors in pathname expansion are silently ignored. If the word is
1580       an invalid pattern, it just becomes the result. The results depend on
1581       the null-glob option when no matching pathnames are found.
1582
1583       Pattern matching is done for each filename (or pathname component) of
1584       pathnames. The shell skips matching for literal patterns that contain
1585       no wildcards or bracket expressions. As a result, the patterns /*/foo
1586       and /*/fo[o] may yield different expansion results when the case-glob
1587       option is disabled; for example, the pattern /*/fo[o] matches the
1588       pathname /bar/FOO but the pattern /*/foo does not because matching is
1589       skipped for foo.
1590
1591       Extension in pathname expansion
1592           The following patterns can be used when the extended-glob option is
1593           enabled.
1594
1595           **
1596               The directory is searched recursively and the pattern matches
1597               any number of directory filenames (each separated by a slash).
1598               Any directory whose name begins with a period is excluded from
1599               search. For example, the pattern dir/**/file can match the
1600               pathnames dir/file, dir/foo/file, dir/a/b/c/file, etc.
1601
1602               This pattern is not effective when appearing at the end of the
1603               whole pattern (i.e.  foo/bar/**).
1604
1605           .**
1606               This pattern is like **, but all directories are searched
1607               including ones with a name starting with a period.
1608
1609           ***
1610               This pattern is like **, but if a symbolic link to a directory
1611               is found during recursive search, the directory is searched
1612               recursively as well.
1613
1614           .***
1615               This pattern is like ***, but all directories are searched
1616               including ones with a name starting with a period.
1617

PATTERN MATCHING NOTATION

1619       Pattern matching notation is a syntax of patterns that represent
1620       particular sets of strings. When a string is included in the set of
1621       strings a pattern represents, the pattern is said to match the string.
1622       Whether a pattern matches a string or not is defined as follows.
1623
1624   Normal characters
1625       A character that is not quoted or any of special characters defined
1626       below is a normal character, which matches the character itself.
1627
1628       For example, the pattern abc matches the string abc, and not any other
1629       strings.
1630
1631   Single-character wildcard
1632       The character ? matches any single character.
1633
1634       For example, the pattern a?c matches any three-character strings that
1635       starts with a and ends with c, such as aac, abc, and a;c.
1636
1637   Multi-character wildcard
1638       The character * matches any strings (of any length, including the empty
1639       string).
1640
1641       For example, the pattern a*c matches any string that starts with a and
1642       ends with c, such as ac, abc, and a;xyz;c.
1643
1644   Bracket expression
1645       A pattern that is enclosed by brackets ([ and ]) is a bracket
1646       expression. A bracket expression must have at least one character
1647       between the brackets. The characters between the brackets are
1648       interpreted as a bracket expression pattern, which is a below-defined
1649       special notation for bracket expression. A bracket expression pattern
1650       represents a set of characters. The bracket expression matches any one
1651       of the characters in the set the bracket expression pattern represents.
1652
1653       If the opening bracket ([) is followed by an exclamation mark (!), the
1654       exclamation is not treated as part of the bracket expression pattern
1655       and the whole bracket expression instead matches a character that is
1656       not included in the set the bracket expression pattern represents. If
1657       the opening bracket is followed by a caret (^), it is treated like an
1658       exclamation mark as above (but shells other than yash may treat the
1659       caret differently).
1660
1661       If the opening bracket (or the following exclamation or caret, if any)
1662       is followed by a closing bracket (]), it is treated as part of the
1663       bracket expression pattern rather than the end of the bracket
1664       expression. You cannot quote characters in the bracket expression
1665       pattern because quotation is treated before bracket expression.
1666
1667       An opening bracket in a pattern is treated as a normal character if it
1668       is not the beginning of a valid bracket expression.
1669
1670   Normal characters (in bracket expression pattern)
1671       A character that is not any of special characters defined below is a
1672       normal character, which represents the character itself.
1673
1674       For example, the bracket expression pattern abc represents the set of
1675       the three characters a, b, and c. The bracket expression [abc]
1676       therefore matches any of the three characters.
1677
1678   Range expressions
1679       A hyphen preceded and followed by a character (or collating symbol) is
1680       a range expression, which represents the set of the two characters and
1681       all characters between the two in the collation order. A collation
1682       order is an order of characters that is defined in the locale data.
1683
1684       If a hyphen is followed by a closing bracket (]), the bracket is
1685       treated as the end of the bracket expression and the hyphen as a normal
1686       character.
1687
1688       For example, the range expression 3-5 represents the set of the three
1689       characters 3, 4, and 5. The bracket expression [3-5-] therefore matches
1690       one of the four characters 3, 4, 5, and -.
1691
1692   Collating symbols
1693       A collating symbol allows more than one character to be treated as a
1694       single character in matching. A collating symbol is made up of one or
1695       more characters enclosed by the special brackets [. and .].
1696
1697       One or more characters that are treated as a single character in
1698       matching are called a collating element. Precisely, a bracket
1699       expression pattern represents a set of collating elements and a bracket
1700       expression matches a collating element rather than a character, but we
1701       do not differentiate them for brevity here.
1702
1703       For example, the character combination “ch” was treated as a single
1704       character in the traditional Spanish language. If this character
1705       combination is registered as a collating element in the locale data,
1706       the bracket expression [[.ch.]df] matches one of ch, d, and f.
1707
1708   Equivalence classes
1709       An equivalence class represents a set of characters that are considered
1710       equivalent. A equivalence class is made up of a character (or more
1711       precisely, a collating element) enclosed by the special brackets [= and
1712       =].
1713
1714       An equivalence class represents the set of characters that consists of
1715       the character enclosed by the brackets and the characters that are in
1716       the same primary equivalence class as the enclosed character. The shell
1717       consults the locale data for the definition of equivalence classes in
1718       the current locale.
1719
1720       For example, if the six characters a, à, á, â, ã, ä are defined to be
1721       in the same primary equivalence class, the bracket expressions [[=a=]],
1722       [[=à=]], and [[=á=]] match one of the six.
1723
1724   Character classes
1725       A character class represents a predefined set of characters. A
1726       character class is made up of a class name enclosed by the special
1727       brackets [: and :]. The shell consults the locale data for which class
1728       a character belongs to.
1729
1730       The following character classes can be used in all locales:
1731
1732       [:lower:]
1733           set of lowercase letters
1734
1735       [:upper:]
1736           set of uppercase letters
1737
1738       [:alpha:]
1739           set of letters, including the [:lower:] and [:upper:] classes.
1740
1741       [:digit:]
1742           set of decimal digits
1743
1744       [:xdigit:]
1745           set of hexadecimal digits
1746
1747       [:alnum:]
1748           set of letters and digits, including the [:alpha:] and [:digit:]
1749           classes.
1750
1751       [:blank:]
1752           set of blank characters, not including the newline character
1753
1754       [:space:]
1755           set of space characters, including the newline character
1756
1757       [:punct:]
1758           set of punctuations
1759
1760       [:print:]
1761           set of printable characters
1762
1763       [:cntrl:]
1764           set of control characters
1765
1766       For example, the bracket expression [[:lower:][:upper:]] matches a
1767       lower or upper case character. In addition to the classes listed above,
1768       other classes may be used depending on the definition of the current
1769       locale.
1770

REDIRECTION

1772       Redirection is a feature you can use to modify file descriptors of
1773       commands. By using redirection, you can execute commands with their
1774       standard input/output connected with files or devices other than the
1775       terminal.
1776
1777       You can do redirection by adding redirection operators to a command
1778       (simple command or compound command) In a simple command, redirection
1779       operators may appear anywhere in the command as long as operator tokens
1780       are separated from other tokens. In a compound command, redirection
1781       operators must appear at the end of the command.
1782
1783       Redirection operators are processed before the command body is
1784       executed. More than one redirection operator in a command are processed
1785       in the order of appearance. Redirection operators affect only the
1786       command in which they appear, except when they appear in an exec
1787       built-in without command operands. That is, file descriptors modified
1788       by redirection are restored after the command has finished.
1789
1790       A redirection operator starts with < or >. Redirection operators
1791       starting with < affects the standard input (file descriptor 0) by
1792       default. Redirection operators starting with > affects the standard
1793       output (file descriptor 1) by default. To affect another file
1794       descriptor, you can prefix a redirection operator with a non-negative
1795       integer; the operator will affect the file descriptor specified by the
1796       integer. The integer must immediately precede the < or > without any
1797       whitespaces in between. The integer must not be quoted, either.
1798
1799   Redirection to files
1800       The most common type of redirection is redirection to files.
1801
1802       Redirection of input
1803           < token
1804
1805       Redirection of output
1806           > token
1807
1808           >| token
1809
1810           >> token
1811
1812       Redirection of input and output
1813           <> token
1814
1815       The token is subject to the four expansions. It is also subject to
1816       pathname expansion if the shell is interactive. The expansion result is
1817       treated as the pathname of the file to which redirection is performed.
1818       If the pathname expansion does not result in a single pathname, it is
1819       an error.
1820
1821       In redirection of input, the standard input is replaced with a file
1822       descriptor which is open for read-only access to the target file. If
1823       the target file cannot be opened for read-only access, it is an error.
1824
1825       In redirection of output, the standard output is replaced with a file
1826       descriptor which is open for write-only access to the target file. If
1827       the target file cannot be opened for write-only access, it is an error.
1828       If the target file does not exist, a new empty file is created and
1829       opened. If the target file already exists, the file is opened as
1830       follows:
1831
1832       •   For the >| operator, the file is emptied when opened if it is a
1833           regular file.
1834
1835       •   For the > operator, the behavior is the same as the >| operator if
1836           the clobber option is enabled. If the option is disabled and the
1837           file is a regular file, it is treated as an error.
1838
1839       •   For the >> operator, the file is opened for appending; any output
1840           to the file descriptor is appended to the end of the file.
1841
1842       In redirection of input and output, the standard input is replaced with
1843       a file descriptor which is open for read-and-write access to the target
1844       file. If the file does not exist, a new empty file is created and
1845       opened.
1846
1847       Socket redirection
1848           If the pathname of the target file is of the form
1849           /dev/tcp/host/port or /dev/udp/host/port and the file cannot be
1850           opened in the usual manner, a new socket is opened for
1851           communication with the port of the host. The redirection replaces
1852           the standard input or output with the file descriptor to the
1853           socket.
1854
1855           A stream socket is opened for the form /dev/tcp/host/port and a
1856           datagram socket for the form /dev/udp/host/port. The protocol
1857           actually used for communication is determined by the socket library
1858           the shell uses. Typically, stream sockets use TCP and datagram
1859           sockets UDP.
1860
1861           In socket redirection, the file descriptor is both readable and
1862           writable regardless of the type of the redirection operator used.
1863
1864           Socket redirection is yash’s extension that is not defined in
1865           POSIX. Bash as well has socket redirection as extension.
1866
1867   Duplication of file descriptors
1868       Redirection allows duplicating or closing existing file descriptors.
1869
1870       Duplication of file descriptor
1871           <& token
1872
1873           >& token
1874
1875       The token is subject to expansion as in redirection to files, but it is
1876       treated as a file descriptor rather than a pathname. Thus the expanded
1877       token must be a non-negative integer.
1878
1879       The <& and >& operators duplicate the file descriptor specified by
1880       token to the standard input and output, respectively. (The operators
1881       can be prefixed with a non-negative integer so that the file descriptor
1882       is duplicated to a file descriptor other than the standard input or
1883       output.)
1884
1885       If the expanded token is a single hyphen rather than a non-negative
1886       integer, the file descriptor is closed rather than duplicated. By
1887       default, the <& and >& operators close the standard input and output,
1888       respectively, but the operators can be prefixed with a non-negative
1889       integer so that another file descriptor is closed.
1890
1891       In the POSIXly-correct mode, a file descriptor must be readable when
1892       duplicated by the <& operator and writable when duplicated by the >&
1893       operator.
1894
1895   Here documents and here strings
1896       Here document and here string allow redirection to file descriptors
1897       that reads strings directly specified in shell commands.
1898
1899       Here document
1900           << token
1901
1902           <<- token
1903
1904       Here string
1905           <<< token
1906
1907       In a here document or here string, the standard input is replaced with
1908       a readable file descriptor. When the command reads from the file
1909       descriptor, it will read the contents of the here document/string,
1910       which is defined below.
1911
1912       When a here document operator (<< or <<-) appears in a command, the
1913       shell reads the contents of the here document starting from the next
1914       line. The contents of here documents are not parsed nor executed as
1915       commands. The token after the operand specifies a delimiter that
1916       indicates the end of the contents. (The token is not subject to any
1917       expansion, but quotation is processed.) The contents of the here
1918       document is terminated just before the first line containing the token
1919       only. When using the <<- operator, all tab characters at the beginning
1920       of each line in the here document contents are removed and the
1921       delimiter token may be preceded by tab characters.
1922
1923       If there are more than one here document operator on one line, the
1924       contents of the here documents are parsed in order: The contents of the
1925       first here document starts from the next line and ends before the first
1926       line containing the token that followed the first operator. Just after
1927       that line, the contents of the second here document starts, and so on.
1928
1929       The contents of here documents are treated literally: whitespaces,
1930       tabs, etc. remain as is. The exception is that, when the token is not
1931       quoted at all:
1932
1933       •   the contents are subject to parameter expansion, command
1934           substitution, arithmetic expansion.
1935
1936       •   a backslash in the contents is treated as quotation if and only if
1937           it precedes $, `, ", or another backslash.
1938
1939       •   a backslash followed by a newline is treated as line continuation.
1940
1941       In here string, the token after the operator is subject to expansion as
1942       in redirection to files. The expansion result becomes the contents of
1943       the here string. A newline character is automatically appended to the
1944       end of here string contents.
1945
1946       Here string is yash’s extension that is not defined in POSIX. Other
1947       shells like bash, ksh, and zsh have the same feature.
1948
1949   Pipeline redirection
1950       Pipeline redirection allows opening pipelines that can be used for
1951       arbitrary purposes.
1952
1953       Pipeline redirection
1954           >>| token
1955
1956       The token is subject to expansion as in redirection to files, but it is
1957       treated as a file descriptor rather than a pathname. Thus the expanded
1958       token must be a non-negative integer.
1959
1960       Pipeline redirection opens a new pipeline. The standard output (or the
1961       file descriptor specified before the operator, if any) is replaced with
1962       the file descriptor open for writing to the pipeline. The file
1963       descriptor specified by token is replaced with the file descriptor open
1964       for reading from the pipeline.
1965
1966       Pipeline redirection is yash’s extension that is not defined in POSIX.
1967
1968   Process redirection
1969       Process redirection creates a pipeline connected to another command.
1970
1971       Process redirection
1972           <(command...)
1973
1974           >(command...)
1975
1976       In process redirection, the command specified is executed in a
1977       subshell. If the process redirection is of the form <(command...), the
1978       standard output of command is connected with a pipeline to the standard
1979       input of the command the redirection is associated with. If the process
1980       redirection is of the form >(command...), the standard input of command
1981       is connected with a pipeline to the standard output of the command the
1982       redirection is associated with.
1983
1984       Process redirection is yash’s extension that is not defined in POSIX.
1985       Bash and zsh have a feature called process substitution, which uses the
1986       same syntax as yash’s process redirection, but incompatibly differs in
1987       behavior.
1988

COMMAND EXECUTION

1990       This section describes how commands are executed.
1991
1992   Execution of simple commands
1993       A simple command is executed as follows:
1994
1995        1. All tokens in the simple command are expanded except for assignment
1996           and redirection tokens. If an error occurs during expansion, the
1997           execution of the simple command is aborted with a non-zero exit
1998           status.
1999
2000           In the following steps, the first word of the expansion results is
2001           referred to as command name, and the other words as command
2002           arguments. If there is only one word of the expansion results,
2003           there are no command argument words. If there are none of the
2004           expansion results, there is no command name either.
2005
2006        2. If the command name exists and there are any redirections specified
2007           in the command, they are processed. The word token after each
2008           redirection operator is expanded. If an error occurs during
2009           processing the redirections (including when expanding the word
2010           token), the execution of this simple command is aborted with a
2011           non-zero exit status.
2012
2013               Note
2014               In other shells, redirections may be processed in a different
2015               step: POSIX does not specify the order in which redirections
2016               and assignments are processed when there is no command name or
2017               the name denotes a special built-in.
2018
2019        3. Assignments specified in the command, if any, are processed. For
2020           each assignment token, the value is expanded and assigned to the
2021           specified variable. If an error occurs during assignments
2022           (including when expanding the values to be assigned), the execution
2023           of this simple command is aborted with a non-zero exit status.
2024
2025           •   If there is no command name or the name denotes a special
2026               built-in, the assignments are permanent: the assigned values
2027               remain after the command has finished (until the variable is
2028               reassigned).
2029
2030           •   Otherwise, the assignments are temporary: the assigned values
2031               only last during the execution of this simple command.
2032
2033           The assigned variables are automatically exported when the command
2034           name is specified or the all-export option is enabled.
2035
2036               Note
2037               In other shells, assignments may behave differently: For
2038               special built-ins and functions, assigned variables may not be
2039               exported. For functions, assigned variables may be persistent,
2040               that is, may remain even after the execution of the simple
2041               command.
2042
2043        4. If there is no command name, the redirections are processed in a
2044           subshell, then the command execution ends. If an error occurs in
2045           the redirections, the exit status of the simple command is
2046           non-zero. If there were any command substitutions performed in the
2047           assignments, the exit status of the simple command is that of the
2048           last executed command substitution. Otherwise, the exit status is
2049           zero.
2050
2051        5. A command to be executed is determined using the command search
2052           algorithm and the command is executed.
2053
2054           •   If the command is an external command, the command is executed
2055               by creating a new subshell and calling the “exec” system call
2056               in the subshell. The command name and arguments are passed to
2057               the executed command. Exported variables are passed to the
2058               executed command as environment variables.
2059
2060           •   If the command is a built-in, the built-in is executed with the
2061               command arguments passed to the built-in.
2062
2063           •   If the command is a function, the contents of the function are
2064               executed with the command arguments as function arguments.
2065
2066           If the command was executed, the exit status of this simple command
2067           is that of the executed command. If the algorithm failed to
2068           determine a command, no command is executed and the exit status is
2069           127. If the shell failed to execute the determined command, the
2070           exit status is 126. If the executed command was killed by a signal,
2071           the exit status is the signal number plus 384.
2072
2073               Note
2074               In shells other than yash, the exit status may be different
2075               when the command was killed by a signal, because the POSIX
2076               standard only requires that the exit status be "greater than
2077               128."
2078           If the shell is not in the POSIXly-correct mode and the algorithm
2079           failed to determine a command, the command eval -i --
2080           "${COMMAND_NOT_FOUND_HANDLER-}" is evaluated. During the command
2081           execution, positional parameters are temporarily set to the command
2082           name and arguments that resulted in the first step. Any local
2083           variables defined during the execution are removed when the
2084           execution is finished. The HANDLED local variable is automatically
2085           defined with the initial value being the empty string. If the
2086           HANDLED variable has a non-empty value when the execution of the
2087           command string is finished, the shell pretends that the command was
2088           successfully determined and executed. The exit status of the simple
2089           command is that of the command string in this case.
2090
2091       Command search
2092           A command that is executed in a simple command is determined by the
2093           command name using the following algorithm:
2094
2095            1. If the command name contains a slash (/), the whole name is
2096               treated as the pathname of an external command. The external
2097               command is determined as the executed command.
2098
2099            2. If the command name is a special built-in, the built-in is
2100               determined as the executed command.
2101
2102            3. If the command name is the name of an existing function, the
2103               function is determined as the executed command.
2104
2105            4. If the command name is a semi-special built-in, the built-in is
2106               determined as the executed command.
2107
2108            5. If the command name is a regular built-in, the built-in is
2109               determined as the executed command unless the shell is in the
2110               POSIXly-correct mode.
2111
2112            6. The shell searches the PATH for a executed command:
2113
2114               The value of the PATH variable is separated by colons. Each
2115               separated part is considered as a directory pathname (an empty
2116               pathname denotes the current working directory). The shell
2117               searches the directories (in the order of appearance) and
2118               checks if any directory directly contains an executable regular
2119               file whose name is equal to the command name. If such a file is
2120               found:
2121
2122               •   If the command name is the name of a built-in, the built-in
2123                   is determined as the executed command.
2124
2125               •   Otherwise, the file is determined as the executed command.
2126                   (The file will be executed as an external command.)
2127
2128               If no such file is found, no command is determined as the
2129               executed command.
2130
2131           When the shell finds a file that matches the command name during
2132           the search above, the shell remembers the pathname of the file if
2133           it is an absolute path. When the algorithm above is used for the
2134           same command name again, the shell skips searching and directly
2135           determines the command to be executed. If an executable regular
2136           file no longer exists at the remembered pathname, however, the
2137           shell searches again to update the remembered pathname. You can
2138           manage remembered pathnames using the hash built-in.
2139
2140   Termination of the shell
2141       The shell exits when it reached the end of input and has parsed and
2142       executed all input commands or when the exit built-in is executed. The
2143       exit status of the shell is that of the last command the shell executed
2144       (or zero if no commands were executed). The exit status of the shell is
2145       always between 0 and 255 (inclusive). If the exit status of the last
2146       command is 256 or larger, the exit status of the shell will be the
2147       remainder of the exit status divided by 256.
2148
2149       If an exit handler has been registered by the trap built-in, the
2150       handler is executed just before the shell exits. The exit status of the
2151       commands executed in the handler does not affect the exit status of the
2152       shell.
2153
2154       If a non-interactive shell encountered one of the following errors, the
2155       shell immediately exits with a non-zero exit status:
2156
2157       •   A command cannot be parsed due to an syntax error (except during
2158           shell initialization).
2159
2160       •   An error occurs during execution of a special built-in in the
2161           POSIXly-correct mode.
2162
2163       •   A redirection error occurs in a simple command whose command name
2164           is a special built-in and the shell is in the POSIXly-correct mode.
2165
2166       •   An assignment error occurs in a simple command.
2167
2168       •   An error occurs during expansion (except during shell
2169           initialization).
2170
2171           Note
2172           Some shells other than yash exit when they fail to find a command
2173           to execute in command search.
2174
2175   Functions
2176       Functions allow executing a compound command as a simple command. A
2177       function can be defined by the function definition command and executed
2178       by a simple command. You can use the unset built-in to remove function
2179       definitions.
2180
2181       There are no functions predefined when yash is started.
2182
2183       A function is executed by executing its body, which is a compound
2184       command. While the function is being executed, positional parameters
2185       are set to the arguments given to the function. The old positional
2186       parameters are restored when the function execution finishes.
2187
2188       Local variables
2189           Local variables are temporary variables that are defined in a
2190           function and exist during the function execution only. They can be
2191           defined by the typeset built-in or implicitly created by a for
2192           loop. They are removed when the function execution finishes.
2193
2194           Local variables may hide variables that have already been defined
2195           before the function execution had started. An existing variable
2196           becomes inaccessible if a local variable of the same name is
2197           defined in a function. The old variable becomes accessible again
2198           when the function execution finishes.
2199
2200           You cannot create a local variable when not executing a function. A
2201           normal variable is created if you try to do so.
2202
2203   Command execution environment
2204       The shell holds following properties during execution.
2205
2206       •   The working directory
2207
2208       •   Open file descriptors
2209
2210       •   The file creation mask (umask)
2211
2212       •   The set of signals whose handler is set to “ignore” (trap)
2213
2214       •   Environment variables
2215
2216       •   Resource limits (ulimit)
2217
2218       Those properties are inherited from the invoker of the shell to the
2219       shell, and from the shell to each external command executed by the
2220       shell.
2221
2222       The properties can be changed during the execution of the shell by
2223       built-in commands, variable assignments, etc.
2224
2225       Subshells
2226           A subshell is a copy of the shell process. Subshells are used in
2227           execution of groupings, pipelines, etc.
2228
2229           Subshells inherit functions, aliases, etc. defined in the shell as
2230           well as the properties above since subshells are copies of the
2231           shell process. Notable exceptions are:
2232
2233           •   Traps registered by the trap built-in are all reset in
2234               subshells except for ones whose action is set to “ignore”. (See
2235               below)
2236
2237           •   The interactive mode and job control are disabled in subshells.
2238               Jobs are not inherited by subshells.
2239
2240           Subshells are executed independently of the original shell, so
2241           changes of any properties above do not affect those of the original
2242           shell.
2243
2244               Note
2245               If the subshell contains a single trap built-in, some shells
2246               (but not yash) may not reset the traps on entry to the
2247               subshell.
2248

INTERACTIVE MODE

2250       The interactive mode is a mode of the shell intended for direct
2251       interaction with a user. If yash is in the interactive mode, it is
2252       called an interactive shell.
2253
2254       Whether a shell runs in the interactive mode or not is determined in
2255       the invocation of the shell. After the shell has started up, the
2256       interactive mode cannot be switched on or off.
2257
2258       When the shell is interactive:
2259
2260       •   Initialization scripts are executed during invocation.
2261
2262       •   The shell checks for mail and prints a command prompt when it reads
2263           a command. Job status changes are also reported if job control is
2264           active.  Line-editing may be used depending on the capability of
2265           the terminal.
2266
2267       •   Commands executed are automatically registered in command history.
2268
2269       •   If a command executed by the shell is killed by a signal other than
2270           SIGINT and SIGPIPE, the shell reports the fact to the standard
2271           error.
2272
2273       •   The filename token is subject to pathname expansion in file
2274           redirection.
2275
2276       •   The shell does not exit when it encounters a syntax or expansion
2277           error during command execution. (cf.  Termination of the shell)
2278
2279       •   The shell does not exit when it receives the SIGINT, SIGTERM, or
2280           SIGQUIT signal.
2281
2282       •   A signal handler can be changed by the trap built-in even if the
2283           handler had been set to “ignore” when the shell was invoked.
2284
2285       •   The value of the - special parameter contains i.
2286
2287       •   The shell’s locale reflects the value of the LC_CTYPE variable
2288           whenever the value is changed (if the shell is not in the
2289           POSIXly-correct mode).
2290
2291       •   Commands are executed even when the exec option is off.
2292
2293       •   The ignore-eof option takes effect when enabled.
2294
2295       •   When the shell reaches the end of input or the exit built-in is
2296           executed, the shell checks if there is any stopped job. If so, the
2297           shell prints a warning and does not actually exit.
2298
2299       •   The suspend built-in by default cannot stop the shell if it is a
2300           session leader.
2301
2302       •   The shell does not exit when the dot built-in fails to find a
2303           script file to read.
2304
2305       •   The shell does not exit when the exec built-in fails to execute a
2306           command (if not in the POSIXly-correct mode).
2307
2308       •   When a job finished for which the wait built-in has been waiting,
2309           the fact is reported (only if job control is active and not in the
2310           POSIXly-correct mode).
2311
2312       •   A prompt is printed when the read built-in reads a second or
2313           following line.
2314
2315   Prompts
2316       The interactive shell prints a prompt just before it reads a command.
2317       The contents of the prompt is specified by the value of the PS1 and PS2
2318       variables. The former is used for reading the first line of the command
2319       and the latter for other lines.
2320
2321       When the prompt is printed, the variable value is subjected to
2322       parameter expansion, command substitution, and arithmetic expansion
2323       (but note that the POSIX standard requires parameter expansion only).
2324       The result of the expansion is parsed by the rules below to make the
2325       actual prompt string, which is printed to the standard error.
2326
2327       In the POSIXly-correct mode, each exclamation mark (!) in the string is
2328       substituted with the command history number of the command that is
2329       being input. Two adjacent exclamation marks (!!) are printed as a
2330       single exclamation. Other characters are printed intact.
2331
2332       If the shell is not in the POSIXly-command mode, the following
2333       notations can be used to format the prompt string. Notations are
2334       replaced with the strings designated in the list below. Characters that
2335       are not interpreted as notations are printed intact.
2336
2337       \a
2338           Bell character (ASCII code: 7)
2339
2340       \e
2341           Escape character (ASCII code: 27)
2342
2343       \j
2344           The number of jobs in the shell.
2345
2346       \n
2347           Newline character (ASCII code: 10)
2348
2349       \r
2350           Carriage return character (ASCII code: 13)
2351
2352       \!
2353           The command history number of the command that is being input
2354
2355       \$
2356           # if the shell’s effective user ID is 0; $ otherwise.
2357
2358       \\
2359           Backslash
2360
2361       \[, \]
2362           These two notations can surround part of the prompt string that is
2363           not visible on the terminal. The surrounded part is ignored when
2364           the shell counts the number of characters that is displayed on the
2365           terminal, thus making characters correctly aligned on the terminal
2366           when the prompt string contains special invisible characters.
2367
2368       \ffontspecs.
2369           When line-editing is active, this notation is replaced with special
2370           characters to change font styles on the terminal if the terminal is
2371           capable of it. If line-editing is inactive or the terminal is
2372           incapable of changing font styles, this notation is silently
2373           ignored. One or more of the following can be used for fontspecs:
2374
2375           k
2376               Change font color to black
2377
2378           r
2379               Change font color to red
2380
2381           g
2382               Change font color to green
2383
2384           y
2385               Change font color to yellow
2386
2387           b
2388               Change font color to blue
2389
2390           m
2391               Change font color to magenta
2392
2393           c
2394               Change font color to cyan
2395
2396           w
2397               Change font color to white
2398
2399           K
2400               Change background color to black
2401
2402           R
2403               Change background color to red
2404
2405           G
2406               Change background color to green
2407
2408           Y
2409               Change background color to yellow
2410
2411           B
2412               Change background color to blue
2413
2414           M
2415               Change background color to magenta
2416
2417           C
2418               Change background color to cyan
2419
2420           W
2421               Change background color to white
2422
2423           t
2424               Make font color or background brighter (can only be used just
2425               after one of the characters above)
2426
2427           d
2428               Change font and background colors to normal
2429
2430           s
2431               Make font standout
2432
2433           u
2434               Make font underlined
2435
2436           v
2437               Make font and background colors reversed
2438
2439           b
2440               Make font blink
2441
2442           i
2443               Make font dim
2444
2445           o
2446               Make font bold
2447
2448           x
2449               Make font invisible
2450
2451           D
2452               Make color and style normal
2453
2454           The actual colors of font and background are defined by the
2455           terminal. Different terminals may use different colors.
2456
2457       In addition to the normal prompt, a prompt string can be displayed to
2458       the right of the cursor if line-editing is active. Those prompts are
2459       called right prompts. The contents of right prompts are defined by the
2460       value of the PS1R and PS2R variables, each corresponding to the PS1 and
2461       PS2 variables.
2462
2463       Using the above-said notations, the font style of command strings the
2464       user inputs can be changed as well as that of prompts. The font style
2465       of command strings is defined by the value of the PS1S and PS2S
2466       variables, each corresponding to the PS1 and PS2 variables. The value
2467       can contain the \ffontspecs. notation only.
2468
2469       When the shell is not in the POSIXly-correct mode, the prompt variables
2470       can be defined with a name prefixed with YASH_ (e.g. YASH_PS1). This
2471       allows using a different prompt string than that in the POSIXly-correct
2472       mode.
2473
2474       When the shell is not in the POSIXly-correct mode, the value of the
2475       PROMPT_COMMAND variable is executed before each prompt.
2476
2477   Command history
2478       Command history is a feature of the shell that remembers executed
2479       commands to allow re-executing them later. Commands executed in the
2480       interactive mode are automatically saved in the command history. Saved
2481       commands can be edited and re-executed using line-editing and the fc
2482       and history built-ins.
2483
2484       Commands are saved line by line. Lines that do not contain any
2485       non-whitespace characters are not saved in the history. Lines that
2486       start with whitespaces are not saved when the hist-space option is on.
2487
2488       Command history is saved in a file. When history is first used after an
2489       interactive shell was started, the shell opens a file to save history
2490       in. The filename is specified by the value of the HISTFILE variable. If
2491       the file contains history data when opened, the data is restored to the
2492       shell’s history. The file contents are updated in real time as the user
2493       inputs commands into the shell. If the HISTFILE variable is not set or
2494       the file cannot be opened successfully, history is not saved in the
2495       file, but the history feature will be functional in all other respects.
2496
2497       The number of commands saved in history is specified by the value of
2498       the HISTSIZE variable. The shell automatically removes old history data
2499       so that the number of saved commands does not exceed the value. If the
2500       HISTSIZE variable is not set or its value is not a natural number, 500
2501       items will be saved in history.
2502
2503       The shell looks at the value of the HISTFILE and HISTSIZE variables
2504       only when the history feature is first used after the shell was
2505       started. “The history feature is used” when:
2506
2507       •   the fc or history built-in is executed,
2508
2509       •   line-editing is used (regardless of whether or not history data is
2510           recalled in line-editing), or
2511
2512       •   a command is input to the shell
2513
2514       Therefore, the variables should be set in initialization scripts.
2515
2516       When more than one instance of yash shares a single history file, all
2517       the shells use the same history data. As a result, commands that have
2518       been executed by a shell instance can be recalled on another shell
2519       instance. Shells sharing the same history should have the same HISTSIZE
2520       value so that they manipulate history data properly.
2521
2522       Yash’s history data file has its own format that is incompatible with
2523       other kinds of shells.
2524
2525       The HISTRMDUP variable can be set to remove duplicate history items.
2526
2527   Mail checking
2528       An interactive shell can notify receipt of email. The shell
2529       periodically checks the modification date/time of a file specified by
2530       the user. If the file has been modified since the previous check, the
2531       shell prints a notification message (except when the shell is not in
2532       the POSIXly-correct mode and the file is empty). By specifying a
2533       mailbox file to be checked, the shell will print a message when the
2534       file has been modified, that is, some mail has been received.
2535
2536       Check is done just before the shell prints a command line prompt. The
2537       interval of checks can be specified by the MAILCHECK variable in
2538       seconds. If the variable value is 0, check is done before every prompt.
2539       If the variable value is not a non-negative integer, no checks are
2540       done.
2541
2542       The file whose modification time is checked is specified by the MAIL
2543       variable. The variable value should be set to the pathname of the file.
2544
2545       If you want to check more than one file or customize the notification
2546       message, you can set the MAILPATH variable instead of the MAIL
2547       variable. When the MAILPATH variable is set, the MAIL variable is
2548       ignored. The value of the MAILPATH variable should be set to one or
2549       more colon-separated pathnames of files to be checked. Each pathname
2550       can be followed by a percent sign (%) and a custom notification
2551       message, which is printed when the corresponding file has been
2552       modified. If the pathname contains a percent sign, it should be quoted
2553       by a backslash. The specified message is subject to parameter
2554       expansion. For example, if the value of the MAILPATH variable is
2555       /foo/mail%New mail!:/bar/mailbox%You've got mail:/baz/mail\%data, the
2556       shell will print
2557
2558New mail!  when the file /foo/mail has been modified
2559
2560You've got mail when the file /bar/mailbox has been modified
2561
2562       •   the default message when the file /baz/mail%data has been modified.
2563

JOB CONTROL

2565       Job control is a function of the shell that executes multiple commands
2566       simultaneously and suspends/resumes the commands.
2567
2568       When job control is active:
2569
2570       •   Every pipeline executed by the shell becomes a job. A job has its
2571           unique process group ID that is shared among all processes in the
2572           job.
2573
2574       •   If the processes of a job are suspended while the shell is waiting
2575           for the processes to finish, the shell continues to the next
2576           command as if the process have finished. The shell remembers the
2577           job as suspended so that it can be resumed later.
2578
2579       •   If a job is executed synchronously, the shell sets the foreground
2580           process group of the terminal to the process group of the job. When
2581           the job is finished (or suspended), the shell gets back to the
2582           foreground.
2583
2584       •   The subshell executing a command substitution has its own unique
2585           process group ID like a job. However, the shell does not remember
2586           the subshell as a job, so it cannot be suspended or resumed.
2587
2588       •   If the shell is interactive, job status is reported before every
2589           command line prompt as if the command jobs -n is executed.
2590
2591       •   The standard input of an asynchronous command is not automatically
2592           redirected to /dev/null.
2593
2594       •   The shell does not exit when it receives the SIGTSTP signal.
2595
2596       •   The value of the - special parameter contains m.
2597
2598       •   When a job finished for which the wait built-in has been waiting,
2599           the fact is reported (only if the shell is interactive and not in
2600           the POSIXly-correct mode).
2601
2602       When job control is inactive, processes executed by the shell have the
2603       same process group ID as the shell. The shell treats asynchronous
2604       commands as an uncontrolled job.
2605
2606       You can use the following built-ins to manipulate jobs:
2607
2608       jobs
2609           prints existing jobs
2610
2611       fg and bg
2612           run jobs in the foreground or background
2613
2614       wait
2615           waits for jobs to be finished (or suspended)
2616
2617       disown
2618           forgets jobs
2619
2620       kill
2621           sends a signal to jobs
2622
2623       An interactive job-controlling shell reports jobs status before every
2624       prompt by default. You can set the following options to make the shell
2625       report status at other timings:
2626
2627       notify
2628           the shell reports immediately whenever job status changes.
2629
2630       notify-le
2631           the shell reports immediately when job status changes while
2632           line-editing.
2633
2634       A job is removed from the shell’s job list when:
2635
2636       •   it has finished and the jobs built-in reported it,
2637
2638       •   the wait built-in successfully waited for the job to finish, or
2639
2640       •   the disown built-in removed the job.
2641
2642       Jobs are not removed from the list when an interactive shell
2643       automatically reports the status of jobs.
2644
2645           Note
2646           The word “stop” is synonymous to “suspend” in the context of job
2647           control.
2648
2649   Job ID
2650       Some built-ins use the following notation, which is called job ID, to
2651       specify a job to operate on:
2652
2653       %, %%, %+
2654           the current job
2655
2656       %-
2657           the previous job
2658
2659       %n
2660           the job that has job number n, where n is a positive integer
2661
2662       %string
2663           the job whose name begins with string
2664
2665       %?string
2666           the job whose name contains string
2667
2668       The current job and previous job are jobs selected by the shell
2669       according to the following rules:
2670
2671       •   When there is one or more suspended jobs, the current job is
2672           selected from them.
2673
2674       •   When there is one or more suspended jobs other than the current
2675           job, the previous job is selected from them.
2676
2677       •   The current and previous jobs are always different. When the shell
2678           has only one job, it is the current job and there is no previous
2679           job.
2680
2681       •   When the current job finished, the previous job becomes the current
2682           job.
2683
2684       •   When the current job is changed, the old current job becomes the
2685           previous job except when the old job finished.
2686
2687       •   When the foreground job is suspended, the job becomes the current
2688           job.
2689
2690       Yash has some options to modify the rules of the current/previous job
2691       selection. (The rules above have priority over the options below.)
2692
2693       cur-async
2694           When a new asynchronous command is started, it becomes the current
2695           job.
2696
2697       cur-bg
2698           When a job is resumed by the bg built-in, the job becomes the
2699           current job.
2700
2701       cur-stop
2702           When a job is suspended, it becomes the current job.
2703
2704       The current and previous jobs are not changed as long as the rules
2705       above are met.
2706
2707       The rules of the current/previous job selection defined in the POSIX
2708       standard are looser than yash’s rules above. Other POSIX-compliant
2709       shells may select the current and previous jobs differently.
2710

BUILT-IN COMMANDS

2712       Built-in commands are commands that are implemented in the shell and
2713       are executed by the shell without external programs.
2714
2715   Types of built-in commands
2716       There are three types of built-in commands in yash: special built-in
2717       commands, semi-special built-in commands and regular built-in commands.
2718
2719       Special built-in commands are much more important commands than others.
2720       They are executed regardless of whether the corresponding external
2721       commands exist or not. Results of variable assignments that occur in a
2722       simple command that invokes a special built-in last after the command
2723       has finished. Moreover, in the POSIXly-correct mode, a non-interactive
2724       shell immediately exits with a non-zero exit status when a redirect
2725       error, assignment error, or misuse of option or operand occurs in a
2726       special built-in command.
2727
2728       Semi special built-in commands are the second important built-in
2729       commands. They are executed regardless of whether the corresponding
2730       external commands exist or not. In other parts they are the same as
2731       regular built-in commands.
2732
2733       Regular built-in commands are less important built-in commands
2734       including commands that can be implemented as external commands or are
2735       not listed in POSIX. In the POSIXly-correct mode, a regular built-in is
2736       executed only when a corresponding external command is found in PATH.
2737
2738   Syntax of command arguments
2739       In this section we explain common rules about command arguments. The
2740       built-in commands of yash follow the rules unless otherwise stated.
2741
2742       There are two types of command arguments. One is options and the other
2743       is operands. An option is an argument that starts with a hyphen (-) and
2744       changes the way the command behaves. Some options take arguments. An
2745       operand is an argument that is not an option and specifies objects the
2746       command operates on.
2747
2748       If you specify more than one option to a command, the order of the
2749       options are normally not significant. The order of operands, however,
2750       affects the command behavior.
2751
2752       An option is either a single-character option or a long option. A
2753       single-character option is identified by one alphabetic character. A
2754       long option is identified by multiple alphabetic characters. The POSIX
2755       standard only prescribes single-character options, so in the
2756       POSIXly-correct mode you cannot use long options.
2757
2758       A single-character option is composed of a hyphen followed by a letter.
2759       For example, -a is a single-character option. A single-character option
2760       that takes an argument requires the argument to be just after the
2761       option name.
2762
2763       Example 4. The set built-in and single-character options
2764
2765       For the set built-in, -m is a single-character option that does not
2766       take an argument and -o is one that takes an argument.
2767
2768set -o errexit -m
2769
2770set -oerrexit -m
2771
2772       In these two command lines, errexit is the argument to the -o option.
2773
2774       In the second example above, the -o option and its argument are
2775       combined into a single command line argument. The POSIX standard
2776       deprecates that style and any POSIX-conforming applications must
2777       specify options and their arguments as separate command line arguments,
2778       although yash accepts both styles.
2779
2780       You can combine single-character options that do not take arguments
2781       into a single command line argument. For example, the three options -a,
2782       -b and -c can be combined into -abc.
2783
2784       A long option is composed of two hyphens followed by an option name.
2785       For example, --long-option is a long option. You can omit some last
2786       characters of a long option name as long as it is not ambiguous. For
2787       example, you can use --long instead of --long-option if there is no
2788       other options beginning with --long. Like a single-character option, a
2789       long option that takes an argument requires the argument to be a
2790       command line argument just after the option name or to be specified in
2791       the same command line argument as the option name, separated by an
2792       equal sign (=).
2793
2794       Example 5. The fc built-in and long options
2795
2796       For the fc built-in, --quiet is a long option that does not take an
2797       argument and --editor is one that takes an argument.
2798
2799fc --editor vi --quiet
2800
2801fc --editor=vi --quiet
2802
2803       In these command lines, vi is the argument to the --editor option.
2804
2805       Arguments that are not options (nor arguments to them) are interpreted
2806       as operands. The POSIX standard requires all options should be
2807       specified before any operands. Therefore, in the POSIXly-correct mode,
2808       any arguments that come after the first operand are interpreted as
2809       operands (even if they look like options). If not in the
2810       POSIXly-correct mode, you can specify options after operand.
2811
2812       Regardless of whether the shell is in the POSIXly-correct mode or not,
2813       an argument that is just composed of two hyphens (--) can be used as a
2814       separator between options and operands. All command line arguments
2815       after the -- separator are interpreted as operands, so you can specify
2816       operands that start with a hyphen correctly using the separator.
2817
2818       Example 6. Options and operands to the set built-in
2819
2820set -a -b -- -c -d
2821
2822       In this example, -a and -b are options and -c and -d are operands. The
2823       -- separator itself is neither an option nor an operand.
2824
2825       Regardless of whether the shell is in the POSIXly-correct mode or not,
2826       an argument that is just composed of a single hyphen (-) is interpreted
2827       as an operand.
2828

LINE-EDITING

2830       With the line-editing feature, you can edit the command text when you
2831       input a command to an interactive shell. It not only works as a simple
2832       visual-interface editor, but also is integrated with the command
2833       history. You can recall, edit, and execute commands in the history with
2834       line-editing instead of using the fc built-in.
2835
2836       Line-editing has two editing modes, the vi and emacs modes, which each
2837       have their own key binding settings. By switching editing modes, you
2838       can change key bindings used in line-editing. Each mode has a
2839       corresponding shell option, which determines whether the mode is
2840       currently active or not. No more than one mode can be active at a time,
2841       so the options for the other modes are automatically turned off when
2842       you turn on the option for one mode. The whole line-editing feature is
2843       deactivated when those options are off.
2844
2845       When an interactive shell is started, the vi mode is automatically
2846       activated if the standard input and error are both connected to a
2847       terminal.
2848
2849       Line-editing can be used only when the standard input and error are
2850       both connected to a terminal. If not, the shell silently falls back to
2851       the normal input mechanism. While line-editing is being used, the shell
2852       uses the termios interface to change I/O settings of the terminal and
2853       the terminfo interface to parse input key sequences.
2854
2855   Shell options on line-editing
2856       The following options can be set by the set built-in to enable
2857       line-editing and choose an editing mode to activate:
2858
2859       vi
2860           activates the vi mode.
2861
2862       emacs
2863           activates the emacs mode.
2864
2865       The other line-editing-related options are:
2866
2867       le-always-rp
2868           When this options is enabled, the right prompt is always visible:
2869           when the cursor reaches the right prompt, it moves to the next line
2870           from the original position, which would otherwise be overwritten by
2871           input text.
2872
2873       le-comp-debug
2874           When enabled, internal information is printed during completion,
2875           which will help debugging completion scripts.
2876
2877       le-conv-meta
2878           When enabled, the 8th bit of each input byte is always treated as a
2879           meta-key flag, regardless of terminfo data.
2880
2881       le-no-conv-meta
2882           When enabled, the 8th bit of each input byte is never treated as a
2883           meta-key flag, regardless of terminfo data.
2884
2885           The le-conv-meta and le-no-conv-meta options cannot be both enabled
2886           at a time. When either is enabled, the other is automatically
2887           disabled. When neither is enabled, the 8th bit may be treated as a
2888           meta-key flag depending on terminfo data.
2889
2890       le-predict
2891           activates command line prediction.
2892
2893       le-predict-empty
2894           When enabled, and command line prediction is active, suggestions
2895           are also provided for empty input lines.
2896
2897       le-prompt-sp
2898           When enabled, the shell prints a special character sequence before
2899           printing each prompt so that every prompt is printed at the
2900           beginning of a line.
2901
2902           This option is enabled by default.
2903
2904       le-visible-bell
2905           When enabled, the shell flashes the terminal instead of sounding an
2906           alarm when an alert is required.
2907
2908   Editing modes
2909       The vi mode is an editing mode that offers key bindings similar to that
2910       of the vi editor. The vi mode has two sub-modes that are switched
2911       during editing: the insert and command modes. The sub-mode is always
2912       reset to the insert mode when line-editing is started for a new command
2913       line. In the insert mode, most characters are inserted to the buffer as
2914       typed. In the command mode, input characters are treated as commands
2915       that move the cursor, insert/delete text, etc.
2916
2917       The emacs mode offers key bindings similar to the emacs editor. Most
2918       characters are inserted to the buffer as typed, but more characters are
2919       treated as commands than the vi insert mode.
2920
2921       Another sub-mode is used while you enter search keywords. The sub-mode
2922       is called the search mode, which offers slightly different key bindings
2923       depending on the active editing mode.
2924
2925   Line-editing commands
2926       All characters the user enters while line-editing is active are treated
2927       as line-editing commands listed below. The bindkey built-in allows
2928       customizing the key bindings of each mode (except for the search mode).
2929
2930       The list below shows not only the functions of commands but also the
2931       default key bindings. The keywords “vi-insert”, “vi-command”,
2932       “vi-search”, “emacs”, “emacs-search” means the vi insert mode, the vi
2933       command mode, the search mode for the vi mode (the vi search mode), the
2934       emacs mode, and the search mode for the emacs mode (the emacs search
2935       mode), respectively.
2936
2937       Some commands take an argument that affects the function of the
2938       commands. For example, the forward-char command moves the cursor by as
2939       many characters as specified by the argument. To specify an argument,
2940       use the digit-argument command just before another command that takes
2941       an argument.
2942
2943       Basic editing commands
2944           noop
2945               Do nothing.
2946
2947               vi-command
2948                   \^[
2949
2950           alert
2951               Alert.
2952
2953           self-insert
2954               Insert the input character at the current cursor position.
2955               Characters escaped by escape sequences cannot be inserted.
2956
2957               vi-insert, emacs
2958                   \\
2959
2960           insert-tab
2961               Insert a tab character at the current cursor position.
2962
2963               emacs
2964                   \^[\^I
2965
2966           expect-verbatim
2967               Insert a character that is entered just after this command at
2968               the current cursor position. This command can input a character
2969               that cannot be input by the self-insert command, except a null
2970               character ('\0').
2971
2972               vi-insert, vi-search, emacs-search
2973                   \^V
2974
2975               emacs
2976                   \^Q, \^V
2977
2978           digit-argument
2979               Pass the input digit to the next command as an argument.
2980
2981               This command can be bound to a digit or hyphen. To pass “12” as
2982               an argument to the forward-char command in the vi mode, for
2983               example, enter 12l.
2984
2985               vi-command
2986                   1, 2, 3, 4, 5, 6, 7, 8, 9
2987
2988               emacs
2989                   \^[0, \^[1, \^[2, \^[3, \^[4, \^[5, \^[6, \^[7, \^[8, \^[9,
2990                   \^[-,
2991
2992           bol-or-digit
2993               Like the beginning-of-line command if there is no argument;
2994               like the digit-argument command otherwise.
2995
2996               vi-command
2997                   0
2998
2999           accept-line
3000               Finish editing the current line. A newline is automatically
3001               appended to the line. The line will be executed by the shell.
3002
3003               If command line prediction is active, the current prediction
3004               (if any) is ignored. See also the accept-prediction command.
3005
3006               vi-insert, vi-command, emacs, emacs-search
3007                   \^J, \^M
3008
3009           abort-line
3010               Abandon the current buffer and finish editing as if an empty
3011               line was input.
3012
3013               vi-insert, vi-command, vi-search, emacs, emacs-search
3014                   \!, \^C
3015
3016           eof
3017               Abandon the current buffer and finish editing as if the shell
3018               reached the end of input. This normally makes the shell exit.
3019
3020           eof-if-empty
3021               Like the eof command if the buffer is empty; like the alert
3022               command otherwise.
3023
3024               vi-insert, vi-command
3025                   \#, \^D
3026
3027           eof-or-delete
3028               Like the eof command if the buffer is empty; like the
3029               delete-char command otherwise.
3030
3031               emacs
3032                   \#, \^D
3033
3034           accept-with-hash
3035               If the current line does not begin with a hash sign (#) or
3036               there is no argument specified for this command, a hash sign is
3037               inserted at the beginning of the line. Otherwise, the beginning
3038               hash sign is removed from the line. Finally, the line is
3039               accepted like the accept-line command.
3040
3041               vi-command
3042                   #
3043
3044               emacs
3045                   \^[#
3046
3047           accept-prediction
3048               Like the accept-line command, but include the predicted part.
3049
3050           setmode-viinsert
3051               Switch to the vi insert mode.
3052
3053               vi-command
3054                   i, \I
3055
3056           setmode-vicommand
3057               Switch to the vi command mode.
3058
3059               vi-insert
3060                   \^[
3061
3062           setmode-emacs
3063               Switch to the emacs mode.
3064
3065           expect-char, abort-expect-char
3066               These commands are not meant for use by the user. They are used
3067               by the shell to implement some other commands.
3068
3069           redraw-all
3070               Reprint the prompt and the current line to the terminal.
3071
3072               vi-insert, vi-command, vi-search, emacs, emacs-search
3073                   \^L
3074
3075           clear-and-redraw-all
3076               Clear the terminal and reprint the prompt and the current line.
3077
3078       Motion commands
3079           Motion commands move the cursor on the line. Most motion commands
3080           accept an argument. When passed an argument, they repeat the cursor
3081           motion as many times as specified by the argument. Passing “4” as
3082           an argument to the forward-char command, for example, advances the
3083           cursor by four characters.
3084
3085           The shell has several definitions of words as units of distance: A
3086           bigword is one or more adjacent non-whitespace characters. A
3087           semiword is one or more adjacent characters that contain no
3088           whitespaces or punctuations. An emacsword is one or more adjacent
3089           alphanumeric characters. A viword is either:
3090
3091           •   one or more adjacent alphanumeric characters and/or underscores
3092               (_), or
3093
3094           •   one or more adjacent characters that contain none of
3095               alphanumeric characters, underscores, and whitespaces.
3096
3097           forward-char
3098               Move the cursor to the next character.
3099
3100               vi-insert
3101                   \R
3102
3103               vi-command
3104                   l, (space), \R
3105
3106               emacs
3107                   \R, \^F
3108
3109           backward-char
3110               Move the cursor to the previous character.
3111
3112               vi-insert
3113                   \L
3114
3115               vi-command
3116                   h, \B, \L, \?, \^H
3117
3118               emacs
3119                   \L, \^B
3120
3121           forward-bigword
3122               Move the cursor to the next bigword.
3123
3124               vi-command
3125                   W
3126
3127           end-of-bigword
3128               Move the cursor to the next end of a bigword.
3129
3130               vi-command
3131                   E
3132
3133           backward-bigword
3134               Move the cursor to the previous bigword.
3135
3136               vi-command
3137                   B
3138
3139           forward-semiword
3140               Move the cursor to the next semiword.
3141
3142           end-of-semiword
3143               Move the cursor to the next end of a semiword.
3144
3145           backward-semiword
3146               Move the cursor to the previous semiword.
3147
3148           forward-viword
3149               Move the cursor to the next viword.
3150
3151               vi-command
3152                   w
3153
3154           end-of-viword
3155               Move the cursor to the next end of a viword.
3156
3157               vi-command
3158                   e
3159
3160           backward-viword
3161               Move the cursor to the previous viword.
3162
3163               vi-command
3164                   b
3165
3166           forward-emacsword
3167               Move the cursor to the next emacsword.
3168
3169               emacs
3170                   \^[f, \^[F
3171
3172           backward-emacsword
3173               Move the cursor to the previous emacsword.
3174
3175               emacs
3176                   \^[b, \^[B
3177
3178           beginning-of-line
3179               Move the cursor to the beginning of the line.
3180
3181               vi-insert, vi-command
3182                   \H
3183
3184               emacs
3185                   \H, \^A
3186
3187           end-of-line
3188               Move the cursor to the end of the line.
3189
3190               vi-insert
3191                   \E
3192
3193               vi-command
3194                   $, \E
3195
3196               emacs
3197                   \E, \^E
3198
3199           go-to-column
3200               Move the cursor to the nth character on the line, where n is
3201               the argument. Assume n = 1 when no argument.
3202
3203               vi-command
3204                   |
3205
3206           first-nonblank
3207               Move the cursor to the first non-blank character on the line.
3208
3209               vi-command
3210                   ^
3211
3212           find-char
3213               Move the cursor to the first position where a character that is
3214               entered just after this command appears after the current
3215               cursor position.
3216
3217               vi-command
3218                   f
3219
3220               emacs
3221                   \^]
3222
3223           find-char-rev
3224               Move the cursor to the last position where a character that is
3225               entered just after this command appears before the current
3226               cursor position.
3227
3228               vi-command
3229                   F
3230
3231               emacs
3232                   \^[\^]
3233
3234           till-char
3235               Move the cursor to the first position just before a character
3236               that is entered just after this command appears after the
3237               current cursor position.
3238
3239               vi-command
3240                   t
3241
3242           till-char-rev
3243               Move the cursor to the last position just after a character
3244               that is entered just after this command appears before the
3245               current cursor position.
3246
3247               vi-command
3248                   T
3249
3250           refind-char
3251               Redo the last find-char, find-char-rev, till-char,
3252               till-char-rev command.
3253
3254               vi-command
3255                   ;
3256
3257           refind-char-rev
3258               Redo the last find-char, find-char-rev, till-char,
3259               till-char-rev command in the reverse direction.
3260
3261               vi-command
3262                   ,
3263
3264       Editing commands
3265           Editing commands modify contents of the buffer. Most editing
3266           commands accept an argument. When passed an argument, they repeat
3267           the modification as many times as specified by the argument.
3268
3269           Texts deleted by commands whose name starts with “kill” are saved
3270           in kill ring, from which deleted contents can be restored to the
3271           buffer. The most recent 32 texts are kept in the kill ring.
3272
3273           delete-char
3274               Delete a character at the current cursor position if no
3275               argument is passed; like the kill-char command otherwise.
3276
3277               vi-insert, emacs
3278                   \X
3279
3280           delete-bigword
3281               Delete a bigword at the current cursor position if no argument
3282               is passed; like the kill-bigword command otherwise.
3283
3284           delete-semiword
3285               Delete a semiword at the current cursor position if no argument
3286               is passed; like the kill-semiword command otherwise.
3287
3288           delete-viword
3289               Delete a viword at the current cursor position if no argument
3290               is passed; like the kill-viword command otherwise.
3291
3292           delete-emacsword
3293               Delete a emacsword at the current cursor position if no
3294               argument is passed; like the kill-emacsword command otherwise.
3295
3296           backward-delete-char
3297               Delete a character just before the current cursor position if
3298               no argument is passed; like the backward-kill-char command
3299               otherwise.
3300
3301               vi-insert, emacs
3302                   \B, \?, \^H
3303
3304           backward-delete-bigword
3305               Delete a bigword just before the current cursor position if no
3306               argument is passed; like the backward-kill-bigword command
3307               otherwise.
3308
3309           backward-delete-semiword
3310               Delete a semiword just before the current cursor position if no
3311               argument is passed; like the backward-kill-semiword command
3312               otherwise.
3313
3314               vi-insert
3315                   \^W
3316
3317           backward-delete-viword
3318               Delete a viword just before the current cursor position if no
3319               argument is passed; like the backward-kill-viword command
3320               otherwise.
3321
3322           backward-delete-emacsword
3323               Delete a emacsword just before the current cursor position if
3324               no argument is passed; like the backward-kill-emacsword command
3325               otherwise.
3326
3327           delete-line
3328               Delete the whole buffer contents.
3329
3330           forward-delete-line
3331               Delete all characters from the current cursor position to the
3332               end of the buffer.
3333
3334           backward-delete-line
3335               Delete all characters before the current cursor position.
3336
3337               vi-insert
3338                   \$, \^U
3339
3340           kill-char
3341               Delete a character at the current cursor position and add it to
3342               the kill ring.
3343
3344               vi-command
3345                   x, \X
3346
3347           kill-bigword
3348               Delete a bigword at the current cursor position and add it to
3349               the kill ring.
3350
3351           kill-semiword
3352               Delete a semiword at the current cursor position and add it to
3353               the kill ring.
3354
3355           kill-viword
3356               Delete a viword at the current cursor position and add it to
3357               the kill ring.
3358
3359           kill-emacsword
3360               Delete a emacsword at the current cursor position and add it to
3361               the kill ring.
3362
3363               emacs
3364                   \^[d, \^[D
3365
3366           backward-kill-char
3367               Delete a character just before the current cursor position and
3368               add it to the kill ring.
3369
3370               vi-command
3371                   X
3372
3373           backward-kill-bigword
3374               Delete a bigword just before the current cursor position and
3375               add it to the kill ring.
3376
3377               emacs
3378                   \^W
3379
3380           backward-kill-semiword
3381               Delete a semiword just before the current cursor position and
3382               add it to the kill ring.
3383
3384           backward-kill-viword
3385               Delete a viword just before the current cursor position and add
3386               it to the kill ring.
3387
3388           backward-kill-emacsword
3389               Delete a emacsword just before the current cursor position and
3390               add it to the kill ring.
3391
3392               emacs
3393                   \^[\B, \^[\?, \^[\^H
3394
3395           kill-line
3396               Delete the whole buffer contents and add it to the kill ring.
3397
3398           forward-kill-line
3399               Delete all characters from the current cursor position to the
3400               end of the buffer and add it to the kill ring.
3401
3402               emacs
3403                   \^K
3404
3405           backward-kill-line
3406               Delete all characters before the current cursor position and
3407               add it to the kill ring.
3408
3409               emacs
3410                   \$, \^U, \^X\B, \^X\?
3411
3412           put-before
3413               Insert the last-killed text before the current cursor position
3414               and move the cursor to the last character that was inserted.
3415
3416               vi-command
3417                   P
3418
3419           put
3420               Insert the last-killed text after the current cursor position
3421               and move the cursor to the last character that was inserted.
3422
3423               vi-command
3424                   p
3425
3426           put-left
3427               Insert the last-killed text before the current cursor position
3428               and move the cursor to the last character that was inserted.
3429
3430               emacs
3431                   \^Y
3432
3433           put-pop
3434               Replace the just put text with the next older killed text.
3435
3436               This command can be used only just after the put-before, put,
3437               put-left, or put-pop command.
3438
3439               emacs
3440                   \^[y, \^[Y
3441
3442           undo
3443               Cancel modification by the last editing command.
3444
3445               vi
3446                   u
3447
3448               emacs
3449                   \^_, \^X\$, \^X\^U
3450
3451           undo-all
3452               Cancel all modification in the current buffer, restoring the
3453               initial contents.
3454
3455               vi
3456                   U
3457
3458               emacs
3459                   \^[\^R, \^[r, \^[R
3460
3461           cancel-undo
3462               Cancel cancellation by the last undo or undo-all command.
3463
3464               vi
3465                   \^R
3466
3467           cancel-undo-all
3468               Cancel all cancellation by all most recent undo and undo-all
3469               commands.
3470
3471           redo
3472               Repeat modification by the last editing command.
3473
3474               vi-command
3475                   .
3476
3477       Completion commands
3478           complete
3479               Complete a word just before the cursor position and, if there
3480               is more than one candidate, show a list of the candidates.
3481
3482           complete-next-candidate
3483               Like the complete command when candidates are not being listed;
3484               otherwise, select the next candidate in the list.
3485
3486               vi-insert, emacs
3487                   \^I
3488
3489           complete-prev-candidate
3490               Like the complete command when candidates are not being listed;
3491               otherwise, select the previous candidate in the list.
3492
3493               vi-insert, emacs
3494                   \bt
3495
3496           complete-next-column
3497               Like the complete command when candidates are not being listed;
3498               otherwise, select the first candidate in the next column in the
3499               list.
3500
3501           complete-prev-column
3502               Like the complete command when candidates are not being listed;
3503               otherwise, select the first candidate in the previous column in
3504               the list.
3505
3506           complete-next-page
3507               Like the complete command when candidates are not being listed;
3508               otherwise, select the first candidate in the next page in the
3509               list.
3510
3511           complete-prev-page
3512               Like the complete command when candidates are not being listed;
3513               otherwise, select the first candidate in the previous page in
3514               the list.
3515
3516           complete-list
3517               Complete a word just before the cursor position.
3518
3519               If you pass no argument, a list of completion candidates is
3520               shown. Otherwise, the word is completed with the nth candidate
3521               where n is the argument.
3522
3523               emacs
3524                   \^[?, \^[=
3525
3526           complete-all
3527               Replace a word just before the cursor position with all
3528               possible completion candidates, each separated by a space.
3529
3530               emacs
3531                   \^[*
3532
3533           complete-max
3534               Complete a word just before the cursor position with the
3535               longest prefix of all possible completion candidates.
3536
3537           complete-max-then-list
3538               Works like the complete-max command for the first use, then
3539               like the complete command when used successively.
3540
3541           complete-max-then-next-candidate
3542               Works like the complete-max command for the first use, then
3543               like the complete-next-candidate command when used
3544               successively.
3545
3546           complete-max-then-prev-candidate
3547               Works like the complete-max command for the first use, then
3548               like the complete-prev-candidate command when used
3549               successively.
3550
3551           clear-candidates
3552               Clear the list of completion candidates.
3553
3554       Vi-specific commands
3555           vi-replace-char
3556               Replace the character at the cursor position with a character
3557               that is entered just after this command.
3558
3559               vi-command
3560                   r
3561
3562           vi-insert-beginning
3563               Move the cursor to the beginning of the line and switch to the
3564               vi insert mode.
3565
3566               vi-command
3567                   I
3568
3569           vi-append
3570               Move the cursor to the next character and switch to the vi
3571               insert mode.
3572
3573               vi-command
3574                   I
3575
3576           vi-append-to-eol
3577               Move the cursor to the end of the line and switch to the vi
3578               insert mode.
3579
3580               vi-command
3581                   A
3582
3583           vi-replace
3584               Switch to the vi insert mode and start overwriting. While
3585               overwriting, the self-insert command replaces the character at
3586               cursor position rather than inserting a character. Overwriting
3587               ends when the editing mode is changed.
3588
3589               vi-command
3590                   R
3591
3592           vi-switch-case
3593               Switch case of characters between the current and next cursor
3594               positions. This command must be followed by a motion command,
3595               which determines the next cursor position.
3596
3597           vi-switch-case-char
3598               Switch case of the character at the current cursor position and
3599               move the cursor to the next character.
3600
3601               vi-command
3602                   ~
3603
3604           vi-yank
3605               Add to the kill ring the characters between the current and
3606               next cursor positions. This command must be followed by a
3607               motion command, which determines the next cursor position.
3608
3609               vi-command
3610                   y
3611
3612           vi-yank-to-eol
3613               Add to the kill ring the characters from the current cursor
3614               position to the end of the line.
3615
3616               vi-command
3617                   Y
3618
3619           vi-delete
3620               Delete characters between the current and next cursor positions
3621               and add it to the kill ring. This command must be followed by a
3622               motion command, which determines the next cursor position.
3623
3624               vi-command
3625                   d
3626
3627           vi-delete-to-eol
3628               Delete the characters from the current cursor position to the
3629               end of the line and add it to the kill ring.
3630
3631               vi-command
3632                   D
3633
3634           vi-change
3635               Delete characters between the current and next cursor positions
3636               and switch to the vi insert mode. This command must be followed
3637               by a motion command, which determines the next cursor position.
3638
3639               vi-command
3640                   c
3641
3642           vi-change-to-eol
3643               Delete the characters from the current cursor position to the
3644               end of the line and switch to the vi insert mode.
3645
3646               vi-command
3647                   C
3648
3649           vi-change-line
3650               Delete the whole buffer contents and switch to the vi insert
3651               mode.
3652
3653               vi-command
3654                   S
3655
3656           vi-yank-and-change
3657               Like the vi-change command, but the deleted text is added to
3658               the kill ring.
3659
3660           vi-yank-and-change-to-eol
3661               Like the vi-change-to-eol command, but the deleted text is
3662               added to the kill ring.
3663
3664           vi-yank-and-change-line
3665               Like the vi-change-line command, but the deleted text is added
3666               to the kill ring.
3667
3668           vi-substitute
3669               Delete a character at the current cursor position, add it to
3670               the kill ring, and switch to the vi insert mode.
3671
3672               vi-command
3673                   s
3674
3675           vi-append-last-bigword
3676               Insert a space and the last bigword in the most recent command
3677               history entry just after the current cursor position and switch
3678               to the vi insert mode. If argument n is passed, the nth bigword
3679               in the entry is inserted instead of the last.
3680
3681               vi-command
3682                   _
3683
3684           vi-exec-alias
3685               Execute the value of an alias named _c as editing commands
3686               where c is a character input just after this command.
3687
3688               vi-command
3689                   @
3690
3691           vi-edit-and-accept
3692               Start the vi editor to edit the current buffer contents. When
3693               the editor finished, the edited buffer contents is accepted
3694               like the accept-line command unless the exit status of the
3695               editor is non-zero.
3696
3697               vi-command
3698                   v
3699
3700           vi-complete-list
3701               Like the complete-list command, but also switch to the vi
3702               insert mode.
3703
3704               vi-command
3705                   =
3706
3707           vi-complete-all
3708               Like the complete-all command, but also switch to the vi insert
3709               mode.
3710
3711               vi-command
3712                   *
3713
3714           vi-complete-max
3715               Like the complete-max command, but also switch to the vi insert
3716               mode.
3717
3718               vi-command
3719                   \\
3720
3721           vi-search-forward
3722               Switch to the vi search mode and start forward history search.
3723
3724               vi-command
3725                   ?
3726
3727           vi-search-backward
3728               Switch to the vi search mode and start backward history search.
3729
3730               vi-command
3731                   /
3732
3733       Emacs-specific commands
3734           emacs-transpose-chars
3735               Move a character just before the cursor to the right.
3736
3737               emacs
3738                   \^T
3739
3740           emacs-transpose-words
3741               Move an emacsword just before the cursor to the right.
3742
3743               emacs
3744                   \^[t, \^[T
3745
3746           emacs-downcase-word
3747               Make an emacsword just after the cursor lowercase.
3748
3749               emacs
3750                   \^[l, \^[L
3751
3752           emacs-upcase-word
3753               Make an emacsword just after the cursor uppercase.
3754
3755               emacs
3756                   \^[u, \^[U
3757
3758           emacs-capitalize-word
3759               Capitalize the first letter of an emacsword just after the
3760               cursor.
3761
3762               emacs
3763                   \^[c, \^[u
3764
3765           emacs-delete-horizontal-space
3766               Delete spaces around the cursor. If any argument was passed,
3767               delete spaces just before the cursor only.
3768
3769               emacs
3770                   \^[\\
3771
3772           emacs-just-one-space
3773               Delete spaces around the cursor and leave one space. If an
3774               argument is specified, leave as many spaces as the argument.
3775
3776               emacs
3777                   \^[ (Escape followed by a space)
3778
3779           emacs-search-forward
3780               Switch to the emacs search mode and start forward history
3781               search.
3782
3783               emacs
3784                   \^S
3785
3786           emacs-search-backward
3787               Switch to the emacs search mode and start backward history
3788               search.
3789
3790               emacs
3791                   \^R
3792
3793       History-related commands
3794           oldest-history
3795               Recall the oldest entry in the history. If argument n is
3796               passed, the entry whose number is n is recalled instead. The
3797               cursor position remains unchanged.
3798
3799           newest-history
3800               Recall the newest entry in the history. If argument n is
3801               passed, the entry whose number is n is recalled instead. The
3802               cursor position remains unchanged.
3803
3804           return-history
3805               Return to the initial buffer corresponding to none of existing
3806               history entries. If argument n is passed, the entry whose
3807               number is n is recalled instead. The cursor position remains
3808               unchanged.
3809
3810           oldest-history-bol
3811               Recall the oldest entry in the history and move the cursor to
3812               the beginning of the line. If argument n is passed, the entry
3813               whose number is n is recalled instead.
3814
3815               vi-command
3816                   G
3817
3818           newest-history-bol
3819               Recall the newest entry in the history and move the cursor to
3820               the beginning of the line. If argument n is passed, the entry
3821               whose number is n is recalled instead.
3822
3823           return-history-bol
3824               Return to the initial buffer corresponding to none of existing
3825               history entries and move the cursor to the beginning of the
3826               line. If argument n is passed, the entry whose number is n is
3827               recalled instead.
3828
3829               vi-command
3830                   g
3831
3832           oldest-history-eol
3833               Recall the oldest entry in the history and move the cursor to
3834               the end of the line. If argument n is passed, the entry whose
3835               number is n is recalled instead.
3836
3837               emacs
3838                   \^[<
3839
3840           newest-history-eol
3841               Recall the newest entry in the history and move the cursor to
3842               the end of the line. If argument n is passed, the entry whose
3843               number is n is recalled instead.
3844
3845           return-history-eol
3846               Return to the initial buffer corresponding to none of existing
3847               history entries and move the cursor to the end of the line. If
3848               argument n is passed, the entry whose number is n is recalled
3849               instead.
3850
3851               emacs
3852                   \^[>
3853
3854           next-history
3855               Recall the next history entry. The cursor position remains
3856               unchanged.
3857
3858           prev-history
3859               Recall the previous history entry. The cursor position remains
3860               unchanged.
3861
3862           next-history-bol
3863               Recall the next history entry and move the cursor to the
3864               beginning of the line.
3865
3866               vi-command
3867                   j, +, \D, \^N
3868
3869           prev-history-bol
3870               Recall the previous history entry and move the cursor to the
3871               beginning of the line.
3872
3873               vi-command
3874                   k, -, \U, \^P
3875
3876           next-history-eol
3877               Recall the next history entry and move the cursor to the end of
3878               the line.
3879
3880               vi-insert, emacs
3881                   \D, \^N
3882
3883           prev-history-eol
3884               Recall the previous history entry and move the cursor to the
3885               end of the line.
3886
3887               vi-insert, emacs
3888                   \U, \^P
3889
3890           search-again
3891               Repeat the last command history search.
3892
3893               vi-command
3894                   n
3895
3896           search-again-rev
3897               Repeat the last command history search in the reverse
3898               direction.
3899
3900               vi-command
3901                   N
3902
3903           search-again-forward
3904               Repeat the last command history search in the forward
3905               direction.
3906
3907           search-again-backward
3908               Repeat the last command history search in the backward
3909               direction.
3910
3911           beginning-search-forward
3912               Recall the next history entry that starts with the same text as
3913               the text from the beginning of the line up to the current
3914               cursor position. The cursor position remains unchanged.
3915
3916           beginning-search-backward
3917               Recall the previous history entry that starts with the same
3918               text as the text from the beginning of the line up to the
3919               current cursor position. The cursor position remains unchanged.
3920
3921       Search mode commands
3922           srch-self-insert
3923               Insert the input character at the current cursor position.
3924               Characters escaped by escape sequences cannot be inserted.
3925
3926               vi-search, emacs-search
3927                   \\
3928
3929           srch-backward-delete-char
3930               Delete the last character in the search text. If the text is
3931               empty:
3932
3933               •   like the srch-abort-search command when in the vi search
3934                   mode, or
3935
3936               •   like the alert command when in the emacs search mode.
3937
3938               vi-search, emacs-search
3939                   \B, \?, \^H
3940
3941           srch-backward-delete-line
3942               Delete the whole search text.
3943
3944               vi-search, emacs-search
3945                   \$, \^U
3946
3947           srch-continue-forward
3948               Find the next matching history entry.
3949
3950               emacs-search
3951                   \^S
3952
3953           srch-continue-backward
3954               Find the previous matching history entry.
3955
3956               emacs-search
3957                   \^R
3958
3959           srch-accept-search
3960               Finish the search mode, accepting the result being shown.
3961
3962               vi-search
3963                   \^J, \^M
3964
3965               emacs-search
3966                   \^J, \^[
3967
3968           srch-abort-search
3969               Abort search and restore the previous buffer contents.
3970
3971               vi-search
3972                   \^[
3973
3974               emacs-search
3975                   \^G
3976
3977   Escape sequences
3978       In the bindkey built-in, escape sequences are used to represent special
3979       keys such as function keys and arrow keys. Every escape sequence starts
3980       with a backslash (\) and thus there is also an escape sequence for a
3981       backslash itself.
3982
3983       Below are available escape sequences:
3984
3985       \\
3986           Backslash (\)
3987
3988       \B
3989           Backspace
3990
3991       \D
3992           Down arrow
3993
3994       \E
3995           End
3996
3997       \H
3998           Home
3999
4000       \I
4001           Insert (Insert-char, Enter-insert-mode)
4002
4003       \L
4004           Left arrow
4005
4006       \N
4007           Page-down (Next-page)
4008
4009       \P
4010           Page-up (Previous-page)
4011
4012       \R
4013           Right arrow
4014
4015       \U
4016           Up arrow
4017
4018       \X
4019           Delete
4020
4021       \!
4022           INTR
4023
4024       \#
4025           EOF
4026
4027       \$
4028           KILL
4029
4030       \?
4031           ERASE
4032
4033       \^@
4034           Ctrl + @
4035
4036       \^A, \^B, ..., \^Z
4037           Ctrl + A, Ctrl + B, ..., Ctrl + Z
4038
4039           Note that Ctrl + I, Ctrl + J, and Ctrl + M are tab, newline, and
4040           carriage return, respectively.
4041
4042       \^[
4043           Ctrl + [ (Escape)
4044
4045       \^\
4046           Ctrl + \
4047
4048       \^]
4049           Ctrl + ]
4050
4051       \^^
4052           Ctrl + ^
4053
4054       \^_
4055           Ctrl + _
4056
4057       \^?
4058           Ctrl + ? (Delete)
4059
4060       \F00, \F01, ..., \F63
4061           F0, F1, ..., F63
4062
4063       \a1
4064           Top-left on keypad
4065
4066       \a3
4067           Top-right on keypad
4068
4069       \b2
4070           Center on keypad
4071
4072       \bg
4073           Beginning
4074
4075       \bt
4076           Back-tab
4077
4078       \c1
4079           Bottom-left on keypad
4080
4081       \c3
4082           Bottom-right on keypad
4083
4084       \ca
4085           Clear-all-tabs
4086
4087       \cl
4088           Close
4089
4090       \cn
4091           Cancel
4092
4093       \co
4094           Command
4095
4096       \cp
4097           Copy
4098
4099       \cr
4100           Create
4101
4102       \cs
4103           Clear-screen or erase
4104
4105       \ct
4106           Clear-tab
4107
4108       \dl
4109           Delete-line
4110
4111       \ei
4112           Exit-insert-mode
4113
4114       \el
4115           Clear-to-end-of-line
4116
4117       \es
4118           Clear-to-end-of-screen
4119
4120       \et
4121           Enter (Send)
4122
4123       \ex
4124           Exit
4125
4126       \fd
4127           Find
4128
4129       \hp
4130           Help
4131
4132       \il
4133           Insert-line
4134
4135       \ll
4136           Home-down
4137
4138       \me
4139           Message
4140
4141       \mk
4142           Mark
4143
4144       \ms
4145           Mouse event
4146
4147       \mv
4148           Move
4149
4150       \nx
4151           Next-object
4152
4153       \on
4154           Open
4155
4156       \op
4157           Options
4158
4159       \pr
4160           Print (Copy)
4161
4162       \pv
4163           Previous-object
4164
4165       \rd
4166           Redo
4167
4168       \re
4169           Resume
4170
4171       \rf
4172           Ref (Reference)
4173
4174       \rh
4175           Refresh
4176
4177       \rp
4178           Replace
4179
4180       \rs
4181           Restart
4182
4183       \sf
4184           Scroll-forward (Scroll-down)
4185
4186       \sl
4187           Select
4188
4189       \sr
4190           Scroll-backward (Scroll-up)
4191
4192       \st
4193           Set-tab
4194
4195       \su
4196           Suspend
4197
4198       \sv
4199           Save
4200
4201       \ud
4202           Undo
4203
4204       \SE
4205           Shift + End
4206
4207       \SH
4208           Shift + Home
4209
4210       \SI
4211           Shift + Insert
4212
4213       \SL
4214           Shift + Left arrow
4215
4216       \SR
4217           Shift + Right arrow
4218
4219       \SX
4220           Shift + Delete
4221
4222       \Sbg
4223           Shift + Beginning
4224
4225       \Scn
4226           Shift + Cancel
4227
4228       \Sco
4229           Shift + Command
4230
4231       \Scp
4232           Shift + Copy
4233
4234       \Scr
4235           Shift + Create
4236
4237       \Sdl
4238           Shift + Delete-line
4239
4240       \Sel
4241           Shift + End-of-line
4242
4243       \Sex
4244           Shift + Exit
4245
4246       \Sfd
4247           Shift + Find
4248
4249       \Shp
4250           Shift + Help
4251
4252       \Smg
4253           Shift + Message
4254
4255       \Smv
4256           Shift + Move
4257
4258       \Snx
4259           Shift + Next
4260
4261       \Sop
4262           Shift + Options
4263
4264       \Spr
4265           Shift + Print
4266
4267       \Spv
4268           Shift + Previous
4269
4270       \Srd
4271           Shift + Redo
4272
4273       \Sre
4274           Shift + Resume
4275
4276       \Srp
4277           Shift + Replace
4278
4279       \Ssu
4280           Shift + Suspend
4281
4282       \Ssv
4283           Shift + Save
4284
4285       \Sud
4286           Shift + Undo
4287
4288       INTR, EOF, KILL, and ERASE are special characters configured by the
4289       stty command. In a typical configuration, they are sent by typing
4290       Ctrl+C, Ctrl+D, Ctrl+U, and Ctrl+H, respectively, but some
4291       configuration uses Ctrl+? instead of Ctrl+H for ERASE.
4292
4293   Command line completion
4294       By using the complete and complete-next-candidate commands, etc., you
4295       can complete command names, options, and operands. By default, the
4296       complete-next-candidate command is bound with the Tab key in the vi
4297       insert and emacs modes.
4298
4299       Type a few first letters of a command name or pathname and hit the Tab
4300       key, and a list of matching names will be shown. You can choose a
4301       candidate from the list to complete the name by hitting the Tab key
4302       again. If there is only one matching name, no list will be shown and
4303       the name will directly be completed.
4304
4305       If the name to be completed contains characters like * and ?, it is
4306       treated as a pattern. The name on the command line will be directly
4307       substituted with all possible names matching the pattern (you cannot
4308       choose from a list).
4309
4310       Normally, command names are completed with command names and command
4311       arguments with pathnames. However, completion functions can be defined
4312       to refine completion results.
4313
4314       Completion details
4315           When doing completion for the first time after the shell has been
4316           started, the INIT file is loaded as if the command string . -AL
4317           completion/INIT is executed. If the file is not found, it is
4318           silently ignored. This automatic loading is mainly intended for
4319           loading completion functions bundled with the shell, but you can
4320           let the shell load your own functions by putting a file in the load
4321           path.
4322
4323           When completing a command name, the shell executes the
4324           completion//command function and when completing a command
4325           argument, the completion//argument function. If those completion
4326           functions are not defined, the shell just completes with command
4327           names or pathnames. When completing other names, such as the user
4328           name in tilde expansion and the parameter name in parameter
4329           expansion, completion functions are never used: the shell just
4330           completes with user names, parameter names, or whatever applicable.
4331
4332           Completion functions are executed without any arguments. The
4333           following local variables are automatically defined while executing
4334           completion functions:
4335
4336           IFS
4337               The value is the three characters of a space, a tab, and a
4338               newline, which are the default value of the variable.
4339
4340           WORDS
4341               This variable is an array whose elements are a command name and
4342               arguments that have already been entered before the argument
4343               being completed. When completing a command name, the array has
4344               no elements.
4345
4346           TARGETWORD
4347               The value is the partially entered command name or argument
4348               that is being completed.
4349
4350           Completion candidates are generated by executing the complete
4351           built-in during a completion function.
4352
4353           Completion functions must not perform I/O to the terminal, or
4354           displayed text will be corrupted. Completion functions should run
4355           as quickly as possible for better user experience.
4356
4357           While a completion function is being executed:
4358
4359           •   the POSIXly-correct mode and the err-return option are
4360               temporarily disabled,
4361
4362           •   the err-exit option is temporarily ignored, and
4363
4364           •   traps are not executed.
4365
4366   Command line prediction
4367       This is an experimental feature. When the le-predict option is enabled,
4368       the shell automatically tries to predict a command string fragment that
4369       follows the part of the command you have already typed in line-editing.
4370
4371       For example, assume you have once typed the command ls Documents. Next
4372       time you start typing ls Doc, the shell will show uments just after the
4373       cursor. If you are satisfied with this suggestion, you can move the
4374       cursor to the right by the forward-char or any other motion commands
4375       instead of typing the rest of the command. After moving the cursor
4376       after the last s, you can use the accept-line command to execute the
4377       command. You can also use the accept-prediction command to immediately
4378       execute the suggested command without moving the cursor.
4379
4380       To distinguish the typed part and the predicted part of a command
4381       string, you can change the font style of the typed part by setting the
4382       PS1S variable. Customizing the font style of the predicted part is not
4383       (yet) supported; it is always shown in the default style.
4384
4385       When you move the cursor to the right, the predicted part up to the
4386       cursor becomes the typed part as if you actually typed it. Moving the
4387       cursor to the left does not turn the typed part back to the prediction.
4388       Use deletion commands such as backward-delete-char to delete typed
4389       command fragment.
4390
4391       The predicted part of the command is shown only when the cursor is at
4392       the end of the typed part.
4393
4394       By default, the predicted part is shown after you start typing a
4395       command string. By enabling the le-predict-empty option, the predicted
4396       part is also shown before you type the first character of the command
4397       string.
4398
4399       The prediction algorithm suggests command fragments on the basis of the
4400       command history. The algorithm considers recent history entries more
4401       probable. It also takes command succession patterns into account. A
4402       predicted command fragment is not always a complete valid command
4403       because less probable part of the fragment is excluded from prediction.
4404

POSIXLY-CORRECT MODE

4406       Yash behaves as defined in POSIX.1-2008, Shell & Utilities for the most
4407       part, but some functionalities disobey POSIX for usability. When full
4408       POSIX-conformance is needed, you can enable the POSIXly-correct mode to
4409       make yash obey POSIX as much as possible.
4410
4411       If yash is started with the name “sh”, the POSIXly-correct mode is
4412       automatically enabled. The -o posixly-correct command-line option also
4413       enables the POSIXly-correct mode. After yash has been started, the
4414       POSIXly-correct mode can be enabled by executing the command string set
4415       -o posixly-correct.
4416
4417       When the POSIXly-correct mode is on, yash not only tries to obey the
4418       requirements by POSIX, but also treats as errors most conditions where
4419       the behavior is undefined or unspecified by POSIX. As a result, most
4420       yash-specific functionalities are disabled in the POSIXly-correct mode.
4421
4422       Below is the complete list of the behavioral differences between when
4423       yash is in the POSIXly-correct mode and when not. When the
4424       POSIXly-correct mode is enabled:
4425
4426       •   Different initialization scripts are used.
4427
4428       •   If the shell was started with the -c option, sh -c (instead of yash
4429           -c) is printed as the script pathname on a syntax error.
4430
4431       •   Global aliases are not substituted.
4432
4433       •   Nested commands in a compound command must not be empty.
4434
4435       •   The for loop iteration variable is created as global, regardless of
4436           the for-local shell option. The variable must have a portable
4437           (ASCII-only) name.
4438
4439       •   The first pattern in a case command cannot be esac.
4440
4441       •   The !  keyword cannot be followed by ( without any whitespaces
4442           in-between.
4443
4444       •   The double-bracket command cannot be used.
4445
4446       •   The function keyword cannot be used for function definition. The
4447           function must have a portable (ASCII-only) name.
4448
4449       •   Simple commands cannot assign to arrays.
4450
4451       •   Changing the value of the LC_CTYPE variable after the shell has
4452           been initialized does not affect the shell’s locale.
4453
4454       •   The RANDOM variable cannot be used to generate random numbers.
4455
4456       •   Tilde expansion only expands ~ and ~username.
4457
4458       •   Parameter expansion cannot be nested. No indexes or modifiers with
4459           word2 are allowed.
4460
4461       •   The commands in a command substitution of the form $(commands) are
4462           parsed every time the substitution is executed.
4463
4464       •   In arithmetic expansion, fractional numbers and the ++ and --
4465           operators cannot be used. All variables must be numeric.
4466
4467       •   The operand of a redirection cannot be the integer prefix to a next
4468           redirection operator.
4469
4470       •   A compound command with a redirection cannot be immediately
4471           followed by a keyword like } and fi.
4472
4473       •   In a redirection to a file, if the pathname expansion yielded more
4474           than one or no pathname, it is not immediately treated as an error.
4475           Instead, the shell tries to treat the word before the expansion as
4476           a pathname.
4477
4478       •   A file descriptor must be readable and writable when duplicated by
4479           the <& and >& redirection operator, respectively.
4480
4481       •   Socket redirection, here strings, pipe redirection, and process
4482           redirection cannot be used.
4483
4484       •   When executing a simple command, failure in command search does not
4485           trigger execution of the COMMAND_NOT_FOUND_HANDLER variable.
4486
4487       •   In command search, a regular built-in needs to have a corresponding
4488           external command for the built-in to be found.
4489
4490       •   Some built-ins behave differently. Especially, long command-line
4491           options (as well as some others) cannot be used.
4492
4493       •   A non-interactive shell exits when a special built-in is given a
4494           syntactically wrong arguments or when an error occurs in assignment
4495           or redirection with a special built-in.
4496
4497       •   An interactive shell does not execute the PROMPT_COMMAND variable
4498           before printing a prompt. The values of the PS1, PS2, and PS4
4499           variables are parsed differently. Prompt variables with a YASH_
4500           prefix (e.g.  YASH_PS1) are not used.
4501
4502       •   In mail checking, a notification message is printed if the file has
4503           been modified, regardless of whether the file is empty.
4504

FREQUENTLY ASKED QUESTIONS AND TROUBLESHOOTING

4506   How can I use Unicode (non-ASCII) characters?
4507       You need to set locale environment variables to enable Unicode
4508       character support.
4509
4510       If the variables have already been configured for your preference, you
4511       probably don’t have to do anything. To check the current locale
4512       configurations, you can use the locale command:
4513
4514           $ locale
4515           LANG=
4516           LC_CTYPE="en_US.utf8"
4517           LC_NUMERIC="en_US.utf8"
4518           LC_TIME="en_US.utf8"
4519           LC_COLLATE="en_US.utf8"
4520           LC_MONETARY="en_US.utf8"
4521           LC_MESSAGES="en_US.utf8"
4522           LC_PAPER="en_US.utf8"
4523           LC_NAME="en_US.utf8"
4524           LC_ADDRESS="en_US.utf8"
4525           LC_TELEPHONE="en_US.utf8"
4526           LC_MEASUREMENT="en_US.utf8"
4527           LC_IDENTIFICATION="en_US.utf8"
4528           LC_ALL=en_US.utf8
4529
4530       In this example, the locale command shows that all the locale setting
4531       categories are configured for the English language, the United States
4532       region, and the UTF-8 encoding.
4533
4534       If the current configuration does not seem to match your preference,
4535       set the LC_ALL variable like this:
4536
4537           export LC_ALL=en_US.utf8
4538
4539       If you want to use other languages, regions, or encodings, you have to
4540       set the variable to a different value. Please consult your OS’s
4541       documentation to learn how to configure these variables in detail.
4542
4543       If you want to apply the same configuration every time you start yash,
4544       write the command in ~/.yashrc or ~/.yash_profile.
4545
4546       If yash still rejects Unicode characters being entered, see the section
4547       below regarding line-editing.
4548
4549   Line-editing does not work
4550       First, type echo $TERM and see if it prints a sane value. xterm is the
4551       safest value that should work on any existing environment. Colored
4552       versions like xterm-16color and other terminal types like rxvt and
4553       vt100 may also work. All possible values can be listed by the toe
4554       command. It’s most desirable to choose a value that matches the actual
4555       terminal type you are using, but it might not work if the terminal type
4556       you chose is not supported on the system on which yash is running. If
4557       so, try changing the TERM value by export TERM=xterm, for example, to
4558       find a value that works.
4559
4560       If line-editing works but you have trouble entering Unicode (non-ASCII)
4561       characters, try enabling the le-no-conv-meta option by set -o
4562       le-no-conv-meta.
4563

FORMAL DEFINITION OF COMMAND SYNTAX

4565       This chapter defines the syntax of the shell command language.
4566
4567           Note
4568           Some of the syntactic features described below are not supported in
4569           the POSIXly-correct mode.
4570
4571   Tokenization
4572       The characters of the input source code are first delimited into
4573       tokens. Tokens are delimited so that the earlier token spans as long as
4574       possible. A sequence of one or more unquoted blank characters delimits
4575       a token.
4576
4577       The following tokens are the operator tokens:
4578
4579       & && ( ) ; ;; | || < << <& <( <<- <<< <> > >> >& >( >>| >| (newline)
4580
4581           Note
4582           Unlike other programming languages, the newline operator is a token
4583           rather than a white space.
4584
4585       Characters that are not blank nor part of an operator compose a word
4586       token. Words are parsed by the following parsing expression grammar:
4587
4588       Word
4589           (WordElement / !SpecialChar .)+
4590
4591       WordElement
4592           \ . /
4593
4594           ' (!' .)*  ' /
4595
4596           " QuoteElement* " /
4597
4598           Parameter /
4599
4600           Arithmetic /
4601
4602           CommandSubstitution
4603
4604       QuoteElement
4605           \ ([$`"\] / <newline>) /
4606
4607           Parameter /
4608
4609           Arithmetic /
4610
4611           CommandSubstitutionQuoted /
4612
4613           ![`"\] .
4614
4615       Parameter
4616           $ [@*#?-$!  [:digit:]] /
4617
4618           $ PortableName /
4619
4620           $ ParameterBody
4621
4622       PortableName
4623           ![0-9] [0-9 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]+
4624
4625       ParameterBody
4626           { ParameterNumber? (ParameterName / ParameterBody / $ ParameterBody
4627           / Arithmetic / CommandSubstitution) ParameterIndex?
4628           ParameterMatch?  }
4629
4630       ParameterNumber
4631           # ![}+=:/%] !([-?#] !})
4632
4633       ParameterName
4634           [@*#?-$!] /
4635
4636           [[:alnum:] _]+
4637
4638       ParameterIndex
4639           [ ParameterIndexWord (, ParameterIndexWord)?  ]
4640
4641       ParameterIndexWord
4642           (WordElement / !["'],] .)+
4643
4644       ParameterMatch
4645           :? [-+=?]  ParameterMatchWord /
4646
4647           (# / ## / % / %%) ParameterMatchWord /
4648
4649           (:/ / / [#%/]?)  ParameterMatchWordNoSlash (/ ParameterMatchWord)?
4650
4651       ParameterMatchWord
4652           (WordElement / !["'}] .)*
4653
4654       ParameterMatchWordNoSlash
4655           (WordElement / !["'/}] .)*
4656
4657       Arithmetic
4658           $(( ArithmeticBody* ))
4659
4660       ArithmeticBody
4661           \ . /
4662
4663           Parameter /
4664
4665           Arithmetic /
4666
4667           CommandSubstitution /
4668
4669           ( ArithmeticBody ) /
4670
4671           ![`()] .
4672
4673       CommandSubstitution
4674           $( CompleteProgram ) /
4675
4676           ` CommandSubstitutionBody* `
4677
4678       CommandSubstitutionQuoted
4679           $( CompleteProgram ) /
4680
4681           ` CommandSubstitutionBodyQuoted* `
4682
4683       CommandSubstitutionBody
4684           \ [$`\] /
4685
4686           !` .
4687
4688       CommandSubstitutionBodyQuoted
4689           \ [$`\`] /
4690
4691           !` .
4692
4693       SpecialChar
4694           [|&;<>()`\"' [:blank:]] / <newline>
4695
4696       The set of terminals of the grammar is the set of characters that can
4697       be handled on the environment in which the shell is run (a.k.a.
4698       execution character set), with the exception that the set does not
4699       contain the null character ('\0').
4700
4701       Strictly speaking, the definition above is not a complete parsing
4702       expression grammar because the rule for CommandSubstitution (Quoted)
4703       depends on CompleteProgram which is a non-terminal of the syntax.
4704
4705       Token classification
4706           After a word token is delimited, the token may be further
4707           classified as an IO_NUMBER token, reserved word, name word,
4708           assignment word, or just normal word. Classification other than the
4709           normal word is applied only when applicable in the context in which
4710           the word appears. See Tokens and keywords for the list of the
4711           reserved words (keywords) and the context in which a word may be
4712           recognized as a reserved word.
4713
4714           A token is an IO_NUMBER token iff it is composed of digit
4715           characters only and immediately followed by < or >.
4716
4717           An assignment token is a token that starts with a name followed by
4718           =:
4719
4720           AssignmentWord
4721               AssignmentPrefix Word
4722
4723           AssignmentPrefix
4724               Name =
4725
4726           Name
4727               ![[:digit:]] \[[:alnum:] _]+
4728
4729       Comments
4730           A comment begins with # and continues up to (but not including) the
4731           next newline character. Comments are treated like a blank character
4732           and do not become part of a token. The initial # of a comment must
4733           appear as if it would otherwise be the first character of a word
4734           token; Other #s are just treated as part of a word token.
4735
4736           Comment
4737               # (!<newline> .)*
4738
4739   Syntax
4740       After tokens have been delimited, the sequence of the tokens is parsed
4741       according to the context-free grammar defined below, where *, +, and ?
4742       should be interpreted in the same manner as standard regular
4743       expression:
4744
4745       CompleteProgram
4746           NL* | CompoundList
4747
4748       CompoundList
4749           NL* AndOrList ((; | & | NL) CompleteProgram)?
4750
4751       AndOrList
4752           Pipeline ((&& | ||) NL* Pipeline)*
4753
4754       Pipeline
4755           !?  Command (| NL* Command)*
4756
4757       Command
4758           CompoundCommand Redirection* |
4759
4760           FunctionDefinition |
4761
4762           SimpleCommand
4763
4764       CompoundCommand
4765           Subshell |
4766
4767           Grouping |
4768
4769           IfCommand |
4770
4771           ForCommand |
4772
4773           WhileCommand |
4774
4775           CaseCommand |
4776
4777           DoubleBracketCommand |
4778
4779           FunctionCommand
4780
4781       Subshell
4782           ( CompoundList )
4783
4784       Grouping
4785           { CompoundList }
4786
4787       IfCommand
4788           if CompoundList then CompoundList (elif CompoundList then
4789           CompoundList)* (else CompoundList)?  fi
4790
4791       ForCommand
4792           for Name ((NL* in Word*)? (; | NL) NL*)?  do CompoundList done
4793
4794       WhileCommand
4795           (while | until) CompoundList do CompoundList done
4796
4797       CaseCommand
4798           case Word NL* in NL* CaseList?  esac
4799
4800       CaseList
4801           CaseItem (;; NL* CaseList)?
4802
4803       CaseItem
4804           (?  Word (| Word)* ) CompleteProgram
4805
4806       DoubleBracketCommand
4807           [[ Ors ]]
4808
4809       Ors
4810           Ands (|| Ands)*
4811
4812       Ands
4813           Nots (&& Nots)*
4814
4815       Nots
4816           !*  Primary
4817
4818       Primary
4819           (-b | -c | -d | -e | -f | -G | -g | -h | -k | -L | -N | -n | -O |
4820           -o | -p | -r | -S | -s | -t | -u | -w | -x | -z) Word |
4821
4822           Word (-ef | -eq | -ge | -gt | -le | -lt | -ne | -nt | -ot | -veq |
4823           -vge | -vgt | -vle | -vlt | -vne | = | == | === | =~ | != | !== | <
4824           | >) Word |
4825
4826           ( Ors ) |
4827
4828           Word
4829
4830       FunctionCommand
4831           function Word (( ))?  NL* CompoundCommand Redirection*
4832
4833       FunctionDefinition
4834           Name ( ) NL* CompoundCommand Redirection*
4835
4836       SimpleCommand
4837           (Assignment | Redirection) SimpleCommand? |
4838
4839           Word (Word | Redirection)*
4840
4841       Assignment
4842           AssignmentWord |
4843
4844           AssignmentPrefix( NL* (Word NL*)* )
4845
4846       Redirection
4847           IO_NUMBER?  RedirectionOperator Word |
4848
4849           IO_NUMBER?  <( CompleteProgram ) |
4850
4851           IO_NUMBER?  >( CompleteProgram )
4852
4853       RedirectionOperator
4854           < | <> | > | >| | >> | >>| | <& | >& | << | <<- | <<<
4855
4856       NL
4857           <newline>
4858
4859       In the rule for Primary, Word tokens must not be ]]. Additionally, if a
4860       Primary starts with a Word, it must not be any of the possible unary
4861       operators allowed in the rule.
4862
4863       In the rule for SimpleCommand, a Word token is accepted only when the
4864       token cannot be parsed as the first token of an Assignment.
4865
4866       In the rule for Assignment, the ( token must immediately follow the
4867       AssignmentPrefix token, without any blank characters in between.
4868
4869       Here-document contents do not appear as part of the grammar above. They
4870       are parsed just after the newline (NL) token that follows the
4871       corresponding redirection operator.
4872
4873       Alias substitution
4874           Word tokens are subject to alias substitution.
4875
4876           •   If a word is going to be parsed as a Word of a SimpleCommand,
4877               the word is subjected to alias substitution of any kind (normal
4878               and global aliases).
4879
4880           •   If a word is the next token after the result of an alias
4881               substitution and the substitution string ends with a blank
4882               character, then the word is also subjected to alias
4883               substitution of any kind.
4884
4885           •   Other words are subjected to global alias substitution unless
4886               the shell is in the POSIXly-correct mode.
4887
4888           Tokens that are classified as reserved words are not subject to
4889           alias substitution.
4890

ALIAS BUILT-IN

4892       The alias built-in defines and/or prints aliases.
4893
4894   Syntax
4895alias [-gp] [name[=value]...]
4896
4897   Description
4898       The alias built-in defines and/or prints aliases as specified by
4899       operands. The printed aliases can be used as (part of) shell commands.
4900       The built-in prints all currently defined aliases when given no
4901       operands.
4902
4903   Options
4904       -g, --global
4905           With this option, aliases are defined as global aliases; without
4906           this option, as normal aliases.
4907
4908       -p, --prefix
4909           With this option, aliases are printed in a full command form like
4910           alias -g foo='bar'. Without this option, only command operands are
4911           printed like foo='bar'.
4912
4913   Operands
4914       name
4915           The name of an alias that should be printed.
4916
4917       name=value
4918           The name and value of an alias that is being defined.
4919
4920   Exit status
4921       The exit status of the alias built-in is zero unless there is any
4922       error.
4923
4924   Notes
4925       The characters that cannot be used in an alias name are the space, tab,
4926       newline, and any of =$<>\'"`;&|()#. You can use any characters in an
4927       alias value.
4928
4929       The alias built-in is a semi-special built-in.
4930
4931       The POSIX standard defines no options for the alias built-in, thus no
4932       options are available in the POSIXly correct mode.
4933

ARRAY BUILT-IN

4935       The array built-in prints or modifies arrays.
4936
4937   Syntax
4938array
4939
4940array name [value...]
4941
4942array -d name [index...]
4943
4944array -i name index [value...]
4945
4946array -s name index value
4947
4948   Description
4949       When executed without any option or operands, the built-in prints all
4950       array definitions to the standard output in a form that can be parsed
4951       as commands.
4952
4953       When executed with name and values (but without an option), the
4954       built-in sets the values as the values of the array named name.
4955
4956       With the -d (--delete) option, the built-in removes the indexth values
4957       of the array named name. The number of values in the array will be
4958       decreased by the number of the indexes specified. If the indexth value
4959       does not exist, it is silently ignored.
4960
4961       With the -i (--insert) option, the built-in inserts values into the
4962       array named name. The number of values in the array will be increased
4963       by the number of the values specified. The values are inserted between
4964       the indexth and next values. If index is zero, the values are inserted
4965       before the first value. If index is larger than the number of values in
4966       the array, the values are appended after the last element.
4967
4968       With the -s (--set) option, the built-in sets value as the indexth
4969       value of the array named name. The array must have at least index
4970       values.
4971
4972   Options
4973       -d, --delete
4974           Delete array values.
4975
4976       -i, --insert
4977           Insert array values.
4978
4979       -s, --set
4980           Set an array value.
4981
4982   Operands
4983       name
4984           The name of an array to operate on.
4985
4986       index
4987           The index to an array element. The first element has the index of
4988           1.
4989
4990       value
4991           A string to which the array element is set.
4992
4993   Exit status
4994       The exit status of the array built-in is zero unless there is any
4995       error.
4996
4997   Notes
4998       The array built-in is not defined in the POSIX standard.
4999
5000       The command array name value... is equivalent to the assignment
5001       name=(value...).
5002

BG BUILT-IN

5004       The bg built-in resumes a job in the background.
5005
5006   Syntax
5007bg [job...]
5008
5009   Description
5010       The bg built-in sends the SIGCONT signal to the specified job. As a
5011       result, the job is resumed in the background (if it has been
5012       suspended).
5013
5014       The name of the job is printed when the job is resumed.
5015
5016       The built-in can be used only when job control is enabled.
5017
5018   Operands
5019       job
5020           The job ID of the job to be resumed.
5021
5022           More than one job can be specified at a time. The current job is
5023           resumed if none is specified.
5024
5025           The percent sign (%) at the beginning of a job ID can be omitted if
5026           the shell is not in the POSIXly-correct mode.
5027
5028   Exit status
5029       The exit status of the bg built-in is zero unless there is any error.
5030
5031   Notes
5032       The bg built-in is a semi-special built-in.
5033
5034       The POSIX standard provides that the built-in shall have no effect when
5035       the job is already running. The bg built-in of yash, however, always
5036       sends the SIGCONT signal to the job.
5037

BINDKEY BUILT-IN

5039       The bindkey built-in prints or modifies key bindings used in
5040       line-editing.
5041
5042   Syntax
5043bindkey -aev [key [command]]
5044
5045bindkey -l
5046
5047   Description
5048       When executed with the -l (--list) option, the built-in lists all
5049       available line-editing commands to the standard output.
5050
5051       When executed with one of the other options, the built-in prints or
5052       modifies key bindings for the editing mode specified by the option:
5053
5054       •   Without key or command, all currently defined bindings are printed
5055           to the standard output in a form that can be parsed as commands
5056           that restore the current bindings when executed.
5057
5058       •   With key but without command, only the binding for the given key is
5059           printed.
5060
5061       •   With key and command, key is bound to command.
5062
5063   Options
5064       -a, --vi-command
5065           Print or modify bindings for the vi command mode.
5066
5067       -e, --emacs
5068           Print or modify bindings for the emacs mode.
5069
5070       -v, --vi-insert
5071           Print or modify bindings for the vi insert mode.
5072
5073   Operands
5074       key
5075           A character sequence of one or more keys that is bound to an
5076           editing command. The sequence may include escape sequences.
5077
5078       command
5079           A line-editing command to which key is bound. If command is a
5080           single hyphen (-), key is unbound.
5081
5082   Exit status
5083       The exit status of the bindkey built-in is zero unless there is any
5084       error.
5085
5086   Notes
5087       The bindkey built-in is a semi-special built-in. In the POSIX standard,
5088       it is defined as a command with unspecified behavior.
5089

BREAK BUILT-IN

5091       The break built-in aborts a loop being executed.
5092
5093   Syntax
5094break [nest]
5095
5096break -i
5097
5098   Description
5099       When executed without the -i (--iteration) option, the built-in aborts
5100       a currently executed for, while, or until loop. When executed in nested
5101       loops, it aborts the nestth innermost loop. The default nest is one. If
5102       the number of currently executed nested loops is less than nest, the
5103       built-in aborts the outermost loop.
5104
5105       When executed with the -i (--iteration) option, the built-in aborts the
5106       currently executed (innermost) iterative execution.
5107
5108   Options
5109       -i, --iteration
5110           Abort an iterative execution instead of a loop.
5111
5112   Operands
5113       nest
5114           The number of loops to abort, which must be a positive integer.
5115
5116   Exit status
5117       The exit status of the break built-in is:
5118
5119       •   zero if a loop was successfully aborted.
5120
5121       •   that of the command that was executed just before the break
5122           built-in if an iterative execution was successfully aborted.
5123
5124   Notes
5125       The break built-in is a special built-in.
5126
5127       The POSIX standard defines no options for the break built-in; the
5128       built-in accepts no options in the POSIXly-correct mode.
5129
5130       Treatment of currently executed loops that are not lexically enclosing
5131       the break built-in is unspecified in POSIX. Examples of such loops
5132       include:
5133
5134       •   A loop invoking a function in which the break built-in is used.
5135
5136       •   A loop in which a trap action is executed in which the break
5137           built-in is used.
5138
5139       Yash does not allow breaking such loops.
5140

CD BUILT-IN

5142       The cd built-in changes the working directory.
5143
5144   Syntax
5145cd [-L|-P] [directory]
5146
5147   Description
5148       The cd built-in changes the working directory to the directory
5149       specified by the operand.
5150
5151       The pathname of the new working directory is assigned to the PWD
5152       variable, whose previous value is again assigned to the OLDPWD
5153       variable. The new PWD value will not contain any . or .. components
5154       except when the shell is in the POSIXly-correct mode and the new
5155       pathname begins with /...
5156
5157       If directory is a relative path that does not start with ‘.’ or ‘..’,
5158       paths in the CDPATH variable are searched to find a new working
5159       directory. The search is done in a manner similar to the last step of
5160       command search, but a directory is sought instead of an executable
5161       regular file. If a new working directory was found from CDPATH, its
5162       pathname is printed to the standard output. If no applicable directory
5163       was found in the search, directory is simply treated as a pathname
5164       relative to the current working directory.
5165
5166       If the working directory was successfully changed, the value of the
5167       YASH_AFTER_CD variable is executed as a command unless the shell is in
5168       the POSIXly-correct mode. If the variable is an array, its values are
5169       executed iteratively (cf. eval built-in).
5170
5171   Options
5172       -L, --logical
5173           Symbolic links in the pathname of the new working directory are not
5174           resolved. The new value of the PWD may include pathname components
5175           that are symbolic links.
5176
5177       -P, --physical
5178           Symbolic links in the pathname of the new working directory are
5179           resolved. The new value of the PWD variable never includes pathname
5180           components that are symbolic links.
5181
5182       --default-directory=directory
5183           If this option is specified and the directory operand is omitted,
5184           the argument to this option is used for the directory operand. If
5185           the directory operand is specified, this option is ignored.
5186
5187       The -L (--logical) and -P (--physical) options are mutually exclusive:
5188       only the last specified one is effective. If neither is specified, -L
5189       is assumed.
5190
5191   Operands
5192       directory
5193           The pathname of the new working directory.
5194
5195           If directory is a single hyphen (‘-’), the value of the OLDPWD
5196           variable is assumed for the new directory pathname, which is
5197           printed to the standard output.
5198
5199           If directory is omitted, the working directory is changed to the
5200           directory specified by the --default-directory=...  option. If that
5201           option is not specified either, the default is the home directory.
5202
5203   Exit status
5204       The exit status of the cd built-in is zero if the working directory was
5205       successfully changed and non-zero if there was an error.
5206
5207   Notes
5208       The cd built-in is a semi-special built-in.
5209
5210       The POSIX standard does not define the use of the YASH_AFTER_CD
5211       variable or the --default-directory=... option. The standard does not
5212       allow using an option with a single hyphen operand.
5213
5214       The exit status of the commands in the YASH_AFTER_CD variable does not
5215       affect that of the cd built-in.
5216

COLON BUILT-IN

5218       The colon built-in does nothing.
5219
5220   Syntax
5221: [argument...]
5222
5223   Description
5224       The colon built-in does nothing. Any command line arguments are
5225       ignored.
5226
5227   Exit status
5228       The exit status of the colon built-in is zero.
5229
5230   Notes
5231       The colon built-in is a special built-in.
5232
5233       Arguments are expanded and redirections are performed as usual. The
5234       colon and true built-ins have the same effect, but colon is a special
5235       built-in while true is a semi-special.
5236

COMMAND BUILT-IN

5238       The command built-in executes or identifies a command.
5239
5240   Syntax
5241command [-befp] command [argument...]
5242
5243command -v|-V [-abefkp] command...
5244
5245   Description
5246       Without the -v (--identify) or -V (--verbose-identify) option, the
5247       built-in executes command with arguments in the same manner as the last
5248       step of execution of simple commands. The command is treated as a
5249       built-in or external command or a function according to the options
5250       specified to the command built-in. The shell does not exit on argument
5251       syntax error etc. even if the command is a special built-in
5252
5253       With the -v (--identify) option, command is identified. If the command
5254       is found in $PATH, its full pathname is printed. If it is a keyword,
5255       function, or built-in that is not found in $PATH, the command name is
5256       simply printed. If it is an alias, it is printed in the form like alias
5257       ll='ls -l'. If the command is not found, nothing is printed and the
5258       exit status is non-zero.
5259
5260       The -V (--verbose-identify) option is similar to the -v (--identify)
5261       option, but the output format is more human-friendly.
5262
5263   Options
5264       -a, --alias
5265           Search for the command as an alias. Must be used with the -v
5266           (--identify) or -V (--verbose-identify) option.
5267
5268       -b, --builtin-command
5269           Search for the command as a built-in.
5270
5271       -e, --external-command
5272           Search for the command as an external command.
5273
5274       -f, --function
5275           Search for the command as a function.
5276
5277       -k, --keyword
5278           Search for the command as a keyword. Must be used with the -v
5279           (--identify) or -V (--verbose-identify) option.
5280
5281       -p, --standard-path
5282           Search the system’s default PATH instead of the current $PATH.
5283
5284       -v, --identify
5285           Identify commands and print in the format defined in the POSIX
5286           standard.
5287
5288       -V, --verbose-identify
5289           Identify commands and print in a human-friendly format.
5290
5291       If none of the -a (--alias), -b (--builtin-command), -e
5292       (--external-command), -f (--function), and -k (--keyword) options is
5293       specified, the following defaults are assumed:
5294
5295       Without the -v (--identify) or -V (--verbose-identify) option
5296           -b -e
5297
5298       With the -v (--identify) or -V (--verbose-identify) option
5299           -a -b -e -f -k
5300
5301   Operands
5302       command
5303           A command to be executed or identified.
5304
5305       argument...
5306           Arguments passed to the executed command.
5307
5308   Exit status
5309       The exit status of the command built-in is:
5310
5311       Without the -v (--identify) or -V (--verbose-identify) option
5312           the exit status of the executed command.
5313
5314       With the -v (--identify) or -V (--verbose-identify) option
5315           zero unless there is any error.
5316
5317   Notes
5318       The command built-in is a semi-special built-in.
5319
5320       In the POSIXly-correct mode, options other than -p, -v, and -V cannot
5321       be used and at most one command can be specified. The POSIX standard
5322       does not allow specifying both -v and -V together, but yash does (only
5323       the last specified one is effective).
5324

COMPLETE BUILT-IN

5326       The complete built-in generates completion candidates. This built-in
5327       can only be executed from completion functions during command line
5328       completion.
5329
5330   Syntax
5331complete [-A pattern] [-R pattern] [-T] [-P prefix] [-S suffix]
5332           [-abcdfghjkuv] [[-O] [-D description] word...]
5333
5334   Description
5335       The built-in generates completion candidates according to the specified
5336       arguments. No matter how candidates are generated, only candidates that
5337       match the word being completed are generated.
5338
5339   Options
5340       -A pattern, --accept=pattern
5341           Only accept candidates that match the pattern specified by this
5342           option. When more than one of this option is specified, only
5343           candidates that match all of the patterns are generated.
5344
5345       -D description, --description=description
5346           Give a description of the word candidates. The description is shown
5347           beside the candidates in the candidate list.
5348
5349       -O, --option
5350           The candidates are treated as command line options. A hyphen is
5351           prepended to each candidate that is treated as an option.
5352
5353       -P prefix, --prefix=prefix
5354           Ignore prefix of the word being completed when generating
5355           candidates. The specified prefix must be initial part of the word.
5356
5357           If the word being completed is file:///home/user/docume for
5358           example, the command line complete -P file:// -f will generate
5359           pathname candidates that complete /home/user/docume.
5360
5361       -R pattern, --reject=pattern
5362           Reject candidates that match the pattern specified by this option.
5363           When more than one of this option is specified, only candidates
5364           that match none of the patterns are generated.
5365
5366       -S suffix, --suffix=suffix
5367           Append suffix to each generated candidate.
5368
5369       -T, --no-termination
5370           Do not append a space after the word is completed. Without this
5371           option, a space is appended to the completed word so that you do
5372           not have to enter a space before the next word.
5373
5374       Options that select candidate types
5375           -a, --alias
5376               Aliases. (same as --normal-alias --global-alias)
5377
5378           --array-variable
5379               Arrays.
5380
5381           --bindkey
5382               Line-editing commands the bindkey built-in accepts.
5383
5384           -b, --builtin-command
5385               Built-in commands. (same as --special-builtin
5386               --semi-special-builtin --regular-builtin)
5387
5388           -c, --command
5389               Commands. (same as --builtin-command --external-command
5390               --function)
5391
5392           -d, --directory
5393               Directories.
5394
5395           --dirstack-index
5396               Valid indices of the directory stack.
5397
5398           --executable-file
5399               Executable regular files.
5400
5401           --external-command
5402               External commands.
5403
5404           -f, --file
5405               Files (including directories).
5406
5407           --finished-job
5408               Job IDs of finished jobs.
5409
5410           --function
5411               Functions.
5412
5413           --global-alias
5414               Global aliases.
5415
5416           -g, --group
5417               User groups.
5418
5419           -h, --hostname
5420               Host names.
5421
5422           -j, --job
5423               Job IDs.
5424
5425           -k, --keyword
5426               Keywords.
5427
5428           --normal-alias
5429               Normal aliases.
5430
5431           --regular-builtin
5432               Regular built-in commands.
5433
5434           --running-job
5435               Job IDs of jobs that are being executed.
5436
5437           --scalar-variable
5438               Variables that are not arrays.
5439
5440           --semi-special-builtin
5441               Semi-special built-in commands.
5442
5443           --signal
5444               Signals.
5445
5446           --special-builtin
5447               Special built-in commands.
5448
5449           --stopped-job
5450               Job IDs of jobs that are suspended.
5451
5452           -u, --username
5453               Users' log-in names.
5454
5455           -v, --variable
5456               Variables.
5457
5458           If the -d (--directory) option is specified without the -f (--file)
5459           option, the -S / -T options are assumed.
5460
5461           Generated candidates for job IDs do not have leading percent signs
5462           (%). If the word being completed starts with a percent sign, the -P
5463           % option should be specified.
5464
5465   Operands
5466       Operands are treated as completion candidates.
5467
5468   Exit status
5469       The exit status of the built-in is zero if one or more candidates were
5470       generated, one if no candidates were generated, or larger than one if
5471       an error occurred.
5472
5473   Notes
5474       The complete built-in is a semi-special built-in. In the POSIX
5475       standard, it is defined as a command with unspecified behavior.
5476

CONTINUE BUILT-IN

5478       The continue built-in skips an iteration of a loop being executed.
5479
5480   Syntax
5481continue [nest]
5482
5483continue -i
5484
5485   Description
5486       When executed without the -i (--iteration) option, the built-in aborts
5487       the current iteration of for, while, or until loop and starts the next
5488       iteration of the loop. When executed in nested loops, it affects the
5489       nestth innermost loop. The default nest is one. If the number of
5490       currently executed nested loops is less than nest, the built-in affects
5491       the outermost loop.
5492
5493       When executed with the -i (--iteration) option, the built-in aborts the
5494       current iteration of (innermost) iterative execution.
5495
5496   Options
5497       -i, --iteration
5498           Skip an iterative execution instead of a loop.
5499
5500   Operands
5501       nest
5502           The nestth innermost loop is affected.  nest must be a positive
5503           integer.
5504
5505   Exit status
5506       The exit status of the continue built-in is:
5507
5508       •   zero if loop iteration was successfully skipped.
5509
5510       •   that of the command that was executed just before the continue
5511           built-in if iterative execution was successfully skipped.
5512
5513   Notes
5514       The continue built-in is a special built-in.
5515
5516       The POSIX standard defines no options for the continue built-in; the
5517       built-in accepts no options in the POSIXly-correct mode.
5518
5519       Treatment of currently executed loops that are not lexically enclosing
5520       the continue built-in is unspecified in POSIX. Examples of such loops
5521       include:
5522
5523       •   A loop invoking a function in which the continue built-in is used
5524
5525       •   A loop in which a trap action is executed in which the continue
5526           built-in is used
5527
5528       Yash does not allow continuing such loops.
5529

DIRS BUILT-IN

5531       The dirs built-in prints the contents of the directory stack.
5532
5533   Syntax
5534dirs [-cv] [index..]
5535
5536   Description
5537       The directory stack is a feature that records history of working
5538       directories. You can use the pushd built-in to save a working directory
5539       in the directory stack, the popd built-in to recall the saved working
5540       directory, and the dirs built-in to see the stack contents. Those
5541       built-ins use the DIRSTACK array and the PWD variable to save the stack
5542       contents. Modifying the array means modifying the stack contents.
5543
5544       Directory stack entries are indexed by signed integers. The entry of
5545       index +0 is the current working directory, +1 is the last saved
5546       directory, +2 is the second last, and so on. Negative indices are in
5547       the reverse order: the entry of index -0 is the first saved directory,
5548       -1 is the second, and -n is the current working directory if the stack
5549       has n entries,
5550
5551       When executed without the -c (--clear) option, the dirs built-in prints
5552       the current contents of the directory stack to the standard output.
5553       With the -c (--clear) option, the built-in clears the directory stack.
5554
5555   Options
5556       -c, --clear
5557           Clear the directory stack contents except for the current working
5558           directory, which has index +0.
5559
5560       -v, --verbose
5561           Print indices when printing stack contents.
5562
5563   Operands
5564       index
5565           The index of a stack entry to be printed.
5566
5567           You can specify more than one index. If you do not specify any
5568           index, all the entries are printed.
5569
5570   Exit status
5571       The exit status of the dirs built-in is zero unless there is any error.
5572
5573   Notes
5574       The dirs built-in is a semi-special built-in. In the POSIX standard, it
5575       is defined as a command with unspecified behavior.
5576

DISOWN BUILT-IN

5578       The disown built-in removes jobs.
5579
5580   Syntax
5581disown [-a] [job...}
5582
5583   Description
5584       The disown built-in removes the specified jobs from the job list. The
5585       removed jobs will no longer be job-controlled, but the job processes
5586       continue execution (unless they have been suspended).
5587
5588   Options
5589       -a, --all
5590           Removes all jobs.
5591
5592   Operands
5593       job
5594           The job ID of the job to be removed.
5595
5596           You can specify more than one job ID. If you do not specify any job
5597           ID, the current job is removed. If the shell is not in the
5598           POSIXly-correct mode, the %-prefix of the job ID can be omitted.
5599
5600   Exit status
5601       The exit status of the disown built-in is zero unless there is any
5602       error.
5603
5604   Notes
5605       The disown built-in is a semi-special built-in. In the POSIX standard,
5606       it is defined as a command with unspecified behavior.
5607

DOT BUILT-IN

5609       The dot built-in reads a file and executes commands in it.
5610
5611   Syntax
5612. [-AL] file [argument...]
5613
5614   Description
5615       The dot built-in reads the specified file, parses its contents as
5616       commands, and executes them in the current command execution
5617       environment.
5618
5619       If arguments are specified, positional parameters are temporarily set
5620       to them. The positional parameters will be restored when the dot
5621       built-in finishes. If no arguments are specified, the positional
5622       parameters are not changed.
5623
5624       If file does not contain any slashes, the shell searches $PATH for a
5625       readable (but not necessarily executable) shell script file whose name
5626       is file in the same manner as command search. If no such file was
5627       found, the shell searches the current working directory for a file
5628       unless in the POSIXly-correct mode. To ensure that the file in the
5629       current working directory is used, start file with ‘./’.
5630
5631   Options
5632       -A, --no-alias
5633           Disable alias substitution while parsing.
5634
5635       -L, --autoload
5636           Search $YASH_LOADPATH instead of $PATH, regardless of whether file
5637           contains slashes. The file value is not considered relative to the
5638           current working directory.
5639
5640       The dot built-in treats as operands any command line arguments after
5641       the first operand.
5642
5643   Operands
5644       file
5645           The pathname of a file to be read.
5646
5647       arguments...
5648           Strings to which positional parameters are set while execution.
5649
5650   Exit status
5651       The exit status of the dot built-in is that of the last command
5652       executed. The exit status is zero if the file contains no commands to
5653       execute and non-zero if a file was not found or could not be opened.
5654
5655   Notes
5656       The dot built-in is a special built-in.
5657
5658       A non-interactive shell immediately exits with a non-zero exit status
5659       if the dot built-in fails to find or open a file to execute.
5660
5661       The POSIX standard defines no options for the dot built-in; the
5662       built-in accepts no options in the POSIXly-correct mode.
5663
5664       The POSIX standard does not define the arguments... operands. It is an
5665       error to specify the arguments... operands in the POSIXly-correct mode.
5666

ECHO BUILT-IN

5668       The echo built-in prints its arguments.
5669
5670   Syntax
5671echo [string...]
5672
5673       The built-in treats all command line arguments as operands except for
5674       the options described below. Any word that cannot be parsed as an
5675       acceptable option is treated as an operand. Options must precede all
5676       operands. Syntax errors never happen in the echo built-in.
5677
5678   Description
5679       The echo built-in prints the operand strings followed by a newline to
5680       the standard output. The strings are each separated by a space.
5681
5682       Escape sequences
5683           The ECHO_STYLE variable and the -e option enable escape sequences
5684           that are replaced with corresponding characters:
5685
5686           \a
5687               Bell character (ASCII code: 7)
5688
5689           \b
5690               Backspace (ASCII code: 8)
5691
5692           \c
5693               Nothing. After this escape sequence, no characters are printed
5694               at all.
5695
5696           \e
5697               Escape character (ASCII code: 27)
5698
5699           \f
5700               Form feed character (ASCII code: 12)
5701
5702           \n
5703               Newline character (ASCII code: 10)
5704
5705           \r
5706               Carriage return character (ASCII code: 13)
5707
5708           \t
5709               Horizontal tab character (ASCII code: 9)
5710
5711           \v
5712               Vertical tab character (ASCII code: 11)
5713
5714           \\
5715               Backslash
5716
5717           \0xxx
5718               Character whose code is xxx, where xxx is an octal number of at
5719               most three digits.
5720
5721           When escape sequences are not enabled, they are just printed
5722           intact.
5723
5724       ECHO_STYLE variable
5725           The ECHO_STYLE variable defines which options are accepted and
5726           whether escape sequences are enabled by default. The variable value
5727           should be set to one of the following:
5728
5729           SYSV, XSI
5730               No options are accepted. Escape sequences are always enabled.
5731
5732           BSD
5733               The -n option is accepted. Escape sequences are never enabled.
5734
5735           GNU
5736               The -n, -e, and -E options are accepted. Escape sequences are
5737               not enabled by default, but can be enabled by the -e option.
5738
5739           ZSH
5740               The -n, -e, and -E options are accepted. Escape sequences are
5741               enabled by default, but can be disabled by the -E option.
5742
5743           DASH
5744               The -n option is accepted. Escape sequences are always enabled.
5745
5746           RAW
5747               No options are accepted. Escape sequences are never enabled.
5748
5749           When the ECHO_STYLE variable is not set, it defaults to SYSV.
5750
5751   Options
5752       -n
5753           Do not print a newline at the end.
5754
5755       -e
5756           Enable escape sequences.
5757
5758       -E
5759           Disable escape sequences.
5760
5761   Exit status
5762       The exit status of the echo built-in is zero unless there is any error.
5763
5764   Notes
5765       The POSIX standard does not define the ECHO_STYLE variable nor any
5766       options for the built-in. According to POSIX, the behavior of the
5767       built-in is implementation-defined when the first argument is -n or
5768       when any argument contains a backslash. For maximum portability, the
5769       printf built-in should be preferred over the echo built-in.
5770
5771       Although many values for the ECHO_STYLE variable are defined on the
5772       basis of other existing implementations, yash is not intended to
5773       exactly imitate those originals. Zsh’s echo built-in interprets a
5774       single hyphen argument as a separator between options and operands.
5775       Yash does not support such use of hyphen.
5776

EVAL BUILT-IN

5778       The eval built-in evaluates operands as commands.
5779
5780   Syntax
5781eval [-i] [command...]
5782
5783       The eval built-in requires that all options precede operands. Any
5784       command line arguments after the first operand are all treated as
5785       operands.
5786
5787   Description
5788       The eval parses operands as commands and executes them in the current
5789       command execution environment.
5790
5791       When executed without the -i (--iteration) option, all the operands are
5792       concatenated into one string (with a space inserted between each
5793       operand) and parsed/executed at once.
5794
5795       With the -i (--iteration) option, the built-in performs iterative
5796       execution: operands are parsed/executed one by one. If the continue
5797       built-in is executed with the -i (--iteration) option during the
5798       iterative execution, the execution of the current operand is aborted
5799       and the next operand is parsed/executed immediately. The break built-in
5800       with the -i (--iteration) option is similar but the remaining operands
5801       are not parsed/executed. The value of the ? special parameter is saved
5802       before the iterative execution is started. The parameter value is
5803       restored to the saved one after each iteration.
5804
5805   Options
5806       -i, --iteration
5807           Perform iterative execution.
5808
5809   Operands
5810       command
5811           A string that is parsed and executed as commands.
5812
5813   Exit status
5814       The exit status is zero if no command was specified or command
5815       contained no actual command that can be executed. Otherwise, that is,
5816       if the eval built-in executed one or more commands, the exit status of
5817       the eval built-in is that of the last executed command.
5818
5819   Notes
5820       The eval built-in is a special built-in.
5821
5822       The POSIX standard defines no options for the eval built-in; the
5823       built-in accepts no options in the POSIXly-correct mode.
5824

EXEC BUILT-IN

5826       The exec built-in replaces the shell process with another external
5827       command.
5828
5829   Syntax
5830exec [-cf] [-a name] [command [argument...]]
5831
5832       The exec built-in requires that all options precede operands. It is
5833       important so that options to the exec built-in are not confused with
5834       options to command. Any command line arguments after command are
5835       treated as arguments.
5836
5837   Description
5838       When the exec built-in is executed with command, the shell executes
5839       command with arguments in a manner similar to the last step of
5840       execution of a simple command. The differences are that command is
5841       always treated as an external command ignoring any existing functions
5842       and built-ins and that the exec system call that starts the external
5843       command is called in the current command execution environment instead
5844       of a subshell, replacing the shell process with the new command
5845       process.
5846
5847       If the shell is in the POSIXly-correct mode or not interactive, failure
5848       in execution of command causes the shell to exit immediately.
5849
5850       If an interactive shell that is not in the POSIXly-correct mode has a
5851       stopped job, the shell prints a warning message and refuses to execute
5852       command. Once the shell process is replaced with an external command,
5853       information about the shell’s jobs is lost, so you will have to resume
5854       or kill the stopped jobs by sending signals by hand. To force the shell
5855       to execute command regardless, specify the -f (--force) option.
5856
5857       When executed without command, the built-in does nothing. As a side
5858       effect, however, redirection applied to the built-in remains in the
5859       current command execution environment even after the built-in finished.
5860
5861   Options
5862       -a name, --as=name
5863           Pass name, instead of command, to the external command as its name.
5864
5865       -c, --clear
5866           Pass to the external command only variables that are assigned in
5867           the simple command in which the built-in is being executed. Other
5868           environment variables are not passed to the command.
5869
5870       -f, --force
5871           Suppress warnings that would prevent command execution.
5872
5873   Operands
5874       command
5875           An external command to be executed.
5876
5877       argument...
5878           Arguments to be passed to the command.
5879
5880   Exit status
5881       If the shell process was successfully replaced with the external
5882       command, there is no exit status since the shell process no longer
5883       exists.
5884
5885       The exit status is:
5886
5887       •   127 if the command was not found,
5888
5889       •   126 if the command was found but could not be executed, and
5890
5891       •   zero if no command was specified.
5892
5893   Notes
5894       The exec built-in is a special built-in.
5895
5896       The POSIX standard defines no options for the exec built-in; the
5897       built-in accepts no options in the POSIXly-correct mode.
5898

EXIT BUILT-IN

5900       The exit built-in causes the shell process to exit.
5901
5902   Syntax
5903exit [-f] [exit_status]
5904
5905   Description
5906       The exit built-in causes the current shell (or subshell) process to
5907       exit.
5908
5909       If an interactive shell has a stopped job, the shell prints a warning
5910       message and refuses to exit. To force the shell to exit regardless,
5911       specify the -f (--force) option or execute the built-in twice in a row.
5912
5913       If an EXIT trap has been set, the shell executes the trap before
5914       exiting.
5915
5916   Options
5917       -f, --force
5918           Suppress warnings that would prevent the shell from exiting.
5919
5920   Operands
5921       exit_status
5922           A non-negative integer that will be the exit status of the exiting
5923           shell.
5924
5925           If this operand is omitted, the exit status of the shell will be
5926           that of the last command executed before the exit built-in (but, if
5927           the built-in is executed during a trap, the exit status will be
5928           that of the last command before the trap is entered).
5929
5930           If exit_status is 256 or larger, the actual exit status will be the
5931           remainder of exit_status divided by 256.
5932
5933   Exit status
5934       Because the built-in causes the shell to exit, there is no exit status
5935       of the built-in.
5936
5937       As an exception, if the shell refused to exit, the exit status of the
5938       built-in is non-zero.
5939
5940   Notes
5941       The exit built-in is a special built-in.
5942
5943       The POSIX standard defines no options for the exit built-in; the
5944       built-in accepts no options in the POSIXly-correct mode.
5945
5946       The POSIX standard provides that the exit_status operand should be
5947       between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
5948       an extension.
5949
5950       If the built-in is executed during an EXIT trap, the shell just exits
5951       without executing the trap again. If exit_status was not specified, the
5952       exit status of the shell is what the exit status would be if the trap
5953       had not been set. See also Termination of the shell.
5954

EXPORT BUILT-IN

5956       The export built-in marks variables for export to child processes.
5957
5958   Syntax
5959export [-prX] [name[=value]...]
5960
5961   Description
5962       The export built-in is equivalent to the typeset built-in with the -gx
5963       option.
5964
5965   Notes
5966       The export built-in is a special built-in.
5967
5968       The POSIX standard defines the -p option only; other options cannot be
5969       used in the POSIXly-correct mode. The POSIX does not allow using the
5970       option together with operands.
5971

FALSE BUILT-IN

5973       The false built-in does nothing unsuccessfully.
5974
5975   Syntax
5976false
5977
5978   Description
5979       The false built-in does nothing. Any command line arguments are
5980       ignored.
5981
5982   Exit status
5983       The exit status of the false built-in is non-zero.
5984
5985   Notes
5986       The false built-in is a semi-special built-in.
5987

FC BUILT-IN

5989       The fc built-in re-executes or prints commands from command history.
5990
5991   Syntax
5992fc [-qr] [-e editor] [start [end]]
5993
5994fc -s[q] [old=new] [start]
5995
5996fc -l[nrv] [start [end]]
5997
5998   Description
5999       When executed without the -l (--list) option, the built-in executes the
6000       commands in the command history range specified by the operands. If the
6001       -s (--silent) option is not specified, the shell invokes an editor
6002       which allows you to edit the commands before they are executed. The
6003       commands are executed when you quit the editor. If the -s (--silent)
6004       option is specified, the commands are immediately executed. In either
6005       case, the executed commands are printed to the standard output and
6006       added to the history.
6007
6008       When executed with the -l (--list) option, the built-in prints the
6009       commands in the command history range specified by the operands. By
6010       default, commands are printed with their history entry numbers, but
6011       output format can be changed using the -n (--no-numbers)) and -v
6012       (--verbose) options.
6013
6014   Options
6015       -e editor, --editor=editor
6016           Specify an editor that is used to edit commands.
6017
6018           If this option is not specified, the value of the FCEDIT variable
6019           is used. If the variable is not set either, ed is used.
6020
6021       -l, --list
6022           Print command history entries.
6023
6024       -n, --no-numbers
6025           Don’t print entry numbers when printing history entries.
6026
6027       -q, --quiet
6028           Don’t print commands before executing.
6029
6030       -r, --reverse
6031           Reverse the order of command entries in the range.
6032
6033       -s, --silent
6034           Execute commands without editing them.
6035
6036       -v, --verbose
6037           Print execution time before each history entry when printing.
6038
6039   Operands
6040       start and end
6041           The start and end operands specify a range of command history
6042           entries that are executed or printed. If one of the operands is an
6043           integer, it is treated as a history entry number. A negative
6044           integer means the nth most recent entry where n is the absolute
6045           value of the integer. If one of the operands is not an integer, it
6046           is treated as part of a command string: the most recent entry that
6047           starts with the string is selected as the start or end of the
6048           range.
6049
6050           If the first entry of the range that is specified by start is newer
6051           than the last entry of the range that is specified by end, the
6052           range is reversed as if the -r (--reverse) option was specified.
6053           (If the option is already specified, it is cancelled.)
6054
6055           The default values for start and end are:
6056
6057           ┌──────┬─────────┬───────────────┐
6058           │      │ with -l without -l    
6059           ├──────┼─────────┼───────────────┤
6060start │ -16     │ -1            │
6061           ├──────┼─────────┼───────────────┤
6062end   │ -16     │ same as start
6063           └──────┴─────────┴───────────────┘
6064
6065       old=new
6066           An operand of this format replaces part of the command string. If
6067           the command string contains old, it is replaced with new and the
6068           new string is executed. Only the first occurrence of old is
6069           replaced.
6070
6071   Exit status
6072       If commands was executed, the exit status of the fc built-in is that of
6073       the last executed command. Otherwise, the exit status is zero unless
6074       there is any error.
6075
6076   Notes
6077       The fc built-in is a semi-special built-in.
6078
6079       The POSIX standard does not define the -q (--quiet) or -v (--verbose)
6080       options, so they cannot be used in the POSIXly-correct mode.
6081
6082       Command history cannot be modified during line-editing.
6083

FG BUILT-IN

6085       The fg built-in resumes a job in the foreground.
6086
6087   Syntax
6088fg [job...]
6089
6090   Description
6091       The fg built-in brings the specified job to the foreground and sends
6092       the SIGCONT signal to the job. As a result, the job is resumed in the
6093       foreground (if it has been suspended). The built-in then waits for the
6094       job to finish and returns the exit status of it.
6095
6096       The name of the job is printed when the job is resumed. When not in the
6097       POSIXly-correct mode, the job number is also printed.
6098
6099       The built-in can be used only when job control is enabled.
6100
6101   Operands
6102       job
6103           The job ID of the job to be resumed.
6104
6105           If more than one job is specified, they are resumed in order, one
6106           at a time. The current job is resumed if none is specified.
6107
6108           The percent sign (%) at the beginning of a job ID can be omitted if
6109           the shell is not in the POSIXly-correct mode.
6110
6111   Exit status
6112       The exit status of the fg built-in is that of the (last) job resumed.
6113       The exit status is non-zero when there was some error.
6114
6115   Notes
6116       The fg built-in is a semi-special built-in.
6117
6118       You cannot specify more than one job in the POSIXly-correct mode.
6119

GETOPTS BUILT-IN

6121       The getopts built-in parses command options.
6122
6123   Syntax
6124getopts optionlist variable [argument...]
6125
6126   Description
6127       The getopts built-in parses single-character options that appear in
6128       arguments. Each time the built-in is invoked, it parses one option and
6129       assigns the option character to variable.
6130
6131       The optionlist operand is a list of option characters that should be
6132       accepted by the parser. In optionlist, an option that takes an argument
6133       should be specified as the option character followed by a colon. For
6134       example, if you want the -a, -b and -c options to be parsed and the -b
6135       option to take an argument, then optionlist should be ab:c.
6136
6137       When an option that takes an argument is parsed, the argument is
6138       assigned to the OPTARG variable.
6139
6140       When an option that is not specified in optionlist is found or when an
6141       option argument is missing, the result depends on the first character
6142       of optionlist:
6143
6144       •   If optionlist starts with a colon, the option character is assigned
6145           to the OPTARG variable and variable is set to either ?  (when the
6146           option is not in optionlist) or : (when the option argument is
6147           missing).
6148
6149       •   Otherwise, variable is set to ?, the OPTARG variable is unset, and
6150           an error message is printed.
6151
6152       The built-in parses one option for each execution. For all options in a
6153       set of command line arguments to be parsed, the built-in has to be
6154       executed repeatedly with the same arguments. The built-in uses the
6155       OPTIND variable to remember which argument should be parsed next. When
6156       the built-in is invoked for the first time, the variable value must be
6157       1, which is the default value. You must not modify the variable until
6158       all the options have been parsed, when the built-in sets the variable
6159       to the index of the first operand in arguments. (If there are no
6160       operands, it will be set to the number of arguments plus one.)
6161
6162       When you want to start parsing a new set of arguments, you have to
6163       reset the OPTIND variable to 1 beforehand.
6164
6165   Operands
6166       optionlist
6167           A list of options that should be accepted as valid options in
6168           parsing.
6169
6170       variable
6171           The name of a variable the result is to be assigned to.
6172
6173       arguments
6174           Command line arguments that are to be parsed.
6175
6176           When no arguments are given, the positional parameters are parsed.
6177
6178   Exit status
6179       If an option is found, whether or not it is specified in optionlist,
6180       the exit status is zero. If there is no more option to be parsed, the
6181       exit status is non-zero.
6182
6183   Example
6184           aopt=false bopt= copt=false
6185           while getopts ab:c opt
6186           do
6187             case $opt in
6188             a) aopt=true ;;
6189             b) bopt=$OPTARG ;;
6190             c) copt=true ;;
6191             \?) return 2 ;;
6192             esac
6193           done
6194           if $aopt;          then echo Option -a specified;       fi
6195           if [ -n "$bopt" ]; then echo Option -b $bopt specified; fi
6196           if $copt;          then echo Option -c specified;       fi
6197           shift $((OPTIND - 1))
6198           echo Operands are: $*
6199
6200   Notes
6201       In arguments that are parsed, options must precede operands. The
6202       built-in ends parsing when it encounters the first operand.
6203
6204       The getopts built-in is a semi-special built-in.
6205
6206       The POSIX standard does not specify what will happen when the OPTIND
6207       variable is assigned a value other than 1.
6208
6209       In the POSIXly-correct mode, option characters in optionlist must be
6210       alphanumeric.
6211

HASH BUILT-IN

6213       The hash built-in remembers, forgets, or reports command locations.
6214
6215   Syntax
6216hash command...
6217
6218hash -r [command...]
6219
6220hash [-a]
6221
6222hash -d user...
6223
6224hash -dr [user...]
6225
6226hash -d
6227
6228   Description
6229       When executed with commands but without options, the built-in
6230       immediately performs command path search and caches commands' full
6231       paths.
6232
6233       When executed with the -r (--remove) option, it removes the paths of
6234       commands (or all cached paths if none specified) from the cache.
6235
6236       When executed without options or commands, it prints the currently
6237       cached paths to the standard output.
6238
6239       With the -d (--directory) option, the built-in does the same things to
6240       the home directory cache, rather than the command path cache. Cached
6241       home directory paths are used in tilde expansion.
6242
6243   Options
6244       -a, --all
6245           Print all cached paths.
6246
6247           Without this option, paths for built-ins are not printed.
6248
6249       -d, --directory
6250           Affect the home directory cache instead of the command path cache.
6251
6252       -r, --remove
6253           Remove cached paths.
6254
6255   Operands
6256       command
6257           The name of an external command (that does not contain any slash).
6258
6259       user
6260           A user name.
6261
6262   Exit status
6263       The exit status of the hash built-in is zero unless there is any error.
6264
6265   Notes
6266       The shell automatically caches command and directory paths when
6267       executing a command or performing tilde expansion, so normally there is
6268       no need to use this built-in explicitly to cache paths.
6269
6270       Assigning a value to the PATH variable removes all command paths from
6271       the cache as if hash -r was executed.
6272
6273       The POSIX standard defines the -r option only: other options cannot be
6274       used in the POSIXly-correct mode.
6275
6276       The hash built-in is a semi-special built-in.
6277

HELP BUILT-IN

6279       The help built-in prints usage of built-ins.
6280
6281   Syntax
6282help [built-in...]
6283
6284   Description
6285       The help built-in prints a description of built-ins.
6286
6287   Operands
6288       built-ins
6289           Names of built-ins.
6290
6291   Exit status
6292       The exit status of the help built-in is zero unless there is any error.
6293
6294   Notes
6295       The help built-in is a semi-special built-in. In the POSIX standard, it
6296       is defined as a command with unspecified behavior.
6297
6298       Many built-ins of yash accept the --help option that prints the same
6299       description.
6300

HISTORY BUILT-IN

6302       The history built-in prints or edits command history.
6303
6304   Syntax
6305history [-cF] [-d entry] [-s command] [-r file] [-w file] [count]
6306
6307   Description
6308       The history built-in prints or edits command history.
6309
6310       When executed with an option, the built-in edits history according to
6311       the option. If more than one option is specified, each option is
6312       processed in order.
6313
6314       When executed with the count operand, the built-in prints the most
6315       recent count history entries to the standard output in the same manner
6316       as the fc built-in.
6317
6318       When executed with neither options nor operands, the built-in prints
6319       the whole history.
6320
6321   Options
6322       -c, --clear
6323           Clear all history entries completely.
6324
6325       -d entry, --delete=entry
6326           Delete the specified entry. The entry should be specified in the
6327           same manner as the start and end operands of the fc built-in.
6328
6329       -F, --flush-file
6330           Rebuild the history file. This operation removes unused old data
6331           from the file.
6332
6333       -r file, --read=file
6334           Read command lines from file and add them to the history. The file
6335           contents are treated as lines of simple text.
6336
6337       -s command, --set=command
6338           Add command as a new history entry after removing the most recent
6339           entry.
6340
6341       -w file, --write=file
6342           Write the whole history to file. Any existing data in the file will
6343           be lost. The output format is lines of simple text, each of which
6344           is a command string.
6345
6346   Operands
6347       count
6348           The number of entries to be printed.
6349
6350   Exit status
6351       The exit status of the history built-in is zero unless there is any
6352       error.
6353
6354   Notes
6355       The history built-in is a semi-special built-in. In the POSIX standard,
6356       it is defined as a command with unspecified behavior.
6357
6358       Command history cannot be modified during line-editing.
6359

JOBS BUILT-IN

6361       The jobs built-in reports job status.
6362
6363   Syntax
6364jobs [-lnprs] [job...]
6365
6366   Description
6367       The jobs built-in prints information of jobs the shell is currently
6368       controlling.
6369
6370       By default, the following information is printed for each job, line by
6371       line:
6372
6373       •   the job number,
6374
6375       •   the + or - symbol if the job is the current or previous job,
6376           respectively,
6377
6378       •   the status, and
6379
6380       •   the command string.
6381
6382   Options
6383       -l, --verbose
6384           Print the process ID, status, and command string for each process
6385           in the jobs.
6386
6387       -n, --new
6388           Print new jobs only: jobs whose status has never been reported
6389           since the status changed.
6390
6391       -p, --pgid-only
6392           Print process group IDs of jobs only.
6393
6394       -r, --running-only
6395           Print running jobs only.
6396
6397       -s, --stopped-only
6398           Print stopped jobs only.
6399
6400   Operands
6401       jobs
6402           The job IDs of jobs to be reported. When no job is specified, all
6403           jobs under the shell’s control are reported.
6404
6405           The percent sign (%) at the beginning of a job ID can be omitted if
6406           the shell is not in the POSIXly-correct mode.
6407
6408   Exit status
6409       The exit status of the jobs built-in is zero unless there is any error.
6410
6411   Notes
6412       The jobs built-in is a semi-special built-in.
6413
6414       The POSIX standard defines the -l and -p options only: other options
6415       cannot be used in the POSIXly-correct mode. In the POSIXly-correct
6416       mode, the effect of the -l option is different in that status is
6417       reported for each job rather than for each process.
6418
6419       The process group ID of a job executed by yash is equal to the process
6420       ID of the first command of the pipeline that forms the job.
6421

KILL BUILT-IN

6423       The kill built-in sends a signal to processes.
6424
6425   Syntax
6426kill [-signal|-s signal|-n signal] process...
6427
6428kill -l [-v] [signal...]
6429
6430       The kill built-in requires that all options precede operands. Any
6431       command line arguments after the first operand are all treated as
6432       operands.
6433
6434   Description
6435       When executed without the -l option, the built-in sends a signal to
6436       processes. The signal sent can be specified by option. The SIGTERM
6437       signal is sent if no signal is specified.
6438
6439       When executed with the -l option, the built-in prints information of
6440       signals to the standard output. If no signal is specified, information
6441       of all signals is printed.
6442
6443   Options
6444       Signal-specifying options
6445           -signal, -s signal, -n signal
6446               A signal-specifying option specifies a signal to be sent to
6447               processes.  signal can be specified by name or number. If
6448               number 0 is specified, the built-in checks if a signal could be
6449               sent to the processes but no signal is actually sent. Signal
6450               names are case-insensitive.
6451
6452           You can specify at most one signal-specifying option at a time.
6453
6454       Other options
6455           -l
6456               Print signal information instead of sending a signal.
6457
6458           -v
6459               Print more signal information.
6460
6461               Without this option, the built-in prints the signal name only.
6462               This option adds the signal number and a short description.
6463
6464               When the -v option is specified, the -l option can be omitted.
6465
6466   Operands
6467       processes
6468           Specify processes to which a signal is sent.
6469
6470           Processes can be specified by the process ID, the process group ID,
6471           or the job ID. The process group ID must be prefixed with a hyphen
6472           (-) so that it is not treated as a process ID.
6473
6474           When 0 is specified as process, the signal is sent to the process
6475           group to which the shell process belongs. When -1 is specified, the
6476           signal is sent to all processes on the system.
6477
6478       signal
6479           Specify a signal of which information is printed.
6480
6481           The signal can be specified by the name, the number, or the exit
6482           status of a command that was killed by the signal.
6483
6484   Exit status
6485       The exit status of the kill built-in is zero unless there is any error.
6486       If the signal was sent to at least one process, the exit status is zero
6487       even if the signal was not sent to all of the specified processes.
6488
6489   Notes
6490       The kill built-in is a semi-special built-in.
6491
6492       Command arguments that start with a hyphen should be used with care.
6493       The command kill -1 -2, for example, sends signal 1 to process group 2
6494       since -1 is treated as a signal-specifying option and -2 as an operand
6495       that specifies a process group. The commands kill -- -1 -2 and kill
6496       -TERM -1 -2, on the other hand, treats both -1 and -2 as operands.
6497
6498       The POSIX standard does not define the -n or -v options, so they cannot
6499       be used in the POSIXly-correct mode. The standard does not allow
6500       specifying a signal number as the argument of the -s option or a signal
6501       name as the signal operand.
6502
6503       The standard requires signal names to be specified without the SIG
6504       prefix, like INT and QUIT. If the shell is not in the POSIXly-correct
6505       mode, the built-in accepts SIG-prefixed signal names as well.
6506

LOCAL BUILT-IN

6508       The local built-in prints or sets local variables.
6509
6510   Syntax
6511local [-rxX] [name[=value]...]
6512
6513   Description
6514       The local built-in is equivalent to the typeset built-in except that
6515       the -f (--functions) and -g (--global) options cannot be used.
6516
6517   Notes
6518       The local built-in is a semi-special built-in. In the POSIX standard,
6519       it is defined as a command with unspecified behavior.
6520

POPD BUILT-IN

6522       The popd built-in pops a directory from the directory stack.
6523
6524   Syntax
6525popd [index]
6526
6527   Description
6528       The popd built-in removes the last entry from the directory stack,
6529       returning to the previous working directory. If index is given, the
6530       entry specified by index is removed instead of the last one.
6531
6532   Operands
6533       index
6534           The index of a directory stack entry you want to remove.
6535
6536           If omitted, +0 (the last entry) is assumed.
6537
6538   Exit status
6539       The exit status of the popd built-in is zero unless there is any error.
6540
6541   Notes
6542       It is an error to use this built-in when there is only one directory
6543       stack entry.
6544
6545       The popd built-in is a semi-special built-in. In the POSIX standard, it
6546       is defined as a command with unspecified behavior.
6547

PRINTF BUILT-IN

6549       The printf built-in prints formatted values.
6550
6551   Syntax
6552printf format [value...]
6553
6554   Description
6555       The printf built-in formats values according to format and prints them
6556       to the standard output. Unlike the echo built-in, the printf built-in
6557       does not print a newline automatically.
6558
6559       The formatting process is very similar to that of the printf function
6560       in the C programming language. You can use conversion specifications
6561       (which start with %) and escape sequences (which start with \) in
6562       format. Any other characters that are not part of a conversion
6563       specification or escape sequence are printed literally.
6564
6565       Conversion specifications
6566           A conversion specification starts with a percent sign (%).
6567
6568           A conversion specification except %% consumes a value, which is
6569           formatted according to the specification and printed. Each
6570           conversion specification consumes one value in the order of
6571           appearance. If there are more values than conversion
6572           specifications, the entire format is re-processed until all the
6573           values are consumed. If a value to be consumed is missing, it is
6574           assumed to be an empty string (if the specification requires a
6575           string) or zero (if a number). If no values are given, format is
6576           processed just once.
6577
6578           Available conversion specifications are:
6579
6580           %d, %i
6581               prints a signed integer in decimal
6582
6583           %u
6584               prints an unsigned integer in decimal
6585
6586           %o
6587               prints an unsigned integer in octal
6588
6589           %x
6590               prints an unsigned integer in lowercase hexadecimal
6591
6592           %X
6593               prints an unsigned integer in uppercase hexadecimal
6594
6595           %f
6596               prints a floating-point number in lowercase
6597
6598           %F
6599               prints a floating-point number in uppercase
6600
6601           %e
6602               prints a floating-point number with exponent in lowercase
6603
6604           %E
6605               prints a floating-point number with exponent in uppercase
6606
6607           %g
6608               the same as %f or %e, automatically selected
6609
6610           %G
6611               the same as %F or %E, automatically selected
6612
6613           %c
6614               prints the first character of string
6615
6616           %s
6617               prints a string
6618
6619           %b
6620               prints a string (recognizing escape sequences like the echo
6621               built-in)
6622
6623           %%
6624               prints a percent sign (%)
6625
6626           For %g and %G, the specification that is actually used is %f or %F
6627           if the exponent part is between -5 and the precision (exclusive);
6628           %e or %E otherwise.
6629
6630           In a conversion specification except %%, the leading percent sign
6631           may be followed by flags, field width, and/or precision in this
6632           order.
6633
6634           The flags are a sequence of any number of the following characters:
6635
6636           Minus sign (-)
6637               With this flag, spaces are appended to the formatted value to
6638               fill up to the field width. Otherwise, spaces are prepended.
6639
6640           Plus sign (+)
6641               A plus or minus sign is always prepended to a number.
6642
6643           Space ( )
6644               A space is prepended to a formatted number if it has no plus or
6645               minus sign.
6646
6647           Hash sign (#)
6648               The value is formatted in an alternative form: For %o, the
6649               printed octal integer has at least one leading zero. For %x and
6650               %X, a non-zero integer is formatted with 0x and 0X prefixes,
6651               respectively. For %e, %E, %f, %F, %g, and %G, a decimal mark
6652               (a.k.a. radix character) is always printed even if the value is
6653               an exact integer. For %g and %G, the printed number has at
6654               least one digit in the fractional part.
6655
6656           Zero (0)
6657               Zeros are prepended to a formatted number to fill up to the
6658               field width. This flag is ignored if the minus flag is
6659               specified or if the conversion specification is %d, %i, %u, %o,
6660               %x, or %X with a precision.
6661
6662           A field width is specified as a decimal integer that has no leading
6663           zeros.
6664
6665           A field width defines a minimum byte count of a formatted value. If
6666           the formatted value does not reach the minimum byte count, so many
6667           spaces are prepended that the printed value has the specified byte
6668           count.
6669
6670           A precision is specified as a period (.) followed by a decimal
6671           integer. If the integer is omitted after the period, the precision
6672           is assumed to be zero.
6673
6674           For conversion specifications %d, %i, %u, %o, %x, and %X, a
6675           precision defines a minimum digit count. If the formatted integer
6676           does not reach the minimum digit count, so many zeros are prepended
6677           that the printed integer has the specified number of digits. The
6678           default precision is one for these conversion specifications.
6679
6680           For conversion specifications %e, %E, %f, and %F, a precision
6681           defines the number of digits after the decimal mark. The default
6682           precision is six for these conversion specifications.
6683
6684           For conversion specifications %g, and %G, a precision defines a
6685           maximum number of significant digits in the printed value. The
6686           default precision is six for these conversion specifications.
6687
6688           For conversion specifications %s, and %b, a precision defines a
6689           maximum byte count of the printed string. The default precision is
6690           infinity for these conversion specifications.
6691
6692           In the conversion specification %08.3f, the zero flag is specified,
6693           the field width is 8, and the precision is 3. If this specification
6694           is applied to value 12.34, the output will be 0012.340.
6695
6696       Escape sequences
6697           The following escape sequences are recognized in format:
6698
6699           \a
6700               Bell character (ASCII code: 7)
6701
6702           \b
6703               Backspace (ASCII code: 8)
6704
6705           \f
6706               Form feed character (ASCII code: 12)
6707
6708           \n
6709               Newline character (ASCII code: 10)
6710
6711           \r
6712               Carriage return character (ASCII code: 13)
6713
6714           \t
6715               Horizontal tab character (ASCII code: 9)
6716
6717           \v
6718               Vertical tab character (ASCII code: 11)
6719
6720           \\
6721               Backslash
6722
6723           \"
6724               Double quotation
6725
6726           \'
6727               Single quotation (apostrophe)
6728
6729           \xxx
6730               Character whose code is xxx, where xxx is an octal number of at
6731               most three digits.
6732
6733   Operands
6734       format
6735           A string that defines how values should be formatted.
6736
6737       values
6738           Values that are formatted according to format.
6739
6740           A value is either a number or a string.
6741
6742           When a numeric value is required, value can be a single or double
6743           quotation followed by a character, instead of a normal number. For
6744           example, the command printf '%d' '"3' will print 51 on a typical
6745           environment where character 3 has character code 51.
6746
6747   Exit status
6748       The exit status of the printf built-in is zero unless there is any
6749       error.
6750
6751   Notes
6752       The POSIX standard does not precisely define how multibyte characters
6753       should be handled by the built-in. When you use the %s conversion
6754       specification with precision or the %c conversion specification, you
6755       may obtain unexpected results if the formatted value contains a
6756       character that is represented by more than one byte. Yash never prints
6757       only part of the bytes that represent a single multibyte character
6758       because all multibyte characters are converted to wide characters when
6759       processed in the shell.
6760
6761       If the shell is not in the POSIXly-correct mode and the “long double”
6762       floating-point arithmetic is supported on the running system, then
6763       “long double” is used for floating-point conversion specifications.
6764       Otherwise, “double” is used.
6765

PUSHD BUILT-IN

6767       The pushd built-in pushes a directory into the directory stack.
6768
6769   Syntax
6770pushd [-L|-P] [directory]
6771
6772   Description
6773       The pushd built-in changes the working directory to directory in the
6774       same manner as the cd built-in and adds it to the directory stack. If
6775       the working directory could not be changed successfully, the stack is
6776       not modified.
6777
6778   Options
6779       The pushd built-in accepts the following option as well as the options
6780       that can be used for the cd built-in:
6781
6782       --remove-duplicates
6783           If the new working directory has already been in the directory
6784           stack, the existing entry is removed from the stack before the new
6785           directory is pushed into the stack.
6786
6787   Operands
6788       directory
6789           The pathname of the new working directory.
6790
6791           If directory is a single hyphen (‘-’), the value of the OLDPWD
6792           variable is assumed for the new directory pathname, which is
6793           printed to the standard output.
6794
6795           If directory is an integer with a plus or minus sign, it is
6796           considered as an entry index of the directory stack. The entry is
6797           removed from the stack and then pushed to the stack again.
6798
6799           If directory is omitted, the working directory is changed to the
6800           directory specified by the --default-directory=...  option. If that
6801           option is not specified either, the default is index +1.
6802
6803   Exit status
6804       The exit status of the pushd built-in is zero unless there is any
6805       error.
6806
6807   Notes
6808       The pushd built-in is a semi-special built-in. In the POSIX standard,
6809       it is defined as a command with unspecified behavior.
6810

PWD BUILT-IN

6812       The pwd built-in prints the current working directory.
6813
6814   Syntax
6815pwd [-L|-P]
6816
6817   Description
6818       The pwd built-in prints an absolute path to the shell’s current working
6819       directory to the standard output.
6820
6821   Options
6822       -L, --logical
6823           If the value of the PWD variable is an absolute path to the shell’s
6824           working directory and the path does not contain any .  or ..
6825           components, then the path is printed. Otherwise, the printed path
6826           is the same as when the -P option is specified.
6827
6828       -P, --physical
6829           The printed path does not contain any .  or ..  components,
6830           symbolic link components, or redundant slashes.
6831
6832       The -L (--logical) and -P (--physical) options are mutually exclusive:
6833       only the last specified one is effective. If neither is specified, -L
6834       is assumed.
6835
6836   Exit status
6837       The exit status of the pwd built-in is zero unless there is any error.
6838
6839   Notes
6840       The pwd built-in is a semi-special built-in.
6841

READ BUILT-IN

6843       The read built-in reads a line from the standard input.
6844
6845   Syntax
6846read [-Aer] [-P|-p] variable...
6847
6848   Description
6849       The read built-in reads a line of string from the standard input and
6850       assigns it to the specified variables.
6851
6852       If the -r (--raw-mode) option is specified, all characters in the line
6853       are treated literally.
6854
6855       If the -r (--raw-mode) option is not specified, backslashes in the line
6856       are treated as quotations. If a backslash is at the end of the line, it
6857       is treated as a line continuation. When the built-in reads the next
6858       line, the PS2 variable is used as a prompt if the shell is interactive
6859       and the standard input is a terminal.
6860
6861       The input line is subject to field splitting. The resulting words are
6862       assigned to variables in order. If there are more words than variables,
6863       the last variable is assigned all the remaining words (as if the words
6864       were not split). If the words are fewer than variables, the remaining
6865       variables are assigned empty strings.
6866
6867   Options
6868       -A, --array
6869           Make the last variable an array. Instead of assigning a
6870           concatenation of the remaining words to a normal variable, the
6871           words are assigned to an array.
6872
6873       -e, --line-editing
6874           Use line-editing to read the line.
6875
6876           To use line-editing, all of the following conditions must also be
6877           met:
6878
6879           •   The shell is interactive.
6880
6881           •   The vi or emacs option is enabled.
6882
6883           •   The standard input and standard error are connected to a
6884               terminal.
6885
6886       -P, --ps1
6887           Print the PS1 variable as a prompt before reading the (first) line
6888           if the shell is interactive and the standard input is a terminal.
6889
6890       -p prompt, --prompt=prompt
6891           Print the specified prompt before reading the (first) line if the
6892           shell is interactive and the standard input is a terminal.
6893
6894       -r, --raw-mode
6895           Don’t treat backslashes as quotations.
6896
6897   Operands
6898       variables
6899           Names of variables to which input words are assigned.
6900
6901   Exit status
6902       The exit status of the read built-in is zero unless there is any error.
6903
6904       Note that the exit status is non-zero if an end of input is encountered
6905       before reading the entire line.
6906
6907   Notes
6908       The read built-in is a semi-special built-in.
6909
6910       The POSIX standard defines the -r option only: other options cannot be
6911       used in the POSIXly-correct mode.
6912
6913       The PS1R and PS1S variables affect the behavior of line-editing if the
6914       PS1 prompt is used. The same for PS2.
6915

READONLY BUILT-IN

6917       The readonly built-in makes variables and functions read-only.
6918
6919   Syntax
6920readonly [-pxX] [name[=value]...]
6921
6922readonly -f[p] [name...]
6923
6924   Description
6925       The readonly built-in is equivalent to the typeset built-in with the
6926       -gr option.
6927
6928   Notes
6929       The readonly built-in is a special built-in.
6930
6931       The POSIX standard defines the -p option only; other options cannot be
6932       used in the POSIXly-correct mode. The POSIX does not allow using the
6933       option together with operands.
6934

RETURN BUILT-IN

6936       The return built-in returns from a function or script.
6937
6938   Syntax
6939return [-n] [exit_status]
6940
6941   Description
6942       When executed without the -n (--no-return) option, one of the following
6943       happens:
6944
6945       •   If the shell is executing a function, the execution of the function
6946           is terminated.
6947
6948       •   If the dot built-in is executing a script, the execution of the
6949           script is terminated.
6950
6951       •   If the shell is executing a script during initialization, the
6952           execution of the script is terminated.
6953
6954       •   If the shell is executing a trap, the execution of the trap is
6955           terminated for the currently handled signal.
6956
6957       •   Otherwise, the shell exits unless it is interactive.
6958
6959       When executed with the -n (--no-return) option, the built-in does
6960       nothing but return the specified exit_status.
6961
6962   Options
6963       -n, --no-return
6964           Do not terminate a function, script, trap, or the shell.
6965
6966   Operands
6967       exit_status
6968           The exit status of the built-in.
6969
6970           The value must be a non-negative integer.
6971
6972           If omitted, the exit status of the last executed command is used.
6973           (But when the shell is executing a trap, the exit status of the
6974           last command before the trap is used.)
6975
6976   Exit status
6977       The exit status of the return built-in is defined by the exit_status
6978       operand. The exit status is used also as the exit status of the
6979       terminated function, script, or the shell.
6980
6981   Notes
6982       The return built-in is a special built-in.
6983
6984       The POSIX standard provides that the exit_status operand should be
6985       between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
6986       an extension.
6987
6988       In the POSIX standard, the behavior of the return built-in is defined
6989       only when the shell is executing a function or script.
6990
6991       The POSIX standard defines no options for the return built-in; the
6992       built-in accepts no options in the POSIXly-correct mode.
6993

SET BUILT-IN

6995       The set built-in sets shell options and positional parameters.
6996
6997   Syntax
6998set [options] [operands]
6999
7000set -o
7001
7002set +o
7003
7004       The set built-in requires that all options precede operands. Any
7005       command line arguments after the first operand are all treated as
7006       operands.
7007
7008   Description
7009       When executed without any command arguments, the built-in prints a list
7010       of all existing variables to the standard input in a form that can be
7011       reused as commands that will restore the variable definitions.
7012
7013       When -o is the only command argument, the built-in prints a list of
7014       shell options with their current settings. When +o is the only command
7015       argument, the built-in prints commands that can be reused to restore
7016       the current shell option settings.
7017
7018       In other cases, the built-in changes shell option settings and/or
7019       positional parameters.
7020
7021   Options
7022       When one or more options are specified, the built-in enables or
7023       disables the shell options. A normal hyphen-prefixed option enables a
7024       shell option. An option that is prefixed with a plus (+) instead of a
7025       hyphen disables a shell option. For example, options -m, -o monitor,
7026       and --monitor enable the monitor option and options +m, +o monitor,
7027       ++monitor disable it.
7028
7029       The name of a long option is case-insensitive and may include
7030       irrelevant non-alphanumeric characters, which are ignored. For example,
7031       options --le-comp-debug and --LeCompDebug are equivalent. If no is
7032       prepended to the name of a long option, the meaning is reversed. For
7033       example, --noallexport is equivalent to ++allexport and ++nonotify to
7034       --notify.
7035
7036       An option can be specified in one of the following forms:
7037
7038       •   a long option e.g.  --allexport
7039
7040       •   an -o option with a option name specified as the argument e.g.  -o
7041           allexport
7042
7043       •   a single-character option e.g.  -a
7044
7045       Not all options can be specified as single-character options.
7046
7047       The available options are:
7048
7049       all-export (-a)
7050           When enabled, all variables are automatically exported when
7051           assigned.
7052
7053       brace-expand
7054           This option enables brace expansion.
7055
7056       case-glob
7057           (Enabled by default) When enabled, pattern matching is
7058           case-sensitive in pathname expansion.
7059
7060       clobber (+C)
7061           (Enabled by default) When enabled, the > redirection behaves the
7062           same as the >| redirection.
7063
7064       cur-async, cur-bg, cur-stop
7065           (Enabled by default) These options affect choice of the current job
7066           (cf.  job ID).
7067
7068       dot-glob
7069           When enabled, periods at the beginning of filenames are not treated
7070           specially in pathname expansion.
7071
7072       emacs
7073           This option enables line-editing in the emacs mode.
7074
7075       empty-last-field
7076           When enabled, field splitting does not remove the last field even
7077           if it is empty.
7078
7079       err-exit (-e)
7080           When enabled, if a pipeline ends with a non-zero exit status, the
7081           shell immediately exits unless the following suppress condition is
7082           met:
7083
7084           •   the pipeline is a condition of an if command or while or until
7085               loop;
7086
7087           •   the pipeline is prefixed by !; or
7088
7089           •   the pipeline is a single compound command other than a subshell
7090               grouping.
7091
7092       err-return
7093           This option is like the err-exit option, but the return built-in is
7094           executed instead of the shell exiting on a non-zero exit status.
7095           Unlike err-exit, the suppress condition does not apply inside a
7096           function, subshell grouping, or script file.
7097
7098       exec (+n)
7099           (Enabled by default) Commands are actually executed only when this
7100           option is enabled. Otherwise, commands are just parsed and not
7101           executed. Disabling this option may be useful for syntax checking.
7102           In an interactive shell, this option is always assumed enabled.
7103
7104       extended-glob
7105           This option enables extension in pathname expansion.
7106
7107       for-local
7108           (Enabled by default) If a for loop is executed within a function,
7109           this option causes the iteration variable to be created as a local
7110           variable, even if the variable already exists globally. This option
7111           has no effect if the POSIXly-correct mode is active.
7112
7113       glob (+f)
7114           (Enabled by default) This option enables pathname expansion.
7115
7116       hash-on-def (-h)
7117           When a function is defined when this option is enabled, the shell
7118           immediately performs command path search for each command that
7119           appears in the function and caches the command’s full path.
7120
7121       hist-space
7122           When enabled, command lines that start with a whitespace are not
7123           saved in command history.
7124
7125       ignore-eof
7126           When enabled, an interactive shell does not exit when EOF (end of
7127           file) is input. This prevents the shell from exiting when you
7128           accidentally hit Ctrl-D.
7129
7130       le-always-rp, le-comp-debug, le-conv-meta, le-no-conv-meta, le-predict,
7131       le-predict-empty, le-prompt-sp, le-visible-bell
7132           See shell options on line-editing.
7133
7134       mark-dirs
7135           When enabled, resulting directory names are suffixed by a slash in
7136           pathname expansion.
7137
7138       monitor (-m)
7139           This option enables job control. This option is enabled by default
7140           for an interactive shell.
7141
7142       notify (-b)
7143           When the status of a job changes when this option is enabled, the
7144           shell immediately notifies at any time. This option overrides the
7145           notify-le option.
7146
7147       notify-le
7148           This option is similar to the notify option, but the status change
7149           is notified only while the shell is waiting for input with
7150           line-editing.
7151
7152       null-glob
7153           When enabled, in pathname expansion, patterns that do not match any
7154           pathname are removed from the command line rather than left as is.
7155
7156       pipe-fail
7157           When enabled, the exit status of a pipeline is zero if and only if
7158           all the subcommands of the pipeline exit with an exit status of
7159           zero.
7160
7161       posixly-correct
7162           This option enables the POSIXly-correct mode.
7163
7164       trace-all
7165           (Enabled by default) When this option is disabled, the x-trace
7166           option is temporarily disabled while the shell is executing
7167           commands defined in the COMMAND_NOT_FOUND_HANDLER, PROMPT_COMMAND,
7168           or YASH_AFTER_CD variable.
7169
7170       unset (+u)
7171           (Enabled by default) When enabled, an undefined parameter is
7172           expanded to an empty string in parameter expansion and treated as
7173           zero in arithmetic expansion. When disabled, expansion of an
7174           undefined parameter results in an error.
7175
7176       verbose (-v)
7177           When enabled, the shell prints each command line to the standard
7178           error before parsing and executing it.
7179
7180       vi
7181           This option enables line-editing in the vi mode. This option is
7182           enabled by default in an interactive shell if the standard input
7183           and error are both terminals.
7184
7185       x-trace (-x)
7186           When enabled, the results of expansion are printed to the standard
7187           error for each simple command being executed. When printed, each
7188           line is prepended with an expansion result of the PS4 variable. See
7189           also the trace-all option.
7190
7191   Operands
7192       If one or more operands are passed to the set built-in, current
7193       positional parameters are all removed and the operands are set as new
7194       positional parameters. If the -- separator (cf. syntax of command
7195       arguments) is passed, the positional parameters are set even when there
7196       are no operands, in which case new positional parameters will be
7197       nothing.
7198
7199   Exit status
7200       The exit status of the set built-in is zero unless there is any error.
7201
7202   Notes
7203       The set built-in is a special built-in.
7204
7205       In the POSIX standard, available shell options are much limited. The
7206       standard does not define:
7207
7208       •   long options such as --allexport,
7209
7210       •   prepending no to negate an option,
7211
7212       •   using uppercase letters and/or non-alphanumeric characters in
7213           option names
7214
7215       The options defined in the standard are:
7216
7217-a, -o allexport
7218
7219-e, -o errexit
7220
7221-m, -o monitor
7222
7223-C, -o noclobber
7224
7225-n, -o noexec
7226
7227-f, -o noglob
7228
7229-b, -o notify
7230
7231-u, -o nounset
7232
7233-v, -o verbose
7234
7235-x, -o xtrace
7236
7237-h
7238
7239-o ignoreeof
7240
7241-o nolog
7242
7243-o vi
7244
7245       Yash does not support the nolog option, which prevents function
7246       definitions from being added to command history.
7247

SHIFT BUILT-IN

7249       The shift built-in removes some positional parameters or array values.
7250
7251   Syntax
7252shift [-A array] [count]
7253
7254   Description
7255       The shift built-in removes the first count positional parameters or
7256       array values, where count is specified by the operand.
7257
7258   Options
7259       -A array, --array=array
7260           Remove first count values of array instead of positional
7261           parameters.
7262
7263   Operands
7264       count
7265           The number of positional parameters or array values to be removed.
7266
7267           It is an error if the actual number of positional parameters or
7268           array values is less than count. If omitted, the default value is
7269           one. If negative, the last -count positional parameters or array
7270           values are removed instead of the first ones.
7271
7272   Exit status
7273       The exit status of the shift built-in is zero unless there is any
7274       error.
7275
7276   Notes
7277       The shift built-in is a special built-in.
7278
7279       The number of positional parameters can be obtained with the # special
7280       parameter. The number of array values can be obtained with ${array[#]}.
7281
7282       The POSIX standard defines no options for the shift built-in; the
7283       built-in accepts no options in the POSIXly-correct mode.
7284
7285       Negative operands are not allowed in the POSIXly-correct mode.
7286

SUSPEND BUILT-IN

7288       The suspend built-in suspends the shell.
7289
7290   Syntax
7291suspend [-f]
7292
7293   Description
7294       The suspend built-in sends a SIGSTOP signal to all processes in the
7295       process group to which the shell process belongs. The signal suspends
7296       the processes (including the shell). The suspended processes resume
7297       when they receive a SIGCONT signal.
7298
7299       If the shell is interactive and its process group ID is equal to the
7300       process ID of the session leader, the shell prints a warning message
7301       and refuses to send a signal unless the -f (--force) option is
7302       specified. (In such a case, there is no other job-controlling shell
7303       that can send a SIGCONT signal to resume the suspended shell, so the
7304       shell could never be resumed.)
7305
7306   Options
7307       -f, --force
7308           Suppress warnings that would prevent the shell from sending a
7309           signal.
7310
7311   Exit status
7312       The exit status is zero if the signal was successfully sent and
7313       non-zero otherwise.
7314
7315   Notes
7316       The suspend built-in is a semi-special built-in. In the POSIX standard,
7317       it is defined as a command with unspecified behavior.
7318

TEST BUILT-IN

7320       The test built-in evaluates an expression.
7321
7322   Syntax
7323test expression
7324
7325[ expression ]
7326
7327       The test built-in does not distinguish options and operands; all
7328       command line arguments are interpreted as expression. If the built-in
7329       is executed with the name [, expression must be followed by ].
7330
7331   Description
7332       The test built-in evaluates expression as a conditional expression that
7333       is made up of operators and operands described below. The exit status
7334       is 0 if the condition is true and 1 otherwise.
7335
7336       The unary operators below test a file. If the operand file is a
7337       symbolic link, the file referred to by the link is tested (except for
7338       the -h and -L operators).
7339
7340       -b file
7341           file is a block special file
7342
7343       -c file
7344           file is a character special file
7345
7346       -d file
7347           file is a directory
7348
7349       -e file
7350           file exists
7351
7352       -f file
7353           file is a regular file
7354
7355       -G file
7356           file's group ID is same as the shell’s effective group ID
7357
7358       -g file
7359           file's set-group-ID flag is set
7360
7361       -h file
7362           same as -L
7363
7364       -k file
7365           file's sticky bit is set
7366
7367       -L file
7368           file is a symbolic link
7369
7370       -N file
7371           file has not been accessed since last modified
7372
7373       -O file
7374           file's user ID is same as the shell’s effective user ID
7375
7376       -p file
7377           file is a FIFO (named pipe)
7378
7379       -r file
7380           file is readable
7381
7382       -S file
7383           file is a socket
7384
7385       -s file
7386           file is not empty
7387
7388       -u file
7389           file's set-user-ID flag is set
7390
7391       -w file
7392           file is writable
7393
7394       -x file
7395           file is executable
7396
7397       The unary operator below tests a file descriptor:
7398
7399       -t fd
7400           fd is associated with a terminal
7401
7402       The unary operators below test a string:
7403
7404       -n string
7405           string is not empty
7406
7407       -z string
7408           string is empty
7409
7410       The unary operator below tests a shell option:
7411
7412       -o ?option
7413           option is a valid shell option name
7414
7415       -o option
7416           option is a valid shell option name that is enabled
7417
7418       The binary operators below compare files. Non-existing files are
7419       considered older than any existing files.
7420
7421       file1 -nt file2
7422           file1 is newer than file2
7423
7424       file1 -ot file2
7425           file1 is older than file2
7426
7427       file1 -ef file2
7428           file1 is a hard link to file2
7429
7430       The binary operators below compare strings:
7431
7432       string1 = string2, string1 == string2
7433           string1 is the same string as string2
7434
7435       string1 != string2
7436           string1 is not the same string as string2
7437
7438       The binary operators below compare strings according to the alphabetic
7439       order in the current locale:
7440
7441       string1 === string2
7442           string1 is equal to string2
7443
7444       string1 !== string2
7445           string1 is not equal to string2
7446
7447       string1 < string2
7448           string1 is less than string2
7449
7450       string1 <= string2
7451           string1 is less than or equal to string2
7452
7453       string1 > string2
7454           string1 is greater than string2
7455
7456       string1 >= string2
7457           string1 is greater than or equal to string2
7458
7459       The binary operator below performs pattern matching:
7460
7461       string =~ pattern
7462           extended regular expression pattern matches (part of) string
7463
7464       The binary operators below compare integers:
7465
7466       v1 -eq v2
7467           v1 is equal to v2
7468
7469       v1 -ne v2
7470           v1 is not equal to v2
7471
7472       v1 -gt v2
7473           v1 is greater than v2
7474
7475       v1 -ge v2
7476           v1 is greater than or equal to v2
7477
7478       v1 -lt v2
7479           v1 is less than v2
7480
7481       v1 -le v2
7482           v1 is less than or equal to v2
7483
7484       The binary operators below compare version numbers:
7485
7486       v1 -veq v2
7487           v1 is equal to v2
7488
7489       v1 -vne v2
7490           v1 is not equal to v2
7491
7492       v1 -vgt v2
7493           v1 is greater than v2
7494
7495       v1 -vge v2
7496           v1 is greater than or equal to v2
7497
7498       v1 -vlt v2
7499           v1 is less than v2
7500
7501       v1 -vle v2
7502           v1 is less than or equal to v2
7503
7504       The operators below can be used to make complex expressions:
7505
7506       ! expression
7507           negate (reverse) the result
7508
7509       ( expression )
7510           change operator precedence
7511
7512       expression1 -a expression2
7513           logical conjunction (and)
7514
7515       expression1 -o expression2
7516           logical disjunction (or)
7517
7518       If the expression is a single word without operators, the -n operator
7519       is assumed. An empty expression evaluates to false.
7520
7521       Comparison of version numbers
7522           Comparison of version numbers is similar to comparison of strings
7523           in alphabetic order. The differences are:
7524
7525           •   Adjacent digits are treated as an integer. Integers are
7526               compared in mathematical order rather than alphabetic order.
7527
7528           •   Digits are considered larger than any non-digit characters.
7529
7530           For example, version numbers 0.1.2-3 and 00.001.02-3 are equal and
7531           0.2.1 is smaller than 0.10.0.
7532
7533   Exit status
7534       The exit status of the test built-in is 0 if expression is true and 1
7535       otherwise. The exit status is 2 if expression cannot be evaluated
7536       because of a syntax error or any other reasons.
7537
7538   Notes
7539       Complex expressions may cause confusion and should be avoided. Use the
7540       shell’s compound commands. For example, [ 1 -eq 1 ] && [ -t = 1 ] && !
7541       [ foo ] is preferred over [ 1 -eq 1 -a -t = 1 -a ! foo ].
7542
7543       The POSIX standard provides that the exit status should be larger than
7544       1 on error. The POSIX standard does not define the following operators:
7545       -G, -k, -N, -O, -nt, -ot, -ef, ==, ===, !==, <, <=, >, >=, =~, -veq,
7546       -vne, -vgt, -vge, -vlt, and -vle. POSIX neither specifies -o as a unary
7547       operator.
7548

TIMES BUILT-IN

7550       The times built-in prints CPU time usage.
7551
7552   Syntax
7553times
7554
7555   Description
7556       The times built-in prints the CPU times consumed by the shell process
7557       and its child processes to the standard output.
7558
7559       The built-in prints two lines: the first line shows the CPU time of the
7560       shell process and the second one that of its child processes (not
7561       including those which have not terminated). Each line shows the CPU
7562       times consumed in the user and system mode.
7563
7564   Exit status
7565       The exit status of the times built-in is zero unless there is any
7566       error.
7567
7568   Notes
7569       The times built-in is a special built-in.
7570

TRAP BUILT-IN

7572       The trap built-in sets or prints signal handlers.
7573
7574   Syntax
7575trap
7576
7577trap action signal...
7578
7579trap signal_number [signal...]
7580
7581trap -p [signal...]
7582
7583   Description
7584       The trap built-in sets or prints actions that are taken when the shell
7585       receives signals. (Those actions are called traps.)
7586
7587       When executed with action and one or more signals, the built-in sets
7588       the traps for signals to action. If the shell receives one of the
7589       signals, the action will be taken.
7590
7591       If the first operand is signal_number instead of action, the built-in
7592       resets the traps for signal_number and signals as if action was -.
7593
7594       When executed with the -p (--print) option or with no operands, the
7595       built-in prints currently set traps to the standard output in a format
7596       that can be executed as commands that restore the current traps. If one
7597       or more signals are specified, only those signals are printed.
7598       Otherwise, all signals with non-default actions are printed. (In some
7599       situations, however, the built-in may print previous trap settings
7600       instead of the current. See notes below.)
7601
7602   Options
7603       -p, --print
7604           Print current trap settings.
7605
7606   Operands
7607       action
7608           An action that will be taken when signal is received.
7609
7610           If action is a single hyphen (-), the action is reset to the
7611           default action that is defined by the operating system. If action
7612           is an empty string, the signal is ignored on receipt. Otherwise,
7613           action is treated as a command string: the string is parsed and
7614           executed as commands when the signal is received. (If a signal is
7615           received while a command is being executed, the action is taken
7616           just after the command finishes.)
7617
7618       signal
7619           The number or name of a signal.
7620
7621           If signal is number 0 or name EXIT, it is treated as a special
7622           imaginary signal that is always received when the shell exits. The
7623           action set for this signal is taken when the shell exits normally.
7624
7625       signal_number
7626           This is like signal, but must be a number.
7627
7628   Exit status
7629       The exit status of the trap built-in is zero unless there is any error.
7630
7631   Notes
7632       The trap built-in is a special built-in.
7633
7634       The POSIX standard defines no options for the trap built-in; the
7635       built-in accepts no options in the POSIXly-correct mode.
7636
7637       The POSIX standard requires that signal names must be specified without
7638       the SIG-prefix, like INT and QUIT. As an extension, yash accepts
7639       SIG-prefixed names like SIGINT and SIGQUIT and treats signal names
7640       case-insensitively.
7641
7642       Reusing output of the built-in
7643           Output of the trap built-in can be saved in a variable, which can
7644           be later executed by the eval built-in to restore the traps.
7645
7646               saved_traps=$(trap)
7647               trap '...' INT
7648               eval "$saved_traps"
7649
7650           There are some tricks behind the scenes to allow this idiom. You
7651           use a command substitution to save the output of the trap built-in
7652           in the variable. The command substitution is executed in a
7653           subshell. The subshell resets all traps (except ignored ones) at
7654           the beginning of itself. This seemingly would result in (almost)
7655           empty output from the built-in that would fail to restore the traps
7656           as expected.
7657
7658           To avoid that pitfall, POSIX requires the shell to follow one of
7659           the two options below:
7660
7661           •   If a command substitution just contains a single trap built-in,
7662               traps should not be reset when the subshell is started to
7663               execute the built-in; or
7664
7665           •   A subshell always resets the traps but remembers the previous
7666               traps. If the trap built-in is executed in the subshell but no
7667               other trap built-in has been executed to modify traps in the
7668               subshell, then the built-in should print the remembered traps.
7669
7670           Yash obeys the second.
7671

TRUE BUILT-IN

7673       The true built-in does nothing successfully.
7674
7675   Syntax
7676true
7677
7678   Description
7679       The true built-in does nothing. Any command line arguments are ignored.
7680
7681   Exit status
7682       The exit status of the true built-in is zero.
7683
7684   Notes
7685       The true built-in is a semi-special built-in.
7686
7687       The true and colon built-ins have the same effect, but true is a
7688       semi-special built-in while colon is a special.
7689

TYPE BUILT-IN

7691       The type built-in identifies a command.
7692
7693   Syntax
7694type [-abefkp] [command...]
7695
7696   Description
7697       The type built-in is equivalent to the command built-in with the -V
7698       option.
7699
7700   Notes
7701       The POSIX standard does not define the relation between the type and
7702       command built-ins. The standard does not define options for the type
7703       built-in.
7704
7705       At least one command operand must be specified in the POSIXly-correct
7706       mode.
7707
7708       The type built-in is a semi-special built-in.
7709

TYPESET BUILT-IN

7711       The typeset built-in prints or sets variables or functions.
7712
7713   Syntax
7714typeset [-gprxX] [variable[=value]...]
7715
7716typeset -f[pr] [function...]
7717
7718   Description
7719       If executed without the -f (--functions) option, the typeset built-in
7720       prints or sets variables to the standard output. Otherwise, it prints
7721       or sets functions.
7722
7723       If executed with the -p (--print) option, the built-in prints the
7724       variables or functions specified by operands. Without the option, it
7725       sets variables or functions. If no operands are specified, it prints
7726       all existing variables or functions, regardless of whether the -p
7727       (--print) option is specified.
7728
7729   Options
7730       -f, --functions
7731           Print or set functions rather than variables.
7732
7733       -g, --global
7734           When setting a new variable, the variable will be a global variable
7735           if this option is specified. Without this option, the variable
7736           would be a local variable.
7737
7738           When printing variables, all existing variables including global
7739           variables are printed if this option is specified. Without this
7740           option, only local variables are printed.
7741
7742       -p, --print
7743           Print variables or functions in a form that can be parsed and
7744           executed as commands that will restore the currently set variables
7745           or functions.
7746
7747       -r, --readonly
7748           When setting variables or functions, make them read-only.
7749
7750           When printing variables or functions, print read-only variables or
7751           functions only.
7752
7753       -x, --export
7754           When setting variables, mark them for export, so that they will be
7755           exported to external commands.
7756
7757           When printing variables, print exported variables only.
7758
7759       -X, --unexport
7760           When setting variables, cancel exportation of the variables.
7761
7762   Operands
7763       variable (without value)
7764           The name of a variable that is to be set or printed.
7765
7766           Without the -p (--print) option, the variable is defined (if not
7767           yet defined) but its value is not set nor changed. Variables that
7768           are defined without values are treated as unset in parameter
7769           expansion.
7770
7771       variable=value
7772           The name of a variable and its new value.
7773
7774           The value is assigned to the variable (regardless of the -p
7775           (--print) option).
7776
7777       function
7778           The name of an existing function that is to be set or printed.
7779
7780   Exit status
7781       The exit status of the typeset built-in is zero unless there is any
7782       error.
7783
7784   Notes
7785       A global variable cannot be newly defined if a local variable has
7786       already been defined with the same name. The local variable will be set
7787       regardless of the -g (--global) option.
7788
7789       The typeset built-in is a semi-special built-in. In the POSIX standard,
7790       it is defined as a command with unspecified behavior.
7791
7792       The export and readonly built-ins are equivalent to the typeset
7793       built-in with the -gx and -gr options, respectively. The local built-in
7794       is equivalent to the typeset built-in except that the -f (--functions)
7795       and -g (--global) options cannot be used.
7796

ULIMIT BUILT-IN

7798       The ulimit built-in sets or prints a resource limit.
7799
7800   Syntax
7801ulimit -a [-H|-S]
7802
7803ulimit [-H|-S] [-efilnqrstuvx] [limit]
7804
7805   Description
7806       The ulimit built-in sets or prints a resource limit.
7807
7808       If executed with the -a (--all) option, the built-in prints the current
7809       limits for all resource types. Otherwise, it sets or prints the limit
7810       of a single resource type. The resource type can be specified by the
7811       options listed below. The resource limits will affect the current shell
7812       process and all commands invoked from the shell.
7813
7814       Each resource type has two limit values: the hard and soft limit. You
7815       can change a soft limit freely as long as it does not exceed the hard
7816       limit. You can decrease a hard limit but cannot increase it without a
7817       proper permission.
7818
7819       When the -H (--hard) or -S (--soft) option is specified, the built-in
7820       sets or prints the hard or soft limit, respectively. If neither of the
7821       options is specified, the built-in sets both the hard and soft limit or
7822       prints the soft limit.
7823
7824   Options
7825       -H, --hard
7826           Set or print a hard limit.
7827
7828       -S, --soft
7829           Set or print a soft limit.
7830
7831       -a, --all
7832           Print all current limit settings.
7833
7834       The following options specify the type of resources. If none of them is
7835       specified, -f is the default. The types of resources that can be set
7836       depend on the operating system.
7837
7838       -c, --core
7839           Maximum size of core files created (in 512-byte blocks)
7840
7841       -d, --data
7842           Maximum size of a process’s data segment (in kilobytes)
7843
7844       -e, --nice
7845           Maximum scheduling priority (‘nice’)
7846
7847       -f, --fsize
7848           Maximum size of files created by a process (in 512-byte blocks)
7849
7850       -i, --sigpending
7851           Maximum number of pending signals
7852
7853       -l, --memlock
7854           Maximum memory size that can be locked into RAM (in kilobytes)
7855
7856       -m, --rss
7857           Maximum size of a process’s resident set (in kilobytes)
7858
7859       -n, --nofile
7860           Maximum file descriptor + 1
7861
7862       -q, --msgqueue
7863           Maximum size of POSIX message queues
7864
7865       -r, --rtprio
7866           Maximum real-time scheduling priority
7867
7868       -s, --stack
7869           Maximum size of a process’s stack (in kilobytes)
7870
7871       -t, --cpu
7872           Maximum CPU time that can be used by a process (in seconds)
7873
7874       -u, --nproc
7875           Maximum number of processes for a user
7876
7877       -v, --as
7878           Maximum size of memory used by a process (in kilobytes)
7879
7880       -x, --locks
7881           Maximum number of file locks
7882
7883   Operands
7884       limit
7885           A limit to be set.
7886
7887           The value must be a non-negative integer or one of hard, soft, and
7888           unlimited. If value is hard or soft, the new limit is set to the
7889           current hard or soft limit. If limit is not specified, the current
7890           limit is printed.
7891
7892   Exit status
7893       The exit status of the ulimit built-in is zero unless there is any
7894       error.
7895
7896   Notes
7897       The POSIX standard defines no options other than -f. It neither defines
7898       hard, soft, or unlimited for limit values.
7899
7900       The ulimit built-in is a semi-special built-in.
7901

UMASK BUILT-IN

7903       The umask built-in sets or prints the file mode creation mask.
7904
7905   Syntax
7906umask mask
7907
7908umask [-S]
7909
7910   Description
7911       If executed without the mask operand, the built-in prints the current
7912       file mode creation mask of the shell to the standard output in a form
7913       that can later be used as mask to restore the current mask.
7914
7915       Otherwise, the built-in sets the file mode creation mask to mask.
7916
7917   Options
7918       -S, --symbolic
7919           Print in the symbolic form instead of the octal integer form.
7920
7921   Operands
7922       mask
7923           The new file mode creation mask either in the symbolic or octal
7924           integer form.
7925
7926       Octal integer form
7927           In the octal integer form, the mask is specified as a non-negative
7928           octal integer that is the sum of the following permissions:
7929
7930           0400
7931               read by owner
7932
7933           0200
7934               write by owner
7935
7936           0100
7937               execute/search by owner
7938
7939           0040
7940               read by group
7941
7942           0020
7943               write by group
7944
7945           0010
7946               execute/search by group
7947
7948           0004
7949               read by others
7950
7951           0002
7952               write by others
7953
7954           0001
7955               execute/search by others
7956
7957       Symbolic form
7958           In the symbolic form, the mask is specified as a symbolic
7959           expression that denotes permissions that are not included in the
7960           mask.
7961
7962           The entire expression is one or more clauses separated by comma. A
7963           clause is a sequence of whos followed by one or more actions.
7964
7965           A who is one of:
7966
7967           u
7968               owner
7969
7970           g
7971               group
7972
7973           o
7974               others
7975
7976           a
7977               all of owner, group, and others
7978
7979           An empty sequence of whos is equivalent to who a.
7980
7981           An action is an operator followed by permission. An operator is one
7982           of:
7983
7984           =
7985               set who's permission to permission
7986
7987           +
7988               add permission to who's permission
7989
7990           -
7991               remove permission from who's permission
7992
7993           and permission is one of:
7994
7995           r
7996               read
7997
7998           w
7999               write
8000
8001           x
8002               execute/search
8003
8004           X
8005               execute/search (only if some user already has execute/search
8006               permission)
8007
8008           s
8009               set-user-ID and set-group-ID
8010
8011           u
8012               user’s current permissions
8013
8014           g
8015               group’s current permissions
8016
8017           o
8018               others' current permissions
8019
8020           but more than one of r, w, x, X, and s can be specified after a
8021           single operand.
8022
8023           For example, the command umask u=rwx,go+r-w
8024
8025           •   unmasks the user’s read, write, and execute/search permissions;
8026
8027           •   unmasks the group’s and others' read permission; and
8028
8029           •   masks the group’s and others' write permission.
8030
8031   Exit status
8032       The exit status of the umask built-in is zero unless there is any
8033       error.
8034
8035   Notes
8036       The umask built-in is a semi-special built-in.
8037
8038       The POSIX standard does not require the default output format (used
8039       when the -S option is not specified) to be the octal integer form.
8040

UNALIAS BUILT-IN

8042       The unalias built-in undefines aliases.
8043
8044   Syntax
8045unalias name...
8046
8047unalias -a
8048
8049   Description
8050       The unalias built-in removes the definition of the aliases specified by
8051       operands.
8052
8053   Options
8054       -a, --all
8055           Undefine all aliases.
8056
8057   Operands
8058       name
8059           The name of an alias to be undefined.
8060
8061   Exit status
8062       The exit status of the unalias built-in is zero unless there is any
8063       error. It is an error to specify the name of a non-existing alias as
8064       name.
8065
8066   Notes
8067       The unalias built-in is a semi-special built-in.
8068

UNSET BUILT-IN

8070       The unset built-in undefines variables or functions.
8071
8072   Syntax
8073unset [-fv] [name...]
8074
8075   Description
8076       The unset built-in removes the definition of the variables or functions
8077       specified by operands.
8078
8079       It is not an error if any of the specified variables or functions do
8080       not exist; they are silently ignored.
8081
8082   Options
8083       -f, --functions
8084           Undefine functions.
8085
8086       -v, --variables
8087           Undefine variables.
8088
8089       These options are mutually exclusive: only the last specified one is
8090       effective. If neither is specified, -v is assumed.
8091
8092   Operands
8093       name
8094           The name of a variable or function to be undefined.
8095
8096   Exit status
8097       The exit status of the unset built-in is zero unless there is any
8098       error.
8099
8100   Notes
8101       The unset built-in is a special built-in.
8102
8103       Although yash does not do so, the POSIX standard allows removing a
8104       function if neither of the -f and -v options is specified and the
8105       specified variable does not exist.
8106
8107       At least one name operand must be specified in the POSIXly-correct
8108       mode.
8109

WAIT BUILT-IN

8111       The wait built-in waits for jobs to terminate.
8112
8113   Syntax
8114wait [job...]
8115
8116   Description
8117       The wait built-in waits for background jobs to terminate. If job
8118       control is enabled, stopped jobs are considered as terminated.
8119
8120       The built-in can be used to wait for asynchronous commands if job
8121       control is disabled.
8122
8123       If the shell receives a signal while the built-in is waiting and if a
8124       trap has been set for the signal, then the trap is executed and the
8125       built-in immediately finishes (without waiting for the jobs). If the
8126       shell receives a SIGINT signal when job control is enabled, the
8127       built-in aborts waiting.
8128
8129       If the shell is interactive, job-controlling, and not in the
8130       POSIXly-correct mode, the job status is printed when the job is
8131       terminated or stopped.
8132
8133   Operands
8134       job
8135           The job ID of the job or the process ID of a process in the job.
8136
8137       If no jobs are specified, the built-in waits for all existing jobs.
8138
8139       If the specified job does not exist, the job is considered to have
8140       terminated with the exit status of 127.
8141
8142   Exit status
8143       If no jobs were specified and the built-in successfully waited for all
8144       the jobs, the exit status is zero. If one or more jobs were specified,
8145       the exit status is that of the last job.
8146
8147       If the built-in was aborted by a signal, the exit status is an integer
8148       (> 128) that denotes the signal. If there was any other error, the exit
8149       status is between 1 and 126 (inclusive).
8150
8151   Notes
8152       The wait built-in is a semi-special built-in.
8153
8154       The process ID of the last process of a job can be obtained by the !
8155       special parameter. You can use the jobs built-in as well to obtain
8156       process IDs of job processes.
8157

AUTHOR

8159       Yuki Watanabe <magicant@users.osdn.me>
8160           Author.
8161
8162
8163
8164  2.52                            2021-10-11                           YASH(1)
Impressum