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. If the command name exists and there are any redirections specified
2007 in the command, they are processed. The word token after each
2008 redirection operator is expanded. If an error occurs during
2009 processing the redirections (including when expanding the word
2010 token), the execution of this simple command is aborted with a
2011 non-zero exit status.
2012 Note
2014 In other shells, redirections may be processed in a different
2015 step: POSIX does not specify the order in which redirections
2016 and assignments are processed when there is no command name or
2017 the name denotes a special built-in.
2018 3. Assignments specified in the command, if any, are processed. For
2020 each assignment token, the value is expanded and assigned to the
2021 specified variable. If an error occurs during assignments
2022 (including when expanding the values to be assigned), the execution
2023 of this simple command is aborted with a non-zero exit status.
2024 • If there is no command name or the name denotes a special
2026 built-in, the assignments are permanent: the assigned values
2027 remain after the command has finished (until the variable is
2028 reassigned).
2029 • Otherwise, the assignments are temporary: the assigned values
2031 only last during the execution of this simple command.
2032 The assigned variables are automatically exported when the command
2034 name is specified or the all-export option is enabled.
2035 Note
2037 In other shells, assignments may behave differently: For
2038 special built-ins and functions, assigned variables may not be
2039 exported. For functions, assigned variables may be persistent,
2040 that is, may remain even after the execution of the simple
2041 command.
2042 4. If there is no command name, the redirections are processed in a
2044 subshell, then the command execution ends. If an error occurs in
2045 the redirections, the exit status of the simple command is
2046 non-zero. If there were any command substitutions performed in the
2047 assignments, the exit status of the simple command is that of the
2048 last executed command substitution. Otherwise, the exit status is
2049 zero.
2050 5. A command to be executed is determined using the command search
2052 algorithm and the command is executed.
2053 • If the command is an external command, the command is executed
2055 by creating a new subshell and calling the “exec” system call
2056 in the subshell. The command name and arguments are passed to
2057 the executed command. Exported variables are passed to the
2058 executed command as environment variables.
2059 • If the command is a built-in, the built-in is executed with the
2061 command arguments passed to the built-in.
2062 • If the command is a function, the contents of the function are
2064 executed with the command arguments as function arguments.
2065 If the command was executed, the exit status of this simple command
2067 is that of the executed command. If the algorithm failed to
2068 determine a command, no command is executed and the exit status is
2069 127. If the shell failed to execute the determined command, the
2070 exit status is 126. If the executed command was killed by a signal,
2071 the exit status is the signal number plus 384.
2072 Note
2074 In shells other than yash, the exit status may be different
2075 when the command was killed by a signal, because the POSIX
2076 standard only requires that the exit status be "greater than
2077 128."
2078 If the shell is not in the POSIXly-correct mode and the algorithm
2079 failed to determine a command, the command eval -i --
2080 "${COMMAND_NOT_FOUND_HANDLER-}" is evaluated. During the command
2081 execution, positional parameters are temporarily set to the command
2082 name and arguments that resulted in the first step. Any local
2083 variables defined during the execution are removed when the
2084 execution is finished. The HANDLED local variable is automatically
2085 defined with the initial value being the empty string. If the
2086 HANDLED variable has a non-empty value when the execution of the
2087 command string is finished, the shell pretends that the command was
2088 successfully determined and executed. The exit status of the simple
2089 command is that of the command string in this case.
2090 Command search
2092 A command that is executed in a simple command is determined by the
2093 command name using the following algorithm:
2094 1. If the command name contains a slash (/), the whole name is
2096 treated as the pathname of an external command. The external
2097 command is determined as the executed command.
2098 2. If the command name is a special built-in, the built-in is
2100 determined as the executed command.
2101 3. If the command name is the name of an existing function, the
2103 function is determined as the executed command.
2104 4. If the command name is a semi-special built-in, the built-in is
2106 determined as the executed command.
2107 5. If the command name is a regular built-in, the built-in is
2109 determined as the executed command unless the shell is in the
2110 POSIXly-correct mode.
2111 6. The shell searches the PATH for a executed command:
2113 The value of the PATH variable is separated by colons. Each
2115 separated part is considered as a directory pathname (an empty
2116 pathname denotes the current working directory). The shell
2117 searches the directories (in the order of appearance) and
2118 checks if any directory directly contains an executable regular
2119 file whose name is equal to the command name. If such a file is
2120 found:
2121 • If the command name is the name of a built-in, the built-in
2123 is determined as the executed command.
2124 • Otherwise, the file is determined as the executed command.
2126 (The file will be executed as an external command.)
2127 If no such file is found, no command is determined as the
2129 executed command.
2130 When the shell finds a file that matches the command name during
2132 the search above, the shell remembers the pathname of the file if
2133 it is an absolute path. When the algorithm above is used for the
2134 same command name again, the shell skips searching and directly
2135 determines the command to be executed. If an executable regular
2136 file no longer exists at the remembered pathname, however, the
2137 shell searches again to update the remembered pathname. You can
2138 manage remembered pathnames using the hash built-in.
2139 Termination of the shell
2141 The shell exits when it reached the end of input and has parsed and
2142 executed all input commands or when the exit built-in is executed. The
2143 exit status of the shell is that of the last command the shell executed
2144 (or zero if no commands were executed). The exit status of the shell is
2145 always between 0 and 255 (inclusive). If the exit status of the last
2146 command is 256 or larger, the exit status of the shell will be the
2147 remainder of the exit status divided by 256.
2148 If an exit handler has been registered by the trap built-in, the
2150 handler is executed just before the shell exits. The exit status of the
2151 commands executed in the handler does not affect the exit status of the
2152 shell.
2153 If a non-interactive shell encountered one of the following errors, the
2155 shell immediately exits with a non-zero exit status:
2156 • A command cannot be parsed due to an syntax error (except during
2158 shell initialization).
2159 • An error occurs during execution of a special built-in in the
2161 POSIXly-correct mode.
2162 • A redirection error occurs in a simple command whose command name
2164 is a special built-in and the shell is in the POSIXly-correct mode.
2165 • An assignment error occurs in a simple command.
2167 • An error occurs during expansion (except during shell
2169 initialization).
2170 Note
2172 Some shells other than yash exit when they fail to find a command
2173 to execute in command search.
2174 Functions
2176 Functions allow executing a compound command as a simple command. A
2177 function can be defined by the function definition command and executed
2178 by a simple command. You can use the unset built-in to remove function
2179 definitions.
2180 There are no functions predefined when yash is started.
2182 A function is executed by executing its body, which is a compound
2184 command. While the function is being executed, positional parameters
2185 are set to the arguments given to the function. The old positional
2186 parameters are restored when the function execution finishes.
2187 Local variables
2189 Local variables are temporary variables that are defined in a
2190 function and exist during the function execution only. They can be
2191 defined by the typeset built-in or implicitly created by a for
2192 loop. They are removed when the function execution finishes.
2193 Local variables may hide variables that have already been defined
2195 before the function execution had started. An existing variable
2196 becomes inaccessible if a local variable of the same name is
2197 defined in a function. The old variable becomes accessible again
2198 when the function execution finishes.
2199 You cannot create a local variable when not executing a function. A
2201 normal variable is created if you try to do so.
2202 Command execution environment
2204 The shell holds following properties during execution.
2205 • The working directory
2207 • Open file descriptors
2209 • The file creation mask (umask)
2211 • The set of signals whose handler is set to “ignore” (trap)
2213 • Environment variables
2215 • Resource limits (ulimit)
2217 Those properties are inherited from the invoker of the shell to the
2219 shell, and from the shell to each external command executed by the
2220 shell.
2221 The properties can be changed during the execution of the shell by
2223 built-in commands, variable assignments, etc.
2224 Subshells
2226 A subshell is a copy of the shell process. Subshells are used in
2227 execution of groupings, pipelines, etc.
2228 Subshells inherit functions, aliases, etc. defined in the shell as
2230 well as the properties above since subshells are copies of the
2231 shell process. Notable exceptions are:
2232 • Traps registered by the trap built-in are all reset in
2234 subshells except for ones whose action is set to “ignore”. (See
2235 below)
2236 • The interactive mode and job control are disabled in subshells.
2238 Jobs are not inherited by subshells.
2239 Subshells are executed independently of the original shell, so
2241 changes of any properties above do not affect those of the original
2242 shell.
2243 Note
2245 If the subshell contains a single trap built-in, some shells
2246 (but not yash) may not reset the traps on entry to the
2247 subshell.
2248
2250 The interactive mode is a mode of the shell intended for direct
2251 interaction with a user. If yash is in the interactive mode, it is
2252 called an interactive shell.
2253 Whether a shell runs in the interactive mode or not is determined in
2255 the invocation of the shell. After the shell has started up, the
2256 interactive mode cannot be switched on or off.
2257 When the shell is interactive:
2259 • Initialization scripts are executed during invocation.
2261 • The shell checks for mail and prints a command prompt when it reads
2263 a command. Job status changes are also reported if job control is
2264 active. Line-editing may be used depending on the capability of
2265 the terminal.
2266 • Commands executed are automatically registered in command history.
2268 • If a command executed by the shell is killed by a signal other than
2270 SIGINT and SIGPIPE, the shell reports the fact to the standard
2271 error.
2272 • The filename token is subject to pathname expansion in file
2274 redirection.
2275 • The shell does not exit when it encounters a syntax or expansion
2277 error during command execution. (cf. Termination of the shell)
2278 • The shell does not exit when it receives the SIGINT, SIGTERM, or
2280 SIGQUIT signal.
2281 • A signal handler can be changed by the trap built-in even if the
2283 handler had been set to “ignore” when the shell was invoked.
2284 • The value of the - special parameter contains i.
2286 • The shell’s locale reflects the value of the LC_CTYPE variable
2288 whenever the value is changed (if the shell is not in the
2289 POSIXly-correct mode).
2290 • Commands are executed even when the exec option is off.
2292 • The ignore-eof option takes effect when enabled.
2294 • When the shell reaches the end of input or the exit built-in is
2296 executed, the shell checks if there is any stopped job. If so, the
2297 shell prints a warning and does not actually exit.
2298 • The suspend built-in by default cannot stop the shell if it is a
2300 session leader.
2301 • The shell does not exit when the dot built-in fails to find a
2303 script file to read.
2304 • The shell does not exit when the exec built-in fails to execute a
2306 command (if not in the POSIXly-correct mode).
2307 • When a job finished for which the wait built-in has been waiting,
2309 the fact is reported (only if job control is active and not in the
2310 POSIXly-correct mode).
2311 • A prompt is printed when the read built-in reads a second or
2313 following line.
2314 Prompts
2316 The interactive shell prints a prompt just before it reads a command.
2317 The contents of the prompt is specified by the value of the PS1 and PS2
2318 variables. The former is used for reading the first line of the command
2319 and the latter for other lines.
2320 When the prompt is printed, the variable value is subjected to
2322 parameter expansion, command substitution, and arithmetic expansion
2323 (but note that the POSIX standard requires parameter expansion only).
2324 The result of the expansion is parsed by the rules below to make the
2325 actual prompt string, which is printed to the standard error.
2326 In the POSIXly-correct mode, each exclamation mark (!) in the string is
2328 substituted with the command history number of the command that is
2329 being input. Two adjacent exclamation marks (!!) are printed as a
2330 single exclamation. Other characters are printed intact.
2331 If the shell is not in the POSIXly-command mode, the following
2333 notations can be used to format the prompt string. Notations are
2334 replaced with the strings designated in the list below. Characters that
2335 are not interpreted as notations are printed intact.
2336 \a
2338 Bell character (ASCII code: 7)
2339 \e
2341 Escape character (ASCII code: 27)
2342 \j
2344 The number of jobs in the shell.
2345 \n
2347 Newline character (ASCII code: 10)
2348 \r
2350 Carriage return character (ASCII code: 13)
2351 \!
2353 The command history number of the command that is being input
2354 \$
2356 # if the shell’s effective user ID is 0; $ otherwise.
2357 \\
2359 Backslash
2360 \[, \]
2362 These two notations can surround part of the prompt string that is
2363 not visible on the terminal. The surrounded part is ignored when
2364 the shell counts the number of characters that is displayed on the
2365 terminal, thus making characters correctly aligned on the terminal
2366 when the prompt string contains special invisible characters.
2367 \ffontspecs.
2369 When line-editing is active, this notation is replaced with special
2370 characters to change font styles on the terminal if the terminal is
2371 capable of it. If line-editing is inactive or the terminal is
2372 incapable of changing font styles, this notation is silently
2373 ignored. One or more of the following can be used for fontspecs:
2374 k
2376 Change font color to black
2377 r
2379 Change font color to red
2380 g
2382 Change font color to green
2383 y
2385 Change font color to yellow
2386 b
2388 Change font color to blue
2389 m
2391 Change font color to magenta
2392 c
2394 Change font color to cyan
2395 w
2397 Change font color to white
2398 K
2400 Change background color to black
2401 R
2403 Change background color to red
2404 G
2406 Change background color to green
2407 Y
2409 Change background color to yellow
2410 B
2412 Change background color to blue
2413 M
2415 Change background color to magenta
2416 C
2418 Change background color to cyan
2419 W
2421 Change background color to white
2422 t
2424 Make font color or background brighter (can only be used just
2425 after one of the characters above)
2426 d
2428 Change font and background colors to normal
2429 s
2431 Make font standout
2432 u
2434 Make font underlined
2435 v
2437 Make font and background colors reversed
2438 b
2440 Make font blink
2441 i
2443 Make font dim
2444 o
2446 Make font bold
2447 x
2449 Make font invisible
2450 D
2452 Make color and style normal
2453 The actual colors of font and background are defined by the
2455 terminal. Different terminals may use different colors.
2456 In addition to the normal prompt, a prompt string can be displayed to
2458 the right of the cursor if line-editing is active. Those prompts are
2459 called right prompts. The contents of right prompts are defined by the
2460 value of the PS1R and PS2R variables, each corresponding to the PS1 and
2461 PS2 variables.
2462 Using the above-said notations, the font style of command strings the
2464 user inputs can be changed as well as that of prompts. The font style
2465 of command strings is defined by the value of the PS1S and PS2S
2466 variables, each corresponding to the PS1 and PS2 variables. The value
2467 can contain the \ffontspecs. notation only.
2468 When the shell is not in the POSIXly-correct mode, the prompt variables
2470 can be defined with a name prefixed with YASH_ (e.g. YASH_PS1). This
2471 allows using a different prompt string than that in the POSIXly-correct
2472 mode.
2473 When the shell is not in the POSIXly-correct mode, the value of the
2475 PROMPT_COMMAND variable is executed before each prompt.
2476 Command history
2478 Command history is a feature of the shell that remembers executed
2479 commands to allow re-executing them later. Commands executed in the
2480 interactive mode are automatically saved in the command history. Saved
2481 commands can be edited and re-executed using line-editing and the fc
2482 and history built-ins.
2483 Commands are saved line by line. Lines that do not contain any
2485 non-whitespace characters are not saved in the history. Lines that
2486 start with whitespaces are not saved when the hist-space option is on.
2487 Command history is saved in a file. When history is first used after an
2489 interactive shell was started, the shell opens a file to save history
2490 in. The filename is specified by the value of the HISTFILE variable. If
2491 the file contains history data when opened, the data is restored to the
2492 shell’s history. The file contents are updated in real time as the user
2493 inputs commands into the shell. If the HISTFILE variable is not set or
2494 the file cannot be opened successfully, history is not saved in the
2495 file, but the history feature will be functional in all other respects.
2496 The number of commands saved in history is specified by the value of
2498 the HISTSIZE variable. The shell automatically removes old history data
2499 so that the number of saved commands does not exceed the value. If the
2500 HISTSIZE variable is not set or its value is not a natural number, 500
2501 items will be saved in history.
2502 The shell looks at the value of the HISTFILE and HISTSIZE variables
2504 only when the history feature is first used after the shell was
2505 started. “The history feature is used” when:
2506 • the fc or history built-in is executed,
2508 • line-editing is used (regardless of whether or not history data is
2510 recalled in line-editing), or
2511 • a command is input to the shell
2513 Therefore, the variables should be set in initialization scripts.
2515 When more than one instance of yash shares a single history file, all
2517 the shells use the same history data. As a result, commands that have
2518 been executed by a shell instance can be recalled on another shell
2519 instance. Shells sharing the same history should have the same HISTSIZE
2520 value so that they manipulate history data properly.
2521 Yash’s history data file has its own format that is incompatible with
2523 other kinds of shells.
2524 The HISTRMDUP variable can be set to remove duplicate history items.
2526 Mail checking
2528 An interactive shell can notify receipt of email. The shell
2529 periodically checks the modification date/time of a file specified by
2530 the user. If the file has been modified since the previous check, the
2531 shell prints a notification message (except when the shell is not in
2532 the POSIXly-correct mode and the file is empty). By specifying a
2533 mailbox file to be checked, the shell will print a message when the
2534 file has been modified, that is, some mail has been received.
2535 Check is done just before the shell prints a command line prompt. The
2537 interval of checks can be specified by the MAILCHECK variable in
2538 seconds. If the variable value is 0, check is done before every prompt.
2539 If the variable value is not a non-negative integer, no checks are
2540 done.
2541 The file whose modification time is checked is specified by the MAIL
2543 variable. The variable value should be set to the pathname of the file.
2544 If you want to check more than one file or customize the notification
2546 message, you can set the MAILPATH variable instead of the MAIL
2547 variable. When the MAILPATH variable is set, the MAIL variable is
2548 ignored. The value of the MAILPATH variable should be set to one or
2549 more colon-separated pathnames of files to be checked. Each pathname
2550 can be followed by a percent sign (%) and a custom notification
2551 message, which is printed when the corresponding file has been
2552 modified. If the pathname contains a percent sign, it should be quoted
2553 by a backslash. The specified message is subject to parameter
2554 expansion. For example, if the value of the MAILPATH variable is
2555 /foo/mail%New mail!:/bar/mailbox%You've got mail:/baz/mail\%data, the
2556 shell will print
2557 • New mail! when the file /foo/mail has been modified
2559 • You've got mail when the file /bar/mailbox has been modified
2561 • the default message when the file /baz/mail%data has been modified.
2563
2565 Job control is a function of the shell that executes multiple commands
2566 simultaneously and suspends/resumes the commands.
2567 When job control is active:
2569 • Every pipeline executed by the shell becomes a job. A job has its
2571 unique process group ID that is shared among all processes in the
2572 job.
2573 • If the processes of a job are suspended while the shell is waiting
2575 for the processes to finish, the shell continues to the next
2576 command as if the process have finished. The shell remembers the
2577 job as suspended so that it can be resumed later.
2578 • If a job is executed synchronously, the shell sets the foreground
2580 process group of the terminal to the process group of the job. When
2581 the job is finished (or suspended), the shell gets back to the
2582 foreground.
2583 • The subshell executing a command substitution has its own unique
2585 process group ID like a job. However, the shell does not remember
2586 the subshell as a job, so it cannot be suspended or resumed.
2587 • If the shell is interactive, job status is reported before every
2589 command line prompt as if the command jobs -n is executed.
2590 • The standard input of an asynchronous command is not automatically
2592 redirected to /dev/null.
2593 • The shell does not exit when it receives the SIGTSTP signal.
2595 • The value of the - special parameter contains m.
2597 • When a job finished for which the wait built-in has been waiting,
2599 the fact is reported (only if the shell is interactive and not in
2600 the POSIXly-correct mode).
2601 When job control is inactive, processes executed by the shell have the
2603 same process group ID as the shell. The shell treats asynchronous
2604 commands as an uncontrolled job.
2605 You can use the following built-ins to manipulate jobs:
2607 jobs
2609 prints existing jobs
2610 fg and bg
2612 run jobs in the foreground or background
2613 wait
2615 waits for jobs to be finished (or suspended)
2616 disown
2618 forgets jobs
2619 kill
2621 sends a signal to jobs
2622 An interactive job-controlling shell reports jobs status before every
2624 prompt by default. You can set the following options to make the shell
2625 report status at other timings:
2626 notify
2628 the shell reports immediately whenever job status changes.
2629 notify-le
2631 the shell reports immediately when job status changes while
2632 line-editing.
2633 A job is removed from the shell’s job list when:
2635 • it has finished and the jobs built-in reported it,
2637 • the wait built-in successfully waited for the job to finish, or
2639 • the disown built-in removed the job.
2641 Jobs are not removed from the list when an interactive shell
2643 automatically reports the status of jobs.
2644 Note
2646 The word “stop” is synonymous to “suspend” in the context of job
2647 control.
2648 Job ID
2650 Some built-ins use the following notation, which is called job ID, to
2651 specify a job to operate on:
2652 %, %%, %+
2654 the current job
2655 %-
2657 the previous job
2658 %n
2660 the job that has job number n, where n is a positive integer
2661 %string
2663 the job whose name begins with string
2664 %?string
2666 the job whose name contains string
2667 The current job and previous job are jobs selected by the shell
2669 according to the following rules:
2670 • When there is one or more suspended jobs, the current job is
2672 selected from them.
2673 • When there is one or more suspended jobs other than the current
2675 job, the previous job is selected from them.
2676 • The current and previous jobs are always different. When the shell
2678 has only one job, it is the current job and there is no previous
2679 job.
2680 • When the current job finished, the previous job becomes the current
2682 job.
2683 • When the current job is changed, the old current job becomes the
2685 previous job except when the old job finished.
2686 • When the foreground job is suspended, the job becomes the current
2688 job.
2689 Yash has some options to modify the rules of the current/previous job
2691 selection. (The rules above have priority over the options below.)
2692 cur-async
2694 When a new asynchronous command is started, it becomes the current
2695 job.
2696 cur-bg
2698 When a job is resumed by the bg built-in, the job becomes the
2699 current job.
2700 cur-stop
2702 When a job is suspended, it becomes the current job.
2703 The current and previous jobs are not changed as long as the rules
2705 above are met.
2706 The rules of the current/previous job selection defined in the POSIX
2708 standard are looser than yash’s rules above. Other POSIX-compliant
2709 shells may select the current and previous jobs differently.
2710
2712 Built-in commands are commands that are implemented in the shell and
2713 are executed by the shell without external programs.
2714 Types of built-in commands
2716 There are three types of built-in commands in yash: special built-in
2717 commands, semi-special built-in commands and regular built-in commands.
2718 Special built-in commands are much more important commands than others.
2720 They are executed regardless of whether the corresponding external
2721 commands exist or not. Results of variable assignments that occur in a
2722 simple command that invokes a special built-in last after the command
2723 has finished. Moreover, in the POSIXly-correct mode, a non-interactive
2724 shell immediately exits with a non-zero exit status when a redirect
2725 error, assignment error, or misuse of option or operand occurs in a
2726 special built-in command.
2727 Semi special built-in commands are the second important built-in
2729 commands. They are executed regardless of whether the corresponding
2730 external commands exist or not. In other parts they are the same as
2731 regular built-in commands.
2732 Regular built-in commands are less important built-in commands
2734 including commands that can be implemented as external commands or are
2735 not listed in POSIX. In the POSIXly-correct mode, a regular built-in is
2736 executed only when a corresponding external command is found in PATH.
2737 Syntax of command arguments
2739 In this section we explain common rules about command arguments. The
2740 built-in commands of yash follow the rules unless otherwise stated.
2741 There are two types of command arguments. One is options and the other
2743 is operands. An option is an argument that starts with a hyphen (-) and
2744 changes the way the command behaves. Some options take arguments. An
2745 operand is an argument that is not an option and specifies objects the
2746 command operates on.
2747 If you specify more than one option to a command, the order of the
2749 options are normally not significant. The order of operands, however,
2750 affects the command behavior.
2751 An option is either a single-character option or a long option. A
2753 single-character option is identified by one alphabetic character. A
2754 long option is identified by multiple alphabetic characters. The POSIX
2755 standard only prescribes single-character options, so in the
2756 POSIXly-correct mode you cannot use long options.
2757 A single-character option is composed of a hyphen followed by a letter.
2759 For example, -a is a single-character option. A single-character option
2760 that takes an argument requires the argument to be just after the
2761 option name.
2762 Example 4. The set built-in and single-character options
2764 For the set built-in, -m is a single-character option that does not
2766 take an argument and -o is one that takes an argument.
2767 • set -o errexit -m
2769 • set -oerrexit -m
2771 In these two command lines, errexit is the argument to the -o option.
2773 In the second example above, the -o option and its argument are
2775 combined into a single command line argument. The POSIX standard
2776 deprecates that style and any POSIX-conforming applications must
2777 specify options and their arguments as separate command line arguments,
2778 although yash accepts both styles.
2779 You can combine single-character options that do not take arguments
2781 into a single command line argument. For example, the three options -a,
2782 -b and -c can be combined into -abc.
2783 A long option is composed of two hyphens followed by an option name.
2785 For example, --long-option is a long option. You can omit some last
2786 characters of a long option name as long as it is not ambiguous. For
2787 example, you can use --long instead of --long-option if there is no
2788 other options beginning with --long. Like a single-character option, a
2789 long option that takes an argument requires the argument to be a
2790 command line argument just after the option name or to be specified in
2791 the same command line argument as the option name, separated by an
2792 equal sign (=).
2793 Example 5. The fc built-in and long options
2795 For the fc built-in, --quiet is a long option that does not take an
2797 argument and --editor is one that takes an argument.
2798 • fc --editor vi --quiet
2800 • fc --editor=vi --quiet
2802 In these command lines, vi is the argument to the --editor option.
2804 Arguments that are not options (nor arguments to them) are interpreted
2806 as operands. The POSIX standard requires all options should be
2807 specified before any operands. Therefore, in the POSIXly-correct mode,
2808 any arguments that come after the first operand are interpreted as
2809 operands (even if they look like options). If not in the
2810 POSIXly-correct mode, you can specify options after operand.
2811 Regardless of whether the shell is in the POSIXly-correct mode or not,
2813 an argument that is just composed of two hyphens (--) can be used as a
2814 separator between options and operands. All command line arguments
2815 after the -- separator are interpreted as operands, so you can specify
2816 operands that start with a hyphen correctly using the separator.
2817 Example 6. Options and operands to the set built-in
2819 • set -a -b -- -c -d
2821 In this example, -a and -b are options and -c and -d are operands. The
2823 -- separator itself is neither an option nor an operand.
2824 Regardless of whether the shell is in the POSIXly-correct mode or not,
2826 an argument that is just composed of a single hyphen (-) is interpreted
2827 as an operand.
2828
2830 With the line-editing feature, you can edit the command text when you
2831 input a command to an interactive shell. It not only works as a simple
2832 visual-interface editor, but also is integrated with the command
2833 history. You can recall, edit, and execute commands in the history with
2834 line-editing instead of using the fc built-in.
2835 Line-editing has two editing modes, the vi and emacs modes, which each
2837 have their own key binding settings. By switching editing modes, you
2838 can change key bindings used in line-editing. Each mode has a
2839 corresponding shell option, which determines whether the mode is
2840 currently active or not. No more than one mode can be active at a time,
2841 so the options for the other modes are automatically turned off when
2842 you turn on the option for one mode. The whole line-editing feature is
2843 deactivated when those options are off.
2844 When an interactive shell is started, the vi mode is automatically
2846 activated if the standard input and error are both connected to a
2847 terminal.
2848 Line-editing can be used only when the standard input and error are
2850 both connected to a terminal. If not, the shell silently falls back to
2851 the normal input mechanism. While line-editing is being used, the shell
2852 uses the termios interface to change I/O settings of the terminal and
2853 the terminfo interface to parse input key sequences.
2854 Shell options on line-editing
2856 The following options can be set by the set built-in to enable
2857 line-editing and choose an editing mode to activate:
2858 vi
2860 activates the vi mode.
2861 emacs
2863 activates the emacs mode.
2864 The other line-editing-related options are:
2866 le-always-rp
2868 When this options is enabled, the right prompt is always visible:
2869 when the cursor reaches the right prompt, it moves to the next line
2870 from the original position, which would otherwise be overwritten by
2871 input text.
2872 le-comp-debug
2874 When enabled, internal information is printed during completion,
2875 which will help debugging completion scripts.
2876 le-conv-meta
2878 When enabled, the 8th bit of each input byte is always treated as a
2879 meta-key flag, regardless of terminfo data.
2880 le-no-conv-meta
2882 When enabled, the 8th bit of each input byte is never treated as a
2883 meta-key flag, regardless of terminfo data.
2884 The le-conv-meta and le-no-conv-meta options cannot be both enabled
2886 at a time. When either is enabled, the other is automatically
2887 disabled. When neither is enabled, the 8th bit may be treated as a
2888 meta-key flag depending on terminfo data.
2889 le-predict
2891 activates command line prediction.
2892 le-predict-empty
2894 When enabled, and command line prediction is active, suggestions
2895 are also provided for empty input lines.
2896 le-prompt-sp
2898 When enabled, the shell prints a special character sequence before
2899 printing each prompt so that every prompt is printed at the
2900 beginning of a line.
2901 This option is enabled by default.
2903 le-visible-bell
2905 When enabled, the shell flashes the terminal instead of sounding an
2906 alarm when an alert is required.
2907 Editing modes
2909 The vi mode is an editing mode that offers key bindings similar to that
2910 of the vi editor. The vi mode has two sub-modes that are switched
2911 during editing: the insert and command modes. The sub-mode is always
2912 reset to the insert mode when line-editing is started for a new command
2913 line. In the insert mode, most characters are inserted to the buffer as
2914 typed. In the command mode, input characters are treated as commands
2915 that move the cursor, insert/delete text, etc.
2916 The emacs mode offers key bindings similar to the emacs editor. Most
2918 characters are inserted to the buffer as typed, but more characters are
2919 treated as commands than the vi insert mode.
2920 Another sub-mode is used while you enter search keywords. The sub-mode
2922 is called the search mode, which offers slightly different key bindings
2923 depending on the active editing mode.
2924 Line-editing commands
2926 All characters the user enters while line-editing is active are treated
2927 as line-editing commands listed below. The bindkey built-in allows
2928 customizing the key bindings of each mode (except for the search mode).
2929 The list below shows not only the functions of commands but also the
2931 default key bindings. The keywords “vi-insert”, “vi-command”,
2932 “vi-search”, “emacs”, “emacs-search” means the vi insert mode, the vi
2933 command mode, the search mode for the vi mode (the vi search mode), the
2934 emacs mode, and the search mode for the emacs mode (the emacs search
2935 mode), respectively.
2936 Some commands take an argument that affects the function of the
2938 commands. For example, the forward-char command moves the cursor by as
2939 many characters as specified by the argument. To specify an argument,
2940 use the digit-argument command just before another command that takes
2941 an argument.
2942 Basic editing commands
2944 noop
2945 Do nothing.
2946 vi-command
2948 \^[
2949 alert
2951 Alert.
2952 self-insert
2954 Insert the input character at the current cursor position.
2955 Characters escaped by escape sequences cannot be inserted.
2956 vi-insert, emacs
2958 \\
2959 insert-tab
2961 Insert a tab character at the current cursor position.
2962 emacs
2964 \^[\^I
2965 expect-verbatim
2967 Insert a character that is entered just after this command at
2968 the current cursor position. This command can input a character
2969 that cannot be input by the self-insert command, except a null
2970 character ('\0').
2971 vi-insert, vi-search, emacs-search
2973 \^V
2974 emacs
2976 \^Q, \^V
2977 digit-argument
2979 Pass the input digit to the next command as an argument.
2980 This command can be bound to a digit or hyphen. To pass “12” as
2982 an argument to the forward-char command in the vi mode, for
2983 example, enter 12l.
2984 vi-command
2986 1, 2, 3, 4, 5, 6, 7, 8, 9
2987 emacs
2989 \^[0, \^[1, \^[2, \^[3, \^[4, \^[5, \^[6, \^[7, \^[8, \^[9,
2990 \^[-,
2991 bol-or-digit
2993 Like the beginning-of-line command if there is no argument;
2994 like the digit-argument command otherwise.
2995 vi-command
2997 0
2998 accept-line
3000 Finish editing the current line. A newline is automatically
3001 appended to the line. The line will be executed by the shell.
3002 If command line prediction is active, the current prediction
3004 (if any) is ignored. See also the accept-prediction command.
3005 vi-insert, vi-command, emacs, emacs-search
3007 \^J, \^M
3008 abort-line
3010 Abandon the current buffer and finish editing as if an empty
3011 line was input.
3012 vi-insert, vi-command, vi-search, emacs, emacs-search
3014 \!, \^C
3015 eof
3017 Abandon the current buffer and finish editing as if the shell
3018 reached the end of input. This normally makes the shell exit.
3019 eof-if-empty
3021 Like the eof command if the buffer is empty; like the alert
3022 command otherwise.
3023 vi-insert, vi-command
3025 \#, \^D
3026 eof-or-delete
3028 Like the eof command if the buffer is empty; like the
3029 delete-char command otherwise.
3030 emacs
3032 \#, \^D
3033 accept-with-hash
3035 If the current line does not begin with a hash sign (#) or
3036 there is no argument specified for this command, a hash sign is
3037 inserted at the beginning of the line. Otherwise, the beginning
3038 hash sign is removed from the line. Finally, the line is
3039 accepted like the accept-line command.
3040 vi-command
3042 #
3043 emacs
3045 \^[#
3046 accept-prediction
3048 Like the accept-line command, but include the predicted part.
3049 setmode-viinsert
3051 Switch to the vi insert mode.
3052 vi-command
3054 i, \I
3055 setmode-vicommand
3057 Switch to the vi command mode.
3058 vi-insert
3060 \^[
3061 setmode-emacs
3063 Switch to the emacs mode.
3064 expect-char, abort-expect-char
3066 These commands are not meant for use by the user. They are used
3067 by the shell to implement some other commands.
3068 redraw-all
3070 Reprint the prompt and the current line to the terminal.
3071 vi-insert, vi-command, vi-search, emacs, emacs-search
3073 \^L
3074 clear-and-redraw-all
3076 Clear the terminal and reprint the prompt and the current line.
3077 Motion commands
3079 Motion commands move the cursor on the line. Most motion commands
3080 accept an argument. When passed an argument, they repeat the cursor
3081 motion as many times as specified by the argument. Passing “4” as
3082 an argument to the forward-char command, for example, advances the
3083 cursor by four characters.
3084 The shell has several definitions of words as units of distance: A
3086 bigword is one or more adjacent non-whitespace characters. A
3087 semiword is one or more adjacent characters that contain no
3088 whitespaces or punctuations. An emacsword is one or more adjacent
3089 alphanumeric characters. A viword is either:
3090 • one or more adjacent alphanumeric characters and/or underscores
3092 (_), or
3093 • one or more adjacent characters that contain none of
3095 alphanumeric characters, underscores, and whitespaces.
3096 forward-char
3098 Move the cursor to the next character.
3099 vi-insert
3101 \R
3102 vi-command
3104 l, (space), \R
3105 emacs
3107 \R, \^F
3108 backward-char
3110 Move the cursor to the previous character.
3111 vi-insert
3113 \L
3114 vi-command
3116 h, \B, \L, \?, \^H
3117 emacs
3119 \L, \^B
3120 forward-bigword
3122 Move the cursor to the next bigword.
3123 vi-command
3125 W
3126 end-of-bigword
3128 Move the cursor to the next end of a bigword.
3129 vi-command
3131 E
3132 backward-bigword
3134 Move the cursor to the previous bigword.
3135 vi-command
3137 B
3138 forward-semiword
3140 Move the cursor to the next semiword.
3141 end-of-semiword
3143 Move the cursor to the next end of a semiword.
3144 backward-semiword
3146 Move the cursor to the previous semiword.
3147 forward-viword
3149 Move the cursor to the next viword.
3150 vi-command
3152 w
3153 end-of-viword
3155 Move the cursor to the next end of a viword.
3156 vi-command
3158 e
3159 backward-viword
3161 Move the cursor to the previous viword.
3162 vi-command
3164 b
3165 forward-emacsword
3167 Move the cursor to the next emacsword.
3168 emacs
3170 \^[f, \^[F
3171 backward-emacsword
3173 Move the cursor to the previous emacsword.
3174 emacs
3176 \^[b, \^[B
3177 beginning-of-line
3179 Move the cursor to the beginning of the line.
3180 vi-insert, vi-command
3182 \H
3183 emacs
3185 \H, \^A
3186 end-of-line
3188 Move the cursor to the end of the line.
3189 vi-insert
3191 \E
3192 vi-command
3194 $, \E
3195 emacs
3197 \E, \^E
3198 go-to-column
3200 Move the cursor to the nth character on the line, where n is
3201 the argument. Assume n = 1 when no argument.
3202 vi-command
3204 |
3205 first-nonblank
3207 Move the cursor to the first non-blank character on the line.
3208 vi-command
3210 ^
3211 find-char
3213 Move the cursor to the first position where a character that is
3214 entered just after this command appears after the current
3215 cursor position.
3216 vi-command
3218 f
3219 emacs
3221 \^]
3222 find-char-rev
3224 Move the cursor to the last position where a character that is
3225 entered just after this command appears before the current
3226 cursor position.
3227 vi-command
3229 F
3230 emacs
3232 \^[\^]
3233 till-char
3235 Move the cursor to the first position just before a character
3236 that is entered just after this command appears after the
3237 current cursor position.
3238 vi-command
3240 t
3241 till-char-rev
3243 Move the cursor to the last position just after a character
3244 that is entered just after this command appears before the
3245 current cursor position.
3246 vi-command
3248 T
3249 refind-char
3251 Redo the last find-char, find-char-rev, till-char,
3252 till-char-rev command.
3253 vi-command
3255 ;
3256 refind-char-rev
3258 Redo the last find-char, find-char-rev, till-char,
3259 till-char-rev command in the reverse direction.
3260 vi-command
3262 ,
3263 Editing commands
3265 Editing commands modify contents of the buffer. Most editing
3266 commands accept an argument. When passed an argument, they repeat
3267 the modification as many times as specified by the argument.
3268 Texts deleted by commands whose name starts with “kill” are saved
3270 in kill ring, from which deleted contents can be restored to the
3271 buffer. The most recent 32 texts are kept in the kill ring.
3272 delete-char
3274 Delete a character at the current cursor position if no
3275 argument is passed; like the kill-char command otherwise.
3276 vi-insert, emacs
3278 \X
3279 delete-bigword
3281 Delete a bigword at the current cursor position if no argument
3282 is passed; like the kill-bigword command otherwise.
3283 delete-semiword
3285 Delete a semiword at the current cursor position if no argument
3286 is passed; like the kill-semiword command otherwise.
3287 delete-viword
3289 Delete a viword at the current cursor position if no argument
3290 is passed; like the kill-viword command otherwise.
3291 delete-emacsword
3293 Delete a emacsword at the current cursor position if no
3294 argument is passed; like the kill-emacsword command otherwise.
3295 backward-delete-char
3297 Delete a character just before the current cursor position if
3298 no argument is passed; like the backward-kill-char command
3299 otherwise.
3300 vi-insert, emacs
3302 \B, \?, \^H
3303 backward-delete-bigword
3305 Delete a bigword just before the current cursor position if no
3306 argument is passed; like the backward-kill-bigword command
3307 otherwise.
3308 backward-delete-semiword
3310 Delete a semiword just before the current cursor position if no
3311 argument is passed; like the backward-kill-semiword command
3312 otherwise.
3313 vi-insert
3315 \^W
3316 backward-delete-viword
3318 Delete a viword just before the current cursor position if no
3319 argument is passed; like the backward-kill-viword command
3320 otherwise.
3321 backward-delete-emacsword
3323 Delete a emacsword just before the current cursor position if
3324 no argument is passed; like the backward-kill-emacsword command
3325 otherwise.
3326 delete-line
3328 Delete the whole buffer contents.
3329 forward-delete-line
3331 Delete all characters from the current cursor position to the
3332 end of the buffer.
3333 backward-delete-line
3335 Delete all characters before the current cursor position.
3336 vi-insert
3338 \$, \^U
3339 kill-char
3341 Delete a character at the current cursor position and add it to
3342 the kill ring.
3343 vi-command
3345 x, \X
3346 kill-bigword
3348 Delete a bigword at the current cursor position and add it to
3349 the kill ring.
3350 kill-semiword
3352 Delete a semiword at the current cursor position and add it to
3353 the kill ring.
3354 kill-viword
3356 Delete a viword at the current cursor position and add it to
3357 the kill ring.
3358 kill-emacsword
3360 Delete a emacsword at the current cursor position and add it to
3361 the kill ring.
3362 emacs
3364 \^[d, \^[D
3365 backward-kill-char
3367 Delete a character just before the current cursor position and
3368 add it to the kill ring.
3369 vi-command
3371 X
3372 backward-kill-bigword
3374 Delete a bigword just before the current cursor position and
3375 add it to the kill ring.
3376 emacs
3378 \^W
3379 backward-kill-semiword
3381 Delete a semiword just before the current cursor position and
3382 add it to the kill ring.
3383 backward-kill-viword
3385 Delete a viword just before the current cursor position and add
3386 it to the kill ring.
3387 backward-kill-emacsword
3389 Delete a emacsword just before the current cursor position and
3390 add it to the kill ring.
3391 emacs
3393 \^[\B, \^[\?, \^[\^H
3394 kill-line
3396 Delete the whole buffer contents and add it to the kill ring.
3397 forward-kill-line
3399 Delete all characters from the current cursor position to the
3400 end of the buffer and add it to the kill ring.
3401 emacs
3403 \^K
3404 backward-kill-line
3406 Delete all characters before the current cursor position and
3407 add it to the kill ring.
3408 emacs
3410 \$, \^U, \^X\B, \^X\?
3411 put-before
3413 Insert the last-killed text before the current cursor position
3414 and move the cursor to the last character that was inserted.
3415 vi-command
3417 P
3418 put
3420 Insert the last-killed text after the current cursor position
3421 and move the cursor to the last character that was inserted.
3422 vi-command
3424 p
3425 put-left
3427 Insert the last-killed text before the current cursor position
3428 and move the cursor to the last character that was inserted.
3429 emacs
3431 \^Y
3432 put-pop
3434 Replace the just put text with the next older killed text.
3435 This command can be used only just after the put-before, put,
3437 put-left, or put-pop command.
3438 emacs
3440 \^[y, \^[Y
3441 undo
3443 Cancel modification by the last editing command.
3444 vi
3446 u
3447 emacs
3449 \^_, \^X\$, \^X\^U
3450 undo-all
3452 Cancel all modification in the current buffer, restoring the
3453 initial contents.
3454 vi
3456 U
3457 emacs
3459 \^[\^R, \^[r, \^[R
3460 cancel-undo
3462 Cancel cancellation by the last undo or undo-all command.
3463 vi
3465 \^R
3466 cancel-undo-all
3468 Cancel all cancellation by all most recent undo and undo-all
3469 commands.
3470 redo
3472 Repeat modification by the last editing command.
3473 vi-command
3475 .
3476 Completion commands
3478 complete
3479 Complete a word just before the cursor position and, if there
3480 is more than one candidate, show a list of the candidates.
3481 complete-next-candidate
3483 Like the complete command when candidates are not being listed;
3484 otherwise, select the next candidate in the list.
3485 vi-insert, emacs
3487 \^I
3488 complete-prev-candidate
3490 Like the complete command when candidates are not being listed;
3491 otherwise, select the previous candidate in the list.
3492 vi-insert, emacs
3494 \bt
3495 complete-next-column
3497 Like the complete command when candidates are not being listed;
3498 otherwise, select the first candidate in the next column in the
3499 list.
3500 complete-prev-column
3502 Like the complete command when candidates are not being listed;
3503 otherwise, select the first candidate in the previous column in
3504 the list.
3505 complete-next-page
3507 Like the complete command when candidates are not being listed;
3508 otherwise, select the first candidate in the next page in the
3509 list.
3510 complete-prev-page
3512 Like the complete command when candidates are not being listed;
3513 otherwise, select the first candidate in the previous page in
3514 the list.
3515 complete-list
3517 Complete a word just before the cursor position.
3518 If you pass no argument, a list of completion candidates is
3520 shown. Otherwise, the word is completed with the nth candidate
3521 where n is the argument.
3522 emacs
3524 \^[?, \^[=
3525 complete-all
3527 Replace a word just before the cursor position with all
3528 possible completion candidates, each separated by a space.
3529 emacs
3531 \^[*
3532 complete-max
3534 Complete a word just before the cursor position with the
3535 longest prefix of all possible completion candidates.
3536 complete-max-then-list
3538 Works like the complete-max command for the first use, then
3539 like the complete command when used successively.
3540 complete-max-then-next-candidate
3542 Works like the complete-max command for the first use, then
3543 like the complete-next-candidate command when used
3544 successively.
3545 complete-max-then-prev-candidate
3547 Works like the complete-max command for the first use, then
3548 like the complete-prev-candidate command when used
3549 successively.
3550 clear-candidates
3552 Clear the list of completion candidates.
3553 Vi-specific commands
3555 vi-replace-char
3556 Replace the character at the cursor position with a character
3557 that is entered just after this command.
3558 vi-command
3560 r
3561 vi-insert-beginning
3563 Move the cursor to the beginning of the line and switch to the
3564 vi insert mode.
3565 vi-command
3567 I
3568 vi-append
3570 Move the cursor to the next character and switch to the vi
3571 insert mode.
3572 vi-command
3574 I
3575 vi-append-to-eol
3577 Move the cursor to the end of the line and switch to the vi
3578 insert mode.
3579 vi-command
3581 A
3582 vi-replace
3584 Switch to the vi insert mode and start overwriting. While
3585 overwriting, the self-insert command replaces the character at
3586 cursor position rather than inserting a character. Overwriting
3587 ends when the editing mode is changed.
3588 vi-command
3590 R
3591 vi-switch-case
3593 Switch case of characters between the current and next cursor
3594 positions. This command must be followed by a motion command,
3595 which determines the next cursor position.
3596 vi-switch-case-char
3598 Switch case of the character at the current cursor position and
3599 move the cursor to the next character.
3600 vi-command
3602 ~
3603 vi-yank
3605 Add to the kill ring the characters between the current and
3606 next cursor positions. This command must be followed by a
3607 motion command, which determines the next cursor position.
3608 vi-command
3610 y
3611 vi-yank-to-eol
3613 Add to the kill ring the characters from the current cursor
3614 position to the end of the line.
3615 vi-command
3617 Y
3618 vi-delete
3620 Delete characters between the current and next cursor positions
3621 and add it to the kill ring. This command must be followed by a
3622 motion command, which determines the next cursor position.
3623 vi-command
3625 d
3626 vi-delete-to-eol
3628 Delete the characters from the current cursor position to the
3629 end of the line and add it to the kill ring.
3630 vi-command
3632 D
3633 vi-change
3635 Delete characters between the current and next cursor positions
3636 and switch to the vi insert mode. This command must be followed
3637 by a motion command, which determines the next cursor position.
3638 vi-command
3640 c
3641 vi-change-to-eol
3643 Delete the characters from the current cursor position to the
3644 end of the line and switch to the vi insert mode.
3645 vi-command
3647 C
3648 vi-change-line
3650 Delete the whole buffer contents and switch to the vi insert
3651 mode.
3652 vi-command
3654 S
3655 vi-yank-and-change
3657 Like the vi-change command, but the deleted text is added to
3658 the kill ring.
3659 vi-yank-and-change-to-eol
3661 Like the vi-change-to-eol command, but the deleted text is
3662 added to the kill ring.
3663 vi-yank-and-change-line
3665 Like the vi-change-line command, but the deleted text is added
3666 to the kill ring.
3667 vi-substitute
3669 Delete a character at the current cursor position, add it to
3670 the kill ring, and switch to the vi insert mode.
3671 vi-command
3673 s
3674 vi-append-last-bigword
3676 Insert a space and the last bigword in the most recent command
3677 history entry just after the current cursor position and switch
3678 to the vi insert mode. If argument n is passed, the nth bigword
3679 in the entry is inserted instead of the last.
3680 vi-command
3682 _
3683 vi-exec-alias
3685 Execute the value of an alias named _c as editing commands
3686 where c is a character input just after this command.
3687 vi-command
3689 @
3690 vi-edit-and-accept
3692 Start the vi editor to edit the current buffer contents. When
3693 the editor finished, the edited buffer contents is accepted
3694 like the accept-line command unless the exit status of the
3695 editor is non-zero.
3696 vi-command
3698 v
3699 vi-complete-list
3701 Like the complete-list command, but also switch to the vi
3702 insert mode.
3703 vi-command
3705 =
3706 vi-complete-all
3708 Like the complete-all command, but also switch to the vi insert
3709 mode.
3710 vi-command
3712 *
3713 vi-complete-max
3715 Like the complete-max command, but also switch to the vi insert
3716 mode.
3717 vi-command
3719 \\
3720 vi-search-forward
3722 Switch to the vi search mode and start forward history search.
3723 vi-command
3725 ?
3726 vi-search-backward
3728 Switch to the vi search mode and start backward history search.
3729 vi-command
3731 /
3732 Emacs-specific commands
3734 emacs-transpose-chars
3735 Move a character just before the cursor to the right.
3736 emacs
3738 \^T
3739 emacs-transpose-words
3741 Move an emacsword just before the cursor to the right.
3742 emacs
3744 \^[t, \^[T
3745 emacs-downcase-word
3747 Make an emacsword just after the cursor lowercase.
3748 emacs
3750 \^[l, \^[L
3751 emacs-upcase-word
3753 Make an emacsword just after the cursor uppercase.
3754 emacs
3756 \^[u, \^[U
3757 emacs-capitalize-word
3759 Capitalize the first letter of an emacsword just after the
3760 cursor.
3761 emacs
3763 \^[c, \^[u
3764 emacs-delete-horizontal-space
3766 Delete spaces around the cursor. If any argument was passed,
3767 delete spaces just before the cursor only.
3768 emacs
3770 \^[\\
3771 emacs-just-one-space
3773 Delete spaces around the cursor and leave one space. If an
3774 argument is specified, leave as many spaces as the argument.
3775 emacs
3777 \^[ (Escape followed by a space)
3778 emacs-search-forward
3780 Switch to the emacs search mode and start forward history
3781 search.
3782 emacs
3784 \^S
3785 emacs-search-backward
3787 Switch to the emacs search mode and start backward history
3788 search.
3789 emacs
3791 \^R
3792 History-related commands
3794 oldest-history
3795 Recall the oldest entry in the history. If argument n is
3796 passed, the entry whose number is n is recalled instead. The
3797 cursor position remains unchanged.
3798 newest-history
3800 Recall the newest entry in the history. If argument n is
3801 passed, the entry whose number is n is recalled instead. The
3802 cursor position remains unchanged.
3803 return-history
3805 Return to the initial buffer corresponding to none of existing
3806 history entries. If argument n is passed, the entry whose
3807 number is n is recalled instead. The cursor position remains
3808 unchanged.
3809 oldest-history-bol
3811 Recall the oldest entry in the history and move the cursor to
3812 the beginning of the line. If argument n is passed, the entry
3813 whose number is n is recalled instead.
3814 vi-command
3816 G
3817 newest-history-bol
3819 Recall the newest entry in the history and move the cursor to
3820 the beginning of the line. If argument n is passed, the entry
3821 whose number is n is recalled instead.
3822 return-history-bol
3824 Return to the initial buffer corresponding to none of existing
3825 history entries and move the cursor to the beginning of the
3826 line. If argument n is passed, the entry whose number is n is
3827 recalled instead.
3828 vi-command
3830 g
3831 oldest-history-eol
3833 Recall the oldest entry in the history and move the cursor to
3834 the end of the line. If argument n is passed, the entry whose
3835 number is n is recalled instead.
3836 emacs
3838 \^[<
3839 newest-history-eol
3841 Recall the newest entry in the history and move the cursor to
3842 the end of the line. If argument n is passed, the entry whose
3843 number is n is recalled instead.
3844 return-history-eol
3846 Return to the initial buffer corresponding to none of existing
3847 history entries and move the cursor to the end of the line. If
3848 argument n is passed, the entry whose number is n is recalled
3849 instead.
3850 emacs
3852 \^[>
3853 next-history
3855 Recall the next history entry. The cursor position remains
3856 unchanged.
3857 prev-history
3859 Recall the previous history entry. The cursor position remains
3860 unchanged.
3861 next-history-bol
3863 Recall the next history entry and move the cursor to the
3864 beginning of the line.
3865 vi-command
3867 j, +, \D, \^N
3868 prev-history-bol
3870 Recall the previous history entry and move the cursor to the
3871 beginning of the line.
3872 vi-command
3874 k, -, \U, \^P
3875 next-history-eol
3877 Recall the next history entry and move the cursor to the end of
3878 the line.
3879 vi-insert, emacs
3881 \D, \^N
3882 prev-history-eol
3884 Recall the previous history entry and move the cursor to the
3885 end of the line.
3886 vi-insert, emacs
3888 \U, \^P
3889 search-again
3891 Repeat the last command history search.
3892 vi-command
3894 n
3895 search-again-rev
3897 Repeat the last command history search in the reverse
3898 direction.
3899 vi-command
3901 N
3902 search-again-forward
3904 Repeat the last command history search in the forward
3905 direction.
3906 search-again-backward
3908 Repeat the last command history search in the backward
3909 direction.
3910 beginning-search-forward
3912 Recall the next history entry that starts with the same text as
3913 the text from the beginning of the line up to the current
3914 cursor position. The cursor position remains unchanged.
3915 beginning-search-backward
3917 Recall the previous history entry that starts with the same
3918 text as the text from the beginning of the line up to the
3919 current cursor position. The cursor position remains unchanged.
3920 Search mode commands
3922 srch-self-insert
3923 Insert the input character at the current cursor position.
3924 Characters escaped by escape sequences cannot be inserted.
3925 vi-search, emacs-search
3927 \\
3928 srch-backward-delete-char
3930 Delete the last character in the search text. If the text is
3931 empty:
3932 • like the srch-abort-search command when in the vi search
3934 mode, or
3935 • like the alert command when in the emacs search mode.
3937 vi-search, emacs-search
3939 \B, \?, \^H
3940 srch-backward-delete-line
3942 Delete the whole search text.
3943 vi-search, emacs-search
3945 \$, \^U
3946 srch-continue-forward
3948 Find the next matching history entry.
3949 emacs-search
3951 \^S
3952 srch-continue-backward
3954 Find the previous matching history entry.
3955 emacs-search
3957 \^R
3958 srch-accept-search
3960 Finish the search mode, accepting the result being shown.
3961 vi-search
3963 \^J, \^M
3964 emacs-search
3966 \^J, \^[
3967 srch-abort-search
3969 Abort search and restore the previous buffer contents.
3970 vi-search
3972 \^[
3973 emacs-search
3975 \^G
3976 Escape sequences
3978 In the bindkey built-in, escape sequences are used to represent special
3979 keys such as function keys and arrow keys. Every escape sequence starts
3980 with a backslash (\) and thus there is also an escape sequence for a
3981 backslash itself.
3982 Below are available escape sequences:
3984 \\
3986 Backslash (\)
3987 \B
3989 Backspace
3990 \D
3992 Down arrow
3993 \E
3995 End
3996 \H
3998 Home
3999 \I
4001 Insert (Insert-char, Enter-insert-mode)
4002 \L
4004 Left arrow
4005 \N
4007 Page-down (Next-page)
4008 \P
4010 Page-up (Previous-page)
4011 \R
4013 Right arrow
4014 \U
4016 Up arrow
4017 \X
4019 Delete
4020 \!
4022 INTR
4023 \#
4025 EOF
4026 \$
4028 KILL
4029 \?
4031 ERASE
4032 \^@
4034 Ctrl + @
4035 \^A, \^B, ..., \^Z
4037 Ctrl + A, Ctrl + B, ..., Ctrl + Z
4038 Note that Ctrl + I, Ctrl + J, and Ctrl + M are tab, newline, and
4040 carriage return, respectively.
4041 \^[
4043 Ctrl + [ (Escape)
4044 \^\
4046 Ctrl + \
4047 \^]
4049 Ctrl + ]
4050 \^^
4052 Ctrl + ^
4053 \^_
4055 Ctrl + _
4056 \^?
4058 Ctrl + ? (Delete)
4059 \F00, \F01, ..., \F63
4061 F0, F1, ..., F63
4062 \a1
4064 Top-left on keypad
4065 \a3
4067 Top-right on keypad
4068 \b2
4070 Center on keypad
4071 \bg
4073 Beginning
4074 \bt
4076 Back-tab
4077 \c1
4079 Bottom-left on keypad
4080 \c3
4082 Bottom-right on keypad
4083 \ca
4085 Clear-all-tabs
4086 \cl
4088 Close
4089 \cn
4091 Cancel
4092 \co
4094 Command
4095 \cp
4097 Copy
4098 \cr
4100 Create
4101 \cs
4103 Clear-screen or erase
4104 \ct
4106 Clear-tab
4107 \dl
4109 Delete-line
4110 \ei
4112 Exit-insert-mode
4113 \el
4115 Clear-to-end-of-line
4116 \es
4118 Clear-to-end-of-screen
4119 \et
4121 Enter (Send)
4122 \ex
4124 Exit
4125 \fd
4127 Find
4128 \hp
4130 Help
4131 \il
4133 Insert-line
4134 \ll
4136 Home-down
4137 \me
4139 Message
4140 \mk
4142 Mark
4143 \ms
4145 Mouse event
4146 \mv
4148 Move
4149 \nx
4151 Next-object
4152 \on
4154 Open
4155 \op
4157 Options
4158 \pr
4160 Print (Copy)
4161 \pv
4163 Previous-object
4164 \rd
4166 Redo
4167 \re
4169 Resume
4170 \rf
4172 Ref (Reference)
4173 \rh
4175 Refresh
4176 \rp
4178 Replace
4179 \rs
4181 Restart
4182 \sf
4184 Scroll-forward (Scroll-down)
4185 \sl
4187 Select
4188 \sr
4190 Scroll-backward (Scroll-up)
4191 \st
4193 Set-tab
4194 \su
4196 Suspend
4197 \sv
4199 Save
4200 \ud
4202 Undo
4203 \SE
4205 Shift + End
4206 \SH
4208 Shift + Home
4209 \SI
4211 Shift + Insert
4212 \SL
4214 Shift + Left arrow
4215 \SR
4217 Shift + Right arrow
4218 \SX
4220 Shift + Delete
4221 \Sbg
4223 Shift + Beginning
4224 \Scn
4226 Shift + Cancel
4227 \Sco
4229 Shift + Command
4230 \Scp
4232 Shift + Copy
4233 \Scr
4235 Shift + Create
4236 \Sdl
4238 Shift + Delete-line
4239 \Sel
4241 Shift + End-of-line
4242 \Sex
4244 Shift + Exit
4245 \Sfd
4247 Shift + Find
4248 \Shp
4250 Shift + Help
4251 \Smg
4253 Shift + Message
4254 \Smv
4256 Shift + Move
4257 \Snx
4259 Shift + Next
4260 \Sop
4262 Shift + Options
4263 \Spr
4265 Shift + Print
4266 \Spv
4268 Shift + Previous
4269 \Srd
4271 Shift + Redo
4272 \Sre
4274 Shift + Resume
4275 \Srp
4277 Shift + Replace
4278 \Ssu
4280 Shift + Suspend
4281 \Ssv
4283 Shift + Save
4284 \Sud
4286 Shift + Undo
4287 INTR, EOF, KILL, and ERASE are special characters configured by the
4289 stty command. In a typical configuration, they are sent by typing
4290 Ctrl+C, Ctrl+D, Ctrl+U, and Ctrl+H, respectively, but some
4291 configuration uses Ctrl+? instead of Ctrl+H for ERASE.
4292 Command line completion
4294 By using the complete and complete-next-candidate commands, etc., you
4295 can complete command names, options, and operands. By default, the
4296 complete-next-candidate command is bound with the Tab key in the vi
4297 insert and emacs modes.
4298 Type a few first letters of a command name or pathname and hit the Tab
4300 key, and a list of matching names will be shown. You can choose a
4301 candidate from the list to complete the name by hitting the Tab key
4302 again. If there is only one matching name, no list will be shown and
4303 the name will directly be completed.
4304 If the name to be completed contains characters like * and ?, it is
4306 treated as a pattern. The name on the command line will be directly
4307 substituted with all possible names matching the pattern (you cannot
4308 choose from a list).
4309 Normally, command names are completed with command names and command
4311 arguments with pathnames. However, completion functions can be defined
4312 to refine completion results.
4313 Completion details
4315 When doing completion for the first time after the shell has been
4316 started, the INIT file is loaded as if the command string . -AL
4317 completion/INIT is executed. If the file is not found, it is
4318 silently ignored. This automatic loading is mainly intended for
4319 loading completion functions bundled with the shell, but you can
4320 let the shell load your own functions by putting a file in the load
4321 path.
4322 When completing a command name, the shell executes the
4324 completion//command function and when completing a command
4325 argument, the completion//argument function. If those completion
4326 functions are not defined, the shell just completes with command
4327 names or pathnames. When completing other names, such as the user
4328 name in tilde expansion and the parameter name in parameter
4329 expansion, completion functions are never used: the shell just
4330 completes with user names, parameter names, or whatever applicable.
4331 Completion functions are executed without any arguments. The
4333 following local variables are automatically defined while executing
4334 completion functions:
4335 IFS
4337 The value is the three characters of a space, a tab, and a
4338 newline, which are the default value of the variable.
4339 WORDS
4341 This variable is an array whose elements are a command name and
4342 arguments that have already been entered before the argument
4343 being completed. When completing a command name, the array has
4344 no elements.
4345 TARGETWORD
4347 The value is the partially entered command name or argument
4348 that is being completed.
4349 Completion candidates are generated by executing the complete
4351 built-in during a completion function.
4352 Completion functions must not perform I/O to the terminal, or
4354 displayed text will be corrupted. Completion functions should run
4355 as quickly as possible for better user experience.
4356 While a completion function is being executed:
4358 • the POSIXly-correct mode and the err-return option are
4360 temporarily disabled,
4361 • the err-exit option is temporarily ignored, and
4363 • traps are not executed.
4365 Command line prediction
4367 This is an experimental feature. When the le-predict option is enabled,
4368 the shell automatically tries to predict a command string fragment that
4369 follows the part of the command you have already typed in line-editing.
4370 For example, assume you have once typed the command ls Documents. Next
4372 time you start typing ls Doc, the shell will show uments just after the
4373 cursor. If you are satisfied with this suggestion, you can move the
4374 cursor to the right by the forward-char or any other motion commands
4375 instead of typing the rest of the command. After moving the cursor
4376 after the last s, you can use the accept-line command to execute the
4377 command. You can also use the accept-prediction command to immediately
4378 execute the suggested command without moving the cursor.
4379 To distinguish the typed part and the predicted part of a command
4381 string, you can change the font style of the typed part by setting the
4382 PS1S variable. Customizing the font style of the predicted part is not
4383 (yet) supported; it is always shown in the default style.
4384 When you move the cursor to the right, the predicted part up to the
4386 cursor becomes the typed part as if you actually typed it. Moving the
4387 cursor to the left does not turn the typed part back to the prediction.
4388 Use deletion commands such as backward-delete-char to delete typed
4389 command fragment.
4390 The predicted part of the command is shown only when the cursor is at
4392 the end of the typed part.
4393 By default, the predicted part is shown after you start typing a
4395 command string. By enabling the le-predict-empty option, the predicted
4396 part is also shown before you type the first character of the command
4397 string.
4398 The prediction algorithm suggests command fragments on the basis of the
4400 command history. The algorithm considers recent history entries more
4401 probable. It also takes command succession patterns into account. A
4402 predicted command fragment is not always a complete valid command
4403 because less probable part of the fragment is excluded from prediction.
4404
4406 Yash behaves as defined in POSIX.1-2008, Shell & Utilities for the most
4407 part, but some functionalities disobey POSIX for usability. When full
4408 POSIX-conformance is needed, you can enable the POSIXly-correct mode to
4409 make yash obey POSIX as much as possible.
4410 If yash is started with the name “sh”, the POSIXly-correct mode is
4412 automatically enabled. The -o posixly-correct command-line option also
4413 enables the POSIXly-correct mode. After yash has been started, the
4414 POSIXly-correct mode can be enabled by executing the command string set
4415 -o posixly-correct.
4416 When the POSIXly-correct mode is on, yash not only tries to obey the
4418 requirements by POSIX, but also treats as errors most conditions where
4419 the behavior is undefined or unspecified by POSIX. As a result, most
4420 yash-specific functionalities are disabled in the POSIXly-correct mode.
4421 Below is the complete list of the behavioral differences between when
4423 yash is in the POSIXly-correct mode and when not. When the
4424 POSIXly-correct mode is enabled:
4425 • Different initialization scripts are used.
4427 • If the shell was started with the -c option, sh -c (instead of yash
4429 -c) is printed as the script pathname on a syntax error.
4430 • Global aliases are not substituted.
4432 • Nested commands in a compound command must not be empty.
4434 • The for loop iteration variable is created as global, regardless of
4436 the for-local shell option. The variable must have a portable
4437 (ASCII-only) name.
4438 • The first pattern in a case command cannot be esac.
4440 • The ! keyword cannot be followed by ( without any whitespaces
4442 in-between.
4443 • The double-bracket command cannot be used.
4445 • The function keyword cannot be used for function definition. The
4447 function must have a portable (ASCII-only) name.
4448 • Simple commands cannot assign to arrays.
4450 • Changing the value of the LC_CTYPE variable after the shell has
4452 been initialized does not affect the shell’s locale.
4453 • The RANDOM variable cannot be used to generate random numbers.
4455 • Tilde expansion only expands ~ and ~username.
4457 • Parameter expansion cannot be nested. No indexes or modifiers with
4459 word2 are allowed.
4460 • The commands in a command substitution of the form $(commands) are
4462 parsed every time the substitution is executed.
4463 • In arithmetic expansion, fractional numbers and the ++ and --
4465 operators cannot be used. All variables must be numeric.
4466 • The operand of a redirection cannot be the integer prefix to a next
4468 redirection operator.
4469 • A compound command with a redirection cannot be immediately
4471 followed by a keyword like } and fi.
4472 • In a redirection to a file, if the pathname expansion yielded more
4474 than one or no pathname, it is not immediately treated as an error.
4475 Instead, the shell tries to treat the word before the expansion as
4476 a pathname.
4477 • A file descriptor must be readable and writable when duplicated by
4479 the <& and >& redirection operator, respectively.
4480 • Socket redirection, here strings, pipe redirection, and process
4482 redirection cannot be used.
4483 • When executing a simple command, failure in command search does not
4485 trigger execution of the COMMAND_NOT_FOUND_HANDLER variable.
4486 • In command search, a regular built-in needs to have a corresponding
4488 external command for the built-in to be found.
4489 • Some built-ins behave differently. Especially, long command-line
4491 options (as well as some others) cannot be used.
4492 • A non-interactive shell exits when a special built-in is given a
4494 syntactically wrong arguments or when an error occurs in assignment
4495 or redirection with a special built-in.
4496 • An interactive shell does not execute the PROMPT_COMMAND variable
4498 before printing a prompt. The values of the PS1, PS2, and PS4
4499 variables are parsed differently. Prompt variables with a YASH_
4500 prefix (e.g. YASH_PS1) are not used.
4501 • In mail checking, a notification message is printed if the file has
4503 been modified, regardless of whether the file is empty.
4504
4506 How can I use Unicode (non-ASCII) characters?
4507 You need to set locale environment variables to enable Unicode
4508 character support.
4509 If the variables have already been configured for your preference, you
4511 probably don’t have to do anything. To check the current locale
4512 configurations, you can use the locale command:
4513 $ locale
4515 LANG=
4516 LC_CTYPE="en_US.utf8"
4517 LC_NUMERIC="en_US.utf8"
4518 LC_TIME="en_US.utf8"
4519 LC_COLLATE="en_US.utf8"
4520 LC_MONETARY="en_US.utf8"
4521 LC_MESSAGES="en_US.utf8"
4522 LC_PAPER="en_US.utf8"
4523 LC_NAME="en_US.utf8"
4524 LC_ADDRESS="en_US.utf8"
4525 LC_TELEPHONE="en_US.utf8"
4526 LC_MEASUREMENT="en_US.utf8"
4527 LC_IDENTIFICATION="en_US.utf8"
4528 LC_ALL=en_US.utf8
4529 In this example, the locale command shows that all the locale setting
4531 categories are configured for the English language, the United States
4532 region, and the UTF-8 encoding.
4533 If the current configuration does not seem to match your preference,
4535 set the LC_ALL variable like this:
4536 export LC_ALL=en_US.utf8
4538 If you want to use other languages, regions, or encodings, you have to
4540 set the variable to a different value. Please consult your OS’s
4541 documentation to learn how to configure these variables in detail.
4542 If you want to apply the same configuration every time you start yash,
4544 write the command in ~/.yashrc or ~/.yash_profile.
4545 If yash still rejects Unicode characters being entered, see the section
4547 below regarding line-editing.
4548 Line-editing does not work
4550 First, type echo $TERM and see if it prints a sane value. xterm is the
4551 safest value that should work on any existing environment. Colored
4552 versions like xterm-16color and other terminal types like rxvt and
4553 vt100 may also work. All possible values can be listed by the toe
4554 command. It’s most desirable to choose a value that matches the actual
4555 terminal type you are using, but it might not work if the terminal type
4556 you chose is not supported on the system on which yash is running. If
4557 so, try changing the TERM value by export TERM=xterm, for example, to
4558 find a value that works.
4559 If line-editing works but you have trouble entering Unicode (non-ASCII)
4561 characters, try enabling the le-no-conv-meta option by set -o
4562 le-no-conv-meta.
4563
4565 This chapter defines the syntax of the shell command language.
4566 Note
4568 Some of the syntactic features described below are not supported in
4569 the POSIXly-correct mode.
4570 Tokenization
4572 The characters of the input source code are first delimited into
4573 tokens. Tokens are delimited so that the earlier token spans as long as
4574 possible. A sequence of one or more unquoted blank characters delimits
4575 a token.
4576 The following tokens are the operator tokens:
4578 & && ( ) ; ;; | || < << <& <( <<- <<< <> > >> >& >( >>| >| (newline)
4580 Note
4582 Unlike other programming languages, the newline operator is a token
4583 rather than a white space.
4584 Characters that are not blank nor part of an operator compose a word
4586 token. Words are parsed by the following parsing expression grammar:
4587 Word
4589 (WordElement / !SpecialChar .)+
4590 WordElement
4592 \ . /
4593 ' (!' .)* ' /
4595 " QuoteElement* " /
4597 Parameter /
4599 Arithmetic /
4601 CommandSubstitution
4603 QuoteElement
4605 \ ([$`"\] / <newline>) /
4606 Parameter /
4608 Arithmetic /
4610 CommandSubstitutionQuoted /
4612 ![`"\] .
4614 Parameter
4616 $ [@*#?-$! [:digit:]] /
4617 $ PortableName /
4619 $ ParameterBody
4621 PortableName
4623 ![0-9] [0-9 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]+
4624 ParameterBody
4626 { ParameterNumber? (ParameterName / ParameterBody / $ ParameterBody
4627 / Arithmetic / CommandSubstitution) ParameterIndex?
4628 ParameterMatch? }
4629 ParameterNumber
4631 # ![}+=:/%] !([-?#] !})
4632 ParameterName
4634 [@*#?-$!] /
4635 [[:alnum:] _]+
4637 ParameterIndex
4639 [ ParameterIndexWord (, ParameterIndexWord)? ]
4640 ParameterIndexWord
4642 (WordElement / !["'],] .)+
4643 ParameterMatch
4645 :? [-+=?] ParameterMatchWord /
4646 (# / ## / % / %%) ParameterMatchWord /
4648 (:/ / / [#%/]?) ParameterMatchWordNoSlash (/ ParameterMatchWord)?
4650 ParameterMatchWord
4652 (WordElement / !["'}] .)*
4653 ParameterMatchWordNoSlash
4655 (WordElement / !["'/}] .)*
4656 Arithmetic
4658 $(( ArithmeticBody* ))
4659 ArithmeticBody
4661 \ . /
4662 Parameter /
4664 Arithmetic /
4666 CommandSubstitution /
4668 ( ArithmeticBody ) /
4670 ![`()] .
4672 CommandSubstitution
4674 $( CompleteProgram ) /
4675 ` CommandSubstitutionBody* `
4677 CommandSubstitutionQuoted
4679 $( CompleteProgram ) /
4680 ` CommandSubstitutionBodyQuoted* `
4682 CommandSubstitutionBody
4684 \ [$`\] /
4685 !` .
4687 CommandSubstitutionBodyQuoted
4689 \ [$`\`] /
4690 !` .
4692 SpecialChar
4694 [|&;<>()`\"' [:blank:]] / <newline>
4695 The set of terminals of the grammar is the set of characters that can
4697 be handled on the environment in which the shell is run (a.k.a.
4698 execution character set), with the exception that the set does not
4699 contain the null character ('\0').
4700 Strictly speaking, the definition above is not a complete parsing
4702 expression grammar because the rule for CommandSubstitution (Quoted)
4703 depends on CompleteProgram which is a non-terminal of the syntax.
4704 Token classification
4706 After a word token is delimited, the token may be further
4707 classified as an IO_NUMBER token, reserved word, name word,
4708 assignment word, or just normal word. Classification other than the
4709 normal word is applied only when applicable in the context in which
4710 the word appears. See Tokens and keywords for the list of the
4711 reserved words (keywords) and the context in which a word may be
4712 recognized as a reserved word.
4713 A token is an IO_NUMBER token iff it is composed of digit
4715 characters only and immediately followed by < or >.
4716 An assignment token is a token that starts with a name followed by
4718 =:
4719 AssignmentWord
4721 AssignmentPrefix Word
4722 AssignmentPrefix
4724 Name =
4725 Name
4727 ![[:digit:]] \[[:alnum:] _]+
4728 Comments
4730 A comment begins with # and continues up to (but not including) the
4731 next newline character. Comments are treated like a blank character
4732 and do not become part of a token. The initial # of a comment must
4733 appear as if it would otherwise be the first character of a word
4734 token; Other #s are just treated as part of a word token.
4735 Comment
4737 # (!<newline> .)*
4738 Syntax
4740 After tokens have been delimited, the sequence of the tokens is parsed
4741 according to the context-free grammar defined below, where *, +, and ?
4742 should be interpreted in the same manner as standard regular
4743 expression:
4744 CompleteProgram
4746 NL* | CompoundList
4747 CompoundList
4749 NL* AndOrList ((; | & | NL) CompleteProgram)?
4750 AndOrList
4752 Pipeline ((&& | ||) NL* Pipeline)*
4753 Pipeline
4755 !? Command (| NL* Command)*
4756 Command
4758 CompoundCommand Redirection* |
4759 FunctionDefinition |
4761 SimpleCommand
4763 CompoundCommand
4765 Subshell |
4766 Grouping |
4768 IfCommand |
4770 ForCommand |
4772 WhileCommand |
4774 CaseCommand |
4776 DoubleBracketCommand |
4778 FunctionCommand
4780 Subshell
4782 ( CompoundList )
4783 Grouping
4785 { CompoundList }
4786 IfCommand
4788 if CompoundList then CompoundList (elif CompoundList then
4789 CompoundList)* (else CompoundList)? fi
4790 ForCommand
4792 for Name ((NL* in Word*)? (; | NL) NL*)? do CompoundList done
4793 WhileCommand
4795 (while | until) CompoundList do CompoundList done
4796 CaseCommand
4798 case Word NL* in NL* CaseList? esac
4799 CaseList
4801 CaseItem (;; NL* CaseList)?
4802 CaseItem
4804 (? Word (| Word)* ) CompleteProgram
4805 DoubleBracketCommand
4807 [[ Ors ]]
4808 Ors
4810 Ands (|| Ands)*
4811 Ands
4813 Nots (&& Nots)*
4814 Nots
4816 !* Primary
4817 Primary
4819 (-b | -c | -d | -e | -f | -G | -g | -h | -k | -L | -N | -n | -O |
4820 -o | -p | -r | -S | -s | -t | -u | -w | -x | -z) Word |
4821 Word (-ef | -eq | -ge | -gt | -le | -lt | -ne | -nt | -ot | -veq |
4823 -vge | -vgt | -vle | -vlt | -vne | = | == | === | =~ | != | !== | <
4824 | >) Word |
4825 ( Ors ) |
4827 Word
4829 FunctionCommand
4831 function Word (( ))? NL* CompoundCommand Redirection*
4832 FunctionDefinition
4834 Name ( ) NL* CompoundCommand Redirection*
4835 SimpleCommand
4837 (Assignment | Redirection) SimpleCommand? |
4838 Word (Word | Redirection)*
4840 Assignment
4842 AssignmentWord |
4843 AssignmentPrefix( NL* (Word NL*)* )
4845 Redirection
4847 IO_NUMBER? RedirectionOperator Word |
4848 IO_NUMBER? <( CompleteProgram ) |
4850 IO_NUMBER? >( CompleteProgram )
4852 RedirectionOperator
4854 < | <> | > | >| | >> | >>| | <& | >& | << | <<- | <<<
4855 NL
4857 <newline>
4858 In the rule for Primary, Word tokens must not be ]]. Additionally, if a
4860 Primary starts with a Word, it must not be any of the possible unary
4861 operators allowed in the rule.
4862 In the rule for SimpleCommand, a Word token is accepted only when the
4864 token cannot be parsed as the first token of an Assignment.
4865 In the rule for Assignment, the ( token must immediately follow the
4867 AssignmentPrefix token, without any blank characters in between.
4868 Here-document contents do not appear as part of the grammar above. They
4870 are parsed just after the newline (NL) token that follows the
4871 corresponding redirection operator.
4872 Alias substitution
4874 Word tokens are subject to alias substitution.
4875 • If a word is going to be parsed as a Word of a SimpleCommand,
4877 the word is subjected to alias substitution of any kind (normal
4878 and global aliases).
4879 • If a word is the next token after the result of an alias
4881 substitution and the substitution string ends with a blank
4882 character, then the word is also subjected to alias
4883 substitution of any kind.
4884 • Other words are subjected to global alias substitution unless
4886 the shell is in the POSIXly-correct mode.
4887 Tokens that are classified as reserved words are not subject to
4889 alias substitution.
4890
4892 The alias built-in defines and/or prints aliases.
4893 Syntax
4895 • alias [-gp] [name[=value]...]
4896 Description
4898 The alias built-in defines and/or prints aliases as specified by
4899 operands. The printed aliases can be used as (part of) shell commands.
4900 The built-in prints all currently defined aliases when given no
4901 operands.
4902 Options
4904 -g, --global
4905 With this option, aliases are defined as global aliases; without
4906 this option, as normal aliases.
4907 -p, --prefix
4909 With this option, aliases are printed in a full command form like
4910 alias -g foo='bar'. Without this option, only command operands are
4911 printed like foo='bar'.
4912 Operands
4914 name
4915 The name of an alias that should be printed.
4916 name=value
4918 The name and value of an alias that is being defined.
4919 Exit status
4921 The exit status of the alias built-in is zero unless there is any
4922 error.
4923 Notes
4925 The characters that cannot be used in an alias name are the space, tab,
4926 newline, and any of =$<>\'"`;&|()#. You can use any characters in an
4927 alias value.
4928 The alias built-in is a semi-special built-in.
4930 The POSIX standard defines no options for the alias built-in, thus no
4932 options are available in the POSIXly correct mode.
4933
4935 The array built-in prints or modifies arrays.
4936 Syntax
4938 • array
4939 • array name [value...]
4941 • array -d name [index...]
4943 • array -i name index [value...]
4945 • array -s name index value
4947 Description
4949 When executed without any option or operands, the built-in prints all
4950 array definitions to the standard output in a form that can be parsed
4951 as commands.
4952 When executed with name and values (but without an option), the
4954 built-in sets the values as the values of the array named name.
4955 With the -d (--delete) option, the built-in removes the indexth values
4957 of the array named name. The number of values in the array will be
4958 decreased by the number of the indexes specified. If the indexth value
4959 does not exist, it is silently ignored.
4960 With the -i (--insert) option, the built-in inserts values into the
4962 array named name. The number of values in the array will be increased
4963 by the number of the values specified. The values are inserted between
4964 the indexth and next values. If index is zero, the values are inserted
4965 before the first value. If index is larger than the number of values in
4966 the array, the values are appended after the last element.
4967 With the -s (--set) option, the built-in sets value as the indexth
4969 value of the array named name. The array must have at least index
4970 values.
4971 Options
4973 -d, --delete
4974 Delete array values.
4975 -i, --insert
4977 Insert array values.
4978 -s, --set
4980 Set an array value.
4981 Operands
4983 name
4984 The name of an array to operate on.
4985 index
4987 The index to an array element. The first element has the index of
4988 1.
4989 value
4991 A string to which the array element is set.
4992 Exit status
4994 The exit status of the array built-in is zero unless there is any
4995 error.
4996 Notes
4998 The array built-in is not defined in the POSIX standard.
4999 The command array name value... is equivalent to the assignment
5001 name=(value...).
5002
5004 The bg built-in resumes a job in the background.
5005 Syntax
5007 • bg [job...]
5008 Description
5010 The bg built-in sends the SIGCONT signal to the specified job. As a
5011 result, the job is resumed in the background (if it has been
5012 suspended).
5013 The name of the job is printed when the job is resumed.
5015 The built-in can be used only when job control is enabled.
5017 Operands
5019 job
5020 The job ID of the job to be resumed.
5021 More than one job can be specified at a time. The current job is
5023 resumed if none is specified.
5024 The percent sign (%) at the beginning of a job ID can be omitted if
5026 the shell is not in the POSIXly-correct mode.
5027 Exit status
5029 The exit status of the bg built-in is zero unless there is any error.
5030 Notes
5032 The bg built-in is a semi-special built-in.
5033 The POSIX standard provides that the built-in shall have no effect when
5035 the job is already running. The bg built-in of yash, however, always
5036 sends the SIGCONT signal to the job.
5037
5039 The bindkey built-in prints or modifies key bindings used in
5040 line-editing.
5041 Syntax
5043 • bindkey -aev [key [command]]
5044 • bindkey -l
5046 Description
5048 When executed with the -l (--list) option, the built-in lists all
5049 available line-editing commands to the standard output.
5050 When executed with one of the other options, the built-in prints or
5052 modifies key bindings for the editing mode specified by the option:
5053 • Without key or command, all currently defined bindings are printed
5055 to the standard output in a form that can be parsed as commands
5056 that restore the current bindings when executed.
5057 • With key but without command, only the binding for the given key is
5059 printed.
5060 • With key and command, key is bound to command.
5062 Options
5064 -a, --vi-command
5065 Print or modify bindings for the vi command mode.
5066 -e, --emacs
5068 Print or modify bindings for the emacs mode.
5069 -v, --vi-insert
5071 Print or modify bindings for the vi insert mode.
5072 Operands
5074 key
5075 A character sequence of one or more keys that is bound to an
5076 editing command. The sequence may include escape sequences.
5077 command
5079 A line-editing command to which key is bound. If command is a
5080 single hyphen (-), key is unbound.
5081 Exit status
5083 The exit status of the bindkey built-in is zero unless there is any
5084 error.
5085 Notes
5087 The bindkey built-in is a semi-special built-in. In the POSIX standard,
5088 it is defined as a command with unspecified behavior.
5089
5091 The break built-in aborts a loop being executed.
5092 Syntax
5094 • break [nest]
5095 • break -i
5097 Description
5099 When executed without the -i (--iteration) option, the built-in aborts
5100 a currently executed for, while, or until loop. When executed in nested
5101 loops, it aborts the nestth innermost loop. The default nest is one. If
5102 the number of currently executed nested loops is less than nest, the
5103 built-in aborts the outermost loop.
5104 When executed with the -i (--iteration) option, the built-in aborts the
5106 currently executed (innermost) iterative execution.
5107 Options
5109 -i, --iteration
5110 Abort an iterative execution instead of a loop.
5111 Operands
5113 nest
5114 The number of loops to abort, which must be a positive integer.
5115 Exit status
5117 The exit status of the break built-in is:
5118 • zero if a loop was successfully aborted.
5120 • that of the command that was executed just before the break
5122 built-in if an iterative execution was successfully aborted.
5123 Notes
5125 The break built-in is a special built-in.
5126 The POSIX standard defines no options for the break built-in; the
5128 built-in accepts no options in the POSIXly-correct mode.
5129 Treatment of currently executed loops that are not lexically enclosing
5131 the break built-in is unspecified in POSIX. Examples of such loops
5132 include:
5133 • A loop invoking a function in which the break built-in is used.
5135 • A loop in which a trap action is executed in which the break
5137 built-in is used.
5138 Yash does not allow breaking such loops.
5140
5142 The cd built-in changes the working directory.
5143 Syntax
5145 • cd [-L|-P] [directory]
5146 Description
5148 The cd built-in changes the working directory to the directory
5149 specified by the operand.
5150 The pathname of the new working directory is assigned to the PWD
5152 variable, whose previous value is again assigned to the OLDPWD
5153 variable. The new PWD value will not contain any . or .. components
5154 except when the shell is in the POSIXly-correct mode and the new
5155 pathname begins with /...
5156 If directory is a relative path that does not start with ‘.’ or ‘..’,
5158 paths in the CDPATH variable are searched to find a new working
5159 directory. The search is done in a manner similar to the last step of
5160 command search, but a directory is sought instead of an executable
5161 regular file. If a new working directory was found from CDPATH, its
5162 pathname is printed to the standard output. If no applicable directory
5163 was found in the search, directory is simply treated as a pathname
5164 relative to the current working directory.
5165 If the working directory was successfully changed, the value of the
5167 YASH_AFTER_CD variable is executed as a command unless the shell is in
5168 the POSIXly-correct mode. If the variable is an array, its values are
5169 executed iteratively (cf. eval built-in).
5170 Options
5172 -L, --logical
5173 Symbolic links in the pathname of the new working directory are not
5174 resolved. The new value of the PWD may include pathname components
5175 that are symbolic links.
5176 -P, --physical
5178 Symbolic links in the pathname of the new working directory are
5179 resolved. The new value of the PWD variable never includes pathname
5180 components that are symbolic links.
5181 --default-directory=directory
5183 If this option is specified and the directory operand is omitted,
5184 the argument to this option is used for the directory operand. If
5185 the directory operand is specified, this option is ignored.
5186 The -L (--logical) and -P (--physical) options are mutually exclusive:
5188 only the last specified one is effective. If neither is specified, -L
5189 is assumed.
5190 Operands
5192 directory
5193 The pathname of the new working directory.
5194 If directory is a single hyphen (‘-’), the value of the OLDPWD
5196 variable is assumed for the new directory pathname, which is
5197 printed to the standard output.
5198 If directory is omitted, the working directory is changed to the
5200 directory specified by the --default-directory=... option. If that
5201 option is not specified either, the default is the home directory.
5202 Exit status
5204 The exit status of the cd built-in is zero if the working directory was
5205 successfully changed and non-zero if there was an error.
5206 Notes
5208 The cd built-in is a semi-special built-in.
5209 The POSIX standard does not define the use of the YASH_AFTER_CD
5211 variable or the --default-directory=... option. The standard does not
5212 allow using an option with a single hyphen operand.
5213 The exit status of the commands in the YASH_AFTER_CD variable does not
5215 affect that of the cd built-in.
5216
5218 The colon built-in does nothing.
5219 Syntax
5221 • : [argument...]
5222 Description
5224 The colon built-in does nothing. Any command line arguments are
5225 ignored.
5226 Exit status
5228 The exit status of the colon built-in is zero.
5229 Notes
5231 The colon built-in is a special built-in.
5232 Arguments are expanded and redirections are performed as usual. The
5234 colon and true built-ins have the same effect, but colon is a special
5235 built-in while true is a semi-special.
5236
5238 The command built-in executes or identifies a command.
5239 Syntax
5241 • command [-befp] command [argument...]
5242 • command -v|-V [-abefkp] command...
5244 Description
5246 Without the -v (--identify) or -V (--verbose-identify) option, the
5247 built-in executes command with arguments in the same manner as the last
5248 step of execution of simple commands. The command is treated as a
5249 built-in or external command or a function according to the options
5250 specified to the command built-in. The shell does not exit on argument
5251 syntax error etc. even if the command is a special built-in
5252 With the -v (--identify) option, command is identified. If the command
5254 is found in $PATH, its full pathname is printed. If it is a keyword,
5255 function, or built-in that is not found in $PATH, the command name is
5256 simply printed. If it is an alias, it is printed in the form like alias
5257 ll='ls -l'. If the command is not found, nothing is printed and the
5258 exit status is non-zero.
5259 The -V (--verbose-identify) option is similar to the -v (--identify)
5261 option, but the output format is more human-friendly.
5262 Options
5264 -a, --alias
5265 Search for the command as an alias. Must be used with the -v
5266 (--identify) or -V (--verbose-identify) option.
5267 -b, --builtin-command
5269 Search for the command as a built-in.
5270 -e, --external-command
5272 Search for the command as an external command.
5273 -f, --function
5275 Search for the command as a function.
5276 -k, --keyword
5278 Search for the command as a keyword. Must be used with the -v
5279 (--identify) or -V (--verbose-identify) option.
5280 -p, --standard-path
5282 Search the system’s default PATH instead of the current $PATH.
5283 -v, --identify
5285 Identify commands and print in the format defined in the POSIX
5286 standard.
5287 -V, --verbose-identify
5289 Identify commands and print in a human-friendly format.
5290 If none of the -a (--alias), -b (--builtin-command), -e
5292 (--external-command), -f (--function), and -k (--keyword) options is
5293 specified, the following defaults are assumed:
5294 Without the -v (--identify) or -V (--verbose-identify) option
5296 -b -e
5297 With the -v (--identify) or -V (--verbose-identify) option
5299 -a -b -e -f -k
5300 Operands
5302 command
5303 A command to be executed or identified.
5304 argument...
5306 Arguments passed to the executed command.
5307 Exit status
5309 The exit status of the command built-in is:
5310 Without the -v (--identify) or -V (--verbose-identify) option
5312 the exit status of the executed command.
5313 With the -v (--identify) or -V (--verbose-identify) option
5315 zero unless there is any error.
5316 Notes
5318 The command built-in is a semi-special built-in.
5319 In the POSIXly-correct mode, options other than -p, -v, and -V cannot
5321 be used and at most one command can be specified. The POSIX standard
5322 does not allow specifying both -v and -V together, but yash does (only
5323 the last specified one is effective).
5324
5326 The complete built-in generates completion candidates. This built-in
5327 can only be executed from completion functions during command line
5328 completion.
5329 Syntax
5331 • complete [-A pattern] [-R pattern] [-T] [-P prefix] [-S suffix]
5332 [-abcdfghjkuv] [[-O] [-D description] word...]
5333 Description
5335 The built-in generates completion candidates according to the specified
5336 arguments. No matter how candidates are generated, only candidates that
5337 match the word being completed are generated.
5338 Options
5340 -A pattern, --accept=pattern
5341 Only accept candidates that match the pattern specified by this
5342 option. When more than one of this option is specified, only
5343 candidates that match all of the patterns are generated.
5344 -D description, --description=description
5346 Give a description of the word candidates. The description is shown
5347 beside the candidates in the candidate list.
5348 -O, --option
5350 The candidates are treated as command line options. A hyphen is
5351 prepended to each candidate that is treated as an option.
5352 -P prefix, --prefix=prefix
5354 Ignore prefix of the word being completed when generating
5355 candidates. The specified prefix must be initial part of the word.
5356 If the word being completed is file:///home/user/docume for
5358 example, the command line complete -P file:// -f will generate
5359 pathname candidates that complete /home/user/docume.
5360 -R pattern, --reject=pattern
5362 Reject candidates that match the pattern specified by this option.
5363 When more than one of this option is specified, only candidates
5364 that match none of the patterns are generated.
5365 -S suffix, --suffix=suffix
5367 Append suffix to each generated candidate.
5368 -T, --no-termination
5370 Do not append a space after the word is completed. Without this
5371 option, a space is appended to the completed word so that you do
5372 not have to enter a space before the next word.
5373 Options that select candidate types
5375 -a, --alias
5376 Aliases. (same as --normal-alias --global-alias)
5377 --array-variable
5379 Arrays.
5380 --bindkey
5382 Line-editing commands the bindkey built-in accepts.
5383 -b, --builtin-command
5385 Built-in commands. (same as --special-builtin
5386 --semi-special-builtin --regular-builtin)
5387 -c, --command
5389 Commands. (same as --builtin-command --external-command
5390 --function)
5391 -d, --directory
5393 Directories.
5394 --dirstack-index
5396 Valid indices of the directory stack.
5397 --executable-file
5399 Executable regular files.
5400 --external-command
5402 External commands.
5403 -f, --file
5405 Files (including directories).
5406 --finished-job
5408 Job IDs of finished jobs.
5409 --function
5411 Functions.
5412 --global-alias
5414 Global aliases.
5415 -g, --group
5417 User groups.
5418 -h, --hostname
5420 Host names.
5421 -j, --job
5423 Job IDs.
5424 -k, --keyword
5426 Keywords.
5427 --normal-alias
5429 Normal aliases.
5430 --regular-builtin
5432 Regular built-in commands.
5433 --running-job
5435 Job IDs of jobs that are being executed.
5436 --scalar-variable
5438 Variables that are not arrays.
5439 --semi-special-builtin
5441 Semi-special built-in commands.
5442 --signal
5444 Signals.
5445 --special-builtin
5447 Special built-in commands.
5448 --stopped-job
5450 Job IDs of jobs that are suspended.
5451 -u, --username
5453 Users' log-in names.
5454 -v, --variable
5456 Variables.
5457 If the -d (--directory) option is specified without the -f (--file)
5459 option, the -S / -T options are assumed.
5460 Generated candidates for job IDs do not have leading percent signs
5462 (%). If the word being completed starts with a percent sign, the -P
5463 % option should be specified.
5464 Operands
5466 Operands are treated as completion candidates.
5467 Exit status
5469 The exit status of the built-in is zero if one or more candidates were
5470 generated, one if no candidates were generated, or larger than one if
5471 an error occurred.
5472 Notes
5474 The complete built-in is a semi-special built-in. In the POSIX
5475 standard, it is defined as a command with unspecified behavior.
5476
5478 The continue built-in skips an iteration of a loop being executed.
5479 Syntax
5481 • continue [nest]
5482 • continue -i
5484 Description
5486 When executed without the -i (--iteration) option, the built-in aborts
5487 the current iteration of for, while, or until loop and starts the next
5488 iteration of the loop. When executed in nested loops, it affects the
5489 nestth innermost loop. The default nest is one. If the number of
5490 currently executed nested loops is less than nest, the built-in affects
5491 the outermost loop.
5492 When executed with the -i (--iteration) option, the built-in aborts the
5494 current iteration of (innermost) iterative execution.
5495 Options
5497 -i, --iteration
5498 Skip an iterative execution instead of a loop.
5499 Operands
5501 nest
5502 The nestth innermost loop is affected. nest must be a positive
5503 integer.
5504 Exit status
5506 The exit status of the continue built-in is:
5507 • zero if loop iteration was successfully skipped.
5509 • that of the command that was executed just before the continue
5511 built-in if iterative execution was successfully skipped.
5512 Notes
5514 The continue built-in is a special built-in.
5515 The POSIX standard defines no options for the continue built-in; the
5517 built-in accepts no options in the POSIXly-correct mode.
5518 Treatment of currently executed loops that are not lexically enclosing
5520 the continue built-in is unspecified in POSIX. Examples of such loops
5521 include:
5522 • A loop invoking a function in which the continue built-in is used
5524 • A loop in which a trap action is executed in which the continue
5526 built-in is used
5527 Yash does not allow continuing such loops.
5529
5531 The dirs built-in prints the contents of the directory stack.
5532 Syntax
5534 • dirs [-cv] [index..]
5535 Description
5537 The directory stack is a feature that records history of working
5538 directories. You can use the pushd built-in to save a working directory
5539 in the directory stack, the popd built-in to recall the saved working
5540 directory, and the dirs built-in to see the stack contents. Those
5541 built-ins use the DIRSTACK array and the PWD variable to save the stack
5542 contents. Modifying the array means modifying the stack contents.
5543 Directory stack entries are indexed by signed integers. The entry of
5545 index +0 is the current working directory, +1 is the last saved
5546 directory, +2 is the second last, and so on. Negative indices are in
5547 the reverse order: the entry of index -0 is the first saved directory,
5548 -1 is the second, and -n is the current working directory if the stack
5549 has n entries,
5550 When executed without the -c (--clear) option, the dirs built-in prints
5552 the current contents of the directory stack to the standard output.
5553 With the -c (--clear) option, the built-in clears the directory stack.
5554 Options
5556 -c, --clear
5557 Clear the directory stack contents except for the current working
5558 directory, which has index +0.
5559 -v, --verbose
5561 Print indices when printing stack contents.
5562 Operands
5564 index
5565 The index of a stack entry to be printed.
5566 You can specify more than one index. If you do not specify any
5568 index, all the entries are printed.
5569 Exit status
5571 The exit status of the dirs built-in is zero unless there is any error.
5572 Notes
5574 The dirs built-in is a semi-special built-in. In the POSIX standard, it
5575 is defined as a command with unspecified behavior.
5576
5578 The disown built-in removes jobs.
5579 Syntax
5581 • disown [-a] [job...}
5582 Description
5584 The disown built-in removes the specified jobs from the job list. The
5585 removed jobs will no longer be job-controlled, but the job processes
5586 continue execution (unless they have been suspended).
5587 Options
5589 -a, --all
5590 Removes all jobs.
5591 Operands
5593 job
5594 The job ID of the job to be removed.
5595 You can specify more than one job ID. If you do not specify any job
5597 ID, the current job is removed. If the shell is not in the
5598 POSIXly-correct mode, the %-prefix of the job ID can be omitted.
5599 Exit status
5601 The exit status of the disown built-in is zero unless there is any
5602 error.
5603 Notes
5605 The disown built-in is a semi-special built-in. In the POSIX standard,
5606 it is defined as a command with unspecified behavior.
5607
5609 The dot built-in reads a file and executes commands in it.
5610 Syntax
5612 • . [-AL] file [argument...]
5613 Description
5615 The dot built-in reads the specified file, parses its contents as
5616 commands, and executes them in the current command execution
5617 environment.
5618 If arguments are specified, positional parameters are temporarily set
5620 to them. The positional parameters will be restored when the dot
5621 built-in finishes. If no arguments are specified, the positional
5622 parameters are not changed.
5623 If file does not contain any slashes, the shell searches $PATH for a
5625 readable (but not necessarily executable) shell script file whose name
5626 is file in the same manner as command search. If no such file was
5627 found, the shell searches the current working directory for a file
5628 unless in the POSIXly-correct mode. To ensure that the file in the
5629 current working directory is used, start file with ‘./’.
5630 Options
5632 -A, --no-alias
5633 Disable alias substitution while parsing.
5634 -L, --autoload
5636 Search $YASH_LOADPATH instead of $PATH, regardless of whether file
5637 contains slashes. The file value is not considered relative to the
5638 current working directory.
5639 The dot built-in treats as operands any command line arguments after
5641 the first operand.
5642 Operands
5644 file
5645 The pathname of a file to be read.
5646 arguments...
5648 Strings to which positional parameters are set while execution.
5649 Exit status
5651 The exit status of the dot built-in is that of the last command
5652 executed. The exit status is zero if the file contains no commands to
5653 execute and non-zero if a file was not found or could not be opened.
5654 Notes
5656 The dot built-in is a special built-in.
5657 A non-interactive shell immediately exits with a non-zero exit status
5659 if the dot built-in fails to find or open a file to execute.
5660 The POSIX standard defines no options for the dot built-in; the
5662 built-in accepts no options in the POSIXly-correct mode.
5663 The POSIX standard does not define the arguments... operands. It is an
5665 error to specify the arguments... operands in the POSIXly-correct mode.
5666
5668 The echo built-in prints its arguments.
5669 Syntax
5671 • echo [string...]
5672 The built-in treats all command line arguments as operands except for
5674 the options described below. Any word that cannot be parsed as an
5675 acceptable option is treated as an operand. Options must precede all
5676 operands. Syntax errors never happen in the echo built-in.
5677 Description
5679 The echo built-in prints the operand strings followed by a newline to
5680 the standard output. The strings are each separated by a space.
5681 Escape sequences
5683 The ECHO_STYLE variable and the -e option enable escape sequences
5684 that are replaced with corresponding characters:
5685 \a
5687 Bell character (ASCII code: 7)
5688 \b
5690 Backspace (ASCII code: 8)
5691 \c
5693 Nothing. After this escape sequence, no characters are printed
5694 at all.
5695 \e
5697 Escape character (ASCII code: 27)
5698 \f
5700 Form feed character (ASCII code: 12)
5701 \n
5703 Newline character (ASCII code: 10)
5704 \r
5706 Carriage return character (ASCII code: 13)
5707 \t
5709 Horizontal tab character (ASCII code: 9)
5710 \v
5712 Vertical tab character (ASCII code: 11)
5713 \\
5715 Backslash
5716 \0xxx
5718 Character whose code is xxx, where xxx is an octal number of at
5719 most three digits.
5720 When escape sequences are not enabled, they are just printed
5722 intact.
5723 ECHO_STYLE variable
5725 The ECHO_STYLE variable defines which options are accepted and
5726 whether escape sequences are enabled by default. The variable value
5727 should be set to one of the following:
5728 SYSV, XSI
5730 No options are accepted. Escape sequences are always enabled.
5731 BSD
5733 The -n option is accepted. Escape sequences are never enabled.
5734 GNU
5736 The -n, -e, and -E options are accepted. Escape sequences are
5737 not enabled by default, but can be enabled by the -e option.
5738 ZSH
5740 The -n, -e, and -E options are accepted. Escape sequences are
5741 enabled by default, but can be disabled by the -E option.
5742 DASH
5744 The -n option is accepted. Escape sequences are always enabled.
5745 RAW
5747 No options are accepted. Escape sequences are never enabled.
5748 When the ECHO_STYLE variable is not set, it defaults to SYSV.
5750 Options
5752 -n
5753 Do not print a newline at the end.
5754 -e
5756 Enable escape sequences.
5757 -E
5759 Disable escape sequences.
5760 Exit status
5762 The exit status of the echo built-in is zero unless there is any error.
5763 Notes
5765 The POSIX standard does not define the ECHO_STYLE variable nor any
5766 options for the built-in. According to POSIX, the behavior of the
5767 built-in is implementation-defined when the first argument is -n or
5768 when any argument contains a backslash. For maximum portability, the
5769 printf built-in should be preferred over the echo built-in.
5770 Although many values for the ECHO_STYLE variable are defined on the
5772 basis of other existing implementations, yash is not intended to
5773 exactly imitate those originals. Zsh’s echo built-in interprets a
5774 single hyphen argument as a separator between options and operands.
5775 Yash does not support such use of hyphen.
5776
5778 The eval built-in evaluates operands as commands.
5779 Syntax
5781 • eval [-i] [command...]
5782 The eval built-in requires that all options precede operands. Any
5784 command line arguments after the first operand are all treated as
5785 operands.
5786 Description
5788 The eval parses operands as commands and executes them in the current
5789 command execution environment.
5790 When executed without the -i (--iteration) option, all the operands are
5792 concatenated into one string (with a space inserted between each
5793 operand) and parsed/executed at once.
5794 With the -i (--iteration) option, the built-in performs iterative
5796 execution: operands are parsed/executed one by one. If the continue
5797 built-in is executed with the -i (--iteration) option during the
5798 iterative execution, the execution of the current operand is aborted
5799 and the next operand is parsed/executed immediately. The break built-in
5800 with the -i (--iteration) option is similar but the remaining operands
5801 are not parsed/executed. The value of the ? special parameter is saved
5802 before the iterative execution is started. The parameter value is
5803 restored to the saved one after each iteration.
5804 Options
5806 -i, --iteration
5807 Perform iterative execution.
5808 Operands
5810 command
5811 A string that is parsed and executed as commands.
5812 Exit status
5814 The exit status is zero if no command was specified or command
5815 contained no actual command that can be executed. Otherwise, that is,
5816 if the eval built-in executed one or more commands, the exit status of
5817 the eval built-in is that of the last executed command.
5818 Notes
5820 The eval built-in is a special built-in.
5821 The POSIX standard defines no options for the eval built-in; the
5823 built-in accepts no options in the POSIXly-correct mode.
5824
5826 The exec built-in replaces the shell process with another external
5827 command.
5828 Syntax
5830 • exec [-cf] [-a name] [command [argument...]]
5831 The exec built-in requires that all options precede operands. It is
5833 important so that options to the exec built-in are not confused with
5834 options to command. Any command line arguments after command are
5835 treated as arguments.
5836 Description
5838 When the exec built-in is executed with command, the shell executes
5839 command with arguments in a manner similar to the last step of
5840 execution of a simple command. The differences are that command is
5841 always treated as an external command ignoring any existing functions
5842 and built-ins and that the exec system call that starts the external
5843 command is called in the current command execution environment instead
5844 of a subshell, replacing the shell process with the new command
5845 process.
5846 If the shell is in the POSIXly-correct mode or not interactive, failure
5848 in execution of command causes the shell to exit immediately.
5849 If an interactive shell that is not in the POSIXly-correct mode has a
5851 stopped job, the shell prints a warning message and refuses to execute
5852 command. Once the shell process is replaced with an external command,
5853 information about the shell’s jobs is lost, so you will have to resume
5854 or kill the stopped jobs by sending signals by hand. To force the shell
5855 to execute command regardless, specify the -f (--force) option.
5856 When executed without command, the built-in does nothing. As a side
5858 effect, however, redirection applied to the built-in remains in the
5859 current command execution environment even after the built-in finished.
5860 Options
5862 -a name, --as=name
5863 Pass name, instead of command, to the external command as its name.
5864 -c, --clear
5866 Pass to the external command only variables that are assigned in
5867 the simple command in which the built-in is being executed. Other
5868 environment variables are not passed to the command.
5869 -f, --force
5871 Suppress warnings that would prevent command execution.
5872 Operands
5874 command
5875 An external command to be executed.
5876 argument...
5878 Arguments to be passed to the command.
5879 Exit status
5881 If the shell process was successfully replaced with the external
5882 command, there is no exit status since the shell process no longer
5883 exists.
5884 The exit status is:
5886 • 127 if the command was not found,
5888 • 126 if the command was found but could not be executed, and
5890 • zero if no command was specified.
5892 Notes
5894 The exec built-in is a special built-in.
5895 The POSIX standard defines no options for the exec built-in; the
5897 built-in accepts no options in the POSIXly-correct mode.
5898
5900 The exit built-in causes the shell process to exit.
5901 Syntax
5903 • exit [-f] [exit_status]
5904 Description
5906 The exit built-in causes the current shell (or subshell) process to
5907 exit.
5908 If an interactive shell has a stopped job, the shell prints a warning
5910 message and refuses to exit. To force the shell to exit regardless,
5911 specify the -f (--force) option or execute the built-in twice in a row.
5912 If an EXIT trap has been set, the shell executes the trap before
5914 exiting.
5915 Options
5917 -f, --force
5918 Suppress warnings that would prevent the shell from exiting.
5919 Operands
5921 exit_status
5922 A non-negative integer that will be the exit status of the exiting
5923 shell.
5924 If this operand is omitted, the exit status of the shell will be
5926 that of the last command executed before the exit built-in (but, if
5927 the built-in is executed during a trap, the exit status will be
5928 that of the last command before the trap is entered).
5929 If exit_status is 256 or larger, the actual exit status will be the
5931 remainder of exit_status divided by 256.
5932 Exit status
5934 Because the built-in causes the shell to exit, there is no exit status
5935 of the built-in.
5936 As an exception, if the shell refused to exit, the exit status of the
5938 built-in is non-zero.
5939 Notes
5941 The exit built-in is a special built-in.
5942 The POSIX standard defines no options for the exit built-in; the
5944 built-in accepts no options in the POSIXly-correct mode.
5945 The POSIX standard provides that the exit_status operand should be
5947 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
5948 an extension.
5949 If the built-in is executed during an EXIT trap, the shell just exits
5951 without executing the trap again. If exit_status was not specified, the
5952 exit status of the shell is what the exit status would be if the trap
5953 had not been set. See also Termination of the shell.
5954
5956 The export built-in marks variables for export to child processes.
5957 Syntax
5959 • export [-prX] [name[=value]...]
5960 Description
5962 The export built-in is equivalent to the typeset built-in with the -gx
5963 option.
5964 Notes
5966 The export built-in is a special built-in.
5967 The POSIX standard defines the -p option only; other options cannot be
5969 used in the POSIXly-correct mode. The POSIX does not allow using the
5970 option together with operands.
5971
5973 The false built-in does nothing unsuccessfully.
5974 Syntax
5976 • false
5977 Description
5979 The false built-in does nothing. Any command line arguments are
5980 ignored.
5981 Exit status
5983 The exit status of the false built-in is non-zero.
5984 Notes
5986 The false built-in is a semi-special built-in.
5987
5989 The fc built-in re-executes or prints commands from command history.
5990 Syntax
5992 • fc [-qr] [-e editor] [start [end]]
5993 • fc -s[q] [old=new] [start]
5995 • fc -l[nrv] [start [end]]
5997 Description
5999 When executed without the -l (--list) option, the built-in executes the
6000 commands in the command history range specified by the operands. If the
6001 -s (--silent) option is not specified, the shell invokes an editor
6002 which allows you to edit the commands before they are executed. The
6003 commands are executed when you quit the editor. If the -s (--silent)
6004 option is specified, the commands are immediately executed. In either
6005 case, the executed commands are printed to the standard output and
6006 added to the history.
6007 When executed with the -l (--list) option, the built-in prints the
6009 commands in the command history range specified by the operands. By
6010 default, commands are printed with their history entry numbers, but
6011 output format can be changed using the -n (--no-numbers)) and -v
6012 (--verbose) options.
6013 Options
6015 -e editor, --editor=editor
6016 Specify an editor that is used to edit commands.
6017 If this option is not specified, the value of the FCEDIT variable
6019 is used. If the variable is not set either, ed is used.
6020 -l, --list
6022 Print command history entries.
6023 -n, --no-numbers
6025 Don’t print entry numbers when printing history entries.
6026 -q, --quiet
6028 Don’t print commands before executing.
6029 -r, --reverse
6031 Reverse the order of command entries in the range.
6032 -s, --silent
6034 Execute commands without editing them.
6035 -v, --verbose
6037 Print execution time before each history entry when printing.
6038 Operands
6040 start and end
6041 The start and end operands specify a range of command history
6042 entries that are executed or printed. If one of the operands is an
6043 integer, it is treated as a history entry number. A negative
6044 integer means the nth most recent entry where n is the absolute
6045 value of the integer. If one of the operands is not an integer, it
6046 is treated as part of a command string: the most recent entry that
6047 starts with the string is selected as the start or end of the
6048 range.
6049 If the first entry of the range that is specified by start is newer
6051 than the last entry of the range that is specified by end, the
6052 range is reversed as if the -r (--reverse) option was specified.
6053 (If the option is already specified, it is cancelled.)
6054 The default values for start and end are:
6056 ┌──────┬─────────┬───────────────┐
6058 │ │ with -l │ without -l │
6059 ├──────┼─────────┼───────────────┤
6060 │start │ -16 │ -1 │
6061 ├──────┼─────────┼───────────────┤
6062 │end │ -16 │ same as start │
6063 └──────┴─────────┴───────────────┘
6064 old=new
6066 An operand of this format replaces part of the command string. If
6067 the command string contains old, it is replaced with new and the
6068 new string is executed. Only the first occurrence of old is
6069 replaced.
6070 Exit status
6072 If commands was executed, the exit status of the fc built-in is that of
6073 the last executed command. Otherwise, the exit status is zero unless
6074 there is any error.
6075 Notes
6077 The fc built-in is a semi-special built-in.
6078 The POSIX standard does not define the -q (--quiet) or -v (--verbose)
6080 options, so they cannot be used in the POSIXly-correct mode.
6081 Command history cannot be modified during line-editing.
6083
6085 The fg built-in resumes a job in the foreground.
6086 Syntax
6088 • fg [job...]
6089 Description
6091 The fg built-in brings the specified job to the foreground and sends
6092 the SIGCONT signal to the job. As a result, the job is resumed in the
6093 foreground (if it has been suspended). The built-in then waits for the
6094 job to finish and returns the exit status of it.
6095 The name of the job is printed when the job is resumed. When not in the
6097 POSIXly-correct mode, the job number is also printed.
6098 The built-in can be used only when job control is enabled.
6100 Operands
6102 job
6103 The job ID of the job to be resumed.
6104 If more than one job is specified, they are resumed in order, one
6106 at a time. The current job is resumed if none is specified.
6107 The percent sign (%) at the beginning of a job ID can be omitted if
6109 the shell is not in the POSIXly-correct mode.
6110 Exit status
6112 The exit status of the fg built-in is that of the (last) job resumed.
6113 The exit status is non-zero when there was some error.
6114 Notes
6116 The fg built-in is a semi-special built-in.
6117 You cannot specify more than one job in the POSIXly-correct mode.
6119
6121 The getopts built-in parses command options.
6122 Syntax
6124 • getopts optionlist variable [argument...]
6125 Description
6127 The getopts built-in parses single-character options that appear in
6128 arguments. Each time the built-in is invoked, it parses one option and
6129 assigns the option character to variable.
6130 The optionlist operand is a list of option characters that should be
6132 accepted by the parser. In optionlist, an option that takes an argument
6133 should be specified as the option character followed by a colon. For
6134 example, if you want the -a, -b and -c options to be parsed and the -b
6135 option to take an argument, then optionlist should be ab:c.
6136 When an option that takes an argument is parsed, the argument is
6138 assigned to the OPTARG variable.
6139 When an option that is not specified in optionlist is found or when an
6141 option argument is missing, the result depends on the first character
6142 of optionlist:
6143 • If optionlist starts with a colon, the option character is assigned
6145 to the OPTARG variable and variable is set to either ? (when the
6146 option is not in optionlist) or : (when the option argument is
6147 missing).
6148 • Otherwise, variable is set to ?, the OPTARG variable is unset, and
6150 an error message is printed.
6151 The built-in parses one option for each execution. For all options in a
6153 set of command line arguments to be parsed, the built-in has to be
6154 executed repeatedly with the same arguments. The built-in uses the
6155 OPTIND variable to remember which argument should be parsed next. When
6156 the built-in is invoked for the first time, the variable value must be
6157 1, which is the default value. You must not modify the variable until
6158 all the options have been parsed, when the built-in sets the variable
6159 to the index of the first operand in arguments. (If there are no
6160 operands, it will be set to the number of arguments plus one.)
6161 When you want to start parsing a new set of arguments, you have to
6163 reset the OPTIND variable to 1 beforehand.
6164 Operands
6166 optionlist
6167 A list of options that should be accepted as valid options in
6168 parsing.
6169 variable
6171 The name of a variable the result is to be assigned to.
6172 arguments
6174 Command line arguments that are to be parsed.
6175 When no arguments are given, the positional parameters are parsed.
6177 Exit status
6179 If an option is found, whether or not it is specified in optionlist,
6180 the exit status is zero. If there is no more option to be parsed, the
6181 exit status is non-zero.
6182 Example
6184 aopt=false bopt= copt=false
6185 while getopts ab:c opt
6186 do
6187 case $opt in
6188 a) aopt=true ;;
6189 b) bopt=$OPTARG ;;
6190 c) copt=true ;;
6191 \?) return 2 ;;
6192 esac
6193 done
6194 if $aopt; then echo Option -a specified; fi
6195 if [ -n "$bopt" ]; then echo Option -b $bopt specified; fi
6196 if $copt; then echo Option -c specified; fi
6197 shift $((OPTIND - 1))
6198 echo Operands are: $*
6199 Notes
6201 In arguments that are parsed, options must precede operands. The
6202 built-in ends parsing when it encounters the first operand.
6203 The getopts built-in is a semi-special built-in.
6205 The POSIX standard does not specify what will happen when the OPTIND
6207 variable is assigned a value other than 1.
6208 In the POSIXly-correct mode, option characters in optionlist must be
6210 alphanumeric.
6211
6213 The hash built-in remembers, forgets, or reports command locations.
6214 Syntax
6216 • hash command...
6217 • hash -r [command...]
6219 • hash [-a]
6221 • hash -d user...
6223 • hash -dr [user...]
6225 • hash -d
6227 Description
6229 When executed with commands but without options, the built-in
6230 immediately performs command path search and caches commands' full
6231 paths.
6232 When executed with the -r (--remove) option, it removes the paths of
6234 commands (or all cached paths if none specified) from the cache.
6235 When executed without options or commands, it prints the currently
6237 cached paths to the standard output.
6238 With the -d (--directory) option, the built-in does the same things to
6240 the home directory cache, rather than the command path cache. Cached
6241 home directory paths are used in tilde expansion.
6242 Options
6244 -a, --all
6245 Print all cached paths.
6246 Without this option, paths for built-ins are not printed.
6248 -d, --directory
6250 Affect the home directory cache instead of the command path cache.
6251 -r, --remove
6253 Remove cached paths.
6254 Operands
6256 command
6257 The name of an external command (that does not contain any slash).
6258 user
6260 A user name.
6261 Exit status
6263 The exit status of the hash built-in is zero unless there is any error.
6264 Notes
6266 The shell automatically caches command and directory paths when
6267 executing a command or performing tilde expansion, so normally there is
6268 no need to use this built-in explicitly to cache paths.
6269 Assigning a value to the PATH variable removes all command paths from
6271 the cache as if hash -r was executed.
6272 The POSIX standard defines the -r option only: other options cannot be
6274 used in the POSIXly-correct mode.
6275 The hash built-in is a semi-special built-in.
6277
6279 The help built-in prints usage of built-ins.
6280 Syntax
6282 • help [built-in...]
6283 Description
6285 The help built-in prints a description of built-ins.
6286 Operands
6288 built-ins
6289 Names of built-ins.
6290 Exit status
6292 The exit status of the help built-in is zero unless there is any error.
6293 Notes
6295 The help built-in is a semi-special built-in. In the POSIX standard, it
6296 is defined as a command with unspecified behavior.
6297 Many built-ins of yash accept the --help option that prints the same
6299 description.
6300
6302 The history built-in prints or edits command history.
6303 Syntax
6305 • history [-cF] [-d entry] [-s command] [-r file] [-w file] [count]
6306 Description
6308 The history built-in prints or edits command history.
6309 When executed with an option, the built-in edits history according to
6311 the option. If more than one option is specified, each option is
6312 processed in order.
6313 When executed with the count operand, the built-in prints the most
6315 recent count history entries to the standard output in the same manner
6316 as the fc built-in.
6317 When executed with neither options nor operands, the built-in prints
6319 the whole history.
6320 Options
6322 -c, --clear
6323 Clear all history entries completely.
6324 -d entry, --delete=entry
6326 Delete the specified entry. The entry should be specified in the
6327 same manner as the start and end operands of the fc built-in.
6328 -F, --flush-file
6330 Rebuild the history file. This operation removes unused old data
6331 from the file.
6332 -r file, --read=file
6334 Read command lines from file and add them to the history. The file
6335 contents are treated as lines of simple text.
6336 -s command, --set=command
6338 Add command as a new history entry after removing the most recent
6339 entry.
6340 -w file, --write=file
6342 Write the whole history to file. Any existing data in the file will
6343 be lost. The output format is lines of simple text, each of which
6344 is a command string.
6345 Operands
6347 count
6348 The number of entries to be printed.
6349 Exit status
6351 The exit status of the history built-in is zero unless there is any
6352 error.
6353 Notes
6355 The history built-in is a semi-special built-in. In the POSIX standard,
6356 it is defined as a command with unspecified behavior.
6357 Command history cannot be modified during line-editing.
6359
6361 The jobs built-in reports job status.
6362 Syntax
6364 • jobs [-lnprs] [job...]
6365 Description
6367 The jobs built-in prints information of jobs the shell is currently
6368 controlling.
6369 By default, the following information is printed for each job, line by
6371 line:
6372 • the job number,
6374 • the + or - symbol if the job is the current or previous job,
6376 respectively,
6377 • the status, and
6379 • the command string.
6381 Options
6383 -l, --verbose
6384 Print the process ID, status, and command string for each process
6385 in the jobs.
6386 -n, --new
6388 Print new jobs only: jobs whose status has never been reported
6389 since the status changed.
6390 -p, --pgid-only
6392 Print process group IDs of jobs only.
6393 -r, --running-only
6395 Print running jobs only.
6396 -s, --stopped-only
6398 Print stopped jobs only.
6399 Operands
6401 jobs
6402 The job IDs of jobs to be reported. When no job is specified, all
6403 jobs under the shell’s control are reported.
6404 The percent sign (%) at the beginning of a job ID can be omitted if
6406 the shell is not in the POSIXly-correct mode.
6407 Exit status
6409 The exit status of the jobs built-in is zero unless there is any error.
6410 Notes
6412 The jobs built-in is a semi-special built-in.
6413 The POSIX standard defines the -l and -p options only: other options
6415 cannot be used in the POSIXly-correct mode. In the POSIXly-correct
6416 mode, the effect of the -l option is different in that status is
6417 reported for each job rather than for each process.
6418 The process group ID of a job executed by yash is equal to the process
6420 ID of the first command of the pipeline that forms the job.
6421
6423 The kill built-in sends a signal to processes.
6424 Syntax
6426 • kill [-signal|-s signal|-n signal] process...
6427 • kill -l [-v] [signal...]
6429 The kill built-in requires that all options precede operands. Any
6431 command line arguments after the first operand are all treated as
6432 operands.
6433 Description
6435 When executed without the -l option, the built-in sends a signal to
6436 processes. The signal sent can be specified by option. The SIGTERM
6437 signal is sent if no signal is specified.
6438 When executed with the -l option, the built-in prints information of
6440 signals to the standard output. If no signal is specified, information
6441 of all signals is printed.
6442 Options
6444 Signal-specifying options
6445 -signal, -s signal, -n signal
6446 A signal-specifying option specifies a signal to be sent to
6447 processes. signal can be specified by name or number. If
6448 number 0 is specified, the built-in checks if a signal could be
6449 sent to the processes but no signal is actually sent. Signal
6450 names are case-insensitive.
6451 You can specify at most one signal-specifying option at a time.
6453 Other options
6455 -l
6456 Print signal information instead of sending a signal.
6457 -v
6459 Print more signal information.
6460 Without this option, the built-in prints the signal name only.
6462 This option adds the signal number and a short description.
6463 When the -v option is specified, the -l option can be omitted.
6465 Operands
6467 processes
6468 Specify processes to which a signal is sent.
6469 Processes can be specified by the process ID, the process group ID,
6471 or the job ID. The process group ID must be prefixed with a hyphen
6472 (-) so that it is not treated as a process ID.
6473 When 0 is specified as process, the signal is sent to the process
6475 group to which the shell process belongs. When -1 is specified, the
6476 signal is sent to all processes on the system.
6477 signal
6479 Specify a signal of which information is printed.
6480 The signal can be specified by the name, the number, or the exit
6482 status of a command that was killed by the signal.
6483 Exit status
6485 The exit status of the kill built-in is zero unless there is any error.
6486 If the signal was sent to at least one process, the exit status is zero
6487 even if the signal was not sent to all of the specified processes.
6488 Notes
6490 The kill built-in is a semi-special built-in.
6491 Command arguments that start with a hyphen should be used with care.
6493 The command kill -1 -2, for example, sends signal 1 to process group 2
6494 since -1 is treated as a signal-specifying option and -2 as an operand
6495 that specifies a process group. The commands kill -- -1 -2 and kill
6496 -TERM -1 -2, on the other hand, treats both -1 and -2 as operands.
6497 The POSIX standard does not define the -n or -v options, so they cannot
6499 be used in the POSIXly-correct mode. The standard does not allow
6500 specifying a signal number as the argument of the -s option or a signal
6501 name as the signal operand.
6502 The standard requires signal names to be specified without the SIG
6504 prefix, like INT and QUIT. If the shell is not in the POSIXly-correct
6505 mode, the built-in accepts SIG-prefixed signal names as well.
6506
6508 The local built-in prints or sets local variables.
6509 Syntax
6511 • local [-rxX] [name[=value]...]
6512 Description
6514 The local built-in is equivalent to the typeset built-in except that
6515 the -f (--functions) and -g (--global) options cannot be used.
6516 Notes
6518 The local built-in is a semi-special built-in. In the POSIX standard,
6519 it is defined as a command with unspecified behavior.
6520
6522 The popd built-in pops a directory from the directory stack.
6523 Syntax
6525 • popd [index]
6526 Description
6528 The popd built-in removes the last entry from the directory stack,
6529 returning to the previous working directory. If index is given, the
6530 entry specified by index is removed instead of the last one.
6531 Operands
6533 index
6534 The index of a directory stack entry you want to remove.
6535 If omitted, +0 (the last entry) is assumed.
6537 Exit status
6539 The exit status of the popd built-in is zero unless there is any error.
6540 Notes
6542 It is an error to use this built-in when there is only one directory
6543 stack entry.
6544 The popd built-in is a semi-special built-in. In the POSIX standard, it
6546 is defined as a command with unspecified behavior.
6547
6549 The printf built-in prints formatted values.
6550 Syntax
6552 • printf format [value...]
6553 Description
6555 The printf built-in formats values according to format and prints them
6556 to the standard output. Unlike the echo built-in, the printf built-in
6557 does not print a newline automatically.
6558 The formatting process is very similar to that of the printf function
6560 in the C programming language. You can use conversion specifications
6561 (which start with %) and escape sequences (which start with \) in
6562 format. Any other characters that are not part of a conversion
6563 specification or escape sequence are printed literally.
6564 Conversion specifications
6566 A conversion specification starts with a percent sign (%).
6567 A conversion specification except %% consumes a value, which is
6569 formatted according to the specification and printed. Each
6570 conversion specification consumes one value in the order of
6571 appearance. If there are more values than conversion
6572 specifications, the entire format is re-processed until all the
6573 values are consumed. If a value to be consumed is missing, it is
6574 assumed to be an empty string (if the specification requires a
6575 string) or zero (if a number). If no values are given, format is
6576 processed just once.
6577 Available conversion specifications are:
6579 %d, %i
6581 prints a signed integer in decimal
6582 %u
6584 prints an unsigned integer in decimal
6585 %o
6587 prints an unsigned integer in octal
6588 %x
6590 prints an unsigned integer in lowercase hexadecimal
6591 %X
6593 prints an unsigned integer in uppercase hexadecimal
6594 %f
6596 prints a floating-point number in lowercase
6597 %F
6599 prints a floating-point number in uppercase
6600 %e
6602 prints a floating-point number with exponent in lowercase
6603 %E
6605 prints a floating-point number with exponent in uppercase
6606 %g
6608 the same as %f or %e, automatically selected
6609 %G
6611 the same as %F or %E, automatically selected
6612 %c
6614 prints the first character of string
6615 %s
6617 prints a string
6618 %b
6620 prints a string (recognizing escape sequences like the echo
6621 built-in)
6622 %%
6624 prints a percent sign (%)
6625 For %g and %G, the specification that is actually used is %f or %F
6627 if the exponent part is between -5 and the precision (exclusive);
6628 %e or %E otherwise.
6629 In a conversion specification except %%, the leading percent sign
6631 may be followed by flags, field width, and/or precision in this
6632 order.
6633 The flags are a sequence of any number of the following characters:
6635 Minus sign (-)
6637 With this flag, spaces are appended to the formatted value to
6638 fill up to the field width. Otherwise, spaces are prepended.
6639 Plus sign (+)
6641 A plus or minus sign is always prepended to a number.
6642 Space ( )
6644 A space is prepended to a formatted number if it has no plus or
6645 minus sign.
6646 Hash sign (#)
6648 The value is formatted in an alternative form: For %o, the
6649 printed octal integer has at least one leading zero. For %x and
6650 %X, a non-zero integer is formatted with 0x and 0X prefixes,
6651 respectively. For %e, %E, %f, %F, %g, and %G, a decimal mark
6652 (a.k.a. radix character) is always printed even if the value is
6653 an exact integer. For %g and %G, the printed number has at
6654 least one digit in the fractional part.
6655 Zero (0)
6657 Zeros are prepended to a formatted number to fill up to the
6658 field width. This flag is ignored if the minus flag is
6659 specified or if the conversion specification is %d, %i, %u, %o,
6660 %x, or %X with a precision.
6661 A field width is specified as a decimal integer that has no leading
6663 zeros.
6664 A field width defines a minimum byte count of a formatted value. If
6666 the formatted value does not reach the minimum byte count, so many
6667 spaces are prepended that the printed value has the specified byte
6668 count.
6669 A precision is specified as a period (.) followed by a decimal
6671 integer. If the integer is omitted after the period, the precision
6672 is assumed to be zero.
6673 For conversion specifications %d, %i, %u, %o, %x, and %X, a
6675 precision defines a minimum digit count. If the formatted integer
6676 does not reach the minimum digit count, so many zeros are prepended
6677 that the printed integer has the specified number of digits. The
6678 default precision is one for these conversion specifications.
6679 For conversion specifications %e, %E, %f, and %F, a precision
6681 defines the number of digits after the decimal mark. The default
6682 precision is six for these conversion specifications.
6683 For conversion specifications %g, and %G, a precision defines a
6685 maximum number of significant digits in the printed value. The
6686 default precision is six for these conversion specifications.
6687 For conversion specifications %s, and %b, a precision defines a
6689 maximum byte count of the printed string. The default precision is
6690 infinity for these conversion specifications.
6691 In the conversion specification %08.3f, the zero flag is specified,
6693 the field width is 8, and the precision is 3. If this specification
6694 is applied to value 12.34, the output will be 0012.340.
6695 Escape sequences
6697 The following escape sequences are recognized in format:
6698 \a
6700 Bell character (ASCII code: 7)
6701 \b
6703 Backspace (ASCII code: 8)
6704 \f
6706 Form feed character (ASCII code: 12)
6707 \n
6709 Newline character (ASCII code: 10)
6710 \r
6712 Carriage return character (ASCII code: 13)
6713 \t
6715 Horizontal tab character (ASCII code: 9)
6716 \v
6718 Vertical tab character (ASCII code: 11)
6719 \\
6721 Backslash
6722 \"
6724 Double quotation
6725 \'
6727 Single quotation (apostrophe)
6728 \xxx
6730 Character whose code is xxx, where xxx is an octal number of at
6731 most three digits.
6732 Operands
6734 format
6735 A string that defines how values should be formatted.
6736 values
6738 Values that are formatted according to format.
6739 A value is either a number or a string.
6741 When a numeric value is required, value can be a single or double
6743 quotation followed by a character, instead of a normal number. For
6744 example, the command printf '%d' '"3' will print 51 on a typical
6745 environment where character 3 has character code 51.
6746 Exit status
6748 The exit status of the printf built-in is zero unless there is any
6749 error.
6750 Notes
6752 The POSIX standard does not precisely define how multibyte characters
6753 should be handled by the built-in. When you use the %s conversion
6754 specification with precision or the %c conversion specification, you
6755 may obtain unexpected results if the formatted value contains a
6756 character that is represented by more than one byte. Yash never prints
6757 only part of the bytes that represent a single multibyte character
6758 because all multibyte characters are converted to wide characters when
6759 processed in the shell.
6760 If the shell is not in the POSIXly-correct mode and the “long double”
6762 floating-point arithmetic is supported on the running system, then
6763 “long double” is used for floating-point conversion specifications.
6764 Otherwise, “double” is used.
6765
6767 The pushd built-in pushes a directory into the directory stack.
6768 Syntax
6770 • pushd [-L|-P] [directory]
6771 Description
6773 The pushd built-in changes the working directory to directory in the
6774 same manner as the cd built-in and adds it to the directory stack. If
6775 the working directory could not be changed successfully, the stack is
6776 not modified.
6777 Options
6779 The pushd built-in accepts the following option as well as the options
6780 that can be used for the cd built-in:
6781 --remove-duplicates
6783 If the new working directory has already been in the directory
6784 stack, the existing entry is removed from the stack before the new
6785 directory is pushed into the stack.
6786 Operands
6788 directory
6789 The pathname of the new working directory.
6790 If directory is a single hyphen (‘-’), the value of the OLDPWD
6792 variable is assumed for the new directory pathname, which is
6793 printed to the standard output.
6794 If directory is an integer with a plus or minus sign, it is
6796 considered as an entry index of the directory stack. The entry is
6797 removed from the stack and then pushed to the stack again.
6798 If directory is omitted, the working directory is changed to the
6800 directory specified by the --default-directory=... option. If that
6801 option is not specified either, the default is index +1.
6802 Exit status
6804 The exit status of the pushd built-in is zero unless there is any
6805 error.
6806 Notes
6808 The pushd built-in is a semi-special built-in. In the POSIX standard,
6809 it is defined as a command with unspecified behavior.
6810
6812 The pwd built-in prints the current working directory.
6813 Syntax
6815 • pwd [-L|-P]
6816 Description
6818 The pwd built-in prints an absolute path to the shell’s current working
6819 directory to the standard output.
6820 Options
6822 -L, --logical
6823 If the value of the PWD variable is an absolute path to the shell’s
6824 working directory and the path does not contain any . or ..
6825 components, then the path is printed. Otherwise, the printed path
6826 is the same as when the -P option is specified.
6827 -P, --physical
6829 The printed path does not contain any . or .. components,
6830 symbolic link components, or redundant slashes.
6831 The -L (--logical) and -P (--physical) options are mutually exclusive:
6833 only the last specified one is effective. If neither is specified, -L
6834 is assumed.
6835 Exit status
6837 The exit status of the pwd built-in is zero unless there is any error.
6838 Notes
6840 The pwd built-in is a semi-special built-in.
6841
6843 The read built-in reads a line from the standard input.
6844 Syntax
6846 • read [-Aer] [-P|-p] variable...
6847 Description
6849 The read built-in reads a line of string from the standard input and
6850 assigns it to the specified variables.
6851 If the -r (--raw-mode) option is specified, all characters in the line
6853 are treated literally.
6854 If the -r (--raw-mode) option is not specified, backslashes in the line
6856 are treated as quotations. If a backslash is at the end of the line, it
6857 is treated as a line continuation. When the built-in reads the next
6858 line, the PS2 variable is used as a prompt if the shell is interactive
6859 and the standard input is a terminal.
6860 The input line is subject to field splitting. The resulting words are
6862 assigned to variables in order. If there are more words than variables,
6863 the last variable is assigned all the remaining words (as if the words
6864 were not split). If the words are fewer than variables, the remaining
6865 variables are assigned empty strings.
6866 Options
6868 -A, --array
6869 Make the last variable an array. Instead of assigning a
6870 concatenation of the remaining words to a normal variable, the
6871 words are assigned to an array.
6872 -e, --line-editing
6874 Use line-editing to read the line.
6875 To use line-editing, all of the following conditions must also be
6877 met:
6878 • The shell is interactive.
6880 • The vi or emacs option is enabled.
6882 • The standard input and standard error are connected to a
6884 terminal.
6885 -P, --ps1
6887 Print the PS1 variable as a prompt before reading the (first) line
6888 if the shell is interactive and the standard input is a terminal.
6889 -p prompt, --prompt=prompt
6891 Print the specified prompt before reading the (first) line if the
6892 shell is interactive and the standard input is a terminal.
6893 -r, --raw-mode
6895 Don’t treat backslashes as quotations.
6896 Operands
6898 variables
6899 Names of variables to which input words are assigned.
6900 Exit status
6902 The exit status of the read built-in is zero unless there is any error.
6903 Note that the exit status is non-zero if an end of input is encountered
6905 before reading the entire line.
6906 Notes
6908 The read built-in is a semi-special built-in.
6909 The POSIX standard defines the -r option only: other options cannot be
6911 used in the POSIXly-correct mode.
6912 The PS1R and PS1S variables affect the behavior of line-editing if the
6914 PS1 prompt is used. The same for PS2.
6915
6917 The readonly built-in makes variables and functions read-only.
6918 Syntax
6920 • readonly [-pxX] [name[=value]...]
6921 • readonly -f[p] [name...]
6923 Description
6925 The readonly built-in is equivalent to the typeset built-in with the
6926 -gr option.
6927 Notes
6929 The readonly built-in is a special built-in.
6930 The POSIX standard defines the -p option only; other options cannot be
6932 used in the POSIXly-correct mode. The POSIX does not allow using the
6933 option together with operands.
6934
6936 The return built-in returns from a function or script.
6937 Syntax
6939 • return [-n] [exit_status]
6940 Description
6942 When executed without the -n (--no-return) option, one of the following
6943 happens:
6944 • If the shell is executing a function, the execution of the function
6946 is terminated.
6947 • If the dot built-in is executing a script, the execution of the
6949 script is terminated.
6950 • If the shell is executing a script during initialization, the
6952 execution of the script is terminated.
6953 • If the shell is executing a trap, the execution of the trap is
6955 terminated for the currently handled signal.
6956 • Otherwise, the shell exits unless it is interactive.
6958 When executed with the -n (--no-return) option, the built-in does
6960 nothing but return the specified exit_status.
6961 Options
6963 -n, --no-return
6964 Do not terminate a function, script, trap, or the shell.
6965 Operands
6967 exit_status
6968 The exit status of the built-in.
6969 The value must be a non-negative integer.
6971 If omitted, the exit status of the last executed command is used.
6973 (But when the shell is executing a trap, the exit status of the
6974 last command before the trap is used.)
6975 Exit status
6977 The exit status of the return built-in is defined by the exit_status
6978 operand. The exit status is used also as the exit status of the
6979 terminated function, script, or the shell.
6980 Notes
6982 The return built-in is a special built-in.
6983 The POSIX standard provides that the exit_status operand should be
6985 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
6986 an extension.
6987 In the POSIX standard, the behavior of the return built-in is defined
6989 only when the shell is executing a function or script.
6990 The POSIX standard defines no options for the return built-in; the
6992 built-in accepts no options in the POSIXly-correct mode.
6993
6995 The set built-in sets shell options and positional parameters.
6996 Syntax
6998 • set [options] [operands]
6999 • set -o
7001 • set +o
7003 The set built-in requires that all options precede operands. Any
7005 command line arguments after the first operand are all treated as
7006 operands.
7007 Description
7009 When executed without any command arguments, the built-in prints a list
7010 of all existing variables to the standard input in a form that can be
7011 reused as commands that will restore the variable definitions.
7012 When -o is the only command argument, the built-in prints a list of
7014 shell options with their current settings. When +o is the only command
7015 argument, the built-in prints commands that can be reused to restore
7016 the current shell option settings.
7017 In other cases, the built-in changes shell option settings and/or
7019 positional parameters.
7020 Options
7022 When one or more options are specified, the built-in enables or
7023 disables the shell options. A normal hyphen-prefixed option enables a
7024 shell option. An option that is prefixed with a plus (+) instead of a
7025 hyphen disables a shell option. For example, options -m, -o monitor,
7026 and --monitor enable the monitor option and options +m, +o monitor,
7027 ++monitor disable it.
7028 The name of a long option is case-insensitive and may include
7030 irrelevant non-alphanumeric characters, which are ignored. For example,
7031 options --le-comp-debug and --LeCompDebug are equivalent. If no is
7032 prepended to the name of a long option, the meaning is reversed. For
7033 example, --noallexport is equivalent to ++allexport and ++nonotify to
7034 --notify.
7035 An option can be specified in one of the following forms:
7037 • a long option e.g. --allexport
7039 • an -o option with a option name specified as the argument e.g. -o
7041 allexport
7042 • a single-character option e.g. -a
7044 Not all options can be specified as single-character options.
7046 The available options are:
7048 all-export (-a)
7050 When enabled, all variables are automatically exported when
7051 assigned.
7052 brace-expand
7054 This option enables brace expansion.
7055 case-glob
7057 (Enabled by default) When enabled, pattern matching is
7058 case-sensitive in pathname expansion.
7059 clobber (+C)
7061 (Enabled by default) When enabled, the > redirection behaves the
7062 same as the >| redirection.
7063 cur-async, cur-bg, cur-stop
7065 (Enabled by default) These options affect choice of the current job
7066 (cf. job ID).
7067 dot-glob
7069 When enabled, periods at the beginning of filenames are not treated
7070 specially in pathname expansion.
7071 emacs
7073 This option enables line-editing in the emacs mode.
7074 empty-last-field
7076 When enabled, field splitting does not remove the last field even
7077 if it is empty.
7078 err-exit (-e)
7080 When enabled, if a pipeline ends with a non-zero exit status, the
7081 shell immediately exits unless the following suppress condition is
7082 met:
7083 • the pipeline is a condition of an if command or while or until
7085 loop;
7086 • the pipeline is prefixed by !; or
7088 • the pipeline is a single compound command other than a subshell
7090 grouping.
7091 err-return
7093 This option is like the err-exit option, but the return built-in is
7094 executed instead of the shell exiting on a non-zero exit status.
7095 Unlike err-exit, the suppress condition does not apply inside a
7096 function, subshell grouping, or script file.
7097 exec (+n)
7099 (Enabled by default) Commands are actually executed only when this
7100 option is enabled. Otherwise, commands are just parsed and not
7101 executed. Disabling this option may be useful for syntax checking.
7102 In an interactive shell, this option is always assumed enabled.
7103 extended-glob
7105 This option enables extension in pathname expansion.
7106 for-local
7108 (Enabled by default) If a for loop is executed within a function,
7109 this option causes the iteration variable to be created as a local
7110 variable, even if the variable already exists globally. This option
7111 has no effect if the POSIXly-correct mode is active.
7112 glob (+f)
7114 (Enabled by default) This option enables pathname expansion.
7115 hash-on-def (-h)
7117 When a function is defined when this option is enabled, the shell
7118 immediately performs command path search for each command that
7119 appears in the function and caches the command’s full path.
7120 hist-space
7122 When enabled, command lines that start with a whitespace are not
7123 saved in command history.
7124 ignore-eof
7126 When enabled, an interactive shell does not exit when EOF (end of
7127 file) is input. This prevents the shell from exiting when you
7128 accidentally hit Ctrl-D.
7129 le-always-rp, le-comp-debug, le-conv-meta, le-no-conv-meta, le-predict,
7131 le-predict-empty, le-prompt-sp, le-visible-bell
7132 See shell options on line-editing.
7133 mark-dirs
7135 When enabled, resulting directory names are suffixed by a slash in
7136 pathname expansion.
7137 monitor (-m)
7139 This option enables job control. This option is enabled by default
7140 for an interactive shell.
7141 notify (-b)
7143 When the status of a job changes when this option is enabled, the
7144 shell immediately notifies at any time. This option overrides the
7145 notify-le option.
7146 notify-le
7148 This option is similar to the notify option, but the status change
7149 is notified only while the shell is waiting for input with
7150 line-editing.
7151 null-glob
7153 When enabled, in pathname expansion, patterns that do not match any
7154 pathname are removed from the command line rather than left as is.
7155 pipe-fail
7157 When enabled, the exit status of a pipeline is zero if and only if
7158 all the subcommands of the pipeline exit with an exit status of
7159 zero.
7160 posixly-correct
7162 This option enables the POSIXly-correct mode.
7163 trace-all
7165 (Enabled by default) When this option is disabled, the x-trace
7166 option is temporarily disabled while the shell is executing
7167 commands defined in the COMMAND_NOT_FOUND_HANDLER, PROMPT_COMMAND,
7168 or YASH_AFTER_CD variable.
7169 unset (+u)
7171 (Enabled by default) When enabled, an undefined parameter is
7172 expanded to an empty string in parameter expansion and treated as
7173 zero in arithmetic expansion. When disabled, expansion of an
7174 undefined parameter results in an error.
7175 verbose (-v)
7177 When enabled, the shell prints each command line to the standard
7178 error before parsing and executing it.
7179 vi
7181 This option enables line-editing in the vi mode. This option is
7182 enabled by default in an interactive shell if the standard input
7183 and error are both terminals.
7184 x-trace (-x)
7186 When enabled, the results of expansion are printed to the standard
7187 error for each simple command being executed. When printed, each
7188 line is prepended with an expansion result of the PS4 variable. See
7189 also the trace-all option.
7190 Operands
7192 If one or more operands are passed to the set built-in, current
7193 positional parameters are all removed and the operands are set as new
7194 positional parameters. If the -- separator (cf. syntax of command
7195 arguments) is passed, the positional parameters are set even when there
7196 are no operands, in which case new positional parameters will be
7197 nothing.
7198 Exit status
7200 The exit status of the set built-in is zero unless there is any error.
7201 Notes
7203 The set built-in is a special built-in.
7204 In the POSIX standard, available shell options are much limited. The
7206 standard does not define:
7207 • long options such as --allexport,
7209 • prepending no to negate an option,
7211 • using uppercase letters and/or non-alphanumeric characters in
7213 option names
7214 The options defined in the standard are:
7216 • -a, -o allexport
7218 • -e, -o errexit
7220 • -m, -o monitor
7222 • -C, -o noclobber
7224 • -n, -o noexec
7226 • -f, -o noglob
7228 • -b, -o notify
7230 • -u, -o nounset
7232 • -v, -o verbose
7234 • -x, -o xtrace
7236 • -h
7238 • -o ignoreeof
7240 • -o nolog
7242 • -o vi
7244 Yash does not support the nolog option, which prevents function
7246 definitions from being added to command history.
7247
7249 The shift built-in removes some positional parameters or array values.
7250 Syntax
7252 • shift [-A array] [count]
7253 Description
7255 The shift built-in removes the first count positional parameters or
7256 array values, where count is specified by the operand.
7257 Options
7259 -A array, --array=array
7260 Remove first count values of array instead of positional
7261 parameters.
7262 Operands
7264 count
7265 The number of positional parameters or array values to be removed.
7266 It is an error if the actual number of positional parameters or
7268 array values is less than count. If omitted, the default value is
7269 one. If negative, the last -count positional parameters or array
7270 values are removed instead of the first ones.
7271 Exit status
7273 The exit status of the shift built-in is zero unless there is any
7274 error.
7275 Notes
7277 The shift built-in is a special built-in.
7278 The number of positional parameters can be obtained with the # special
7280 parameter. The number of array values can be obtained with ${array[#]}.
7281 The POSIX standard defines no options for the shift built-in; the
7283 built-in accepts no options in the POSIXly-correct mode.
7284 Negative operands are not allowed in the POSIXly-correct mode.
7286
7288 The suspend built-in suspends the shell.
7289 Syntax
7291 • suspend [-f]
7292 Description
7294 The suspend built-in sends a SIGSTOP signal to all processes in the
7295 process group to which the shell process belongs. The signal suspends
7296 the processes (including the shell). The suspended processes resume
7297 when they receive a SIGCONT signal.
7298 If the shell is interactive and its process group ID is equal to the
7300 process ID of the session leader, the shell prints a warning message
7301 and refuses to send a signal unless the -f (--force) option is
7302 specified. (In such a case, there is no other job-controlling shell
7303 that can send a SIGCONT signal to resume the suspended shell, so the
7304 shell could never be resumed.)
7305 Options
7307 -f, --force
7308 Suppress warnings that would prevent the shell from sending a
7309 signal.
7310 Exit status
7312 The exit status is zero if the signal was successfully sent and
7313 non-zero otherwise.
7314 Notes
7316 The suspend built-in is a semi-special built-in. In the POSIX standard,
7317 it is defined as a command with unspecified behavior.
7318
7320 The test built-in evaluates an expression.
7321 Syntax
7323 • test expression
7324 • [ expression ]
7326 The test built-in does not distinguish options and operands; all
7328 command line arguments are interpreted as expression. If the built-in
7329 is executed with the name [, expression must be followed by ].
7330 Description
7332 The test built-in evaluates expression as a conditional expression that
7333 is made up of operators and operands described below. The exit status
7334 is 0 if the condition is true and 1 otherwise.
7335 The unary operators below test a file. If the operand file is a
7337 symbolic link, the file referred to by the link is tested (except for
7338 the -h and -L operators).
7339 -b file
7341 file is a block special file
7342 -c file
7344 file is a character special file
7345 -d file
7347 file is a directory
7348 -e file
7350 file exists
7351 -f file
7353 file is a regular file
7354 -G file
7356 file's group ID is same as the shell’s effective group ID
7357 -g file
7359 file's set-group-ID flag is set
7360 -h file
7362 same as -L
7363 -k file
7365 file's sticky bit is set
7366 -L file
7368 file is a symbolic link
7369 -N file
7371 file has not been accessed since last modified
7372 -O file
7374 file's user ID is same as the shell’s effective user ID
7375 -p file
7377 file is a FIFO (named pipe)
7378 -r file
7380 file is readable
7381 -S file
7383 file is a socket
7384 -s file
7386 file is not empty
7387 -u file
7389 file's set-user-ID flag is set
7390 -w file
7392 file is writable
7393 -x file
7395 file is executable
7396 The unary operator below tests a file descriptor:
7398 -t fd
7400 fd is associated with a terminal
7401 The unary operators below test a string:
7403 -n string
7405 string is not empty
7406 -z string
7408 string is empty
7409 The unary operator below tests a shell option:
7411 -o ?option
7413 option is a valid shell option name
7414 -o option
7416 option is a valid shell option name that is enabled
7417 The binary operators below compare files. Non-existing files are
7419 considered older than any existing files.
7420 file1 -nt file2
7422 file1 is newer than file2
7423 file1 -ot file2
7425 file1 is older than file2
7426 file1 -ef file2
7428 file1 is a hard link to file2
7429 The binary operators below compare strings:
7431 string1 = string2, string1 == string2
7433 string1 is the same string as string2
7434 string1 != string2
7436 string1 is not the same string as string2
7437 The binary operators below compare strings according to the alphabetic
7439 order in the current locale:
7440 string1 === string2
7442 string1 is equal to string2
7443 string1 !== string2
7445 string1 is not equal to string2
7446 string1 < string2
7448 string1 is less than string2
7449 string1 <= string2
7451 string1 is less than or equal to string2
7452 string1 > string2
7454 string1 is greater than string2
7455 string1 >= string2
7457 string1 is greater than or equal to string2
7458 The binary operator below performs pattern matching:
7460 string =~ pattern
7462 extended regular expression pattern matches (part of) string
7463 The binary operators below compare integers:
7465 v1 -eq v2
7467 v1 is equal to v2
7468 v1 -ne v2
7470 v1 is not equal to v2
7471 v1 -gt v2
7473 v1 is greater than v2
7474 v1 -ge v2
7476 v1 is greater than or equal to v2
7477 v1 -lt v2
7479 v1 is less than v2
7480 v1 -le v2
7482 v1 is less than or equal to v2
7483 The binary operators below compare version numbers:
7485 v1 -veq v2
7487 v1 is equal to v2
7488 v1 -vne v2
7490 v1 is not equal to v2
7491 v1 -vgt v2
7493 v1 is greater than v2
7494 v1 -vge v2
7496 v1 is greater than or equal to v2
7497 v1 -vlt v2
7499 v1 is less than v2
7500 v1 -vle v2
7502 v1 is less than or equal to v2
7503 The operators below can be used to make complex expressions:
7505 ! expression
7507 negate (reverse) the result
7508 ( expression )
7510 change operator precedence
7511 expression1 -a expression2
7513 logical conjunction (and)
7514 expression1 -o expression2
7516 logical disjunction (or)
7517 If the expression is a single word without operators, the -n operator
7519 is assumed. An empty expression evaluates to false.
7520 Comparison of version numbers
7522 Comparison of version numbers is similar to comparison of strings
7523 in alphabetic order. The differences are:
7524 • Adjacent digits are treated as an integer. Integers are
7526 compared in mathematical order rather than alphabetic order.
7527 • Digits are considered larger than any non-digit characters.
7529 For example, version numbers 0.1.2-3 and 00.001.02-3 are equal and
7531 0.2.1 is smaller than 0.10.0.
7532 Exit status
7534 The exit status of the test built-in is 0 if expression is true and 1
7535 otherwise. The exit status is 2 if expression cannot be evaluated
7536 because of a syntax error or any other reasons.
7537 Notes
7539 Complex expressions may cause confusion and should be avoided. Use the
7540 shell’s compound commands. For example, [ 1 -eq 1 ] && [ -t = 1 ] && !
7541 [ foo ] is preferred over [ 1 -eq 1 -a -t = 1 -a ! foo ].
7542 The POSIX standard provides that the exit status should be larger than
7544 1 on error. The POSIX standard does not define the following operators:
7545 -G, -k, -N, -O, -nt, -ot, -ef, ==, ===, !==, <, <=, >, >=, =~, -veq,
7546 -vne, -vgt, -vge, -vlt, and -vle. POSIX neither specifies -o as a unary
7547 operator.
7548
7550 The times built-in prints CPU time usage.
7551 Syntax
7553 • times
7554 Description
7556 The times built-in prints the CPU times consumed by the shell process
7557 and its child processes to the standard output.
7558 The built-in prints two lines: the first line shows the CPU time of the
7560 shell process and the second one that of its child processes (not
7561 including those which have not terminated). Each line shows the CPU
7562 times consumed in the user and system mode.
7563 Exit status
7565 The exit status of the times built-in is zero unless there is any
7566 error.
7567 Notes
7569 The times built-in is a special built-in.
7570
7572 The trap built-in sets or prints signal handlers.
7573 Syntax
7575 • trap
7576 • trap action signal...
7578 • trap signal_number [signal...]
7580 • trap -p [signal...]
7582 Description
7584 The trap built-in sets or prints actions that are taken when the shell
7585 receives signals. (Those actions are called traps.)
7586 When executed with action and one or more signals, the built-in sets
7588 the traps for signals to action. If the shell receives one of the
7589 signals, the action will be taken.
7590 If the first operand is signal_number instead of action, the built-in
7592 resets the traps for signal_number and signals as if action was -.
7593 When executed with the -p (--print) option or with no operands, the
7595 built-in prints currently set traps to the standard output in a format
7596 that can be executed as commands that restore the current traps. If one
7597 or more signals are specified, only those signals are printed.
7598 Otherwise, all signals with non-default actions are printed. (In some
7599 situations, however, the built-in may print previous trap settings
7600 instead of the current. See notes below.)
7601 Options
7603 -p, --print
7604 Print current trap settings.
7605 Operands
7607 action
7608 An action that will be taken when signal is received.
7609 If action is a single hyphen (-), the action is reset to the
7611 default action that is defined by the operating system. If action
7612 is an empty string, the signal is ignored on receipt. Otherwise,
7613 action is treated as a command string: the string is parsed and
7614 executed as commands when the signal is received. (If a signal is
7615 received while a command is being executed, the action is taken
7616 just after the command finishes.)
7617 signal
7619 The number or name of a signal.
7620 If signal is number 0 or name EXIT, it is treated as a special
7622 imaginary signal that is always received when the shell exits. The
7623 action set for this signal is taken when the shell exits normally.
7624 signal_number
7626 This is like signal, but must be a number.
7627 Exit status
7629 The exit status of the trap built-in is zero unless there is any error.
7630 Notes
7632 The trap built-in is a special built-in.
7633 The POSIX standard defines no options for the trap built-in; the
7635 built-in accepts no options in the POSIXly-correct mode.
7636 The POSIX standard requires that signal names must be specified without
7638 the SIG-prefix, like INT and QUIT. As an extension, yash accepts
7639 SIG-prefixed names like SIGINT and SIGQUIT and treats signal names
7640 case-insensitively.
7641 Reusing output of the built-in
7643 Output of the trap built-in can be saved in a variable, which can
7644 be later executed by the eval built-in to restore the traps.
7645 saved_traps=$(trap)
7647 trap '...' INT
7648 eval "$saved_traps"
7649 There are some tricks behind the scenes to allow this idiom. You
7651 use a command substitution to save the output of the trap built-in
7652 in the variable. The command substitution is executed in a
7653 subshell. The subshell resets all traps (except ignored ones) at
7654 the beginning of itself. This seemingly would result in (almost)
7655 empty output from the built-in that would fail to restore the traps
7656 as expected.
7657 To avoid that pitfall, POSIX requires the shell to follow one of
7659 the two options below:
7660 • If a command substitution just contains a single trap built-in,
7662 traps should not be reset when the subshell is started to
7663 execute the built-in; or
7664 • A subshell always resets the traps but remembers the previous
7666 traps. If the trap built-in is executed in the subshell but no
7667 other trap built-in has been executed to modify traps in the
7668 subshell, then the built-in should print the remembered traps.
7669 Yash obeys the second.
7671
7673 The true built-in does nothing successfully.
7674 Syntax
7676 • true
7677 Description
7679 The true built-in does nothing. Any command line arguments are ignored.
7680 Exit status
7682 The exit status of the true built-in is zero.
7683 Notes
7685 The true built-in is a semi-special built-in.
7686 The true and colon built-ins have the same effect, but true is a
7688 semi-special built-in while colon is a special.
7689
7691 The type built-in identifies a command.
7692 Syntax
7694 • type [-abefkp] [command...]
7695 Description
7697 The type built-in is equivalent to the command built-in with the -V
7698 option.
7699 Notes
7701 The POSIX standard does not define the relation between the type and
7702 command built-ins. The standard does not define options for the type
7703 built-in.
7704 At least one command operand must be specified in the POSIXly-correct
7706 mode.
7707 The type built-in is a semi-special built-in.
7709
7711 The typeset built-in prints or sets variables or functions.
7712 Syntax
7714 • typeset [-gprxX] [variable[=value]...]
7715 • typeset -f[pr] [function...]
7717 Description
7719 If executed without the -f (--functions) option, the typeset built-in
7720 prints or sets variables to the standard output. Otherwise, it prints
7721 or sets functions.
7722 If executed with the -p (--print) option, the built-in prints the
7724 variables or functions specified by operands. Without the option, it
7725 sets variables or functions. If no operands are specified, it prints
7726 all existing variables or functions, regardless of whether the -p
7727 (--print) option is specified.
7728 Options
7730 -f, --functions
7731 Print or set functions rather than variables.
7732 -g, --global
7734 When setting a new variable, the variable will be a global variable
7735 if this option is specified. Without this option, the variable
7736 would be a local variable.
7737 When printing variables, all existing variables including global
7739 variables are printed if this option is specified. Without this
7740 option, only local variables are printed.
7741 -p, --print
7743 Print variables or functions in a form that can be parsed and
7744 executed as commands that will restore the currently set variables
7745 or functions.
7746 -r, --readonly
7748 When setting variables or functions, make them read-only.
7749 When printing variables or functions, print read-only variables or
7751 functions only.
7752 -x, --export
7754 When setting variables, mark them for export, so that they will be
7755 exported to external commands.
7756 When printing variables, print exported variables only.
7758 -X, --unexport
7760 When setting variables, cancel exportation of the variables.
7761 Operands
7763 variable (without value)
7764 The name of a variable that is to be set or printed.
7765 Without the -p (--print) option, the variable is defined (if not
7767 yet defined) but its value is not set nor changed. Variables that
7768 are defined without values are treated as unset in parameter
7769 expansion.
7770 variable=value
7772 The name of a variable and its new value.
7773 The value is assigned to the variable (regardless of the -p
7775 (--print) option).
7776 function
7778 The name of an existing function that is to be set or printed.
7779 Exit status
7781 The exit status of the typeset built-in is zero unless there is any
7782 error.
7783 Notes
7785 A global variable cannot be newly defined if a local variable has
7786 already been defined with the same name. The local variable will be set
7787 regardless of the -g (--global) option.
7788 The typeset built-in is a semi-special built-in. In the POSIX standard,
7790 it is defined as a command with unspecified behavior.
7791 The export and readonly built-ins are equivalent to the typeset
7793 built-in with the -gx and -gr options, respectively. The local built-in
7794 is equivalent to the typeset built-in except that the -f (--functions)
7795 and -g (--global) options cannot be used.
7796
7798 The ulimit built-in sets or prints a resource limit.
7799 Syntax
7801 • ulimit -a [-H|-S]
7802 • ulimit [-H|-S] [-efilnqrstuvx] [limit]
7804 Description
7806 The ulimit built-in sets or prints a resource limit.
7807 If executed with the -a (--all) option, the built-in prints the current
7809 limits for all resource types. Otherwise, it sets or prints the limit
7810 of a single resource type. The resource type can be specified by the
7811 options listed below. The resource limits will affect the current shell
7812 process and all commands invoked from the shell.
7813 Each resource type has two limit values: the hard and soft limit. You
7815 can change a soft limit freely as long as it does not exceed the hard
7816 limit. You can decrease a hard limit but cannot increase it without a
7817 proper permission.
7818 When the -H (--hard) or -S (--soft) option is specified, the built-in
7820 sets or prints the hard or soft limit, respectively. If neither of the
7821 options is specified, the built-in sets both the hard and soft limit or
7822 prints the soft limit.
7823 Options
7825 -H, --hard
7826 Set or print a hard limit.
7827 -S, --soft
7829 Set or print a soft limit.
7830 -a, --all
7832 Print all current limit settings.
7833 The following options specify the type of resources. If none of them is
7835 specified, -f is the default. The types of resources that can be set
7836 depend on the operating system.
7837 -c, --core
7839 Maximum size of core files created (in 512-byte blocks)
7840 -d, --data
7842 Maximum size of a process’s data segment (in kilobytes)
7843 -e, --nice
7845 Maximum scheduling priority (‘nice’)
7846 -f, --fsize
7848 Maximum size of files created by a process (in 512-byte blocks)
7849 -i, --sigpending
7851 Maximum number of pending signals
7852 -l, --memlock
7854 Maximum memory size that can be locked into RAM (in kilobytes)
7855 -m, --rss
7857 Maximum size of a process’s resident set (in kilobytes)
7858 -n, --nofile
7860 Maximum file descriptor + 1
7861 -q, --msgqueue
7863 Maximum size of POSIX message queues
7864 -r, --rtprio
7866 Maximum real-time scheduling priority
7867 -s, --stack
7869 Maximum size of a process’s stack (in kilobytes)
7870 -t, --cpu
7872 Maximum CPU time that can be used by a process (in seconds)
7873 -u, --nproc
7875 Maximum number of processes for a user
7876 -v, --as
7878 Maximum size of memory used by a process (in kilobytes)
7879 -x, --locks
7881 Maximum number of file locks
7882 Operands
7884 limit
7885 A limit to be set.
7886 The value must be a non-negative integer or one of hard, soft, and
7888 unlimited. If value is hard or soft, the new limit is set to the
7889 current hard or soft limit. If limit is not specified, the current
7890 limit is printed.
7891 Exit status
7893 The exit status of the ulimit built-in is zero unless there is any
7894 error.
7895 Notes
7897 The POSIX standard defines no options other than -f. It neither defines
7898 hard, soft, or unlimited for limit values.
7899 The ulimit built-in is a semi-special built-in.
7901
7903 The umask built-in sets or prints the file mode creation mask.
7904 Syntax
7906 • umask mask
7907 • umask [-S]
7909 Description
7911 If executed without the mask operand, the built-in prints the current
7912 file mode creation mask of the shell to the standard output in a form
7913 that can later be used as mask to restore the current mask.
7914 Otherwise, the built-in sets the file mode creation mask to mask.
7916 Options
7918 -S, --symbolic
7919 Print in the symbolic form instead of the octal integer form.
7920 Operands
7922 mask
7923 The new file mode creation mask either in the symbolic or octal
7924 integer form.
7925 Octal integer form
7927 In the octal integer form, the mask is specified as a non-negative
7928 octal integer that is the sum of the following permissions:
7929 0400
7931 read by owner
7932 0200
7934 write by owner
7935 0100
7937 execute/search by owner
7938 0040
7940 read by group
7941 0020
7943 write by group
7944 0010
7946 execute/search by group
7947 0004
7949 read by others
7950 0002
7952 write by others
7953 0001
7955 execute/search by others
7956 Symbolic form
7958 In the symbolic form, the mask is specified as a symbolic
7959 expression that denotes permissions that are not included in the
7960 mask.
7961 The entire expression is one or more clauses separated by comma. A
7963 clause is a sequence of whos followed by one or more actions.
7964 A who is one of:
7966 u
7968 owner
7969 g
7971 group
7972 o
7974 others
7975 a
7977 all of owner, group, and others
7978 An empty sequence of whos is equivalent to who a.
7980 An action is an operator followed by permission. An operator is one
7982 of:
7983 =
7985 set who's permission to permission
7986 +
7988 add permission to who's permission
7989 -
7991 remove permission from who's permission
7992 and permission is one of:
7994 r
7996 read
7997 w
7999 write
8000 x
8002 execute/search
8003 X
8005 execute/search (only if some user already has execute/search
8006 permission)
8007 s
8009 set-user-ID and set-group-ID
8010 u
8012 user’s current permissions
8013 g
8015 group’s current permissions
8016 o
8018 others' current permissions
8019 but more than one of r, w, x, X, and s can be specified after a
8021 single operand.
8022 For example, the command umask u=rwx,go+r-w
8024 • unmasks the user’s read, write, and execute/search permissions;
8026 • unmasks the group’s and others' read permission; and
8028 • masks the group’s and others' write permission.
8030 Exit status
8032 The exit status of the umask built-in is zero unless there is any
8033 error.
8034 Notes
8036 The umask built-in is a semi-special built-in.
8037 The POSIX standard does not require the default output format (used
8039 when the -S option is not specified) to be the octal integer form.
8040
8042 The unalias built-in undefines aliases.
8043 Syntax
8045 • unalias name...
8046 • unalias -a
8048 Description
8050 The unalias built-in removes the definition of the aliases specified by
8051 operands.
8052 Options
8054 -a, --all
8055 Undefine all aliases.
8056 Operands
8058 name
8059 The name of an alias to be undefined.
8060 Exit status
8062 The exit status of the unalias built-in is zero unless there is any
8063 error. It is an error to specify the name of a non-existing alias as
8064 name.
8065 Notes
8067 The unalias built-in is a semi-special built-in.
8068
8070 The unset built-in undefines variables or functions.
8071 Syntax
8073 • unset [-fv] [name...]
8074 Description
8076 The unset built-in removes the definition of the variables or functions
8077 specified by operands.
8078 It is not an error if any of the specified variables or functions do
8080 not exist; they are silently ignored.
8081 Options
8083 -f, --functions
8084 Undefine functions.
8085 -v, --variables
8087 Undefine variables.
8088 These options are mutually exclusive: only the last specified one is
8090 effective. If neither is specified, -v is assumed.
8091 Operands
8093 name
8094 The name of a variable or function to be undefined.
8095 Exit status
8097 The exit status of the unset built-in is zero unless there is any
8098 error.
8099 Notes
8101 The unset built-in is a special built-in.
8102 Although yash does not do so, the POSIX standard allows removing a
8104 function if neither of the -f and -v options is specified and the
8105 specified variable does not exist.
8106 At least one name operand must be specified in the POSIXly-correct
8108 mode.
8109
8111 The wait built-in waits for jobs to terminate.
8112 Syntax
8114 • wait [job...]
8115 Description
8117 The wait built-in waits for background jobs to terminate. If job
8118 control is enabled, stopped jobs are considered as terminated.
8119 The built-in can be used to wait for asynchronous commands if job
8121 control is disabled.
8122 If the shell receives a signal while the built-in is waiting and if a
8124 trap has been set for the signal, then the trap is executed and the
8125 built-in immediately finishes (without waiting for the jobs). If the
8126 shell receives a SIGINT signal when job control is enabled, the
8127 built-in aborts waiting.
8128 If the shell is interactive, job-controlling, and not in the
8130 POSIXly-correct mode, the job status is printed when the job is
8131 terminated or stopped.
8132 Operands
8134 job
8135 The job ID of the job or the process ID of a process in the job.
8136 If no jobs are specified, the built-in waits for all existing jobs.
8138 If the specified job does not exist, the job is considered to have
8140 terminated with the exit status of 127.
8141 Exit status
8143 If no jobs were specified and the built-in successfully waited for all
8144 the jobs, the exit status is zero. If one or more jobs were specified,
8145 the exit status is that of the last job.
8146 If the built-in was aborted by a signal, the exit status is an integer
8148 (> 128) that denotes the signal. If there was any other error, the exit
8149 status is between 1 and 126 (inclusive).
8150 Notes
8152 The wait built-in is a semi-special built-in.
8153 The process ID of the last process of a job can be obtained by the !
8155 special parameter. You can use the jobs built-in as well to obtain
8156 process IDs of job processes.
8157
8159 Yuki Watanabe <magicant@users.osdn.me>
8160 Author.
8161 2.52 2021-10-11 YASH(1)