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 PS1R
928 This variable specifies the auxiliary prompt string printed to
929 the right of the cursor when you input a command line to an
930 interactive shell. See Prompts for the format of the variable
931 value.
932 PS1S
934 This variable specifies the font style of command strings you
935 enter to an interactive shell. See Prompts for the format of
936 the variable value.
937 PS2
939 This variable is like the PS1 variable, but it is used for the
940 second and following lines of a command that is longer than one
941 line. See Prompts for the format of the variable value. The
942 value is initialized to > when the shell is started.
943 PS2R
945 This variable is like the PS1R variable, but it is used when
946 PS2 is used. See Prompts for the format of the variable value.
947 PS2S
949 This variable is like the PS1S variable, but it is used when
950 PS2 is used. See Prompts for the format of the variable value.
951 PS4
953 The value of this variable is printed before each command trace
954 output when the xtrace option is enabled. The value is subject
955 to parameter expansion, command substitution, arithmetic
956 expansion. You can also use backslash notations if the shell is
957 not in the POSIXly-correct mode. The value is initialized to +
958 when the shell is started.
959 PS4S
961 This variable is like the PS1S variable, but it is used when
962 PS4 is used. You can use this variable to modify font style of
963 command trace output.
964 PWD
966 The value of this variable is the pathname of the current
967 working directory. The value is set when the shell is started
968 and reset each time the working directory is changed by the cd
969 or other built-ins. This variable is exported by default.
970 RANDOM
972 You can use this variable to get random numbers. The value of
973 this variable is a uniformly distributed random integer between
974 0 and 32767 (inclusive). You will get a different number each
975 time the variable is expanded.
976 You can set the “seed” of random numbers by assigning a
978 non-negative integer to the variable.
979 If you remove this variable, it will no longer work as a random
981 number generator. If the shell was invoked in the
982 POSIXly-correct mode, this variable does not work as a random
983 number generator.
984 TERM
986 This variable specifies the type of the terminal in which the
987 shell is running. The value affects the behavior of
988 line-editing. This variable has to be exported to take effect.
989 YASH_AFTER_CD
991 The shell interprets and executes the value of this variable
992 after each time the shell’s working directory is changed by the
993 cd or other built-ins. This behavior is equivalent to executing
994 the command eval -i -- "${YASH_AFTER_CD-}" after the directory
995 was changed.
996 YASH_LOADPATH
998 This variable specifies directories the dot built-in searches
999 for a script file. More than one directory can be specified by
1000 separating them by colons like the PATH variable. When the
1001 shell is started, this variable is initialized to the pathname
1002 of the directory where common script files are installed.
1003 YASH_LE_TIMEOUT
1005 This variable specifies how long the shell should wait for a
1006 next possible input from the terminal when it encountered an
1007 ambiguous control sequence while line-editing. The value must
1008 be specified in milliseconds. If you do not define this
1009 variable, the default value of 100 milliseconds is assumed.
1010 YASH_PS1, YASH_PS1R, YASH_PS1S, YASH_PS2, YASH_PS2R, YASH_PS2S,
1012 YASH_PS4, YASH_PS4S
1013 When not in the POSIXly-correct mode, if any of these variables
1014 is defined, it takes precedence over the corresponding variable
1015 without the YASH_ prefix in the name (e.g. PS1). These
1016 variables are ignored in the POSIXly-correct mode. You should
1017 define them to include yash-specific notations in the prompt,
1018 so that unhandled notations do not mangle the prompt in the
1019 POSIXly-correct mode.
1020 YASH_VERSION
1022 The value is initialized to the version number of the shell
1023 when the shell is started.
1024 Arrays
1026 An array is a variable that contains zero or more strings. The
1027 string values of an array are identified by natural numbers (like
1028 positional parameters).
1029 You can assign values to an array by using a simple command as well
1031 as the array built-in. You can use the unset built-in to remove
1032 arrays.
1033 Arrays cannot be exported as arrays. When an array is exported, it
1035 is treated as a normal variable whose value is a concatenation of
1036 all the array values, each separated by a colon.
1037 Arrays are not supported in the POSIXly-correct mode.
1039
1041 Word expansion is substitution of part of a word with another
1042 particular string. There are seven types of word expansions:
1043 1. Tilde expansion
1045 2. Parameter expansion
1047 3. Command substitution
1049 4. Arithmetic expansion
1051 5. Brace expansion
1053 6. Field splitting
1055 7. Pathname expansion (globbing)
1057 These types of expansions are performed in the order specified above.
1059 Tilde expansion, parameter expansion, command substitution, and
1061 arithmetic expansion are called the four expansions.
1062 Tilde expansion
1064 In tilde expansion, parts of words that start with a tilde (~) are
1065 substituted with particular pathnames. The part of each word that gets
1066 substituted is from the beginning of the word, which is a tilde, up to
1067 (but not including) the first slash (/) in the word. If the word does
1068 not contain a slash, the whole word is substituted. If any character in
1069 the substituted part is quoted, tilde expansion is not performed on the
1070 word.
1071 The results of expansion are determined by the format of the
1073 substituted part:
1074 ~
1076 A single tilde is substituted with the value of the HOME variable.
1077 ~username
1079 A tilde followed by a user name is substituted with the pathname of
1080 the user’s home directory.
1081 ~+
1083 ~+ is substituted with the value of the PWD variable.
1084 ~-
1086 ~- is substituted with the value of the OLDPWD variable.
1087 ~+n, ~-n
1089 where n is a non-negative integer. This type of tilde expansion
1090 yields the pathname of a directory of which ~+n or ~-n is the index
1091 in the directory stack.
1092 When tilde expansion is performed on the value of a variable assignment
1094 that occurs during execution of a simple command, the value is
1095 considered as a colon-separated list of words and those words are each
1096 subject to tilde expansion. For example, the variable assignment
1097 VAR=~/a:~/b:~/c
1099 is equivalent to
1101 VAR=/home/foo/a:/home/foo/b:/home/foo/c
1103 if the value of HOME variable is /home/foo.
1105 The POSIX standard does not prescribe how the shell should behave when
1107 it encounters an error during tilde expansion (e.g., when the HOME
1108 variable is not defined). Yash silently ignores any errors during tilde
1109 expansion; the part of the word that would be substituted is left
1110 intact.
1111 In the POSIXly-correct mode, tilde expansion supports the formats of ~
1113 and ~username only.
1114 Parameter expansion
1116 Parameter expansion expands to the value of a parameter.
1117 The syntax of typical, simple parameter expansion is ${parameter},
1119 which expands to the value of the parameter whose name is parameter.
1120 You can omit the braces (e.g., $parameter) if
1121 · parameter is a special parameter,
1123 · parameter is a positional parameter whose index is a one-digit
1125 integer, or
1126 · parameter is a variable and the parameter expansion is not followed
1128 by a character that can be used as part of a variable name. For
1129 example, ${path}-name is equivalent to $path-name, but ${path}name
1130 and $pathname are different.
1131 If parameter is none of a special parameter, positional parameter, and
1133 variable, it is a syntax error. (Some shells other than yash may treat
1134 such a case as an expansion error.)
1135 If the unset option is disabled and the parameter is an undefined
1137 variable, it is an expansion error. If the unset option is enabled, an
1138 undefined variable expands to the empty string.
1139 More complex syntax of parameter expansion allows modifying the value
1141 of a parameter.
1142 Parameter expansion
1144 ${ prefix parameter index modifier }
1145 The spaces in the syntax definition above are for readability only and
1147 must be omitted. You can omit prefix, index, and/or modifier.
1148 Prefix
1150 The prefix, if any, must be a hash sign (#). If a parameter
1151 expansion has the prefix, the result of expansion is the number of
1152 characters in the value this expansion would be expanded to without
1153 the prefix.
1154 Parameter name
1156 The parameter name (parameter) must be either
1157 · a name of a special parameter, positional parameter, or
1159 variable; or
1160 · another parameter expansion, command substitution, or
1162 arithmetic expansion.
1163 The parameter expansion is expanded to the value of the parameter.
1165 If parameter is an array variable, the values of the array are
1166 field-split like the @ special parameter unless the index [*] is
1167 specified.
1168 If parameter is another expansion, it is called a nested expansion.
1170 Nested expansion cannot be used in the POSIXly-correct mode. The
1171 braces ({ }) of a nested parameter expansion cannot be omitted.
1172 Index.sp An index allows extracting part of the parameter value (or
1173 some of array values).
1174 Index
1176 [word1]
1177 [word1,word2]
1179 where word1 and word2 are parsed in the same manner as normal tokens
1181 except that they are always delimited by , or ] and can contain
1182 whitespace characters.
1183 If there is an index in a parameter expansion, it is interpreted as
1185 follows:
1186 1. Words word1 and word2 are subjected to parameter expansion, command
1188 substitution, and arithmetic expansion.
1189 2. If there is no word2 and if word1 expands to one of *, @, and #,
1191 then that is the interpretation of index and the next step is not
1192 taken.
1193 3. The results of the previous steps (the expanded word1 and word2)
1195 are interpreted and evaluated as an arithmetic expression in the
1196 same manner as in arithmetic expansion. The resulting integers are
1197 the interpretation of index. If the results are not integers, it is
1198 an expansion error. If there is no word2, it is assumed that word2
1199 is equal to word1.
1200 If parameter is an array variable, the index specifies the part of the
1202 array. If parameter is either the * or @ special parameter, the index
1203 specifies the index range of positional parameters. In other cases, the
1204 index specifies the index range of a substring of the parameter value
1205 that is being expanded. In all cases, the specified range of the array
1206 values, positional parameters, or parameter value remains in the
1207 results of the expansion and other values are dropped.
1208 If the interpretation of index is one or two integers, the following
1210 rules apply:
1211 · If the interpreted index value is negative, it wraps around. For
1213 example, the index value of -1 corresponds to the last
1214 value/character.
1215 · It is not an error when the index value is out of range. Existing
1217 values/characters within the range are just selected.
1218 · If the interpretation of either word1 or word2 is 0, the range is
1220 assumed empty and the expansion results in nothing.
1221 If the interpretation of index is one of *, @, and #, it is treated as
1223 follows:
1224 *
1226 If parameter is an array, all the array values are field-split or
1227 concatenated in the same manner as the * special parameter. If
1228 parameter is the * or @ special parameter, the positional
1229 parameters are likewise field-split or concatenated. In other
1230 cases, the interpretation of index is treated as if the
1231 interpretation is the two integers 1 and -1.
1232 @
1234 The interpretation of index is treated as if the interpretation is
1235 the two integers 1 and -1.
1236 #
1238 The interpretation of the # index is special in that it does not
1239 simply specify a range. Instead, the expanded values are
1240 substituted with the count.
1241 If parameter is an array, the result of this parameter expansion
1243 will be the number of values in the array being expanded. If
1244 parameter is the * or @ special parameter, the result will be the
1245 number of current positional parameters. Otherwise, the result will
1246 be the number of characters in the value that is being expanded.
1247 If a parameter expansion does not contain an index, it is assumed to be
1249 [@]. In the POSIXly-correct mode, index cannot be specified.
1250 Example 1. Expansion of a normal variable
1252 The following commands will print the string ABC:
1254 var='123ABC789'
1256 echo "${var[4,6]}"
1257 Example 2. Expansion of positional parameters
1259 The following commands will print the string 2 3 4:
1261 set 1 2 3 4 5
1263 echo "${*[2,-2]}"
1264 Example 3. Expansion of an array
1266 The following commands will print the string 2 3 4:
1268 array=(1 2 3 4 5)
1270 echo "${array[2,-2]}"
1271 Modifier
1273 You can modify the value to be expanded by using modifiers:
1274 -word
1276 If the parameter name (parameter) is an undefined variable, the
1277 parameter expansion is expanded to word. It is not treated as
1278 an error if the unset option is disabled.
1279 +word
1281 If the parameter name (parameter) is an existing variable, the
1282 parameter expansion is expanded to word. It is not treated as
1283 an error if the unset option is disabled.
1284 =word
1286 If the parameter name (parameter) is an undefined variable,
1287 word is assigned to the variable and the parameter expansion is
1288 expanded to word. It is not treated as an error if the unset
1289 option is disabled.
1290 ?word
1292 If the parameter name (parameter) is an undefined variable,
1293 word is printed as an error message to the standard error. If
1294 word is empty, the default error message is printed instead.
1295 :-word, :+word, :=word, :?word
1297 These are similar to the four types of modifiers above. The
1298 only difference is that, if parameter exists and has an empty
1299 value, it is also treated as an undefined variable.
1300 #word
1302 The shell performs pattern matching against the value that is
1303 being expanded, using word as a pattern. If word matches the
1304 beginning of the value, the matching part is removed from the
1305 value and the other part remains as expansion results. The
1306 shortest matching is used if more than one matching is
1307 possible.
1308 ##word
1310 This is similar to #word above. The only difference is that the
1311 longest matching is used if more than one matching is possible.
1312 %word
1314 This is similar to #word above. The only difference is that
1315 matching is tried at the end of the value rather than at the
1316 beginning: if word matches the end of the value, the matching
1317 part is removed from the value and the other part remains as
1318 expansion results.
1319 %%word
1321 This is similar to %word above. The only difference is that the
1322 longest matching is used if more than one matching is possible.
1323 /word1/word2
1325 The shell performs pattern matching against the value that is
1326 being expanded, using word1 as a pattern. If word1 matches any
1327 part of the value, the matching part is replaced with word2 and
1328 the whole value after the replacement remains as expansion
1329 results. If word1 matches more than one part of the value, only
1330 the first part is replaced. The shortest matching is replaced
1331 if more than one matching is possible for the same starting
1332 point in the value.
1333 This modifier cannot be used in the POSIXly-correct mode.
1335 /#word1/word2
1337 This is similar to /word1/word2 above. The only difference is
1338 that word1 matches only at the beginning of the value being
1339 expanded.
1340 /%word1/word2
1342 This is similar to /word1/word2 above. The only difference is
1343 that word1 matches only at the end of the value being expanded.
1344 //word1/word2
1346 This is similar to /word1/word2 above. The only difference is
1347 that all matched parts are replaced if word1 matches more than
1348 one part of the value.
1349 :/word1/word2
1351 This is similar to /word1/word2 above. The only difference is
1352 that the value is replaced only when word1 matches the whole
1353 value.
1354 In all types of modifiers above, words are subjected to the four
1356 expansions when (and only when) they are used.
1357 If parameter is an array variable or the @ or * special parameter,
1359 modifiers affect each value of the array or all positional
1360 parameters.
1361 Command substitution
1363 Command substitution expands to output of commands specified.
1364 Command substitution
1366 $(commands)
1367 `commands`
1369 When command substitution is evaluated, commands are executed by a
1371 subshell with output pipelined to the shell. When the commands
1372 finished, command substitution is substituted with the output of the
1373 commands. Any trailing newline characters in the output are ignored.
1374 When command substitution of the form $(commands) is parsed, the
1376 commands are parsed carefully so that complex commands such as nested
1377 command substitution are parsed correctly. If commands start with (,
1378 you should put a space before commands so that the whole command
1379 substitution is not confused with arithmetic expansion. If the shell is
1380 in the POSIXly-correctly mode, the commands are parsed each time the
1381 command substitution is expanded; otherwise, commands are parsed only
1382 when the command substitution is parsed.
1383 If command substitution is of the form `commands`, the commands are not
1385 parsed when the command substitution is parsed; the commands are parsed
1386 each time the command substitution is expanded. The end of commands is
1387 detected by the first backquote character (`) after the beginning of
1388 commands that is not quoted by a backslash. Backquotes that are part of
1389 commands (typically used for nested command substitution) must be
1390 quoted by backslashes. In commands, backslashes are treated as quotes
1391 only when preceding a dollar ($), backquote, newline, or another
1392 backslash. Additionally, if the command substitution occurs inside
1393 double quotes, double quotes in commands must be quoted with a
1394 backslash. Those backslashes are removed before commands are parsed.
1395 Arithmetic expansion
1397 Arithmetic expansion evaluates an arithmetic expression and expands to
1398 the value of the expression.
1399 Arithmetic expansion
1401 $((expression))
1402 When arithmetic expansion is expanded, the expression is subject to
1404 parameter expansion, command substitution, and (nested) arithmetic
1405 expansion. The expression is parsed in (almost) same manner as an
1406 expression of the C programming language.
1407 Yash allows an expression to be either an integer (of the long type in
1409 C) or a floating-point number (of the double type in C). An operation
1410 on integers yields an integer and an operation involving a
1411 floating-point number yields a floating-point number. In the
1412 POSIXly-correct mode, you can use integers only.
1413 The following operators are available (in the order of precedence):
1415 1. ( )
1417 2. ++ -- (postfix operators)
1419 3. ++ -- + - ~ ! (prefix operators)
1421 4. * / %
1423 5. + - (binary operators)
1425 6. << >>
1427 7. < <= > >=
1429 8. == !=
1431 9. &
1433 10. ^
1435 11. |
1437 12. &&
1439 13. ||
1441 14. ? :
1443 15. = *= /= %= += -= <<= >>= &= ^= |=
1445 The ++ and -- operators cannot be used in the POSIXly-correct mode.
1447 An atomic expression can be one of an integer literal, a floating-point
1449 number literal, and a variable. Literals are parsed in the same manner
1450 as in C. An octal integer literal starts with 0, and hexadecimal with
1451 0x. A floating-point number literal may have an exponent (i.e.
1452 1.23e+6). A variable with a non-numeric value will result in an error
1453 when parsed as a number. An unset variable is treated as a value of
1454 zero if the unset option is enabled.
1455 In the POSIXly-correct mode, variables are always parsed as numbers.
1457 Otherwise, variables are parsed only when they are used as numbers in
1458 computation. Unparsed variables are left intact.
1459 set +o posixly-correct
1461 foo=bar
1462 echo $((0 ? foo : foo)) # prints "bar"
1463 echo $((foo + 0)) # error
1464 Brace expansion
1466 Brace expansion expands to several split words with preceding and
1467 succeeding portions duplicated to each split words. Brace expansion is
1468 expanded only when the brace-expand option is enabled.
1469 Comma-separated brace expansion
1471 {word1,word2,...,wordn}
1472 Range brace expansion
1474 {start..end}
1475 {start..end..delta}
1477 Comma-separated brace expansion is expanded to each comma-separated
1479 word. For example, a{1,2,3}b is expanded to the three words a1b, a2b,
1480 and a3b.
1481 Range brace expansion is expanded to integers in the range defined by
1483 start and end. The difference between each integer can be defined by
1484 delta. If start is larger than end, the results will be in descending
1485 order. When ..delta is omitted, it defaults to 1 or -1. For example,
1486 a{1..3}b is expanded to the three words a1b, a2b, and a3b; and
1487 a{1..7..2}b to the four words a1b, a3b, a5b, and a7b.
1488 Multiple brace expansions can be used in one word. Brace expansions can
1490 also be nested. You can quote braces and/or commas to prevent them from
1491 being treated as brace expansion.
1492 Any errors in brace expansion are silently ignored.
1494 Field splitting
1496 In field splitting, words are split at predefined separators.
1497 Field splitting can occur only within parts of words that resulted from
1499 parameter expansion, command substitution, and arithmetic expansion
1500 that are not between double-quotation marks. Expansion results of the @
1501 special parameter are exceptionally split even between double-quotation
1502 marks.
1503 Separators used in field splitting are defined by the value of the IFS
1505 variable. If the variable does not exist, the value is assumed to be
1506 the three characters of space, tab, and newline.
1507 Characters included in the value of the IFS variable are called IFS
1509 characters. IFS characters that are any of space, tab, and newline are
1510 called IFS whitespace and other IFS characters are called IFS
1511 non-whitespace.
1512 Field splitting is performed as follows:
1514 1. The shell searches words for split points. A split point is one or
1516 more adjacent IFS characters within the word portions where field
1517 splitting can occur. The following steps are taken for each split
1518 point found.
1519 2. If the split point includes one or more IFS non-whitespaces, all
1521 the IFS whitespaces in the split point are ignored and the word is
1522 split at each IFS non-whitespace in the split point.
1523 3. If the split point includes no IFS non-whitespaces, the word is
1525 split at the split point unless it is at the beginning or end of
1526 the word.
1527 4. The split points are removed from the results.
1529 Finally, the last word is removed from the results if:
1531 · the empty-last-field option is not enabled;
1533 · the result is more than one word; and
1535 · the last word is empty.
1537 Note
1539 Words are not split at all when the value of the IFS variable is
1540 empty.
1541 Pathname expansion
1543 Pathname expansion performs pattern matching and expands to pathnames
1544 matched by the pattern.
1545 A word subjected to pathname expansion is treated as a pattern. If one
1547 or more pathnames are found that are matched by the pattern, the
1548 pathnames become the results of the pathname expansion.
1549 Pathname expansion is not performed when the glob option is disabled.
1551 The shell searches readable directories for matching pathnames.
1553 Unreadable directories are silently ignored.
1554 The following options affect the behavior of pathname expansion:
1556 null-glob
1558 This option affects the result of pathname expansion when no
1559 matching pathnames are found. If enabled, the result is no word. If
1560 disabled, the result is the original pattern word.
1561 case-glob
1563 This option specifies case-sensitivity in matching. If enabled,
1564 pattern matching is done case-sensitively.
1565 dot-glob
1567 This option affects matching of filenames that start with a period
1568 (.). If disabled, a period at the beginning of a filename does not
1569 match wildcard patterns (? and *) or bracket expressions. If
1570 enabled, there is no such special treatment of periods.
1571 mark-dirs
1573 If enabled, each resulting pathname that is a directory name is
1574 suffixed by a slash (/).
1575 extended-glob
1577 This option enables the extension. (See below)
1578 Any errors in pathname expansion are silently ignored. If the word is
1580 an invalid pattern, it just becomes the result. The results depend on
1581 the null-glob option when no matching pathnames are found.
1582 Pattern matching is done for each filename (or pathname component) of
1584 pathnames. The shell skips matching for literal patterns that contain
1585 no wildcards or bracket expressions. As a result, the patterns /*/foo
1586 and /*/fo[o] may yield different expansion results when the case-glob
1587 option is disabled; for example, the pattern /*/fo[o] matches the
1588 pathname /bar/FOO but the pattern /*/foo does not because matching is
1589 skipped for foo.
1590 Extension in pathname expansion
1592 The following patterns can be used when the extended-glob option is
1593 enabled.
1594 **
1596 The directory is searched recursively and the pattern matches
1597 any number of directory filenames (each separated by a slash).
1598 Any directory whose name begins with a period is excluded from
1599 search. For example, the pattern dir/**/file can match the
1600 pathnames dir/file, dir/foo/file, dir/a/b/c/file, etc.
1601 This pattern is not effective when appearing at the end of the
1603 whole pattern (i.e. foo/bar/**).
1604 .**
1606 This pattern is like **, but all directories are searched
1607 including ones with a name starting with a period.
1608 ***
1610 This pattern is like **, but if a symbolic link to a directory
1611 is found during recursive search, the directory is searched
1612 recursively as well.
1613 .***
1615 This pattern is like ***, but all directories are searched
1616 including ones with a name starting with a period.
1617
1619 Pattern matching notation is a syntax of patterns that represent
1620 particular sets of strings. When a string is included in the set of
1621 strings a pattern represents, the pattern is said to match the string.
1622 Whether a pattern matches a string or not is defined as follows.
1623 Normal characters
1625 A character that is not quoted or any of special characters defined
1626 below is a normal character, which matches the character itself.
1627 For example, the pattern abc matches the string abc, and not any other
1629 strings.
1630 Single-character wildcard
1632 The character ? matches any single character.
1633 For example, the pattern a?c matches any three-character strings that
1635 starts with a and ends with c, such as aac, abc, and a;c.
1636 Multi-character wildcard
1638 The character * matches any strings (of any length, including the empty
1639 string).
1640 For example, the pattern a*c matches any string that starts with a and
1642 ends with c, such as ac, abc, and a;xyz;c.
1643 Bracket expression
1645 A pattern that is enclosed by brackets ([ and ]) is a bracket
1646 expression. A bracket expression must have at least one character
1647 between the brackets. The characters between the brackets are
1648 interpreted as a bracket expression pattern, which is a below-defined
1649 special notation for bracket expression. A bracket expression pattern
1650 represents a set of characters. The bracket expression matches any one
1651 of the characters in the set the bracket expression pattern represents.
1652 If the opening bracket ([) is followed by an exclamation mark (!), the
1654 exclamation is not treated as part of the bracket expression pattern
1655 and the whole bracket expression instead matches a character that is
1656 not included in the set the bracket expression pattern represents. If
1657 the opening bracket is followed by a caret (^), it is treated like an
1658 exclamation mark as above (but shells other than yash may treat the
1659 caret differently).
1660 If the opening bracket (or the following exclamation or caret, if any)
1662 is followed by a closing bracket (]), it is treated as part of the
1663 bracket expression pattern rather than the end of the bracket
1664 expression. You cannot quote characters in the bracket expression
1665 pattern because quotation is treated before bracket expression.
1666 An opening bracket in a pattern is treated as a normal character if it
1668 is not the beginning of a valid bracket expression.
1669 Normal characters (in bracket expression pattern)
1671 A character that is not any of special characters defined below is a
1672 normal character, which represents the character itself.
1673 For example, the bracket expression pattern abc represents the set of
1675 the three characters a, b, and c. The bracket expression [abc]
1676 therefore matches any of the three characters.
1677 Range expressions
1679 A hyphen preceded and followed by a character (or collating symbol) is
1680 a range expression, which represents the set of the two characters and
1681 all characters between the two in the collation order. A collation
1682 order is an order of characters that is defined in the locale data.
1683 If a hyphen is followed by a closing bracket (]), the bracket is
1685 treated as the end of the bracket expression and the hyphen as a normal
1686 character.
1687 For example, the range expression 3-5 represents the set of the three
1689 characters 3, 4, and 5. The bracket expression [3-5-] therefore matches
1690 one of the four characters 3, 4, 5, and -.
1691 Collating symbols
1693 A collating symbol allows more than one character to be treated as a
1694 single character in matching. A collating symbol is made up of one or
1695 more characters enclosed by the special brackets [. and .].
1696 One or more characters that are treated as a single character in
1698 matching are called a collating element. Precisely, a bracket
1699 expression pattern represents a set of collating elements and a bracket
1700 expression matches a collating element rather than a character, but we
1701 do not differentiate them for brevity here.
1702 For example, the character combination “ch” was treated as a single
1704 character in the traditional Spanish language. If this character
1705 combination is registered as a collating element in the locale data,
1706 the bracket expression [[.ch.]df] matches one of ch, d, and f.
1707 Equivalence classes
1709 An equivalence class represents a set of characters that are considered
1710 equivalent. A equivalence class is made up of a character (or more
1711 precisely, a collating element) enclosed by the special brackets [= and
1712 =].
1713 An equivalence class represents the set of characters that consists of
1715 the character enclosed by the brackets and the characters that are in
1716 the same primary equivalence class as the enclosed character. The shell
1717 consults the locale data for the definition of equivalence classes in
1718 the current locale.
1719 For example, if the six characters a, à, á, â, ã, ä are defined to be
1721 in the same primary equivalence class, the bracket expressions [[=a=]],
1722 [[=à=]], and [[=á=]] match one of the six.
1723 Character classes
1725 A character class represents a predefined set of characters. A
1726 character class is made up of a class name enclosed by the special
1727 brackets [: and :]. The shell consults the locale data for which class
1728 a character belongs to.
1729 The following character classes can be used in all locales:
1731 [:lower:]
1733 set of lowercase letters
1734 [:upper:]
1736 set of uppercase letters
1737 [:alpha:]
1739 set of letters, including the [:lower:] and [:upper:] classes.
1740 [:digit:]
1742 set of decimal digits
1743 [:xdigit:]
1745 set of hexadecimal digits
1746 [:alnum:]
1748 set of letters and digits, including the [:alpha:] and [:digit:]
1749 classes.
1750 [:blank:]
1752 set of blank characters, not including the newline character
1753 [:space:]
1755 set of space characters, including the newline character
1756 [:punct:]
1758 set of punctuations
1759 [:print:]
1761 set of printable characters
1762 [:cntrl:]
1764 set of control characters
1765 For example, the bracket expression [[:lower:][:upper:]] matches a
1767 lower or upper case character. In addition to the classes listed above,
1768 other classes may be used depending on the definition of the current
1769 locale.
1770
1772 Redirection is a feature you can use to modify file descriptors of
1773 commands. By using redirection, you can execute commands with their
1774 standard input/output connected with files or devices other than the
1775 terminal.
1776 You can do redirection by adding redirection operators to a command
1778 (simple command or compound command) In a simple command, redirection
1779 operators may appear anywhere in the command as long as operator tokens
1780 are separated from other tokens. In a compound command, redirection
1781 operators must appear at the end of the command.
1782 Redirection operators are processed before the command body is
1784 executed. More than one redirection operator in a command are processed
1785 in the order of appearance. Redirection operators affect only the
1786 command in which they appear, except when they appear in an exec
1787 built-in without command operands. That is, file descriptors modified
1788 by redirection are restored after the command has finished.
1789 A redirection operator starts with < or >. Redirection operators
1791 starting with < affects the standard input (file descriptor 0) by
1792 default. Redirection operators starting with > affects the standard
1793 output (file descriptor 1) by default. To affect another file
1794 descriptor, you can prefix a redirection operator with a non-negative
1795 integer; the operator will affect the file descriptor specified by the
1796 integer. The integer must immediately precede the < or > without any
1797 whitespaces in between. The integer must not be quoted, either.
1798 Redirection to files
1800 The most common type of redirection is redirection to files.
1801 Redirection of input
1803 < token
1804 Redirection of output
1806 > token
1807 >| token
1809 >> token
1811 Redirection of input and output
1813 <> token
1814 The token is subject to the four expansions. It is also subject to
1816 pathname expansion if the shell is interactive. The expansion result is
1817 treated as the pathname of the file to which redirection is performed.
1818 If the pathname expansion does not result in a single pathname, it is
1819 an error.
1820 In redirection of input, the standard input is replaced with a file
1822 descriptor which is open for read-only access to the target file. If
1823 the target file cannot be opened for read-only access, it is an error.
1824 In redirection of output, the standard output is replaced with a file
1826 descriptor which is open for write-only access to the target file. If
1827 the target file cannot be opened for write-only access, it is an error.
1828 If the target file does not exist, a new empty file is created and
1829 opened. If the target file already exists, the file is opened as
1830 follows:
1831 · For the >| operator, the file is emptied when opened if it is a
1833 regular file.
1834 · For the > operator, the behavior is the same as the >| operator if
1836 the clobber option is enabled. If the option is disabled and the
1837 file is a regular file, it is treated as an error.
1838 · For the >> operator, the file is opened for appending; any output
1840 to the file descriptor is appended to the end of the file.
1841 In redirection of input and output, the standard input is replaced with
1843 a file descriptor which is open for read-and-write access to the target
1844 file. If the file does not exist, a new empty file is created and
1845 opened.
1846 Socket redirection
1848 If the pathname of the target file is of the form
1849 /dev/tcp/host/port or /dev/udp/host/port and the file cannot be
1850 opened in the usual manner, a new socket is opened for
1851 communication with the port of the host. The redirection replaces
1852 the standard input or output with the file descriptor to the
1853 socket.
1854 A stream socket is opened for the form /dev/tcp/host/port and a
1856 datagram socket for the form /dev/udp/host/port. The protocol
1857 actually used for communication is determined by the socket library
1858 the shell uses. Typically, stream sockets use TCP and datagram
1859 sockets UDP.
1860 In socket redirection, the file descriptor is both readable and
1862 writable regardless of the type of the redirection operator used.
1863 Socket redirection is yash’s extension that is not defined in
1865 POSIX. Bash as well has socket redirection as extension.
1866 Duplication of file descriptors
1868 Redirection allows duplicating or closing existing file descriptors.
1869 Duplication of file descriptor
1871 <& token
1872 >& token
1874 The token is subject to expansion as in redirection to files, but it is
1876 treated as a file descriptor rather than a pathname. Thus the expanded
1877 token must be a non-negative integer.
1878 The <& and >& operators duplicate the file descriptor specified by
1880 token to the standard input and output, respectively. (The operators
1881 can be prefixed with a non-negative integer so that the file descriptor
1882 is duplicated to a file descriptor other than the standard input or
1883 output.)
1884 If the expanded token is a single hyphen rather than a non-negative
1886 integer, the file descriptor is closed rather than duplicated. By
1887 default, the <& and >& operators close the standard input and output,
1888 respectively, but the operators can be prefixed with a non-negative
1889 integer so that another file descriptor is closed.
1890 In the POSIXly-correct mode, a file descriptor must be readable when
1892 duplicated by the <& operator and writable when duplicated by the >&
1893 operator.
1894 Here documents and here strings
1896 Here document and here string allow redirection to file descriptors
1897 that reads strings directly specified in shell commands.
1898 Here document
1900 << token
1901 <<- token
1903 Here string
1905 <<< token
1906 In a here document or here string, the standard input is replaced with
1908 a readable file descriptor. When the command reads from the file
1909 descriptor, it will read the contents of the here document/string,
1910 which is defined below.
1911 When a here document operator (<< or <<-) appears in a command, the
1913 shell reads the contents of the here document starting from the next
1914 line. The contents of here documents are not parsed nor executed as
1915 commands. The token after the operand specifies a delimiter that
1916 indicates the end of the contents. (The token is not subject to any
1917 expansion, but quotation is processed.) The contents of the here
1918 document is terminated just before the first line containing the token
1919 only. When using the <<- operator, all tab characters at the beginning
1920 of each line in the here document contents are removed and the
1921 delimiter token may be preceded by tab characters.
1922 If there are more than one here document operator on one line, the
1924 contents of the here documents are parsed in order: The contents of the
1925 first here document starts from the next line and ends before the first
1926 line containing the token that followed the first operator. Just after
1927 that line, the contents of the second here document starts, and so on.
1928 The contents of here documents are treated literally: whitespaces,
1930 tabs, etc. remain as is. The exception is that, when the token is not
1931 quoted at all:
1932 · the contents are subject to parameter expansion, command
1934 substitution, arithmetic expansion.
1935 · a backslash in the contents is treated as quotation if and only if
1937 it precedes $, `, ", or another backslash.
1938 · a backslash followed by a newline is treated as line continuation.
1940 In here string, the token after the operator is subject to expansion as
1942 in redirection to files. The expansion result becomes the contents of
1943 the here string. A newline character is automatically appended to the
1944 end of here string contents.
1945 Here string is yash’s extension that is not defined in POSIX. Other
1947 shells like bash, ksh, and zsh have the same feature.
1948 Pipeline redirection
1950 Pipeline redirection allows opening pipelines that can be used for
1951 arbitrary purposes.
1952 Pipeline redirection
1954 >>| token
1955 The token is subject to expansion as in redirection to files, but it is
1957 treated as a file descriptor rather than a pathname. Thus the expanded
1958 token must be a non-negative integer.
1959 Pipeline redirection opens a new pipeline. The standard output (or the
1961 file descriptor specified before the operator, if any) is replaced with
1962 the file descriptor open for writing to the pipeline. The file
1963 descriptor specified by token is replaced with the file descriptor open
1964 for reading from the pipeline.
1965 Pipeline redirection is yash’s extension that is not defined in POSIX.
1967 Process redirection
1969 Process redirection creates a pipeline connected to another command.
1970 Process redirection
1972 <(command...)
1973 >(command...)
1975 In process redirection, the command specified is executed in a
1977 subshell. If the process redirection is of the form <(command...), the
1978 standard output of command is connected with a pipeline to the standard
1979 input of the command the redirection is associated with. If the process
1980 redirection is of the form >(command...), the standard input of command
1981 is connected with a pipeline to the standard output of the command the
1982 redirection is associated with.
1983 Process redirection is yash’s extension that is not defined in POSIX.
1985 Bash and zsh have a feature called process substitution, which uses the
1986 same syntax as yash’s process redirection, but incompatibly differs in
1987 behavior.
1988
1990 This section describes how commands are executed.
1991 Execution of simple commands
1993 A simple command is executed as follows:
1994 1. All tokens in the simple command are expanded except for assignment
1996 and redirection tokens. If an error occurs during expansion, the
1997 execution of the simple command is aborted with a non-zero exit
1998 status.
1999 In the following steps, the first word of the expansion results is
2001 referred to as command name, and the other words as command
2002 arguments. If there is only one word of the expansion results,
2003 there are no command argument words. If there are none of the
2004 expansion results, there is no command name either.
2005 2. Redirection specified in the command, if any, is processed. The
2007 word token after each redirection operator is expanded. If an error
2008 occurs during processing redirection (including when expanding the
2009 word token), the execution of this simple command is aborted with a
2010 non-zero exit status.
2011 3. Assignments specified in the command, if any, are processed. For
2013 each assignment token, the value is expanded and assigned to the
2014 specified variable. If an error occurs during assignments
2015 (including when expanding the values to be assigned), the execution
2016 of this simple command is aborted with a non-zero exit status.
2017 · If there is no command name or the name denotes a special
2019 built-in, the assignments are permanent: the assigned values
2020 remain after the command has finished (until the variable is
2021 reassigned).
2022 · Otherwise, the assignments are temporary: the assigned values
2024 only last during the execution of this simple command.
2025 The assigned variables are automatically exported when the command
2027 name is specified or the all-export option is enabled.
2028 Note
2030 In other shells, assignments may behave differently: For
2031 special built-ins and functions, assigned variables may not be
2032 exported. For functions, assigned variables may be persistent,
2033 that is, may remain even after the execution of the simple
2034 command.
2035 4. If there is no command name, the command execution ends with the
2037 exit status of zero (unless there are any command substitutions in
2038 the command, in which case the exit status of the simple command is
2039 that of the last executed command substitution).
2040 5. A command to be executed is determined using the command search
2042 algorithm and the command is executed.
2043 · If the command is an external command, the command is executed
2045 by creating a new subshell and calling the “exec” system call
2046 in the subshell. The command name and arguments are passed to
2047 the executed command. Exported variables are passed to the
2048 executed command as environment variables.
2049 · If the command is a built-in, the built-in is executed with the
2051 command arguments passed to the built-in.
2052 · If the command is a function, the contents of the function are
2054 executed with the command arguments as function arguments.
2055 If the command was executed, the exit status of this simple command
2057 is that of the executed command. If the algorithm failed to
2058 determine a command, no command is executed and the exit status is
2059 127. If the shell failed to execute the determined command, the
2060 exit status is 126. If the executed command was killed by a signal,
2061 the exit status is the signal number plus 384.
2062 Note
2064 In shells other than yash, the exit status may be different
2065 when the command was killed by a signal, because the POSIX
2066 standard only requires that the exit status be "greater than
2067 128."
2068 If the shell is not in the POSIXly-correct mode and the algorithm
2069 failed to determine a command, the command eval -i --
2070 "${COMMAND_NOT_FOUND_HANDLER-}" is evaluated. During the command
2071 execution, positional parameters are temporarily set to the command
2072 name and arguments that resulted in the first step. Any local
2073 variables defined during the execution are removed when the
2074 execution is finished. The HANDLED local variable is automatically
2075 defined with the initial value being the empty string. If the
2076 HANDLED variable has a non-empty value when the execution of the
2077 command string is finished, the shell pretends that the command was
2078 successfully determined and executed. The exit status of the simple
2079 command is that of the command string in this case.
2080 Command search
2082 A command that is executed in a simple command is determined by the
2083 command name using the following algorithm:
2084 1. If the command name contains a slash (/), the whole name is
2086 treated as the pathname of an external command. The external
2087 command is determined as the executed command.
2088 2. If the command name is a special built-in, the built-in is
2090 determined as the executed command.
2091 3. If the command name is the name of an existing function, the
2093 function is determined as the executed command.
2094 4. If the command name is a semi-special built-in, the built-in is
2096 determined as the executed command.
2097 5. If the command name is a regular built-in, the built-in is
2099 determined as the executed command unless the shell is in the
2100 POSIXly-correct mode.
2101 6. The shell searches the PATH for a executed command:
2103 The value of the PATH variable is separated by colons. Each
2105 separated part is considered as a directory pathname (an empty
2106 pathname denotes the current working directory). The shell
2107 searches the directories (in the order of appearance) and
2108 checks if any directory directly contains an executable regular
2109 file whose name is equal to the command name. If such a file is
2110 found:
2111 · If the command name is the name of a built-in, the built-in
2113 is determined as the executed command.
2114 · Otherwise, the file is determined as the executed command.
2116 (The file will be executed as an external command.)
2117 If no such file is found, no command is determined as the
2119 executed command.
2120 When the shell finds a file that matches the command name during
2122 the search above, the shell remembers the pathname of the file if
2123 it is an absolute path. When the algorithm above is used for the
2124 same command name again, the shell skips searching and directly
2125 determines the command to be executed. If an executable regular
2126 file no longer exists at the remembered pathname, however, the
2127 shell searches again to update the remembered pathname. You can
2128 manage remembered pathnames using the hash built-in.
2129 Termination of the shell
2131 The shell exits when it reached the end of input and has parsed and
2132 executed all input commands or when the exit built-in is executed. The
2133 exit status of the shell is that of the last command the shell executed
2134 (or zero if no commands were executed). The exit status of the shell is
2135 always between 0 and 255 (inclusive). If the exit status of the last
2136 command is 256 or larger, the exit status of the shell will be the
2137 remainder of the exit status divided by 256.
2138 If an exit handler has been registered by the trap built-in, the
2140 handler is executed just before the shell exits. The exit status of the
2141 commands executed in the handler does not affect the exit status of the
2142 shell.
2143 If a non-interactive shell encountered one of the following errors, the
2145 shell immediately exits with a non-zero exit status:
2146 · A command cannot be parsed due to an syntax error (except during
2148 shell initialization).
2149 · An error occurs during execution of a special built-in in the
2151 POSIXly-correct mode.
2152 · A redirection error occurs in a simple command whose command name
2154 is a special built-in and the shell is in the POSIXly-correct mode.
2155 · An assignment error occurs in a simple command.
2157 · An error occurs during expansion (except during shell
2159 initialization).
2160 Note
2162 Some shells other than yash exit when they fail to find a command
2163 to execute in command search.
2164 Functions
2166 Functions allow executing a compound command as a simple command. A
2167 function can be defined by the function definition command and executed
2168 by a simple command. You can use the unset built-in to remove function
2169 definitions.
2170 There are no functions predefined when yash is started.
2172 A function is executed by executing its body, which is a compound
2174 command. While the function is being executed, positional parameters
2175 are set to the arguments given to the function. The old positional
2176 parameters are restored when the function execution finishes.
2177 Local variables
2179 Local variables are temporary variables that are defined in a
2180 function and exist during the function execution only. They can be
2181 defined by the typeset built-in or implicitly created by a for
2182 loop. They are removed when the function execution finishes.
2183 Local variables may hide variables that have already been defined
2185 before the function execution had started. An existing variable
2186 becomes inaccessible if a local variable of the same name is
2187 defined in a function. The old variable becomes accessible again
2188 when the function execution finishes.
2189 You cannot create a local variable when not executing a function. A
2191 normal variable is created if you try to do so.
2192 Command execution environment
2194 The shell holds following properties during execution.
2195 · The working directory
2197 · Open file descriptors
2199 · The file creation mask (umask)
2201 · The set of signals whose handler is set to “ignore” (trap)
2203 · Environment variables
2205 · Resource limits (ulimit)
2207 Those properties are inherited from the invoker of the shell to the
2209 shell, and from the shell to each external command executed by the
2210 shell.
2211 The properties can be changed during the execution of the shell by
2213 built-in commands, variable assignments, etc.
2214 Subshells
2216 A subshell is a copy of the shell process. Subshells are used in
2217 execution of groupings, pipelines, etc.
2218 Subshells inherit functions, aliases, etc. defined in the shell as
2220 well as the properties above since subshells are copies of the
2221 shell process. Notable exceptions are:
2222 · Traps registered by the trap built-in are all reset in
2224 subshells except for ones whose action is set to “ignore”. (See
2225 below)
2226 · The interactive mode and job control are disabled in subshells.
2228 Jobs are not inherited by subshells.
2229 Subshells are executed independently of the original shell, so
2231 changes of any properties above do not affect those of the original
2232 shell.
2233 Note
2235 If the subshell contains a single trap built-in, some shells
2236 (but not yash) may not reset the traps on entry to the
2237 subshell.
2238
2240 The interactive mode is a mode of the shell intended for direct
2241 interaction with a user. If yash is in the interactive mode, it is
2242 called an interactive shell.
2243 Whether a shell runs in the interactive mode or not is determined in
2245 the invocation of the shell. After the shell has started up, the
2246 interactive mode cannot be switched on or off.
2247 When the shell is interactive:
2249 · Initialization scripts are executed during invocation.
2251 · The shell checks for mail and prints a command prompt when it reads
2253 a command. Job status changes are also reported if job control is
2254 active. Line-editing may be used depending on the capability of
2255 the terminal.
2256 · Commands executed are automatically registered in command history.
2258 · If a command executed by the shell is killed by a signal other than
2260 SIGINT and SIGPIPE, the shell reports the fact to the standard
2261 error.
2262 · The filename token is subject to pathname expansion in file
2264 redirection.
2265 · The shell does not exit when it encounters a syntax or expansion
2267 error during command execution. (cf. Termination of the shell)
2268 · The shell does not exit when it receives the SIGINT, SIGTERM, or
2270 SIGQUIT signal.
2271 · A signal handler can be changed by the trap built-in even if the
2273 handler had been set to “ignore” when the shell was invoked.
2274 · The value of the - special parameter contains i.
2276 · The shell’s locale reflects the value of the LC_CTYPE variable
2278 whenever the value is changed (if the shell is not in the
2279 POSIXly-correct mode).
2280 · Commands are executed even when the exec option is off.
2282 · The ignore-eof option takes effect when enabled.
2284 · When the shell reaches the end of input or the exit built-in is
2286 executed, the shell checks if there is any stopped job. If so, the
2287 shell prints a warning and does not actually exit.
2288 · The suspend built-in by default cannot stop the shell if it is a
2290 session leader.
2291 · The shell does not exit when the dot built-in fails to find a
2293 script file to read.
2294 · The shell does not exit when the exec built-in fails to execute a
2296 command (if not in the POSIXly-correct mode).
2297 · When a job finished for which the wait built-in has been waiting,
2299 the fact is reported (only if job control is active and not in the
2300 POSIXly-correct mode).
2301 · A prompt is printed when the read built-in reads a second or
2303 following line.
2304 Prompts
2306 The interactive shell prints a prompt just before it reads a command.
2307 The contents of the prompt is specified by the value of the PS1 and PS2
2308 variables. The former is used for reading the first line of the command
2309 and the latter for other lines.
2310 When the prompt is printed, the variable value is subjected to
2312 parameter expansion, command substitution, and arithmetic expansion
2313 (but note that the POSIX standard requires parameter expansion only).
2314 The result of the expansion is parsed by the rules below to make the
2315 actual prompt string, which is printed to the standard error.
2316 In the POSIXly-correct mode, each exclamation mark (!) in the string is
2318 substituted with the command history number of the command that is
2319 being input. Two adjacent exclamation marks (!!) are printed as a
2320 single exclamation. Other characters are printed intact.
2321 If the shell is not in the POSIXly-command mode, the following
2323 notations can be used to format the prompt string. Notations are
2324 replaced with the strings designated in the list below. Characters that
2325 are not interpreted as notations are printed intact.
2326 \a
2328 Bell character (ASCII code: 7)
2329 \e
2331 Escape character (ASCII code: 27)
2332 \j
2334 The number of jobs in the shell.
2335 \n
2337 Newline character (ASCII code: 10)
2338 \r
2340 Carriage return character (ASCII code: 13)
2341 \!
2343 The command history number of the command that is being input
2344 \$
2346 # if the shell’s effective user ID is 0; $ otherwise.
2347 \\
2349 Backslash
2350 \[, \]
2352 These two notations can surround part of the prompt string that is
2353 not visible on the terminal. The surrounded part is ignored when
2354 the shell counts the number of characters that is displayed on the
2355 terminal, thus making characters correctly aligned on the terminal
2356 when the prompt string contains special invisible characters.
2357 \ffontspecs.
2359 When line-editing is active, this notation is replaced with special
2360 characters to change font styles on the terminal if the terminal is
2361 capable of it. If line-editing is inactive or the terminal is
2362 incapable of changing font styles, this notation is silently
2363 ignored. One or more of the following can be used for fontspecs:
2364 k
2366 Change font color to black
2367 r
2369 Change font color to red
2370 g
2372 Change font color to green
2373 y
2375 Change font color to yellow
2376 b
2378 Change font color to blue
2379 m
2381 Change font color to magenta
2382 c
2384 Change font color to cyan
2385 w
2387 Change font color to white
2388 K
2390 Change background color to black
2391 R
2393 Change background color to red
2394 G
2396 Change background color to green
2397 Y
2399 Change background color to yellow
2400 B
2402 Change background color to blue
2403 M
2405 Change background color to magenta
2406 C
2408 Change background color to cyan
2409 W
2411 Change background color to white
2412 t
2414 Make font color or background brighter (can only be used just
2415 after one of the characters above)
2416 d
2418 Change font and background colors to normal
2419 s
2421 Make font standout
2422 u
2424 Make font underlined
2425 v
2427 Make font and background colors reversed
2428 b
2430 Make font blink
2431 i
2433 Make font dim
2434 o
2436 Make font bold
2437 x
2439 Make font invisible
2440 D
2442 Make color and style normal
2443 The actual colors of font and background are defined by the
2445 terminal. Different terminals may use different colors.
2446 In addition to the normal prompt, a prompt string can be displayed to
2448 the right of the cursor if line-editing is active. Those prompts are
2449 called right prompts. The contents of right prompts are defined by the
2450 value of the PS1R and PS2R variables, each corresponding to the PS1 and
2451 PS2 variables.
2452 Using the above-said notations, the font style of command strings the
2454 user inputs can be changed as well as that of prompts. The font style
2455 of command strings is defined by the value of the PS1S and PS2S
2456 variables, each corresponding to the PS1 and PS2 variables. The value
2457 can contain the \ffontspecs. notation only.
2458 When the shell is not in the POSIXly-correct mode, the prompt variables
2460 can be defined with a name prefixed with YASH_ (e.g. YASH_PS1). This
2461 allows using a different prompt string than that in the POSIXly-correct
2462 mode.
2463 When the shell is not in the POSIXly-correct mode, the value of the
2465 PROMPT_COMMAND variable is executed before each prompt.
2466 Command history
2468 Command history is a feature of the shell that remembers executed
2469 commands to allow re-executing them later. Commands executed in the
2470 interactive mode are automatically saved in the command history. Saved
2471 commands can be edited and re-executed using line-editing and the fc
2472 and history built-ins.
2473 Commands are saved line by line. Lines that do not contain any
2475 non-whitespace characters are not saved in the history. Lines that
2476 start with whitespaces are not saved when the hist-space option is on.
2477 Command history is saved in a file. When history is first used after an
2479 interactive shell was started, the shell opens a file to save history
2480 in. The filename is specified by the value of the HISTFILE variable. If
2481 the file contains history data when opened, the data is restored to the
2482 shell’s history. The file contents are updated in real time as the user
2483 inputs commands into the shell. If the HISTFILE variable is not set or
2484 the file cannot be opened successfully, history is not saved in the
2485 file, but the history feature will be functional in all other respects.
2486 The number of commands saved in history is specified by the value of
2488 the HISTSIZE variable. The shell automatically removes old history data
2489 so that the number of saved commands does not exceed the value. If the
2490 HISTSIZE variable is not set or its value is not a natural number, 500
2491 items will be saved in history.
2492 The shell looks at the value of the HISTFILE and HISTSIZE variables
2494 only when the history feature is first used after the shell was
2495 started. “The history feature is used” when:
2496 · the fc or history built-in is executed,
2498 · line-editing is used (regardless of whether or not history data is
2500 recalled in line-editing), or
2501 · a command is input to the shell
2503 Therefore, the variables should be set in initialization scripts.
2505 When more than one instance of yash shares a single history file, all
2507 the shells use the same history data. As a result, commands that have
2508 been executed by a shell instance can be recalled on another shell
2509 instance. Shells sharing the same history should have the same HISTSIZE
2510 value so that they manipulate history data properly.
2511 Yash’s history data file has its own format that is incompatible with
2513 other kinds of shells.
2514 The HISTRMDUP variable can be set to remove duplicate history items.
2516 Mail checking
2518 An interactive shell can notify receipt of email. The shell
2519 periodically checks the modification date/time of a file specified by
2520 the user. If the file has been modified since the previous check, the
2521 shell prints a notification message (except when the shell is not in
2522 the POSIXly-correct mode and the file is empty). By specifying a
2523 mailbox file to be checked, the shell will print a message when the
2524 file has been modified, that is, some mail has been received.
2525 Check is done just before the shell prints a command line prompt. The
2527 interval of checks can be specified by the MAILCHECK variable in
2528 seconds. If the variable value is 0, check is done before every prompt.
2529 If the variable value is not a non-negative integer, no checks are
2530 done.
2531 The file whose modification time is checked is specified by the MAIL
2533 variable. The variable value should be set to the pathname of the file.
2534 If you want to check more than one file or customize the notification
2536 message, you can set the MAILPATH variable instead of the MAIL
2537 variable. When the MAILPATH variable is set, the MAIL variable is
2538 ignored. The value of the MAILPATH variable should be set to one or
2539 more colon-separated pathnames of files to be checked. Each pathname
2540 can be followed by a percent sign (%) and a custom notification
2541 message, which is printed when the corresponding file has been
2542 modified. If the pathname contains a percent sign, it should be quoted
2543 by a backslash. The specified message is subject to parameter
2544 expansion. For example, if the value of the MAILPATH variable is
2545 /foo/mail%New mail!:/bar/mailbox%You've got mail:/baz/mail\%data, the
2546 shell will print
2547 · New mail! when the file /foo/mail has been modified
2549 · You've got mail when the file /bar/mailbox has been modified
2551 · the default message when the file /baz/mail%data has been modified.
2553
2555 Job control is a function of the shell that executes multiple commands
2556 simultaneously and suspends/resumes the commands.
2557 When job control is active:
2559 · Every pipeline executed by the shell becomes a job. A job has its
2561 unique process group ID that is shared among all processes in the
2562 job.
2563 · If the processes of a job are suspended while the shell is waiting
2565 for the processes to finish, the shell continues to the next
2566 command as if the process have finished. The shell remembers the
2567 job as suspended so that it can be resumed later.
2568 · If a job is executed synchronously, the shell sets the foreground
2570 process group of the terminal to the process group of the job. When
2571 the job is finished (or suspended), the shell gets back to the
2572 foreground.
2573 · The subshell executing a command substitution has its own unique
2575 process group ID like a job. However, the shell does not remember
2576 the subshell as a job, so it cannot be suspended or resumed.
2577 · If the shell is interactive, job status is reported before every
2579 command line prompt as if the command jobs -n is executed.
2580 · The standard input of an asynchronous command is not automatically
2582 redirected to /dev/null.
2583 · The shell does not exit when it receives the SIGTSTP signal.
2585 · The value of the - special parameter contains m.
2587 · When a job finished for which the wait built-in has been waiting,
2589 the fact is reported (only if the shell is interactive and not in
2590 the POSIXly-correct mode).
2591 When job control is inactive, processes executed by the shell have the
2593 same process group ID as the shell. The shell treats asynchronous
2594 commands as an uncontrolled job.
2595 You can use the following built-ins to manipulate jobs:
2597 jobs
2599 prints existing jobs
2600 fg and bg
2602 run jobs in the foreground or background
2603 wait
2605 waits for jobs to be finished (or suspended)
2606 disown
2608 forgets jobs
2609 kill
2611 sends a signal to jobs
2612 An interactive job-controlling shell reports jobs status before every
2614 prompt by default. You can set the following options to make the shell
2615 report status at other timings:
2616 notify
2618 the shell reports immediately whenever job status changes.
2619 notify-le
2621 the shell reports immediately when job status changes while
2622 line-editing.
2623 A job is removed from the shell’s job list when:
2625 · it has finished and the jobs built-in reported it,
2627 · the wait built-in successfully waited for the job to finish, or
2629 · the disown built-in removed the job.
2631 Jobs are not removed from the list when an interactive shell
2633 automatically reports the status of jobs.
2634 Note
2636 The word “stop” is synonymous to “suspend” in the context of job
2637 control.
2638 Job ID
2640 Some built-ins use the following notation, which is called job ID, to
2641 specify a job to operate on:
2642 %, %%, %+
2644 the current job
2645 %-
2647 the previous job
2648 %n
2650 the job that has job number n, where n is a positive integer
2651 %string
2653 the job whose name begins with string
2654 %?string
2656 the job whose name contains string
2657 The current job and previous job are jobs selected by the shell
2659 according to the following rules:
2660 · When there is one or more suspended jobs, the current job is
2662 selected from them.
2663 · When there is one or more suspended jobs other than the current
2665 job, the previous job is selected from them.
2666 · The current and previous jobs are always different. When the shell
2668 has only one job, it is the current job and there is no previous
2669 job.
2670 · When the current job finished, the previous job becomes the current
2672 job.
2673 · When the current job is changed, the old current job becomes the
2675 previous job except when the old job finished.
2676 · When the foreground job is suspended, the job becomes the current
2678 job.
2679 Yash has some options to modify the rules of the current/previous job
2681 selection. (The rules above have priority over the options below.)
2682 cur-async
2684 When a new asynchronous command is started, it becomes the current
2685 job.
2686 cur-bg
2688 When a job is resumed by the bg built-in, the job becomes the
2689 current job.
2690 cur-stop
2692 When a job is suspended, it becomes the current job.
2693 The current and previous jobs are not changed as long as the rules
2695 above are met.
2696 The rules of the current/previous job selection defined in the POSIX
2698 standard are looser than yash’s rules above. Other POSIX-compliant
2699 shells may select the current and previous jobs differently.
2700
2702 Built-in commands are commands that are implemented in the shell and
2703 are executed by the shell without external programs.
2704 Types of built-in commands
2706 There are three types of built-in commands in yash: special built-in
2707 commands, semi-special built-in commands and regular built-in commands.
2708 Special built-in commands are much more important commands than others.
2710 They are executed regardless of whether the corresponding external
2711 commands exist or not. Results of variable assignments that occur in a
2712 simple command that invokes a special built-in last after the command
2713 has finished. Moreover, in the POSIXly-correct mode, a non-interactive
2714 shell immediately exits with a non-zero exit status when a redirect
2715 error, assignment error, or misuse of option or operand occurs in a
2716 special built-in command.
2717 Semi special built-in commands are the second important built-in
2719 commands. They are executed regardless of whether the corresponding
2720 external commands exist or not. In other parts they are the same as
2721 regular built-in commands.
2722 Regular built-in commands are less important built-in commands
2724 including commands that can be implemented as external commands or are
2725 not listed in POSIX. In the POSIXly-correct mode, a regular built-in is
2726 executed only when a corresponding external command is found in PATH.
2727 Syntax of command arguments
2729 In this section we explain common rules about command arguments. The
2730 built-in commands of yash follow the rules unless otherwise stated.
2731 There are two types of command arguments. One is options and the other
2733 is operands. An option is an argument that starts with a hyphen (-) and
2734 changes the way the command behaves. Some options take arguments. An
2735 operand is an argument that is not an option and specifies objects the
2736 command operates on.
2737 If you specify more than one option to a command, the order of the
2739 options are normally not significant. The order of operands, however,
2740 affects the command behavior.
2741 An option is either a single-character option or a long option. A
2743 single-character option is identified by one alphabetic character. A
2744 long option is identified by multiple alphabetic characters. The POSIX
2745 standard only prescribes single-character options, so in the
2746 POSIXly-correct mode you cannot use long options.
2747 A single-character option is composed of a hyphen followed by a letter.
2749 For example, -a is a single-character option. A single-character option
2750 that takes an argument requires the argument to be just after the
2751 option name.
2752 Example 4. The set built-in and single-character options
2754 For the set built-in, -m is a single-character option that does not
2756 take an argument and -o is one that takes an argument.
2757 · set -o errexit -m
2759 · set -oerrexit -m
2761 In these two command lines, errexit is the argument to the -o option.
2763 In the second example above, the -o option and its argument are
2765 combined into a single command line argument. The POSIX standard
2766 deprecates that style and any POSIX-conforming applications must
2767 specify options and their arguments as separate command line arguments,
2768 although yash accepts both styles.
2769 You can combine single-character options that do not take arguments
2771 into a single command line argument. For example, the three options -a,
2772 -b and -c can be combined into -abc.
2773 A long option is composed of two hyphens followed by an option name.
2775 For example, --long-option is a long option. You can omit some last
2776 characters of a long option name as long as it is not ambiguous. For
2777 example, you can use --long instead of --long-option if there is no
2778 other options beginning with --long. Like a single-character option, a
2779 long option that takes an argument requires the argument to be a
2780 command line argument just after the option name or to be specified in
2781 the same command line argument as the option name, separated by an
2782 equal sign (=).
2783 Example 5. The fc built-in and long options
2785 For the fc built-in, --quiet is a long option that does not take an
2787 argument and --editor is one that takes an argument.
2788 · fc --editor vi --quiet
2790 · fc --editor=vi --quiet
2792 In these command lines, vi is the argument to the --editor option.
2794 Arguments that are not options (nor arguments to them) are interpreted
2796 as operands. The POSIX standard requires all options should be
2797 specified before any operands. Therefore, in the POSIXly-correct mode,
2798 any arguments that come after the first operand are interpreted as
2799 operands (even if they look like options). If not in the
2800 POSIXly-correct mode, you can specify options after operand.
2801 Regardless of whether the shell is in the POSIXly-correct mode or not,
2803 an argument that is just composed of two hyphens (--) can be used as a
2804 separator between options and operands. All command line arguments
2805 after the -- separator are interpreted as operands, so you can specify
2806 operands that start with a hyphen correctly using the separator.
2807 Example 6. Options and operands to the set built-in
2809 · set -a -b -- -c -d
2811 In this example, -a and -b are options and -c and -d are operands. The
2813 -- separator itself is neither an option nor an operand.
2814 Regardless of whether the shell is in the POSIXly-correct mode or not,
2816 an argument that is just composed of a single hyphen (-) is interpreted
2817 as an operand.
2818
2820 With the line-editing feature, you can edit the command text when you
2821 input a command to an interactive shell. It not only works as a simple
2822 visual-interface editor, but also is integrated with the command
2823 history. You can recall, edit, and execute commands in the history with
2824 line-editing instead of using the fc built-in.
2825 Line-editing has two editing modes, the vi and emacs modes, which each
2827 have their own key binding settings. By switching editing modes, you
2828 can change key bindings used in line-editing. Each mode has a
2829 corresponding shell option, which determines whether the mode is
2830 currently active or not. No more than one mode can be active at a time,
2831 so the options for the other modes are automatically turned off when
2832 you turn on the option for one mode. The whole line-editing feature is
2833 deactivated when those options are off.
2834 When an interactive shell is started, the vi mode is automatically
2836 activated if the standard input and error are both connected to a
2837 terminal.
2838 Line-editing can be used only when the standard input and error are
2840 both connected to a terminal. If not, the shell silently falls back to
2841 the normal input mechanism. While line-editing is being used, the shell
2842 uses the termios interface to change I/O settings of the terminal and
2843 the terminfo interface to parse input key sequences.
2844 Shell options on line-editing
2846 The following options can be set by the set built-in to enable
2847 line-editing and choose an editing mode to activate:
2848 vi
2850 activates the vi mode.
2851 emacs
2853 activates the emacs mode.
2854 The other line-editing-related options are:
2856 le-always-rp
2858 When this options is enabled, the right prompt is always visible:
2859 when the cursor reaches the right prompt, it moves to the next line
2860 from the original position, which would otherwise be overwritten by
2861 input text.
2862 le-comp-debug
2864 When enabled, internal information is printed during completion,
2865 which will help debugging completion scripts.
2866 le-conv-meta
2868 When enabled, the 8th bit of each input byte is always treated as a
2869 meta-key flag, regardless of terminfo data.
2870 le-no-conv-meta
2872 When enabled, the 8th bit of each input byte is never treated as a
2873 meta-key flag, regardless of terminfo data.
2874 The le-conv-meta and le-no-conv-meta options cannot be both enabled
2876 at a time. When either is enabled, the other is automatically
2877 disabled. When neither is enabled, the 8th bit may be treated as a
2878 meta-key flag depending on terminfo data.
2879 le-predict
2881 activates command line prediction.
2882 le-predict-empty
2884 When enabled, and command line prediction is active, suggestions
2885 are also provided for empty input lines.
2886 le-prompt-sp
2888 When enabled, the shell prints a special character sequence before
2889 printing each prompt so that every prompt is printed at the
2890 beginning of a line.
2891 This option is enabled by default.
2893 le-visible-bell
2895 When enabled, the shell flashes the terminal instead of sounding an
2896 alarm when an alert is required.
2897 Editing modes
2899 The vi mode is an editing mode that offers key bindings similar to that
2900 of the vi editor. The vi mode has two sub-modes that are switched
2901 during editing: the insert and command modes. The sub-mode is always
2902 reset to the insert mode when line-editing is started for a new command
2903 line. In the insert mode, most characters are inserted to the buffer as
2904 typed. In the command mode, input characters are treated as commands
2905 that move the cursor, insert/delete text, etc.
2906 The emacs mode offers key bindings similar to the emacs editor. Most
2908 characters are inserted to the buffer as typed, but more characters are
2909 treated as commands than the vi insert mode.
2910 Another sub-mode is used while you enter search keywords. The sub-mode
2912 is called the search mode, which offers slightly different key bindings
2913 depending on the active editing mode.
2914 Line-editing commands
2916 All characters the user enters while line-editing is active are treated
2917 as line-editing commands listed below. The bindkey built-in allows
2918 customizing the key bindings of each mode (except for the search mode).
2919 The list below shows not only the functions of commands but also the
2921 default key bindings. The keywords “vi-insert”, “vi-command”,
2922 “vi-search”, “emacs”, “emacs-search” means the vi insert mode, the vi
2923 command mode, the search mode for the vi mode (the vi search mode), the
2924 emacs mode, and the search mode for the emacs mode (the emacs search
2925 mode), respectively.
2926 Some commands take an argument that affects the function of the
2928 commands. For example, the forward-char command moves the cursor by as
2929 many characters as specified by the argument. To specify an argument,
2930 use the digit-argument command just before another command that takes
2931 an argument.
2932 Basic editing commands
2934 noop
2935 Do nothing.
2936 vi-command
2938 \^[
2939 alert
2941 Alert.
2942 self-insert
2944 Insert the input character at the current cursor position.
2945 Characters escaped by escape sequences cannot be inserted.
2946 vi-insert, emacs
2948 \\
2949 insert-tab
2951 Insert a tab character at the current cursor position.
2952 emacs
2954 \^[\^I
2955 expect-verbatim
2957 Insert a character that is entered just after this command at
2958 the current cursor position. This command can input a character
2959 that cannot be input by the self-insert command, except a null
2960 character ('\0').
2961 vi-insert, vi-search, emacs-search
2963 \^V
2964 emacs
2966 \^Q, \^V
2967 digit-argument
2969 Pass the input digit to the next command as an argument.
2970 This command can be bound to a digit or hyphen. To pass “12” as
2972 an argument to the forward-char command in the vi mode, for
2973 example, enter 12l.
2974 vi-command
2976 1, 2, 3, 4, 5, 6, 7, 8, 9
2977 emacs
2979 \^[0, \^[1, \^[2, \^[3, \^[4, \^[5, \^[6, \^[7, \^[8, \^[9,
2980 \^[-,
2981 bol-or-digit
2983 Like the beginning-of-line command if there is no argument;
2984 like the digit-argument command otherwise.
2985 vi-command
2987 0
2988 accept-line
2990 Finish editing the current line. A newline is automatically
2991 appended to the line. The line will be executed by the shell.
2992 If command line prediction is active, the current prediction
2994 (if any) is ignored. See also the accept-prediction command.
2995 vi-insert, vi-command, emacs, emacs-search
2997 \^J, \^M
2998 abort-line
3000 Abandon the current buffer and finish editing as if an empty
3001 line was input.
3002 vi-insert, vi-command, vi-search, emacs, emacs-search
3004 \!, \^C
3005 eof
3007 Abandon the current buffer and finish editing as if the shell
3008 reached the end of input. This normally makes the shell exit.
3009 eof-if-empty
3011 Like the eof command if the buffer is empty; like the alert
3012 command otherwise.
3013 vi-insert, vi-command
3015 \#, \^D
3016 eof-or-delete
3018 Like the eof command if the buffer is empty; like the
3019 delete-char command otherwise.
3020 emacs
3022 \#, \^D
3023 accept-with-hash
3025 If the current line does not begin with a hash sign (#) or
3026 there is no argument specified for this command, a hash sign is
3027 inserted at the beginning of the line. Otherwise, the beginning
3028 hash sign is removed from the line. Finally, the line is
3029 accepted like the accept-line command.
3030 vi-command
3032 #
3033 emacs
3035 \^[#
3036 accept-prediction
3038 Like the accept-line command, but include the predicted part.
3039 setmode-viinsert
3041 Switch to the vi insert mode.
3042 vi-command
3044 i, \I
3045 setmode-vicommand
3047 Switch to the vi command mode.
3048 vi-insert
3050 \^[
3051 setmode-emacs
3053 Switch to the emacs mode.
3054 expect-char, abort-expect-char
3056 These commands are not meant for use by the user. They are used
3057 by the shell to implement some other commands.
3058 redraw-all
3060 Reprint the prompt and the current line to the terminal.
3061 vi-insert, vi-command, vi-search, emacs, emacs-search
3063 \^L
3064 clear-and-redraw-all
3066 Clear the terminal and reprint the prompt and the current line.
3067 Motion commands
3069 Motion commands move the cursor on the line. Most motion commands
3070 accept an argument. When passed an argument, they repeat the cursor
3071 motion as many times as specified by the argument. Passing “4” as
3072 an argument to the forward-char command, for example, advances the
3073 cursor by four characters.
3074 The shell has several definitions of words as units of distance: A
3076 bigword is one or more adjacent non-whitespace characters. A
3077 semiword is one or more adjacent characters that contain no
3078 whitespaces or punctuations. An emacsword is one or more adjacent
3079 alphanumeric characters. A viword is either:
3080 · one or more adjacent alphanumeric characters and/or underscores
3082 (_), or
3083 · one or more adjacent characters that contain none of
3085 alphanumeric characters, underscores, and whitespaces.
3086 forward-char
3088 Move the cursor to the next character.
3089 vi-insert
3091 \R
3092 vi-command
3094 l, (space), \R
3095 emacs
3097 \R, \^F
3098 backward-char
3100 Move the cursor to the previous character.
3101 vi-insert
3103 \L
3104 vi-command
3106 h, \B, \L, \?, \^H
3107 emacs
3109 \L, \^B
3110 forward-bigword
3112 Move the cursor to the next bigword.
3113 vi-command
3115 W
3116 end-of-bigword
3118 Move the cursor to the next end of a bigword.
3119 vi-command
3121 E
3122 backward-bigword
3124 Move the cursor to the previous bigword.
3125 vi-command
3127 B
3128 forward-semiword
3130 Move the cursor to the next semiword.
3131 end-of-semiword
3133 Move the cursor to the next end of a semiword.
3134 backward-semiword
3136 Move the cursor to the previous semiword.
3137 forward-viword
3139 Move the cursor to the next viword.
3140 vi-command
3142 w
3143 end-of-viword
3145 Move the cursor to the next end of a viword.
3146 vi-command
3148 e
3149 backward-viword
3151 Move the cursor to the previous viword.
3152 vi-command
3154 b
3155 forward-emacsword
3157 Move the cursor to the next emacsword.
3158 emacs
3160 \^[f, \^[F
3161 backward-emacsword
3163 Move the cursor to the previous emacsword.
3164 emacs
3166 \^[b, \^[B
3167 beginning-of-line
3169 Move the cursor to the beginning of the line.
3170 vi-insert, vi-command
3172 \H
3173 emacs
3175 \H, \^A
3176 end-of-line
3178 Move the cursor to the end of the line.
3179 vi-insert
3181 \E
3182 vi-command
3184 $, \E
3185 emacs
3187 \E, \^E
3188 go-to-column
3190 Move the cursor to the nth character on the line, where n is
3191 the argument. Assume n = 1 when no argument.
3192 vi-command
3194 |
3195 first-nonblank
3197 Move the cursor to the first non-blank character on the line.
3198 vi-command
3200 ^
3201 find-char
3203 Move the cursor to the first position where a character that is
3204 entered just after this command appears after the current
3205 cursor position.
3206 vi-command
3208 f
3209 emacs
3211 \^]
3212 find-char-rev
3214 Move the cursor to the last position where a character that is
3215 entered just after this command appears before the current
3216 cursor position.
3217 vi-command
3219 F
3220 emacs
3222 \^[\^]
3223 till-char
3225 Move the cursor to the first position just before a character
3226 that is entered just after this command appears after the
3227 current cursor position.
3228 vi-command
3230 t
3231 till-char-rev
3233 Move the cursor to the last position just after a character
3234 that is entered just after this command appears before the
3235 current cursor position.
3236 vi-command
3238 T
3239 refind-char
3241 Redo the last find-char, find-char-rev, till-char,
3242 till-char-rev command.
3243 vi-command
3245 ;
3246 refind-char-rev
3248 Redo the last find-char, find-char-rev, till-char,
3249 till-char-rev command in the reverse direction.
3250 vi-command
3252 ,
3253 Editing commands
3255 Editing commands modify contents of the buffer. Most editing
3256 commands accept an argument. When passed an argument, they repeat
3257 the modification as many times as specified by the argument.
3258 Texts deleted by commands whose name starts with “kill” are saved
3260 in kill ring, from which deleted contents can be restored to the
3261 buffer. The most recent 32 texts are kept in the kill ring.
3262 delete-char
3264 Delete a character at the current cursor position if no
3265 argument is passed; like the kill-char command otherwise.
3266 vi-insert, emacs
3268 \X
3269 delete-bigword
3271 Delete a bigword at the current cursor position if no argument
3272 is passed; like the kill-bigword command otherwise.
3273 delete-semiword
3275 Delete a semiword at the current cursor position if no argument
3276 is passed; like the kill-semiword command otherwise.
3277 delete-viword
3279 Delete a viword at the current cursor position if no argument
3280 is passed; like the kill-viword command otherwise.
3281 delete-emacsword
3283 Delete a emacsword at the current cursor position if no
3284 argument is passed; like the kill-emacsword command otherwise.
3285 backward-delete-char
3287 Delete a character just before the current cursor position if
3288 no argument is passed; like the backward-kill-char command
3289 otherwise.
3290 vi-insert, emacs
3292 \B, \?, \^H
3293 backward-delete-bigword
3295 Delete a bigword just before the current cursor position if no
3296 argument is passed; like the backward-kill-bigword command
3297 otherwise.
3298 backward-delete-semiword
3300 Delete a semiword just before the current cursor position if no
3301 argument is passed; like the backward-kill-semiword command
3302 otherwise.
3303 vi-insert
3305 \^W
3306 backward-delete-viword
3308 Delete a viword just before the current cursor position if no
3309 argument is passed; like the backward-kill-viword command
3310 otherwise.
3311 backward-delete-emacsword
3313 Delete a emacsword just before the current cursor position if
3314 no argument is passed; like the backward-kill-emacsword command
3315 otherwise.
3316 delete-line
3318 Delete the whole buffer contents.
3319 forward-delete-line
3321 Delete all characters from the current cursor position to the
3322 end of the buffer.
3323 backward-delete-line
3325 Delete all characters before the current cursor position.
3326 vi-insert
3328 \$, \^U
3329 kill-char
3331 Delete a character at the current cursor position and add it to
3332 the kill ring.
3333 vi-command
3335 x, \X
3336 kill-bigword
3338 Delete a bigword at the current cursor position and add it to
3339 the kill ring.
3340 kill-semiword
3342 Delete a semiword at the current cursor position and add it to
3343 the kill ring.
3344 kill-viword
3346 Delete a viword at the current cursor position and add it to
3347 the kill ring.
3348 kill-emacsword
3350 Delete a emacsword at the current cursor position and add it to
3351 the kill ring.
3352 emacs
3354 \^[d, \^[D
3355 backward-kill-char
3357 Delete a character just before the current cursor position and
3358 add it to the kill ring.
3359 vi-command
3361 X
3362 backward-kill-bigword
3364 Delete a bigword just before the current cursor position and
3365 add it to the kill ring.
3366 emacs
3368 \^W
3369 backward-kill-semiword
3371 Delete a semiword just before the current cursor position and
3372 add it to the kill ring.
3373 backward-kill-viword
3375 Delete a viword just before the current cursor position and add
3376 it to the kill ring.
3377 backward-kill-emacsword
3379 Delete a emacsword just before the current cursor position and
3380 add it to the kill ring.
3381 emacs
3383 \^[\B, \^[\?, \^[\^H
3384 kill-line
3386 Delete the whole buffer contents and add it to the kill ring.
3387 forward-kill-line
3389 Delete all characters from the current cursor position to the
3390 end of the buffer and add it to the kill ring.
3391 emacs
3393 \^K
3394 backward-kill-line
3396 Delete all characters before the current cursor position and
3397 add it to the kill ring.
3398 emacs
3400 \$, \^U, \^X\B, \^X\?
3401 put-before
3403 Insert the last-killed text before the current cursor position
3404 and move the cursor to the last character that was inserted.
3405 vi-command
3407 P
3408 put
3410 Insert the last-killed text after the current cursor position
3411 and move the cursor to the last character that was inserted.
3412 vi-command
3414 p
3415 put-left
3417 Insert the last-killed text before the current cursor position
3418 and move the cursor to the last character that was inserted.
3419 emacs
3421 \^Y
3422 put-pop
3424 Replace the just put text with the next older killed text.
3425 This command can be used only just after the put-before, put,
3427 put-left, or put-pop command.
3428 emacs
3430 \^[y, \^[Y
3431 undo
3433 Cancel modification by the last editing command.
3434 vi
3436 u
3437 emacs
3439 \^_, \^X\$, \^X\^U
3440 undo-all
3442 Cancel all modification in the current buffer, restoring the
3443 initial contents.
3444 vi
3446 U
3447 emacs
3449 \^[\^R, \^[r, \^[R
3450 cancel-undo
3452 Cancel cancellation by the last undo or undo-all command.
3453 vi
3455 \^R
3456 cancel-undo-all
3458 Cancel all cancellation by all most recent undo and undo-all
3459 commands.
3460 redo
3462 Repeat modification by the last editing command.
3463 vi-command
3465 .
3466 Completion commands
3468 complete
3469 Complete a word just before the cursor position and, if there
3470 is more than one candidate, show a list of the candidates.
3471 complete-next-candidate
3473 Like the complete command when candidates are not being listed;
3474 otherwise, select the next candidate in the list.
3475 vi-insert, emacs
3477 \^I
3478 complete-prev-candidate
3480 Like the complete command when candidates are not being listed;
3481 otherwise, select the previous candidate in the list.
3482 vi-insert, emacs
3484 \bt
3485 complete-next-column
3487 Like the complete command when candidates are not being listed;
3488 otherwise, select the first candidate in the next column in the
3489 list.
3490 complete-prev-column
3492 Like the complete command when candidates are not being listed;
3493 otherwise, select the first candidate in the previous column in
3494 the list.
3495 complete-next-page
3497 Like the complete command when candidates are not being listed;
3498 otherwise, select the first candidate in the next page in the
3499 list.
3500 complete-prev-page
3502 Like the complete command when candidates are not being listed;
3503 otherwise, select the first candidate in the previous page in
3504 the list.
3505 complete-list
3507 Complete a word just before the cursor position.
3508 If you pass no argument, a list of completion candidates is
3510 shown. Otherwise, the word is completed with the nth candidate
3511 where n is the argument.
3512 emacs
3514 \^[?, \^[=
3515 complete-all
3517 Replace a word just before the cursor position with all
3518 possible completion candidates, each separated by a space.
3519 emacs
3521 \^[*
3522 complete-max
3524 Complete a word just before the cursor position with the
3525 longest prefix of all possible completion candidates.
3526 complete-max-then-list
3528 Works like the complete-max command for the first use, then
3529 like the complete command when used successively.
3530 complete-max-then-next-candidate
3532 Works like the complete-max command for the first use, then
3533 like the complete-next-candidate command when used
3534 successively.
3535 complete-max-then-prev-candidate
3537 Works like the complete-max command for the first use, then
3538 like the complete-prev-candidate command when used
3539 successively.
3540 clear-candidates
3542 Clear the list of completion candidates.
3543 Vi-specific commands
3545 vi-replace-char
3546 Replace the character at the cursor position with a character
3547 that is entered just after this command.
3548 vi-command
3550 r
3551 vi-insert-beginning
3553 Move the cursor to the beginning of the line and switch to the
3554 vi insert mode.
3555 vi-command
3557 I
3558 vi-append
3560 Move the cursor to the next character and switch to the vi
3561 insert mode.
3562 vi-command
3564 I
3565 vi-append-to-eol
3567 Move the cursor to the end of the line and switch to the vi
3568 insert mode.
3569 vi-command
3571 A
3572 vi-replace
3574 Switch to the vi insert mode and start overwriting. While
3575 overwriting, the self-insert command replaces the character at
3576 cursor position rather than inserting a character. Overwriting
3577 ends when the editing mode is changed.
3578 vi-command
3580 R
3581 vi-switch-case
3583 Switch case of characters between the current and next cursor
3584 positions. This command must be followed by a motion command,
3585 which determines the next cursor position.
3586 vi-switch-case-char
3588 Switch case of the character at the current cursor position and
3589 move the cursor to the next character.
3590 vi-command
3592 ~
3593 vi-yank
3595 Add to the kill ring the characters between the current and
3596 next cursor positions. This command must be followed by a
3597 motion command, which determines the next cursor position.
3598 vi-command
3600 y
3601 vi-yank-to-eol
3603 Add to the kill ring the characters from the current cursor
3604 position to the end of the line.
3605 vi-command
3607 Y
3608 vi-delete
3610 Delete characters between the current and next cursor positions
3611 and add it to the kill ring. This command must be followed by a
3612 motion command, which determines the next cursor position.
3613 vi-command
3615 d
3616 vi-delete-to-eol
3618 Delete the characters from the current cursor position to the
3619 end of the line and add it to the kill ring.
3620 vi-command
3622 D
3623 vi-change
3625 Delete characters between the current and next cursor positions
3626 and switch to the vi insert mode. This command must be followed
3627 by a motion command, which determines the next cursor position.
3628 vi-command
3630 c
3631 vi-change-to-eol
3633 Delete the characters from the current cursor position to the
3634 end of the line and switch to the vi insert mode.
3635 vi-command
3637 C
3638 vi-change-line
3640 Delete the whole buffer contents and switch to the vi insert
3641 mode.
3642 vi-command
3644 S
3645 vi-yank-and-change
3647 Like the vi-change command, but the deleted text is added to
3648 the kill ring.
3649 vi-yank-and-change-to-eol
3651 Like the vi-change-to-eol command, but the deleted text is
3652 added to the kill ring.
3653 vi-yank-and-change-line
3655 Like the vi-change-line command, but the deleted text is added
3656 to the kill ring.
3657 vi-substitute
3659 Delete a character at the current cursor position, add it to
3660 the kill ring, and switch to the vi insert mode.
3661 vi-command
3663 s
3664 vi-append-last-bigword
3666 Insert a space and the last bigword in the most recent command
3667 history entry just after the current cursor position and switch
3668 to the vi insert mode. If argument n is passed, the nth bigword
3669 in the entry is inserted instead of the last.
3670 vi-command
3672 _
3673 vi-exec-alias
3675 Execute the value of an alias named _c as editing commands
3676 where c is a character input just after this command.
3677 vi-command
3679 @
3680 vi-edit-and-accept
3682 Start the vi editor to edit the current buffer contents. When
3683 the editor finished, the edited buffer contents is accepted
3684 like the accept-line command unless the exit status of the
3685 editor is non-zero.
3686 vi-command
3688 v
3689 vi-complete-list
3691 Like the complete-list command, but also switch to the vi
3692 insert mode.
3693 vi-command
3695 =
3696 vi-complete-all
3698 Like the complete-all command, but also switch to the vi insert
3699 mode.
3700 vi-command
3702 *
3703 vi-complete-max
3705 Like the complete-max command, but also switch to the vi insert
3706 mode.
3707 vi-command
3709 \\
3710 vi-search-forward
3712 Switch to the vi search mode and start forward history search.
3713 vi-command
3715 ?
3716 vi-search-backward
3718 Switch to the vi search mode and start backward history search.
3719 vi-command
3721 /
3722 Emacs-specific commands
3724 emacs-transpose-chars
3725 Move a character just before the cursor to the right.
3726 emacs
3728 \^T
3729 emacs-transpose-words
3731 Move an emacsword just before the cursor to the right.
3732 emacs
3734 \^[t, \^[T
3735 emacs-downcase-word
3737 Make an emacsword just after the cursor lowercase.
3738 emacs
3740 \^[l, \^[L
3741 emacs-upcase-word
3743 Make an emacsword just after the cursor uppercase.
3744 emacs
3746 \^[u, \^[U
3747 emacs-capitalize-word
3749 Capitalize the first letter of an emacsword just after the
3750 cursor.
3751 emacs
3753 \^[c, \^[u
3754 emacs-delete-horizontal-space
3756 Delete spaces around the cursor. If any argument was passed,
3757 delete spaces just before the cursor only.
3758 emacs
3760 \^[\\
3761 emacs-just-one-space
3763 Delete spaces around the cursor and leave one space. If an
3764 argument is specified, leave as many spaces as the argument.
3765 emacs
3767 \^[ (Escape followed by a space)
3768 emacs-search-forward
3770 Switch to the emacs search mode and start forward history
3771 search.
3772 emacs
3774 \^S
3775 emacs-search-backward
3777 Switch to the emacs search mode and start backward history
3778 search.
3779 emacs
3781 \^R
3782 History-related commands
3784 oldest-history
3785 Recall the oldest entry in the history. If argument n is
3786 passed, the entry whose number is n is recalled instead. The
3787 cursor position remains unchanged.
3788 newest-history
3790 Recall the newest entry in the history. If argument n is
3791 passed, the entry whose number is n is recalled instead. The
3792 cursor position remains unchanged.
3793 return-history
3795 Return to the initial buffer corresponding to none of existing
3796 history entries. If argument n is passed, the entry whose
3797 number is n is recalled instead. The cursor position remains
3798 unchanged.
3799 oldest-history-bol
3801 Recall the oldest entry in the history and move the cursor to
3802 the beginning of the line. If argument n is passed, the entry
3803 whose number is n is recalled instead.
3804 vi-command
3806 G
3807 newest-history-bol
3809 Recall the newest entry in the history and move the cursor to
3810 the beginning of the line. If argument n is passed, the entry
3811 whose number is n is recalled instead.
3812 return-history-bol
3814 Return to the initial buffer corresponding to none of existing
3815 history entries and move the cursor to the beginning of the
3816 line. If argument n is passed, the entry whose number is n is
3817 recalled instead.
3818 vi-command
3820 g
3821 oldest-history-eol
3823 Recall the oldest entry in the history and move the cursor to
3824 the end of the line. If argument n is passed, the entry whose
3825 number is n is recalled instead.
3826 emacs
3828 \^[<
3829 newest-history-eol
3831 Recall the newest entry in the history and move the cursor to
3832 the end of the line. If argument n is passed, the entry whose
3833 number is n is recalled instead.
3834 return-history-eol
3836 Return to the initial buffer corresponding to none of existing
3837 history entries and move the cursor to the end of the line. If
3838 argument n is passed, the entry whose number is n is recalled
3839 instead.
3840 emacs
3842 \^[>
3843 next-history
3845 Recall the next history entry. The cursor position remains
3846 unchanged.
3847 prev-history
3849 Recall the previous history entry. The cursor position remains
3850 unchanged.
3851 next-history-bol
3853 Recall the next history entry and move the cursor to the
3854 beginning of the line.
3855 vi-command
3857 j, +, \D, \^N
3858 prev-history-bol
3860 Recall the previous history entry and move the cursor to the
3861 beginning of the line.
3862 vi-command
3864 k, -, \U, \^P
3865 next-history-eol
3867 Recall the next history entry and move the cursor to the end of
3868 the line.
3869 vi-insert, emacs
3871 \D, \^N
3872 prev-history-eol
3874 Recall the previous history entry and move the cursor to the
3875 end of the line.
3876 vi-insert, emacs
3878 \U, \^P
3879 search-again
3881 Repeat the last command history search.
3882 vi-command
3884 n
3885 search-again-rev
3887 Repeat the last command history search in the reverse
3888 direction.
3889 vi-command
3891 N
3892 search-again-forward
3894 Repeat the last command history search in the forward
3895 direction.
3896 search-again-backward
3898 Repeat the last command history search in the backward
3899 direction.
3900 beginning-search-forward
3902 Recall the next history entry that starts with the same text as
3903 the text from the beginning of the line up to the current
3904 cursor position. The cursor position remains unchanged.
3905 beginning-search-backward
3907 Recall the previous history entry that starts with the same
3908 text as the text from the beginning of the line up to the
3909 current cursor position. The cursor position remains unchanged.
3910 Search mode commands
3912 srch-self-insert
3913 Insert the input character at the current cursor position.
3914 Characters escaped by escape sequences cannot be inserted.
3915 vi-search, emacs-search
3917 \\
3918 srch-backward-delete-char
3920 Delete the last character in the search text. If the text is
3921 empty:
3922 · like the srch-abort-search command when in the vi search
3924 mode, or
3925 · like the alert command when in the emacs search mode.
3927 vi-search, emacs-search
3929 \B, \?, \^H
3930 srch-backward-delete-line
3932 Delete the whole search text.
3933 vi-search, emacs-search
3935 \$, \^U
3936 srch-continue-forward
3938 Find the next matching history entry.
3939 emacs-search
3941 \^S
3942 srch-continue-backward
3944 Find the previous matching history entry.
3945 emacs-search
3947 \^R
3948 srch-accept-search
3950 Finish the search mode, accepting the result being shown.
3951 vi-search
3953 \^J, \^M
3954 emacs-search
3956 \^J, \^[
3957 srch-abort-search
3959 Abort search and restore the previous buffer contents.
3960 vi-search
3962 \^[
3963 emacs-search
3965 \^G
3966 Escape sequences
3968 In the bindkey built-in, escape sequences are used to represent special
3969 keys such as function keys and arrow keys. Every escape sequence starts
3970 with a backslash (\) and thus there is also an escape sequence for a
3971 backslash itself.
3972 Below are available escape sequences:
3974 \\
3976 Backslash (\)
3977 \B
3979 Backspace
3980 \D
3982 Down arrow
3983 \E
3985 End
3986 \H
3988 Home
3989 \I
3991 Insert (Insert-char, Enter-insert-mode)
3992 \L
3994 Left arrow
3995 \N
3997 Page-down (Next-page)
3998 \P
4000 Page-up (Previous-page)
4001 \R
4003 Right arrow
4004 \U
4006 Up arrow
4007 \X
4009 Delete
4010 \!
4012 INTR
4013 \#
4015 EOF
4016 \$
4018 KILL
4019 \?
4021 ERASE
4022 \^@
4024 Ctrl + @
4025 \^A, \^B, ..., \^Z
4027 Ctrl + A, Ctrl + B, ..., Ctrl + Z
4028 Note that Ctrl + I, Ctrl + J, and Ctrl + M are tab, newline, and
4030 carriage return, respectively.
4031 \^[
4033 Ctrl + [ (Escape)
4034 \^\
4036 Ctrl + \
4037 \^]
4039 Ctrl + ]
4040 \^^
4042 Ctrl + ^
4043 \^_
4045 Ctrl + _
4046 \^?
4048 Ctrl + ? (Delete)
4049 \F00, \F01, ..., \F63
4051 F0, F1, ..., F63
4052 \a1
4054 Top-left on keypad
4055 \a3
4057 Top-right on keypad
4058 \b2
4060 Center on keypad
4061 \bg
4063 Beginning
4064 \bt
4066 Back-tab
4067 \c1
4069 Bottom-left on keypad
4070 \c3
4072 Bottom-right on keypad
4073 \ca
4075 Clear-all-tabs
4076 \cl
4078 Close
4079 \cn
4081 Cancel
4082 \co
4084 Command
4085 \cp
4087 Copy
4088 \cr
4090 Create
4091 \cs
4093 Clear-screen or erase
4094 \ct
4096 Clear-tab
4097 \dl
4099 Delete-line
4100 \ei
4102 Exit-insert-mode
4103 \el
4105 Clear-to-end-of-line
4106 \es
4108 Clear-to-end-of-screen
4109 \et
4111 Enter (Send)
4112 \ex
4114 Exit
4115 \fd
4117 Find
4118 \hp
4120 Help
4121 \il
4123 Insert-line
4124 \ll
4126 Home-down
4127 \me
4129 Message
4130 \mk
4132 Mark
4133 \ms
4135 Mouse event
4136 \mv
4138 Move
4139 \nx
4141 Next-object
4142 \on
4144 Open
4145 \op
4147 Options
4148 \pr
4150 Print (Copy)
4151 \pv
4153 Previous-object
4154 \rd
4156 Redo
4157 \re
4159 Resume
4160 \rf
4162 Ref (Reference)
4163 \rh
4165 Refresh
4166 \rp
4168 Replace
4169 \rs
4171 Restart
4172 \sf
4174 Scroll-forward (Scroll-down)
4175 \sl
4177 Select
4178 \sr
4180 Scroll-backward (Scroll-up)
4181 \st
4183 Set-tab
4184 \su
4186 Suspend
4187 \sv
4189 Save
4190 \ud
4192 Undo
4193 \SE
4195 Shift + End
4196 \SH
4198 Shift + Home
4199 \SI
4201 Shift + Insert
4202 \SL
4204 Shift + Left arrow
4205 \SR
4207 Shift + Right arrow
4208 \SX
4210 Shift + Delete
4211 \Sbg
4213 Shift + Beginning
4214 \Scn
4216 Shift + Cancel
4217 \Sco
4219 Shift + Command
4220 \Scp
4222 Shift + Copy
4223 \Scr
4225 Shift + Create
4226 \Sdl
4228 Shift + Delete-line
4229 \Sel
4231 Shift + End-of-line
4232 \Sex
4234 Shift + Exit
4235 \Sfd
4237 Shift + Find
4238 \Shp
4240 Shift + Help
4241 \Smg
4243 Shift + Message
4244 \Smv
4246 Shift + Move
4247 \Snx
4249 Shift + Next
4250 \Sop
4252 Shift + Options
4253 \Spr
4255 Shift + Print
4256 \Spv
4258 Shift + Previous
4259 \Srd
4261 Shift + Redo
4262 \Sre
4264 Shift + Resume
4265 \Srp
4267 Shift + Replace
4268 \Ssu
4270 Shift + Suspend
4271 \Ssv
4273 Shift + Save
4274 \Sud
4276 Shift + Undo
4277 INTR, EOF, KILL, and ERASE are special characters configured by the
4279 stty command. In a typical configuration, they are sent by typing
4280 Ctrl+C, Ctrl+D, Ctrl+U, and Ctrl+H, respectively, but some
4281 configuration uses Ctrl+? instead of Ctrl+H for ERASE.
4282 Command line completion
4284 By using the complete and complete-next-candidate commands, etc., you
4285 can complete command names, options, and operands. By default, the
4286 complete-next-candidate command is bound with the Tab key in the vi
4287 insert and emacs modes.
4288 Type a few first letters of a command name or pathname and hit the Tab
4290 key, and a list of matching names will be shown. You can choose a
4291 candidate from the list to complete the name by hitting the Tab key
4292 again. If there is only one matching name, no list will be shown and
4293 the name will directly be completed.
4294 If the name to be completed contains characters like * and ?, it is
4296 treated as a pattern. The name on the command line will be directly
4297 substituted with all possible names matching the pattern (you cannot
4298 choose from a list).
4299 Normally, command names are completed with command names and command
4301 arguments with pathnames. However, completion functions can be defined
4302 to refine completion results.
4303 Completion details
4305 When doing completion for the first time after the shell has been
4306 started, the INIT file is loaded as if the command string . -AL
4307 completion/INIT is executed. If the file is not found, it is
4308 silently ignored. This automatic loading is mainly intended for
4309 loading completion functions bundled with the shell, but you can
4310 let the shell load your own functions by putting a file in the load
4311 path.
4312 When completing a command name, the shell executes the
4314 completion//command function and when completing a command
4315 argument, the completion//argument function. If those completion
4316 functions are not defined, the shell just completes with command
4317 names or pathnames. When completing other names, such as the user
4318 name in tilde expansion and the parameter name in parameter
4319 expansion, completion functions are never used: the shell just
4320 completes with user names, parameter names, or whatever applicable.
4321 Completion functions are executed without any arguments. The
4323 following local variables are automatically defined while executing
4324 completion functions:
4325 IFS
4327 The value is the three characters of a space, a tab, and a
4328 newline, which are the default value of the variable.
4329 WORDS
4331 This variable is an array whose elements are a command name and
4332 arguments that have already been entered before the argument
4333 being completed. When completing a command name, the array has
4334 no elements.
4335 TARGETWORD
4337 The value is the partially entered command name or argument
4338 that is being completed.
4339 Completion candidates are generated by executing the complete
4341 built-in during a completion function.
4342 Completion functions must not perform I/O to the terminal, or
4344 displayed text will be corrupted. Completion functions should run
4345 as quickly as possible for better user experience.
4346 While a completion function is being executed:
4348 · the POSIXly-correct mode and the err-return option are
4350 temporarily disabled,
4351 · the err-exit option is temporarily ignored, and
4353 · traps are not executed.
4355 Command line prediction
4357 This is an experimental feature. When the le-predict option is enabled,
4358 the shell automatically tries to predict a command string fragment that
4359 follows the part of the command you have already typed in line-editing.
4360 For example, assume you have once typed the command ls Documents. Next
4362 time you start typing ls Doc, the shell will show uments just after the
4363 cursor. If you are satisfied with this suggestion, you can move the
4364 cursor to the right by the forward-char or any other motion commands
4365 instead of typing the rest of the command. After moving the cursor
4366 after the last s, you can use the accept-line command to execute the
4367 command. You can also use the accept-prediction command to immediately
4368 execute the suggested command without moving the cursor.
4369 To distinguish the typed part and the predicted part of a command
4371 string, you can change the font style of the typed part by setting the
4372 PS1S variable. Customizing the font style of the predicted part is not
4373 (yet) supported; it is always shown in the default style.
4374 When you move the cursor to the right, the predicted part up to the
4376 cursor becomes the typed part as if you actually typed it. Moving the
4377 cursor to the left does not turn the typed part back to the prediction.
4378 Use deletion commands such as backward-delete-char to delete typed
4379 command fragment.
4380 The predicted part of the command is shown only when the cursor is at
4382 the end of the typed part.
4383 By default, the predicted part is shown after you start typing a
4385 command string. By enabling the le-predict-empty option, the predicted
4386 part is also shown before you type the first character of the command
4387 string.
4388 The prediction algorithm suggests command fragments on the basis of the
4390 command history. The algorithm considers recent history entries more
4391 probable. It also takes command succession patterns into account. A
4392 predicted command fragment is not always a complete valid command
4393 because less probable part of the fragment is excluded from prediction.
4394
4396 Yash behaves as defined in POSIX.1-2008, Shell & Utilities for the most
4397 part, but some functionalities disobey POSIX for usability. When full
4398 POSIX-conformance is needed, you can enable the POSIXly-correct mode to
4399 make yash obey POSIX as much as possible.
4400 If yash is started with the name “sh”, the POSIXly-correct mode is
4402 automatically enabled. The -o posixly-correct command-line option also
4403 enables the POSIXly-correct mode. After yash has been started, the
4404 POSIXly-correct mode can be enabled by executing the command string set
4405 -o posixly-correct.
4406 When the POSIXly-correct mode is on, yash not only tries to obey the
4408 requirements by POSIX, but also treats as errors most conditions where
4409 the behavior is undefined or unspecified by POSIX. As a result, most
4410 yash-specific functionalities are disabled in the POSIXly-correct mode.
4411 Below is the complete list of the behavioral differences between when
4413 yash is in the POSIXly-correct mode and when not. When the
4414 POSIXly-correct mode is enabled:
4415 · Different initialization scripts are used.
4417 · If the shell was started with the -c option, sh -c (instead of yash
4419 -c) is printed as the script pathname on a syntax error.
4420 · Global aliases are not substituted.
4422 · Nested commands in a compound command must not be empty.
4424 · The for loop iteration variable is created as global, regardless of
4426 the for-local shell option. The variable must have a portable
4427 (ASCII-only) name.
4428 · The first pattern in a case command cannot be esac.
4430 · The ! keyword cannot be followed by ( without any whitespaces
4432 in-between.
4433 · The double-bracket command cannot be used.
4435 · The function keyword cannot be used for function definition. The
4437 function must have a portable (ASCII-only) name.
4438 · Simple commands cannot assign to arrays.
4440 · Changing the value of the LC_CTYPE variable after the shell has
4442 been initialized does not affect the shell’s locale.
4443 · The RANDOM variable cannot be used to generate random numbers.
4445 · Tilde expansion only expands ~ and ~username.
4447 · Parameter expansion cannot be nested. No indexes or modifiers with
4449 word2 are allowed.
4450 · The commands in a command substitution of the form $(commands) are
4452 parsed every time the substitution is executed.
4453 · In arithmetic expansion, fractional numbers and the ++ and --
4455 operators cannot be used. All variables must be numeric.
4456 · The operand of a redirection cannot be the integer prefix to a next
4458 redirection operator.
4459 · A compound command with a redirection cannot be immediately
4461 followed by a keyword like } and fi.
4462 · In a redirection to a file, if the pathname expansion yielded more
4464 than one or no pathname, it is not immediately treated as an error.
4465 Instead, the shell tries to treat the word before the expansion as
4466 a pathname.
4467 · A file descriptor must be readable and writable when duplicated by
4469 the <& and >& redirection operator, respectively.
4470 · Socket redirection, here strings, pipe redirection, and process
4472 redirection cannot be used.
4473 · When executing a simple command, failure in command search does not
4475 trigger execution of the COMMAND_NOT_FOUND_HANDLER variable.
4476 · In command search, a regular built-in needs to have a corresponding
4478 external command for the built-in to be found.
4479 · Some built-ins behave differently. Especially, long command-line
4481 options (as well as some others) cannot be used.
4482 · A non-interactive shell exits when a special built-in is given a
4484 syntactically wrong arguments or when an error occurs in assignment
4485 or redirection with a special built-in.
4486 · An interactive shell does not execute the PROMPT_COMMAND variable
4488 before printing a prompt. The values of the PS1, PS2, and PS4
4489 variables are parsed differently. Prompt variables with a YASH_
4490 prefix (e.g. YASH_PS1) are not used.
4491 · In mail checking, a notification message is printed if the file has
4493 been modified, regardless of whether the file is empty.
4494
4496 How can I use Unicode (non-ASCII) characters?
4497 You need to set locale environment variables to enable Unicode
4498 character support.
4499 If the variables have already been configured for your preference, you
4501 probably don’t have to do anything. To check the current locale
4502 configurations, you can use the locale command:
4503 $ locale
4505 LANG=
4506 LC_CTYPE="en_US.utf8"
4507 LC_NUMERIC="en_US.utf8"
4508 LC_TIME="en_US.utf8"
4509 LC_COLLATE="en_US.utf8"
4510 LC_MONETARY="en_US.utf8"
4511 LC_MESSAGES="en_US.utf8"
4512 LC_PAPER="en_US.utf8"
4513 LC_NAME="en_US.utf8"
4514 LC_ADDRESS="en_US.utf8"
4515 LC_TELEPHONE="en_US.utf8"
4516 LC_MEASUREMENT="en_US.utf8"
4517 LC_IDENTIFICATION="en_US.utf8"
4518 LC_ALL=en_US.utf8
4519 In this example, the locale command shows that all the locale setting
4521 categories are configured for the English language, the United States
4522 region, and the UTF-8 encoding.
4523 If the current configuration does not seem to match your preference,
4525 set the LC_ALL variable like this:
4526 export LC_ALL=en_US.utf8
4528 If you want to use other languages, regions, or encodings, you have to
4530 set the variable to a different value. Please consult your OS’s
4531 documentation to learn how to configure these variables in detail.
4532 If you want to apply the same configuration every time you start yash,
4534 write the command in ~/.yashrc or ~/.yash_profile.
4535 If yash still rejects Unicode characters being entered, see the section
4537 below regarding line-editing.
4538 Line-editing does not work
4540 First, type echo $TERM and see if it prints a sane value. xterm is the
4541 safest value that should work on any existing environment. Colored
4542 versions like xterm-16color and other terminal types like rxvt and
4543 vt100 may also work. All possible values can be listed by the toe
4544 command. It’s most desirable to choose a value that matches the actual
4545 terminal type you are using, but it might not work if the terminal type
4546 you chose is not supported on the system on which yash is running. If
4547 so, try changing the TERM value by export TERM=xterm, for example, to
4548 find a value that works.
4549 If line-editing works but you have trouble entering Unicode (non-ASCII)
4551 characters, try enabling the le-no-conv-meta option by set -o
4552 le-no-conv-meta.
4553
4555 This chapter defines the syntax of the shell command language.
4556 Note
4558 Some of the syntactic features described below are not supported in
4559 the POSIXly-correct mode.
4560 Tokenization
4562 The characters of the input source code are first delimited into
4563 tokens. Tokens are delimited so that the earlier token spans as long as
4564 possible. A sequence of one or more unquoted blank characters delimits
4565 a token.
4566 The following tokens are the operator tokens:
4568 & && ( ) ; ;; | || < << <& <( <<- <<< <> > >> >& >( >>| >| (newline)
4570 Note
4572 Unlike other programming languages, the newline operator is a token
4573 rather than a white space.
4574 Characters that are not blank nor part of an operator compose a word
4576 token. Words are parsed by the following parsing expression grammar:
4577 Word
4579 (WordElement / !SpecialChar .)+
4580 WordElement
4582 \ . /
4583 ' (!' .)* ' /
4585 " QuoteElement* " /
4587 Parameter /
4589 Arithmetic /
4591 CommandSubstitution
4593 QuoteElement
4595 \ ([$`"\] / <newline>) /
4596 Parameter /
4598 Arithmetic /
4600 CommandSubstitutionQuoted /
4602 ![`"\] .
4604 Parameter
4606 $ [@*#?-$! [:digit:]] /
4607 $ PortableName /
4609 $ ParameterBody
4611 PortableName
4613 ![0-9] [0-9 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]+
4614 ParameterBody
4616 { ParameterNumber? (ParameterName / ParameterBody / $ ParameterBody
4617 / Arithmetic / CommandSubstitution) ParameterIndex?
4618 ParameterMatch? }
4619 ParameterNumber
4621 # ![}+=:/%] !([-?#] !})
4622 ParameterName
4624 [@*#?-$!] /
4625 [[:alnum:] _]+
4627 ParameterIndex
4629 [ ParameterIndexWord (, ParameterIndexWord)? ]
4630 ParameterIndexWord
4632 (WordElement / !["'],] .)+
4633 ParameterMatch
4635 :? [-+=?] ParameterMatchWord /
4636 (# / ## / % / %%) ParameterMatchWord /
4638 (:/ / / [#%/]?) ParameterMatchWordNoSlash (/ ParameterMatchWord)?
4640 ParameterMatchWord
4642 (WordElement / !["'}] .)*
4643 ParameterMatchWordNoSlash
4645 (WordElement / !["'/}] .)*
4646 Arithmetic
4648 $(( ArithmeticBody* ))
4649 ArithmeticBody
4651 \ . /
4652 Parameter /
4654 Arithmetic /
4656 CommandSubstitution /
4658 ( ArithmeticBody ) /
4660 ![`()] .
4662 CommandSubstitution
4664 $( CompleteProgram ) /
4665 ` CommandSubstitutionBody* `
4667 CommandSubstitutionQuoted
4669 $( CompleteProgram ) /
4670 ` CommandSubstitutionBodyQuoted* `
4672 CommandSubstitutionBody
4674 \ [$`\] /
4675 !` .
4677 CommandSubstitutionBodyQuoted
4679 \ [$`\`] /
4680 !` .
4682 SpecialChar
4684 [|&;<>()`\"' [:blank:]] / <newline>
4685 The set of terminals of the grammar is the set of characters that can
4687 be handled on the environment in which the shell is run (a.k.a.
4688 execution character set), with the exception that the set does not
4689 contain the null character ('\0').
4690 Strictly speaking, the definition above is not a complete parsing
4692 expression grammar because the rule for CommandSubstitution (Quoted)
4693 depends on CompleteProgram which is a non-terminal of the syntax.
4694 Token classification
4696 After a word token is delimited, the token may be further
4697 classified as an IO_NUMBER token, reserved word, name word,
4698 assignment word, or just normal word. Classification other than the
4699 normal word is applied only when applicable in the context in which
4700 the word appears. See Tokens and keywords for the list of the
4701 reserved words (keywords) and the context in which a word may be
4702 recognized as a reserved word.
4703 A token is an IO_NUMBER token iff it is composed of digit
4705 characters only and immediately followed by < or >.
4706 An assignment token is a token that starts with a name followed by
4708 =:
4709 AssignmentWord
4711 AssignmentPrefix Word
4712 AssignmentPrefix
4714 Name =
4715 Name
4717 ![[:digit:]] \[[:alnum:] _]+
4718 Comments
4720 A comment begins with # and continues up to (but not including) the
4721 next newline character. Comments are treated like a blank character
4722 and do not become part of a token. The initial # of a comment must
4723 appear as if it would otherwise be the first character of a word
4724 token; Other #s are just treated as part of a word token.
4725 Comment
4727 # (!<newline> .)*
4728 Syntax
4730 After tokens have been delimited, the sequence of the tokens is parsed
4731 according to the context-free grammar defined below, where *, +, and ?
4732 should be interpreted in the same manner as standard regular
4733 expression:
4734 CompleteProgram
4736 NL* | CompoundList
4737 CompoundList
4739 NL* AndOrList ((; | & | NL) CompleteProgram)?
4740 AndOrList
4742 Pipeline ((&& | ||) NL* Pipeline)*
4743 Pipeline
4745 !? Command (| NL* Command)*
4746 Command
4748 CompoundCommand Redirection* |
4749 FunctionDefinition |
4751 SimpleCommand
4753 CompoundCommand
4755 Subshell |
4756 Grouping |
4758 IfCommand |
4760 ForCommand |
4762 WhileCommand |
4764 CaseCommand |
4766 DoubleBracketCommand |
4768 FunctionCommand
4770 Subshell
4772 ( CompoundList )
4773 Grouping
4775 { CompoundList }
4776 IfCommand
4778 if CompoundList then CompoundList (elif CompoundList then
4779 CompoundList)* (else CompoundList)? fi
4780 ForCommand
4782 for Name ((NL* in Word*)? (; | NL) NL*)? do CompoundList done
4783 WhileCommand
4785 (while | until) CompoundList do CompoundList done
4786 CaseCommand
4788 case Word NL* in NL* CaseList? esac
4789 CaseList
4791 CaseItem (;; NL* CaseList)?
4792 CaseItem
4794 (? Word (| Word)* ) CompleteProgram
4795 DoubleBracketCommand
4797 [[ Ors ]]
4798 Ors
4800 Ands (|| Ands)*
4801 Ands
4803 Nots (&& Nots)*
4804 Nots
4806 !* Primary
4807 Primary
4809 (-b | -c | -d | -e | -f | -G | -g | -h | -k | -L | -N | -n | -O |
4810 -o | -p | -r | -S | -s | -t | -u | -w | -x | -z) Word |
4811 Word (-ef | -eq | -ge | -gt | -le | -lt | -ne | -nt | -ot | -veq |
4813 -vge | -vgt | -vle | -vlt | -vne | = | == | === | =~ | != | !== | <
4814 | >) Word |
4815 ( Ors ) |
4817 Word
4819 FunctionCommand
4821 function Word (( ))? NL* CompoundCommand Redirection*
4822 FunctionDefinition
4824 Name ( ) NL* CompoundCommand Redirection*
4825 SimpleCommand
4827 (Assignment | Redirection) SimpleCommand? |
4828 Word (Word | Redirection)*
4830 Assignment
4832 AssignmentWord |
4833 AssignmentPrefix( NL* (Word NL*)* )
4835 Redirection
4837 IO_NUMBER? RedirectionOperator Word |
4838 IO_NUMBER? <( CompleteProgram ) |
4840 IO_NUMBER? >( CompleteProgram )
4842 RedirectionOperator
4844 < | <> | > | >| | >> | >>| | <& | >& | << | <<- | <<<
4845 NL
4847 <newline>
4848 In the rule for Primary, Word tokens must not be ]]. Additionally, if a
4850 Primary starts with a Word, it must not be any of the possible unary
4851 operators allowed in the rule.
4852 In the rule for SimpleCommand, a Word token is accepted only when the
4854 token cannot be parsed as the first token of an Assignment.
4855 In the rule for Assignment, the ( token must immediately follow the
4857 AssignmentPrefix token, without any blank characters in between.
4858 Here-document contents do not appear as part of the grammar above. They
4860 are parsed just after the newline (NL) token that follows the
4861 corresponding redirection operator.
4862 Alias substitution
4864 Word tokens are subject to alias substitution.
4865 · If a word is going to be parsed as a Word of a SimpleCommand,
4867 the word is subjected to alias substitution of any kind (normal
4868 and global aliases).
4869 · If a word is the next token after the result of an alias
4871 substitution and the substitution string ends with a blank
4872 character, then the word is also subjected to alias
4873 substitution of any kind.
4874 · Other words are subjected to global alias substitution unless
4876 the shell is in the POSIXly-correct mode.
4877 Tokens that are classified as reserved words are not subject to
4879 alias substitution.
4880
4882 The alias built-in defines and/or prints aliases.
4883 Syntax
4885 · alias [-gp] [name[=value]...]
4886 Description
4888 The alias built-in defines and/or prints aliases as specified by
4889 operands. The printed aliases can be used as (part of) shell commands.
4890 The built-in prints all currently defined aliases when given no
4891 operands.
4892 Options
4894 -g, --global
4895 With this option, aliases are defined as global aliases; without
4896 this option, as normal aliases.
4897 -p, --prefix
4899 With this option, aliases are printed in a full command form like
4900 alias -g foo='bar'. Without this option, only command operands are
4901 printed like foo='bar'.
4902 Operands
4904 name
4905 The name of an alias that should be printed.
4906 name=value
4908 The name and value of an alias that is being defined.
4909 Exit status
4911 The exit status of the alias built-in is zero unless there is any
4912 error.
4913 Notes
4915 The characters that cannot be used in an alias name are the space, tab,
4916 newline, and any of =$<>\'"`;&|()#. You can use any characters in an
4917 alias value.
4918 The alias built-in is a semi-special built-in.
4920 The POSIX standard defines no options for the alias built-in, thus no
4922 options are available in the POSIXly correct mode.
4923
4925 The array built-in prints or modifies arrays.
4926 Syntax
4928 · array
4929 · array name [value...]
4931 · array -d name [index...]
4933 · array -i name index [value...]
4935 · array -s name index value
4937 Description
4939 When executed without any option or operands, the built-in prints all
4940 array definitions to the standard output in a form that can be parsed
4941 as commands.
4942 When executed with name and values (but without an option), the
4944 built-in sets the values as the values of the array named name.
4945 With the -d (--delete) option, the built-in removes the indexth values
4947 of the array named name. The number of values in the array will be
4948 decreased by the number of the indexes specified. If the indexth value
4949 does not exist, it is silently ignored.
4950 With the -i (--insert) option, the built-in inserts values into the
4952 array named name. The number of values in the array will be increased
4953 by the number of the values specified. The values are inserted between
4954 the indexth and next values. If index is zero, the values are inserted
4955 before the first value. If index is larger than the number of values in
4956 the array, the values are appended after the last element.
4957 With the -s (--set) option, the built-in sets value as the indexth
4959 value of the array named name. The array must have at least index
4960 values.
4961 Options
4963 -d, --delete
4964 Delete array values.
4965 -i, --insert
4967 Insert array values.
4968 -s, --set
4970 Set an array value.
4971 Operands
4973 name
4974 The name of an array to operate on.
4975 index
4977 The index to an array element. The first element has the index of
4978 1.
4979 value
4981 A string to which the array element is set.
4982 Exit status
4984 The exit status of the array built-in is zero unless there is any
4985 error.
4986 Notes
4988 The array built-in is not defined in the POSIX standard.
4989 The command array name value... is equivalent to the assignment
4991 name=(value...).
4992
4994 The bg built-in resumes a job in the background.
4995 Syntax
4997 · bg [job...]
4998 Description
5000 The bg built-in sends the SIGCONT signal to the specified job. As a
5001 result, the job is resumed in the background (if it has been
5002 suspended).
5003 The name of the job is printed when the job is resumed.
5005 The built-in can be used only when job control is enabled.
5007 Operands
5009 job
5010 The job ID of the job to be resumed.
5011 More than one job can be specified at a time. The current job is
5013 resumed if none is specified.
5014 The percent sign (%) at the beginning of a job ID can be omitted if
5016 the shell is not in the POSIXly-correct mode.
5017 Exit status
5019 The exit status of the bg built-in is zero unless there is any error.
5020 Notes
5022 The bg built-in is a semi-special built-in.
5023 The POSIX standard provides that the built-in shall have no effect when
5025 the job is already running. The bg built-in of yash, however, always
5026 sends the SIGCONT signal to the job.
5027
5029 The bindkey built-in prints or modifies key bindings used in
5030 line-editing.
5031 Syntax
5033 · bindkey -aev [key [command]]
5034 · bindkey -l
5036 Description
5038 When executed with the -l (--list) option, the built-in lists all
5039 available line-editing commands to the standard output.
5040 When executed with one of the other options, the built-in prints or
5042 modifies key bindings for the editing mode specified by the option:
5043 · Without key or command, all currently defined bindings are printed
5045 to the standard output in a form that can be parsed as commands
5046 that restore the current bindings when executed.
5047 · With key but without command, only the binding for the given key is
5049 printed.
5050 · With key and command, key is bound to command.
5052 Options
5054 -a, --vi-command
5055 Print or modify bindings for the vi command mode.
5056 -e, --emacs
5058 Print or modify bindings for the emacs mode.
5059 -v, --vi-insert
5061 Print or modify bindings for the vi insert mode.
5062 Operands
5064 key
5065 A character sequence of one or more keys that is bound to an
5066 editing command. The sequence may include escape sequences.
5067 command
5069 A line-editing command to which key is bound. If command is a
5070 single hyphen (-), key is unbound.
5071 Exit status
5073 The exit status of the bindkey built-in is zero unless there is any
5074 error.
5075 Notes
5077 The bindkey built-in is a semi-special built-in. In the POSIX standard,
5078 it is defined as a command with unspecified behavior.
5079
5081 The break built-in aborts a loop being executed.
5082 Syntax
5084 · break [nest]
5085 · break -i
5087 Description
5089 When executed without the -i (--iteration) option, the built-in aborts
5090 a currently executed for, while, or until loop. When executed in nested
5091 loops, it aborts the nestth innermost loop. The default nest is one. If
5092 the number of currently executed nested loops is less than nest, the
5093 built-in aborts the outermost loop.
5094 When executed with the -i (--iteration) option, the built-in aborts the
5096 currently executed (innermost) iterative execution.
5097 Options
5099 -i, --iteration
5100 Abort an iterative execution instead of a loop.
5101 Operands
5103 nest
5104 The number of loops to abort, which must be a positive integer.
5105 Exit status
5107 The exit status of the break built-in is:
5108 · zero if a loop was successfully aborted.
5110 · that of the command that was executed just before the break
5112 built-in if an iterative execution was successfully aborted.
5113 Notes
5115 The break built-in is a special built-in.
5116 The POSIX standard defines no options for the break built-in; the
5118 built-in accepts no options in the POSIXly-correct mode.
5119 Treatment of currently executed loops that are not lexically enclosing
5121 the break built-in is unspecified in POSIX. Examples of such loops
5122 include:
5123 · A loop invoking a function in which the break built-in is used.
5125 · A loop in which a trap action is executed in which the break
5127 built-in is used.
5128 Yash does not allow breaking such loops.
5130
5132 The cd built-in changes the working directory.
5133 Syntax
5135 · cd [-L|-P] [directory]
5136 Description
5138 The cd built-in changes the working directory to the directory
5139 specified by the operand.
5140 The pathname of the new working directory is assigned to the PWD
5142 variable, whose previous value is again assigned to the OLDPWD
5143 variable. The new PWD value will not contain any . or .. components
5144 except when the shell is in the POSIXly-correct mode and the new
5145 pathname begins with /...
5146 If directory is a relative path that does not start with ‘.’ or ‘..’,
5148 paths in the CDPATH variable are searched to find a new working
5149 directory. The search is done in a manner similar to the last step of
5150 command search, but a directory is sought instead of an executable
5151 regular file. If a new working directory was found from CDPATH, its
5152 pathname is printed to the standard output. If no applicable directory
5153 was found in the search, directory is simply treated as a pathname
5154 relative to the current working directory.
5155 If the working directory was successfully changed, the value of the
5157 YASH_AFTER_CD variable is executed as a command unless the shell is in
5158 the POSIXly-correct mode. If the variable is an array, its values are
5159 executed iteratively (cf. eval built-in).
5160 Options
5162 -L, --logical
5163 Symbolic links in the pathname of the new working directory are not
5164 resolved. The new value of the PWD may include pathname components
5165 that are symbolic links.
5166 -P, --physical
5168 Symbolic links in the pathname of the new working directory are
5169 resolved. The new value of the PWD variable never includes pathname
5170 components that are symbolic links.
5171 --default-directory=directory
5173 If this option is specified and the directory operand is omitted,
5174 the argument to this option is used for the directory operand. If
5175 the directory operand is specified, this option is ignored.
5176 The -L (--logical) and -P (--physical) options are mutually exclusive:
5178 only the last specified one is effective. If neither is specified, -L
5179 is assumed.
5180 Operands
5182 directory
5183 The pathname of the new working directory.
5184 If directory is a single hyphen (‘-’), the value of the OLDPWD
5186 variable is assumed for the new directory pathname, which is
5187 printed to the standard output.
5188 If directory is omitted, the working directory is changed to the
5190 directory specified by the --default-directory=... option. If that
5191 option is not specified either, the default is the home directory.
5192 Exit status
5194 The exit status of the cd built-in is zero if the working directory was
5195 successfully changed and non-zero if there was an error.
5196 Notes
5198 The cd built-in is a semi-special built-in.
5199 The POSIX standard does not define the use of the YASH_AFTER_CD
5201 variable or the --default-directory=... option. The standard does not
5202 allow using an option with a single hyphen operand.
5203 The exit status of the commands in the YASH_AFTER_CD variable does not
5205 affect that of the cd built-in.
5206
5208 The colon built-in does nothing.
5209 Syntax
5211 · : [argument...]
5212 Description
5214 The colon built-in does nothing. Any command line arguments are
5215 ignored.
5216 Exit status
5218 The exit status of the colon built-in is zero.
5219 Notes
5221 The colon built-in is a special built-in.
5222 Arguments are expanded and redirections are performed as usual. The
5224 colon and true built-ins have the same effect, but colon is a special
5225 built-in while true is a semi-special.
5226
5228 The command built-in executes or identifies a command.
5229 Syntax
5231 · command [-befp] command [argument...]
5232 · command -v|-V [-abefkp] command...
5234 Description
5236 Without the -v (--identify) or -V (--verbose-identify) option, the
5237 built-in executes command with arguments in the same manner as the last
5238 step of execution of simple commands. The command is treated as a
5239 built-in or external command or a function according to the options
5240 specified to the command built-in. The shell does not exit on argument
5241 syntax error etc. even if the command is a special built-in
5242 With the -v (--identify) option, command is identified. If the command
5244 is found in $PATH, its full pathname is printed. If it is a keyword,
5245 function, or built-in that is not found in $PATH, the command name is
5246 simply printed. If it is an alias, it is printed in the form like alias
5247 ll='ls -l'. If the command is not found, nothing is printed and the
5248 exit status is non-zero.
5249 The -V (--verbose-identify) option is similar to the -v (--identify)
5251 option, but the output format is more human-friendly.
5252 Options
5254 -a, --alias
5255 Search for the command as an alias. Must be used with the -v
5256 (--identify) or -V (--verbose-identify) option.
5257 -b, --builtin-command
5259 Search for the command as a built-in.
5260 -e, --external-command
5262 Search for the command as an external command.
5263 -f, --function
5265 Search for the command as a function.
5266 -k, --keyword
5268 Search for the command as a keyword. Must be used with the -v
5269 (--identify) or -V (--verbose-identify) option.
5270 -p, --standard-path
5272 Search the system’s default PATH instead of the current $PATH.
5273 -v, --identify
5275 Identify commands and print in the format defined in the POSIX
5276 standard.
5277 -V, --verbose-identify
5279 Identify commands and print in a human-friendly format.
5280 If none of the -a (--alias), -b (--builtin-command), -e
5282 (--external-command), -f (--function), and -k (--keyword) options is
5283 specified, the following defaults are assumed:
5284 Without the -v (--identify) or -V (--verbose-identify) option
5286 -b -e
5287 With the -v (--identify) or -V (--verbose-identify) option
5289 -a -b -e -f -k
5290 Operands
5292 command
5293 A command to be executed or identified.
5294 argument...
5296 Arguments passed to the executed command.
5297 Exit status
5299 The exit status of the command built-in is:
5300 Without the -v (--identify) or -V (--verbose-identify) option
5302 the exit status of the executed command.
5303 With the -v (--identify) or -V (--verbose-identify) option
5305 zero unless there is any error.
5306 Notes
5308 The command built-in is a semi-special built-in.
5309 In the POSIXly-correct mode, options other than -p, -v, and -V cannot
5311 be used and at most one command can be specified. The POSIX standard
5312 does not allow specifying both -v and -V together, but yash does (only
5313 the last specified one is effective).
5314
5316 The complete built-in generates completion candidates. This built-in
5317 can only be executed from completion functions during command line
5318 completion.
5319 Syntax
5321 · complete [-A pattern] [-R pattern] [-T] [-P prefix] [-S suffix]
5322 [-abcdfghjkuv] [[-O] [-D description] word...]
5323 Description
5325 The built-in generates completion candidates according to the specified
5326 arguments. No matter how candidates are generated, only candidates that
5327 match the word being completed are generated.
5328 Options
5330 -A pattern, --accept=pattern
5331 Only accept candidates that match the pattern specified by this
5332 option. When more than one of this option is specified, only
5333 candidates that match all of the patterns are generated.
5334 -D description, --description=description
5336 Give a description of the word candidates. The description is shown
5337 beside the candidates in the candidate list.
5338 -O, --option
5340 The candidates are treated as command line options. A hyphen is
5341 prepended to each candidate that is treated as an option.
5342 -P prefix, --prefix=prefix
5344 Ignore prefix of the word being completed when generating
5345 candidates. The specified prefix must be initial part of the word.
5346 If the word being completed is file:///home/user/docume for
5348 example, the command line complete -P file:// -f will generate
5349 pathname candidates that complete /home/user/docume.
5350 -R pattern, --reject=pattern
5352 Reject candidates that match the pattern specified by this option.
5353 When more than one of this option is specified, only candidates
5354 that match none of the patterns are generated.
5355 -S suffix, --suffix=suffix
5357 Append suffix to each generated candidate.
5358 -T, --no-termination
5360 Do not append a space after the word is completed. Without this
5361 option, a space is appended to the completed word so that you do
5362 not have to enter a space before the next word.
5363 Options that select candidate types
5365 -a, --alias
5366 Aliases. (same as --normal-alias --global-alias)
5367 --array-variable
5369 Arrays.
5370 --bindkey
5372 Line-editing commands the bindkey built-in accepts.
5373 -b, --builtin-command
5375 Built-in commands. (same as --special-builtin
5376 --semi-special-builtin --regular-builtin)
5377 -c, --command
5379 Commands. (same as --builtin-command --external-command
5380 --function)
5381 -d, --directory
5383 Directories.
5384 --dirstack-index
5386 Valid indices of the directory stack.
5387 --executable-file
5389 Executable regular files.
5390 --external-command
5392 External commands.
5393 -f, --file
5395 Files (including directories).
5396 --finished-job
5398 Job IDs of finished jobs.
5399 --function
5401 Functions.
5402 --global-alias
5404 Global aliases.
5405 -g, --group
5407 User groups.
5408 -h, --hostname
5410 Host names.
5411 -j, --job
5413 Job IDs.
5414 -k, --keyword
5416 Keywords.
5417 --normal-alias
5419 Normal aliases.
5420 --regular-builtin
5422 Regular built-in commands.
5423 --running-job
5425 Job IDs of jobs that are being executed.
5426 --scalar-variable
5428 Variables that are not arrays.
5429 --semi-special-builtin
5431 Semi-special built-in commands.
5432 --signal
5434 Signals.
5435 --special-builtin
5437 Special built-in commands.
5438 --stopped-job
5440 Job IDs of jobs that are suspended.
5441 -u, --username
5443 Users' log-in names.
5444 -v, --variable
5446 Variables.
5447 If the -d (--directory) option is specified without the -f (--file)
5449 option, the -S / -T options are assumed.
5450 Generated candidates for job IDs do not have leading percent signs
5452 (%). If the word being completed starts with a percent sign, the -P
5453 % option should be specified.
5454 Operands
5456 Operands are treated as completion candidates.
5457 Exit status
5459 The exit status of the built-in is zero if one or more candidates were
5460 generated, one if no candidates were generated, or larger than one if
5461 an error occurred.
5462 Notes
5464 The complete built-in is a semi-special built-in. In the POSIX
5465 standard, it is defined as a command with unspecified behavior.
5466
5468 The continue built-in skips an iteration of a loop being executed.
5469 Syntax
5471 · continue [nest]
5472 · continue -i
5474 Description
5476 When executed without the -i (--iteration) option, the built-in aborts
5477 the current iteration of for, while, or until loop and starts the next
5478 iteration of the loop. When executed in nested loops, it affects the
5479 nestth innermost loop. The default nest is one. If the number of
5480 currently executed nested loops is less than nest, the built-in affects
5481 the outermost loop.
5482 When executed with the -i (--iteration) option, the built-in aborts the
5484 current iteration of (innermost) iterative execution.
5485 Options
5487 -i, --iteration
5488 Skip an iterative execution instead of a loop.
5489 Operands
5491 nest
5492 The nestth innermost loop is affected. nest must be a positive
5493 integer.
5494 Exit status
5496 The exit status of the continue built-in is:
5497 · zero if loop iteration was successfully skipped.
5499 · that of the command that was executed just before the continue
5501 built-in if iterative execution was successfully skipped.
5502 Notes
5504 The continue built-in is a special built-in.
5505 The POSIX standard defines no options for the continue built-in; the
5507 built-in accepts no options in the POSIXly-correct mode.
5508 Treatment of currently executed loops that are not lexically enclosing
5510 the continue built-in is unspecified in POSIX. Examples of such loops
5511 include:
5512 · A loop invoking a function in which the continue built-in is used
5514 · A loop in which a trap action is executed in which the continue
5516 built-in is used
5517 Yash does not allow continuing such loops.
5519
5521 The dirs built-in prints the contents of the directory stack.
5522 Syntax
5524 · dirs [-cv] [index..]
5525 Description
5527 The directory stack is a feature that records history of working
5528 directories. You can use the pushd built-in to save a working directory
5529 in the directory stack, the popd built-in to recall the saved working
5530 directory, and the dirs built-in to see the stack contents. Those
5531 built-ins use the DIRSTACK array and the PWD variable to save the stack
5532 contents. Modifying the array means modifying the stack contents.
5533 Directory stack entries are indexed by signed integers. The entry of
5535 index +0 is the current working directory, +1 is the last saved
5536 directory, +2 is the second last, and so on. Negative indices are in
5537 the reverse order: the entry of index -0 is the first saved directory,
5538 -1 is the second, and -n is the current working directory if the stack
5539 has n entries,
5540 When executed without the -c (--clear) option, the dirs built-in prints
5542 the current contents of the directory stack to the standard output.
5543 With the -c (--clear) option, the built-in clears the directory stack.
5544 Options
5546 -c, --clear
5547 Clear the directory stack contents except for the current working
5548 directory, which has index +0.
5549 -v, --verbose
5551 Print indices when printing stack contents.
5552 Operands
5554 index
5555 The index of a stack entry to be printed.
5556 You can specify more than one index. If you do not specify any
5558 index, all the entries are printed.
5559 Exit status
5561 The exit status of the dirs built-in is zero unless there is any error.
5562 Notes
5564 The dirs built-in is a semi-special built-in. In the POSIX standard, it
5565 is defined as a command with unspecified behavior.
5566
5568 The disown built-in removes jobs.
5569 Syntax
5571 · disown [-a] [job...}
5572 Description
5574 The disown built-in removes the specified jobs from the job list. The
5575 removed jobs will no longer be job-controlled, but the job processes
5576 continue execution (unless they have been suspended).
5577 Options
5579 -a, --all
5580 Removes all jobs.
5581 Operands
5583 job
5584 The job ID of the job to be removed.
5585 You can specify more than one job ID. If you do not specify any job
5587 ID, the current job is removed. If the shell is not in the
5588 POSIXly-correct mode, the %-prefix of the job ID can be omitted.
5589 Exit status
5591 The exit status of the disown built-in is zero unless there is any
5592 error.
5593 Notes
5595 The disown built-in is a semi-special built-in. In the POSIX standard,
5596 it is defined as a command with unspecified behavior.
5597
5599 The dot built-in reads a file and executes commands in it.
5600 Syntax
5602 · . [-AL] file [argument...]
5603 Description
5605 The dot built-in reads the specified file, parses its contents as
5606 commands, and executes them in the current command execution
5607 environment.
5608 If arguments are specified, positional parameters are temporarily set
5610 to them. The positional parameters will be restored when the dot
5611 built-in finishes. If no arguments are specified, the positional
5612 parameters are not changed.
5613 If file does not contain any slashes, the shell searches $PATH for a
5615 readable (but not necessarily executable) shell script file whose name
5616 is file in the same manner as command search. If no such file was
5617 found, the shell searches the current working directory for a file
5618 unless in the POSIXly-correct mode. To ensure that the file in the
5619 current working directory is used, start file with ‘./’.
5620 Options
5622 -A, --no-alias
5623 Disable alias substitution while parsing.
5624 -L, --autoload
5626 Search $YASH_LOADPATH instead of $PATH, regardless of whether file
5627 contains slashes. The file value is not considered relative to the
5628 current working directory.
5629 The dot built-in treats as operands any command line arguments after
5631 the first operand.
5632 Operands
5634 file
5635 The pathname of a file to be read.
5636 arguments...
5638 Strings to which positional parameters are set while execution.
5639 Exit status
5641 The exit status of the dot built-in is that of the last command
5642 executed. The exit status is zero if the file contains no commands to
5643 execute and non-zero if a file was not found or could not be opened.
5644 Notes
5646 The dot built-in is a special built-in.
5647 A non-interactive shell immediately exits with a non-zero exit status
5649 if the dot built-in fails to find or open a file to execute.
5650 The POSIX standard defines no options for the dot built-in; the
5652 built-in accepts no options in the POSIXly-correct mode.
5653 The POSIX standard does not define the arguments... operands. It is an
5655 error to specify the arguments... operands in the POSIXly-correct mode.
5656
5658 The echo built-in prints its arguments.
5659 Syntax
5661 · echo [string...]
5662 The built-in treats all command line arguments as operands except for
5664 the options described below. Any word that cannot be parsed as an
5665 acceptable option is treated as an operand. Options must precede all
5666 operands. Syntax errors never happen in the echo built-in.
5667 Description
5669 The echo built-in prints the operand strings followed by a newline to
5670 the standard output. The strings are each separated by a space.
5671 Escape sequences
5673 The ECHO_STYLE variable and the -e option enable escape sequences
5674 that are replaced with corresponding characters:
5675 \a
5677 Bell character (ASCII code: 7)
5678 \b
5680 Backspace (ASCII code: 8)
5681 \c
5683 Nothing. After this escape sequence, no characters are printed
5684 at all.
5685 \e
5687 Escape character (ASCII code: 27)
5688 \f
5690 Form feed character (ASCII code: 12)
5691 \n
5693 Newline character (ASCII code: 10)
5694 \r
5696 Carriage return character (ASCII code: 13)
5697 \t
5699 Horizontal tab character (ASCII code: 9)
5700 \v
5702 Vertical tab character (ASCII code: 11)
5703 \\
5705 Backslash
5706 \0xxx
5708 Character whose code is xxx, where xxx is an octal number of at
5709 most three digits.
5710 When escape sequences are not enabled, they are just printed
5712 intact.
5713 ECHO_STYLE variable
5715 The ECHO_STYLE variable defines which options are accepted and
5716 whether escape sequences are enabled by default. The variable value
5717 should be set to one of the following:
5718 SYSV, XSI
5720 No options are accepted. Escape sequences are always enabled.
5721 BSD
5723 The -n option is accepted. Escape sequences are never enabled.
5724 GNU
5726 The -n, -e, and -E options are accepted. Escape sequences are
5727 not enabled by default, but can be enabled by the -e option.
5728 ZSH
5730 The -n, -e, and -E options are accepted. Escape sequences are
5731 enabled by default, but can be disabled by the -E option.
5732 DASH
5734 The -n option is accepted. Escape sequences are always enabled.
5735 RAW
5737 No options are accepted. Escape sequences are never enabled.
5738 When the ECHO_STYLE variable is not set, it defaults to SYSV.
5740 Options
5742 -n
5743 Do not print a newline at the end.
5744 -e
5746 Enable escape sequences.
5747 -E
5749 Disable escape sequences.
5750 Exit status
5752 The exit status of the echo built-in is zero unless there is any error.
5753 Notes
5755 The POSIX standard does not define the ECHO_STYLE variable nor any
5756 options for the built-in. According to POSIX, the behavior of the
5757 built-in is implementation-defined when the first argument is -n or
5758 when any argument contains a backslash. For maximum portability, the
5759 printf built-in should be preferred over the echo built-in.
5760 Although many values for the ECHO_STYLE variable are defined on the
5762 basis of other existing implementations, yash is not intended to
5763 exactly imitate those originals. Zsh’s echo built-in interprets a
5764 single hyphen argument as a separator between options and operands.
5765 Yash does not support such use of hyphen.
5766
5768 The eval built-in evaluates operands as commands.
5769 Syntax
5771 · eval [-i] [command...]
5772 The eval built-in requires that all options precede operands. Any
5774 command line arguments after the first operand are all treated as
5775 operands.
5776 Description
5778 The eval parses operands as commands and executes them in the current
5779 command execution environment.
5780 When executed without the -i (--iteration) option, all the operands are
5782 concatenated into one string (with a space inserted between each
5783 operand) and parsed/executed at once.
5784 With the -i (--iteration) option, the built-in performs iterative
5786 execution: operands are parsed/executed one by one. If the continue
5787 built-in is executed with the -i (--iteration) option during the
5788 iterative execution, the execution of the current operand is aborted
5789 and the next operand is parsed/executed immediately. The break built-in
5790 with the -i (--iteration) option is similar but the remaining operands
5791 are not parsed/executed. The value of the ? special parameter is saved
5792 before the iterative execution is started. The parameter value is
5793 restored to the saved one after each iteration.
5794 Options
5796 -i, --iteration
5797 Perform iterative execution.
5798 Operands
5800 command
5801 A string that is parsed and executed as commands.
5802 Exit status
5804 The exit status is zero if no command was specified or command
5805 contained no actual command that can be executed. Otherwise, that is,
5806 if the eval built-in executed one or more commands, the exit status of
5807 the eval built-in is that of the last executed command.
5808 Notes
5810 The eval built-in is a special built-in.
5811 The POSIX standard defines no options for the eval built-in; the
5813 built-in accepts no options in the POSIXly-correct mode.
5814
5816 The exec built-in replaces the shell process with another external
5817 command.
5818 Syntax
5820 · exec [-cf] [-a name] [command [argument...]]
5821 The exec built-in requires that all options precede operands. It is
5823 important so that options to the exec built-in are not confused with
5824 options to command. Any command line arguments after command are
5825 treated as arguments.
5826 Description
5828 When the exec built-in is executed with command, the shell executes
5829 command with arguments in a manner similar to the last step of
5830 execution of a simple command. The differences are that command is
5831 always treated as an external command ignoring any existing functions
5832 and built-ins and that the exec system call that starts the external
5833 command is called in the current command execution environment instead
5834 of a subshell, replacing the shell process with the new command
5835 process.
5836 If the shell is in the POSIXly-correct mode or not interactive, failure
5838 in execution of command causes the shell to exit immediately.
5839 If an interactive shell that is not in the POSIXly-correct mode has a
5841 stopped job, the shell prints a warning message and refuses to execute
5842 command. Once the shell process is replaced with an external command,
5843 information about the shell’s jobs is lost, so you will have to resume
5844 or kill the stopped jobs by sending signals by hand. To force the shell
5845 to execute command regardless, specify the -f (--force) option.
5846 When executed without command, the built-in does nothing. As a side
5848 effect, however, redirection applied to the built-in remains in the
5849 current command execution environment even after the built-in finished.
5850 Options
5852 -a name, --as=name
5853 Pass name, instead of command, to the external command as its name.
5854 -c, --clear
5856 Pass to the external command only variables that are assigned in
5857 the simple command in which the built-in is being executed. Other
5858 environment variables are not passed to the command.
5859 -f, --force
5861 Suppress warnings that would prevent command execution.
5862 Operands
5864 command
5865 An external command to be executed.
5866 argument...
5868 Arguments to be passed to the command.
5869 Exit status
5871 If the shell process was successfully replaced with the external
5872 command, there is no exit status since the shell process no longer
5873 exists.
5874 The exit status is:
5876 · 127 if the command was not found,
5878 · 126 if the command was found but could not be executed, and
5880 · zero if no command was specified.
5882 Notes
5884 The exec built-in is a special built-in.
5885 The POSIX standard defines no options for the exec built-in; the
5887 built-in accepts no options in the POSIXly-correct mode.
5888
5890 The exit built-in causes the shell process to exit.
5891 Syntax
5893 · exit [-f] [exit_status]
5894 Description
5896 The exit built-in causes the current shell (or subshell) process to
5897 exit.
5898 If an interactive shell has a stopped job, the shell prints a warning
5900 message and refuses to exit. To force the shell to exit regardless,
5901 specify the -f (--force) option or execute the built-in twice in a row.
5902 If an EXIT trap has been set, the shell executes the trap before
5904 exiting.
5905 Options
5907 -f, --force
5908 Suppress warnings that would prevent the shell from exiting.
5909 Operands
5911 exit_status
5912 A non-negative integer that will be the exit status of the exiting
5913 shell.
5914 If this operand is omitted, the exit status of the shell will be
5916 that of the last command executed before the exit built-in (but, if
5917 the built-in is executed during a trap, the exit status will be
5918 that of the last command before the trap is entered).
5919 If exit_status is 256 or larger, the actual exit status will be the
5921 remainder of exit_status divided by 256.
5922 Exit status
5924 Because the built-in causes the shell to exit, there is no exit status
5925 of the built-in.
5926 As an exception, if the shell refused to exit, the exit status of the
5928 built-in is non-zero.
5929 Notes
5931 The exit built-in is a special built-in.
5932 The POSIX standard defines no options for the exit built-in; the
5934 built-in accepts no options in the POSIXly-correct mode.
5935 The POSIX standard provides that the exit_status operand should be
5937 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
5938 an extension.
5939 If the built-in is executed during an EXIT trap, the shell just exits
5941 without executing the trap again. If exit_status was not specified, the
5942 exit status of the shell is what the exit status would be if the trap
5943 had not been set. See also Termination of the shell.
5944
5946 The export built-in marks variables for export to child processes.
5947 Syntax
5949 · export [-prX] [name[=value]...]
5950 Description
5952 The export built-in is equivalent to the typeset built-in with the -gx
5953 option.
5954 Notes
5956 The export built-in is a special built-in.
5957 The POSIX standard defines the -p option only; other options cannot be
5959 used in the POSIXly-correct mode. The POSIX does not allow using the
5960 option together with operands.
5961
5963 The false built-in does nothing unsuccessfully.
5964 Syntax
5966 · false
5967 Description
5969 The false built-in does nothing. Any command line arguments are
5970 ignored.
5971 Exit status
5973 The exit status of the false built-in is non-zero.
5974 Notes
5976 The false built-in is a semi-special built-in.
5977
5979 The fc built-in re-executes or prints commands from command history.
5980 Syntax
5982 · fc [-qr] [-e editor] [start [end]]
5983 · fc -s[q] [old=new] [start]
5985 · fc -l[nrv] [start [end]]
5987 Description
5989 When executed without the -l (--list) option, the built-in executes the
5990 commands in the command history range specified by the operands. If the
5991 -s (--silent) option is not specified, the shell invokes an editor
5992 which allows you to edit the commands before they are executed. The
5993 commands are executed when you quit the editor. If the -s (--silent)
5994 option is specified, the commands are immediately executed. In either
5995 case, the executed commands are printed to the standard output and
5996 added to the history.
5997 When executed with the -l (--list) option, the built-in prints the
5999 commands in the command history range specified by the operands. By
6000 default, commands are printed with their history entry numbers, but
6001 output format can be changed using the -n (--no-numbers)) and -v
6002 (--verbose) options.
6003 Options
6005 -e editor, --editor=editor
6006 Specify an editor that is used to edit commands.
6007 If this option is not specified, the value of the FCEDIT variable
6009 is used. If the variable is not set either, ed is used.
6010 -l, --list
6012 Print command history entries.
6013 -n, --no-numbers
6015 Don’t print entry numbers when printing history entries.
6016 -q, --quiet
6018 Don’t print commands before executing.
6019 -r, --reverse
6021 Reverse the order of command entries in the range.
6022 -s, --silent
6024 Execute commands without editing them.
6025 -v, --verbose
6027 Print execution time before each history entry when printing.
6028 Operands
6030 start and end
6031 The start and end operands specify a range of command history
6032 entries that are executed or printed. If one of the operands is an
6033 integer, it is treated as a history entry number. A negative
6034 integer means the nth most recent entry where n is the absolute
6035 value of the integer. If one of the operands is not an integer, it
6036 is treated as part of a command string: the most recent entry that
6037 starts with the string is selected as the start or end of the
6038 range.
6039 If the first entry of the range that is specified by start is newer
6041 than the last entry of the range that is specified by end, the
6042 range is reversed as if the -r (--reverse) option was specified.
6043 (If the option is already specified, it is cancelled.)
6044 The default values for start and end are:
6046 ┌──────┬─────────┬───────────────┐
6048 │ │ with -l │ without -l │
6049 ├──────┼─────────┼───────────────┤
6050 │start │ -16 │ -1 │
6051 ├──────┼─────────┼───────────────┤
6052 │end │ -16 │ same as start │
6053 └──────┴─────────┴───────────────┘
6054 old=new
6056 An operand of this format replaces part of the command string. If
6057 the command string contains old, it is replaced with new and the
6058 new string is executed. Only the first occurrence of old is
6059 replaced.
6060 Exit status
6062 If commands was executed, the exit status of the fc built-in is that of
6063 the last executed command. Otherwise, the exit status is zero unless
6064 there is any error.
6065 Notes
6067 The fc built-in is a semi-special built-in.
6068 The POSIX standard does not define the -q (--quiet) or -v (--verbose)
6070 options, so they cannot be used in the POSIXly-correct mode.
6071 Command history cannot be modified during line-editing.
6073
6075 The fg built-in resumes a job in the foreground.
6076 Syntax
6078 · fg [job...]
6079 Description
6081 The fg built-in brings the specified job to the foreground and sends
6082 the SIGCONT signal to the job. As a result, the job is resumed in the
6083 foreground (if it has been suspended). The built-in then waits for the
6084 job to finish and returns the exit status of it.
6085 The name of the job is printed when the job is resumed. When not in the
6087 POSIXly-correct mode, the job number is also printed.
6088 The built-in can be used only when job control is enabled.
6090 Operands
6092 job
6093 The job ID of the job to be resumed.
6094 If more than one job is specified, they are resumed in order, one
6096 at a time. The current job is resumed if none is specified.
6097 The percent sign (%) at the beginning of a job ID can be omitted if
6099 the shell is not in the POSIXly-correct mode.
6100 Exit status
6102 The exit status of the fg built-in is that of the (last) job resumed.
6103 The exit status is non-zero when there was some error.
6104 Notes
6106 The fg built-in is a semi-special built-in.
6107 You cannot specify more than one job in the POSIXly-correct mode.
6109
6111 The getopts built-in parses command options.
6112 Syntax
6114 · getopts optionlist variable [argument...]
6115 Description
6117 The getopts built-in parses single-character options that appear in
6118 arguments. Each time the built-in is invoked, it parses one option and
6119 assigns the option character to variable.
6120 The optionlist operand is a list of option characters that should be
6122 accepted by the parser. In optionlist, an option that takes an argument
6123 should be specified as the option character followed by a colon. For
6124 example, if you want the -a, -b and -c options to be parsed and the -b
6125 option to take an argument, then optionlist should be ab:c.
6126 When an option that takes an argument is parsed, the argument is
6128 assigned to the OPTARG variable.
6129 When an option that is not specified in optionlist is found or when an
6131 option argument is missing, the result depends on the first character
6132 of optionlist:
6133 · If optionlist starts with a colon, the option character is assigned
6135 to the OPTARG variable and variable is set to either ? (when the
6136 option is not in optionlist) or : (when the option argument is
6137 missing).
6138 · Otherwise, variable is set to ?, the OPTARG variable is unset, and
6140 an error message is printed.
6141 The built-in parses one option for each execution. For all options in a
6143 set of command line arguments to be parsed, the built-in has to be
6144 executed repeatedly with the same arguments. The built-in uses the
6145 OPTIND variable to remember which argument should be parsed next. When
6146 the built-in is invoked for the first time, the variable value must be
6147 1, which is the default value. You must not modify the variable until
6148 all the options have been parsed, when the built-in sets the variable
6149 to the index of the first operand in arguments. (If there are no
6150 operands, it will be set to the number of arguments plus one.)
6151 When you want to start parsing a new set of arguments, you have to
6153 reset the OPTIND variable to 1 beforehand.
6154 Operands
6156 optionlist
6157 A list of options that should be accepted as valid options in
6158 parsing.
6159 variable
6161 The name of a variable the result is to be assigned to.
6162 arguments
6164 Command line arguments that are to be parsed.
6165 When no arguments are given, the positional parameters are parsed.
6167 Exit status
6169 If an option is found, whether or not it is specified in optionlist,
6170 the exit status is zero. If there is no more option to be parsed, the
6171 exit status is non-zero.
6172 Example
6174 aopt=false bopt= copt=false
6175 while getopts ab:c opt
6176 do
6177 case $opt in
6178 a) aopt=true ;;
6179 b) bopt=$OPTARG ;;
6180 c) copt=true ;;
6181 \?) return 2 ;;
6182 esac
6183 done
6184 if $aopt; then echo Option -a specified; fi
6185 if [ -n "$bopt" ]; then echo Option -b $bopt specified; fi
6186 if $copt; then echo Option -c specified; fi
6187 shift $((OPTIND - 1))
6188 echo Operands are: $*
6189 Notes
6191 In arguments that are parsed, options must precede operands. The
6192 built-in ends parsing when it encounters the first operand.
6193 The getopts built-in is a semi-special built-in.
6195 The POSIX standard does not specify what will happen when the OPTIND
6197 variable is assigned a value other than 1.
6198 In the POSIXly-correct mode, option characters in optionlist must be
6200 alphanumeric.
6201
6203 The hash built-in remembers, forgets, or reports command locations.
6204 Syntax
6206 · hash command...
6207 · hash -r [command...]
6209 · hash [-a]
6211 · hash -d user...
6213 · hash -dr [user...]
6215 · hash -d
6217 Description
6219 When executed with commands but without options, the built-in
6220 immediately performs command path search and caches commands' full
6221 paths.
6222 When executed with the -r (--remove) option, it removes the paths of
6224 commands (or all cached paths if none specified) from the cache.
6225 When executed without options or commands, it prints the currently
6227 cached paths to the standard output.
6228 With the -d (--directory) option, the built-in does the same things to
6230 the home directory cache, rather than the command path cache. Cached
6231 home directory paths are used in tilde expansion.
6232 Options
6234 -a, --all
6235 Print all cached paths.
6236 Without this option, paths for built-ins are not printed.
6238 -d, --directory
6240 Affect the home directory cache instead of the command path cache.
6241 -r, --remove
6243 Remove cached paths.
6244 Operands
6246 command
6247 The name of an external command (that does not contain any slash).
6248 user
6250 A user name.
6251 Exit status
6253 The exit status of the hash built-in is zero unless there is any error.
6254 Notes
6256 The shell automatically caches command and directory paths when
6257 executing a command or performing tilde expansion, so normally there is
6258 no need to use this built-in explicitly to cache paths.
6259 Assigning a value to the PATH variable removes all command paths from
6261 the cache as if hash -r was executed.
6262 The POSIX standard defines the -r option only: other options cannot be
6264 used in the POSIXly-correct mode.
6265 The hash built-in is a semi-special built-in.
6267
6269 The help built-in prints usage of built-ins.
6270 Syntax
6272 · help [built-in...]
6273 Description
6275 The help built-in prints a description of built-ins.
6276 Operands
6278 built-ins
6279 Names of built-ins.
6280 Exit status
6282 The exit status of the help built-in is zero unless there is any error.
6283 Notes
6285 The help built-in is a semi-special built-in. In the POSIX standard, it
6286 is defined as a command with unspecified behavior.
6287 Many built-ins of yash accept the --help option that prints the same
6289 description.
6290
6292 The history built-in prints or edits command history.
6293 Syntax
6295 · history [-cF] [-d entry] [-s command] [-r file] [-w file] [count]
6296 Description
6298 The history built-in prints or edits command history.
6299 When executed with an option, the built-in edits history according to
6301 the option. If more than one option is specified, each option is
6302 processed in order.
6303 When executed with the count operand, the built-in prints the most
6305 recent count history entries to the standard output in the same manner
6306 as the fc built-in.
6307 When executed with neither options nor operands, the built-in prints
6309 the whole history.
6310 Options
6312 -c, --clear
6313 Clear all history entries completely.
6314 -d entry, --delete=entry
6316 Delete the specified entry. The entry should be specified in the
6317 same manner as the start and end operands of the fc built-in.
6318 -F, --flush-file
6320 Rebuild the history file. This operation removes unused old data
6321 from the file.
6322 -r file, --read=file
6324 Read command lines from file and add them to the history. The file
6325 contents are treated as lines of simple text.
6326 -s command, --set=command
6328 Add command as a new history entry after removing the most recent
6329 entry.
6330 -w file, --write=file
6332 Write the whole history to file. Any existing data in the file will
6333 be lost. The output format is lines of simple text, each of which
6334 is a command string.
6335 Operands
6337 count
6338 The number of entries to be printed.
6339 Exit status
6341 The exit status of the history built-in is zero unless there is any
6342 error.
6343 Notes
6345 The history built-in is a semi-special built-in. In the POSIX standard,
6346 it is defined as a command with unspecified behavior.
6347 Command history cannot be modified during line-editing.
6349
6351 The jobs built-in reports job status.
6352 Syntax
6354 · jobs [-lnprs] [job...]
6355 Description
6357 The jobs built-in prints information of jobs the shell is currently
6358 controlling.
6359 By default, the following information is printed for each job, line by
6361 line:
6362 · the job number,
6364 · the + or - symbol if the job is the current or previous job,
6366 respectively,
6367 · the status, and
6369 · the command string.
6371 Options
6373 -l, --verbose
6374 Print the process ID, status, and command string for each process
6375 in the jobs.
6376 -n, --new
6378 Print new jobs only: jobs whose status has never been reported
6379 since the status changed.
6380 -p, --pgid-only
6382 Print process group IDs of jobs only.
6383 -r, --running-only
6385 Print running jobs only.
6386 -s, --stopped-only
6388 Print stopped jobs only.
6389 Operands
6391 jobs
6392 The job IDs of jobs to be reported. When no job is specified, all
6393 jobs under the shell’s control are reported.
6394 The percent sign (%) at the beginning of a job ID can be omitted if
6396 the shell is not in the POSIXly-correct mode.
6397 Exit status
6399 The exit status of the jobs built-in is zero unless there is any error.
6400 Notes
6402 The jobs built-in is a semi-special built-in.
6403 The POSIX standard defines the -l and -p options only: other options
6405 cannot be used in the POSIXly-correct mode. In the POSIXly-correct
6406 mode, the effect of the -l option is different in that status is
6407 reported for each job rather than for each process.
6408 The process group ID of a job executed by yash is equal to the process
6410 ID of the first command of the pipeline that forms the job.
6411
6413 The kill built-in sends a signal to processes.
6414 Syntax
6416 · kill [-signal|-s signal|-n signal] process...
6417 · kill -l [-v] [signal...]
6419 The kill built-in requires that all options precede operands. Any
6421 command line arguments after the first operand are all treated as
6422 operands.
6423 Description
6425 When executed without the -l option, the built-in sends a signal to
6426 processes. The signal sent can be specified by option. The SIGTERM
6427 signal is sent if no signal is specified.
6428 When executed with the -l option, the built-in prints information of
6430 signals to the standard output. If no signal is specified, information
6431 of all signals is printed.
6432 Options
6434 Signal-specifying options
6435 -signal, -s signal, -n signal
6436 A signal-specifying option specifies a signal to be sent to
6437 processes. signal can be specified by name or number. If
6438 number 0 is specified, the built-in checks if a signal could be
6439 sent to the processes but no signal is actually sent. Signal
6440 names are case-insensitive.
6441 You can specify at most one signal-specifying option at a time.
6443 Other options
6445 -l
6446 Print signal information instead of sending a signal.
6447 -v
6449 Print more signal information.
6450 Without this option, the built-in prints the signal name only.
6452 This option adds the signal number and a short description.
6453 When the -v option is specified, the -l option can be omitted.
6455 Operands
6457 processes
6458 Specify processes to which a signal is sent.
6459 Processes can be specified by the process ID, the process group ID,
6461 or the job ID. The process group ID must be prefixed with a hyphen
6462 (-) so that it is not treated as a process ID.
6463 When 0 is specified as process, the signal is sent to the process
6465 group to which the shell process belongs. When -1 is specified, the
6466 signal is sent to all processes on the system.
6467 signal
6469 Specify a signal of which information is printed.
6470 The signal can be specified by the name, the number, or the exit
6472 status of a command that was killed by the signal.
6473 Exit status
6475 The exit status of the kill built-in is zero unless there is any error.
6476 If the signal was sent to at least one process, the exit status is zero
6477 even if the signal was not sent to all of the specified processes.
6478 Notes
6480 The kill built-in is a semi-special built-in.
6481 Command arguments that start with a hyphen should be used with care.
6483 The command kill -1 -2, for example, sends signal 1 to process group 2
6484 since -1 is treated as a signal-specifying option and -2 as an operand
6485 that specifies a process group. The commands kill -- -1 -2 and kill
6486 -TERM -1 -2, on the other hand, treats both -1 and -2 as operands.
6487 The POSIX standard does not define the -n or -v options, so they cannot
6489 be used in the POSIXly-correct mode. The standard does not allow
6490 specifying a signal number as the argument of the -s option or a signal
6491 name as the signal operand.
6492 The standard requires signal names to be specified without the SIG
6494 prefix, like INT and QUIT. If the shell is not in the POSIXly-correct
6495 mode, the built-in accepts SIG-prefixed signal names as well.
6496
6498 The local built-in prints or sets local variables.
6499 Syntax
6501 · local [-rxX] [name[=value]...]
6502 Description
6504 The local built-in is equivalent to the typeset built-in except that
6505 the -f (--functions) and -g (--global) options cannot be used.
6506 Notes
6508 The local built-in is a semi-special built-in. In the POSIX standard,
6509 it is defined as a command with unspecified behavior.
6510
6512 The popd built-in pops a directory from the directory stack.
6513 Syntax
6515 · popd [index]
6516 Description
6518 The popd built-in removes the last entry from the directory stack,
6519 returning to the previous working directory. If index is given, the
6520 entry specified by index is removed instead of the last one.
6521 Operands
6523 index
6524 The index of a directory stack entry you want to remove.
6525 If omitted, +0 (the last entry) is assumed.
6527 Exit status
6529 The exit status of the popd built-in is zero unless there is any error.
6530 Notes
6532 It is an error to use this built-in when there is only one directory
6533 stack entry.
6534 The popd built-in is a semi-special built-in. In the POSIX standard, it
6536 is defined as a command with unspecified behavior.
6537
6539 The printf built-in prints formatted values.
6540 Syntax
6542 · printf format [value...]
6543 Description
6545 The printf built-in formats values according to format and prints them
6546 to the standard output. Unlike the echo built-in, the printf built-in
6547 does not print a newline automatically.
6548 The formatting process is very similar to that of the printf function
6550 in the C programming language. You can use conversion specifications
6551 (which start with %) and escape sequences (which start with \) in
6552 format. Any other characters that are not part of a conversion
6553 specification or escape sequence are printed literally.
6554 Conversion specifications
6556 A conversion specification starts with a percent sign (%).
6557 A conversion specification except %% consumes a value, which is
6559 formatted according to the specification and printed. Each
6560 conversion specification consumes one value in the order of
6561 appearance. If there are more values than conversion
6562 specifications, the entire format is re-processed until all the
6563 values are consumed. If a value to be consumed is missing, it is
6564 assumed to be an empty string (if the specification requires a
6565 string) or zero (if a number). If no values are given, format is
6566 processed just once.
6567 Available conversion specifications are:
6569 %d, %i
6571 prints a signed integer in decimal
6572 %u
6574 prints an unsigned integer in decimal
6575 %o
6577 prints an unsigned integer in octal
6578 %x
6580 prints an unsigned integer in lowercase hexadecimal
6581 %X
6583 prints an unsigned integer in uppercase hexadecimal
6584 %f
6586 prints a floating-point number in lowercase
6587 %F
6589 prints a floating-point number in uppercase
6590 %e
6592 prints a floating-point number with exponent in lowercase
6593 %E
6595 prints a floating-point number with exponent in uppercase
6596 %g
6598 the same as %f or %e, automatically selected
6599 %G
6601 the same as %F or %E, automatically selected
6602 %c
6604 prints the first character of string
6605 %s
6607 prints a string
6608 %b
6610 prints a string (recognizing escape sequences like the echo
6611 built-in)
6612 %%
6614 prints a percent sign (%)
6615 For %g and %G, the specification that is actually used is %f or %F
6617 if the exponent part is between -5 and the precision (exclusive);
6618 %e or %E otherwise.
6619 In a conversion specification except %%, the leading percent sign
6621 may be followed by flags, field width, and/or precision in this
6622 order.
6623 The flags are a sequence of any number of the following characters:
6625 Minus sign (-)
6627 With this flag, spaces are appended to the formatted value to
6628 fill up to the field width. Otherwise, spaces are prepended.
6629 Plus sign (+)
6631 A plus or minus sign is always prepended to a number.
6632 Space ( )
6634 A space is prepended to a formatted number if it has no plus or
6635 minus sign.
6636 Hash sign (#)
6638 The value is formatted in an alternative form: For %o, the
6639 printed octal integer has at least one leading zero. For %x and
6640 %X, a non-zero integer is formatted with 0x and 0X prefixes,
6641 respectively. For %e, %E, %f, %F, %g, and %G, a decimal mark
6642 (a.k.a. radix character) is always printed even if the value is
6643 an exact integer. For %g and %G, the printed number has at
6644 least one digit in the fractional part.
6645 Zero (0)
6647 Zeros are prepended to a formatted number to fill up to the
6648 field width. This flag is ignored if the minus flag is
6649 specified or if the conversion specification is %d, %i, %u, %o,
6650 %x, or %X with a precision.
6651 A field width is specified as a decimal integer that has no leading
6653 zeros.
6654 A field width defines a minimum byte count of a formatted value. If
6656 the formatted value does not reach the minimum byte count, so many
6657 spaces are prepended that the printed value has the specified byte
6658 count.
6659 A precision is specified as a period (.) followed by a decimal
6661 integer. If the integer is omitted after the period, the precision
6662 is assumed to be zero.
6663 For conversion specifications %d, %i, %u, %o, %x, and %X, a
6665 precision defines a minimum digit count. If the formatted integer
6666 does not reach the minimum digit count, so many zeros are prepended
6667 that the printed integer has the specified number of digits. The
6668 default precision is one for these conversion specifications.
6669 For conversion specifications %e, %E, %f, and %F, a precision
6671 defines the number of digits after the decimal mark. The default
6672 precision is six for these conversion specifications.
6673 For conversion specifications %g, and %G, a precision defines a
6675 maximum number of significant digits in the printed value. The
6676 default precision is six for these conversion specifications.
6677 For conversion specifications %s, and %b, a precision defines a
6679 maximum byte count of the printed string. The default precision is
6680 infinity for these conversion specifications.
6681 In the conversion specification %08.3f, the zero flag is specified,
6683 the field width is 8, and the precision is 3. If this specification
6684 is applied to value 12.34, the output will be 0012.340.
6685 Escape sequences
6687 The following escape sequences are recognized in format:
6688 \a
6690 Bell character (ASCII code: 7)
6691 \b
6693 Backspace (ASCII code: 8)
6694 \f
6696 Form feed character (ASCII code: 12)
6697 \n
6699 Newline character (ASCII code: 10)
6700 \r
6702 Carriage return character (ASCII code: 13)
6703 \t
6705 Horizontal tab character (ASCII code: 9)
6706 \v
6708 Vertical tab character (ASCII code: 11)
6709 \\
6711 Backslash
6712 \"
6714 Double quotation
6715 \'
6717 Single quotation (apostrophe)
6718 \xxx
6720 Character whose code is xxx, where xxx is an octal number of at
6721 most three digits.
6722 Operands
6724 format
6725 A string that defines how values should be formatted.
6726 values
6728 Values that are formatted according to format.
6729 A value is either a number or a string.
6731 When a numeric value is required, value can be a single or double
6733 quotation followed by a character, instead of a normal number. For
6734 example, the command printf '%d' '"3' will print 51 on a typical
6735 environment where character 3 has character code 51.
6736 Exit status
6738 The exit status of the printf built-in is zero unless there is any
6739 error.
6740 Notes
6742 The POSIX standard does not precisely define how multibyte characters
6743 should be handled by the built-in. When you use the %s conversion
6744 specification with precision or the %c conversion specification, you
6745 may obtain unexpected results if the formatted value contains a
6746 character that is represented by more than one byte. Yash never prints
6747 only part of the bytes that represent a single multibyte character
6748 because all multibyte characters are converted to wide characters when
6749 processed in the shell.
6750 If the shell is not in the POSIXly-correct mode and the “long double”
6752 floating-point arithmetic is supported on the running system, then
6753 “long double” is used for floating-point conversion specifications.
6754 Otherwise, “double” is used.
6755
6757 The pushd built-in pushes a directory into the directory stack.
6758 Syntax
6760 · pushd [-L|-P] [directory]
6761 Description
6763 The pushd built-in changes the working directory to directory in the
6764 same manner as the cd built-in and adds it to the directory stack. If
6765 the working directory could not be changed successfully, the stack is
6766 not modified.
6767 Options
6769 The pushd built-in accepts the following option as well as the options
6770 that can be used for the cd built-in:
6771 --remove-duplicates
6773 If the new working directory has already been in the directory
6774 stack, the existing entry is removed from the stack before the new
6775 directory is pushed into the stack.
6776 Operands
6778 directory
6779 The pathname of the new working directory.
6780 If directory is a single hyphen (‘-’), the value of the OLDPWD
6782 variable is assumed for the new directory pathname, which is
6783 printed to the standard output.
6784 If directory is an integer with a plus or minus sign, it is
6786 considered as an entry index of the directory stack. The entry is
6787 removed from the stack and then pushed to the stack again.
6788 If directory is omitted, the working directory is changed to the
6790 directory specified by the --default-directory=... option. If that
6791 option is not specified either, the default is index +1.
6792 Exit status
6794 The exit status of the pushd built-in is zero unless there is any
6795 error.
6796 Notes
6798 The pushd built-in is a semi-special built-in. In the POSIX standard,
6799 it is defined as a command with unspecified behavior.
6800
6802 The pwd built-in prints the current working directory.
6803 Syntax
6805 · pwd [-L|-P]
6806 Description
6808 The pwd built-in prints an absolute path to the shell’s current working
6809 directory to the standard output.
6810 Options
6812 -L, --logical
6813 If the value of the PWD variable is an absolute path to the shell’s
6814 working directory and the path does not contain any . or ..
6815 components, then the path is printed. Otherwise, the printed path
6816 is the same as when the -P option is specified.
6817 -P, --physical
6819 The printed path does not contain any . or .. components,
6820 symbolic link components, or redundant slashes.
6821 The -L (--logical) and -P (--physical) options are mutually exclusive:
6823 only the last specified one is effective. If neither is specified, -L
6824 is assumed.
6825 Exit status
6827 The exit status of the pwd built-in is zero unless there is any error.
6828 Notes
6830 The pwd built-in is a semi-special built-in.
6831
6833 The read built-in reads a line from the standard input.
6834 Syntax
6836 · read [-Aer] [-P|-p] variable...
6837 Description
6839 The read built-in reads a line of string from the standard input and
6840 assigns it to the specified variables.
6841 If the -r (--raw-mode) option is specified, all characters in the line
6843 are treated literally.
6844 If the -r (--raw-mode) option is not specified, backslashes in the line
6846 are treated as quotations. If a backslash is at the end of the line, it
6847 is treated as a line continuation. When the built-in reads the next
6848 line, the PS2 variable is used as a prompt if the shell is interactive
6849 and the standard input is a terminal.
6850 The input line is subject to field splitting. The resulting words are
6852 assigned to variables in order. If there are more words than variables,
6853 the last variable is assigned all the remaining words (as if the words
6854 were not split). If the words are fewer than variables, the remaining
6855 variables are assigned empty strings.
6856 Options
6858 -A, --array
6859 Make the last variable an array. Instead of assigning a
6860 concatenation of the remaining words to a normal variable, the
6861 words are assigned to an array.
6862 -e, --line-editing
6864 Use line-editing to read the line.
6865 To use line-editing, all of the following conditions must also be
6867 met:
6868 · The shell is interactive.
6870 · The vi or emacs option is enabled.
6872 · The standard input and standard error are connected to a
6874 terminal.
6875 -P, --ps1
6877 Print the PS1 variable as a prompt before reading the (first) line
6878 if the shell is interactive and the standard input is a terminal.
6879 -p prompt, --prompt=prompt
6881 Print the specified prompt before reading the (first) line if the
6882 shell is interactive and the standard input is a terminal.
6883 -r, --raw-mode
6885 Don’t treat backslashes as quotations.
6886 Operands
6888 variables
6889 Names of variables to which input words are assigned.
6890 Exit status
6892 The exit status of the read built-in is zero unless there is any error.
6893 Note that the exit status is non-zero if an end of input is encountered
6895 before reading the entire line.
6896 Notes
6898 The read built-in is a semi-special built-in.
6899 The POSIX standard defines the -r option only: other options cannot be
6901 used in the POSIXly-correct mode.
6902 The PS1R and PS1S variables affect the behavior of line-editing if the
6904 PS1 prompt is used. The same for PS2.
6905
6907 The readonly built-in makes variables and functions read-only.
6908 Syntax
6910 · readonly [-pxX] [name[=value]...]
6911 · readonly -f[p] [name...]
6913 Description
6915 The readonly built-in is equivalent to the typeset built-in with the
6916 -gr option.
6917 Notes
6919 The readonly built-in is a special built-in.
6920 The POSIX standard defines the -p option only; other options cannot be
6922 used in the POSIXly-correct mode. The POSIX does not allow using the
6923 option together with operands.
6924
6926 The return built-in returns from a function or script.
6927 Syntax
6929 · return [-n] [exit_status]
6930 Description
6932 When executed without the -n (--no-return) option, one of the following
6933 happens:
6934 · If the shell is executing a function, the execution of the function
6936 is terminated.
6937 · If the dot built-in is executing a script, the execution of the
6939 script is terminated.
6940 · If the shell is executing a script during initialization, the
6942 execution of the script is terminated.
6943 · If the shell is executing a trap, the execution of the trap is
6945 terminated for the currently handled signal.
6946 · Otherwise, the shell exits unless it is interactive.
6948 When executed with the -n (--no-return) option, the built-in does
6950 nothing but return the specified exit_status.
6951 Options
6953 -n, --no-return
6954 Do not terminate a function, script, trap, or the shell.
6955 Operands
6957 exit_status
6958 The exit status of the built-in.
6959 The value must be a non-negative integer.
6961 If omitted, the exit status of the last executed command is used.
6963 (But when the shell is executing a trap, the exit status of the
6964 last command before the trap is used.)
6965 Exit status
6967 The exit status of the return built-in is defined by the exit_status
6968 operand. The exit status is used also as the exit status of the
6969 terminated function, script, or the shell.
6970 Notes
6972 The return built-in is a special built-in.
6973 The POSIX standard provides that the exit_status operand should be
6975 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
6976 an extension.
6977 In the POSIX standard, the behavior of the return built-in is defined
6979 only when the shell is executing a function or script.
6980 The POSIX standard defines no options for the return built-in; the
6982 built-in accepts no options in the POSIXly-correct mode.
6983
6985 The set built-in sets shell options and positional parameters.
6986 Syntax
6988 · set [options] [operands]
6989 · set -o
6991 · set +o
6993 The set built-in requires that all options precede operands. Any
6995 command line arguments after the first operand are all treated as
6996 operands.
6997 Description
6999 When executed without any command arguments, the built-in prints a list
7000 of all existing variables to the standard input in a form that can be
7001 reused as commands that will restore the variable definitions.
7002 When -o is the only command argument, the built-in prints a list of
7004 shell options with their current settings. When +o is the only command
7005 argument, the built-in prints commands that can be reused to restore
7006 the current shell option settings.
7007 In other cases, the built-in changes shell option settings and/or
7009 positional parameters.
7010 Options
7012 When one or more options are specified, the built-in enables or
7013 disables the shell options. A normal hyphen-prefixed option enables a
7014 shell option. An option that is prefixed with a plus (+) instead of a
7015 hyphen disables a shell option. For example, options -m, -o monitor,
7016 and --monitor enable the monitor option and options +m, +o monitor,
7017 ++monitor disable it.
7018 The name of a long option is case-insensitive and may include
7020 irrelevant non-alphanumeric characters, which are ignored. For example,
7021 options --le-comp-debug and --LeCompDebug are equivalent. If no is
7022 prepended to the name of a long option, the meaning is reversed. For
7023 example, --noallexport is equivalent to ++allexport and ++nonotify to
7024 --notify.
7025 An option can be specified in one of the following forms:
7027 · a long option e.g. --allexport
7029 · an -o option with a option name specified as the argument e.g. -o
7031 allexport
7032 · a single-character option e.g. -a
7034 Not all options can be specified as single-character options.
7036 The available options are:
7038 all-export (-a)
7040 When enabled, all variables are automatically exported when
7041 assigned.
7042 brace-expand
7044 This option enables brace expansion.
7045 case-glob
7047 (Enabled by default) When enabled, pattern matching is
7048 case-sensitive in pathname expansion.
7049 clobber (+C)
7051 (Enabled by default) When enabled, the > redirection behaves the
7052 same as the >| redirection.
7053 cur-async, cur-bg, cur-stop
7055 (Enabled by default) These options affect choice of the current job
7056 (cf. job ID).
7057 dot-glob
7059 When enabled, periods at the beginning of filenames are not treated
7060 specially in pathname expansion.
7061 emacs
7063 This option enables line-editing in the emacs mode.
7064 empty-last-field
7066 When enabled, field splitting does not remove the last field even
7067 if it is empty.
7068 err-exit (-e)
7070 When enabled, if a pipeline ends with a non-zero exit status, the
7071 shell immediately exits unless the following suppress condition is
7072 met:
7073 · the pipeline is a condition of an if command or while or until
7075 loop;
7076 · the pipeline is prefixed by !; or
7078 · the pipeline is a single compound command other than a subshell
7080 grouping.
7081 err-return
7083 This option is like the err-exit option, but the return built-in is
7084 executed instead of the shell exiting on a non-zero exit status.
7085 Unlike err-exit, the suppress condition does not apply inside a
7086 function, subshell grouping, or script file.
7087 exec (+n)
7089 (Enabled by default) Commands are actually executed only when this
7090 option is enabled. Otherwise, commands are just parsed and not
7091 executed. Disabling this option may be useful for syntax checking.
7092 In an interactive shell, this option is always assumed enabled.
7093 extended-glob
7095 This option enables extension in pathname expansion.
7096 for-local
7098 (Enabled by default) If a for loop is executed within a function,
7099 this option causes the iteration variable to be created as a local
7100 variable, even if the variable already exists globally. This option
7101 has no effect if the POSIXly-correct mode is active.
7102 glob (+f)
7104 (Enabled by default) This option enables pathname expansion.
7105 hash-on-def (-h)
7107 When a function is defined when this option is enabled, the shell
7108 immediately performs command path search for each command that
7109 appears in the function and caches the command’s full path.
7110 hist-space
7112 When enabled, command lines that start with a whitespace are not
7113 saved in command history.
7114 ignore-eof
7116 When enabled, an interactive shell does not exit when EOF (end of
7117 file) is input. This prevents the shell from exiting when you
7118 accidentally hit Ctrl-D.
7119 le-always-rp, le-comp-debug, le-conv-meta, le-no-conv-meta, le-predict,
7121 le-predict-empty, le-prompt-sp, le-visible-bell
7122 See shell options on line-editing.
7123 mark-dirs
7125 When enabled, resulting directory names are suffixed by a slash in
7126 pathname expansion.
7127 monitor (-m)
7129 This option enables job control. This option is enabled by default
7130 for an interactive shell.
7131 notify (-b)
7133 When the status of a job changes when this option is enabled, the
7134 shell immediately notifies at any time. This option overrides the
7135 notify-le option.
7136 notify-le
7138 This option is similar to the notify option, but the status change
7139 is notified only while the shell is waiting for input with
7140 line-editing.
7141 null-glob
7143 When enabled, in pathname expansion, patterns that do not match any
7144 pathname are removed from the command line rather than left as is.
7145 pipe-fail
7147 When enabled, the exit status of a pipeline is zero if and only if
7148 all the subcommands of the pipeline exit with an exit status of
7149 zero.
7150 posixly-correct
7152 This option enables the POSIXly-correct mode.
7153 trace-all
7155 (Enabled by default) When this option is disabled, the x-trace
7156 option is temporarily disabled while the shell is executing
7157 commands defined in the COMMAND_NOT_FOUND_HANDLER, PROMPT_COMMAND,
7158 or YASH_AFTER_CD variable.
7159 unset (+u)
7161 (Enabled by default) When enabled, an undefined parameter is
7162 expanded to an empty string in parameter expansion and treated as
7163 zero in arithmetic expansion. When disabled, expansion of an
7164 undefined parameter results in an error.
7165 verbose (-v)
7167 When enabled, the shell prints each command line to the standard
7168 error before parsing and executing it.
7169 vi
7171 This option enables line-editing in the vi mode. This option is
7172 enabled by default in an interactive shell if the standard input
7173 and error are both terminals.
7174 x-trace (-x)
7176 When enabled, the results of expansion are printed to the standard
7177 error for each simple command being executed. When printed, each
7178 line is prepended with an expansion result of the PS4 variable. See
7179 also the trace-all option.
7180 Operands
7182 If one or more operands are passed to the set built-in, current
7183 positional parameters are all removed and the operands are set as new
7184 positional parameters. If the -- separator (cf. syntax of command
7185 arguments) is passed, the positional parameters are set even when there
7186 are no operands, in which case new positional parameters will be
7187 nothing.
7188 Exit status
7190 The exit status of the set built-in is zero unless there is any error.
7191 Notes
7193 The set built-in is a special built-in.
7194 In the POSIX standard, available shell options are much limited. The
7196 standard does not define:
7197 · long options such as --allexport,
7199 · prepending no to negate an option,
7201 · using uppercase letters and/or non-alphanumeric characters in
7203 option names
7204 The options defined in the standard are:
7206 · -a, -o allexport
7208 · -e, -o errexit
7210 · -m, -o monitor
7212 · -C, -o noclobber
7214 · -n, -o noexec
7216 · -f, -o noglob
7218 · -b, -o notify
7220 · -u, -o nounset
7222 · -v, -o verbose
7224 · -x, -o xtrace
7226 · -h
7228 · -o ignoreeof
7230 · -o nolog
7232 · -o vi
7234 Yash does not support the nolog option, which prevents function
7236 definitions from being added to command history.
7237
7239 The shift built-in removes some positional parameters or array values.
7240 Syntax
7242 · shift [-A array] [count]
7243 Description
7245 The shift built-in removes the first count positional parameters or
7246 array values, where count is specified by the operand.
7247 Options
7249 -A array, --array=array
7250 Remove first count values of array instead of positional
7251 parameters.
7252 Operands
7254 count
7255 The number of positional parameters or array values to be removed.
7256 It is an error if the actual number of positional parameters or
7258 array values is less than count. If omitted, the default value is
7259 one. If negative, the last -count positional parameters or array
7260 values are removed instead of the first ones.
7261 Exit status
7263 The exit status of the shift built-in is zero unless there is any
7264 error.
7265 Notes
7267 The shift built-in is a special built-in.
7268 The number of positional parameters can be obtained with the # special
7270 parameter. The number of array values can be obtained with ${array[#]}.
7271 The POSIX standard defines no options for the shift built-in; the
7273 built-in accepts no options in the POSIXly-correct mode.
7274 Negative operands are not allowed in the POSIXly-correct mode.
7276
7278 The suspend built-in suspends the shell.
7279 Syntax
7281 · suspend [-f]
7282 Description
7284 The suspend built-in sends a SIGSTOP signal to all processes in the
7285 process group to which the shell process belongs. The signal suspends
7286 the processes (including the shell). The suspended processes resume
7287 when they receive a SIGCONT signal.
7288 If the shell is interactive and its process group ID is equal to the
7290 process ID of the session leader, the shell prints a warning message
7291 and refuses to send a signal unless the -f (--force) option is
7292 specified. (In such a case, there is no other job-controlling shell
7293 that can send a SIGCONT signal to resume the suspended shell, so the
7294 shell could never be resumed.)
7295 Options
7297 -f, --force
7298 Suppress warnings that would prevent the shell from sending a
7299 signal.
7300 Exit status
7302 The exit status is zero if the signal was successfully sent and
7303 non-zero otherwise.
7304 Notes
7306 The suspend built-in is a semi-special built-in. In the POSIX standard,
7307 it is defined as a command with unspecified behavior.
7308
7310 The test built-in evaluates an expression.
7311 Syntax
7313 · test expression
7314 · [ expression ]
7316 The test built-in does not distinguish options and operands; all
7318 command line arguments are interpreted as expression. If the built-in
7319 is executed with the name [, expression must be followed by ].
7320 Description
7322 The test built-in evaluates expression as a conditional expression that
7323 is made up of operators and operands described below. The exit status
7324 is 0 if the condition is true and 1 otherwise.
7325 The unary operators below test a file. If the operand file is a
7327 symbolic link, the file referred to by the link is tested (except for
7328 the -h and -L operators).
7329 -b file
7331 file is a block special file
7332 -c file
7334 file is a character special file
7335 -d file
7337 file is a directory
7338 -e file
7340 file exists
7341 -f file
7343 file is a regular file
7344 -G file
7346 file's group ID is same as the shell’s effective group ID
7347 -g file
7349 file's set-group-ID flag is set
7350 -h file
7352 same as -L
7353 -k file
7355 file's sticky bit is set
7356 -L file
7358 file is a symbolic link
7359 -N file
7361 file has not been accessed since last modified
7362 -O file
7364 file's user ID is same as the shell’s effective user ID
7365 -p file
7367 file is a FIFO (named pipe)
7368 -r file
7370 file is readable
7371 -S file
7373 file is a socket
7374 -s file
7376 file is not empty
7377 -u file
7379 file's set-user-ID flag is set
7380 -w file
7382 file is writable
7383 -x file
7385 file is executable
7386 The unary operator below tests a file descriptor:
7388 -t fd
7390 fd is associated with a terminal
7391 The unary operators below test a string:
7393 -n string
7395 string is not empty
7396 -z string
7398 string is empty
7399 The unary operator below tests a shell option:
7401 -o ?option
7403 option is a valid shell option name
7404 -o option
7406 option is a valid shell option name that is enabled
7407 The binary operators below compare files. Non-existing files are
7409 considered older than any existing files.
7410 file1 -nt file2
7412 file1 is newer than file2
7413 file1 -ot file2
7415 file1 is older than file2
7416 file1 -ef file2
7418 file1 is a hard link to file2
7419 The binary operators below compare strings:
7421 string1 = string2, string1 == string2
7423 string1 is the same string as string2
7424 string1 != string2
7426 string1 is not the same string as string2
7427 The binary operators below compare strings according to the alphabetic
7429 order in the current locale:
7430 string1 === string2
7432 string1 is equal to string2
7433 string1 !== string2
7435 string1 is not equal to string2
7436 string1 < string2
7438 string1 is less than string2
7439 string1 <= string2
7441 string1 is less than or equal to string2
7442 string1 > string2
7444 string1 is greater than string2
7445 string1 >= string2
7447 string1 is greater than or equal to string2
7448 The binary operator below performs pattern matching:
7450 string =~ pattern
7452 extended regular expression pattern matches (part of) string
7453 The binary operators below compare integers:
7455 v1 -eq v2
7457 v1 is equal to v2
7458 v1 -ne v2
7460 v1 is not equal to v2
7461 v1 -gt v2
7463 v1 is greater than v2
7464 v1 -ge v2
7466 v1 is greater than or equal to v2
7467 v1 -lt v2
7469 v1 is less than v2
7470 v1 -le v2
7472 v1 is less than or equal to v2
7473 The binary operators below compare version numbers:
7475 v1 -veq v2
7477 v1 is equal to v2
7478 v1 -vne v2
7480 v1 is not equal to v2
7481 v1 -vgt v2
7483 v1 is greater than v2
7484 v1 -vge v2
7486 v1 is greater than or equal to v2
7487 v1 -vlt v2
7489 v1 is less than v2
7490 v1 -vle v2
7492 v1 is less than or equal to v2
7493 The operators below can be used to make complex expressions:
7495 ! expression
7497 negate (reverse) the result
7498 ( expression )
7500 change operator precedence
7501 expression1 -a expression2
7503 logical conjunction (and)
7504 expression1 -o expression2
7506 logical disjunction (or)
7507 If the expression is a single word without operators, the -n operator
7509 is assumed. An empty expression evaluates to false.
7510 Comparison of version numbers
7512 Comparison of version numbers is similar to comparison of strings
7513 in alphabetic order. The differences are:
7514 · Adjacent digits are treated as an integer. Integers are
7516 compared in mathematical order rather than alphabetic order.
7517 · Digits are considered larger than any non-digit characters.
7519 For example, version numbers 0.1.2-3 and 00.001.02-3 are equal and
7521 0.2.1 is smaller than 0.10.0.
7522 Exit status
7524 The exit status of the test built-in is 0 if expression is true and 1
7525 otherwise. The exit status is 2 if expression cannot be evaluated
7526 because of a syntax error or any other reasons.
7527 Notes
7529 Complex expressions may cause confusion and should be avoided. Use the
7530 shell’s compound commands. For example, [ 1 -eq 1 ] && [ -t = 1 ] && !
7531 [ foo ] is preferred over [ 1 -eq 1 -a -t = 1 -a ! foo ].
7532 The POSIX standard provides that the exit status should be larger than
7534 1 on error. The POSIX standard does not define the following operators:
7535 -G, -k, -N, -O, -nt, -ot, -ef, ==, ===, !==, <, <=, >, >=, =~, -veq,
7536 -vne, -vgt, -vge, -vlt, and -vle. POSIX neither specifies -o as a unary
7537 operator.
7538
7540 The times built-in prints CPU time usage.
7541 Syntax
7543 · times
7544 Description
7546 The times built-in prints the CPU times consumed by the shell process
7547 and its child processes to the standard output.
7548 The built-in prints two lines: the first line shows the CPU time of the
7550 shell process and the second one that of its child processes (not
7551 including those which have not terminated). Each line shows the CPU
7552 times consumed in the user and system mode.
7553 Exit status
7555 The exit status of the times built-in is zero unless there is any
7556 error.
7557 Notes
7559 The times built-in is a special built-in.
7560
7562 The trap built-in sets or prints signal handlers.
7563 Syntax
7565 · trap
7566 · trap action signal...
7568 · trap signal_number [signal...]
7570 · trap -p [signal...]
7572 Description
7574 The trap built-in sets or prints actions that are taken when the shell
7575 receives signals. (Those actions are called traps.)
7576 When executed with action and one or more signals, the built-in sets
7578 the traps for signals to action. If the shell receives one of the
7579 signals, the action will be taken.
7580 If the first operand is signal_number instead of action, the built-in
7582 resets the traps for signal_number and signals as if action was -.
7583 When executed with the -p (--print) option or with no operands, the
7585 built-in prints currently set traps to the standard output in a format
7586 that can be executed as commands that restore the current traps. If one
7587 or more signals are specified, only those signals are printed.
7588 Otherwise, all signals with non-default actions are printed. (In some
7589 situations, however, the built-in may print previous trap settings
7590 instead of the current. See notes below.)
7591 Options
7593 -p, --print
7594 Print current trap settings.
7595 Operands
7597 action
7598 An action that will be taken when signal is received.
7599 If action is a single hyphen (-), the action is reset to the
7601 default action that is defined by the operating system. If action
7602 is an empty string, the signal is ignored on receipt. Otherwise,
7603 action is treated as a command string: the string is parsed and
7604 executed as commands when the signal is received. (If a signal is
7605 received while a command is being executed, the action is taken
7606 just after the command finishes.)
7607 signal
7609 The number or name of a signal.
7610 If signal is number 0 or name EXIT, it is treated as a special
7612 imaginary signal that is always received when the shell exits. The
7613 action set for this signal is taken when the shell exits normally.
7614 signal_number
7616 This is like signal, but must be a number.
7617 Exit status
7619 The exit status of the trap built-in is zero unless there is any error.
7620 Notes
7622 The trap built-in is a special built-in.
7623 The POSIX standard defines no options for the trap built-in; the
7625 built-in accepts no options in the POSIXly-correct mode.
7626 The POSIX standard requires that signal names must be specified without
7628 the SIG-prefix, like INT and QUIT. As an extension, yash accepts
7629 SIG-prefixed names like SIGINT and SIGQUIT and treats signal names
7630 case-insensitively.
7631 Reusing output of the built-in
7633 Output of the trap built-in can be saved in a variable, which can
7634 be later executed by the eval built-in to restore the traps.
7635 saved_traps=$(trap)
7637 trap '...' INT
7638 eval "$saved_traps"
7639 There are some tricks behind the scenes to allow this idiom. You
7641 use a command substitution to save the output of the trap built-in
7642 in the variable. The command substitution is executed in a
7643 subshell. The subshell resets all traps (except ignored ones) at
7644 the beginning of itself. This seemingly would result in (almost)
7645 empty output from the built-in that would fail to restore the traps
7646 as expected.
7647 To avoid that pitfall, POSIX requires the shell to follow one of
7649 the two options below:
7650 · If a command substitution just contains a single trap built-in,
7652 traps should not be reset when the subshell is started to
7653 execute the built-in; or
7654 · A subshell always resets the traps but remembers the previous
7656 traps. If the trap built-in is executed in the subshell but no
7657 other trap built-in has been executed to modify traps in the
7658 subshell, then the built-in should print the remembered traps.
7659 Yash obeys the second.
7661
7663 The true built-in does nothing successfully.
7664 Syntax
7666 · true
7667 Description
7669 The true built-in does nothing. Any command line arguments are ignored.
7670 Exit status
7672 The exit status of the true built-in is zero.
7673 Notes
7675 The true built-in is a semi-special built-in.
7676 The true and colon built-ins have the same effect, but true is a
7678 semi-special built-in while colon is a special.
7679
7681 The type built-in identifies a command.
7682 Syntax
7684 · type [-abefkp] [command...]
7685 Description
7687 The type built-in is equivalent to the command built-in with the -V
7688 option.
7689 Notes
7691 The POSIX standard does not define the relation between the type and
7692 command built-ins. The standard does not define options for the type
7693 built-in.
7694 At least one command operand must be specified in the POSIXly-correct
7696 mode.
7697 The type built-in is a semi-special built-in.
7699
7701 The typeset built-in prints or sets variables or functions.
7702 Syntax
7704 · typeset [-gprxX] [variable[=value]...]
7705 · typeset -f[pr] [function...]
7707 Description
7709 If executed without the -f (--functions) option, the typeset built-in
7710 prints or sets variables to the standard output. Otherwise, it prints
7711 or sets functions.
7712 If executed with the -p (--print) option, the built-in prints the
7714 variables or functions specified by operands. Without the option, it
7715 sets variables or functions. If no operands are specified, it prints
7716 all existing variables or functions, regardless of whether the -p
7717 (--print) option is specified.
7718 Options
7720 -f, --functions
7721 Print or set functions rather than variables.
7722 -g, --global
7724 When setting a new variable, the variable will be a global variable
7725 if this option is specified. Without this option, the variable
7726 would be a local variable.
7727 When printing variables, all existing variables including global
7729 variables are printed if this option is specified. Without this
7730 option, only local variables are printed.
7731 -p, --print
7733 Print variables or functions in a form that can be parsed and
7734 executed as commands that will restore the currently set variables
7735 or functions.
7736 -r, --readonly
7738 When setting variables or functions, make them read-only.
7739 When printing variables or functions, print read-only variables or
7741 functions only.
7742 -x, --export
7744 When setting variables, mark them for export, so that they will be
7745 exported to external commands.
7746 When printing variables, print exported variables only.
7748 -X, --unexport
7750 When setting variables, cancel exportation of the variables.
7751 Operands
7753 variable (without value)
7754 The name of a variable that is to be set or printed.
7755 Without the -p (--print) option, the variable is defined (if not
7757 yet defined) but its value is not set nor changed. Variables that
7758 are defined without values are treated as unset in parameter
7759 expansion.
7760 variable=value
7762 The name of a variable and its new value.
7763 The value is assigned to the variable (regardless of the -p
7765 (--print) option).
7766 function
7768 The name of an existing function that is to be set or printed.
7769 Exit status
7771 The exit status of the typeset built-in is zero unless there is any
7772 error.
7773 Notes
7775 A global variable cannot be newly defined if a local variable has
7776 already been defined with the same name. The local variable will be set
7777 regardless of the -g (--global) option.
7778 The typeset built-in is a semi-special built-in. In the POSIX standard,
7780 it is defined as a command with unspecified behavior.
7781 The export and readonly built-ins are equivalent to the typeset
7783 built-in with the -gx and -gr options, respectively. The local built-in
7784 is equivalent to the typeset built-in except that the -f (--functions)
7785 and -g (--global) options cannot be used.
7786
7788 The ulimit built-in sets or prints a resource limit.
7789 Syntax
7791 · ulimit -a [-H|-S]
7792 · ulimit [-H|-S] [-efilnqrstuvx] [limit]
7794 Description
7796 The ulimit built-in sets or prints a resource limit.
7797 If executed with the -a (--all) option, the built-in prints the current
7799 limits for all resource types. Otherwise, it sets or prints the limit
7800 of a single resource type. The resource type can be specified by the
7801 options listed below. The resource limits will affect the current shell
7802 process and all commands invoked from the shell.
7803 Each resource type has two limit values: the hard and soft limit. You
7805 can change a soft limit freely as long as it does not exceed the hard
7806 limit. You can decrease a hard limit but cannot increase it without a
7807 proper permission.
7808 When the -H (--hard) or -S (--soft) option is specified, the built-in
7810 sets or prints the hard or soft limit, respectively. If neither of the
7811 options is specified, the built-in sets both the hard and soft limit or
7812 prints the soft limit.
7813 Options
7815 -H, --hard
7816 Set or print a hard limit.
7817 -S, --soft
7819 Set or print a soft limit.
7820 -a, --all
7822 Print all current limit settings.
7823 The following options specify the type of resources. If none of them is
7825 specified, -f is the default. The types of resources that can be set
7826 depend on the operating system.
7827 -c, --core
7829 Maximum size of core files created (in 512-byte blocks)
7830 -d, --data
7832 Maximum size of a process’s data segment (in kilobytes)
7833 -e, --nice
7835 Maximum scheduling priority (‘nice’)
7836 -f, --fsize
7838 Maximum size of files created by a process (in 512-byte blocks)
7839 -i, --sigpending
7841 Maximum number of pending signals
7842 -l, --memlock
7844 Maximum memory size that can be locked into RAM (in kilobytes)
7845 -m, --rss
7847 Maximum size of a process’s resident set (in kilobytes)
7848 -n, --nofile
7850 Maximum file descriptor + 1
7851 -q, --msgqueue
7853 Maximum size of POSIX message queues
7854 -r, --rtprio
7856 Maximum real-time scheduling priority
7857 -s, --stack
7859 Maximum size of a process’s stack (in kilobytes)
7860 -t, --cpu
7862 Maximum CPU time that can be used by a process (in seconds)
7863 -u, --nproc
7865 Maximum number of processes for a user
7866 -v, --as
7868 Maximum size of memory used by a process (in kilobytes)
7869 -x, --locks
7871 Maximum number of file locks
7872 Operands
7874 limit
7875 A limit to be set.
7876 The value must be a non-negative integer or one of hard, soft, and
7878 unlimited. If value is hard or soft, the new limit is set to the
7879 current hard or soft limit. If limit is not specified, the current
7880 limit is printed.
7881 Exit status
7883 The exit status of the ulimit built-in is zero unless there is any
7884 error.
7885 Notes
7887 The POSIX standard defines no options other than -f. It neither defines
7888 hard, soft, or unlimited for limit values.
7889 The ulimit built-in is a semi-special built-in.
7891
7893 The umask built-in sets or prints the file mode creation mask.
7894 Syntax
7896 · umask mask
7897 · umask [-S]
7899 Description
7901 If executed without the mask operand, the built-in prints the current
7902 file mode creation mask of the shell to the standard output in a form
7903 that can later be used as mask to restore the current mask.
7904 Otherwise, the built-in sets the file mode creation mask to mask.
7906 Options
7908 -S, --symbolic
7909 Print in the symbolic form instead of the octal integer form.
7910 Operands
7912 mask
7913 The new file mode creation mask either in the symbolic or octal
7914 integer form.
7915 Octal integer form
7917 In the octal integer form, the mask is specified as a non-negative
7918 octal integer that is the sum of the following permissions:
7919 0400
7921 read by owner
7922 0200
7924 write by owner
7925 0100
7927 execute/search by owner
7928 0040
7930 read by group
7931 0020
7933 write by group
7934 0010
7936 execute/search by group
7937 0004
7939 read by others
7940 0002
7942 write by others
7943 0001
7945 execute/search by others
7946 Symbolic form
7948 In the symbolic form, the mask is specified as a symbolic
7949 expression that denotes permissions that are not included in the
7950 mask.
7951 The entire expression is one or more clauses separated by comma. A
7953 clause is a sequence of whos followed by one or more actions.
7954 A who is one of:
7956 u
7958 owner
7959 g
7961 group
7962 o
7964 others
7965 a
7967 all of owner, group, and others
7968 An empty sequence of whos is equivalent to who a.
7970 An action is an operator followed by permission. An operator is one
7972 of:
7973 =
7975 set who's permission to permission
7976 +
7978 add permission to who's permission
7979 -
7981 remove permission from who's permission
7982 and permission is one of:
7984 r
7986 read
7987 w
7989 write
7990 x
7992 execute/search
7993 X
7995 execute/search (only if some user already has execute/search
7996 permission)
7997 s
7999 set-user-ID and set-group-ID
8000 u
8002 user’s current permissions
8003 g
8005 group’s current permissions
8006 o
8008 others' current permissions
8009 but more than one of r, w, x, X, and s can be specified after a
8011 single operand.
8012 For example, the command umask u=rwx,go+r-w
8014 · unmasks the user’s read, write, and execute/search permissions;
8016 · unmasks the group’s and others' read permission; and
8018 · masks the group’s and others' write permission.
8020 Exit status
8022 The exit status of the umask built-in is zero unless there is any
8023 error.
8024 Notes
8026 The umask built-in is a semi-special built-in.
8027 The POSIX standard does not require the default output format (used
8029 when the -S option is not specified) to be the octal integer form.
8030
8032 The unalias built-in undefines aliases.
8033 Syntax
8035 · unalias name...
8036 · unalias -a
8038 Description
8040 The unalias built-in removes the definition of the aliases specified by
8041 operands.
8042 Options
8044 -a, --all
8045 Undefine all aliases.
8046 Operands
8048 name
8049 The name of an alias to be undefined.
8050 Exit status
8052 The exit status of the unalias built-in is zero unless there is any
8053 error. It is an error to specify the name of a non-existing alias as
8054 name.
8055 Notes
8057 The unalias built-in is a semi-special built-in.
8058
8060 The unset built-in undefines variables or functions.
8061 Syntax
8063 · unset [-fv] [name...]
8064 Description
8066 The unset built-in removes the definition of the variables or functions
8067 specified by operands.
8068 It is not an error if any of the specified variables or functions do
8070 not exist; they are silently ignored.
8071 Options
8073 -f, --functions
8074 Undefine functions.
8075 -v, --variables
8077 Undefine variables.
8078 These options are mutually exclusive: only the last specified one is
8080 effective. If neither is specified, -v is assumed.
8081 Operands
8083 name
8084 The name of a variable or function to be undefined.
8085 Exit status
8087 The exit status of the unset built-in is zero unless there is any
8088 error.
8089 Notes
8091 The unset built-in is a special built-in.
8092 Although yash does not do so, the POSIX standard allows removing a
8094 function if neither of the -f and -v options is specified and the
8095 specified variable does not exist.
8096 At least one name operand must be specified in the POSIXly-correct
8098 mode.
8099
8101 The wait built-in waits for jobs to terminate.
8102 Syntax
8104 · wait [job...]
8105 Description
8107 The wait built-in waits for background jobs to terminate. If job
8108 control is enabled, stopped jobs are considered as terminated.
8109 The built-in can be used to wait for asynchronous commands if job
8111 control is disabled.
8112 If the shell receives a signal while the built-in is waiting and if a
8114 trap has been set for the signal, then the trap is executed and the
8115 built-in immediately finishes (without waiting for the jobs). If the
8116 shell receives a SIGINT signal when job control is enabled, the
8117 built-in aborts waiting.
8118 If the shell is interactive, job-controlling, and not in the
8120 POSIXly-correct mode, the job status is printed when the job is
8121 terminated or stopped.
8122 Operands
8124 job
8125 The job ID of the job or the process ID of a process in the job.
8126 If no jobs are specified, the built-in waits for all existing jobs.
8128 If the specified job does not exist, the job is considered to have
8130 terminated with the exit status of 127.
8131 Exit status
8133 If no jobs were specified and the built-in successfully waited for all
8134 the jobs, the exit status is zero. If one or more jobs were specified,
8135 the exit status is that of the last job.
8136 If the built-in was aborted by a signal, the exit status is an integer
8138 (> 128) that denotes the signal. If there was any other error, the exit
8139 status is between 1 and 126 (inclusive).
8140 Notes
8142 The wait built-in is a semi-special built-in.
8143 The process ID of the last process of a job can be obtained by the !
8145 special parameter. You can use the jobs built-in as well to obtain
8146 process IDs of job processes.
8147
8149 Yuki Watanabe <magicant@users.osdn.me>
8150 Author.
8151 2.49 2019-09-21 YASH(1)