1YASH(1) YASH(1)
2
3
4
6 yash - a POSIX-compliant command line shell
7
9 yash [options...] [--] [operands...]
10
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
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
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
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
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
1122 • parameter is a special parameter,
1123
1124 • parameter is a positional parameter whose index is a one-digit
1125 integer, or
1126
1127 • parameter 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 It is an expansion error if the result of an expression is not defined
1466 in C.
1467
1468 Brace expansion
1469 Brace expansion expands to several split words with preceding and
1470 succeeding portions duplicated to each split words. Brace expansion is
1471 expanded only when the brace-expand option is enabled.
1472
1473 Comma-separated brace expansion
1474 {word1,word2,...,wordn}
1475
1476 Range brace expansion
1477 {start..end}
1478
1479 {start..end..delta}
1480
1481 Comma-separated brace expansion is expanded to each comma-separated
1482 word. For example, a{1,2,3}b is expanded to the three words a1b, a2b,
1483 and a3b.
1484
1485 Range brace expansion is expanded to integers in the range defined by
1486 start and end. The difference between each integer can be defined by
1487 delta. If start is larger than end, the results will be in descending
1488 order. When ..delta is omitted, it defaults to 1 or -1. For example,
1489 a{1..3}b is expanded to the three words a1b, a2b, and a3b; and
1490 a{1..7..2}b to the four words a1b, a3b, a5b, and a7b.
1491
1492 Multiple brace expansions can be used in one word. Brace expansions can
1493 also be nested. You can quote braces and/or commas to prevent them from
1494 being treated as brace expansion.
1495
1496 Any errors in brace expansion are silently ignored.
1497
1498 Field splitting
1499 In field splitting, words are split at predefined separators.
1500
1501 Field splitting can occur only within parts of words that resulted from
1502 parameter expansion, command substitution, and arithmetic expansion
1503 that are not between double-quotation marks. Expansion results of the @
1504 special parameter are exceptionally split even between double-quotation
1505 marks.
1506
1507 Separators used in field splitting are defined by the value of the IFS
1508 variable. If the variable does not exist, the value is assumed to be
1509 the three characters of space, tab, and newline.
1510
1511 Characters included in the value of the IFS variable are called IFS
1512 characters. IFS characters that are any of space, tab, and newline are
1513 called IFS whitespace and other IFS characters are called IFS
1514 non-whitespace.
1515
1516 Field splitting is performed as follows:
1517
1518 1. The shell searches words for split points. A split point is one or
1519 more adjacent IFS characters within the word portions where field
1520 splitting can occur. The following steps are taken for each split
1521 point found.
1522
1523 2. If the split point includes one or more IFS non-whitespaces, all
1524 the IFS whitespaces in the split point are ignored and the word is
1525 split at each IFS non-whitespace in the split point.
1526
1527 3. If the split point includes no IFS non-whitespaces, the word is
1528 split at the split point unless it is at the beginning or end of
1529 the word.
1530
1531 4. The split points are removed from the results.
1532
1533 Finally, the last word is removed from the results if:
1534
1535 • the empty-last-field option is not enabled;
1536
1537 • the result is more than one word; and
1538
1539 • the last word is empty.
1540
1541 Note
1542 Words are not split at all when the value of the IFS variable is
1543 empty.
1544
1545 Pathname expansion
1546 Pathname expansion performs pattern matching and expands to pathnames
1547 matched by the pattern.
1548
1549 A word subjected to pathname expansion is treated as a pattern. If one
1550 or more pathnames are found that are matched by the pattern, the
1551 pathnames become the results of the pathname expansion.
1552
1553 Pathname expansion is not performed when the glob option is disabled.
1554
1555 The shell searches readable directories for matching pathnames.
1556 Unreadable directories are silently ignored.
1557
1558 The following options affect the behavior of pathname expansion:
1559
1560 null-glob
1561 This option affects the result of pathname expansion when no
1562 matching pathnames are found. If enabled, the result is no word. If
1563 disabled, the result is the original pattern word.
1564
1565 case-glob
1566 This option specifies case-sensitivity in matching. If enabled,
1567 pattern matching is done case-sensitively.
1568
1569 dot-glob
1570 This option affects matching of filenames that start with a period
1571 (.). If disabled, a period at the beginning of a filename does not
1572 match wildcard patterns (? and *) or bracket expressions. If
1573 enabled, there is no such special treatment of periods.
1574
1575 mark-dirs
1576 If enabled, each resulting pathname that is a directory name is
1577 suffixed by a slash (/).
1578
1579 extended-glob
1580 This option enables the extension. (See below)
1581
1582 Any errors in pathname expansion are silently ignored. If the word is
1583 an invalid pattern, it just becomes the result. The results depend on
1584 the null-glob option when no matching pathnames are found.
1585
1586 Pattern matching is done for each filename (or pathname component) of
1587 pathnames. The shell skips matching for literal patterns that contain
1588 no wildcards or bracket expressions. As a result, the patterns /*/foo
1589 and /*/fo[o] may yield different expansion results when the case-glob
1590 option is disabled; for example, the pattern /*/fo[o] matches the
1591 pathname /bar/FOO but the pattern /*/foo does not because matching is
1592 skipped for foo.
1593
1594 Extension in pathname expansion
1595 The following patterns can be used when the extended-glob option is
1596 enabled.
1597
1598 **
1599 The directory is searched recursively and the pattern matches
1600 any number of directory filenames (each separated by a slash).
1601 Any directory whose name begins with a period is excluded from
1602 search. For example, the pattern dir/**/file can match the
1603 pathnames dir/file, dir/foo/file, dir/a/b/c/file, etc.
1604
1605 This pattern is not effective when appearing at the end of the
1606 whole pattern (i.e. foo/bar/**).
1607
1608 .**
1609 This pattern is like **, but all directories are searched
1610 including ones with a name starting with a period.
1611
1612 ***
1613 This pattern is like **, but if a symbolic link to a directory
1614 is found during recursive search, the directory is searched
1615 recursively as well.
1616
1617 .***
1618 This pattern is like ***, but all directories are searched
1619 including ones with a name starting with a period.
1620
1622 Pattern matching notation is a syntax of patterns that represent
1623 particular sets of strings. When a string is included in the set of
1624 strings a pattern represents, the pattern is said to match the string.
1625 Whether a pattern matches a string or not is defined as follows.
1626
1627 Normal characters
1628 A character that is not quoted or any of special characters defined
1629 below is a normal character, which matches the character itself.
1630
1631 For example, the pattern abc matches the string abc, and not any other
1632 strings.
1633
1634 Single-character wildcard
1635 The character ? matches any single character.
1636
1637 For example, the pattern a?c matches any three-character strings that
1638 starts with a and ends with c, such as aac, abc, and a;c.
1639
1640 Multi-character wildcard
1641 The character * matches any strings (of any length, including the empty
1642 string).
1643
1644 For example, the pattern a*c matches any string that starts with a and
1645 ends with c, such as ac, abc, and a;xyz;c.
1646
1647 Bracket expression
1648 A pattern that is enclosed by brackets ([ and ]) is a bracket
1649 expression. A bracket expression must have at least one character
1650 between the brackets. The characters between the brackets are
1651 interpreted as a bracket expression pattern, which is a below-defined
1652 special notation for bracket expression. A bracket expression pattern
1653 represents a set of characters. The bracket expression matches any one
1654 of the characters in the set the bracket expression pattern represents.
1655
1656 If the opening bracket ([) is followed by an exclamation mark (!), the
1657 exclamation is not treated as part of the bracket expression pattern
1658 and the whole bracket expression instead matches a character that is
1659 not included in the set the bracket expression pattern represents. If
1660 the opening bracket is followed by a caret (^), it is treated like an
1661 exclamation mark as above (but shells other than yash may treat the
1662 caret differently).
1663
1664 If the opening bracket (or the following exclamation or caret, if any)
1665 is followed by a closing bracket (]), it is treated as part of the
1666 bracket expression pattern rather than the end of the bracket
1667 expression. You cannot quote characters in the bracket expression
1668 pattern because quotation is treated before bracket expression.
1669
1670 An opening bracket in a pattern is treated as a normal character if it
1671 is not the beginning of a valid bracket expression.
1672
1673 Normal characters (in bracket expression pattern)
1674 A character that is not any of special characters defined below is a
1675 normal character, which represents the character itself.
1676
1677 For example, the bracket expression pattern abc represents the set of
1678 the three characters a, b, and c. The bracket expression [abc]
1679 therefore matches any of the three characters.
1680
1681 Range expressions
1682 A hyphen preceded and followed by a character (or collating symbol) is
1683 a range expression, which represents the set of the two characters and
1684 all characters between the two in the collation order. A collation
1685 order is an order of characters that is defined in the locale data.
1686
1687 If a hyphen is followed by a closing bracket (]), the bracket is
1688 treated as the end of the bracket expression and the hyphen as a normal
1689 character.
1690
1691 For example, the range expression 3-5 represents the set of the three
1692 characters 3, 4, and 5. The bracket expression [3-5-] therefore matches
1693 one of the four characters 3, 4, 5, and -.
1694
1695 Collating symbols
1696 A collating symbol allows more than one character to be treated as a
1697 single character in matching. A collating symbol is made up of one or
1698 more characters enclosed by the special brackets [. and .].
1699
1700 One or more characters that are treated as a single character in
1701 matching are called a collating element. Precisely, a bracket
1702 expression pattern represents a set of collating elements and a bracket
1703 expression matches a collating element rather than a character, but we
1704 do not differentiate them for brevity here.
1705
1706 For example, the character combination “ch” was treated as a single
1707 character in the traditional Spanish language. If this character
1708 combination is registered as a collating element in the locale data,
1709 the bracket expression [[.ch.]df] matches one of ch, d, and f.
1710
1711 Equivalence classes
1712 An equivalence class represents a set of characters that are considered
1713 equivalent. A equivalence class is made up of a character (or more
1714 precisely, a collating element) enclosed by the special brackets [= and
1715 =].
1716
1717 An equivalence class represents the set of characters that consists of
1718 the character enclosed by the brackets and the characters that are in
1719 the same primary equivalence class as the enclosed character. The shell
1720 consults the locale data for the definition of equivalence classes in
1721 the current locale.
1722
1723 For example, if the six characters a, à, á, â, ã, ä are defined to be
1724 in the same primary equivalence class, the bracket expressions [[=a=]],
1725 [[=à=]], and [[=á=]] match one of the six.
1726
1727 Character classes
1728 A character class represents a predefined set of characters. A
1729 character class is made up of a class name enclosed by the special
1730 brackets [: and :]. The shell consults the locale data for which class
1731 a character belongs to.
1732
1733 The following character classes can be used in all locales:
1734
1735 [:lower:]
1736 set of lowercase letters
1737
1738 [:upper:]
1739 set of uppercase letters
1740
1741 [:alpha:]
1742 set of letters, including the [:lower:] and [:upper:] classes.
1743
1744 [:digit:]
1745 set of decimal digits
1746
1747 [:xdigit:]
1748 set of hexadecimal digits
1749
1750 [:alnum:]
1751 set of letters and digits, including the [:alpha:] and [:digit:]
1752 classes.
1753
1754 [:blank:]
1755 set of blank characters, not including the newline character
1756
1757 [:space:]
1758 set of space characters, including the newline character
1759
1760 [:punct:]
1761 set of punctuations
1762
1763 [:print:]
1764 set of printable characters
1765
1766 [:cntrl:]
1767 set of control characters
1768
1769 For example, the bracket expression [[:lower:][:upper:]] matches a
1770 lower or upper case character. In addition to the classes listed above,
1771 other classes may be used depending on the definition of the current
1772 locale.
1773
1775 Redirection is a feature you can use to modify file descriptors of
1776 commands. By using redirection, you can execute commands with their
1777 standard input/output connected with files or devices other than the
1778 terminal.
1779
1780 You can do redirection by adding redirection operators to a command
1781 (simple command or compound command) In a simple command, redirection
1782 operators may appear anywhere in the command as long as operator tokens
1783 are separated from other tokens. In a compound command, redirection
1784 operators must appear at the end of the command.
1785
1786 Redirection operators are processed before the command body is
1787 executed. More than one redirection operator in a command are processed
1788 in the order of appearance. Redirection operators affect only the
1789 command in which they appear, except when they appear in an exec
1790 built-in without command operands. That is, file descriptors modified
1791 by redirection are restored after the command has finished.
1792
1793 A redirection operator starts with < or >. Redirection operators
1794 starting with < affects the standard input (file descriptor 0) by
1795 default. Redirection operators starting with > affects the standard
1796 output (file descriptor 1) by default. To affect another file
1797 descriptor, you can prefix a redirection operator with a non-negative
1798 integer; the operator will affect the file descriptor specified by the
1799 integer. The integer must immediately precede the < or > without any
1800 whitespaces in between. The integer must not be quoted, either.
1801
1802 Redirection to files
1803 The most common type of redirection is redirection to files.
1804
1805 Redirection of input
1806 < token
1807
1808 Redirection of output
1809 > token
1810
1811 >| token
1812
1813 >> token
1814
1815 Redirection of input and output
1816 <> token
1817
1818 The token is subject to the four expansions. It is also subject to
1819 pathname expansion if the shell is interactive. The expansion result is
1820 treated as the pathname of the file to which redirection is performed.
1821 If the pathname expansion does not result in a single pathname, it is
1822 an error.
1823
1824 In redirection of input, the standard input is replaced with a file
1825 descriptor which is open for read-only access to the target file. If
1826 the target file cannot be opened for read-only access, it is an error.
1827
1828 In redirection of output, the standard output is replaced with a file
1829 descriptor which is open for write-only access to the target file. If
1830 the target file cannot be opened for write-only access, it is an error.
1831 If the target file does not exist, a new empty file is created and
1832 opened. If the target file already exists, the file is opened as
1833 follows:
1834
1835 • For the >| operator, the file is emptied when opened if it is a
1836 regular file.
1837
1838 • For the > operator, the behavior is the same as the >| operator if
1839 the clobber option is enabled. If the option is disabled and the
1840 file is a regular file, it is treated as an error.
1841
1842 • For the >> operator, the file is opened for appending; any output
1843 to the file descriptor is appended to the end of the file.
1844
1845 In redirection of input and output, the standard input is replaced with
1846 a file descriptor which is open for read-and-write access to the target
1847 file. If the file does not exist, a new empty file is created and
1848 opened.
1849
1850 Socket redirection
1851 If the pathname of the target file is of the form
1852 /dev/tcp/host/port or /dev/udp/host/port and the file cannot be
1853 opened in the usual manner, a new socket is opened for
1854 communication with the port of the host. The redirection replaces
1855 the standard input or output with the file descriptor to the
1856 socket.
1857
1858 A stream socket is opened for the form /dev/tcp/host/port and a
1859 datagram socket for the form /dev/udp/host/port. The protocol
1860 actually used for communication is determined by the socket library
1861 the shell uses. Typically, stream sockets use TCP and datagram
1862 sockets UDP.
1863
1864 In socket redirection, the file descriptor is both readable and
1865 writable regardless of the type of the redirection operator used.
1866
1867 Socket redirection is yash’s extension that is not defined in
1868 POSIX. Bash as well has socket redirection as extension.
1869
1870 Duplication of file descriptors
1871 Redirection allows duplicating or closing existing file descriptors.
1872
1873 Duplication of file descriptor
1874 <& token
1875
1876 >& token
1877
1878 The token is subject to expansion as in redirection to files, but it is
1879 treated as a file descriptor rather than a pathname. Thus the expanded
1880 token must be a non-negative integer.
1881
1882 The <& and >& operators duplicate the file descriptor specified by
1883 token to the standard input and output, respectively. (The operators
1884 can be prefixed with a non-negative integer so that the file descriptor
1885 is duplicated to a file descriptor other than the standard input or
1886 output.)
1887
1888 If the expanded token is a single hyphen rather than a non-negative
1889 integer, the file descriptor is closed rather than duplicated. By
1890 default, the <& and >& operators close the standard input and output,
1891 respectively, but the operators can be prefixed with a non-negative
1892 integer so that another file descriptor is closed.
1893
1894 In the POSIXly-correct mode, a file descriptor must be readable when
1895 duplicated by the <& operator and writable when duplicated by the >&
1896 operator.
1897
1898 Here documents and here strings
1899 Here document and here string allow redirection to file descriptors
1900 that reads strings directly specified in shell commands.
1901
1902 Here document
1903 << token
1904
1905 <<- token
1906
1907 Here string
1908 <<< token
1909
1910 In a here document or here string, the standard input is replaced with
1911 a readable file descriptor. When the command reads from the file
1912 descriptor, it will read the contents of the here document/string,
1913 which is defined below.
1914
1915 When a here document operator (<< or <<-) appears in a command, the
1916 shell reads the contents of the here document starting from the next
1917 line. The contents of here documents are not parsed nor executed as
1918 commands. The token after the operand specifies a delimiter that
1919 indicates the end of the contents. (The token is not subject to any
1920 expansion, but quotation is processed.) The contents of the here
1921 document is terminated just before the first line containing the token
1922 only. When using the <<- operator, all tab characters at the beginning
1923 of each line in the here document contents are removed and the
1924 delimiter token may be preceded by tab characters.
1925
1926 If there are more than one here document operator on one line, the
1927 contents of the here documents are parsed in order: The contents of the
1928 first here document starts from the next line and ends before the first
1929 line containing the token that followed the first operator. Just after
1930 that line, the contents of the second here document starts, and so on.
1931
1932 The contents of here documents are treated literally: whitespaces,
1933 tabs, etc. remain as is. The exception is that, when the token is not
1934 quoted at all:
1935
1936 • the contents are subject to parameter expansion, command
1937 substitution, arithmetic expansion.
1938
1939 • a backslash in the contents is treated as quotation if and only if
1940 it precedes $, `, ", or another backslash.
1941
1942 • a backslash followed by a newline is treated as line continuation.
1943
1944 In here string, the token after the operator is subject to expansion as
1945 in redirection to files. The expansion result becomes the contents of
1946 the here string. A newline character is automatically appended to the
1947 end of here string contents.
1948
1949 Here string is yash’s extension that is not defined in POSIX. Other
1950 shells like bash, ksh, and zsh have the same feature.
1951
1952 Pipeline redirection
1953 Pipeline redirection allows opening pipelines that can be used for
1954 arbitrary purposes.
1955
1956 Pipeline redirection
1957 >>| token
1958
1959 The token is subject to expansion as in redirection to files, but it is
1960 treated as a file descriptor rather than a pathname. Thus the expanded
1961 token must be a non-negative integer.
1962
1963 Pipeline redirection opens a new pipeline. The standard output (or the
1964 file descriptor specified before the operator, if any) is replaced with
1965 the file descriptor open for writing to the pipeline. The file
1966 descriptor specified by token is replaced with the file descriptor open
1967 for reading from the pipeline.
1968
1969 Pipeline redirection is yash’s extension that is not defined in POSIX.
1970
1971 Process redirection
1972 Process redirection creates a pipeline connected to another command.
1973
1974 Process redirection
1975 <(command...)
1976
1977 >(command...)
1978
1979 In process redirection, the command specified is executed in a
1980 subshell. If the process redirection is of the form <(command...), the
1981 standard output of command is connected with a pipeline to the standard
1982 input of the command the redirection is associated with. If the process
1983 redirection is of the form >(command...), the standard input of command
1984 is connected with a pipeline to the standard output of the command the
1985 redirection is associated with.
1986
1987 Process redirection is yash’s extension that is not defined in POSIX.
1988 Bash and zsh have a feature called process substitution, which uses the
1989 same syntax as yash’s process redirection, but incompatibly differs in
1990 behavior.
1991
1993 This section describes how commands are executed.
1994
1995 Execution of simple commands
1996 A simple command is executed as follows:
1997
1998 1. All tokens in the simple command are expanded except for assignment
1999 and redirection tokens. If an error occurs during expansion, the
2000 execution of the simple command is aborted with a non-zero exit
2001 status.
2002
2003 In the following steps, the first word of the expansion results is
2004 referred to as command name, and the other words as command
2005 arguments. If there is only one word of the expansion results,
2006 there are no command argument words. If there are none of the
2007 expansion results, there is no command name either.
2008
2009 2. If the command name exists and there are any redirections specified
2010 in the command, they are processed. The word token after each
2011 redirection operator is expanded. If an error occurs during
2012 processing the redirections (including when expanding the word
2013 token), the execution of this simple command is aborted with a
2014 non-zero exit status.
2015
2016 Note
2017 In other shells, redirections may be processed in a different
2018 step: POSIX does not specify the order in which redirections
2019 and assignments are processed when there is no command name or
2020 the name denotes a special built-in.
2021
2022 3. Assignments specified in the command, if any, are processed. For
2023 each assignment token, the value is expanded and assigned to the
2024 specified variable. If an error occurs during assignments
2025 (including when expanding the values to be assigned), the execution
2026 of this simple command is aborted with a non-zero exit status.
2027
2028 • If there is no command name or the name denotes a special
2029 built-in, the assignments are permanent: the assigned values
2030 remain after the command has finished (until the variable is
2031 reassigned).
2032
2033 • Otherwise, the assignments are temporary: the assigned values
2034 only last during the execution of this simple command.
2035
2036 The assigned variables are automatically exported when the command
2037 name is specified or the all-export option is enabled.
2038
2039 Note
2040 In other shells, assignments may behave differently: For
2041 special built-ins and functions, assigned variables may not be
2042 exported. For functions, assigned variables may be persistent,
2043 that is, may remain even after the execution of the simple
2044 command.
2045
2046 4. If there is no command name, the redirections are processed in a
2047 subshell, then the command execution ends. If an error occurs in
2048 the redirections, the exit status of the simple command is
2049 non-zero. If there were any command substitutions performed in the
2050 assignments, the exit status of the simple command is that of the
2051 last executed command substitution. Otherwise, the exit status is
2052 zero.
2053
2054 5. A command to be executed is determined using the command search
2055 algorithm and the command is executed.
2056
2057 • If the command is an external command, the command is executed
2058 by creating a new subshell and calling the “exec” system call
2059 in the subshell. The command name and arguments are passed to
2060 the executed command. Exported variables are passed to the
2061 executed command as environment variables.
2062
2063 • If the command is a built-in, the built-in is executed with the
2064 command arguments passed to the built-in.
2065
2066 • If the command is a function, the contents of the function are
2067 executed with the command arguments as function arguments.
2068
2069 If the command was executed, the exit status of this simple command
2070 is that of the executed command. If the algorithm failed to
2071 determine a command, no command is executed and the exit status is
2072 127. If the shell failed to execute the determined command, the
2073 exit status is 126. If the executed command was killed by a signal,
2074 the exit status is the signal number plus 384.
2075
2076 Note
2077 In shells other than yash, the exit status may be different
2078 when the command was killed by a signal, because the POSIX
2079 standard only requires that the exit status be "greater than
2080 128."
2081 If the shell is not in the POSIXly-correct mode and the algorithm
2082 failed to determine a command, the command eval -i --
2083 "${COMMAND_NOT_FOUND_HANDLER-}" is evaluated. During the command
2084 execution, positional parameters are temporarily set to the command
2085 name and arguments that resulted in the first step. Any local
2086 variables defined during the execution are removed when the
2087 execution is finished. The HANDLED local variable is automatically
2088 defined with the initial value being the empty string. If the
2089 HANDLED variable has a non-empty value when the execution of the
2090 command string is finished, the shell pretends that the command was
2091 successfully determined and executed. The exit status of the simple
2092 command is that of the command string in this case.
2093
2094 Command search
2095 A command that is executed in a simple command is determined by the
2096 command name using the following algorithm:
2097
2098 1. If the command name contains a slash (/), the whole name is
2099 treated as the pathname of an external command. The external
2100 command is determined as the executed command.
2101
2102 2. If the command name is a special built-in, the built-in is
2103 determined as the executed command.
2104
2105 3. If the command name is the name of an existing function, the
2106 function is determined as the executed command.
2107
2108 4. If the command name is a semi-special built-in, the built-in is
2109 determined as the executed command.
2110
2111 5. If the command name is a regular built-in, the built-in is
2112 determined as the executed command unless the shell is in the
2113 POSIXly-correct mode.
2114
2115 6. The shell searches the PATH for a executed command:
2116
2117 The value of the PATH variable is separated by colons. Each
2118 separated part is considered as a directory pathname (an empty
2119 pathname denotes the current working directory). The shell
2120 searches the directories (in the order of appearance) and
2121 checks if any directory directly contains an executable regular
2122 file whose name is equal to the command name. If such a file is
2123 found:
2124
2125 • If the command name is the name of a built-in, the built-in
2126 is determined as the executed command.
2127
2128 • Otherwise, the file is determined as the executed command.
2129 (The file will be executed as an external command.)
2130
2131 If no such file is found, no command is determined as the
2132 executed command.
2133
2134 When the shell finds a file that matches the command name during
2135 the search above, the shell remembers the pathname of the file if
2136 it is an absolute path. When the algorithm above is used for the
2137 same command name again, the shell skips searching and directly
2138 determines the command to be executed. If an executable regular
2139 file no longer exists at the remembered pathname, however, the
2140 shell searches again to update the remembered pathname. You can
2141 manage remembered pathnames using the hash built-in.
2142
2143 Termination of the shell
2144 The shell exits when it reached the end of input and has parsed and
2145 executed all input commands or when the exit built-in is executed. The
2146 exit status of the shell is that of the last command the shell executed
2147 (or zero if no commands were executed). The exit status of the shell is
2148 always between 0 and 255 (inclusive). If the exit status of the last
2149 command is 256 or larger, the exit status of the shell will be the
2150 remainder of the exit status divided by 256.
2151
2152 If an exit handler has been registered by the trap built-in, the
2153 handler is executed just before the shell exits. The exit status of the
2154 commands executed in the handler does not affect the exit status of the
2155 shell.
2156
2157 If a non-interactive shell encountered one of the following errors, the
2158 shell immediately exits with a non-zero exit status:
2159
2160 • A command cannot be parsed due to an syntax error (except during
2161 shell initialization).
2162
2163 • An error occurs during execution of a special built-in in the
2164 POSIXly-correct mode.
2165
2166 • A redirection error occurs in a simple command whose command name
2167 is a special built-in and the shell is in the POSIXly-correct mode.
2168
2169 • An assignment error occurs in a simple command.
2170
2171 • An error occurs during expansion (except during shell
2172 initialization).
2173
2174 Note
2175 Some shells other than yash exit when they fail to find a command
2176 to execute in command search.
2177
2178 Functions
2179 Functions allow executing a compound command as a simple command. A
2180 function can be defined by the function definition command and executed
2181 by a simple command. You can use the unset built-in to remove function
2182 definitions.
2183
2184 There are no functions predefined when yash is started.
2185
2186 A function is executed by executing its body, which is a compound
2187 command. While the function is being executed, positional parameters
2188 are set to the arguments given to the function. The old positional
2189 parameters are restored when the function execution finishes.
2190
2191 Local variables
2192 Local variables are temporary variables that are defined in a
2193 function and exist during the function execution only. They can be
2194 defined by the typeset built-in or implicitly created by a for
2195 loop. They are removed when the function execution finishes.
2196
2197 Local variables may hide variables that have already been defined
2198 before the function execution had started. An existing variable
2199 becomes inaccessible if a local variable of the same name is
2200 defined in a function. The old variable becomes accessible again
2201 when the function execution finishes.
2202
2203 You cannot create a local variable when not executing a function. A
2204 normal variable is created if you try to do so.
2205
2206 Command execution environment
2207 The shell holds following properties during execution.
2208
2209 • The working directory
2210
2211 • Open file descriptors
2212
2213 • The file creation mask (umask)
2214
2215 • The set of signals whose handler is set to “ignore” (trap)
2216
2217 • Environment variables
2218
2219 • Resource limits (ulimit)
2220
2221 Those properties are inherited from the invoker of the shell to the
2222 shell, and from the shell to each external command executed by the
2223 shell.
2224
2225 The properties can be changed during the execution of the shell by
2226 built-in commands, variable assignments, etc.
2227
2228 Subshells
2229 A subshell is a copy of the shell process. Subshells are used in
2230 execution of groupings, pipelines, etc.
2231
2232 Subshells inherit functions, aliases, etc. defined in the shell as
2233 well as the properties above since subshells are copies of the
2234 shell process. Notable exceptions are:
2235
2236 • Traps registered by the trap built-in are all reset in
2237 subshells except for ones whose action is set to “ignore”. (See
2238 below)
2239
2240 • The interactive mode and job control are disabled in subshells.
2241 Jobs are not inherited by subshells.
2242
2243 Subshells are executed independently of the original shell, so
2244 changes of any properties above do not affect those of the original
2245 shell.
2246
2247 Note
2248 If the subshell contains a single trap built-in, some shells
2249 (but not yash) may not reset the traps on entry to the
2250 subshell.
2251
2253 The interactive mode is a mode of the shell intended for direct
2254 interaction with a user. If yash is in the interactive mode, it is
2255 called an interactive shell.
2256
2257 Whether a shell runs in the interactive mode or not is determined in
2258 the invocation of the shell. After the shell has started up, the
2259 interactive mode cannot be switched on or off.
2260
2261 When the shell is interactive:
2262
2263 • Initialization scripts are executed during invocation.
2264
2265 • The shell checks for mail and prints a command prompt when it reads
2266 a command. Job status changes are also reported if job control is
2267 active. Line-editing may be used depending on the capability of
2268 the terminal.
2269
2270 • Commands executed are automatically registered in command history.
2271
2272 • If a command executed by the shell is killed by a signal other than
2273 SIGINT and SIGPIPE, the shell reports the fact to the standard
2274 error.
2275
2276 • The filename token is subject to pathname expansion in file
2277 redirection.
2278
2279 • The shell does not exit when it encounters a syntax or expansion
2280 error during command execution. (cf. Termination of the shell)
2281
2282 • The shell does not exit when it receives the SIGINT, SIGTERM, or
2283 SIGQUIT signal.
2284
2285 • A signal handler can be changed by the trap built-in even if the
2286 handler had been set to “ignore” when the shell was invoked.
2287
2288 • The value of the - special parameter contains i.
2289
2290 • The shell’s locale reflects the value of the LC_CTYPE variable
2291 whenever the value is changed (if the shell is not in the
2292 POSIXly-correct mode).
2293
2294 • Commands are executed even when the exec option is off.
2295
2296 • The ignore-eof option takes effect when enabled.
2297
2298 • When the shell reaches the end of input or the exit built-in is
2299 executed, the shell checks if there is any stopped job. If so, the
2300 shell prints a warning and does not actually exit.
2301
2302 • The suspend built-in by default cannot stop the shell if it is a
2303 session leader.
2304
2305 • The shell does not exit when the dot built-in fails to find a
2306 script file to read.
2307
2308 • The shell does not exit when the exec built-in fails to execute a
2309 command (if not in the POSIXly-correct mode).
2310
2311 • When a job finished for which the wait built-in has been waiting,
2312 the fact is reported (only if job control is active and not in the
2313 POSIXly-correct mode).
2314
2315 • A prompt is printed when the read built-in reads a second or
2316 following line.
2317
2318 Prompts
2319 The interactive shell prints a prompt just before it reads a command.
2320 The contents of the prompt is specified by the value of the PS1 and PS2
2321 variables. The former is used for reading the first line of the command
2322 and the latter for other lines.
2323
2324 When the prompt is printed, the variable value is subjected to
2325 parameter expansion, command substitution, and arithmetic expansion
2326 (but note that the POSIX standard requires parameter expansion only).
2327 The result of the expansion is parsed by the rules below to make the
2328 actual prompt string, which is printed to the standard error.
2329
2330 In the POSIXly-correct mode, each exclamation mark (!) in the string is
2331 substituted with the command history number of the command that is
2332 being input. Two adjacent exclamation marks (!!) are printed as a
2333 single exclamation. Other characters are printed intact.
2334
2335 If the shell is not in the POSIXly-command mode, the following
2336 notations can be used to format the prompt string. Notations are
2337 replaced with the strings designated in the list below. Characters that
2338 are not interpreted as notations are printed intact.
2339
2340 \a
2341 Bell character (ASCII code: 7)
2342
2343 \e
2344 Escape character (ASCII code: 27)
2345
2346 \j
2347 The number of jobs in the shell.
2348
2349 \n
2350 Newline character (ASCII code: 10)
2351
2352 \r
2353 Carriage return character (ASCII code: 13)
2354
2355 \!
2356 The command history number of the command that is being input
2357
2358 \$
2359 # if the shell’s effective user ID is 0; $ otherwise.
2360
2361 \\
2362 Backslash
2363
2364 \[, \]
2365 These two notations can surround part of the prompt string that is
2366 not visible on the terminal. The surrounded part is ignored when
2367 the shell counts the number of characters that is displayed on the
2368 terminal, thus making characters correctly aligned on the terminal
2369 when the prompt string contains special invisible characters.
2370
2371 \ffontspecs.
2372 When line-editing is active, this notation is replaced with special
2373 characters to change font styles on the terminal if the terminal is
2374 capable of it. If line-editing is inactive or the terminal is
2375 incapable of changing font styles, this notation is silently
2376 ignored. One or more of the following can be used for fontspecs:
2377
2378 k
2379 Change font color to black
2380
2381 r
2382 Change font color to red
2383
2384 g
2385 Change font color to green
2386
2387 y
2388 Change font color to yellow
2389
2390 b
2391 Change font color to blue
2392
2393 m
2394 Change font color to magenta
2395
2396 c
2397 Change font color to cyan
2398
2399 w
2400 Change font color to white
2401
2402 K
2403 Change background color to black
2404
2405 R
2406 Change background color to red
2407
2408 G
2409 Change background color to green
2410
2411 Y
2412 Change background color to yellow
2413
2414 B
2415 Change background color to blue
2416
2417 M
2418 Change background color to magenta
2419
2420 C
2421 Change background color to cyan
2422
2423 W
2424 Change background color to white
2425
2426 t
2427 Make font color or background brighter (can only be used just
2428 after one of the characters above)
2429
2430 d
2431 Change font and background colors to normal
2432
2433 s
2434 Make font standout
2435
2436 u
2437 Make font underlined
2438
2439 v
2440 Make font and background colors reversed
2441
2442 b
2443 Make font blink
2444
2445 i
2446 Make font dim
2447
2448 o
2449 Make font bold
2450
2451 x
2452 Make font invisible
2453
2454 D
2455 Make color and style normal
2456
2457 The actual colors of font and background are defined by the
2458 terminal. Different terminals may use different colors.
2459
2460 In addition to the normal prompt, a prompt string can be displayed to
2461 the right of the cursor if line-editing is active. Those prompts are
2462 called right prompts. The contents of right prompts are defined by the
2463 value of the PS1R and PS2R variables, each corresponding to the PS1 and
2464 PS2 variables.
2465
2466 Using the above-said notations, the font style of command strings the
2467 user inputs can be changed as well as that of prompts. The font style
2468 of command strings is defined by the value of the PS1S and PS2S
2469 variables, each corresponding to the PS1 and PS2 variables. The value
2470 can contain the \ffontspecs. notation only.
2471
2472 When the shell is not in the POSIXly-correct mode, the prompt variables
2473 can be defined with a name prefixed with YASH_ (e.g. YASH_PS1). This
2474 allows using a different prompt string than that in the POSIXly-correct
2475 mode.
2476
2477 When the shell is not in the POSIXly-correct mode, the value of the
2478 PROMPT_COMMAND variable is executed before each prompt.
2479
2480 Command history
2481 Command history is a feature of the shell that remembers executed
2482 commands to allow re-executing them later. Commands executed in the
2483 interactive mode are automatically saved in the command history. Saved
2484 commands can be edited and re-executed using line-editing and the fc
2485 and history built-ins.
2486
2487 Commands are saved line by line. Lines that do not contain any
2488 non-whitespace characters are not saved in the history. Lines that
2489 start with whitespaces are not saved when the hist-space option is on.
2490
2491 Command history is saved in a file. When history is first used after an
2492 interactive shell was started, the shell opens a file to save history
2493 in. The filename is specified by the value of the HISTFILE variable. If
2494 the file contains history data when opened, the data is restored to the
2495 shell’s history. The file contents are updated in real time as the user
2496 inputs commands into the shell. If the HISTFILE variable is not set or
2497 the file cannot be opened successfully, history is not saved in the
2498 file, but the history feature will be functional in all other respects.
2499
2500 The number of commands saved in history is specified by the value of
2501 the HISTSIZE variable. The shell automatically removes old history data
2502 so that the number of saved commands does not exceed the value. If the
2503 HISTSIZE variable is not set or its value is not a natural number, 500
2504 items will be saved in history.
2505
2506 The shell looks at the value of the HISTFILE and HISTSIZE variables
2507 only when the history feature is first used after the shell was
2508 started. “The history feature is used” when:
2509
2510 • the fc or history built-in is executed,
2511
2512 • line-editing is used (regardless of whether or not history data is
2513 recalled in line-editing), or
2514
2515 • a command is input to the shell
2516
2517 Therefore, the variables should be set in initialization scripts.
2518
2519 When more than one instance of yash shares a single history file, all
2520 the shells use the same history data. As a result, commands that have
2521 been executed by a shell instance can be recalled on another shell
2522 instance. Shells sharing the same history should have the same HISTSIZE
2523 value so that they manipulate history data properly.
2524
2525 Yash’s history data file has its own format that is incompatible with
2526 other kinds of shells.
2527
2528 The HISTRMDUP variable can be set to remove duplicate history items.
2529
2530 Mail checking
2531 An interactive shell can notify receipt of email. The shell
2532 periodically checks the modification date/time of a file specified by
2533 the user. If the file has been modified since the previous check, the
2534 shell prints a notification message (except when the shell is not in
2535 the POSIXly-correct mode and the file is empty). By specifying a
2536 mailbox file to be checked, the shell will print a message when the
2537 file has been modified, that is, some mail has been received.
2538
2539 Check is done just before the shell prints a command line prompt. The
2540 interval of checks can be specified by the MAILCHECK variable in
2541 seconds. If the variable value is 0, check is done before every prompt.
2542 If the variable value is not a non-negative integer, no checks are
2543 done.
2544
2545 The file whose modification time is checked is specified by the MAIL
2546 variable. The variable value should be set to the pathname of the file.
2547
2548 If you want to check more than one file or customize the notification
2549 message, you can set the MAILPATH variable instead of the MAIL
2550 variable. When the MAILPATH variable is set, the MAIL variable is
2551 ignored. The value of the MAILPATH variable should be set to one or
2552 more colon-separated pathnames of files to be checked. Each pathname
2553 can be followed by a percent sign (%) and a custom notification
2554 message, which is printed when the corresponding file has been
2555 modified. If the pathname contains a percent sign, it should be quoted
2556 by a backslash. The specified message is subject to parameter
2557 expansion. For example, if the value of the MAILPATH variable is
2558 /foo/mail%New mail!:/bar/mailbox%You've got mail:/baz/mail\%data, the
2559 shell will print
2560
2561 • New mail! when the file /foo/mail has been modified
2562
2563 • You've got mail when the file /bar/mailbox has been modified
2564
2565 • the default message when the file /baz/mail%data has been modified.
2566
2568 Job control is a function of the shell that executes multiple commands
2569 simultaneously and suspends/resumes the commands.
2570
2571 When job control is active:
2572
2573 • Every pipeline executed by the shell becomes a job. A job has its
2574 unique process group ID that is shared among all processes in the
2575 job.
2576
2577 • If the processes of a job are suspended while the shell is waiting
2578 for the processes to finish, the shell continues to the next
2579 command as if the process have finished. The shell remembers the
2580 job as suspended so that it can be resumed later.
2581
2582 • If a job is executed synchronously, the shell sets the foreground
2583 process group of the terminal to the process group of the job. When
2584 the job is finished (or suspended), the shell gets back to the
2585 foreground.
2586
2587 • The subshell executing a command substitution has its own unique
2588 process group ID like a job. However, the shell does not remember
2589 the subshell as a job, so it cannot be suspended or resumed.
2590
2591 • If the shell is interactive, job status is reported before every
2592 command line prompt as if the command jobs -n is executed.
2593
2594 • The standard input of an asynchronous command is not automatically
2595 redirected to /dev/null.
2596
2597 • The shell does not exit when it receives the SIGTSTP signal.
2598
2599 • The value of the - special parameter contains m.
2600
2601 • When a job finished for which the wait built-in has been waiting,
2602 the fact is reported (only if the shell is interactive and not in
2603 the POSIXly-correct mode).
2604
2605 When job control is inactive, processes executed by the shell have the
2606 same process group ID as the shell. The shell treats asynchronous
2607 commands as an uncontrolled job.
2608
2609 You can use the following built-ins to manipulate jobs:
2610
2611 jobs
2612 prints existing jobs
2613
2614 fg and bg
2615 run jobs in the foreground or background
2616
2617 wait
2618 waits for jobs to be finished (or suspended)
2619
2620 disown
2621 forgets jobs
2622
2623 kill
2624 sends a signal to jobs
2625
2626 An interactive job-controlling shell reports jobs status before every
2627 prompt by default. You can set the following options to make the shell
2628 report status at other timings:
2629
2630 notify
2631 the shell reports immediately whenever job status changes.
2632
2633 notify-le
2634 the shell reports immediately when job status changes while
2635 line-editing.
2636
2637 A job is removed from the shell’s job list when:
2638
2639 • it has finished and the jobs built-in reported it,
2640
2641 • the wait built-in successfully waited for the job to finish, or
2642
2643 • the disown built-in removed the job.
2644
2645 Jobs are not removed from the list when an interactive shell
2646 automatically reports the status of jobs.
2647
2648 Note
2649 The word “stop” is synonymous to “suspend” in the context of job
2650 control.
2651
2652 Job ID
2653 Some built-ins use the following notation, which is called job ID, to
2654 specify a job to operate on:
2655
2656 %, %%, %+
2657 the current job
2658
2659 %-
2660 the previous job
2661
2662 %n
2663 the job that has job number n, where n is a positive integer
2664
2665 %string
2666 the job whose name begins with string
2667
2668 %?string
2669 the job whose name contains string
2670
2671 The current job and previous job are jobs selected by the shell
2672 according to the following rules:
2673
2674 • When there is one or more suspended jobs, the current job is
2675 selected from them.
2676
2677 • When there is one or more suspended jobs other than the current
2678 job, the previous job is selected from them.
2679
2680 • The current and previous jobs are always different. When the shell
2681 has only one job, it is the current job and there is no previous
2682 job.
2683
2684 • When the current job finished, the previous job becomes the current
2685 job.
2686
2687 • When the current job is changed, the old current job becomes the
2688 previous job except when the old job finished.
2689
2690 • When the foreground job is suspended, the job becomes the current
2691 job.
2692
2693 Yash has some options to modify the rules of the current/previous job
2694 selection. (The rules above have priority over the options below.)
2695
2696 cur-async
2697 When a new asynchronous command is started, it becomes the current
2698 job.
2699
2700 cur-bg
2701 When a job is resumed by the bg built-in, the job becomes the
2702 current job.
2703
2704 cur-stop
2705 When a job is suspended, it becomes the current job.
2706
2707 The current and previous jobs are not changed as long as the rules
2708 above are met.
2709
2710 The rules of the current/previous job selection defined in the POSIX
2711 standard are looser than yash’s rules above. Other POSIX-compliant
2712 shells may select the current and previous jobs differently.
2713
2715 Built-in commands are commands that are implemented in the shell and
2716 are executed by the shell without external programs.
2717
2718 Types of built-in commands
2719 There are three types of built-in commands in yash: special built-in
2720 commands, semi-special built-in commands and regular built-in commands.
2721
2722 Special built-in commands are much more important commands than others.
2723 They are executed regardless of whether the corresponding external
2724 commands exist or not. Results of variable assignments that occur in a
2725 simple command that invokes a special built-in last after the command
2726 has finished. Moreover, in the POSIXly-correct mode, a non-interactive
2727 shell immediately exits with a non-zero exit status when a redirect
2728 error, assignment error, or misuse of option or operand occurs in a
2729 special built-in command.
2730
2731 Semi special built-in commands are the second important built-in
2732 commands. They are executed regardless of whether the corresponding
2733 external commands exist or not. In other parts they are the same as
2734 regular built-in commands.
2735
2736 Regular built-in commands are less important built-in commands
2737 including commands that can be implemented as external commands or are
2738 not listed in POSIX. In the POSIXly-correct mode, a regular built-in is
2739 executed only when a corresponding external command is found in PATH.
2740
2741 Syntax of command arguments
2742 In this section we explain common rules about command arguments. The
2743 built-in commands of yash follow the rules unless otherwise stated.
2744
2745 There are two types of command arguments. One is options and the other
2746 is operands. An option is an argument that starts with a hyphen (-) and
2747 changes the way the command behaves. Some options take arguments. An
2748 operand is an argument that is not an option and specifies objects the
2749 command operates on.
2750
2751 If you specify more than one option to a command, the order of the
2752 options are normally not significant. The order of operands, however,
2753 affects the command behavior.
2754
2755 An option is either a single-character option or a long option. A
2756 single-character option is identified by one alphabetic character. A
2757 long option is identified by multiple alphabetic characters. The POSIX
2758 standard only prescribes single-character options, so in the
2759 POSIXly-correct mode you cannot use long options.
2760
2761 A single-character option is composed of a hyphen followed by a letter.
2762 For example, -a is a single-character option. A single-character option
2763 that takes an argument requires the argument to be just after the
2764 option name.
2765
2766 Example 4. The set built-in and single-character options
2767
2768 For the set built-in, -m is a single-character option that does not
2769 take an argument and -o is one that takes an argument.
2770
2771 • set -o errexit -m
2772
2773 • set -oerrexit -m
2774
2775 In these two command lines, errexit is the argument to the -o option.
2776
2777 In the second example above, the -o option and its argument are
2778 combined into a single command line argument. The POSIX standard
2779 deprecates that style and any POSIX-conforming applications must
2780 specify options and their arguments as separate command line arguments,
2781 although yash accepts both styles.
2782
2783 You can combine single-character options that do not take arguments
2784 into a single command line argument. For example, the three options -a,
2785 -b and -c can be combined into -abc.
2786
2787 A long option is composed of two hyphens followed by an option name.
2788 For example, --long-option is a long option. You can omit some last
2789 characters of a long option name as long as it is not ambiguous. For
2790 example, you can use --long instead of --long-option if there is no
2791 other options beginning with --long. Like a single-character option, a
2792 long option that takes an argument requires the argument to be a
2793 command line argument just after the option name or to be specified in
2794 the same command line argument as the option name, separated by an
2795 equal sign (=).
2796
2797 Example 5. The fc built-in and long options
2798
2799 For the fc built-in, --quiet is a long option that does not take an
2800 argument and --editor is one that takes an argument.
2801
2802 • fc --editor vi --quiet
2803
2804 • fc --editor=vi --quiet
2805
2806 In these command lines, vi is the argument to the --editor option.
2807
2808 Arguments that are not options (nor arguments to them) are interpreted
2809 as operands. The POSIX standard requires all options should be
2810 specified before any operands. Therefore, in the POSIXly-correct mode,
2811 any arguments that come after the first operand are interpreted as
2812 operands (even if they look like options). If not in the
2813 POSIXly-correct mode, you can specify options after operand.
2814
2815 Regardless of whether the shell is in the POSIXly-correct mode or not,
2816 an argument that is just composed of two hyphens (--) can be used as a
2817 separator between options and operands. All command line arguments
2818 after the -- separator are interpreted as operands, so you can specify
2819 operands that start with a hyphen correctly using the separator.
2820
2821 Example 6. Options and operands to the set built-in
2822
2823 • set -a -b -- -c -d
2824
2825 In this example, -a and -b are options and -c and -d are operands. The
2826 -- separator itself is neither an option nor an operand.
2827
2828 Regardless of whether the shell is in the POSIXly-correct mode or not,
2829 an argument that is just composed of a single hyphen (-) is interpreted
2830 as an operand.
2831
2833 With the line-editing feature, you can edit the command text when you
2834 input a command to an interactive shell. It not only works as a simple
2835 visual-interface editor, but also is integrated with the command
2836 history. You can recall, edit, and execute commands in the history with
2837 line-editing instead of using the fc built-in.
2838
2839 Line-editing has two editing modes, the vi and emacs modes, which each
2840 have their own key binding settings. By switching editing modes, you
2841 can change key bindings used in line-editing. Each mode has a
2842 corresponding shell option, which determines whether the mode is
2843 currently active or not. No more than one mode can be active at a time,
2844 so the options for the other modes are automatically turned off when
2845 you turn on the option for one mode. The whole line-editing feature is
2846 deactivated when those options are off.
2847
2848 When an interactive shell is started, the vi mode is automatically
2849 activated if the standard input and error are both connected to a
2850 terminal.
2851
2852 Line-editing can be used only when the standard input and error are
2853 both connected to a terminal. If not, the shell silently falls back to
2854 the normal input mechanism. While line-editing is being used, the shell
2855 uses the termios interface to change I/O settings of the terminal and
2856 the terminfo interface to parse input key sequences.
2857
2858 Shell options on line-editing
2859 The following options can be set by the set built-in to enable
2860 line-editing and choose an editing mode to activate:
2861
2862 vi
2863 activates the vi mode.
2864
2865 emacs
2866 activates the emacs mode.
2867
2868 The other line-editing-related options are:
2869
2870 le-always-rp
2871 When this options is enabled, the right prompt is always visible:
2872 when the cursor reaches the right prompt, it moves to the next line
2873 from the original position, which would otherwise be overwritten by
2874 input text.
2875
2876 le-comp-debug
2877 When enabled, internal information is printed during completion,
2878 which will help debugging completion scripts.
2879
2880 le-conv-meta
2881 When enabled, the 8th bit of each input byte is always treated as a
2882 meta-key flag, regardless of terminfo data.
2883
2884 le-no-conv-meta
2885 When enabled, the 8th bit of each input byte is never treated as a
2886 meta-key flag, regardless of terminfo data.
2887
2888 The le-conv-meta and le-no-conv-meta options cannot be both enabled
2889 at a time. When either is enabled, the other is automatically
2890 disabled. When neither is enabled, the 8th bit may be treated as a
2891 meta-key flag depending on terminfo data.
2892
2893 le-predict
2894 activates command line prediction.
2895
2896 le-predict-empty
2897 When enabled, and command line prediction is active, suggestions
2898 are also provided for empty input lines.
2899
2900 le-prompt-sp
2901 When enabled, the shell prints a special character sequence before
2902 printing each prompt so that every prompt is printed at the
2903 beginning of a line.
2904
2905 This option is enabled by default.
2906
2907 le-visible-bell
2908 When enabled, the shell flashes the terminal instead of sounding an
2909 alarm when an alert is required.
2910
2911 Editing modes
2912 The vi mode is an editing mode that offers key bindings similar to that
2913 of the vi editor. The vi mode has two sub-modes that are switched
2914 during editing: the insert and command modes. The sub-mode is always
2915 reset to the insert mode when line-editing is started for a new command
2916 line. In the insert mode, most characters are inserted to the buffer as
2917 typed. In the command mode, input characters are treated as commands
2918 that move the cursor, insert/delete text, etc.
2919
2920 The emacs mode offers key bindings similar to the emacs editor. Most
2921 characters are inserted to the buffer as typed, but more characters are
2922 treated as commands than the vi insert mode.
2923
2924 Another sub-mode is used while you enter search keywords. The sub-mode
2925 is called the search mode, which offers slightly different key bindings
2926 depending on the active editing mode.
2927
2928 Line-editing commands
2929 All characters the user enters while line-editing is active are treated
2930 as line-editing commands listed below. The bindkey built-in allows
2931 customizing the key bindings of each mode (except for the search mode).
2932
2933 The list below shows not only the functions of commands but also the
2934 default key bindings. The keywords “vi-insert”, “vi-command”,
2935 “vi-search”, “emacs”, “emacs-search” means the vi insert mode, the vi
2936 command mode, the search mode for the vi mode (the vi search mode), the
2937 emacs mode, and the search mode for the emacs mode (the emacs search
2938 mode), respectively.
2939
2940 Some commands take an argument that affects the function of the
2941 commands. For example, the forward-char command moves the cursor by as
2942 many characters as specified by the argument. To specify an argument,
2943 use the digit-argument command just before another command that takes
2944 an argument.
2945
2946 Basic editing commands
2947 noop
2948 Do nothing.
2949
2950 vi-command
2951 \^[
2952
2953 alert
2954 Alert.
2955
2956 self-insert
2957 Insert the input character at the current cursor position.
2958 Characters escaped by escape sequences cannot be inserted.
2959
2960 vi-insert, emacs
2961 \\
2962
2963 insert-tab
2964 Insert a tab character at the current cursor position.
2965
2966 emacs
2967 \^[\^I
2968
2969 expect-verbatim
2970 Insert a character that is entered just after this command at
2971 the current cursor position. This command can input a character
2972 that cannot be input by the self-insert command, except a null
2973 character ('\0').
2974
2975 vi-insert, vi-search, emacs-search
2976 \^V
2977
2978 emacs
2979 \^Q, \^V
2980
2981 digit-argument
2982 Pass the input digit to the next command as an argument.
2983
2984 This command can be bound to a digit or hyphen. To pass “12” as
2985 an argument to the forward-char command in the vi mode, for
2986 example, enter 12l.
2987
2988 vi-command
2989 1, 2, 3, 4, 5, 6, 7, 8, 9
2990
2991 emacs
2992 \^[0, \^[1, \^[2, \^[3, \^[4, \^[5, \^[6, \^[7, \^[8, \^[9,
2993 \^[-,
2994
2995 bol-or-digit
2996 Like the beginning-of-line command if there is no argument;
2997 like the digit-argument command otherwise.
2998
2999 vi-command
3000 0
3001
3002 accept-line
3003 Finish editing the current line. A newline is automatically
3004 appended to the line. The line will be executed by the shell.
3005
3006 If command line prediction is active, the current prediction
3007 (if any) is ignored. See also the accept-prediction command.
3008
3009 vi-insert, vi-command, emacs, emacs-search
3010 \^J, \^M
3011
3012 abort-line
3013 Abandon the current buffer and finish editing as if an empty
3014 line was input.
3015
3016 vi-insert, vi-command, vi-search, emacs, emacs-search
3017 \!, \^C
3018
3019 eof
3020 Abandon the current buffer and finish editing as if the shell
3021 reached the end of input. This normally makes the shell exit.
3022
3023 eof-if-empty
3024 Like the eof command if the buffer is empty; like the alert
3025 command otherwise.
3026
3027 vi-insert, vi-command
3028 \#, \^D
3029
3030 eof-or-delete
3031 Like the eof command if the buffer is empty; like the
3032 delete-char command otherwise.
3033
3034 emacs
3035 \#, \^D
3036
3037 accept-with-hash
3038 If the current line does not begin with a hash sign (#) or
3039 there is no argument specified for this command, a hash sign is
3040 inserted at the beginning of the line. Otherwise, the beginning
3041 hash sign is removed from the line. Finally, the line is
3042 accepted like the accept-line command.
3043
3044 vi-command
3045 #
3046
3047 emacs
3048 \^[#
3049
3050 accept-prediction
3051 Like the accept-line command, but include the predicted part.
3052
3053 setmode-viinsert
3054 Switch to the vi insert mode.
3055
3056 vi-command
3057 i, \I
3058
3059 setmode-vicommand
3060 Switch to the vi command mode.
3061
3062 vi-insert
3063 \^[
3064
3065 setmode-emacs
3066 Switch to the emacs mode.
3067
3068 expect-char, abort-expect-char
3069 These commands are not meant for use by the user. They are used
3070 by the shell to implement some other commands.
3071
3072 redraw-all
3073 Reprint the prompt and the current line to the terminal.
3074
3075 vi-insert, vi-command, vi-search, emacs, emacs-search
3076 \^L
3077
3078 clear-and-redraw-all
3079 Clear the terminal and reprint the prompt and the current line.
3080
3081 Motion commands
3082 Motion commands move the cursor on the line. Most motion commands
3083 accept an argument. When passed an argument, they repeat the cursor
3084 motion as many times as specified by the argument. Passing “4” as
3085 an argument to the forward-char command, for example, advances the
3086 cursor by four characters.
3087
3088 The shell has several definitions of words as units of distance: A
3089 bigword is one or more adjacent non-whitespace characters. A
3090 semiword is one or more adjacent characters that contain no
3091 whitespaces or punctuations. An emacsword is one or more adjacent
3092 alphanumeric characters. A viword is either:
3093
3094 • one or more adjacent alphanumeric characters and/or underscores
3095 (_), or
3096
3097 • one or more adjacent characters that contain none of
3098 alphanumeric characters, underscores, and whitespaces.
3099
3100 forward-char
3101 Move the cursor to the next character.
3102
3103 vi-insert
3104 \R
3105
3106 vi-command
3107 l, (space), \R
3108
3109 emacs
3110 \R, \^F
3111
3112 backward-char
3113 Move the cursor to the previous character.
3114
3115 vi-insert
3116 \L
3117
3118 vi-command
3119 h, \B, \L, \?, \^H
3120
3121 emacs
3122 \L, \^B
3123
3124 forward-bigword
3125 Move the cursor to the next bigword.
3126
3127 vi-command
3128 W
3129
3130 end-of-bigword
3131 Move the cursor to the next end of a bigword.
3132
3133 vi-command
3134 E
3135
3136 backward-bigword
3137 Move the cursor to the previous bigword.
3138
3139 vi-command
3140 B
3141
3142 forward-semiword
3143 Move the cursor to the next semiword.
3144
3145 end-of-semiword
3146 Move the cursor to the next end of a semiword.
3147
3148 backward-semiword
3149 Move the cursor to the previous semiword.
3150
3151 forward-viword
3152 Move the cursor to the next viword.
3153
3154 vi-command
3155 w
3156
3157 end-of-viword
3158 Move the cursor to the next end of a viword.
3159
3160 vi-command
3161 e
3162
3163 backward-viword
3164 Move the cursor to the previous viword.
3165
3166 vi-command
3167 b
3168
3169 forward-emacsword
3170 Move the cursor to the next emacsword.
3171
3172 emacs
3173 \^[f, \^[F
3174
3175 backward-emacsword
3176 Move the cursor to the previous emacsword.
3177
3178 emacs
3179 \^[b, \^[B
3180
3181 beginning-of-line
3182 Move the cursor to the beginning of the line.
3183
3184 vi-insert, vi-command
3185 \H
3186
3187 emacs
3188 \H, \^A
3189
3190 end-of-line
3191 Move the cursor to the end of the line.
3192
3193 vi-insert
3194 \E
3195
3196 vi-command
3197 $, \E
3198
3199 emacs
3200 \E, \^E
3201
3202 go-to-column
3203 Move the cursor to the nth character on the line, where n is
3204 the argument. Assume n = 1 when no argument.
3205
3206 vi-command
3207 |
3208
3209 first-nonblank
3210 Move the cursor to the first non-blank character on the line.
3211
3212 vi-command
3213 ^
3214
3215 find-char
3216 Move the cursor to the first position where a character that is
3217 entered just after this command appears after the current
3218 cursor position.
3219
3220 vi-command
3221 f
3222
3223 emacs
3224 \^]
3225
3226 find-char-rev
3227 Move the cursor to the last position where a character that is
3228 entered just after this command appears before the current
3229 cursor position.
3230
3231 vi-command
3232 F
3233
3234 emacs
3235 \^[\^]
3236
3237 till-char
3238 Move the cursor to the first position just before a character
3239 that is entered just after this command appears after the
3240 current cursor position.
3241
3242 vi-command
3243 t
3244
3245 till-char-rev
3246 Move the cursor to the last position just after a character
3247 that is entered just after this command appears before the
3248 current cursor position.
3249
3250 vi-command
3251 T
3252
3253 refind-char
3254 Redo the last find-char, find-char-rev, till-char,
3255 till-char-rev command.
3256
3257 vi-command
3258 ;
3259
3260 refind-char-rev
3261 Redo the last find-char, find-char-rev, till-char,
3262 till-char-rev command in the reverse direction.
3263
3264 vi-command
3265 ,
3266
3267 Editing commands
3268 Editing commands modify contents of the buffer. Most editing
3269 commands accept an argument. When passed an argument, they repeat
3270 the modification as many times as specified by the argument.
3271
3272 Texts deleted by commands whose name starts with “kill” are saved
3273 in kill ring, from which deleted contents can be restored to the
3274 buffer. The most recent 32 texts are kept in the kill ring.
3275
3276 delete-char
3277 Delete a character at the current cursor position if no
3278 argument is passed; like the kill-char command otherwise.
3279
3280 vi-insert, emacs
3281 \X
3282
3283 delete-bigword
3284 Delete a bigword at the current cursor position if no argument
3285 is passed; like the kill-bigword command otherwise.
3286
3287 delete-semiword
3288 Delete a semiword at the current cursor position if no argument
3289 is passed; like the kill-semiword command otherwise.
3290
3291 delete-viword
3292 Delete a viword at the current cursor position if no argument
3293 is passed; like the kill-viword command otherwise.
3294
3295 delete-emacsword
3296 Delete a emacsword at the current cursor position if no
3297 argument is passed; like the kill-emacsword command otherwise.
3298
3299 backward-delete-char
3300 Delete a character just before the current cursor position if
3301 no argument is passed; like the backward-kill-char command
3302 otherwise.
3303
3304 vi-insert, emacs
3305 \B, \?, \^H
3306
3307 backward-delete-bigword
3308 Delete a bigword just before the current cursor position if no
3309 argument is passed; like the backward-kill-bigword command
3310 otherwise.
3311
3312 backward-delete-semiword
3313 Delete a semiword just before the current cursor position if no
3314 argument is passed; like the backward-kill-semiword command
3315 otherwise.
3316
3317 vi-insert
3318 \^W
3319
3320 backward-delete-viword
3321 Delete a viword just before the current cursor position if no
3322 argument is passed; like the backward-kill-viword command
3323 otherwise.
3324
3325 backward-delete-emacsword
3326 Delete a emacsword just before the current cursor position if
3327 no argument is passed; like the backward-kill-emacsword command
3328 otherwise.
3329
3330 delete-line
3331 Delete the whole buffer contents.
3332
3333 forward-delete-line
3334 Delete all characters from the current cursor position to the
3335 end of the buffer.
3336
3337 backward-delete-line
3338 Delete all characters before the current cursor position.
3339
3340 vi-insert
3341 \$, \^U
3342
3343 kill-char
3344 Delete a character at the current cursor position and add it to
3345 the kill ring.
3346
3347 vi-command
3348 x, \X
3349
3350 kill-bigword
3351 Delete a bigword at the current cursor position and add it to
3352 the kill ring.
3353
3354 kill-semiword
3355 Delete a semiword at the current cursor position and add it to
3356 the kill ring.
3357
3358 kill-viword
3359 Delete a viword at the current cursor position and add it to
3360 the kill ring.
3361
3362 kill-emacsword
3363 Delete a emacsword at the current cursor position and add it to
3364 the kill ring.
3365
3366 emacs
3367 \^[d, \^[D
3368
3369 backward-kill-char
3370 Delete a character just before the current cursor position and
3371 add it to the kill ring.
3372
3373 vi-command
3374 X
3375
3376 backward-kill-bigword
3377 Delete a bigword just before the current cursor position and
3378 add it to the kill ring.
3379
3380 emacs
3381 \^W
3382
3383 backward-kill-semiword
3384 Delete a semiword just before the current cursor position and
3385 add it to the kill ring.
3386
3387 backward-kill-viword
3388 Delete a viword just before the current cursor position and add
3389 it to the kill ring.
3390
3391 backward-kill-emacsword
3392 Delete a emacsword just before the current cursor position and
3393 add it to the kill ring.
3394
3395 emacs
3396 \^[\B, \^[\?, \^[\^H
3397
3398 kill-line
3399 Delete the whole buffer contents and add it to the kill ring.
3400
3401 forward-kill-line
3402 Delete all characters from the current cursor position to the
3403 end of the buffer and add it to the kill ring.
3404
3405 emacs
3406 \^K
3407
3408 backward-kill-line
3409 Delete all characters before the current cursor position and
3410 add it to the kill ring.
3411
3412 emacs
3413 \$, \^U, \^X\B, \^X\?
3414
3415 put-before
3416 Insert the last-killed text before the current cursor position
3417 and move the cursor to the last character that was inserted.
3418
3419 vi-command
3420 P
3421
3422 put
3423 Insert the last-killed text after the current cursor position
3424 and move the cursor to the last character that was inserted.
3425
3426 vi-command
3427 p
3428
3429 put-left
3430 Insert the last-killed text before the current cursor position
3431 and move the cursor to the last character that was inserted.
3432
3433 emacs
3434 \^Y
3435
3436 put-pop
3437 Replace the just put text with the next older killed text.
3438
3439 This command can be used only just after the put-before, put,
3440 put-left, or put-pop command.
3441
3442 emacs
3443 \^[y, \^[Y
3444
3445 undo
3446 Cancel modification by the last editing command.
3447
3448 vi
3449 u
3450
3451 emacs
3452 \^_, \^X\$, \^X\^U
3453
3454 undo-all
3455 Cancel all modification in the current buffer, restoring the
3456 initial contents.
3457
3458 vi
3459 U
3460
3461 emacs
3462 \^[\^R, \^[r, \^[R
3463
3464 cancel-undo
3465 Cancel cancellation by the last undo or undo-all command.
3466
3467 vi
3468 \^R
3469
3470 cancel-undo-all
3471 Cancel all cancellation by all most recent undo and undo-all
3472 commands.
3473
3474 redo
3475 Repeat modification by the last editing command.
3476
3477 vi-command
3478 .
3479
3480 Completion commands
3481 complete
3482 Complete a word just before the cursor position and, if there
3483 is more than one candidate, show a list of the candidates.
3484
3485 complete-next-candidate
3486 Like the complete command when candidates are not being listed;
3487 otherwise, select the next candidate in the list.
3488
3489 vi-insert, emacs
3490 \^I
3491
3492 complete-prev-candidate
3493 Like the complete command when candidates are not being listed;
3494 otherwise, select the previous candidate in the list.
3495
3496 vi-insert, emacs
3497 \bt
3498
3499 complete-next-column
3500 Like the complete command when candidates are not being listed;
3501 otherwise, select the first candidate in the next column in the
3502 list.
3503
3504 complete-prev-column
3505 Like the complete command when candidates are not being listed;
3506 otherwise, select the first candidate in the previous column in
3507 the list.
3508
3509 complete-next-page
3510 Like the complete command when candidates are not being listed;
3511 otherwise, select the first candidate in the next page in the
3512 list.
3513
3514 complete-prev-page
3515 Like the complete command when candidates are not being listed;
3516 otherwise, select the first candidate in the previous page in
3517 the list.
3518
3519 complete-list
3520 Complete a word just before the cursor position.
3521
3522 If you pass no argument, a list of completion candidates is
3523 shown. Otherwise, the word is completed with the nth candidate
3524 where n is the argument.
3525
3526 emacs
3527 \^[?, \^[=
3528
3529 complete-all
3530 Replace a word just before the cursor position with all
3531 possible completion candidates, each separated by a space.
3532
3533 emacs
3534 \^[*
3535
3536 complete-max
3537 Complete a word just before the cursor position with the
3538 longest prefix of all possible completion candidates.
3539
3540 complete-max-then-list
3541 Works like the complete-max command for the first use, then
3542 like the complete command when used successively.
3543
3544 complete-max-then-next-candidate
3545 Works like the complete-max command for the first use, then
3546 like the complete-next-candidate command when used
3547 successively.
3548
3549 complete-max-then-prev-candidate
3550 Works like the complete-max command for the first use, then
3551 like the complete-prev-candidate command when used
3552 successively.
3553
3554 clear-candidates
3555 Clear the list of completion candidates.
3556
3557 Vi-specific commands
3558 vi-replace-char
3559 Replace the character at the cursor position with a character
3560 that is entered just after this command.
3561
3562 vi-command
3563 r
3564
3565 vi-insert-beginning
3566 Move the cursor to the beginning of the line and switch to the
3567 vi insert mode.
3568
3569 vi-command
3570 I
3571
3572 vi-append
3573 Move the cursor to the next character and switch to the vi
3574 insert mode.
3575
3576 vi-command
3577 I
3578
3579 vi-append-to-eol
3580 Move the cursor to the end of the line and switch to the vi
3581 insert mode.
3582
3583 vi-command
3584 A
3585
3586 vi-replace
3587 Switch to the vi insert mode and start overwriting. While
3588 overwriting, the self-insert command replaces the character at
3589 cursor position rather than inserting a character. Overwriting
3590 ends when the editing mode is changed.
3591
3592 vi-command
3593 R
3594
3595 vi-switch-case
3596 Switch case of characters between the current and next cursor
3597 positions. This command must be followed by a motion command,
3598 which determines the next cursor position.
3599
3600 vi-switch-case-char
3601 Switch case of the character at the current cursor position and
3602 move the cursor to the next character.
3603
3604 vi-command
3605 ~
3606
3607 vi-yank
3608 Add to the kill ring the characters between the current and
3609 next cursor positions. This command must be followed by a
3610 motion command, which determines the next cursor position.
3611
3612 vi-command
3613 y
3614
3615 vi-yank-to-eol
3616 Add to the kill ring the characters from the current cursor
3617 position to the end of the line.
3618
3619 vi-command
3620 Y
3621
3622 vi-delete
3623 Delete characters between the current and next cursor positions
3624 and add it to the kill ring. This command must be followed by a
3625 motion command, which determines the next cursor position.
3626
3627 vi-command
3628 d
3629
3630 vi-delete-to-eol
3631 Delete the characters from the current cursor position to the
3632 end of the line and add it to the kill ring.
3633
3634 vi-command
3635 D
3636
3637 vi-change
3638 Delete characters between the current and next cursor positions
3639 and switch to the vi insert mode. This command must be followed
3640 by a motion command, which determines the next cursor position.
3641
3642 vi-command
3643 c
3644
3645 vi-change-to-eol
3646 Delete the characters from the current cursor position to the
3647 end of the line and switch to the vi insert mode.
3648
3649 vi-command
3650 C
3651
3652 vi-change-line
3653 Delete the whole buffer contents and switch to the vi insert
3654 mode.
3655
3656 vi-command
3657 S
3658
3659 vi-yank-and-change
3660 Like the vi-change command, but the deleted text is added to
3661 the kill ring.
3662
3663 vi-yank-and-change-to-eol
3664 Like the vi-change-to-eol command, but the deleted text is
3665 added to the kill ring.
3666
3667 vi-yank-and-change-line
3668 Like the vi-change-line command, but the deleted text is added
3669 to the kill ring.
3670
3671 vi-substitute
3672 Delete a character at the current cursor position, add it to
3673 the kill ring, and switch to the vi insert mode.
3674
3675 vi-command
3676 s
3677
3678 vi-append-last-bigword
3679 Insert a space and the last bigword in the most recent command
3680 history entry just after the current cursor position and switch
3681 to the vi insert mode. If argument n is passed, the nth bigword
3682 in the entry is inserted instead of the last.
3683
3684 vi-command
3685 _
3686
3687 vi-exec-alias
3688 Execute the value of an alias named _c as editing commands
3689 where c is a character input just after this command.
3690
3691 vi-command
3692 @
3693
3694 vi-edit-and-accept
3695 Start the vi editor to edit the current buffer contents. When
3696 the editor finished, the edited buffer contents is accepted
3697 like the accept-line command unless the exit status of the
3698 editor is non-zero.
3699
3700 vi-command
3701 v
3702
3703 vi-complete-list
3704 Like the complete-list command, but also switch to the vi
3705 insert mode.
3706
3707 vi-command
3708 =
3709
3710 vi-complete-all
3711 Like the complete-all command, but also switch to the vi insert
3712 mode.
3713
3714 vi-command
3715 *
3716
3717 vi-complete-max
3718 Like the complete-max command, but also switch to the vi insert
3719 mode.
3720
3721 vi-command
3722 \\
3723
3724 vi-search-forward
3725 Switch to the vi search mode and start forward history search.
3726
3727 vi-command
3728 ?
3729
3730 vi-search-backward
3731 Switch to the vi search mode and start backward history search.
3732
3733 vi-command
3734 /
3735
3736 Emacs-specific commands
3737 emacs-transpose-chars
3738 Move a character just before the cursor to the right.
3739
3740 emacs
3741 \^T
3742
3743 emacs-transpose-words
3744 Move an emacsword just before the cursor to the right.
3745
3746 emacs
3747 \^[t, \^[T
3748
3749 emacs-downcase-word
3750 Make an emacsword just after the cursor lowercase.
3751
3752 emacs
3753 \^[l, \^[L
3754
3755 emacs-upcase-word
3756 Make an emacsword just after the cursor uppercase.
3757
3758 emacs
3759 \^[u, \^[U
3760
3761 emacs-capitalize-word
3762 Capitalize the first letter of an emacsword just after the
3763 cursor.
3764
3765 emacs
3766 \^[c, \^[u
3767
3768 emacs-delete-horizontal-space
3769 Delete spaces around the cursor. If any argument was passed,
3770 delete spaces just before the cursor only.
3771
3772 emacs
3773 \^[\\
3774
3775 emacs-just-one-space
3776 Delete spaces around the cursor and leave one space. If an
3777 argument is specified, leave as many spaces as the argument.
3778
3779 emacs
3780 \^[ (Escape followed by a space)
3781
3782 emacs-search-forward
3783 Switch to the emacs search mode and start forward history
3784 search.
3785
3786 emacs
3787 \^S
3788
3789 emacs-search-backward
3790 Switch to the emacs search mode and start backward history
3791 search.
3792
3793 emacs
3794 \^R
3795
3796 History-related commands
3797 oldest-history
3798 Recall the oldest entry in the history. If argument n is
3799 passed, the entry whose number is n is recalled instead. The
3800 cursor position remains unchanged.
3801
3802 newest-history
3803 Recall the newest entry in the history. If argument n is
3804 passed, the entry whose number is n is recalled instead. The
3805 cursor position remains unchanged.
3806
3807 return-history
3808 Return to the initial buffer corresponding to none of existing
3809 history entries. If argument n is passed, the entry whose
3810 number is n is recalled instead. The cursor position remains
3811 unchanged.
3812
3813 oldest-history-bol
3814 Recall the oldest entry in the history and move the cursor to
3815 the beginning of the line. If argument n is passed, the entry
3816 whose number is n is recalled instead.
3817
3818 vi-command
3819 G
3820
3821 newest-history-bol
3822 Recall the newest entry in the history and move the cursor to
3823 the beginning of the line. If argument n is passed, the entry
3824 whose number is n is recalled instead.
3825
3826 return-history-bol
3827 Return to the initial buffer corresponding to none of existing
3828 history entries and move the cursor to the beginning of the
3829 line. If argument n is passed, the entry whose number is n is
3830 recalled instead.
3831
3832 vi-command
3833 g
3834
3835 oldest-history-eol
3836 Recall the oldest entry in the history and move the cursor to
3837 the end of the line. If argument n is passed, the entry whose
3838 number is n is recalled instead.
3839
3840 emacs
3841 \^[<
3842
3843 newest-history-eol
3844 Recall the newest entry in the history and move the cursor to
3845 the end of the line. If argument n is passed, the entry whose
3846 number is n is recalled instead.
3847
3848 return-history-eol
3849 Return to the initial buffer corresponding to none of existing
3850 history entries and move the cursor to the end of the line. If
3851 argument n is passed, the entry whose number is n is recalled
3852 instead.
3853
3854 emacs
3855 \^[>
3856
3857 next-history
3858 Recall the next history entry. The cursor position remains
3859 unchanged.
3860
3861 prev-history
3862 Recall the previous history entry. The cursor position remains
3863 unchanged.
3864
3865 next-history-bol
3866 Recall the next history entry and move the cursor to the
3867 beginning of the line.
3868
3869 vi-command
3870 j, +, \D, \^N
3871
3872 prev-history-bol
3873 Recall the previous history entry and move the cursor to the
3874 beginning of the line.
3875
3876 vi-command
3877 k, -, \U, \^P
3878
3879 next-history-eol
3880 Recall the next history entry and move the cursor to the end of
3881 the line.
3882
3883 vi-insert, emacs
3884 \D, \^N
3885
3886 prev-history-eol
3887 Recall the previous history entry and move the cursor to the
3888 end of the line.
3889
3890 vi-insert, emacs
3891 \U, \^P
3892
3893 search-again
3894 Repeat the last command history search.
3895
3896 vi-command
3897 n
3898
3899 search-again-rev
3900 Repeat the last command history search in the reverse
3901 direction.
3902
3903 vi-command
3904 N
3905
3906 search-again-forward
3907 Repeat the last command history search in the forward
3908 direction.
3909
3910 search-again-backward
3911 Repeat the last command history search in the backward
3912 direction.
3913
3914 beginning-search-forward
3915 Recall the next history entry that starts with the same text as
3916 the text from the beginning of the line up to the current
3917 cursor position. The cursor position remains unchanged.
3918
3919 beginning-search-backward
3920 Recall the previous history entry that starts with the same
3921 text as the text from the beginning of the line up to the
3922 current cursor position. The cursor position remains unchanged.
3923
3924 Search mode commands
3925 srch-self-insert
3926 Insert the input character at the current cursor position.
3927 Characters escaped by escape sequences cannot be inserted.
3928
3929 vi-search, emacs-search
3930 \\
3931
3932 srch-backward-delete-char
3933 Delete the last character in the search text. If the text is
3934 empty:
3935
3936 • like the srch-abort-search command when in the vi search
3937 mode, or
3938
3939 • like the alert command when in the emacs search mode.
3940
3941 vi-search, emacs-search
3942 \B, \?, \^H
3943
3944 srch-backward-delete-line
3945 Delete the whole search text.
3946
3947 vi-search, emacs-search
3948 \$, \^U
3949
3950 srch-continue-forward
3951 Find the next matching history entry.
3952
3953 emacs-search
3954 \^S
3955
3956 srch-continue-backward
3957 Find the previous matching history entry.
3958
3959 emacs-search
3960 \^R
3961
3962 srch-accept-search
3963 Finish the search mode, accepting the result being shown.
3964
3965 vi-search
3966 \^J, \^M
3967
3968 emacs-search
3969 \^J, \^[
3970
3971 srch-abort-search
3972 Abort search and restore the previous buffer contents.
3973
3974 vi-search
3975 \^[
3976
3977 emacs-search
3978 \^G
3979
3980 Escape sequences
3981 In the bindkey built-in, escape sequences are used to represent special
3982 keys such as function keys and arrow keys. Every escape sequence starts
3983 with a backslash (\) and thus there is also an escape sequence for a
3984 backslash itself.
3985
3986 Below are available escape sequences:
3987
3988 \\
3989 Backslash (\)
3990
3991 \B
3992 Backspace
3993
3994 \D
3995 Down arrow
3996
3997 \E
3998 End
3999
4000 \H
4001 Home
4002
4003 \I
4004 Insert (Insert-char, Enter-insert-mode)
4005
4006 \L
4007 Left arrow
4008
4009 \N
4010 Page-down (Next-page)
4011
4012 \P
4013 Page-up (Previous-page)
4014
4015 \R
4016 Right arrow
4017
4018 \U
4019 Up arrow
4020
4021 \X
4022 Delete
4023
4024 \!
4025 INTR
4026
4027 \#
4028 EOF
4029
4030 \$
4031 KILL
4032
4033 \?
4034 ERASE
4035
4036 \^@
4037 Ctrl + @
4038
4039 \^A, \^B, ..., \^Z
4040 Ctrl + A, Ctrl + B, ..., Ctrl + Z
4041
4042 Note that Ctrl + I, Ctrl + J, and Ctrl + M are tab, newline, and
4043 carriage return, respectively.
4044
4045 \^[
4046 Ctrl + [ (Escape)
4047
4048 \^\
4049 Ctrl + \
4050
4051 \^]
4052 Ctrl + ]
4053
4054 \^^
4055 Ctrl + ^
4056
4057 \^_
4058 Ctrl + _
4059
4060 \^?
4061 Ctrl + ? (Delete)
4062
4063 \F00, \F01, ..., \F63
4064 F0, F1, ..., F63
4065
4066 \a1
4067 Top-left on keypad
4068
4069 \a3
4070 Top-right on keypad
4071
4072 \b2
4073 Center on keypad
4074
4075 \bg
4076 Beginning
4077
4078 \bt
4079 Back-tab
4080
4081 \c1
4082 Bottom-left on keypad
4083
4084 \c3
4085 Bottom-right on keypad
4086
4087 \ca
4088 Clear-all-tabs
4089
4090 \cl
4091 Close
4092
4093 \cn
4094 Cancel
4095
4096 \co
4097 Command
4098
4099 \cp
4100 Copy
4101
4102 \cr
4103 Create
4104
4105 \cs
4106 Clear-screen or erase
4107
4108 \ct
4109 Clear-tab
4110
4111 \dl
4112 Delete-line
4113
4114 \ei
4115 Exit-insert-mode
4116
4117 \el
4118 Clear-to-end-of-line
4119
4120 \es
4121 Clear-to-end-of-screen
4122
4123 \et
4124 Enter (Send)
4125
4126 \ex
4127 Exit
4128
4129 \fd
4130 Find
4131
4132 \hp
4133 Help
4134
4135 \il
4136 Insert-line
4137
4138 \ll
4139 Home-down
4140
4141 \me
4142 Message
4143
4144 \mk
4145 Mark
4146
4147 \ms
4148 Mouse event
4149
4150 \mv
4151 Move
4152
4153 \nx
4154 Next-object
4155
4156 \on
4157 Open
4158
4159 \op
4160 Options
4161
4162 \pr
4163 Print (Copy)
4164
4165 \pv
4166 Previous-object
4167
4168 \rd
4169 Redo
4170
4171 \re
4172 Resume
4173
4174 \rf
4175 Ref (Reference)
4176
4177 \rh
4178 Refresh
4179
4180 \rp
4181 Replace
4182
4183 \rs
4184 Restart
4185
4186 \sf
4187 Scroll-forward (Scroll-down)
4188
4189 \sl
4190 Select
4191
4192 \sr
4193 Scroll-backward (Scroll-up)
4194
4195 \st
4196 Set-tab
4197
4198 \su
4199 Suspend
4200
4201 \sv
4202 Save
4203
4204 \ud
4205 Undo
4206
4207 \SE
4208 Shift + End
4209
4210 \SH
4211 Shift + Home
4212
4213 \SI
4214 Shift + Insert
4215
4216 \SL
4217 Shift + Left arrow
4218
4219 \SR
4220 Shift + Right arrow
4221
4222 \SX
4223 Shift + Delete
4224
4225 \Sbg
4226 Shift + Beginning
4227
4228 \Scn
4229 Shift + Cancel
4230
4231 \Sco
4232 Shift + Command
4233
4234 \Scp
4235 Shift + Copy
4236
4237 \Scr
4238 Shift + Create
4239
4240 \Sdl
4241 Shift + Delete-line
4242
4243 \Sel
4244 Shift + End-of-line
4245
4246 \Sex
4247 Shift + Exit
4248
4249 \Sfd
4250 Shift + Find
4251
4252 \Shp
4253 Shift + Help
4254
4255 \Smg
4256 Shift + Message
4257
4258 \Smv
4259 Shift + Move
4260
4261 \Snx
4262 Shift + Next
4263
4264 \Sop
4265 Shift + Options
4266
4267 \Spr
4268 Shift + Print
4269
4270 \Spv
4271 Shift + Previous
4272
4273 \Srd
4274 Shift + Redo
4275
4276 \Sre
4277 Shift + Resume
4278
4279 \Srp
4280 Shift + Replace
4281
4282 \Ssu
4283 Shift + Suspend
4284
4285 \Ssv
4286 Shift + Save
4287
4288 \Sud
4289 Shift + Undo
4290
4291 INTR, EOF, KILL, and ERASE are special characters configured by the
4292 stty command. In a typical configuration, they are sent by typing
4293 Ctrl+C, Ctrl+D, Ctrl+U, and Ctrl+H, respectively, but some
4294 configuration uses Ctrl+? instead of Ctrl+H for ERASE.
4295
4296 Command line completion
4297 By using the complete and complete-next-candidate commands, etc., you
4298 can complete command names, options, and operands. By default, the
4299 complete-next-candidate command is bound with the Tab key in the vi
4300 insert and emacs modes.
4301
4302 Type a few first letters of a command name or pathname and hit the Tab
4303 key, and a list of matching names will be shown. You can choose a
4304 candidate from the list to complete the name by hitting the Tab key
4305 again. If there is only one matching name, no list will be shown and
4306 the name will directly be completed.
4307
4308 If the name to be completed contains characters like * and ?, it is
4309 treated as a pattern. The name on the command line will be directly
4310 substituted with all possible names matching the pattern (you cannot
4311 choose from a list).
4312
4313 Normally, command names are completed with command names and command
4314 arguments with pathnames. However, completion functions can be defined
4315 to refine completion results.
4316
4317 Completion details
4318 When doing completion for the first time after the shell has been
4319 started, the INIT file is loaded as if the command string . -AL
4320 completion/INIT is executed. If the file is not found, it is
4321 silently ignored. This automatic loading is mainly intended for
4322 loading completion functions bundled with the shell, but you can
4323 let the shell load your own functions by putting a file in the load
4324 path.
4325
4326 When completing a command name, the shell executes the
4327 completion//command function and when completing a command
4328 argument, the completion//argument function. If those completion
4329 functions are not defined, the shell just completes with command
4330 names or pathnames. When completing other names, such as the user
4331 name in tilde expansion and the parameter name in parameter
4332 expansion, completion functions are never used: the shell just
4333 completes with user names, parameter names, or whatever applicable.
4334
4335 Completion functions are executed without any arguments. The
4336 following local variables are automatically defined while executing
4337 completion functions:
4338
4339 IFS
4340 The value is the three characters of a space, a tab, and a
4341 newline, which are the default value of the variable.
4342
4343 WORDS
4344 This variable is an array whose elements are a command name and
4345 arguments that have already been entered before the argument
4346 being completed. When completing a command name, the array has
4347 no elements.
4348
4349 TARGETWORD
4350 The value is the partially entered command name or argument
4351 that is being completed.
4352
4353 Completion candidates are generated by executing the complete
4354 built-in during a completion function.
4355
4356 Completion functions must not perform I/O to the terminal, or
4357 displayed text will be corrupted. Completion functions should run
4358 as quickly as possible for better user experience.
4359
4360 While a completion function is being executed:
4361
4362 • the POSIXly-correct mode and the err-return option are
4363 temporarily disabled,
4364
4365 • the err-exit option is temporarily ignored, and
4366
4367 • traps are not executed.
4368
4369 Command line prediction
4370 This is an experimental feature. When the le-predict option is enabled,
4371 the shell automatically tries to predict a command string fragment that
4372 follows the part of the command you have already typed in line-editing.
4373
4374 For example, assume you have once typed the command ls Documents. Next
4375 time you start typing ls Doc, the shell will show uments just after the
4376 cursor. If you are satisfied with this suggestion, you can move the
4377 cursor to the right by the forward-char or any other motion commands
4378 instead of typing the rest of the command. After moving the cursor
4379 after the last s, you can use the accept-line command to execute the
4380 command. You can also use the accept-prediction command to immediately
4381 execute the suggested command without moving the cursor.
4382
4383 To distinguish the typed part and the predicted part of a command
4384 string, you can change the font style of the typed part by setting the
4385 PS1S variable. Customizing the font style of the predicted part is not
4386 (yet) supported; it is always shown in the default style.
4387
4388 When you move the cursor to the right, the predicted part up to the
4389 cursor becomes the typed part as if you actually typed it. Moving the
4390 cursor to the left does not turn the typed part back to the prediction.
4391 Use deletion commands such as backward-delete-char to delete typed
4392 command fragment.
4393
4394 The predicted part of the command is shown only when the cursor is at
4395 the end of the typed part.
4396
4397 By default, the predicted part is shown after you start typing a
4398 command string. By enabling the le-predict-empty option, the predicted
4399 part is also shown before you type the first character of the command
4400 string.
4401
4402 The prediction algorithm suggests command fragments on the basis of the
4403 command history. The algorithm considers recent history entries more
4404 probable. It also takes command succession patterns into account. A
4405 predicted command fragment is not always a complete valid command
4406 because less probable part of the fragment is excluded from prediction.
4407
4409 Yash behaves as defined in POSIX.1-2008, Shell & Utilities for the most
4410 part, but some functionalities disobey POSIX for usability. When full
4411 POSIX-conformance is needed, you can enable the POSIXly-correct mode to
4412 make yash obey POSIX as much as possible.
4413
4414 If yash is started with the name “sh”, the POSIXly-correct mode is
4415 automatically enabled. The -o posixly-correct command-line option also
4416 enables the POSIXly-correct mode. After yash has been started, the
4417 POSIXly-correct mode can be enabled by executing the command string set
4418 -o posixly-correct.
4419
4420 When the POSIXly-correct mode is on, yash not only tries to obey the
4421 requirements by POSIX, but also treats as errors most conditions where
4422 the behavior is undefined or unspecified by POSIX. As a result, most
4423 yash-specific functionalities are disabled in the POSIXly-correct mode.
4424
4425 Below is the complete list of the behavioral differences between when
4426 yash is in the POSIXly-correct mode and when not. When the
4427 POSIXly-correct mode is enabled:
4428
4429 • Different initialization scripts are used.
4430
4431 • If the shell was started with the -c option, sh -c (instead of yash
4432 -c) is printed as the script pathname on a syntax error.
4433
4434 • Global aliases are not substituted.
4435
4436 • Nested commands in a compound command must not be empty.
4437
4438 • The for loop iteration variable is created as global, regardless of
4439 the for-local shell option. The variable must have a portable
4440 (ASCII-only) name.
4441
4442 • The first pattern in a case command cannot be esac.
4443
4444 • The ! keyword cannot be followed by ( without any whitespaces
4445 in-between.
4446
4447 • The double-bracket command cannot be used.
4448
4449 • The function keyword cannot be used for function definition. The
4450 function must have a portable (ASCII-only) name.
4451
4452 • Simple commands cannot assign to arrays.
4453
4454 • Changing the value of the LC_CTYPE variable after the shell has
4455 been initialized does not affect the shell’s locale.
4456
4457 • The RANDOM variable cannot be used to generate random numbers.
4458
4459 • Tilde expansion only expands ~ and ~username.
4460
4461 • Parameter expansion cannot be nested. No indexes or modifiers with
4462 word2 are allowed.
4463
4464 • The commands in a command substitution of the form $(commands) are
4465 parsed every time the substitution is executed.
4466
4467 • In arithmetic expansion, fractional numbers and the ++ and --
4468 operators cannot be used. All variables must be numeric.
4469
4470 • The operand of a redirection cannot be the integer prefix to a next
4471 redirection operator.
4472
4473 • A compound command with a redirection cannot be immediately
4474 followed by a keyword like } and fi.
4475
4476 • In a redirection to a file, if the pathname expansion yielded more
4477 than one or no pathname, it is not immediately treated as an error.
4478 Instead, the shell tries to treat the word before the expansion as
4479 a pathname.
4480
4481 • A file descriptor must be readable and writable when duplicated by
4482 the <& and >& redirection operator, respectively.
4483
4484 • Socket redirection, here strings, pipe redirection, and process
4485 redirection cannot be used.
4486
4487 • When executing a simple command, failure in command search does not
4488 trigger execution of the COMMAND_NOT_FOUND_HANDLER variable.
4489
4490 • In command search, a regular built-in needs to have a corresponding
4491 external command for the built-in to be found.
4492
4493 • Some built-ins behave differently. Especially, long command-line
4494 options (as well as some others) cannot be used.
4495
4496 • A non-interactive shell exits when a special built-in is given a
4497 syntactically wrong arguments or when an error occurs in assignment
4498 or redirection with a special built-in.
4499
4500 • An interactive shell does not execute the PROMPT_COMMAND variable
4501 before printing a prompt. The values of the PS1, PS2, and PS4
4502 variables are parsed differently. Prompt variables with a YASH_
4503 prefix (e.g. YASH_PS1) are not used.
4504
4505 • In mail checking, a notification message is printed if the file has
4506 been modified, regardless of whether the file is empty.
4507
4509 How can I use Unicode (non-ASCII) characters?
4510 You need to set locale environment variables to enable Unicode
4511 character support.
4512
4513 If the variables have already been configured for your preference, you
4514 probably don’t have to do anything. To check the current locale
4515 configurations, you can use the locale command:
4516
4517 $ locale
4518 LANG=
4519 LC_CTYPE="en_US.utf8"
4520 LC_NUMERIC="en_US.utf8"
4521 LC_TIME="en_US.utf8"
4522 LC_COLLATE="en_US.utf8"
4523 LC_MONETARY="en_US.utf8"
4524 LC_MESSAGES="en_US.utf8"
4525 LC_PAPER="en_US.utf8"
4526 LC_NAME="en_US.utf8"
4527 LC_ADDRESS="en_US.utf8"
4528 LC_TELEPHONE="en_US.utf8"
4529 LC_MEASUREMENT="en_US.utf8"
4530 LC_IDENTIFICATION="en_US.utf8"
4531 LC_ALL=en_US.utf8
4532
4533 In this example, the locale command shows that all the locale setting
4534 categories are configured for the English language, the United States
4535 region, and the UTF-8 encoding.
4536
4537 If the current configuration does not seem to match your preference,
4538 set the LC_ALL variable like this:
4539
4540 export LC_ALL=en_US.utf8
4541
4542 If you want to use other languages, regions, or encodings, you have to
4543 set the variable to a different value. Please consult your OS’s
4544 documentation to learn how to configure these variables in detail.
4545
4546 If you want to apply the same configuration every time you start yash,
4547 write the command in ~/.yashrc or ~/.yash_profile.
4548
4549 If yash still rejects Unicode characters being entered, see the section
4550 below regarding line-editing.
4551
4552 Line-editing does not work
4553 First, type echo $TERM and see if it prints a sane value. xterm is the
4554 safest value that should work on any existing environment. Colored
4555 versions like xterm-16color and other terminal types like rxvt and
4556 vt100 may also work. All possible values can be listed by the toe
4557 command. It’s most desirable to choose a value that matches the actual
4558 terminal type you are using, but it might not work if the terminal type
4559 you chose is not supported on the system on which yash is running. If
4560 so, try changing the TERM value by export TERM=xterm, for example, to
4561 find a value that works.
4562
4563 If line-editing works but you have trouble entering Unicode (non-ASCII)
4564 characters, try enabling the le-no-conv-meta option by set -o
4565 le-no-conv-meta.
4566
4568 This chapter defines the syntax of the shell command language.
4569
4570 Note
4571 Some of the syntactic features described below are not supported in
4572 the POSIXly-correct mode.
4573
4574 Tokenization
4575 The characters of the input source code are first delimited into
4576 tokens. Tokens are delimited so that the earlier token spans as long as
4577 possible. A sequence of one or more unquoted blank characters delimits
4578 a token.
4579
4580 The following tokens are the operator tokens:
4581
4582 & && ( ) ; ;; | || < << <& <( <<- <<< <> > >> >& >( >>| >| (newline)
4583
4584 Note
4585 Unlike other programming languages, the newline operator is a token
4586 rather than a white space.
4587
4588 Characters that are not blank nor part of an operator compose a word
4589 token. Words are parsed by the following parsing expression grammar:
4590
4591 Word
4592 (WordElement / !SpecialChar .)+
4593
4594 WordElement
4595 \ . /
4596
4597 ' (!' .)* ' /
4598
4599 " QuoteElement* " /
4600
4601 Parameter /
4602
4603 Arithmetic /
4604
4605 CommandSubstitution
4606
4607 QuoteElement
4608 \ ([$`"\] / <newline>) /
4609
4610 Parameter /
4611
4612 Arithmetic /
4613
4614 CommandSubstitutionQuoted /
4615
4616 ![`"\] .
4617
4618 Parameter
4619 $ [@*#?-$! [:digit:]] /
4620
4621 $ PortableName /
4622
4623 $ ParameterBody
4624
4625 PortableName
4626 ![0-9] [0-9 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]+
4627
4628 ParameterBody
4629 { ParameterNumber? (ParameterName / ParameterBody / $ ParameterBody
4630 / Arithmetic / CommandSubstitution) ParameterIndex?
4631 ParameterMatch? }
4632
4633 ParameterNumber
4634 # ![}+=:/%] !([-?#] !})
4635
4636 ParameterName
4637 [@*#?-$!] /
4638
4639 [[:alnum:] _]+
4640
4641 ParameterIndex
4642 [ ParameterIndexWord (, ParameterIndexWord)? ]
4643
4644 ParameterIndexWord
4645 (WordElement / !["'],] .)+
4646
4647 ParameterMatch
4648 :? [-+=?] ParameterMatchWord /
4649
4650 (# / ## / % / %%) ParameterMatchWord /
4651
4652 (:/ / / [#%/]?) ParameterMatchWordNoSlash (/ ParameterMatchWord)?
4653
4654 ParameterMatchWord
4655 (WordElement / !["'}] .)*
4656
4657 ParameterMatchWordNoSlash
4658 (WordElement / !["'/}] .)*
4659
4660 Arithmetic
4661 $(( ArithmeticBody* ))
4662
4663 ArithmeticBody
4664 \ . /
4665
4666 Parameter /
4667
4668 Arithmetic /
4669
4670 CommandSubstitution /
4671
4672 ( ArithmeticBody ) /
4673
4674 ![`()] .
4675
4676 CommandSubstitution
4677 $( CompleteProgram ) /
4678
4679 ` CommandSubstitutionBody* `
4680
4681 CommandSubstitutionQuoted
4682 $( CompleteProgram ) /
4683
4684 ` CommandSubstitutionBodyQuoted* `
4685
4686 CommandSubstitutionBody
4687 \ [$`\] /
4688
4689 !` .
4690
4691 CommandSubstitutionBodyQuoted
4692 \ [$`\`] /
4693
4694 !` .
4695
4696 SpecialChar
4697 [|&;<>()`\"' [:blank:]] / <newline>
4698
4699 The set of terminals of the grammar is the set of characters that can
4700 be handled on the environment in which the shell is run (a.k.a.
4701 execution character set), with the exception that the set does not
4702 contain the null character ('\0').
4703
4704 Strictly speaking, the definition above is not a complete parsing
4705 expression grammar because the rule for CommandSubstitution (Quoted)
4706 depends on CompleteProgram which is a non-terminal of the syntax.
4707
4708 Token classification
4709 After a word token is delimited, the token may be further
4710 classified as an IO_NUMBER token, reserved word, name word,
4711 assignment word, or just normal word. Classification other than the
4712 normal word is applied only when applicable in the context in which
4713 the word appears. See Tokens and keywords for the list of the
4714 reserved words (keywords) and the context in which a word may be
4715 recognized as a reserved word.
4716
4717 A token is an IO_NUMBER token iff it is composed of digit
4718 characters only and immediately followed by < or >.
4719
4720 An assignment token is a token that starts with a name followed by
4721 =:
4722
4723 AssignmentWord
4724 AssignmentPrefix Word
4725
4726 AssignmentPrefix
4727 Name =
4728
4729 Name
4730 ![[:digit:]] \[[:alnum:] _]+
4731
4732 Comments
4733 A comment begins with # and continues up to (but not including) the
4734 next newline character. Comments are treated like a blank character
4735 and do not become part of a token. The initial # of a comment must
4736 appear as if it would otherwise be the first character of a word
4737 token; Other #s are just treated as part of a word token.
4738
4739 Comment
4740 # (!<newline> .)*
4741
4742 Syntax
4743 After tokens have been delimited, the sequence of the tokens is parsed
4744 according to the context-free grammar defined below, where *, +, and ?
4745 should be interpreted in the same manner as standard regular
4746 expression:
4747
4748 CompleteProgram
4749 NL* | CompoundList
4750
4751 CompoundList
4752 NL* AndOrList ((; | & | NL) CompleteProgram)?
4753
4754 AndOrList
4755 Pipeline ((&& | ||) NL* Pipeline)*
4756
4757 Pipeline
4758 !? Command (| NL* Command)*
4759
4760 Command
4761 CompoundCommand Redirection* |
4762
4763 FunctionDefinition |
4764
4765 SimpleCommand
4766
4767 CompoundCommand
4768 Subshell |
4769
4770 Grouping |
4771
4772 IfCommand |
4773
4774 ForCommand |
4775
4776 WhileCommand |
4777
4778 CaseCommand |
4779
4780 DoubleBracketCommand |
4781
4782 FunctionCommand
4783
4784 Subshell
4785 ( CompoundList )
4786
4787 Grouping
4788 { CompoundList }
4789
4790 IfCommand
4791 if CompoundList then CompoundList (elif CompoundList then
4792 CompoundList)* (else CompoundList)? fi
4793
4794 ForCommand
4795 for Name ((NL* in Word*)? (; | NL) NL*)? do CompoundList done
4796
4797 WhileCommand
4798 (while | until) CompoundList do CompoundList done
4799
4800 CaseCommand
4801 case Word NL* in NL* CaseList? esac
4802
4803 CaseList
4804 CaseItem (;; NL* CaseList)?
4805
4806 CaseItem
4807 (? Word (| Word)* ) CompleteProgram
4808
4809 DoubleBracketCommand
4810 [[ Ors ]]
4811
4812 Ors
4813 Ands (|| Ands)*
4814
4815 Ands
4816 Nots (&& Nots)*
4817
4818 Nots
4819 !* Primary
4820
4821 Primary
4822 (-b | -c | -d | -e | -f | -G | -g | -h | -k | -L | -N | -n | -O |
4823 -o | -p | -r | -S | -s | -t | -u | -w | -x | -z) Word |
4824
4825 Word (-ef | -eq | -ge | -gt | -le | -lt | -ne | -nt | -ot | -veq |
4826 -vge | -vgt | -vle | -vlt | -vne | = | == | === | =~ | != | !== | <
4827 | >) Word |
4828
4829 ( Ors ) |
4830
4831 Word
4832
4833 FunctionCommand
4834 function Word (( ))? NL* CompoundCommand Redirection*
4835
4836 FunctionDefinition
4837 Name ( ) NL* CompoundCommand Redirection*
4838
4839 SimpleCommand
4840 (Assignment | Redirection) SimpleCommand? |
4841
4842 Word (Word | Redirection)*
4843
4844 Assignment
4845 AssignmentWord |
4846
4847 AssignmentPrefix( NL* (Word NL*)* )
4848
4849 Redirection
4850 IO_NUMBER? RedirectionOperator Word |
4851
4852 IO_NUMBER? <( CompleteProgram ) |
4853
4854 IO_NUMBER? >( CompleteProgram )
4855
4856 RedirectionOperator
4857 < | <> | > | >| | >> | >>| | <& | >& | << | <<- | <<<
4858
4859 NL
4860 <newline>
4861
4862 In the rule for Primary, Word tokens must not be ]]. Additionally, if a
4863 Primary starts with a Word, it must not be any of the possible unary
4864 operators allowed in the rule.
4865
4866 In the rule for SimpleCommand, a Word token is accepted only when the
4867 token cannot be parsed as the first token of an Assignment.
4868
4869 In the rule for Assignment, the ( token must immediately follow the
4870 AssignmentPrefix token, without any blank characters in between.
4871
4872 Here-document contents do not appear as part of the grammar above. They
4873 are parsed just after the newline (NL) token that follows the
4874 corresponding redirection operator.
4875
4876 Alias substitution
4877 Word tokens are subject to alias substitution.
4878
4879 • If a word is going to be parsed as a Word of a SimpleCommand,
4880 the word is subjected to alias substitution of any kind (normal
4881 and global aliases).
4882
4883 • If a word is the next token after the result of an alias
4884 substitution and the substitution string ends with a blank
4885 character, then the word is also subjected to alias
4886 substitution of any kind.
4887
4888 • Other words are subjected to global alias substitution unless
4889 the shell is in the POSIXly-correct mode.
4890
4891 Tokens that are classified as reserved words are not subject to
4892 alias substitution.
4893
4895 The alias built-in defines and/or prints aliases.
4896
4897 Syntax
4898 • alias [-gp] [name[=value]...]
4899
4900 Description
4901 The alias built-in defines and/or prints aliases as specified by
4902 operands. The printed aliases can be used as (part of) shell commands.
4903 The built-in prints all currently defined aliases when given no
4904 operands.
4905
4906 Options
4907 -g, --global
4908 With this option, aliases are defined as global aliases; without
4909 this option, as normal aliases.
4910
4911 -p, --prefix
4912 With this option, aliases are printed in a full command form like
4913 alias -g foo='bar'. Without this option, only command operands are
4914 printed like foo='bar'.
4915
4916 Operands
4917 name
4918 The name of an alias that should be printed.
4919
4920 name=value
4921 The name and value of an alias that is being defined.
4922
4923 Exit status
4924 The exit status of the alias built-in is zero unless there is any
4925 error.
4926
4927 Notes
4928 The characters that cannot be used in an alias name are the space, tab,
4929 newline, and any of =$<>\'"`;&|()#. You can use any characters in an
4930 alias value.
4931
4932 The alias built-in is a semi-special built-in.
4933
4934 The POSIX standard defines no options for the alias built-in, thus no
4935 options are available in the POSIXly correct mode.
4936
4938 The array built-in prints or modifies arrays.
4939
4940 Syntax
4941 • array
4942
4943 • array name [value...]
4944
4945 • array -d name [index...]
4946
4947 • array -i name index [value...]
4948
4949 • array -s name index value
4950
4951 Description
4952 When executed without any option or operands, the built-in prints all
4953 array definitions to the standard output in a form that can be parsed
4954 as commands.
4955
4956 When executed with name and values (but without an option), the
4957 built-in sets the values as the values of the array named name.
4958
4959 With the -d (--delete) option, the built-in removes the indexth values
4960 of the array named name. The number of values in the array will be
4961 decreased by the number of the indexes specified. If the indexth value
4962 does not exist, it is silently ignored.
4963
4964 With the -i (--insert) option, the built-in inserts values into the
4965 array named name. The number of values in the array will be increased
4966 by the number of the values specified. The values are inserted between
4967 the indexth and next values. If index is zero, the values are inserted
4968 before the first value. If index is larger than the number of values in
4969 the array, the values are appended after the last element.
4970
4971 With the -s (--set) option, the built-in sets value as the indexth
4972 value of the array named name. The array must have at least index
4973 values.
4974
4975 Options
4976 -d, --delete
4977 Delete array values.
4978
4979 -i, --insert
4980 Insert array values.
4981
4982 -s, --set
4983 Set an array value.
4984
4985 Operands
4986 name
4987 The name of an array to operate on.
4988
4989 index
4990 The index to an array element. The first element has the index of
4991 1.
4992
4993 value
4994 A string to which the array element is set.
4995
4996 Exit status
4997 The exit status of the array built-in is zero unless there is any
4998 error.
4999
5000 Notes
5001 The array built-in is not defined in the POSIX standard.
5002
5003 The command array name value... is equivalent to the assignment
5004 name=(value...).
5005
5007 The bg built-in resumes a job in the background.
5008
5009 Syntax
5010 • bg [job...]
5011
5012 Description
5013 The bg built-in sends the SIGCONT signal to the specified job. As a
5014 result, the job is resumed in the background (if it has been
5015 suspended).
5016
5017 The name of the job is printed when the job is resumed.
5018
5019 The built-in can be used only when job control is enabled.
5020
5021 Operands
5022 job
5023 The job ID of the job to be resumed.
5024
5025 More than one job can be specified at a time. The current job is
5026 resumed if none is specified.
5027
5028 The percent sign (%) at the beginning of a job ID can be omitted if
5029 the shell is not in the POSIXly-correct mode.
5030
5031 Exit status
5032 The exit status of the bg built-in is zero unless there is any error.
5033
5034 Notes
5035 The bg built-in is a semi-special built-in.
5036
5037 The POSIX standard provides that the built-in shall have no effect when
5038 the job is already running. The bg built-in of yash, however, always
5039 sends the SIGCONT signal to the job.
5040
5042 The bindkey built-in prints or modifies key bindings used in
5043 line-editing.
5044
5045 Syntax
5046 • bindkey -aev [key [command]]
5047
5048 • bindkey -l
5049
5050 Description
5051 When executed with the -l (--list) option, the built-in lists all
5052 available line-editing commands to the standard output.
5053
5054 When executed with one of the other options, the built-in prints or
5055 modifies key bindings for the editing mode specified by the option:
5056
5057 • Without key or command, all currently defined bindings are printed
5058 to the standard output in a form that can be parsed as commands
5059 that restore the current bindings when executed.
5060
5061 • With key but without command, only the binding for the given key is
5062 printed.
5063
5064 • With key and command, key is bound to command.
5065
5066 Options
5067 -a, --vi-command
5068 Print or modify bindings for the vi command mode.
5069
5070 -e, --emacs
5071 Print or modify bindings for the emacs mode.
5072
5073 -v, --vi-insert
5074 Print or modify bindings for the vi insert mode.
5075
5076 Operands
5077 key
5078 A character sequence of one or more keys that is bound to an
5079 editing command. The sequence may include escape sequences.
5080
5081 command
5082 A line-editing command to which key is bound. If command is a
5083 single hyphen (-), key is unbound.
5084
5085 Exit status
5086 The exit status of the bindkey built-in is zero unless there is any
5087 error.
5088
5089 Notes
5090 The bindkey built-in is a semi-special built-in. In the POSIX standard,
5091 it is defined as a command with unspecified behavior.
5092
5094 The break built-in aborts a loop being executed.
5095
5096 Syntax
5097 • break [nest]
5098
5099 • break -i
5100
5101 Description
5102 When executed without the -i (--iteration) option, the built-in aborts
5103 a currently executed for, while, or until loop. When executed in nested
5104 loops, it aborts the nestth innermost loop. The default nest is one. If
5105 the number of currently executed nested loops is less than nest, the
5106 built-in aborts the outermost loop.
5107
5108 When executed with the -i (--iteration) option, the built-in aborts the
5109 currently executed (innermost) iterative execution.
5110
5111 Options
5112 -i, --iteration
5113 Abort an iterative execution instead of a loop.
5114
5115 Operands
5116 nest
5117 The number of loops to abort, which must be a positive integer.
5118
5119 Exit status
5120 The exit status of the break built-in is:
5121
5122 • zero if a loop was successfully aborted.
5123
5124 • that of the command that was executed just before the break
5125 built-in if an iterative execution was successfully aborted.
5126
5127 Notes
5128 The break built-in is a special built-in.
5129
5130 The POSIX standard defines no options for the break built-in; the
5131 built-in accepts no options in the POSIXly-correct mode.
5132
5133 Treatment of currently executed loops that are not lexically enclosing
5134 the break built-in is unspecified in POSIX. Examples of such loops
5135 include:
5136
5137 • A loop invoking a function in which the break built-in is used.
5138
5139 • A loop in which a trap action is executed in which the break
5140 built-in is used.
5141
5142 Yash does not allow breaking such loops.
5143
5145 The cd built-in changes the working directory.
5146
5147 Syntax
5148 • cd [-L|-P] [directory]
5149
5150 Description
5151 The cd built-in changes the working directory to the directory
5152 specified by the operand.
5153
5154 The pathname of the new working directory is assigned to the PWD
5155 variable, whose previous value is again assigned to the OLDPWD
5156 variable. The new PWD value will not contain any . or .. components
5157 except when the shell is in the POSIXly-correct mode and the new
5158 pathname begins with /...
5159
5160 If directory is a relative path that does not start with ‘.’ or ‘..’,
5161 paths in the CDPATH variable are searched to find a new working
5162 directory. The search is done in a manner similar to the last step of
5163 command search, but a directory is sought instead of an executable
5164 regular file. If a new working directory was found from CDPATH, its
5165 pathname is printed to the standard output. If no applicable directory
5166 was found in the search, directory is simply treated as a pathname
5167 relative to the current working directory.
5168
5169 If the working directory was successfully changed, the value of the
5170 YASH_AFTER_CD variable is executed as a command unless the shell is in
5171 the POSIXly-correct mode. If the variable is an array, its values are
5172 executed iteratively (cf. eval built-in).
5173
5174 Options
5175 -L, --logical
5176 Symbolic links in the pathname of the new working directory are not
5177 resolved. The new value of the PWD may include pathname components
5178 that are symbolic links.
5179
5180 -P, --physical
5181 Symbolic links in the pathname of the new working directory are
5182 resolved. The new value of the PWD variable never includes pathname
5183 components that are symbolic links.
5184
5185 --default-directory=directory
5186 If this option is specified and the directory operand is omitted,
5187 the argument to this option is used for the directory operand. If
5188 the directory operand is specified, this option is ignored.
5189
5190 The -L (--logical) and -P (--physical) options are mutually exclusive:
5191 only the last specified one is effective. If neither is specified, -L
5192 is assumed.
5193
5194 Operands
5195 directory
5196 The pathname of the new working directory.
5197
5198 If directory is a single hyphen (‘-’), the value of the OLDPWD
5199 variable is assumed for the new directory pathname, which is
5200 printed to the standard output.
5201
5202 If directory is omitted, the working directory is changed to the
5203 directory specified by the --default-directory=... option. If that
5204 option is not specified either, the default is the home directory.
5205
5206 Exit status
5207 The exit status of the cd built-in is zero if the working directory was
5208 successfully changed and non-zero if there was an error.
5209
5210 Notes
5211 The cd built-in is a semi-special built-in.
5212
5213 The POSIX standard does not define the use of the YASH_AFTER_CD
5214 variable or the --default-directory=... option. The standard does not
5215 allow using an option with a single hyphen operand.
5216
5217 The exit status of the commands in the YASH_AFTER_CD variable does not
5218 affect that of the cd built-in.
5219
5221 The colon built-in does nothing.
5222
5223 Syntax
5224 • : [argument...]
5225
5226 Description
5227 The colon built-in does nothing. Any command line arguments are
5228 ignored.
5229
5230 Exit status
5231 The exit status of the colon built-in is zero.
5232
5233 Notes
5234 The colon built-in is a special built-in.
5235
5236 Arguments are expanded and redirections are performed as usual. The
5237 colon and true built-ins have the same effect, but colon is a special
5238 built-in while true is a semi-special.
5239
5241 The command built-in executes or identifies a command.
5242
5243 Syntax
5244 • command [-befp] command [argument...]
5245
5246 • command -v|-V [-abefkp] command...
5247
5248 Description
5249 Without the -v (--identify) or -V (--verbose-identify) option, the
5250 built-in executes command with arguments in the same manner as the last
5251 step of execution of simple commands. The command is treated as a
5252 built-in or external command or a function according to the options
5253 specified to the command built-in. The shell does not exit on argument
5254 syntax error etc. even if the command is a special built-in
5255
5256 With the -v (--identify) option, command is identified. If the command
5257 is found in $PATH, its full pathname is printed. If it is a keyword,
5258 function, or built-in that is not found in $PATH, the command name is
5259 simply printed. If it is an alias, it is printed in the form like alias
5260 ll='ls -l'. If the command is not found, nothing is printed and the
5261 exit status is non-zero.
5262
5263 The -V (--verbose-identify) option is similar to the -v (--identify)
5264 option, but the output format is more human-friendly.
5265
5266 Options
5267 -a, --alias
5268 Search for the command as an alias. Must be used with the -v
5269 (--identify) or -V (--verbose-identify) option.
5270
5271 -b, --builtin-command
5272 Search for the command as a built-in.
5273
5274 -e, --external-command
5275 Search for the command as an external command.
5276
5277 -f, --function
5278 Search for the command as a function.
5279
5280 -k, --keyword
5281 Search for the command as a keyword. Must be used with the -v
5282 (--identify) or -V (--verbose-identify) option.
5283
5284 -p, --standard-path
5285 Search the system’s default PATH instead of the current $PATH.
5286
5287 -v, --identify
5288 Identify commands and print in the format defined in the POSIX
5289 standard.
5290
5291 -V, --verbose-identify
5292 Identify commands and print in a human-friendly format.
5293
5294 If none of the -a (--alias), -b (--builtin-command), -e
5295 (--external-command), -f (--function), and -k (--keyword) options is
5296 specified, the following defaults are assumed:
5297
5298 Without the -v (--identify) or -V (--verbose-identify) option
5299 -b -e
5300
5301 With the -v (--identify) or -V (--verbose-identify) option
5302 -a -b -e -f -k
5303
5304 Operands
5305 command
5306 A command to be executed or identified.
5307
5308 argument...
5309 Arguments passed to the executed command.
5310
5311 Exit status
5312 The exit status of the command built-in is:
5313
5314 Without the -v (--identify) or -V (--verbose-identify) option
5315 the exit status of the executed command.
5316
5317 With the -v (--identify) or -V (--verbose-identify) option
5318 zero unless there is any error.
5319
5320 Notes
5321 The command built-in is a semi-special built-in.
5322
5323 In the POSIXly-correct mode, options other than -p, -v, and -V cannot
5324 be used and at most one command can be specified. The POSIX standard
5325 does not allow specifying both -v and -V together, but yash does (only
5326 the last specified one is effective).
5327
5329 The complete built-in generates completion candidates. This built-in
5330 can only be executed from completion functions during command line
5331 completion.
5332
5333 Syntax
5334 • complete [-A pattern] [-R pattern] [-T] [-P prefix] [-S suffix]
5335 [-abcdfghjkuv] [[-O] [-D description] word...]
5336
5337 Description
5338 The built-in generates completion candidates according to the specified
5339 arguments. No matter how candidates are generated, only candidates that
5340 match the word being completed are generated.
5341
5342 Options
5343 -A pattern, --accept=pattern
5344 Only accept candidates that match the pattern specified by this
5345 option. When more than one of this option is specified, only
5346 candidates that match all of the patterns are generated.
5347
5348 -D description, --description=description
5349 Give a description of the word candidates. The description is shown
5350 beside the candidates in the candidate list.
5351
5352 -O, --option
5353 The candidates are treated as command line options. A hyphen is
5354 prepended to each candidate that is treated as an option.
5355
5356 -P prefix, --prefix=prefix
5357 Ignore prefix of the word being completed when generating
5358 candidates. The specified prefix must be initial part of the word.
5359
5360 If the word being completed is file:///home/user/docume for
5361 example, the command line complete -P file:// -f will generate
5362 pathname candidates that complete /home/user/docume.
5363
5364 -R pattern, --reject=pattern
5365 Reject candidates that match the pattern specified by this option.
5366 When more than one of this option is specified, only candidates
5367 that match none of the patterns are generated.
5368
5369 -S suffix, --suffix=suffix
5370 Append suffix to each generated candidate.
5371
5372 -T, --no-termination
5373 Do not append a space after the word is completed. Without this
5374 option, a space is appended to the completed word so that you do
5375 not have to enter a space before the next word.
5376
5377 Options that select candidate types
5378 -a, --alias
5379 Aliases. (same as --normal-alias --global-alias)
5380
5381 --array-variable
5382 Arrays.
5383
5384 --bindkey
5385 Line-editing commands the bindkey built-in accepts.
5386
5387 -b, --builtin-command
5388 Built-in commands. (same as --special-builtin
5389 --semi-special-builtin --regular-builtin)
5390
5391 -c, --command
5392 Commands. (same as --builtin-command --external-command
5393 --function)
5394
5395 -d, --directory
5396 Directories.
5397
5398 --dirstack-index
5399 Valid indices of the directory stack.
5400
5401 --executable-file
5402 Executable regular files.
5403
5404 --external-command
5405 External commands.
5406
5407 -f, --file
5408 Files (including directories).
5409
5410 --finished-job
5411 Job IDs of finished jobs.
5412
5413 --function
5414 Functions.
5415
5416 --global-alias
5417 Global aliases.
5418
5419 -g, --group
5420 User groups.
5421
5422 -h, --hostname
5423 Host names.
5424
5425 -j, --job
5426 Job IDs.
5427
5428 -k, --keyword
5429 Keywords.
5430
5431 --normal-alias
5432 Normal aliases.
5433
5434 --regular-builtin
5435 Regular built-in commands.
5436
5437 --running-job
5438 Job IDs of jobs that are being executed.
5439
5440 --scalar-variable
5441 Variables that are not arrays.
5442
5443 --semi-special-builtin
5444 Semi-special built-in commands.
5445
5446 --signal
5447 Signals.
5448
5449 --special-builtin
5450 Special built-in commands.
5451
5452 --stopped-job
5453 Job IDs of jobs that are suspended.
5454
5455 -u, --username
5456 Users' log-in names.
5457
5458 -v, --variable
5459 Variables.
5460
5461 If the -d (--directory) option is specified without the -f (--file)
5462 option, the -S / -T options are assumed.
5463
5464 Generated candidates for job IDs do not have leading percent signs
5465 (%). If the word being completed starts with a percent sign, the -P
5466 % option should be specified.
5467
5468 Operands
5469 Operands are treated as completion candidates.
5470
5471 Exit status
5472 The exit status of the built-in is zero if one or more candidates were
5473 generated, one if no candidates were generated, or larger than one if
5474 an error occurred.
5475
5476 Notes
5477 The complete built-in is a semi-special built-in. In the POSIX
5478 standard, it is defined as a command with unspecified behavior.
5479
5481 The continue built-in skips an iteration of a loop being executed.
5482
5483 Syntax
5484 • continue [nest]
5485
5486 • continue -i
5487
5488 Description
5489 When executed without the -i (--iteration) option, the built-in aborts
5490 the current iteration of for, while, or until loop and starts the next
5491 iteration of the loop. When executed in nested loops, it affects the
5492 nestth innermost loop. The default nest is one. If the number of
5493 currently executed nested loops is less than nest, the built-in affects
5494 the outermost loop.
5495
5496 When executed with the -i (--iteration) option, the built-in aborts the
5497 current iteration of (innermost) iterative execution.
5498
5499 Options
5500 -i, --iteration
5501 Skip an iterative execution instead of a loop.
5502
5503 Operands
5504 nest
5505 The nestth innermost loop is affected. nest must be a positive
5506 integer.
5507
5508 Exit status
5509 The exit status of the continue built-in is:
5510
5511 • zero if loop iteration was successfully skipped.
5512
5513 • that of the command that was executed just before the continue
5514 built-in if iterative execution was successfully skipped.
5515
5516 Notes
5517 The continue built-in is a special built-in.
5518
5519 The POSIX standard defines no options for the continue built-in; the
5520 built-in accepts no options in the POSIXly-correct mode.
5521
5522 Treatment of currently executed loops that are not lexically enclosing
5523 the continue built-in is unspecified in POSIX. Examples of such loops
5524 include:
5525
5526 • A loop invoking a function in which the continue built-in is used
5527
5528 • A loop in which a trap action is executed in which the continue
5529 built-in is used
5530
5531 Yash does not allow continuing such loops.
5532
5534 The dirs built-in prints the contents of the directory stack.
5535
5536 Syntax
5537 • dirs [-cv] [index..]
5538
5539 Description
5540 The directory stack is a feature that records history of working
5541 directories. You can use the pushd built-in to save a working directory
5542 in the directory stack, the popd built-in to recall the saved working
5543 directory, and the dirs built-in to see the stack contents. Those
5544 built-ins use the DIRSTACK array and the PWD variable to save the stack
5545 contents. Modifying the array means modifying the stack contents.
5546
5547 Directory stack entries are indexed by signed integers. The entry of
5548 index +0 is the current working directory, +1 is the last saved
5549 directory, +2 is the second last, and so on. Negative indices are in
5550 the reverse order: the entry of index -0 is the first saved directory,
5551 -1 is the second, and -n is the current working directory if the stack
5552 has n entries,
5553
5554 When executed without the -c (--clear) option, the dirs built-in prints
5555 the current contents of the directory stack to the standard output.
5556 With the -c (--clear) option, the built-in clears the directory stack.
5557
5558 Options
5559 -c, --clear
5560 Clear the directory stack contents except for the current working
5561 directory, which has index +0.
5562
5563 -v, --verbose
5564 Print indices when printing stack contents.
5565
5566 Operands
5567 index
5568 The index of a stack entry to be printed.
5569
5570 You can specify more than one index. If you do not specify any
5571 index, all the entries are printed.
5572
5573 Exit status
5574 The exit status of the dirs built-in is zero unless there is any error.
5575
5576 Notes
5577 The dirs built-in is a semi-special built-in. In the POSIX standard, it
5578 is defined as a command with unspecified behavior.
5579
5581 The disown built-in removes jobs.
5582
5583 Syntax
5584 • disown [-a] [job...}
5585
5586 Description
5587 The disown built-in removes the specified jobs from the job list. The
5588 removed jobs will no longer be job-controlled, but the job processes
5589 continue execution (unless they have been suspended).
5590
5591 Options
5592 -a, --all
5593 Removes all jobs.
5594
5595 Operands
5596 job
5597 The job ID of the job to be removed.
5598
5599 You can specify more than one job ID. If you do not specify any job
5600 ID, the current job is removed. If the shell is not in the
5601 POSIXly-correct mode, the %-prefix of the job ID can be omitted.
5602
5603 Exit status
5604 The exit status of the disown built-in is zero unless there is any
5605 error.
5606
5607 Notes
5608 The disown built-in is a semi-special built-in. In the POSIX standard,
5609 it is defined as a command with unspecified behavior.
5610
5612 The dot built-in reads a file and executes commands in it.
5613
5614 Syntax
5615 • . [-AL] file [argument...]
5616
5617 Description
5618 The dot built-in reads the specified file, parses its contents as
5619 commands, and executes them in the current command execution
5620 environment.
5621
5622 If arguments are specified, positional parameters are temporarily set
5623 to them. The positional parameters will be restored when the dot
5624 built-in finishes. If no arguments are specified, the positional
5625 parameters are not changed.
5626
5627 If file does not contain any slashes, the shell searches $PATH for a
5628 readable (but not necessarily executable) shell script file whose name
5629 is file in the same manner as command search. If no such file was
5630 found, the shell searches the current working directory for a file
5631 unless in the POSIXly-correct mode. To ensure that the file in the
5632 current working directory is used, start file with ‘./’.
5633
5634 Options
5635 -A, --no-alias
5636 Disable alias substitution while parsing.
5637
5638 -L, --autoload
5639 Search $YASH_LOADPATH instead of $PATH, regardless of whether file
5640 contains slashes. The file value is not considered relative to the
5641 current working directory.
5642
5643 The dot built-in treats as operands any command line arguments after
5644 the first operand.
5645
5646 Operands
5647 file
5648 The pathname of a file to be read.
5649
5650 arguments...
5651 Strings to which positional parameters are set while execution.
5652
5653 Exit status
5654 The exit status of the dot built-in is that of the last command
5655 executed. The exit status is zero if the file contains no commands to
5656 execute and non-zero if a file was not found or could not be opened.
5657
5658 Notes
5659 The dot built-in is a special built-in.
5660
5661 A non-interactive shell immediately exits with a non-zero exit status
5662 if the dot built-in fails to find or open a file to execute.
5663
5664 The POSIX standard defines no options for the dot built-in; the
5665 built-in accepts no options in the POSIXly-correct mode.
5666
5667 The POSIX standard does not define the arguments... operands. It is an
5668 error to specify the arguments... operands in the POSIXly-correct mode.
5669
5671 The echo built-in prints its arguments.
5672
5673 Syntax
5674 • echo [string...]
5675
5676 The built-in treats all command line arguments as operands except for
5677 the options described below. Any word that cannot be parsed as an
5678 acceptable option is treated as an operand. Options must precede all
5679 operands. Syntax errors never happen in the echo built-in.
5680
5681 Description
5682 The echo built-in prints the operand strings followed by a newline to
5683 the standard output. The strings are each separated by a space.
5684
5685 Escape sequences
5686 The ECHO_STYLE variable and the -e option enable escape sequences
5687 that are replaced with corresponding characters:
5688
5689 \a
5690 Bell character (ASCII code: 7)
5691
5692 \b
5693 Backspace (ASCII code: 8)
5694
5695 \c
5696 Nothing. After this escape sequence, no characters are printed
5697 at all.
5698
5699 \e
5700 Escape character (ASCII code: 27)
5701
5702 \f
5703 Form feed character (ASCII code: 12)
5704
5705 \n
5706 Newline character (ASCII code: 10)
5707
5708 \r
5709 Carriage return character (ASCII code: 13)
5710
5711 \t
5712 Horizontal tab character (ASCII code: 9)
5713
5714 \v
5715 Vertical tab character (ASCII code: 11)
5716
5717 \\
5718 Backslash
5719
5720 \0xxx
5721 Character whose code is xxx, where xxx is an octal number of at
5722 most three digits.
5723
5724 When escape sequences are not enabled, they are just printed
5725 intact.
5726
5727 ECHO_STYLE variable
5728 The ECHO_STYLE variable defines which options are accepted and
5729 whether escape sequences are enabled by default. The variable value
5730 should be set to one of the following:
5731
5732 SYSV, XSI
5733 No options are accepted. Escape sequences are always enabled.
5734
5735 BSD
5736 The -n option is accepted. Escape sequences are never enabled.
5737
5738 GNU
5739 The -n, -e, and -E options are accepted. Escape sequences are
5740 not enabled by default, but can be enabled by the -e option.
5741
5742 ZSH
5743 The -n, -e, and -E options are accepted. Escape sequences are
5744 enabled by default, but can be disabled by the -E option.
5745
5746 DASH
5747 The -n option is accepted. Escape sequences are always enabled.
5748
5749 RAW
5750 No options are accepted. Escape sequences are never enabled.
5751
5752 When the ECHO_STYLE variable is not set, it defaults to SYSV.
5753
5754 Options
5755 -n
5756 Do not print a newline at the end.
5757
5758 -e
5759 Enable escape sequences.
5760
5761 -E
5762 Disable escape sequences.
5763
5764 Exit status
5765 The exit status of the echo built-in is zero unless there is any error.
5766
5767 Notes
5768 The POSIX standard does not define the ECHO_STYLE variable nor any
5769 options for the built-in. According to POSIX, the behavior of the
5770 built-in is implementation-defined when the first argument is -n or
5771 when any argument contains a backslash. For maximum portability, the
5772 printf built-in should be preferred over the echo built-in.
5773
5774 Although many values for the ECHO_STYLE variable are defined on the
5775 basis of other existing implementations, yash is not intended to
5776 exactly imitate those originals. Zsh’s echo built-in interprets a
5777 single hyphen argument as a separator between options and operands.
5778 Yash does not support such use of hyphen.
5779
5781 The eval built-in evaluates operands as commands.
5782
5783 Syntax
5784 • eval [-i] [command...]
5785
5786 The eval built-in requires that all options precede operands. Any
5787 command line arguments after the first operand are all treated as
5788 operands.
5789
5790 Description
5791 The eval parses operands as commands and executes them in the current
5792 command execution environment.
5793
5794 When executed without the -i (--iteration) option, all the operands are
5795 concatenated into one string (with a space inserted between each
5796 operand) and parsed/executed at once.
5797
5798 With the -i (--iteration) option, the built-in performs iterative
5799 execution: operands are parsed/executed one by one. If the continue
5800 built-in is executed with the -i (--iteration) option during the
5801 iterative execution, the execution of the current operand is aborted
5802 and the next operand is parsed/executed immediately. The break built-in
5803 with the -i (--iteration) option is similar but the remaining operands
5804 are not parsed/executed. The value of the ? special parameter is saved
5805 before the iterative execution is started. The parameter value is
5806 restored to the saved one after each iteration.
5807
5808 Options
5809 -i, --iteration
5810 Perform iterative execution.
5811
5812 Operands
5813 command
5814 A string that is parsed and executed as commands.
5815
5816 Exit status
5817 The exit status is zero if no command was specified or command
5818 contained no actual command that can be executed. Otherwise, that is,
5819 if the eval built-in executed one or more commands, the exit status of
5820 the eval built-in is that of the last executed command.
5821
5822 Notes
5823 The eval built-in is a special built-in.
5824
5825 The POSIX standard defines no options for the eval built-in; the
5826 built-in accepts no options in the POSIXly-correct mode.
5827
5829 The exec built-in replaces the shell process with another external
5830 command.
5831
5832 Syntax
5833 • exec [-cf] [-a name] [command [argument...]]
5834
5835 The exec built-in requires that all options precede operands. It is
5836 important so that options to the exec built-in are not confused with
5837 options to command. Any command line arguments after command are
5838 treated as arguments.
5839
5840 Description
5841 When the exec built-in is executed with command, the shell executes
5842 command with arguments in a manner similar to the last step of
5843 execution of a simple command. The differences are that command is
5844 always treated as an external command ignoring any existing functions
5845 and built-ins and that the exec system call that starts the external
5846 command is called in the current command execution environment instead
5847 of a subshell, replacing the shell process with the new command
5848 process.
5849
5850 If the shell is in the POSIXly-correct mode or not interactive, failure
5851 in execution of command causes the shell to exit immediately.
5852
5853 If an interactive shell that is not in the POSIXly-correct mode has a
5854 stopped job, the shell prints a warning message and refuses to execute
5855 command. Once the shell process is replaced with an external command,
5856 information about the shell’s jobs is lost, so you will have to resume
5857 or kill the stopped jobs by sending signals by hand. To force the shell
5858 to execute command regardless, specify the -f (--force) option.
5859
5860 When executed without command, the built-in does nothing. As a side
5861 effect, however, redirection applied to the built-in remains in the
5862 current command execution environment even after the built-in finished.
5863
5864 Options
5865 -a name, --as=name
5866 Pass name, instead of command, to the external command as its name.
5867
5868 -c, --clear
5869 Pass to the external command only variables that are assigned in
5870 the simple command in which the built-in is being executed. Other
5871 environment variables are not passed to the command.
5872
5873 -f, --force
5874 Suppress warnings that would prevent command execution.
5875
5876 Operands
5877 command
5878 An external command to be executed.
5879
5880 argument...
5881 Arguments to be passed to the command.
5882
5883 Exit status
5884 If the shell process was successfully replaced with the external
5885 command, there is no exit status since the shell process no longer
5886 exists.
5887
5888 The exit status is:
5889
5890 • 127 if the command was not found,
5891
5892 • 126 if the command was found but could not be executed, and
5893
5894 • zero if no command was specified.
5895
5896 Notes
5897 The exec built-in is a special built-in.
5898
5899 The POSIX standard defines no options for the exec built-in; the
5900 built-in accepts no options in the POSIXly-correct mode.
5901
5903 The exit built-in causes the shell process to exit.
5904
5905 Syntax
5906 • exit [-f] [exit_status]
5907
5908 Description
5909 The exit built-in causes the current shell (or subshell) process to
5910 exit.
5911
5912 If an interactive shell has a stopped job, the shell prints a warning
5913 message and refuses to exit. To force the shell to exit regardless,
5914 specify the -f (--force) option or execute the built-in twice in a row.
5915
5916 If an EXIT trap has been set, the shell executes the trap before
5917 exiting.
5918
5919 Options
5920 -f, --force
5921 Suppress warnings that would prevent the shell from exiting.
5922
5923 Operands
5924 exit_status
5925 A non-negative integer that will be the exit status of the exiting
5926 shell.
5927
5928 If this operand is omitted, the exit status of the shell will be
5929 that of the last command executed before the exit built-in (but, if
5930 the built-in is executed during a trap, the exit status will be
5931 that of the last command before the trap is entered).
5932
5933 If exit_status is 256 or larger, the actual exit status will be the
5934 remainder of exit_status divided by 256.
5935
5936 Exit status
5937 Because the built-in causes the shell to exit, there is no exit status
5938 of the built-in.
5939
5940 As an exception, if the shell refused to exit, the exit status of the
5941 built-in is non-zero.
5942
5943 Notes
5944 The exit built-in is a special built-in.
5945
5946 The POSIX standard defines no options for the exit built-in; the
5947 built-in accepts no options in the POSIXly-correct mode.
5948
5949 The POSIX standard provides that the exit_status operand should be
5950 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
5951 an extension.
5952
5953 If the built-in is executed during an EXIT trap, the shell just exits
5954 without executing the trap again. If exit_status was not specified, the
5955 exit status of the shell is what the exit status would be if the trap
5956 had not been set. See also Termination of the shell.
5957
5959 The export built-in marks variables for export to child processes.
5960
5961 Syntax
5962 • export [-prX] [name[=value]...]
5963
5964 Description
5965 The export built-in is equivalent to the typeset built-in with the -gx
5966 option.
5967
5968 Notes
5969 The export built-in is a special built-in.
5970
5971 The POSIX standard defines the -p option only; other options cannot be
5972 used in the POSIXly-correct mode. The POSIX does not allow using the
5973 option together with operands.
5974
5976 The false built-in does nothing unsuccessfully.
5977
5978 Syntax
5979 • false
5980
5981 Description
5982 The false built-in does nothing. Any command line arguments are
5983 ignored.
5984
5985 Exit status
5986 The exit status of the false built-in is non-zero.
5987
5988 Notes
5989 The false built-in is a semi-special built-in.
5990
5992 The fc built-in re-executes or prints commands from command history.
5993
5994 Syntax
5995 • fc [-qr] [-e editor] [start [end]]
5996
5997 • fc -s[q] [old=new] [start]
5998
5999 • fc -l[nrv] [start [end]]
6000
6001 Description
6002 When executed without the -l (--list) option, the built-in executes the
6003 commands in the command history range specified by the operands. If the
6004 -s (--silent) option is not specified, the shell invokes an editor
6005 which allows you to edit the commands before they are executed. The
6006 commands are executed when you quit the editor. If the -s (--silent)
6007 option is specified, the commands are immediately executed. In either
6008 case, the executed commands are printed to the standard output and
6009 added to the history.
6010
6011 When executed with the -l (--list) option, the built-in prints the
6012 commands in the command history range specified by the operands. By
6013 default, commands are printed with their history entry numbers, but
6014 output format can be changed using the -n (--no-numbers)) and -v
6015 (--verbose) options.
6016
6017 Options
6018 -e editor, --editor=editor
6019 Specify an editor that is used to edit commands.
6020
6021 If this option is not specified, the value of the FCEDIT variable
6022 is used. If the variable is not set either, ed is used.
6023
6024 -l, --list
6025 Print command history entries.
6026
6027 -n, --no-numbers
6028 Don’t print entry numbers when printing history entries.
6029
6030 -q, --quiet
6031 Don’t print commands before executing.
6032
6033 -r, --reverse
6034 Reverse the order of command entries in the range.
6035
6036 -s, --silent
6037 Execute commands without editing them.
6038
6039 -v, --verbose
6040 Print execution time before each history entry when printing.
6041
6042 Operands
6043 start and end
6044 The start and end operands specify a range of command history
6045 entries that are executed or printed. If one of the operands is an
6046 integer, it is treated as a history entry number. A negative
6047 integer means the nth most recent entry where n is the absolute
6048 value of the integer. If one of the operands is not an integer, it
6049 is treated as part of a command string: the most recent entry that
6050 starts with the string is selected as the start or end of the
6051 range.
6052
6053 If the first entry of the range that is specified by start is newer
6054 than the last entry of the range that is specified by end, the
6055 range is reversed as if the -r (--reverse) option was specified.
6056 (If the option is already specified, it is cancelled.)
6057
6058 The default values for start and end are:
6059
6060 ┌──────┬─────────┬───────────────┐
6061 │ │ with -l │ without -l │
6062 ├──────┼─────────┼───────────────┤
6063 │start │ -16 │ -1 │
6064 ├──────┼─────────┼───────────────┤
6065 │end │ -16 │ same as start │
6066 └──────┴─────────┴───────────────┘
6067
6068 old=new
6069 An operand of this format replaces part of the command string. If
6070 the command string contains old, it is replaced with new and the
6071 new string is executed. Only the first occurrence of old is
6072 replaced.
6073
6074 Exit status
6075 If commands was executed, the exit status of the fc built-in is that of
6076 the last executed command. Otherwise, the exit status is zero unless
6077 there is any error.
6078
6079 Notes
6080 The fc built-in is a semi-special built-in.
6081
6082 The POSIX standard does not define the -q (--quiet) or -v (--verbose)
6083 options, so they cannot be used in the POSIXly-correct mode.
6084
6085 Command history cannot be modified during line-editing.
6086
6088 The fg built-in resumes a job in the foreground.
6089
6090 Syntax
6091 • fg [job...]
6092
6093 Description
6094 The fg built-in brings the specified job to the foreground and sends
6095 the SIGCONT signal to the job. As a result, the job is resumed in the
6096 foreground (if it has been suspended). The built-in then waits for the
6097 job to finish and returns the exit status of it.
6098
6099 The name of the job is printed when the job is resumed. When not in the
6100 POSIXly-correct mode, the job number is also printed.
6101
6102 The built-in can be used only when job control is enabled.
6103
6104 Operands
6105 job
6106 The job ID of the job to be resumed.
6107
6108 If more than one job is specified, they are resumed in order, one
6109 at a time. The current job is resumed if none is specified.
6110
6111 The percent sign (%) at the beginning of a job ID can be omitted if
6112 the shell is not in the POSIXly-correct mode.
6113
6114 Exit status
6115 The exit status of the fg built-in is that of the (last) job resumed.
6116 The exit status is non-zero when there was some error.
6117
6118 Notes
6119 The fg built-in is a semi-special built-in.
6120
6121 You cannot specify more than one job in the POSIXly-correct mode.
6122
6124 The getopts built-in parses command options.
6125
6126 Syntax
6127 • getopts optionlist variable [argument...]
6128
6129 Description
6130 The getopts built-in parses single-character options that appear in
6131 arguments. Each time the built-in is invoked, it parses one option and
6132 assigns the option character to variable.
6133
6134 The optionlist operand is a list of option characters that should be
6135 accepted by the parser. In optionlist, an option that takes an argument
6136 should be specified as the option character followed by a colon. For
6137 example, if you want the -a, -b and -c options to be parsed and the -b
6138 option to take an argument, then optionlist should be ab:c.
6139
6140 When an option that takes an argument is parsed, the argument is
6141 assigned to the OPTARG variable.
6142
6143 When an option that is not specified in optionlist is found or when an
6144 option argument is missing, the result depends on the first character
6145 of optionlist:
6146
6147 • If optionlist starts with a colon, the option character is assigned
6148 to the OPTARG variable and variable is set to either ? (when the
6149 option is not in optionlist) or : (when the option argument is
6150 missing).
6151
6152 • Otherwise, variable is set to ?, the OPTARG variable is unset, and
6153 an error message is printed.
6154
6155 The built-in parses one option for each execution. For all options in a
6156 set of command line arguments to be parsed, the built-in has to be
6157 executed repeatedly with the same arguments. The built-in uses the
6158 OPTIND variable to remember which argument should be parsed next. When
6159 the built-in is invoked for the first time, the variable value must be
6160 1, which is the default value. You must not modify the variable until
6161 all the options have been parsed, when the built-in sets the variable
6162 to the index of the first operand in arguments. (If there are no
6163 operands, it will be set to the number of arguments plus one.)
6164
6165 When you want to start parsing a new set of arguments, you have to
6166 reset the OPTIND variable to 1 beforehand.
6167
6168 Operands
6169 optionlist
6170 A list of options that should be accepted as valid options in
6171 parsing.
6172
6173 variable
6174 The name of a variable the result is to be assigned to.
6175
6176 arguments
6177 Command line arguments that are to be parsed.
6178
6179 When no arguments are given, the positional parameters are parsed.
6180
6181 Exit status
6182 If an option is found, whether or not it is specified in optionlist,
6183 the exit status is zero. If there is no more option to be parsed, the
6184 exit status is non-zero.
6185
6186 Example
6187 aopt=false bopt= copt=false
6188 while getopts ab:c opt
6189 do
6190 case $opt in
6191 a) aopt=true ;;
6192 b) bopt=$OPTARG ;;
6193 c) copt=true ;;
6194 \?) return 2 ;;
6195 esac
6196 done
6197 if $aopt; then echo Option -a specified; fi
6198 if [ -n "$bopt" ]; then echo Option -b $bopt specified; fi
6199 if $copt; then echo Option -c specified; fi
6200 shift $((OPTIND - 1))
6201 echo Operands are: $*
6202
6203 Notes
6204 In arguments that are parsed, options must precede operands. The
6205 built-in ends parsing when it encounters the first operand.
6206
6207 The getopts built-in is a semi-special built-in.
6208
6209 The POSIX standard does not specify what will happen when the OPTIND
6210 variable is assigned a value other than 1.
6211
6212 In the POSIXly-correct mode, option characters in optionlist must be
6213 alphanumeric.
6214
6216 The hash built-in remembers, forgets, or reports command locations.
6217
6218 Syntax
6219 • hash command...
6220
6221 • hash -r [command...]
6222
6223 • hash [-a]
6224
6225 • hash -d user...
6226
6227 • hash -dr [user...]
6228
6229 • hash -d
6230
6231 Description
6232 When executed with commands but without options, the built-in
6233 immediately performs command path search and caches commands' full
6234 paths.
6235
6236 When executed with the -r (--remove) option, it removes the paths of
6237 commands (or all cached paths if none specified) from the cache.
6238
6239 When executed without options or commands, it prints the currently
6240 cached paths to the standard output.
6241
6242 With the -d (--directory) option, the built-in does the same things to
6243 the home directory cache, rather than the command path cache. Cached
6244 home directory paths are used in tilde expansion.
6245
6246 Options
6247 -a, --all
6248 Print all cached paths.
6249
6250 Without this option, paths for built-ins are not printed.
6251
6252 -d, --directory
6253 Affect the home directory cache instead of the command path cache.
6254
6255 -r, --remove
6256 Remove cached paths.
6257
6258 Operands
6259 command
6260 The name of an external command (that does not contain any slash).
6261
6262 user
6263 A user name.
6264
6265 Exit status
6266 The exit status of the hash built-in is zero unless there is any error.
6267
6268 Notes
6269 The shell automatically caches command and directory paths when
6270 executing a command or performing tilde expansion, so normally there is
6271 no need to use this built-in explicitly to cache paths.
6272
6273 Assigning a value to the PATH variable removes all command paths from
6274 the cache as if hash -r was executed.
6275
6276 The POSIX standard defines the -r option only: other options cannot be
6277 used in the POSIXly-correct mode.
6278
6279 The hash built-in is a semi-special built-in.
6280
6282 The help built-in prints usage of built-ins.
6283
6284 Syntax
6285 • help [built-in...]
6286
6287 Description
6288 The help built-in prints a description of built-ins.
6289
6290 Operands
6291 built-ins
6292 Names of built-ins.
6293
6294 Exit status
6295 The exit status of the help built-in is zero unless there is any error.
6296
6297 Notes
6298 The help built-in is a semi-special built-in. In the POSIX standard, it
6299 is defined as a command with unspecified behavior.
6300
6301 Many built-ins of yash accept the --help option that prints the same
6302 description.
6303
6305 The history built-in prints or edits command history.
6306
6307 Syntax
6308 • history [-cF] [-d entry] [-s command] [-r file] [-w file] [count]
6309
6310 Description
6311 The history built-in prints or edits command history.
6312
6313 When executed with an option, the built-in edits history according to
6314 the option. If more than one option is specified, each option is
6315 processed in order.
6316
6317 When executed with the count operand, the built-in prints the most
6318 recent count history entries to the standard output in the same manner
6319 as the fc built-in.
6320
6321 When executed with neither options nor operands, the built-in prints
6322 the whole history.
6323
6324 Options
6325 -c, --clear
6326 Clear all history entries completely.
6327
6328 -d entry, --delete=entry
6329 Delete the specified entry. The entry should be specified in the
6330 same manner as the start and end operands of the fc built-in.
6331
6332 -F, --flush-file
6333 Rebuild the history file. This operation removes unused old data
6334 from the file.
6335
6336 -r file, --read=file
6337 Read command lines from file and add them to the history. The file
6338 contents are treated as lines of simple text.
6339
6340 -s command, --set=command
6341 Add command as a new history entry after removing the most recent
6342 entry.
6343
6344 -w file, --write=file
6345 Write the whole history to file. Any existing data in the file will
6346 be lost. The output format is lines of simple text, each of which
6347 is a command string.
6348
6349 Operands
6350 count
6351 The number of entries to be printed.
6352
6353 Exit status
6354 The exit status of the history built-in is zero unless there is any
6355 error.
6356
6357 Notes
6358 The history built-in is a semi-special built-in. In the POSIX standard,
6359 it is defined as a command with unspecified behavior.
6360
6361 Command history cannot be modified during line-editing.
6362
6364 The jobs built-in reports job status.
6365
6366 Syntax
6367 • jobs [-lnprs] [job...]
6368
6369 Description
6370 The jobs built-in prints information of jobs the shell is currently
6371 controlling.
6372
6373 By default, the following information is printed for each job, line by
6374 line:
6375
6376 • the job number,
6377
6378 • the + or - symbol if the job is the current or previous job,
6379 respectively,
6380
6381 • the status, and
6382
6383 • the command string.
6384
6385 Options
6386 -l, --verbose
6387 Print the process ID, status, and command string for each process
6388 in the jobs.
6389
6390 -n, --new
6391 Print new jobs only: jobs whose status has never been reported
6392 since the status changed.
6393
6394 -p, --pgid-only
6395 Print process group IDs of jobs only.
6396
6397 -r, --running-only
6398 Print running jobs only.
6399
6400 -s, --stopped-only
6401 Print stopped jobs only.
6402
6403 Operands
6404 jobs
6405 The job IDs of jobs to be reported. When no job is specified, all
6406 jobs under the shell’s control are reported.
6407
6408 The percent sign (%) at the beginning of a job ID can be omitted if
6409 the shell is not in the POSIXly-correct mode.
6410
6411 Exit status
6412 The exit status of the jobs built-in is zero unless there is any error.
6413
6414 Notes
6415 The jobs built-in is a semi-special built-in.
6416
6417 The POSIX standard defines the -l and -p options only: other options
6418 cannot be used in the POSIXly-correct mode. In the POSIXly-correct
6419 mode, the effect of the -l option is different in that status is
6420 reported for each job rather than for each process.
6421
6422 The process group ID of a job executed by yash is equal to the process
6423 ID of the first command of the pipeline that forms the job.
6424
6426 The kill built-in sends a signal to processes.
6427
6428 Syntax
6429 • kill [-signal|-s signal|-n signal] process...
6430
6431 • kill -l [-v] [signal...]
6432
6433 The kill built-in requires that all options precede operands. Any
6434 command line arguments after the first operand are all treated as
6435 operands.
6436
6437 Description
6438 When executed without the -l option, the built-in sends a signal to
6439 processes. The signal sent can be specified by option. The SIGTERM
6440 signal is sent if no signal is specified.
6441
6442 When executed with the -l option, the built-in prints information of
6443 signals to the standard output. If no signal is specified, information
6444 of all signals is printed.
6445
6446 Options
6447 Signal-specifying options
6448 -signal, -s signal, -n signal
6449 A signal-specifying option specifies a signal to be sent to
6450 processes. signal can be specified by name or number. If
6451 number 0 is specified, the built-in checks if a signal could be
6452 sent to the processes but no signal is actually sent. Signal
6453 names are case-insensitive.
6454
6455 You can specify at most one signal-specifying option at a time.
6456
6457 Other options
6458 -l
6459 Print signal information instead of sending a signal.
6460
6461 -v
6462 Print more signal information.
6463
6464 Without this option, the built-in prints the signal name only.
6465 This option adds the signal number and a short description.
6466
6467 When the -v option is specified, the -l option can be omitted.
6468
6469 Operands
6470 processes
6471 Specify processes to which a signal is sent.
6472
6473 Processes can be specified by the process ID, the process group ID,
6474 or the job ID. The process group ID must be prefixed with a hyphen
6475 (-) so that it is not treated as a process ID.
6476
6477 When 0 is specified as process, the signal is sent to the process
6478 group to which the shell process belongs. When -1 is specified, the
6479 signal is sent to all processes on the system.
6480
6481 signal
6482 Specify a signal of which information is printed.
6483
6484 The signal can be specified by the name, the number, or the exit
6485 status of a command that was killed by the signal.
6486
6487 Exit status
6488 The exit status of the kill built-in is zero unless there is any error.
6489 If the signal was sent to at least one process, the exit status is zero
6490 even if the signal was not sent to all of the specified processes.
6491
6492 Notes
6493 The kill built-in is a semi-special built-in.
6494
6495 Command arguments that start with a hyphen should be used with care.
6496 The command kill -1 -2, for example, sends signal 1 to process group 2
6497 since -1 is treated as a signal-specifying option and -2 as an operand
6498 that specifies a process group. The commands kill -- -1 -2 and kill
6499 -TERM -1 -2, on the other hand, treats both -1 and -2 as operands.
6500
6501 The POSIX standard does not define the -n or -v options, so they cannot
6502 be used in the POSIXly-correct mode. The standard does not allow
6503 specifying a signal number as the argument of the -s option or a signal
6504 name as the signal operand.
6505
6506 The standard requires signal names to be specified without the SIG
6507 prefix, like INT and QUIT. If the shell is not in the POSIXly-correct
6508 mode, the built-in accepts SIG-prefixed signal names as well.
6509
6511 The local built-in prints or sets local variables.
6512
6513 Syntax
6514 • local [-rxX] [name[=value]...]
6515
6516 Description
6517 The local built-in is equivalent to the typeset built-in except that
6518 the -f (--functions) and -g (--global) options cannot be used.
6519
6520 Notes
6521 The local built-in is a semi-special built-in. In the POSIX standard,
6522 it is defined as a command with unspecified behavior.
6523
6525 The popd built-in pops a directory from the directory stack.
6526
6527 Syntax
6528 • popd [index]
6529
6530 Description
6531 The popd built-in removes the last entry from the directory stack,
6532 returning to the previous working directory. If index is given, the
6533 entry specified by index is removed instead of the last one.
6534
6535 Operands
6536 index
6537 The index of a directory stack entry you want to remove.
6538
6539 If omitted, +0 (the last entry) is assumed.
6540
6541 Exit status
6542 The exit status of the popd built-in is zero unless there is any error.
6543
6544 Notes
6545 It is an error to use this built-in when there is only one directory
6546 stack entry.
6547
6548 The popd built-in is a semi-special built-in. In the POSIX standard, it
6549 is defined as a command with unspecified behavior.
6550
6552 The printf built-in prints formatted values.
6553
6554 Syntax
6555 • printf format [value...]
6556
6557 Description
6558 The printf built-in formats values according to format and prints them
6559 to the standard output. Unlike the echo built-in, the printf built-in
6560 does not print a newline automatically.
6561
6562 The formatting process is very similar to that of the printf function
6563 in the C programming language. You can use conversion specifications
6564 (which start with %) and escape sequences (which start with \) in
6565 format. Any other characters that are not part of a conversion
6566 specification or escape sequence are printed literally.
6567
6568 Conversion specifications
6569 A conversion specification starts with a percent sign (%).
6570
6571 A conversion specification except %% consumes a value, which is
6572 formatted according to the specification and printed. Each
6573 conversion specification consumes one value in the order of
6574 appearance. If there are more values than conversion
6575 specifications, the entire format is re-processed until all the
6576 values are consumed. If a value to be consumed is missing, it is
6577 assumed to be an empty string (if the specification requires a
6578 string) or zero (if a number). If no values are given, format is
6579 processed just once.
6580
6581 Available conversion specifications are:
6582
6583 %d, %i
6584 prints a signed integer in decimal
6585
6586 %u
6587 prints an unsigned integer in decimal
6588
6589 %o
6590 prints an unsigned integer in octal
6591
6592 %x
6593 prints an unsigned integer in lowercase hexadecimal
6594
6595 %X
6596 prints an unsigned integer in uppercase hexadecimal
6597
6598 %f
6599 prints a floating-point number in lowercase
6600
6601 %F
6602 prints a floating-point number in uppercase
6603
6604 %e
6605 prints a floating-point number with exponent in lowercase
6606
6607 %E
6608 prints a floating-point number with exponent in uppercase
6609
6610 %g
6611 the same as %f or %e, automatically selected
6612
6613 %G
6614 the same as %F or %E, automatically selected
6615
6616 %c
6617 prints the first character of string
6618
6619 %s
6620 prints a string
6621
6622 %b
6623 prints a string (recognizing escape sequences like the echo
6624 built-in)
6625
6626 %%
6627 prints a percent sign (%)
6628
6629 For %g and %G, the specification that is actually used is %f or %F
6630 if the exponent part is between -5 and the precision (exclusive);
6631 %e or %E otherwise.
6632
6633 In a conversion specification except %%, the leading percent sign
6634 may be followed by flags, field width, and/or precision in this
6635 order.
6636
6637 The flags are a sequence of any number of the following characters:
6638
6639 Minus sign (-)
6640 With this flag, spaces are appended to the formatted value to
6641 fill up to the field width. Otherwise, spaces are prepended.
6642
6643 Plus sign (+)
6644 A plus or minus sign is always prepended to a number.
6645
6646 Space ( )
6647 A space is prepended to a formatted number if it has no plus or
6648 minus sign.
6649
6650 Hash sign (#)
6651 The value is formatted in an alternative form: For %o, the
6652 printed octal integer has at least one leading zero. For %x and
6653 %X, a non-zero integer is formatted with 0x and 0X prefixes,
6654 respectively. For %e, %E, %f, %F, %g, and %G, a decimal mark
6655 (a.k.a. radix character) is always printed even if the value is
6656 an exact integer. For %g and %G, the printed number has at
6657 least one digit in the fractional part.
6658
6659 Zero (0)
6660 Zeros are prepended to a formatted number to fill up to the
6661 field width. This flag is ignored if the minus flag is
6662 specified or if the conversion specification is %d, %i, %u, %o,
6663 %x, or %X with a precision.
6664
6665 A field width is specified as a decimal integer that has no leading
6666 zeros.
6667
6668 A field width defines a minimum byte count of a formatted value. If
6669 the formatted value does not reach the minimum byte count, so many
6670 spaces are prepended that the printed value has the specified byte
6671 count.
6672
6673 A precision is specified as a period (.) followed by a decimal
6674 integer. If the integer is omitted after the period, the precision
6675 is assumed to be zero.
6676
6677 For conversion specifications %d, %i, %u, %o, %x, and %X, a
6678 precision defines a minimum digit count. If the formatted integer
6679 does not reach the minimum digit count, so many zeros are prepended
6680 that the printed integer has the specified number of digits. The
6681 default precision is one for these conversion specifications.
6682
6683 For conversion specifications %e, %E, %f, and %F, a precision
6684 defines the number of digits after the decimal mark. The default
6685 precision is six for these conversion specifications.
6686
6687 For conversion specifications %g, and %G, a precision defines a
6688 maximum number of significant digits in the printed value. The
6689 default precision is six for these conversion specifications.
6690
6691 For conversion specifications %s, and %b, a precision defines a
6692 maximum byte count of the printed string. The default precision is
6693 infinity for these conversion specifications.
6694
6695 In the conversion specification %08.3f, the zero flag is specified,
6696 the field width is 8, and the precision is 3. If this specification
6697 is applied to value 12.34, the output will be 0012.340.
6698
6699 Escape sequences
6700 The following escape sequences are recognized in format:
6701
6702 \a
6703 Bell character (ASCII code: 7)
6704
6705 \b
6706 Backspace (ASCII code: 8)
6707
6708 \f
6709 Form feed character (ASCII code: 12)
6710
6711 \n
6712 Newline character (ASCII code: 10)
6713
6714 \r
6715 Carriage return character (ASCII code: 13)
6716
6717 \t
6718 Horizontal tab character (ASCII code: 9)
6719
6720 \v
6721 Vertical tab character (ASCII code: 11)
6722
6723 \\
6724 Backslash
6725
6726 \"
6727 Double quotation
6728
6729 \'
6730 Single quotation (apostrophe)
6731
6732 \xxx
6733 Character whose code is xxx, where xxx is an octal number of at
6734 most three digits.
6735
6736 Operands
6737 format
6738 A string that defines how values should be formatted.
6739
6740 values
6741 Values that are formatted according to format.
6742
6743 A value is either a number or a string.
6744
6745 When a numeric value is required, value can be a single or double
6746 quotation followed by a character, instead of a normal number. For
6747 example, the command printf '%d' '"3' will print 51 on a typical
6748 environment where character 3 has character code 51.
6749
6750 Exit status
6751 The exit status of the printf built-in is zero unless there is any
6752 error.
6753
6754 Notes
6755 The POSIX standard does not precisely define how multibyte characters
6756 should be handled by the built-in. When you use the %s conversion
6757 specification with precision or the %c conversion specification, you
6758 may obtain unexpected results if the formatted value contains a
6759 character that is represented by more than one byte. Yash never prints
6760 only part of the bytes that represent a single multibyte character
6761 because all multibyte characters are converted to wide characters when
6762 processed in the shell.
6763
6764 If the shell is not in the POSIXly-correct mode and the “long double”
6765 floating-point arithmetic is supported on the running system, then
6766 “long double” is used for floating-point conversion specifications.
6767 Otherwise, “double” is used.
6768
6770 The pushd built-in pushes a directory into the directory stack.
6771
6772 Syntax
6773 • pushd [-L|-P] [directory]
6774
6775 Description
6776 The pushd built-in changes the working directory to directory in the
6777 same manner as the cd built-in and adds it to the directory stack. If
6778 the working directory could not be changed successfully, the stack is
6779 not modified.
6780
6781 Options
6782 The pushd built-in accepts the following option as well as the options
6783 that can be used for the cd built-in:
6784
6785 --remove-duplicates
6786 If the new working directory has already been in the directory
6787 stack, the existing entry is removed from the stack before the new
6788 directory is pushed into the stack.
6789
6790 Operands
6791 directory
6792 The pathname of the new working directory.
6793
6794 If directory is a single hyphen (‘-’), the value of the OLDPWD
6795 variable is assumed for the new directory pathname, which is
6796 printed to the standard output.
6797
6798 If directory is an integer with a plus or minus sign, it is
6799 considered as an entry index of the directory stack. The entry is
6800 removed from the stack and then pushed to the stack again.
6801
6802 If directory is omitted, the working directory is changed to the
6803 directory specified by the --default-directory=... option. If that
6804 option is not specified either, the default is index +1.
6805
6806 Exit status
6807 The exit status of the pushd built-in is zero unless there is any
6808 error.
6809
6810 Notes
6811 The pushd built-in is a semi-special built-in. In the POSIX standard,
6812 it is defined as a command with unspecified behavior.
6813
6815 The pwd built-in prints the current working directory.
6816
6817 Syntax
6818 • pwd [-L|-P]
6819
6820 Description
6821 The pwd built-in prints an absolute path to the shell’s current working
6822 directory to the standard output.
6823
6824 Options
6825 -L, --logical
6826 If the value of the PWD variable is an absolute path to the shell’s
6827 working directory and the path does not contain any . or ..
6828 components, then the path is printed. Otherwise, the printed path
6829 is the same as when the -P option is specified.
6830
6831 -P, --physical
6832 The printed path does not contain any . or .. components,
6833 symbolic link components, or redundant slashes.
6834
6835 The -L (--logical) and -P (--physical) options are mutually exclusive:
6836 only the last specified one is effective. If neither is specified, -L
6837 is assumed.
6838
6839 Exit status
6840 The exit status of the pwd built-in is zero unless there is any error.
6841
6842 Notes
6843 The pwd built-in is a semi-special built-in.
6844
6846 The read built-in reads a line from the standard input.
6847
6848 Syntax
6849 • read [-Aer] [-P|-p] variable...
6850
6851 Description
6852 The read built-in reads a line of string from the standard input and
6853 assigns it to the specified variables.
6854
6855 If the -r (--raw-mode) option is specified, all characters in the line
6856 are treated literally.
6857
6858 If the -r (--raw-mode) option is not specified, backslashes in the line
6859 are treated as quotations. If a backslash is at the end of the line, it
6860 is treated as a line continuation. When the built-in reads the next
6861 line, the PS2 variable is used as a prompt if the shell is interactive
6862 and the standard input is a terminal.
6863
6864 The input line is subject to field splitting. The resulting words are
6865 assigned to variables in order. If there are more words than variables,
6866 the last variable is assigned all the remaining words (as if the words
6867 were not split). If the words are fewer than variables, the remaining
6868 variables are assigned empty strings.
6869
6870 Options
6871 -A, --array
6872 Make the last variable an array. Instead of assigning a
6873 concatenation of the remaining words to a normal variable, the
6874 words are assigned to an array.
6875
6876 -e, --line-editing
6877 Use line-editing to read the line.
6878
6879 To use line-editing, all of the following conditions must also be
6880 met:
6881
6882 • The shell is interactive.
6883
6884 • The vi or emacs option is enabled.
6885
6886 • The standard input and standard error are connected to a
6887 terminal.
6888
6889 -P, --ps1
6890 Print the PS1 variable as a prompt before reading the (first) line
6891 if the shell is interactive and the standard input is a terminal.
6892
6893 -p prompt, --prompt=prompt
6894 Print the specified prompt before reading the (first) line if the
6895 shell is interactive and the standard input is a terminal.
6896
6897 -r, --raw-mode
6898 Don’t treat backslashes as quotations.
6899
6900 Operands
6901 variables
6902 Names of variables to which input words are assigned.
6903
6904 Exit status
6905 The exit status of the read built-in is zero unless there is any error.
6906
6907 Note that the exit status is non-zero if an end of input is encountered
6908 before reading the entire line.
6909
6910 Notes
6911 The read built-in is a semi-special built-in.
6912
6913 The POSIX standard defines the -r option only: other options cannot be
6914 used in the POSIXly-correct mode.
6915
6916 The PS1R and PS1S variables affect the behavior of line-editing if the
6917 PS1 prompt is used. The same for PS2.
6918
6920 The readonly built-in makes variables and functions read-only.
6921
6922 Syntax
6923 • readonly [-pxX] [name[=value]...]
6924
6925 • readonly -f[p] [name...]
6926
6927 Description
6928 The readonly built-in is equivalent to the typeset built-in with the
6929 -gr option.
6930
6931 Notes
6932 The readonly built-in is a special built-in.
6933
6934 The POSIX standard defines the -p option only; other options cannot be
6935 used in the POSIXly-correct mode. The POSIX does not allow using the
6936 option together with operands.
6937
6939 The return built-in returns from a function or script.
6940
6941 Syntax
6942 • return [-n] [exit_status]
6943
6944 Description
6945 When executed without the -n (--no-return) option, one of the following
6946 happens:
6947
6948 • If the shell is executing a function, the execution of the function
6949 is terminated.
6950
6951 • If the dot built-in is executing a script, the execution of the
6952 script is terminated.
6953
6954 • If the shell is executing a script during initialization, the
6955 execution of the script is terminated.
6956
6957 • If the shell is executing a trap, the execution of the trap is
6958 terminated for the currently handled signal.
6959
6960 • Otherwise, the shell exits unless it is interactive.
6961
6962 When executed with the -n (--no-return) option, the built-in does
6963 nothing but return the specified exit_status.
6964
6965 Options
6966 -n, --no-return
6967 Do not terminate a function, script, trap, or the shell.
6968
6969 Operands
6970 exit_status
6971 The exit status of the built-in.
6972
6973 The value must be a non-negative integer.
6974
6975 If omitted, the exit status of the last executed command is used.
6976 (But when the shell is executing a trap, the exit status of the
6977 last command before the trap is used.)
6978
6979 Exit status
6980 The exit status of the return built-in is defined by the exit_status
6981 operand. The exit status is used also as the exit status of the
6982 terminated function, script, or the shell.
6983
6984 Notes
6985 The return built-in is a special built-in.
6986
6987 The POSIX standard provides that the exit_status operand should be
6988 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
6989 an extension.
6990
6991 In the POSIX standard, the behavior of the return built-in is defined
6992 only when the shell is executing a function or script.
6993
6994 The POSIX standard defines no options for the return built-in; the
6995 built-in accepts no options in the POSIXly-correct mode.
6996
6998 The set built-in sets shell options and positional parameters.
6999
7000 Syntax
7001 • set [options] [operands]
7002
7003 • set -o
7004
7005 • set +o
7006
7007 The set built-in requires that all options precede operands. Any
7008 command line arguments after the first operand are all treated as
7009 operands.
7010
7011 Description
7012 When executed without any command arguments, the built-in prints a list
7013 of all existing variables to the standard input in a form that can be
7014 reused as commands that will restore the variable definitions.
7015
7016 When -o is the only command argument, the built-in prints a list of
7017 shell options with their current settings. When +o is the only command
7018 argument, the built-in prints commands that can be reused to restore
7019 the current shell option settings.
7020
7021 In other cases, the built-in changes shell option settings and/or
7022 positional parameters.
7023
7024 Options
7025 When one or more options are specified, the built-in enables or
7026 disables the shell options. A normal hyphen-prefixed option enables a
7027 shell option. An option that is prefixed with a plus (+) instead of a
7028 hyphen disables a shell option. For example, options -m, -o monitor,
7029 and --monitor enable the monitor option and options +m, +o monitor,
7030 ++monitor disable it.
7031
7032 The name of a long option is case-insensitive and may include
7033 irrelevant non-alphanumeric characters, which are ignored. For example,
7034 options --le-comp-debug and --LeCompDebug are equivalent. If no is
7035 prepended to the name of a long option, the meaning is reversed. For
7036 example, --noallexport is equivalent to ++allexport and ++nonotify to
7037 --notify.
7038
7039 An option can be specified in one of the following forms:
7040
7041 • a long option e.g. --allexport
7042
7043 • an -o option with a option name specified as the argument e.g. -o
7044 allexport
7045
7046 • a single-character option e.g. -a
7047
7048 Not all options can be specified as single-character options.
7049
7050 The available options are:
7051
7052 all-export (-a)
7053 When enabled, all variables are automatically exported when
7054 assigned.
7055
7056 brace-expand
7057 This option enables brace expansion.
7058
7059 case-glob
7060 (Enabled by default) When enabled, pattern matching is
7061 case-sensitive in pathname expansion.
7062
7063 clobber (+C)
7064 (Enabled by default) When enabled, the > redirection behaves the
7065 same as the >| redirection.
7066
7067 cur-async, cur-bg, cur-stop
7068 (Enabled by default) These options affect choice of the current job
7069 (cf. job ID).
7070
7071 dot-glob
7072 When enabled, periods at the beginning of filenames are not treated
7073 specially in pathname expansion.
7074
7075 emacs
7076 This option enables line-editing in the emacs mode.
7077
7078 empty-last-field
7079 When enabled, field splitting does not remove the last field even
7080 if it is empty.
7081
7082 err-exit (-e)
7083 When enabled, if a pipeline ends with a non-zero exit status, the
7084 shell immediately exits unless the following suppress condition is
7085 met:
7086
7087 • the pipeline is a condition of an if command or while or until
7088 loop;
7089
7090 • the pipeline is prefixed by !; or
7091
7092 • the pipeline is a single compound command other than a subshell
7093 grouping.
7094
7095 err-return
7096 This option is like the err-exit option, but the return built-in is
7097 executed instead of the shell exiting on a non-zero exit status.
7098 Unlike err-exit, the suppress condition does not apply inside a
7099 function, subshell grouping, or script file.
7100
7101 exec (+n)
7102 (Enabled by default) Commands are actually executed only when this
7103 option is enabled. Otherwise, commands are just parsed and not
7104 executed. Disabling this option may be useful for syntax checking.
7105 In an interactive shell, this option is always assumed enabled.
7106
7107 extended-glob
7108 This option enables extension in pathname expansion.
7109
7110 for-local
7111 (Enabled by default) If a for loop is executed within a function,
7112 this option causes the iteration variable to be created as a local
7113 variable, even if the variable already exists globally. This option
7114 has no effect if the POSIXly-correct mode is active.
7115
7116 glob (+f)
7117 (Enabled by default) This option enables pathname expansion.
7118
7119 hash-on-def (-h)
7120 When a function is defined when this option is enabled, the shell
7121 immediately performs command path search for each command that
7122 appears in the function and caches the command’s full path.
7123
7124 hist-space
7125 When enabled, command lines that start with a whitespace are not
7126 saved in command history.
7127
7128 ignore-eof
7129 When enabled, an interactive shell does not exit when EOF (end of
7130 file) is input. This prevents the shell from exiting when you
7131 accidentally hit Ctrl-D.
7132
7133 le-always-rp, le-comp-debug, le-conv-meta, le-no-conv-meta, le-predict,
7134 le-predict-empty, le-prompt-sp, le-visible-bell
7135 See shell options on line-editing.
7136
7137 mark-dirs
7138 When enabled, resulting directory names are suffixed by a slash in
7139 pathname expansion.
7140
7141 monitor (-m)
7142 This option enables job control. This option is enabled by default
7143 for an interactive shell.
7144
7145 notify (-b)
7146 When the status of a job changes when this option is enabled, the
7147 shell immediately notifies at any time. This option overrides the
7148 notify-le option.
7149
7150 notify-le
7151 This option is similar to the notify option, but the status change
7152 is notified only while the shell is waiting for input with
7153 line-editing.
7154
7155 null-glob
7156 When enabled, in pathname expansion, patterns that do not match any
7157 pathname are removed from the command line rather than left as is.
7158
7159 pipe-fail
7160 When enabled, the exit status of a pipeline is zero if and only if
7161 all the subcommands of the pipeline exit with an exit status of
7162 zero.
7163
7164 posixly-correct
7165 This option enables the POSIXly-correct mode.
7166
7167 trace-all
7168 (Enabled by default) When this option is disabled, the x-trace
7169 option is temporarily disabled while the shell is executing
7170 commands defined in the COMMAND_NOT_FOUND_HANDLER, PROMPT_COMMAND,
7171 or YASH_AFTER_CD variable.
7172
7173 unset (+u)
7174 (Enabled by default) When enabled, an undefined parameter is
7175 expanded to an empty string in parameter expansion and treated as
7176 zero in arithmetic expansion. When disabled, expansion of an
7177 undefined parameter results in an error.
7178
7179 verbose (-v)
7180 When enabled, the shell prints each command line to the standard
7181 error before parsing and executing it.
7182
7183 vi
7184 This option enables line-editing in the vi mode. This option is
7185 enabled by default in an interactive shell if the standard input
7186 and error are both terminals.
7187
7188 x-trace (-x)
7189 When enabled, the results of expansion are printed to the standard
7190 error for each simple command being executed. When printed, each
7191 line is prepended with an expansion result of the PS4 variable. See
7192 also the trace-all option.
7193
7194 Operands
7195 If one or more operands are passed to the set built-in, current
7196 positional parameters are all removed and the operands are set as new
7197 positional parameters. If the -- separator (cf. syntax of command
7198 arguments) is passed, the positional parameters are set even when there
7199 are no operands, in which case new positional parameters will be
7200 nothing.
7201
7202 Exit status
7203 The exit status of the set built-in is zero unless there is any error.
7204
7205 Notes
7206 The set built-in is a special built-in.
7207
7208 In the POSIX standard, available shell options are much limited. The
7209 standard does not define:
7210
7211 • long options such as --allexport,
7212
7213 • prepending no to negate an option,
7214
7215 • using uppercase letters and/or non-alphanumeric characters in
7216 option names
7217
7218 The options defined in the standard are:
7219
7220 • -a, -o allexport
7221
7222 • -e, -o errexit
7223
7224 • -m, -o monitor
7225
7226 • -C, -o noclobber
7227
7228 • -n, -o noexec
7229
7230 • -f, -o noglob
7231
7232 • -b, -o notify
7233
7234 • -u, -o nounset
7235
7236 • -v, -o verbose
7237
7238 • -x, -o xtrace
7239
7240 • -h
7241
7242 • -o ignoreeof
7243
7244 • -o nolog
7245
7246 • -o vi
7247
7248 Yash does not support the nolog option, which prevents function
7249 definitions from being added to command history.
7250
7252 The shift built-in removes some positional parameters or array values.
7253
7254 Syntax
7255 • shift [-A array] [count]
7256
7257 Description
7258 The shift built-in removes the first count positional parameters or
7259 array values, where count is specified by the operand.
7260
7261 Options
7262 -A array, --array=array
7263 Remove first count values of array instead of positional
7264 parameters.
7265
7266 Operands
7267 count
7268 The number of positional parameters or array values to be removed.
7269
7270 It is an error if the actual number of positional parameters or
7271 array values is less than count. If omitted, the default value is
7272 one. If negative, the last -count positional parameters or array
7273 values are removed instead of the first ones.
7274
7275 Exit status
7276 The exit status of the shift built-in is zero unless there is any
7277 error.
7278
7279 Notes
7280 The shift built-in is a special built-in.
7281
7282 The number of positional parameters can be obtained with the # special
7283 parameter. The number of array values can be obtained with ${array[#]}.
7284
7285 The POSIX standard defines no options for the shift built-in; the
7286 built-in accepts no options in the POSIXly-correct mode.
7287
7288 Negative operands are not allowed in the POSIXly-correct mode.
7289
7291 The suspend built-in suspends the shell.
7292
7293 Syntax
7294 • suspend [-f]
7295
7296 Description
7297 The suspend built-in sends a SIGSTOP signal to all processes in the
7298 process group to which the shell process belongs. The signal suspends
7299 the processes (including the shell). The suspended processes resume
7300 when they receive a SIGCONT signal.
7301
7302 If the shell is interactive and its process group ID is equal to the
7303 process ID of the session leader, the shell prints a warning message
7304 and refuses to send a signal unless the -f (--force) option is
7305 specified. (In such a case, there is no other job-controlling shell
7306 that can send a SIGCONT signal to resume the suspended shell, so the
7307 shell could never be resumed.)
7308
7309 Options
7310 -f, --force
7311 Suppress warnings that would prevent the shell from sending a
7312 signal.
7313
7314 Exit status
7315 The exit status is zero if the signal was successfully sent and
7316 non-zero otherwise.
7317
7318 Notes
7319 The suspend built-in is a semi-special built-in. In the POSIX standard,
7320 it is defined as a command with unspecified behavior.
7321
7323 The test built-in evaluates an expression.
7324
7325 Syntax
7326 • test expression
7327
7328 • [ expression ]
7329
7330 The test built-in does not distinguish options and operands; all
7331 command line arguments are interpreted as expression. If the built-in
7332 is executed with the name [, expression must be followed by ].
7333
7334 Description
7335 The test built-in evaluates expression as a conditional expression that
7336 is made up of operators and operands described below. The exit status
7337 is 0 if the condition is true and 1 otherwise.
7338
7339 The unary operators below test a file. If the operand file is a
7340 symbolic link, the file referred to by the link is tested (except for
7341 the -h and -L operators).
7342
7343 -b file
7344 file is a block special file
7345
7346 -c file
7347 file is a character special file
7348
7349 -d file
7350 file is a directory
7351
7352 -e file
7353 file exists
7354
7355 -f file
7356 file is a regular file
7357
7358 -G file
7359 file's group ID is same as the shell’s effective group ID
7360
7361 -g file
7362 file's set-group-ID flag is set
7363
7364 -h file
7365 same as -L
7366
7367 -k file
7368 file's sticky bit is set
7369
7370 -L file
7371 file is a symbolic link
7372
7373 -N file
7374 file has not been accessed since last modified
7375
7376 -O file
7377 file's user ID is same as the shell’s effective user ID
7378
7379 -p file
7380 file is a FIFO (named pipe)
7381
7382 -r file
7383 file is readable
7384
7385 -S file
7386 file is a socket
7387
7388 -s file
7389 file is not empty
7390
7391 -u file
7392 file's set-user-ID flag is set
7393
7394 -w file
7395 file is writable
7396
7397 -x file
7398 file is executable
7399
7400 The unary operator below tests a file descriptor:
7401
7402 -t fd
7403 fd is associated with a terminal
7404
7405 The unary operators below test a string:
7406
7407 -n string
7408 string is not empty
7409
7410 -z string
7411 string is empty
7412
7413 The unary operator below tests a shell option:
7414
7415 -o ?option
7416 option is a valid shell option name
7417
7418 -o option
7419 option is a valid shell option name that is enabled
7420
7421 The binary operators below compare files. Non-existing files are
7422 considered older than any existing files.
7423
7424 file1 -nt file2
7425 file1 is newer than file2
7426
7427 file1 -ot file2
7428 file1 is older than file2
7429
7430 file1 -ef file2
7431 file1 is a hard link to file2
7432
7433 The binary operators below compare strings:
7434
7435 string1 = string2, string1 == string2
7436 string1 is the same string as string2
7437
7438 string1 != string2
7439 string1 is not the same string as string2
7440
7441 The binary operators below compare strings according to the alphabetic
7442 order in the current locale:
7443
7444 string1 === string2
7445 string1 is equal to string2
7446
7447 string1 !== string2
7448 string1 is not equal to string2
7449
7450 string1 < string2
7451 string1 is less than string2
7452
7453 string1 <= string2
7454 string1 is less than or equal to string2
7455
7456 string1 > string2
7457 string1 is greater than string2
7458
7459 string1 >= string2
7460 string1 is greater than or equal to string2
7461
7462 The binary operator below performs pattern matching:
7463
7464 string =~ pattern
7465 extended regular expression pattern matches (part of) string
7466
7467 The binary operators below compare integers:
7468
7469 v1 -eq v2
7470 v1 is equal to v2
7471
7472 v1 -ne v2
7473 v1 is not equal to v2
7474
7475 v1 -gt v2
7476 v1 is greater than v2
7477
7478 v1 -ge v2
7479 v1 is greater than or equal to v2
7480
7481 v1 -lt v2
7482 v1 is less than v2
7483
7484 v1 -le v2
7485 v1 is less than or equal to v2
7486
7487 The binary operators below compare version numbers:
7488
7489 v1 -veq v2
7490 v1 is equal to v2
7491
7492 v1 -vne v2
7493 v1 is not equal to v2
7494
7495 v1 -vgt v2
7496 v1 is greater than v2
7497
7498 v1 -vge v2
7499 v1 is greater than or equal to v2
7500
7501 v1 -vlt v2
7502 v1 is less than v2
7503
7504 v1 -vle v2
7505 v1 is less than or equal to v2
7506
7507 The operators below can be used to make complex expressions:
7508
7509 ! expression
7510 negate (reverse) the result
7511
7512 ( expression )
7513 change operator precedence
7514
7515 expression1 -a expression2
7516 logical conjunction (and)
7517
7518 expression1 -o expression2
7519 logical disjunction (or)
7520
7521 If the expression is a single word without operators, the -n operator
7522 is assumed. An empty expression evaluates to false.
7523
7524 Comparison of version numbers
7525 Comparison of version numbers is similar to comparison of strings
7526 in alphabetic order. The differences are:
7527
7528 • Adjacent digits are treated as an integer. Integers are
7529 compared in mathematical order rather than alphabetic order.
7530
7531 • Digits are considered larger than any non-digit characters.
7532
7533 For example, version numbers 0.1.2-3 and 00.001.02-3 are equal and
7534 0.2.1 is smaller than 0.10.0.
7535
7536 Exit status
7537 The exit status of the test built-in is 0 if expression is true and 1
7538 otherwise. The exit status is 2 if expression cannot be evaluated
7539 because of a syntax error or any other reasons.
7540
7541 Notes
7542 Complex expressions may cause confusion and should be avoided. Use the
7543 shell’s compound commands. For example, [ 1 -eq 1 ] && [ -t = 1 ] && !
7544 [ foo ] is preferred over [ 1 -eq 1 -a -t = 1 -a ! foo ].
7545
7546 The POSIX standard provides that the exit status should be larger than
7547 1 on error. The POSIX standard does not define the following operators:
7548 -G, -k, -N, -O, -nt, -ot, -ef, ==, ===, !==, <, <=, >, >=, =~, -veq,
7549 -vne, -vgt, -vge, -vlt, and -vle. POSIX neither specifies -o as a unary
7550 operator.
7551
7553 The times built-in prints CPU time usage.
7554
7555 Syntax
7556 • times
7557
7558 Description
7559 The times built-in prints the CPU times consumed by the shell process
7560 and its child processes to the standard output.
7561
7562 The built-in prints two lines: the first line shows the CPU time of the
7563 shell process and the second one that of its child processes (not
7564 including those which have not terminated). Each line shows the CPU
7565 times consumed in the user and system mode.
7566
7567 Exit status
7568 The exit status of the times built-in is zero unless there is any
7569 error.
7570
7571 Notes
7572 The times built-in is a special built-in.
7573
7575 The trap built-in sets or prints signal handlers.
7576
7577 Syntax
7578 • trap
7579
7580 • trap action signal...
7581
7582 • trap signal_number [signal...]
7583
7584 • trap -p [signal...]
7585
7586 Description
7587 The trap built-in sets or prints actions that are taken when the shell
7588 receives signals. (Those actions are called traps.)
7589
7590 When executed with action and one or more signals, the built-in sets
7591 the traps for signals to action. If the shell receives one of the
7592 signals, the action will be taken.
7593
7594 If the first operand is signal_number instead of action, the built-in
7595 resets the traps for signal_number and signals as if action was -.
7596
7597 When executed with the -p (--print) option or with no operands, the
7598 built-in prints currently set traps to the standard output in a format
7599 that can be executed as commands that restore the current traps. If one
7600 or more signals are specified, only those signals are printed.
7601 Otherwise, all signals with non-default actions are printed. (In some
7602 situations, however, the built-in may print previous trap settings
7603 instead of the current. See notes below.)
7604
7605 Options
7606 -p, --print
7607 Print current trap settings.
7608
7609 Operands
7610 action
7611 An action that will be taken when signal is received.
7612
7613 If action is a single hyphen (-), the action is reset to the
7614 default action that is defined by the operating system. If action
7615 is an empty string, the signal is ignored on receipt. Otherwise,
7616 action is treated as a command string: the string is parsed and
7617 executed as commands when the signal is received. (If a signal is
7618 received while a command is being executed, the action is taken
7619 just after the command finishes.)
7620
7621 signal
7622 The number or name of a signal.
7623
7624 If signal is number 0 or name EXIT, it is treated as a special
7625 imaginary signal that is always received when the shell exits. The
7626 action set for this signal is taken when the shell exits normally.
7627
7628 signal_number
7629 This is like signal, but must be a number.
7630
7631 Exit status
7632 The exit status of the trap built-in is zero unless there is any error.
7633
7634 Notes
7635 The trap built-in is a special built-in.
7636
7637 The POSIX standard defines no options for the trap built-in; the
7638 built-in accepts no options in the POSIXly-correct mode.
7639
7640 The POSIX standard requires that signal names must be specified without
7641 the SIG-prefix, like INT and QUIT. As an extension, yash accepts
7642 SIG-prefixed names like SIGINT and SIGQUIT and treats signal names
7643 case-insensitively.
7644
7645 Reusing output of the built-in
7646 Output of the trap built-in can be saved in a variable, which can
7647 be later executed by the eval built-in to restore the traps.
7648
7649 saved_traps=$(trap)
7650 trap '...' INT
7651 eval "$saved_traps"
7652
7653 There are some tricks behind the scenes to allow this idiom. You
7654 use a command substitution to save the output of the trap built-in
7655 in the variable. The command substitution is executed in a
7656 subshell. The subshell resets all traps (except ignored ones) at
7657 the beginning of itself. This seemingly would result in (almost)
7658 empty output from the built-in that would fail to restore the traps
7659 as expected.
7660
7661 To avoid that pitfall, POSIX requires the shell to follow one of
7662 the two options below:
7663
7664 • If a command substitution just contains a single trap built-in,
7665 traps should not be reset when the subshell is started to
7666 execute the built-in; or
7667
7668 • A subshell always resets the traps but remembers the previous
7669 traps. If the trap built-in is executed in the subshell but no
7670 other trap built-in has been executed to modify traps in the
7671 subshell, then the built-in should print the remembered traps.
7672
7673 Yash obeys the second.
7674
7676 The true built-in does nothing successfully.
7677
7678 Syntax
7679 • true
7680
7681 Description
7682 The true built-in does nothing. Any command line arguments are ignored.
7683
7684 Exit status
7685 The exit status of the true built-in is zero.
7686
7687 Notes
7688 The true built-in is a semi-special built-in.
7689
7690 The true and colon built-ins have the same effect, but true is a
7691 semi-special built-in while colon is a special.
7692
7694 The type built-in identifies a command.
7695
7696 Syntax
7697 • type [-abefkp] [command...]
7698
7699 Description
7700 The type built-in is equivalent to the command built-in with the -V
7701 option.
7702
7703 Notes
7704 The POSIX standard does not define the relation between the type and
7705 command built-ins. The standard does not define options for the type
7706 built-in.
7707
7708 At least one command operand must be specified in the POSIXly-correct
7709 mode.
7710
7711 The type built-in is a semi-special built-in.
7712
7714 The typeset built-in prints or sets variables or functions.
7715
7716 Syntax
7717 • typeset [-gprxX] [variable[=value]...]
7718
7719 • typeset -f[pr] [function...]
7720
7721 Description
7722 If executed without the -f (--functions) option, the typeset built-in
7723 prints or sets variables to the standard output. Otherwise, it prints
7724 or sets functions.
7725
7726 If executed with the -p (--print) option, the built-in prints the
7727 variables or functions specified by operands. Without the option, it
7728 sets variables or functions. If no operands are specified, it prints
7729 all existing variables or functions, regardless of whether the -p
7730 (--print) option is specified.
7731
7732 Options
7733 -f, --functions
7734 Print or set functions rather than variables.
7735
7736 -g, --global
7737 When setting a new variable, the variable will be a global variable
7738 if this option is specified. Without this option, the variable
7739 would be a local variable.
7740
7741 When printing variables, all existing variables including global
7742 variables are printed if this option is specified. Without this
7743 option, only local variables are printed.
7744
7745 -p, --print
7746 Print variables or functions in a form that can be parsed and
7747 executed as commands that will restore the currently set variables
7748 or functions.
7749
7750 -r, --readonly
7751 When setting variables or functions, make them read-only.
7752
7753 When printing variables or functions, print read-only variables or
7754 functions only.
7755
7756 -x, --export
7757 When setting variables, mark them for export, so that they will be
7758 exported to external commands.
7759
7760 When printing variables, print exported variables only.
7761
7762 -X, --unexport
7763 When setting variables, cancel exportation of the variables.
7764
7765 Operands
7766 variable (without value)
7767 The name of a variable that is to be set or printed.
7768
7769 Without the -p (--print) option, the variable is defined (if not
7770 yet defined) but its value is not set nor changed. Variables that
7771 are defined without values are treated as unset in parameter
7772 expansion.
7773
7774 variable=value
7775 The name of a variable and its new value.
7776
7777 The value is assigned to the variable (regardless of the -p
7778 (--print) option).
7779
7780 function
7781 The name of an existing function that is to be set or printed.
7782
7783 Exit status
7784 The exit status of the typeset built-in is zero unless there is any
7785 error.
7786
7787 Notes
7788 A global variable cannot be newly defined if a local variable has
7789 already been defined with the same name. The local variable will be set
7790 regardless of the -g (--global) option.
7791
7792 The typeset built-in is a semi-special built-in. In the POSIX standard,
7793 it is defined as a command with unspecified behavior.
7794
7795 The export and readonly built-ins are equivalent to the typeset
7796 built-in with the -gx and -gr options, respectively. The local built-in
7797 is equivalent to the typeset built-in except that the -f (--functions)
7798 and -g (--global) options cannot be used.
7799
7801 The ulimit built-in sets or prints a resource limit.
7802
7803 Syntax
7804 • ulimit -a [-H|-S]
7805
7806 • ulimit [-H|-S] [-efilnqrstuvx] [limit]
7807
7808 Description
7809 The ulimit built-in sets or prints a resource limit.
7810
7811 If executed with the -a (--all) option, the built-in prints the current
7812 limits for all resource types. Otherwise, it sets or prints the limit
7813 of a single resource type. The resource type can be specified by the
7814 options listed below. The resource limits will affect the current shell
7815 process and all commands invoked from the shell.
7816
7817 Each resource type has two limit values: the hard and soft limit. You
7818 can change a soft limit freely as long as it does not exceed the hard
7819 limit. You can decrease a hard limit but cannot increase it without a
7820 proper permission.
7821
7822 When the -H (--hard) or -S (--soft) option is specified, the built-in
7823 sets or prints the hard or soft limit, respectively. If neither of the
7824 options is specified, the built-in sets both the hard and soft limit or
7825 prints the soft limit.
7826
7827 Options
7828 -H, --hard
7829 Set or print a hard limit.
7830
7831 -S, --soft
7832 Set or print a soft limit.
7833
7834 -a, --all
7835 Print all current limit settings.
7836
7837 The following options specify the type of resources. If none of them is
7838 specified, -f is the default. The types of resources that can be set
7839 depend on the operating system.
7840
7841 -c, --core
7842 Maximum size of core files created (in 512-byte blocks)
7843
7844 -d, --data
7845 Maximum size of a process’s data segment (in kilobytes)
7846
7847 -e, --nice
7848 Maximum scheduling priority (‘nice’)
7849
7850 -f, --fsize
7851 Maximum size of files created by a process (in 512-byte blocks)
7852
7853 -i, --sigpending
7854 Maximum number of pending signals
7855
7856 -l, --memlock
7857 Maximum memory size that can be locked into RAM (in kilobytes)
7858
7859 -m, --rss
7860 Maximum size of a process’s resident set (in kilobytes)
7861
7862 -n, --nofile
7863 Maximum file descriptor + 1
7864
7865 -q, --msgqueue
7866 Maximum size of POSIX message queues
7867
7868 -r, --rtprio
7869 Maximum real-time scheduling priority
7870
7871 -s, --stack
7872 Maximum size of a process’s stack (in kilobytes)
7873
7874 -t, --cpu
7875 Maximum CPU time that can be used by a process (in seconds)
7876
7877 -u, --nproc
7878 Maximum number of processes for a user
7879
7880 -v, --as
7881 Maximum size of memory used by a process (in kilobytes)
7882
7883 -x, --locks
7884 Maximum number of file locks
7885
7886 Operands
7887 limit
7888 A limit to be set.
7889
7890 The value must be a non-negative integer or one of hard, soft, and
7891 unlimited. If value is hard or soft, the new limit is set to the
7892 current hard or soft limit. If limit is not specified, the current
7893 limit is printed.
7894
7895 Exit status
7896 The exit status of the ulimit built-in is zero unless there is any
7897 error.
7898
7899 Notes
7900 The POSIX standard defines no options other than -f. It neither defines
7901 hard, soft, or unlimited for limit values.
7902
7903 The ulimit built-in is a semi-special built-in.
7904
7906 The umask built-in sets or prints the file mode creation mask.
7907
7908 Syntax
7909 • umask mask
7910
7911 • umask [-S]
7912
7913 Description
7914 If executed without the mask operand, the built-in prints the current
7915 file mode creation mask of the shell to the standard output in a form
7916 that can later be used as mask to restore the current mask.
7917
7918 Otherwise, the built-in sets the file mode creation mask to mask.
7919
7920 Options
7921 -S, --symbolic
7922 Print in the symbolic form instead of the octal integer form.
7923
7924 Operands
7925 mask
7926 The new file mode creation mask either in the symbolic or octal
7927 integer form.
7928
7929 Octal integer form
7930 In the octal integer form, the mask is specified as a non-negative
7931 octal integer that is the sum of the following permissions:
7932
7933 0400
7934 read by owner
7935
7936 0200
7937 write by owner
7938
7939 0100
7940 execute/search by owner
7941
7942 0040
7943 read by group
7944
7945 0020
7946 write by group
7947
7948 0010
7949 execute/search by group
7950
7951 0004
7952 read by others
7953
7954 0002
7955 write by others
7956
7957 0001
7958 execute/search by others
7959
7960 Symbolic form
7961 In the symbolic form, the mask is specified as a symbolic
7962 expression that denotes permissions that are not included in the
7963 mask.
7964
7965 The entire expression is one or more clauses separated by comma. A
7966 clause is a sequence of whos followed by one or more actions.
7967
7968 A who is one of:
7969
7970 u
7971 owner
7972
7973 g
7974 group
7975
7976 o
7977 others
7978
7979 a
7980 all of owner, group, and others
7981
7982 An empty sequence of whos is equivalent to who a.
7983
7984 An action is an operator followed by permission. An operator is one
7985 of:
7986
7987 =
7988 set who's permission to permission
7989
7990 +
7991 add permission to who's permission
7992
7993 -
7994 remove permission from who's permission
7995
7996 and permission is one of:
7997
7998 r
7999 read
8000
8001 w
8002 write
8003
8004 x
8005 execute/search
8006
8007 X
8008 execute/search (only if some user already has execute/search
8009 permission)
8010
8011 s
8012 set-user-ID and set-group-ID
8013
8014 u
8015 user’s current permissions
8016
8017 g
8018 group’s current permissions
8019
8020 o
8021 others' current permissions
8022
8023 but more than one of r, w, x, X, and s can be specified after a
8024 single operand.
8025
8026 For example, the command umask u=rwx,go+r-w
8027
8028 • unmasks the user’s read, write, and execute/search permissions;
8029
8030 • unmasks the group’s and others' read permission; and
8031
8032 • masks the group’s and others' write permission.
8033
8034 Exit status
8035 The exit status of the umask built-in is zero unless there is any
8036 error.
8037
8038 Notes
8039 The umask built-in is a semi-special built-in.
8040
8041 The POSIX standard does not require the default output format (used
8042 when the -S option is not specified) to be the octal integer form.
8043
8045 The unalias built-in undefines aliases.
8046
8047 Syntax
8048 • unalias name...
8049
8050 • unalias -a
8051
8052 Description
8053 The unalias built-in removes the definition of the aliases specified by
8054 operands.
8055
8056 Options
8057 -a, --all
8058 Undefine all aliases.
8059
8060 Operands
8061 name
8062 The name of an alias to be undefined.
8063
8064 Exit status
8065 The exit status of the unalias built-in is zero unless there is any
8066 error. It is an error to specify the name of a non-existing alias as
8067 name.
8068
8069 Notes
8070 The unalias built-in is a semi-special built-in.
8071
8073 The unset built-in undefines variables or functions.
8074
8075 Syntax
8076 • unset [-fv] [name...]
8077
8078 Description
8079 The unset built-in removes the definition of the variables or functions
8080 specified by operands.
8081
8082 It is not an error if any of the specified variables or functions do
8083 not exist; they are silently ignored.
8084
8085 Options
8086 -f, --functions
8087 Undefine functions.
8088
8089 -v, --variables
8090 Undefine variables.
8091
8092 These options are mutually exclusive: only the last specified one is
8093 effective. If neither is specified, -v is assumed.
8094
8095 Operands
8096 name
8097 The name of a variable or function to be undefined.
8098
8099 Exit status
8100 The exit status of the unset built-in is zero unless there is any
8101 error.
8102
8103 Notes
8104 The unset built-in is a special built-in.
8105
8106 Although yash does not do so, the POSIX standard allows removing a
8107 function if neither of the -f and -v options is specified and the
8108 specified variable does not exist.
8109
8110 At least one name operand must be specified in the POSIXly-correct
8111 mode.
8112
8114 The wait built-in waits for jobs to terminate.
8115
8116 Syntax
8117 • wait [job...]
8118
8119 Description
8120 The wait built-in waits for background jobs to terminate. If job
8121 control is enabled, stopped jobs are considered as terminated.
8122
8123 The built-in can be used to wait for asynchronous commands if job
8124 control is disabled.
8125
8126 If the shell receives a signal while the built-in is waiting and if a
8127 trap has been set for the signal, then the trap is executed and the
8128 built-in immediately finishes (without waiting for the jobs). If the
8129 shell receives a SIGINT signal when job control is enabled, the
8130 built-in aborts waiting.
8131
8132 If the shell is interactive, job-controlling, and not in the
8133 POSIXly-correct mode, the job status is printed when the job is
8134 terminated or stopped.
8135
8136 Operands
8137 job
8138 The job ID of the job or the process ID of a process in the job.
8139
8140 If no jobs are specified, the built-in waits for all existing jobs.
8141
8142 If the specified job does not exist, the job is considered to have
8143 terminated with the exit status of 127.
8144
8145 Exit status
8146 If no jobs were specified and the built-in successfully waited for all
8147 the jobs, the exit status is zero. If one or more jobs were specified,
8148 the exit status is that of the last job.
8149
8150 If the built-in was aborted by a signal, the exit status is an integer
8151 (> 128) that denotes the signal. If there was any other error, the exit
8152 status is between 1 and 126 (inclusive).
8153
8154 Notes
8155 The wait built-in is a semi-special built-in.
8156
8157 The process ID of the last process of a job can be obtained by the !
8158 special parameter. You can use the jobs built-in as well to obtain
8159 process IDs of job processes.
8160
8162 Yuki Watanabe <magicant@users.osdn.me>
8163 Author.
8164
8165
8166
8167 2.53 2022-08-23 YASH(1)