1YASH(1) YASH(1)
2
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 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 This manual can be freely modified and redistributed under the terms of
24 Creative Commons Attribution-ShareAlike 2.1 Japan.
25 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 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 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 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 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 You cannot use both the -c (--cmdline) and -s (--stdin) options at a
64 time.
65 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 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 If you specify the -l (--login) option, the shell behaves as a login
78 shell.
79 The --noprofile, --norcfile, --profile, and --rcfile options determine
81 how the shell is initialized (see below for details).
82 In addition to the options described above, you can specify options
84 that can be specified to the set built-in.
85 If the first operand is - and the options and the operands are not
87 separated by --, the first operand is ignored.
88 Initialization of yash
90 Yash initializes itself as follows:
91 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 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 3. Job control is automatically enabled in an interactive shell unless
102 the +m (++monitor) option is specified.
103 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 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 If the --profile=filename option is not specified, the shell
115 reads ~/.yash_profile as a default.
116 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 If the --rcfile=filename option is not specified, the shell
122 instead reads the following files:
123 • 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 • 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 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 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 The following symbols have special meanings in the shell syntax and in
152 most cases separate tokens:
153 ; & | < > ( ) [newline]
155 The following symbols do not separate tokens, but have syntactic
157 meanings:
158 $ ` \ " ' * ? [ # ~ = %
160 The following tokens are treated as keywords depending on the context
162 in which they appear:
163 ! { } [[ case do done elif else esac fi
165 for function if in then until while
166 A token is treated as a keyword when:
168 • it is the first token of a command,
170 • it follows another keyword (except case, for, and in), or
172 • it is a non-first token of a command and is supposed to be a
174 keyword to compose a composite command.
175 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 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 • A backslash (\) quotes a character that immediately follows.
188 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 • 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 • 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 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 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 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 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 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 You can define aliases using the alias built-in and remove using the
231 unalias built-in.
232 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 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 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 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 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 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 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 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 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 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 And/or lists
290 An and/or list is a sequence of one or more pipelines separated by &&
291 or ||.
292 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 • If two pipelines are separated by && and the exit status of the
299 first pipeline is zero, the second pipeline is executed.
300 • If two pipelines are separated by || and the exit status of the
302 first pipeline is not zero, the second pipeline is executed.
303 • In other cases, the execution of the and/or list ends: the second
305 and any remaining pipelines are not executed.
306 The exit status of an and/or list is that of the last pipeline that was
308 executed.
309 Normally, an and/or list must be terminated by a semicolon, ampersand,
311 or newline. See Command separators and asynchronous commands.
312 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 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 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 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 Compound commands
339 Compound commands provide you with programmatic control of shell
340 command execution.
341 Grouping
343 A grouping is a list of commands that is treated as a simple
344 command.
345 Normal grouping syntax
347 { command...; }
348 Subshell grouping syntax
350 (command...)
351 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 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 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 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 If command
369 The if command performs a conditional branch.
370 Basic if command syntax
372 if condition...; then body...; fi
373 Syntax with the else clause
375 if condition...; then body...; else body...; fi
376 Syntax with the elif clause
378 if condition...; then body...; elif condition...; then body...;
379 fi
380 Syntax with the elif clause
382 if condition...; then body...; elif condition...; then body...;
383 else body...; fi
384 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 An if command may have more than one elif-then clause.
399 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 While and until loops
406 The while loop and until loop are simple loops with condition.
407 While loop syntax
409 while condition...; do body...; done
410 Until loop syntax
412 until condition...; do body...; done
413 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 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 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 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 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 For loop
439 The for loop repeats commands with a variable assigned one of given
440 values in each round.
441 For loop syntax
443 for varname in word...; do command...; done
444 for varname do command...; done
446 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 The varname must be a portable (ASCII-only) name in the
454 POSIXly-correct mode.
455 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 1. Assign the word to the variable whose name is varname.
463 2. Execute the commands.
465 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 If the expansion of the words yields no words, no variable is
472 created and the commands are not executed at all.
473 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 If the variable is read-only, the execution of the for loop is
480 interrupted and the exit status will be non-zero.
481 Case command
483 The case command performs a pattern matching to select commands to
484 execute.
485 Case command syntax
487 case word in caseitem... esac
488 Case item syntax
490 (patterns) command...;;
491 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 The patterns in a case item are one or more tokens each separated
502 by a | token.
503 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 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 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 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 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 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 Double-bracket command syntax
535 [[ expression ]]
536 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 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 In the double-bracket command, the following primaries from the
547 test built-in can be used:
548 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 Binary primaries
554 -ef, -eq, -ge, -gt, -le, -lt, -ne, -nt, -ot, -veq, -vge, -vgt,
555 -vle, -vlt, -vne, ===, !==, =~, <, >
556 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 The operand word of a primary must be quoted if it is ]] or can be
565 confused with another primary operator.
566 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 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 The following operands (listed in the descending order of
577 precedence) can be used to combine primaries:
578 ( expression )
580 A pair of parentheses change operator precedence.
581 ! expression
583 An exclamation mark negates (reverses) the result.
584 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 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 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 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 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 Function definition
615 The function definition command defines a function.
616 Function definition syntax
618 funcname ( ) compound_command
619 function funcname compound_command
621 function funcname ( ) compound_command
623 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 When a function definition command is executed, a function whose name
632 is funcname is defined with its body being compound_command.
633 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 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 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 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 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 Positional parameters can be manipulated by built-in commands like set
667 and shift.
668 Note that 0 is not a positional parameter but a special parameter.
670 Special parameters
672 Special parameters are parameters each identified by a single symbol.
673 They cannot be directly assigned to by the user.
674 Yash provides the following special parameters:
676 0
678 The name of the shell executable file or the script file that was
679 specified in the invocation of the shell.
680 #
682 The number of current positional parameters. The value is a
683 non-negative integer.
684 $
686 The process ID of the shell. The value is a positive integer and is
687 never changed even in subshells.
688 -
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 ?
697 The exit status of the last executed pipeline. The value is a
698 non-negative integer.
699 !
701 The process ID of the last executed asynchronous list.
702 *
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 • 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 • If the IFS variable exists and has an empty value, positional
715 parameters are just concatenated without any separator.
716 • If the IFS variable does not exist, positional parameters are
718 each separated by a space character.
719 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 @
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 • When there are no positional parameters, the command words echo
738 1 "$@" 2 are expanded to the three words echo, 1, and 2.
739 • 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 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 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 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 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 Variables used by the shell
764 The following variables are used by the shell for special purposes.
765 CDPATH
767 This variable is used by the cd built-in to find a destination
768 directory.
769 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 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 This feature is disabled in the POSIXly-correct mode.
782 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 ECHO_STYLE
789 This variable specifies the behavior of the echo built-in.
790 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 FCEDIT
797 This variable specifies an editor program used to edit command
798 lines during execution of the fc built-in.
799 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 HISTFILE
806 This variable specifies the pathname of the file to save the
807 command history in.
808 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 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 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 HISTSIZE
827 This variable specifies the maximum number of items in the
828 command history.
829 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 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 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 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 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 In the interactive shell, the line number is reset to 1 each
858 time the shell reads and executes a command.
859 If you assign to or remove this variable, it will no longer
861 provide line numbers.
862 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 MAIL
869 This variable specifies the pathname of a file that is checked
870 in mail checking.
871 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 MAILPATH
879 This variable specifies the pathnames of files that are checked
880 in mail checking.
881 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 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 OPTARG
893 When the getopts built-in parses an option that takes an
894 argument, the argument value is assigned to this variable.
895 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 PATH
902 This variable specifies paths that are searched for a command
903 in command search.
904 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 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 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 PS1P
928 This variable specifies the font style of predicted commands.
929 See Prompts for the format of the variable value.
930 PS1R
932 This variable specifies the auxiliary prompt string printed to
933 the right of the cursor when you input a command line to an
934 interactive shell. See Prompts for the format of the variable
935 value.
936 PS1S
938 This variable specifies the font style of command strings you
939 enter to an interactive shell. See Prompts for the format of
940 the variable value.
941 PS2
943 This variable is like the PS1 variable, but it is used for the
944 second and following lines of a command that is longer than one
945 line. See Prompts for the format of the variable value. The
946 value is initialized to > when the shell is started.
947 PS2P
949 This variable is like the PS1P variable, but it is used when
950 PS2 is used. See Prompts for the format of the variable value.
951 PS2R
953 This variable is like the PS1R variable, but it is used when
954 PS2 is used. See Prompts for the format of the variable value.
955 PS2S
957 This variable is like the PS1S variable, but it is used when
958 PS2 is used. See Prompts for the format of the variable value.
959 PS4
961 The value of this variable is printed before each command trace
962 output when the xtrace option is enabled. The value is subject
963 to parameter expansion, command substitution, arithmetic
964 expansion. You can also use backslash notations if the shell is
965 not in the POSIXly-correct mode. The value is initialized to +
966 when the shell is started.
967 PS4S
969 This variable is like the PS1S variable, but it is used when
970 PS4 is used. You can use this variable to modify font style of
971 command trace output.
972 PWD
974 The value of this variable is the pathname of the current
975 working directory. The value is set when the shell is started
976 and reset each time the working directory is changed by the cd
977 or other built-ins. This variable is exported by default.
978 RANDOM
980 You can use this variable to get random numbers. The value of
981 this variable is a uniformly distributed random integer between
982 0 and 32767 (inclusive). You will get a different number each
983 time the variable is expanded.
984 You can set the “seed” of random numbers by assigning a
986 non-negative integer to the variable.
987 If you remove this variable, it will no longer work as a random
989 number generator. If the shell was invoked in the
990 POSIXly-correct mode, this variable does not work as a random
991 number generator.
992 TERM
994 This variable specifies the type of the terminal in which the
995 shell is running. The value affects the behavior of
996 line-editing. This variable has to be exported to take effect.
997 YASH_AFTER_CD
999 The shell interprets and executes the value of this variable
1000 after each time the shell’s working directory is changed by the
1001 cd or other built-ins. This behavior is equivalent to executing
1002 the command eval -i -- "${YASH_AFTER_CD-}" after the directory
1003 was changed.
1004 YASH_LOADPATH
1006 This variable specifies directories the dot built-in searches
1007 for a script file. More than one directory can be specified by
1008 separating them by colons like the PATH variable. When the
1009 shell is started, this variable is initialized to the pathname
1010 of the directory where common script files are installed.
1011 YASH_LE_TIMEOUT
1013 This variable specifies how long the shell should wait for a
1014 next possible input from the terminal when it encountered an
1015 ambiguous control sequence while line-editing. The value must
1016 be specified in milliseconds. If you do not define this
1017 variable, the default value of 100 milliseconds is assumed.
1018 YASH_PS1, YASH_PS1P, YASH_PS1R, YASH_PS1S, YASH_PS2, YASH_PS2P,
1020 YASH_PS2R, YASH_PS2S, YASH_PS4, YASH_PS4S
1021 When not in the POSIXly-correct mode, if any of these variables
1022 is defined, it takes precedence over the corresponding variable
1023 without the YASH_ prefix in the name (e.g. PS1). These
1024 variables are ignored in the POSIXly-correct mode. You should
1025 define them to include yash-specific notations in the prompt,
1026 so that unhandled notations do not mangle the prompt in the
1027 POSIXly-correct mode.
1028 YASH_VERSION
1030 The value is initialized to the version number of the shell
1031 when the shell is started.
1032 Arrays
1034 An array is a variable that contains zero or more strings. The
1035 string values of an array are identified by natural numbers (like
1036 positional parameters).
1037 You can assign values to an array by using a simple command as well
1039 as the array built-in. You can use the unset built-in to remove
1040 arrays.
1041 Arrays cannot be exported as arrays. When an array is exported, it
1043 is treated as a normal variable whose value is a concatenation of
1044 all the array values, each separated by a colon.
1045 Arrays are not supported in the POSIXly-correct mode.
1047
1049 Word expansion is substitution of part of a word with another
1050 particular string. There are seven types of word expansions:
1051 1. Tilde expansion
1053 2. Parameter expansion
1055 3. Command substitution
1057 4. Arithmetic expansion
1059 5. Brace expansion
1061 6. Field splitting
1063 7. Pathname expansion (globbing)
1065 These types of expansions are performed in the order specified above.
1067 Tilde expansion, parameter expansion, command substitution, and
1069 arithmetic expansion are called the four expansions.
1070 Tilde expansion
1072 In tilde expansion, parts of words that start with a tilde (~) are
1073 substituted with particular pathnames. The part of each word that gets
1074 substituted is from the beginning of the word, which is a tilde, up to
1075 (but not including) the first slash (/) in the word. If the word does
1076 not contain a slash, the whole word is substituted. If any character in
1077 the substituted part is quoted, tilde expansion is not performed on the
1078 word.
1079 The results of expansion are determined by the format of the
1081 substituted part:
1082 ~
1084 A single tilde is substituted with the value of the HOME variable.
1085 ~username
1087 A tilde followed by a user name is substituted with the pathname of
1088 the user’s home directory.
1089 ~+
1091 ~+ is substituted with the value of the PWD variable.
1092 ~-
1094 ~- is substituted with the value of the OLDPWD variable.
1095 ~+n, ~-n
1097 where n is a non-negative integer. This type of tilde expansion
1098 yields the pathname of a directory of which ~+n or ~-n is the index
1099 in the directory stack.
1100 When tilde expansion is performed on the value of a variable assignment
1102 that occurs during execution of a simple command, the value is
1103 considered as a colon-separated list of words and those words are each
1104 subject to tilde expansion. For example, the variable assignment
1105 VAR=~/a:~/b:~/c
1107 is equivalent to
1109 VAR=/home/foo/a:/home/foo/b:/home/foo/c
1111 if the value of HOME variable is /home/foo.
1113 The POSIX standard does not prescribe how the shell should behave when
1115 it encounters an error during tilde expansion (e.g., when the HOME
1116 variable is not defined). Yash silently ignores any errors during tilde
1117 expansion; the part of the word that would be substituted is left
1118 intact.
1119 In the POSIXly-correct mode, tilde expansion supports the formats of ~
1121 and ~username only.
1122 Parameter expansion
1124 Parameter expansion expands to the value of a parameter.
1125 The syntax of typical, simple parameter expansion is ${parameter},
1127 which expands to the value of the parameter whose name is parameter.
1128 You can omit the braces (e.g., $parameter) if
1129 • parameter is a special parameter,
1131 • parameter is a positional parameter whose index is a one-digit
1133 integer, or
1134 • parameter is a variable and the parameter expansion is not followed
1136 by a character that can be used as part of a variable name. For
1137 example, ${path}-name is equivalent to $path-name, but ${path}name
1138 and $pathname are different.
1139 If parameter is none of a special parameter, positional parameter, and
1141 variable, it is a syntax error. (Some shells other than yash may treat
1142 such a case as an expansion error.)
1143 If the unset option is disabled and the parameter is an undefined
1145 variable, it is an expansion error. If the unset option is enabled, an
1146 undefined variable expands to the empty string.
1147 More complex syntax of parameter expansion allows modifying the value
1149 of a parameter.
1150 Parameter expansion
1152 ${ prefix parameter index modifier }
1153 The spaces in the syntax definition above are for readability only and
1155 must be omitted. You can omit prefix, index, and/or modifier.
1156 Prefix
1158 The prefix, if any, must be a hash sign (#). If a parameter
1159 expansion has the prefix, the result of expansion is the number of
1160 characters in the value this expansion would be expanded to without
1161 the prefix.
1162 Parameter name
1164 The parameter name (parameter) must be either
1165 • a name of a special parameter, positional parameter, or
1167 variable; or
1168 • another parameter expansion, command substitution, or
1170 arithmetic expansion.
1171 The parameter expansion is expanded to the value of the parameter.
1173 If parameter is an array variable, the values of the array are
1174 field-split like the @ special parameter unless the index [*] is
1175 specified.
1176 If parameter is another expansion, it is called a nested expansion.
1178 Nested expansion cannot be used in the POSIXly-correct mode. The
1179 braces ({ }) of a nested parameter expansion cannot be omitted.
1180 Index.sp An index allows extracting part of the parameter value (or
1181 some of array values).
1182 Index
1184 [word1]
1185 [word1,word2]
1187 where word1 and word2 are parsed in the same manner as normal tokens
1189 except that they are always delimited by , or ] and can contain
1190 whitespace characters.
1191 If there is an index in a parameter expansion, it is interpreted as
1193 follows:
1194 1. Words word1 and word2 are subjected to parameter expansion, command
1196 substitution, and arithmetic expansion.
1197 2. If there is no word2 and if word1 expands to one of *, @, and #,
1199 then that is the interpretation of index and the next step is not
1200 taken.
1201 3. The results of the previous steps (the expanded word1 and word2)
1203 are interpreted and evaluated as an arithmetic expression in the
1204 same manner as in arithmetic expansion. The resulting integers are
1205 the interpretation of index. If the results are not integers, it is
1206 an expansion error. If there is no word2, it is assumed that word2
1207 is equal to word1.
1208 If parameter is an array variable, the index specifies the part of the
1210 array. If parameter is either the * or @ special parameter, the index
1211 specifies the index range of positional parameters. In other cases, the
1212 index specifies the index range of a substring of the parameter value
1213 that is being expanded. In all cases, the specified range of the array
1214 values, positional parameters, or parameter value remains in the
1215 results of the expansion and other values are dropped.
1216 If the interpretation of index is one or two integers, the following
1218 rules apply:
1219 • If the interpreted index value is negative, it wraps around. For
1221 example, the index value of -1 corresponds to the last
1222 value/character.
1223 • It is not an error when the index value is out of range. Existing
1225 values/characters within the range are just selected.
1226 • If the interpretation of either word1 or word2 is 0, the range is
1228 assumed empty and the expansion results in nothing.
1229 If the interpretation of index is one of *, @, and #, it is treated as
1231 follows:
1232 *
1234 If parameter is an array, all the array values are field-split or
1235 concatenated in the same manner as the * special parameter. If
1236 parameter is the * or @ special parameter, the positional
1237 parameters are likewise field-split or concatenated. In other
1238 cases, the interpretation of index is treated as if the
1239 interpretation is the two integers 1 and -1.
1240 @
1242 The interpretation of index is treated as if the interpretation is
1243 the two integers 1 and -1.
1244 #
1246 The interpretation of the # index is special in that it does not
1247 simply specify a range. Instead, the expanded values are
1248 substituted with the count.
1249 If parameter is an array, the result of this parameter expansion
1251 will be the number of values in the array being expanded. If
1252 parameter is the * or @ special parameter, the result will be the
1253 number of current positional parameters. Otherwise, the result will
1254 be the number of characters in the value that is being expanded.
1255 If a parameter expansion does not contain an index, it is assumed to be
1257 [@]. In the POSIXly-correct mode, index cannot be specified.
1258 Example 1. Expansion of a normal variable
1260 The following commands will print the string ABC:
1262 var='123ABC789'
1264 echo "${var[4,6]}"
1265 Example 2. Expansion of positional parameters
1267 The following commands will print the string 2 3 4:
1269 set 1 2 3 4 5
1271 echo "${*[2,-2]}"
1272 Example 3. Expansion of an array
1274 The following commands will print the string 2 3 4:
1276 array=(1 2 3 4 5)
1278 echo "${array[2,-2]}"
1279 Modifier
1281 You can modify the value to be expanded by using modifiers:
1282 -word
1284 If the parameter name (parameter) is an undefined variable, the
1285 parameter expansion is expanded to word. It is not treated as
1286 an error if the unset option is disabled.
1287 +word
1289 If the parameter name (parameter) is an existing variable, the
1290 parameter expansion is expanded to word. It is not treated as
1291 an error if the unset option is disabled.
1292 =word
1294 If the parameter name (parameter) is an undefined variable,
1295 word is assigned to the variable and the parameter expansion is
1296 expanded to word. It is not treated as an error if the unset
1297 option is disabled.
1298 ?word
1300 If the parameter name (parameter) is an undefined variable,
1301 word is printed as an error message to the standard error. If
1302 word is empty, the default error message is printed instead.
1303 :-word, :+word, :=word, :?word
1305 These are similar to the four types of modifiers above. The
1306 only difference is that, if parameter exists and has an empty
1307 value, it is also treated as an undefined variable.
1308 #word
1310 The shell performs pattern matching against the value that is
1311 being expanded, using word as a pattern. If word matches the
1312 beginning of the value, the matching part is removed from the
1313 value and the other part remains as expansion results. The
1314 shortest matching is used if more than one matching is
1315 possible.
1316 ##word
1318 This is similar to #word above. The only difference is that the
1319 longest matching is used if more than one matching is possible.
1320 %word
1322 This is similar to #word above. The only difference is that
1323 matching is tried at the end of the value rather than at the
1324 beginning: if word matches the end of the value, the matching
1325 part is removed from the value and the other part remains as
1326 expansion results.
1327 %%word
1329 This is similar to %word above. The only difference is that the
1330 longest matching is used if more than one matching is possible.
1331 /word1/word2
1333 The shell performs pattern matching against the value that is
1334 being expanded, using word1 as a pattern. If word1 matches any
1335 part of the value, the matching part is replaced with word2 and
1336 the whole value after the replacement remains as expansion
1337 results. If word1 matches more than one part of the value, only
1338 the first part is replaced. The shortest matching is replaced
1339 if more than one matching is possible for the same starting
1340 point in the value.
1341 This modifier cannot be used in the POSIXly-correct mode.
1343 /#word1/word2
1345 This is similar to /word1/word2 above. The only difference is
1346 that word1 matches only at the beginning of the value being
1347 expanded.
1348 /%word1/word2
1350 This is similar to /word1/word2 above. The only difference is
1351 that word1 matches only at the end of the value being expanded.
1352 //word1/word2
1354 This is similar to /word1/word2 above. The only difference is
1355 that all matched parts are replaced if word1 matches more than
1356 one part of the value.
1357 :/word1/word2
1359 This is similar to /word1/word2 above. The only difference is
1360 that the value is replaced only when word1 matches the whole
1361 value.
1362 In all types of modifiers above, words are subjected to the four
1364 expansions when (and only when) they are used.
1365 If parameter is an array variable or the @ or * special parameter,
1367 modifiers affect each value of the array or all positional
1368 parameters.
1369 Command substitution
1371 Command substitution expands to output of commands specified.
1372 Command substitution
1374 $(commands)
1375 `commands`
1377 When command substitution is evaluated, commands are executed by a
1379 subshell with output pipelined to the shell. When the commands
1380 finished, command substitution is substituted with the output of the
1381 commands. Any trailing newline characters in the output are ignored.
1382 When command substitution of the form $(commands) is parsed, the
1384 commands are parsed carefully so that complex commands such as nested
1385 command substitution are parsed correctly. If commands start with (,
1386 you should put a space before commands so that the whole command
1387 substitution is not confused with arithmetic expansion. If the shell is
1388 in the POSIXly-correctly mode, the commands are parsed each time the
1389 command substitution is expanded; otherwise, commands are parsed only
1390 when the command substitution is parsed.
1391 If command substitution is of the form `commands`, the commands are not
1393 parsed when the command substitution is parsed; the commands are parsed
1394 each time the command substitution is expanded. The end of commands is
1395 detected by the first backquote character (`) after the beginning of
1396 commands that is not quoted by a backslash. Backquotes that are part of
1397 commands (typically used for nested command substitution) must be
1398 quoted by backslashes. In commands, backslashes are treated as quotes
1399 only when preceding a dollar ($), backquote, newline, or another
1400 backslash. Additionally, if the command substitution occurs inside
1401 double quotes, double quotes in commands must be quoted with a
1402 backslash. Those backslashes are removed before commands are parsed.
1403 Arithmetic expansion
1405 Arithmetic expansion evaluates an arithmetic expression and expands to
1406 the value of the expression.
1407 Arithmetic expansion
1409 $((expression))
1410 When arithmetic expansion is expanded, the expression is subject to
1412 parameter expansion, command substitution, and (nested) arithmetic
1413 expansion. The expression is parsed in (almost) same manner as an
1414 expression of the C programming language.
1415 Yash allows an expression to be either an integer (of the long type in
1417 C) or a floating-point number (of the double type in C). An operation
1418 on integers yields an integer and an operation involving a
1419 floating-point number yields a floating-point number. In the
1420 POSIXly-correct mode, you can use integers only.
1421 The following operators are available (in the order of precedence):
1423 1. ( )
1425 2. ++ -- (postfix operators)
1427 3. ++ -- + - ~ ! (prefix operators)
1429 4. * / %
1431 5. + - (binary operators)
1433 6. << >>
1435 7. < <= > >=
1437 8. == !=
1439 9. &
1441 10. ^
1443 11. |
1445 12. &&
1447 13. ||
1449 14. ? :
1451 15. = *= /= %= += -= <<= >>= &= ^= |=
1453 The ++ and -- operators cannot be used in the POSIXly-correct mode.
1455 An atomic expression can be one of an integer literal, a floating-point
1457 number literal, and a variable. Literals are parsed in the same manner
1458 as in C. An octal integer literal starts with 0, and hexadecimal with
1459 0x. A floating-point number literal may have an exponent (i.e.
1460 1.23e+6). A variable with a non-numeric value will result in an error
1461 when parsed as a number. An unset variable is treated as a value of
1462 zero if the unset option is enabled.
1463 In the POSIXly-correct mode, variables are always parsed as numbers.
1465 Otherwise, variables are parsed only when they are used as numbers in
1466 computation. Unparsed variables are left intact.
1467 set +o posixly-correct
1469 foo=bar
1470 echo $((0 ? foo : foo)) # prints "bar"
1471 echo $((foo + 0)) # error
1472 It is an expansion error if the result of an expression is not defined
1474 in C.
1475 Brace expansion
1477 Brace expansion expands to several split words with preceding and
1478 succeeding portions duplicated to each split words. Brace expansion is
1479 expanded only when the brace-expand option is enabled.
1480 Comma-separated brace expansion
1482 {word1,word2,...,wordn}
1483 Range brace expansion
1485 {start..end}
1486 {start..end..delta}
1488 Comma-separated brace expansion is expanded to each comma-separated
1490 word. For example, a{1,2,3}b is expanded to the three words a1b, a2b,
1491 and a3b.
1492 Range brace expansion is expanded to integers in the range defined by
1494 start and end. The difference between each integer can be defined by
1495 delta. If start is larger than end, the results will be in descending
1496 order. When ..delta is omitted, it defaults to 1 or -1. For example,
1497 a{1..3}b is expanded to the three words a1b, a2b, and a3b; and
1498 a{1..7..2}b to the four words a1b, a3b, a5b, and a7b.
1499 Multiple brace expansions can be used in one word. Brace expansions can
1501 also be nested. You can quote braces and/or commas to prevent them from
1502 being treated as brace expansion.
1503 Any errors in brace expansion are silently ignored.
1505 Field splitting
1507 In field splitting, words are split at predefined separators.
1508 Field splitting can occur only within parts of words that resulted from
1510 parameter expansion, command substitution, and arithmetic expansion
1511 that are not between double-quotation marks. Expansion results of the @
1512 special parameter are exceptionally split even between double-quotation
1513 marks.
1514 Separators used in field splitting are defined by the value of the IFS
1516 variable. If the variable does not exist, the value is assumed to be
1517 the three characters of space, tab, and newline.
1518 Characters included in the value of the IFS variable are called IFS
1520 characters. IFS characters that are any of space, tab, and newline are
1521 called IFS whitespace and other IFS characters are called IFS
1522 non-whitespace.
1523 Field splitting is performed as follows:
1525 1. The shell searches words for split points. A split point is one or
1527 more adjacent IFS characters within the word portions where field
1528 splitting can occur. The following steps are taken for each split
1529 point found.
1530 2. If the split point includes one or more IFS non-whitespaces, all
1532 the IFS whitespaces in the split point are ignored and the word is
1533 split at each IFS non-whitespace in the split point.
1534 3. If the split point includes no IFS non-whitespaces, the word is
1536 split at the split point unless it is at the beginning or end of
1537 the word.
1538 4. The split points are removed from the results.
1540 Finally, the last word is removed from the results if:
1542 • the empty-last-field option is not enabled;
1544 • the result is more than one word; and
1546 • the last word is empty.
1548 Note
1550 Words are not split at all when the value of the IFS variable is
1551 empty.
1552 Pathname expansion
1554 Pathname expansion performs pattern matching and expands to pathnames
1555 matched by the pattern.
1556 A word subjected to pathname expansion is treated as a pattern. If one
1558 or more pathnames are found that are matched by the pattern, the
1559 pathnames become the results of the pathname expansion.
1560 Pathname expansion is not performed when the glob option is disabled.
1562 The shell searches readable directories for matching pathnames.
1564 Unreadable directories are silently ignored.
1565 The following options affect the behavior of pathname expansion:
1567 null-glob
1569 This option affects the result of pathname expansion when no
1570 matching pathnames are found. If enabled, the result is no word. If
1571 disabled, the result is the original pattern word.
1572 case-glob
1574 This option specifies case-sensitivity in matching. If enabled,
1575 pattern matching is done case-sensitively.
1576 dot-glob
1578 This option affects matching of filenames that start with a period
1579 (.). If disabled, a period at the beginning of a filename does not
1580 match wildcard patterns (? and *) or bracket expressions. If
1581 enabled, there is no such special treatment of periods.
1582 mark-dirs
1584 If enabled, each resulting pathname that is a directory name is
1585 suffixed by a slash (/).
1586 extended-glob
1588 This option enables the extension. (See below)
1589 Any errors in pathname expansion are silently ignored. If the word is
1591 an invalid pattern, it just becomes the result. The results depend on
1592 the null-glob option when no matching pathnames are found.
1593 Pattern matching is done for each filename (or pathname component) of
1595 pathnames. The shell skips matching for literal patterns that contain
1596 no wildcards or bracket expressions. As a result, the patterns /*/foo
1597 and /*/fo[o] may yield different expansion results when the case-glob
1598 option is disabled; for example, the pattern /*/fo[o] matches the
1599 pathname /bar/FOO but the pattern /*/foo does not because matching is
1600 skipped for foo.
1601 Extension in pathname expansion
1603 The following patterns can be used when the extended-glob option is
1604 enabled.
1605 **
1607 The directory is searched recursively and the pattern matches
1608 any number of directory filenames (each separated by a slash).
1609 Any directory whose name begins with a period is excluded from
1610 search. For example, the pattern dir/**/file can match the
1611 pathnames dir/file, dir/foo/file, dir/a/b/c/file, etc.
1612 This pattern is not effective when appearing at the end of the
1614 whole pattern (i.e. foo/bar/**).
1615 .**
1617 This pattern is like **, but all directories are searched
1618 including ones with a name starting with a period.
1619 ***
1621 This pattern is like **, but if a symbolic link to a directory
1622 is found during recursive search, the directory is searched
1623 recursively as well.
1624 .***
1626 This pattern is like ***, but all directories are searched
1627 including ones with a name starting with a period.
1628
1630 Pattern matching notation is a syntax of patterns that represent
1631 particular sets of strings. When a string is included in the set of
1632 strings a pattern represents, the pattern is said to match the string.
1633 Whether a pattern matches a string or not is defined as follows.
1634 Normal characters
1636 A character that is not quoted or any of special characters defined
1637 below is a normal character, which matches the character itself.
1638 For example, the pattern abc matches the string abc, and not any other
1640 strings.
1641 Single-character wildcard
1643 The character ? matches any single character.
1644 For example, the pattern a?c matches any three-character strings that
1646 starts with a and ends with c, such as aac, abc, and a;c.
1647 Multi-character wildcard
1649 The character * matches any strings (of any length, including the empty
1650 string).
1651 For example, the pattern a*c matches any string that starts with a and
1653 ends with c, such as ac, abc, and a;xyz;c.
1654 Bracket expression
1656 A pattern that is enclosed by brackets ([ and ]) is a bracket
1657 expression. A bracket expression must have at least one character
1658 between the brackets. The characters between the brackets are
1659 interpreted as a bracket expression pattern, which is a below-defined
1660 special notation for bracket expression. A bracket expression pattern
1661 represents a set of characters. The bracket expression matches any one
1662 of the characters in the set the bracket expression pattern represents.
1663 If the opening bracket ([) is followed by an exclamation mark (!), the
1665 exclamation is not treated as part of the bracket expression pattern
1666 and the whole bracket expression instead matches a character that is
1667 not included in the set the bracket expression pattern represents. If
1668 the opening bracket is followed by a caret (^), it is treated like an
1669 exclamation mark as above (but shells other than yash may treat the
1670 caret differently).
1671 If the opening bracket (or the following exclamation or caret, if any)
1673 is followed by a closing bracket (]), it is treated as part of the
1674 bracket expression pattern rather than the end of the bracket
1675 expression. You cannot quote characters in the bracket expression
1676 pattern because quotation is treated before bracket expression.
1677 An opening bracket in a pattern is treated as a normal character if it
1679 is not the beginning of a valid bracket expression.
1680 Normal characters (in bracket expression pattern)
1682 A character that is not any of special characters defined below is a
1683 normal character, which represents the character itself.
1684 For example, the bracket expression pattern abc represents the set of
1686 the three characters a, b, and c. The bracket expression [abc]
1687 therefore matches any of the three characters.
1688 Range expressions
1690 A hyphen preceded and followed by a character (or collating symbol) is
1691 a range expression, which represents the set of the two characters and
1692 all characters between the two in the collation order. A collation
1693 order is an order of characters that is defined in the locale data.
1694 If a hyphen is followed by a closing bracket (]), the bracket is
1696 treated as the end of the bracket expression and the hyphen as a normal
1697 character.
1698 For example, the range expression 3-5 represents the set of the three
1700 characters 3, 4, and 5. The bracket expression [3-5-] therefore matches
1701 one of the four characters 3, 4, 5, and -.
1702 Collating symbols
1704 A collating symbol allows more than one character to be treated as a
1705 single character in matching. A collating symbol is made up of one or
1706 more characters enclosed by the special brackets [. and .].
1707 One or more characters that are treated as a single character in
1709 matching are called a collating element. Precisely, a bracket
1710 expression pattern represents a set of collating elements and a bracket
1711 expression matches a collating element rather than a character, but we
1712 do not differentiate them for brevity here.
1713 For example, the character combination “ch” was treated as a single
1715 character in the traditional Spanish language. If this character
1716 combination is registered as a collating element in the locale data,
1717 the bracket expression [[.ch.]df] matches one of ch, d, and f.
1718 Equivalence classes
1720 An equivalence class represents a set of characters that are considered
1721 equivalent. A equivalence class is made up of a character (or more
1722 precisely, a collating element) enclosed by the special brackets [= and
1723 =].
1724 An equivalence class represents the set of characters that consists of
1726 the character enclosed by the brackets and the characters that are in
1727 the same primary equivalence class as the enclosed character. The shell
1728 consults the locale data for the definition of equivalence classes in
1729 the current locale.
1730 For example, if the six characters a, à, á, â, ã, ä are defined to be
1732 in the same primary equivalence class, the bracket expressions [[=a=]],
1733 [[=à=]], and [[=á=]] match one of the six.
1734 Character classes
1736 A character class represents a predefined set of characters. A
1737 character class is made up of a class name enclosed by the special
1738 brackets [: and :]. The shell consults the locale data for which class
1739 a character belongs to.
1740 The following character classes can be used in all locales:
1742 [:lower:]
1744 set of lowercase letters
1745 [:upper:]
1747 set of uppercase letters
1748 [:alpha:]
1750 set of letters, including the [:lower:] and [:upper:] classes.
1751 [:digit:]
1753 set of decimal digits
1754 [:xdigit:]
1756 set of hexadecimal digits
1757 [:alnum:]
1759 set of letters and digits, including the [:alpha:] and [:digit:]
1760 classes.
1761 [:blank:]
1763 set of blank characters, not including the newline character
1764 [:space:]
1766 set of space characters, including the newline character
1767 [:punct:]
1769 set of punctuations
1770 [:print:]
1772 set of printable characters
1773 [:cntrl:]
1775 set of control characters
1776 For example, the bracket expression [[:lower:][:upper:]] matches a
1778 lower or upper case character. In addition to the classes listed above,
1779 other classes may be used depending on the definition of the current
1780 locale.
1781
1783 Redirection is a feature you can use to modify file descriptors of
1784 commands. By using redirection, you can execute commands with their
1785 standard input/output connected with files or devices other than the
1786 terminal.
1787 You can do redirection by adding redirection operators to a command
1789 (simple command or compound command) In a simple command, redirection
1790 operators may appear anywhere in the command as long as operator tokens
1791 are separated from other tokens. In a compound command, redirection
1792 operators must appear at the end of the command.
1793 Redirection operators are processed before the command body is
1795 executed. More than one redirection operator in a command are processed
1796 in the order of appearance. Redirection operators affect only the
1797 command in which they appear, except when they appear in an exec
1798 built-in without command operands. That is, file descriptors modified
1799 by redirection are restored after the command has finished.
1800 A redirection operator starts with < or >. Redirection operators
1802 starting with < affects the standard input (file descriptor 0) by
1803 default. Redirection operators starting with > affects the standard
1804 output (file descriptor 1) by default. To affect another file
1805 descriptor, you can prefix a redirection operator with a non-negative
1806 integer; the operator will affect the file descriptor specified by the
1807 integer. The integer must immediately precede the < or > without any
1808 whitespaces in between. The integer must not be quoted, either.
1809 Redirection to files
1811 The most common type of redirection is redirection to files.
1812 Redirection of input
1814 < token
1815 Redirection of output
1817 > token
1818 >| token
1820 >> token
1822 Redirection of input and output
1824 <> token
1825 The token is subject to the four expansions. It is also subject to
1827 pathname expansion if the shell is interactive. The expansion result is
1828 treated as the pathname of the file to which redirection is performed.
1829 If the pathname expansion does not result in a single pathname, it is
1830 an error.
1831 In redirection of input, the standard input is replaced with a file
1833 descriptor which is open for read-only access to the target file. If
1834 the target file cannot be opened for read-only access, it is an error.
1835 In redirection of output, the standard output is replaced with a file
1837 descriptor which is open for write-only access to the target file. If
1838 the target file cannot be opened for write-only access, it is an error.
1839 If the target file does not exist, a new empty file is created and
1840 opened. If the target file already exists, the file is opened as
1841 follows:
1842 • For the >| operator, the file is emptied when opened if it is a
1844 regular file.
1845 • For the > operator, the behavior is the same as the >| operator if
1847 the clobber option is enabled. If the option is disabled and the
1848 file is a regular file, it is treated as an error.
1849 • For the >> operator, the file is opened for appending; any output
1851 to the file descriptor is appended to the end of the file.
1852 In redirection of input and output, the standard input is replaced with
1854 a file descriptor which is open for read-and-write access to the target
1855 file. If the file does not exist, a new empty file is created and
1856 opened.
1857 Socket redirection
1859 If the pathname of the target file is of the form
1860 /dev/tcp/host/port or /dev/udp/host/port and the file cannot be
1861 opened in the usual manner, a new socket is opened for
1862 communication with the port of the host. The redirection replaces
1863 the standard input or output with the file descriptor to the
1864 socket.
1865 A stream socket is opened for the form /dev/tcp/host/port and a
1867 datagram socket for the form /dev/udp/host/port. The protocol
1868 actually used for communication is determined by the socket library
1869 the shell uses. Typically, stream sockets use TCP and datagram
1870 sockets UDP.
1871 In socket redirection, the file descriptor is both readable and
1873 writable regardless of the type of the redirection operator used.
1874 Socket redirection is yash’s extension that is not defined in
1876 POSIX. Bash as well has socket redirection as extension.
1877 Duplication of file descriptors
1879 Redirection allows duplicating or closing existing file descriptors.
1880 Duplication of file descriptor
1882 <& token
1883 >& token
1885 The token is subject to expansion as in redirection to files, but it is
1887 treated as a file descriptor rather than a pathname. Thus the expanded
1888 token must be a non-negative integer.
1889 The <& and >& operators duplicate the file descriptor specified by
1891 token to the standard input and output, respectively. (The operators
1892 can be prefixed with a non-negative integer so that the file descriptor
1893 is duplicated to a file descriptor other than the standard input or
1894 output.)
1895 If the expanded token is a single hyphen rather than a non-negative
1897 integer, the file descriptor is closed rather than duplicated. By
1898 default, the <& and >& operators close the standard input and output,
1899 respectively, but the operators can be prefixed with a non-negative
1900 integer so that another file descriptor is closed.
1901 In the POSIXly-correct mode, a file descriptor must be readable when
1903 duplicated by the <& operator and writable when duplicated by the >&
1904 operator.
1905 Here documents and here strings
1907 Here document and here string allow redirection to file descriptors
1908 that reads strings directly specified in shell commands.
1909 Here document
1911 << token
1912 <<- token
1914 Here string
1916 <<< token
1917 In a here document or here string, the standard input is replaced with
1919 a readable file descriptor. When the command reads from the file
1920 descriptor, it will read the contents of the here document/string,
1921 which is defined below.
1922 When a here document operator (<< or <<-) appears in a command, the
1924 shell reads the contents of the here document starting from the next
1925 line. The contents of here documents are not parsed nor executed as
1926 commands. The token after the operand specifies a delimiter that
1927 indicates the end of the contents. (The token is not subject to any
1928 expansion, but quotation is processed.) The contents of the here
1929 document is terminated just before the first line containing the token
1930 only. When using the <<- operator, all tab characters at the beginning
1931 of each line in the here document contents are removed and the
1932 delimiter token may be preceded by tab characters.
1933 If there are more than one here document operator on one line, the
1935 contents of the here documents are parsed in order: The contents of the
1936 first here document starts from the next line and ends before the first
1937 line containing the token that followed the first operator. Just after
1938 that line, the contents of the second here document starts, and so on.
1939 The contents of here documents are treated literally: whitespaces,
1941 tabs, etc. remain as is. The exception is that, when the token is not
1942 quoted at all:
1943 • the contents are subject to parameter expansion, command
1945 substitution, arithmetic expansion.
1946 • a backslash in the contents is treated as quotation if and only if
1948 it precedes $, `, ", or another backslash.
1949 • a backslash followed by a newline is treated as line continuation.
1951 In here string, the token after the operator is subject to expansion as
1953 in redirection to files. The expansion result becomes the contents of
1954 the here string. A newline character is automatically appended to the
1955 end of here string contents.
1956 Here string is yash’s extension that is not defined in POSIX. Other
1958 shells like bash, ksh, and zsh have the same feature.
1959 Pipeline redirection
1961 Pipeline redirection allows opening pipelines that can be used for
1962 arbitrary purposes.
1963 Pipeline redirection
1965 >>| token
1966 The token is subject to expansion as in redirection to files, but it is
1968 treated as a file descriptor rather than a pathname. Thus the expanded
1969 token must be a non-negative integer.
1970 Pipeline redirection opens a new pipeline. The standard output (or the
1972 file descriptor specified before the operator, if any) is replaced with
1973 the file descriptor open for writing to the pipeline. The file
1974 descriptor specified by token is replaced with the file descriptor open
1975 for reading from the pipeline.
1976 Pipeline redirection is yash’s extension that is not defined in POSIX.
1978 Process redirection
1980 Process redirection creates a pipeline connected to another command.
1981 Process redirection
1983 <(command...)
1984 >(command...)
1986 In process redirection, the command specified is executed in a
1988 subshell. If the process redirection is of the form <(command...), the
1989 standard output of command is connected with a pipeline to the standard
1990 input of the command the redirection is associated with. If the process
1991 redirection is of the form >(command...), the standard input of command
1992 is connected with a pipeline to the standard output of the command the
1993 redirection is associated with.
1994 Process redirection is yash’s extension that is not defined in POSIX.
1996 Bash and zsh have a feature called process substitution, which uses the
1997 same syntax as yash’s process redirection, but incompatibly differs in
1998 behavior.
1999
2001 This section describes how commands are executed.
2002 Execution of simple commands
2004 A simple command is executed as follows:
2005 1. All tokens in the simple command are expanded except for assignment
2007 and redirection tokens. If an error occurs during expansion, the
2008 execution of the simple command is aborted with a non-zero exit
2009 status.
2010 In the following steps, the first word of the expansion results is
2012 referred to as command name, and the other words as command
2013 arguments. If there is only one word of the expansion results,
2014 there are no command argument words. If there are none of the
2015 expansion results, there is no command name either.
2016 2. If the command name exists and there are any redirections specified
2018 in the command, they are processed. The word token after each
2019 redirection operator is expanded. If an error occurs during
2020 processing the redirections (including when expanding the word
2021 token), the execution of this simple command is aborted with a
2022 non-zero exit status.
2023 Note
2025 In other shells, redirections may be processed in a different
2026 step: POSIX does not specify the order in which redirections
2027 and assignments are processed when there is no command name or
2028 the name denotes a special built-in.
2029 3. Assignments specified in the command, if any, are processed. For
2031 each assignment token, the value is expanded and assigned to the
2032 specified variable. If an error occurs during assignments
2033 (including when expanding the values to be assigned), the execution
2034 of this simple command is aborted with a non-zero exit status.
2035 • If there is no command name or the name denotes a special
2037 built-in, the assignments are permanent: the assigned values
2038 remain after the command has finished (until the variable is
2039 reassigned).
2040 • Otherwise, the assignments are temporary: the assigned values
2042 only last during the execution of this simple command.
2043 The assigned variables are automatically exported when the command
2045 name is specified or the all-export option is enabled.
2046 Note
2048 In other shells, assignments may behave differently: For
2049 special built-ins and functions, assigned variables may not be
2050 exported. For functions, assigned variables may be persistent,
2051 that is, may remain even after the execution of the simple
2052 command.
2053 4. If there is no command name, the redirections are processed in a
2055 subshell, then the command execution ends. If an error occurs in
2056 the redirections, the exit status of the simple command is
2057 non-zero. If there were any command substitutions performed in the
2058 assignments, the exit status of the simple command is that of the
2059 last executed command substitution. Otherwise, the exit status is
2060 zero.
2061 5. A command to be executed is determined using the command search
2063 algorithm and the command is executed.
2064 • If the command is an external command, the command is executed
2066 by creating a new subshell and calling the “exec” system call
2067 in the subshell. The command name and arguments are passed to
2068 the executed command. Exported variables are passed to the
2069 executed command as environment variables.
2070 • If the command is a built-in, the built-in is executed with the
2072 command arguments passed to the built-in. As an exception, in
2073 the POSIXly-correct mode, the built-in is not executed if it is
2074 an elective built-in.
2075 • If the command is a function, the contents of the function are
2077 executed with the command arguments as function arguments.
2078 If the command was executed, the exit status of this simple command
2080 is that of the executed command. If the algorithm failed to
2081 determine a command, no command is executed and the exit status is
2082 127. If the shell failed to execute the determined command, the
2083 exit status is 126. If the executed command was killed by a signal,
2084 the exit status is the signal number plus 384. If the elective
2085 built-in was not executed in the POSIXly-correct mode, the exit
2086 status is 127.
2087 Note
2089 In shells other than yash, the exit status may be different
2090 when the command was killed by a signal, because the POSIX
2091 standard only requires that the exit status be "greater than
2092 128."
2093 If the shell is not in the POSIXly-correct mode and the algorithm
2094 failed to determine a command, the command eval -i --
2095 "${COMMAND_NOT_FOUND_HANDLER-}" is evaluated. During the command
2096 execution, positional parameters are temporarily set to the command
2097 name and arguments that resulted in the first step. Any local
2098 variables defined during the execution are removed when the
2099 execution is finished. The HANDLED local variable is automatically
2100 defined with the initial value being the empty string. If the
2101 HANDLED variable has a non-empty value when the execution of the
2102 command string is finished, the shell pretends that the command was
2103 successfully determined and executed. The exit status of the simple
2104 command is that of the command string in this case.
2105 Command search
2107 A command that is executed in a simple command is determined by the
2108 command name using the following algorithm:
2109 1. If the command name contains a slash (/), the whole name is
2111 treated as the pathname of an external command. The external
2112 command is determined as the executed command.
2113 2. If the command name is a special built-in, the built-in is
2115 determined as the executed command.
2116 3. If the command name is the name of an existing function, the
2118 function is determined as the executed command.
2119 4. If the command name is a mandatory or elective built-in, the
2121 built-in is determined as the executed command.
2122 5. If the command name is an extension built-in and the shell is
2124 not in the POSIXly-correct mode, the built-in is determined as
2125 the executed command.
2126 6. The shell searches the PATH for a executed command:
2128 The value of the PATH variable is separated by colons. Each
2130 separated part is considered as a directory pathname (an empty
2131 pathname denotes the current working directory). The shell
2132 searches the directories (in the order of appearance) and
2133 checks if any directory directly contains an executable regular
2134 file whose name is equal to the command name. If such a file is
2135 found:
2136 • If the command name is the name of a substitutive built-in,
2138 the built-in is determined as the executed command.
2139 • Otherwise, the file is determined as the executed command.
2141 (The file will be executed as an external command.)
2142 If no such file is found, no command is determined as the
2144 executed command.
2145 When the shell finds a file that matches the command name during
2147 the search above, the shell remembers the pathname of the file if
2148 it is an absolute path. When the algorithm above is used for the
2149 same command name again, the shell skips searching and directly
2150 determines the command to be executed. If an executable regular
2151 file no longer exists at the remembered pathname, however, the
2152 shell searches again to update the remembered pathname. You can
2153 manage remembered pathnames using the hash built-in.
2154 Termination of the shell
2156 The shell exits when it reached the end of input and has parsed and
2157 executed all input commands or when the exit built-in is executed. The
2158 exit status of the shell is that of the last command the shell executed
2159 (or zero if no commands were executed). The exit status of the shell is
2160 always between 0 and 255 (inclusive). If the exit status of the last
2161 command is 256 or larger, the exit status of the shell will be the
2162 remainder of the exit status divided by 256.
2163 If an exit handler has been registered by the trap built-in, the
2165 handler is executed just before the shell exits. The exit status of the
2166 commands executed in the handler does not affect the exit status of the
2167 shell.
2168 If a non-interactive shell encountered one of the following errors, the
2170 shell immediately exits with a non-zero exit status:
2171 • A command cannot be parsed due to an syntax error (except during
2173 shell initialization).
2174 • An error occurs during execution of a special built-in in the
2176 POSIXly-correct mode.
2177 • A redirection error occurs in a simple command whose command name
2179 is a special built-in and the shell is in the POSIXly-correct mode.
2180 • An assignment error occurs in a simple command.
2182 • An error occurs during expansion (except during shell
2184 initialization).
2185 Note
2187 Some shells other than yash exit when they fail to find a command
2188 to execute in command search.
2189 Functions
2191 Functions allow executing a compound command as a simple command. A
2192 function can be defined by the function definition command and executed
2193 by a simple command. You can use the unset built-in to remove function
2194 definitions.
2195 There are no functions predefined when yash is started.
2197 A function is executed by executing its body, which is a compound
2199 command. While the function is being executed, positional parameters
2200 are set to the arguments given to the function. The old positional
2201 parameters are restored when the function execution finishes.
2202 Local variables
2204 Local variables are temporary variables that are defined in a
2205 function and exist during the function execution only. They can be
2206 defined by the typeset built-in or implicitly created by a for
2207 loop. They are removed when the function execution finishes.
2208 Local variables may hide variables that have already been defined
2210 before the function execution had started. An existing variable
2211 becomes inaccessible if a local variable of the same name is
2212 defined in a function. The old variable becomes accessible again
2213 when the function execution finishes.
2214 You cannot create a local variable when not executing a function. A
2216 normal variable is created if you try to do so.
2217 Command execution environment
2219 The shell holds following properties during execution.
2220 • The working directory
2222 • Open file descriptors
2224 • The file creation mask (umask)
2226 • The set of signals whose handler is set to “ignore” (trap)
2228 • Environment variables
2230 • Resource limits (ulimit)
2232 Those properties are inherited from the invoker of the shell to the
2234 shell, and from the shell to each external command executed by the
2235 shell.
2236 The properties can be changed during the execution of the shell by
2238 built-in commands, variable assignments, etc.
2239 Subshells
2241 A subshell is a copy of the shell process. Subshells are used in
2242 execution of groupings, pipelines, etc.
2243 Subshells inherit functions, aliases, etc. defined in the shell as
2245 well as the properties above since subshells are copies of the
2246 shell process. Notable exceptions are:
2247 • Traps registered by the trap built-in are all reset in
2249 subshells except for ones whose action is set to “ignore”. (See
2250 below)
2251 • The interactive mode and job control are disabled in subshells.
2253 Jobs are not inherited by subshells.
2254 Subshells are executed independently of the original shell, so
2256 changes of any properties above do not affect those of the original
2257 shell.
2258 Note
2260 If the subshell contains a single trap built-in, some shells
2261 (but not yash) may not reset the traps on entry to the
2262 subshell.
2263
2265 The interactive mode is a mode of the shell intended for direct
2266 interaction with a user. If yash is in the interactive mode, it is
2267 called an interactive shell.
2268 Whether a shell runs in the interactive mode or not is determined in
2270 the invocation of the shell. After the shell has started up, the
2271 interactive mode cannot be switched on or off.
2272 When the shell is interactive:
2274 • Initialization scripts are executed during invocation.
2276 • The shell checks for mail and prints a command prompt when it reads
2278 a command. Job status changes are also reported if job control is
2279 active. Line-editing may be used depending on the capability of
2280 the terminal.
2281 • Commands executed are automatically registered in command history.
2283 • If a command executed by the shell is killed by a signal other than
2285 SIGINT and SIGPIPE, the shell reports the fact to the standard
2286 error.
2287 • The filename token is subject to pathname expansion in file
2289 redirection.
2290 • The shell does not exit when it encounters a syntax or expansion
2292 error during command execution. (cf. Termination of the shell)
2293 • The shell does not exit when it receives the SIGINT, SIGTERM, or
2295 SIGQUIT signal.
2296 • A signal handler can be changed by the trap built-in even if the
2298 handler had been set to “ignore” when the shell was invoked.
2299 • The value of the - special parameter contains i.
2301 • The shell’s locale reflects the value of the LC_CTYPE variable
2303 whenever the value is changed (if the shell is not in the
2304 POSIXly-correct mode).
2305 • Commands are executed even when the exec option is off.
2307 • The ignore-eof option takes effect when enabled.
2309 • When the shell reaches the end of input or the exit built-in is
2311 executed, the shell checks if there is any stopped job. If so, the
2312 shell prints a warning and does not actually exit.
2313 • The suspend built-in by default cannot stop the shell if it is a
2315 session leader.
2316 • The shell does not exit when the dot built-in fails to find a
2318 script file to read.
2319 • The shell does not exit when the exec built-in fails to execute a
2321 command (if not in the POSIXly-correct mode).
2322 • When a job finished for which the wait built-in has been waiting,
2324 the fact is reported (only if job control is active and not in the
2325 POSIXly-correct mode).
2326 • A prompt is printed when the read built-in reads a second or
2328 following line.
2329 Prompts
2331 The interactive shell prints a prompt just before it reads a command.
2332 The contents of the prompt is specified by the value of the PS1 and PS2
2333 variables. The former is used for reading the first line of the command
2334 and the latter for other lines.
2335 When the prompt is printed, the variable value is subjected to
2337 parameter expansion, command substitution, and arithmetic expansion
2338 (but note that the POSIX standard requires parameter expansion only).
2339 The result of the expansion is parsed by the rules below to make the
2340 actual prompt string, which is printed to the standard error.
2341 In the POSIXly-correct mode, each exclamation mark (!) in the string is
2343 substituted with the command history number of the command that is
2344 being input. Two adjacent exclamation marks (!!) are printed as a
2345 single exclamation. Other characters are printed intact.
2346 If the shell is not in the POSIXly-command mode, the following
2348 notations can be used to format the prompt string. Notations are
2349 replaced with the strings designated in the list below. Characters that
2350 are not interpreted as notations are printed intact.
2351 \a
2353 Bell character (ASCII code: 7)
2354 \e
2356 Escape character (ASCII code: 27)
2357 \j
2359 The number of jobs in the shell.
2360 \n
2362 Newline character (ASCII code: 10)
2363 \r
2365 Carriage return character (ASCII code: 13)
2366 \!
2368 The command history number of the command that is being input
2369 \$
2371 # if the shell’s effective user ID is 0; $ otherwise.
2372 \\
2374 Backslash
2375 \[, \]
2377 These two notations can surround part of the prompt string that is
2378 not visible on the terminal. The surrounded part is ignored when
2379 the shell counts the number of characters that is displayed on the
2380 terminal, thus making characters correctly aligned on the terminal
2381 when the prompt string contains special invisible characters.
2382 \ffontspecs.
2384 When line-editing is active, this notation is replaced with special
2385 characters to change font styles on the terminal if the terminal is
2386 capable of it. If line-editing is inactive or the terminal is
2387 incapable of changing font styles, this notation is silently
2388 ignored. One or more of the following can be used for fontspecs:
2389 k
2391 Change font color to black
2392 r
2394 Change font color to red
2395 g
2397 Change font color to green
2398 y
2400 Change font color to yellow
2401 b
2403 Change font color to blue
2404 m
2406 Change font color to magenta
2407 c
2409 Change font color to cyan
2410 w
2412 Change font color to white
2413 K
2415 Change background color to black
2416 R
2418 Change background color to red
2419 G
2421 Change background color to green
2422 Y
2424 Change background color to yellow
2425 B
2427 Change background color to blue
2428 M
2430 Change background color to magenta
2431 C
2433 Change background color to cyan
2434 W
2436 Change background color to white
2437 t
2439 Make font color or background brighter (can only be used just
2440 after one of the characters above)
2441 d
2443 Change font and background colors to normal
2444 s
2446 Make font standout
2447 u
2449 Make font underlined
2450 v
2452 Make font and background colors reversed
2453 b
2455 Make font blink
2456 i
2458 Make font dim
2459 o
2461 Make font bold
2462 x
2464 Make font invisible
2465 D
2467 Make color and style normal
2468 The actual colors of font and background are defined by the
2470 terminal. Different terminals may use different colors.
2471 In addition to the normal prompt, a prompt string can be displayed to
2473 the right of the cursor if line-editing is active. Those prompts are
2474 called right prompts. The contents of right prompts are defined by the
2475 value of the PS1R and PS2R variables, each corresponding to the PS1 and
2476 PS2 variables.
2477 Using the above-said notations, the font style of command strings the
2479 user inputs can be changed as well as that of prompts. The font style
2480 of command strings is defined by the value of the PS1S and PS2S
2481 variables, each corresponding to the PS1 and PS2 variables. The value
2482 can contain the \ffontspecs. notation only. If you enable command line
2483 prediction, the predicted part of the command line can also be styled
2484 with the PS1P and PS2P variables.
2485 When the shell is not in the POSIXly-correct mode, the prompt variables
2487 can be defined with a name prefixed with YASH_ (e.g. YASH_PS1). This
2488 allows using a different prompt string than that in the POSIXly-correct
2489 mode.
2490 When the shell is not in the POSIXly-correct mode, the value of the
2492 PROMPT_COMMAND variable is executed before each prompt.
2493 Command history
2495 Command history is a feature of the shell that remembers executed
2496 commands to allow re-executing them later. Commands executed in the
2497 interactive mode are automatically saved in the command history. Saved
2498 commands can be edited and re-executed using line-editing and the fc
2499 and history built-ins.
2500 Commands are saved line by line. Lines that do not contain any
2502 non-whitespace characters are not saved in the history. Lines that
2503 start with whitespaces are not saved when the hist-space option is on.
2504 Command history is saved in a file. When history is first used after an
2506 interactive shell was started, the shell opens a file to save history
2507 in. The filename is specified by the value of the HISTFILE variable. If
2508 the file contains history data when opened, the data is restored to the
2509 shell’s history. The file contents are updated in real time as the user
2510 inputs commands into the shell. If the HISTFILE variable is not set or
2511 the file cannot be opened successfully, history is not saved in the
2512 file, but the history feature will be functional in all other respects.
2513 The number of commands saved in history is specified by the value of
2515 the HISTSIZE variable. The shell automatically removes old history data
2516 so that the number of saved commands does not exceed the value. If the
2517 HISTSIZE variable is not set or its value is not a natural number, 500
2518 items will be saved in history.
2519 The shell looks at the value of the HISTFILE and HISTSIZE variables
2521 only when the history feature is first used after the shell was
2522 started. “The history feature is used” when:
2523 • the fc or history built-in is executed,
2525 • line-editing is used (regardless of whether or not history data is
2527 recalled in line-editing), or
2528 • a command is input to the shell
2530 Therefore, the variables should be set in initialization scripts.
2532 When more than one instance of yash shares a single history file, all
2534 the shells use the same history data. As a result, commands that have
2535 been executed by a shell instance can be recalled on another shell
2536 instance. Shells sharing the same history should have the same HISTSIZE
2537 value so that they manipulate history data properly.
2538 Yash’s history data file has its own format that is incompatible with
2540 other kinds of shells.
2541 The HISTRMDUP variable can be set to remove duplicate history items.
2543 Mail checking
2545 An interactive shell can notify receipt of email. The shell
2546 periodically checks the modification date/time of a file specified by
2547 the user. If the file has been modified since the previous check, the
2548 shell prints a notification message (except when the shell is not in
2549 the POSIXly-correct mode and the file is empty). By specifying a
2550 mailbox file to be checked, the shell will print a message when the
2551 file has been modified, that is, some mail has been received.
2552 Check is done just before the shell prints a command line prompt. The
2554 interval of checks can be specified by the MAILCHECK variable in
2555 seconds. If the variable value is 0, check is done before every prompt.
2556 If the variable value is not a non-negative integer, no checks are
2557 done.
2558 The file whose modification time is checked is specified by the MAIL
2560 variable. The variable value should be set to the pathname of the file.
2561 If you want to check more than one file or customize the notification
2563 message, you can set the MAILPATH variable instead of the MAIL
2564 variable. When the MAILPATH variable is set, the MAIL variable is
2565 ignored. The value of the MAILPATH variable should be set to one or
2566 more colon-separated pathnames of files to be checked. Each pathname
2567 can be followed by a percent sign (%) and a custom notification
2568 message, which is printed when the corresponding file has been
2569 modified. If the pathname contains a percent sign, it should be quoted
2570 by a backslash. The specified message is subject to parameter
2571 expansion. For example, if the value of the MAILPATH variable is
2572 /foo/mail%New mail!:/bar/mailbox%You've got mail:/baz/mail\%data, the
2573 shell will print
2574 • New mail! when the file /foo/mail has been modified
2576 • You've got mail when the file /bar/mailbox has been modified
2578 • the default message when the file /baz/mail%data has been modified.
2580
2582 Job control is a function of the shell that executes multiple commands
2583 simultaneously and suspends/resumes the commands.
2584 When job control is active:
2586 • Every pipeline executed by the shell becomes a job. A job has its
2588 unique process group ID that is shared among all processes in the
2589 job.
2590 • If the processes of a job are suspended while the shell is waiting
2592 for the processes to finish, the shell continues to the next
2593 command as if the process have finished. The shell remembers the
2594 job as suspended so that it can be resumed later.
2595 • If a job is executed synchronously, the shell sets the foreground
2597 process group of the terminal to the process group of the job. When
2598 the job is finished (or suspended), the shell gets back to the
2599 foreground.
2600 • If the shell is interactive, job status is reported before every
2602 command line prompt as if the command jobs -n is executed.
2603 • The standard input of an asynchronous command is not automatically
2605 redirected to /dev/null.
2606 • The shell does not stop when it receives the SIGTTIN, SIGTTOU, or
2608 SIGTSTP signal.
2609 • The value of the - special parameter contains m.
2611 • When a job finished for which the wait built-in has been waiting,
2613 the fact is reported (only if the shell is interactive and not in
2614 the POSIXly-correct mode).
2615 When job control is inactive, processes executed by the shell have the
2617 same process group ID as the shell. The shell treats asynchronous
2618 commands as an uncontrolled job.
2619 You can use the following built-ins to manipulate jobs:
2621 jobs
2623 prints existing jobs
2624 fg and bg
2626 run jobs in the foreground or background
2627 wait
2629 waits for jobs to be finished (or suspended)
2630 disown
2632 forgets jobs
2633 kill
2635 sends a signal to jobs
2636 An interactive job-controlling shell reports jobs status before every
2638 prompt by default. You can set the following options to make the shell
2639 report status at other timings:
2640 notify
2642 the shell reports immediately whenever job status changes.
2643 notify-le
2645 the shell reports immediately when job status changes while
2646 line-editing.
2647 A job is removed from the shell’s job list when:
2649 • it has finished and the jobs built-in reported it,
2651 • the wait built-in successfully waited for the job to finish, or
2653 • the disown built-in removed the job.
2655 Jobs are not removed from the list when an interactive shell
2657 automatically reports the status of jobs.
2658 Note
2660 The word “stop” is synonymous to “suspend” in the context of job
2661 control.
2662 Job ID
2664 Some built-ins use the following notation, which is called job ID, to
2665 specify a job to operate on:
2666 %, %%, %+
2668 the current job
2669 %-
2671 the previous job
2672 %n
2674 the job that has job number n, where n is a positive integer
2675 %string
2677 the job whose name begins with string
2678 %?string
2680 the job whose name contains string
2681 The current job and previous job are jobs selected by the shell
2683 according to the following rules:
2684 • When there is one or more suspended jobs, the current job is
2686 selected from them.
2687 • When there is one or more suspended jobs other than the current
2689 job, the previous job is selected from them.
2690 • The current and previous jobs are always different. When the shell
2692 has only one job, it is the current job and there is no previous
2693 job.
2694 • When the current job finished, the previous job becomes the current
2696 job.
2697 • When the current job is changed, the old current job becomes the
2699 previous job except when the old job finished.
2700 • When the foreground job is suspended, the job becomes the current
2702 job.
2703 Yash has some options to modify the rules of the current/previous job
2705 selection. (The rules above have priority over the options below.)
2706 cur-async
2708 When a new asynchronous command is started, it becomes the current
2709 job.
2710 cur-bg
2712 When a job is resumed by the bg built-in, the job becomes the
2713 current job.
2714 cur-stop
2716 When a job is suspended, it becomes the current job.
2717 The current and previous jobs are not changed as long as the rules
2719 above are met.
2720 The rules of the current/previous job selection defined in the POSIX
2722 standard are looser than yash’s rules above. Other POSIX-compliant
2723 shells may select the current and previous jobs differently.
2724
2726 Built-in commands are commands that are implemented in the shell and
2727 are executed by the shell without starting external programs.
2728 Types of built-in commands
2730 Yash has several types of built-in commands described below.
2731 Special built-in commands are the most important kinds of built-in
2733 commands. They are executed regardless of whether the corresponding
2734 external commands exist or not. Results of variable assignments that
2735 occur in a simple command that invokes a special built-in last after
2736 the command has finished. Moreover, in the POSIXly-correct mode, a
2737 non-interactive shell immediately exits with a non-zero exit status
2738 when an error occurs in a simple command executing a special built-in.
2739 Mandatory built-in commands and elective built-in commands are similar
2741 to special built-ins in that they do not need external commands to be
2742 executed but differ in that they may be overridden by functions. While
2743 mandatory built-ins are always available, you cannot use elective
2744 built-ins in the POSIXly-correct mode because POSIX only reserves their
2745 names without defining their behavior.
2746 An extension built-in command is a built-in that is not mentioned in
2748 POSIX. Like an elective built-in, it can be executed without an
2749 external command when the POSIXly-correct mode is off. However, when
2750 the POSIXly-correct mode is on, the shell works as if the built-in does
2751 not exist.
2752 Substitutive built-in commands work on behalf of external commands
2754 found in PATH. These built-ins improve execution speed by bypassing
2755 invocation overheads for external programs.
2756 Syntax of command arguments
2758 In this section we explain common rules about command arguments. The
2759 built-in commands of yash follow the rules unless otherwise stated.
2760 There are two types of command arguments. One is options and the other
2762 is operands. An option is an argument that starts with a hyphen (-) and
2763 changes the way the command behaves. Some options take arguments. An
2764 operand is an argument that is not an option and specifies objects the
2765 command operates on.
2766 If you specify more than one option to a command, the order of the
2768 options are normally not significant. The order of operands, however,
2769 affects the command behavior.
2770 An option is either a single-character option or a long option. A
2772 single-character option is identified by one alphabetic character. A
2773 long option is identified by multiple alphabetic characters. The POSIX
2774 standard only prescribes single-character options, so in the
2775 POSIXly-correct mode you cannot use long options.
2776 A single-character option is composed of a hyphen followed by a letter.
2778 For example, -a is a single-character option. A single-character option
2779 that takes an argument requires the argument to be just after the
2780 option name.
2781 Example 4. The set built-in and single-character options
2783 For the set built-in, -m is a single-character option that does not
2785 take an argument and -o is one that takes an argument.
2786 • set -o errexit -m
2788 • set -oerrexit -m
2790 In these two command lines, errexit is the argument to the -o option.
2792 In the second example above, the -o option and its argument are
2794 combined into a single command line argument. The POSIX standard
2795 deprecates that style and any POSIX-conforming applications must
2796 specify options and their arguments as separate command line arguments,
2797 although yash accepts both styles.
2798 You can combine single-character options that do not take arguments
2800 into a single command line argument. For example, the three options -a,
2801 -b and -c can be combined into -abc.
2802 A long option is composed of two hyphens followed by an option name.
2804 For example, --long-option is a long option. You can omit some last
2805 characters of a long option name as long as it is not ambiguous. For
2806 example, you can use --long instead of --long-option if there is no
2807 other options beginning with --long. Like a single-character option, a
2808 long option that takes an argument requires the argument to be a
2809 command line argument just after the option name or to be specified in
2810 the same command line argument as the option name, separated by an
2811 equal sign (=).
2812 Example 5. The fc built-in and long options
2814 For the fc built-in, --quiet is a long option that does not take an
2816 argument and --editor is one that takes an argument.
2817 • fc --editor vi --quiet
2819 • fc --editor=vi --quiet
2821 In these command lines, vi is the argument to the --editor option.
2823 Arguments that are not options (nor arguments to them) are interpreted
2825 as operands. The POSIX standard requires all options should be
2826 specified before any operands. Therefore, in the POSIXly-correct mode,
2827 any arguments that come after the first operand are interpreted as
2828 operands (even if they look like options). If not in the
2829 POSIXly-correct mode, you can specify options after operand.
2830 Regardless of whether the shell is in the POSIXly-correct mode or not,
2832 an argument that is just composed of two hyphens (--) can be used as a
2833 separator between options and operands. All command line arguments
2834 after the -- separator are interpreted as operands, so you can specify
2835 operands that start with a hyphen correctly using the separator.
2836 Example 6. Options and operands to the set built-in
2838 • set -a -b -- -c -d
2840 In this example, -a and -b are options and -c and -d are operands. The
2842 -- separator itself is neither an option nor an operand.
2843 Regardless of whether the shell is in the POSIXly-correct mode or not,
2845 an argument that is just composed of a single hyphen (-) is interpreted
2846 as an operand.
2847
2849 With the line-editing feature, you can edit the command text when you
2850 input a command to an interactive shell. It not only works as a simple
2851 visual-interface editor, but also is integrated with the command
2852 history. You can recall, edit, and execute commands in the history with
2853 line-editing instead of using the fc built-in.
2854 Line-editing has two editing modes, the vi and emacs modes, which each
2856 have their own key binding settings. By switching editing modes, you
2857 can change key bindings used in line-editing. Each mode has a
2858 corresponding shell option, which determines whether the mode is
2859 currently active or not. No more than one mode can be active at a time,
2860 so the options for the other modes are automatically turned off when
2861 you turn on the option for one mode. The whole line-editing feature is
2862 deactivated when those options are off.
2863 When an interactive shell is started, the vi mode is automatically
2865 activated if the standard input and error are both connected to a
2866 terminal.
2867 Line-editing can be used only when the standard input and error are
2869 both connected to a terminal. If not, the shell silently falls back to
2870 the normal input mechanism. While line-editing is being used, the shell
2871 uses the termios interface to change I/O settings of the terminal and
2872 the terminfo interface to parse input key sequences.
2873 Shell options on line-editing
2875 The following options can be set by the set built-in to enable
2876 line-editing and choose an editing mode to activate:
2877 vi
2879 activates the vi mode.
2880 emacs
2882 activates the emacs mode.
2883 The other line-editing-related options are:
2885 le-always-rp
2887 When this options is enabled, the right prompt is always visible:
2888 when the cursor reaches the right prompt, it moves to the next line
2889 from the original position, which would otherwise be overwritten by
2890 input text.
2891 le-comp-debug
2893 When enabled, internal information is printed during completion,
2894 which will help debugging completion scripts.
2895 le-conv-meta
2897 When enabled, the 8th bit of each input byte is always treated as a
2898 meta-key flag, regardless of terminfo data.
2899 le-no-conv-meta
2901 When enabled, the 8th bit of each input byte is never treated as a
2902 meta-key flag, regardless of terminfo data.
2903 The le-conv-meta and le-no-conv-meta options cannot be both enabled
2905 at a time. When either is enabled, the other is automatically
2906 disabled. When neither is enabled, the 8th bit may be treated as a
2907 meta-key flag depending on terminfo data.
2908 le-predict
2910 activates command line prediction.
2911 le-predict-empty
2913 When enabled, and command line prediction is active, suggestions
2914 are also provided for empty input lines.
2915 le-prompt-sp
2917 When enabled, the shell prints a special character sequence before
2918 printing each prompt so that every prompt is printed at the
2919 beginning of a line.
2920 This option is enabled by default.
2922 le-visible-bell
2924 When enabled, the shell flashes the terminal instead of sounding an
2925 alarm when an alert is required.
2926 le-trim-right
2928 When enabled, the right prompt, set by YASH_PS1R will right justify
2929 all the way to the edge of the screen, the default behaviour is to
2930 leave an empty space for the cursor when the prompt is too large.
2931 Editing modes
2933 The vi mode is an editing mode that offers key bindings similar to that
2934 of the vi editor. The vi mode has two sub-modes that are switched
2935 during editing: the insert and command modes. The sub-mode is always
2936 reset to the insert mode when line-editing is started for a new command
2937 line. In the insert mode, most characters are inserted to the buffer as
2938 typed. In the command mode, input characters are treated as commands
2939 that move the cursor, insert/delete text, etc.
2940 The emacs mode offers key bindings similar to the emacs editor. Most
2942 characters are inserted to the buffer as typed, but more characters are
2943 treated as commands than the vi insert mode.
2944 Another sub-mode is used while you enter search keywords. The sub-mode
2946 is called the search mode, which offers slightly different key bindings
2947 depending on the active editing mode.
2948 Line-editing commands
2950 All characters the user enters while line-editing is active are treated
2951 as line-editing commands listed below. The bindkey built-in allows
2952 customizing the key bindings of each mode (except for the search mode).
2953 The list below shows not only the functions of commands but also the
2955 default key bindings. The keywords “vi-insert”, “vi-command”,
2956 “vi-search”, “emacs”, “emacs-search” means the vi insert mode, the vi
2957 command mode, the search mode for the vi mode (the vi search mode), the
2958 emacs mode, and the search mode for the emacs mode (the emacs search
2959 mode), respectively.
2960 Some commands take an argument that affects the function of the
2962 commands. For example, the forward-char command moves the cursor by as
2963 many characters as specified by the argument. To specify an argument,
2964 use the digit-argument command just before another command that takes
2965 an argument.
2966 Basic editing commands
2968 noop
2969 Do nothing.
2970 vi-command
2972 \^[
2973 alert
2975 Alert.
2976 self-insert
2978 Insert the input character at the current cursor position.
2979 Characters escaped by escape sequences cannot be inserted.
2980 vi-insert, emacs
2982 \\
2983 insert-tab
2985 Insert a tab character at the current cursor position.
2986 emacs
2988 \^[\^I
2989 expect-verbatim
2991 Insert a character that is entered just after this command at
2992 the current cursor position. This command can input a character
2993 that cannot be input by the self-insert command, except a null
2994 character ('\0').
2995 vi-insert, vi-search, emacs-search
2997 \^V
2998 emacs
3000 \^Q, \^V
3001 digit-argument
3003 Pass the input digit to the next command as an argument.
3004 This command can be bound to a digit or hyphen. To pass “12” as
3006 an argument to the forward-char command in the vi mode, for
3007 example, enter 12l.
3008 vi-command
3010 1, 2, 3, 4, 5, 6, 7, 8, 9
3011 emacs
3013 \^[0, \^[1, \^[2, \^[3, \^[4, \^[5, \^[6, \^[7, \^[8, \^[9,
3014 \^[-,
3015 bol-or-digit
3017 Like the beginning-of-line command if there is no argument;
3018 like the digit-argument command otherwise.
3019 vi-command
3021 0
3022 accept-line
3024 Finish editing the current line. A newline is automatically
3025 appended to the line. The line will be executed by the shell.
3026 If command line prediction is active, the current prediction
3028 (if any) is ignored. See also the accept-prediction command.
3029 vi-insert, vi-command, emacs
3031 \^J, \^M, \et
3032 emacs-search
3034 \^M, \et
3035 abort-line
3037 Abandon the current buffer and finish editing as if an empty
3038 line was input.
3039 vi-insert, vi-command, vi-search, emacs, emacs-search
3041 \!, \^C
3042 eof
3044 Abandon the current buffer and finish editing as if the shell
3045 reached the end of input. This normally makes the shell exit.
3046 eof-if-empty
3048 Like the eof command if the buffer is empty; like the alert
3049 command otherwise.
3050 vi-insert, vi-command
3052 \#, \^D
3053 eof-or-delete
3055 Like the eof command if the buffer is empty; like the
3056 delete-char command otherwise.
3057 emacs
3059 \#, \^D
3060 accept-with-hash
3062 If the current line does not begin with a hash sign (#) or
3063 there is no argument specified for this command, a hash sign is
3064 inserted at the beginning of the line. Otherwise, the beginning
3065 hash sign is removed from the line. Finally, the line is
3066 accepted like the accept-line command.
3067 vi-command
3069 #
3070 emacs
3072 \^[#
3073 accept-prediction
3075 Like the accept-line command, but include the predicted part.
3076 setmode-viinsert
3078 Switch to the vi insert mode.
3079 vi-command
3081 i, \I
3082 setmode-vicommand
3084 Switch to the vi command mode.
3085 vi-insert
3087 \^[
3088 setmode-emacs
3090 Switch to the emacs mode.
3091 expect-char, abort-expect-char
3093 These commands are not meant for use by the user. They are used
3094 by the shell to implement some other commands.
3095 redraw-all
3097 Reprint the prompt and the current line to the terminal. If any
3098 argument is passed, the terminal screen is cleared.
3099 vi-insert, vi-command, vi-search, emacs, emacs-search
3101 \^L
3102 clear-and-redraw-all
3104 Clear the terminal screen and reprint the prompt and the
3105 current line. If any argument is passed, the screen is not
3106 cleared.
3107 Motion commands
3109 Motion commands move the cursor on the line. Most motion commands
3110 accept an argument. When passed an argument, they repeat the cursor
3111 motion as many times as specified by the argument. Passing “4” as
3112 an argument to the forward-char command, for example, advances the
3113 cursor by four characters.
3114 The shell has several definitions of words as units of distance: A
3116 bigword is one or more adjacent non-whitespace characters. A
3117 semiword is one or more adjacent characters that contain no
3118 whitespaces or punctuations. An emacsword is one or more adjacent
3119 alphanumeric characters. A viword is either:
3120 • one or more adjacent alphanumeric characters and/or underscores
3122 (_), or
3123 • one or more adjacent characters that contain none of
3125 alphanumeric characters, underscores, and whitespaces.
3126 forward-char
3128 Move the cursor to the next character.
3129 vi-insert
3131 \R
3132 vi-command
3134 l, (space), \R
3135 emacs
3137 \R, \^F
3138 backward-char
3140 Move the cursor to the previous character.
3141 vi-insert
3143 \L
3144 vi-command
3146 h, \B, \L, \?, \^H
3147 emacs
3149 \L, \^B
3150 forward-bigword
3152 Move the cursor to the next bigword.
3153 vi-command
3155 W
3156 end-of-bigword
3158 Move the cursor to the next end of a bigword.
3159 vi-command
3161 E
3162 backward-bigword
3164 Move the cursor to the previous bigword.
3165 vi-command
3167 B
3168 forward-semiword
3170 Move the cursor to the next semiword.
3171 end-of-semiword
3173 Move the cursor to the next end of a semiword.
3174 backward-semiword
3176 Move the cursor to the previous semiword.
3177 forward-viword
3179 Move the cursor to the next viword.
3180 vi-command
3182 w
3183 end-of-viword
3185 Move the cursor to the next end of a viword.
3186 vi-command
3188 e
3189 backward-viword
3191 Move the cursor to the previous viword.
3192 vi-command
3194 b
3195 forward-emacsword
3197 Move the cursor to the next emacsword.
3198 emacs
3200 \^[f, \^[F
3201 backward-emacsword
3203 Move the cursor to the previous emacsword.
3204 emacs
3206 \^[b, \^[B
3207 beginning-of-line
3209 Move the cursor to the beginning of the line.
3210 vi-insert, vi-command
3212 \H
3213 emacs
3215 \H, \^A
3216 end-of-line
3218 Move the cursor to the end of the line.
3219 vi-insert
3221 \E
3222 vi-command
3224 $, \E
3225 emacs
3227 \E, \^E
3228 go-to-column
3230 Move the cursor to the nth character on the line, where n is
3231 the argument. Assume n = 1 when no argument.
3232 vi-command
3234 |
3235 first-nonblank
3237 Move the cursor to the first non-blank character on the line.
3238 vi-command
3240 ^
3241 find-char
3243 Move the cursor to the first position where a character that is
3244 entered just after this command appears after the current
3245 cursor position.
3246 vi-command
3248 f
3249 emacs
3251 \^]
3252 find-char-rev
3254 Move the cursor to the last position where a character that is
3255 entered just after this command appears before the current
3256 cursor position.
3257 vi-command
3259 F
3260 emacs
3262 \^[\^]
3263 till-char
3265 Move the cursor to the first position just before a character
3266 that is entered just after this command appears after the
3267 current cursor position.
3268 vi-command
3270 t
3271 till-char-rev
3273 Move the cursor to the last position just after a character
3274 that is entered just after this command appears before the
3275 current cursor position.
3276 vi-command
3278 T
3279 refind-char
3281 Redo the last find-char, find-char-rev, till-char,
3282 till-char-rev command.
3283 vi-command
3285 ;
3286 refind-char-rev
3288 Redo the last find-char, find-char-rev, till-char,
3289 till-char-rev command in the reverse direction.
3290 vi-command
3292 ,
3293 Editing commands
3295 Editing commands modify contents of the buffer. Most editing
3296 commands accept an argument. When passed an argument, they repeat
3297 the modification as many times as specified by the argument.
3298 Texts deleted by commands whose name starts with “kill” are saved
3300 in kill ring, from which deleted contents can be restored to the
3301 buffer. The most recent 32 texts are kept in the kill ring.
3302 delete-char
3304 Delete a character at the current cursor position if no
3305 argument is passed; like the kill-char command otherwise.
3306 vi-insert, emacs
3308 \X
3309 delete-bigword
3311 Delete a bigword at the current cursor position if no argument
3312 is passed; like the kill-bigword command otherwise.
3313 delete-semiword
3315 Delete a semiword at the current cursor position if no argument
3316 is passed; like the kill-semiword command otherwise.
3317 delete-viword
3319 Delete a viword at the current cursor position if no argument
3320 is passed; like the kill-viword command otherwise.
3321 delete-emacsword
3323 Delete a emacsword at the current cursor position if no
3324 argument is passed; like the kill-emacsword command otherwise.
3325 backward-delete-char
3327 Delete a character just before the current cursor position if
3328 no argument is passed; like the backward-kill-char command
3329 otherwise.
3330 vi-insert, emacs
3332 \B, \?, \^H
3333 backward-delete-bigword
3335 Delete a bigword just before the current cursor position if no
3336 argument is passed; like the backward-kill-bigword command
3337 otherwise.
3338 backward-delete-semiword
3340 Delete a semiword just before the current cursor position if no
3341 argument is passed; like the backward-kill-semiword command
3342 otherwise.
3343 vi-insert
3345 \^W
3346 backward-delete-viword
3348 Delete a viword just before the current cursor position if no
3349 argument is passed; like the backward-kill-viword command
3350 otherwise.
3351 backward-delete-emacsword
3353 Delete a emacsword just before the current cursor position if
3354 no argument is passed; like the backward-kill-emacsword command
3355 otherwise.
3356 delete-line
3358 Delete the whole buffer contents.
3359 forward-delete-line
3361 Delete all characters from the current cursor position to the
3362 end of the buffer.
3363 backward-delete-line
3365 Delete all characters before the current cursor position.
3366 vi-insert
3368 \$, \^U
3369 kill-char
3371 Delete a character at the current cursor position and add it to
3372 the kill ring.
3373 vi-command
3375 x, \X
3376 kill-bigword
3378 Delete a bigword at the current cursor position and add it to
3379 the kill ring.
3380 kill-semiword
3382 Delete a semiword at the current cursor position and add it to
3383 the kill ring.
3384 kill-viword
3386 Delete a viword at the current cursor position and add it to
3387 the kill ring.
3388 kill-emacsword
3390 Delete a emacsword at the current cursor position and add it to
3391 the kill ring.
3392 emacs
3394 \^[d, \^[D
3395 backward-kill-char
3397 Delete a character just before the current cursor position and
3398 add it to the kill ring.
3399 vi-command
3401 X
3402 backward-kill-bigword
3404 Delete a bigword just before the current cursor position and
3405 add it to the kill ring.
3406 emacs
3408 \^W
3409 backward-kill-semiword
3411 Delete a semiword just before the current cursor position and
3412 add it to the kill ring.
3413 backward-kill-viword
3415 Delete a viword just before the current cursor position and add
3416 it to the kill ring.
3417 backward-kill-emacsword
3419 Delete a emacsword just before the current cursor position and
3420 add it to the kill ring.
3421 emacs
3423 \^[\B, \^[\?, \^[\^H
3424 kill-line
3426 Delete the whole buffer contents and add it to the kill ring.
3427 forward-kill-line
3429 Delete all characters from the current cursor position to the
3430 end of the buffer and add it to the kill ring.
3431 emacs
3433 \^K
3434 backward-kill-line
3436 Delete all characters before the current cursor position and
3437 add it to the kill ring.
3438 emacs
3440 \$, \^U, \^X\B, \^X\?
3441 put-before
3443 Insert the last-killed text before the current cursor position
3444 and move the cursor to the last character that was inserted.
3445 vi-command
3447 P
3448 put
3450 Insert the last-killed text after the current cursor position
3451 and move the cursor to the last character that was inserted.
3452 vi-command
3454 p
3455 put-left
3457 Insert the last-killed text before the current cursor position
3458 and move the cursor to the last character that was inserted.
3459 emacs
3461 \^Y
3462 put-pop
3464 Replace the just put text with the next older killed text.
3465 This command can be used only just after the put-before, put,
3467 put-left, or put-pop command.
3468 emacs
3470 \^[y, \^[Y
3471 undo
3473 Cancel modification by the last editing command.
3474 vi
3476 u
3477 emacs
3479 \^_, \^X\$, \^X\^U
3480 undo-all
3482 Cancel all modification in the current buffer, restoring the
3483 initial contents.
3484 vi
3486 U
3487 emacs
3489 \^[\^R, \^[r, \^[R
3490 cancel-undo
3492 Cancel cancellation by the last undo or undo-all command.
3493 vi
3495 \^R
3496 cancel-undo-all
3498 Cancel all cancellation by all most recent undo and undo-all
3499 commands.
3500 redo
3502 Repeat modification by the last editing command.
3503 vi-command
3505 .
3506 Completion commands
3508 complete
3509 Complete a word just before the cursor position and, if there
3510 is more than one candidate, show a list of the candidates.
3511 complete-next-candidate
3513 Like the complete command when candidates are not being listed;
3514 otherwise, select the next candidate in the list.
3515 vi-insert, emacs
3517 \^I
3518 complete-prev-candidate
3520 Like the complete command when candidates are not being listed;
3521 otherwise, select the previous candidate in the list.
3522 vi-insert, emacs
3524 \bt
3525 complete-next-column
3527 Like the complete command when candidates are not being listed;
3528 otherwise, select the first candidate in the next column in the
3529 list.
3530 complete-prev-column
3532 Like the complete command when candidates are not being listed;
3533 otherwise, select the first candidate in the previous column in
3534 the list.
3535 complete-next-page
3537 Like the complete command when candidates are not being listed;
3538 otherwise, select the first candidate in the next page in the
3539 list.
3540 complete-prev-page
3542 Like the complete command when candidates are not being listed;
3543 otherwise, select the first candidate in the previous page in
3544 the list.
3545 complete-list
3547 Complete a word just before the cursor position.
3548 If you pass no argument, a list of completion candidates is
3550 shown. Otherwise, the word is completed with the nth candidate
3551 where n is the argument.
3552 emacs
3554 \^[?, \^[=
3555 complete-all
3557 Replace a word just before the cursor position with all
3558 possible completion candidates, each separated by a space.
3559 emacs
3561 \^[*
3562 complete-max
3564 Complete a word just before the cursor position with the
3565 longest prefix of all possible completion candidates.
3566 complete-max-then-list
3568 Works like the complete-max command for the first use, then
3569 like the complete command when used successively.
3570 complete-max-then-next-candidate
3572 Works like the complete-max command for the first use, then
3573 like the complete-next-candidate command when used
3574 successively.
3575 complete-max-then-prev-candidate
3577 Works like the complete-max command for the first use, then
3578 like the complete-prev-candidate command when used
3579 successively.
3580 clear-candidates
3582 Clear the list of completion candidates.
3583 Vi-specific commands
3585 vi-replace-char
3586 Replace the character at the cursor position with a character
3587 that is entered just after this command.
3588 vi-command
3590 r
3591 vi-insert-beginning
3593 Move the cursor to the beginning of the line and switch to the
3594 vi insert mode.
3595 vi-command
3597 I
3598 vi-append
3600 Move the cursor to the next character and switch to the vi
3601 insert mode.
3602 vi-command
3604 I
3605 vi-append-to-eol
3607 Move the cursor to the end of the line and switch to the vi
3608 insert mode.
3609 vi-command
3611 A
3612 vi-replace
3614 Switch to the vi insert mode and start overwriting. While
3615 overwriting, the self-insert command replaces the character at
3616 cursor position rather than inserting a character. Overwriting
3617 ends when the editing mode is changed.
3618 vi-command
3620 R
3621 vi-switch-case
3623 Switch case of characters between the current and next cursor
3624 positions. This command must be followed by a motion command,
3625 which determines the next cursor position.
3626 vi-switch-case-char
3628 Switch case of the character at the current cursor position and
3629 move the cursor to the next character.
3630 vi-command
3632 ~
3633 vi-yank
3635 Add to the kill ring the characters between the current and
3636 next cursor positions. This command must be followed by a
3637 motion command, which determines the next cursor position.
3638 vi-command
3640 y
3641 vi-yank-to-eol
3643 Add to the kill ring the characters from the current cursor
3644 position to the end of the line.
3645 vi-command
3647 Y
3648 vi-delete
3650 Delete characters between the current and next cursor positions
3651 and add it to the kill ring. This command must be followed by a
3652 motion command, which determines the next cursor position.
3653 vi-command
3655 d
3656 vi-delete-to-eol
3658 Delete the characters from the current cursor position to the
3659 end of the line and add it to the kill ring.
3660 vi-command
3662 D
3663 vi-change
3665 Delete characters between the current and next cursor positions
3666 and switch to the vi insert mode. This command must be followed
3667 by a motion command, which determines the next cursor position.
3668 vi-command
3670 c
3671 vi-change-to-eol
3673 Delete the characters from the current cursor position to the
3674 end of the line and switch to the vi insert mode.
3675 vi-command
3677 C
3678 vi-change-line
3680 Delete the whole buffer contents and switch to the vi insert
3681 mode.
3682 vi-command
3684 S
3685 vi-yank-and-change
3687 Like the vi-change command, but the deleted text is added to
3688 the kill ring.
3689 vi-yank-and-change-to-eol
3691 Like the vi-change-to-eol command, but the deleted text is
3692 added to the kill ring.
3693 vi-yank-and-change-line
3695 Like the vi-change-line command, but the deleted text is added
3696 to the kill ring.
3697 vi-substitute
3699 Delete a character at the current cursor position, add it to
3700 the kill ring, and switch to the vi insert mode.
3701 vi-command
3703 s
3704 vi-append-last-bigword
3706 Insert a space and the last bigword in the most recent command
3707 history entry just after the current cursor position and switch
3708 to the vi insert mode. If argument n is passed, the nth bigword
3709 in the entry is inserted instead of the last.
3710 vi-command
3712 _
3713 vi-exec-alias
3715 Execute the value of an alias named _c as editing commands
3716 where c is a character input just after this command.
3717 vi-command
3719 @
3720 vi-edit-and-accept
3722 Start the vi editor to edit the current buffer contents. When
3723 the editor finished, the edited buffer contents is accepted
3724 like the accept-line command unless the exit status of the
3725 editor is non-zero.
3726 vi-command
3728 v
3729 vi-complete-list
3731 Like the complete-list command, but also switch to the vi
3732 insert mode.
3733 vi-command
3735 =
3736 vi-complete-all
3738 Like the complete-all command, but also switch to the vi insert
3739 mode.
3740 vi-command
3742 *
3743 vi-complete-max
3745 Like the complete-max command, but also switch to the vi insert
3746 mode.
3747 vi-command
3749 \\
3750 vi-search-forward
3752 Switch to the vi search mode and start forward history search.
3753 vi-command
3755 ?
3756 vi-search-backward
3758 Switch to the vi search mode and start backward history search.
3759 vi-command
3761 /
3762 Emacs-specific commands
3764 emacs-transpose-chars
3765 Move a character just before the cursor to the right.
3766 emacs
3768 \^T
3769 emacs-transpose-words
3771 Move an emacsword just before the cursor to the right.
3772 emacs
3774 \^[t, \^[T
3775 emacs-downcase-word
3777 Make an emacsword just after the cursor lowercase.
3778 emacs
3780 \^[l, \^[L
3781 emacs-upcase-word
3783 Make an emacsword just after the cursor uppercase.
3784 emacs
3786 \^[u, \^[U
3787 emacs-capitalize-word
3789 Capitalize the first letter of an emacsword just after the
3790 cursor.
3791 emacs
3793 \^[c, \^[u
3794 emacs-delete-horizontal-space
3796 Delete spaces around the cursor. If any argument was passed,
3797 delete spaces just before the cursor only.
3798 emacs
3800 \^[\\
3801 emacs-just-one-space
3803 Delete spaces around the cursor and leave one space. If an
3804 argument is specified, leave as many spaces as the argument.
3805 emacs
3807 \^[ (Escape followed by a space)
3808 emacs-search-forward
3810 Switch to the emacs search mode and start forward history
3811 search.
3812 emacs
3814 \^S
3815 emacs-search-backward
3817 Switch to the emacs search mode and start backward history
3818 search.
3819 emacs
3821 \^R
3822 History-related commands
3824 oldest-history
3825 Recall the oldest entry in the history. If argument n is
3826 passed, the entry whose number is n is recalled instead. The
3827 cursor position remains unchanged.
3828 newest-history
3830 Recall the newest entry in the history. If argument n is
3831 passed, the entry whose number is n is recalled instead. The
3832 cursor position remains unchanged.
3833 return-history
3835 Return to the initial buffer corresponding to none of existing
3836 history entries. If argument n is passed, the entry whose
3837 number is n is recalled instead. The cursor position remains
3838 unchanged.
3839 oldest-history-bol
3841 Recall the oldest entry in the history and move the cursor to
3842 the beginning of the line. If argument n is passed, the entry
3843 whose number is n is recalled instead.
3844 vi-command
3846 G
3847 newest-history-bol
3849 Recall the newest entry in the history and move the cursor to
3850 the beginning of the line. If argument n is passed, the entry
3851 whose number is n is recalled instead.
3852 return-history-bol
3854 Return to the initial buffer corresponding to none of existing
3855 history entries and move the cursor to the beginning of the
3856 line. If argument n is passed, the entry whose number is n is
3857 recalled instead.
3858 vi-command
3860 g
3861 oldest-history-eol
3863 Recall the oldest entry in the history and move the cursor to
3864 the end of the line. If argument n is passed, the entry whose
3865 number is n is recalled instead.
3866 emacs
3868 \^[<
3869 newest-history-eol
3871 Recall the newest entry in the history and move the cursor to
3872 the end of the line. If argument n is passed, the entry whose
3873 number is n is recalled instead.
3874 return-history-eol
3876 Return to the initial buffer corresponding to none of existing
3877 history entries and move the cursor to the end of the line. If
3878 argument n is passed, the entry whose number is n is recalled
3879 instead.
3880 emacs
3882 \^[>
3883 next-history
3885 Recall the next history entry. The cursor position remains
3886 unchanged.
3887 prev-history
3889 Recall the previous history entry. The cursor position remains
3890 unchanged.
3891 next-history-bol
3893 Recall the next history entry and move the cursor to the
3894 beginning of the line.
3895 vi-command
3897 j, +, \D, \^N
3898 prev-history-bol
3900 Recall the previous history entry and move the cursor to the
3901 beginning of the line.
3902 vi-command
3904 k, -, \U, \^P
3905 next-history-eol
3907 Recall the next history entry and move the cursor to the end of
3908 the line.
3909 vi-insert, emacs
3911 \D, \^N
3912 prev-history-eol
3914 Recall the previous history entry and move the cursor to the
3915 end of the line.
3916 vi-insert, emacs
3918 \U, \^P
3919 search-again
3921 Repeat the last command history search.
3922 vi-command
3924 n
3925 search-again-rev
3927 Repeat the last command history search in the reverse
3928 direction.
3929 vi-command
3931 N
3932 search-again-forward
3934 Repeat the last command history search in the forward
3935 direction.
3936 search-again-backward
3938 Repeat the last command history search in the backward
3939 direction.
3940 beginning-search-forward
3942 Recall the next history entry that starts with the same text as
3943 the text from the beginning of the line up to the current
3944 cursor position. The cursor position remains unchanged.
3945 beginning-search-backward
3947 Recall the previous history entry that starts with the same
3948 text as the text from the beginning of the line up to the
3949 current cursor position. The cursor position remains unchanged.
3950 Search mode commands
3952 srch-self-insert
3953 Insert the input character at the current cursor position.
3954 Characters escaped by escape sequences cannot be inserted.
3955 vi-search, emacs-search
3957 \\
3958 srch-backward-delete-char
3960 Delete the last character in the search text. If the text is
3961 empty:
3962 • like the srch-abort-search command when in the vi search
3964 mode, or
3965 • like the alert command when in the emacs search mode.
3967 vi-search, emacs-search
3969 \B, \?, \^H
3970 srch-backward-delete-line
3972 Delete the whole search text.
3973 vi-search, emacs-search
3975 \$, \^U
3976 srch-continue-forward
3978 Find the next matching history entry.
3979 emacs-search
3981 \^S
3982 srch-continue-backward
3984 Find the previous matching history entry.
3985 emacs-search
3987 \^R
3988 srch-accept-search
3990 Finish the search mode, accepting the result being shown.
3991 vi-search
3993 \^J, \^M, \et
3994 emacs-search
3996 \^J, \^[
3997 srch-abort-search
3999 Abort search and restore the previous buffer contents.
4000 vi-search
4002 \^[
4003 emacs-search
4005 \^G
4006 Escape sequences
4008 In the bindkey built-in, escape sequences are used to represent special
4009 keys such as function keys and arrow keys. Every escape sequence starts
4010 with a backslash (\) and thus there is also an escape sequence for a
4011 backslash itself.
4012 Below are available escape sequences:
4014 \\
4016 Backslash (\)
4017 \B
4019 Backspace
4020 \D
4022 Down arrow
4023 \E
4025 End
4026 \H
4028 Home
4029 \I
4031 Insert (Insert-char, Enter-insert-mode)
4032 \L
4034 Left arrow
4035 \N
4037 Page-down (Next-page)
4038 \P
4040 Page-up (Previous-page)
4041 \R
4043 Right arrow
4044 \U
4046 Up arrow
4047 \X
4049 Delete
4050 \!
4052 INTR
4053 \#
4055 EOF
4056 \$
4058 KILL
4059 \?
4061 ERASE
4062 \^@
4064 Ctrl + @
4065 \^A, \^B, ..., \^Z
4067 Ctrl + A, Ctrl + B, ..., Ctrl + Z
4068 Note that Ctrl + I, Ctrl + J, and Ctrl + M are tab, newline, and
4070 carriage return, respectively.
4071 \^[
4073 Ctrl + [ (Escape)
4074 \^\
4076 Ctrl + \
4077 \^]
4079 Ctrl + ]
4080 \^^
4082 Ctrl + ^
4083 \^_
4085 Ctrl + _
4086 \^?
4088 Ctrl + ? (Delete)
4089 \F00, \F01, ..., \F63
4091 F0, F1, ..., F63
4092 \a1
4094 Top-left on keypad
4095 \a3
4097 Top-right on keypad
4098 \b2
4100 Center on keypad
4101 \bg
4103 Beginning
4104 \bt
4106 Back-tab
4107 \c1
4109 Bottom-left on keypad
4110 \c3
4112 Bottom-right on keypad
4113 \ca
4115 Clear-all-tabs
4116 \cl
4118 Close
4119 \cn
4121 Cancel
4122 \co
4124 Command
4125 \cp
4127 Copy
4128 \cr
4130 Create
4131 \cs
4133 Clear-screen or erase
4134 \ct
4136 Clear-tab
4137 \dl
4139 Delete-line
4140 \ei
4142 Exit-insert-mode
4143 \el
4145 Clear-to-end-of-line
4146 \es
4148 Clear-to-end-of-screen
4149 \et
4151 Enter (Send)
4152 \ex
4154 Exit
4155 \fd
4157 Find
4158 \hp
4160 Help
4161 \il
4163 Insert-line
4164 \ll
4166 Home-down
4167 \me
4169 Message
4170 \mk
4172 Mark
4173 \ms
4175 Mouse event
4176 \mv
4178 Move
4179 \nx
4181 Next-object
4182 \on
4184 Open
4185 \op
4187 Options
4188 \pr
4190 Print (Copy)
4191 \pv
4193 Previous-object
4194 \rd
4196 Redo
4197 \re
4199 Resume
4200 \rf
4202 Ref (Reference)
4203 \rh
4205 Refresh
4206 \rp
4208 Replace
4209 \rs
4211 Restart
4212 \sf
4214 Scroll-forward (Scroll-down)
4215 \sl
4217 Select
4218 \sr
4220 Scroll-backward (Scroll-up)
4221 \st
4223 Set-tab
4224 \su
4226 Suspend
4227 \sv
4229 Save
4230 \ud
4232 Undo
4233 \SE
4235 Shift + End
4236 \SH
4238 Shift + Home
4239 \SI
4241 Shift + Insert
4242 \SL
4244 Shift + Left arrow
4245 \SR
4247 Shift + Right arrow
4248 \SX
4250 Shift + Delete
4251 \Sbg
4253 Shift + Beginning
4254 \Scn
4256 Shift + Cancel
4257 \Sco
4259 Shift + Command
4260 \Scp
4262 Shift + Copy
4263 \Scr
4265 Shift + Create
4266 \Sdl
4268 Shift + Delete-line
4269 \Sel
4271 Shift + End-of-line
4272 \Sex
4274 Shift + Exit
4275 \Sfd
4277 Shift + Find
4278 \Shp
4280 Shift + Help
4281 \Smg
4283 Shift + Message
4284 \Smv
4286 Shift + Move
4287 \Snx
4289 Shift + Next
4290 \Sop
4292 Shift + Options
4293 \Spr
4295 Shift + Print
4296 \Spv
4298 Shift + Previous
4299 \Srd
4301 Shift + Redo
4302 \Sre
4304 Shift + Resume
4305 \Srp
4307 Shift + Replace
4308 \Ssu
4310 Shift + Suspend
4311 \Ssv
4313 Shift + Save
4314 \Sud
4316 Shift + Undo
4317 INTR, EOF, KILL, and ERASE are special characters configured by the
4319 stty command. In a typical configuration, they are sent by typing
4320 Ctrl+C, Ctrl+D, Ctrl+U, and Ctrl+H, respectively, but some
4321 configuration uses Ctrl+? instead of Ctrl+H for ERASE.
4322 Command line completion
4324 By using the complete and complete-next-candidate commands, etc., you
4325 can complete command names, options, and operands. By default, the
4326 complete-next-candidate command is bound with the Tab key in the vi
4327 insert and emacs modes.
4328 Type a few first letters of a command name or pathname and hit the Tab
4330 key, and a list of matching names will be shown. You can choose a
4331 candidate from the list to complete the name by hitting the Tab key
4332 again. If there is only one matching name, no list will be shown and
4333 the name will directly be completed.
4334 If the name to be completed contains characters like * and ?, it is
4336 treated as a pattern. The name on the command line will be directly
4337 substituted with all possible names matching the pattern (you cannot
4338 choose from a list).
4339 Normally, command names are completed with command names and command
4341 arguments with pathnames. However, completion functions can be defined
4342 to refine completion results.
4343 Completion details
4345 When doing completion for the first time after the shell has been
4346 started, the INIT file is loaded as if the command string . -AL
4347 completion/INIT is executed. If the file is not found, it is
4348 silently ignored. This automatic loading is mainly intended for
4349 loading completion functions bundled with the shell, but you can
4350 let the shell load your own functions by putting a file in the load
4351 path.
4352 When completing a command name, the shell executes the
4354 completion//command function and when completing a command
4355 argument, the completion//argument function. If those completion
4356 functions are not defined, the shell just completes with command
4357 names or pathnames. When completing other names, such as the user
4358 name in tilde expansion and the parameter name in parameter
4359 expansion, completion functions are never used: the shell just
4360 completes with user names, parameter names, or whatever applicable.
4361 Completion functions are executed without any arguments. The
4363 following local variables are automatically defined while executing
4364 completion functions:
4365 IFS
4367 The value is the three characters of a space, a tab, and a
4368 newline, which are the default value of the variable.
4369 WORDS
4371 This variable is an array whose elements are a command name and
4372 arguments that have already been entered before the argument
4373 being completed. When completing a command name, the array has
4374 no elements.
4375 TARGETWORD
4377 The value is the partially entered command name or argument
4378 that is being completed.
4379 Completion candidates are generated by executing the complete
4381 built-in during a completion function.
4382 Completion functions must not perform I/O to the terminal, or
4384 displayed text will be corrupted. Completion functions should run
4385 as quickly as possible for better user experience.
4386 While a completion function is being executed:
4388 • the POSIXly-correct mode and the err-return option are
4390 temporarily disabled,
4391 • the err-exit option is temporarily ignored, and
4393 • traps are not executed.
4395 Command line prediction
4397 This is an experimental feature. When the le-predict option is enabled,
4398 the shell automatically tries to predict a command string fragment that
4399 follows the part of the command you have already typed in line-editing.
4400 For example, assume you have once typed the command ls Documents. Next
4402 time you start typing ls Doc, the shell will show uments just after the
4403 cursor. If you are satisfied with this suggestion, you can move the
4404 cursor to the right by the forward-char or any other motion commands
4405 instead of typing the rest of the command. After moving the cursor
4406 after the last s, you can use the accept-line command to execute the
4407 command. You can also use the accept-prediction command to immediately
4408 execute the suggested command without moving the cursor.
4409 To distinguish the typed and predicted parts of a command string, you
4411 can change the font style of those parts by setting the PS1S and PS1P
4412 variables.
4413 When you move the cursor to the right, the predicted part up to the
4415 cursor becomes the typed part as if you actually typed it. Moving the
4416 cursor to the left does not turn the typed part back to the prediction.
4417 Use deletion commands such as backward-delete-char to delete typed
4418 command fragment.
4419 The predicted part of the command is shown only when the cursor is at
4421 the end of the typed part.
4422 By default, the predicted part is shown after you start typing a
4424 command string. By enabling the le-predict-empty option, the predicted
4425 part is also shown before you type the first character of the command
4426 string.
4427 The prediction algorithm suggests command fragments on the basis of the
4429 command history. The algorithm considers recent history entries more
4430 probable. It also takes command succession patterns into account. A
4431 predicted command fragment is not always a complete valid command
4432 because less probable part of the fragment is excluded from prediction.
4433
4435 Yash behaves as defined in POSIX.1-2008, Shell & Utilities for the most
4436 part, but some functionalities disobey POSIX for usability. When full
4437 POSIX-conformance is needed, you can enable the POSIXly-correct mode to
4438 make yash obey POSIX as much as possible.
4439 If yash is started with the name “sh”, the POSIXly-correct mode is
4441 automatically enabled. The -o posixly-correct command-line option also
4442 enables the POSIXly-correct mode. After yash has been started, the
4443 POSIXly-correct mode can be enabled by executing the command string set
4444 -o posixly-correct.
4445 When the POSIXly-correct mode is on, yash not only tries to obey the
4447 requirements by POSIX, but also treats as errors most conditions where
4448 the behavior is undefined or unspecified by POSIX. As a result, most
4449 yash-specific functionalities are disabled in the POSIXly-correct mode.
4450 Below is the complete list of the behavioral differences between when
4452 yash is in the POSIXly-correct mode and when not. When the
4453 POSIXly-correct mode is enabled:
4454 • Different initialization scripts are used.
4456 • If the shell was started with the -c option, sh -c (instead of yash
4458 -c) is printed as the script pathname on a syntax error.
4459 • Global aliases are not substituted.
4461 • Nested commands in a compound command must not be empty.
4463 • The for loop iteration variable is created as global, regardless of
4465 the for-local shell option. The variable must have a portable
4466 (ASCII-only) name.
4467 • The first pattern in a case command cannot be esac.
4469 • The ! keyword cannot be followed by ( without any whitespaces
4471 in-between.
4472 • The double-bracket command cannot be used.
4474 • The function keyword cannot be used for function definition. The
4476 function must have a portable (ASCII-only) name.
4477 • Simple commands cannot assign to arrays.
4479 • Changing the value of the LC_CTYPE variable after the shell has
4481 been initialized does not affect the shell’s locale.
4482 • The RANDOM variable cannot be used to generate random numbers.
4484 • Tilde expansion only expands ~ and ~username.
4486 • Parameter expansion cannot be nested. No indexes or modifiers with
4488 word2 are allowed.
4489 • The commands in a command substitution of the form $(commands) are
4491 parsed every time the substitution is executed.
4492 • In arithmetic expansion, fractional numbers and the ++ and --
4494 operators cannot be used. All variables must be numeric.
4495 • The operand of a redirection cannot be the integer prefix to a next
4497 redirection operator.
4498 • A compound command with a redirection cannot be immediately
4500 followed by a keyword like } and fi.
4501 • In a redirection to a file, if the pathname expansion yielded more
4503 than one or no pathname, it is not immediately treated as an error.
4504 Instead, the shell tries to treat the word before the expansion as
4505 a pathname.
4506 • A file descriptor must be readable and writable when duplicated by
4508 the <& and >& redirection operator, respectively.
4509 • Socket redirection, here strings, pipe redirection, and process
4511 redirection cannot be used.
4512 • When executing a simple command, failure in command search does not
4514 trigger execution of the COMMAND_NOT_FOUND_HANDLER variable.
4515 • Elective and extension built-ins cannot be executed.
4517 • Some built-ins behave differently. Especially, long command-line
4519 options (as well as some others) cannot be used.
4520 • A non-interactive shell exits when a special built-in is given a
4522 syntactically wrong arguments or when an error occurs in assignment
4523 or redirection with a special built-in.
4524 • An interactive shell does not execute the PROMPT_COMMAND variable
4526 before printing a prompt. The values of the PS1, PS2, and PS4
4527 variables are parsed differently. Prompt variables with a YASH_
4528 prefix (e.g. YASH_PS1) are not used.
4529 • In mail checking, a notification message is printed if the file has
4531 been modified, regardless of whether the file is empty.
4532
4534 How can I use Unicode (non-ASCII) characters?
4535 You need to set locale environment variables to enable Unicode
4536 character support.
4537 If the variables have already been configured for your preference, you
4539 probably don’t have to do anything. To check the current locale
4540 configurations, you can use the locale command:
4541 $ locale
4543 LANG=
4544 LC_CTYPE="en_US.utf8"
4545 LC_NUMERIC="en_US.utf8"
4546 LC_TIME="en_US.utf8"
4547 LC_COLLATE="en_US.utf8"
4548 LC_MONETARY="en_US.utf8"
4549 LC_MESSAGES="en_US.utf8"
4550 LC_PAPER="en_US.utf8"
4551 LC_NAME="en_US.utf8"
4552 LC_ADDRESS="en_US.utf8"
4553 LC_TELEPHONE="en_US.utf8"
4554 LC_MEASUREMENT="en_US.utf8"
4555 LC_IDENTIFICATION="en_US.utf8"
4556 LC_ALL=en_US.utf8
4557 In this example, the locale command shows that all the locale setting
4559 categories are configured for the English language, the United States
4560 region, and the UTF-8 encoding.
4561 If the current configuration does not seem to match your preference,
4563 set the LC_ALL variable like this:
4564 export LC_ALL=en_US.utf8
4566 If you want to use other languages, regions, or encodings, you have to
4568 set the variable to a different value. Please consult your OS’s
4569 documentation to learn how to configure these variables in detail.
4570 If you want to apply the same configuration every time you start yash,
4572 write the command in ~/.yashrc or ~/.yash_profile.
4573 If yash still rejects Unicode characters being entered, see the section
4575 below regarding line-editing.
4576 Line-editing does not work
4578 First, type echo $TERM and see if it prints a sane value. xterm is the
4579 safest value that should work on any existing environment. Colored
4580 versions like xterm-16color and other terminal types like rxvt and
4581 vt100 may also work. All possible values can be listed by the toe
4582 command. It’s most desirable to choose a value that matches the actual
4583 terminal type you are using, but it might not work if the terminal type
4584 you chose is not supported on the system on which yash is running. If
4585 so, try changing the TERM value by export TERM=xterm, for example, to
4586 find a value that works.
4587 If line-editing works but you have trouble entering Unicode (non-ASCII)
4589 characters, try enabling the le-no-conv-meta option by set -o
4590 le-no-conv-meta.
4591
4593 This chapter defines the syntax of the shell command language.
4594 Note
4596 Some of the syntactic features described below are not supported in
4597 the POSIXly-correct mode.
4598 Tokenization
4600 The characters of the input source code are first delimited into
4601 tokens. Tokens are delimited so that the earlier token spans as long as
4602 possible. A sequence of one or more unquoted blank characters delimits
4603 a token.
4604 The following tokens are the operator tokens:
4606 & && ( ) ; ;; | || < << <& <( <<- <<< <> > >> >& >( >>| >| (newline)
4608 Note
4610 Unlike other programming languages, the newline operator is a token
4611 rather than a white space.
4612 Characters that are not blank nor part of an operator compose a word
4614 token. Words are parsed by the following parsing expression grammar:
4615 Word
4617 (WordElement / !SpecialChar .)+
4618 WordElement
4620 \ . /
4621 ' (!' .)* ' /
4623 " QuoteElement* " /
4625 Parameter /
4627 Arithmetic /
4629 CommandSubstitution
4631 QuoteElement
4633 \ ([$`"\] / <newline>) /
4634 Parameter /
4636 Arithmetic /
4638 CommandSubstitutionQuoted /
4640 ![`"\] .
4642 Parameter
4644 $ [@*#?-$! [:digit:]] /
4645 $ PortableName /
4647 $ ParameterBody
4649 PortableName
4651 ![0-9] [0-9 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]+
4652 ParameterBody
4654 { ParameterNumber? (ParameterName / ParameterBody / $ ParameterBody
4655 / Arithmetic / CommandSubstitution) ParameterIndex?
4656 ParameterMatch? }
4657 ParameterNumber
4659 # ![}+=:/%] !([-?#] !})
4660 ParameterName
4662 [@*#?-$!] /
4663 [[:alnum:] _]+
4665 ParameterIndex
4667 [ ParameterIndexWord (, ParameterIndexWord)? ]
4668 ParameterIndexWord
4670 (WordElement / !["'],] .)+
4671 ParameterMatch
4673 :? [-+=?] ParameterMatchWord /
4674 (# / ## / % / %%) ParameterMatchWord /
4676 (:/ / / [#%/]?) ParameterMatchWordNoSlash (/ ParameterMatchWord)?
4678 ParameterMatchWord
4680 (WordElement / !["'}] .)*
4681 ParameterMatchWordNoSlash
4683 (WordElement / !["'/}] .)*
4684 Arithmetic
4686 $(( ArithmeticBody* ))
4687 ArithmeticBody
4689 \ . /
4690 Parameter /
4692 Arithmetic /
4694 CommandSubstitution /
4696 ( ArithmeticBody ) /
4698 ![`()] .
4700 CommandSubstitution
4702 $( CompleteProgram ) /
4703 ` CommandSubstitutionBody* `
4705 CommandSubstitutionQuoted
4707 $( CompleteProgram ) /
4708 ` CommandSubstitutionBodyQuoted* `
4710 CommandSubstitutionBody
4712 \ [$`\] /
4713 !` .
4715 CommandSubstitutionBodyQuoted
4717 \ [$`\`] /
4718 !` .
4720 SpecialChar
4722 [|&;<>()`\"' [:blank:]] / <newline>
4723 The set of terminals of the grammar is the set of characters that can
4725 be handled on the environment in which the shell is run (a.k.a.
4726 execution character set), with the exception that the set does not
4727 contain the null character ('\0').
4728 Strictly speaking, the definition above is not a complete parsing
4730 expression grammar because the rule for CommandSubstitution (Quoted)
4731 depends on CompleteProgram which is a non-terminal of the syntax.
4732 Token classification
4734 After a word token is delimited, the token may be further
4735 classified as an IO_NUMBER token, reserved word, name word,
4736 assignment word, or just normal word. Classification other than the
4737 normal word is applied only when applicable in the context in which
4738 the word appears. See Tokens and keywords for the list of the
4739 reserved words (keywords) and the context in which a word may be
4740 recognized as a reserved word.
4741 A token is an IO_NUMBER token iff it is composed of digit
4743 characters only and immediately followed by < or >.
4744 An assignment token is a token that starts with a name followed by
4746 =:
4747 AssignmentWord
4749 AssignmentPrefix Word
4750 AssignmentPrefix
4752 Name =
4753 Name
4755 ![[:digit:]] \[[:alnum:] _]+
4756 Comments
4758 A comment begins with # and continues up to (but not including) the
4759 next newline character. Comments are treated like a blank character
4760 and do not become part of a token. The initial # of a comment must
4761 appear as if it would otherwise be the first character of a word
4762 token; Other #s are just treated as part of a word token.
4763 Comment
4765 # (!<newline> .)*
4766 Syntax
4768 After tokens have been delimited, the sequence of the tokens is parsed
4769 according to the context-free grammar defined below, where *, +, and ?
4770 should be interpreted in the same manner as standard regular
4771 expression:
4772 CompleteProgram
4774 NL* | CompoundList
4775 CompoundList
4777 NL* AndOrList ((; | & | NL) CompleteProgram)?
4778 AndOrList
4780 Pipeline ((&& | ||) NL* Pipeline)*
4781 Pipeline
4783 !? Command (| NL* Command)*
4784 Command
4786 CompoundCommand Redirection* |
4787 FunctionDefinition |
4789 SimpleCommand
4791 CompoundCommand
4793 Subshell |
4794 Grouping |
4796 IfCommand |
4798 ForCommand |
4800 WhileCommand |
4802 CaseCommand |
4804 DoubleBracketCommand |
4806 FunctionCommand
4808 Subshell
4810 ( CompoundList )
4811 Grouping
4813 { CompoundList }
4814 IfCommand
4816 if CompoundList then CompoundList (elif CompoundList then
4817 CompoundList)* (else CompoundList)? fi
4818 ForCommand
4820 for Name ((NL* in Word*)? (; | NL) NL*)? do CompoundList done
4821 WhileCommand
4823 (while | until) CompoundList do CompoundList done
4824 CaseCommand
4826 case Word NL* in NL* CaseList? esac
4827 CaseList
4829 CaseItem (;; NL* CaseList)?
4830 CaseItem
4832 (? Word (| Word)* ) CompleteProgram
4833 DoubleBracketCommand
4835 [[ Ors ]]
4836 Ors
4838 Ands (|| Ands)*
4839 Ands
4841 Nots (&& Nots)*
4842 Nots
4844 !* Primary
4845 Primary
4847 (-b | -c | -d | -e | -f | -G | -g | -h | -k | -L | -N | -n | -O |
4848 -o | -p | -r | -S | -s | -t | -u | -w | -x | -z) Word |
4849 Word (-ef | -eq | -ge | -gt | -le | -lt | -ne | -nt | -ot | -veq |
4851 -vge | -vgt | -vle | -vlt | -vne | = | == | === | =~ | != | !== | <
4852 | >) Word |
4853 ( Ors ) |
4855 Word
4857 FunctionCommand
4859 function Word (( ))? NL* CompoundCommand Redirection*
4860 FunctionDefinition
4862 Name ( ) NL* CompoundCommand Redirection*
4863 SimpleCommand
4865 (Assignment | Redirection) SimpleCommand? |
4866 Word (Word | Redirection)*
4868 Assignment
4870 AssignmentWord |
4871 AssignmentPrefix( NL* (Word NL*)* )
4873 Redirection
4875 IO_NUMBER? RedirectionOperator Word |
4876 IO_NUMBER? <( CompleteProgram ) |
4878 IO_NUMBER? >( CompleteProgram )
4880 RedirectionOperator
4882 < | <> | > | >| | >> | >>| | <& | >& | << | <<- | <<<
4883 NL
4885 <newline>
4886 In the rule for Primary, Word tokens must not be ]]. Additionally, if a
4888 Primary starts with a Word, it must not be any of the possible unary
4889 operators allowed in the rule.
4890 In the rule for SimpleCommand, a Word token is accepted only when the
4892 token cannot be parsed as the first token of an Assignment.
4893 In the rule for Assignment, the ( token must immediately follow the
4895 AssignmentPrefix token, without any blank characters in between.
4896 Here-document contents do not appear as part of the grammar above. They
4898 are parsed just after the newline (NL) token that follows the
4899 corresponding redirection operator.
4900 Alias substitution
4902 Word tokens are subject to alias substitution.
4903 • If a word is going to be parsed as a Word of a SimpleCommand,
4905 the word is subjected to alias substitution of any kind (normal
4906 and global aliases).
4907 • If a word is the next token after the result of an alias
4909 substitution and the substitution string ends with a blank
4910 character, then the word is also subjected to alias
4911 substitution of any kind.
4912 • Other words are subjected to global alias substitution unless
4914 the shell is in the POSIXly-correct mode.
4915 Tokens that are classified as reserved words are not subject to
4917 alias substitution.
4918
4920 The alias built-in defines and/or prints aliases.
4921 Syntax
4923 • alias [-gp] [name[=value]...]
4924 Description
4926 The alias built-in defines and/or prints aliases as specified by
4927 operands. The printed aliases can be used as (part of) shell commands.
4928 The built-in prints all currently defined aliases when given no
4929 operands.
4930 Options
4932 -g, --global
4933 With this option, aliases are defined as global aliases; without
4934 this option, as normal aliases.
4935 -p, --prefix
4937 With this option, aliases are printed in a full command form like
4938 alias -g foo='bar'. Without this option, only command operands are
4939 printed like foo='bar'.
4940 Operands
4942 name
4943 The name of an alias that should be printed.
4944 name=value
4946 The name and value of an alias that is being defined.
4947 Exit status
4949 The exit status of the alias built-in is zero unless there is any
4950 error.
4951 Notes
4953 The characters that cannot be used in an alias name are the space, tab,
4954 newline, and any of =$<>\'"`;&|()#. You can use any characters in an
4955 alias value.
4956 The alias built-in is a mandatory built-in.
4958 The POSIX standard defines no options for the alias built-in, thus no
4960 options are available in the POSIXly correct mode.
4961
4963 The array built-in prints or modifies arrays.
4964 Syntax
4966 • array
4967 • array name [value...]
4969 • array -d name [index...]
4971 • array -i name index [value...]
4973 • array -s name index value
4975 Description
4977 When executed without any option or operands, the built-in prints all
4978 array definitions to the standard output in a form that can be parsed
4979 as commands.
4980 When executed with name and values (but without an option), the
4982 built-in sets the values as the values of the array named name.
4983 With the -d (--delete) option, the built-in removes the indexth values
4985 of the array named name. The number of values in the array will be
4986 decreased by the number of the indexes specified. If the indexth value
4987 does not exist, it is silently ignored.
4988 With the -i (--insert) option, the built-in inserts values into the
4990 array named name. The number of values in the array will be increased
4991 by the number of the values specified. The values are inserted between
4992 the indexth and next values. If index is zero, the values are inserted
4993 before the first value. If index is larger than the number of values in
4994 the array, the values are appended after the last element.
4995 With the -s (--set) option, the built-in sets value as the indexth
4997 value of the array named name. The array must have at least index
4998 values.
4999 Options
5001 -d, --delete
5002 Delete array values.
5003 -i, --insert
5005 Insert array values.
5006 -s, --set
5008 Set an array value.
5009 Operands
5011 name
5012 The name of an array to operate on.
5013 index
5015 The index to an array element. The first element has the index of
5016 1.
5017 value
5019 A string to which the array element is set.
5020 Exit status
5022 The exit status of the array built-in is zero unless there is any
5023 error.
5024 Notes
5026 The array built-in is not defined in the POSIX standard. Yash
5027 implements the built-in as an extension.
5028 The command array name value... is equivalent to the assignment
5030 name=(value...).
5031
5033 The bg built-in resumes a job in the background.
5034 Syntax
5036 • bg [job...]
5037 Description
5039 The bg built-in sends the SIGCONT signal to the specified job. As a
5040 result, the job is resumed in the background (if it has been
5041 suspended).
5042 The name of the job is printed when the job is resumed.
5044 The built-in can be used only when job control is enabled.
5046 Operands
5048 job
5049 The job ID of the job to be resumed.
5050 More than one job can be specified at a time. The current job is
5052 resumed if none is specified.
5053 The percent sign (%) at the beginning of a job ID can be omitted if
5055 the shell is not in the POSIXly-correct mode.
5056 Exit status
5058 The exit status of the bg built-in is zero unless there is any error.
5059 Notes
5061 The bg built-in is a mandatory built-in.
5062 The POSIX standard provides that the built-in shall have no effect when
5064 the job is already running. The bg built-in of yash, however, always
5065 sends the SIGCONT signal to the job.
5066
5068 The bindkey built-in prints or modifies key bindings used in
5069 line-editing.
5070 Syntax
5072 • bindkey -aev [key [command]]
5073 • bindkey -l
5075 Description
5077 When executed with the -l (--list) option, the built-in lists all
5078 available line-editing commands to the standard output.
5079 When executed with one of the other options, the built-in prints or
5081 modifies key bindings for the editing mode specified by the option:
5082 • Without key or command, all currently defined bindings are printed
5084 to the standard output in a form that can be parsed as commands
5085 that restore the current bindings when executed.
5086 • With key but without command, only the binding for the given key is
5088 printed.
5089 • With key and command, key is bound to command.
5091 Options
5093 -a, --vi-command
5094 Print or modify bindings for the vi command mode.
5095 -e, --emacs
5097 Print or modify bindings for the emacs mode.
5098 -v, --vi-insert
5100 Print or modify bindings for the vi insert mode.
5101 Operands
5103 key
5104 A character sequence of one or more keys that is bound to an
5105 editing command. The sequence may include escape sequences.
5106 command
5108 A line-editing command to which key is bound. If command is a
5109 single hyphen (-), key is unbound.
5110 Exit status
5112 The exit status of the bindkey built-in is zero unless there is any
5113 error.
5114 Notes
5116 The bindkey built-in is an elective built-in. It cannot be used in the
5117 POSIXly-correct mode because POSIX does not define its behavior.
5118
5120 The break built-in aborts a loop being executed.
5121 Syntax
5123 • break [nest]
5124 • break -i
5126 Description
5128 When executed without the -i (--iteration) option, the built-in aborts
5129 a currently executed for, while, or until loop. When executed in nested
5130 loops, it aborts the nestth innermost loop. The default nest is one. If
5131 the number of currently executed nested loops is less than nest, the
5132 built-in aborts the outermost loop.
5133 When executed with the -i (--iteration) option, the built-in aborts the
5135 currently executed (innermost) iterative execution.
5136 Options
5138 -i, --iteration
5139 Abort an iterative execution instead of a loop.
5140 Operands
5142 nest
5143 The number of loops to abort, which must be a positive integer.
5144 Exit status
5146 The exit status of the break built-in is:
5147 • zero if a loop was successfully aborted.
5149 • that of the command that was executed just before the break
5151 built-in if an iterative execution was successfully aborted.
5152 Notes
5154 The break built-in is a special built-in.
5155 The POSIX standard defines no options for the break built-in; the
5157 built-in accepts no options in the POSIXly-correct mode.
5158 Treatment of currently executed loops that are not lexically enclosing
5160 the break built-in is unspecified in POSIX. Examples of such loops
5161 include:
5162 • A loop invoking a function in which the break built-in is used.
5164 • A loop in which a trap action is executed in which the break
5166 built-in is used.
5167 Yash does not allow breaking such loops.
5169
5171 The cd built-in changes the working directory.
5172 Syntax
5174 • cd [-L|-P] [directory]
5175 Description
5177 The cd built-in changes the working directory to the directory
5178 specified by the operand.
5179 The pathname of the new working directory is assigned to the PWD
5181 variable, whose previous value is again assigned to the OLDPWD
5182 variable. The new PWD value will not contain any . or .. components
5183 except when the shell is in the POSIXly-correct mode and the new
5184 pathname begins with /...
5185 If directory is a relative path that does not start with ‘.’ or ‘..’,
5187 paths in the CDPATH variable are searched to find a new working
5188 directory. The search is done in a manner similar to the last step of
5189 command search, but a directory is sought instead of an executable
5190 regular file. If a new working directory was found from CDPATH, its
5191 pathname is printed to the standard output. If no applicable directory
5192 was found in the search, directory is simply treated as a pathname
5193 relative to the current working directory.
5194 If the working directory was successfully changed, the value of the
5196 YASH_AFTER_CD variable is executed as a command unless the shell is in
5197 the POSIXly-correct mode. If the variable is an array, its values are
5198 executed iteratively (cf. eval built-in).
5199 Options
5201 -L, --logical
5202 Symbolic links in the pathname of the new working directory are not
5203 resolved. The new value of the PWD may include pathname components
5204 that are symbolic links.
5205 -P, --physical
5207 Symbolic links in the pathname of the new working directory are
5208 resolved. The new value of the PWD variable never includes pathname
5209 components that are symbolic links.
5210 --default-directory=directory
5212 If this option is specified and the directory operand is omitted,
5213 the argument to this option is used for the directory operand. If
5214 the directory operand is specified, this option is ignored.
5215 The -L (--logical) and -P (--physical) options are mutually exclusive:
5217 only the last specified one is effective. If neither is specified, -L
5218 is assumed.
5219 Operands
5221 directory
5222 The pathname of the new working directory.
5223 If directory is a single hyphen (‘-’), the value of the OLDPWD
5225 variable is assumed for the new directory pathname, which is
5226 printed to the standard output.
5227 If directory is omitted, the working directory is changed to the
5229 directory specified by the --default-directory=... option. If that
5230 option is not specified either, the default is the home directory.
5231 Exit status
5233 The exit status of the cd built-in is zero if the working directory was
5234 successfully changed and non-zero if there was an error.
5235 Notes
5237 The cd built-in is a mandatory built-in.
5238 The POSIX standard does not define the use of the YASH_AFTER_CD
5240 variable or the --default-directory=... option. The standard does not
5241 allow using an option with a single hyphen operand.
5242 The exit status of the commands in the YASH_AFTER_CD variable does not
5244 affect that of the cd built-in.
5245
5247 The colon built-in does nothing.
5248 Syntax
5250 • : [argument...]
5251 Description
5253 The colon built-in does nothing. Any command line arguments are
5254 ignored.
5255 Exit status
5257 The exit status of the colon built-in is zero.
5258 Notes
5260 The colon built-in is a special built-in.
5261 Arguments are expanded and redirections are performed as usual. The
5263 colon and true built-ins have the same effect, but colon is a special
5264 built-in while true is a mandatory.
5265
5267 The command built-in executes or identifies a command.
5268 Syntax
5270 • command [-befp] command [argument...]
5271 • command -v|-V [-abefkp] command...
5273 Description
5275 Without the -v (--identify) or -V (--verbose-identify) option, the
5276 built-in executes command with arguments in the same manner as the last
5277 step of execution of simple commands. The command is treated as a
5278 built-in or external command or a function according to the options
5279 specified to the command built-in. The shell does not exit on argument
5280 syntax error etc. even if the command is a special built-in
5281 With the -v (--identify) option, command is identified. If the command
5283 is found in $PATH, its full pathname is printed. If it is a keyword,
5284 function, or built-in that is not found in $PATH, the command name is
5285 simply printed. If it is an alias, it is printed in the form like alias
5286 ll='ls -l'. If the command is not found, nothing is printed and the
5287 exit status is non-zero.
5288 The -V (--verbose-identify) option is similar to the -v (--identify)
5290 option, but the output format is more human-friendly.
5291 Options
5293 -a, --alias
5294 Search for the command as an alias. Must be used with the -v
5295 (--identify) or -V (--verbose-identify) option.
5296 -b, --builtin-command
5298 Search for the command as a built-in.
5299 -e, --external-command
5301 Search for the command as an external command.
5302 -f, --function
5304 Search for the command as a function.
5305 -k, --keyword
5307 Search for the command as a keyword. Must be used with the -v
5308 (--identify) or -V (--verbose-identify) option.
5309 -p, --standard-path
5311 Search the system’s default PATH instead of the current $PATH.
5312 -v, --identify
5314 Identify commands and print in the format defined in the POSIX
5315 standard.
5316 -V, --verbose-identify
5318 Identify commands and print in a human-friendly format.
5319 If none of the -a (--alias), -b (--builtin-command), -e
5321 (--external-command), -f (--function), and -k (--keyword) options is
5322 specified, the following defaults are assumed:
5323 Without the -v (--identify) or -V (--verbose-identify) option
5325 -b -e
5326 With the -v (--identify) or -V (--verbose-identify) option
5328 -a -b -e -f -k
5329 Operands
5331 command
5332 A command to be executed or identified.
5333 argument...
5335 Arguments passed to the executed command.
5336 Exit status
5338 The exit status of the command built-in is:
5339 Without the -v (--identify) or -V (--verbose-identify) option
5341 the exit status of the executed command.
5342 With the -v (--identify) or -V (--verbose-identify) option
5344 zero unless there is any error.
5345 Notes
5347 The command built-in is a mandatory built-in.
5348 In the POSIXly-correct mode, options other than -p, -v, and -V cannot
5350 be used and at most one command can be specified. The POSIX standard
5351 does not allow specifying both -v and -V together, but yash does (only
5352 the last specified one is effective).
5353
5355 The complete built-in generates completion candidates. This built-in
5356 can only be executed from completion functions during command line
5357 completion.
5358 Syntax
5360 • complete [-A pattern] [-R pattern] [-T] [-P prefix] [-S suffix]
5361 [-abcdfghjkuv] [[-O] [-D description] word...]
5362 Description
5364 The built-in generates completion candidates according to the specified
5365 arguments. No matter how candidates are generated, only candidates that
5366 match the word being completed are generated.
5367 Options
5369 -A pattern, --accept=pattern
5370 Only accept candidates that match the pattern specified by this
5371 option. When more than one of this option is specified, only
5372 candidates that match all of the patterns are generated.
5373 -D description, --description=description
5375 Give a description of the word candidates. The description is shown
5376 beside the candidates in the candidate list.
5377 -O, --option
5379 The candidates are treated as command line options. A hyphen is
5380 prepended to each candidate that is treated as an option.
5381 -P prefix, --prefix=prefix
5383 Ignore prefix of the word being completed when generating
5384 candidates. The specified prefix must be initial part of the word.
5385 If the word being completed is file:///home/user/docume for
5387 example, the command line complete -P file:// -f will generate
5388 pathname candidates that complete /home/user/docume.
5389 -R pattern, --reject=pattern
5391 Reject candidates that match the pattern specified by this option.
5392 When more than one of this option is specified, only candidates
5393 that match none of the patterns are generated.
5394 -S suffix, --suffix=suffix
5396 Append suffix to each generated candidate.
5397 -T, --no-termination
5399 Do not append a space after the word is completed. Without this
5400 option, a space is appended to the completed word so that you do
5401 not have to enter a space before the next word.
5402 Options that select candidate types
5404 -a, --alias
5405 Aliases. (same as --normal-alias --global-alias)
5406 --array-variable
5408 Arrays.
5409 --bindkey
5411 Line-editing commands the bindkey built-in accepts.
5412 -b, --builtin-command
5414 Built-in commands. (same as --special-builtin
5415 --mandatory-builtin --elective-builtin --extension-builtin
5416 --substitutive-builtin)
5417 -c, --command
5419 Commands. (same as --builtin-command --external-command
5420 --function)
5421 -d, --directory
5423 Directories.
5424 --dirstack-index
5426 Valid indices of the directory stack.
5427 --elective-builtin
5429 Elective built-in commands.
5430 --executable-file
5432 Executable regular files.
5433 --extension-builtin
5435 Extension built-in commands.
5436 --external-command
5438 External commands.
5439 -f, --file
5441 Files (including directories).
5442 --finished-job
5444 Job IDs of finished jobs.
5445 --function
5447 Functions.
5448 --global-alias
5450 Global aliases.
5451 -g, --group
5453 User groups.
5454 -h, --hostname
5456 Host names.
5457 -j, --job
5459 Job IDs.
5460 -k, --keyword
5462 Keywords.
5463 --mandatory-builtin
5465 Mandatory built-in commands.
5466 --normal-alias
5468 Normal aliases.
5469 --regular-builtin
5471 Obsolete synonym for --extension-builtin
5472 --substitutive-builtin.
5473 --running-job
5475 Job IDs of jobs that are being executed.
5476 --scalar-variable
5478 Variables that are not arrays.
5479 --semi-special-builtin
5481 Obsolete synonym for --mandatory-builtin --elective-builtin.
5482 --signal
5484 Signals.
5485 --special-builtin
5487 Special built-in commands.
5488 --stopped-job
5490 Job IDs of jobs that are suspended.
5491 --substitutive-builtin
5493 Substitutive built-in commands.
5494 -u, --username
5496 Users' log-in names.
5497 -v, --variable
5499 Variables.
5500 If the -d (--directory) option is specified without the -f (--file)
5502 option, the -S / -T options are assumed.
5503 Generated candidates for job IDs do not have leading percent signs
5505 (%). If the word being completed starts with a percent sign, the -P
5506 % option should be specified.
5507 Operands
5509 Operands are treated as completion candidates.
5510 Exit status
5512 The exit status of the built-in is zero if one or more candidates were
5513 generated, one if no candidates were generated, or larger than one if
5514 an error occurred.
5515 Notes
5517 The complete built-in is an elective built-in. It can be used in
5518 completion functions even in the POSIXly-correct mode because the mode
5519 is temporarily disabled during completion.
5520
5522 The continue built-in skips an iteration of a loop being executed.
5523 Syntax
5525 • continue [nest]
5526 • continue -i
5528 Description
5530 When executed without the -i (--iteration) option, the built-in aborts
5531 the current iteration of for, while, or until loop and starts the next
5532 iteration of the loop. When executed in nested loops, it affects the
5533 nestth innermost loop. The default nest is one. If the number of
5534 currently executed nested loops is less than nest, the built-in affects
5535 the outermost loop.
5536 When executed with the -i (--iteration) option, the built-in aborts the
5538 current iteration of (innermost) iterative execution.
5539 Options
5541 -i, --iteration
5542 Skip an iterative execution instead of a loop.
5543 Operands
5545 nest
5546 The nestth innermost loop is affected. nest must be a positive
5547 integer.
5548 Exit status
5550 The exit status of the continue built-in is:
5551 • zero if loop iteration was successfully skipped.
5553 • that of the command that was executed just before the continue
5555 built-in if iterative execution was successfully skipped.
5556 Notes
5558 The continue built-in is a special built-in.
5559 The POSIX standard defines no options for the continue built-in; the
5561 built-in accepts no options in the POSIXly-correct mode.
5562 Treatment of currently executed loops that are not lexically enclosing
5564 the continue built-in is unspecified in POSIX. Examples of such loops
5565 include:
5566 • A loop invoking a function in which the continue built-in is used
5568 • A loop in which a trap action is executed in which the continue
5570 built-in is used
5571 Yash does not allow continuing such loops.
5573
5575 The dirs built-in prints the contents of the directory stack.
5576 Syntax
5578 • dirs [-cv] [index..]
5579 Description
5581 The directory stack is a feature that records history of working
5582 directories. You can use the pushd built-in to save a working directory
5583 in the directory stack, the popd built-in to recall the saved working
5584 directory, and the dirs built-in to see the stack contents. Those
5585 built-ins use the DIRSTACK array and the PWD variable to save the stack
5586 contents. Modifying the array means modifying the stack contents.
5587 Directory stack entries are indexed by signed integers. The entry of
5589 index +0 is the current working directory, +1 is the last saved
5590 directory, +2 is the second last, and so on. Negative indices are in
5591 the reverse order: the entry of index -0 is the first saved directory,
5592 -1 is the second, and -n is the current working directory if the stack
5593 has n entries,
5594 When executed without the -c (--clear) option, the dirs built-in prints
5596 the current contents of the directory stack to the standard output.
5597 With the -c (--clear) option, the built-in clears the directory stack.
5598 Options
5600 -c, --clear
5601 Clear the directory stack contents except for the current working
5602 directory, which has index +0.
5603 -v, --verbose
5605 Print indices when printing stack contents.
5606 Operands
5608 index
5609 The index of a stack entry to be printed.
5610 You can specify more than one index. If you do not specify any
5612 index, all the entries are printed.
5613 Exit status
5615 The exit status of the dirs built-in is zero unless there is any error.
5616 Notes
5618 The dirs built-in is an elective built-in. It cannot be used in the
5619 POSIXly-correct mode because POSIX does not define its behavior.
5620
5622 The disown built-in removes jobs.
5623 Syntax
5625 • disown [-a] [job...}
5626 Description
5628 The disown built-in removes the specified jobs from the job list. The
5629 removed jobs will no longer be job-controlled, but the job processes
5630 continue execution (unless they have been suspended).
5631 Options
5633 -a, --all
5634 Removes all jobs.
5635 Operands
5637 job
5638 The job ID of the job to be removed.
5639 You can specify more than one job ID. If you do not specify any job
5641 ID, the current job is removed. If the shell is not in the
5642 POSIXly-correct mode, the %-prefix of the job ID can be omitted.
5643 Exit status
5645 The exit status of the disown built-in is zero unless there is any
5646 error.
5647 Notes
5649 The disown built-in is an elective built-in. It cannot be used in the
5650 POSIXly-correct mode because POSIX does not define its behavior.
5651
5653 The dot built-in reads a file and executes commands in it.
5654 Syntax
5656 • . [-AL] file [argument...]
5657 Description
5659 The dot built-in reads the specified file, parses its contents as
5660 commands, and executes them in the current command execution
5661 environment.
5662 If arguments are specified, positional parameters are temporarily set
5664 to them. The positional parameters will be restored when the dot
5665 built-in finishes. If no arguments are specified, the positional
5666 parameters are not changed.
5667 If file does not contain any slashes, the shell searches $PATH for a
5669 readable (but not necessarily executable) shell script file whose name
5670 is file in the same manner as command search. If no such file was
5671 found, the shell searches the current working directory for a file
5672 unless in the POSIXly-correct mode. To ensure that the file in the
5673 current working directory is used, start file with ‘./’.
5674 Options
5676 -A, --no-alias
5677 Disable alias substitution while parsing.
5678 -L, --autoload
5680 Search $YASH_LOADPATH instead of $PATH, regardless of whether file
5681 contains slashes. The file value is not considered relative to the
5682 current working directory.
5683 The dot built-in treats as operands any command line arguments after
5685 the first operand.
5686 Operands
5688 file
5689 The pathname of a file to be read.
5690 arguments...
5692 Strings to which positional parameters are set while execution.
5693 Exit status
5695 The exit status of the dot built-in is that of the last command
5696 executed. The exit status is zero if the file contains no commands to
5697 execute and non-zero if a file was not found or could not be opened.
5698 Notes
5700 The dot built-in is a special built-in.
5701 A non-interactive shell immediately exits with a non-zero exit status
5703 if the dot built-in fails to find or open a file to execute.
5704 The POSIX standard defines no options for the dot built-in; the
5706 built-in accepts no options in the POSIXly-correct mode.
5707 The POSIX standard does not define the arguments... operands. It is an
5709 error to specify the arguments... operands in the POSIXly-correct mode.
5710
5712 The echo built-in prints its arguments.
5713 Syntax
5715 • echo [string...]
5716 The built-in treats all command line arguments as operands except for
5718 the options described below. Any word that cannot be parsed as an
5719 acceptable option is treated as an operand. Options must precede all
5720 operands. Syntax errors never happen in the echo built-in.
5721 Description
5723 The echo built-in prints the operand strings followed by a newline to
5724 the standard output. The strings are each separated by a space.
5725 Escape sequences
5727 The ECHO_STYLE variable and the -e option enable escape sequences
5728 that are replaced with corresponding characters:
5729 \a
5731 Bell character (ASCII code: 7)
5732 \b
5734 Backspace (ASCII code: 8)
5735 \c
5737 Nothing. After this escape sequence, no characters are printed
5738 at all.
5739 \e
5741 Escape character (ASCII code: 27)
5742 \f
5744 Form feed character (ASCII code: 12)
5745 \n
5747 Newline character (ASCII code: 10)
5748 \r
5750 Carriage return character (ASCII code: 13)
5751 \t
5753 Horizontal tab character (ASCII code: 9)
5754 \v
5756 Vertical tab character (ASCII code: 11)
5757 \\
5759 Backslash
5760 \0xxx
5762 Character whose code is xxx, where xxx is an octal number of at
5763 most three digits.
5764 When escape sequences are not enabled, they are just printed
5766 intact.
5767 ECHO_STYLE variable
5769 The ECHO_STYLE variable defines which options are accepted and
5770 whether escape sequences are enabled by default. The variable value
5771 should be set to one of the following:
5772 SYSV, XSI
5774 No options are accepted. Escape sequences are always enabled.
5775 BSD
5777 The -n option is accepted. Escape sequences are never enabled.
5778 GNU
5780 The -n, -e, and -E options are accepted. Escape sequences are
5781 not enabled by default, but can be enabled by the -e option.
5782 ZSH
5784 The -n, -e, and -E options are accepted. Escape sequences are
5785 enabled by default, but can be disabled by the -E option.
5786 DASH
5788 The -n option is accepted. Escape sequences are always enabled.
5789 RAW
5791 No options are accepted. Escape sequences are never enabled.
5792 When the ECHO_STYLE variable is not set, it defaults to SYSV.
5794 Options
5796 -n
5797 Do not print a newline at the end.
5798 -e
5800 Enable escape sequences.
5801 -E
5803 Disable escape sequences.
5804 Exit status
5806 The exit status of the echo built-in is zero unless there is any error.
5807 Notes
5809 The POSIX standard does not define the ECHO_STYLE variable nor any
5810 options for the built-in. According to POSIX, the behavior of the
5811 built-in is implementation-defined when the first argument is -n or
5812 when any argument contains a backslash. For maximum portability, the
5813 printf built-in should be preferred over the echo built-in.
5814 Although many values for the ECHO_STYLE variable are defined on the
5816 basis of other existing implementations, yash is not intended to
5817 exactly imitate those originals. Zsh’s echo built-in interprets a
5818 single hyphen argument as a separator between options and operands.
5819 Yash does not support such use of hyphen.
5820
5822 The eval built-in evaluates operands as commands.
5823 Syntax
5825 • eval [-i] [command...]
5826 The eval built-in requires that all options precede operands. Any
5828 command line arguments after the first operand are all treated as
5829 operands.
5830 Description
5832 The eval parses operands as commands and executes them in the current
5833 command execution environment.
5834 When executed without the -i (--iteration) option, all the operands are
5836 concatenated into one string (with a space inserted between each
5837 operand) and parsed/executed at once.
5838 With the -i (--iteration) option, the built-in performs iterative
5840 execution: operands are parsed/executed one by one. If the continue
5841 built-in is executed with the -i (--iteration) option during the
5842 iterative execution, the execution of the current operand is aborted
5843 and the next operand is parsed/executed immediately. The break built-in
5844 with the -i (--iteration) option is similar but the remaining operands
5845 are not parsed/executed. The value of the ? special parameter is saved
5846 before the iterative execution is started. The parameter value is
5847 restored to the saved one after each iteration.
5848 Options
5850 -i, --iteration
5851 Perform iterative execution.
5852 Operands
5854 command
5855 A string that is parsed and executed as commands.
5856 Exit status
5858 The exit status is zero if no command was specified or command
5859 contained no actual command that can be executed. Otherwise, that is,
5860 if the eval built-in executed one or more commands, the exit status of
5861 the eval built-in is that of the last executed command.
5862 Notes
5864 The eval built-in is a special built-in.
5865 The POSIX standard defines no options for the eval built-in; the
5867 built-in accepts no options in the POSIXly-correct mode.
5868
5870 The exec built-in replaces the shell process with another external
5871 command.
5872 Syntax
5874 • exec [-cf] [-a name] [command [argument...]]
5875 The exec built-in requires that all options precede operands. It is
5877 important so that options to the exec built-in are not confused with
5878 options to command. Any command line arguments after command are
5879 treated as arguments.
5880 Description
5882 When the exec built-in is executed with command, the shell executes
5883 command with arguments in a manner similar to the last step of
5884 execution of a simple command. The differences are that command is
5885 always treated as an external command ignoring any existing functions
5886 and built-ins and that the exec system call that starts the external
5887 command is called in the current command execution environment instead
5888 of a subshell, replacing the shell process with the new command
5889 process.
5890 If the shell is in the POSIXly-correct mode or not interactive, failure
5892 in execution of command causes the shell to exit immediately.
5893 If an interactive shell that is not in the POSIXly-correct mode has a
5895 stopped job, the shell prints a warning message and refuses to execute
5896 command. Once the shell process is replaced with an external command,
5897 information about the shell’s jobs is lost, so you will have to resume
5898 or kill the stopped jobs by sending signals by hand. To force the shell
5899 to execute command regardless, specify the -f (--force) option.
5900 When executed without command, the built-in does nothing. As a side
5902 effect, however, redirection applied to the built-in remains in the
5903 current command execution environment even after the built-in finished.
5904 Options
5906 -a name, --as=name
5907 Pass name, instead of command, to the external command as its name.
5908 -c, --clear
5910 Pass to the external command only variables that are assigned in
5911 the simple command in which the built-in is being executed. Other
5912 environment variables are not passed to the command.
5913 -f, --force
5915 Suppress warnings that would prevent command execution.
5916 Operands
5918 command
5919 An external command to be executed.
5920 argument...
5922 Arguments to be passed to the command.
5923 Exit status
5925 If the shell process was successfully replaced with the external
5926 command, there is no exit status since the shell process no longer
5927 exists.
5928 The exit status is:
5930 • 127 if the command was not found,
5932 • 126 if the command was found but could not be executed, and
5934 • zero if no command was specified.
5936 Notes
5938 The exec built-in is a special built-in.
5939 The POSIX standard defines no options for the exec built-in; the
5941 built-in accepts no options in the POSIXly-correct mode.
5942
5944 The exit built-in causes the shell process to exit.
5945 Syntax
5947 • exit [-f] [exit_status]
5948 Description
5950 The exit built-in causes the current shell (or subshell) process to
5951 exit.
5952 If an interactive shell has a stopped job, the shell prints a warning
5954 message and refuses to exit. To force the shell to exit regardless,
5955 specify the -f (--force) option or execute the built-in twice in a row.
5956 If an EXIT trap has been set, the shell executes the trap before
5958 exiting.
5959 Options
5961 -f, --force
5962 Suppress warnings that would prevent the shell from exiting.
5963 Operands
5965 exit_status
5966 A non-negative integer that will be the exit status of the exiting
5967 shell.
5968 If this operand is omitted, the exit status of the shell will be
5970 that of the last command executed before the exit built-in (but, if
5971 the built-in is executed during a trap, the exit status will be
5972 that of the last command before the trap is entered).
5973 If exit_status is 256 or larger, the actual exit status will be the
5975 remainder of exit_status divided by 256.
5976 Exit status
5978 Because the built-in causes the shell to exit, there is no exit status
5979 of the built-in.
5980 As an exception, if the shell refused to exit, the exit status of the
5982 built-in is non-zero.
5983 Notes
5985 The exit built-in is a special built-in.
5986 The POSIX standard defines no options for the exit built-in; the
5988 built-in accepts no options in the POSIXly-correct mode.
5989 The POSIX standard provides that the exit_status operand should be
5991 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
5992 an extension.
5993 If the built-in is executed during an EXIT trap, the shell just exits
5995 without executing the trap again. If exit_status was not specified, the
5996 exit status of the shell is what the exit status would be if the trap
5997 had not been set. See also Termination of the shell.
5998
6000 The export built-in marks variables for export to child processes.
6001 Syntax
6003 • export [-prX] [name[=value]...]
6004 Description
6006 The export built-in is equivalent to the typeset built-in with the -gx
6007 option.
6008 Notes
6010 The export built-in is a special built-in.
6011 The POSIX standard defines the -p option only; other options cannot be
6013 used in the POSIXly-correct mode. The POSIX does not allow using the
6014 option together with operands.
6015
6017 The false built-in does nothing unsuccessfully.
6018 Syntax
6020 • false
6021 Description
6023 The false built-in does nothing. Any command line arguments are
6024 ignored.
6025 Exit status
6027 The exit status of the false built-in is non-zero.
6028 Notes
6030 The false built-in is a mandatory built-in.
6031
6033 The fc built-in re-executes or prints commands from command history.
6034 Syntax
6036 • fc [-qr] [-e editor] [start [end]]
6037 • fc -s[q] [old=new] [start]
6039 • fc -l[nrv] [start [end]]
6041 Description
6043 When executed without the -l (--list) option, the built-in executes the
6044 commands in the command history range specified by the operands. If the
6045 -s (--silent) option is not specified, the shell invokes an editor
6046 which allows you to edit the commands before they are executed. The
6047 commands are executed when you quit the editor. If the -s (--silent)
6048 option is specified, the commands are immediately executed. In either
6049 case, the executed commands are printed to the standard output and
6050 added to the history.
6051 When executed with the -l (--list) option, the built-in prints the
6053 commands in the command history range specified by the operands. By
6054 default, commands are printed with their history entry numbers, but
6055 output format can be changed using the -n (--no-numbers)) and -v
6056 (--verbose) options.
6057 Options
6059 -e editor, --editor=editor
6060 Specify an editor that is used to edit commands.
6061 If this option is not specified, the value of the FCEDIT variable
6063 is used. If the variable is not set either, ed is used.
6064 -l, --list
6066 Print command history entries.
6067 -n, --no-numbers
6069 Don’t print entry numbers when printing history entries.
6070 -q, --quiet
6072 Don’t print commands before executing.
6073 -r, --reverse
6075 Reverse the order of command entries in the range.
6076 -s, --silent
6078 Execute commands without editing them.
6079 -v, --verbose
6081 Print execution time before each history entry when printing.
6082 Operands
6084 start and end
6085 The start and end operands specify a range of command history
6086 entries that are executed or printed. If one of the operands is an
6087 integer, it is treated as a history entry number. A negative
6088 integer means the nth most recent entry where n is the absolute
6089 value of the integer. If one of the operands is not an integer, it
6090 is treated as part of a command string: the most recent entry that
6091 starts with the string is selected as the start or end of the
6092 range.
6093 If the first entry of the range that is specified by start is newer
6095 than the last entry of the range that is specified by end, the
6096 range is reversed as if the -r (--reverse) option was specified.
6097 (If the option is already specified, it is cancelled.)
6098 The default values for start and end are:
6100 ┌──────┬─────────┬───────────────┐
6102 │ │ with -l │ without -l │
6103 ├──────┼─────────┼───────────────┤
6104 │start │ -16 │ -1 │
6105 ├──────┼─────────┼───────────────┤
6106 │end │ -16 │ same as start │
6107 └──────┴─────────┴───────────────┘
6108 old=new
6110 An operand of this format replaces part of the command string. If
6111 the command string contains old, it is replaced with new and the
6112 new string is executed. Only the first occurrence of old is
6113 replaced.
6114 Exit status
6116 If commands was executed, the exit status of the fc built-in is that of
6117 the last executed command. Otherwise, the exit status is zero unless
6118 there is any error.
6119 Notes
6121 The fc built-in is a mandatory built-in.
6122 The POSIX standard does not define the -q (--quiet) or -v (--verbose)
6124 options, so they cannot be used in the POSIXly-correct mode.
6125 Command history cannot be modified during line-editing.
6127
6129 The fg built-in resumes a job in the foreground.
6130 Syntax
6132 • fg [job...]
6133 Description
6135 The fg built-in brings the specified job to the foreground and sends
6136 the SIGCONT signal to the job. As a result, the job is resumed in the
6137 foreground (if it has been suspended). The built-in then waits for the
6138 job to finish and returns the exit status of it.
6139 The name of the job is printed when the job is resumed. When not in the
6141 POSIXly-correct mode, the job number is also printed.
6142 The built-in can be used only when job control is enabled.
6144 Operands
6146 job
6147 The job ID of the job to be resumed.
6148 If more than one job is specified, they are resumed in order, one
6150 at a time. The current job is resumed if none is specified.
6151 The percent sign (%) at the beginning of a job ID can be omitted if
6153 the shell is not in the POSIXly-correct mode.
6154 Exit status
6156 The exit status of the fg built-in is that of the (last) job resumed.
6157 The exit status is non-zero when there was some error.
6158 Notes
6160 The fg built-in is a mandatory built-in.
6161 You cannot specify more than one job in the POSIXly-correct mode.
6163
6165 The getopts built-in parses command options.
6166 Syntax
6168 • getopts optionlist variable [argument...]
6169 Description
6171 The getopts built-in parses single-character options that appear in
6172 arguments. Each time the built-in is invoked, it parses one option and
6173 assigns the option character to variable.
6174 The optionlist operand is a list of option characters that should be
6176 accepted by the parser. In optionlist, an option that takes an argument
6177 should be specified as the option character followed by a colon. For
6178 example, if you want the -a, -b and -c options to be parsed and the -b
6179 option to take an argument, then optionlist should be ab:c.
6180 When an option that takes an argument is parsed, the argument is
6182 assigned to the OPTARG variable.
6183 When an option that is not specified in optionlist is found or when an
6185 option argument is missing, the result depends on the first character
6186 of optionlist:
6187 • If optionlist starts with a colon, the option character is assigned
6189 to the OPTARG variable and variable is set to either ? (when the
6190 option is not in optionlist) or : (when the option argument is
6191 missing).
6192 • Otherwise, variable is set to ?, the OPTARG variable is unset, and
6194 an error message is printed.
6195 The built-in parses one option for each execution. For all options in a
6197 set of command line arguments to be parsed, the built-in has to be
6198 executed repeatedly with the same arguments. The built-in uses the
6199 OPTIND variable to remember which argument should be parsed next. When
6200 the built-in is invoked for the first time, the variable value must be
6201 1, which is the default value. You must not modify the variable until
6202 all the options have been parsed, when the built-in sets the variable
6203 to the index of the first operand in arguments. (If there are no
6204 operands, it will be set to the number of arguments plus one.)
6205 When you want to start parsing a new set of arguments, you have to
6207 reset the OPTIND variable to 1 beforehand.
6208 Operands
6210 optionlist
6211 A list of options that should be accepted as valid options in
6212 parsing.
6213 variable
6215 The name of a variable the result is to be assigned to.
6216 arguments
6218 Command line arguments that are to be parsed.
6219 When no arguments are given, the positional parameters are parsed.
6221 Exit status
6223 If an option is found, whether or not it is specified in optionlist,
6224 the exit status is zero. If there is no more option to be parsed, the
6225 exit status is non-zero.
6226 Example
6228 aopt=false bopt= copt=false
6229 while getopts ab:c opt
6230 do
6231 case $opt in
6232 a) aopt=true ;;
6233 b) bopt=$OPTARG ;;
6234 c) copt=true ;;
6235 \?) return 2 ;;
6236 esac
6237 done
6238 if $aopt; then echo Option -a specified; fi
6239 if [ -n "$bopt" ]; then echo Option -b $bopt specified; fi
6240 if $copt; then echo Option -c specified; fi
6241 shift $((OPTIND - 1))
6242 echo Operands are: $*
6243 Notes
6245 In arguments that are parsed, options must precede operands. The
6246 built-in ends parsing when it encounters the first operand.
6247 The getopts built-in is a mandatory built-in.
6249 The POSIX standard does not specify what will happen when the OPTIND
6251 variable is assigned a value other than 1.
6252 In the POSIXly-correct mode, option characters in optionlist must be
6254 alphanumeric.
6255
6257 The hash built-in remembers, forgets, or reports command locations.
6258 Syntax
6260 • hash command...
6261 • hash -r [command...]
6263 • hash [-a]
6265 • hash -d user...
6267 • hash -dr [user...]
6269 • hash -d
6271 Description
6273 When executed with commands but without options, the built-in
6274 immediately performs command path search and caches commands' full
6275 paths.
6276 When executed with the -r (--remove) option, it removes the paths of
6278 commands (or all cached paths if none specified) from the cache.
6279 When executed without options or commands, it prints the currently
6281 cached paths to the standard output.
6282 With the -d (--directory) option, the built-in does the same things to
6284 the home directory cache, rather than the command path cache. Cached
6285 home directory paths are used in tilde expansion.
6286 Options
6288 -a, --all
6289 Print all cached paths.
6290 Without this option, paths for built-ins are not printed.
6292 -d, --directory
6294 Affect the home directory cache instead of the command path cache.
6295 -r, --remove
6297 Remove cached paths.
6298 Operands
6300 command
6301 The name of an external command (that does not contain any slash).
6302 user
6304 A user name.
6305 Exit status
6307 The exit status of the hash built-in is zero unless there is any error.
6308 Notes
6310 The shell automatically caches command and directory paths when
6311 executing a command or performing tilde expansion, so normally there is
6312 no need to use this built-in explicitly to cache paths.
6313 Assigning a value to the PATH variable removes all command paths from
6315 the cache as if hash -r was executed.
6316 The POSIX standard defines the -r option only: other options cannot be
6318 used in the POSIXly-correct mode.
6319 The hash built-in is a mandatory built-in.
6321
6323 The help built-in prints usage of built-ins.
6324 Syntax
6326 • help [built-in...]
6327 Description
6329 The help built-in prints a description of built-ins.
6330 Operands
6332 built-ins
6333 Names of built-ins.
6334 Exit status
6336 The exit status of the help built-in is zero unless there is any error.
6337 Notes
6339 The help built-in is an elective built-in. It cannot be used in the
6340 POSIXly-correct mode because POSIX does not define its behavior.
6341 Many built-ins of yash accept the --help option that prints the same
6343 description.
6344
6346 The history built-in prints or edits command history.
6347 Syntax
6349 • history [-cF] [-d entry] [-s command] [-r file] [-w file] [count]
6350 Description
6352 The history built-in prints or edits command history.
6353 When executed with an option, the built-in edits history according to
6355 the option. If more than one option is specified, each option is
6356 processed in order.
6357 When executed with the count operand, the built-in prints the most
6359 recent count history entries to the standard output in the same manner
6360 as the fc built-in.
6361 When executed with neither options nor operands, the built-in prints
6363 the whole history.
6364 Options
6366 -c, --clear
6367 Clear all history entries completely.
6368 -d entry, --delete=entry
6370 Delete the specified entry. The entry should be specified in the
6371 same manner as the start and end operands of the fc built-in.
6372 -F, --flush-file
6374 Rebuild the history file. This operation removes unused old data
6375 from the file.
6376 -r file, --read=file
6378 Read command lines from file and add them to the history. The file
6379 contents are treated as lines of simple text.
6380 -s command, --set=command
6382 Add command as a new history entry after removing the most recent
6383 entry.
6384 -w file, --write=file
6386 Write the whole history to file. Any existing data in the file will
6387 be lost. The output format is lines of simple text, each of which
6388 is a command string.
6389 Operands
6391 count
6392 The number of entries to be printed.
6393 Exit status
6395 The exit status of the history built-in is zero unless there is any
6396 error.
6397 Notes
6399 The history built-in is an elective built-in. It cannot be used in the
6400 POSIXly-correct mode because POSIX does not define its behavior.
6401 Command history cannot be modified during line-editing.
6403
6405 The jobs built-in reports job status.
6406 Syntax
6408 • jobs [-lnprs] [job...]
6409 Description
6411 The jobs built-in prints information of jobs the shell is currently
6412 controlling.
6413 By default, the following information is printed for each job, line by
6415 line:
6416 • the job number,
6418 • the + or - symbol if the job is the current or previous job,
6420 respectively,
6421 • the status, and
6423 • the command string.
6425 Options
6427 -l, --verbose
6428 Print the process ID, status, and command string for each process
6429 in the jobs.
6430 -n, --new
6432 Print new jobs only: jobs whose status has never been reported
6433 since the status changed.
6434 -p, --pgid-only
6436 Print process group IDs of jobs only.
6437 -r, --running-only
6439 Print running jobs only.
6440 -s, --stopped-only
6442 Print stopped jobs only.
6443 Operands
6445 jobs
6446 The job IDs of jobs to be reported. When no job is specified, all
6447 jobs under the shell’s control are reported.
6448 The percent sign (%) at the beginning of a job ID can be omitted if
6450 the shell is not in the POSIXly-correct mode.
6451 Exit status
6453 The exit status of the jobs built-in is zero unless there is any error.
6454 Notes
6456 The jobs built-in is a mandatory built-in.
6457 The POSIX standard defines the -l and -p options only: other options
6459 cannot be used in the POSIXly-correct mode. In the POSIXly-correct
6460 mode, the effect of the -l option is different in that status is
6461 reported for each job rather than for each process.
6462 The process group ID of a job executed by yash is equal to the process
6464 ID of the first command of the pipeline that forms the job.
6465
6467 The kill built-in sends a signal to processes.
6468 Syntax
6470 • kill [-signal|-s signal|-n signal] process...
6471 • kill -l [-v] [signal...]
6473 The kill built-in requires that all options precede operands. Any
6475 command line arguments after the first operand are all treated as
6476 operands.
6477 Description
6479 When executed without the -l option, the built-in sends a signal to
6480 processes. The signal sent can be specified by option. The SIGTERM
6481 signal is sent if no signal is specified.
6482 When executed with the -l option, the built-in prints information of
6484 signals to the standard output. If no signal is specified, information
6485 of all signals is printed.
6486 Options
6488 Signal-specifying options
6489 -signal, -s signal, -n signal
6490 A signal-specifying option specifies a signal to be sent to
6491 processes. signal can be specified by name or number. If
6492 number 0 is specified, the built-in checks if a signal could be
6493 sent to the processes but no signal is actually sent. Signal
6494 names are case-insensitive.
6495 You can specify at most one signal-specifying option at a time.
6497 Other options
6499 -l
6500 Print signal information instead of sending a signal.
6501 -v
6503 Print more signal information.
6504 Without this option, the built-in prints the signal name only.
6506 This option adds the signal number and a short description.
6507 When the -v option is specified, the -l option can be omitted.
6509 Operands
6511 processes
6512 Specify processes to which a signal is sent.
6513 Processes can be specified by the process ID, the process group ID,
6515 or the job ID. The process group ID must be prefixed with a hyphen
6516 (-) so that it is not treated as a process ID.
6517 When 0 is specified as process, the signal is sent to the process
6519 group to which the shell process belongs. When -1 is specified, the
6520 signal is sent to all processes on the system.
6521 signal
6523 Specify a signal of which information is printed.
6524 The signal can be specified by the name, the number, or the exit
6526 status of a command that was killed by the signal.
6527 Exit status
6529 The exit status of the kill built-in is zero unless there is any error.
6530 If the signal was sent to at least one process, the exit status is zero
6531 even if the signal was not sent to all of the specified processes.
6532 Notes
6534 The kill built-in is a mandatory built-in.
6535 Command arguments that start with a hyphen should be used with care.
6537 The command kill -1 -2, for example, sends signal 1 to process group 2
6538 since -1 is treated as a signal-specifying option and -2 as an operand
6539 that specifies a process group. The commands kill -- -1 -2 and kill
6540 -TERM -1 -2, on the other hand, treats both -1 and -2 as operands.
6541 The POSIX standard does not define the -n or -v options, so they cannot
6543 be used in the POSIXly-correct mode. The standard does not allow
6544 specifying a signal number as the argument of the -s option or a signal
6545 name as the signal operand.
6546 The standard requires signal names to be specified without the SIG
6548 prefix, like INT and QUIT. If the shell is not in the POSIXly-correct
6549 mode, the built-in accepts SIG-prefixed signal names as well.
6550
6552 The local built-in prints or sets local variables.
6553 Syntax
6555 • local [-rxX] [name[=value]...]
6556 Description
6558 The local built-in is equivalent to the typeset built-in except that
6559 the -f (--functions) and -g (--global) options cannot be used.
6560 Notes
6562 The local built-in is an elective built-in. It cannot be used in the
6563 POSIXly-correct mode because POSIX does not define its behavior.
6564
6566 The popd built-in pops a directory from the directory stack.
6567 Syntax
6569 • popd [index]
6570 Description
6572 The popd built-in removes the last entry from the directory stack,
6573 returning to the previous working directory. If index is given, the
6574 entry specified by index is removed instead of the last one.
6575 Operands
6577 index
6578 The index of a directory stack entry you want to remove.
6579 If omitted, +0 (the last entry) is assumed.
6581 Exit status
6583 The exit status of the popd built-in is zero unless there is any error.
6584 Notes
6586 It is an error to use this built-in when there is only one directory
6587 stack entry.
6588 The popd built-in is an elective built-in. It cannot be used in the
6590 POSIXly-correct mode because POSIX does not define its behavior.
6591
6593 The printf built-in prints formatted values.
6594 Syntax
6596 • printf format [value...]
6597 Description
6599 The printf built-in formats values according to format and prints them
6600 to the standard output. Unlike the echo built-in, the printf built-in
6601 does not print a newline automatically.
6602 The formatting process is very similar to that of the printf function
6604 in the C programming language. You can use conversion specifications
6605 (which start with %) and escape sequences (which start with \) in
6606 format. Any other characters that are not part of a conversion
6607 specification or escape sequence are printed literally.
6608 Conversion specifications
6610 A conversion specification starts with a percent sign (%).
6611 A conversion specification except %% consumes a value, which is
6613 formatted according to the specification and printed. Each
6614 conversion specification consumes one value in the order of
6615 appearance. If there are more values than conversion
6616 specifications, the entire format is re-processed until all the
6617 values are consumed. If a value to be consumed is missing, it is
6618 assumed to be an empty string (if the specification requires a
6619 string) or zero (if a number). If no values are given, format is
6620 processed just once.
6621 Available conversion specifications are:
6623 %d, %i
6625 prints a signed integer in decimal
6626 %u
6628 prints an unsigned integer in decimal
6629 %o
6631 prints an unsigned integer in octal
6632 %x
6634 prints an unsigned integer in lowercase hexadecimal
6635 %X
6637 prints an unsigned integer in uppercase hexadecimal
6638 %f
6640 prints a floating-point number in lowercase
6641 %F
6643 prints a floating-point number in uppercase
6644 %e
6646 prints a floating-point number with exponent in lowercase
6647 %E
6649 prints a floating-point number with exponent in uppercase
6650 %g
6652 the same as %f or %e, automatically selected
6653 %G
6655 the same as %F or %E, automatically selected
6656 %c
6658 prints the first character of string
6659 %s
6661 prints a string
6662 %b
6664 prints a string (recognizing escape sequences like the echo
6665 built-in)
6666 %%
6668 prints a percent sign (%)
6669 For %g and %G, the specification that is actually used is %f or %F
6671 if the exponent part is between -5 and the precision (exclusive);
6672 %e or %E otherwise.
6673 In a conversion specification except %%, the leading percent sign
6675 may be followed by flags, field width, and/or precision in this
6676 order.
6677 The flags are a sequence of any number of the following characters:
6679 Minus sign (-)
6681 With this flag, spaces are appended to the formatted value to
6682 fill up to the field width. Otherwise, spaces are prepended.
6683 Plus sign (+)
6685 A plus or minus sign is always prepended to a number.
6686 Space ( )
6688 A space is prepended to a formatted number if it has no plus or
6689 minus sign.
6690 Hash sign (#)
6692 The value is formatted in an alternative form: For %o, the
6693 printed octal integer has at least one leading zero. For %x and
6694 %X, a non-zero integer is formatted with 0x and 0X prefixes,
6695 respectively. For %e, %E, %f, %F, %g, and %G, a decimal mark
6696 (a.k.a. radix character) is always printed even if the value is
6697 an exact integer. For %g and %G, the printed number has at
6698 least one digit in the fractional part.
6699 Zero (0)
6701 Zeros are prepended to a formatted number to fill up to the
6702 field width. This flag is ignored if the minus flag is
6703 specified or if the conversion specification is %d, %i, %u, %o,
6704 %x, or %X with a precision.
6705 A field width is specified as a decimal integer that has no leading
6707 zeros.
6708 A field width defines a minimum byte count of a formatted value. If
6710 the formatted value does not reach the minimum byte count, so many
6711 spaces are prepended that the printed value has the specified byte
6712 count.
6713 A precision is specified as a period (.) followed by a decimal
6715 integer. If the integer is omitted after the period, the precision
6716 is assumed to be zero.
6717 For conversion specifications %d, %i, %u, %o, %x, and %X, a
6719 precision defines a minimum digit count. If the formatted integer
6720 does not reach the minimum digit count, so many zeros are prepended
6721 that the printed integer has the specified number of digits. The
6722 default precision is one for these conversion specifications.
6723 For conversion specifications %e, %E, %f, and %F, a precision
6725 defines the number of digits after the decimal mark. The default
6726 precision is six for these conversion specifications.
6727 For conversion specifications %g, and %G, a precision defines a
6729 maximum number of significant digits in the printed value. The
6730 default precision is six for these conversion specifications.
6731 For conversion specifications %s, and %b, a precision defines a
6733 maximum byte count of the printed string. The default precision is
6734 infinity for these conversion specifications.
6735 In the conversion specification %08.3f, the zero flag is specified,
6737 the field width is 8, and the precision is 3. If this specification
6738 is applied to value 12.34, the output will be 0012.340.
6739 Escape sequences
6741 The following escape sequences are recognized in format:
6742 \a
6744 Bell character (ASCII code: 7)
6745 \b
6747 Backspace (ASCII code: 8)
6748 \f
6750 Form feed character (ASCII code: 12)
6751 \n
6753 Newline character (ASCII code: 10)
6754 \r
6756 Carriage return character (ASCII code: 13)
6757 \t
6759 Horizontal tab character (ASCII code: 9)
6760 \v
6762 Vertical tab character (ASCII code: 11)
6763 \\
6765 Backslash
6766 \"
6768 Double quotation
6769 \'
6771 Single quotation (apostrophe)
6772 \xxx
6774 Character whose code is xxx, where xxx is an octal number of at
6775 most three digits.
6776 Operands
6778 format
6779 A string that defines how values should be formatted.
6780 values
6782 Values that are formatted according to format.
6783 A value is either a number or a string.
6785 When a numeric value is required, value can be a single or double
6787 quotation followed by a character, instead of a normal number. For
6788 example, the command printf '%d' '"3' will print 51 on a typical
6789 environment where character 3 has character code 51.
6790 Exit status
6792 The exit status of the printf built-in is zero unless there is any
6793 error.
6794 Notes
6796 The POSIX standard does not precisely define how multibyte characters
6797 should be handled by the built-in. When you use the %s conversion
6798 specification with precision or the %c conversion specification, you
6799 may obtain unexpected results if the formatted value contains a
6800 character that is represented by more than one byte. Yash never prints
6801 only part of the bytes that represent a single multibyte character
6802 because all multibyte characters are converted to wide characters when
6803 processed in the shell.
6804 If the shell is not in the POSIXly-correct mode and the “long double”
6806 floating-point arithmetic is supported on the running system, then
6807 “long double” is used for floating-point conversion specifications.
6808 Otherwise, “double” is used.
6809
6811 The pushd built-in pushes a directory into the directory stack.
6812 Syntax
6814 • pushd [-L|-P] [directory]
6815 Description
6817 The pushd built-in changes the working directory to directory in the
6818 same manner as the cd built-in and adds it to the directory stack. If
6819 the working directory could not be changed successfully, the stack is
6820 not modified.
6821 Options
6823 The pushd built-in accepts the following option as well as the options
6824 that can be used for the cd built-in:
6825 --remove-duplicates
6827 If the new working directory has already been in the directory
6828 stack, the existing entry is removed from the stack before the new
6829 directory is pushed into the stack.
6830 Operands
6832 directory
6833 The pathname of the new working directory.
6834 If directory is a single hyphen (‘-’), the value of the OLDPWD
6836 variable is assumed for the new directory pathname, which is
6837 printed to the standard output.
6838 If directory is an integer with a plus or minus sign, it is
6840 considered as an entry index of the directory stack. The entry is
6841 removed from the stack and then pushed to the stack again.
6842 If directory is omitted, the working directory is changed to the
6844 directory specified by the --default-directory=... option. If that
6845 option is not specified either, the default is index +1.
6846 Exit status
6848 The exit status of the pushd built-in is zero unless there is any
6849 error.
6850 Notes
6852 The pushd built-in is an elective built-in. It cannot be used in the
6853 POSIXly-correct mode because POSIX does not define its behavior.
6854
6856 The pwd built-in prints the current working directory.
6857 Syntax
6859 • pwd [-L|-P]
6860 Description
6862 The pwd built-in prints an absolute path to the shell’s current working
6863 directory to the standard output.
6864 Options
6866 -L, --logical
6867 If the value of the PWD variable is an absolute path to the shell’s
6868 working directory and the path does not contain any . or ..
6869 components, then the path is printed. Otherwise, the printed path
6870 is the same as when the -P option is specified.
6871 -P, --physical
6873 The printed path does not contain any . or .. components,
6874 symbolic link components, or redundant slashes.
6875 The -L (--logical) and -P (--physical) options are mutually exclusive:
6877 only the last specified one is effective. If neither is specified, -L
6878 is assumed.
6879 Exit status
6881 The exit status of the pwd built-in is zero unless there is any error.
6882 Notes
6884 The pwd built-in is a mandatory built-in.
6885
6887 The read built-in reads a line from the standard input.
6888 Syntax
6890 • read [-Aer] [-P|-p] variable...
6891 Description
6893 The read built-in reads a line of string from the standard input and
6894 assigns it to the specified variables.
6895 If the -r (--raw-mode) option is specified, all characters in the line
6897 are treated literally.
6898 If the -r (--raw-mode) option is not specified, backslashes in the line
6900 are treated as quotations. If a backslash is at the end of the line, it
6901 is treated as a line continuation. When the built-in reads the next
6902 line, the PS2 variable is used as a prompt if the shell is interactive
6903 and the standard input is a terminal.
6904 The input line is subject to field splitting. The resulting words are
6906 assigned to variables in order. If there are more words than variables,
6907 the last variable is assigned all the remaining words (as if the words
6908 were not split). If the words are fewer than variables, the remaining
6909 variables are assigned empty strings.
6910 Options
6912 -A, --array
6913 Make the last variable an array. Instead of assigning a
6914 concatenation of the remaining words to a normal variable, the
6915 words are assigned to an array.
6916 -e, --line-editing
6918 Use line-editing to read the line.
6919 To use line-editing, all of the following conditions must also be
6921 met:
6922 • The shell is interactive.
6924 • The vi or emacs option is enabled.
6926 • The standard input and standard error are connected to a
6928 terminal.
6929 -P, --ps1
6931 Print the PS1 variable as a prompt before reading the (first) line
6932 if the shell is interactive and the standard input is a terminal.
6933 -p prompt, --prompt=prompt
6935 Print the specified prompt before reading the (first) line if the
6936 shell is interactive and the standard input is a terminal.
6937 -r, --raw-mode
6939 Don’t treat backslashes as quotations.
6940 Operands
6942 variables
6943 Names of variables to which input words are assigned.
6944 Exit status
6946 The exit status of the read built-in is zero unless there is any error.
6947 Note that the exit status is non-zero if an end of input is encountered
6949 before reading the entire line.
6950 Notes
6952 The read built-in is a mandatory built-in.
6953 The POSIX standard defines the -r option only: other options cannot be
6955 used in the POSIXly-correct mode.
6956 The PS1R and PS1S variables affect the behavior of line-editing if the
6958 PS1 prompt is used. The same for PS2.
6959
6961 The readonly built-in makes variables and functions read-only.
6962 Syntax
6964 • readonly [-pxX] [name[=value]...]
6965 • readonly -f[p] [name...]
6967 Description
6969 The readonly built-in is equivalent to the typeset built-in with the
6970 -gr option.
6971 Notes
6973 The readonly built-in is a special built-in.
6974 The POSIX standard defines the -p option only; other options cannot be
6976 used in the POSIXly-correct mode. The POSIX does not allow using the
6977 option together with operands.
6978
6980 The return built-in returns from a function or script.
6981 Syntax
6983 • return [-n] [exit_status]
6984 Description
6986 When executed without the -n (--no-return) option, one of the following
6987 happens:
6988 • If the shell is executing a function, the execution of the function
6990 is terminated.
6991 • If the dot built-in is executing a script, the execution of the
6993 script is terminated.
6994 • If the shell is executing a script during initialization, the
6996 execution of the script is terminated.
6997 • If the shell is executing a trap, the execution of the trap is
6999 terminated for the currently handled signal.
7000 • Otherwise, the shell exits unless it is interactive.
7002 When executed with the -n (--no-return) option, the built-in does
7004 nothing but return the specified exit_status.
7005 Options
7007 -n, --no-return
7008 Do not terminate a function, script, trap, or the shell.
7009 Operands
7011 exit_status
7012 The exit status of the built-in.
7013 The value must be a non-negative integer.
7015 If omitted, the exit status of the last executed command is used.
7017 (But when the shell is executing a trap, the exit status of the
7018 last command before the trap is used.)
7019 Exit status
7021 The exit status of the return built-in is defined by the exit_status
7022 operand. The exit status is used also as the exit status of the
7023 terminated function, script, or the shell.
7024 Notes
7026 The return built-in is a special built-in.
7027 The POSIX standard provides that the exit_status operand should be
7029 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
7030 an extension.
7031 In the POSIX standard, the behavior of the return built-in is defined
7033 only when the shell is executing a function or script.
7034 The POSIX standard defines no options for the return built-in; the
7036 built-in accepts no options in the POSIXly-correct mode.
7037
7039 The set built-in sets shell options and positional parameters.
7040 Syntax
7042 • set [options] [operands]
7043 • set -o
7045 • set +o
7047 The set built-in requires that all options precede operands. Any
7049 command line arguments after the first operand are all treated as
7050 operands.
7051 Description
7053 When executed without any command arguments, the built-in prints a list
7054 of all existing variables to the standard input in a form that can be
7055 reused as commands that will restore the variable definitions.
7056 When -o is the only command argument, the built-in prints a list of
7058 shell options with their current settings. When +o is the only command
7059 argument, the built-in prints commands that can be reused to restore
7060 the current shell option settings.
7061 In other cases, the built-in changes shell option settings and/or
7063 positional parameters.
7064 Options
7066 When one or more options are specified, the built-in enables or
7067 disables the shell options. A normal hyphen-prefixed option enables a
7068 shell option. An option that is prefixed with a plus (+) instead of a
7069 hyphen disables a shell option. For example, options -m, -o monitor,
7070 and --monitor enable the monitor option and options +m, +o monitor,
7071 ++monitor disable it.
7072 The name of a long option is case-insensitive and may include
7074 irrelevant non-alphanumeric characters, which are ignored. For example,
7075 options --le-comp-debug and --LeCompDebug are equivalent. If no is
7076 prepended to the name of a long option, the meaning is reversed. For
7077 example, --noallexport is equivalent to ++allexport and ++nonotify to
7078 --notify.
7079 An option can be specified in one of the following forms:
7081 • a long option e.g. --allexport
7083 • an -o option with a option name specified as the argument e.g. -o
7085 allexport
7086 • a single-character option e.g. -a
7088 Not all options can be specified as single-character options.
7090 The available options are:
7092 all-export (-a)
7094 When enabled, all variables are automatically exported when
7095 assigned.
7096 brace-expand
7098 This option enables brace expansion.
7099 case-glob
7101 (Enabled by default) When enabled, pattern matching is
7102 case-sensitive in pathname expansion.
7103 clobber (+C)
7105 (Enabled by default) When enabled, the > redirection behaves the
7106 same as the >| redirection.
7107 cur-async, cur-bg, cur-stop
7109 (Enabled by default) These options affect choice of the current job
7110 (cf. job ID).
7111 dot-glob
7113 When enabled, periods at the beginning of filenames are not treated
7114 specially in pathname expansion.
7115 emacs
7117 This option enables line-editing in the emacs mode.
7118 empty-last-field
7120 When enabled, field splitting does not remove the last field even
7121 if it is empty.
7122 err-exit (-e)
7124 When enabled, if a pipeline ends with a non-zero exit status, the
7125 shell immediately exits unless the following suppress condition is
7126 met:
7127 • the pipeline is a condition of an if command or while or until
7129 loop;
7130 • the pipeline is prefixed by !; or
7132 • the pipeline is a single compound command other than a subshell
7134 grouping.
7135 err-return
7137 This option is like the err-exit option, but the return built-in is
7138 executed instead of the shell exiting on a non-zero exit status.
7139 Unlike err-exit, the suppress condition does not apply inside a
7140 function, subshell grouping, or script file.
7141 exec (+n)
7143 (Enabled by default) Commands are actually executed only when this
7144 option is enabled. Otherwise, commands are just parsed and not
7145 executed. Disabling this option may be useful for syntax checking.
7146 In an interactive shell, this option is always assumed enabled.
7147 extended-glob
7149 This option enables extension in pathname expansion.
7150 for-local
7152 (Enabled by default) If a for loop is executed within a function,
7153 this option causes the iteration variable to be created as a local
7154 variable, even if the variable already exists globally. This option
7155 has no effect if the POSIXly-correct mode is active.
7156 glob (+f)
7158 (Enabled by default) This option enables pathname expansion.
7159 hash-on-def (-h)
7161 When a function is defined when this option is enabled, the shell
7162 immediately performs command path search for each command that
7163 appears in the function and caches the command’s full path.
7164 hist-space
7166 When enabled, command lines that start with a whitespace are not
7167 saved in command history.
7168 ignore-eof
7170 When enabled, an interactive shell does not exit when EOF (end of
7171 file) is input. This prevents the shell from exiting when you
7172 accidentally hit Ctrl-D.
7173 le-always-rp, le-comp-debug, le-conv-meta, le-no-conv-meta, le-predict,
7175 le-predict-empty, le-prompt-sp, le-visible-bell, le-trim-right
7176 See shell options on line-editing.
7177 mark-dirs
7179 When enabled, resulting directory names are suffixed by a slash in
7180 pathname expansion.
7181 monitor (-m)
7183 This option enables job control. This option is enabled by default
7184 for an interactive shell.
7185 notify (-b)
7187 When the status of a job changes when this option is enabled, the
7188 shell immediately notifies at any time. This option overrides the
7189 notify-le option.
7190 notify-le
7192 This option is similar to the notify option, but the status change
7193 is notified only while the shell is waiting for input with
7194 line-editing.
7195 null-glob
7197 When enabled, in pathname expansion, patterns that do not match any
7198 pathname are removed from the command line rather than left as is.
7199 pipe-fail
7201 When enabled, the exit status of a pipeline is zero if and only if
7202 all the subcommands of the pipeline exit with an exit status of
7203 zero.
7204 posixly-correct
7206 This option enables the POSIXly-correct mode.
7207 trace-all
7209 (Enabled by default) When this option is disabled, the x-trace
7210 option is temporarily disabled while the shell is executing
7211 commands defined in the COMMAND_NOT_FOUND_HANDLER, PROMPT_COMMAND,
7212 or YASH_AFTER_CD variable.
7213 unset (+u)
7215 (Enabled by default) When enabled, an undefined parameter is
7216 expanded to an empty string in parameter expansion and treated as
7217 zero in arithmetic expansion. When disabled, expansion of an
7218 undefined parameter results in an error.
7219 verbose (-v)
7221 When enabled, the shell prints each command line to the standard
7222 error before parsing and executing it.
7223 vi
7225 This option enables line-editing in the vi mode. This option is
7226 enabled by default in an interactive shell if the standard input
7227 and error are both terminals.
7228 x-trace (-x)
7230 When enabled, the results of expansion are printed to the standard
7231 error for each simple command being executed. When printed, each
7232 line is prepended with an expansion result of the PS4 variable. See
7233 also the trace-all option.
7234 Operands
7236 If one or more operands are passed to the set built-in, current
7237 positional parameters are all removed and the operands are set as new
7238 positional parameters. If the -- separator (cf. syntax of command
7239 arguments) is passed, the positional parameters are set even when there
7240 are no operands, in which case new positional parameters will be
7241 nothing.
7242 Exit status
7244 The exit status of the set built-in is zero unless there is any error.
7245 Notes
7247 The set built-in is a special built-in.
7248 In the POSIX standard, available shell options are much limited. The
7250 standard does not define:
7251 • long options such as --allexport,
7253 • prepending no to negate an option,
7255 • using uppercase letters and/or non-alphanumeric characters in
7257 option names
7258 The options defined in the standard are:
7260 • -a, -o allexport
7262 • -e, -o errexit
7264 • -m, -o monitor
7266 • -C, -o noclobber
7268 • -n, -o noexec
7270 • -f, -o noglob
7272 • -b, -o notify
7274 • -u, -o nounset
7276 • -v, -o verbose
7278 • -x, -o xtrace
7280 • -h
7282 • -o ignoreeof
7284 • -o nolog
7286 • -o vi
7288 Yash does not support the nolog option, which prevents function
7290 definitions from being added to command history.
7291
7293 The shift built-in removes some positional parameters or array values.
7294 Syntax
7296 • shift [-A array] [count]
7297 Description
7299 The shift built-in removes the first count positional parameters or
7300 array values, where count is specified by the operand.
7301 Options
7303 -A array, --array=array
7304 Remove first count values of array instead of positional
7305 parameters.
7306 Operands
7308 count
7309 The number of positional parameters or array values to be removed.
7310 It is an error if the actual number of positional parameters or
7312 array values is less than count. If omitted, the default value is
7313 one. If negative, the last -count positional parameters or array
7314 values are removed instead of the first ones.
7315 Exit status
7317 The exit status of the shift built-in is zero unless there is any
7318 error.
7319 Notes
7321 The shift built-in is a special built-in.
7322 The number of positional parameters can be obtained with the # special
7324 parameter. The number of array values can be obtained with ${array[#]}.
7325 The POSIX standard defines no options for the shift built-in; the
7327 built-in accepts no options in the POSIXly-correct mode.
7328 Negative operands are not allowed in the POSIXly-correct mode.
7330
7332 The suspend built-in suspends the shell.
7333 Syntax
7335 • suspend [-f]
7336 Description
7338 The suspend built-in sends a SIGSTOP signal to all processes in the
7339 process group to which the shell process belongs. The signal suspends
7340 the processes (including the shell). The suspended processes resume
7341 when they receive a SIGCONT signal.
7342 If the shell is interactive and its process group ID is equal to the
7344 process ID of the session leader, the shell prints a warning message
7345 and refuses to send a signal unless the -f (--force) option is
7346 specified. (In such a case, there is no other job-controlling shell
7347 that can send a SIGCONT signal to resume the suspended shell, so the
7348 shell could never be resumed.)
7349 Options
7351 -f, --force
7352 Suppress warnings that would prevent the shell from sending a
7353 signal.
7354 Exit status
7356 The exit status is zero if the signal was successfully sent and
7357 non-zero otherwise.
7358 Notes
7360 The suspend built-in is an elective built-in. It cannot be used in the
7361 POSIXly-correct mode because POSIX does not define its behavior.
7362
7364 The test built-in evaluates an expression.
7365 Syntax
7367 • test expression
7368 • [ expression ]
7370 The test built-in does not distinguish options and operands; all
7372 command line arguments are interpreted as expression. If the built-in
7373 is executed with the name [, expression must be followed by ].
7374 Description
7376 The test built-in evaluates expression as a conditional expression that
7377 is made up of operators and operands described below. The exit status
7378 is 0 if the condition is true and 1 otherwise.
7379 The unary operators below test a file. If the operand file is a
7381 symbolic link, the file referred to by the link is tested (except for
7382 the -h and -L operators).
7383 -b file
7385 file is a block special file
7386 -c file
7388 file is a character special file
7389 -d file
7391 file is a directory
7392 -e file
7394 file exists
7395 -f file
7397 file is a regular file
7398 -G file
7400 file's group ID is same as the shell’s effective group ID
7401 -g file
7403 file's set-group-ID flag is set
7404 -h file
7406 same as -L
7407 -k file
7409 file's sticky bit is set
7410 -L file
7412 file is a symbolic link
7413 -N file
7415 file has not been accessed since last modified
7416 -O file
7418 file's user ID is same as the shell’s effective user ID
7419 -p file
7421 file is a FIFO (named pipe)
7422 -r file
7424 file is readable
7425 -S file
7427 file is a socket
7428 -s file
7430 file is not empty
7431 -u file
7433 file's set-user-ID flag is set
7434 -w file
7436 file is writable
7437 -x file
7439 file is executable
7440 The unary operator below tests a file descriptor:
7442 -t fd
7444 fd is associated with a terminal
7445 The unary operators below test a string:
7447 -n string
7449 string is not empty
7450 -z string
7452 string is empty
7453 The unary operator below tests a shell option:
7455 -o ?option
7457 option is a valid shell option name
7458 -o option
7460 option is a valid shell option name that is enabled
7461 The binary operators below compare files. Non-existing files are
7463 considered older than any existing files.
7464 file1 -nt file2
7466 file1 is newer than file2
7467 file1 -ot file2
7469 file1 is older than file2
7470 file1 -ef file2
7472 file1 is a hard link to file2
7473 The binary operators below compare strings:
7475 string1 = string2, string1 == string2
7477 string1 is the same string as string2
7478 string1 != string2
7480 string1 is not the same string as string2
7481 The binary operators below compare strings according to the alphabetic
7483 order in the current locale:
7484 string1 === string2
7486 string1 is equal to string2
7487 string1 !== string2
7489 string1 is not equal to string2
7490 string1 < string2
7492 string1 is less than string2
7493 string1 <= string2
7495 string1 is less than or equal to string2
7496 string1 > string2
7498 string1 is greater than string2
7499 string1 >= string2
7501 string1 is greater than or equal to string2
7502 The binary operator below performs pattern matching:
7504 string =~ pattern
7506 extended regular expression pattern matches (part of) string
7507 The binary operators below compare integers:
7509 v1 -eq v2
7511 v1 is equal to v2
7512 v1 -ne v2
7514 v1 is not equal to v2
7515 v1 -gt v2
7517 v1 is greater than v2
7518 v1 -ge v2
7520 v1 is greater than or equal to v2
7521 v1 -lt v2
7523 v1 is less than v2
7524 v1 -le v2
7526 v1 is less than or equal to v2
7527 The binary operators below compare version numbers:
7529 v1 -veq v2
7531 v1 is equal to v2
7532 v1 -vne v2
7534 v1 is not equal to v2
7535 v1 -vgt v2
7537 v1 is greater than v2
7538 v1 -vge v2
7540 v1 is greater than or equal to v2
7541 v1 -vlt v2
7543 v1 is less than v2
7544 v1 -vle v2
7546 v1 is less than or equal to v2
7547 The operators below can be used to make complex expressions:
7549 ! expression
7551 negate (reverse) the result
7552 ( expression )
7554 change operator precedence
7555 expression1 -a expression2
7557 logical conjunction (and)
7558 expression1 -o expression2
7560 logical disjunction (or)
7561 If the expression is a single word without operators, the -n operator
7563 is assumed. An empty expression evaluates to false.
7564 Comparison of version numbers
7566 Comparison of version numbers is similar to comparison of strings
7567 in alphabetic order. The differences are:
7568 • Adjacent digits are treated as an integer. Integers are
7570 compared in mathematical order rather than alphabetic order.
7571 • Digits are considered larger than any non-digit characters.
7573 For example, version numbers 0.1.2-3 and 00.001.02-3 are equal and
7575 0.2.1 is smaller than 0.10.0.
7576 Exit status
7578 The exit status of the test built-in is 0 if expression is true and 1
7579 otherwise. The exit status is 2 if expression cannot be evaluated
7580 because of a syntax error or any other reasons.
7581 Notes
7583 Complex expressions may cause confusion and should be avoided. Use the
7584 shell’s compound commands. For example, [ 1 -eq 1 ] && [ -t = 1 ] && !
7585 [ foo ] is preferred over [ 1 -eq 1 -a -t = 1 -a ! foo ].
7586 The POSIX standard provides that the exit status should be larger than
7588 1 on error. The POSIX standard does not define the following operators:
7589 -G, -k, -N, -O, -nt, -ot, -ef, ==, ===, !==, <, <=, >, >=, =~, -veq,
7590 -vne, -vgt, -vge, -vlt, and -vle. POSIX neither specifies -o as a unary
7591 operator.
7592
7594 The times built-in prints CPU time usage.
7595 Syntax
7597 • times
7598 Description
7600 The times built-in prints the CPU times consumed by the shell process
7601 and its child processes to the standard output.
7602 The built-in prints two lines: the first line shows the CPU time of the
7604 shell process and the second one that of its child processes (not
7605 including those which have not terminated). Each line shows the CPU
7606 times consumed in the user and system mode.
7607 Exit status
7609 The exit status of the times built-in is zero unless there is any
7610 error.
7611 Notes
7613 The times built-in is a special built-in.
7614
7616 The trap built-in sets or prints signal handlers.
7617 Syntax
7619 • trap
7620 • trap action signal...
7622 • trap signal_number [signal...]
7624 • trap -p [signal...]
7626 Description
7628 The trap built-in sets or prints actions that are taken when the shell
7629 receives signals. (Those actions are called traps.)
7630 When executed with action and one or more signals, the built-in sets
7632 the traps for signals to action. If the shell receives one of the
7633 signals, the action will be taken.
7634 If the first operand is signal_number instead of action, the built-in
7636 resets the traps for signal_number and signals as if action was -.
7637 When executed with the -p (--print) option or with no operands, the
7639 built-in prints currently set traps to the standard output in a format
7640 that can be executed as commands that restore the current traps. If one
7641 or more signals are specified, only those signals are printed.
7642 Otherwise, all signals with non-default actions are printed. (In some
7643 situations, however, the built-in may print previous trap settings
7644 instead of the current. See notes below.)
7645 Options
7647 -p, --print
7648 Print current trap settings.
7649 Operands
7651 action
7652 An action that will be taken when signal is received.
7653 If action is a single hyphen (-), the action is reset to the
7655 default action that is defined by the operating system. If action
7656 is an empty string, the signal is ignored on receipt. Otherwise,
7657 action is treated as a command string: the string is parsed and
7658 executed as commands when the signal is received. (If a signal is
7659 received while a command is being executed, the action is taken
7660 just after the command finishes.)
7661 signal
7663 The number or name of a signal.
7664 If signal is number 0 or name EXIT, it is treated as a special
7666 imaginary signal that is always received when the shell exits. The
7667 action set for this signal is taken when the shell exits normally.
7668 signal_number
7670 This is like signal, but must be a number.
7671 Exit status
7673 The exit status of the trap built-in is zero unless there is any error.
7674 Notes
7676 The trap built-in is a special built-in.
7677 The POSIX standard defines no options for the trap built-in; the
7679 built-in accepts no options in the POSIXly-correct mode.
7680 The POSIX standard requires that signal names must be specified without
7682 the SIG-prefix, like INT and QUIT. As an extension, yash accepts
7683 SIG-prefixed names like SIGINT and SIGQUIT and treats signal names
7684 case-insensitively.
7685 Reusing output of the built-in
7687 Output of the trap built-in can be saved in a variable, which can
7688 be later executed by the eval built-in to restore the traps.
7689 saved_traps=$(trap)
7691 trap '...' INT
7692 eval "$saved_traps"
7693 There are some tricks behind the scenes to allow this idiom. You
7695 use a command substitution to save the output of the trap built-in
7696 in the variable. The command substitution is executed in a
7697 subshell. The subshell resets all traps (except ignored ones) at
7698 the beginning of itself. This seemingly would result in (almost)
7699 empty output from the built-in that would fail to restore the traps
7700 as expected.
7701 To avoid that pitfall, POSIX requires the shell to follow one of
7703 the two options below:
7704 • If a command substitution just contains a single trap built-in,
7706 traps should not be reset when the subshell is started to
7707 execute the built-in; or
7708 • A subshell always resets the traps but remembers the previous
7710 traps. If the trap built-in is executed in the subshell but no
7711 other trap built-in has been executed to modify traps in the
7712 subshell, then the built-in should print the remembered traps.
7713 Yash obeys the second.
7715
7717 The true built-in does nothing successfully.
7718 Syntax
7720 • true
7721 Description
7723 The true built-in does nothing. Any command line arguments are ignored.
7724 Exit status
7726 The exit status of the true built-in is zero.
7727 Notes
7729 The true built-in is a mandatory built-in.
7730 The true and colon built-ins have the same effect, but true is a
7732 mandatory built-in while colon is a special.
7733
7735 The type built-in identifies a command.
7736 Syntax
7738 • type [-abefkp] [command...]
7739 Description
7741 The type built-in is equivalent to the command built-in with the -V
7742 option.
7743 Notes
7745 The POSIX standard does not define the relation between the type and
7746 command built-ins. The standard does not define options for the type
7747 built-in.
7748 At least one command operand must be specified in the POSIXly-correct
7750 mode.
7751 The type built-in is a mandatory built-in.
7753
7755 The typeset built-in prints or sets variables or functions.
7756 Syntax
7758 • typeset [-gprxX] [variable[=value]...]
7759 • typeset -f[pr] [function...]
7761 Description
7763 If executed without the -f (--functions) option, the typeset built-in
7764 prints or sets variables to the standard output. Otherwise, it prints
7765 or sets functions.
7766 If executed with the -p (--print) option, the built-in prints the
7768 variables or functions specified by operands. Without the option, it
7769 sets variables or functions. If no operands are specified, it prints
7770 all existing variables or functions, regardless of whether the -p
7771 (--print) option is specified.
7772 Options
7774 -f, --functions
7775 Print or set functions rather than variables.
7776 -g, --global
7778 When setting a new variable, the variable will be a global variable
7779 if this option is specified. Without this option, the variable
7780 would be a local variable.
7781 When printing variables, all existing variables including global
7783 variables are printed if this option is specified. Without this
7784 option, only local variables are printed.
7785 -p, --print
7787 Print variables or functions in a form that can be parsed and
7788 executed as commands that will restore the currently set variables
7789 or functions.
7790 -r, --readonly
7792 When setting variables or functions, make them read-only.
7793 When printing variables or functions, print read-only variables or
7795 functions only.
7796 -x, --export
7798 When setting variables, mark them for export, so that they will be
7799 exported to external commands.
7800 When printing variables, print exported variables only.
7802 -X, --unexport
7804 When setting variables, cancel exportation of the variables.
7805 Operands
7807 variable (without value)
7808 The name of a variable that is to be set or printed.
7809 Without the -p (--print) option, the variable is defined (if not
7811 yet defined) but its value is not set nor changed. Variables that
7812 are defined without values are treated as unset in parameter
7813 expansion.
7814 variable=value
7816 The name of a variable and its new value.
7817 The value is assigned to the variable (regardless of the -p
7819 (--print) option).
7820 function
7822 The name of an existing function that is to be set or printed.
7823 Exit status
7825 The exit status of the typeset built-in is zero unless there is any
7826 error.
7827 Notes
7829 A global variable cannot be newly defined if a local variable has
7830 already been defined with the same name. The local variable will be set
7831 regardless of the -g (--global) option.
7832 The typeset built-in is an elective built-in. It cannot be used in the
7834 POSIXly-correct mode because POSIX does not define its behavior.
7835 The export and readonly built-ins are equivalent to the typeset
7837 built-in with the -gx and -gr options, respectively. The local built-in
7838 is equivalent to the typeset built-in except that the -f (--functions)
7839 and -g (--global) options cannot be used.
7840
7842 The ulimit built-in sets or prints a resource limit.
7843 Syntax
7845 • ulimit -a [-H|-S]
7846 • ulimit [-H|-S] [-efilnqrstuvx] [limit]
7848 Description
7850 The ulimit built-in sets or prints a resource limit.
7851 If executed with the -a (--all) option, the built-in prints the current
7853 limits for all resource types. Otherwise, it sets or prints the limit
7854 of a single resource type. The resource type can be specified by the
7855 options listed below. The resource limits will affect the current shell
7856 process and all commands invoked from the shell.
7857 Each resource type has two limit values: the hard and soft limit. You
7859 can change a soft limit freely as long as it does not exceed the hard
7860 limit. You can decrease a hard limit but cannot increase it without a
7861 proper permission.
7862 When the -H (--hard) or -S (--soft) option is specified, the built-in
7864 sets or prints the hard or soft limit, respectively. If neither of the
7865 options is specified, the built-in sets both the hard and soft limit or
7866 prints the soft limit.
7867 Options
7869 -H, --hard
7870 Set or print a hard limit.
7871 -S, --soft
7873 Set or print a soft limit.
7874 -a, --all
7876 Print all current limit settings.
7877 The following options specify the type of resources. If none of them is
7879 specified, -f is the default. The types of resources that can be set
7880 depend on the operating system.
7881 -c, --core
7883 Maximum size of core files created (in 512-byte blocks)
7884 -d, --data
7886 Maximum size of a process’s data segment (in kilobytes)
7887 -e, --nice
7889 Maximum scheduling priority (‘nice’)
7890 -f, --fsize
7892 Maximum size of files created by a process (in 512-byte blocks)
7893 -i, --sigpending
7895 Maximum number of pending signals
7896 -l, --memlock
7898 Maximum memory size that can be locked into RAM (in kilobytes)
7899 -m, --rss
7901 Maximum size of a process’s resident set (in kilobytes)
7902 -n, --nofile
7904 Maximum file descriptor + 1
7905 -q, --msgqueue
7907 Maximum size of POSIX message queues
7908 -r, --rtprio
7910 Maximum real-time scheduling priority
7911 -s, --stack
7913 Maximum size of a process’s stack (in kilobytes)
7914 -t, --cpu
7916 Maximum CPU time that can be used by a process (in seconds)
7917 -u, --nproc
7919 Maximum number of processes for a user
7920 -v, --as
7922 Maximum size of memory used by a process (in kilobytes)
7923 -x, --locks
7925 Maximum number of file locks
7926 Operands
7928 limit
7929 A limit to be set.
7930 The value must be a non-negative integer or one of hard, soft, and
7932 unlimited. If value is hard or soft, the new limit is set to the
7933 current hard or soft limit. If limit is not specified, the current
7934 limit is printed.
7935 Exit status
7937 The exit status of the ulimit built-in is zero unless there is any
7938 error.
7939 Notes
7941 The POSIX standard defines no options other than -f. It neither defines
7942 hard, soft, or unlimited for limit values.
7943 The ulimit built-in is a mandatory built-in.
7945
7947 The umask built-in sets or prints the file mode creation mask.
7948 Syntax
7950 • umask mask
7951 • umask [-S]
7953 Description
7955 If executed without the mask operand, the built-in prints the current
7956 file mode creation mask of the shell to the standard output in a form
7957 that can later be used as mask to restore the current mask.
7958 Otherwise, the built-in sets the file mode creation mask to mask.
7960 Options
7962 -S, --symbolic
7963 Print in the symbolic form instead of the octal integer form.
7964 Operands
7966 mask
7967 The new file mode creation mask either in the symbolic or octal
7968 integer form.
7969 Octal integer form
7971 In the octal integer form, the mask is specified as a non-negative
7972 octal integer that is the sum of the following permissions:
7973 0400
7975 read by owner
7976 0200
7978 write by owner
7979 0100
7981 execute/search by owner
7982 0040
7984 read by group
7985 0020
7987 write by group
7988 0010
7990 execute/search by group
7991 0004
7993 read by others
7994 0002
7996 write by others
7997 0001
7999 execute/search by others
8000 Symbolic form
8002 In the symbolic form, the mask is specified as a symbolic
8003 expression that denotes permissions that are not included in the
8004 mask.
8005 The entire expression is one or more clauses separated by comma. A
8007 clause is a sequence of whos followed by one or more actions.
8008 A who is one of:
8010 u
8012 owner
8013 g
8015 group
8016 o
8018 others
8019 a
8021 all of owner, group, and others
8022 An empty sequence of whos is equivalent to who a.
8024 An action is an operator followed by permission. An operator is one
8026 of:
8027 =
8029 set who's permission to permission
8030 +
8032 add permission to who's permission
8033 -
8035 remove permission from who's permission
8036 and permission is one of:
8038 r
8040 read
8041 w
8043 write
8044 x
8046 execute/search
8047 X
8049 execute/search (only if some user already has execute/search
8050 permission)
8051 s
8053 set-user-ID and set-group-ID
8054 u
8056 user’s current permissions
8057 g
8059 group’s current permissions
8060 o
8062 others' current permissions
8063 but more than one of r, w, x, X, and s can be specified after a
8065 single operand.
8066 For example, the command umask u=rwx,go+r-w
8068 • unmasks the user’s read, write, and execute/search permissions;
8070 • unmasks the group’s and others' read permission; and
8072 • masks the group’s and others' write permission.
8074 Exit status
8076 The exit status of the umask built-in is zero unless there is any
8077 error.
8078 Notes
8080 The umask built-in is a mandatory built-in.
8081 The POSIX standard does not require the default output format (used
8083 when the -S option is not specified) to be the octal integer form.
8084
8086 The unalias built-in undefines aliases.
8087 Syntax
8089 • unalias name...
8090 • unalias -a
8092 Description
8094 The unalias built-in removes the definition of the aliases specified by
8095 operands.
8096 Options
8098 -a, --all
8099 Undefine all aliases.
8100 Operands
8102 name
8103 The name of an alias to be undefined.
8104 Exit status
8106 The exit status of the unalias built-in is zero unless there is any
8107 error. It is an error to specify the name of a non-existing alias as
8108 name.
8109 Notes
8111 The unalias built-in is a mandatory built-in.
8112
8114 The unset built-in undefines variables or functions.
8115 Syntax
8117 • unset [-fv] [name...]
8118 Description
8120 The unset built-in removes the definition of the variables or functions
8121 specified by operands.
8122 It is not an error if any of the specified variables or functions do
8124 not exist; they are silently ignored.
8125 Options
8127 -f, --functions
8128 Undefine functions.
8129 -v, --variables
8131 Undefine variables.
8132 These options are mutually exclusive: only the last specified one is
8134 effective. If neither is specified, -v is assumed.
8135 Operands
8137 name
8138 The name of a variable or function to be undefined.
8139 Exit status
8141 The exit status of the unset built-in is zero unless there is any
8142 error.
8143 Notes
8145 The unset built-in is a special built-in.
8146 Although yash does not do so, the POSIX standard allows removing a
8148 function if neither of the -f and -v options is specified and the
8149 specified variable does not exist.
8150 At least one name operand must be specified in the POSIXly-correct
8152 mode.
8153
8155 The wait built-in waits for jobs to terminate.
8156 Syntax
8158 • wait [job...]
8159 Description
8161 The wait built-in waits for background jobs to terminate. If job
8162 control is enabled, stopped jobs are considered as terminated.
8163 The built-in can be used to wait for asynchronous commands if job
8165 control is disabled.
8166 If the shell receives a signal while the built-in is waiting and if a
8168 trap has been set for the signal, then the trap is executed and the
8169 built-in immediately finishes (without waiting for the jobs). If the
8170 shell receives a SIGINT signal when job control is enabled, the
8171 built-in aborts waiting.
8172 If the shell is interactive, job-controlling, and not in the
8174 POSIXly-correct mode, the job status is printed when the job is
8175 terminated or stopped.
8176 Operands
8178 job
8179 The job ID of the job or the process ID of a process in the job.
8180 If no jobs are specified, the built-in waits for all existing jobs.
8182 If the specified job does not exist, the job is considered to have
8184 terminated with the exit status of 127.
8185 Exit status
8187 If no jobs were specified and the built-in successfully waited for all
8188 the jobs, the exit status is zero. If one or more jobs were specified,
8189 the exit status is that of the last job.
8190 If the built-in was aborted by a signal, the exit status is an integer
8192 (> 128) that denotes the signal. If there was any other error, the exit
8193 status is between 1 and 126 (inclusive).
8194 Notes
8196 The wait built-in is a mandatory built-in.
8197 The process ID of the last process of a job can be obtained by the !
8199 special parameter. You can use the jobs built-in as well to obtain
8200 process IDs of job processes.
8201
8203 Yuki Watanabe <magicant@users.osdn.me>
8204 Author.
8205 2.55 2023-08-21 YASH(1)